@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/skills/workflow/ralph/SKILL.md

@@ -1,41 +1,41 @@
 ---
 name: ralph
-description: "Run all pending beads end-to-end using parallel subagents with review gates: initialise, dispatch up to 5 concurrent pipeline-stage chores, open and report PRs immediately, then wait for merges before continuing. Use when running the full task backlog with human approval points."
+description: "Run all pending beads end-to-end with up to 5 concurrent pipeline-stage chores in dedicated worktrees, opening review-gated PRs immediately and pausing for human merges. Use when you want to \"run the backlog\", \"run all beads\", or \"run ralph\" with human approval gates."
 ---
 
-# Fleet
+# Ralph
 
-Parallel task orchestration: find ready beads, dispatch them as background subagents, process each outcome through the pipeline (code → verify → review → document, with fix loops on failure), then open review-gated PRs before considering feature work complete.
+Ralph is a parallel orchestration loop. It advances AFK task beads through pipeline-stage chores (`code` → `verify` → `review` → `document`), dispatching each stage as a background subagent in the feature's worktree, then opens review-gated feature and epic PRs and pauses for human merges. Ralph never writes code itself — it dispatches, tracks, and reports.
 
-Orchestration state is derived entirely from beads — there is no separate state file. In-flight work is tracked as chore beads with status `in_progress`. Ready work is discovered via `bd ready`. Pipeline configuration lives in `skills/planning/create-task/pipeline.json`. Stage runner prompt templates live in `skills/workflow/run-pipeline-stage/prompts/` and playbooks in `skills/workflow/run-pipeline-stage/playbooks/`.
+State model: task state lives in beads (ready/in_progress via `bd`); the only local file is `.agent-cortex/ralph/state.json`, holding the poll-timer shellId and the agent-ID→bead mapping. Pipeline configuration comes from `skills/planning/create-task/pipeline.json`, and stage execution belongs to the `run-pipeline-stage` skill.
 
-## Branching and Review Model
+## When to use
 
-1. **Epic integration branch**: each epic runs on `epic/<epic-id>` (base: `origin/main`, never local `main`).
-2. **Feature branch per parent bead**: each AFK parent task runs on `feature/<parent-task-id>`, based from its epic branch. This branch is treated as the **agent branch** for HITL PRs.
-3. **Dedicated worktree per parent bead**: each feature branch uses `.agent-cortex/worktrees/<parent-task-id>`.
-4. **Feature PR gate**: each feature has a child HITL task bead (`lifecycle:feature-pr`) created by `create-task`. When `document` completes, open/update PR `feature/<parent-task-id> -> epic/<epic-id>` (agent-branch → feature branch), report the PR URL immediately, then wait for the HITL PR gate bead to be closed by a human.
-5. **Epic PR gate**: when an epic's feature beads are complete, open/update a PR `epic/<epic-id> -> main` and pause until merged.
+- "Run the backlog", "run all beads", "run ralph", "run everything pending".
+- A planning session has produced classified, unblocked AFK task beads and you want autonomous execution with human review gates.
+- You want the full pipeline (implement → verify → review → document) orchestrated concurrently, with fix loops on failure.
 
-See [REFERENCE.md](./REFERENCE.md) for detailed procedures: dispatching, fix loop, log polling, and shutdown.
+## When NOT to use
 
----
+- Working a single bead or stage inline — use the `run-pipeline-stage` skill instead.
+- Interactive planning, PRDs, or scoping — use the `plan` skill instead.
+- Running as a background or delegated subagent — ralph must be the interactive foreground agent, or it cannot receive completion notifications.
 
-## Initialization
+## Workflow
 
-Run once at startup:
+### 1. Initialize (run once at startup)
 
-1. Run `bd prime`. Hold the full output verbatim in memory — forward it unchanged to every subagent.
+1. Run `bd prime` and hold the output verbatim in memory.
 2. Ensure `.agent-cortex/` and `.agent-cortex/worktrees/` are in the project's `.gitignore` (append any that are missing).
-3. Ensure Ralph's workspace directory exists: `mkdir -p .agent-cortex/ralph`.
-4. Read `skills/planning/create-task/pipeline.json` and hold it in memory — you need `maxFixRounds` for the fix loop.
-5. Run `bd ready` to get the initial list of available beads.
-6. For each available bead:
+3. Create the workspace: `mkdir -p .agent-cortex/ralph`.
+4. Initialize state: write `.agent-cortex/ralph/state.json` with `{ "timerShellId": null, "inflight": [] }`.
+5. Read `skills/planning/create-task/pipeline.json` and hold it in memory — you need its `maxFixRounds` for the fix loop.
+6. Run `bd ready` and classify each available bead:
    - **Chore with a `stage:*` label**: pipeline stage bead — eligible for dispatch.
