@jaybeeuu/agent-cortex 1.20.0

package/skills/workflow/ralph/REFERENCE.md

@@ -0,0 +1,202 @@
+# Fleet — Reference
+
+Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL.md) for the top-level event loop.
+
+---
+
+## Dispatching a Chore Bead
+
+1. **Claim** the bead: `bd update <id> --claim`.
+2. **Read its `stage:*` label** from `bd show <id>`.
+3. **Load the universal stage runner prompt** from `skills/workflow/run-pipeline-stage/prompts/stage-runner.md`.
+4. **Read the parent task context**: follow the `parent-child` dependency to the parent task bead, run `bd show <parent-id>` to get the full task description.
+5. **Ensure branch + worktree exist for this parent task** (see _Feature branches and worktrees_ below), then note the worktree path — you'll pass it as `cwd` to `task`.
+6. **Fill in the prompt** — replace placeholders with:
+   - Stage from bead label (`stage:<stage>`) for `<stage>`
+   - `bd prime` output (held in memory from initialization)
+   - Parent task description from `bd show <parent-id>`
+   - For `fix` stage: `FILES_CHANGED` from the preceding stage's report (the required changes come from the fix bead's own description — read via `bd show <fix-id>`)
+   - For `verify`, `review`, `document` stages: `SUMMARY` and `FILES_CHANGED` from the preceding stage's report
+   - Bead ID and log file path (`.agent-cortex/ralph/ralph-<bead-id>.log`)
+7. **Call the `task` tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
+8. **Map** the agent ID to the bead ID in memory for lookup on completion.
+
+---
+
+## Feature Branches and Worktrees
+
+For each parent task bead (`<parent-id>`):
+
+1. Determine the parent epic (`<epic-id>`) from the task's `epic:<epic-id>` label.
+2. Ensure epic branch exists (always based on the latest `origin/main`, never local `main`):
+   ```bash
+   git fetch origin
+   git rev-parse --verify epic/<epic-id> >/dev/null 2>&1 || git branch epic/<epic-id> origin/main
+   ```
+3. Ensure feature worktree exists:
+   ```bash
+   git worktree add .agent-cortex/worktrees/<parent-id> -b feature/<parent-id> epic/<epic-id>
+   ```
+   If `.agent-cortex/worktrees/<parent-id>` already exists, reuse it.
+4. All chores for this parent run in `.agent-cortex/worktrees/<parent-id>`. The `feature/<parent-id>` branch is the agent branch for HITL PRs.
+
+---
+
+## Feature PR Gate
+
+When the `document` chore for a parent task completes:
+
+1. Close the `document` chore.
+2. Create or update a feature PR immediately from the agent branch to the feature branch (`feature/<parent-id>` into `epic/<epic-id>`):
+   ```bash
+   gh pr create --base epic/<epic-id> --head feature/<parent-id> --title "[<parent-id>] <task-title>" --body "<summary>"
+   ```
+   If an open PR already exists, update it instead of creating a duplicate.
+3. Report the PR URL in chat as soon as it is created.
+4. Find the child HITL task bead for this parent with label `lifecycle:feature-pr` (created by `create-task`).
+5. Update that HITL bead with the PR URL/status (comment or note) so the reviewer has the link.
+6. Do not schedule new parent features while this HITL PR gate bead remains open.
+7. Once the PR is merged, a human closes the HITL PR gate bead. After that, close the parent feature bead:
+   ```bash
+   bd close <parent-id>
+   ```
+   Only then continue with next parent features.
+
+---
+
+## Fix Loop
+
+When a verify or review stage fails:
+
+1. **Determine the parent task**: look up the chore bead's parent via `bd show <chore-id>` (follow the `parent-child` dependency).
+2. **Count existing fix rounds**: list all chore beads that are children of the parent task with label `stage:fix`. The count of these (including closed ones) is the number of fix rounds already attempted.
+3. **Read `maxFixRounds`** from `skills/planning/create-task/pipeline.json` (held in memory since initialization).
+4. **If fix rounds ≥ maxFixRounds**: close the parent task bead as failed (`bd close <parent-id> --reason "Max fix rounds reached"`). Do not create another fix chore.
+5. **Otherwise, create a fix chore** with the feedback in its description so the fixer agent can read it directly from `bd show`:
+   ```bash
+   fix_id=$(bd create "[<parent-id>] Fix (round <N>)" --type chore \
+     --priority <same as parent> \
+     --description "<CHANGES_REQUESTED list or VERIFY_FAILURES list from the triggering REPORT>" -q)
+   bd tag $fix_id stage:fix
+   bd dep add $fix_id <parent-id> --type parent-child   # fix-chore is child of parent
+   ```
+6. **Find the verify chore** for this parent task (the chore with label `stage:verify` and a `parent-child` dep to the parent).
+7. **Block the verify chore** on the new fix chore:
+   ```bash
+   bd dep add <verify-id> $fix_id --type blocks          # verify waits for fix
+   ```
+8. **Reopen the verify chore**:
+   ```bash
+   bd reopen <verify-id>
+   ```
+   This ensures the fix chore runs first, then verify re-runs automatically when the fix closes.
+
+---
+
+## Log Polling
+
+Run whenever polling is triggered (timer or agent completion):
+
+1. **Query in-flight beads**: `bd list --status=in_progress --type=chore`. Extract each bead's ID and title.
+2. For each in-flight bead, read new lines from its log file (track the next unread line number per bead in memory, starting at 1):
+   ```bash
+   tail -n +<lastLine> .agent-cortex/ralph/ralph-<bead-id>.log 2>/dev/null
+   ```
+3. For each bead that has new lines:
+   - **Post a chat summary** of new key events (stage transitions and notable events — not every line verbatim):
+     ```
+     📋 [bead-id] <title>
+        coding → verifying  (or whatever transition)
+        Tests: 12 passed, 0 failed
+     ```
+   - Update the in-memory line offset for that bead.
+4. If no bead had new lines, post nothing — do not spam the chat with empty polls.
+
+---
+
+## HITL Pause
+
+Proceed here when no chore beads are in-flight, no `stage:*` chore beads are ready, and HITL gate beads are pending (open `lifecycle:feature-pr` beads or epics tagged `awaiting-epic-pr-merge`). Ralph stops rather than burning requests on idle polls.
+
+1. Regenerate `.agent-cortex/ralph/progress.md` one final time — do not delete it.
+2. For each epic whose feature beads are all closed but not yet tagged `awaiting-epic-pr-merge`, open/update an epic PR to main:
+   ```bash
+   gh pr create --base main --head epic/<epic-id> --title "[<epic-id>] Merge epic into main" --body "<epic summary>"
+   ```
+   Tag each epic bead with `awaiting-epic-pr-merge` until merged.
+3. Run:
+   ```bash
+   bd dolt push
+   ```
+4. Collect pending HITL gate beads and their PR URLs:
+   ```bash
+   bd list -l lifecycle:feature-pr -l implementation-type:hitl
+   bd list -l awaiting-epic-pr-merge
+   ```
+   For each bead, run `bd show <id>` to retrieve the PR URL from bead notes.
+5. Output the **Pending Human Action** summary:
+   ```
+   ⏸️  Ralph is paused — human action required before work can continue.
+
+   | Bead ID | Title | Action needed | PR |
+   |---------|-------|---------------|----|
+   | <id>    | <title> | Review and merge feature PR, then close this bead | <url or "–"> |
+   | <id>    | <title> | Review and merge epic PR into main | <url or "–"> |
+   ...
+
+   When you've completed the above, prompt me to continue.
+   ```
+6. **Stop completely.** Do not restart the poll timer. Do not continue the event loop. Wait for the user to re-prompt before doing any further work.
+
+---
+
+## Shutdown
+
+When `bd list --status=in_progress --type=chore` returns no results AND `bd ready` returns no chore beads with `stage:*` labels:
+
+1. Regenerate `.agent-cortex/ralph/progress.md` one final time — do not delete it.
+2. For each epic whose feature beads are all closed, open/update an epic PR to main:
+   ```bash
+   gh pr create --base main --head epic/<epic-id> --title "[<epic-id>] Merge epic into main" --body "<epic summary>"
+   ```
+   Tag each epic bead with `awaiting-epic-pr-merge` until merged.
+3. Run:
+   ```bash
+   bd dolt push
+   ```
+4. If any HITL beads were noted during the session, output:
+   ```
+   All agent work is complete. The following steps require human action before work can continue:
+
+   | Bead ID | Title | Why human action is needed |
+   |---------|-------|---------------------------|
+   | <id>    | <title> | <HITL reason from bead body> |
+   ...
+
+   Run `bd show <id>` for full details on each step.
+   ```
+5. If any epics are tagged `awaiting-epic-pr-merge`, output a **Pending Epic Review** table (epic bead ID, branch, PR URL) and stop.
+6. If no HITL beads remain, output:
+   ```
+   All beads complete.
+   ```
+
+---
+
+## State Files
+
+| File | Purpose |
+|------|---------|
+| `.agent-cortex/ralph/progress.md` | Human-readable snapshot. Regenerate: `workspace="/abs/path"; pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"`. `workspace` must be an **absolute** path — never `.` or `$(pwd)`. **Never hand-edit.** |
+| `.agent-cortex/ralph/ralph-*.log` | Per-bead log files written by subagents (e.g. `.agent-cortex/ralph/ralph-abc-123.log`). |
+
+All orchestration state is derived from beads:
+
+| Question | How to answer |
+|----------|---------------|
+| What is in-flight? | `bd list --status=in_progress --type=chore` |
+| What is ready? | `bd ready` — filter for chores with `stage:*` labels |
+| What stage is a bead in? | Read the `stage:*` label from `bd show <id>` |
+| How many fix rounds? | Count chore beads with label `stage:fix` that are children of the parent task. Read `maxFixRounds` from `skills/planning/create-task/pipeline.json`. |
+| Which features are review-gated? | Find open child task beads labelled `lifecycle:feature-pr` and `implementation-type:hitl` |
+| Which epics are review-gated? | `bd list -l awaiting-epic-pr-merge` |

