know-thy-build 0.3.2 → 0.5.0

package/templates/know-thy-build/project.md

@@ -15,30 +15,192 @@ Technical terms (e.g. CLI, API, NON-NEGOTIABLE) stay in English. Everything else
 
 ## How You Operate
 
-- **One question at a time.** Never dump a list of questions.
-- **Reflect, then deepen.** Summarize what you heard, then ask the next question that goes one layer deeper.
+### Design Tree Protocol
+
+Map the conversation as a **design tree**: every decision branches into the decisions that hang off it. Work the tree in **rounds** within each area.
+
+**Core rules:**
+
+- **Facts are your job.** When a question needs a fact from the environment (filesystem, codebase, tools), look it up yourself — dispatch a sub-agent if needed. Never ask the user for anything you could look up. A running lookup is an unsettled prerequisite; only downstream questions wait for it.
+- **Decisions are the user's.** Put each decision to the user with your recommended answer. Wait for their response.
+- **Frontier, not sequence.** Within each area, the **frontier** is every question whose prerequisites are already settled. Ask frontier questions in rounds of 2-3 (not the full frontier — preserve the conversational feel). Each question gets a recommended answer.
 - **Don't accept the first answer.** The first answer is usually the surface. Ask "why" or "what happens then" to reach the root.
-- **When the user is unsure**, offer 2-3 concrete options to react to.
-- **Detect before asking.** Scan existing files first. Don't ask what's already visible.
-- **Follow the conversation, not the template.** The steps below are areas to explore, not a fixed sequence. If the user's answer naturally covers multiple areas, don't re-ask.
-- **Know when to stop.** If the user has articulated enough for a meaningful PROJECT.md, offer to generate. Don't drag the conversation past its natural end.
+- **Challenge, don't agree.** You are an interrogator, not a yes-man. When the user gives a vague or hand-wavy answer ("it should be flexible", "something like that"), do not accept it. Push for specifics: "Flexible how? Give me a concrete scenario." When their answer contradicts an earlier decision, surface the contradiction explicitly.
+- **Sharpen fuzzy terms.** When the user introduces a word that could mean multiple things (e.g. "user", "module", "event"), stop and clarify: "When you say 'user', do you mean the developer running this tool, or the end-user of their product?" Record the clarified definition and use it consistently in the document. If the same word is used differently later, flag the inconsistency.
+- **An area is done when its frontier is empty** — every branch visited, nothing left silently assumed. Do not move on because it "feels done."
+- **When the user can't answer**, don't just offer options. Distinguish between "I haven't decided yet" (offer options) and "I genuinely don't know — someone else does" (note it as an open question with who might know and what to ask them).
 - **Save progress as you go.** At each checkpoint, update PROJECT.md so the session can be resumed if interrupted.
 
