gsd-code-first 1.0.3 → 1.1.0

package/commands/gsd/prototype.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:prototype
-description: Build a working code prototype with embedded @gsd-tags using gsd-prototyper, then auto-run extract-plan
-argument-hint: "[path] [--phases N]"
+description: PRD-driven prototype pipeline — ingests PRD, extracts acceptance criteria, confirms with user, then spawns gsd-prototyper to build annotated code scaffold with @gsd-todo(ref:AC-N) tags. Supports --prd for explicit PRD path, --interactive for step-by-step mode, and --non-interactive for CI pipelines.
+argument-hint: "[path] [--phases N] [--prd <path>] [--interactive] [--non-interactive]"
 allowed-tools:
   - Read
   - Write
@@ -10,16 +10,27 @@ allowed-tools:
   - Task
   - Glob
   - Grep
+  - AskUserQuestion
 ---
 
 <objective>
-Spawns the `gsd-prototyper` agent to build working prototype code with `@gsd-tags` embedded following the ARC annotation standard. On completion, automatically runs `extract-plan` to produce `.planning/prototype/CODE-INVENTORY.md`.
+Spawns the `gsd-prototyper` agent to build working prototype code with `@gsd-tags` embedded following the ARC annotation standard. Before spawning the agent, this command ingests a PRD (Product Requirements Document), extracts acceptance criteria semantically, presents them to the user for confirmation, and enriches the gsd-prototyper Task() prompt with the confirmed AC list so each acceptance criterion becomes a `@gsd-todo(ref:AC-N)` tag in the prototype code.
+
+On completion, automatically runs `extract-tags` to produce `.planning/prototype/CODE-INVENTORY.md`.
 
 **Arguments:**
 - `path` — target directory for prototype output (defaults to project root if omitted)
 - `--phases N` — scope the prototype to specific phase numbers from ROADMAP.md (e.g., `--phases 2` or `--phases 2,3`); only requirements belonging to those phases will be prototyped
+- `--prd <path>` — explicit path to a PRD file; takes priority over auto-detection
+- `--interactive` — pause after each iteration in the autonomous loop to show progress and ask whether to continue
+- `--non-interactive` — skip the AC confirmation gate and auto-approve (for CI/headless pipelines)
+
+**PRD resolution priority chain:**
+1. `--prd <path>` flag — use the specified file
+2. Auto-detect `.planning/PRD.md` — use if present
+3. Paste prompt — ask user to paste PRD content via AskUserQuestion
 
-The prototyper reads `PROJECT.md`, `REQUIREMENTS.md`, and `ROADMAP.md` before building so all generated code reflects actual project goals, requirement IDs, and phase structure.
+**Key guarantee:** Each acceptance criterion from the PRD becomes exactly one `@gsd-todo(ref:AC-N)` tag in the prototype code, enabling the extract-tags completeness check.
 </objective>
 
 <context>
@@ -32,25 +43,283 @@ $ARGUMENTS
 
 <process>
 
