@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

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

@@ -1,65 +1,50 @@
 ---
 name: init-beads
-description: Install and initialise the beads (bd) task-tracker in the current project using stealth mode. Use when the user wants to set up beads, install bd, initialise beads, or mentions "bd init".
+description: Install and initialise the beads (bd) task-tracker in the current project using stealth mode. Use when the user wants to "set up beads", "install bd", "initialise beads", or mentions "bd init".
 ---
 
 # Init Beads
 
-Install and initialise the `bd` CLI task tracker in the current project. Prefer stealth mode — minimise commits to the main repo and questions to the user.
+Install and initialise the `bd` CLI task tracker in the current project, running in stealth mode: minimise commits to the main repo, git hooks, and questions to the user.
 
-## Quick start
+## When to use
 
-```bash
-# Install bd if missing
-brew install beads          # macOS/Linux (preferred)
-npm install -g @beads/bd    # fallback
+- The user asks to "set up beads", "install bd", "initialise beads", or "run bd init" in a project — or mentions beads tracking with no setup present.
+- A project has no `.beads/` directory yet and the user wants task tracking enabled.
 
-# Initialise in the project (stealth)
-bd init --quiet --stealth
-```
+## When NOT to use
+
+- The project already has `.beads/`, or the user wants to work with existing beads rather than set them up — use `bd-tool` instead.
+- The user explicitly asks for git hooks or an interactive wizard — `bd init --stealth` deliberately skips both.
 
 ## Workflow
 
 ### 1. Check if `bd` is installed
 
-```bash
-which bd || bd version
-```
-
-If missing, install silently:
+Run `which bd || bd version`. If missing, install silently — prefer Homebrew → npm → script, detect the best method from the environment, and decide without asking:
 
 | Platform | Command |
-|----------|---------|
+|---|---|
 | macOS / Linux (Homebrew) | `brew install beads` |
 | npm available | `npm install -g @beads/bd` |
 | Go available | `go install github.com/steveyegge/beads/cmd/bd@latest` |
 | Any (script) | `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh \| bash` |
 
-Prefer Homebrew → npm → script. Do NOT ask the user which method to use — detect and decide.
-
 ### 2. Check if beads is already initialised
 
-```bash
-bd version 2>/dev/null && ls .beads/ 2>/dev/null
-```
-
-If `.beads/` already exists, skip `bd init` and tell the user.
-
-### 3. Initialise beads
+Run `bd version 2>/dev/null && ls .beads/ 2>/dev/null`. If `.beads/` exists, skip `bd init` and tell the user beads is already set up.
 
-Always use `--quiet --stealth`:
+### 3. Initialise beads in stealth mode
 
 ```bash
 bd init --quiet --stealth
 ```
 
-`--stealth` keeps everything local — no git hooks, no commits to the main repo.  
-`--quiet` suppresses the interactive wizard.
+Always pass `--quiet --stealth`: local-only init, no git hooks or commits to the main repo, no interactive wizard.
 
 ### 4. Update AGENTS.md
 
-If `AGENTS.md` exists, append the beads quick-reference block if it isn't already there.  
-If it doesn't exist, create it.
+Append the quick-reference block below to `AGENTS.md` if missing, or create `AGENTS.md` with this exact block:
 
 ```markdown
 ## Task tracking
@@ -73,21 +58,44 @@ Quick reference:
 - `bd create "Title" -p <0-3>` — create a task (P0 = critical)
 - `bd update <id> --claim` — claim a task
 - `bd close <id>` — complete a task
+- `bd dep add <A> <B>` — **"A depends on B"** (B blocks A). First arg waits, second arg
+  is waited-for. To express "X blocks Y", write `bd dep add Y X`.
 - `bd dolt push` — sync to remote at session end
 ```
 
 ### 5. Report
 
