projector-plan

name: projector-plan description: Turn a raw spec, brief, or feature request into an agile backlog (epics → stories → tasks) inside a Projector MCP project, ordered as a layer cake so an agent walking the backlog A→Z progressively extends a continuously-deployable system. Use when the user provides a spec/PRD/idea and asks you to "plan the project", "break this into epics and stories", "create the backlog", "set up the agile breakdown", or similar.

Instructions

You take a user's requirements and produce a Projector backlog: a Project → Epic → Story → Task tree, ordered as a layer cake where epics are the layers — epic 1 is the thinnest whole-product slice, each later epic one layer thicker. The tree read strictly top-to-bottom is the build order (lower ordinal = built first, at every level). That order is what the human curating the board reads top-to-bottom when they select the next layer of work for the projector-dev skill to execute — selecting an epic cascades to its stories and tasks, so "select the topmost not-yet-done layer" is the obvious move, and every layer ends with the product deployable and one step richer.

You are not writing code in this skill. You are normalising requirements into agile units, ordering them, and persisting the result with one backlog.plan call. The dev skill (projector-dev) is a separate skill that consumes what you produce: the human selects work on the board, and projector-dev assembles a one-shot prompt from that selection and runs it.

Hierarchy: Project → Epic → Story → Task — tasks are the leaf unit (there are no work-items in this server). Statuses: backlog → todo → in_progress → in_review → done | cancelled. New items default to backlog; stories and tasks that are ready for a human to select and hand to the dev skill should be created at todo so "ready" work is visually distinct from "not yet refined" work on the board.

THE GOVERNING RULE — THE BACKLOG IS A WATERFALL READ TOP-TO-BOTTOM.

The tree you produce must be buildable in strict pre-order depth-first sequence: read it top to bottom — epic 1 before epic 2, story 1.1 before 1.2, task 1.1.1 before 1.1.2 — and that linear order is the order the work gets done. Lower ordinal = built first, at every level, with no jumping. A human scanning the board top-to-bottom, or selecting an epic and handing it to projector-dev, is walking a waterfall: each item assumes everything above it already exists, and nothing below it.

This is the blend of agile and layer-cake architecture: epics ARE the layers. Epic 1 is the thinnest complete end-to-end slice of the whole product (a walking skeleton). Each later epic is one horizontal layer thicker — breadth, then enrichment, then polish — and every epic, when finished, leaves the product deployable and demoable, just richer than the layer before. Selecting and completing epics in order is a sequence of shippable increments.

CRITICAL — TITLES NEVER CONTAIN ORDINAL NUMBERS.

Position is derived from sibling order, not from the title. You must never put ordinals — or any other position markers — into the title field of an epic, story, or task. The title is just the name of the thing; baked-in numbers rot the instant any sibling is added, removed, or reordered.

Forbidden in any title, anywhere: leading numerals (1., 2), 3 -), dotted ordinals (1.1, 1.1.2), layer prefixes (Layer 0 — , L1: ), phase prefixes (Phase 1:, Stage 2 — ), step prefixes (Step 3., Part 4:), Roman numerals (I., II — ), or letter prefixes (A. , b) ). This applies even when you are about to render the preview that does show ordinals — the ordinals belong in the preview rendering, NOT in the title strings you persist.

Wrong: "1. Authentication", "1.1 — Sign-up flow", "Layer 1: Login", "Phase 2 — Billing", "Step 3. Wire form". Right: "Authentication", "Sign-up flow", "Login", "Billing", "Wire form to auth context".

When to use

Trigger when the user has handed you raw material that needs to become an agile plan:

A SPEC.md, PRD, design doc, or README excerpt
A multi-paragraph feature description in chat
A list of requirements / user goals
A vague-but-meaty request like "build me a CLI that does X, Y, Z"

