managing-plans_skill

Overview

This skill orchestrates project plan state management and execution using ROADMAP.md and phase files. It ensures tasks move through Pending → In Progress → Complete, handles blockers with formal handoffs, and enforces atomic state updates for reproducibility. Use it whenever you are operating on an existing project plan to run, update, or verify plan progress.

How this skill works

The skill reads .cattoolkit/plan/{project-slug}/ROADMAP.md to find the active phase, then reads the phase file (e.g., phases/01-setup/01-01-PLAN.md) to discover tasks. It runs an execution loop: pick the next pending task, execute work or dispatch to a worker agent, verify results, and immediately update the task status. If a blocker or unrecoverable error occurs, it creates a HANDOFF.md using the template and pauses execution.

When to use it

• Executing a defined project plan and progressing phases
• Updating task or phase status after completing work or verification
• Coordinating non-interactive worker agents to dispatch and monitor tasks
• Handling blockers that require another team or human decision via a handoff
• Creating or updating phase summaries and finalizing phase completion

Best practices

• Always read ROADMAP.md before starting any plan operation to avoid conflicts
• Make one atomic commit per status change (one commit per checkmark) for traceability
• Verify outputs at task, phase, and plan levels before marking complete
• Use the HANDOFF.md template for any blocker that cannot be auto-recovered
• Follow the defined recovery levels: automatic retry → partial recovery → handoff

Example use cases

• Running a release phase: pick tasks, run build/test steps, mark tasks complete
• Onboarding setup: execute environment tasks sequentially and update ROADMAP.md
• Coordinating long-running jobs by dispatching to worker agents and monitoring results
• Documenting a blocker: generate HANDOFF.md, update task to Blocked, pause execution
• Finalizing a phase: verify all tasks, create summary, and mark the phase complete in ROADMAP.md