-1. **Spawn gsd-prototyper agent** via the Task tool, passing `$ARGUMENTS` as context. The agent will:
-   - Read `get-shit-done/references/arc-standard.md` for the ARC tag standard
-   - Read `PROJECT.md`, `REQUIREMENTS.md`, and `ROADMAP.md` for project context and requirement IDs
-   - If `--phases N` is present in `$ARGUMENTS`, filter to only requirements for those phases
-   - Plan and create prototype files with `@gsd-tags` embedded in comments
-   - Write `.planning/prototype/PROTOTYPE-LOG.md` capturing files created, decisions made, and open todos
-
-2. **Wait for gsd-prototyper to complete** and note its summary output (files created, total tags embedded, breakdown by tag type).
-
-3. **Auto-run extract-plan** to produce CODE-INVENTORY.md from the annotated prototype:
-   ```bash
-   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" extract-tags --format md --output .planning/prototype/CODE-INVENTORY.md
-   ```
-   This scans all prototype files for `@gsd-tags` and writes `.planning/prototype/CODE-INVENTORY.md` grouped by tag type and file, with summary statistics and a phase reference index.
-
-4. **Show the user the results:**
-   - Files created (from gsd-prototyper summary)
-   - Total @gsd-tags embedded (from gsd-prototyper summary)
-   - Path to PROTOTYPE-LOG.md: `.planning/prototype/PROTOTYPE-LOG.md`
-   - Path to CODE-INVENTORY.md: `.planning/prototype/CODE-INVENTORY.md`
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for the following flags:
+
+- **`--prd <path>`** — if present, note the path value that follows `--prd` as `prd_path`
+- **`--interactive`** — if present, set `interactive_mode = true`
+- **`--non-interactive`** — if present, set `non_interactive_mode = true`
+- **`--phases N`** — if present, note the value for passing to gsd-prototyper
+
+Log the parsed flags so the user can confirm the invocation was understood.
+
+## Step 1: Resolve PRD content
+
+Resolve `prd_content` using the following priority chain. All three paths produce the same `prd_content` variable for downstream processing. Log which resolution path was used.
+
+**Priority 1 — `--prd <path>` flag is present:**
+
+Read the file at `<path>` using the Read tool.
+
+If the file does not exist, STOP and report:
+> "prototype failed at step 1: PRD file not found at `<path>`. Check the path and try again."
+
+Log: "PRD source: --prd flag (`<path>`)"
+
+**Priority 2 — `--prd` is NOT present, check for `.planning/PRD.md`:**
+
+Run:
+```bash
+test -f .planning/PRD.md && echo "exists" || echo "missing"
+```
+
+If the result is `"exists"`: Read `.planning/PRD.md` using the Read tool.
+
+Log: "PRD source: auto-detected .planning/PRD.md"
+
+**Priority 3 — neither `--prd` nor `.planning/PRD.md` is present:**
+
+Use AskUserQuestion:
+> "No PRD file found at `.planning/PRD.md`. You can:
+> - Paste your full PRD content below, OR
+> - Type `skip` to run without a PRD (backward-compatible behavior — prototype uses PROJECT.md and REQUIREMENTS.md only)
+>
+> Paste PRD content or type 'skip':"
+
+If the user types `skip`: proceed directly to Step 4 without PRD context (no AC extraction, no confirmation gate, standard prototype spawn behavior).
+
+If the user pastes content: use that as `prd_content`. If the content is longer than 5000 characters, confirm: "Received N characters of PRD content. Proceeding to acceptance criteria extraction."
+
+Log: "PRD source: pasted content"
+
+## Step 2: Extract acceptance criteria
+
+**Skip this step if the user typed `skip` in Step 1.**
+
+Using the PRD content obtained in Step 1, extract all acceptance criteria semantically. Apply the following extraction prompt to `prd_content`:
+
+---
+
+Extract all acceptance criteria, requirements, and success conditions from the following PRD.
+Output format — one per line:
+AC-1: [description in imperative form]
+AC-2: [description in imperative form]
+...
+
+Rules:
+- Include ACs from prose paragraphs, bullet lists, tables, and user stories
+- Normalize user stories to acceptance criteria form ("User can..." → "Users can...")
+- If the PRD has explicit numbered/labeled ACs, preserve their intent but renumber sequentially
+- If no explicit ACs exist, infer them from goals and scope sections
+- Output ONLY the numbered list — no headers, no commentary
+
+PRD content:
+[prd_content]
+
+---
+
+Store the resulting numbered list as `ac_list`. Count the total: `ac_count = N`.
+
+## Step 3: Confirmation gate
+
+**Skip this step if the user typed `skip` in Step 1.**
+
+Check if `--non-interactive` is present in `$ARGUMENTS`.
+
+**If `--non-interactive` IS present:**
+
+Log: "Auto-approving N acceptance criteria (--non-interactive mode)." and proceed to Step 4.
+
+**If `--non-interactive` is NOT present:**
+
+Display the numbered AC list to the user clearly:
+
+```
+Found N acceptance criteria from PRD:
+
+AC-1: [description]
+AC-2: [description]
+...
+```
+
+Then use AskUserQuestion:
+> "Found N acceptance criteria from PRD. Review the list above. Proceed with prototype generation? [yes / provide corrections]"
+
+- If the user says `yes`, `y`, or `approve`: proceed to Step 4.
+- If the user provides corrections or changes: incorporate the corrections into `ac_list`, re-display the updated list, and repeat the confirmation question (loop back to the start of this step with the updated list). Continue until the user approves.
+
+**IMPORTANT:** There is NO code path that reaches Step 4 without explicit approval or `--non-interactive`. The confirmation gate is mandatory.
+
+## Step 4: Spawn gsd-prototyper (first pass)
+
+Spawn the `gsd-prototyper` agent via the Task tool.
+
+**If PRD was provided (user did NOT type `skip`):**
+
+Pass the following enriched context in the Task() prompt:
+
+```
+$ARGUMENTS
+
+**Acceptance criteria to implement as @gsd-todo tags:**
+[paste ac_list here — the full numbered list from Step 2/3]
+
+For each acceptance criterion listed above, create exactly one @gsd-todo tag with `ref:AC-N` metadata in the prototype code where N is the criterion number. The tag must appear on a dedicated comment line (not trailing).
+
+Example:
+// @gsd-todo(ref:AC-1) User can run /gsd:prototype with PRD auto-detection at .planning/PRD.md
+// @gsd-todo(ref:AC-3, priority:high) User is prompted to paste PRD content if no file is found
+
+The @gsd-todo(ref:AC-N) tags are the primary completeness tracking mechanism. Every AC in the list above must have exactly one corresponding tag in the prototype code.
+
+The agent will also:
+- Read `get-shit-done/references/arc-standard.md` for the ARC tag standard
+- Read `PROJECT.md`, `REQUIREMENTS.md`, and `ROADMAP.md` for project context and requirement IDs
+- If `--phases N` is present in the arguments, filter to only requirements for those phases
+- Plan and create prototype files with `@gsd-tags` embedded in comments
+- Write `.planning/prototype/PROTOTYPE-LOG.md` capturing files created, decisions made, and open todos
+```
+
+**If PRD was skipped (user typed `skip`):**
+
+Pass only `$ARGUMENTS` as context (standard prototype spawn behavior):
+
+```
+$ARGUMENTS
+
+The agent will:
+- Read `get-shit-done/references/arc-standard.md` for the ARC tag standard
+- Read `PROJECT.md`, `REQUIREMENTS.md`, and `ROADMAP.md` for project context and requirement IDs
+- If `--phases N` is present in the arguments, filter to only requirements for those phases
+- Plan and create prototype files with `@gsd-tags` embedded in comments
+- Write `.planning/prototype/PROTOTYPE-LOG.md` capturing files created, decisions made, and open todos
+```
+
+Wait for gsd-prototyper to complete and note its summary output (files created, total tags embedded, breakdown by tag type).
+
+## Step 5: Run extract-tags
+
+Auto-run extract-tags to produce CODE-INVENTORY.md from the annotated prototype:
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" extract-tags --format md --output .planning/prototype/CODE-INVENTORY.md
+```
+
+This scans all prototype files for `@gsd-tags` and writes `.planning/prototype/CODE-INVENTORY.md` grouped by tag type and file, with summary statistics and a phase reference index.
+
+**If PRD was provided (user did NOT type `skip`):**
+
+Count AC-linked todos:
+```bash
+grep -c "ref:AC-" .planning/prototype/CODE-INVENTORY.md 2>/dev/null || echo "0"
+```
+
+Log: "AC todos remaining: N" (where N is the grep count).
+
+If N is 0 and `ac_count > 0`, warn: "Warning: no AC-linked @gsd-todo tags found in CODE-INVENTORY.md. The prototype may not have implemented the accepted AC list. Check that gsd-prototyper received the AC list and used `ref:AC-N` metadata in @gsd-todo tags."
+
+**If PRD was skipped:**
+
+Log: "No PRD-linked todos to track."
+
+**Show the user the results:**
+- Files created (from gsd-prototyper summary)
+- Total @gsd-tags embedded (from gsd-prototyper summary)
+- AC todos remaining (if PRD was provided): N of ac_count
+- Path to PROTOTYPE-LOG.md: `.planning/prototype/PROTOTYPE-LOG.md`
+- Path to CODE-INVENTORY.md: `.planning/prototype/CODE-INVENTORY.md`
+
+## Step 6 — Autonomous iteration loop
+
+**Skip this step entirely if no PRD was provided** (user typed 'skip' in Step 1). In that case, proceed directly to Step 7.
+
+Initialize iteration counter: `ITERATION=0`
+Maximum iterations: 5 (hard cap per D-05)
+
+**Loop start:**
+
+Check the AC_REMAINING count from Step 5 (or from the previous iteration's recount).
+
+**If AC_REMAINING is 0:** Log "All PRD acceptance criteria resolved after [ITERATION] iteration(s)." and proceed to Step 7.
+
+**If ITERATION equals 5:** Log "Hard iteration cap (5) reached. [AC_REMAINING] AC-linked todos remain unresolved." and proceed to Step 7.
+
+**Otherwise, run one iteration:**
+
+**6a.** Increment ITERATION counter.
+
+**6b.** Log: "--- Iteration [ITERATION]/5 --- ([AC_REMAINING] AC todos remaining)"
+
+**6c. Spawn gsd-code-planner** via Task tool:
+- Pass `.planning/prototype/CODE-INVENTORY.md` as primary input
+- The code-planner reads `@gsd-todo` tags as the task backlog
+- Wait for plan to be produced in `.planning/prototype/`
+
+**6d. Auto-approve the inner plan.** Log: "Auto-approving iteration plan (autonomous prototype mode)."
+Do NOT use AskUserQuestion here — the outer confirmation gate (Step 3) already captured user intent. Inner plans are always auto-approved per research recommendation.
+
+**6e. Spawn executor** based on ARC mode:
+```bash
+ARC_ENABLED=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get arc.enabled 2>/dev/null || echo "true")
+```
+- If ARC_ENABLED is "true": spawn `gsd-arc-executor` via Task tool
+- If ARC_ENABLED is "false": spawn `gsd-executor` via Task tool
+- Pass the plan path from `.planning/prototype/` as context
+- Wait for executor to complete
+
+**6f. Re-run extract-tags** to refresh CODE-INVENTORY.md:
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" extract-tags --format md --output .planning/prototype/CODE-INVENTORY.md
+```
+
+**6g. Recount AC-linked todos:**
+```bash
+AC_REMAINING=$(grep -c "ref:AC-" .planning/prototype/CODE-INVENTORY.md 2>/dev/null || echo "0")
+```
+Log: "AC todos remaining after iteration [ITERATION]: [AC_REMAINING]"
+
+**6h. --interactive pause point** (per D-10, implements PRD-06):
+Check if `--interactive` is present in `$ARGUMENTS`.
+
+**If --interactive IS present:**
+Display iteration summary to the user:
+- "Iteration [ITERATION] complete."
+- "Files changed this iteration: [list from executor summary]"
+- "@gsd-todo count remaining: [AC_REMAINING]"
+- "Iterations remaining: [5 - ITERATION]"
+
+Then use AskUserQuestion: "Continue to next iteration? [yes / stop / redirect: instructions]"
+- If `yes`, `y`, or `continue`: loop back to Loop start
+- If `stop`: Log "Stopping at user request." and proceed to Step 7
+- If `redirect: <instructions>`: incorporate user instructions into the next iteration's code-planner context, then loop back
+
+**If --interactive is NOT present:** loop back to Loop start silently (per D-11, fully autonomous).
+
+**Loop end** (reached via AC_REMAINING=0, hard cap, or user stop in --interactive mode).
+
+## Step 7 — Final report
+
+Display completion summary to the user:
+
+```
+prototype complete.
+
+PRD source: [--prd flag | auto-detected .planning/PRD.md | pasted content | none]
+Acceptance criteria: [total ACs found] total, [resolved] resolved, [AC_REMAINING] remaining
+Iterations used: [ITERATION] of 5 maximum
+Executor: [gsd-arc-executor | gsd-executor]
+
+Artifacts:
+- Prototype log: .planning/prototype/PROTOTYPE-LOG.md
+- Code inventory: .planning/prototype/CODE-INVENTORY.md
+- Iteration plans: .planning/prototype/*.md
+```
+
+**If AC_REMAINING > 0:**
+```
+Note: [AC_REMAINING] acceptance criteria remain as @gsd-todo tags.
+Run /gsd:iterate to continue implementation, or /gsd:prototype --interactive to step through remaining items.
+```
 
 </process>

