@jaybeeuu/agent-cortex 1.37.1 → 1.38.1

package/.agents/skills/style-versioning/SKILL.md

@@ -61,18 +61,19 @@ Fix status bead showing wrong priority after update
 
 ## After merge to main
 
-The `release.yml` workflow handles everything automatically:
+The `release` job in `.github/workflows/ci.yml` handles everything automatically:
 
 1. **Detects new changesets** on main
-2. **Creates or updates a "Version Packages" PR** with bumped versions and updated CHANGELOG
+2. **Creates a "Version Packages" PR** — the `version` step runs `pnpm version-packages`, which bumps `package.json`, syncs `plugin.json` (via `scripts/sync-plugin-version.sh`), updates `CHANGELOG.md`, and regenerates the committed generated output (`pnpm build:claude`, `pnpm build:copilot`) so the drift gates never fail on a version bump
 3. **When "Version Packages" is merged**:
-   - Bumps `package.json` version
-   - Syncs `plugin.json` version (via `scripts/sync-plugin-version.sh`)
-   - Updates `CHANGELOG.md`
    - Creates a git tag
-   - Publishes to npm via OIDC (no `NPM_TOKEN` needed)
+   - Publishes to npm — `pnpm publish-package` packs with `pnpm pack` and publishes with `npm publish --provenance --access public`. Authenticates via npm Trusted Publishing (OIDC): the release job's `id-token` permission lets npm exchange a GitHub OIDC token for a short-lived npm token at publish time, so no `NPM_TOKEN` secret or `.npmrc` auth config is required — only the one-time npm-side Trusted Publishing setup on npmjs.com (package → Access → Trusted Publishing → GitHub repo `jaybeeuu/agent-cortex` + workflow `.github/workflows/ci.yml`)
    - Creates a GitHub release automatically
 
+`changesets/action` execs the `version`/`publish` inputs without a shell, so each
+must be a single unquoted command token — keep release logic in pnpm scripts
+(`version-packages`, `publish-package`), never inline shell strings.
+
 ### Version lockstep
 
 All version numbers stay in lockstep automatically:
@@ -96,6 +97,6 @@ All version numbers stay in lockstep automatically:
 | Before (manual) | After (changesets) |
 |---|---|
 | Agent bumps versions locally | Agent writes a changeset file |
-| Manual GitHub release creation | Automated via `release.yml` |
-| `publish.yml` triggered by release | `release.yml` triggered by push to main |
+| Manual GitHub release creation | Automated by the `release` job in `ci.yml` |
+| `publish.yml` triggered by release | `ci.yml` release job on push to main |
 | Version sync was manual | `sync-plugin-version.sh` runs automatically |

package/.github/workflows/ci.yml

@@ -7,7 +7,40 @@ on:
   pull_request:
 
 jobs:
-  changeset:
+  setup:
+    name: Setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+
+  changeset-check:
     name: Changeset check
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
@@ -21,7 +54,7 @@ jobs:
           BASE_REF: ${{ github.event.pull_request.base.ref }}
         run: |
           # Paths that require a changeset when modified
-          VERSIONED_PATHS='extensions/\|skills/\|agents/\|package.json\|plugin.json'
+          VERSIONED_PATHS='extensions/|skills/|agents/|package\.json|plugin\.json'
 
           changed=$(git diff --name-only "origin/${BASE_REF}...HEAD")
           echo "Changed files:"
@@ -46,29 +79,178 @@ jobs:
 
           echo "Changeset found: $changesets"
 
-  checks:
+  lint:
+    name: Lint
+    needs: setup
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
           version: 10
           run_install: false
+
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+
       - name: Lint
         run: pnpm lint
+
+  test:
+    name: Test
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
       - name: Test
         run: pnpm test
-      - name: Build
-        run: pnpm build
+
+  claude-plugin-check:
+    name: Claude plugin check
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # `pnpm build:claude` is an alias of `agent-cortex install claude` (both run
+      # bin/installers/claude.mjs), so this drift check proves the committed subtree
+      # equals the installer's output — stale output or hand-edits to generated
+      # files fail the build. The subtree stays committed because the marketplace
+      # install flow reads it straight from the working tree (fresh clone installs
+      # as-is).
       - name: Check generated Claude plugin is up to date
         run: |
           pnpm build:claude
