@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

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

@@ -37,6 +37,61 @@ We use labels to track state. Key patterns:
 | `lifecycle:<phase>` | Lifecycle gate | `feature-pr` |
 | `epic:<id>` | Parent epic link | `epic:abc-123` |
 | `priority:<level>` | Priority (0-3) | `priority:1` |
+| `defect:<class>` | The kind of defect a review rejection names — one per rejection, closed list, never the whole message | `defect:test-unproven` |
+
+## Where operational state lives
+
+Operational state lives in bead fields, not in files: progress, what a stage learned, the
+decisions taken, and the branch, PR, commit or worktree refs. A cold agent reads all of it from
+the bead.
+
+| State | Home |
+|---|---|
+| What a stage did, and what it learned | `bd note <id> "…"` — an append-only trail |
+| Status: never started, in flight, blocked, paused, done | the bead's own status — `bd statuses` |
+| A decision and its reason | `bd note <id> "…"` — the same trail |
+| Branch, PR, commit, worktree | `bd provenance record --issue <id> …` |
+| Reviewer handoff prose | `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md` — unchanged |
+| Screenshots, logs, repro scripts | the bead's working-docs directory — unchanged |
+
+Durable, committable documents stay files: `SKILL.md`, `REFERENCE.md`, playbooks, prompts,
+`docs/`, `AGENTS.md`. Never migrate those into beads — they are reviewed, diffed and versioned as
+text. A scratch file for progress is wrong twice: it duplicates the bead, and no other agent finds
+it.
+
+### Use the built-in statuses; add no state labels
+
+`bd statuses` lists the seven statuses the tracker owns, and they already answer "where is this
+work?": `open` never started, `in_progress` being worked on, `blocked` stopped with no bead to
+wait on, `deferred` stopped on purpose, `closed` finished, and `pinned`/`hooked` parked by the
+tracker. A label such as `progress:blocked` repeats a status and splits the answer across two
+places, so do not add one.
+
+A stop that needs a human decision becomes a bead, not a label: create the decision bead
+(`execution:hitl`, the question in its title) and depend the waiting bead on it. The waiting bead
+leaves `bd ready`, and the decision shows up as work a human can take. Use `--status blocked` only
+when no bead can carry the blocker — a fix-round cap, an outage. Record the stop and its reason
+with `bd note`, which appends, so the trail keeps every checkpoint in order.
+
+```text
+$ bd create "Decide: which upstream API do we call?" -t task -l execution:hitl
+✓ Created issue: probe-3i4 — Decide: which upstream API do we call?
+$ bd dep add probe-ijd probe-3i4         # probe-ijd waits on the decision
+✓ Added dependency: probe-ijd (Rate-limit the export endpoint) depends on probe-3i4 (…) (blocks)
+$ bd ready                               # only the decision bead is ready now
+○ probe-3i4 P2 Decide: which upstream API do we call?
+$ bd note probe-ijd "[2026-11-14T08:26:38Z] stopped: API choice open; decision bead filed"
+✓ Note added to probe-ijd — Rate-limit the export endpoint
+```
+
+**Never set a state dimension.** `bd set-state` writes a label for a dimension and removes the
+label it replaces, so `bd set-state <id> stage=verify` deletes `stage:code` and rewrites the
+bead's route. Statuses and notes cover every case above, so no dimension is needed.
+
+### `defect:<class>` classifies a defect; it is not a state
+
+A review rejection carries one class from the closed list in
+[review-defects](../../review/review-defects/SKILL.md), which owns how to apply, remove and query it.
 
 ## Creating work
 

package/skills/productivity/write-a-skill/SKILL.md

@@ -25,7 +25,7 @@ Clarify the skill goal with the user. Ask what triggers users would actually say
 
 ### 2. Draft from the anatomy template
 
-Read `docs/skills/skill-anatomy.md` as the source of truth. Follow the annotated template for section ordering and front-matter fields. Target ~150 lines for `SKILL.md` but stay under the 150-line hard cap. When the workflow branches or has decision points, include one inline ASCII workflow diagram per the anatomy doc's diagram style guide — ASCII only, never Mermaid.
+Read `{{PATH:skill_anatomy}}` as the source of truth. Follow the annotated template for section ordering and front-matter fields. Target ~150 lines for `SKILL.md` but stay under the 150-line hard cap. When the workflow branches or has decision points, include one inline ASCII workflow diagram per the anatomy doc's diagram style guide — ASCII only, never Mermaid.
 
 ### 3. Apply voice and tone rules
 
