Skip to main content

Plan File Lifecycle

Source: .agents/references/implementation/plan-file-lifecycle.md

Content​

Plan File Lifecycle

The master checklist plan file is a temporary resumability artifact for .agents/skills/implement-feature/SKILL.md.

Location​

Create the file at:

plan-docs/<feature-name>-master-checklist.md

Use a kebab-case feature name.

Creation Timing​

Create the file after requirements are clarified and before implementation assignment begins.

The file must include:

  • Clarified requirements summary
  • Dependencies section
  • Master checklist
  • Worktree assignments
  • QA/review results as they happen
  • Integration status

Git Policy​

  • Keep the file uncommitted by default.
  • Do not stage or commit it unless the user explicitly asks to preserve implementation history.
  • If the file is generated during a feature run, include it in status summaries as a temporary artifact.

Updates During Execution​

Update the file whenever:

  • A task changes status.
  • A dependency changes.
  • QA fails or passes.
  • Code review fails or passes.
  • Retry count changes.
  • A task is split, merged, reassigned, or blocked.
  • Integration status changes.

Deletion​

Delete the file after:

  • Every task is passed or merged.
  • Final integration is complete.
  • Final verification passes.
  • Final summary is prepared.

Do not delete it if:

  • Any task is still blocked or failed.
  • The user asks to preserve it.
  • The agent must stop before completion and the file is needed for resumption.

Resuming From the File​

When resuming:

  1. Read the plan file.
  2. Verify current git status and worktree assignments.
  3. Re-load required context.
  4. Continue from the first non-passed/non-merged task.
  5. Update the file before making further assignments.