@jaybeeuu/agent-cortex 1.20.0

package/README.md

@@ -0,0 +1,209 @@
+# agent-cortex
+
+A personal collection of custom agents and skills, shipped to three harnesses from one
+source: the [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating),
+pi, and [Claude Code](https://code.claude.com/docs) (as a plugin).
+
+## Structure
+
+```
+agent-cortex/
+├── plugin.json               # Copilot plugin manifest
+├── .claude-plugin/
+│   └── marketplace.json      # Claude marketplace (exposes ./claude as the "jaybeeuu" market)
+├── agents/                   # Canonical agents (Copilot/pi format: *.agent.md)
+│   ├── ralph.agent.md
+│   ├── ralph-plan.agent.md
+│   ├── plan.agent.md
+│   └── strategy.agent.md
+├── agents-native/            # Claude-only agents with no Copilot equivalent
+│   └── ralph.md              #  the lean Claude Ralph
+├── skills/                   # Skills (grouped by domain) — shared by all harnesses
+│   ├── engineering/          #  tdd, improve-codebase-architecture, …
+│   ├── planning/             #  write-a-prd, prd-to-tasks, design-an-interface, …
+│   ├── productivity/         #  bd-tool, write-a-skill, grill-me, …
+│   ├── review/               #  review-security, refactor-skill, maintain-agent-docs
+│   ├── style/                #  style-code, style-tests, style-comms, style-documentation
+│   └── workflow/             #  ralph, run-pipeline-stage, create-task, …
+├── extensions/               # pi extensions (pi only)
+│   ├── skill-stats/
+│   └── notify/
+├── pi/                       # Global pi configuration (see below)
+│   └── settings.json
+├── scripts/
+│   └── build-claude-agents.mjs   # builds the claude/ subtree from the sources above
+└── claude/                   # Self-contained Claude Code plugin (GENERATED — do not hand-edit)
+    ├── .claude-plugin/
+    │   └── plugin.json
+    ├── .mcp.json             #  MCP servers (context7, github)
+    ├── hooks.json            #  SessionStart hooks (beads context + style policy)
+    ├── agents/               #  generated from agents/*.agent.md + copied from agents-native/
+    └── skills/               #  symlinks to the grouped skills/ dirs (28 skills)
+```
+
+The same `agents/` and `skills/` power three harnesses (Copilot, pi, Claude Code).
+The `claude/` subtree is **generated** by `scripts/build-claude-agents.mjs`
+(`pnpm build:claude`) and committed; CI checks it is never stale:
+
+- **Skills** stay single-source — `claude/skills/<name>` are symlinks into the grouped
+  `skills/<group>/<name>` dirs (Claude discovers skills only one level deep, so the
+  grouping is flattened via links, not copies).
+- **Agents** can't be shared files (the frontmatter formats differ), so `claude/agents/*.md`
+  are converted from the canonical `agents/*.agent.md`. Claude only loads agents from a
+  plugin's default `agents/` dir, so the plugin root is `claude/` — isolating it from the
+  Copilot `.agent.md` files.
+- **Claude-native agents** that have no Copilot equivalent live in `agents-native/*.md` and are
+  copied verbatim into `claude/agents/`. `ralph` is one: it is reimplemented for Claude around
+  background workers + an independent review gate (the Copilot Ralph's `task`/`read_agent`
+  poll loop has no Claude equivalent), so it can't be mechanically converted.
+
+Edit the sources (`agents/*.agent.md`, `agents-native/*.md`, `skills/**`), never anything
+under `claude/`.
+
+## Installation
+
+### Symlink as global pi config
+
+This repo's `pi/settings.json` is symlinked to `~/.pi/agent/settings.json`,
+making it the canonical store for personal pi agent configuration:
+
+```sh
+~/.pi/agent/settings.json -> /path/to/agent-cortex/pi/settings.json
+```
+
+All `pi install` / `pi remove` commands write to this file, and changes are
+committed to git. On a fresh machine:
+
+```sh
+git clone https://github.com/jaybeeuu/agent-cortex
+ln -sf "$PWD/agent-cortex/pi/settings.json" ~/.pi/agent/settings.json
+```
+
+### Pi package dependencies
+
+These packages are declared in `pi/settings.json` and auto-installed by pi:
+
+| Package | Version | Purpose |
+|---|---|---|
+| [`pi-web-access`](https://www.npmjs.com/package/pi-web-access) | 0.10.7 | Web search, URL fetching, GitHub repo access, PDF/YouTube/video analysis |
+
+Desktop notifications are handled by the local `extensions/notify/` extension
+(replaces the former `pi-notify` dependency). It sends an OSC desktop
+notification on multi-turn tasks, labelled with the tmux session:window.pane
+if available, or the project directory name otherwise.
+
+### Copilot plugin (separate)
+
+```sh
+copilot plugin install jaybeeuu/agent-cortex
+```
+
+Or install a local checkout:
+
+```sh
+copilot plugin install ./agent-cortex
+```
+
+### Claude Code plugin (separate)
+
+The Claude plugin is the self-contained `claude/` subtree (manifest at
+`claude/.claude-plugin/plugin.json`), containing **4 agents** (`strategy`, `plan`,
+`ralph-plan`, `ralph`), **28 skills**, a `SessionStart` hook, and 2 MCP servers.
+
+`claude/` is committed, so a fresh clone is installable as-is. If you change the sources,
+rebuild it (the generator is a zero-dependency Node script):
+
+```sh
+pnpm build:claude    # or: node scripts/build-claude-agents.mjs
+```
+
+#### Try it for one session
+
+```sh
+claude --plugin-dir /path/to/agent-cortex/claude
+# verify what loaded:
+claude --plugin-dir /path/to/agent-cortex/claude plugin details agent-cortex
+```
+
+`SKILL.md` edits are picked up live in that session; agent, hook, and MCP changes need
+`/reload-plugins`.
+
+#### Install persistently (recommended)
+
+The repo ships a marketplace manifest (`.claude-plugin/marketplace.json`) that exposes the
+`claude/` subtree. Register it by **absolute path** (a bare `.` is rejected — use an absolute
+path or a `./`-prefixed one), then install:
+
+```sh
+claude plugin marketplace add /path/to/agent-cortex
+claude plugin install agent-cortex@jaybeeuu          # every session (user scope)
+# or, for this project only:
+claude plugin install agent-cortex@jaybeeuu --scope local
+```
+
+After installing, the agents and skills are available in every session with no `--plugin-dir`
+flag, and Ralph is just `claude --agent agent-cortex:ralph`.
+
+#### Update
+
+The marketplace source is your local checkout, so after pulling changes you must rebuild the
+`claude/` subtree and refresh the plugin:
+
+```sh
+git pull
+pnpm build:claude                          # regenerate claude/ from the sources
+claude plugin marketplace update jaybeeuu
+claude plugin update agent-cortex          # restart Claude Code to apply
+```
+
+#### Uninstall
+
+```sh
+claude plugin uninstall agent-cortex
+claude plugin marketplace remove jaybeeuu
+```
+
+#### Using the agents
+
+| Agent | How to invoke | Purpose |
+|---|---|---|
+| `strategy` | delegate: "use the **strategy** agent…" | Vision brief / PRD / technical-direction docs |
+| `ralph-plan` | delegate: "use the **ralph-plan** agent…" | Explore, grill, and file beads for a change |
+| `plan` | delegate: "use the **plan** agent…" | End-to-end planning (PRD → classified beads) |
+| `ralph` | **run as the main agent**: `claude --agent agent-cortex:ralph` | Parallel backlog orchestrator (below) |
+
+Skills auto-trigger from their descriptions, or invoke one explicitly as
+`/agent-cortex:<skill>` (e.g. `/agent-cortex:tdd`).
+
+The lean **Ralph** runs as the interactive main agent (not delegated — it must stay alive to
+receive its workers' completions):
+
+```sh
+claude --agent agent-cortex:ralph        # (add --plugin-dir .../claude if not installed)
+```
+
+It finds ready beads, spawns parallel background workers (implement → independent review →
+fix), opens a PR per feature, and pauses at each human merge gate. After you merge, re-invoke
+it and it resumes from `bd ready`.
+
+#### Style-skill enforcement
+
+The plugin's `SessionStart` hook injects a "style policy" each session, nudging Claude to
+invoke `style-code` / `style-tests` / `style-documentation` / `style-comms` before the
+corresponding work; the style skills' descriptions are also written to auto-trigger proactively.
+
+#### Not ported / follow-ups
+
+- The pi `extensions/` have no Claude runtime-extension equivalent (use hooks/MCP instead).
+- Ralph follow-ups: multi-feature epic branches, and a GitHub-trigger routine to auto-resume
+  after a PR merge (instead of manual re-invocation).
+- The Copilot/pi Ralph (the 4-stage `run-pipeline-stage` pipeline) is unchanged; those two
+  ralph-coupled skills (`ralph`, `run-pipeline-stage`) are intentionally not shipped to Claude.
+
+#### Contributing to the Claude plugin
+
+Edit the **sources** — `agents/*.agent.md` (Copilot format, auto-converted),
+`agents-native/*.md` (Claude-only agents like `ralph`), and `skills/**` — then run
+`pnpm build:claude`. Never hand-edit anything under `claude/` (except the hand-authored
+`claude/hooks.json`, `claude/.mcp.json`, and `claude/.claude-plugin/plugin.json`). CI runs
+`git diff --exit-code claude/agents/ claude/skills/` so the generated tree can never drift.

package/agents/README.md

@@ -0,0 +1,235 @@
+# Agent Directory Format
+
+This document defines the canonical format for composable agent directories in agent-cortex.
+
+## Motivation
+
+The current format uses a single `*.agent.md` file per agent, combining harness-agnostic logic with harness-specific configuration. This creates duplication when the same agent needs to run on multiple harnesses (PI, Copilot, Claude) with different tool names and polling mechanisms.
+
+The new format separates concerns:
+
+- **Shared body**: Harness-agnostic instructions (workflow, branching model, constraints)
+- **Harness-specific frontmatter**: Tool names, model preferences, metadata per harness
+- **Section files**: Harness-specific instructions (e.g., polling loops) included via tokens
+
+## Directory Structure
+
+```
+agents/
+├── <agent-name>/
+│   ├── agent.md                    # Shared body (harness-agnostic)
+│   ├── pi/
+│   │   ├── frontmatter.json        # PI-specific metadata
+│   │   └── <section>.md            # Optional: PI-specific sections
+│   ├── copilot/
+│   │   ├── frontmatter.json        # Copilot-specific metadata
+│   │   └── <section>.md            # Optional: Copilot-specific sections
+│   └── claude/
+│       ├── frontmatter.json        # Claude-specific metadata
+│       └── <section>.md            # Optional: Claude-specific sections
+```
+
+### Example: ralph agent
+
+```
+agents/ralph/
+├── agent.md                        # Shared body (branching model, dispatch logic, constraints)
+├── pi/
+│   ├── frontmatter.json            # PI tools: ["bash", "task", "read_agent"]
+│   └── polling.md                  # PI polling loop using read_agent
+├── copilot/
+│   ├── frontmatter.json            # Copilot tools (same as PI for now)
+│   └── polling.md                  # Copilot polling (same as PI)
+└── claude/
+    ├── frontmatter.json            # Claude tools: ["bash", "task"]
+    └── polling.md                  # Claude event-driven (no polling)
+```
+
+### Example: plan agent (no per-harness sections)
+
+```
+agents/plan/
+├── agent.md                        # Shared body (planning workflow)
+├── pi/
+│   └── frontmatter.json            # PI tools
+├── copilot/
+│   └── frontmatter.json            # Copilot tools
+└── claude/
+    └── frontmatter.json            # Claude tools
+```
+
+## File Specifications
+
+### agent.md
+
+The shared body contains everything harness-agnostic:
+
+- Workflow instructions
+- Branching model
+- Stage pipeline rules
+- Bead lifecycle management
+- Constraints and guardrails
+- Any shared logic
+
+**No YAML frontmatter.** The file is pure markdown.
+
+### frontmatter.json
+
+JSON schema for harness-specific metadata:
+
+```json
+{
+  "name": "agent-cortex:ralph",
+  "description": "Parallel task orchestration agent",
+  "tools": ["bash", "task", "read_agent"],
+  "model": "claude-sonnet-4-5",           // optional
+  "argumentHint": "Run all pending beads"  // optional
+}
+```
+
+#### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Agent identifier (e.g., `agent-cortex:ralph`) |
+| `description` | `string` | What the agent does (used in agent selection) |
+| `tools` | `string[]` | Tool names the agent can use (non-empty) |
+
+#### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `model` | `string` | Preferred model for this harness |
+| `argumentHint` | `string` | Usage hint shown to users |
+
+#### Constraints
+
+- No unknown fields allowed (strict schema)
+- `name` and `description` must be non-empty strings
+- `tools` must be a non-empty array of strings
+
+### Section Files
+
+Optional markdown files in harness subdirectories that contain harness-specific instructions. Included via `{{SECTION:name}}` tokens in agent.md.
+
+Examples:
+- `polling.md` — Polling loop logic (differs between PI and Claude)
+- `authentication.md` — Harness-specific auth setup
+- `output-format.md` — Harness-specific output formatting
+
+## Token Format
+
+Tokens in agent.md reference tools, paths, and sections:
+
+| Token | Syntax | Description |
+|-------|--------|-------------|
+| Tool reference | `{{TOOL:name}}` | Reference a tool by name (for documentation/highlighting) |
+| Path reference | `{{PATH:path}}` | Reference a file path (e.g., skills, extensions) |
+| Section include | `{{SECTION:name}}` | Include content from a section file in the harness directory |
+
+### Examples
+
+```markdown
+Use {{TOOL:task}} to spawn subagents.
+
+Read {{PATH:skills/workflow/plan/SKILL.md}} for the full workflow.
+
+{{SECTION:polling}}
+```
+
+When composing the final agent file for a specific harness:
+
+1. Start with agent.md content
+2. Replace `{{SECTION:name}}` with content from `<harness>/<name>.md`
+3. `{{TOOL:name}}` and `{{PATH:name}}` remain as-is (documentation tokens)
+
+## Composition Rules
+
+### For Harnesses with Sections
+
+When a harness directory contains section files:
+
+```
+agent.md + pi/frontmatter.json + pi/polling.md → composed agent
+```
+
+The composer:
+1. Reads agent.md as the base
+2. For each `{{SECTION:name}}` token, reads `<harness>/<name>.md` and replaces the token
+3. Prepends YAML frontmatter from `<harness>/frontmatter.json`
+4. Outputs the composed agent file
+
+### For Harnesses Without Sections
+
+When a harness directory only has frontmatter.json:
+
+```
+agent.md + pi/frontmatter.json → composed agent
+```
+
+The composer:
+1. Reads agent.md as the base
+2. No section replacements needed
+3. Prepends YAML frontmatter from `<harness>/frontmatter.json`
+4. Outputs the composed agent file
+
+### Agents with No Per-Harness Differences
+
+Agents like `plan`, `ralph-plan`, and `strategy` that have identical behavior across harnesses still need per-harness directories for their frontmatter.json (since tool names differ between harnesses).
+
+```
+agents/plan/
+├── agent.md              # Shared body (same for all harnesses)
+├── pi/frontmatter.json   # PI tools
+├── copilot/frontmatter.json  # Copilot tools
+└── claude/frontmatter.json    # Claude tools
+```
+
+## Migration Path
+
+1. Define the format (this document)
+2. Migrate ralph agent first (proves the pattern)
+3. Migrate plan, ralph-plan, strategy agents
+4. Update the installer/composer to handle the new format
+5. Remove old `*.agent.md` files
+
+## Validation
+
+Use the `validate-agent-dir` script to validate agent directories:
+
+```bash
+node --test --import tsx/esm skills/productivity/validate-agent-dir/scripts/validate-agent-dir.test.ts
+```
+
+The validator checks:
+- agent.md exists
+- At least one harness subdirectory with valid frontmatter.json
+- Frontmatter conforms to the schema (required fields, no unknown fields)
+
+## Design Decisions
+
+### Why JSON for frontmatter instead of YAML?
+
+- JSON has strict syntax (no comments, no ambiguity)
+- Easier to validate with JSON Schema
+- Consistent with existing tooling (package.json, plugin.json)
+- No need for YAML parser dependency
+
+### Why separate section files instead of inline sections?
+
+- Keeps agent.md focused on shared logic
+- Allows harness-specific sections to evolve independently
+- Makes it clear what's shared vs what's harness-specific
+- Enables conditional inclusion (only include sections relevant to the harness)
+
+### Why require at least one harness directory?
+
+- Ensures every agent has explicit harness configuration
+- Prevents "default harness" ambiguity
+- Makes the agent's capabilities explicit per harness
+
+### Why strict schema (no unknown fields)?
+
+- Catches typos and configuration errors early
+- Makes the format self-documenting
+- Prevents accidental field additions that break tooling

package/agents/plan.agent.md

@@ -0,0 +1,56 @@
+---
+description: "Guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution. Full end-to-end planning workflow using the plan skill. Use when starting a new feature, scoping work to hand off to ralph, or saying 'plan this'."
+name: "agent-cortex:plan"
+tools: ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"]
+argument-hint: "Plan <feature or change description>"
+---
+
+You are a planning agent. Your job is to guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution.
+
+You follow the **plan** skill workflow. The skill is defined in `skills/workflow/plan/SKILL.md`. Read it now to load the full instructions.
+
+## Workflow summary
+
+### Phase 1 — Understand and specify
+1. Ask the user to describe the problem, goal, or feature.
+2. Explore the codebase to verify assertions and understand current state.
+3. Interview the user relentlessly — scope, data models, module boundaries, trade-offs.
+4. Sketch major modules.
+5. Draft a PRD using the `write-a-prd` template.
+6. Present the PRD for user approval.
+7. Create an epic bead from the approved PRD.
+
+### Phase 2 — Break into tasks
+8. Review PRD stories and identify vertical-slice phases.
+9. Define each phase (title, stories, what to build, acceptance criteria).
+10. Create epics for multi-phase work.
+11. Present the breakdown for user approval.
+
+### Phase 3 — Create and classify beads
+13. Create task beads via `create-task` for each task.
+14. Tag parent epics with aggregate classification.
+15. Present the full bead tree.
+
+### Phase 4 — Prepare handoff to ralph
+16. Determine the handoff bead (epic or meta-epic).
+17. Tag it `workflow:ralph`.
+18. Push bead state with `bd dolt push`.
+19. Present the handoff summary.
+
+## Permitted writes
+
+| Location | Purpose |
+|---|---|
+| `.agent-cortex/working-docs/` | Research notes, decisions, exploration findings — gitignored |
+| Bead fields (`description`, `design`) | Plans and specifications |
+| `docs/prd/<topic>.md` | PRD documents |
+
+Do **not** modify source code or tracked documentation outside these locations.
+
+## Constraints
+
+- Never modify source code.
+- Always get user approval before moving between phases.
+- Each phase has a gate — do not skip it.
+- Work in `.agent-cortex/working-docs/` for scratchpad notes.
+- Use `bd` commands for all bead operations.

package/agents/ralph-plan.agent.md

@@ -0,0 +1,119 @@
+---
+description: "Plans changes by exploring codebases and creating beads to track the work. Use when you want to scope a feature, bug fix, or refactor — the agent reads, reasons, grills the user, writes a high-level plan into the top-level bead, then files child beads ready for ralph."
+name: "agent-cortex:ralph-plan"
+tools: ["bash", "view", "edit", "create", "grep", "glob", "ask_user"]
+argument-hint: "Plan <feature or change description>"
+---
+
+You are a planning agent. Your job is to understand a task, explore the codebase, grill the user until the design is clear, write a concise implementation plan, and file beads for ralph to implement. You **must not** modify any source code or tracked documentation — your writes are limited to `.agent-cortex/working-docs/` and bead fields.
+
+## Permitted writes
+
+| Location | Purpose |
+|---|---|
+| `.agent-cortex/working-docs/` | Research notes, decision records, exploration findings — gitignored, never committed |
+| Bead `description` / `design` fields | High-level plan (≤100 lines) written via MCP tools |
+
+Do **not** write anywhere else. No source files, no READMEs, no tracked docs, no commits.
+
+## .agent-cortex/working-docs conventions
+
+- Create `.agent-cortex/working-docs/` if it doesn't exist.
+- One file per concern: `exploration-<area>.md`, `decisions.md`, `open-questions.md`, etc.
+- Sub-agents write their findings here; they do not update beads.
+- Keep files focused — a few hundred lines max each.
+- The directory is gitignored; treat it as a scratchpad, not a deliverable.
+
+## Workflow
+
+### 1. Load context
+Invoke the **beads** skill (set workspace root, run `bd prime`). Hold the output in memory.
+
+If the input looks like a PRD (product requirements document), invoke the **prd-to-tasks** skill first — it handles exploration, user quizzing, and creates epics and task beads directly. Then continue from step 7 (Agree with the user).
+
+### 2. Understand the request
+If the request is ambiguous or incomplete, use `ask_user` to resolve blockers before exploring. One question at a time.
+
+If the domain language is unclear or inconsistent, invoke the **grill-with-docs** skill to extract canonical terms. It updates `CONTEXT.md` inline and surfaces ambiguities.
+
+### 3. Explore the codebase
+Dispatch parallel **explore** sub-agents — one per independent research area. Tell each sub-agent to write its findings to a named file in `.agent-cortex/working-docs/` and **not** to modify any beads or source files. Provide each sub-agent with the full `bd prime` output.
+
+- If the task involves a bug or regression, investigate the root cause directly before exploring broader context: trace the code path, check recent changes with `git log`, attempt to reproduce, and classify the failure (regression / missing edge case / design flaw). Also identify the missing test coverage that let the bug ship — the bead's fix plan should fill that testing gap.
+- If the task involves architectural change, invoke **improve-codebase-architecture** to surface structural concerns.
+- If the task requires designing a new module API or interface, invoke **design-an-interface** to generate and compare options. Write the output to `.agent-cortex/working-docs/interface-design.md`.
+
+### 4. Grill the user
+After reviewing exploration findings, invoke the **grill-me** skill to surface and resolve outstanding design questions. Keep grilling until there are no open questions that would block implementation. Record answers in `.agent-cortex/working-docs/decisions.md`.
+
+### 5. Write the plan
+Update the top-level bead's `design` field with a high-level implementation plan. Invoke the **style-comms** skill first so the plan matches the project's communication style.
+
+- **≤100 lines**. Link to `.agent-cortex/working-docs/` files for any detail that would push it over.
+- Structure: Goal → Key decisions → Ordered workstreams → Risks / out-of-scope
+- No line-by-line code guidance — just what, not how.
+
+### 6. Decompose into tasks
+For large workstreams (multiple distinct areas) invoke the **prd-to-tasks** skill. For a single self-contained task invoke **create-task**. Pass the full `bd prime` output and any relevant design context from the `design` field to each skill.
+
+For each new feature bead and each new task bead, create a HITL planning gate before handoff. The feature/task bead depends on this gate and stays blocked until the user explicitly confirms planning is sufficient **for that specific feature/task**.
+
+Every planning gate description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
+
+```bash
+gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>")
+bd tag <planning-gate-id> implementation-type:hitl
+bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on planning gate (gate blocks implementation)
+```
+
+Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature/task is ready to implement; leave all unconfirmed gates open and blocking.
+
+After creating each bead, invoke **classify-bead** to ensure it has an `implementation-type` label before handing off.
+
+Tag every bead created in this step with `workflow:ralph`:
+
+```bash
+bd tag <id> workflow:ralph
+```
+
+Tag every bead with a priority using the unified scale:
+
+```bash
+bd tag <id> priority:<p0|p1|p2|p3|p4|p5>
+```
+
+| Priority | When | Examples |
+|---|---|---|
+| P0 | Drop everything | Crash, data loss, security breach |
+| P1 | Fix before next feature | Major bug, no workaround |
+| P2 | Fix soon, still before features | Minor bug, workaround exists |
+| P3 | Core feature, blocks others | Feature that unlocks downstream work |
+| P4 | Feature, important | Valuable but doesn't block others |
+| P5 | Nice-to-have | Polish, cosmetic, improvement |
+
+Bugs naturally outrank features on this scale (P0-P2 are always bugs). Calibrate each
+bead against the full backlog — a P3 feature that blocks others may need a higher
+explicit priority than a standalone P4 feature.
+
+### 7. Agree with the user
+Present the bead list (IDs, titles, one-line rationale each) plus planning gate status for each item using `✅` (confirmed/closed) or `⏳` (awaiting confirmation/open). Ask the user to confirm or request changes before finishing.
+
+If any planning gates remain open, include an explicit warning that those features/tasks are still blocked and cannot be handed off to ralph yet. Iterate until approved.
+
+### 8. Hand off to ralph
+Once approved, report: "Plan complete — `bd ready` will show the first tasks for ralph."
+
+## Exploration sub-agent instructions
+
+Every explore sub-agent prompt must include:
+1. The full `bd prime` output as context.
+2. The specific area to investigate.
+3. The path to write findings to (e.g. `.agent-cortex/working-docs/exploration-auth.md`).
+4. The instruction: **"Write your findings to the file above. Do not modify any beads, source files, or tracked documentation."**
+
+## Guardrails
+
+- Never assume — verify by reading actual code before creating a bead.
+- Never write outside `.agent-cortex/working-docs/` or bead fields.
+- Never make commits, open PRs, or run shell commands that modify the repo.
+- Use `bash` only for read-only commands (`git log`, `find`, `cat`, etc.).