-   - **Task or other type without an `implementation-type:*` label**: unexpected here — classification is a planning-stage concern already applied by `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note for the shutdown summary.
-   - **Task labelled `implementation-type:hitl`**: skip — record the bead ID for the **Pending Human Action** summary at shutdown.
-7. For each ready chore bead (up to 5), **dispatch** it (see _Dispatching a chore bead_ in REFERENCE.md). Chores for a parent bead must run from that parent's worktree.
-8. **If** any chore beads were dispatched in step 7, start the **poll timer** (Copilot only): run `sleep 120` as a background bash process and hold its shellId in memory. PI has no timer — keep a `wait_for_agents` call outstanding over every in-flight agent ID instead (see the Event Loop note). **Otherwise**, if HITL gate beads are pending (check `bd list -l lifecycle:feature-pr -l implementation-type:hitl` and `bd list -l awaiting-epic-pr-merge`), proceed to **HITL Pause** (see REFERENCE.md) immediately.
+   - **Task or other type without an `implementation-type:*` label**: unexpected here — classification happens at planning time via `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note it for the shutdown summary.
+   - **Task labelled `implementation-type:hitl`**: skip — record the ID for the Pending Human Action summary at shutdown.
+7. For each ready chore bead (up to 5), dispatch it from its parent's feature worktree (see _Dispatching a chore bead_ in REFERENCE.md — create branches/worktrees first).
+8. Hand over to your harness's completion-detection mechanism: Copilot keeps a `sleep 120` poll timer running in the background; PI keeps a {{TOOL:wait_for_agents}} call outstanding over every in-flight agent ID. If no chore was dispatched and HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge`), go straight to HITL Pause (REFERENCE.md).
 9. Regenerate `.agent-cortex/ralph/progress.md`:
    ```bash
    # workspace must be the absolute path you cd'd into — never . or $(pwd)
@@ -43,63 +43,77 @@ Run once at startup:
    pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"
    ```
 
----
+### 2. Event loop
 
-## Event Loop
+On each completion notification (background agent finished, or the poll timer fired):
 
-After initialization, wait for background agents or the poll timer to complete. Completion detection is harness-specific: the `sleep 120` poll timer described below is the **Copilot** mechanism. **PI** replaces it with the blocking `wait_for_agents` tool — it returns as soon as any in-flight agent finishes, so each return plays the role of a poll-timer tick with its completed-agent result attached; there is no timer to start or kill on PI. On each completion notification:
+1. Poll that parent's log for new lines — `tail -n +<nextLine> .agent-cortex/ralph/ralph-<parent-id>.log` (logs are keyed by parent bead ID, so every stage of a feature shares one file) — and post only new key events (stage transitions, test/lint results), never empty updates.
+2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome.
+3. Close the chore bead: `bd close <bead-id>`.
+4. Advance the parent per the dispatch table:
 
-### Poll timer completed
+   | Stage completed | Condition | Next action |
+   |-----------------|-----------|-------------|
+   | `code` | — | Closing the code chore unblocks the verify chore |
+   | `fix` | — | Closing the fix chore unblocks the verify chore |
+   | `verify` | `VERIFY_OUTCOME: PASS` | Closing the verify chore unblocks the review chore |
+   | `verify` | `VERIFY_OUTCOME: FAIL` | Run the fix loop (REFERENCE.md) |
+   | `review` | `REVIEW_OUTCOME: APPROVED` | Closing the review chore unblocks the document chore |
+   | `review` | `REVIEW_OUTCOME: CHANGES_REQUESTED` | Run the fix loop (REFERENCE.md) |
+   | `document` | — | Open/update the feature PR now (`feature/<parent-id>` → its base branch), report the URL, and update the child HITL gate bead (`lifecycle:feature-pr`). Wait for a human to close that bead after merge, then `bd close <parent-id>` |
 