-          git diff --exit-code claude/agents/ claude/skills/
+          git diff --exit-code claude/agents/ claude/skills/ claude/.claude-plugin/plugin.json claude/hooks.json claude/hooks/
+
+      - name: Check generated Copilot agent files are up to date
+        run: |
+          pnpm build:copilot
+          git diff --exit-code -- 'agents/*.agent.md'
+
+  release:
+    name: Release
+    needs: [lint, test, claude-plugin-check]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      # npm Trusted Publishing (OIDC): npm exchanges this id-token for a
+      # short-lived npm token at publish time — no token config or secret.
+      id-token: write
+    concurrency: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Cache pnpm store
+        uses: actions/cache@v4
+        with:
+          path: ~/.pnpm-store
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          # changesets/action execs these inputs via @actions/exec with NO shell:
+          # the string is split by argStringToArray on whitespace (single quotes
+          # survive literally), so each must be a single unquoted command token
+          # that runs a pnpm script. version-packages bumps versions, syncs
+          # plugin.json, THEN regenerates the committed generated output
+          # (build:claude writes claude/.claude-plugin/plugin.json with the NEW
+          # version, build:copilot re-derives agents/*.agent.md) before the action
+          # commits, so the Version Packages PR always passes the drift gates.
+          version: pnpm version-packages
+          publish: pnpm publish-package
+          commit: "chore: version packages"
+          title: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Publish authenticates via npm Trusted Publishing (OIDC token
+          # exchange at publish time) — no NPM_TOKEN secret, no token config.
+          # Requires the one-time npm-side setup: npmjs.com → @jaybeeuu/
+          # agent-cortex → Access → Trusted Publishing, tied to GitHub repo
+          # jaybeeuu/agent-cortex + workflow .github/workflows/ci.yml.

package/AGENTS.md

@@ -4,9 +4,10 @@ Instructions for agents working on this repository.
 
 ## What This Repo Is
 
-A personal Copilot CLI plugin containing custom agents and skills, plus PI extensions for
-enhancing the coding agent runtime. Changes here affect the behaviour of every agent, skill,
-and PI extension available in the author's coding sessions.
+A personal Copilot CLI plugin containing custom agents and skills, shipped to Copilot, pi,
+and Claude Code, plus PI extensions and Claude hooks for enhancing the coding agent
+runtime. Changes here affect the behaviour of every agent, skill, and PI extension
+available in the author's coding sessions.
 
 ## Structure
 
@@ -14,8 +15,12 @@ and PI extension available in the author's coding sessions.
 agent-cortex/
 ├── package.json           # PI package manifest (pi: { extensions, skills })
 ├── plugin.json            # GitHub Copilot plugin manifest — agents, skills, MCP servers
-├── agents/                # Custom agents (*.agent.md)
-│   └── ralph.agent.md
+├── agents/                # Custom agents — canonical composable <name>/ dirs
+│   ├── *.agent.md         #   generated from <name>/ by scripts/build-copilot-agents.mjs
+│   ├── ralph/             #   composable format — see agents/README.md
+│   ├── plan/              #   "
+│   ├── ralph-plan/        #   "
+│   └── strategy/          #   "
 ├── skills/               # Grouped by domain, discovered recursively
 │   ├── planning/         # Scope, spec, decompose
 │   ├── engineering/      # The coding loop
@@ -27,6 +32,8 @@ agent-cortex/
 │   └── skill-stats/
 │       ├── README.md      # Installation & usage
 │       └── index.ts       # Extension entrypoint
+├── hooks/                # Canonical Claude Code hooks (hooks.json + scripts — see docs/claude-hooks.md)
+│   └── claude/           #   generated into claude/hooks.json + claude/hooks/ by bin/installers/claude.mjs
 └── package.json          # PI package manifest (pi: { extensions, skills })
 ```
 
@@ -52,7 +59,17 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 
 ## Agent Conventions
 
-- Agent files are named `<name>.agent.md` and live in `agents/`.
+- Agents live in composable `<name>/` directories under `agents/`: a shared `agent.md` body plus
+  per-harness subdirectories `pi/`, `copilot/`, `claude/` (frontmatter.json and optional section
+  files) per the spec in `agents/README.md`. `ralph`, `plan`, `ralph-plan`, and `strategy` all use
+  the composable layout. The flat `agents/*.agent.md` files are **generated output** — composed
+  from the canonical directories by the shared `bin/installers/copilot.mjs` code path behind both
+  `agent-cortex install copilot` and `scripts/build-copilot-agents.mjs` (thin wrapper), and
+  committed for Copilot CLI (plugin.json `agents: "agents/"` scans for `*.agent.md`); never edit
+  them by hand. The `claude/` subtree is generated by the install-time generator
+  `bin/installers/claude.mjs` (`pnpm build:claude` aliases `agent-cortex install claude`; `ralph`
+  is authored natively in `agents-native/` and copied verbatim; the other agents compose from their
+  `claude/` harness dirs).
 - Keep orchestration logic in the agent file; extract shared per-task workflow into a skill
   so it can be reused (e.g. ralph delegates per-task stage execution to `run-pipeline-stage`).
 
@@ -65,6 +82,8 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   commands — they should not add token overhead.
 - Extensions that persist data should write to `~/.pi/agent-cortex/` (global, cross-project)
   and tag records with the project path for per-project slicing.
+- PI extensions with Claude Code equivalents are ported to `hooks/claude/`; the port/reject
+  audit with rationale lives in `docs/claude-hooks.md`.
 
 ## User preferences
 

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.38.1
+
+### Patch Changes
+
+- 5def727: Fix generate-progress parser for current bd list format
+- 735f083: Fix Release CI npm publish (ENEEDAUTH): the release job now publishes via npm Trusted Publishing (OIDC) — no `NPM_TOKEN` secret or `.npmrc` auth config. The `release` job's `id-token: write` permission is the only workflow-side requirement; npm exchanges the GitHub OIDC token for a short-lived npm token at publish time.
+
+  **One-time npm-side setup required** (no GitHub secret): on npmjs.com, open the package `@jaybeeuu/agent-cortex` → Access → Trusted Publishing → Add new publisher → GitHub, select the `jaybeeuu/agent-cortex` repository and the `.github/workflows/ci.yml` workflow. Publishing then needs no token configuration.
+
+## 1.38.0
+
+### Minor Changes
+
+- fbc6fa5: Add the Copilot CLI harness installer (`agent-cortex install copilot`), sharing the generator with `pnpm build:copilot`. It regenerates the flat `agents/*.agent.md` files the Copilot plugin loads (plugin.json `agents: "agents/"`), with the same `--dry-run` / `--output` contract as the claude and pi installers.
+- 42d3a33: Add central token-map.json mapping tool names, paths, and agent naming across the copilot, claude, and pi harnesses, with the token substitution contract for the install-time generation system. Use {{TOOL:...}} / {{PATH:...}} tokens in canonical sources; installers substitute per-harness names from the map.
+- 3a7e896: Add using-agent-skills meta-skill with 8 core operating behaviors and skill routing tree. Routes incoming work to the right skill, enforces scope discipline, and flags persistent failures to the user instead of working around them.
+- 4f5b134: Add a `wait_for_agents` tool to the subagent extension: it blocks until at least one background sub-agent (spawned with `task`) completes and returns its result, with `read_agent` kept as a fallback. Ralph's PI completion detection now waits on `wait_for_agents` instead of a `sleep 120` poll loop.
+- e1180d5: Update the agent-modes extension to discover agents from the composable directory format (`agents/<name>/` + per-harness `pi/frontmatter.json`). The PI system prompt is composed from `agent.md`, resolving `{{SECTION:...}}` includes from the agent's `pi/` directory and substituting `{{TOOL:...}}` / `{{PATH:...}}` tokens via token-map.json, so tool restrictions now translate to real PI tool names (e.g. `view` → `read`, `web_fetch` → `fetch_content`, null-mapped tools dropped). Flat `*.agent.md` files remain supported as a fallback for agents that have not been migrated to composable directories yet.
+- 603679a: Make the composable agent directories (`agents/<name>/`) canonical: the hand-authored flat `agents/*.agent.md` sources are removed and the flat Copilot/pi agent files are now generated output, composed from the canonical dirs by `scripts/build-copilot-agents.mjs` (`pnpm build:copilot`). `claude/agents/*.md` is composed from the same dirs' `claude/` harness by `scripts/build-claude-agents.mjs` (ralph stays native via `agents-native/ralph.md`). Agent names, descriptions, and tool sets are unchanged; agent bodies now carry the composable (tokenized) content. CI verifies both generated outputs never drift.
+- 60d498f: Port the pi extensions with Claude equivalents to the Claude Code plugin's hooks:
+  SessionStart now also injects the using-agent-skills / bd-tool / git-workflow skill
+  policy, and a Notification hook matched on documented notification types
+  (`agent_completed|agent_needs_input|permission_prompt`) raises desktop notifications
+  via the bundled `hooks/scripts/notify.mjs`. Hook support scripts are now bundled
+  into `claude/hooks/` by the shared installer, and the audit (auto-name, skill-stats,
+  subagent, agent-modes rejected with rationale) is recorded in `docs/claude-hooks.md`.
+- 6863b0e: Add `agent-cortex install claude` — install-time generator for the Claude Code plugin
+  subtree, sharing one code path with `pnpm build:claude` so the outputs can never diverge.
+  `claude/.claude-plugin/plugin.json` (version now tracked from `package.json`) and
+  `claude/hooks.json` (from the new canonical `hooks/claude/` source) are generated rather
+  than hand-maintained, and the committed `claude/skills/` gains the previously-missing
+  `using-agent-skills` symlink. Root tests (`test/`) are now included in `pnpm test`.
+- f2b441e: Add the pi harness installer (`agent-cortex install pi`): composes agents from the canonical composable directories plus `pi/` sections, substitutes `{{TOOL:...}}` / `{{PATH:...}}` tokens against token-map.json's pi column (null-mapped tools dropped with warnings, paths resolved against the plugin root), and writes `<output>/agents/<name>.agent.md` plus token-substituted skill copies to `<output>/skills` (default `~/.pi/agent`). Supports `--dry-run`, `--output <dir>`, and an optional `--plugin-root <dir>` override. The shared composer gains pi-friendly options (`dropNullTools`, `pluginRoot`, `resolveRelativePaths`, `warn`) with the copilot/claude build defaults unchanged, and the root test suite is now wired into `pnpm test`.
+
+### Patch Changes
+
+- 99fcc9a: Complete the move to install-time Claude code generation: the standalone `scripts/build-claude-agents.mjs` build script is removed and `pnpm build:claude` is now a pure alias of `agent-cortex install claude` — both invoke the shared `bin/installers/claude.mjs` generator, so there is a single code path for the committed `claude/` plugin subtree and install-time vs regenerated output can never diverge. Generated agents carry installer provenance headers, and CI's drift check (regenerate + `git diff --exit-code`) validates the committed subtree byte-for-byte against installer output. `agents-native/` remains the canonical source for Claude-native agents (`ralph`), copied verbatim by the installer.
+- 9b0c4fc: Fix the release pipeline so Version Packages PRs regenerate generated output. `changesets/action` execs the `version`/`publish` inputs without a shell, so quoted multi-command strings crash (`bash -c '...'` split on whitespace → unterminated quote, exit 2). The chain now lives in exec-safe single-command pnpm scripts: `pnpm version-packages` bumps versions, syncs `plugin.json`, then regenerates the committed Claude/Copilot agent output so the drift gates never fail on the bumped version; `pnpm publish-package` performs the pack + provenance publish.
+- f1b8a25: Add composable agent directory structures for the plan, ralph-plan, and strategy agents (`agents/plan/`, `agents/ralph-plan/`, `agents/strategy/` with per-harness `pi/`, `copilot/`, and `claude/` frontmatter). The existing flat `*.agent.md` files are retained until the composer/installer migration lands, so no shipped behaviour changes yet.
+- d83a7cf: Add composable agent directory structure for the ralph agent (`agents/ralph/` with per-harness `pi/`, `copilot/`, and `claude/` frontmatter and polling sections). The existing flat `agents/ralph.agent.md` is retained until the composer/installer migration lands, so no shipped behaviour changes yet.
+- c4728c5: Migrate hardcoded tool names in skill files to `{{TOOL:name}}` tokens (task, read_agent, bash, view, rg, glob) so installers can substitute per-harness names.
+
 ## 1.37.1
 
 ### Patch Changes

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,92 @@ 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 — agent-cortex install claude (pnpm build:claude aliases it)
 ├── 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`) — `pnpm build:claude` is a pure alias of
+`agent-cortex install claude`, so there is no separate build-time code path, and the
+committed subtree can never diverge from a real install. 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 +146,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 +185,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 (same generator)
+# 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 in place
+node bin/agent-cortex.mjs install claude --dry-run       # plan only, no writes
+node bin/agent-cortex.mjs install claude --output /tmp/x # write the subtree elsewhere
 ```
 
 #### Try it for one session
@@ -151,7 +237,7 @@ The marketplace source is your local checkout, so after pulling changes you must
 
 ```sh
 git pull
-pnpm build:claude                          # regenerate claude/ from the sources
+pnpm build:claude                          # alias of agent-cortex install claude
 claude plugin marketplace update jaybeeuu
 claude plugin update agent-cortex          # restart Claude Code to apply
 ```
@@ -186,15 +272,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 +295,14 @@ 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` (an alias of `agent-cortex install claude`). 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.