diff --git a/.claude/commands/design-review.md b/.claude/commands/design-review.md index ff14113..fe2314f 100644 --- a/.claude/commands/design-review.md +++ b/.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 diff --git a/.claude/commands/feature-resume.md b/.claude/commands/feature-resume.md index aacc4d9..dd20539 100644 --- a/.claude/commands/feature-resume.md +++ b/.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. diff --git a/.claude/commands/feature.md b/.claude/commands/feature.md index 8833eaa..cd1aaf6 100644 --- a/.claude/commands/feature.md +++ b/.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 diff --git a/.claude/commands/qa-verify.md b/.claude/commands/qa-verify.md index 90928a2..22b9717 100644 --- a/.claude/commands/qa-verify.md +++ b/.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 diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 826b819..356b63d 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/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", diff --git a/plugin/commands/design-review.md b/plugin/commands/design-review.md index ff14113..fe2314f 100644 --- a/plugin/commands/design-review.md +++ b/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 diff --git a/plugin/commands/feature-resume.md b/plugin/commands/feature-resume.md index aacc4d9..dd20539 100644 --- a/plugin/commands/feature-resume.md +++ b/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. diff --git a/plugin/commands/feature.md b/plugin/commands/feature.md index 8833eaa..cd1aaf6 100644 --- a/plugin/commands/feature.md +++ b/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 diff --git a/plugin/commands/qa-verify.md b/plugin/commands/qa-verify.md index 90928a2..22b9717 100644 --- a/plugin/commands/qa-verify.md +++ b/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