manual-planning
Skill321 starsChanged 7 days agoMITView on GitHub
Create, update, review, and execute manual Markdown implementation plans when harness planning mode is not being used. Use when the user asks for a plan file, manual plan, implementation plan, execution plan, roadmap, task checklist, planning document, or agent-maintained plan with statuses, validations, milestones, approval gates, and cleanup steps. Also use when resuming or maintaining an existing plan — marking a task complete, checking plan status, recording a decision, or validating a plan file — even when the user does not say "plan file". Triggers: plan file, manual plan, implementation plan, execution plan, planning document, plan template, resume plan, update the plan, continue the plan, plan status, task checklist, roadmap, milestones, exit criteria, approval gate, decision log, cleanup phase, check-plan, new-plan.
In this repository49 other files it gives its agents.
- .agents/skills/unsafe-checker/AGENTS.mdAGENTS.md
- benchmarks/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- src-tauri/CLAUDE.mdCLAUDE.md
- website/CLAUDE.mdCLAUDE.md
- website/llms-full.txtllms.txt
- website/llms.txtllms.txt
- ci-gate-diagnosisSkill
- coding-guidelinesSkill
- domain-webSkill
- exploration-modeSkill
- flathub-maintenanceSkill
- m01-ownershipSkill
- m02-resourceSkill
- m03-mutabilitySkill
- m04-zero-costSkill
- m05-type-drivenSkill
- m06-error-handlingSkill
- m07-concurrencySkill
- m09-domainSkill
- m10-performanceSkill
- m11-ecosystemSkill
- m12-lifecycleSkill
- m13-domain-errorSkill
- m14-mental-modelSkill
- m15-anti-patternSkill
- runbooksSkill
- rust-call-graphSkill
- rust-code-navigatorSkill
- rust-dailySkill
- rust-deps-visualizerSkill
- rust-learnerSkill
- rust-refactor-helperSkill
- rust-skill-creatorSkill
- rust-symbol-analyzerSkill
- rust-trait-explorerSkill
- security-stanceSkill
- seo-auditSkill
- seo-performance-reviewSkill
- skill-improverSkill
- solidjsSkill
- sync-lockfilesSkill
- tauri-agent-devSkill
- tauri-v2Skill
- tiptapSkill
- todo-managerSkill
- unsafe-checkerSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
29 rules. About 0 are common, 13 are distinctive, and 16 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
16
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 65
Default to not committing the plan.
- Very specific: line 69
If the plan stays untracked and its ??
- Very specific: line 79
Create the file with new-plan.py, choosing --milestoned for more than 10 tasks.
- Distinctive: line 88
Do not begin implementation until the user approves the plan, unless the user explicitly asks to proceed without approval.
- Distinctive: line 99
If no such tool is available, send a concise formatted message in the conversation.
- Very specific: line 101
After the user answers, replace the entry with the resolved answer, or the section with None.
- Distinctive: line 103
Ask only questions that affect correctness, scope, risk, validation, sequencing, or approval.
- Distinctive: line 108
Do not combine unresolved clarifying questions and final approval in the same user prompt.
- Very specific: line 123
Use BLOCKED when planning or implementation cannot continue, and record the blocker.
- Very specific: line 127
Every plan has these top-level sections, which is what check-plan.py E009 enforces:
- Very specific: line 143
Use exactly these task statuses: TO BE DONE, IN PROGRESS, COMPLETED, BLOCKED, SKIPPED.
- Very specific: line 145
Use exactly these plan statuses: DRAFT, QUESTIONS PENDING, READY FOR APPROVAL, APPROVED, IN PROGRESS, COMPLETED, BLOCKED.
- Very specific: line 180
Commits are steps: Write each commit where it belongs: Commit: <message scope>.
- Distinctive: line 185
Prefer deterministic validation — a test, build, linter, or exact file inspection.
- Very specific: line 200
Before starting a task, set it to IN PROGRESS — plan-status.py <plan> set <id> "IN PROGRESS".
- Very specific: line 202
Run the task validation. Before declaring it passed, check the task's Steps and Validation for explicitly named tests (e.g.
- Distinctive: line 208
Update the milestone status when its tasks satisfy its exit criteria.
- Very specific: line 209
Start the next task only after the plan file reflects the current state, then continue to it without asking (see ## Session Protocol).
- Distinctive: line 212
If validation was intentionally deferred earlier, reconcile the plan text once the deferred checks actually run.
- Distinctive: line 215
Discovered issues: If a bug or unplanned problem is identified while working on a task, choose one path immediately — do not defer via a …
- Very specific: line 219
Create a new task in the plan with status BLOCKED if it is out of scope for the current task.
- Distinctive: line 243
Write an entry before moving to the next task, never retrospectively.
- Very specific: line 260
Read references/decision-log.md when the inline log passes ~10 entries (check-plan.py warns with W005), when the user asks for a companion …
- Distinctive: line 266
Every plan must include a cleanup task near the end, removing intermediate artifacts that should not ship: temporary documentation, one-off …
- Distinctive: line 270
Do not remove artifacts the user asked to keep, artifacts required for future maintainability, or generated files that are part of the …
- Distinctive: line 273
Changelog steps are conditional: Add one only when the project actually has a changelog file.
- Very specific: line 281
If the session-telemetry skill is installed, run telemetry.py close <plan> at COMPLETED and paste its summary into ## Final Verification.
- Very specific: line 289
Run the checker and paste its output into ## Plan Self-Check with the date:
- Very specific: line 298
Do not replace this with a hand-ticked list.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Manual Planning
Produce Markdown plans that another coding agent can execute without reinterpreting the original conversation. A plan is an execution ledger, not a proposal: it has to stay accurate while it is being worked through, and it has to be readable cold by a session that was not there when it was written.
Anything that can be checked mechanically is checked by a script. Do not hand-verify what
check-plan.py verifies.
Scripts
Standard library Python 3 only — no install step. Run with python3 or uv run.
# Create a plan: correct name, correct directory, version stamped from this SKILL.md
python3 scripts/new-plan.py "<title>" [--milestoned] [--dir docs/plans]
[--exclude-locally | --tracked] [--force]
# Validate a plan (read-only). exit 0 = clean, 1 = errors, 2 = warnings only
python3 scripts/check-plan.py <plan-file> [--json] [--strict] [--dir docs/plans]
# Read state: every status, or the session-start digest
python3 scripts/plan-status.py <plan-file> show
python3 scripts/plan-status.py <plan-file> brief
# Write state
python3 scripts/plan-status.py <plan-file> set <task-id> "<STATUS>"
python3 scripts/plan-status.py <plan-file> set-plan "<PLAN STATUS>"
python3 scripts/plan-status.py <plan-file> resume --state "..." --next <ids> --stop <reason>
[--detail ...] [--green ...] [--env ...] [--risks ...] [--from-file F]
python3 scripts/plan-status.py <plan-file> decision --task <id> --title T --decision D --rationale R
python3 scripts/plan-status.py <plan-file> note --task <id> "<evidence line>"Each answers --help, which lists every check ID and exit code. Quote status arguments: three of
the five task statuses contain a space.
Default Location
docs/plans/YYYY-MM-DD-<name>-plan.md.
The date in the filename is the date of record, which is why the metadata block carries no
Created or Last Updated field. new-plan.py produces both the directory and the filename, so
neither is a rule you have to remember. Avoid names like notes.md, scratch.md or todo.md.
Plan Tracking
Default to not committing the plan. Follow the repo instead when it already has a convention: if the plan directory holds tracked plans, this project commits them. Commit the plan when the user asks.
If the plan stays untracked and its ?? entry interferes — a plan's own cleanup task validates with
git status --porcelain — add the plan directory to .git/info/exclude rather than .gitignore;
.gitignore is itself a tracked file, so editing it creates the commit you were avoiding.
new-plan.py --exclude-locally does this and stamps Tracking: untracked (locally excluded).
Plan Creation Workflow
- Gather enough repository context to identify scope, dependencies, test surfaces, and likely
risks. Everything you learn here goes in
## Context For A Clean Session— seereferences/context-and-evidence.md. - Create the file with
new-plan.py, choosing--milestonedfor more than 10 tasks. - Fill in the template. Every factual claim carries evidence: a
file:linereference, a section reference (SKILL_RULES.md §5), or a re-runnable command. - Set
Plan StatustoQUESTIONS PENDINGif clarification is required, then surface the questions to the user. Mirror them inOpen Questions. - Incorporate the answers, run
check-plan.py, and paste its output into## Plan Self-Check. - Set
Plan StatustoREADY FOR APPROVALonly when the checker is clean and the only remaining gate is user approval.
Do not begin implementation until the user approves the plan, unless the user explicitly asks to
proceed without approval. When approval is given, replace the ## Approval Gate boilerplate with
Approved by <who> on <date>. — the section is a record, not a standing instruction.
Open Question Handling
Open questions are not plan-only notes. When clarification is needed, actively ask the user before
marking the plan READY FOR APPROVAL.
- Use the native question-asking tool (
question,ask-user,request-input, or whatever the current harness exposes). Always prefer a structured tool over plain text. - If no such tool is available, send a concise formatted message in the conversation.
- Record both the question and the user's answer in
Open Questions. - After the user answers, replace the entry with the resolved answer, or the section with
None.
Ask only questions that affect correctness, scope, risk, validation, sequencing, or approval. Do not ask what the repository can answer or what can safely become a stated assumption.
All open questions must be answered before the plan can transition to READY FOR APPROVAL.
Do not combine unresolved clarifying questions and final approval in the same user prompt.
Plan State Lifecycle
Plan Status in the metadata block is the authoritative plan-level state. It is modelled once —
there is no separate Approval field, because in the surveyed corpus the two contradicted each
other in 11 of 32 plans.
DRAFTwhile creating the first version.QUESTIONS PENDINGwhile waiting for required clarification.READY FOR APPROVALafter clarification is incorporated and the checker is clean.APPROVEDafter the user approves execution.IN PROGRESSwhile implementation is underway.COMPLETEDafter cleanup,## Pre-flight Checksand final verification all pass.
Use BLOCKED when planning or implementation cannot continue, and record the blocker.
Plan Format Rules
Every plan has these top-level sections, which is what check-plan.py E009 enforces:
Metadata, Status Legend, Resume, Context For A Clean Session, Goal, Scope, Non-Goals,
Assumptions, Open Questions, Milestones (or Tasks in a simple plan), Project Gates,
Pre-flight Checks, Decision Log, Final Verification, Approval Gate, Plan Self-Check,
Execution Notes.
The metadata block is exactly four fields:
- Plan Status: DRAFT
- Plan Format: manual-planning v2.1.0
- Template: milestoned
- Tracking: untrackedUse exactly these task statuses: TO BE DONE, IN PROGRESS, COMPLETED, BLOCKED, SKIPPED.
Use exactly these plan statuses: DRAFT, QUESTIONS PENDING, READY FOR APPROVAL, APPROVED,
IN PROGRESS, COMPLETED, BLOCKED.
A status may carry a trailing annotation (COMPLETED — 381/381 passing); the vocabulary applies to
the leading token.
More than 10 tasks requires milestones. With 10 or fewer, omit milestones unless they clarify independent delivery phases.
## Project Gates is where project-specific rules live — per-project lint/build/test commands,
manual-verification requirements, changelog or backlog bookkeeping. Put them there rather than
forking this skill for a project.
## Pre-flight Checks is a named checklist of the project's actual commands, run before the plan may
reach COMPLETED. It is distinct from per-task validation: per-task validation proves one task
worked, pre-flight checks prove the repository is shippable.
## Resume is the session handover. Only plan-status.py resume writes it.
Task Rules
Each task must include:
Status: one of the task statuses.Depends On:none, or a list of task numbers.Objective: the observable outcome.Steps: concrete implementation steps.Validation: commands, tests, inspections, or self-checks that prove completion.Notes: constraints, affected files, orNone.
Task numbering is not an execution order. Depends On is the order. Task 3.1 may be runnable
before Task 2.2.
A task should fit in one session. Split long or paid verification into gated subtasks.
Commits are steps. Write each commit where it belongs: Commit: <message scope>.
Results are at most 3 lines in the task's Notes. Longer evidence goes to the companion
-notes.md via plan-status.py note.
Prefer deterministic validation — a test, build, linter, or exact file inspection. Where none is
possible, state the manual check in observable terms. Say explicitly when a validation passes by
producing no output: grep finding nothing exits 1, and so does diff on files that are meant to
differ. An executing agent that branches on $? will read those as failures.
Milestone Rules
Each milestone must include Status, Purpose, Exit Criteria, and its tasks. Exit criteria must
be broader than any single task validation: they confirm the completed tasks work together and that
the next milestone can safely start.
Implementation Workflow
- Set the plan status to
IN PROGRESSbefore starting implementation —plan-status.py <plan> set-plan "IN PROGRESS". - Before starting a task, set it to
IN PROGRESS—plan-status.py <plan> set <id> "IN PROGRESS". - Complete the task.
- Run the task validation. Before declaring it passed, check the task's
StepsandValidationfor explicitly named tests (e.g. "add a testtest_foo_bar"). A green test suite does not mean those tests were written — verify by name. A test or guard added for a fix must be seen failing before the fix and passing after. - Fix issues until validation passes, or mark the task
BLOCKEDwith a reason. - Set the task to
COMPLETEDimmediately after validation passes. - Update the milestone status when its tasks satisfy its exit criteria.
- Start the next task only after the plan file reflects the current state, then continue to it
without asking (see
## Session Protocol).
If validation was intentionally deferred earlier, reconcile the plan text once the deferred checks actually run. Leave no stale "validation pending" phrasing describing a state the plan has moved past.
Discovered issues. If a bug or unplanned problem is identified while working on a task, choose one path immediately — do not defer via a mental note:
- Fix it in the current task if it is small and in scope.
- Create a new task in the plan with status
BLOCKEDif it is out of scope for the current task.
A bug that is noticed but neither fixed nor recorded will be forgotten. There is no third option.
Session Protocol
- Start with
plan-status.py <plan> brief. Read only what it points to, not the whole plan. - Continue to the next runnable task without asking. Stop only for a
## Project Gatesitem, a question only the user can answer, or context pressure. - Before stopping, run
plan-status.py <plan> resume, then end the final message withStop: <done | ask | gate | question | context | limit> — <detail>.
The user restarts with Continue <plan> from its Resume block.
Plan Writes
Change the plan only with the Edit tool or plan-status.py, never with an ad-hoc script.
Decision Log
## Decision Log is always present, in simple and milestoned plans alike. Deviations, discovered
issues and deferred validations are the same shape of event and all land in this one append-only
section.
Write an entry before moving to the next task, never retrospectively. Entries written after the fact are unreliable.
An entry is required when implementation diverges from what the plan specifies (different path, signature, or approach), when a validation failure forces the plan to adapt, when an unplanned problem is found, or when a validation is deliberately deferred. No entry is needed when execution matches the plan, or for wording differences that change no outcome.
### DEC-001 — <short title>
- Date: YYYY-MM-DD
- Task: <task number>
- Decision: <what was chosen>
- Rationale: <why>Read references/decision-log.md when the inline log passes ~10 entries (check-plan.py warns with
W005), when the user asks for a companion decisions file, or when you are unsure whether something
qualifies as an entry.
Cleanup Phase
Every plan must include a cleanup task near the end, removing intermediate artifacts that should not ship: temporary documentation, one-off test cases, scratch scripts, temporary fixtures, generated data, debug logs, local-only outputs, and obsolete plan fragments.
Do not remove artifacts the user asked to keep, artifacts required for future maintainability, or generated files that are part of the repository contract.
Changelog steps are conditional. Add one only when the project actually has a changelog file.
check-plan.py E010 looks for CHANGELOG* at the repository root and requires a task step
mentioning it only when one exists — a project without a changelog needs no changelog step.
Plan Retirement
Untracked plans need no retirement step; deleting the file is enough.
If the session-telemetry skill is installed, run telemetry.py close <plan> at COMPLETED and
paste its summary into ## Final Verification.
Where plans are committed, the project owns the retirement convention, and check-plan.py must pass
before a plan is retired: in a tracked repo a misleading final state is permanent.
Self-Check Before Approval
Run the checker and paste its output into ## Plan Self-Check with the date:
python3 scripts/check-plan.py docs/plans/<plan>.mdFix every error before requesting approval. Judge each warning on its merits and say in the plan why any surviving warning is acceptable.
Do not replace this with a hand-ticked list. The v1 hand-ticked self-check passed in 32 of 32
surveyed plans and failed in none — including on a plan with no Open Questions section that still
claimed its open questions were explicit. It was a signature, not a gate.
Gotchas
- A deployed skill copy can be older than its repository. Editing a repo changes nothing about
what runs if the deployed path is a copy rather than a symlink into it. Check what the path
actually resolves to (
readlink, then read the file that comes back) before assuming an edit took effect. - Task numbering is not an execution order. That is what
Depends Onis for. Reading the numbers as a sequence serialises work that was designed to run in any dependency-respecting order. .gitignoreversus.git/info/exclude..gitignoreis tracked, so excluding an untracked plan there produces the very commit the untracked default avoids. Use.git/info/exclude.- A plan that reaches
COMPLETEDwith tasks stillTO BE DONEis the single most common way a plan ends up lying. Three surveyed plans were closed with every one of their 18–26 tasks stillTO BE DONE.E005catches it;plan-status.pywarns as soon as a write creates it. - Statuses are scattered. A 26-task plan has 27+ status lines. Use
plan-status.py set, which rewrites exactly one line, rather than editing by hand and missing some. - A validation that passes by producing no output exits non-zero. Read what the validation
asserts rather than branching on
$?. - Greenfield plans cannot cite line numbers in files that do not exist yet. That is why the
evidence check only hardens (
E011) when the plan names files that already exist, and otherwise only warns (W003).
References
references/context-and-evidence.md— read before writing## Context For A Clean Session, or when a plan is being written for a session that will not have the originating conversation.references/decision-log.md— read when the inline decision log passes ~10 entries, when a companion decisions file is requested, or when deciding whether an event qualifies as an entry.references/session-protocol.md— read when writing the Resume block or choosing a stop reason.
Resources
new-plan.py copies the right one; copy by hand only if the script cannot run.
assets/simple-plan-template.md— 10 or fewer tasks.assets/milestoned-plan-template.md— more than 10 tasks.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

