@jaybeeuu/agent-cortex 2.1.0 → 2.3.0

package/skills/planning/create-task/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: create-task
-description: Create a task bead, classify it as AFK or HITL, and if AFK expand it into pipeline stage chores plus a HITL PR gate. Use when starting tracked work with implementation and review gates — "create a task for this", "track this end-to-end", or "get this into the ralph pipeline".
+description: Create a task or feature bead, classify each child as AFK or HITL, and expand AFK beads into pipeline stage chores plus a HITL PR gate. Use when starting tracked work with implementation and review gates — "create a task for this", "track this end-to-end", or "get this into the ralph pipeline".
 ---
 
 # Create Task
 
-Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (epic bead ID, optional — sets a `parent-child` dependency). The description must carry the task's required section — `## Acceptance Criteria` — which `--validate` enforces; fill it from agreed answers, not assumptions (see `bd-tool` → Required sections).
+Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (feature or epic bead ID, optional — sets ownership at create time). The description must carry the task's required section — `## Acceptance Criteria` — which `--validate` enforces; fill it from agreed answers, not assumptions (see `bd-tool` → Required sections).
 
 ## When to use
 
 - Starting new tracked work that must move through implementation, verification, and review gates — user phrases like "create a task for this", "track this work end-to-end", or "get this into the ralph pipeline".
+- Expanding an **existing** AFK task bead that has no `stage:*` chore children — run step 7 only (see _Expanding an existing bead_).
 - A caller (`prd-to-tasks`, `ralph-plan`) needs one task bead with the full child-chore structure.
+- A workstream of several deliverables needs a planning bead in front of them — the feature path in steps 5–6, then step 7 for each AFK impl child.
 
 ## When NOT to use
 
@@ -21,50 +23,84 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Workflow
 
-1. **Create the parent bead.** The description must contain the task's required section —
+1. **Pick the shape.** One deliverable an agent can finish in a session → a **task** bead (steps 2–4). A workstream of several deliverables that needs design settled before code → a **feature** bead carrying a planning bead and one impl task per deliverable (steps 5–6, then step 7 for each AFK impl child).
+
+   **Ownership is `--parent`; ordering is `bd dep add`.** `--parent` records who owns a bead at create time; a dependency records what must finish first. Never express one as the other.
+
+2. **Create the task bead.** The description must contain the task's required section —
    `## Acceptance Criteria` — or `--validate` rejects creation. Fill it from agreed answers, not
    assumptions (see `bd-tool` → Required sections).
 
    ```bash
-   bd create "<title>" --description "<description>" --priority <priority> --validate
+   bd create "<title>" --type task --description "<description>" --priority <priority> \
+     [--parent <feature-id> --no-inherit-labels] --validate
    bd lint <new-id>
    ```
 
-   If a `parent` epic was provided, record the dependency:
-
-   ```bash
-   bd dep add <new-id> <parent> --type parent-child
-   ```
+   Pass `--parent` when a container bead was supplied, and `--no-inherit-labels` with it: `bd` copies a parent's labels at create time, so a child of an `execution:hitl` feature would acquire `execution:hitl` beside the classifier's `execution:afk` — an unroutable bead. No `parent-child` dependency is needed; `--parent` already recorded ownership.
 
-2. **Classify deterministically.** Run the `classify-bead` classifier — it resolves an existing label, the legacy `## Type` field, and explicit heuristic signals without a model call, and applies the label itself when it resolves:
+3. **Classify deterministically.** Run the `classify-bead` classifier — it resolves an existing label, the legacy `## Type` field, and explicit heuristic signals without a model call, and applies the label itself when it resolves:
 
    ```bash
    # Run from the TARGET project's directory — bd resolves its beads DB from cwd.
    node <skill-scripts>/../../classify-bead/scripts/classify-bead.mjs <new-id>
    ```
 