-Print a brief summary:
-- Whether `bd` was installed or already present
-- Whether beads was initialised or already set up
-- Whether AGENTS.md was created or updated
+Print a brief summary: whether `bd` was installed or already present, whether beads was initialised or already set up, and whether AGENTS.md was created or updated. Complete all steps first — do not pause to ask the user.
+
+## Red Flags
+
+- Red flag: running `bd init` without `--stealth` or `--quiet` — this installs git hooks or opens the interactive wizard.
+- Red flag: asking the user which install method to use or whether to proceed — the skill is designed to run unattended.
+- Red flag: committing `.beads/` or any init commit to the repo — stealth mode keeps them local-only.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll skip `--stealth` so the user can see what happens" | Stealth mode is the contract of this skill — non-stealth init adds hooks and commits the user never asked for. |
+| "I should ask before installing software on the user's machine" | Installing `bd` is the requested outcome; asking adds friction and the skill is meant to run headless. |
+
+## Cross-skill references
+
+- Use `bd-tool` for day-to-day beads usage once initialised — `bd prime`, `bd ready`, `bd create`, `bd close`.
+- Use `create-task` to create tasks with pipeline-stage expansion and a HITL review gate.
+
+## Examples
+
+Input: "Set up beads in this repo" → output report example:
 
-Do NOT ask the user to confirm before any of these steps. Just do it.
+- `bd: installed via Homebrew`
+- `beads: initialised in .beads/ (stealth, local-only)`
+- `AGENTS.md: appended task-tracking quick reference`
 
-## Stealth mode rules
+## Verification checklist
 