Do not trigger for: pure code edits, single bug fixes, "what should I do next" questions about an existing backlog (that's projector-dev), or requests already broken down to story-level.

The workflow

Four steps, all in main. No sub-agents.

Understand the requirements and confirm the target project. Read the spec / brief / message. If something material is unclear (architecture choice, scope boundary, integration target), stop and ask before planning. A backlog built on a guessed assumption is worse than no backlog. Don't invent scope the user didn't ask for — flag suggestions in chat instead of slipping them into the tree. Before any other tool call, decide which project this plan attaches to: if the user hasn't named one, list existing projects and ask via AskUserQuestion — pick an existing project or create a new one. Never assume.
Normalise into epics, stories, tasks. See "Decomposition rules" below.
Order as a layer cake. See "Layer-cake ordering" below.
Show the ordinal-formatted preview, get explicit approval, then persist with one backlog.plan call, then add any hard dependencies the linear order can't express and attach feature:<name> tags to stories (mandatory for multi-feature products). See "Persisting" below. Never call backlog.plan before the user has approved the preview.

Decomposition rules

Epics are layers, ordered thinnest-first. Each epic is one horizontal slice of the whole product, and each leaves the product deployable when finished. Epic 1 is the thinnest end-to-end slice (the walking skeleton); each later epic is the next layer of thickness (breadth → enrichment → polish). Name an epic for the layer's outcome in product terms — "Walking skeleton", "Core breadth", "Reliability & error handling", "Reporting & polish" — not for a single feature ("Authentication", "Billing"). Per-feature work is distributed across the layers: the thin-happy-path of auth lives in the skeleton epic, its error states in the breadth epic, its polish in a later epic. Keep feature membership queryable with a feature:<name> tag, not by giving the feature its own epic.
Stories are the per-feature work at one layer. Within a layer epic, each story is a user- or operator-visible deliverable a junior dev could finish in 1–2 days — e.g. inside "Walking skeleton": "Log in (happy path)", "See empty dashboard". Order stories within the epic so earlier ones unblock later ones. Every story has acceptance_criteria. (There is no story points field — it was removed in favour of per-task size. Signal effort by setting size on each task: tiny | small | medium | large | huge.)
Tasks are imperative steps inside a story ("Add /api/login POST handler", "Wire the form to the auth context"), each one PR-shaped, ordered so each builds on the one above. Each task has acceptance_criteria too — one line is fine. Tasks are the leaf unit; this server has no sub-task / work-item layer, so decompose down to PR-shaped tasks and stop there.
Write description and acceptance_criteria as GitHub-flavoured Markdown. Both fields render as rich Markdown in the web UI — use headings, bullet/numbered lists, fenced code blocks, inline code, tables, links, and - [ ] task-list items where they aid clarity. Never write a wall of plain text where structure would help.
Descriptions stand alone. They are inlined verbatim into the dev skill's super-prompt downstream, so the dev agent must be able to act on a task without ever seeing the original spec or sibling stories. Inline the relevant context.
Descriptions are written, not generated. See "Description quality" below — every level has a specific job to do, and "list of child titles" is never the answer.
Capture intended scope exactly. If the user said "with rate limiting", there's a story or task for rate limiting. If they didn't, don't add it — flag it as a suggestion in chat.
acceptance_criteria is a single Markdown string. Encode it as a newline-separated Markdown checklist — "- [ ] User can …\n- [ ] API returns …" — one verifiable condition per line. It renders as a real task list in the UI. Not an array.
No ordinals in titles. Ever. Titles are the name of the thing. Position comes from sibling order, not the title — a number baked into the title rots the moment any sibling is added, removed, or reordered, and reads as noise everywhere the title is shown. This rule applies to every epic, story, and task, with no exceptions. Forbidden prefixes include but are not limited to: 1., 2), 3 -, 1.1, 1.1.2, Layer N — , L0:, Phase N:, Stage N — , Step N., Part N:, Roman numerals (I., II — ), letter prefixes (A. , b) ). Layer membership belongs in status, sibling order, and (optionally) a layer:N tag — never in the title string.

Description quality

