@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

package/README.md

@@ -11,11 +11,12 @@ 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/                   # Canonical agents — composable <name>/ dirs (see agents/README.md)
+│   ├── *.agent.md            #   ralph, ralph-plan, plan, strategy — GENERATED from <name>/ by scripts/build-copilot-agents.mjs
+│   ├── ralph/                #   composable form (shared agent.md + per-harness pi/, copilot/, claude/)
+│   ├── plan/                 #   "
+│   ├── ralph-plan/           #   "
+│   └── strategy/             #   "
 ├── agents-native/            # Claude-only agents with no Copilot equivalent
 │   └── ralph.md              #  the lean Claude Ralph
 ├── skills/                   # Skills (grouped by domain) — shared by all harnesses
@@ -26,39 +27,94 @@ agent-cortex/
 │   ├── style/                #  style-code, style-tests, style-comms, style-documentation
 │   └── workflow/             #  ralph, run-pipeline-stage, create-task, …
 ├── extensions/               # pi extensions (pi only)
+│   ├── agent-modes/          #   switchable agent modes (reads composable agents/)
 │   ├── skill-stats/
 │   └── notify/
 ├── pi/                       # Global pi configuration (see below)
 │   └── settings.json
+├── token-map.json            # canonical tool/path/agent names per harness (install-time token substitution)
+├── token-map.README.md       # design decisions behind token-map.json
+├── bin/
+│   ├── agent-cortex.mjs      # CLI entrypoint
+│   └── installers/
+│       ├── copilot.mjs       # shared generator: agent-cortex install copilot + scripts/build-copilot-agents.mjs
+│       └── claude.mjs        # install-time generator + Claude Code registrar (pnpm build:claude = generate-only --output form)
 ├── scripts/
-│   └── build-claude-agents.mjs   # builds the claude/ subtree from the sources above
+│   └── build-copilot-agents.mjs  # thin wrapper over bin/installers/copilot.mjs (regenerates agents/*.agent.md)
 └── 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)
