recipe-fullstack-build

**Explicit User Instruction**: The user explicitly instructs and authorizes every subagent call named in this recipe. Execute each applicable call when its prerequisites are met. Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings. ## Orchestrator Definition **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill) **Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist. **Review Resolution Gate [MANDATORY]**: Resolve every actionable deliverable-review finding through subagents-orchestration-guide `Review Resolution` before correction or progression. Before the first finding disposition, read `references/review-resolution.md` from the loaded subagents-orchestration-guide skill. ## Required Reference **MANDATORY**: Read `references/monorepo-flow.md` from subagents-orchestration-guide skill BEFORE proceeding. Follow the Extended Task Cycle and Agent Routing defined there. ## Execution Protocol 1. **Invoke named specialists for deliverable production** — pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary") 2. **Route agents by task filename pattern** (see monorepo-flow.md reference): - `*-backend-task-*` → task-executor + quality-fixer - `*-frontend-task-*` → task-executor-frontend + quality-fixer-frontend 3. **Follow the 4-step task cycle exactly**: execute → branch on executor result → quality-fix → commit 4. **Enter autonomous mode** when the user provides execution instruction with an existing Work Plan or task files — this IS the batch approval 5. **Scope**: Complete consumed task-set execution, post-implementation verification, consumed-task cleanup, and completion reporting in order, or stop autonomous execution at the current phase for a valid user-owned escalation. Advance only when the current phase's stated transition condition is satisfied. **CRITICAL**: Run layer-appropriate quality-fixer(s) before every commit. Work plan: $ARGUMENTS ## Pre-execution Prerequisites ### Work Plan Resolution Before any task processing, locate the work plan. Resolution rule: 1. Use the work plan explicitly supplied in `$ARGUMENTS` when present. 2. Otherwise group layer-aware task files by the existing `{plan-name}-{backend|frontend}-task-*.md` naming contract and map each group to `docs/plans/{plan-name}.md`. 3. When task groups produce no candidate, use the only Work Plan under `docs/plans/` when exactly one exists. 4. Select the sole candidate. When multiple candidates remain, present them for selection. When none exists, continue through the missing-prerequisite branch below. ### Consumed Task Set Compute the **Consumed Task Set** for this run — the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution: 1. List task files in `docs/plans/tasks/` matching the layer-aware patterns `{plan-name}-backend-task-*.md` and `{plan-name}-frontend-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. Single-layer tasks are excluded Every subsequent reference to "task files" in this recipe — Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup — uses this set, not the unrestricted `docs/plans/tasks/*.md` glob. ### Task Generation Decision Flow Analyze the Consumed Task Set and determine the action required: | State | Criteria | Next Action | |-------|----------|-------------| | Tasks exist | Consumed Task Set is non-empty | User's execution instruction serves as batch approval → Enter autonomous execution immediately | | No tasks + plan exists | Consumed Task Set is empty and the resolved work plan exists | User's execution instruction serves as batch approval → Run task-decomposer | | Neither exists + Design Doc exists | No plan, no Consumed Task Set, but `docs/design/*.md` exists | Invoke work-planner to create a work plan, then run document-reviewer (`dev-workflows-fullstack:document-reviewer`, doc_type: WorkPlan). Run Review Resolution through correction re-review, its parent requirement or authority exits, and convergence, using work-planner for rerouted corrections; then present the resolved plan for batch approval before task materialization | | Neither exists | No plan, no Consumed Task Set, no Design Doc | Report missing prerequisites to user and stop | ## Task Materialization Phase (Conditional) When the Consumed Task Set is empty: ### 1. Task Materialization Invoke task-decomposer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:task-decomposer" - `description`: "Materialize work plan tasks" - `prompt`: "Read work plan at docs/plans/[plan-name].md and output individual single-commit task files in docs/plans/tasks/. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md from each Work Plan task's Executor lane." ### 2. Verify Generation Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. When it remains empty, apply Specialist Result Acceptance: validate the invocation and returned artifacts, correct recoverable input or naming errors, and rerun. ## Pre-execution Checklist - [ ] Confirmed Consumed Task Set is non-empty (computed in the Consumed Task Set section above) - [ ] Identified task execution order within the Consumed Task Set (dependencies) - [ ] **Environment check**: Can I execute per-task commit cycle? - If commit capability is unavailable → Apply Specialist Result Acceptance before autonomous mode - Other environments (tests, quality tools) → Quality agents retain proof limitations while the task cycle continues ## Task Execution Cycle (Filename-Pattern-Based) **MANDATORY**: For each task in the Consumed Task Set, route agents by task filename pattern from monorepo-flow.md reference. ### Agent Routing Table | Filename Pattern | Executor | Quality Fixer | |-----------------|----------|---------------| | `*-backend-task-*` | dev-workflows-fullstack:task-executor | dev-workflows-fullstack:quality-fixer | | `*-frontend-task-*` | dev-workflows-fullstack:task-executor-frontend | dev-workflows-fullstack:quality-fixer-frontend | ### Task Execution (4-Step Cycle) **MANDATORY EXECUTION CYCLE**: `execute → branch on executor result → quality-fix → commit` For EACH task, YOU MUST: 1. **EXECUTE**: invoke Agent tool (subagent_type per routing table) → Record the current HEAD as `diffBase`, pass `task_file: [path]`, and receive the structured response 2. **BRANCH ON EXECUTOR RESULT**: - `status: "escalation_needed"` or `"blocked"` → Apply subagents-orchestration-guide Specialist Result Acceptance - `requiresTestReview` is `true` → Identify the changed integration/E2E test files in the current changes and invoke integration-test-reviewer with them as `changedTestFiles`, plus `diffBase`, `taskFile`, prompt-only claims, and `mutationEvidence` - `pass` → Proceed to step 3 - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - `status: completed` → Proceed to step 3 3. **QUALITY-FIX**: Invoke the layer-appropriate quality-fixer with `task_file`, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with the layer quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 - `pass` → Proceed to step 4 4. **COMMIT**: Apply subagents-orchestration-guide Commit Boundary Check, then execute git commit after the layer-appropriate quality-fixer returns `pass` or `verification_incomplete`; append its verification trailers for the latter Use each subagent's semantic result and repository evidence through Specialist Result Acceptance; canonical status fields provide the normal routing shortcut. Proceed to the next task after step 4 and retain any verification limitation with its status kept proof-limited. Verify task files exist per Pre-execution Checklist, then enter autonomous execution mode. When requirement changes are detected during execution, escalate to the user with the change summary before continuing. ## Post-Implementation Review (After All Tasks Complete) Before invoking post-implementation reviewers, apply subagents-orchestration-guide's retained verification limitation retry with each layer's quality-fixer. Continue with the reviewers after clearing or retaining each result; include only repeated limitations in the completion report. Resolve all readable Design Docs from the Work Plan, or the Work Plan itself when none exist; missing input blocks review. Emit one code-reviewer call plus one security-reviewer call in one assistant message, then await both: - code-reviewer (subagent_type: "dev-workflows-fullstack:code-reviewer") → review the completed implementation with the resolved typed `governingDocuments` list, the actual files changed by completed tasks as `implementationFiles`, and the Work Plan path - security-reviewer (subagent_type: "dev-workflows-fullstack:security-reviewer") → review the completed implementation against the typed `governingDocuments` list Apply subagents-orchestration-guide's Post-Implementation Review status-routing and fix/re-run rules. Present the unified report; proceed to Final Cleanup after the complete review set reaches Review Resolution convergence. ## Final Cleanup Before the completion report, delete the implementation task files this recipe consumed. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs: - Delete every file in the Consumed Task Set - Preserve the work plan itself (`docs/plans/{plan-name}.md`) — the user decides whether to delete it after final review If task-file deletion fails with a filesystem error, report the failure and continue to the completion report. ## Completion Report Contract Final report must include: - Task materialization status - Implemented task count, including backend/frontend counts - Quality check result - Verification limitations that remained after final retry - Commit count - Cleanup result - Declined actionable findings with ID, governing reason, and evidence, when any occurred - Escalation or blocking summary, if any