@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

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

@@ -64,7 +64,7 @@ Fix status bead showing wrong priority after update
 The `release` job in `.github/workflows/ci.yml` handles everything automatically:
 
 1. **Detects new changesets** on main
-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
+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 Copilot output (`pnpm build:copilot`; the Claude plugin is materialised at install time with the package version, so it has no committed output to regenerate) so the drift gates never fail on a version bump
 3. **When "Version Packages" is merged**:
    - Creates a git tag
    - 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`)

package/.github/workflows/ci.yml

@@ -146,7 +146,7 @@ jobs:
         run: pnpm test
 
   claude-plugin-check:
-    name: Claude plugin check
+    name: Claude plugin materialiser check
     needs: setup
     runs-on: ubuntu-latest
     steps:
@@ -175,16 +175,48 @@ jobs:
       - 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
+      # The claude/ subtree is retired — the installer is the only generator
+      # (plain `agent-cortex install claude` materialises ~/.agent-cortex/claude;
+      # `--output <dir>` is generate-only for tests). There is no committed
+      # output to diff, so this job validates the materialiser itself: it must
+      # produce a complete, structural plugin (generated + hand-authored pieces),
+      # no symlinks, no literal {{TOOL:/{{PATH:/{{SECTION: tokens, and a
+      # plugin.json version tracking the package — exactly what a real install
+      # would ship.
+      - name: Materialise the Claude plugin and run structural checks
         run: |
-          pnpm build:claude
-          git diff --exit-code claude/agents/ claude/skills/ claude/.claude-plugin/plugin.json claude/hooks.json claude/hooks/
+          set -euo pipefail
+          OUT="$RUNNER_TEMP/claude-plugin-check"
+          node bin/agent-cortex.mjs install claude --output "$OUT"
+
+          # structure: generated + hand-authored pieces all present
+          test -f "$OUT/.claude-plugin/plugin.json"
+          test -f "$OUT/agents/plan.md"
+          test -f "$OUT/agents/ralph.md"
+          test -f "$OUT/skills/tdd/SKILL.md"
+          test -f "$OUT/hooks.json"
+          test -f "$OUT/hooks/scripts/notify.mjs"
+          test -f "$OUT/.mcp.json"
+          test -f "$OUT/scripts/statusline-command.sh"
+
+          # flat-copy guarantee: no symlinks in the materialised tree
+          if [ -n "$(find "$OUT" -type l)" ]; then
+            echo "::error::symlinks found in materialised Claude plugin"
+            exit 1
+          fi
+
+          # token substitution: no literal tokens survive materialisation
+          TOKENS=$(grep -rlE '\{\{(TOOL|PATH|SECTION):' "$OUT" || true)
+          if [ -n "$TOKENS" ]; then
+            echo "::error::literal substitution tokens in materialised Claude plugin:"
+            echo "$TOKENS"
+            exit 1
+          fi
+
+          # plugin version tracks the package (never stale)
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          PLUGIN_VERSION=$(node -p "require('$OUT/.claude-plugin/plugin.json').version")
+          test "$PKG_VERSION" = "$PLUGIN_VERSION"
 
       - name: Check generated Copilot agent files are up to date
         run: |
@@ -239,10 +271,11 @@ jobs:
           # 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.
+          # plugin.json, THEN regenerates the committed Copilot output
+          # (build:copilot re-derives agents/*.agent.md; the Claude plugin is
+          # materialised at install time with the package version, so nothing
+          # committed needs regenerating) 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"

package/AGENTS.md

@@ -33,7 +33,10 @@ agent-cortex/
 │       ├── 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
+│   └── claude/           #   generated into the plugin's hooks.json + hooks/ by bin/installers/claude.mjs
+├── claude-extras/        # Hand-authored Claude plugin extras (no committed claude/ output)
+│   ├── .mcp.json         # MCP servers (context7, github) — copied into installs
+│   └── scripts/          # statusline-command.sh — copied into installs (executable)
 └── package.json          # PI package manifest (pi: { extensions, skills })
 ```
 