-- Always pass `--stealth` and `--quiet` to `bd init`
-- Never install git hooks unless the user explicitly asks
-- Never commit `.beads/` to the repo (it's local-only in stealth mode)
-- Prefer non-interactive install methods at every step
+- [ ] `bd` is installed (or was already present) and `bd version` succeeds
+- [ ] `.beads/` exists in the project — stealthed init, no git hooks installed, no repo commits made
+- [ ] `bd prime` runs without error in the project
+- [ ] AGENTS.md contains the task-tracking quick-reference block exactly once (created or appended) and the summary report covers install, init, and AGENTS.md status

package/skills/productivity/validate-agent-dir/scripts/node_modules/.bin/tsc

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

package/skills/productivity/validate-agent-dir/scripts/node_modules/.bin/tsserver

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

package/skills/productivity/validate-agent-dir/scripts/node_modules/.bin/tsx

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

package/skills/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.
+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.
 
 ### 3. Apply voice and tone rules
 
@@ -65,6 +65,7 @@ Output: A new `skills/review-security/SKILL.md` with front matter, When to use,
 - [ ] `docs/skills/skill-anatomy.md` 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
 - [ ] Description uses two-sentence format with 2-4 quoted trigger phrases
 - [ ] Body uses imperative second-person voice with positive framing
 - [ ] Rationale sentences added for non-obvious rules

package/skills/review/maintain-agent-docs/SKILL.md

@@ -1,83 +1,103 @@
 ---
 name: maintain-agent-docs
-description: "Audit and update AGENTS.md and docs/ to keep agent-consumed documentation accurate, specific, and drift-free. Use when user wants to review, update, or improve AGENTS.md, docs/, or other documentation that agents rely on."
+description: Audits and updates AGENTS.md and docs/ to keep agent-consumed documentation accurate, specific, and drift-free. Use when asked to "review AGENTS.md", "check the docs are current", or "fix docs drift".
 ---
 
 # Maintain Agent Docs
 
-Keep AGENTS.md and docs/ accurate, specific, and in sync with the codebase. Also invoke the `style-documentation` skill — its philosophy governs what to document and when.
+## When to use
 
-## When To Use
+- After significant codebase changes — new tooling, renamed modules, changed workflows — leave agent instructions stale.
+- When agents produce poor results due to outdated or missing instructions.
+- Periodic maintenance, after a major release, or when onboarding a new repository to agent-assisted workflows.
+- Trigger phrases: "review AGENTS.md", "check the docs are current", "fix docs drift", "update the agent docs".
 
-- After significant codebase changes (new tooling, renamed modules, changed workflows)
-- When agents are producing poor results due to stale or missing instructions
-- Periodic maintenance — or after major releases
-- When onboarding a new repo to agent-assisted workflows
+## When NOT to use
 
-## Process
+- Deciding what to document or whether a doc is needed — `style-documentation` owns that call; this skill applies it during the audit.
+- Creating or refactoring a skill — use `write-a-skill` or `refactor-skill`.
+- Editing a single doc without auditing the codebase — that is ordinary doc-writing, not maintenance.
 
-### 1. Audit
+## Philosophy / rationale
+
+- **AGENTS.md is an index of expensive truths.** It is injected into every agent conversation, so every line costs tokens and attention. Bloated context files reduce task success while increasing cost (ETH Zurich, ICSE 2026); instructions past the first sections get less attention ("Lost in the Middle", Stanford). Include only what the codebase cannot answer on its own.
+- **Progressive disclosure by need.** Root AGENTS.md stays under 100 lines; path-specific `.instructions.md` files load on demand; depth lives in `docs/` read when needed. When auditing, ask: "Does this line resolve an ambiguity that the code alone cannot?" If not, move it down a level or remove it.
 
-Scan the repository to build a picture of the current state:
+## Workflow
 
-- Read existing AGENTS.md (root and any nested copies) and docs/ contents
-- Compare instructions against actual codebase: directory structure, runnable commands, conventions, tooling
-- Check context budget: is AGENTS.md under 100 lines? Is detail pushed to scoped files?
-- Flag issues, grouped by type:
-  - **Drift** — instructions that no longer match the codebase
-  - **Gaps** — important context missing entirely
-  - **Vagueness** — instructions too generic to be actionable
-  - **Bloat** — content that belongs in scoped files or docs/, not the root
+### 1. Audit
 
-Present findings as a numbered list. Do NOT fix anything yet.
+- Read AGENTS.md (root and any nested copies), scoped `.instructions.md` files, and `docs/` contents.
+- Compare instructions against the actual codebase: directory structure, runnable commands, conventions, tooling.
+- Check the context budget — is AGENTS.md under 100 lines, with detail pushed to scoped files?
+- Flag findings grouped by type: **Drift** (no longer matches), **Gaps** (missing context), **Vagueness** (too generic to act on), **Bloat** (belongs in scoped files or `docs/`). Present them as a numbered list; fix nothing yet.
 
 ### 2. Propose changes
 
-For each issue, propose a specific fix. Present all proposals for user review before applying.
+For each finding, propose a specific fix. Present every proposal for review before applying anything.
 
 ### 3. Apply changes
 
-After approval, update files following the quality principles below.
+After approval, update files following the quality principles below. Verify commands by running them; update what changed, prune what drifted.
 
-## Context Budget
+## Quality principles
 
-AGENTS.md is injected into every agent conversation. Every line costs tokens and attention. Research shows bloated context files *reduce* task success while increasing cost 20%+ (ETH Zurich, ICSE 2026). Instructions buried past the first few sections receive significantly less attention ("Lost in the Middle", Stanford).
+1. **Specificity over generality** — `npm test -- --coverage`, not "run the tests".
+2. **Commands up front** with exact flags — build, test, lint in the first section; position 1 gets the most attention.
+3. **Examples over explanations** — one code snippet beats one paragraph of prose.
+4. **Cover six core areas** — commands, testing, project structure, code style, git workflow, boundaries.
+5. **Explicit boundaries and tech stack with versions** — what agents must NOT do, with reasons; "React 18, TypeScript 5.x", not "a React project".
+6. **Drift-resistant and non-duplicative** — stable concepts (directory purposes) over file lists; reference other docs, do not restate them.
+7. **Progressive disclosure, sparse and maintained** — path-specific detail moves into scoped files or `docs/`; every line must earn its place.
 
-**AGENTS.md is an index of expensive truths** — only include what the codebase cannot answer on its own. If an agent could infer it by reading the code, it does not belong here.
+See [REFERENCE.md](REFERENCE.md) for templates, examples, and detailed section guidance.
 
-### Progressive disclosure hierarchy
+## Red Flags
 
-Not everything belongs in the root file. Push detail to where it's needed:
+- **Fixing findings during the audit.** The propose gate exists because the user knows which imperfections are intentional.
+- **Adding without pruning.** A new section that does not displace a stale one bloats every conversation.
+- **Trusting docs without running the commands.** A command that errors is drift, however plausible it reads.
+- **Auditing only the root file.** Nested `.instructions.md` and `docs/` drift just as easily.
 
-1. **AGENTS.md** (root) — project-wide truths: what it is, how to build/test/lint, structure overview, hard boundaries. Aim for under 100 lines.
-2. **Scoped `.instructions.md`** — path-specific guidance loaded only when the agent works in that area. Use `applyTo` globs to target file types or directories.
-3. **docs/** — deeper context (architecture, ADRs, runbooks) that agents can read on demand but shouldn't carry in every conversation.
+## Common Rationalizations
 
-When auditing, ask: "Does this line resolve an ambiguity that the code alone cannot?" If not, move it down a level or remove it.
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll just fix this one drift directly" | Bypassing the propose gate skips the user's chance to flag intentional imperfections. |
+| "Adding one line is harmless" | Every line costs tokens in every conversation. Sparse accurate beats comprehensive drift. |
+| "The commands are obvious" | Obvious to you, guessed wrong by agents. Verify by running them. |
+| "More detail helps agents" | Bloated context files measurably reduce task success. |
+| "This file is small, it's fine" | Small does not mean current. Only cross-checking against the code reveals drift. |
 
-## Quality Principles
+## Phase-gate checklist
 
-1. **Specificity over generality** — `npm test -- --coverage` not "run the tests"
-2. **Commands up front** — build, test, lint commands in the first section, with exact flags. Position 1 gets the most attention; use it.
-3. **Examples over explanations** — one code snippet > one paragraph of prose
-4. **Six core areas** — commands, testing, project structure, code style, git workflow, boundaries
-5. **Explicit boundaries** — state what agents must NOT do
-6. **Tech stack with versions** — "React 18, TypeScript 5.x, Vite" not "a React project"
-7. **Drift-resistant** — reference stable concepts (directory purposes, architectural decisions) over volatile details (file lists that change weekly)
-8. **Progressive disclosure** — push path-specific or rarely-needed detail into scoped files or docs/, not the root AGENTS.md
-9. **No duplication** — reference other docs, don't restate their content
-10. **Sparse and maintained** — every line must earn its place; a short accurate file outperforms a comprehensive stale one
+- [ ] Phase 1 complete: audit findings presented as a numbered list; nothing fixed yet.
+- [ ] Phase 2 complete: every proposal reviewed and approved before applying.
 
-## Structure Checklist
+## Cross-skill references
 
-A well-maintained AGENTS.md covers:
+| When you need… | Use this skill |
+|---|---|
+| What and whether to document | `style-documentation` |
+| Tone, structure, and concision for the writing | `style-comms` |
+| Creating or refactoring a skill | `write-a-skill`, `refactor-skill` |
+| Scanning changes for leaked secrets | `review-security` |
 
-- [ ] What the project is (one sentence)
-- [ ] How to build, test, and lint (exact commands)
-- [ ] Project structure (directory map with purposes)
-- [ ] Code style and conventions (with examples)
-- [ ] Git workflow (branching, commit, PR conventions)
-- [ ] Boundaries (forbidden files, actions, patterns)
-- [ ] Testing approach (frameworks, coverage expectations)
+## Examples
 
-See [REFERENCE.md](REFERENCE.md) for templates, examples, and detailed section guidance.
+```
+Findings:
+1. [Drift] AGENTS.md says `pnpm run build` but package.json defines `build:dist`
+2. [Gap] New scripts/ directory has no structure entry
+3. [Bloat] Lines 40-52 restate README install steps word-for-word
+```
+
+## Verification checklist
+
+- [ ] Every agent-consumed doc audited — root AGENTS.md, nested `.instructions.md`, `docs/` — and cross-checked against actual structure, commands, and tooling
+- [ ] Findings grouped by drift/gap/vagueness/bloat and presented before any change
+- [ ] All changes applied only after approval
+- [ ] AGENTS.md under 100 lines; detail pushed to scoped files or `docs/`
+- [ ] Commands listed in AGENTS.md verified runnable (build, test, lint)
+- [ ] Content passes the "code alone cannot answer this" test — nothing restated or duplicated
+- [ ] Changes scanned with `review-security` before committing

package/skills/workflow/hitl-collab/SKILL.md

@@ -1,29 +1,98 @@
 ---
 name: hitl-collab
-description: Coordinates HITL collaboration by producing a handoff document and optionally updating the HITL bead with a summary and doc link. Use when a task requires human review/approval, manual steps, or PR handoff collaboration.
+description: Coordinates human-in-the-loop collaboration by writing a handoff document for a human reviewer and linking it from the bead. Use when a task needs human review or approval, manual steps agents cannot run, or a PR handoff — e.g. "hand this to a human", "what does the reviewer need", or "prepare the manual test run".
 ---
 
 # HITL Collab
 
-## Quick start
+## When to use
 
-1. Run `bd show <bead-id>` (bead ID is required).
-2. Create `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md`.
-3. If the bead lacks **PR/branch links + manual steps + acceptance criteria**, add a short note with those details and the handoff doc path via `bd update <bead-id> --notes "<text>"`.
+- Preparing a task handover where the next actor is a human, not an agent.
+- The bead's acceptance criteria depend on reviewer judgment or steps only a human can run — sign-off, credentials, device access.
+- A PR is ready and needs a human to test, review, and merge.
+- You need durable context for a reviewer: what changed, what to run, and what to check.
 
-## Handoff doc template
+## When NOT to use
 
-- **Summary**
-- **Why HITL**
-- **PR/branch links**
-- **Acceptance criteria**
-- **Manual steps**
-- **Verification checklist**
-- **References** (optional)
+- The reader is another agent — use `handoff` to compact the conversation instead.
+- No human gate exists and agents can verify and close the work themselves — run the pipeline directly with `run-pipeline-stage`.
+- You only need bead bookkeeping or task state — use `bd-tool` instead.
 
 ## Workflow
 
-1. Gather context from the bead description and any referenced PRs/branches.
-2. Write the handoff doc using the template above. Use the `style-comms` skill for tone.
-3. Use `.agent-cortex/working-docs/hitl/<bead-id>/` as the home for any additional notes, scripts, screenshots, or logs needed for collaboration.
-4. Only update the bead if it is missing **PR/branch links**, **manual steps**, or **acceptance criteria**. Include the handoff doc path in the note.
+1. Confirm the bead and its HITL gate with `bd show <bead-id>` (ID required). Pull PR/branch links, acceptance criteria, and any manual steps from the task description.
+2. Write `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md` using the handoff doc template below. Follow `style-comms` for tone and structure.
+3. Keep supporting material — screenshots, logs, reproduction scripts — in the same `.agent-cortex/working-docs/hitl/<bead-id>/` directory; it is the collaboration home the reviewer works from.
+4. Link the doc from the bead only when the bead is missing PR/branch links, manual steps, or acceptance criteria. Append — never replace: `bd update <bead-id> --append-notes "<doc path + missing details>"`. The plain `--notes` flag overwrites existing notes and would silently destroy prior context.
+
+## Handoff doc template
+
+Use these sections in this order, adapting headings to the task:
+
+- **Summary** — one paragraph: what was built, its state, what remains.
+- **Why HITL** — the gate that requires a human (approval, manual steps, judgment).
+- **PR/branch links** — where the reviewer starts.
+- **Acceptance criteria** — copied from the bead so the review is checkable.
+- **Manual steps** — copy-runnable commands and actions for the human.
+- **Verification checklist** — what the reviewer must confirm before signing off.
+- **References** — optional links to specs, PRDs, ADRs.
+
+## Red Flags
+
+- Guessing the bead ID instead of running `bd show` — the doc lands in the wrong directory and the wrong task gets reviewed.
+- Using `--notes` when the bead already carries notes — it replaces them; `--append-notes` preserves them.
+- Writing the doc outside `.agent-cortex/working-docs/hitl/<bead-id>/` — it is lost when the worktree is discarded and downstream agents cannot find it.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The human is in the room — no doc needed" | The doc is the durable record the reviewer works from; an in-session chat disappears when the session ends. |
+| "The PR description already covers it" | The PR shows the diff, not the review protocol: what to run, what to check, and how to sign off. |
+| "I'll compress everything into one bead note" | Notes are metadata. Manual steps and acceptance criteria belong in the doc where they survive and can be checked off. |
+
+## Philosophy / rationale
+
+- **Docs are the durable artifact; bead updates are pointers.** The document outlives the session and the worktree, so the human gate always has a stable review surface. The bead carries only what routing needs — links and the doc path.
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| Tone, structure, and concision for the doc | `style-comms` |
+| Conversation compaction for another agent | `handoff` |
+| Bead discovery, queries, and state updates | `bd-tool` |
+
+## Examples
+
+### Handoff doc skeleton
+
+```md
+# Handoff — agnt-ctx-123456
+## Summary
+Implemented X; tests pass; PR open.
+## Why HITL
+Needs sign-off on the API contract change.
+## PR/branch links
+- PR: https://github.com/jaybeeuu/agent-cortex/pull/42
+- Branch: feature/agnt-ctx-123456
+## Acceptance criteria
+- [ ] Contract change approved by reviewer
+## Manual steps
+1. `pnpm install && pnpm test`
+2. `pnpm build:claude && git diff --stat claude/`
+## Verification checklist
+- [ ] Tests pass locally
+- [ ] Generated output up to date
+## References
+- PRD: docs/prds/api-contract.md
+```
+
+## Verification checklist
+
+- [ ] `bd show <bead-id>` confirmed the bead and HITL gate in scope
+- [ ] Handoff doc written to `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md`
+- [ ] Doc covers Summary, Why HITL, PR/branch links, Acceptance criteria, Manual steps, and Verification checklist (References only where useful)
+- [ ] Manual steps are commands a human can copy and run, not prose hints
+- [ ] Bead notes include the doc path and any missing PR/branch links, manual steps, or acceptance criteria
+- [ ] Existing bead notes preserved — used `--append-notes`, not `--notes`

package/skills/workflow/ralph/REFERENCE.md

@@ -1,6 +1,6 @@
-# Fleet — Reference
+# Ralph — Reference
 
-Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL.md) for the top-level event loop.
+Detailed procedures for the ralph orchestration workflow. See [SKILL.md](./SKILL.md) for the top-level event loop; this file holds the per-procedure detail that would overflow the main skill file.
 
 ---
 
@@ -10,15 +10,15 @@ Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL
 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`.
+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 {{TOOL: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)
+   - Chore bead ID and its `bd show` output for the bead specification. Do **not** inject `bd prime` output — the stage runner runs `bd prime` itself if it needs project context
    - 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.
+   - Log file path `.agent-cortex/ralph/ralph-<parent-id>.log` — logs are keyed by **parent** bead ID, so every stage chore of a feature appends to the same file
+7. **Call the {{TOOL: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.
 
 ---
@@ -27,18 +27,20 @@ Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL
 
 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`):
+1. Determine the parent epic (`<epic-id>`) from the task's `epic:<epic-id>` label and count its feature task children (`bd children <epic-id>`, excluding chores). An epic with exactly one feature child is a **single-feature epic**.
+2. **Single-feature epics (1 feature child)**: skip the epic branch entirely. Base `feature/<parent-id>` directly on `origin/main`; its HITL PR targets `main`, and no epic PR is opened later.
+3. **Multi-feature epics (2+ feature children)**: ensure the 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:
+4. Ensure feature worktree exists (base on `epic/<epic-id>` for multi-feature epics, `origin/main` for single-feature):
    ```bash
-   git worktree add .agent-cortex/worktrees/<parent-id> -b feature/<parent-id> epic/<epic-id>
+   # <base> is epic/<epic-id> for multi-feature epics, origin/main for single-feature
+   git worktree add .agent-cortex/worktrees/<parent-id> -b feature/<parent-id> <base>
    ```
    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.
+5. All chores for this parent run in `.agent-cortex/worktrees/<parent-id>`. The `feature/<parent-id>` branch is the agent branch for HITL PRs.
 
 ---
 
@@ -47,9 +49,10 @@ For each parent task bead (`<parent-id>`):
 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>`):
+2. Create or update a feature PR immediately from the agent branch to the feature branch (`feature/<parent-id>` into `epic/<epic-id>`; into `main` for single-feature epics):
    ```bash
-   gh pr create --base epic/<epic-id> --head feature/<parent-id> --title "[<parent-id>] <task-title>" --body "<summary>"
+   # <base> is epic/<epic-id> for multi-feature epics, main for single-feature
+   gh pr create --base <base> --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.
@@ -98,9 +101,9 @@ When a verify or review stage fails:
 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):
+2. For each in-flight bead, read new lines from its **parent's** log file — logs are keyed by **parent** bead ID, so all stages of a feature share one file. Track the next unread line number per parent in memory, starting at 1:
    ```bash
-   tail -n +<lastLine> .agent-cortex/ralph/ralph-<bead-id>.log 2>/dev/null
+   tail -n +<lastLine> .agent-cortex/ralph/ralph-<parent-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):
@@ -119,7 +122,7 @@ Run whenever polling is triggered (timer or agent completion):
 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:
+2. For each **multi-feature** epic whose feature beads are all closed but not yet tagged `awaiting-epic-pr-merge`, open/update an epic PR to main (skip single-feature epics — their feature branch PRs already target `main`):
    ```bash
    gh pr create --base main --head epic/<epic-id> --title "[<epic-id>] Merge epic into main" --body "<epic summary>"
    ```
@@ -155,7 +158,7 @@ Proceed here when no chore beads are in-flight, no `stage:*` chore beads are rea
 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:
+2. For each **multi-feature** epic whose feature beads are all closed, open/update an epic PR to main (skip single-feature epics — no epic branch exists):
    ```bash
    gh pr create --base main --head epic/<epic-id> --title "[<epic-id>] Merge epic into main" --body "<epic summary>"
    ```
@@ -188,15 +191,17 @@ When `bd list --status=in_progress --type=chore` returns no results AND `bd read
 | 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`). |
+| `.agent-cortex/ralph/state.json` | Runtime bookkeeping only: the poll-timer shellId (Copilot) and the in-flight agent-ID→bead mapping. Shape: `{ "timerShellId": null, "inflight": [ { "choreId": "...", "parentId": "...", "title": "...", "agentId": "...", "logLine": 1 } ] }`. Initialise at startup with `{ "timerShellId": null, "inflight": [] }`. Update after every dispatch and every agent completion. **Never hand-edit.** |
+| `.agent-cortex/ralph/ralph-*.log` | Per-parent log files written by subagents — every stage chore of a feature appends to `.agent-cortex/ralph/ralph-<parent-id>.log` (e.g. `ralph-abc-123.log`). |
 
-All orchestration state is derived from beads:
+All task state is derived from beads; `state.json` holds only runtime bookkeeping:
 
 | 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>` |
+| Which agent-ID maps to which bead? | `inflight` entries in `.agent-cortex/ralph/state.json` |
 | 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` |