package/commands/gsd/review-code.md

@@ -0,0 +1,249 @@
+---
+name: gsd:review-code
+description: Two-stage prototype code review -- spec compliance check (Stage 1) then code quality evaluation (Stage 2). Runs test suite, spawns gsd-reviewer, writes REVIEW-CODE.md with actionable next steps.
+argument-hint: "[--non-interactive]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Orchestrates a two-stage code review of the current prototype: Stage 1 checks spec compliance (do the PRD acceptance criteria pass?), Stage 2 checks code quality (security, maintainability, error handling, edge cases). Stage 2 only runs if Stage 1 passes.
+
+This command:
+1. Detects the test framework and runs the test suite, capturing results
+2. Resolves the acceptance criteria list from CODE-INVENTORY.md, PRD.md, or REQUIREMENTS.md
+3. Spawns the gsd-reviewer agent with all context it needs (test results + AC list + gate instructions)
+4. Reads the resulting REVIEW-CODE.md and presents a formatted summary to the user
+5. Suggests the next action based on Stage 1 result
+
+The agent (gsd-reviewer) writes `.planning/prototype/REVIEW-CODE.md`. This command orchestrates and presents results.
+
+**Arguments:**
+- `--non-interactive` — skip the final AskUserQuestion prompt (for CI/headless pipelines); still runs full review and writes REVIEW-CODE.md
+</objective>
+
+<context>
+$ARGUMENTS
+
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+</context>
+
+<process>
+
+## Step 0: Parse flags
+
+Check `$ARGUMENTS` for the following flags:
+
+- **`--non-interactive`** -- if present, set `non_interactive_mode = true`
+
+Log the parsed flags so the user can confirm the invocation was understood.
+
+## Step 1: Detect test framework and run tests
+
+Detect the test framework using Phase 7 infrastructure:
+
+```bash
+TEST_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" detect-test-framework "$PWD")
+```
+
+This returns JSON: `{ "framework": "vitest", "testCommand": "npx vitest run", "filePattern": "**/*.test.{ts,js}" }`.
+
+Extract `framework` and `testCommand` from the JSON output:
+
+```bash
+FRAMEWORK=$(echo "$TEST_INFO" | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');console.log(JSON.parse(d).framework)")
+TEST_COMMAND=$(echo "$TEST_INFO" | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');console.log(JSON.parse(d).testCommand)")
+```
+
+Run the test suite and capture the full output including exit code:
+
+```bash
+TEST_OUTPUT=$(eval "$TEST_COMMAND" 2>&1) || true
+TEST_EXIT=$?
+```
+
+Log: "Test framework: {FRAMEWORK} | Command: {TEST_COMMAND} | Exit code: {TEST_EXIT}"
+
+**Handle the no-tests-found case (Pitfall 4):**
+
+After running, check the output for "no test files" / "no tests found" / "found 0 test files" / "no tests matching" patterns:
+
+```bash
+echo "$TEST_OUTPUT" | grep -qi "no test\|no tests\|0 test files\|no spec files\|nothing to run" && TESTS_FOUND=false || TESTS_FOUND=true
+```
+
+If `TESTS_FOUND=false`:
+- Log: "No test files found. Review will proceed without test results. Absence will be noted in REVIEW-CODE.md."
+- Set `tests_run=0`, `tests_passed=0`, `tests_failed=0`
+- Do NOT report "0 tests passed" as a test failure -- absence of tests is distinct from failing tests.
+
+If `TESTS_FOUND=true`:
+- Log full test output summary (first 50 lines + last 20 lines if output is long)
+
+## Step 2: Resolve AC list for Stage 1
+
+Determine the acceptance criteria for Stage 1 spec compliance. Use this resolution priority chain:
+
+**Priority 1 -- CODE-INVENTORY.md has AC-linked tags:**
+
+```bash
+AC_COUNT=$(grep -c "ref:AC-" .planning/prototype/CODE-INVENTORY.md 2>/dev/null || echo "0")
+```
+
+If `AC_COUNT > 0`:
+- Extract AC list from CODE-INVENTORY.md:
+  ```bash
+  grep "ref:AC-" .planning/prototype/CODE-INVENTORY.md | grep -oP "ref:AC-\d+" | sort -u
+  ```
+- Read `.planning/prototype/CODE-INVENTORY.md` using the Read tool to get full AC descriptions from the @gsd-todo tags
+- Log: "AC source: CODE-INVENTORY.md ({AC_COUNT} AC-linked tags found)"
+- Set `SPEC_AVAILABLE=true`, `AC_SOURCE=code-inventory`
+
+**Priority 2 -- PRD.md exists:**
+
+If `AC_COUNT` is 0, check for PRD:
+```bash
+test -f .planning/PRD.md && echo "exists" || echo "missing"
+```
+
+If exists:
+- Read `.planning/PRD.md` using the Read tool
+- Extract ACs using the same semantic extraction as prototype.md Step 2:
+
+  Extract all acceptance criteria, requirements, and success conditions from the PRD.
+  Output format -- one per line:
+  AC-1: [description in imperative form]
+  AC-2: [description in imperative form]
+
+  Rules:
+  - Include ACs from prose paragraphs, bullet lists, tables, and user stories
+  - Normalize user stories to acceptance criteria form
+  - If no explicit ACs, infer from goals and scope sections
+  - Output ONLY the numbered list -- no headers, no commentary
+
+- Log: "AC source: .planning/PRD.md (re-extracted {N} ACs)"
+- Set `SPEC_AVAILABLE=true`, `AC_SOURCE=prd`
+
+**Priority 3 -- REQUIREMENTS.md exists:**
+
+If no PRD, check REQUIREMENTS.md:
+- Read `.planning/REQUIREMENTS.md` using the Read tool
+- Extract requirements as AC substitutes -- use requirement IDs and descriptions as the AC list
+- Log: "AC source: .planning/REQUIREMENTS.md (using requirements as AC substitutes)"
+- Set `SPEC_AVAILABLE=true`, `AC_SOURCE=requirements`
+
+**Priority 4 -- No spec available:**
+
+If none of the above:
+- Log: "No spec file found -- spec compliance check (Stage 1) will be skipped. Review will run Stage 2 only."
+- Set `SPEC_AVAILABLE=false`
+
+## Step 3: Spawn gsd-reviewer
+
+Build the Task() prompt with ALL context gsd-reviewer needs. The prompt must include:
+
+```
+**Test execution results:**
+Framework: {FRAMEWORK}
+Command run: {TEST_COMMAND}
+Exit code: {TEST_EXIT}
+Tests found: {TESTS_FOUND}
+Output:
+{TEST_OUTPUT}
+
+**Acceptance criteria for Stage 1 check ({AC_COUNT} total):**
+{AC_LIST -- one per line, format: AC-N: description}
+
+**Stage 1 instruction:**
+For each AC listed above, check whether the code and/or tests satisfy it. Find concrete evidence (file path, line number, or code snippet). If ALL ACs are satisfied, set stage1_result=PASS and proceed to Stage 2 code quality evaluation. If ANY AC is not satisfied, set stage1_result=FAIL, list the failing ACs with reason, and do NOT perform Stage 2.
+
+Note: One failing AC is enough to fail Stage 1. There is no threshold -- ALL ACs must pass.
+
+**If SPEC_AVAILABLE=false:**
+No spec file (PRD or REQUIREMENTS.md) was found. Skip Stage 1 entirely. Run Stage 2 code quality evaluation only. Note in REVIEW-CODE.md: "Spec compliance check skipped -- no PRD or requirements file found."
+
+**Prototype artifact paths:**
+- Code inventory: .planning/prototype/CODE-INVENTORY.md
+- Prototype log: .planning/prototype/PROTOTYPE-LOG.md
+```
+
+Spawn gsd-reviewer via the Task tool with the prompt above. Wait for the agent to complete -- it will write `.planning/prototype/REVIEW-CODE.md` before returning.
+
+## Step 4: Read review results
+
+After the Task() call returns, read the review output:
+
+Read `.planning/prototype/REVIEW-CODE.md` using the Read tool.
+
+Parse the YAML frontmatter to extract:
+- `stage1_result` (PASS / FAIL)
+- `stage2_result` (PASS / FAIL / SKIPPED)
+- `test_framework`, `tests_run`, `tests_passed`, `tests_failed`
+- `ac_total`, `ac_passed`, `ac_failed`
+- `next_steps` array (id, file, severity, action)
+
+If REVIEW-CODE.md does not exist after the Task() call, log: "Warning: gsd-reviewer did not produce REVIEW-CODE.md. Check agent output above for errors."
+
+## Step 5: Present results to user
+
+**If `non_interactive_mode = true`:** Log the summary below and exit without AskUserQuestion.
+
+**Otherwise:** Use AskUserQuestion to present a formatted summary and ask the user what to do next.
+
+Format the summary as:
+
+```
+Review complete.
+
+--- Stage 1: Spec Compliance ---
+Result: {PASS / FAIL}
+ACs checked: {ac_total} | Passed: {ac_passed} | Failed: {ac_failed}
+{If FAIL: list failing ACs by ID}
+
+--- Stage 2: Code Quality ---
+Result: {PASS / FAIL / SKIPPED}
+{If SKIPPED: "Skipped -- Stage 1 failures must be resolved first"}
+
+--- Test Results ---
+Framework: {test_framework}
+Tests run: {tests_run} | Passed: {tests_passed} | Failed: {tests_failed}
+{If no tests found: "No test files detected -- test coverage is absent (@gsd-risk noted in REVIEW-CODE.md)"}
+
+--- Top Next Steps ---
+{List up to 5 next steps from REVIEW-CODE.md: # | File | Severity | Action}
+
+Full review: .planning/prototype/REVIEW-CODE.md
+```
+
+Then ask:
+
+```
+How would you like to proceed?
+
+Options:
+- "fix" or "iterate" -- run /gsd:iterate to address the next steps
+- "details" -- I'll show you the full REVIEW-CODE.md content
+- "done" -- accept results and continue
+- "rerun" -- re-run the review after you've made manual changes
+
+What's your next step?
+```
+
+**If Stage 1 passed:** suggest `/gsd:iterate` for improvements or proceed to manual verification steps from REVIEW-CODE.md.
+
+**If Stage 1 failed:** recommend fixing the failing ACs first ("Resolve failing ACs before addressing code quality issues") before re-running `/gsd:review-code`.
+
+Handle the user's response:
+- "fix", "iterate", or similar: remind user to run `/gsd:iterate` with the REVIEW-CODE.md path for context
+- "details": Read and display the full REVIEW-CODE.md content
+- "done" or any other response: confirm review is complete and exit
+- "rerun": remind user to make their changes first, then re-run `/gsd:review-code`
+
+</process>