@@ -62,7 +62,7 @@ Output: A new `skills/review-security/SKILL.md` with front matter, When to use,
 
 ## Verification checklist
 
-- [ ] `docs/skills/skill-anatomy.md` was read before drafting
+- [ ] `{{PATH:skill_anatomy}}` was read before drafting
 - [ ] Required sections present: `## When to use`, `## Workflow`, `## Verification checklist`
 - [ ] Section order follows the anatomy template
 - [ ] Workflow diagram (if present) is ASCII-only and follows the anatomy diagram style guide

package/skills/review/refactor-skill/SKILL.md

@@ -8,7 +8,7 @@ description: Refactor an existing SKILL.md to the canonical anatomy template thr
 ## When to use
 
 - A skill's SKILL.md predates the anatomy template and needs upgrading.
-- You want to align a skill with `docs/skills/skill-anatomy.md` before the refactor wave touches it.
+- You want to align a skill with `{{PATH:skill_anatomy}}` before the refactor wave touches it.
 - You want to compare a skill's structure to the current template standard.
 - Trigger phrases: "refactor this skill", "restructure this skill", "review this skill", "upgrade X to the template", "align with anatomy".
 
@@ -27,7 +27,7 @@ Read the target skill's `skills/<name>/SKILL.md` and the canonical anatomy refer
 
 ```bash
 cat skills/<name>/SKILL.md
-cat docs/skills/skill-anatomy.md
+cat {{PATH:skill_anatomy}}
 ```
 
 If the target has no `SKILL.md` yet, abort — this skill upgrades existing files; use `write-a-skill` for new creation.

package/skills/review/review-defects/EXAMPLES.md