@@ -47,6 +50,13 @@ See the `style-versioning` skill for the full workflow.
 
 Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 
+## Coding Conventions
+
+- **Never block the main thread**: no `*Sync` functions (`readFileSync`, `spawnSync`, …).
+  Tooling code in `bin/`, `scripts/`, `lib/`, `hooks/`, and `test/` must be async —
+  enforced by `scripts/check-no-sync.mjs` (runs via `pnpm lint`). Skill-owned
+  scripts (`skills/*/scripts`) and `extensions/` are the remaining sync surfaces.
+
 ## Skill Conventions
 
 - `SKILL.md` must include a YAML front-matter block with `name` and `description`.
@@ -66,8 +76,14 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   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`
+  them by hand. The Claude plugin is materialised by the install-time generator
+  `bin/installers/claude.mjs`: a plain `agent-cortex install claude` copies it into
+  `~/.agent-cortex/claude` (skills copied flat with `{{TOOL:...}}`/`{{PATH:...}}` substituted,
+  never symlinked), writes the marketplace manifest at
+  `~/.agent-cortex/.claude-plugin/marketplace.json`, and registers it with Claude Code via the
+  `claude plugin` CLI; the repo commits no `claude/` output — hand-authored plugin
+  extras live in `claude-extras/` (`.mcp.json`, `scripts/`), and `--output <dir>` is the
+  generate-only form (tests/CI materialiser checks); `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

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.40.0
+
+### Minor Changes
+
+- 1b6b8b8: `agent-cortex install claude` now materialises the plugin: home-scoped install into `~/.agent-cortex/claude`, copied (token-substituted, no symlinks) skills, marketplace manifest, and automatic registration with Claude Code. Installer toolchain is fully async (no `*Sync` — never block the main thread), enforced by a `check-no-sync` lint scanner.
+- 65119b8: Map `ask_user` → `ask_questions` (pi-questions package) and `skill` → `read` in the pi column of token-map.json: pi agent modes regain interactive questioning (`ask_questions`) instead of dropping the tool with a startup warning, and skill references resolve to reading their SKILL.md. Notes and docs updated to record that `ask_questions` is provided by the pi-questions package.
+- 1b6b8b8: Retire the committed `claude/` plugin subtree: `agent-cortex install claude` into `~/.agent-cortex/claude` (with automatic marketplace registration) is now the only way to build the Claude Code plugin. Hand-authored extras moved to `claude-extras/`, the `build:claude` script is removed, and CI validates the installer instead of diffing committed output.
+
+### Patch Changes
+
+- fcb16d7: Fix grill-with-docs failing to load: quote the front-matter description so skill parsers accept it.
+
+## 1.39.0
+
+### Minor Changes
+
+- 5d4159f: Handoff documents now end with a `## Starter prompt` section: a ready-to-paste first-message prompt pointing the next session at the handoff doc by absolute path and the artifacts it references, telling it to read those before acting, asking it to clean up any provisional artifacts unless the handoff says otherwise, and staying under ~150 words.
+- 5351ae9: agent-cortex install claude now fully installs agent-cortex into Claude Code: it regenerates the claude/ subtree and registers it with the Claude Code runtime via the claude plugin CLI (--dry-run prints the plan without writing; --output <dir> generates only).
+
+### Patch Changes
+
+- adb5f84: Add optional ASCII workflow diagram guidance (inclusion rules, style guide, template example) to the skill anatomy and reference it from write-a-skill
+- 5d4159f: Fix create-chores to resolve `bd` via PATH by default instead of a machine-specific hardcoded path. The BD_PATH env override is retained for machines where bd is not on PATH.
+- 3e8b6e7: Refactor the `hitl-collab` skill to the canonical anatomy template: added When to use / When NOT to use boundaries, Red Flags, Common Rationalizations, a worked handoff-doc example, and a verification checklist; switched bead updates to `--append-notes` so existing notes are preserved.
+- b33d9ef: Refactor the improve-codebase-architecture skill to the anatomy template: add when-to-use / when-not-to-use boundaries, red flags, common rationalizations, philosophy, phase-gate checklists, cross-skill references, a worked example, and a verification checklist.
+- da1e3dd: Add `bd dep add` line to the init-beads skill's embedded AGENTS.md quick-reference template so it matches the repo template and stops re-propagating the drift
+- 358509f: Prune stale doc-contract prose assertions from the run-pipeline-stage progress test; re-enable the skills-script test suites in the pnpm workspace so they actually run in CI.
+- 32b33ac: Refactor the record-idea skill to the anatomy template: add when-to-use boundaries, red flags, rationale, and a verification checklist; move the idea-record scaffold to FORMAT.md to match the generator script.
+- 662cea5: Refactor the `classify-bead` skill to the anatomy template: adds when-not-to-use boundaries, red flags, common rationalizations, philosophy, and a verification checklist.
+- bb01fd6: Refactor create-task skill to the anatomy template: adds When to use / When NOT to use, Red Flags, Common Rationalizations, verification checklist, and moves the bead-property contract detail to REFERENCE.md. No behavioural change — the create-chores script invocation contract is preserved exactly.
+- 876e5cc: Refactor design-an-interface skill to the anatomy template: adds When to use, When NOT to use, verification checklist, phase gates, and rationalization sections while keeping the parallel sub-agent design workflow intact
+- 00c4238: Refactor grill-with-docs to the anatomy template: add when-to-use boundaries, numbered workflow, red flags, common rationalizations, examples, and a verification checklist; consolidate the previously-dangling CONTEXT.md/ADR format links into REFERENCE.md.
+- fd5f787: Refactor init-beads skill to the anatomy template: adds When to use / When NOT to use, Red Flags, Common Rationalizations, Cross-skill references, Examples, and a verification checklist. No behavioural change — the `bd init --quiet --stealth` invocation, install-method preference order, and AGENTS.md quick-reference block are preserved exactly.
+- 608fb58: Refactor maintain-agent-docs skill to the canonical anatomy template: added When NOT to use, Philosophy, Red Flags, Common Rationalizations, Phase-gate checklist, Cross-skill references, Examples, and a concrete Verification checklist; tightened the description to the two-sentence format with quoted trigger phrases.
+- 027431c: Refactor the `prd-to-tasks` skill to the canonical anatomy template: condensed the 5-phase workflow, moved the epic/task body templates into `REFERENCE.md`, added Examples and Phase-gate checklists, and aligned section ordering and voice with `docs/skills/skill-anatomy.md`.
+- e80246a: Refactor the ralph skill to the canonical skill anatomy: add When to use / When NOT to use, Red Flags, Common Rationalizations, Philosophy, phase-gate checklists, cross-skill references, and a verification checklist; align the skill docs with the ralph agent definition (state.json for poll-timer and agent-ID→bead bookkeeping, parent-keyed stage log files, stage runners self-serving `bd prime`, and the single-feature-epic one-hop branching shortcut).
+- d917afb: Refactor request-refactor-plan SKILL.md to the anatomy template; move the refactor plan template into FORMAT.md.
+- d6d33ec: Refactor technical-direction skill to the canonical anatomy template, adding when-to-use/not-to-use boundaries, red flags, common rationalizations, cross-skill references, an examples section, and a verification checklist. The decision-memo template moves to FORMAT.md.
+- 67a668f: Refactor the write-a-prd skill to the anatomy template: adds when-to-use/when-not-to-use boundaries, red flags, common rationalizations, phase gates, cross-skill references, an example, and a verification checklist; the PRD template moves to FORMAT.md.
+- bedd373: Refactor the write-a-ticket skill to the canonical anatomy template: added when-to-use and when-not-to-use boundaries, red flags, common rationalizations, philosophy, cross-skill references, worked examples, and a verification checklist. The ticket template and per-section guidance are preserved.
+- fd95ffe: Refactor run-pipeline-stage SKILL.md to the canonical anatomy template: add `When to use`, `When NOT to use`, `Workflow`, `Red Flags`, `Common Rationalizations`, `Cross-skill references`, `Examples`, `Philosophy / rationale`, and a `Verification checklist`; add quoted trigger phrases to the description; tokenize subagent dispatch as {{TOOL:task}}. No behavioural change to the stage pipeline — all playbooks, prompts, dispatch rules, and path references are preserved.
+
 ## 1.38.1
 
 ### Patch Changes

