explore

name	explore
description	Run a mandatory pre-implementation exploration workflow before writing production code. Use when a task requires code changes and Codex must first map concerns/layers, read relevant files, check existing constants and types, identify the closest existing pattern, plan exact code placement, and confirm architectural guardrails.

Explore

Before implementing anything for a task, complete the following steps in order. Do not write production code until all steps are done.

Step 1: Understand the task

Restate the task in your own words. Identify:

• What crate this touches: koi-common, koi-client, koi-mdns, koi-config, koi-dns, koi-health, koi-proxy, koi-certmesh, koi-crypto, koi-embedded, koi binary
• Which layer is involved: transport, business logic, wire format, CLI
• Expected output: new feature, refactor, bug fix, extension

Step 2: Read existing code

Open and read the 3-5 most relevant existing files. Use searches like:

# Find types related to the task
rg "struct|enum|trait" crates/ -l | head -20

# Find functions related to the task
rg "fn keyword_from_task" crates/

# Find the closest existing implementation to what we're building
rg "similar_feature_keyword" crates/ -l

For each file read, state in one sentence what it does and whether it is relevant.

Step 3: Check for existing constants and types

Run these searches explicitly and report results:

# Constants in the binary crate
rg "const " crates/koi/src/

# Shared types and utilities
rg "struct|enum" crates/koi-common/src/
rg "struct|enum" crates/koi-mdns/src/protocol/

# Client types
rg "struct|enum" crates/koi-client/src/

# Domain crate types
rg "struct|enum" crates/koi-dns/src/
rg "struct|enum" crates/koi-health/src/
rg "struct|enum" crates/koi-proxy/src/
rg "struct|enum" crates/koi-certmesh/src/

For each required piece of functionality, state clearly:

• Already exists
• Needs to be created

Step 4: Identify the closest pattern to follow

Find the most similar existing feature in the codebase. Examples:

• New HTTP endpoint: read crates/koi/src/adapters/http.rs or crates/koi/src/adapters/dispatch.rs
• New CLI command: read a module in crates/koi/src/commands/
• New shared types: read crates/koi-common/src/types.rs or crates/koi-common/src/api.rs
• New domain logic: read the relevant domain crate (e.g., crates/koi-mdns/, crates/koi-dns/)
• Platform integration: read crates/koi/src/platform/
• Formatting: read crates/koi/src/format.rs
• Client operations: read crates/koi-client/src/lib.rs

State:

• Following the pattern from [specific file]

Step 5: Plan where new code will live

For every new file, type, function, or constant, state location and justification:

New code	Location	Justification
(type/fn/const)	(exact path)	(why here and not elsewhere)

Apply crate placement rules:

• Shared types, traits, utilities: crates/koi-common/
• mDNS protocol types: crates/koi-mdns/
• HTTP client methods: crates/koi-client/
• CLI commands / subcommands: crates/koi/src/commands/
• HTTP server / adapters: crates/koi/src/adapters/
• OS integration: crates/koi/src/platform/
• Output formatting: crates/koi/src/format.rs
• DNS domain logic: crates/koi-dns/
• Health checks: crates/koi-health/
• Reverse proxy: crates/koi-proxy/
• Certificate mesh: crates/koi-certmesh/
• Crypto primitives: crates/koi-crypto/
• Configuration / breadcrumb: crates/koi-config/

Step 6: Check for potential violations

Before proceeding, confirm:

• No mdns-sd imports outside crates/koi-mdns/
• No new type duplicates one in koi-common or domain crates
• Constants are co-located with usage (not in a centralized module)
• New protocol types have serde round-trip tests planned
• Cross-crate dependencies flow downward (binary -> domain crates -> koi-common)

Step 7: Present the plan

Summarize findings in this exact format:

Task: (one sentence) Files read: (list with one-sentence relevance notes) Reusing: (list what already exists) Creating new: (table from Step 5) Pattern: (which existing file you're following) Risks: (anything you're unsure about)

Then stop and wait for approval before implementing.