recipe-add-integration-tests · diff

git:20260802.aa3bfed to git:20260802.c018280

3 added, 3 removed. Audit A to A.

---

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 Gate**: Use the active execution plan when one exists. When none exists, create one with first "Map active rules to this task", Steps 0-8, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final verification evidence exists, mark every step `completed`.

+ **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

```bash

# 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

```

- Use only the user-provided paths in `$ARGUMENTS`. Do not auto-discover additional Design Docs or UI Specs.

+ 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.

```text

Generate test skeletons from the following documents:

- Design Docs: [paths]

- UI Specs: [paths, when supplied]

```

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

```json

{

"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:

|---|---|---|---|

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, report the failed path but do not invalidate completed test work.

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