know-thy-build 0.5.0 → 0.6.0

package/bin/cli.js

@@ -122,13 +122,17 @@ function install(lang, global) {
     Define (once):
       /know-thy-build:project      Define your project (What & Why)
       /know-thy-build:technical    Define technical foundation (How)
-      /know-thy-build:qa           Set up QA framework (environment + test axes)
 
-    Per feature (repeat):
-      /know-thy-build:feature      Design a feature (stories + AC + design intent)
-      /know-thy-build:qa           Define test cases (what "done" means)
-      /know-thy-build:designer     [optional] UX deep dive (heuristics, prototyping)
-      /know-thy-build:architect    [optional] Code design (stubs, tests, sub-agents)
+    Per feature (worktree workflow):
+      /know-thy-build:feature      Design feature spec (main) → create worktree → dispatch sub-agent
+
+      Sub-agent orchestrates in worktree:
+        Define:
+          /know-thy-build:architect    Code structure (stubs, tests)
+          /know-thy-build:designer     UX design intent (UI features)
+          /know-thy-build:qa           Test cases (what "done" means)
+        Implement → Review → Gate check
+          /know-thy-build:finish       Merge gate + squash merge + cleanup
 
   Start with /know-thy-build:project
 `);
@@ -148,12 +152,13 @@ if (args.includes("--help") || args.includes("-h")) {
     npx know-thy-build --lang ko    Skip language prompt
 
   Commands installed:
-    :project     Define what and why                → docs/PROJECT.md
+    :project     Define what and why                → docs/PROJECT.md + CLAUDE.md + hooks
     :technical   Define how to build                → docs/TECHNICAL.md
+    :feature     Design feature + worktree + agent  → docs/features/NNN.md + worktree
+    :architect   Code structure (stubs, tests)      → scaffold + signature tests
+    :designer    UX design intent (UI features)     → design intent in feature spec
     :qa          QA framework + test the product    → docs/QA.md
-    :feature     Design a specific feature          → docs/features/NNN.md
-    :designer    UX deep dive (optional)            → ## Design in feature spec
-    :architect   Implementation design (optional)   → Code stubs + tests
+    :finish      Merge gate + squash merge          → main branch + cleanup
 
   Options:
     --global, -g    Install to ~/.claude/commands/ (available in all projects)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Multi-agent project definition & QA framework for Claude Code — Socratic dialogue, behavioral testing axes, design intent, orchestrated review",
   "bin": {
     "know-thy-build": "./bin/cli.js"

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

@@ -48,6 +48,21 @@ State your chosen granularity and why. The user can override.
 
 ## Before You Begin
 
+### 0. Worktree detection
+
+Check if you're working in the correct worktree:
+
+```bash
+REPO=$(basename $(git rev-parse --show-toplevel))
+BRANCH=$(git branch --show-current)
+```
+
+**If the branch starts with `feature/`:** You're in the worktree. Proceed.
+**If the branch is `main` or `master`:**
+- Check if `../${REPO}-wt` exists
+- If yes: "You should be working in the worktree at `../${REPO}-wt`. Switch there before proceeding."
+- If no: "No worktree found. Run `/know-thy-build:feature` first to create the feature spec and worktree."
+
 ### 1. Read all context
 
 ```bash
@@ -596,3 +611,26 @@ Documented for future implementation when usage data confirms which constraints
 2. If editing a stub file and changing lines with `PRE:` or `POST:`: exit 2 with "Contract comments are protected"
 
 **When to implement:** When real-world usage shows sub-agents modifying signature tests or contract comments despite explicit instructions.
+
+---
+
+## Gate Update
+
+After all verification passes (Phase 4 complete), update the feature spec's gate:
+
+1. Find the active feature spec:
+   ```bash
+   FEATURE_NUM=$(git branch --show-current | grep -oE '[0-9]+' | head -1)
+   FEATURE_FILE="docs/features/$(printf '%03d' $FEATURE_NUM).md"
+   ```
+
+2. Update gate status in the frontmatter:
+   Change `architect: pending` to `architect: passed` in the `gate:` section.
+
+3. Add the current date next to the status:
+   ```yaml
+   gate:
+     architect: passed  # {{date}}
+   ```
+
+This gate update is recorded in the worktree. It will be merged to main with the rest of the feature's changes via `/know-thy-build:finish`.

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

@@ -108,6 +108,21 @@ Does this match what you're imagining? Anything that feels off?
 
 ## Before You Begin
 
+### 0. Worktree detection
+
+Check if you're working in the correct worktree:
+
+```bash
+REPO=$(basename $(git rev-parse --show-toplevel))
+BRANCH=$(git branch --show-current)
+```
+
+**If the branch starts with `feature/`:** You're in the worktree. Proceed.
+**If the branch is `main` or `master`:**
+- Check if `../${REPO}-wt` exists
+- If yes: "You should be working in the worktree at `../${REPO}-wt`. Switch there before proceeding."
+- If no: "No worktree found. Run `/know-thy-build:feature` first to create the feature spec and worktree."
+
 ### 1. Read all context
 
 ```bash
@@ -634,3 +649,24 @@ Append to the feature's `## Changes` section:
 - Design section has been updated with affected changes
 - QA Checklist items updated to match
 - Changes recorded in the feature spec
+
+## Gate Update
+
+After design work is complete and documented, update the feature spec's gate:
+
+1. Find the active feature spec:
+   ```bash
+   FEATURE_NUM=$(git branch --show-current | grep -oE '[0-9]+' | head -1)
+   FEATURE_FILE="docs/features/$(printf '%03d' $FEATURE_NUM).md"
+   ```
+
+2. Update gate status in the frontmatter:
+   Change `designer: pending` to `designer: passed` in the `gate:` section.
+
+3. Add the current date next to the status:
+   ```yaml
+   gate:
+     designer: passed  # {{date}}
+   ```
+
+This gate update is recorded in the worktree. It will be merged to main with the rest of the feature's changes via `/know-thy-build:finish`.

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

@@ -367,8 +367,14 @@ id: {{number}}
 title: {{short_title}}
 status: complete
 priority: {{P0|P1|P2}}
+class: {{Spike|Bounded|Architectural}}
 depends_on: [{{feature_ids}}]
 persona: {{primary_persona_name from PROJECT.md}}
+gate:
+  worktree: null
+  architect: pending
+  designer: pending    # set to 'skipped' for non-UI features
+  qa: pending
 assumptions:
   - "{{assumption}}"
 date: {{date}}
@@ -376,6 +382,12 @@ generatedBy: know-thy-build-feature
 ---
 ```
 
+**Gate initialization rules:**
+- **Spike**: No gate field. Spikes produce answers, not implementations.
+- **Bounded (non-UI)**: `architect: pending`, `designer: skipped`, `qa: pending`
+- **Bounded (UI)**: `architect: pending`, `designer: pending`, `qa: pending`
+- **Architectural**: All `pending`
+
 **Priority guide:**
 - **P0**: Must-have for MVP. Without this, the project doesn't deliver its core value.
 - **P1**: Important. Significantly improves the experience but the project works without it.
@@ -573,14 +585,123 @@ This keeps PROJECT.md as the single entry point for the full project picture.
 
 ## Closing
 
-**After CREATE:**
+**After CREATE (Spike):**
+- No worktree, no gate, no implementation. The spike's output is an answer.
+- Run `/know-thy-build:feature` again if the spike reveals something worth building.
+
+**After CREATE (Bounded / Architectural):**
 - Feature spec has been saved to `docs/features/{{NNN}}.md`
 - Feature Registry in `docs/PROJECT.md` has been updated
-- **Next step (mandatory):** `/know-thy-build:qa` — define test cases in `docs/QA.md`. This is what makes "done" concrete. Without test cases, there is no definition of "done."
-- Optional next steps:
-  - **UX deep dive**: `/know-thy-build:designer` — if this feature has complex UI
-  - **Implementation design**: `/know-thy-build:architect` — if this feature is Architectural
-- Run `/know-thy-build:feature` again for the next feature
+
+### Worktree Setup
+
+1. Detect the repo name:
+   ```bash
+   REPO=$(basename $(git rev-parse --show-toplevel))
+   WT_PATH="../${REPO}-wt"
+   ```
+
+2. Check for existing worktree:
+   ```bash
+   git worktree list
+   ls -d "$WT_PATH" 2>/dev/null
+   ```
+
+3. **If `$WT_PATH` already exists:**
+   > "Worktree `$WT_PATH` already exists (branch: {{branch}}). Options:"
+   > 1. Continue with existing worktree (previous feature is in progress)
+   > 2. Remove existing worktree and create new one
+   > 3. Skip worktree (work in main)
+   
+   If user chooses option 1 or 3, skip creation. If option 2, run `git worktree remove "$WT_PATH"` first.
+
+4. **Create worktree:**
+   ```bash
+   git worktree add "$WT_PATH" -b "feature/{{NNN}}-{{short_title_kebab}}"
+   ```
+
+5. Confirm:
+   > "Worktree created at `$WT_PATH` on branch `feature/{{NNN}}-{{short_title_kebab}}`."
+
+6. Update feature spec frontmatter:
+   ```yaml
+   gate:
+     worktree: feature/{{NNN}}-{{short_title_kebab}}
+   ```
+
+### Sub-agent Dispatch
+
+After worktree creation, dispatch a sub-agent to orchestrate the entire feature lifecycle in the worktree.
+
+Use the **Agent tool** with `isolation: "worktree"` is NOT needed here — the worktree is already created manually above. Instead, dispatch the sub-agent with an explicit working directory.
+
+**Sub-agent prompt:**
+
+```
+You are the feature orchestrator for Feature {{NNN}}: {{title}}.
+Your working directory is: {{WT_PATH}}
+
+Read these files first:
+- docs/PROJECT.md — project principles
+- docs/TECHNICAL.md — technical decisions
+- docs/features/{{NNN}}.md — this feature's spec and gate status
+
+## Your job: Define → Implement → Review → Finish
+
+### Phase 1: Define
+Run each role to define their criteria for this feature:
+
+1. Run /know-thy-build:architect
+   - Reads the feature spec
+   - Designs structure: CRC cards, scaffolds, signature tests
+   - Creates stub files with PRE/POST/WHY/EXAMPLE comments
+   - Creates signature contract tests
+
+2. Run /know-thy-build:designer (skip if gate.designer is 'skipped')
+   - Reads the feature spec
+   - Defines design intent map, state catalog, micro-interactions
+   - Updates the feature spec with detailed design intent
+
+3. Run /know-thy-build:qa in REVIEW mode
+   - Reads the feature spec + architect scaffolds + design intent
+   - Defines concrete test cases in docs/QA.md
+   - Each test case has verification method and expected evidence
+
+### Phase 2: Implement
+Fill the scaffolds:
+- Read all stub files with // IMPLEMENT markers
+- Implement each stub following PRE/POST/WHY contracts
+- Run tests after each implementation to verify
+- Do NOT modify signature contract tests (DO NOT MODIFY markers)
+
+### Phase 3: Review
+Submit implementation for review by each role:
+
+1. Architect review:
+   - Verify code follows scaffolds, conventions, and TECHNICAL.md
+   - Check all signature tests pass
+   - Check no // IMPLEMENT markers remain
+   - Update docs/features/{{NNN}}.md: gate.architect → passed
+
+2. Designer review (skip if gate.designer is 'skipped'):
+   - Verify UI matches design intent map
+   - Check all states are handled (empty, error, loading, success)
+   - Update docs/features/{{NNN}}.md: gate.designer → passed
+
+3. QA TEST:
+   - Actually run the product
+   - Execute every test case from docs/QA.md for this feature
+   - Capture evidence (screenshots, console output, state checks)
+   - Update docs/features/{{NNN}}.md: gate.qa → passed
+
+If any review fails → fix and re-submit. Loop until all gates pass.
+
+### Phase 4: Finish
+When all gates are passed/skipped, run /know-thy-build:finish.
+```
+
+> "Sub-agent dispatched to worktree. It will run define → implement → review → finish automatically."
+> "You can continue working on other things in main, or run `/know-thy-build:feature` for the next feature."
 
 **After EDIT:**
 - Feature spec has been updated

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

@@ -0,0 +1,258 @@
+---
+description: Merge a completed feature — checks all review gates, squash merges to main, cleans up worktree. The final step in the feature lifecycle.
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
+---
+
+# Know Thy Build — Finish
+
+You are the **release gate**. Your job is to verify that all review gates have passed, then merge the feature to main and clean up.
+
+You do NOT implement, review, or test. You only verify the gate and execute the merge.
+
+## Language
+
+**All conversation and output MUST be in: {{LANG}}**
+
+Technical terms (e.g. merge, squash, worktree, gate) stay in English. Everything else uses the specified language.
+
+---
+
+## Before You Begin
+
+### 1. Verify worktree context
+
+```bash
+REPO=$(basename $(git rev-parse --show-toplevel))
+BRANCH=$(git branch --show-current)
+WT_PATH="../${REPO}-wt"
+```
+
+**If the branch does NOT start with `feature/`:**
+> "This command must be run from a feature worktree. Current branch: `{{branch}}`."
+→ Stop here.
+
+### 2. Identify the feature
+
+```bash
+FEATURE_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
+FEATURE_FILE="docs/features/$(printf '%03d' $FEATURE_NUM).md"
+```
+
+Read the feature spec and extract the gate section from frontmatter.
+
+---
+
+## Gate Check
+
+Read the `gate:` section from the feature spec's YAML frontmatter.
+
+### Display gate status
+
+Present a clear gate status report:
+
+```
+🚦 Gate Check — Feature {{NNN}}: {{title}}
+
+  Architect:  {{status}}  {{date if passed}}
+  Designer:   {{status}}  {{date if passed}}
+  QA:         {{status}}  {{date if passed}}
+```
+
+### Evaluate
+
+**All gates `passed` or `skipped`:**
+> "All gates passed. Ready to merge."
+→ Proceed to Pre-merge Verification.
+
+**Any gate is `pending`:**
+> "Cannot merge — pending reviews:"
+> - `{{role}}`: pending — run `/know-thy-build:{{role}}` to complete
+
+→ Stop here. Do NOT proceed with merge.
+
+---
+
+## Pre-merge Verification
+
+Before merging, verify the worktree is in a clean, mergeable state:
+
+### 1. Check for uncommitted changes
+
+```bash
+git status --porcelain
+```
+
+If there are uncommitted changes:
+> "Uncommitted changes detected. Commit or stash before merging."
+→ Offer to commit with a descriptive message.
+
+### 2. Verify no IMPLEMENT markers remain
+
+```bash
+grep -rn "// IMPLEMENT\|# IMPLEMENT\|throw new Error('Not implemented')" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" --include="*.rs" . 2>/dev/null
+```
+
+If any remain:
+> "Implementation markers found — the feature is not fully implemented."
+→ Stop here.
+
+### 3. Verify tests pass
+
+```bash
+# Detect test runner from package.json, pyproject.toml, etc.
+# Run appropriate test command
+```
+
+If tests fail:
+> "Tests are failing. Fix before merge."
+→ Stop here.
+
+### 4. Verify artifacts exist
+
+Check that each role left its artifacts in the worktree:
+
+```bash
+# Architect artifacts: scaffold files, signature tests
+grep -rn "DO NOT MODIFY" --include="*.test.*" --include="*_test.*" . 2>/dev/null | head -5
+
+# QA artifacts: test cases in QA.md
+grep -c "Feature {{NNN}}" docs/QA.md 2>/dev/null
+```
+
+Report what will be merged to main:
+> "The following artifacts from this feature will be merged to main:"
+> - Code: {{list of modified/new source files}}
+> - Architect: scaffold structure, signature tests
+> - Designer: design intent updates in feature spec (if applicable)
+> - QA: test cases in `docs/QA.md`
+> - Feature spec: gate statuses updated
+
+---
+
+## Merge
+
+### 1. Switch to main and merge
+
+```bash
+# Ensure main is up to date
+git checkout main
+git pull --ff-only origin main 2>/dev/null || true
+
+# Squash merge
+git merge --squash "feature/{{NNN}}-{{title_kebab}}"
+```
+
+### 2. Create commit
+
+```bash
+git commit -m "feat({{NNN}}): {{title}}
+
+- Architect: {{brief summary of structure decisions}}
+- Designer: {{brief summary of design decisions, or 'skipped'}}
+- QA: {{number}} test cases passed
+
+Feature spec: docs/features/{{NNN}}.md
+Gate: architect ✓ | designer ✓/skipped | qa ✓"
+```
+
+### 3. Update feature spec status
+
+Switch back briefly or edit from main — update the feature spec frontmatter:
+
+```yaml
+status: complete
+gate:
+  worktree: null  # worktree removed
+  architect: passed
+  designer: passed  # or skipped
+  qa: passed
+```
+
+### 4. Update Feature Registry
+
+In `docs/PROJECT.md`, update the Feature Registry row for this feature:
+```
+| {{NNN}} | [{{title}}](features/{{NNN}}.md) | {{priority}} | {{depends_on}} | complete |
+```
+
+---
+
+## Cleanup
+
+### 1. Remove worktree
+
+```bash
+git worktree remove "$WT_PATH"
+```
+
+If removal fails (dirty worktree):
+```bash
+git worktree remove --force "$WT_PATH"
+```
+
+### 2. Delete feature branch
+
+```bash
+git branch -d "feature/{{NNN}}-{{title_kebab}}"
+```
+
+### 3. Prune stale worktree metadata
+
+```bash
+git worktree prune
+```
+
+---
+
+## Report
+
+Present the final summary:
+
+```
+✅ Feature {{NNN}}: {{title}} — merged to main
+
+Commit: {{short hash}} feat({{NNN}}): {{title}}
+Branch: feature/{{NNN}}-{{title_kebab}} — deleted
+Worktree: {{WT_PATH}} — removed
+
+Artifacts merged:
+  - Code changes: {{file count}} files
+  - Architect structure: preserved in code + signature tests
+  - Designer intent: preserved in docs/features/{{NNN}}.md
+  - QA test cases: preserved in docs/QA.md
+  - Gate history: preserved in docs/features/{{NNN}}.md frontmatter
+
+Next: /know-thy-build:feature for the next feature
+```
+
+---
+
+## Edge Cases
+
+### Merge conflicts
+
+If `git merge --squash` produces conflicts:
+
+1. List conflicting files
+2. For each conflict, show the conflict markers
+3. Offer resolution options:
+   - Accept worktree version (ours)
+   - Accept main version (theirs)
+   - Manual resolution
+4. After resolution, continue with commit
+
+### Abandoned feature
+
+If the user explicitly wants to abandon the feature without merging:
+
+```bash
+git checkout main
+git worktree remove --force "$WT_PATH"
+git branch -D "feature/{{NNN}}-{{title_kebab}}"
+git worktree prune
+```
+
+Update feature spec: `status: abandoned`, clear gate.
+Update Feature Registry: status → `abandoned`.
+
+> "Feature {{NNN}} abandoned. Worktree and branch removed. Spec preserved for reference."