package/skills/workflow/ralph/SKILL.md

@@ -0,0 +1,105 @@
+---
+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."
+---
+
+# Fleet
+
+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.
+
+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/`.
+
+## Branching and Review Model
+
+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.
+
+See [REFERENCE.md](./REFERENCE.md) for detailed procedures: dispatching, fix loop, log polling, and shutdown.
+
+---
+
+## Initialization
+
+Run once at startup:
+
+1. Run `bd prime`. Hold the full output verbatim in memory — forward it unchanged to every subagent.
+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:
+   - **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**: run `sleep 120` as a background bash process and hold its shellId in memory. **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.
+9. Regenerate `.agent-cortex/ralph/progress.md`:
+   ```bash
+   # workspace must be the absolute path you cd'd into — never . or $(pwd)
+   workspace="/absolute/path/to/worktree"
+   pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"
+   ```
+
+---
+
+## Event Loop
+
+After initialization, wait for background agents or the poll timer to complete. On each completion notification:
+
+### Poll timer completed
+
+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.
+
+### Background agent completed
+
+1. **Poll that bead's log** to flush any final lines.
+2. **Read** the completed agent's full output with `read_agent`.
+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**:
+
+   | 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`.
+
+---
+
+## 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 `task` tool to spawn subagents** — never use 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 `task` tool prompt.
+- **Always** keep the poll timer running — 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.
+- **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.

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

