@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/skills/planning/classify-bead/SKILL.md

@@ -5,63 +5,87 @@ description: Classify a bead as AFK or HITL and apply the implementation-type la
 
 # Classify Bead
 
-Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as a label.
+Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as an `implementation-type` label.
 
 ## When to use
 
-- When picking up a bead that is missing the `implementation-type` label.
-- Immediately after creating a new bead, before claiming or scheduling it.
-- Any time you are unsure of a bead's classification.
+- A bead is missing its `implementation-type` label and you are about to pick it up.
+- A skill has just created a new bead and needs it classified before claiming or scheduling.
+- You are unsure of a bead's classification and want to resolve it deterministically.
+
+## When NOT to use
+
+- The bead already carries an `implementation-type` label — check `bd label list <id>` before invoking, and never re-classify a labelled bead.
+- You are creating a new task — `create-task` classifies internally; do not spawn this skill separately.
+- The work item is not a bead (e.g. a Jira ticket or plain code task) — use `write-a-ticket` or start the work directly.
 
 ## Invocation
 
-**Always run this skill as a subagent** (background `general-purpose` agent, `model: haiku`) to avoid loading bead content into the calling agent's context. Classification is a rubric lookup, not code generation, so the smaller/cheaper model is sufficient. Pass the bead ID and the `bd prime` output. The subagent runs the procedure below and reports back the classification and the `bd tag` command it applied.
+Run this skill as a background subagent via {{TOOL:task}} so bead content never loads into the calling agent's context. Classification is a rubric lookup, not code generation — a small, cheap model is sufficient. Pass the bead ID and the `bd prime` output; the subagent runs the workflow below and reports back the classification plus the `bd tag` command it applied.
+
+Only run inline when no task-spawning capability exists in the current environment.
+
+**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that already exists wastes a full agent call.
+
+## Workflow
+
+1. **Check for an existing label.**
 
-Only run inline (without a subagent) if no task-spawning capability is available in the current environment.
+   ```bash
+   bd label list <id>
+   ```
 
-**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that's already there wastes a full agent call.
+   - `implementation-type:afk` present → classification is **AFK**. Stop here.
+   - `implementation-type:hitl` present → classification is **HITL**. Stop here.
 
-## Procedure
+2. **Check the `## Type` field (back-compat).**
 
-### 1. Check for an existing label
+   ```bash
+   bd show <id>
+   ```
 
-```bash
-bd label list <id>
-```
+   Locate the `## Type` section in the bead body. `HITL` or `AFK` (case-insensitive) determines the classification; continue to step 4. This field predates the label system, so treat it as authoritative when present.
 
-- If `implementation-type:afk` is present → classification is **AFK**. Stop here.
-- If `implementation-type:hitl` is present → classification is **HITL**. Stop here.
+3. **Classify from first principles** — only when neither the label nor the `## Type` field is present. Read the full bead body and apply the rubric:
 