Descriptions are the single most-read field on every backlog item — by the user reviewing the preview, by the dev skill running tasks, by anyone returning to the project a month later. They are not afterthoughts and not dumping grounds. Each level has a different job; write to that job. A description that just enumerates the titles of its children is a failure — the tree already shows that structure, and re-stating it adds zero information.

The minimum bar at every level: a reader who sees only this description (no spec, no parent, no children) should understand what the item is, why it exists, and what's in/out of scope.

Per-level requirements

Project description. The "what is this product and why does it exist" pitch. Use the labelled sections below as Markdown headings inside the single description string. Aim for ~3–8 short paragraphs total across the sections. Required sections (omit only if genuinely empty for this product):

## Overview — one short paragraph: the problem, the target user, the core value proposition. No bullet list of features.
## Users — who uses this and what they're trying to accomplish. Personas or roles, briefly.
## Core capabilities — the 3–6 capability areas in prose, not a copy of the epic titles. If a capability decomposes into multiple epics, that's fine — describe the capability, don't list the epics.
## System shape — the rough technical shape the spec called for: surfaces (CLI, web, API), key integrations, persistence, runtime. Skip implementation detail the spec didn't pin down.
## Constraints — non-functional requirements, performance targets, compliance, deadlines that came from the user.
## Out of scope — explicit non-goals from the spec. This section catches misunderstandings early.

Epic description. The "what does the product look like once this layer is done, and how is it thicker than the layer before". 2–4 short paragraphs, with these sections:

## Layer outcome — what the whole product can do/demo once this epic is complete, written from the user's perspective. State explicitly how it is deployable and what it adds over the previous layer (e.g. "after the skeleton layer a user can sign up, log in, and see an empty dashboard end-to-end; this layer adds the ability to actually create and view their first resource").
## In scope — which features get worked at this layer, in prose. Do NOT just list the story titles — describe the surface area in your own words. If you find yourself writing "Story 1 covers X, Story 2 covers Y", stop and rewrite as a paragraph.
## Deferred to a later layer — which depth of each feature is intentionally NOT in this layer and roughly where it lands (e.g. "auth error states and rate limiting are deferred to the breadth layer; password reset to enrichment"). This is what keeps the cake honest — every layer names what it is leaving thinner on purpose.
## Cross-cutting decisions (optional) — any choice every story under this epic inherits (e.g. "all endpoints added this layer require authenticated sessions", "all UI uses the existing Tailwind tokens").

Story description. Free-form prose, but disciplined:

Lead with one sentence stating the user-visible deliverable in user or operator terms.
Follow with one paragraph of context: where this fits in the broader flow, what earlier story it builds on, what the user can do after it ships that they couldn't before.
Keep verifiable conditions OUT of the description — they belong in acceptance_criteria.
Do NOT enumerate the task titles. The tasks are right there in the tree.

Task description. Imperative, concrete, and self-sufficient. This string is dropped verbatim into the dev agent's prompt downstream — a junior dev who has never read the spec must be able to start from it. Inline:

The exact change in scope (file paths, function names, endpoints, schema fields if known).
Any decision from the spec that constrains the implementation ("use Bun, not Node", "store as TEXT not JSON", "no external HTTP calls in this task").
The relationship to the parent story in one line, if non-obvious.

acceptance_criteria carries the pass/fail conditions — keep those out of the description.

Self-check before writing each description

Before you commit a description string, ask:

If I deleted the children below this item, would the description still tell me what this item is? If no, it's leaning on the tree structure — rewrite.
Does it repeat the title? Drop the repetition; the title is already shown.
Does it list the child titles in prose form ("This epic covers login, signup, and password reset")? Rewrite as the capability ("Account-holder identity: how a user proves who they are and recovers access when they can't").
Could a reader who has never seen the spec act on this? If no, inline more context.

Layer-cake ordering

The principle: each epic is one horizontal layer of the cake — a complete, working slice of the whole product, just thinner than the epic below it. Read the tree top-to-bottom (epic 1 → epic 2 → …) and that is the build order. Every epic, when finished, leaves the product deployable; each one is the previous product plus one layer of thickness. Epics are the layers — do not organise epics by feature.