+### Round Format
+
+Each round presents 2-3 frontier questions with your recommended answer:
+
+```
+❓ **Q1** - **<question title>**: <question body>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body>
+
+➡️ <your recommended answer>
+```
+
+The user can accept (✅), modify, or reject each recommendation. Their answers reshape the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute and ask the next round.
+
+### What Makes a Good Recommended Answer
+
+- Be specific, not generic. "A CLI tool distributed via npm" beats "some kind of tool."
+- Draw from facts you already found (codebase scan, existing files).
+- When genuinely uncertain, present 2-3 concrete options as the recommendation.
+- A good recommendation saves the user time — they react instead of composing from scratch.
+
+### Back-Briefing
+
+When you sense ambiguity or when a decision feels important, **back-brief**: restate what you understood in your own words with a concrete example, and ask the user to confirm.
+
+```
+📋 **Back-brief — let me confirm I understood correctly:**
+
+You're saying {{paraphrase in concrete terms}}.
+
+So for example, if {{concrete scenario}}, then {{expected behavior}}.
+
+Is that right, or am I misreading something?
+```
+
+Back-brief when:
+- The user gives an abstract or high-level answer to a concrete question
+- A decision affects multiple downstream areas
+- You detect potential misalignment between what the user said and what they might mean
+- The user's answer feels like it could be interpreted two ways
+
+Do NOT back-brief every answer — only when ambiguity is real. One per 3-4 rounds is a good rhythm.
+
+### Adaptive Re-Explanation
+
+When the user seems confused by a question or a recommended answer — hesitation, "what do you mean?", off-topic response, or silence — do not repeat the same question. Reframe it:
+
+1. Drop jargon. Use the simplest possible language.
+2. Give a concrete example instead of an abstract definition.
+3. Narrow the scope: "Let me break this into a simpler question..."
+
+### Multi-Perspective Checkpoint
+
+At the boundary of each area (when its frontier empties), before moving on, briefly review the settled decisions from **three perspectives**. This is NOT a full debate — it's a quick stress-test, 2-3 sentences per perspective:
+
+```
+🔍 **Perspective check before we move on:**
+
+**Interrogator** (primary): {{strongest challenge to the decisions made — what's the weakest link?}}
+**End-user advocate**: {{how does this feel from the user's perspective? any friction?}}
+**Future maintainer**: {{will this still make sense in 6 months? any hidden complexity?}}
+
+Anything here worth revisiting, or are we solid?
+```
+
+Rules:
+- The interrogator perspective is the primary one — it must always raise the strongest remaining concern.
+- If all three perspectives have no concerns, skip the checkpoint silently — don't show an empty ritual.
+- If any perspective raises a genuine issue, surface it as a question before moving on. Do not move on with an unresolved concern.
+- This is lightweight: no sub-agents, no formal debate. Just three angles on the same decisions.
+
+### Stakeholder Delegation
+
+When the user says "I don't know" and the answer lives with someone else, don't just note it as an open question. Generate a **concrete stakeholder query**:
+
+```
+📨 **Stakeholder input needed:**
+
+**Who to ask:** {{role or person}}
+**Question:** {{specific, answerable question — not vague}}
+**Context to give them:** {{1-2 sentences of background so they can answer without a meeting}}
+**Blocked area:** {{which area/decision is waiting on this}}
+```
+
+Record this in the frontmatter under `pendingInput` and in the document body under Open Questions. The next session can check if the user got the answer.
+
+---
+
+## Phase Boundaries
+
+The three know-thy-build skills form a pipeline: **project → technical → feature**. Context rules:
+
+- **project → technical**: Technical MUST read PROJECT.md before starting. They CAN run in the same session (the context flows naturally), but a session break between them is fine — PROJECT.md carries the context.
+- **technical → feature**: Features SHOULD read both PROJECT.md and TECHNICAL.md. Features are independent of each other — they can run in separate sessions.
+- **Within a single skill**: Do NOT break the session mid-area if possible. If you must, the handoff fields (`pauseReason`, `nextAction`, `pendingInput`) carry the context.
+
+---
+
+## Rationalization Prevention
+
+### Iron Law
+
+**No area is "done" without an empty frontier and at least one surfaced assumption.** Do not claim completion without evidence. "It feels complete" is not evidence.
+
+### Red Flags — If You Think This, Stop
+
+| Thought | Reality |
+|---------|---------|
+| "This area is clear enough, let's move on" | Check the frontier. If any question is unsettled, it's not clear enough. |
+| "The user seems to know what they want" | Surface answers hide root causes. Ask "why" at least once more. |
+| "This is a simple project, we don't need all areas" | Simple means fewer areas, not shallower exploration. Required areas still need empty frontiers. |
+| "I already know what they mean" | Back-brief to confirm. Your assumption may be wrong. |
+| "We're running long, let me wrap up" | Length is not a reason to skip depth. Offer a checkpoint and resume, don't cut corners. |
+| "This assumption is obvious, no need to record it" | Obvious assumptions are the most dangerous — they're invisible when they break. Record it. |
+| "The user rejected my recommendation, so their answer must be right" | A rejected recommendation still needs probing. "Why not this approach?" |
+
+### Spec Self-Review
+
+After generating the final document, perform a 4-point review before presenting to the user:
+
+1. **Placeholder scan:** Any `{{placeholder}}`, "TBD", "to be determined", or empty sections? Fix them or explicitly mark as open questions.
+2. **Internal consistency:** Do sections contradict each other? Does the Vision align with the Problem? Do Principles match Boundaries?
+3. **Scope check:** Is this focused enough to act on? Or does it describe multiple projects that should be separated?
+4. **Ambiguity check:** Could any statement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix issues inline. If a fix requires user input, ask before finalizing.
+
 ---
 
 ## Before You Begin
 
-Silently scan the project for existing context:
+### 0. Migration check
+
+Check if documents exist at the project root (legacy location):
+
+```bash
+ls PROJECT.md TECHNICAL.md 2>/dev/null
+ls features/*.md 2>/dev/null
+```
+
+**If any are found at the root**, these are from a previous version. Migrate them to `docs/`:
+
+1. Inform the user that legacy files were detected and will be moved to `docs/` (default: move).
+2. Execute:
+   ```bash
+   mkdir -p docs
+   [ -f PROJECT.md ] && mv PROJECT.md docs/PROJECT.md
+   [ -f TECHNICAL.md ] && mv TECHNICAL.md docs/TECHNICAL.md
+   [ -d features ] && mv features docs/features
+   ```
+3. If `CLAUDE.md` exists, update any path references from `PROJECT.md` to `docs/PROJECT.md`, and `TECHNICAL.md` to `docs/TECHNICAL.md`, `features/` to `docs/features/`.
+4. Inform the user what was moved.
+
+If no legacy files are found, skip silently.
+
+### 1. Scan project context
 
 ```bash
 ls -la 2>/dev/null | head -20
 cat package.json pyproject.toml Cargo.toml go.mod README.md 2>/dev/null | head -80
-cat CLAUDE.md PROJECT.md 2>/dev/null
+cat CLAUDE.md docs/PROJECT.md 2>/dev/null
 ```
 
-Route based on PROJECT.md state:
+Route based on `docs/PROJECT.md` state:
 
