progress-tracking

name	progress-tracking
description	Tiered progress tracking protocol: todowrite for live work, .agents/HANDOFF.md for boundaries, .agents/PROGRESS.md only for heavy-task audit trails.

Progress Tracking

Use the lightest tracker that preserves useful state:

• todowrite: default live tracker for active in-session work.
• .agents/HANDOFF.md: durable tracker only at boundaries: pause, block, user approval/manual testing, transfer, or incomplete session end.
• .agents/PROGRESS.md: exceptional heavy-task tracker only for high-risk migrations/security/payments/auth, multi-agent multi-phase work spanning sessions, complex failure routing, or explicit user request/audit trail.

Use templates/PROGRESS.md only when a heavy-task .agents/PROGRESS.md is justified. Do not initialize it for routine tasks.

PLAN.md ownership lifecycle

Phase	Owner	Can modify .agents/PLAN.md?
Initial planning	planner	Yes — full first draft write.
After grill-me critique	planner or orchestrator coordinating planner revisions	Yes — revise scope/steps per critique before implementation.
After user approval / before implementation	orchestrator	Yes — minor status, execution-mode, or explicit decision-log updates only; record durable reasoning in .agents/HANDOFF.md or .agents/PROGRESS.md only when those trackers are in use.
During implementation	orchestrator	Only status fields, pause decisions, and explicit decision log. Implementers, test-runner, and reviewers are read-only unless explicitly assigned a plan-revision slice.
Post-implementation	orchestrator	Only retroactive correction/decision record if needed; record why in the active durable tracker only when one exists.

Managed state file lifecycle

• .agents/PLAN.md: implementation contract. Created by planner; revised by planner or Orchestrator only for accepted changes. Update sections in place; do not append competing plans.
• todowrite: default in-session task list. Owned by the active agent/orchestrator. Keep it current while work is active; close or revise items before final response.
• .agents/HANDOFF.md: durable handoff/resume artifact. Created only at boundaries. Overwrite for the same issue/slice when superseded; append a new top-level handoff section only for a distinct issue/slice.
• .agents/PROGRESS.md: heavy-task audit/progress ledger. Owned by Orchestrator. Update current status fields in place and append compact activity/check/routing entries chronologically when, and only when, heavy-task criteria apply.
• .agents/TASK_CONTEXT.md: scoped working brief. Created by Orchestrator when durable context is useful; assigned implementation agents may update only their own phase/subtask section.
• .agents/REVIEW.md: read-only deployed review schema template; it is not a result file.
• .agents/REVIEW_<type>-<n>.md: per-pass durable review artifact. The orchestrator allocates the path and its assigned reviewer writes it once. Re-review uses a new successor artifact with predecessor/disposition references; never overwrite it.

Universal handoff status values: completed, completed-with-warnings, partially-completed, blocked, paused, needs-review, needs-fix, failed.

Update rules

• Start with todowrite for live work; skip it only for trivial single-step Q&A or when another explicit tracker is better.
• Create or update .agents/HANDOFF.md only when pausing, blocking, waiting for approval/manual testing, transferring ownership, or ending with incomplete work.
• Create or update .agents/PROGRESS.md only for heavy-task/audit cases. Keep entries factual and concise; do not use it for hidden reasoning.
• If .agents/PLAN.md changes during execution, record the reason in todowrite for active work and in the active durable tracker only when one exists.
• Preserve append-only logs where requested by the active template. Update current status fields in place.
• Route review work by <artifact-path>#F<n> only. HANDOFF, TASK_CONTEXT, and heavy-task PROGRESS may contain owner/status/next-action metadata, never copied findings.

Heavy-task PROGRESS.md sections

templates/PROGRESS.md defines the compact heavy-task-only section order: Current Status, Phase/Subtask Summary, Recent Events, Files Changed, Checks, Issues/Routing, Blockers, Decisions, and Final Summary.

Required status values

• Phase status: not-started, in-progress, completed, blocked, skipped, needs-fix, waiting-for-user.
• Subtask status: not-started, assigned, in-progress, completed, failed, needs-fix, blocked, skipped.
• Overall status: not-started, planning, reviewing-plan, implementing, testing, fixing, waiting-for-user, blocked, completed, completed-with-warnings, failed.
• Test status: not-run, passed, failed, partially-passed, skipped, blocked.