-1. **Poll all in-flight bead logs** (see _Log polling_ in REFERENCE.md).
-2. Regenerate `.agent-cortex/ralph/progress.md`.
-3. **HITL pause check**: if `bd list --status=in_progress --type=chore` returns empty AND `bd ready` has no `stage:*` chore beads AND HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge` returns results), proceed to **HITL Pause** (see REFERENCE.md) — do **not** restart the timer.
-4. **Otherwise**: restart the timer: run `sleep 120` as a new background bash process, hold its shellId in memory.
+5. Run `bd ready` and dispatch new ready `stage:*` chore beads while the in-flight count (`bd list --status=in_progress --type=chore`) is under 5. Do not schedule new parent features while any `lifecycle:feature-pr` HITL gate bead is open.
+6. If no chores are in-flight and `bd ready` returns no `stage:*` chores, proceed to HITL Pause (REFERENCE.md) when HITL gate beads are pending, otherwise to Shutdown (REFERENCE.md).
+7. Regenerate `.agent-cortex/ralph/progress.md`.
 
-### Background agent completed
+### 3. Branching and review model
 
-1. **Poll that bead's log** to flush any final lines.
-2. **Read** the completed agent's full output with {{TOOL:read_agent}} (on PI the completed result arrives in the `wait_for_agents` response; read_agent remains a fallback for a specific result).
-3. **Identify the bead**: parse the `---REPORT---` block for `BEAD_ID` and `STAGE_COMPLETED`.
-4. **Close** the chore bead: `bd close <bead-id>`.
-5. **Handle stage outcome**:
+- **Single-feature epics** (exactly one feature task child — count with `bd children <epic-id>`, excluding chores): no epic branch. `feature/<parent-id>` is based directly on `origin/main`, its feature PR targets `main`, and no epic PR is opened.
+- **Multi-feature epics** (two or more feature task children): the epic runs on `epic/<epic-id>`, based on `origin/main` — never local `main`. Each AFK parent task runs on `feature/<parent-id>`, based from its epic branch, in the dedicated worktree `.agent-cortex/worktrees/<parent-id>`.
+- Feature PR gate: `feature/<parent-id>` → `epic/<epic-id>` (or → `main` for single-feature epics). Epic PR gate: `epic/<epic-id>` → `main`.
+- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_).
 
-   | Stage completed | Condition | Next action |
-   |-----------------|-----------|-------------|
-   | `code` | — | Closing the code chore unblocks the verify chore. |
-   | `fix` | — | Closing the fix chore unblocks the verify chore. |
-   | `verify` | `VERIFY_OUTCOME: PASS` | Closing the verify chore unblocks the review chore. |
-   | `verify` | `VERIFY_OUTCOME: FAIL` | Run the **fix loop** (see REFERENCE.md). |
-   | `review` | `REVIEW_OUTCOME: APPROVED` | Closing the review chore unblocks the document chore. |
-   | `review` | `REVIEW_OUTCOME: CHANGES_REQUESTED` | Run the **fix loop** (see REFERENCE.md). |
-   | `document` | — | Open/update feature PR immediately (`feature/<parent-id> -> epic/<epic-id>`), report the PR URL, then update the child HITL PR gate bead (`lifecycle:feature-pr`) with the PR URL/status. Wait for human to close that HITL bead after merge, then close the parent task bead. |
-
-6. **Check for newly ready beads**: run `bd ready` and inspect results:
-    - **Chore beads with `stage:*` label**: dispatch if in-flight count (from `bd list --status=in_progress --type=chore`) is < 5.
-    - **Task beads without `implementation-type:*` label**: unexpected here — classification happens at planning time via `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note for shutdown.
-   - If any feature PR gate bead (`lifecycle:feature-pr`, `implementation-type:hitl`) is open, do **not** schedule new parent features. Keep working only already in-flight chores.
-7. **Check shutdown or pause**: if `bd list --status=in_progress --type=chore` returns no results AND `bd ready` returns no chore beads with `stage:*` labels:
-   - If HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge` returns results), proceed to **HITL Pause** (see REFERENCE.md).
-   - Otherwise, proceed to **Shutdown** (see REFERENCE.md).
-8. Regenerate `.agent-cortex/ralph/progress.md`.
+### 4. HITL pause and shutdown
 
----
+- **HITL Pause** — when no chores are in-flight, none ready, and HITL gate beads are pending: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag each epic `awaiting-epic-pr-merge` (single-feature epics need none — their feature PRs already target `main`), run `bd dolt push`, output the Pending Human Action table, then stop completely until re-prompted.
+- **Shutdown** — when all work is complete: regenerate `progress.md`, open/update epic PRs to `main` for multi-feature epics and tag them (single-feature epics need none), run `bd dolt push`, then output the Pending Human Action / Needs Refinement / cap-blocked / Pending Epic Review summaries that apply, or "All beads complete."
+
+## Red Flags
+
+- Running as a background or delegated subagent instead of the interactive foreground agent.
+- Spawning a stage runner via {{TOOL:bash}} or running a stage inline instead of {{TOOL:task}}.
+- Editing bead files directly instead of using `bd` commands.
+- Auto-merging a PR, or continuing past a feature/epic gate before a human merge.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll just run this one stage inline" | An orchestrator that executes stages stops being an orchestrator — the review gates exist to catch exactly that shortcut. |
+| "One more task in flight won't hurt" | The 5-task cap bounds log polling, state bookkeeping, and PR sequencing; exceeding it loses track of in-flight work. |
+| "The review passed, so I can merge" | Feature and epic PR merges are human-controlled; the gate exists so a person sees every change. |
+
+## Philosophy / rationale
+
+- Orchestration state derives from beads so a crash loses nothing but an in-memory ID mapping: `state.json` holds only the poll-timer shellId and the agent-ID→bead mapping, never task state.
+- Classification happens up-front at planning time (`create-task`), so the loop can trust `bd ready` instead of re-interpreting each bead's intent.
+- Human review gates are non-negotiable because agent-authored changes still need a person to merge them.
+
+## Phase-gate checklists
+
+- [ ] Init complete: `bd prime` held, gitignore entries present, workspace and state.json created, pipeline.json read, first `bd ready` classified, first chores dispatched.
+- [ ] Event loop handed off: completion-detection mechanism running (or HITL Pause/Shutdown started) and `progress.md` regenerated.
+
+## Cross-skill references
+
+- The `run-pipeline-stage` skill owns the stage-runner prompt, per-stage playbooks, the `---REPORT---` format, and fix-loop feedback beads — read it before dispatching any stage.
+- The `create-task` skill owns `pipeline.json` and creates the `lifecycle:feature-pr` HITL gate beads.
+- Do not invoke `classify-bead` from this loop — classification was already applied at planning time.
+
+## Verification checklist
 
-## Constraints
-
-- **Always** run in **foreground** (interactive) mode. If you find yourself executing as a background task, immediately surface a warning to the user and ask them to re-run you in foreground mode.
-- **Never** write, edit, or create source code or documentation yourself.
-- **Never** edit bead task files directly — only use `bd` commands.
-- **ALWAYS call the {{TOOL:task}} tool to spawn subagents** — never use {{TOOL:bash}}, never run stages inline, never use any other tool. This is your only spawning mechanism.
-- **Always** derive orchestration state from beads — do not maintain a separate state file.
-- **Always** include the full `bd prime` output verbatim in every {{TOOL:task}} tool prompt.
-- **Always** keep the poll timer running (Copilot) — restart it immediately after it fires — **unless** the HITL pause condition is met (no chores in-flight, no `stage:*` chores ready, HITL gate beads pending), in which case proceed to **HITL Pause** (see REFERENCE.md) and stop instead. On PI there is no timer to keep alive — always keep one `wait_for_agents` call outstanding while agents are in-flight.
-- **Never** post empty poll updates to chat — only surface new log content.
-- **Max 5** tasks in-flight at once.
-- **Max fix rounds** per task as defined by `maxFixRounds` in `skills/planning/create-task/pipeline.json`.
-- **Always** execute chore subagents from the parent feature worktree (`.agent-cortex/worktrees/<parent-id>`), never from repo root.
-- **Never** auto-merge PRs. Merges are human-controlled.
-- **Only continue past a feature review gate after the feature PR HITL task bead is closed by a human (after merge into the epic branch).**
-- **Only continue past an epic review gate after the epic PR is merged into `main`.**
-- **When a feature hits the HITL PR gate, push and open the PR immediately and report the URL — do not wait for explicit approval to push or create the PR.**
-- **Always** bump the patch version in `plugin.json` as part of any commit that changes agent or skill files.
+- [ ] Init ran once with observable results: `state.json` exists, `bd ready` was parsed, and the first chore beads are claimed.
+- [ ] Every stage runner was spawned with {{TOOL:task}} from the parent's feature worktree, with the `---REPORT---` instruction in its prompt.
+- [ ] In-flight count never exceeded 5, and fix loops respect `maxFixRounds` from `pipeline.json`.
+- [ ] Feature and epic PRs were pushed and reported immediately at their gates, and nothing was auto-merged.
+- [ ] `bd dolt push` and a final `progress.md` regeneration ran before HITL Pause/Shutdown, and the chat received no empty poll updates.

package/skills/workflow/run-pipeline-stage/REFERENCE.md

@@ -0,0 +1,22 @@
+# Reference — run-pipeline-stage
+
+Rarely-needed detail for the `run-pipeline-stage` skill. The main workflow lives in
+`SKILL.md`; this file covers maintenance of its scripts package only.
+
+## Scripts package maintenance
+
+The scripts package (`skills/workflow/run-pipeline-stage/scripts`, a private workspace
+package `@agent-cortex/run-pipeline-stage-scripts`) backs the progress-doc generator used
+in `SKILL.md` step 6.
+
+Typecheck and test it with:
+
+```bash
+pnpm --prefix skills/workflow/run-pipeline-stage/scripts typecheck
+pnpm --prefix skills/workflow/run-pipeline-stage/scripts test
+```
+
+### Data-fetch / renderer split
+
+The data-fetch layer (`parseBdList` / `parseBdShow`) is kept separate from the renderer
+so the `bd` output format can be swapped without re-fetching.

package/skills/workflow/run-pipeline-stage/SKILL.md

@@ -1,120 +1,63 @@
 ---
 name: run-pipeline-stage
-description: Execute a single pipeline stage for a task. Use when you want to work through beads inline, pick up a specific stage bead, or work without the full ralph parallel orchestrator.
+description: Execute a single pipeline stage for a bead (code, verify, review, document) via its playbook and dispatch rules, reporting the outcome in a fixed REPORT shape. Use when you want to "work through beads inline", "pick up a specific stage bead", or run one stage "without the full ralph orchestrator".
 ---
 
 # Run Pipeline Stage
 
-Execute a single pipeline stage. Stage beads (`code`, `verify`, `review`, `document`) are created by the `create-task` skill from the pipeline definition in `skills/planning/create-task/pipeline.json`; this skill handles executing one at a time.
+Stage beads (`stage:code`, `stage:verify`, `stage:review`, `stage:document`, `stage:fix`) are created by the `create-task` skill from the pipeline definition in `skills/planning/create-task/pipeline.json`. This skill executes one stage at a time and reports the outcome.
 
-## Quick Start
+## When to use
 
-1. Run `bd prime` and hold the output for your own context. Subagents you spawn can run `bd prime` themselves if they need project context.
-2. If no bead is specified, run `bd ready` and ask the user which to work on.
-3. Claim the bead with `bd update <id> --claim`.
-4. Read the bead's `stage:*` label to determine which stage to execute.
-5. Load the universal stage runner prompt from `skills/workflow/run-pipeline-stage/prompts/stage-runner.md`.
-6. Populate `<stage>` (from the bead's `stage:*` label), and follow `skills/workflow/run-pipeline-stage/playbooks/<stage>.md` for stage-specific behavior before spawning a subagent.
+- "Work through beads inline" instead of running a full ralph fleet.
+- "Pick up a specific stage bead" and execute it to a REPORT.
+- Re-run a stage after a `stage:fix` chore completes.
+- Follow a stage's playbook discipline with the right stage skills — tests, style, security, documentation.
 
-## Progress Report
+## When NOT to use
 
-To generate a Markdown snapshot of all bead status (Mermaid dependency graph, active work table, completed list), run:
+- Running many beads concurrently — that is the `ralph` skill.
+- Creating or planning beads — use `create-task` or `plan`.
+- Exploratory bead bookkeeping without a stage — that is `bd-tool`.
 
-```bash
-# workspace must be the absolute path of the project — never . or $(pwd)
-workspace="/absolute/path/to/project"
-pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace"
-```
-
-To typecheck or test the scripts package:
-
-```bash
-pnpm --prefix skills/workflow/run-pipeline-stage/scripts typecheck
-pnpm --prefix skills/workflow/run-pipeline-stage/scripts test
-```
-
-The data-fetch layer (`parseBdList` / `parseBdShow`) is kept separate from the renderer so the output format can be swapped without re-fetching.
+## Workflow
 
-## Progress Logging
-
-When running inside the ralph orchestrator, subagents must write structured progress lines to `.agent-cortex/ralph/ralph-{bead-id}.log` (appending) so ralph can surface live updates. The bead ID and log file path are provided in each prompt.
-
-**Format** — one entry per line:
-```
-[ISO-timestamp] [bead-id] [stage] message
-```
-
-**When to log:**
-- Stage start: `[...] [abc-123] [code] Stage started`
-- Stage transitions: `[...] [abc-123] [code→verify] Stage complete`, `[...] [abc-123] [verify→review] PASS`, `[...] [abc-123] [verify→fix] FAIL`
-- Key events only:
-  - Test results: `Tests: 12 passed, 0 failed`
-  - Lint result: `Lint: PASS` or `Lint: FAIL — <brief reason>`
-  - Build errors: `Build failed: <brief reason>`
-  - Security scan result: `Security scan: PASS` or `Security scan: FAIL — <finding>`
-  - Any significant blocker or decision
-
-**How to write a log line:**
-```bash
-mkdir -p .agent-cortex/ralph && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [bead-id] [stage] message" >> .agent-cortex/ralph/ralph-bead-id.log
-```
-
-Do not log every file read or minor action — only transitions and key events.
-
-## Pipeline
-
-The canonical pipeline is defined in `skills/planning/create-task/pipeline.json`. Current stages:
-
-| Stage | Notes |
-|-------|-------|
-| **code** | Implement the task using a test-driven approach |
-| **verify** | Run the project's test and lint commands and report the outcome |
-| **review** | Review the implementation for security, correctness, and alignment with task requirements |
-| **document** | Review changes and update documentation if key decisions, behaviour changes, or constraints were introduced |
-
-The fix loop (on verify or review failure) is controlled by `maxFixRounds` in `pipeline.json`.
-
-### Stage Transitions
-
-Before dispatching a subagent for any stage, run these two commands (replacing `<id>` and `<stage>` with the bead ID and the stage about to start):
+1. Run `bd prime` and hold the output; subagents can run it themselves if they need context.
+2. If no bead was specified, run `bd ready` and ask the user which to work on.
+3. Claim the bead with `bd update <id> --claim` — the bead, not the prompt, is the source of truth.
+4. Read the bead's `stage:*` label — it names the stage to execute.
+5. Load the universal stage-runner prompt (`skills/workflow/run-pipeline-stage/prompts/stage-runner.md`), populate `<stage>`, and read the matching playbook (`skills/workflow/run-pipeline-stage/playbooks/<stage>.md`) for stage-specific rules.
+6. Tag the stage and regenerate the progress doc so pairing sessions stay current:
 
 ```bash
 bd tag <id> stage:<stage>
 # workspace must be the absolute path of the worktree — never . or $(pwd)
 workspace="/absolute/path/to/worktree"