The standard cake (epic ordinals = layer order):

Epic 1 — Walking skeleton (layers 0+1 fused). The thinnest possible end-to-end journey through the entire product, all corners cut except correctness, with foundation work folded in. Foundation (project init, dependencies, config, entry-point skeleton, test runner) is not its own epic and not its own layer — it is the first story (or first task of the first story) of the skeleton epic, sized just enough to stand the skeleton up. If the product is "auth + dashboard + billing", epic 1 is "app boots → user signs up → logs in → sees an empty dashboard". Verifiable by: bun test runs, the app boots, a user can walk the happy path manually.
Epic 2 — Core breadth. The next critical paths on the slice you already have: error states, the second user role, a second core resource, the create/edit/delete a feature needs beyond its happy path. Still not trying to be complete. Verifiable by: the product handles the common non-happy paths.
Epic 3 — Enrichment. Secondary features the user named, observability, optimisations, the deeper depth of each feature (password reset, reporting). Verifiable by: the named secondary capabilities work.
Epic 4+ — Polish. Edge cases, hardening, performance targets, nice-to-haves.

Small products may collapse this to two or three epics; large ones may split breadth or enrichment into several sequential layer epics. The invariant is constant: epic ordinal = layer order = build order, and every epic ends deployable.

How the dev skill picks up work

There is no server-side "next task" ranker. The human curates the next work by selecting an epic, story, or set of tasks on the board (selecting a parent cascades to its children); projector-dev reads that selection and assembles a one-shot prompt from it. So the order you establish here is not consumed by a ranking algorithm — it's what the human reads top-to-bottom when deciding what to select next.

That makes ordering and status human-facing signals, not machine knobs:

Board order (epic → story → task position) read top-to-bottom is the build order. Epic 1 is the whole-product walking skeleton; each later epic is one layer thicker. The obvious move is "select the topmost not-yet-done epic" — selecting an epic cascades to its stories and tasks, handing one complete deployable layer to the dev skill in one selection.
status marks readiness: todo = "refined and ready to select and hand to the dev skill"; backlog = "not yet ready". A human filtering for todo sees exactly the work that's safe to select now.
Sibling order is priority. There is no priority field — importance within a layer is expressed purely by position among siblings. The earlier a story/task sits under its parent, the sooner it's taken. Order the ready work within a layer most-important-first.

The dev skill, once given a selection, works the active, unblocked tasks in it in board order. So clean top-to-bottom order + accurate status = a backlog a human can drive by selecting one layer at a time, top to bottom.

Concrete ordering moves

Epic order = layer order. Epic 1 is the walking skeleton (whole-product thin slice, foundation folded into its first story). Each subsequent epic is the next layer of thickness: breadth, then enrichment, then polish. The order is fixed by the cake, not by feature.
Story/task order = priority. Order the children under each parent most-important-first; sibling position is the only signal of relative importance (there is no priority field). Within the skeleton, order so earlier stories unblock later ones (e.g. the foundation story, then "log in", then "see dashboard"). The position you set here is exactly the order the dev skill walks.
Initial status. Stamp every story in epic 1 (the walking skeleton) as status: "todo". Leave all later-layer epics' stories at the default backlog. Rationale: todo marks "refined and ready to select"; a human curating the board can filter to todo and select the topmost deployable layer with confidence, leaving thicker layers clearly flagged as not-yet-ready. The walking skeleton is what gets selected and handed to the dev skill first.
Dependencies. Top-to-bottom layer order already encodes "later layers build on earlier ones" — do not restate that with edges. Reserve dependency.add for the rare edge that the linear order can't express, e.g. two stories within the same layer where the later one in board order must wait on the earlier (use sibling order first; only add an edge if the constraint is hard and non-obvious), or a task that cannot run until another commits a schema migration. Don't add dependencies for ordering the linear walk already guarantees.

Persisting

Use one backlog.plan call. Either supply project_id (extending an existing project) or project: { name, description? } (inline create). The server runs the entire tree in a single transaction — partial trees never persist.

