recipe-add-integration-tests

name	recipe-add-integration-tests
description	Add integration/E2E tests to existing codebase using Design Docs
disable-model-invocation	true

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

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

Orchestrator Definition

Core Identity: "I am an orchestrator."

First Action: Register Steps 0-8 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. Task files create context boundaries. Subagents work in isolated context.

Execution Method:

• Skeleton generation → delegate to acceptance-test-generator
• Task file creation → orchestrator creates directly (minimal context usage)
• Test implementation → delegate to task-executor
• Test review → delegate to integration-test-reviewer
• Quality checks → delegate to quality-fixer

Document paths: $ARGUMENTS

Prerequisites

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

Execution Flow

Step 0: Execute Skill

Execute Skill: documentation-criteria (for task file template in Step 3)

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-fullstack: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: Create Task Files [GATE]

Create one task file per layer, using the monorepo-flow.md naming convention for deterministic agent routing:

• Backend skeletons exist → docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md
• Frontend skeletons exist → docs/plans/tasks/integration-tests-frontend-task-YYYYMMDD.md
• Single-layer (no backend/frontend distinction) → docs/plans/tasks/integration-tests-backend-task-YYYYMMDD.md

Template (per task file):

---
name: Implement [layer] integration tests for [feature name]
type: test-implementation
---

## Objective

Implement test cases defined in skeleton files.

## Target Files

- Skeleton: [layer-specific paths from Step 2 generatedFiles]
- Design Doc: [layer-specific Design Doc from Step 1]

## Tasks

- [ ] Implement each test case in skeleton
- [ ] Verify all tests pass
- [ ] Ensure coverage meets requirements

## Acceptance Criteria

- All skeleton test cases implemented
- All tests passing
- quality-fixer reports approved

Output: "Task file(s) created at [path(s)]. Ready for Step 4."

Step 4: Test Implementation

For each task file from Step 3, invoke task-executor routed by filename pattern (per monorepo-flow.md):

• *-backend-task-* → subagent_type: "dev-workflows-fullstack:task-executor"
• *-frontend-task-* → subagent_type: "dev-workflows-fullstack:task-executor-frontend"
• description: "Implement integration tests"
• prompt: "Task file: [task file path from Step 3]. Implement tests following the task file."

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

Expected output: status, testsAdded

Step 5: Test Review

Invoke integration-test-reviewer using Agent tool:

• subagent_type: "dev-workflows-fullstack:integration-test-reviewer"
• description: "Review test quality"
• prompt: "Review test quality. Test files: [paths from Step 4 testsAdded]. Skeleton files: [layer-specific paths from Step 2 generatedFiles matching current task's layer]"

Expected output: status (approved/needs_revision), requiredFixes

Step 6: Apply Review Fixes

Check Step 5 result:

• status: approved → Mark complete, proceed to Step 7
• status: needs_revision → Invoke task-executor with requiredFixes, then return to Step 5

Invoke task-executor routed by task filename pattern:

• *-backend-task-* → subagent_type: "dev-workflows-fullstack:task-executor"
• *-frontend-task-* → subagent_type: "dev-workflows-fullstack:task-executor-frontend"
• description: "Fix review findings"
• prompt: "Fix the following issues in test files: [requiredFixes from Step 5]"

Step 7: Quality Check

Invoke quality-fixer routed by task filename pattern:

• *-backend-task-* → subagent_type: "dev-workflows-fullstack:quality-fixer"
• *-frontend-task-* → subagent_type: "dev-workflows-fullstack:quality-fixer-frontend"
• description: "Final quality assurance"
• 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 4 with incompleteImplementations[] details, then re-execute Steps 4→5→6→7
• blocked → Escalate to user
• approved → Proceed to Step 8

Step 8: Commit

On approved from quality-fixer:

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

Step 9: Final Cleanup

After all task files have been processed and committed, delete the task files this recipe created. Their work is committed; docs/plans/ is ephemeral working state and is not retained between recipe runs:

• Delete every file matching docs/plans/tasks/integration-tests-backend-task-*.md and docs/plans/tasks/integration-tests-frontend-task-*.md created during this run

If task files cannot be deleted (filesystem error), report the failure but do not block completion.

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.