recipe-add-integration-tests

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.

Context: Test addition workflow for existing implementations (backend, frontend, or fullstack)

Orchestrator Definition

Core Identity: "I am an orchestrator."

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.

First Action: Register Steps 1-7 using TaskCreate before any execution.

Why Delegate: Orchestrator's context is shared across all steps. Direct implementation consumes context needed for review and quality check phases. Subagents work in isolated context.

Execution Method:

• Skeleton generation → delegate to acceptance-test-generator
• Test implementation → delegate to task-executor
• Test review → delegate to integration-test-reviewer
• Quality checks → delegate to quality-fixer

At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately.

Document paths: $ARGUMENTS

Prerequisites

• At least one Design Doc must exist (created manually or via reverse-engineer)
• Existing implementation to test

Execution Flow

Step 1: Discover and Validate Documents

# Verify at least one document path was provided
test -n "$ARGUMENTS" || { echo "ERROR: No document paths provided"; exit 1; }

# Verify provided paths exist
ls $ARGUMENTS

# Discover additional documents
ls docs/design/*.md 2>/dev/null | grep -v template
ls docs/ui-spec/*.md 2>/dev/null

Classify discovered documents by filename:

• Filename contains backend → Design Doc (backend)
• Filename contains frontend → Design Doc (frontend)
• Located in docs/ui-spec/ → UI Spec (optional)
• None of the above → treat as single-layer Design Doc

Step 2: Skeleton Generation

Invoke acceptance-test-generator using Agent tool:

• subagent_type: "dev-workflows:acceptance-test-generator"
• description: "Generate test skeletons"
• prompt: List only the documents that exist from Step 1:

  Generate test skeletons from the following documents:
  - Design Doc (backend): [path]    ← include only if exists
  - Design Doc (frontend): [path]   ← include only if exists
  - UI Spec: [path]                 ← include only if exists
  

Expected output: generatedFiles containing integration and e2e paths

Step 3: Test Implementation

For each layer with generated skeletons, record the current HEAD as diffBase, then invoke the layer's task-executor:

• Backend or single-layer → subagent_type: "dev-workflows:task-executor"
• Frontend → subagent_type: "dev-workflows-frontend:task-executor-frontend"
• description: "Implement integration tests"
• prompt: "Implement every test defined by these generated skeletons: [layer-specific Step 2 paths]. Governing documents: [layer-specific Design Doc and UI Spec when present]. Keep changes within the generated tests and the setup or fixture files they require. Verify the implemented tests against the skeleton claims."

Execute one layer at a time through Steps 3→4→5→6→7 before starting the next.

Expected output: status, testsAdded, mutationEvidence

Apply this response gate after every task-executor invocation in Steps 3 and 5:

• status: completed, testsAdded is present, and at least one changed integration/E2E test file is confirmed → Proceed to Step 4
• status: escalation_needed → Escalate to the user
• Any other status, or a response missing the required fields above → Stop and report the invalid or missing fields

Step 4: Test Review

Invoke integration-test-reviewer using Agent tool:

• subagent_type: "dev-workflows:integration-test-reviewer"
• description: "Review test quality"
• prompt: "Review test quality. changedTestFiles: [confirmed changed integration/E2E test paths]. diffBase: [revision recorded before Step 3]. skeletonFiles: [layer-specific paths from Step 2 generatedFiles]. mutationEvidence: [Step 3 mutationEvidence]."

Expected output: status (approved/needs_revision/blocked), testFiles, reviewBasis, qualityIssues; correction re-review also returns prior_feedback_reconciliation

Step 5: Apply Review Fixes

Check Step 4 result:

• status: approved → Mark complete, proceed to Step 6
• status: blocked → Escalate to user
• status: needs_revision → Pass Step 4 qualityIssues unchanged into the Review Resolution Gate; invoke task-executor for rerouted corrections, return to Step 4, and derive convergence from prior_feedback_reconciliation

Invoke the same layer's task-executor:

• description: "Fix review findings"
• prompt: "Fix these adjudicated test-review findings directly: [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]."

Step 6: Quality Check

Invoke quality-fixer for the current layer:

• Backend or single-layer → subagent_type: "dev-workflows:quality-fixer"
• Frontend → subagent_type: "dev-workflows-frontend:quality-fixer-frontend"
• description: "Final quality assurance"
• Pass the latest executor's mutationEvidence.
• prompt: "Final quality assurance for test files added in this workflow. Run all tests and verify coverage."

Expected output: status (approved/stub_detected/blocked)

Check quality-fixer response:

• stub_detected → Return to Step 3 with incompleteImplementations[] details, then re-execute Steps 3→4→5→6
• blocked → Escalate to user
• approved → Proceed to Step 7

Step 7: Commit

On approved from quality-fixer:

• Commit test files using Bash with message format: "test: add [layer] integration tests for [feature name]"

In the completion report, list each declined actionable finding with its ID, governing reason, and evidence when any occurred.

Scope Boundary for Subagents

Append the following block to every subagent prompt invoked from this recipe:

Scope boundary for subagents:
Operate within the task scope and referenced files in the prompt.
Use loaded skills to execute that scope.
Escalate when the required fix or investigation falls outside that scope.