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-truststore, 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:

bash
1# Find types related to the task
2rg "struct|enum|trait" crates/ -l | head -20
3
4# Find functions related to the task
5rg "fn keyword_from_task" crates/
6
7# Find the closest existing implementation to what we're building
8rg "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:

bash
1# Constants in the binary crate
2rg "const " crates/koi/src/
3
4# Shared types and utilities
5rg "struct|enum" crates/koi-common/src/
6rg "struct|enum" crates/koi-mdns/src/protocol/
7
8# Client types
9rg "struct|enum" crates/koi-client/src/
10
11# Domain crate types
12rg "struct|enum" crates/koi-dns/src/
13rg "struct|enum" crates/koi-health/src/
14rg "struct|enum" crates/koi-proxy/src/
15rg "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:

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.