-mkdir -p "$workspace/.agent-cortex/ralph"
 pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"
 ```
 
-This tags the bead with its current stage (beads are the source of truth for stage progress) and regenerates the progress doc so any inline pairing session stays current.
+7. Dispatch one subagent per stage with the composed prompt — spawn it with {{TOOL:task}} and end the prompt with the REPORT contract below.
+8. Route the REPORT through the Dispatch Rules: advance to the next stage, create a feedback bead, or close the parent.
+
+Each step leaves observable state — a claimed bead, a `stage:` tag, a regenerated progress doc, and a REPORT that drives the next action.
 
 ## Dispatch Rules
 
-| Stage completed | Condition | Next action |
-|-----------------|-----------|-------------|
-| `code` | — | Run **verify** stage |
-| `verify` | `OUTCOME: SUCCESS` | Run **review** stage |
+| Stage complete | Condition | Next action |
+|---|---|---|
+| `code` | — | Run **verify** |
+| `verify` | `OUTCOME: SUCCESS` | Run **review** |
 | `verify` | `OUTCOME: BLOCKED` | Create a `stage:fix` chore (see _Feedback Beads_) |
-| `review` | `OUTCOME: SUCCESS` | Run **document** stage |
-| `review` | `OUTCOME: BLOCKED` and fixRounds < maxFixRounds | Create a `stage:fix` chore (see _Feedback Beads_); increment fixRounds |
-| `review` | `OUTCOME: BLOCKED` and fixRounds ≥ maxFixRounds | `bd update <parent-id> --status blocked --notes "max fix rounds reached"` — record for shutdown |
+| `review` | `OUTCOME: SUCCESS` | Run **document** |
+| `review` | `OUTCOME: BLOCKED` and fixRounds < maxFixRounds | Create a `stage:fix` chore; increment fixRounds |
+| `review` | `OUTCOME: BLOCKED` and fixRounds ≥ maxFixRounds | `bd update <parent-id> --status blocked --notes "max fix rounds reached"`; record for shutdown |
 | `document` | — | `bd close <id>` — done |
 
-`maxFixRounds` is read from `skills/planning/create-task/pipeline.json` (`maxFixRounds` field, currently `4`).
-
-### Fix loop flow
-
-When a `stage:fix` chore completes, the next stage depends on which stage triggered the fix:
-- **Fix after verify failure** → re-run **verify**
-- **Fix after review failure** → re-run **review**
-
-The orchestrator (ralph or inline agent) tracks fix rounds and re-dispatches the original stage after the fix chore completes.
+`maxFixRounds` is read from `skills/planning/create-task/pipeline.json` (currently `4`). A fix chore re-runs the stage that failed — fix after verify → verify; fix after review → review.
 
 ## Feedback Beads
 
-When a stage reports a failure or rejection, the orchestrator creates a new chore bead whose description contains the feedback. This keeps feedback durable and visible, and makes the orchestrator's dispatch path uniform — it just picks up whatever `bd ready` returns.
-
-**Create the bead:**
+On stage failure, create a chore bead whose description carries the feedback so the orchestrator's dispatch path stays uniform — it just picks up whatever `bd ready` returns:
 
 ```bash
 new_id=$(bd create "[<parent-id>] <title>" --type chore \
@@ -124,23 +67,37 @@ bd tag $new_id workflow:ralph
 bd dep add $new_id <parent-id> --type parent-child
 ```
 
-| Triggering outcome | Suggested title | Next stage tag | Feedback content to put in description |
+| Triggering outcome | Suggested title | Next stage tag | Description content |
 |---|---|---|---|
 | `OUTCOME: BLOCKED` from verify | `Fix: verify failures` | `stage:code` | Full BLOCKING_ISSUES list |
 | `OUTCOME: BLOCKED` from review | `Fix: reviewer feedback` | `stage:fix` | Full BLOCKING_ISSUES list |
 
-After creating the feedback bead, do **not** dispatch a new agent immediately — the bead will appear in `bd ready` on the next cycle and be dispatched through the normal scheduling path. The stage that consumed the feedback from the REPORT is now finished; its agent result has been processed.
+Do not dispatch a new agent right after creating the feedback bead — it appears in `bd ready` on the next cycle and flows through the normal scheduling path.
+
+## Progress Logging
+
+Inside the ralph orchestrator, write one structured line per transition or key event to `.agent-cortex/ralph/ralph-{bead-id}.log`:
+
+```
+[ISO-timestamp] [bead-id] [stage] message
+```
+
+Log stage starts and completes, test/lint/build/security results, blockers, and decisions — not file reads or minor actions.
+
+```bash
+mkdir -p .agent-cortex/ralph && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [bead-id] [stage] message" >> .agent-cortex/ralph/ralph-bead-id.log
+```
 
 ## Report Format
 
-Every subagent prompt **must** end with this instruction:
+Every subagent prompt must end with the REPORT instruction:
 
 > End your response with a `---REPORT---` block in exactly this format:
 > ```
 > ---REPORT---
 > BEAD_ID: <id>
 > STAGE_COMPLETED: <code|verify|review|document>
-> SUMMARY: <2–3 sentence summary of what was done>
+> SUMMARY: <2-3 sentence summary of what was done>
 > FILES_CHANGED: <comma-separated list, or "none">
 > OUTCOME: <SUCCESS|BLOCKED>
 > BLOCKING_ISSUES:                              ← only if OUTCOME is BLOCKED
@@ -148,4 +105,45 @@ Every subagent prompt **must** end with this instruction:
 > ---
 > ```
 
-Subagents report facts. **Do not ask subagents to suggest or predict the next step.**
+Subagents report facts — do not ask them to suggest or predict the next step.
+
+## Red Flags
+
+- Dispatching a subagent before tagging the stage — beads are the only source of truth for stage progress.
+- Composing a subagent prompt without the REPORT contract — the output cannot be routed.
+- Creating a feedback bead and then dispatching anyway — bypasses the fix-round accounting and parent-child dependency graph.
+- Skipping the playbook "because the stage is simple" — playbooks carry the per-stage discipline the pipeline relies on.
+
+## Common Rationalizations
+
+| "The stage is small — I'll just run it directly" | The stage skills and playbook keep output conformant; skipping them produces work that loops back as a fix chore. |
+| "I'll dispatch the fix right away — faster than a chore bead" | Feedback beads keep dispatch uniform and durable; direct re-dispatch breaks fix-round accounting and the dependency graph. |
+| "The stage is obvious from the prompt — no tag needed" | Beads are the source of truth; prompt drift desynchronises the progress doc, the log, and downstream dispatch. |
+
+## Cross-skill references
+
+- `create-task` owns `pipeline.json` — stages, `maxFixRounds`, and the stage templates.
+- `bd-tool` covers bead mechanics beyond the commands in this skill.
+- `ralph` runs many stage beads concurrently and consumes this skill's log and REPORT contracts.
+- Playbooks delegate to stage skills: `tdd`/`style-code`/`style-tests` (code), `review-security` (review), `style-documentation` (document).
+
+## Examples
+
+- Input: a `stage:verify` bead reporting `OUTCOME: BLOCKED` with two failing tests → Output: a `Fix: verify failures` chore tagged `stage:code` whose description lists both failures; verify closes and the chore is picked up on the next `bd ready` cycle.
+- Input: a `stage:document` bead reporting `OUTCOME: SUCCESS` → Output: the parent bead is closed with `bd close <id>` and that task's pipeline ends.
+
+## Philosophy / rationale
+
+- Beads hold all orchestration state — there is no separate state file to drift out of sync.
+- Subagents return facts in one fixed REPORT shape so routing stays mechanical across stages and harnesses.
+- Feedback as beads, not direct re-dispatches, puts every agent on a single scheduling path and keeps every decision visible in the dependency graph.
+
+## Verification checklist
+
+- [ ] Bead claimed (`bd update <id> --claim`) before any executor works it.
+- [ ] `bd tag <id> stage:<stage>` run and progress doc regenerated before dispatch.
+- [ ] Correct playbook read and followed for the stage; stage skills invoked where the playbook says.
+- [ ] Composed prompt ends with the complete REPORT contract block.
+- [ ] Progress log lines written for every stage transition and key result.
+- [ ] REPORT routed per the Dispatch Rules — next stage, feedback bead, or `bd close <id>`.
+- [ ] Feedback beads carry the full BLOCKING_ISSUES content and the parent-child dependency.

package/skills/workflow/run-pipeline-stage/scripts/generate-progress.test.ts

@@ -1,7 +1,5 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import {
   parseListLine,
   parseBdList,
@@ -144,6 +142,12 @@ describe('parseListLine', () => {
     assert.deepEqual(result, { id: 'proj-eee', status: 'deferred', title: 'Deferred task' });
   });
 
+  it('parses current bd list format without the priority marker column', () => {
+    // Current bd emits `{STATUS} {ID} P{N} {TITLE}`; the `●` before P{N} is legacy.
+    const result = parseListLine('◐ proj-bbb P2 Second task');
+    assert.deepEqual(result, { id: 'proj-bbb', status: 'in_progress', title: 'Second task' });
+  });
+
   it('returns null for separator/summary lines', () => {
     assert.equal(parseListLine('---'), null);
     assert.equal(parseListLine('Total: 5 issues'), null);
@@ -676,108 +680,3 @@ describe('fetchBeads', () => {
     assert.equal(beads.filter((b) => b.id === 'proj-child1').length, 1);
   });
 });
-
-// ─── Behavior 11: plugin session-start hook wiring ────────────────────────────
-
-describe('plugin session-start hook wiring', () => {
-  const repoRoot = join(import.meta.dirname, '..', '..', '..');
-
-  it('declares a hooks config path in plugin.json', () => {
-    const pluginJsonRaw = readFileSync(join(repoRoot, 'plugin.json'), 'utf8');
-    const pluginJson = JSON.parse(pluginJsonRaw) as { hooks?: unknown };
-    assert.equal(pluginJson.hooks, 'hooks.json');
-  });
-
-  it('defines a sessionStart prompt hook that injects baseline context', () => {
-    const hooksJsonRaw = readFileSync(join(repoRoot, 'hooks.json'), 'utf8');
-    const hooksJson = JSON.parse(hooksJsonRaw) as {
-      hooks?: { sessionStart?: Array<{ type?: unknown; prompt?: unknown }> };
-    };
-    assert.ok(Array.isArray(hooksJson.hooks?.sessionStart));
-    const sessionStartHooks = hooksJson.hooks?.sessionStart ?? [];
-    assert.ok(
-      sessionStartHooks.some(
-        (entry) => entry.type === 'prompt' && typeof entry.prompt === 'string' && entry.prompt.length > 0,
-      ),
-    );
-  });
-});
-
-// ─── Behavior 12: skill anatomy documentation contracts ───────────────────────
-
-describe('skill anatomy documentation contracts', () => {
-  const repoRoot = join(import.meta.dirname, '..', '..', '..');
-
-  it('includes the canonical skill anatomy doc', () => {
-    const anatomyDoc = readFileSync(join(repoRoot, 'docs', 'skills', 'skill-anatomy.md'), 'utf8');
-    assert.ok(anatomyDoc.length > 0);
-  });
-
-  it('documents canonical anatomy and an annotated template acceptance checklist', () => {
-    const anatomyDoc = readFileSync(join(repoRoot, 'docs', 'skills', 'skill-anatomy.md'), 'utf8');
-    assert.match(anatomyDoc, /canonical skill anatomy/i);
-    assert.match(anatomyDoc, /annotated template/i);
-    assert.match(anatomyDoc, /acceptance criteria|checklist/i);
-  });
-});
-
-// ─── Behavior 13: skill anatomy expanded documentation requirements ────────────
-
-describe('skill anatomy expanded documentation requirements', () => {
-  const repoRoot = join(import.meta.dirname, '..', '..', '..');
-
-  it('documents required facets for each optional section', () => {
-    const anatomyDoc = readFileSync(join(repoRoot, 'docs', 'skills', 'skill-anatomy.md'), 'utf8');
-    assert.match(anatomyDoc, /optional sections/i);
-    assert.match(anatomyDoc, /what it is/i);
-    assert.match(anatomyDoc, /example snippet/i);
-    assert.match(anatomyDoc, /when to include/i);
-    assert.match(anatomyDoc, /when to omit/i);
-  });
-
-  it('requires placement of "When NOT to use" adjacent to "When to use"', () => {
-    const anatomyDoc = readFileSync(join(repoRoot, 'docs', 'skills', 'skill-anatomy.md'), 'utf8');
-    assert.match(anatomyDoc, /##\s+When to use[\s\S]{0,400}##\s+When NOT to use/i);
-  });
-
-  it('keeps the full annotated SKILL.md template at the end of the document', () => {
-    const anatomyDoc = readFileSync(join(repoRoot, 'docs', 'skills', 'skill-anatomy.md'), 'utf8').trimEnd();
-    assert.match(anatomyDoc, /##\s+Annotated template[\s\S]*```md[\s\S]*```$/i);
-  });
-});
-
-// ─── Behavior 15: research doc promotion/linking contracts ─────────────────────
-
-describe('research doc promotion/linking contracts', () => {
-  const repoRoot = join(import.meta.dirname, '..', '..', '..');
-
-  it('links each research doc from docs/inspirations.md and marks each as promoted', () => {
-    const inspirationsDoc = readFileSync(join(repoRoot, 'docs', 'inspirations.md'), 'utf8');
-    const researchDir = join(repoRoot, 'docs', 'research');
-    const researchFiles = readdirSync(researchDir).filter((fileName) => fileName.endsWith('.md'));
-
-    for (const researchFile of researchFiles) {
-      assert.match(inspirationsDoc, new RegExp(`\\(research\\/${researchFile.replace('.', '\\.')}\\)`));
-      const researchDoc = readFileSync(join(researchDir, researchFile), 'utf8');
-      assert.match(researchDoc, /promoted research note/i);
-      assert.match(researchDoc, /\[Inspirations\]\(\.\.\/inspirations\.md\)/i);
-    }
-  });
-
-  it('does not keep promoted research docs in .agent-cortex/working-docs (true move, not copy)', () => {
-    const researchDir = join(repoRoot, 'docs', 'research');
-    const researchFiles = readdirSync(researchDir).filter((fileName) => fileName.endsWith('.md'));
-    const repoWorkingDocsDir = join(repoRoot, '.agent-cortex', 'working-docs');
-    const workingDocSearchRoots = [repoWorkingDocsDir, join(repoWorkingDocsDir, 'research')];
-
-    for (const workingDocsDir of workingDocSearchRoots) {
-      if (!existsSync(workingDocsDir)) {
-        continue;
-      }
-
-      for (const researchFile of researchFiles) {
-        assert.equal(existsSync(join(workingDocsDir, researchFile)), false);
-      }
-    }
-  });
-});