manage-plan
Create, update, or check the plan for one issue — what gets done, in what order, and why, never how — written to the issue's STM as specs/plan.md in the canonical plan format. Called by an agent after
SKILL.mdcore/components/skills/manage-plan/SKILL.md
GitHubmanage-plan
Plan mode for Garura (#619). Every drive and every play works from a plan on disk: it writes the plan before it works, keeps it current while it works, and is done only when the plan is done. A plan says what gets done, in what order, and why that order. It never says how — that is design, and it belongs in each item's own issue.
You write and update the plan. You do NOT gather context (the calling agent did that) and you do NOT decide what the work is (the issue and its context say that).
Input
Receive from the agent:
| Field | Required | Meaning |
|---|---|---|
action |
yes | create · update · check |
issue |
yes | the issue number the plan is for |
plan_path |
yes | {stm_base}{issue}/specs/plan.md |
context_path |
create, update |
the plan context file the agent wrote (see below) |
change |
update |
what happened, in plain words — e.g. "item 2 is finished", "Kapil moved #619 to the front", "item 4 is dropped: covered by #612" |
report_path |
yes | where to write the check report (e.g. {stm_base}{issue}/context/plan-check.json) |
template_path |
no | the work-plan format; default ~/.garura/core/memory/standards/templates/work-plan.md |
rules_path |
no | the work-plan rules; default ~/.garura/core/memory/standards/rules/work-plan.md |
The plan context file (written by the agent, YAML or JSON) holds:
issue— number, type, title, full bodytree_available—falsewhen the tracker could not report type, parent or children (GitLab, or gh older than 2.94.0); then those are unknown, not emptyparent— number, type, title (or null)children— each child issue's number, type, title, state, and its own childrenlinked— issues the agent found linked by the tracker's parent/child link only, never body mentionsexisting_plan— the path of a plan already on disk, or nullparent_plan— the path of the parent issue's plan, or nulldecisions— paths to decision records the issue points at (ADRs, spike notes), if anynotes— anything the user said about order or priority, quoted, with the date
Process
Read both files first, every time: the format at template_path and the rules at rules_path (defaults in Input). They are the single source; this skill applies them and never restates them. A work plan is not /implement's build plan.
Action: create
- If
existing_planis set, write nothing: run the check on the existing plan and return its paths. A plan is never written twice; the caller sendsupdatewith achangeif it wants the plan changed. - Read the context file and every decision record it lists.
- Write
plan_pathin the canonical format:- What we are trying to reach — what is true today, what should be true instead, and why, in plain words.
- When this plan is done — observable outcomes. For a business intent, say that it is met by its outcome, not by its children closing.
- Where we are now — what is already done or decided, and the next step.
- The plan, in order — finished children under
### Done; open children as numbered items. Each item carries Issue, What, Why here, Done when, Needs. Order follows the context's dependencies and the user's quoted notes; where neither settles it, put decisions before the builds that depend on them. - Mark exactly one item
— now, and set the same number in the front matter. - Every finished item says what kind of done it is — decided, built, or shipped — and what is still not done.
- If
tree_availableisfalse, say in Where we are now that the parent and children could not be read, and list only what the context does hold. - Unless the issue is a business intent, set
serves_planto the parent issue's number andserves_itemto this issue's item in the parent's plan (the context'sparent_plansays where that plan is). If the parent has no plan yet, say so in the log and leave both out. - Log — one dated line: the plan was created, and from what.
- Run the check (below). Fix anything it reports before returning.
Action: update
- Read the plan and the
change. - Apply only that change:
- a finished item moves to
### Doneas one line, keeping its number (**{n}. Decided | Built | Shipped: …**), saying what it settled or delivered and what is still not done; - a dropped item is removed, and the log says why;
- a reorder moves items and fixes every Needs that pointed at them;
- move
— nowand the front matternowto the next item that can start.
- a finished item moves to
- Set
updatedto today. Add one dated log line saying what changed and why. - When no numbered item is left, set
status: doneandnow: -. - A big update (rules file: adding, dropping or reordering items; a play finishing inside a drive; a linked issue completing) is logged as big. Outside a drive, the calling play routes it to
approve-change(planned, #622); this skill does not ask the human. - Run the check. Fix anything it reports before returning.
Action: check
Run the bundled script. It is deterministic: no git, no network, no judgment.
python3 <skill-dir>/scripts/check_plan.py --plan <plan_path> --out <report_path>
<skill-dir> is this skill's folder (.claude/skills/manage-plan/ once installed). Its tests: python3 <skill-dir>/scripts/test_check_plan.py.
Exit 0 — valid and done. Exit 1 — valid, not done (the normal state while work runs). Exit 2 — not valid: the report lists every problem. Exit 3 — the file cannot be read.
Output
Every action writes files and returns their paths — never the content:
plan_path: {stm_base}{issue}/specs/plan.md # create / update
report_path: {stm_base}{issue}/context/plan-check.json
The report at report_path is the script's output, unchanged:
{ "valid": true, "done": false, "status": "active", "now": "2",
"open_items": [2, 3, 4], "serves_plan": "<parent plan path or null>",
"problems": [], "plan": "<plan_path>" }
Never report a plan as done unless that file says done: true.
Constraints
The plan's own rules are in rules_path. This skill adds three of its own:
- Change only what the
changesays. An update is not a rewrite. - Create never overwrites a plan. With a plan already on disk,
createwrites nothing and returns the existing plan's paths. - The script decides done. Not you.