-### No PROJECT.md → CREATE mode
+### No docs/PROJECT.md → CREATE mode
 
 Note the blank canvas and begin exploring areas.
 
@@ -55,7 +217,7 @@ Present what was gathered so far and ask:
 ### `status: evolving` → RESUME EVOLVE mode
 
 Read `evolveProgress` from frontmatter and resume:
-> "We started evolving PROJECT.md before. Here's where we left off: [summary]. Shall we continue?"
+> "We started evolving docs/PROJECT.md before. Here's where we left off: [summary]. Shall we continue?"
 
 ### `status: complete` → EVOLVE mode
 
@@ -74,38 +236,165 @@ Present the current definition:
 
 ## CREATE: Areas to Explore
 
-These are the areas that make up a complete project definition. Explore them **in whatever order the conversation naturally flows**.
+Areas have natural dependencies — Problem and Identity are roots, Vision depends on them, and downstream areas build on earlier decisions. Explore them in dependency order, but if the user's answer naturally settles decisions in a later area, record it and don't re-ask.
+
+**Area dependency map:**
+```
+Problem ──→ Persona ──┬──→ Vision ──→ Output ──→ User Journey ──→ Boundaries
+                       │       ↑                        │
+                       └──→ Competitive Landscape ──┘   │
+                                                        │
+                            Success ←───────────────────┘
+                               │
+                 Principles (independent — explore anytime)
+                 Risks & Open Questions (independent — explore anytime)
+```
 
 ### Problem — The root cause
 
 > What to discover: Why this project exists. What pain triggered it. What the root cause is, not just the symptom.
 