-   - `"classification": "afk" | "hitl"` → the label is applied; branch on that class in step 3.
+   - `"classification": "afk" | "hitl"` → the label is applied; branch on that class in step 4.
    - `"escalate": true` → delegate to the `classify-bead` skill as a subagent via {{TOOL:task}}; it applies the rubric and tags the bead.
 
    `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded. Sibling skills sit alongside this skill's directory in every harness, so `../../classify-bead/scripts/` resolves to the classifier.
 
-3. **Branch on classification.**
+4. **Branch on classification.**
    - **HITL** — stop here. Report the bead ID and classification to the caller. Do not create pipeline chores: a human drives the work, so the chore tree does not apply.
-   - **AFK** — continue to step 4.
+   - **AFK** — continue to step 7.
 
-4. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
+5. **Feature path: create the container.** A feature is a container a person owns, so it is `execution:hitl`; its children state the class of their own work, so nothing aggregates upward.
+
+   ```bash
+   bd create "<Feature title>" --type feature --priority <priority> \
+     -l execution:hitl --description "<feature body>" --validate
+   ```
+
+6. **Feature path: planning bead, then impl children.** The planning bead is the design gate; each impl child delivers one slice and waits for it.
+
+   ```bash
+   # Design gate: human-owned, owned by the feature, blocking every impl child.
+   bd create "Plan: <Feature title>" --type task --priority <priority> \
+     -l execution:hitl --parent <feature-id> --no-inherit-labels \
+     --description "<cold-start plan>" --validate
+
+   # One impl child per deliverable: owned by the feature, labelled for its own work.
+   bd create "<Deliverable title>" --type task --priority <priority> \
+     -l execution:afk --parent <feature-id> --no-inherit-labels \
+     --description "<deliverable body>" --validate
+
+   # Readiness gate: the child leaves `bd ready` until planning closes.
+   bd dep add <impl-task-id> <planning-bead-id>
+   ```
+
+   The planning bead is cold-start ready — what and why, decisions already made, open questions and risks, references — and needs `## Acceptance Criteria`, which `--validate` requires for type `task` (template in `REFERENCE.md` → Hierarchy). A deliverable that genuinely needs a human — visual sign-off, credentials, hardware — is created `-l execution:hitl` and stops there.
+
+7. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
 
    ```bash
    # Run from the TARGET project's directory — bd resolves its beads DB from cwd;
    # the skill's own location or `pnpm --prefix <scripts>` would target the wrong tree.
-   <skill-scripts>/node_modules/.bin/tsx \
-     <skill-scripts>/create-chores.ts \
+   node <skill-scripts>/create-chores.mjs \
      --parent <parent-id> [--priority <priority>]
    ```
 
    `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded — it varies by harness and install location, so never hardcode one harness's path.
 
-5. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
+   On the feature path, run it **once per AFK impl child**, with `--parent <impl-task-id>` — never the feature ID: stage chores inherit their parent's labels, the script checks only that it was handed a parent ID (`REFERENCE.md` → PR gate bead), so an `execution:hitl` feature parent yields a chore tree no executor routes. A deliverable created `execution:hitl` in step 6 is not expanded.
+
+8. **Report.** Return the bead ID (or, on the feature path, the feature ID plus every planning and impl child ID), the classification of each expanded bead (`AFK`), and the created stage chore IDs from the script output (including `featurePrReview`) — one mapping per expanded impl child on the feature path.
+
+### Expanding an existing bead
+
+Steps 2–6 create beads; step 7 expands one. A bead that already exists but has no `stage:*` chore children — an AFK task filed before the pipeline existed, or one ralph found chore-less — is a supported entry point: run step 7's `create-chores.mjs --parent <existing-id> --priority <its-own-priority>` directly, then report the mapping. No create steps, no new description, no re-classification.
+
+**Never re-run `create-task` for an existing bead.** It creates a bead first and expands second, so the run leaves a **second parent** beside the original, which stays chore-less — the duplicate ralph's expansion guard exists to prevent. `create-chores.mjs` expands a bead that already exists; only step 2 creates a bead.
 
 ## Red Flags
 
@@ -73,7 +109,10 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 - **Spawning the `classify-bead` subagent when the classifier already resolved the bead.** The deterministic script is the short-circuit; a subagent is only for `escalate: true`.
 - **Skipping the classifier and classifying by hand.** The rubric is a subagent's job; a hand-rolled guess drifts from it.
 - **Expanding an HITL bead.** If classification is HITL, stop — creating a chore tree for human-driven work is wrong.
+- **Expanding an existing bead by re-running `create-task`.** That step creates a bead, so the original stays chore-less and gains a second parent beside it. Run `create-chores.mjs --parent <existing-id>` instead.
 - **Hardcoding `<skill-scripts>`.** The install path differs per harness (plugin cache, installed-plugins, dev checkout); resolve it at runtime.
+- **Creating a feature with no planning bead.** A feature that goes straight to impl children is a feature nobody designed. The planning bead keeps the children blocked until the design is confirmed.
+- **Expressing ownership as a dependency.** `bd dep add <child> <parent>` mixes hierarchy into the readiness gate; pass `--parent` at create time instead.
 
 ## Common Rationalizations
 
@@ -87,28 +126,33 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 - **The script owns the expansion contract.** Pipeline stages, titles, labels, dependency chains, and the PR gate are deterministic — a one-shot script keeps every chore identical to the contract and reproducible across runs.
 - **The PR gate is a hard human checkpoint.** Every AFK task ends with a `featurePrReview` task that blocks the final document stage, so automated work never merges without a human reviewing the branch.
+- **Each bead states its own execution class.** Containers are human-owned; the work inside them is AFK unless a deliverable genuinely needs a person. Nothing aggregates upward, so a label always answers "who does this?" for that bead.
 
-## Cross-skill references
+## See Also
 
-- `classify-bead` — deterministic classifier first, rubric subagent only on escalation (step 2).
+- [classify-bead](../classify-bead/SKILL.md) — step 3 defers to its deterministic classifier; the rubric subagent runs only on escalation.
+- [prd-to-tasks](../prd-to-tasks/SKILL.md) — calls this skill per vertical slice; load it when the input is a whole PRD.
 
 ## Examples
 
-Input: title `Add export API to invoices`, description `…`, priority `2`, parent `epic-456`. Output: the parent bead ID plus the script's JSON mapping stage IDs → chore bead IDs, with `featurePrReview` as the HITL PR gate:
+Input: title `Add export API to invoices`, description `…`, priority `2`, parent `feature-456`. Output: the bead ID plus the script's JSON mapping stage IDs → chore bead IDs, with `featurePrReview` as the HITL PR gate:
 
 ```json
 {"code": "abc123", "verify": "def456", "review": "ghi789", "document": "jkl012", "featurePrReview": "bd-mno345"}
 ```
 
+Feature path input: "several endpoints, a UI, and a migration". Output: `feature-456` (`execution:hitl`), `plan-457` ("Plan: …", `execution:hitl`, owned by the feature, blocking every child), and one `execution:afk` impl child per deliverable, each expanded into its own stage chores plus PR gate.
+
 The full bead-property contract (titles, labels, dependencies per chore and for the PR gate) is in `REFERENCE.md`.
 
 ## Verification checklist
 
-- [ ] Parent bead exists with the correct title, description, and priority.
-- [ ] Parent bead created with `--validate`, and `bd lint <id>` reports no missing sections.
-- [ ] `parent-child` dependency added when a parent epic was supplied.
-- [ ] `implementation-type` label present on the parent bead (`bd label list <id>`) — resolved by the classifier or, on escalation, the rubric subagent.
+- [ ] Bead created with `--validate`, and `bd lint <id>` reports no missing sections.
+- [ ] `--parent` used for ownership when a container was supplied, with `--no-inherit-labels` beside it.
+- [ ] `execution:afk` or `execution:hitl` label present on the bead (`bd label list <id>`) — resolved by the classifier or, on escalation, the rubric subagent.
 - [ ] HITL path: no pipeline chores created, caller told the classification. AFK path: script ran from the target project's cwd and its JSON contains every stage ID plus `featurePrReview`.
+- [ ] Feature path: the feature is `execution:hitl`, exactly one planning bead is owned by it and carries the cold-start contract, and every impl child is `execution:afk` and depends on the planning bead.
 - [ ] Chore titles/labels/dependencies match the contract (`[<parent-id>] <stage title>`, `stage:<id>`, `parent-child` to parent, `blocks` per `dependsOn`), verified against `REFERENCE.md`.
-- [ ] PR gate task exists and blocks the final document stage chore, carrying **exactly one** `implementation-type` label — `implementation-type:hitl` (never an inherited `implementation-type:afk` alongside it) — plus `lifecycle:feature-pr`.
-- [ ] Report returned the parent bead ID, classification, and all child bead IDs.
+- [ ] PR gate task exists and blocks the final document stage chore, carrying **exactly one** `execution` label — `execution:hitl` (never an inherited `execution:afk` alongside it) — plus `lifecycle:feature-pr`.
+- [ ] Report returned the bead ID, classification, and all child bead IDs.
+- [ ] Expansion-only run (existing bead): the create steps skipped, `create-chores.mjs` expanded that bead, and the tree still holds exactly one parent.

package/skills/planning/create-task/scripts/{create-chores.ts → create-chores.mjs}

@@ -1,3 +1,13 @@
+// @ts-check
+// Pre-create the pipeline stage chores for a task bead, plus the feature PR
+// review gate, from `pipeline.json`.
+//
+// The parent is an `execution:afk` bead. Stage chores inherit that label from it, so
+// create-chores does not classify: a parent that is hitl or unlabelled silently yields
+// a chore tree no executor routes. Check the parent's labels before invoking this.
+//
+// Zero dependencies: run with `node create-chores.mjs --parent <bead-id>`.
+
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
@@ -5,23 +15,30 @@ import { fileURLToPath } from 'node:url';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
-interface Stage {
-  id: string;
-  title: string;
-  description: string;
-  template: string;
-  dependsOn: string[];
-}
-
-interface Pipeline {
-  maxFixRounds: number;
-  stages: Stage[];
-}
+/**
+ * @typedef {object} Stage
+ * @property {string} id
+ * @property {string} title
+ * @property {string} description
+ * @property {string} template
+ * @property {string[]} dependsOn
+ */
+
+/**
+ * @typedef {object} Pipeline
+ * @property {number} maxFixRounds
+ * @property {Stage[]} stages
+ */
 
 // ─── Args ─────────────────────────────────────────────────────────────────────
 
-function parseArgs(args: string[]): { parentId: string; priority: string } {
-  let parentId: string | undefined;
+/**
+ * @param {string[]} args
+ * @returns {{ parentId: string, priority: string }}
+ */
+function parseArgs(args) {
+  /** @type {string | undefined} */
+  let parentId;
   let priority = '2';
 
   for (let i = 0; i < args.length; i++) {
@@ -30,7 +47,7 @@ function parseArgs(args: string[]): { parentId: string; priority: string } {
   }
 
   if (!parentId) {
-    console.error('Usage: create-chores.ts --parent <bead-id> [--priority <0-4>]');
+    console.error('Usage: create-chores.mjs --parent <bead-id> [--priority <0-4>]');
     process.exit(1);
   }
 
@@ -43,7 +60,11 @@ function parseArgs(args: string[]): { parentId: string; priority: string } {
 // Defaults to `bd`, resolved via PATH.
 const BD_PATH = process.env.BD_PATH || 'bd';
 
-function run(args: string[]): string {
+/**
+ * @param {string[]} args
+ * @returns {string}
+ */
+function run(args) {
   const cmd = args[0] === 'bd' ? [BD_PATH, ...args.slice(1)] : args;
   return execSync(cmd.join(' '), { encoding: 'utf-8' }).trim();
 }
@@ -56,9 +77,11 @@ const __dirname = dirname(__filename);
 const { parentId, priority } = parseArgs(process.argv.slice(2));
 
 const pipelinePath = resolve(__dirname, '..', 'pipeline.json');
-const pipeline: Pipeline = JSON.parse(readFileSync(pipelinePath, 'utf-8'));
+/** @type {Pipeline} */
+const pipeline = JSON.parse(readFileSync(pipelinePath, 'utf-8'));
 
-const stageToBeadId = new Map<string, string>();
+/** @type {Map<string, string>} */
+const stageToBeadId = new Map();
 
 for (const stage of pipeline.stages) {
   const title = `[${parentId}] ${stage.title}`;
@@ -107,17 +130,19 @@ const prGateBeadId = run([
   // section. Stage chores require no sections and deliberately omit the flag.
   '--validate',
   '--priority', priority,
-  '--labels', 'implementation-type:hitl,lifecycle:feature-pr',
+  '--labels', 'execution:hitl,lifecycle:feature-pr',
   '--parent', parentId,
-  // The gate declares its own labels; opt out of bd's create-time parent-label
-  // inheritance so its explicit :hitl is never joined by an inherited :afk.
-  // Stage chores deliberately keep inheriting :afk -- do not add this there.
+  // The gate declares its own execution class (it is human-owned review work), so opt
+  // out of bd's create-time parent-label inheritance and its explicit :hitl is never
+  // joined by an inherited :afk. Stage chores deliberately keep inheriting the parent's
+  // :afk -- do not add this flag there.
   '--no-inherit-labels',
   '--silent',
 ]);
 run(['bd', 'dep', 'add', prGateBeadId, documentStageBeadId, '--type', 'blocks']);
 
-const result: Record<string, string> = {
+/** @type {Record<string, string>} */
+const result = {
   ...Object.fromEntries(stageToBeadId),
   featurePrReview: prGateBeadId,
 };

package/skills/planning/flesh-out-idea/REFERENCE.md

@@ -0,0 +1,116 @@
+# flesh-out-idea reference
+
+Detail behind `SKILL.md`: the queries, the round-to-round field updates, and a full promotion
+transcript. Field names and section markers are the contract — see `record-idea`'s `FORMAT.md`
+for the capture-side mapping this builds on.
+
+## Queries
+
+| Question | Command |
+|---|---|
+| Which ideas can be worked now? | `bd ready -l kind:idea` |
+| Every idea, blocked and deferred included | `bd list -l kind:idea` |
+| One idea, fields and markers | `bd show <id> --json` |
+| Why is this idea blocked? | `bd show <id>` — its dependency list, with each blocker's status |
+
+`bd ready` applies blocker-aware semantics: an idea that depends on open work is omitted, while
+`bd list` still returns it. That difference is the readiness signal — there is no separate
+`ready:` label to maintain.
+
+To park an idea behind other work, express it as a dependency rather than an exclusion label:
+
+```bash
+bd dep add <idea-id> <blocker-id>    # "<idea> depends on <blocker>"
+```
+
+## Fields and verbs
+
+| Field | Verb | Use it for |
+|---|---|---|
+| `--description` | `bd update <id> -d …` | Problem, who benefits, proposed outcome — rewrite when an answer supersedes the text |
+| `--design` | `bd update <id> --design …` | How we might do it: mechanism, alternatives, deciding tradeoffs |
+| `--notes` | `bd update <id> --append-notes …` | Validity check, constraints, next validation step, provenance — append so rounds accumulate |
+| `--acceptance` | `bd update <id> --acceptance …` | Promotion criteria, restated once the interview settles what "ready" means |
+| `--priority` | `bd update <id> -p <P0-P4>` | Moves as the idea gets clearer or more urgent |
+
+Multiple `##` sections share one field; keep every marker, because that is how the next round
+finds the section to update.
+
+## Round-by-round updates
+
+Round 1 deepens the mechanism and records what is still open:
+
+```bash
+bd update proj-idea1 \
+  --design "## How we might do it
+
+Two candidates: a pre-commit hook, or a CI gate. The hook catches the mistake earlier; the CI
+gate cannot be bypassed locally. The deciding tradeoff is whether local friction is acceptable." \
+  --append-notes "## Validity check
+
+- Evidence we already have: two accidental token commits in the last six months.
+- Riskiest assumption: that a hook survives the team's current tooling.
+- What would invalidate this idea: a secret scanner already covering this path.
+
+## Next validation step
+
+Check whether the existing pre-commit config already runs a scanner." \
+  -p 3
+```
+
+Round 2 corrects the design in place and appends only what changed:
+
+```bash
+bd update proj-idea1 \
+  --design "## How we might do it
+
+CI gate (chosen): pre-commit config already runs an unrelated linter and the hook is bypassed
+with --no-verify, which the two incidents both used." \
+  --append-notes "## Next validation step
+
+Prototype the gate on one repository and confirm it fails on a seeded fake token."
+```
+
+## Promotion transcript
+
+Promotion is two moves: flip the idea bead into the epic node, then create execution children
+that point at it. The epic stays `execution:hitl` — a human owns the outcome even when every
+child is agent-routable.
+
+```bash
+# 1. The idea bead becomes the epic node.
+bd update proj-idea1 --add-label kind:epic --remove-label kind:idea -t epic
+
+# 2. Execution children hang off it by ownership.
+bd create "Add the token scanner to CI" --parent proj-idea1 \
+  -l execution:afk --no-inherit-labels -t task \
+  -d "Wire the scanner into the pipeline.
+
+## Acceptance Criteria
+- [ ] A seeded fake token fails the build." --validate
+
+# 3. Ordering is a dependency, not a label.
+bd create "Document the scanner baseline" --parent proj-idea1 \
+  -l execution:afk --no-inherit-labels -t task \
+  -d "Record the current findings so new alerts are attributable.
+
+## Acceptance Criteria
+- [ ] Baseline written and linked from the epic." --validate
+bd dep add proj-idea1.2 proj-idea1.1    # the doc waits for the scanner to land
+```
+
+- `--no-inherit-labels` is required on every child: without it a child inherits `kind:epic` and
+  stops reading as ordinary executable work.
+- `bd update <id> --remove-label` and `--add-label` are the label verbs; `bd label add/remove`
+  works too, and `bd tag <id> <label>` is the single-add shorthand.
+- A promoted epic satisfies lint through `--acceptance` (or a `## Success Criteria` section); if
+  the idea never got one, add it at promotion time.
+- `bd close` refuses to close a bead with open children, so the epic closes after its last child
+  — that ordering is the built-in completion rule, not a convention to remember.
+
+## When a planning bead belongs in the hierarchy
+
+If the children cannot be written down yet because the design is still unsettled, create one
+planning bead as a child of the epic (`execution:hitl`) and make every implementation child depend
+on it. The implementation children then surface as ready exactly when planning closes — no extra
+readiness label. Use `create-task` when the children also need pipeline stage chores.

