Skip to content

Agent Task Plan Template

Create a task folder and copy this file to: tmp/agent-plans/<YYYY-MM-DD>-<task-slug>/plan.md before implementation.

Recommended per-task structure:

tmp/agent-plans/
  <YYYY-MM-DD>-<task-slug>/
    plan.md        # required source of truth for the task
    worklog.md     # optional detailed command/output notes
    review.md      # optional reviewer findings and sign-off

0. Kickoff Message (Send Before Implementation)

Use this 5-line kickoff format in chat before substantial implementation/debugging work:

  • Scope:
  • Target tests:
  • Open questions status:
  • Risks:
  • Plan:

Open questions status should normally be None (resolved). If not None (resolved), implementation is blocked until questions are resolved with the human.

1. Task Summary

  • Request:
  • In scope:
  • Out of scope:

2. Clarifications and Decisions

  • Open questions:
  • Open questions resolved before implementation
  • OpenSpec decision:
  • Use OpenSpec
  • OpenSpec overridden by human ("no OpenSpec")
  • If overridden, rationale:
  • Options presented to human:
  • Option A:
  • Option B:
  • Option C:
  • Human decision:
  • Decisions log:

3. Acceptance Targets

Target Tests (Primary Acceptance)

  • Use docs/dev/component_command_registry.md to select canonical commands.
  • Test command 1 (stack-appropriate):
  • Test command 2 (stack-appropriate):
  • New/updated tests to add:

Non-Test Acceptance Criteria

  • Criterion 1:
  • Criterion 2:

4. Edge Cases and Risks

  • Edge case 1:
  • Edge case 2:
  • Risk and mitigation:

5. Test-First Execution Log

  • Wrote/updated tests before any production code changes
  • Verified failing tests before code changes
  • Recorded failing test command/result before first production code change
  • Implemented production code changes
  • Re-ran target tests until green
  • Ran regression/adjacent tests
  • No process violation (no production code edits before failing-test record)

5a. Process Violations (If Any)

  • Violation occurred? (yes/no):
  • What happened:
  • Corrective action taken:

5b. Reviewer Coverage Audit

  • Unit-test coverage reviewed
  • Integration-style test coverage reviewed (or N/A with reason)
  • E2E coverage reviewed via code-path inspection/CI evidence if supported by existing harness (or N/A with reason)
  • Confirmed no local E2E run was performed unless explicitly requested by human
  • Coverage gaps and residual risk documented

5c. Reviewer Output (Required Format)

  • Findings by priority:
  • P0:
  • P1:
  • P2:
  • P3:
  • Use docs/dev/review_severity_rubric.md for priority assignment.
  • Coverage audit summary:
  • Unit:
  • Integration-style:
  • E2E:
  • Residual risk summary:
  • Final recommendation: approve / needs changes

6. Workstream Plan (If Parallelized)

  • Workstream A:
  • Scope:
  • Worktree:
  • Implementor:
  • Reviewer:
  • Workstream B:
  • Scope:
  • Worktree:
  • Implementor:
  • Reviewer:

7. Merge and Verification Checklist

  • Manually inspected each worktree diff
  • Merged workstreams one by one
  • Ran target tests after each merge
  • Committed after each successful merge

8. Progress Log

  • Timestamp:
  • Change:
  • Test result:
  • Commit:

9. Process Improvements

  • Did human corrections or debugging-loop guidance occur? (yes/no):
  • If yes, proposed update location:
  • AGENTS.md path:
  • or local note in tmp/agent-learnings/<YYYY-MM-DD>-<topic>.md:
  • Proposed rule/procedure update: