recipe-add-integration-tests

## Required Skills [LOAD BEFORE EXECUTION] Before loading required skills, use `wc -c` to size the files and set both `exec_command.max_output_tokens` and the outer `// @exec: {"max_output_tokens": N}` budget to accommodate their contents, including the combined output of batched reads. Split oversized reads upfront; recover any truncated content before proceeding. 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 **Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation. **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. **Execution Method**: - Skeleton generation -> Invoke acceptance-test-generator agent - Task file creation -> Orchestrator creates directly (minimal context usage) - Test implementation -> Invoke task-executor agent - Test review -> Invoke integration-test-reviewer agent - Quality checks -> Invoke 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 Require at least one supplied, readable document path. 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 Invoke 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: | implementationKind | Task file | Executor | Quality fixer | |---|---|---|---| | `general` | `docs/plans/tasks/integration-tests-task-01.md` | `task-executor` | `quality-fixer` | | `frontend` | `docs/plans/tasks/integration-tests-frontend-task-01.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. Invoke 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 **Review reception:** Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary. Proceed when the review passes. 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 Invoke 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`/`pass`/`blocked`) ### Step 8: Commit On quality pass, 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.