@@ -0,0 +1,122 @@
+# Review defects — worked examples
+
+One case per class. Each shows what was observed, the label, and the rejection text to write. Six
+were observed in real review rounds and one in a code stage's check of its own change; `scope-creep`
+is described as a situation, because no recorded case exists, so you can match its shape without
+guessing at history.
+
+## `test-unproven` — the name claims a settle-time cleanup
+
+**Observed.** A test named "… removes it when the watch settles" called `stop()` and asserted the
+entry was gone. It never settled the watch, so the settle path had no assertion. The cleanup on
+settle could have been deleted and the test would still pass.
+
+**Label.** `defect:test-unproven`
+
+**Rejection text.** "Test `…removes it when the watch settles` claims removal at the settle step,
+but the body stops the watch and asserts removal once. Add the settle trigger and assert the entry
+is gone after it. Either the name or the assertion must change."
+
+**Why this class.** Not `test-cannot-fail`: the assertion is genuine and would fail for the bug it
+covers. The defect is narrower — the name promises a path the body never takes.
+
+## `test-cannot-fail` — the concurrent case is never exercised
+
+**Observed.** A note appended "a double fire appends nothing twice". The test fired twice in
+sequence and asserted one entry. Two concurrent fires were never run, so the claim could not fail.
+
+**Label.** `defect:test-cannot-fail`
+
+**Rejection text.** "The claim is about concurrent double fires, but the test fires sequentially.
+Await both fires against the same target and assert one entry, or rename the claim. As written no
+implementation can fail it."
+
+**Why this class.** Not `test-unproven`: the name and the assertion agree on "two fires produce one
+entry". The gap is that the case the claim is about is never constructed.
+
+## `missing-proof` — a report of a demonstration that was stubbed
+
+**Observed.** A stage report stated "end-to-end run verified: the check writes the record and the
+follow-up reads it". The command in the evidence block substituted a stub for the check, so no
+end-to-end path ran.
+
+**Label.** `defect:missing-proof`
+
+**Rejection text.** "`SUMMARY` claims an end-to-end demonstration; the evidence command replaces the
+check with a stub, so the record is written by the test, not by the code under review. Paste the
+real invocation and its output."
+
+**Why this class.** Nothing is missing from the code. The gap is between the claim and the evidence
+for it, which is exactly what this class names.
+
+## `docs-drift` — shipped text that shipped past its change
+
+**Observed.** Two shipped text defects in one round: a token map named an exact harness version, so
+the mapping broke on the next release; and a peer-channel section still said one harness only, after
+the fork had made it both.
+
+**Label.** `defect:docs-drift`
+
+**Rejection text.** "The token map names an exact harness version — it must read the running one or
+a documented default. The peer-channel section says one harness only, but the mapping now covers
+both; update the prose to what ships."
+
+**Why this class.** The shipped artefact and the text describing it disagree. A reviewer reading the
+text would predict behaviour the install does not have.
+
+## `criteria-unmet` — the change breaks the criterion it must satisfy
+
+**Observed.** A criterion said an install leaves one directory free of the tool's own files. The
+change wrote its state record into that very directory, so the reviewer could not affirm the
+criterion at all.
+
+**Label.** `defect:criteria-unmet`
+
+**Rejection text.** "The criterion says that directory holds no file of ours; the new record is
+written into it, so the criterion fails. Move the record under the tool's own state directory,
+keyed by the directory it describes, or amend the criterion in the bead and say why."
+
+**Why this class.** The work is real and the scope is honest — part of what was asked is absent.
+
+## `scope-creep` — unrelated tidying rides along
+
+**Situation.** A change that adds one label also renames three unrelated helpers and reformats a
+neighbouring module.
+
+**Label.** `defect:scope-creep`
+
+**Rejection text.** "The rename and the reformat are outside the criteria. Split them into their own
+change so this one can be reviewed and reverted on its own."
+
+**Why this class.** Every line is defensible in isolation. The defect is that the change is wider
+than its reason, which hides the real diff.
+
+## `style-violation` — a written rule is broken
+
+**Observed.** A change added a new skill and declared a `patch` bump in its changeset. The
+versioning rule says a new skill is a `minor` bump and lists "wrong bump type" as a red flag. The
+reviewer rejected the change citing that rule.
+
+**Label.** `defect:style-violation`
+
+**Rejection text.** "The changeset declares `patch`, but this change adds a skill. The versioning
+rule makes an addition `minor` and calls a wrong bump type a red flag. Bump it to `minor`."
+
+**Why this class.** Cite the rule, not a preference. A reviewer who cannot quote a written rule has
+a preference, and preferences are not rejections.
+
+## `regression` — an existing behaviour breaks
+
+**Observed.** A code stage added a manifest write that assumed its target directory existed. An
+install from a source holding no agents and no skills had worked before; after the change it threw
+`ENOENT` on that write. The stage found it in its own check of the change, reproduced it, added a
+test that failed, then fixed it.
+
+**Label.** `defect:regression`
+
+**Rejection text.** "The manifest write assumes its directory exists, so an install from a source
+with no agents and no skills now throws `ENOENT` where it used to succeed. Create the directory
+before writing, and cover the empty-source case with a test."
+
+**Why this class.** The change may satisfy its own criteria fully. It also breaks behaviour nobody
+asked to change, which is a separate fact from `criteria-unmet`.

