@jaybeeuu/agent-cortex 1.39.0 → 1.41.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

@@ -13,7 +13,7 @@ available in the author's coding sessions.
 
 ```
 agent-cortex/
-├── package.json           # PI package manifest (pi: { extensions, skills })
+├── package.json           # PI package manifest (pi: { extensions, skills, packages })
 ├── plugin.json            # GitHub Copilot plugin manifest — agents, skills, MCP servers
 ├── agents/                # Custom agents — canonical composable <name>/ dirs
 │   ├── *.agent.md         #   generated from <name>/ by scripts/build-copilot-agents.mjs
@@ -33,8 +33,12 @@ 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
-└── package.json          # PI package manifest (pi: { extensions, skills })
+│   └── claude/           #   generated into the plugin's hooks.json + hooks/ by bin/installers/claude.mjs
+├── claude/               # Committed Claude user-settings template — merged into ~/.claude/settings.json on install
+├── claude-extras/        # Hand-authored Claude plugin extras
+│   ├── .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, packages })
 ```
 
 ## Versioning
@@ -47,11 +51,24 @@ 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.
+- **Share generic tooling helpers in `scripts/lib/`**: tooling code (installers under
+  `bin/installers/`, hooks, other scripts) imports shared utilities from `scripts/lib/`
+  (e.g. `compose-agent.mjs`, `fs.mjs`) rather than redefining them inline.
+
 ## Skill Conventions
 
 - `SKILL.md` must include a YAML front-matter block with `name` and `description`.
 - `description` must be ≤ 1024 characters. First sentence: what it does. Second: "Use when…".