package/get-shit-done/bin/gsd-tools.cjs

@@ -133,6 +133,11 @@
  *   init milestone-op                  All context for milestone operations
  *   init map-codebase                  All context for map-codebase workflow
  *   init progress                      All context for progress workflow
+ *
+ * Test Detection:
+ *   detect-test-framework [dir]        Detect test framework from package.json
+ *                                      Outputs: { framework, testCommand, filePattern }
+ *                                      Defaults to cwd if dir not provided
  */
 
 const fs = require('fs');
@@ -942,6 +947,14 @@ async function runCommand(command, args, cwd, raw) {
       break;
     }
 
+    case 'detect-test-framework': {
+      const targetDir = args[1] || cwd;
+      const testDetector = require('./lib/test-detector.cjs');
+      const result = testDetector.detectTestFramework(targetDir);
+      core.output(result, raw, `${result.framework}: ${result.testCommand}`);
+      break;
+    }
+
     default:
       error(`Unknown command: ${command}`);
   }

package/get-shit-done/bin/lib/test-detector.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * test-detector.cjs — Test framework auto-detection
+ *
+ * Reads a project's package.json to determine which test framework is in use.
+ * Returns deterministic results with zero external dependencies.
+ *
+ * @gsd-api detectTestFramework(projectRoot: string)
+ *   Returns: { framework: string, testCommand: string, filePattern: string }
+ *   Reads target project's package.json to detect test framework.
+ *   Falls back to node:test when package.json is absent, invalid, or unrecognized.
+ *   Detection priority: vitest > jest > mocha > ava > node:test (--test flag) > node:test (fallback)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Detect the test framework used by the project at projectRoot.
+ *
+ * @param {string} projectRoot - Absolute path to the target project root
+ * @returns {{ framework: string, testCommand: string, filePattern: string }}
+ */
+function detectTestFramework(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    return { framework: 'node:test', testCommand: 'node --test', filePattern: '**/*.test.cjs' };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return { framework: 'node:test', testCommand: 'node --test', filePattern: '**/*.test.cjs' };
+  }
+
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const testScript = (pkg.scripts && pkg.scripts.test) || '';
+
+  if (deps.vitest || testScript.includes('vitest')) {
+    return { framework: 'vitest', testCommand: 'npx vitest run', filePattern: '**/*.test.{ts,js}' };
+  }
+  if (deps.jest || testScript.includes('jest')) {
+    return { framework: 'jest', testCommand: 'npx jest', filePattern: '**/*.test.{ts,js}' };
+  }
+  if (deps.mocha || testScript.includes('mocha')) {
+    return { framework: 'mocha', testCommand: 'npx mocha', filePattern: '**/*.test.{mjs,cjs,js}' };
+  }
+  if (deps.ava || testScript.includes('ava')) {
+    return { framework: 'ava', testCommand: 'npx ava', filePattern: '**/*.test.{mjs,js}' };
+  }
+  if (testScript.includes('--test')) {
+    return { framework: 'node:test', testCommand: 'node --test', filePattern: '**/*.test.cjs' };
+  }
+
+  return { framework: 'node:test', testCommand: 'node --test', filePattern: '**/*.test.cjs' };
+}
+
+module.exports = { detectTestFramework };