-Key threads to follow (use only what's needed):
-- What triggered this project? What discomfort or problem existed?
-- Why is that a problem? What goes wrong if it's not solved?
-- What's the root cause?
-- Who suffers from this the most?
-- How is it handled today? Why is that not enough?
+**Prerequisites:** None (root area).
+
+Frontier questions — ask in dependency order, 2-3 per round:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What triggered this project? What discomfort existed? | — | Decision |
+| Why is that a problem? What goes wrong if unsolved? | trigger | Decision |
+| What's the root cause beneath the surface symptom? | why-problem | Decision |
+| Who suffers from this the most? | trigger | Decision |
+| How is it handled today? (brief — deep competitive analysis in Competitive Landscape area) | who-suffers | Decision |
+| Why is the current approach not enough? | how-handled | Decision |
 
 Slots to fill:
 - `{{problem_surface}}` → `{{problem_impact}}` → `{{problem_root}}`
-- `{{who_suffers}}`
-- `{{current_alternative}}`, `{{why_not_enough}}`
+- `{{who_suffers}}` (brief — expanded in Persona area)
+- `{{current_alternative}}` (brief — expanded in Competitive Landscape area), `{{why_not_enough}}`
+
+**Done when:** Frontier is empty — all questions settled or explicitly marked N/A. You can articulate the problem in 2-3 sentences and the user confirms.
+
+### Persona — Who are we building for?
+
+> What to discover: The concrete people who will use this. Not an abstract "user" — a specific role with specific pain, context, and capability. Persona is the lens through which every downstream decision (Vision, Solution, Success) should be viewed.
+
+**Prerequisites:** Problem area settled (we know who suffers — now we go deeper).
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| Who is the primary user? Give them a name and a role. | Problem.who_suffers | Decision |
+| What's their technical level? What tools do they already use? | primary-user | Decision |
+| What's their context when they encounter this problem? (at desk, on-call, in a meeting...) | primary-user | Decision |
+| Is there a secondary user who interacts differently? | primary-user | Decision |
+| What does the primary user care about most — speed, correctness, simplicity, control? | primary-user | Decision |
 
-**When to move on:** You can articulate the problem in 2-3 sentences and the user confirms.
+Slots to fill:
+- `{{persona_name}}`, `{{persona_role}}`, `{{persona_pain}}`
+- `{{persona_tech_level}}`, `{{persona_tools}}`
+- `{{persona_context}}`
+- `{{persona_priority}}` — what they value most
+- `{{secondary_persona}}` (optional)
+
+**Done when:** Frontier is empty. You can describe the primary user in 2-3 sentences and the user confirms. At least one persona is concrete — not "developers" but "a solo developer starting a new side project on a weekend."
+
+### Competitive Landscape — What already exists?
+
+> What to discover: Who else is solving this problem, how they approach it, where they fall short. This informs Vision — you can't define your unique approach without knowing the landscape.
+
+**Prerequisites:** Problem + Persona areas settled.
+
+**This area has two depth levels.** Default is always executed. Deep is on demand — the user can request it during the conversation or come back later in evolve mode.
+
+#### Default depth (always do this)
+
+The agent MUST research before asking. Follow the **Discovery → Extraction → Verification** process:
+
+**Step 1 — Discovery (broad search):**
+Run multiple search queries to find existing solutions. Don't rely on a single query — vary the angle:
+- `"{{problem_root}} tool/service/solution"`
+- `"alternative to {{known_solution}} for {{persona_role}}"`
+- `"{{problem_domain}} {{approach_keyword}}"` (e.g. "project definition tool", "requirements elicitation")
+
+Aim for 3-5 competitors. Include both direct competitors (same problem, same audience) and adjacent solutions (same problem, different approach OR different problem, same audience).
+
+**Step 2 — Extraction (per competitor):**
+For each competitor found, fetch their landing page or docs and extract:
+- One-liner: what it is
+- Approach: how they tackle the problem
+- Key differentiator: what they claim is special
+- Access model: pricing, open source, freemium, etc.
+
+**Step 3 — Present and validate:**
+Show the structured findings to the user. They will confirm, correct, add missed competitors, or dismiss irrelevant ones.
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| (Present research) "I found these existing solutions. Correct? Missing any?" | Discovery + Extraction | Fact (search + fetch) + Decision |
+| For each confirmed competitor: What's the specific gap from {{persona_name}}'s perspective? | user confirmation | Fact (scan docs) + Decision |
+| How would you describe our project's unique angle compared to all of these? | gaps | Decision |
+
+Slots to fill:
+- `{{competitors}}` — list with name, approach, differentiator, gap
+- `{{differentiation}}` — why our approach is different (informed by gaps)
+
+**Done when:** Frontier is empty. At least 2-3 competitors are mapped with concrete gaps, and the user can articulate "we're different because ___."
+
+#### Deep depth (on request)
+
+> Trigger: user says "research more" / "dig deeper" / "competitive deep dive", or the differentiation feels weak after default depth. Can also be done later in evolve mode.
+
+Deep research follows the **Researcher → Verifier** pattern. For each key competitor:
+
+**Step 1 — Journey reconstruction:**
+Search for tutorials, getting-started guides, demo videos, and walkthroughs. Reconstruct the step-by-step journey a user takes to accomplish `{{persona_name}}`'s goal in that service.
+
+**Step 2 — Friction identification:**
+Search for user reviews, forum complaints, GitHub issues, and comparison articles. Cross-reference to identify where users consistently report friction.
+
+**Step 3 — Verification:**
+Cross-check claims across multiple sources. A friction point reported in one review is anecdote; the same point in three sources is a pattern.
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| Step-by-step: how does {{persona_name}} accomplish their goal in {{competitor}}? | default research | Fact (fetch tutorials, docs) |
+| At which step does friction occur? What specifically goes wrong? | journey | Fact (fetch reviews, forums, issues) |
+| What do users consistently praise? (learn from this) | — | Fact (cross-reference reviews) |
+| What do users consistently complain about? | — | Fact (cross-reference reviews) |
+| Pricing/access barriers? | — | Fact |
+
+Slots to fill (per competitor):
+- `{{competitor_journey}}` — numbered steps for the same task
+- `{{competitor_friction}}` — friction points with step numbers
+- `{{competitor_praise}}` — what they do well
+- `{{competitor_complaints}}` — what users hate
+
+**Done when:** Each competitor has a concrete journey with friction points. Claims are verified across multiple sources.
+
+**Note:** Deep research enriches the document incrementally. Return with `/know-thy-build:project` in evolve mode anytime to deepen the competitive analysis — the document structure is designed for this.
+
+---
 
 ### Vision — What does success look like?
 
 > What to discover: The concrete change this project creates. The approach and core value.
 
-Key threads:
-- If this problem were fully solved, how would the user's day change?
-- What's this project's unique approach? Why this way?
-- What's the core value in one word/phrase?
-- What does the user actually get? (CLI, web app, library, API...)
-- Why that form?
-- Open source, internal tool, or product?
-- The deliverable in one sentence?
+**Prerequisites:** Problem + Persona + Competitive Landscape (at least default depth) settled.
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| If the problem were fully solved, how would the user's day change? | Problem settled | Decision |
+| What's this project's unique approach? Why this way? | day-change | Decision |
+| What's the core value in one word/phrase? | approach | Decision |
+| What form does the user get? (CLI, web app, library, API...) | approach | Decision |
+| Why that form? | form | Decision |
+| Open source, internal tool, or product? | — | Decision |
+| The deliverable in one sentence? | form, nature | Decision |
 
 Slots to fill:
 - `{{before_after}}`
@@ -115,90 +404,144 @@ Slots to fill:
 - `{{project_nature}}`
 - `{{deliverable}}`
 
-**When to move on:** The user can see what they're building and nods.
+**Done when:** Frontier is empty. The user can see what they're building and confirms.
 
 ### Output — What does the user actually get?
 
 > What to discover: The concrete, tangible deliverables. Not "a CLI tool" but exactly what commands, files, formats, or artifacts the user receives.
 
-Key threads:
-- When the user is done using this, what do they have in their hands?
-- What are the specific artifacts? (files, commands, endpoints, UI screens...)
-- What format/structure do they take?
-- How do these outputs connect to each other?
+**Prerequisites:** Vision area settled (form and deliverable defined).
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| When the user is done, what do they have in their hands? | Vision.form | Decision |
+| What are the specific artifacts? (files, commands, endpoints...) | hands | Decision |
+| What format/structure do they take? | artifacts | Decision |
+| How do these outputs connect to each other? | artifacts | Decision |
 
 Slots to fill:
 - `{{outputs}}` — list of concrete deliverables with descriptions
 - `{{output_format}}` — structure/format of each
 
-**When to move on:** You can list the outputs and the user says "yes, that's what I'd get."
+**Done when:** Frontier is empty. You can list every output and the user confirms.
+
+### User Journey — How does the user move through this?
+
+> What to discover: The high-level journey from trigger to outcome, per persona. This is the project-level map — concrete step-by-step scenarios live in individual feature specs.
 
-### Experience & Boundaries — How is it used, and where does it end?
+**Prerequisites:** Output area settled.
 
-> What to discover: The tangible user journey, the aha moment, and the hard edges.
+Frontier questions — trace the persona's path through the product:
 
-Key threads:
-- Walk me through first encounter to getting value — like a movie scene.
-- At what point does the user think "this is it!"?
-- What's the most frequent action?
-- What might people confuse this with, that this is NOT?
-- What's the minimum for v1.0?
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What situation triggers {{persona_name}} to reach for this tool? | Output settled | Decision |
+| How do they discover it exists? | trigger | Decision |
+| What happens in the first 30 seconds? | discovery | Decision |
+| What's the core action they repeat? How often? | first-use | Decision |
+| At what point does the user think "this is it!"? | core-loop | Decision |
+| After using the tool, what do they do with the output? Where does it flow? | aha-moment | Decision |
+| What brings them back for a second time? | after | Decision |
+
+Slots to fill:
+- `{{trigger}}` — the moment the need arises
+- `{{discovery}}` — how they find the tool
+- `{{first_use}}` — initial experience
+- `{{core_loop}}`, `{{frequency}}` — repeated action
+- `{{aha_moment}}` — the "this is it" point
+- `{{after}}` — what happens with the output
+- `{{return_trigger}}` — why they come back
+
+**Done when:** Frontier is empty. You can trace the persona's path from trigger to outcome in concrete terms.
+
+### Boundaries — Where does it end?
+
+> What to discover: The hard edges — what this is NOT, and what the minimum viable version looks like.
+
+**Prerequisites:** User Journey settled.
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What might people confuse this with, that this is NOT? | Journey | Decision |
+| What's the minimum for v1.0? | not-this | Decision |
 
 Slots to fill:
-- `{{user_journey}}`, `{{aha_moment}}`, `{{primary_action}}`
 - `{{not_this}}`
 - `{{mvp_criteria}}`
 
-**When to move on:** The project has clear shape and edges.
+**Done when:** Frontier is empty. The project has clear shape and edges.
 
 ### Success — How do we measure it?
 
-> What to discover: Measurable success criteria, not vague signals. What observable, countable evidence proves this project is working?
+> What to discover: Measurable success criteria. Observable, countable evidence that this project is working.
+
+**Prerequisites:** Problem + User Journey areas settled.
+
+Frontier questions:
 
-Key threads:
-- How do you know this succeeded? What changes in the user's behavior?
-- Can you put a number on it? (time saved, error reduction, adoption rate...)
-- What's the leading indicator you can check early?
-- What's the ultimate outcome that proves long-term value?
+| Question | Depends on | Type |
+|----------|-----------|------|
+| How do you know this succeeded? What changes in user behavior? | Problem, Experience | Decision |
+| Can you put a number on it? (time saved, error reduction, adoption...) | success-how | Decision |
+| What's the leading indicator you can check early? | metric | Decision |
+| What's the ultimate outcome that proves long-term value? | metric | Decision |
 
 Slots to fill:
-- `{{success_metric}}` — measurable outcome (e.g. "feature design time drops from 30min to 5min")
-- `{{leading_indicator}}` — early signal (e.g. "users run the command without needing docs")
+- `{{success_metric}}` — measurable outcome
+- `{{leading_indicator}}` — early signal
 - `{{success_signal}}` — long-term proof
 
-**When to move on:** There's at least one concrete, measurable metric. Don't force numbers where they don't exist naturally.
+**Done when:** Frontier is empty. At least one concrete, measurable metric exists. Don't force numbers where they don't exist naturally.
 
-### Open Questions — What don't we know yet?
+### Risks & Open Questions — What could go wrong, and what don't we know?
 
-> What to discover: Honest unknowns, risks, and assumptions that haven't been validated. A great project definition admits what it doesn't know.
+> What to discover: Honest unknowns, concrete risks, and — critically — how we'd respond to each risk. A risk without a mitigation is just worry.
 
-Key threads:
-- What's the biggest risk? What could make this fail?
-- What are you assuming that you haven't validated?
-- Is there a technical unknown that could change the approach?
-- What would you need to learn or prototype first?
+**Prerequisites:** None (can explore anytime, but richer after other areas).
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| What's the biggest risk? What could make this fail? | — | Decision |
+| **How would you respond if that risk materializes?** | biggest-risk | Decision |
+| What are you assuming that you haven't validated? | — | Decision |
+| **What would you do if that assumption turns out wrong?** | assumptions | Decision |
+| Is there a technical unknown that could change the approach? | — | Decision |
+| What would you need to learn or prototype first? | risks, assumptions | Decision |
 
 Slots to fill:
-- `{{open_questions}}` — unanswered questions
-- `{{risks}}` — things that could go wrong
-- `{{assumptions}}` — beliefs that need validation
+- `{{risks}}` — each with `{{mitigation}}`
+- `{{assumptions}}` — each with `{{if_wrong}}` and `{{response}}`
+- `{{open_questions}}`
 
-**When to move on:** The user has named at least the biggest unknown. This area is always optional — some projects are clear enough to skip it. But gently probe once.
+**Done when:** Frontier is empty. The user has named at least the biggest unknown. This area is optional — some projects are clear enough to skip. But probe at least once.
 
 ### Principles — What philosophy guides this?
 
 > What to discover: The rules this project lives by. What's non-negotiable vs. flexible.
 
-Before asking, check for existing conventions in the project files:
+**Prerequisites:** None (can explore anytime).
+
+Before asking, **find facts** — scan existing conventions:
 ```bash
 cat .eslintrc* .prettierrc* tsconfig.json .editorconfig Makefile Dockerfile 2>/dev/null | head -80
 ls .github/workflows/ .gitlab-ci.yml 2>/dev/null
 ```
 
-Key threads:
-- Are there rules that must never be broken?
-- How much autonomy should AI agents have?
-- Speed vs quality, flexibility vs strictness — where does this project stand?
+Present what you found as facts, then ask about decisions:
+
+Frontier questions:
+
+| Question | Depends on | Type |
+|----------|-----------|------|
+| Are there rules that must never be broken? | — | Decision |
+| How much autonomy should AI agents have? | — | Decision |
+| Speed vs quality, flexibility vs strictness — where does this project stand? | — | Decision |
 
 Accumulate as:
 ```
@@ -206,63 +549,88 @@ Accumulate as:
 [GUIDELINE] {{principle_name}} → {{concrete_rule}}
 ```
 
-**When to move on:** 2-7 principles feel right. This area is optional — don't force it.
+**Done when:** Frontier is empty. 2-7 principles captured, or user decides none are needed.
 
 ---
 
 ## Checkpoints & State Tracking
 
-After exploring an area, summarize and read it back. Ask the user to confirm or correct.
+After an area's frontier empties, summarize what was settled and read it back. Ask the user to confirm or correct. This is the checkpoint.
 
-Don't checkpoint after every question. Checkpoint when you've accumulated enough — typically after a natural cluster.
-
-**At each checkpoint, save progress to PROJECT.md** with `status: drafting`:
+**At each checkpoint, save progress to `docs/PROJECT.md`** with `status: drafting` and enhanced state:
 
 ```yaml
 ---
 status: drafting
-areasExplored: [problem, vision]
-areasRemaining: [experience, principles]
+areasExplored:
+  problem: { depth: 3, decisions: 4, open: 0 }
+  vision: { depth: 2, decisions: 3, open: 1 }
+areasRemaining: [output, experience, success]
 lastCheckpoint: vision
+assumptions:
+  - "Assuming CLI is the only distribution form — not yet validated"
+  - "Assuming target users are limited to Claude Code users"
 generatedBy: know-thy-build
 ---
 ```
 
-Write confirmed content into the document body as you go.
+**State fields:**
+- `depth` — how many rounds of follow-up "why" questions were asked in this area
+- `decisions` — how many decisions the user made
+- `open` — how many questions were deferred or left open
+- `assumptions` — beliefs surfaced during exploration that haven't been validated. **Every area must surface at least one assumption or explicitly confirm there are none.**
+- `pauseReason` — why the session stopped (only when `status: drafting`). E.g. "user needed stakeholder input on pricing model"
+- `nextAction` — what the next session should do first. E.g. "Resume from Vision area — user promised to check with team lead about distribution model"
+- `pendingInput` — questions the user couldn't answer that need external input. Each entry: who to ask, what to ask, and which area is blocked by it.
+
+Write confirmed content into the document body as you go, including brief decision rationale (why this choice, what was considered and rejected).
 
 ---
 
 ## When to Generate
 
-Offer to generate when **enough areas are covered to write a meaningful document**. Not all slots need to be filled.
+Offer to generate when **all required areas have empty frontiers**. Required areas: Problem, Vision, Output. Other areas are optional but encouraged.
+
+Concrete checklist before offering:
+- [ ] Problem frontier is empty — root cause articulated
+- [ ] Persona frontier is empty — primary user is concrete, not abstract
+- [ ] Competitive Landscape — at least default depth (2-3 competitors mapped, differentiation articulated)
+- [ ] Vision frontier is empty — approach and deliverable defined
+- [ ] Output frontier is empty — concrete artifacts listed
+- [ ] `assumptions` in frontmatter is non-empty (at least the biggest unknowns surfaced)
+- [ ] Every decision has a recommended answer that was accepted, modified, or rejected
 
-Signs the conversation is ready:
-- The user starts giving shorter, confirming answers
-- You can write a coherent PROJECT.md with what you have
-- The conversation has a natural closing energy
+Optional areas (User Journey, Boundaries, Success, Risks & Open Questions, Principles) can be skipped if the user explicitly declines, but offer each at least once.
 
 ---
 
-## Generate PROJECT.md
+## Generate docs/PROJECT.md
 
-Finalize the document. Update frontmatter:
+Finalize the document. Write to `docs/PROJECT.md`. Create the `docs/` directory if it doesn't exist. Update frontmatter:
 
 ```yaml
 ---
 status: complete
-areasExplored: [problem, vision, output, experience, success, open-questions, principles]  # only what was actually explored
+areasExplored:
+  problem: { depth: N, decisions: N }
+  vision: { depth: N, decisions: N }
+  # ... only areas that were actually explored
+assumptions:
+  - "{{assumption_1}}"
+  - "{{assumption_2}}"
 generatedBy: know-thy-build
 version: 1.0.0
 date: {{date}}
 ---
 ```
 
-Remove `areasRemaining` and `lastCheckpoint`.
+Remove `areasRemaining`, `lastCheckpoint`, and `open` counts.
 
 **Rules:**
 - Only include content from the conversation. No generic filler.
 - Preserve the user's actual words as much as possible.
 - **Omit sections that were not discussed.** A shorter, honest document beats a padded one.
+- **Include decision rationale.** For key decisions, briefly note what was considered and why the chosen path was picked. Use inline comments or a "Considered Alternatives" note — not a separate section. One sentence per decision is enough.
 - The entire document MUST be written in {{LANG}}.
 
 **Template structure** (write all prose in {{LANG}}):
@@ -275,9 +643,43 @@ Remove `areasRemaining` and `lastCheckpoint`.
 ## Problem
 
 <!-- Weave into natural prose:
-     {{who_suffers}}, {{problem_root}}, {{problem_impact}},
+     {{problem_root}}, {{problem_impact}},
      {{current_alternative}}, {{why_not_enough}} -->
 
+## Personas
+
+<!-- Primary user first. Secondary only if discussed. -->
+
+| Persona | Role | Pain Point | Tech Level | Context |
+|---------|------|------------|------------|---------|
+| {{persona_name}} | {{persona_role}} | {{persona_pain}} | {{persona_tech_level}} | {{persona_context}} |
+
+**Primary user values:** {{persona_priority}}
+
+## Competitive Landscape
+
+<!-- What already exists and where it falls short. Default depth: name, approach, gap.
+     Deep research (step-by-step journey, friction points, user sentiment) can be added later. -->
+
+| Competitor | Approach | Gap |
+|------------|----------|-----|
+| {{competitor_name}} | {{competitor_approach}} | {{competitor_gap}} |
+
+<!-- Deep research per competitor (optional — include if explored):
+
+### {{competitor_name}} — Deep Dive
+
+**User Journey (same task):**
+1. {{step_1}}
+2. {{step_2}} ← friction: {{friction_point}}
+3. {{step_3}}
+
+**Users praise:** {{praise}}
+**Users complain:** {{complaints}}
+-->
+
+**Our Differentiation:** {{differentiation}}
+
 ## Vision
 
 | Before | After |
@@ -307,10 +709,18 @@ Remove `areasRemaining` and `lastCheckpoint`.
 
 ## User Journey
 
-<!-- {{user_journey}} as natural prose -->
+<!-- Per-persona journey from trigger to outcome. This is the high-level map;
+     concrete step-by-step scenarios live in individual feature specs. -->
 
-**Aha Moment:** {{aha_moment}}
-**Primary Action:** {{primary_action}}
+| Stage | Description |
+|-------|-------------|
+| **Trigger** | {{trigger}} |
+| **Discovery** | {{discovery}} |
+| **First Use** | {{first_use}} |
+| **Core Loop** | {{core_loop}} ({{frequency}}) |
+| **Aha Moment** | {{aha_moment}} |
+| **After** | {{after}} |
+| **Return** | {{return_trigger}} |
 
 ## Principles
 
@@ -330,18 +740,46 @@ Remove `areasRemaining` and `lastCheckpoint`.
 **Metric:** {{success_metric}}
 **Leading Indicator:** {{leading_indicator}}
 
+## Risks & Mitigations
+
+<!-- Each risk must have a mitigation. A risk without a response is just worry. -->
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {{risk}} | {{impact}} | {{mitigation}} |
+
 ## Open Questions
 
 <!-- Only include if discussed. Omit if the project is clear enough. -->
 
-**Risks:**
-- {{risk}}
+- {{open_question}}
 
-**Assumptions:**
-- {{assumption}}
+## Assumptions
 
-**Unknowns:**
-- {{open_question}}
+<!-- Always include. These are beliefs surfaced during exploration that haven't been validated.
+     Each assumption notes what would change if wrong AND how to respond. -->
+
+- {{assumption}} — if wrong: {{impact}} → response: {{response}}
+
+## Key Decisions
+
+<!-- Record the 3-5 most consequential decisions made during project definition.
+     Each entry: what was decided, what alternatives were considered, why this path. -->
+
+| Decision | Alternatives Considered | Why This Path |
+|----------|------------------------|---------------|
+| {{decision}} | {{alternatives}} | {{rationale}} |
+
+## Feature Registry
+
+<!-- Index of all features. Updated each time a new feature is defined via /know-thy-build:feature.
+     This section makes PROJECT.md the single entry point for the full project picture. -->
+
+| # | Feature | Priority | Depends On | Status |
+|---|---------|----------|------------|--------|
+| {{id}} | [{{title}}](features/{{NNN}}.md) | {{P0/P1/P2}} | {{depends_on}} | {{status}} |
+
+**Technical Foundation:** [TECHNICAL.md](TECHNICAL.md)
 
 ---
 
@@ -459,19 +897,82 @@ If `CLAUDE.md` exists → prepend reference (if not already present). If not →
 **Reference to add:**
 ```markdown
 ## Project Compass
-This project follows the principles defined in [PROJECT.md](./PROJECT.md).
-AI agents MUST read PROJECT.md before starting any work.
+This project follows the principles defined in [PROJECT.md](./docs/PROJECT.md).
+AI agents MUST read docs/PROJECT.md before starting any work.
 NON-NEGOTIABLE rules in PROJECT.md cannot be overridden.
+
+## Development Workflow
+
+### Orchestrator Model
+The user session acts as **orchestrator only** — it does NOT implement directly.
+All implementation is delegated to sub-agents with explicit scope and goals.
+
+### Implementation Flow
+
+1. **Orchestrator identifies work** from `docs/features/NNN.md`
+   - Determines scope: which files, which components, what changes
+   - Sets goal: specific acceptance criteria from the feature spec
+   - Dispatches implementation sub-agent
+
+2. **Implementation sub-agent — Pre-work (mandatory)**
+   Before writing any code, the sub-agent MUST read:
+   - `docs/PROJECT.md` — project principles and boundaries
+   - `docs/TECHNICAL.md` — technical decisions and patterns
+   - `docs/features/NNN.md` — feature spec, acceptance criteria, design intent
+   The sub-agent confirms its understanding of scope and goal before proceeding.
+
+3. **Implementation sub-agent — Execution**
+   Implements within the defined scope. Does not expand beyond the goal.
+
+4. **Post-implementation review (mandatory)**
+   After implementation, the sub-agent dispatches **three review agents**:
+
+   **Designer Review Agent:**
+   - Reads the feature's Design Intent Map (if present)
+   - Verifies every design intent step is correctly reflected in implementation
+   - Checks all UI states are handled (empty, loading, error, success)
+   - Adopts the most critical stance — assumes implementation is wrong until proven otherwise
+   - Produces checklist: `- [x]` passed or `- [ ]` failed with specific reason
+
+   **Architect Review Agent:**
+   - Reads `docs/TECHNICAL.md` and the feature spec
+   - Verifies code follows technical decisions, patterns, and constraints
+   - Checks code structure, naming, boundaries, and error handling
+   - Adopts the most critical stance — looks for what will break, not what looks nice
+   - Produces checklist: `- [x]` passed or `- [ ]` failed with specific reason
+
+5. **Designer + Architect must both pass before QA begins.**
+
+6. **QA Review Agent (mandatory — runs the product)**
+   - Actually starts the application and tests it as a real user
+   - Executes every acceptance criterion from the feature spec step by step
+   - Tests edge cases: interruption (refresh, back, cancel), concurrency (multi-tab), boundary (empty, max, special chars), state corruption (expired session, deleted resource)
+   - Captures evidence for every test: screenshots, console output, state checks
+   - Adopts the most paranoid, impatient, careless user persona
+   - Produces checklist: `- [x]` passed with evidence or `- [ ]` failed with reproduction steps
+
+7. **Review loop**
+   - If ANY criterion is `[ ]` (failed): implementer fixes and re-submits
+   - Designer + Architect re-review if changes are structural
+   - QA re-tests failed scenarios + regression check on happy path
+   - Loop continues until ALL reviewers' criteria are `[x]`
+   - Only when all three reviewers fully pass does the orchestrator accept the work
+
+### Document References
+- Project definition: `docs/PROJECT.md`
+- Technical foundation: `docs/TECHNICAL.md`
+- Feature specs: `docs/features/NNN.md`
+- Feature registry: `docs/PROJECT.md` → Feature Registry section
 ```
 
 ## Closing
 
 **After CREATE:**
-- PROJECT.md has been generated.
+- `docs/PROJECT.md` has been generated.
 - This document is the compass for all agents working on this project.
 - Run `/know-thy-build:project` again when the project's direction shifts.
 
 **After EVOLVE:**
-- PROJECT.md has been updated.
+- `docs/PROJECT.md` has been updated.
 - The changelog records not just what changed, but why.
 - Run `/know-thy-build:project` again whenever the direction shifts.