| name | test |
| description | Run Phase 4 (Testing) of the privacyclaw feature workflow. PM and Architect decide test types; Test Developer implements them; Stress Tester adds load tests if needed; Test Runner gates completion. Implementation bugs route back through Phase 3. Can be invoked standalone by passing a Development Phase Handoff as the argument. |
| argument-hint | <develop phase handoff> |
| context | fork |
Phase 4 — Testing
You are the Phase 4 coordinator. Your job is to ensure every piece of the
implementation is covered by tests that would catch real bugs in production —
and that all of them pass before the feature branch is declared done.
Input: $ARGUMENTS
Extract from the input:
feature: the feature descriptionbranch: the feature branch (feature/<slug>)impl_log: path to the implementation logfor_next: context from Development (risk areas, known complexity, gaps)WORKTREE: the absolute path to the feature worktree (required;
if missing, derive as $(git rev-parse --show-toplevel)/../worktrees/<branch-slug>)
Derive WORKTREE_PARENT = dirname(<WORKTREE>). The test worktree is a
sibling: <WORKTREE_PARENT>/task-tests-<slug>.
Working directory
All operations in this phase must happen inside <WORKTREE> (or the test
worktree sibling), never in the main repository working tree.
Rules that apply to this coordinator and to every agent it invokes:
- File reads/writes:
<WORKTREE>/<relative-path>
- Git commands:
git -C "<WORKTREE>" <command>
- Cargo commands:
cd "<WORKTREE>" && cargo <command> (or the test worktree path)
- Test worktree: created at
<WORKTREE_PARENT>/task-tests-<slug>
- Every agent message must include
WORKTREE: <worktree_path> with the
appropriate worktree path.
Agent coordination protocol
Try team-based coordination:
TeamCreate({ name: "test-team",
agents: ["pm", "architect", "test-developer",
"stress-tester", "test-runner"] })
SendMessage({ to: "pm", message: "<task + context>" })
Fall back to sequential Agent tool calls if TeamCreate fails. Do not retry
teams more than once.
Agent Handoff format
--- AGENT HANDOFF ---
From: <agent name>
To: <next agent>
Status: complete | blocked
Branch: <branch name>
Done:
- <key action taken>
Decisions:
- <decision + rationale, or "none">
Findings:
- <finding + severity, or "none">
Open:
- <item + owner, or "none">
Pass forward:
<2–3 sentences of critical context for the next agent>
--- END HANDOFF ---
Worktree protocol
Test files are written on a dedicated branch that is a sibling of the
feature worktree (git cannot nest worktrees):
git -C "<WORKTREE>" worktree add "<WORKTREE_PARENT>/task-tests-<slug>" \
-b task/tests-<slug>
Test Developer and Stress Tester commit to task/tests-<slug>.
Test Runner reads from it but does not commit.
After Test Runner confirms all tests pass:
git -C "<WORKTREE>" merge --no-ff task/tests-<slug> \
-m "test(<slug>): add test coverage"
git -C "<WORKTREE>" worktree remove "<WORKTREE_PARENT>/task-tests-<slug>"
Workflow
Step 1 — PM + Architect: test plan
Invoke pm and architect jointly (or sequentially if teams unavailable)
with the implementation log and Development handoff context. Task:
Working directory: <WORKTREE> — read files only within this directory.
Do not access the main repository working tree.
WORKTREE: <worktree_path>
Read the implementation log at <impl_log> and the development context.
Decide which test types are needed for each area of the implementation:
- Unit tests: individual functions and modules
- Functional tests: end-to-end behaviour of a feature
- Integration tests: interaction between components
- Acceptance tests: user-facing correctness criteria
- Stress tests: concurrency, load, throughput (flag explicitly if needed)
Pay special attention to areas flagged as risky or complex in the
development handoff. Produce an Agent Handoff with the test plan —
a list of test areas, type, and rationale for each.
Step 2 — Test Developer
Create the test worktree branch. Invoke test-developer with the test plan
and branch name. Task:
Working directory: <WORKTREE_PARENT>/task-tests-<slug>
(branch: task/tests-<slug>) — do not read or write any
files outside this directory.
WORKTREE: <WORKTREE_PARENT>/task-tests-<slug>
Implement the tests specified in the test plan on branch task/tests-<slug>.
Think adversarially. For every item in the plan, cover:
- Happy path
- Edge cases (empty input, boundary values, type extremes)
- Failure modes (errors, timeouts, invalid state)
- Evasion attempts (inputs that look valid but are not)
Do not write tests that merely confirm the code compiles. Write tests that
would catch real bugs in production. Use #[tokio::test] for async tests.
Commit your changes. Produce an Agent Handoff.
Step 3 — Stress Tester (conditional)
If the test plan includes stress tests, invoke stress-tester with the
Test Developer handoff and branch name. Task:
Working directory: <WORKTREE_PARENT>/task-tests-<slug>
(branch: task/tests-<slug>) — do not read or write any
files outside this directory.
WORKTREE: <WORKTREE_PARENT>/task-tests-<slug>
Implement stress, load, and concurrency tests on branch task/tests-<slug>.
Cover: concurrent connections, resource exhaustion, backpressure, byte
integrity under load, and latency distributions where relevant.
These tests must be able to run in CI without external dependencies.
Commit your changes. Produce an Agent Handoff.
If no stress tests were planned, skip this step.
Step 4 — Test Runner
Invoke test-runner with the full test branch and implementation. Task:
Working directory: <WORKTREE_PARENT>/task-tests-<slug>
(branch: task/tests-<slug>) — do not read or write any
files outside this directory. Run cd "<WORKTREE_PARENT>/task-tests-<slug>" && cargo test.
WORKTREE: <WORKTREE_PARENT>/task-tests-<slug>
Run the full test suite (cargo test) against the current state of
feature/<slug> merged with task/tests-<slug>.
Interpret every failure precisely:
- Is this a test code problem (wrong assertion, bad fixture, flaky timing)?
- Is this an implementation bug (real behaviour does not match spec)?
Produce an Agent Handoff with:
- Verdict: all pass | test failures | implementation bugs
- For each failure: exact test name, failure message, diagnosis, and
classification (test code | implementation)
Step 5 — Route Test Runner verdict
If verdict is "all pass": proceed to phase completion.
If verdict is "test failures" (test code problems):
Return the Test Runner handoff to Test Developer (or Stress Tester for
stress test failures). They fix the test code and re-commit. Return to Step 4.
If verdict is "implementation bugs":
For each implementation bug identified:
- Extract the affected task id(s) from the implementation log.
- Trigger a targeted re-run of the affected task(s) through the Phase 3
per-task cycle. Pass the Test Runner handoff as context so Developer
understands exactly what is broken.
- Once the affected tasks are re-approved by Contrarian and merged back to
the feature branch, return to Step 4 to re-run the full test suite.
This loop continues until Test Runner verdict is "all pass".
Maximum test-runner iterations: 8. If the suite has not gone green after
8 Test Runner invocations, surface the remaining failures to the user.
Team cleanup
If TeamCreate succeeded earlier, shut down all agents and delete the team
before producing the Phase Handoff:
SendMessage({ to: "pm", message: {type: "shutdown_request"} })
SendMessage({ to: "architect", message: {type: "shutdown_request"} })
SendMessage({ to: "test-developer", message: {type: "shutdown_request"} })
SendMessage({ to: "stress-tester", message: {type: "shutdown_request"} })
SendMessage({ to: "test-runner", message: {type: "shutdown_request"} })
TeamDelete()
If TeamCreate was never called (sequential fallback path), skip this section.
Phase completion
Phase 4 is complete when:
- Test Runner verdict is "all pass"
- Test branch has been merged into the feature branch
- PM confirms all planned test types have been covered
Produce a Phase Handoff:
=== PHASE HANDOFF ===
Phase: Testing
Status: complete (or: blocked — <reason>)
Feature: <feature description>
Branch: <branch>
Artifacts:
task/tests-<slug> (merged into feature/<slug>)
Decisions: <bullet list of key testing decisions>
For next: Feature branch is ready to merge to main.
Tests written: <count>. Areas covered: <list>.
Any residual known limitations or deferred test areas.
Open: <unresolved failures or user questions, or "none">
=== END HANDOFF ===
When the orchestrator receives this handoff with Status: complete, it will
merge feature/<slug> into main.
