Dev plan

Dev Plan

Step 1: Read the context

Before asking anything, gather context from two sources.

Product docs — read .harness/product/ if it exists:

• .harness/product/product.md — what's being built and for whom
• .harness/product/roadmap.md — feature priorities (focus on must-haves)
• .harness/product/ux.md — UX workflows and design direction
• .harness/product/competitors.md — competitive landscape for technical benchmarking
• .harness/product/CONTEXT.md — domain vocabulary; use these exact terms in all feature specs and code

Codebase — explore what already exists:

• Read README.md and AGENTS.md for stated architecture and setup
• Identify the tech stack already in use (languages, frameworks, databases, key libraries)
• Scan key directories to understand what's built, what's stubbed, what's absent
• Check .harness/engineering/ and .harness/adr/ to avoid re-deciding settled questions

Synthesize into an internal picture: what needs to be built, what constraints exist, where the real decisions are. Do not share this — use it to skip obvious questions.

Step 2: Interview

Interview the user one question at a time. For every question, lead with your recommendation first — state what you'd choose and why, then ask if they agree. Never ask a bare question.

Be direct about tradeoffs. When a choice has real costs, name them. When a popular tool is the wrong fit, say so. When the user's preference conflicts with what the product needs, surface that conflict.

If a question can be answered by reading the codebase or product docs, answer it yourself and move on.

Work through these dimensions in order; skip or combine when the answer is already clear. See REFERENCE.md for detailed questions per dimension:

1. Architecture
2. Tech stack
3. Key libraries and tools
4. Data model
5. Implementation approach
6. Constraints
7. Visual design (UI projects only)
8. Key tradeoffs

Step 3: Engineering Summary

After the interview, produce:

• Architecture: one paragraph on the chosen structure and why
• Stack: language, framework, database, key libraries — with rationale for each
• Implementation approach: build new / extend / refactor, and the phase order
• Visual design tokens: palette, type system, spacing scale, component tokens (if UI)
• Key decisions: the 2–3 choices that constrain everything else
• Open questions: anything unresolved that affects what gets built

Step 4: Write docs

Spawn three subagents in parallel. Pass the full engineering summary as context — subagents cannot read the conversation.

Runtime note: without parallel subagents (e.g. Codex), see ../_shared/runtime-parallelism.md and write A, B, and C sequentially.

A, B, and C write different files — two subagents must never edit the same .harness/ file (one writer per doc — concurrent edits merge byte-wise but conflict semantically).

Rules: all internal files go under .harness/; update existing rather than overwrite; omit sections not covered in the summary; never link to .harness/ from public docs.

Subagent A — writes .harness/engineering/architecture.md and DESIGN.md (UI only). Subagent B — writes .harness/engineering/implementation-plan.md and ADRs. Subagent C — writes one .harness/engineering/features/[slug].md per must-have feature.

See REFERENCE.md for the exact template each subagent uses.

After all subagents finish, confirm every file written with a one-line summary. Refresh the doc index and commit — worktrees and future sessions only see committed .harness/ content:

doctier agents --write
git add .harness AGENTS.md
[ -f DESIGN.md ] && git add DESIGN.md
git commit -m "docs: engineering plan and feature specs"

Recommend: "Run /implement to build Phase 1 features."