package/skills/planning/flesh-out-idea/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: flesh-out-idea
+description: Deepen an idea bead through an interview, then update its fields or promote it to an epic with task children. Use when the user asks "flesh out an idea", "which ideas are ready", or "promote this idea".
+---
+
+# Flesh Out Idea
+
+Take an idea recorded as a `kind:idea` bead and deepen it until it is either ready to promote or
+explicitly still waiting on something. The bead is the record throughout: deepening rewrites its
+fields, promotion changes its labels and type in place.
+
+## When to use
+
+- The user wants to work on the idea backlog ("flesh out an idea", "which ideas are ready?").
+- An idea bead has stalled — its sections are thin, or its validity check has open questions.
+- An idea looks ready to become an epic and needs the promotion step.
+
+## When NOT to use
+
+- The idea is not yet recorded — run `record-idea` first; deepening an unrecorded idea loses it.
+- The idea is already an epic or a task bead — update it directly, or run `create-task` for
+  pipeline expansion.
+- The work is already understood and needs a requirements document — run `write-a-prd`.
+
+## Workflow
+
+1. **List candidates.** Query the blocker-aware ready view scoped to ideas:
+
+   ```bash
+   bd ready -l kind:idea
+   ```
+
+   `bd ready` respects dependencies, so an idea that `depends-on` in-flight work does not appear
+   until that work closes. Use `bd list -l kind:idea` when you need every idea including blocked
+   and deferred ones. If the user named a bead, skip straight to step 2.
+
+2. **Read the current record.** `bd show <id> --json` — note which `##` markers already carry
+   content and which are empty. Deepening fills gaps and challenges weak sections; it does not
+   restart the capture interview from scratch.
+
+3. **Interview at depth, one question at a time.** Push past the capture-level answer:
+   - **Why** — what problem, and what evidence says it is real? What breaks if it is never done?
+   - **Who** — who benefits, and how would they notice the improvement?
+   - **How** — what shape would the implementation take, what alternatives were considered, and
+     which tradeoffs decide between them?
+   - **When** — what has to be true or landed first? Which dependencies gate it?
+   - **Priority** — where does it now sit relative to current work (P0–P4)?
+
+   Sharpen the validity check while you go: the riskiest assumption, the signal that would
+   invalidate the idea, and the cheapest next step that would firm it up.
+
+4. **Write the answers back into the bead.** Preserve the `##` markers — they are how the next
+   round finds each section. Append notes rather than replacing them so interview rounds
+   accumulate, and correct description or design in place when an answer supersedes what is there:
+
+   ```bash
+   bd update <id> --design "<## How we might do it …>" \
+                  --append-notes "<## Validity check …>" \
+                  -p <P0-P4>
+   ```
+
+   Use `-d/--description` to rewrite the problem, beneficiaries, or outcome, and `--acceptance` to
+   restate the promotion criteria once the interview settles what "ready" means.
+
+5. **Decide readiness against the acceptance criteria.** Read `--acceptance` and check it against
+   what the interview established:
+   - **Met** → go to step 6, or stop if the user only wanted deepening.
+   - **Not met** → stop here. Record the blocking question and the next validation step in
+     `## Next validation step`, and leave the bead open. An idea promoted before its bar is met
+     produces children nobody can execute.
+
+6. **Promote (optional, user-confirmed).** Turn the idea bead into the epic node and hang
+   execution children off it:
+
+   ```bash
+   # the idea becomes the epic; it stays execution:hitl — a human owns the epic
+   bd update <id> --add-label kind:epic --remove-label kind:idea -t epic
+
+   # each executable child is agent-routable and inherits nothing from the epic
+   bd create "<child title>" --parent <id> -l execution:afk --no-inherit-labels -t task \
+     -d "<child description>" --validate
+   ```
+
+   `--parent` expresses ownership; `bd dep add <child> <blocker>` expresses ordering. Where a
+   feature needs planning before implementation, create a planning bead and make the
+   implementation children depend on it — the dependency, not a label, is the readiness gate. Run
+   `create-task` instead when the children need pipeline stage chores.
+
+7. **Report back.** Return the bead ID, what changed (sections rewritten, priority moved,
+   children created), and either the promotion result or the specific reason it is not ready.
+
+## Red Flags
+
+- Promoting on enthusiasm while the acceptance criteria are still unmet — the children inherit a
+  decision nobody made.
+- Replacing notes instead of appending — the interview trail is the provenance the next round reads.
+- Dropping the `##` markers while writing a field — the next flesh-out pass cannot find the section.
+- Restarting the capture interview instead of challenging the existing record.
+- Rewriting the idea as a markdown file — the bead is the record at every stage.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The idea is obviously good, skip to promotion" | Promotion is the moment the idea spends other work's time; the acceptance criteria are the cheapest gate it will ever have. |
+| "I'll remember the interview detail" | Only what lands in a field survives the session. Append it. |
+| "The description is close enough, I'll just add a note" | Superseded description text misleads the next reader; correct it in place and keep the note for provenance. |
+| "Adding children now saves a round trip" | Children created before the bar is met are the round trip — they get rewritten or closed. |
+
+## Philosophy / rationale
+
+- **An idea earns its children.** Promotion is cheap and reversal is not, so the interview
+  pressure-tests the idea until its own acceptance criteria say it can be executed. Everything
+  before that is one bead getting better.
+- **Two axes, one hierarchy.** Ownership is `--parent`; ordering is a dependency. Keeping them
+  separate means the readiness view answers "what can be worked now?" without a second label
+  scheme.
+
+## See Also
+
+- [record-idea](../record-idea/SKILL.md) — load to capture a new idea instead of deepening an existing one.
+- [create-task](../create-task/SKILL.md) — load when a promoted epic needs pipeline-stage chores.
+- [write-a-prd](../write-a-prd/SKILL.md) — load when the deepened idea is ready for requirements capture.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — load for label vocabulary and queries beyond the commands used here.
+
+## Examples
+
+Input: "which ideas are ready?" → `bd ready -l kind:idea` lists three; the user picks one whose
+acceptance criteria name a prototype result.
+
+Output: the interview settles the mechanism and the two tradeoffs that decide it; `--design` and
+`--notes` are updated with the markers preserved, priority moves from P4 to P2, and the bead is
+promoted (`kind:epic`, `-t epic`) with two `execution:afk` children created via `--parent`. See
+`REFERENCE.md` for the full worked promotion.
+
+## Verification checklist
+
+- [ ] The candidate list came from `bd ready -l kind:idea` (or the user named the bead).
+- [ ] The existing record was read before the interview started (`bd show <id> --json`).
+- [ ] Every `##` marker present before the update is still present after it.
+- [ ] Notes were appended, not replaced; superseded description or design text was corrected.
+- [ ] Priority reflects the interview (`bd show <id>` confirms it).
+- [ ] On promotion: label is `kind:epic`, type is `epic`, and `kind:idea` is gone.
+- [ ] On promotion: every child carries `execution:afk` and no inherited epic label.
+- [ ] On no promotion: `## Next validation step` records what would unblock it.
+- [ ] Report returned the bead ID, the changes, and the promotion outcome or blocker.