backlog.plan({
  project: { name, description },              // or project_id
  epics: [
    { title, description, status?, stories: [
      { title, description, acceptance_criteria, status?, tasks: [
        { title, description, acceptance_criteria, status?, size? }
      ]}
    ]}
  ]
})

These are the only fields backlog.plan accepts (verified against src/mcp/tools/backlog.ts). There is no work_items field (tasks are leaves) and no points field on stories — any extra key is silently dropped. size on a task is the enum tiny | small | medium | large | huge and renders as a badge in the UI.

Then, using ids from the plan response:

Loop over your dependency list (hard edges the linear layer order can't express) and call dependency.add per edge.
For any multi-feature product, loop over your stories and tag.attach a feature:<name> tag to each (mandatory — see "Tag by layer and feature"). This is the only thing that keeps a feature's work, now spread across layer epics, queryable.

Do not stage this as many small epic.create / story.create / task.create calls. The whole point of backlog.plan is atomicity and round-trip economy.

Before you call `backlog.plan`

Confirm the target project with the user. Never guess. If they explicitly named a project (or said "new one"), use that. Otherwise call project.list once and ask via AskUserQuestion:
- If one or more active projects exist, present them as options alongside "Create a new project". Wait for an explicit pick before continuing.
- If a near-identical project name to the brief already exists, surface it as the first option — don't silently create a duplicate.
- If the user implied they wanted to extend an existing project, follow "Extending an existing project" below; if they implied a fresh project, take the inline-create path.
This rule applies even when only one project happens to exist: a one-project workspace doesn't authorise you to attach to it without asking, because the user might be starting something unrelated.
Show the full backlog preview with ordinals (mandatory). This is not a summary — it is the entire tree, every epic / story / task, formatted so the user can read the structure and know exactly what is about to be persisted. See "Preview format" below.
Confirm with AskUserQuestion. Offer three options: Approve, Revise, Ask a question. Do not call backlog.plan until the user picks Approve. If they pick Revise or Ask a question, address the feedback and re-show the preview before asking again. Once written, deletion is the only undo.

Preview format

Render the preview as a fenced code block so monospace alignment survives. Every line is <ordinal> <title> plus optional inline metadata. Mirror the UI's hierarchical numbering rules exactly — the ordinals you show here must match what the UI computes from sibling order.

The ordinals on each preview line are rendered by you for the preview only — they are NOT part of the title field you will persist. The title strings stored via backlog.plan must be the bare names (Authentication, Sign-up flow, Wire form to auth context). The web UI computes the same ordinals at display time from sibling order, so re-baking them into the title would cause the UI to render them twice and would rot on any reorder.

Numbering rules — these ordinals are a preview-only structural aid you render so the user can see and approve the shape of the tree. (The live web UI prepends a flat ordinal in the Sidebar project list; it does not render dotted 1.1.1 numbers on the board, so these are for the approval preview, not a mirror of any on-screen numbering.)

Project is shown as a single top-level entry with an item number prefix (1. when only one project is being planned in this run). The project number is the root; everything below extends it.
Epics under that project are 1.1, 1.2, 1.3, …
Stories under an epic are 1.1.1, 1.1.2, 1.1.3, …
Tasks under a story are 1.1.1.1, 1.1.1.2, … (tasks are the leaf level — there is no deeper number).
Indent each level by two spaces so the tree shape reads at a glance.
Show [status] after stories. Epics carry no annotation — their layer importance is the position itself. Show a task's size in parens after tasks that set one: (medium).
After the tree, list any hard dependency edges on their own lines: dep: <ordinal> → <ordinal> (the arrow reads "depends on").

Example shape (illustrative — epics are layers, thinnest-first; not a template to copy verbatim):

1. <Project name>
  1.1 Walking skeleton
    1.1.1 <Foundation + boot story>                [todo]
      1.1.1.1 <Task title>                         (small)
      1.1.1.2 <Task title>                         (medium)
    1.1.2 <Thin happy-path story>                  [todo]
      1.1.2.1 <Task title>                         (large)
  1.2 Core breadth
    1.2.1 <Error-states / 2nd-resource story>      [backlog]
      1.2.1.1 <Task title>
  1.3 Enrichment
    1.3.1 <Secondary-feature story>                [backlog]
      1.3.1.1 <Task title>

dep: 1.3.1 → 1.2.1

If the backlog is large, the preview is still mandatory in full — do not abbreviate to "(… 12 more stories)". The user is approving every line you are about to write.

After it succeeds

Emit a tight summary and stop:

Created project <id> "<name>"
  <N> epics (layers), <M> stories, <K> tasks
  Epic 1  <skeleton title>   <id>
  Epic 2  <breadth title>    <id>
  Epic 3  <enrichment title> <id>
  Epic 4  <polish title>     <id>
  <D> hard dependencies

Do not start the dev skill yourself — that's the user's call (they invoke projector-dev separately).

Extending an existing project

When the user wants to add to an existing project rather than start fresh:

Inspect first. Call backlog.tree { project_id } once to see the current tree. Call dependency.list { item_id } for any item where new edges might collide.
Plan only the delta. Don't redecompose what's already there.
Layer assignment is relative to what exists. There is no new "skeleton" — the product already walks. New work is a new layer appended below the existing ones: either a new layer epic at the bottom of the tree, or new stories slotted into the appropriate existing layer epic (breadth work into the breadth epic, enrichment into enrichment). Never insert a new layer above completed ones — that breaks the top-to-bottom waterfall invariant.
Do not re-stamp existing items. Don't change the order, statuses, or dependencies of items you didn't create. The dev skill may already be mid-flight against them.
Initial-status policy still applies — but only to the new tree. If an addition is the immediate next layer the user is about to work, stamp its new stories todo. Otherwise leave them at default backlog.
Persist with backlog.plan { project_id, epics: [...] } (no project field — you're attaching, not creating).

Handoff to projector-dev

Every field you stamp here is a runtime input downstream. The dev skill assembles a one-shot super-prompt — written for a junior dev with no prior context — from the tasks the human selects. Plan accordingly:

description → inlined verbatim into the dev agent's super-prompt. Must stand alone: a junior dev who has never read the spec must be able to act on it.
acceptance_criteria (single newline-separated string) → used to verify "done" before flipping to in_review. Vague criteria → false positives.
status → marks readiness for selection (todo = ready to hand to the dev skill).
Sibling order → the only signal of relative importance within a parent (there is no priority field). Place the most important child first.
size (tiny | small | medium | large | huge) on a task → effort signal, shown as a badge in the UI.

If you want to encode something for the dev agent that doesn't fit any of these (e.g. "use Bun, not Node", "store as TEXT not JSON"), put it in the description of the relevant task — description and acceptance_criteria are the fields that reach the dev agent's prompt.

Tool reference

All tools are MCP tools on the projector server. Runtime tools (backlog.selected, story.update, task.update, delivery.add, etc.) are out of scope here — they belong to projector-dev.

Project selection

project.list () → existing projects. Inspect first if the user didn't specify or said "add to the existing one".
project.get ({ id }) → project record.
project.create is exposed but prefer creating the project inline as part of backlog.plan so the whole tree commits atomically.

Inspection (for extending an existing project)

backlog.tree ({ project_id? }) → full nested project snapshot.
dependency.list ({ item_type?, item_id? }) → existing dependency edges.

Bulk planning

backlog.plan ({ project_id?, project?, epics? }) → creates the entire nested tree in one transaction. Returns the full nested result with all generated ids.
There is no priority field — relative importance is expressed by sibling order (earlier = more important).
acceptance_criteria is a single string field, newline-separated bullets.

Dependencies

dependency.add ({ item_type, item_id, depends_on_type, depends_on_id }) — call after backlog.plan returns ids. Cycles and self-edges are rejected.

Tag by layer and feature

tag.attach ({ tag, item_type, item_id, create_if_missing: true }) — after planning:
- Layer epics already encode the layer, but attach layer:1, layer:2, … to the epics if you want it queryable as a tag too (optional).
- MANDATORY for any product with more than one feature: attach feature:<name> (e.g. feature:auth, feature:billing) to every story whose work belongs to that feature. Because epics are layers, each feature's work is deliberately spread across several layer epics — the feature: tag is the only thing that keeps "show me all the auth work" answerable via tag.list_items. This is non-negotiable: it is the mitigation that makes the layer-epic structure safe. Skipping it loses feature cohesion entirely.
- The only case you may skip the feature: tag is a genuinely single-feature backlog.

Forbidden in this skill

Do not call backlog.selected, selection.*, story.update, task.update, event.append, delivery.add, or artifact.add. Those are runtime concerns and pollute the planning context.

Rules

Capture intended scope exactly. No inflation, no deflation. Suggestions go in chat, not into the backlog.
Junior-dev readable. Every description must stand alone — assume the dev has not read the spec.
Epics are layers, ordered thinnest-first; the top-to-bottom read is the build order. Lower ordinal = built first at every level. Epic 1 is the whole-product walking skeleton; each later epic is one deployable layer thicker. If an epic's done state is "infrastructure exists but nothing runs end-to-end", re-cut it.
One backlog.plan call. Atomicity matters; a half-written backlog is worse than none.
Sibling order is priority; dependencies only for what the linear walk can't express. Don't add dependencies that layer order or sibling position already implies.
Stamp every story in epic 1 (the walking skeleton) todo. Later-layer epics stay at default backlog.
No ordinals in titles — strictly enforced. Titles never contain any position marker: leading numerals (1., 2)), dotted ordinals (1.1, 1.1.2), Layer N — , Phase N:, Stage N — , Step N., Part N:, Roman numerals (I., II.), or letter prefixes (A., B)). Position comes from sibling order, not the title — embedded numbers read as noise and rot on any reorder. Applies to epics, stories, and tasks without exception.
Confirm before persisting. Show the full ordinal-formatted backlog preview (project + every epic / story / task, with structural numbers like 1.1.1 rendered for the preview) plus dependency edges, then use AskUserQuestion with Approve / Revise / Ask a question. Do not call backlog.plan until the user picks Approve. Once written, deletion is the only undo.
Do not start the dev skill. This skill ends at "backlog created".
One project per skill invocation. If the user describes two unrelated products, plan them in two runs.

