recipe-add-integration-tests

name	recipe-add-integration-tests
description	Add integration/E2E tests to existing codebase using Design Docs.

Required Skills [LOAD BEFORE EXECUTION]

1. [LOAD IF NOT ACTIVE] testing — repository-aware test execution
2. [LOAD IF NOT ACTIVE] integration-e2e-testing — value-based integration/E2E selection
3. [LOAD IF NOT ACTIVE] subagents-orchestration-guide — review resolution and agent coordination
4. [LOAD IF NOT ACTIVE] llm-friendly-context — task file contract

Spawn rule: every spawn_agent call uses fork_turns="none" so the subagent receives only the task message and explicitly provided context.

Context: Test addition workflow for existing implementations

Orchestrator Definition

Core Identity: Coordinate test addition, perform lightweight evidence collection and routing directly, and invoke specialists for generation, implementation, and review judgment.

Execution Plan: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification.

Why Spawn: 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 -> Spawn acceptance-test-generator agent
• Task file creation -> Orchestrator creates directly (minimal context usage)
• Test implementation -> Spawn task-executor agent
• Test review -> Spawn integration-test-reviewer agent
• Quality checks -> Spawn quality-fixer agent

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: Prepare Context

Use the llm-friendly-context Task File Contract 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

Treat the user-provided paths in $ARGUMENTS as the complete document selection.

Treat paths under docs/ui-spec/ as UI Specs and the supplied docs/design/ paths as Design Docs. When a filename is unclear, use the document title and content; layer classification is not an execution gate because the generator returns each artifact's implementation kind.

Step 2: Skeleton Generation

Spawn acceptance-test-generator with the validated document paths from Step 1. Include UI Specs as optional UI evidence.

Generate test skeletons from the following documents:
- Design Docs: [paths]
- UI Specs: [paths, when supplied]

Expected output: consume the acceptance-test-generator contract directly:

{
  "status": "completed",
  "artifacts": [{"path": "path", "implementationKind": "general | frontend"}]
}

Verify returned artifact paths. When the selected set is empty, report that no integration/E2E skeleton was valuable and finish; otherwise continue to Step 3.

Step 3: Create Task Files

Group the returned artifacts by implementationKind and create at most one task per non-empty group:

implementationKind	Task file	Executor	Quality fixer
general	docs/plans/tasks/integration-tests-task-YYYYMMDD.md	task-executor	quality-fixer
frontend	docs/plans/tasks/integration-tests-frontend-task-YYYYMMDD.md	task-executor-frontend	quality-fixer-frontend

Populate the llm-friendly-context Task File Contract with:

• Source Plan Tasks: N/A — standalone test-addition flow
• Implementation Outcome: implement every skeleton in this task's artifact group as a runnable integration/E2E test
• Governing Sources: the supplied Design Doc/UI Spec paths and the ACs cited by the skeletons
• Target Files: the path of every artifact in this task's group
• Investigation Targets: the governing sections, generated skeletons, and one representative existing test per selected lane
• Implementation Steps: implement the skeleton proof obligations, run their focused commands, and keep the selected boundaries observable
• Operation Verification Methods: repository commands and observable pass conditions for the selected lanes
• Verification Focus: when one material false-green condition controls completion, copy its Primary failure and smallest observable proof check
• Completion Criteria: every selected skeleton is executable and its observable checks pass

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

Step 4: Test Implementation

Start the subagents-orchestration-guide Per-Task Change Set before invoking the executor for each task.

For each task file from Step 3, invoke the executor from its table row with: "Task file: [task file path from Step 3]. Implement tests following the task file."

Inspect the executor result and repository diff, then add its paths to taskWriteSet. Resolve an incomplete or unusable implementation through Orchestrator Escalation Resolution.

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

Expected output: completion or escalation state, filesModified, testsAdded, requiresTestReview, and operation-verification evidence

Step 5: Test Review

Use integration/E2E paths from taskWriteSet as the test-review input set. Spawn integration-test-reviewer with changedTestFiles, diffBase, skeletonFiles: [artifact paths in the current task], and taskFile. Keep testsAdded as reporting metadata only.

Consume the reviewer decision, actionable findings, and governing basis. Apply Orchestrator Escalation Resolution when the result is blocked or cannot support the next action.

Step 6: Apply Review Fixes

Proceed when the review is approved. When it contains actionable revision findings, apply Review Resolution with the layer-appropriate executor, add repair paths to taskWriteSet, and rerun the reviewer.

Step 7: Quality Check

Spawn the quality fixer from the current task's Step 3 table row with task_file, filesModified: taskWriteSet, and the executor's operation-verification evidence.

Expected output: status (stub_detected/approved/blocked)

Step 8: Commit

On quality approval, add its filesModified, reconcile and commit the Per-Task Change Set, then mark the temporary task file complete. Repair stubs through the current task's executor and accumulate their paths; resolve blocked results through Orchestrator Escalation Resolution.

Completion Criteria

• Design Doc validated and located
• acceptance-test-generator returned status: completed
• Every returned artifact was implemented, reviewed, quality-checked, and committed
• Task files created by this recipe deleted from docs/plans/tasks/

Final Cleanup

Before the completion report, delete only the integration-test task files this recipe created for the current run. Their work is committed; docs/plans/ is ephemeral working state.

If cleanup fails, preserve completed test work and report the failed path.