@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

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

@@ -63,10 +63,12 @@ execute. The epic bead is the source of truth — no intermediate plan file.
    `## Success Criteria`; `--validate` rejects it otherwise:
 
    ```bash
-   bd create "<Phase Title>" --type epic --description "<epic body from REFERENCE.md>" --validate
+   bd create "<Phase Title>" --type epic -l execution:hitl --description "<epic body from REFERENCE.md>" --validate
    bd lint <epic-id>
    ```
 
+   An epic is a container and a person decides when it closes, so it is `execution:hitl` in its own right — not because of what its children are.
+
 8. Tag each epic with a priority (`p3` default; adjust for p4/p5), and `workflow:ralph`
    when running under ralph-plan or ralph.
 
@@ -76,13 +78,13 @@ execute. The epic bead is the source of truth — no intermediate plan file.
    invoke `create-task` for each — it handles AFK/HITL classification and pipeline
    expansion. Pass the task body template from REFERENCE.md, the priority, and the parent
    epic ID.
-10. Once all tasks exist, tag the epic with the aggregate classification: HITL if any task
-    is HITL, otherwise AFK.
+10. Do not aggregate a child's classification onto its epic. Every bead states its own execution class, and a container's class is `execution:hitl` because a human owns it — copying `execution:afk` upward because the children happen to be AFK labels a human-owned container as agent work.
+11. When a slice is really several deliverables, use the feature shape from `create-task` steps 5–6 instead of fattening one task: a feature bead owns a planning bead that blocks one impl child per deliverable (`REFERENCE.md` → Feature → planning → impl sequence). The planning bead is where the design the PRD left open gets settled, so `bd ready` surfaces the impl children only once planning closes.
 
 ### Phase 5 — Report
 
-11. Present the full bead tree: each epic with its tasks, classifications, and IDs.
-12. If invoked by `ralph-plan`, signal completion so it can proceed; if invoked directly,
+12. Present the full bead tree: each epic with its tasks, classifications, and IDs.
+13. If invoked by `ralph-plan`, signal completion so it can proceed; if invoked directly,
     summarise the tree and confirm the user is happy before finishing.
 
 ## Red Flags
@@ -105,13 +107,11 @@ execute. The epic bead is the source of truth — no intermediate plan file.
 | "This phase is too small for acceptance criteria" | If it is too small for criteria, merge it with another phase. Every deliverable needs a definition of done. |
 | "I know the tasks — no need to check with the user" | The phase breakdown still needs approval, and the full tree is presented in Phase 5. |
 
-## Cross-skill references
+## See Also
 
-- **`create-task`** — invoked for every task bead; handles classification and pipeline
-  expansion.
-- **`write-a-prd`** — use first when the feature is not yet specified.
-- **`style-comms`** — invoke before Phase 2 when you need help writing clear phase
-  descriptions.
+- [create-task](../create-task/SKILL.md) — invoked for every task bead; owns classification and pipeline expansion.
+- [write-a-prd](../write-a-prd/SKILL.md) — load first when the feature is not yet specified.
+- [style-comms](../../style/style-comms/SKILL.md) — load before the phase-description step when the writing reads loosely.
 
 ## Examples
 