Anti-patterns

Do NOT plan a "setup epic" then a "features epic"

// WRONG
Epic 1 — Project setup        (everything boring, nothing runs end-to-end)
Epic 2 — All the features     (everything fun)

Classic horizontal-slab failure: at the end of Epic 1 you have a project that boots and does nothing demoable. The fix is not to abandon layer epics — it's to make every layer epic deployable. Epic 1 is the walking skeleton: foundation folded into its first story, plus the thinnest end-to-end happy path through the whole product. The test for any layer epic is "when this epic is done, can a user demo the product?" — a pure-infrastructure epic fails that test; a thin-but-complete slice passes it.

Do NOT make epics feature-shaped

// WRONG — epics organised by feature
Epic 1 — Authentication      (auth, all the way to polish)
Epic 2 — Billing             (billing, all the way to polish)
Epic 3 — Reporting

Feature epics break the waterfall read: finishing epic 1 gives you one polished feature standing alone, not a deployable product, and the thin end-to-end slice ends up scattered across the first story of every epic. Epics are layers, not features. Epic 1 is the whole-product walking skeleton (thin auth + thin dashboard + thin billing); later epics thicken every feature together. Keep feature membership queryable with a feature:<name> tag, not with a feature epic.

Do NOT mirror the spec's headings as epics