-### 2. Check the `## Type` field (back-compat)
+   **HITL** — the bead requires a human if at least one of the following is true:
+   - The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
+   - A manual action only a human can perform is required (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
+   - A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
 
-```bash
-bd show <id>
-```
+   **AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
 
-Locate the `## Type` section in the bead body.
+4. **Apply the label.**
 
-- If the value is `HITL` (case-insensitive) → classification is **HITL**. Proceed to step 4.
-- If the value is `AFK` (case-insensitive) → classification is **AFK**. Proceed to step 4.
+   ```bash
+   bd tag <id> implementation-type:afk    # or implementation-type:hitl
+   ```
 
-### 3. Classify from first principles
+5. **Return the classification.** Report `AFK` or `HITL` so the calling skill or agent can act on it.
 
-If neither the label nor the `## Type` field is present, read the full bead body and apply this rubric:
+## Red Flags
 
-**HITL** — the bead requires a human if at least one of the following is true:
-- The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
-- The work requires a manual action only a human can perform (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
-- A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
+- Classifying a bead without the caller-side `bd label list` check — you either overwrite a recorded decision or waste an agent spawn re-reading a label that already exists.
+- Defaulting to HITL for a complex task whose acceptance criteria are machine-checkable — complexity alone is not a criterion.
+- Choosing a class without reading the bead body when neither the label nor `## Type` is present.
 
-**AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
+## Common Rationalizations
 
-Prefer AFK. Do not classify as HITL just because the task is complex — only when the agent genuinely cannot complete or verify it without human involvement.
+| Rationalization | Rebuttal |
+|---|---|
+| "This task is complex, so it must be HITL" | Complexity is not a criterion. HITL applies only when a human is genuinely required to complete or verify. |
+| "I'll mark it HITL to be safe" | HITL consumes scarce human attention. Prefer AFK — ralph's review gates still catch agent mistakes. |
+| "The label is probably already there, I'll skip the check" | One `bd label list` command settles it. Skipping it either overwrites a decision or spawns an agent to re-read a label. |
 
-### 4. Apply the label
+## Philosophy / rationale
 
-```bash
-bd tag <id> implementation-type:afk    # or implementation-type:hitl
-```
+- Classification gates automation against human attention: AFK beads feed ralph's autonomous pipeline, HITL beads are routed to a person. We prefer AFK because human time is the scarce resource, and later review gates still catch agent mistakes — escalate only when completion or verification genuinely requires a human.
+- The rubric is deterministic, so this skill is a lookup rather than deep reasoning — which is why a cheap subagent suffices and the step 1 early exit exists.
 
-### 5. Return the classification
+## Verification checklist
 
-Report back `AFK` or `HITL` so the calling skill or agent can act on it.
+- [ ] `bd label list <id>` was checked before any other step.
+- [ ] Classification followed the precedence order: existing label → `## Type` → first-principles rubric.
+- [ ] The full bead body was read before classifying from first principles (step 3).
+- [ ] `bd tag <id> implementation-type:<afk|hitl>` was applied.
+- [ ] The calling skill or agent received the classification in the report.

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

@@ -0,0 +1,40 @@
+# Create Task — Reference
+
+Detail behind `skills/planning/create-task/SKILL.md`. The script (`scripts/create-chores.ts`) is the source of truth for this contract; this document mirrors it for verification.
+
+## Script invocation
+
+```
+tsx create-chores.ts --parent <bead-id> [--priority <0-4>]
+```
+
+- Reads `<skill>/pipeline.json`; creates each stage chore via `bd create` and wires dependencies via `bd dep add`.
+- Prints a JSON object mapping each stage ID to its chore bead ID, plus `featurePrReview` for the PR gate.
+
+## Stage chore beads
+
+One per stage in `pipeline.json` (currently `code`, `verify`, `review`, `document`):
+
+- **Type**: `chore`
+- **Title**: `[<parent-id>] <stage title>` (e.g. `[abc-123] Code`)
+- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`)
+- **Dependencies**: `parent-child` to the parent bead; `blocks` between stages per each stage's `dependsOn` (the script requires `dependsOn` targets to appear earlier in `pipeline.json`).
+
+## PR gate bead (`featurePrReview`)
+
+- **Type**: `task`
+- **Title**: `[<parent-id>] PR Review and Merge`
+- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr`
+- **Dependencies**: `parent-child` to the parent bead; `blocks` on the final document stage chore (`document`, falling back to the last stage in `pipeline.json`).
+- **Purpose**: human review of the agent PR (agent branch → feature branch) before the feature closes.
+
+## Current pipeline stages
+
+| id | title | dependsOn |
+|---|---|---|
+| code | Code | — |
+| verify | Verify | code |
+| review | Review | verify |
+| document | Document | review |
+
+`maxFixRounds: 4` — the maximum fix-retry rounds allowed for a stage's verify loop before the PR gate. Adjust stages only in `pipeline.json`; the script and templates follow it.

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

@@ -1,96 +1,100 @@
 ---
 name: create-task
-description: Create a bead, classify it, and if AFK expand it into pipeline stage child beads plus a HITL PR gate task. Use when creating a new task that should be tracked and moved through implementation and human review gates.
+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".
 ---
 
 # Create Task
 
-Create a bead, classify it via `classify-bead`, and — if AFK — expand it into child chore beads for each pipeline stage plus a child HITL PR gate task bead.
+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).
 
-## Inputs
+## When to use
 
-| Parameter   | Required | Description                          |
-|-------------|----------|--------------------------------------|
-| title       | yes      | Task title                           |
-| description | yes      | Task description                     |
-| priority    | no       | 0–3 (default 2)                      |
-| parent      | no       | Parent bead ID for `parent-child` dep |
+- 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".
+- A caller (`prd-to-tasks`, `ralph-plan`) needs one task bead with the full child-chore structure.
 
-## Procedure
+## When NOT to use
 
-### 1. Create the bead
+- Work that is only a raw idea, not ready to build — use `record-idea`.
+- A feature that needs specification first — use `write-a-prd`, or `prd-to-tasks` to break an approved PRD into epics and tasks (`prd-to-tasks` calls this skill per task itself).
+- A ticket for an external issue tracker aimed at human engineers — use `write-a-ticket`.
+- A refactor that needs an incremental migration plan — use `request-refactor-plan`.
 
-```bash
-bd create "<title>" --description "<description>" --priority <priority>
-```
+## Workflow
 
-If a `parent` was provided, add a `parent-child` dependency:
+1. **Create the parent bead.**
 
-```bash
-bd dep add <new-id> <parent> --type parent-child
-```
+   ```bash
+   bd create "<title>" --description "<description>" --priority <priority>
+   ```
 
-Record the new bead ID.
+   If a `parent` epic was provided, record the dependency:
 
-### 2. Classify the bead
+   ```bash
+   bd dep add <new-id> <parent> --type parent-child
+   ```
 
-Invoke the `classify-bead` skill on the new bead (as a subagent per that skill's invocation instructions). It returns `AFK` or `HITL`.
+2. **Check for an existing classification label.** Run `bd label list <id>`. If `implementation-type` is already present, skip step 3 — re-classifying a labelled bead wastes a subagent call.
 
-### 3. Branch on classification
+3. **Classify the bead.** Delegate to the `classify-bead` skill as a subagent via {{TOOL:task}} — do not classify inline. It returns `AFK` or `HITL` and applies the `implementation-type` label.
 
-**If HITL**: stop. Report the bead ID and classification to the caller. No further action.
+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 5.
 
-**If AFK**: continue to step 4.
+5. **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:
 
-### 4. Expand into pipeline stage chores
+   ```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 \
+     --parent <parent-id> [--priority <priority>]
+   ```
 
-Run the `create-chores` script, which reads `pipeline.json` and deterministically creates all
-stage chores in one shot. They are plain (non-ephemeral) chores — `bd ready` must surface
-them without `--include-ephemeral` for ralph to discover them:
+   `<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.
 
-```bash
-# Run from the TARGET project's directory (cwd must be inside the target's
-# .beads tree) — bd resolves its beads DB from cwd, not from the skill's
-# location. Do NOT use `pnpm --prefix <scripts> exec`, which changes cwd to
-# the scripts dir and makes bd pick the skill repo's own .beads instead of
-# the target project's.
-<skill-scripts>/node_modules/.bin/tsx \
-  <skill-scripts>/create-chores.ts \
-  --parent <parent-id> \
-  --priority <priority>
-```
+6. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
+
+## Red Flags
+
+- **Running the script from the wrong directory.** Chores land in whatever `.beads` tree `bd` resolves from cwd — the target project's root is the only safe cwd.
+- **Classifying inline.** The `classify-bead` rubric is a subagent's job (with a label short-circuit); inlining yours means re-reading bead content and drifting from the rubric.
+- **Expanding an HITL bead.** If classification is HITL, stop — creating a chore tree for human-driven work is wrong.
+- **Hardcoding `<skill-scripts>`.** The install path differs per harness (plugin cache, installed-plugins, dev checkout); resolve it at runtime.
+
+## Common Rationalizations
 
-Where `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory —
-resolve it from wherever this skill was actually loaded from (it varies by harness and
-install location; e.g. a Claude Code plugin cache dir vs. a Copilot
-`~/.copilot/installed-plugins/...` install vs. a local dev checkout). Do not hardcode
-one harness's path.
+| Rationalization | Rebuttal |
+|---|---|
+| "I know this task is AFK — I'll skip the classify-bead call" | Classification is a rubric check against the full bead body; assumptions masked by familiarity cause mislabelled work to hit the wrong queue. |
+| "I'll create the chores by hand instead of running the script" | The script is the single source of truth for titles, labels, dep chains, and the PR gate. Hand-created chores drift silently. |
+| "The pipeline is overkill for this small task" | If the work is worth tracking at all, the stage chore tree is what lets ralph execute and gate it. Not ready for that? Use `record-idea`. |
 
-The script outputs a JSON object mapping stage IDs to chore bead IDs, plus a HITL PR gate task bead ID, e.g.:
+## Philosophy / rationale
+
+- **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.
+
+## Cross-skill references
+
+- `classify-bead` — classify the new bead via subagent (step 3).
+
+## 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:
 
 ```json
-{
-  "code": "abc123",
-  "verify": "def456",
-  "review": "ghi789",
-  "document": "jkl012",
-  "featurePrReview": "bd-mno345"
-}
+{"code": "abc123", "verify": "def456", "review": "ghi789", "document": "jkl012", "featurePrReview": "bd-mno345"}
 ```
 
-Each stage chore is created with:
-- **type**: `chore`
-- **Title pattern**: `[<parent-id>] <stage title>` (e.g. `[abc-123] Code`)
-- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`)
-- **Dependencies**: `parent-child` to parent bead; `blocks` between stages per `dependsOn`
-
-The PR gate bead is created with:
-- **type**: `task`
-- **Title**: `[<parent-id>] PR Review and Merge`
-- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr`
-- **Dependencies**: `parent-child` to parent bead; `blocks` on the final document stage chore
- - **Purpose**: human review of the agent PR (agent-branch → feature branch)
+The full bead-property contract (titles, labels, dependencies per chore and for the PR gate) is in `REFERENCE.md`.
 
-### 5. Report
+## Verification checklist
 
-Return the parent bead ID, classification (`AFK`), and the list of created child bead IDs (including `featurePrReview`).
+- [ ] Parent bead exists with the correct title, description, and priority.
+- [ ] `parent-child` dependency added when a parent epic was supplied.
+- [ ] `implementation-type` label present on the parent bead (`bd label list <id>`).
+- [ ] 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`.
+- [ ] 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 with `implementation-type:hitl` + `lifecycle:feature-pr` labels and blocks the final document stage chore.
+- [ ] Report returned the parent bead ID, classification, and all child bead IDs.

package/skills/planning/create-task/scripts/create-chores.ts

@@ -39,8 +39,13 @@ function parseArgs(args: string[]): { parentId: string; priority: string } {
 
 // ─── Exec ─────────────────────────────────────────────────────────────────────
 
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+// Defaults to `bd`, resolved via PATH.
+const BD_PATH = process.env.BD_PATH || 'bd';
+
 function run(args: string[]): string {
-  return execSync(args.join(' '), { encoding: 'utf-8' }).trim();
+  const cmd = args[0] === 'bd' ? [BD_PATH, ...args.slice(1)] : args;
+  return execSync(cmd.join(' '), { encoding: 'utf-8' }).trim();
 }
 
 // ─── Main ─────────────────────────────────────────────────────────────────────

package/skills/planning/create-task/scripts/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/skills/planning/create-task/scripts/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/skills/planning/create-task/scripts/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

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

@@ -0,0 +1,66 @@
+# PRD to Tasks — Reference
+
+Body templates used in the Phase 3 and Phase 4 workflow steps of `SKILL.md`.
+
+## Epic body template
+
+Passed as the `--description` when creating an epic bead:
+
+```bash
+bd create "<Phase Title>" --type epic --description "<epic body below>"
+```
+
+```markdown
+## Source
+
+PRD: <brief reference>
+
+## Summary
+
+A concise description of this phase. Scope and goal, not implementation details.
+
+## What to build
+
+End-to-end behaviour for this phase. What a demo would show.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- Blocked by #<epic-id> (if any) — or "None — can start immediately"
+```
+
+## Task body template
+
+Passed as the `description` to `create-task` for each task bead:
+
+```markdown
+## Epic
+
+#<epic-id> — <Epic Title>
+
+## What to build
+
+This vertical slice: end-to-end behaviour, not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- Blocked by #<task-id> (if any) — or "None — can start immediately"
+```
+
+## Aggregate classification tags
+
+After all tasks in an epic exist, tag the epic with the aggregate classification:
+
+```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
+```