Force synchronous agent handoffs in the /feature pipeline

.claude/commands/design-review.md

@@ -9,8 +9,11 @@ You are the orchestrator:
 1. Identify the spec to review against: the one named in the arguments, or the
    highest-numbered file in `docs/specs/` if none was given.
 2. Invoke the `ux-designer` subagent in Mode 2 (design verification) with the
-   spec path and `app/public/` as the scope. It writes its report to
-   `docs/design-reviews/` and returns APPROVED or CHANGES REQUIRED.
+   spec path and `app/public/` as the scope — synchronously, with
+   `run_in_background: false`, and wait for it to return before reading its
+   report (the Agent tool defaults to background; a backgrounded call reads as a
+   stall). It writes its report to `docs/design-reviews/` and returns APPROVED or
+   CHANGES REQUIRED.
 3. Present the findings table and verdict to the product owner.
 4. If the verdict is CHANGES REQUIRED, ask the product owner whether to route
    the findings to `frontend-developer` (or `backend-developer` where

.claude/commands/feature-resume.md

@@ -24,4 +24,6 @@ You are the orchestrator, resuming a `/feature` run that was interrupted
    `.claude/commands/feature.md` exactly — same phase definitions, same
    batching rules, same loop bounds (the recorded iteration counters still
    count against the max-2 caps). Keep updating the state file after every
-   phase.
+   phase. As in `/feature`, run every agent synchronously
+   (`run_in_background: false`) and wait for its handoff before the next phase —
+   a backgrounded agent is what makes a resumed run appear to stall again.

.claude/commands/feature.md

@@ -9,6 +9,17 @@ project subagents (`ux-designer`, `frontend-developer`, `backend-developer`,
 `qa-engineer`, `technical-writer`). Rules that apply throughout:
 
 - Pass explicit file paths in every agent prompt — subagents share no context.
+- **Run every pipeline agent synchronously — never in the background.** Each
+  phase consumes the artifact the previous phase wrote, so the pipeline is
+  strictly sequential. Every Agent tool call here MUST pass
+  `run_in_background: false`; wait for the agent to return, then read its
+  handoff footer before doing anything else. The Agent tool defaults to
+  *background* execution — a backgrounded pipeline agent makes the run look
+  "stalled" at the handoff, because you go to read a spec/defect/report the
+  agent hasn't written yet and there is nothing there. When a phase runs two
+  agents in parallel (Phase 2, the fix loops), still put both in one message
+  and still pass `run_in_background: false` on each — "parallel" means one
+  message with two synchronous calls, not backgrounded calls.
 - **OPEN QUESTIONS is a hard stop (all five agents, every phase).** After each
   agent returns, read its handoff footer. If its OPEN QUESTIONS is anything
   other than "none", STOP the pipeline immediately — do not start the next

.claude/commands/qa-verify.md

@@ -8,9 +8,12 @@ You are the orchestrator:
 
 1. Identify the spec to verify: the one named in the arguments, or the
    highest-numbered file in `docs/specs/` if none was given.
-2. Invoke the `qa-engineer` subagent in Mode 1 with the spec path. It updates
-   the test plan, authors/updates tests, runs `node --test app/test/*.test.js`, and
-   files defect reports for any failures.
+2. Invoke the `qa-engineer` subagent in Mode 1 with the spec path —
+   synchronously, with `run_in_background: false`, and wait for it to return
+   before reading its handoff (the Agent tool defaults to background; a
+   backgrounded call reads as a stall). It updates the test plan, authors/updates
+   tests, runs `node --test app/test/*.test.js`, and files defect reports for any
+   failures.
 3. Report the verdict (PASS | FAIL) and any defect file paths to the product
    owner.
 4. If FAIL, ask the product owner whether to run the fix loop now (route each

plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-dev",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agentic dev process: 5 role agents (ux/frontend/backend/qa/docs), the /feature pipeline, and mechanical lane enforcement — all native Claude Code subagents, no framework.",
   "author": { "name": "tmkab121" },
   "homepage": "https://github.com/tmkab121/agentic-dev",

plugin/commands/design-review.md

@@ -9,8 +9,11 @@ You are the orchestrator:
 1. Identify the spec to review against: the one named in the arguments, or the
    highest-numbered file in `docs/specs/` if none was given.
 2. Invoke the `ux-designer` subagent in Mode 2 (design verification) with the
-   spec path and `app/public/` as the scope. It writes its report to
-   `docs/design-reviews/` and returns APPROVED or CHANGES REQUIRED.
+   spec path and `app/public/` as the scope — synchronously, with
+   `run_in_background: false`, and wait for it to return before reading its
+   report (the Agent tool defaults to background; a backgrounded call reads as a
+   stall). It writes its report to `docs/design-reviews/` and returns APPROVED or
+   CHANGES REQUIRED.
 3. Present the findings table and verdict to the product owner.
 4. If the verdict is CHANGES REQUIRED, ask the product owner whether to route
    the findings to `frontend-developer` (or `backend-developer` where

plugin/commands/feature-resume.md

@@ -24,4 +24,6 @@ You are the orchestrator, resuming a `/feature` run that was interrupted
    `.claude/commands/feature.md` exactly — same phase definitions, same
    batching rules, same loop bounds (the recorded iteration counters still
    count against the max-2 caps). Keep updating the state file after every
-   phase.
+   phase. As in `/feature`, run every agent synchronously
+   (`run_in_background: false`) and wait for its handoff before the next phase —
+   a backgrounded agent is what makes a resumed run appear to stall again.

plugin/commands/feature.md

@@ -9,6 +9,17 @@ project subagents (`ux-designer`, `frontend-developer`, `backend-developer`,
 `qa-engineer`, `technical-writer`). Rules that apply throughout:
 
 - Pass explicit file paths in every agent prompt — subagents share no context.
+- **Run every pipeline agent synchronously — never in the background.** Each
+  phase consumes the artifact the previous phase wrote, so the pipeline is
+  strictly sequential. Every Agent tool call here MUST pass
+  `run_in_background: false`; wait for the agent to return, then read its
+  handoff footer before doing anything else. The Agent tool defaults to
+  *background* execution — a backgrounded pipeline agent makes the run look
+  "stalled" at the handoff, because you go to read a spec/defect/report the
+  agent hasn't written yet and there is nothing there. When a phase runs two
+  agents in parallel (Phase 2, the fix loops), still put both in one message
+  and still pass `run_in_background: false` on each — "parallel" means one
+  message with two synchronous calls, not backgrounded calls.
 - **OPEN QUESTIONS is a hard stop (all five agents, every phase).** After each
   agent returns, read its handoff footer. If its OPEN QUESTIONS is anything
   other than "none", STOP the pipeline immediately — do not start the next

plugin/commands/qa-verify.md

@@ -8,9 +8,12 @@ You are the orchestrator:
 
 1. Identify the spec to verify: the one named in the arguments, or the
    highest-numbered file in `docs/specs/` if none was given.
-2. Invoke the `qa-engineer` subagent in Mode 1 with the spec path. It updates
-   the test plan, authors/updates tests, runs `node --test app/test/*.test.js`, and
-   files defect reports for any failures.
+2. Invoke the `qa-engineer` subagent in Mode 1 with the spec path —
+   synchronously, with `run_in_background: false`, and wait for it to return
+   before reading its handoff (the Agent tool defaults to background; a
+   backgrounded call reads as a stall). It updates the test plan, authors/updates
+   tests, runs `node --test app/test/*.test.js`, and files defect reports for any
+   failures.
 3. Report the verdict (PASS | FAIL) and any defect file paths to the product
    owner.
 4. If FAIL, ask the product owner whether to run the fix loop now (route each