skill-planning-format

Planning Output Format

Purpose: Defines the rigid structure for planning documents effectively.

1. Red Flags (Anti-Rationalization)

STOP if you are thinking:

• "I'll plan the details later" -> WRONG. "Later" means "Never". Breakdown must happen NOW.
• "This task is too simple for a file" -> WRONG. Every unit of work needs a task-*.md file for tracking.
• "I'll use my own format" -> WRONG. The Orchestrator relies on this specific structure.
• "I'll draw the plan chart by hand" -> WRONG. plan_gantt.py generates it from the schedule block (§2.1).

2. Development Plan Structure (docs/PLAN.md)

The Main Plan acts as the "Table of Contents" for the feature.

[!TIP] Use the template at assets/templates/plan_md_template.md.

2.1. Schedule block and plan chart

Every docs/PLAN.md carries the schedule block that the template shows. The plan chart is generated by plan_gantt.py of mermaid-authoring-guidelines, never written by hand.

1. Directly under <!-- contract:schedule -->, write one json fence of schema plan-schedule/v1. It lists every task of the sequence once, with the id of its record. Each entry holds title, stage, est in integer hours, deps as a list of ids, and "status": "not-started". The develop workflows change the status (§2.2). The script refuses an entry that breaks one of these rules:
   • id matches ^[A-Za-z0-9][A-Za-z0-9._-]*$. It is not a gantt keyword such as section, it does not start with gantt, topAxis or inclusiveEndDates followed by . or -, and it does not start with a date. Keywords match in any letter case. Two ids collide when they are equal with each ., - and _ read as x, such as 1.1, 1-1 and 1x1.
   • est is a whole number, at least 1.
   • title and stage each keep a visible character once # and zero-width characters are dropped. Two stages whose section titles come out the same, such as Ops# and Ops, are refused; rename one.
   • The bar label is <id> <title>. The label limit of mermaid-authoring-guidelines counts both (references/gantt.md §1.3). A longer label is shortened, with a warning. The id stays whole.
2. For every plan, run python3 .agent/skills/mermaid-authoring-guidelines/scripts/plan_gantt.py docs/PLAN.md --write docs/PLAN.md. With 8 or more tasks, the chart lands between <!-- generated:plan-gantt-start --> and <!-- generated:plan-gantt-end -->. Postcondition: the same command with --check in place of --write exits 0.
3. With fewer than 8 tasks, add no chart. The command of step 2 still validates the block, and both markers stay, with nothing between them.
4. Exit 1 names the defect, such as a cycle, an unknown dependency, a duplicate id or a non-integer estimate. Fix the block and repeat step 2. Each line that starts with plan_gantt: warning: needs an answer, although the exit code is 0. Over the soft bar budget, or with a bar too narrow to read, split the chart (step 6) or attach a render check. A shortened label or section title: shorten the title or the stage name. A label that shows no title: shorten the id.
5. After any later change to the block, repeat step 2.
6. Over the plan chart budget of mermaid-authoring-guidelines (its references/gantt.md states it), generate one chart per stage group. Add --stages A,B --stages C to the --write of step 2, one option per chart, and name every stage in exactly one group. The script stores the groups in the first line of the region, <!-- plan-gantt-groups: ... -->, so the commands of step 2 keep the split as written. A later --stages replaces the groups; one group that names every stage returns the plan to one chart.
7. Without .agent/skills/mermaid-authoring-guidelines/ in the project, the command of step 2 cannot run. Add no chart at any plan size. Report the absent skill at any plan size, in the figures field of the planner's return JSON.