Harald Hoyer
d22acf6906
Gives @pm narrowly-scoped bash access (git show *, git rev-parse *) so it can read TODO.md directly from any git ref. The workflow no longer needs to mktemp + redirect the file before invoking the agent; Phase 2 just tells @pm the bare repo path and default branch and lets it run git show "$DEFAULT_BRANCH:TODO.md" itself. Cleanup steps for the temp snapshot are removed from Phase 10 and the failure handler.
248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
---
|
|
description: "Fire-and-forget multi-agent workflow: plan, test, implement, commit"
|
|
agent: build
|
|
---
|
|
|
|
You are executing the autonomous multi-agent workflow. Run all phases without waiting for user input. The user has walked away.
|
|
|
|
**Task reference:** $ARGUMENTS
|
|
|
|
If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID>` (e.g. `/workflow ABC-1`). The ID must exist in `./TODO.md`."
|
|
|
|
---
|
|
|
|
## Phase 1: Repo Setup
|
|
|
|
Verify you are in a bare git repo and that the issue tracker exists.
|
|
|
|
1. Verify the current repository is bare: `git rev-parse --is-bare-repository 2>/dev/null` must output `true`. If not, stop: "Workflow requires a bare git repository (set up with `git clone --bare` or the `.bare/` + `.git` file pattern)."
|
|
2. Capture the bare repo root for later worktree creation: `BARE_REPO_ROOT="$(pwd)"`.
|
|
3. Determine the default branch (source of TODO.md and base for new worktrees). Resolve in order:
|
|
a. `git symbolic-ref --short HEAD` — the bare repo's HEAD
|
|
b. `git config init.defaultBranch` — the configured default
|
|
c. fall back to `main`
|
|
|
|
Store as `DEFAULT_BRANCH`.
|
|
4. Verify TODO.md exists on the default branch: `git show "$DEFAULT_BRANCH:TODO.md" > /dev/null 2>&1`. If not, stop: "TODO.md not found on `$DEFAULT_BRANCH`. Commit a TODO.md there first — the workflow expects it to be a tracked file."
|
|
5. Proceed to Phase 2.
|
|
|
|
---
|
|
|
|
## Phase 2: Issue Context
|
|
|
|
Dispatch `@pm` in **read-only git-ref mode**: tell it the bare repo path is `$BARE_REPO_ROOT` and to read TODO.md via `git show "$DEFAULT_BRANCH:TODO.md"`. Ask for the issue matching `$ARGUMENTS`:
|
|
- Issue title, description, acceptance criteria
|
|
- Labels and priority
|
|
- Any existing branch name
|
|
|
|
If the issue does not exist or `@pm` fails, stop with error.
|
|
|
|
Derive a branch name: `<issue-id-lowercase>-<slugified-title>` (e.g. `abc-1-add-retry-logic`). Validate: only `[A-Za-z0-9._/-]`, no leading `-`.
|
|
|
|
---
|
|
|
|
## Phase 3: Repo Setup (continued)
|
|
|
|
From `$BARE_REPO_ROOT`:
|
|
|
|
1. If an `origin` remote is configured, run `git fetch origin` (best-effort; ignore failure if there is no remote).
|
|
2. Compute worktree directory: replace all `/` with `-` in the branch name (e.g. `feat/abc-1-foo` becomes `feat-abc-1-foo`)
|
|
3. Check if worktree directory already exists. If yes, enter it and verify `git status --porcelain` is empty. If dirty, stop: "Worktree exists but has uncommitted changes. Clean it up first."
|
|
4. If worktree does not exist: `git worktree add <dir-name> -b <branch-name> "$DEFAULT_BRANCH"`
|
|
5. Change working directory to the new worktree. From here on, `./TODO.md` in the worktree is the **live, writable** copy that Phase 10 will update.
|
|
|
|
---
|
|
|
|
## Phase 4: Plan
|
|
|
|
Analyze the codebase in the worktree context. Create a detailed implementation plan addressing the issue's requirements and acceptance criteria.
|
|
|
|
The plan should include:
|
|
- Problem summary (from issue context)
|
|
- Proposed approach with rationale
|
|
- Files to modify (with brief description of changes)
|
|
- New files to create
|
|
- Risks and open questions
|
|
- **Test Design (conditional — include for non-trivial tasks):**
|
|
- Key behaviors to verify (what tests should assert)
|
|
- Edge cases and error conditions worth testing
|
|
- What explicitly should NOT be tested (prevents bloat)
|
|
- Testability concerns (heavy external deps, GPU-only paths, etc.)
|
|
|
|
**Include Test Design for:** Public API changes, bug fixes with behavioral impact, new features with business logic, multi-module changes.
|
|
**Skip Test Design for:** Config-only changes, decorator swaps, import reorganization, documentation.
|
|
When skipped, `@test` derives test cases directly from acceptance criteria.
|
|
|
|
---
|
|
|
|
## Phase 5: Review Plan
|
|
|
|
Dispatch `@check` and `@simplify` in parallel to review the plan.
|
|
|
|
Reviewers should evaluate testability:
|
|
- `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
|
|
- `@simplify`: Is the test scope appropriate? Over-testing proposed?
|
|
|
|
**Merge rules:**
|
|
- `@check` safety/correctness findings are hard constraints
|
|
- If `@simplify` recommends removing something `@check` flags as needed, `@check` wins
|
|
- Note conflicts explicitly
|
|
|
|
**Review loop (max 3 cycles):**
|
|
1. Send plan to both reviewers
|
|
2. Merge findings
|
|
3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 6
|
|
4. If BLOCK or NEEDS WORK: revise the plan addressing findings, then re-review
|
|
5. **Convergence detection:** if reviewers return the same findings as the previous cycle, stop the loop early
|
|
6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the workflow summary and commit message)
|
|
|
|
---
|
|
|
|
## Phase 6: Split into Tasks
|
|
|
|
Break the approved plan into discrete tasks for `@make`. Each task needs:
|
|
|
|
| Required | Description |
|
|
|----------|-------------|
|
|
| **Task** | Clear description of what to implement |
|
|
| **Acceptance Criteria** | Specific, testable criteria (checkbox format) |
|
|
| **Code Context** | Actual code snippets from the codebase, not just file paths |
|
|
| **Files to Modify** | Explicit list, mark new files with "(create)" |
|
|
| **Test File** | Path for test file (colocated pattern), e.g., `<module>/tests/test_<feature>.py (create)` |
|
|
|
|
Include **Integration Contracts** when a task adds/changes function signatures, APIs, config keys, or has dependencies on other tasks.
|
|
|
|
Include **Test Design** from Phase 4 when available, attached to the relevant task(s).
|
|
|
|
**Task size:** ~10-30 minutes each, single coherent change, clear boundaries.
|
|
|
|
---
|
|
|
|
## Phase 7: Write Tests
|
|
|
|
For each task from Phase 6, dispatch `@test` with:
|
|
- The task spec (acceptance criteria, code context, files to modify)
|
|
- The Test Design section from the plan (if provided)
|
|
- The test file path to create (following colocated pattern)
|
|
|
|
`@test` writes failing tests and verifies RED with structured failure codes.
|
|
|
|
**Post-step file gate (MANDATORY):**
|
|
Before dispatching `@test`, snapshot the current changed files:
|
|
```bash
|
|
git diff --name-only > /tmp/pre_test_baseline.txt
|
|
```
|
|
After `@test` completes, validate only NEW changes:
|
|
```bash
|
|
git diff --name-only | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_files.txt
|
|
```
|
|
All new files must match: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`.
|
|
If any non-matching file appears: discard `@test` output, report violation.
|
|
|
|
**Decision table — handling `@test` results:**
|
|
|
|
| Condition | Action |
|
|
|-----------|--------|
|
|
| `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 8 |
|
|
| `TESTS_READY` + `escalate_to_check: true` | Route tests to `@check` for light review. `@check` diagnoses, caller routes fixes to `@test`. Then proceed. |
|
|
| `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If approved, task goes to `@make` without tests. |
|
|
| `BLOCKED` | Investigate. May need to revise task spec or plan. |
|
|
| Test passes immediately | Investigate — behavior may already exist. Task spec may be wrong. |
|
|
|
|
**Parallelism:** Independent tasks can have tests written in parallel.
|
|
**Constraint:** `@test` must not modify existing conftest.py files (prevents collision during parallel execution).
|
|
|
|
---
|
|
|
|
## Phase 8: Implement
|
|
|
|
Execute each task by dispatching `@make` with:
|
|
- The task spec (from Phase 6)
|
|
- Relevant code context (actual snippets)
|
|
- **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
|
|
|
|
`@make` runs in TDD mode when tests are provided:
|
|
1. Entry validation: run tests, verify RED, check failure codes match handoff
|
|
2. Implement minimal code to make tests pass (GREEN)
|
|
3. Regression check on broader area
|
|
4. Refactor while keeping green
|
|
5. Report RED→GREEN evidence
|
|
|
|
**Escalation:** If `@make` flags test quality concerns during entry validation:
|
|
1. `@make` reports the issue to caller
|
|
2. Caller routes to `@check` for diagnosis
|
|
3. `@check` reports findings
|
|
4. Caller routes to `@test` for fixes
|
|
5. Fixed tests return to `@make`
|
|
|
|
For NOT_TESTABLE tasks, `@make` runs in standard mode.
|
|
|
|
After all tasks complete, verify overall integration:
|
|
- Run the project's test suite if available
|
|
- Run linting/type checking if configured
|
|
- Fix any integration issues between tasks
|
|
|
|
---
|
|
|
|
## Phase 9: Final Review
|
|
|
|
Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
|
|
|
|
Provide reviewers with:
|
|
- The original plan
|
|
- The full diff (`git diff "$DEFAULT_BRANCH"...HEAD`)
|
|
- Any decisions or deviations from the plan
|
|
|
|
**Review loop (max 3 cycles):**
|
|
1. Send implementation to both reviewers
|
|
2. Merge findings (same precedence rules as Phase 5)
|
|
3. If ACCEPTABLE: proceed to Phase 10
|
|
4. If issues found: fix them directly (no need to re-dispatch `@make` for small fixes), then re-review
|
|
5. **Convergence detection:** same findings twice = stop loop early
|
|
6. If unresolved after 3 cycles: document blockers, proceed to commit anyway
|
|
|
|
---
|
|
|
|
## Phase 10: Commit and Wrap Up
|
|
|
|
The workflow is forge-agnostic. It commits locally and stops. **Do not push, and do not open a pull/merge request** — the user chooses their forge and review workflow manually.
|
|
|
|
### Commit Code Changes
|
|
- Stage code changes (everything except `TODO.md` and `.opencode/workflow-summary.md`, which are committed separately below)
|
|
- Write a conventional commit message summarizing the implementation. Reference the TODO.md issue ID in the body (e.g. `Refs: ABC-1`).
|
|
- If changes are large/varied, use multiple atomic commits (one per logical unit)
|
|
|
|
### TODO Update
|
|
- Use `@pm` to update the issue in `./TODO.md` (worktree-local; this is the live, writable copy):
|
|
- Set **Branch** to the worktree branch name
|
|
- Set **Status** to `In Review`
|
|
- Add a comment with the branch name, latest commit SHA, and a one-line summary
|
|
- If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off
|
|
- Commit the TODO.md change as a separate atomic commit: `chore(todo): update <issue-id> status and progress`
|
|
|
|
### Local Summary
|
|
- Write `.opencode/workflow-summary.md` in the worktree with:
|
|
- Run timestamp
|
|
- Issue reference and title
|
|
- Branch name and final commit SHA(s)
|
|
- Summary of implementation
|
|
- TDD evidence (RED→GREEN per task, NOT_TESTABLE justifications)
|
|
- Review outcomes (plan review + final review verdicts)
|
|
- Unresolved items (if any)
|
|
- Files changed
|
|
- Commit the summary: `chore(workflow): summary for <issue-id>`
|
|
|
|
|
|
---
|
|
|
|
## Failure Handling
|
|
|
|
At any phase, if an unrecoverable error occurs:
|
|
1. Write `.opencode/workflow-summary.md` (in the worktree, if one exists) with what was completed and what failed
|
|
2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`
|
|
3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete
|
|
4. If a worktree exists, use `@pm` to add a comment on the issue in `./TODO.md` summarising what failed
|
|
5. Stop execution
|
|
|
|
**Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.
|
|
|