agentleFS
fjrevoredofjrevoredo/mini-diarium/.agents/skills/manual-planning/SKILL.md

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.

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
  1. Distinctive:

    Default to not committing the plan.

    line 65
  2. Very specific:

    If the plan stays untracked and its ??

    line 69
  3. Very specific:

    Create the file with new-plan.py, choosing --milestoned for more than 10 tasks.

    line 79
  4. Distinctive:

    Do not begin implementation until the user approves the plan, unless the user explicitly asks to proceed without approval.

    line 88
  5. Distinctive:

    If no such tool is available, send a concise formatted message in the conversation.

    line 99
  6. Very specific:

    After the user answers, replace the entry with the resolved answer, or the section with None.

    line 101
  7. Distinctive:

    Ask only questions that affect correctness, scope, risk, validation, sequencing, or approval.

    line 103
  8. Distinctive:

    Do not combine unresolved clarifying questions and final approval in the same user prompt.

    line 108
  9. Very specific:

    Use BLOCKED when planning or implementation cannot continue, and record the blocker.

    line 123
  10. Very specific:

    Every plan has these top-level sections, which is what check-plan.py E009 enforces:

    line 127
  11. Very specific:

    Use exactly these task statuses: TO BE DONE, IN PROGRESS, COMPLETED, BLOCKED, SKIPPED.

    line 143
  12. Very specific:

    Use exactly these plan statuses: DRAFT, QUESTIONS PENDING, READY FOR APPROVAL, APPROVED, IN PROGRESS, COMPLETED, BLOCKED.

    line 145
  13. Very specific:

    Commits are steps: Write each commit where it belongs: Commit: <message scope>.

    line 180
  14. Distinctive:

    Prefer deterministic validation — a test, build, linter, or exact file inspection.

    line 185
  15. Very specific:

    Before starting a task, set it to IN PROGRESS — plan-status.py <plan> set <id> "IN PROGRESS".

    line 200
  16. Very specific:

    Run the task validation. Before declaring it passed, check the task's Steps and Validation for explicitly named tests (e.g.

    line 202
  17. Distinctive:

    Update the milestone status when its tasks satisfy its exit criteria.

    line 208
  18. Very specific:

    Start the next task only after the plan file reflects the current state, then continue to it without asking (see ## Session Protocol).

    line 209
  19. Distinctive:

    If validation was intentionally deferred earlier, reconcile the plan text once the deferred checks actually run.

    line 212
  20. Distinctive:

    Discovered issues: If a bug or unplanned problem is identified while working on a task, choose one path immediately — do not defer via a …

    line 215
  21. Very specific:

    Create a new task in the plan with status BLOCKED if it is out of scope for the current task.

    line 219
  22. Distinctive:

    Write an entry before moving to the next task, never retrospectively.

    line 243
  23. Very specific:

    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 …

    line 260
  24. Distinctive:

    Every plan must include a cleanup task near the end, removing intermediate artifacts that should not ship: temporary documentation, one-off …

    line 266
  25. Distinctive:

    Do not remove artifacts the user asked to keep, artifacts required for future maintainability, or generated files that are part of the …

    line 270
  26. Distinctive:

    Changelog steps are conditional: Add one only when the project actually has a changelog file.

    line 273
  27. Very specific:

    If the session-telemetry skill is installed, run telemetry.py close <plan> at COMPLETED and paste its summary into ## Final Verification.

    line 281
  28. Very specific:

    Run the checker and paste its output into ## Plan Self-Check with the date:

    line 289
  29. Very specific:

    Do not replace this with a hand-ticked list.

    line 298

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Gather enough repository context to identify scope, dependencies, test surfaces, and likely risks. Everything you learn here goes in ## Context For A Clean Session — see references/context-and-evidence.md.
  2. Create the file with new-plan.py, choosing --milestoned for more than 10 tasks.
  3. Fill in the template. Every factual claim carries evidence: a file:line reference, a section reference (SKILL_RULES.md §5), or a re-runnable command.
  4. Set Plan Status to QUESTIONS PENDING if clarification is required, then surface the questions to the user. Mirror them in Open Questions.
  5. Incorporate the answers, run check-plan.py, and paste its output into ## Plan Self-Check.
  6. Set Plan Status to READY FOR APPROVAL only 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.

  1. 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.
  2. If no such tool is available, send a concise formatted message in the conversation.
  3. Record both the question and the user's answer in Open Questions.
  4. 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.

  1. DRAFT while creating the first version.
  2. QUESTIONS PENDING while waiting for required clarification.
  3. READY FOR APPROVAL after clarification is incorporated and the checker is clean.
  4. APPROVED after the user approves execution.
  5. IN PROGRESS while implementation is underway.
  6. COMPLETED after cleanup, ## Pre-flight Checks and 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: untracked

Use 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, or None.

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

  1. Set the plan status to IN PROGRESS before starting implementation — plan-status.py <plan> set-plan "IN PROGRESS".
  2. Before starting a task, set it to IN PROGRESS — plan-status.py <plan> set <id> "IN PROGRESS".
  3. Complete the task.
  4. Run the task validation. Before declaring it passed, check the task's Steps and Validation for explicitly named tests (e.g. "add a test test_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.
  5. Fix issues until validation passes, or mark the task BLOCKED with a reason.
  6. Set the task to COMPLETED immediately after validation passes.
  7. Update the milestone status when its tasks satisfy its exit criteria.
  8. 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 BLOCKED if 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

  1. Start with plan-status.py <plan> brief. Read only what it points to, not the whole plan.
  2. Continue to the next runnable task without asking. Stop only for a ## Project Gates item, a question only the user can answer, or context pressure.
  3. Before stopping, run plan-status.py <plan> resume, then end the final message with Stop: <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>.md

Fix 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 On is for. Reading the numbers as a sequence serialises work that was designed to run in any dependency-respecting order.
  • .gitignore versus .git/info/exclude. .gitignore is tracked, so excluding an untracked plan there produces the very commit the untracked default avoids. Use .git/info/exclude.
  • A plan that reaches COMPLETED with tasks still TO BE DONE is the single most common way a plan ends up lying. Three surveyed plans were closed with every one of their 18–26 tasks still TO BE DONE. E005 catches it; plan-status.py warns 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.