@@ -122,8 +122,11 @@ Output: a dependency-ordered tree of epic and task beads:
 Epic: "Phase 1 — Auth" (#123) — HITL
   ├── Task 1 (#124) — AFK
   ├── Task 2 (#125) — HITL (visual review)
-  └── Task 3 (#126) — AFK
-Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
+  ├── Task 3 (#126) — AFK
+  └── Feature 4 (#128) — HITL
+        ├── Plan: Feature 4 (#129) — HITL, blocks #130
+        └── Task 5 (#130) — AFK
+Epic: "Phase 2 — Dashboard" (#127) — HITL (blocked by #123)
 ```
 
 ## Phase-gate checklists
@@ -132,8 +135,8 @@ Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
 - [ ] Phase 2 complete: phases drafted and approved by the user.
 - [ ] Phase 3 complete: epics created in dependency order and tagged (priority, plus
       `workflow:ralph` under ralph-plan/ralph), and `bd lint` clean.
-- [ ] Phase 4 complete: tasks created via `create-task`; epics carry the aggregate
-      `implementation-type` tag.
+- [ ] Phase 4 complete: tasks created via `create-task`; no execution label aggregated from
+      children onto a parent.
 - [ ] Phase 5 complete: full bead tree presented and confirmed.
 
 ## Verification checklist
@@ -143,6 +146,9 @@ Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
 - [ ] All epics are tagged with a priority (and `workflow:ralph` when under ralph).
 - [ ] Epics created with `--validate`; `bd lint` reports no missing sections for the created tree.
 - [ ] All tasks are classified AFK/HITL via `create-task`.
-- [ ] Parent epics carry the aggregate `implementation-type` tag.
+- [ ] Every epic and feature container carries `execution:hitl`, and every task states its own
+      `execution:afk`/`execution:hitl`.
+- [ ] Every impl child of a feature depends on that feature's planning bead.
+- [ ] No execution label was aggregated from children onto a parent.
 - [ ] No intermediate plan file was created — epics are the source of truth.
 - [ ] The full bead tree was presented to the user, or to ralph-plan for its next step.

package/skills/planning/record-idea/FORMAT.md

@@ -1,44 +1,93 @@
-# Idea Record Format
+# Idea Bead Format
 
-`scripts/new-idea.sh` generates this scaffold into `docs/ideas/<slug>.md` (or `docs/ideas/<slug>/<slug>.md` with `--complex`). Fill every section — a record with unfilled sections has not been captured.
+An idea record is a `bd` bead, not a file. `bd create` takes the whole record in one call; this
+document maps the interview onto the bead's fields and lists the content each section needs.
 
-## Scaffold
+## Record shape
 
-```md
-# Idea: <title>
+```bash
+bd create "Idea: <title>" \
+  -l kind:idea,execution:hitl \
+  -p <P0-P4> \
+  -d "<description>" \
+  --design "<design>" \
+  --notes "<notes>" \
+  --acceptance "<promotion criteria>" \
+  --validate --silent
+```
+
+- `kind:idea` marks an unscoped idea; `execution:hitl` keeps it out of agent-workable queries.
+  Ideas stay `open` — hiding them from automation is done by label exclusion, not status.
+- `-p` is the interview's priority. P4 (backlog) is the idea default; raise it when the user puts
+  the idea ahead of current work.
+- `--acceptance` carries the promotion criteria. A `task` bead requires acceptance criteria, so
+  this is what keeps `bd lint` clean for ideas.
+- `--validate` rejects the create when a required section is missing; `--silent` prints only the
+  new bead ID so the caller can report it.
+
+## Field mapping
+
+Keep the `##` markers inside each field. `flesh-out-idea` locates sections by marker, so a
+marker is the contract between capture and deepening.
 
-## Status
-Backlog idea (not implementation-ready)
+| Idea section | Bead field |
+|---|---|
+| Title | `--title` / positional argument, written as `Idea: <title>` |
+| `## Problem`, `## Who benefits`, `## Proposed outcome` | `-d` / `--description` |
+| `## How we might do it` | `--design` |
+| `## Validity check`, `## Constraints`, `## Next validation step`, `## Design so far / provenance`, `## Notes` | `--notes` |
+| Promotion criteria | `--acceptance` |
+| Priority | `-p` |
+| Anything referential (links, prior art, related beads) | `--context` |
 
-## Created
-<YYYY-MM-DD>
+`--description`, `--design`, and `--notes` each hold multiple `##` sections with the markers
+preserved:
 
+```text
+--description
 ## Problem
-<What problem does this idea address?>
+<what problem does this idea address?>
 
 ## Who benefits
-<Who benefits and what improves for them?>
+<who benefits and what improves for them?>
 
 ## Proposed outcome
-<What the idea would deliver, at a capability level — not implementation detail>
+<what the idea would deliver, at a capability level — not implementation detail>
 
+--design
+## How we might do it
+<the rough mechanism: skill, extension, agent, script, convention, …>
+
+--notes
 ## Validity check
 - Evidence we already have: <what supports this idea>
 - Riskiest assumption: <the assumption most likely to be wrong>
 - What would invalidate this idea: <the signal that kills it>
 
 ## Constraints
-<Hard limits: tech, process, scope, resourcing>
+<hard limits: tech, process, scope, resourcing>
 
 ## Next validation step
-<The cheapest next thing that would firm up or kill the idea>
+<the cheapest next thing that would firm up or kill the idea>
+
+## Design so far / provenance
+<where the idea came from, partial designs, options already ruled out, links to the discussion>
 
 ## Notes
-<Anything worth keeping for future prioritisation or review>
+<anything worth keeping for future prioritisation or review>
 ```
 
+Status and creation date are not fields — `bd` tracks status, assignee, and timestamps natively,
+so recording them again duplicates state that drifts.
+
 ## Guidance per section
 
 - Keep the record decision-oriented and scannable — it will be read during future prioritisation.
-- `Validity check` is mandatory: evidence grounds the idea, the riskiest assumption marks where it is weakest, and the invalidation signal tells you when to drop it.
-- `Next validation step` should be concrete enough to act on without re-deriving the context.
+- `Validity check` is mandatory in spirit: evidence grounds the idea, the riskiest assumption
+  marks where it is weakest, and the invalidation signal tells you when to drop it.
+- `Next validation step` should be concrete enough to act on without re-deriving the context.
+- `Design so far / provenance` is where the implementation questions land: the rough mechanism,
+  constraints already spotted, and existing design thoughts or discarded options. When an answer
+  is unknown, record "not considered yet" — the marker stays so the deepening pass can fill it.
+- Promotion criteria in `--acceptance` name what would move the idea out of the backlog: a
+  decision, a prototype result, or a dependency landing. Without it, "ready" is a feeling.

package/skills/planning/record-idea/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: record-idea
-description: Capture an early-stage idea into a structured backlog record with a short interview and validity check before any implementation planning. Use when the user says "capture this idea", "file this under ideas", or shares an idea that is "not ready to build".
+description: Capture an early-stage idea as a `kind:idea` bead with a short, validity-checking interview. Use when the user says "capture this idea", "file this under ideas", or shares an idea that is "not ready to build".
 ---
 
 # Record Idea
 
-Capture an idea that is not implementation-ready into `docs/ideas/`, pressure-testing it with a short high-level interview so the backlog stores a direction, not a slogan.
+Capture an idea that is not implementation-ready as a `bd` bead labelled `kind:idea`, pressure-testing it with a short high-level interview so the backlog stores a direction, not a slogan. The bead is the record: it is searchable, prioritised, syncable, and promotable in place.
 
 ## When to use
 
@@ -18,62 +18,86 @@ Capture an idea that is not implementation-ready into `docs/ideas/`, pressure-te
 - The idea is ready to build and needs a requirements document — run `write-a-prd` instead.
 - The user wants an executable task created now — run `create-task` instead.
 - The idea needs an end-to-end feature plan — run `plan` instead.
+- An idea bead already exists and needs deepening or promoting — run `flesh-out-idea` instead.
 
 ## Workflow
 
-1. **Interview at a high level, one question at a time.** Ask what problem it solves and who benefits, how it might be done (rough approach only — no implementation detail), what would make it timely (triggers, dependencies, timing signals), and what priority it feels like relative to current work. Keep this short — it is a capture step, not a requirements session.
+1. **Interview at a high level, one question at a time.** Ask what problem it solves and who benefits, what outcome it would deliver (capability level, not implementation), what would make it timely (triggers, dependencies, timing signals), and what priority it feels like relative to current work. Default the priority to P4 (backlog) unless the user says otherwise.
 
 2. **Pressure-test briefly.** Challenge weak points such as scope, feasibility, and opportunity cost. The goal is a validity signal for the backlog, not a polished pitch.
 
-3. **Choose the record shape.**
-   - Simple idea: a single file `docs/ideas/<idea-name>.md`.
-   - Complex idea: a folder `docs/ideas/<idea-name>/<idea-name>.md` with supporting docs alongside.
+3. **Ask the implementation questions — bounded, then stop.** After the high-level pass, ask these three, because they are cheap now and expensive to reconstruct later:
+   - **Rough mechanism** — what shape would this take (skill, extension, agent, script, convention, …)?
+   - **Known constraints or tradeoffs** — anything already spotted that would shape it?
+   - **Existing design thoughts** — anything already designed, sketched, or ruled out?
 
-4. **Create the record file.** Run this skill's `scripts/new-idea.sh` helper with {{TOOL:bash}}:
+   Follow up adaptively at most twice, and only when an answer opens a thread worth pulling. The
+   off-ramp is explicit: at any point "enough — record it" ends the interview and the answers so
+   far become the record. "Not considered yet" is a recorded answer, not a prompt to dig. This is
+   capture, not solutionising: the moment the conversation drifts into implementation detail,
+   record what you have.
+
+4. **Create the idea bead.** One `bd create` is the whole record — no files, no scaffold script:
 
    ```bash
-   bash <skill-scripts>/new-idea.sh --title "<idea title>" [--complex]
+   bd create "Idea: <title>" \
+     -l kind:idea,execution:hitl \
+     -p <P0-P4> \
+     -d "<## Problem, ## Who benefits, ## Proposed outcome>" \
+     --design "<## How we might do it>" \
+     --notes "<## Validity check, ## Constraints, ## Next validation step, ## Design so far / provenance>" \
+     --acceptance "<what would make this idea promotable>" \
+     --validate --silent
    ```
 
-   Resolve `<skill-scripts>` as the absolute path to this skill's own `scripts/` directory — it sits next to this `SKILL.md`, and the install location varies by harness, so do not hardcode a repo path. The script generates the scaffold, prints the file path, and errors if the file already exists or the title normalises to an empty slug.
+   Keep the `##` markers inside each field — `flesh-out-idea` finds and updates sections by marker. `kind:idea` marks it as an unscoped idea and `execution:hitl` keeps it out of agent-workable queries. `--acceptance` carries the promotion criteria and satisfies the required-section gate for a `task` bead, so the record lints clean. See `FORMAT.md` for the field mapping and the content each section needs.
 
-5. **Fill the scaffold.** Write concise, decision-oriented content from the interview into every section — see `FORMAT.md` for the section list. Leave no `TODO`: the validity check specifically needs evidence, the riskiest assumption, and what would invalidate the idea.
+5. **Verify the record.** `bd show <id>` to confirm the fields landed, and `bd lint <id>` to confirm no section is missing. Fix anything the lint flags before reporting.
 
-6. **Report back.** Return the file path, a 2–3 sentence summary of the recorded idea, and the suggested priority with its likely timing signal.
+6. **Report back.** Return the bead ID, a 2–3 sentence summary of the recorded idea, and the suggested priority with its likely timing signal.
 
 ## Red Flags
 
 - Drifting into implementation detail during the interview — the record captures a direction, not a design.
+- Chasing an adaptive follow-up past two rounds, or past the user's "enough" — capture that stalls stops being capture.
 - Skipping the pressure-test because the idea sounds good — weak points are cheapest to find here.
-- Leaving scaffold `TODO`s unfilled — an incomplete validity check is no check at all.
+- Writing the idea into a markdown file instead of a bead — the bead is the record; a file is
+  invisible to `bd` queries and dies outside the backlog.
+- Leaving a section that carries no information — record "not considered yet" rather than deleting the marker.
 
 ## Common Rationalizations
 
 | Rationalization | Rebuttal |
 |---|---|
-| "It's just an idea — write it down, don't interview me" | The two-minute interview is what makes the row reusable later; without it you store a slogan, not an idea. |
+| "It's just an idea — write it down, don't interview me" | The two-minute interview is what makes the bead reusable later; without it you store a slogan, not an idea. |
 | "The user already knows what they want" | Knowing the direction is not the same as pressure-testing it. The validity check exists to catch what enthusiasm hides. |
+| "The implementation questions are premature for an idea" | Three questions are cheaper now than a re-interview later, and they seed the provenance section the flesh-out pass reads. |
+| "I'll skip `--acceptance` and fill it in later" | The record is a `task` bead: without it `bd lint` flags the idea and the promotion bar is undefined. |
 
 ## Philosophy / rationale
 
-- **Capture before it becomes plan-shaped.** Scoping too early forces decisions the idea has not earned yet; a backlog note keeps the option open at minimal cost. The validity check is what stops the backlog from filling with confident, doomed ideas.
+- **Capture before it becomes plan-shaped.** Scoping too early forces decisions the idea has not earned yet; a backlog bead keeps the option open at minimal cost. The validity check is what stops the backlog from filling with confident, doomed ideas.
+- **One home for backlog state.** Ideas live in `bd` next to the tasks and epics they become, so priority, dependencies, and search work the same way at every stage and promotion is a label change rather than a migration.
 
-## Cross-skill references
+## See Also
 
-- When an idea passes its validity check and becomes implementation-ready, run `write-a-prd` to scope it properly.
-- For a full feature pipeline from idea to task breakdown, run `plan`.
+- [flesh-out-idea](../flesh-out-idea/SKILL.md) — the next step when the idea needs deepening, promotion, or task children.
+- [write-a-prd](../write-a-prd/SKILL.md) — load once the validity check passes and the idea is implementation-ready.
+- [plan](../../workflow/plan/SKILL.md) — load when the idea should run the whole feature pipeline rather than just be recorded.
 
 ## Examples
 
 Input: "I keep accidentally committing secrets — capture that idea."
-Output: `docs/ideas/secret-scanning-gate.md` — a filled idea record with a validity check, priority, and next validation step. See `FORMAT.md` for the scaffold sections.
+
+Output: `bd create "Idea: secret-scanning gate" -l kind:idea,execution:hitl -p 3 … --silent` → bead `proj-a1b2` — description holds the problem, who benefits, and the proposed outcome; `--design` the rough mechanism (a pre-commit hook); `--notes` the validity check, constraints, next validation step, and provenance; `--acceptance` the bar for promotion. See `FORMAT.md` for the full field mapping.
 
 ## Verification checklist
 
-- [ ] Interview covered who benefits, rough approach, timing, and priority.
+- [ ] Interview covered the problem, who benefits, rough mechanism, timing, and priority.
 - [ ] Idea was pressure-tested; weak points were challenged.
-- [ ] Record file exists at `docs/ideas/<slug>.md` (script printed the path).
-- [ ] Every scaffold section is filled — no `TODO` left in the record.
-- [ ] Validity check records evidence, the riskiest assumption, and what would invalidate the idea.
-- [ ] Record contains no implementation detail.
-- [ ] Report returned the file path, summary, and suggested priority.
+- [ ] Implementation questions were asked, with at most two adaptive follow-ups.
+- [ ] A `kind:idea` + `execution:hitl` bead exists (`bd show <id>` confirms both labels).
+- [ ] Description, `--design`, `--notes`, and `--acceptance` carry their `##` section markers.
+- [ ] `bd lint <id>` is clean.
+- [ ] Record contains no implementation detail beyond the recorded mechanism thoughts.
+- [ ] Report returned the bead ID, summary, and suggested priority.

package/skills/planning/request-refactor-plan/SKILL.md

@@ -62,11 +62,11 @@ description: Create a detailed refactor plan via user interview, split into tiny
 - [ ] Phase 3 complete: commit plan written with every step leaving the codebase working.
 - [ ] Phase 4 complete: bead filed via `create-task` with priority P2.
 
-## Cross-skill references
+## See Also
 
-- `create-task` — files the plan bead and expands it into pipeline stages. Mandatory; never call `bd create` directly.
-- `write-a-prd` — product-level planning that is not a code refactor.
-- `record-idea` — early-stage refactor ideas not ready for a full plan.
+- [create-task](../create-task/SKILL.md) — mandatory next step: files the plan bead and expands it into pipeline stages.
+- [write-a-prd](../write-a-prd/SKILL.md) — load when the change is product-level rather than a code refactor.
+- [record-idea](../record-idea/SKILL.md) — load when the refactor idea is still too early for a commit-sized plan.
 
 ## Examples
 

package/skills/planning/spec-to-tickets/SKILL.md

@@ -115,12 +115,12 @@ Workflow at a glance:
 | "I'll note the open question in the ticket" | Only with the human's explicit agreement. Otherwise resolve it or spike it — an unagreed question is a blocked implementer. |
 | "One big ticket is simpler to track" | Big tickets hide scope and block parallel work. |
 
-## Cross-skill references
+## See Also
 
-- **`write-a-ticket`** — invoked for every body; owns the ticket quality bar.
-- **`write-a-prd`** — use first when no spec exists.
-- **`prd-to-tasks`** — use when the output is beads for the ralph/bd loop, not external tickets.
-- **`style-comms`** — invoke when drafting the map's titles and intents.
+- [write-a-ticket](../write-a-ticket/SKILL.md) — invoked for every ticket body; owns the ticket quality bar.
+- [write-a-prd](../write-a-prd/SKILL.md) — load first when no spec exists.
+- [prd-to-tasks](../prd-to-tasks/SKILL.md) — load when the output is beads for the ralph/bd loop rather than external tickets.
+- [style-comms](../../style/style-comms/SKILL.md) — load when the map's titles and intents read loosely.
 
 ## Phase-gate checklist
 

package/skills/planning/write-a-prd/SKILL.md

@@ -25,7 +25,7 @@ description: Create a PRD through user interview, codebase exploration, and modu
 3. **Interview relentlessly.** Walk down each branch of the design tree, resolving dependencies between decisions one by one, until the user's understanding and yours are identical. The epic's required sections — `## Success Criteria` in particular — are the interview's target: it is complete only when there is enough agreed detail to fill every required section. Never invent an answer; surface it as an assumption and confirm it with the user.
 4. **Sketch the modules.** List the major modules to build or modify, actively looking for deep modules — ones that encapsulate rich behaviour behind a simple, stable interface testable in isolation. Confirm the list with the user, plus which modules they want tests written for.
 5. **Write the PRD.** Render the template in `FORMAT.md` (Problem Statement, Solution, User Stories, Success Criteria, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes). Make the user-story list extremely extensive so it covers all aspects of the feature.
-6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file - --validate`, piping the rendered PRD to stdin, then run the `classify-bead` classifier (`node <this-skill-dir>/../classify-bead/scripts/classify-bead.mjs <epic-id>`, run from the target project's cwd) to label it AFK or HITL. Escalate to the `classify-bead` subagent only when the classifier reports `escalate: true`. Finally run `bd lint <epic-id>` and fix any missing sections before reporting.
+6. **File the bead.** Create the epic with `bd create "<title>" --type epic -l execution:hitl --priority P1 --body-file - --validate`, piping the rendered PRD to stdin. A PRD epic is a container a person owns, so it is `execution:hitl` in its own right — it is not classified; the work beads beneath it are. Finally run `bd lint <epic-id>` and fix any missing sections before reporting.
 
 Run the steps in order. Skip a step only when the user confirms it is unnecessary (e.g. the codebase is already explored).
 
@@ -52,15 +52,14 @@ Run the steps in order. Skip a step only when the user confirms it is unnecessar
 
 - [ ] Gate 1 — shared understanding: every design-tree branch resolved and the user confirms the summary.
 - [ ] Gate 2 — modules agreed: the module list and test expectations match the user's model of the solution.
-- [ ] Gate 3 — PRD filed: the epic bead contains the rendered template, carries an implementation-type label, and lints clean.
+- [ ] Gate 3 — PRD filed: the epic bead contains the rendered template, carries `execution:hitl`, and lints clean.
 
-## Cross-skill references
+## See Also
 
-- Use `record-idea` when the idea is not yet ready to build.
-- Use `write-a-ticket` when the spec targets an external tracker rather than a bead.
-- Use `spec-to-tickets` when an approved PRD/RFC must become a map of external tickets.
-- Run `prd-to-tasks` on the filed epic to break the PRD into an executable backlog.
-- Run the `classify-bead` classifier on the new epic — the repo labels every new bead AFK or HITL. Its `scripts/` directory sits next to this skill's directory in every harness, so `<this-skill-dir>/../classify-bead/scripts/classify-bead.mjs` resolves it. Escalate to its rubric subagent only when the classifier reports `escalate: true`.
+- [prd-to-tasks](../prd-to-tasks/SKILL.md) — the next step after filing: breaks the epic into an executable backlog, and its `create-task` calls classify only the work beads, so never run `classify-bead` on the epic itself.
+- [spec-to-tickets](../spec-to-tickets/SKILL.md) — load when the spec becomes tickets in an external tracker instead of beads.
+- [write-a-ticket](../write-a-ticket/SKILL.md) — load when the output is a single externally tracked ticket.
+- [record-idea](../record-idea/SKILL.md) — load when the idea is not yet ready to build.
 
 ## Examples
 
@@ -75,4 +74,4 @@ Output: an epic bead whose description is the rendered PRD — problem, solution
 - [ ] Every user story follows "As an <actor>, I want <feature>, so that <benefit>".
 - [ ] Codebase assertions verified against the repo before writing.
 - [ ] Implementation Decisions contains no file paths or code snippets.
-- [ ] Epic bead filed with type `epic`, priority P1, the rendered PRD as description, and an implementation-type label applied.
+- [ ] Epic bead filed with type `epic`, priority P1, the rendered PRD as description, and `execution:hitl` applied — a PRD epic is human-owned by definition.

package/skills/planning/write-a-ticket/SKILL.md

@@ -106,13 +106,11 @@ section when there are none.>
 - **Describe the behaviour, not the implementation.** The ticket owns the what and why; the implementer owns the how.
 - **A ticket must stand alone.** Link, don't copy — readers who need the full rationale open the linked document, not a paraphrase.
 
-## Cross-skill references
+## See Also
 
-| When you need…                                          | Use this skill    |
-| ------------------------------------------------------- | ----------------- |
-| To break a spec into a map of tickets                   | `spec-to-tickets` |
-| Tone, structure, and concision for human-facing writing | `style-comms`     |
-| A requirements document that precedes the ticket        | `write-a-prd`     |
+- [spec-to-tickets](../spec-to-tickets/SKILL.md) — load when the spec needs a map of tickets rather than one.
+- [style-comms](../../style/style-comms/SKILL.md) — load for tone and concision rules when the body reads loosely.
+- [write-a-prd](../write-a-prd/SKILL.md) — load when the requirements document that precedes the ticket does not exist.
 
 See [EXAMPLES.md](./EXAMPLES.md) for worked before/after rewrites.
 

package/skills/productivity/bd-tool/SKILL.md

@@ -32,7 +32,8 @@ We use labels to track state. Key patterns:
 | Label | Purpose | Example |
 |---|---|---|
 | `stage:<id>` | Pipeline stage for chore beads | `stage:code`, `stage:verify` |
-| `implementation-type:<type>` | Who works it | `afk`, `hitl` |
+| `execution:<class>` | Who works it — `afk` is agent-routable, `hitl` needs a human | `afk`, `hitl` |
+| `kind:idea` | Unscoped backlog idea, always `execution:hitl` | `kind:idea` |
 | `lifecycle:<phase>` | Lifecycle gate | `feature-pr` |
 | `epic:<id>` | Parent epic link | `epic:abc-123` |
 | `priority:<level>` | Priority (0-3) | `priority:1` |
@@ -49,7 +50,7 @@ bd create "<title>" -d "<description>" -p <0-3> --validate
 For parent-child relationships (create with `--parent`):
 
 ```bash
-bd create "<title>" --parent <parent-id> --validate
+bd create "<title>" --parent <parent-id> -d "<description with the type's required section>" --validate
 ```
 
 For blocking dependencies between beads:
@@ -102,14 +103,18 @@ Optional — beads work locally. Sync at session end when it's convenient.
 ## Key conventions
 
 - **Priority**: 0 = critical, 1 = high, 2 = medium, 3 = low, 4 = backlog. Aliased as P0-P4.
-- **HITL beads**: require human action — do not claim or implement them. Inform the user.
+- **`execution:afk` / `execution:hitl`**: the execution axis, and a query filter only — no
+  auto-claim. `bd ready -l execution:afk` is the agent-workable view; an `execution:hitl` bead
+  needs a human, so do not claim or implement it. Inform the user.
+- **Idea beads** (`kind:idea`): an open, unscoped idea (`execution:hitl`) that is promoted to an
+  epic once fleshed out. They stay `open` and carry no `execution:afk`, so a scoped
+  `bd ready -l execution:afk` view never lists them — but a bare `bd ready` does. Filter a
+  plain ready listing with `bd ready --exclude-label kind:idea`.
 - **Chore beads** (`--type chore`): auto-created pipeline stages. Do not create them manually — use `create-task`. Not ephemeral — they must stay visible to plain `bd ready` for ralph to discover them.
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Creating a new task with pipeline expansion | `create-task` |
-| Executing a single pipeline stage | `run-pipeline-stage` |
-| Running the full end-to-end pipeline | `ralph` |
-| Classifying a bead's implementation type | `classify-bead` |
+- [create-task](../../planning/create-task/SKILL.md) — creating a task that needs pipeline expansion.
+- [classify-bead](../../planning/classify-bead/SKILL.md) — resolving a bead's execution class.
+- [run-pipeline-stage](../../workflow/run-pipeline-stage/SKILL.md) — executing a single pipeline stage for a claimed bead.
+- [ralph](../../workflow/ralph/SKILL.md) — running the whole ready backlog end to end.

package/skills/productivity/grill-me/SKILL.md

@@ -19,3 +19,8 @@ interview is complete only when there is enough agreed detail to fill every requ
 Never invent section content. If you must infer an answer, state it as an assumption and get the
 human to confirm it before it becomes bead content. Leave unresolved branches open — an open
 question is better than a fabricated answer.
+
+## See Also
+
+- [grill-with-docs](../../engineering/grill-with-docs/SKILL.md) — load when the decisions reached should land in CONTEXT.md or an ADR.
+- [technical-direction](../../engineering/technical-direction/SKILL.md) — load when the grilled design needs a justified recommendation between options.

package/skills/productivity/init-beads/SKILL.md

@@ -80,10 +80,10 @@ Print a brief summary: whether `bd` was installed or already present, whether be
 | "I'll skip `--stealth` so the user can see what happens" | Stealth mode is the contract of this skill — non-stealth init adds hooks and commits the user never asked for. |
 | "I should ask before installing software on the user's machine" | Installing `bd` is the requested outcome; asking adds friction and the skill is meant to run headless. |
 
-## Cross-skill references
+## See Also
 
-- Use `bd-tool` for day-to-day beads usage once initialised — `bd prime`, `bd ready`, `bd create`, `bd close`.
-- Use `create-task` to create tasks with pipeline-stage expansion and a HITL review gate.
+- [bd-tool](../bd-tool/SKILL.md) — day-to-day beads usage once the workspace exists.
+- [create-task](../../planning/create-task/SKILL.md) — load when the first tracked task needs pipeline-stage expansion.
 
 ## Examples