The spec is a description; the backlog is an execution plan in layer order. They have different shapes. A spec organised by feature ("Authentication", "Billing", "Reporting") must be re-cut into layers — the happy path of each feature goes into the skeleton epic, the error handling into breadth, the depth into enrichment. A spec section "Performance" might map to zero epics (it becomes acceptance criteria across many stories) or to a late polish layer. Match epic boundaries to layer/delivery boundaries, never to document structure.

Do NOT chain `epic.create` / `story.create` / `task.create` calls

// WRONG — N round-trips, no transactionality, partial trees on failure
project.create -> epic.create -> story.create -> task.create -> ...

Use backlog.plan once. The whole tree, one transaction.

Do NOT add dependencies for sibling ordering

// WRONG — story B is the next story under the same epic; sibling order handles this
dependency.add { item_type: "story", item_id: B, depends_on: A }

Within a parent, sibling order (position, then created_at) is the ordering. Dependencies are for cross-parent edges that ordering alone cannot express.

Do NOT prefix titles with ordinals, layers, phases, or steps

Position comes from sibling order, not the title. Any number, layer label, phase label, or step label you embed in the title is positional noise that rots the instant a sibling is added, removed, or reordered.

// WRONG — every one of these goes stale on reorder and reads as noise
Epic:  "1. Authentication"
Epic:  "Layer 1 — Authentication"
Epic:  "Phase 2: Billing"
Story: "1.1 — Sign-up flow"
Story: "Stage 3: Sign-up flow"
Task:  "1.1.2 — Wire form to auth context"
Task:  "Step 3. Wire form to auth context"
Task:  "Part B: Wire form to auth context"