package/README.md

@@ -9,8 +9,6 @@ pi, and [Claude Code](https://code.claude.com/docs) (as a plugin).
 ```
 agent-cortex/
 ├── plugin.json               # Copilot plugin manifest
-├── .claude-plugin/
-│   └── marketplace.json      # Claude marketplace (exposes ./claude as the "jaybeeuu" market)
 ├── 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/)
@@ -38,17 +36,12 @@ agent-cortex/
 │   ├── 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)
+│       └── claude.mjs        # materialises ~/.agent-cortex/claude + registers with Claude Code (--output <dir> = generate-only form)
 ├── scripts/
 │   └── 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) — 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)
+└── claude-extras/            # Hand-authored Claude plugin extras (no committed claude/ output)
+    ├── .mcp.json             #  MCP servers (context7, github) — copied into installs
+    └── scripts/              #  statusline-command.sh — copied into installs (executable)
 ```
 
 The same `agents/` and `skills/` power three harnesses (Copilot, pi, Claude Code).
@@ -61,34 +54,44 @@ install-time and build-time output can never diverge) and committed so Copilot C
 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 composed from the canonical `agents/<name>/` directories' `claude/` harness dirs
+The Claude plugin is **materialised** at install time by `bin/installers/claude.mjs`. A
+plain `agent-cortex install claude` copies the plugin into the home install root
+(`~/.agent-cortex/claude`), writes a marketplace manifest at
+`~/.agent-cortex/.claude-plugin/marketplace.json` exposing it, and registers it with
+Claude Code by driving the `claude plugin` CLI — state-checked and idempotent (a fresh
+install adds the marketplace + installs the plugin; a re-run updates what state says is
+out of date; a repeat install at the same version is a no-op; a missing or pre-v2 CLI
+warns and prints the manual registration commands instead of failing). The repo commits
+no `claude/` output (hand-authored extras live in `claude-extras/`), so CI validates the
+materialiser itself — a temp-dir install plus structural checks:
+
+- **Skills** stay single-source — the installer copies each `skills/<group>/<name>/` dir
+  flat into `skills/<name>/` (Claude discovers skills only one level deep) with
+  `{{TOOL:...}}` / `{{PATH:...}}` tokens substituted against token-map.json's claude
+  column — no symlinks, so literal tokens never reach Claude.
+- **Agents** can't be shared files (the frontmatter formats differ), so the materialised
+  plugin's `agents/*.md` 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.
+  ships them at its own root (default `~/.agent-cortex/claude/agents/`) — isolating them 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
+  copied verbatim into the materialised plugin's `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.
-- **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
+- **Manifests** are generated too: the plugin's `.claude-plugin/plugin.json` (its `version`
+  tracks `package.json`, so it never goes stale) and `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).
+  the plugin's `hooks/` so hook commands can reach them via `$CLAUDE_PLUGIN_ROOT`. Hand-authored
+  extras — `.mcp.json` and `scripts/` — are copied into every install from the `claude-extras/`
+  dir, which is their canonical store. 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.
+`hooks/claude/`, `claude-extras/`, `package.json`), never the generated
+`agents/*.agent.md` files or anything under the materialised `~/.agent-cortex/claude`.
 
 ## CI
 
@@ -98,6 +101,15 @@ does its own checkout and `pnpm install` rather than sharing build artifacts fro
 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.
 
+The repo commits no generated `claude/` output, so the `claude-plugin-check` job
+validates the Claude plugin **materialiser** instead of diffing a committed mirror:
+it runs `node bin/agent-cortex.mjs install claude --output <tmp dir>` and checks the
+result structurally — `plugin.json` version tracks `package.json`, every generated and
+hand-authored piece is present, no literal `{{TOOL:...}}`/`{{PATH:...}}` tokens survive,
+and no symlinks leak into the copied tree. The Copilot drift check
+(`pnpm build:copilot` + `git diff --exit-code -- 'agents/*.agent.md'`) still guards the
+committed flat agent files.
+
 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` —
@@ -107,7 +119,9 @@ 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
+regenerating the committed Copilot agent files (the Claude plugin is materialised at
+install time with the package version, so it has no committed output to regenerate)
+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 →
@@ -183,32 +197,39 @@ 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`), **29 skills**, `SessionStart` + `Notification` hooks, and 2 MCP servers.
+A plain `agent-cortex install claude` **materialises** the plugin into the home install
+root `~/.agent-cortex/claude` — **4 agents** (`strategy`, `plan`, `ralph-plan`, `ralph`),
+**29 skills** (copied flat per skill, `{{TOOL:...}}` / `{{PATH:...}}` token-substituted — no
+symlinks), `SessionStart` + `Notification` hooks, and 2 MCP servers — writes a marketplace
+manifest at `~/.agent-cortex/.claude-plugin/marketplace.json` exposing `./claude`, and
+registers it with Claude Code. The repo commits no `claude/` output: hand-authored extras
+(`.mcp.json`, `scripts/`) are served from `claude-extras/`, and everything else is generated
+at install time — there is nothing to drift.
 
-`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:
+The generate-only `--output <dir>` form is for previewing and CI validation; the
+documented path is the plain install to `~/.agent-cortex/claude`:
 
 ```sh
 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
+node bin/agent-cortex.mjs install claude           # materialises ~/.agent-cortex/claude + marketplace manifest AND registers it with Claude Code (user scope, idempotent)
+node bin/agent-cortex.mjs install claude --dry-run       # plan generation + registration, no writes/spawns
+node bin/agent-cortex.mjs install claude --require-register  # fail (non-zero exit) when the claude CLI can't drive registration
+node bin/agent-cortex.mjs install claude --output /tmp/x # generate only (preview/CI) — no marketplace manifest, no registration
 ```
 
 #### Try it for one session
 
+Generate a throwaway plugin and point Claude Code at it — no install or registration
+needed:
+
 ```sh
-claude --plugin-dir /path/to/agent-cortex/claude
+node bin/agent-cortex.mjs install claude --output /tmp/agent-cortex-claude
+claude --plugin-dir /tmp/agent-cortex-claude
 # verify what loaded:
-claude --plugin-dir /path/to/agent-cortex/claude plugin details agent-cortex
+claude --plugin-dir /tmp/agent-cortex-claude plugin details agent-cortex
 ```
 
 `SKILL.md` edits are picked up live in that session; agent, hook, and MCP changes need
@@ -216,12 +237,34 @@ 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:
+The plain install does both halves in one step: it materialises the plugin into
+`~/.agent-cortex/claude`, writes `~/.agent-cortex/.claude-plugin/marketplace.json` (the
+home install root doubles as the marketplace root — the manifest exposes `./claude`), and
+registers it with Claude Code by driving the `claude plugin` CLI against that root at
+**user scope** (the `claude plugin install` default, so the plugin is available in every
+session — the recommended persistent flow). Registration is idempotent by state, not by
+exit code: `claude plugin marketplace list --json` picks add-vs-update and
+`claude plugin list --json` picks install-vs-update against the materialised version. A
+fresh install adds the marketplace and installs the plugin; a re-run is the update path
+(`marketplace update`, plus `plugin update` only when a newer version is materialised); a
+repeat install at the same version is a true no-op. It requires the `claude` plugin CLI
+(Claude Code v2+): with a missing or pre-v2 CLI the installer warns and prints the manual
+commands below, exiting 0 — `--require-register` makes registration mandatory and fails
+non-zero when it can't run:
+
+```sh
+agent-cortex install claude                          # materialise + register (user scope, idempotent)
+agent-cortex install claude --require-register       # register or fail the install
+```
+
+`--dry-run` prints the full plan without spawning the claude CLI or writing anything;
+`--output <dir>` generates only, with no marketplace manifest and no registration. The
+equivalent manual registration adds a marketplace root by **absolute path** (a bare `.` is
+rejected) — the home install root (`~/.agent-cortex`) is the marketplace root written by
+the plain install; the repo checkout ships no manifest:
 
 ```sh
-claude plugin marketplace add /path/to/agent-cortex
+claude plugin marketplace add ~/.agent-cortex              # after a plain install
 claude plugin install agent-cortex@jaybeeuu          # every session (user scope)
 # or, for this project only:
 claude plugin install agent-cortex@jaybeeuu --scope local
@@ -232,16 +275,24 @@ 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 plain install re-materialises from the current sources, so after pulling changes
+re-run it — it refreshes the materialised plugin and re-registers whatever the installed
+state says is out of date (`marketplace update`, plus `plugin update` only when a newer
+version is materialised; a repeat install at the same version is a no-op) in one step:
 
 ```sh
 git pull
-pnpm build:claude                          # alias of agent-cortex install claude
-claude plugin marketplace update jaybeeuu
-claude plugin update agent-cortex          # restart Claude Code to apply
+agent-cortex install claude                # re-materialise + refresh (restart Claude Code to apply)
 ```
 
+Registration matches the marketplace by **name**, not path: a marketplace previously added
+from a different root is refreshed in place rather than re-pointed at the fresh home
+install. Re-point it with
+`claude plugin marketplace remove jaybeeuu` and re-run the install.
+
+The plain install IS the update — there is no separate build step. (`--output <dir>` only
+generates a preview and never refreshes an installed plugin.)
+
 #### Uninstall
 
 ```sh
@@ -265,7 +316,7 @@ The lean **Ralph** runs as the interactive main agent (not delegated — it must
 receive its workers' completions):
 
 ```sh
-claude --agent agent-cortex:ralph        # (add --plugin-dir .../claude if not installed)
+claude --agent agent-cortex:ralph        # (omitted once installed via agent-cortex install claude; else --plugin-dir ~/.agent-cortex/claude)
 ```
 
 It finds ready beads, spawns parallel background workers (implement → independent review →
@@ -297,12 +348,16 @@ extension→hook audit.
 
 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
+`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.
+`hooks/claude/hooks.json` (hook config), `claude-extras/` (hand-authored `.mcp.json` and
+`scripts/`), and `package.json` (plugin
+version — picked up at install time) — then run
+`agent-cortex install claude` (re-materialises the home plugin and re-registers it;
+`--output <dir>` generates a preview only). There is no committed
+`claude/` output to hand-edit or regenerate: `~/.agent-cortex/claude` is generated in full
+(`.claude-plugin/plugin.json`, `agents/`, `skills/`, `hooks.json`, `.mcp.json`, `scripts/`)
+so never edit anything under it. The generated `agents/*.agent.md` files are still
+drift-checked by CI (`git diff --exit-code -- 'agents/*.agent.md'`), and CI validates the
+Claude materialiser (structural checks on a temp-dir install) so sources and installer can
+never silently diverge.

package/agents/README.md

@@ -143,8 +143,8 @@ When composing the final agent file for a specific harness:
 2. Replace `{{SECTION:name}}` with content from `<harness>/<name>.md`
 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
+   `build:copilot` and by `bin/installers/claude.mjs` / `bin/installers/pi.mjs`) resolves them when
+   generating the flat files / installing for claude and 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.
 
@@ -209,19 +209,22 @@ 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` (`agent-cortex install claude`; `pnpm build:claude` is a pure
-  alias) composes `claude/agents/*.md` from each agent's `claude/` harness dir (except
-  `ralph`, which ships natively from `agents-native/ralph.md`, copied verbatim).
+- `bin/installers/claude.mjs` (plain `agent-cortex install claude` materialises the plugin
+  into `~/.agent-cortex/claude` and registers it with Claude Code; `--output <dir>` is its
+  generate-only form, used by tests/CI) composes the plugin's
+  `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 single generator behind both `agent-cortex install
-claude` and the `pnpm build:claude` alias (the committed `claude/` subtree is regenerated
-by it and drift-checked, so it can never be stale); `copilot` ships via
+Never edit the generated flat materialised files by hand — edit the composable directory.
+Generation is install-time: `claude` ships
+via `bin/installers/claude.mjs`, the generator behind plain `agent-cortex install claude`
+(which materialises into `~/.agent-cortex/claude` and registers the plugin with Claude
+Code); the repo commits no `claude/` output (hand-authored extras live in `claude-extras/`),
+and CI validates the materialiser with structural checks on a temp-dir install; `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

package/agents/ralph-plan/agent.md

@@ -63,7 +63,7 @@ bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on p
 
 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.
+Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field.
 
 Tag every bead created in this step with `workflow:ralph`:
 

package/agents/ralph-plan.agent.md

@@ -71,7 +71,7 @@ bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on p
 
 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.
+Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field.
 
 Tag every bead created in this step with `workflow:ralph`:
 

package/bin/agent-cortex.mjs

@@ -30,7 +30,7 @@ if (parsed.command === "install") {
 
   if (parsed.harness === "pi") {
     try {
-      const result = installPi({
+      const result = await installPi({
         dryRun: parsed.dryRun ?? false,
         warn: () => {}, // warnings surface once in the printed summary
         ...(parsed.output ? { output: parsed.output } : {}),
@@ -46,15 +46,36 @@ if (parsed.command === "install") {
 
   process.stdout.write(`Installing agent-cortex for "${parsed.harness}" harness…\n`);
 
-  // claude is the first wired harness: generates the plugin subtree from the
-  // canonical sources (agents/, agents-native/, skills/, hooks/claude/) via the
-  // shared installClaude generator — `pnpm build:claude` is an alias of this
-  // invocation, so there is no separate build-time code path.
+  // claude is the first wired harness: a plain `agent-cortex install claude`
+  // materialises the plugin into the home install root (~/.agent-cortex/claude)
+  // with copied, token-substituted skills, writes the marketplace manifest at
+  // ~/.agent-cortex/.claude-plugin/marketplace.json, and registers it with
+  // Claude Code (marketplace add → install → update); `--output <dir>` is the
+  // generate-only form (tests/CI validation), and there is no committed claude/
+  // subtree in the repo anymore.
   if (parsed.harness === "claude") {
     // Avoid loading the installer on the help/summary paths and for other harnesses.
-    const { installClaude } = await import("./installers/claude.mjs");
+    const { installClaude, registerClaude } = await import("./installers/claude.mjs");
     try {
-      installClaude({ output: parsed.output, dryRun: parsed.dryRun });
+      const result = await installClaude({
+        dryRun: parsed.dryRun ?? false,
+        warn: () => {}, // warnings surface once via result.warnings
+        ...(parsed.output ? { output: parsed.output } : {}),
+      });
+      for (const warning of result.warnings) {
+        process.stdout.write(`  ⚠ ${warning}\n`);
+      }
+      // Runtime registration happens only for the plain install — `--output`
+      // keeps generating only (documented in --help).
+      if (parsed.output === undefined) {
+        await registerClaude({
+          root: result.marketplaceRoot,
+          manifest: result.marketplaceManifest,
+          pluginVersion: result.pluginVersion,
+          dryRun: parsed.dryRun ?? false,
+          requireRegister: parsed.requireRegister ?? false,
+        });
+      }
       process.exit(0);
     } catch (err) {
       process.stderr.write(`Install failed: ${err.message}\n`);
@@ -68,7 +89,7 @@ if (parsed.command === "install") {
   if (parsed.harness === "copilot") {
     const { installCopilot } = await import("./installers/copilot.mjs");
     try {
-      installCopilot({ output: parsed.output, dryRun: parsed.dryRun });
+      await installCopilot({ output: parsed.output, dryRun: parsed.dryRun });
       process.exit(0);
     } catch (err) {
       process.stderr.write(`Install failed: ${err.message}\n`);