+    ├── .mcp.json             #  MCP servers (context7, github) — hand-authored
+    ├── hooks.json            #  SessionStart + Notification hooks — generated from hooks/claude/
+    ├── hooks/                #  hook scripts (e.g. scripts/notify.mjs) — generated from hooks/claude/
+    ├── agents/               #  composed from agents/<name>/claude/ + copied from agents-native/
+    └── skills/               #  symlinks to the grouped skills/ dirs (29 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:
+The composable `agents/<name>/` directories are the single source of truth; the flat
+`agents/*.agent.md` files are **generated** by the shared copilot installer
+(`agent-cortex install copilot`, or `scripts/build-copilot-agents.mjs` via
+`pnpm build:copilot` — both run the same `bin/installers/copilot.mjs` code path, so
+install-time and build-time output can never diverge) and committed so Copilot CLI
+(plugin.json `agents: "agents/"`) and pi keep loading the agents — don't hand-edit them.
+The `{{TOOL:...}}` / `{{PATH:...}}` tokens written in agent and skill files are resolved
+per harness at install time from `token-map.json`, the single source of truth for
+canonical tool/path/agent names (see `token-map.README.md` and the `contract` section).
+The `claude/` subtree is **generated** by the install-time generator
+(`bin/installers/claude.mjs`). A plain `agent-cortex install claude` regenerates the
+subtree AND registers it with Claude Code by driving the `claude plugin` CLI (marketplace
+add → install → marketplace update → plugin update). `pnpm build:claude` is the pure,
+generate-only alias — it passes `--output claude`, so CI and release drift-checks never
+spawn the claude CLI or touch `~/.claude`. CI regenerates it and 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.
+  are composed from the canonical `agents/<name>/` directories' `claude/` harness dirs
+  (frontmatter.json + section files), exactly like the Copilot flats are composed from their
+  `copilot/` dirs. 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/`.
+- **Manifests** are generated too: `claude/.claude-plugin/plugin.json` (its `version` tracks
+  `package.json`, so it never goes stale) and `claude/hooks.json` (copied from the canonical
+  `hooks/claude/hooks.json` source), plus any support files under `hooks/claude/` bundled into
+  `claude/hooks/` so hook commands can reach them via `$CLAUDE_PLUGIN_ROOT`. `claude/.mcp.json`
+  and `claude/scripts/` stay hand-authored. See `docs/claude-hooks.md` for the extension→hook
+  mapping and the rejections (auto-name, skill-stats, subagent, agent-modes).
+
+Edit the sources (`agents/<name>/` composable dirs, `agents-native/*.md`, `skills/**`,
+`hooks/claude/`, `package.json`), never anything under `claude/` or the generated
+`agents/*.agent.md` files.
+
+## CI
+
+The CI pipeline runs lint, test, and claude-plugin-check as three parallel jobs
+(`lint`, `test`, `claude-plugin-check`), each gated on `needs: setup`. Each job
+does its own checkout and `pnpm install` rather than sharing build artifacts from
+the `setup` job — pnpm workspace symlinks don't survive artifact upload/download,
+so artifact sharing would break the workspace resolution that the build depends on.
+
+A separate `changeset-check` job runs only on pull requests and fails any PR that
+touches a versioned path (`extensions/`, `skills/`, `agents/`, `package.json`, or
+`plugin.json`) without a changeset in `.changeset/`. Add one with `pnpm changeset` —
+the `style-versioning` skill documents the format.
+
+On pushes to `main`, a `release` job (gated on `lint`, `test`, and
+`claude-plugin-check`) runs changesets to open a `chore: version packages` PR when
+changesets are pending, then publishes to npm once it lands. The version step runs
+`pnpm version-packages` — bumping `package.json`, syncing `plugin.json`, and
+regenerating the committed generated output so the drift gates stay green; the
+publish step runs `pnpm publish-package` (pack + provenance publish). Publish
+authenticates via npm Trusted Publishing (OIDC) — no npm token or GitHub
+secret is needed, only the one-time npm-side setup on npmjs.com (package →
+Access → Trusted Publishing for the `jaybeeuu/agent-cortex` repo). Releases
+are sourced entirely from `main`.
 
 ## Installation
 
@@ -92,6 +148,29 @@ Desktop notifications are handled by the local `extensions/notify/` extension
 notification on multi-turn tasks, labelled with the tmux session:window.pane
 if available, or the project directory name otherwise.
 
+### Pi harness agents & skills (`agent-cortex install pi`)
+
+The agents are already available to pi through the package (`pi.skills` + the
+`agent-modes` extension compose them at runtime), but the raw package files carry
+literal `{{TOOL:...}}` / `{{PATH:...}}` tokens. Run the pi installer to materialise
+composed agents and token-substituted skills into pi's user scope:
+
+```sh
+agent-cortex install pi
+# → ~/.pi/agent/agents/<name>.agent.md (ralph, plan, ralph-plan, strategy)
+# → ~/.pi/agent/skills/  (token-substituted skill tree)
+```
+
+Flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `--dry-run` | Show what would be installed without writing anything |
+| `--output <dir>` | Install into `<dir>/agents` and `<dir>/skills` (default `~/.pi/agent`) |
+| `--plugin-root <dir>` | Override the plugin root used for `{{PATH:...}}` tokens (default: token-map.json's pi value — use it for checkout or symlinked installs) |
+
+Re-run whenever you pull changes (`git pull` + reinstall, or after `pnpm build:copilot`).
+
 ### Copilot plugin (separate)
 
 ```sh
@@ -108,13 +187,22 @@ copilot plugin install ./agent-cortex
 
 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.
+`ralph-plan`, `ralph`), **29 skills**, `SessionStart` + `Notification` hooks, 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):
+`claude/` is committed (the marketplace install flow reads it straight from the working
+tree, so a fresh clone installs as-is), and rebuilt via the install-time generator if you
+change the sources:
 
 ```sh
-pnpm build:claude    # or: node scripts/build-claude-agents.mjs
+pnpm build:copilot   # or: node scripts/build-copilot-agents.mjs (regenerates agents/*.agent.md)
+pnpm build:claude    # or: node bin/agent-cortex.mjs install claude --output claude (generate-only)
+# or the install-time entry (same generator, less typing):
+node bin/agent-cortex.mjs install copilot          # regenerates agents/*.agent.md in place
+node bin/agent-cortex.mjs install copilot --dry-run       # plan only, no writes
+node bin/agent-cortex.mjs install copilot --output /tmp/x # preview the flat files elsewhere
+node bin/agent-cortex.mjs install claude           # regenerates ./claude AND registers it with Claude Code
+node bin/agent-cortex.mjs install claude --dry-run       # plan generation + registration, no writes/spawns
+node bin/agent-cortex.mjs install claude --output /tmp/x # generate only — no registration
 ```
 
 #### Try it for one session
@@ -131,8 +219,20 @@ claude --plugin-dir /path/to/agent-cortex/claude plugin details agent-cortex
 #### 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:
+`claude/` subtree. A plain `agent-cortex install claude` does both halves in one step: it
+regenerates `claude/` and registers the plugin with Claude Code by driving the `claude
+plugin` CLI (marketplace add → install → marketplace update → plugin update), pointing it
+at this checkout's manifest. This requires the `claude` plugin CLI (Claude Code v2+):
+
+```sh
+git clone https://github.com/jaybeeuu/agent-cortex   # first time (or git pull to update)
+agent-cortex install claude                          # regenerate + register (user scope)
+```
+
+`--dry-run` prints the full plan without spawning the claude CLI or writing anything;
+`--output <dir>` regenerates only, with no registration. The equivalent manual registration
+(e.g. on a Claude Code build without the plugin CLI) adds the checkout by **absolute path**
+(a bare `.` is rejected):
 
 ```sh
 claude plugin marketplace add /path/to/agent-cortex
@@ -146,16 +246,18 @@ 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:
+The marketplace source is your local checkout, so after pulling changes re-run the installer —
+it rebuilds the `claude/` subtree and refreshes the registered plugin (marketplace update →
+plugin update) in one step:
 
 ```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
+agent-cortex install claude                # rebuild + refresh (restart Claude Code to apply)
 ```
 
+`pnpm build:claude` only regenerates the subtree (no registration), so on its own it won't
+refresh an installed plugin.
+
 #### Uninstall
 
 ```sh
@@ -186,15 +288,22 @@ It finds ready beads, spawns parallel background workers (implement → independ
 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
+#### Hooks
 
-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.
+`SessionStart` injects a per-session policy nudging Claude to prefer the shipped skills over
+ad-hoc choices: the "style policy" (invoke `style-code` / `style-tests` /
+`style-documentation` / `style-comms` before the corresponding work — their descriptions also
+auto-trigger proactively) and the "skill policy" (`using-agent-skills` for routing, `bd-tool`
+for beads context, `git-workflow` for branch/PR discipline). A `Notification` hook matched on
+`agent_completed|agent_needs_input|permission_prompt` raises a desktop notification when a
+task finishes, waits on input, or needs approval. See `docs/claude-hooks.md` for the full
+extension→hook audit.
 
 #### Not ported / follow-ups
 
-- The pi `extensions/` have no Claude runtime-extension equivalent (use hooks/MCP instead).
+- Only `session-start` and `notify` had Claude equivalents (both ported to hooks); the other
+  pi `extensions/` (auto-name, skill-stats, subagent, agent-modes) have none — the audit and
+  rejection rationale live in `docs/claude-hooks.md`.
 - 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
@@ -202,8 +311,16 @@ corresponding work; the style skills' descriptions are also written to auto-trig
 
 #### 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.
+Edit the **sources** — the composable `agents/<name>/` directories (shared `agent.md` +
+per-harness frontmatter/sections, auto-composed by `scripts/build-copilot-agents.mjs` and
+the install-time generator `bin/installers/claude.mjs`), `agents-native/*.md` (Claude-only
+agents like `ralph` — the canonical bodies the installer copies verbatim), `skills/**`,
+`hooks/claude/hooks.json` (hook config), and `package.json` (plugin
+version) — then run `pnpm build:claude` (the generate-only alias of `agent-cortex install
+claude --output claude`; run the plain install instead if you also want the plugin
+re-registered with Claude Code). Never hand-edit
+anything under `claude/` except the hand-authored `claude/.mcp.json` and `claude/scripts/`
+files, or the generated `agents/*.agent.md` files, `claude/agents/`, `claude/skills/`,
+`claude/.claude-plugin/plugin.json`, and `claude/hooks.json`. CI runs
+`git diff --exit-code claude/agents/ claude/skills/ claude/.claude-plugin/plugin.json claude/hooks.json`
+and `git diff --exit-code -- 'agents/*.agent.md'` so the generated outputs can never drift.

package/agents/README.md

@@ -4,9 +4,9 @@ This document defines the canonical format for composable agent directories in a
 
 ## 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 original format used a single `*.agent.md` file per agent, combining harness-agnostic logic with harness-specific configuration. This created duplication when the same agent needed to run on multiple harnesses (PI, Copilot, Claude) with different tool names and polling mechanisms.
 
-The new format separates concerns:
+The composable directory format separates concerns:
 
 - **Shared body**: Harness-agnostic instructions (workflow, branching model, constraints)
 - **Harness-specific frontmatter**: Tool names, model preferences, metadata per harness
@@ -35,11 +35,11 @@ agents/
 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
+│   ├── frontmatter.json            # PI tools: ["bash", "task", "read_agent", "wait_for_agents"]
+│   └── polling.md                  # PI completion: blocking wait_for_agents (no poll timer)
 ├── copilot/
-│   ├── frontmatter.json            # Copilot tools (same as PI for now)
-│   └── polling.md                  # Copilot polling (same as PI)
+│   ├── frontmatter.json            # Copilot tools: ["bash", "task", "read_agent"]
+│   └── polling.md                  # Copilot completion: sleep-120 poll timer + read_agent
 └── claude/
     ├── frontmatter.json            # Claude tools: ["bash", "task"]
     └── polling.md                  # Claude event-driven (no polling)
@@ -123,9 +123,9 @@ 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 |
+| Tool reference | `{{TOOL:name}}` | Canonical tool name; resolved per harness from `token-map.json` |
+| Path reference | `{{PATH:path}}` | Canonical path name; resolved per harness from `token-map.json` |
+| Section include | `{{SECTION:name}}` | Include content from a section file in the harness directory (substituted by the composer) |
 
 ### Examples
 
@@ -141,7 +141,17 @@ 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)
+3. `{{TOOL:name}}` and `{{PATH:name}}` are resolved against `token-map.json` — the
+   canonical tool/path/agent names per harness. `scripts/lib/compose-agent.mjs` (used by
+   `build:copilot` / `build:claude` and by `bin/installers/pi.mjs`) resolves them when
+   generating the flat files / installing for pi; pi's `agent-modes` extension does the
+   same at runtime. See the `contract` section of `token-map.json` and
+   `token-map.README.md` for the rules.
+
+The pi harness's `agent-modes` extension is a runtime consumer of this format: it
+composes agent prompts on the fly from `agent.md` + `pi/frontmatter.json`, substituting
+tokens against `token-map.json`'s pi column with no install step. See
+`extensions/agent-modes/README.md`.
 
 ## Composition Rules
 
@@ -188,10 +198,36 @@ agents/plan/
 ## Migration Path
 
 1. Define the format (this document)
-2. Migrate ralph agent first (proves the pattern)
-3. Migrate plan, ralph-plan, strategy agents
+2. Migrate ralph agent first (proves the pattern) — DONE
+3. Migrate plan, ralph-plan, strategy agents — DONE
 4. Update the installer/composer to handle the new format
-5. Remove old `*.agent.md` files
+5. Remove old `*.agent.md` files — DONE (the flat files are now **generated output**, see below)
+
+All four agents (`ralph`, `plan`, `ralph-plan`, `strategy`) use the composable layout and the
+flat `agents/*.agent.md` files are built from them:
+
+- `scripts/build-copilot-agents.mjs` (`pnpm build:copilot`) composes `agents/*.agent.md` from
+  each agent's `copilot/` harness dir — committed for Copilot CLI, which loads `*.agent.md`
+  from `plugin.json`'s `agents: "agents/"` path.
+- `bin/installers/claude.mjs` (plain `agent-cortex install claude` also registers the plugin
+  with Claude Code; `pnpm build:claude` is its generate-only alias, running `install claude
+  --output claude`) composes `claude/agents/*.md` from each agent's `claude/` harness dir (except
+  `ralph`, which ships natively from `agents-native/ralph.md`, copied verbatim).
+- The pi harness delivers two ways: the `agent-modes` extension composes `agent.md` +
+  `pi/frontmatter.json` at runtime against `token-map.json`, and `agent-cortex install pi`
+  materialises composed agents + token-substituted skills into `~/.pi/agent` at install
+  time (see README "Pi harness agents & skills").
+
+Never edit the generated flat/claude files by hand — edit the composable directory. CI
+regenerates both outputs and fails on drift. Generation is install-time: `claude` ships
+via `bin/installers/claude.mjs`, the generator behind plain `agent-cortex install claude`
+(which also registers the plugin with Claude Code) and its generate-only `pnpm
+build:claude` alias (`install claude --output claude`) — the committed `claude/` subtree
+is regenerated by it and drift-checked, so it can never be stale; `copilot` ships via
+`bin/installers/copilot.mjs`, the shared code path behind both `agent-cortex install
+copilot` and `scripts/build-copilot-agents.mjs`; `pi` ships via
+`bin/installers/pi.mjs`, which materialises composed agents + token-substituted skills
+into `~/.pi/agent`.
 
 ## Validation
 

package/agents/plan/agent.md

@@ -0,0 +1,51 @@
+# plan — end-to-end feature planning agent
+
+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 `{{PATH: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/plan/claude/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:plan",
+  "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'.",
+  "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob", "AskUserQuestion", "Task", "Skill"],
+  "argumentHint": "Plan <feature or change description>"
+}

package/agents/plan/copilot/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:plan",
+  "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'.",
+  "tools": ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"],
+  "argumentHint": "Plan <feature or change description>"
+}

package/agents/plan/pi/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:plan",
+  "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'.",
+  "tools": ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill"],
+  "argumentHint": "Plan <feature or change description>"
+}

package/agents/plan.agent.md

@@ -1,10 +1,13 @@
 ---
+# GENERATED from agents/plan/ by scripts/build-copilot-agents.mjs — DO NOT EDIT.
 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>"
 ---
 
+# plan — end-to-end feature planning agent
+
 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.