Skill Planning Format

---
name: skill-planning-format
description: Standards for Development Plans (PLAN.md) and Detailed Task Descriptions (TASK.md).
tier: 1
version: 1.5
---

# 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.

**Why.** The script reads the JSON block and never the plan's prose. Headings and field labels
follow the project's language (ARCHITECTURE §7.2, invariant L1).

### 2.2. Plan status
A develop workflow keeps the `status` of each task in the schedule block of `docs/PLAN.md`
(TASK 110 R8). `plan_gantt.py` draws `done` and `in-progress` bars from it.

1. A task turns `in-progress` when it starts and `done` when its review approves it. A task
   entered again after `done`, to be fixed, turns `in-progress`. A failure path leaves the status
   as it is.
2. A status edit changes the value. After each edit, run
   `python3 .agent/skills/mermaid-authoring-guidelines/scripts/plan_gantt.py docs/PLAN.md --write docs/PLAN.md`,
   then the same with `--check docs/PLAN.md` in place of `--write docs/PLAN.md`. A step that leaves
   the value as it was runs neither command.
3. The first edit of a task adds its `status` key. A block without `status` keys stays valid: a
   task without one is `not-started`.
4. The step skips:
   - a PLAN with no schedule anchor: no edit, no command;
   - a task with no entry in the block: no edit, no command. The step never adds an entry;
   - a project where `mermaid-authoring-guidelines` is not installed: the status is edited, and
     both commands are skipped, as §2.1 step 7 skips the chart.
5. `--write` is not on the allow-list of `.claude/settings.json`, so each run asks for approval.

## 3. Detailed Task Description Structure
For **each** task in the plan, you must create a separate file: `docs/tasks/task-{ID}-{SubID}-{slug}.md`.

- `{ID}` is the Task ID of `docs/TASK.md`, zero-padded to three digits.
- `{SubID}` matches `\d+[a-z]?`: digits, then at most one lowercase letter. A sub-task added
  after `05` is `05a`, the next one `05b`; `05` keeps its name.
- The file's first H1 is `# Task {ID}-{SubID}: {Task Name}`, e.g. `# Task 033-05a: Test database`.
  Older files write `# Task {ID}.{SubID}`; both forms are read.
- `skill-archive-task` tells a sub-task from a parent archive by this H1 first and by the
  filename second (TASK 114). A file with the H1 `# Task {ID}: …` is read as a parent archive;
  a file whose H1 names no task ID is classified by its filename.

> [!TIP]
> Use the template at `assets/templates/task_md_template.md`.

### Rationalization Table
| Agent Excuse | Reality / Counter-Argument |
| :--- | :--- |
| "I don't know the implementation details yet" | That is why you are in PLANNING mode: research until you know. |
| "Writing 5 files takes too long" | Fixing a disorganized codebase takes 10x longer. |

## 4. Result Structure Rules
1. **`docs/PLAN.md` file** — general development plan with task sequence and schedule block
   (§2.1).
2. **`docs/tasks/task-{ID}-{SubID}-{Slug}.md` files** — detailed descriptions of each task.
3. **CRITICAL:** Use only RELATIVE paths for file links (e.g., `[Link](docs/tasks/file.md)`), never absolute.

## 5. Resources
- `assets/templates/`: Standard markdown templates.
- `examples/`: Real-world planning examples.