package/skills/review/review-defects/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: review-defects
+description: The closed vocabulary of `defect:<class>` labels a reviewer applies to a rejected bead, so rejections become countable data. Use when rejecting a change, when deciding which class names a finding, or when querying which defects recur.
+---
+
+# Review defects
+
+A rejection says what is wrong. The class says *which kind* of wrong, in one word, so rejections can
+be counted, compared and trended across tasks instead of re-read one at a time.
+
+## One closed list, one label per rejection
+
+Apply exactly one class from this table. Never invent one.
+
+| Class | The defect | Evidence the rejection must show |
+|---|---|---|
+| `test-unproven` | A test's name claims a requirement its assertions never check. | The named clause, and the assertion that is missing. |
+| `test-cannot-fail` | An assertion passes against a broken implementation. | The case that should fail and does not. |
+| `criteria-unmet` | A criterion from the bead is not delivered. | The criterion, quoted, and what is absent. |
+| `scope-creep` | The change does more than the criteria ask. | The touched behaviour that no criterion names. |
+| `style-violation` | A `style-*` rule is broken. | The rule, quoted, and the line that breaks it. |
+| `missing-proof` | A report claims success with no evidence. | The claim, and the command output that is absent. |
+| `regression` | Behaviour that worked before now breaks. | The old behaviour, and the check that now fails. |
+| `docs-drift` | Shipped text no longer matches what ships. | The text, and the behaviour that contradicts it. |
+
+Two findings of different kinds are two entries in the rejection text and one label: the class of
+the finding that must be fixed first.
+
+## A class is a classification, not a state
+
+The bead's own status still answers "where is this work?". The label answers "what kind of defect
+was this?" — so never use it to mean blocked, in progress or done, and never add a parallel state
+label.
+
+## Apply it
+
+1. Name the class in the rejection text, next to the specific reason.
+2. Apply it to the bead whose work you reject:
+
+   ```bash
+   bd update <id> --add-label defect:test-unproven
+   ```
+
+   That bead is normally already closed — a pipeline closes the chore whose work is rejected before
+   the review runs — and the label attaches to it anyway. So the queries below pass `--all`.
+
+3. Write the specific reason — the file, the line, the missing assertion — in the rejection text.
+   The label is queryable; it is never the whole message.
+
+## Remove it when the fix closes
+
+The review that confirms the fix removes the label, so the vocabulary describes only defects whose
+fix is unconfirmed:
+
+```bash
+bd update <id> --remove-label defect:test-unproven
+```
+
+Record the removal in that review's trail entry ("`defect:test-unproven` cleared"), not as a label.
+A closed defect is a fact in the trail, not a second class.
+
+## An unknown class is itself a defect
+
+A class that is not on the list above is not a label. Applying one is a review defect in itself:
+state it in the rejection text, use the nearest real class for the finding, and raise the gap with
+the owner. Do not extend the list inside a review — a vocabulary that grows per rejection counts
+nothing.
+
+## Query it
+
+```bash
+bd list -l defect:test-unproven --all        # one class, any status
+bd list --label-pattern 'defect:*' --all     # every defect, any class
+```
+
+`--all` is not optional. `bd list` hides closed beads by default, defects are historical data, and
+the bead carrying one is usually closed: drop the flag and the query reports "No issues found" on
+a label that is set.
+
+Count the pattern output per class to see what recurs, and fix the process that produces it — a
+class that keeps appearing is a gap in the stage before this one.
+
+## Worked examples
+
+`EXAMPLES.md` carries one real case per class, with the rejection text a reviewer should write.
+
+## See Also
+
+- [review-security](../review-security/SKILL.md) — the security verdict that precedes any rejection.
+- [run-pipeline-stage](../../workflow/run-pipeline-stage/SKILL.md) — the stage that applies these labels.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — labels, notes and statuses.

package/skills/style/style-tests/EXAMPLES.md