// RIGHT — the title is just the name of the thing
Epic:  "Authentication"
Epic:  "Billing"
Story: "Sign-up flow"
Task:  "Wire form to auth context"

This applies even when you have just rendered an ordinal-prefixed preview line for the same item. The ordinal lives in the preview rendering only — never in the title field you pass to backlog.plan. If the user wants layer membership queryable, attach a layer:N tag — don't bake it into the title.

Do NOT write descriptions that just list the children

// WRONG — project description
"A task management app. Includes the following epics: Authentication, Projects,
Tasks, Notifications, Reporting, Admin."

// WRONG — epic description
"This epic covers the sign-up flow, the login flow, password reset, and session
management."

These add nothing the tree doesn't already show. Rewrite to describe the thing — what problem it solves, who uses it, what's in and out of scope, what shape the system takes — in coherent prose under the required section headings. The reader of a description should learn something they couldn't get by glancing at the tree.

Do NOT silently invent scope

If the user's spec doesn't mention auth, do not add an Auth epic on autopilot. Surface the gap and ask. The point of capturing intended scope exactly is that the user gets back the project they asked for.

Quality checklist

Before calling backlog.plan:

Does every requirement map to at least one story?
Does every story have acceptance criteria a junior dev can verify "done" against?
Do project / epic / story descriptions follow "Description quality"? Specifically: project has the required ## Overview / ## Users / ## Core capabilities / ## System shape / ## Constraints / ## Out of scope sections; each epic has ## Layer outcome / ## In scope / ## Deferred to a later layer; no description is a thinly-disguised list of child titles.
Are epics ordered as layers thinnest-first (epic 1 = whole-product walking skeleton, later epics one layer thicker), NOT feature-shaped? Is foundation work absorbed as the first story of epic 1 — not its own epic?
Are epic 1's stories stamped todo, later-layer epics at default backlog?
Does reading the tree strictly top-to-bottom give a valid waterfall build order where every epic, when finished, leaves the product deployable and one layer richer?
Are priorities stamped on every epic and story (critical skeleton → low polish)?
Are dependencies limited to hard constraints the linear top-to-bottom walk can't express (and not restating layer order or sibling order)?
Did I show the full ordinal-formatted preview (project as 1., epics 1.1, stories 1.1.1, tasks 1.1.1.1) and get explicit Approve via AskUserQuestion before the plan call?
Are all titles free of position prefixes (1., 1.1 — , Layer N — , Phase N:)?

After backlog.plan returns:

Did every dependency edge resolve to ids and persist via dependency.add?
For a multi-feature product, did every story get a feature:<name> tag via tag.attach?
Did I emit a tight summary and stop, without starting the dev skill?