@@ -0,0 +1,151 @@
+---
+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.
+---
+
+# 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.
+
+## Quick Start
+
+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.
+
+## Progress Report
+
+To generate a Markdown snapshot of all bead status (Mermaid dependency graph, active work table, completed list), run:
+
+```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.
+
+## 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):
+
+```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.
+
+## Dispatch Rules
+
+| Stage completed | Condition | Next action |
+|-----------------|-----------|-------------|
+| `code` | — | Run **verify** stage |
+| `verify` | `OUTCOME: SUCCESS` | Run **review** stage |
+| `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 |
+| `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.
+
+## 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:**
+
+```bash
+new_id=$(bd create "[<parent-id>] <title>" --type chore \
+  --description "<feedback content from REPORT>" --priority <parent-priority> -q)
+bd tag $new_id stage:<next-stage>
+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 |
+|---|---|---|---|
+| `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.
+
+## Report Format
+
+Every subagent prompt **must** end with this 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>
+> FILES_CHANGED: <comma-separated list, or "none">
+> OUTCOME: <SUCCESS|BLOCKED>
+> BLOCKING_ISSUES:                              ← only if OUTCOME is BLOCKED
+> - <specific blocking issue>
+> ---
+> ```
+
+Subagents report facts. **Do not ask subagents to suggest or predict the next step.**

package/skills/workflow/run-pipeline-stage/playbooks/code.md

@@ -0,0 +1,17 @@
+# Stage Playbook: coding
+
+## Stage Instructions
+
+1. Invoke `style-tests` before writing tests.
+2. Invoke `tdd` for the red-green-refactor implementation loop.
+3. Invoke `style-code` before making code changes.
+4. Do not add speculative code — only what is required by current tests/requirements.
+5. Make only task-scoped changes; avoid unrelated refactors.
+6. Use context7 for third-party libraries when API/version details matter.
+
+## Stage Outcome
+
+- Set `OUTCOME: SUCCESS` when implementation passes all tests and meets requirements.
+- Set `OUTCOME: BLOCKED` if tests fail or requirements cannot be met.
+- If blocked, list issues under `BLOCKING_ISSUES`.
+- `FILES_CHANGED` lists all modified source/test files.

package/skills/workflow/run-pipeline-stage/playbooks/document.md

@@ -0,0 +1,18 @@
+# Stage Playbook: documenting
+
+## Stage Instructions
+
+1. Invoke the `style-documentation` skill before making documentation changes.
+2. Update docs only when changes introduce:
+   - a key decision,
+   - macro-level behavior change,
+   - a lasting constraint/trade-off.
+3. Prefer updating existing docs; create new docs only when no suitable home exists.
+4. Do not modify source code in this stage.
+
+## Stage Outcome
+
+- Set `OUTCOME: SUCCESS` when docs are updated as needed (or none needed).
+- Set `OUTCOME: BLOCKED` if unable to update or content guidance is unclear.
+- If blocked, list issues under `BLOCKING_ISSUES`.
+- `FILES_CHANGED` lists docs touched, or `none` if no doc change is needed.

package/skills/workflow/run-pipeline-stage/playbooks/fix.md

@@ -0,0 +1,17 @@
+# Stage Playbook: fixing
+
+## Stage Instructions
+
+1. Invoke `style-tests` before writing or updating tests.
+2. Invoke `tdd` to drive any implementation or test changes.
+3. Invoke `style-code` before making code changes.
+4. Apply only the requested changes from the triggering feedback.
+5. Do not perform unrelated modifications.
+6. Preserve task scope and keep fixes minimal and explicit.
+
+## Stage Outcome
+
+- Set `OUTCOME: SUCCESS` when requested changes are successfully applied.
+- Set `OUTCOME: BLOCKED` if unable to apply changes or guidance is unclear.
+- If blocked, list issues under `BLOCKING_ISSUES`.
+- `FILES_CHANGED` lists files updated to address requested changes.

package/skills/workflow/run-pipeline-stage/playbooks/review.md

@@ -0,0 +1,19 @@
+# Stage Playbook: reviewing
+
+## Stage Instructions
+
+1. Invoke the `review-security` skill first.
+2. If security verdict is FAIL:
+   - set `OUTCOME: BLOCKED`,
+   - include each finding under `BLOCKING_ISSUES`,
+   - stop further review.
+3. Invoke `style-code` and `style-tests` for code and test review criteria.
+4. Review for correctness, requirement alignment, and material quality issues.
+5. Do not request changes for stylistic preferences alone.
+
+## Stage Outcome
+
+- Set `OUTCOME: SUCCESS` if approved.
+- Set `OUTCOME: BLOCKED` if changes are requested.
+- If blocked, enumerate required changes under `BLOCKING_ISSUES`.
+- `FILES_CHANGED` should be `none`.

package/skills/workflow/run-pipeline-stage/playbooks/verify.md

@@ -0,0 +1,14 @@
+# Stage Playbook: verifying
+
+## Stage Instructions
+
+1. Discover test/lint/check commands from project conventions (`package.json`, `Makefile`, language configs).
+2. Run each discovered command in project root and capture output.
+3. Do not fix failures in this stage — report only.
+
+## Stage Outcome
+
+- Set `OUTCOME: SUCCESS` when all commands succeed.
+- Set `OUTCOME: BLOCKED` when any command fails.
+- If blocked, summarize failures under `BLOCKING_ISSUES`.
+- `FILES_CHANGED` should be `none`.

package/skills/workflow/run-pipeline-stage/prompts/stage-runner.md

@@ -0,0 +1,20 @@
+## Project context
+Run `bd prime` if you need project-level context (conventions, tech stack, goals).
+
+## Stage metadata
+- Stage: `<stage>`
+- Playbook: `skills/workflow/run-pipeline-stage/playbooks/<stage>.md`
+
+## Bead specification
+<bd show <id> output — verbatim>
+
+## Prior stage context (if any)
+<prior REPORT fields, dependency context, and relevant files>
+
+## Progress log
+Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
+
+## Instructions
+1. Read and follow the playbook file listed above.
+2. Treat the bead as the source-of-truth specification (not a prompt script).
+3. Keep output factual and stage-scoped.