@@ -434,6 +434,36 @@ for (const item of cart.items) {
 expect(cart.items.map((item) => item.price)).toStrictEqual([10, 20, 30]);
 ```
 
+### A test name is a claim
+
+The name says what the test proves. Read it as a list of assertions and check that each one
+appears in the body. A clause with no assertion is a requirement the suite never enforces, so the
+test stays green while the behaviour breaks.
+
+```ts
+// ❌ Instead — the name claims one notice; the body only claims that something exists.
+// Remove the notice and this test still passes, because a list is always defined.
+it("sends one notice", async () => {
+  await publishAll(recipients);
+
+  expect(await notices.list()).toBeDefined();
+});
+
+// ✅ Write — the count in the name is asserted, so two notices and no notices both fail
+it("sends one notice", async () => {
+  await publishAll(recipients);
+
+  expect(await notices.list()).toHaveLength(1);
+});
+```
+
+A state in the name works the same way — "returns the cached user" needs an assertion that the
+returned user came from the cache, not that a user came back — and a "not" needs an assertion of
+the absence, such as a call count of zero.
+
+The *Workflow* mutation check catches this at run time: disable the behaviour and the bad form
+above stays green, while the good form goes red.
+
 ## Determinism and async
 
 ```ts

package/skills/style/style-tests/SKILL.md

@@ -25,6 +25,7 @@ description: Defines test-writing conventions — assertion strategy, mock disci
 - **Integration and e2e exercise real services.** Run the genuine collaborator — Postgres, Redis, a queue, object storage via TestContainers or LocalStack — never a fake that drifts from the real contract. Reserve e2e for a small number of smoke tests proving the system hangs together.
 - **No more tests than needed.** Every test earns its cost by pinpointing exactly where a failure lies. A test that cannot localise a fault adds maintenance weight without signal.
 - **One behaviour per test.** A test should fail for exactly one reason; several unrelated assertions turn a failure into a debugging exercise.
+- **A test's name is a claim, and every clause of it is an assertion.** A count in the name — "one notice", "both callers", "no retries" — asserts that count; a state in the name asserts that state; a "not" in the name asserts the absence. A name that outruns its assertions states a requirement the test never proves, so the test cannot fail for the reason its name promises. See _Red Flags_, and the "one notice" pair under _A test name is a claim_ in `EXAMPLES.md`.
 - **Test code is production code.** Linted, typechecked, properly typed — no `any`, no unsafe casts, no shortcuts in constructing data. Tolerate WETness where it leaves tests more descriptive.
 - **All setup and assertion data is visible inline.** Show exactly and only the values that explain the case; a helper with sensible defaults keeps it terse.
 - **Deterministic and performant.** A failing or flaky test is investigated now. Deferring is acceptable only against a top-priority bead.
@@ -71,7 +72,9 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 5. **Write targeted assertions.** Prefer `toMatchObject` over asserting every property. Multiple assertions are fine when they all verify the same behaviour. Avoid asserting call counts when asserting call arguments already covers the behaviour. Assert behaviour the file participates in, never its static contents.
 
-6. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
+6. **Run the mutation check.** Before you finish, disable or revert each behaviour a test claims, then run the suite. Every test named for that behaviour must fail. A named test that still passes proves nothing about its name: it is the _Red Flags_ row on empty implementations, applied to the whole name. Restore the behaviour and confirm the suite is green again.
+
+7. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
 
 ## Red Flags
 
@@ -80,7 +83,8 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 | Asserting static file content — an expected config/markdown/terraform string, or a snapshot of static content | Assert the behaviour the file participates in: data inserted into a template, a header compiled correctly, a deployed service ready to serve traffic |
 | Shared mutable top-level fixture reused across tests | Build fresh data per test via a factory; a module-scope constant only when genuinely immutable and read-only |
 | Repeated full literals for the same shape | A small configurable factory taking partial overrides with sensible defaults |
-| A test with no assertion, or one that cannot fail (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| A test with no assertion, or one that passes against an empty implementation (`expect(result).toBeDefined()`) | Assert the observable contract — a specific value the code must produce |
+| A test name whose claim no assertion mentions — "one notice" proven only by `toBeDefined()`, a count proven by truthiness | Assert every clause of the name: the count (`toHaveLength(1)`), the state, the absence |
 | Computing the expected value with the implementation's own logic | Hard-code the expected value from a known-good case; the test must not share the implementation's bug |
 | Mocking implementation details or internal module structure | Mock the genuine external boundary and test through the public interface |
 | An "integration" test that mocks the collaborator it is meant to integrate with | Run the real collaborator (TestContainers/LocalStack); a fake drifts from the real contract |
@@ -115,9 +119,8 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 
 ## Examples
 
-The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md`: behaviour over
-implementation, test data, mocking, integration and e2e, targeted assertions, structure and
-naming, determinism and async, isolation, and content assertions. Headline pairs:
+The full `❌ Instead` / `✅ Write` catalogue lives in `EXAMPLES.md` — including _A test name is a
+claim_, with the "one notice" pair. Headline pairs:
 
 | Instead of… | Write… |
 |---|---|
@@ -131,7 +134,8 @@ naming, determinism and async, isolation, and content assertions. Headline pairs
 - [ ] Test verifies behaviour, not implementation structure
 - [ ] Integration tests exercise the real collaborator — no mocking the engine you are integrating with
 - [ ] E2E smoke tests prove wiring, migrations, and the journey — not business rules covered lower down
-- [ ] Each test fails for exactly one reason, and its name states the behaviour
+- [ ] Each test fails for exactly one reason, and its name states only behaviour an assertion proves — count, state, and absence included
+- [ ] Mutation check run: each claimed behaviour was disabled, its named tests failed, and the suite is green again
 - [ ] No mocking of internal module details — only public interfaces
 - [ ] No `before`/`after` hooks for shared test state (infrastructure setup only)
 - [ ] Assertions are targeted — no over-asserting, no tautologies, no assertion-free tests

package/skills/workflow/plan/SKILL.md

@@ -156,7 +156,7 @@ For each task (within each epic), create a bead, classify it, and expand AFK tas
 
 ### Phase 4 — Prepare handoff to ralph
 
-Deliver a handoff bead and instructions for running ralph.
+Deliver a handoff bead, message the running ralph session, and give the instructions for running ralph.
 
 17. Determine the entry point:
 
@@ -188,7 +188,15 @@ Deliver a handoff bead and instructions for running ralph.
     ```
     **Gate on the exit status.** Non-zero: retry once, then stop and report the command, exit code and stderr as a sync blocker — the handoff has not left this machine, so do not present the handoff summary.
 
-20. Present the handoff summary:
+20. Send the handoff to the running ralph session, now that the bead exists:
+    ```
+    handoff <handoff-id> — <one-line scope>
+    ```
+    The peer channel carries it: run {{TOOL:peer_list}} first, because with no reachable ralph there is no receiver — report that in the summary and keep the manual instruction below as the handoff path. When ralph is reachable, send it with {{TOOL:peer_send}}, set the intent to `task` where the transport has an intent, and write the kind as the first word of the text — never type into a busy session's terminal, where stray keystrokes are queued as user prompts. Ralph answers `done`, `blocked` or `failed`; `running` or `queued` means delivered, not done, so never read the send itself as acknowledgement. The full kind table, the acknowledgement rule and the per-session setup live in [ralph's REFERENCE](../ralph/REFERENCE.md) (_Peer messaging (planner ↔ ralph)_).
+
+21. While the planning session stays open, treat ralph's `blocked` messages as your pending-human list: each one names a gate bead awaiting a human, so run `bd show <id>` and surface it together with ralph's `done`, `failed` and `update` reports instead of watching a terminal. Read the same gates from `bd` as well, so a message that never arrived is not mistaken for no gate. A peer message is never human consent and never approval for a gate: confirm the gate in `bd`, and let a person close it.
+
+22. Present the handoff summary:
     ```
     ✅ Plan complete. Ready for ralph.
 
@@ -214,6 +222,7 @@ Deliver a handoff bead and instructions for running ralph.
 - [ ] Every handoff-path bead lints clean (`bd lint`)
 - [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary presented with the exact instruction to give an agent
+- [ ] Handoff message sent to ralph through {{TOOL:peer_send}} (kind `handoff`, naming the handoff bead), or a missing receiver reported in the summary with the manual instruction kept
 
 ## Phase-gate checklist
 
@@ -228,6 +237,7 @@ Deliver a handoff bead and instructions for running ralph.
 - **Skipping the user interview.** The agent has incomplete context. The interview resolves ambiguities that would otherwise surface mid-execution as rework.
 - **Creating horizontal slices.** "All the DB work first, then all the API work" is not tracer bullets. Every task must deliver end-to-end value.
 - **Moving past Phase 2 without user approval.** The task breakdown shapes the entire execution. Do not create beads until the breakdown is approved.
+- **Treating a sent handoff as an accepted one.** A `handoff` message carries no receipt: ralph's status stays `running` or `queued` until it answers `done`, `blocked` or `failed`, so a send that returned is not proof the work started.
 
 ## Common Rationalizations
 
@@ -251,7 +261,7 @@ Deliver a handoff bead and instructions for running ralph.
 - [prd-to-tasks](../../planning/prd-to-tasks/SKILL.md) — load when the PRD is already written and only decomposition is needed.
 - [spec-to-tickets](../../planning/spec-to-tickets/SKILL.md) — load instead when the PRD must become external tickets rather than beads.
 - [create-task](../../planning/create-task/SKILL.md) — Phase 3's per-task bead creation and pipeline expansion; it invokes `classify-bead` internally, so this skill never classifies directly.
-- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by running a separate agent with "Use the ralph skill. Start from bead #<handoff-id>".
+- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by sending ralph a `handoff` message naming the bead, with "Use the ralph skill. Start from bead #<handoff-id>" as the manual fallback when no ralph session is online. Its [REFERENCE.md](../ralph/REFERENCE.md) owns the planner ↔ ralph message convention.
 
 ## Examples
 
@@ -293,3 +303,4 @@ Full bead tree:
 - [ ] Handoff bead tagged `workflow:ralph`
 - [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary includes the exact instruction to give an agent
+- [ ] Handoff message sent to ralph (kind `handoff`, naming the handoff bead) through {{TOOL:peer_send}}; ralph's `done`/`blocked`/`failed` replies were the only evidence of completion, never the send itself