-- Keep `SKILL.md` under ~100 lines. Overflow into `REFERENCE.md` for rarely-needed detail.
+- Keep `SKILL.md` near the ~150-line target in `docs/skills/skill-anatomy.md`, overflowing into
+  purpose-named support files (`REFERENCE.md`, `EXAMPLES.md`, `FORMAT.md`). `style-tests`
+  deliberately sits at the top of that range rather than splitting — its principles must load
+  automatically with the skill.
 - Add utility scripts to `scripts/` when an operation is deterministic and would otherwise be
   regenerated each time (e.g. install scripts, scanners).
 - Skill names use kebab-case and are grouped by prefix where related (e.g. `review-security`,
@@ -66,10 +83,17 @@ 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` (a plain `agent-cortex install claude` also registers the plugin
-  with Claude Code via the `claude plugin` CLI; `pnpm build:claude` is the generate-only alias,
-  running `agent-cortex install claude --output 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`, merges the committed `claude/settings.json`
+  template into `~/.claude/settings.json`, and registers it with Claude Code via the
+  `claude plugin` CLI. The settings merge preserves personal config: the CLI owns exactly
+  `enabledPlugins` + `extraKnownMarketplaces`, and every other key is left untouched. Only
+  that settings template is committed under `claude/` — the generated plugin subtree is not;
+  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
@@ -82,6 +106,9 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 - Extensions are auto-discovered when the repo is installed as a PI package via `pi install`.
 - Keep extensions lightweight: no internal LLM calls. Extensions observe events and provide
   commands — they should not add token overhead.
+- Register CLI flags from the extension factory (load time), never from a `session_start`
+  handler: PI matches parsed CLI flags against the extensions loaded at startup, so late
+  registration makes the flag fail with `Unknown option`.
 - 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

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.41.0
+
+### Minor Changes
+
+- a6b1929: `agent-cortex install pi` now materialises the pi config files as real CLI-managed files, replacing the legacy symlinks into the repo's `pi/` directory. `settings.json` is merged — the committed template supplies defaults, values already present (personal config and anything pi wrote) win, and the CLI owns the `packages` list with the repo path entry resolved against the settings file — so personal config survives re-install. `keybindings.json` is written from the template, refreshed when the template changes, and left alone once edited by hand. The generated header lives in a top-level `"//"` key because pi parses both files with a bare `JSON.parse`. `--dry-run` prints the plan (including "would remove symlink …") and `--output <dir>` keeps the generate-only semantics. Two caveats: because the live value wins, a changed default in the committed template only reaches fresh installs (edit the live file to adopt it); and `packages` is rebuilt from the template, so any `npm:` package added to the live file with `pi install npm:<pkg>` is dropped on the next install — declare long-lived packages in the repo template. An unparseable live `settings.json` is warned about and overwritten.
+- d6ac5a5: Provision the pi packages agent-cortex needs (pi-questions for `ask_questions`, pi-web-access for `fetch_content`) on `agent-cortex install pi`. The package manifest now declares them under `pi.packages`, the installer installs any that the pi user scope is missing via the pi CLI (idempotent, warns and continues on failure), and `--no-provision` opts an offline machine out. The token-map `ask_user` / `web_fetch` mappings are no longer no-ops on a clean `~/.pi`.
+- daa77c8: Encode test-quality rules into `style-tests`: the full agreed principle set (behaviour over
+  implementation, mocking only at external edges, module-boundary units, realistic
+  LocalStack/TestContainers integration, test independence, CI-only truth, spec-by-test, and
+  more), a blanket ban on asserting the static contents of a file (config, markdown, terraform,
+  snapshots) with the behaviour-not-inventory distinction, and test-data construction rules —
+  inline data, no shared mutable top-level fixtures, and small configurable factories over
+  repeated full literals. The content-assertion ban and the test-data rules land as red-flag rows
+  plus verification-checklist items. `style-tests/SKILL.md` deliberately occupies the full
+  ~150-line `SKILL.md` budget so the principles load automatically, rather than splitting into
+  `REFERENCE.md`.
+
+### Patch Changes
+
+- 3e2d149: Add the `agent-guardrails` pi extension: it appends behavioural circuit-breakers to the PI
+  system prompt once per user prompt — two-strikes retry limits, explicit check-in triggers, and
+  atomic-change discipline (first slice of `docs/ideas/improve-pi-system-prompt.md`).
+- a6b1929: The bundled `agent-modes` pi extension now registers its `--agent <name>` CLI flag while the extension loads, instead of from its `session_start` handler. PI validates parsed CLI flags against the extensions present at startup, so the late registration meant `pi --agent <name>` failed with `Unknown option: --agent`. Registration is extracted into a `registerAgentFlag(pi, agents)` helper called directly by the extension factory.
+- a6b1929: Materialise `~/.claude/settings.json` from a new committed `claude/settings.json` template when
+  `agent-cortex install claude` runs (parity with the pi installer's merge-keep-personal contract).
+  The template supplies defaults and personal values win; the installer owns exactly
+  `enabledPlugins` + `extraKnownMarketplaces`, so `permissions`, `hooks`, `env`, `statusLine` and
+  unknown keys are never touched. A legacy symlinked settings file is replaced with a real file,
+  `--dry-run` plans without writing, and `--output <dir>` leaves the user's Claude config alone.
+- 140d9d4: Add a deterministic classifier to the `classify-bead` skill
+  (`skills/planning/classify-bead/scripts/classify-bead.mjs`). One command resolves an
+  existing `implementation-type` label, the legacy `## Type` field, then conservative
+  heuristic signals, and applies the label itself; only beads with no deterministic signal
+  escalate to the rubric subagent. `create-task` and `write-a-prd` now run the classifier
+  before spawning a subagent, and `--audit` reports the deterministic-vs-rubric split
+  over recent beads.
+- e055123: Extract the generic async `isFile`/`isDirectory` stat wrappers into a shared `scripts/lib/fs.mjs` and import them from the claude, copilot, and pi installers instead of redefining them inline.
+- 720d678: Add a milestone-notes discipline to the `run-pipeline-stage` skill: the stage-runner prompt and
+  SKILL.md now instruct agents to append a short checkpoint to the bead's notes (`bd update <id>
+--append-notes`) at stage start and at each milestone, so a fresh session can resume from
+  `bd show <id>` alone if the original session dies mid-stage.
+- 515b75e: Document why the pi installer's substituted skills are the sole pi skill source (the local pi/settings.json packages filter `{ source, "skills": [] }` keeps raw package skills out) and update pi/settings.json to the current runtime config (models, packages, compaction, TUI prefs).
+- 11f9a36: Add a class-over-factory rule to `style-code`: when a module holds mutable state and exposes
+  methods that transform or manage it, model it as a class with public methods and native
+  `#private` fields rather than a factory function returning a closure of methods (TypeScript's
+  `private` modifier is compile-time only). Existing functional guidance for stateless components,
+  hooks, and pure transforms is unchanged.
+
+## 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