package/skills/planning/prd-to-tasks/REFERENCE.md

@@ -56,11 +56,60 @@ This vertical slice: end-to-end behaviour, not layer-by-layer implementation.
 - Blocked by #<task-id> (if any) — or "None — can start immediately"
 ```
 
-## Aggregate classification tags
+## Feature → planning → impl sequence
 
-After all tasks in an epic exist, tag the epic with the aggregate classification:
+When a slice is several deliverables, it gets a planning bead in front of them. Ownership is
+`--parent` at create time; ordering is `bd dep add`:
 
 ```bash
-bd tag <epic-id> implementation-type:hitl    # if any task is HITL
-bd tag <epic-id> implementation-type:afk     # if all tasks are AFK
-```
+# The slice, as a container.
+bd create "<Slice Title>" --type feature -l execution:hitl --description "<slice body>" --validate
+
+# The planning bead: human-owned, owned by the feature, blocking every impl child.
+bd create "Plan: <Slice Title>" --type task -l execution:hitl --parent <feature-id> \
+  --no-inherit-labels --description "<planning body>" --validate
+
+# One impl child per deliverable. Owned by the feature (not by the planning bead),
+# labelled for the work it does.
+bd create "<Deliverable title>" --type task -l execution:afk --parent <feature-id> \
+  --no-inherit-labels --description "<task body above>" --validate
+
+# Readiness gate: impl stays out of `bd ready` until the planning bead closes.
+bd dep add <impl-task-id> <planning-bead-id>
+```
+
+`--no-inherit-labels` is required on both children: `bd` copies a parent's labels at create
+time, so a child of a `execution:hitl` feature would silently acquire `execution:hitl`.
+
+### Planning bead body template
+
+Cold-start ready — another person picks it up with no chat history:
+
+```markdown
+## What and why
+
+The deliverable this feature produces and the problem it solves.
+
+## Decisions already made
+
+- Decision — rationale
+
+## Open questions / risks
+
+- Question — who answers it
+
+## References
+
+- Bead IDs, files, docs consulted
+
+## Acceptance Criteria
+
+- [ ] The user confirms planning is sufficient for this feature.
+```
+
+## No aggregate classification
+
+Do not tag a container with its children's execution class. A human owns an epic or feature, so
+it is `execution:hitl`; each impl task states `execution:afk` or `execution:hitl` for its own
+work. Aggregating upward labels a human-owned container as agent work and gives a single bead two
+answers to "who does this?".