@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/docs/research/skill-design-research.md

@@ -58,9 +58,9 @@ Both repos follow the same two-part format: capability sentence + `"Use when..."
 > "Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says 'diagnose this' / 'debug this', reports a bug, says something is broken/throwing/failing, or describes a performance regression."
 
 **agent-cortex example** (vaguer triggers):
-> "Create a bead, classify it, and if AFK expand it into pipeline stage child beads plus a HITL PR gate task. Use when creating a new task that should be tracked and moved through implementation and human review gates."
+> "Create a task bead, classify it as AFK or HITL, and if AFK expand it into pipeline stage chores plus a HITL PR gate. Use when starting tracked work with implementation and review gates — 'create a task for this', 'track this end-to-end', or 'get this into the ralph pipeline'."
 
-The agent-cortex description describes internal mechanics rather than what the user is trying to accomplish.
+The agent-cortex description leads with internal mechanics ("task bead", "AFK", "HITL") rather than what the user is trying to accomplish — the quoted triggers were added in a later refactor, but the jargon remains.
 
 ---
 
@@ -180,7 +180,7 @@ Move to Phase 2 only when both boxes are checked.
 
 **Evidence**: Anthropic Building Effective Agents: *"Think of this as writing a great docstring for a junior developer on your team."* For agents, descriptions are the only routing signal. FLAN (Wei et al., ICLR 2022) showed instruction-tuned models generalise from natural language task descriptions — use the vocabulary a user would *actually speak*, not internal system jargon. Anthropic tool use note: `"Use when"` language *actively counteracts* the model's default tendency to solve problems without invoking tools.
 
-**Current state**: some agent-cortex descriptions describe internal mechanics rather than user intent. E.g., `create-task`: *"Use when creating a new task that should be tracked and moved through implementation and human review gates"* — references internal workflow terms a user wouldn't say.
+**Current state**: some agent-cortex descriptions describe internal mechanics rather than user intent. E.g., `create-task`: *"Use when starting tracked work with implementation and review gates — 'create a task for this', 'track this end-to-end', or 'get this into the ralph pipeline'."* — rewritten to add quoted user triggers (per this rec), though it still leans on internal jargon like "ralph pipeline" a user wouldn't say.
 
 **Recommendation**: Rewrite descriptions to lead with user-vocabulary triggers. Include 2–4 quoted phrases or scenario patterns a user might say:
 
@@ -219,7 +219,7 @@ argument-hint: "Describe the bug or paste the error message"
 
 ### Rec 10 — Fix prd-to-epics Missing SKILL.md
 
-**Current state**: `skills/prd-to-epics/` directory exists in the repo but has no `SKILL.md`. It cannot be invoked.
+**Current state**: Resolved in #16 — the broken `skills/prd-to-epics/` directory was removed; epic/task decomposition is consolidated into the `prd-to-tasks` skill (see CHANGELOG 1.0.0).
 
 **Recommendation**: Either write the missing `SKILL.md` or remove the directory. This is a straightforward bug.
 

package/docs/research/skill-improvements-analysis.md

@@ -110,7 +110,7 @@ REFERENCE.md" — keeping SKILL.md as the primary working document rather than g
 | Verification checklists | Planned |
 | Concrete examples | Planned |
 | Reconsider 100-line limit | Done (raised to 150) |
-| ASCII workflow diagrams | Not yet |
+| ASCII workflow diagrams | Done (ASCII-only style guide in skill-anatomy.md) |
 | Cross-references between skills | Planned |
 | Consistent skeleton template | Partially adopted |
 

package/docs/skills/skill-anatomy.md

@@ -57,6 +57,23 @@ For each optional section, define **what it is**, include an **example snippet**
 | `Phase-gate checklists` | Mid-workflow gates that must pass before proceeding | `- [ ] Phase 1 complete: baseline tests captured.` | Multi-phase workflows (3+ distinct phases) | Linear single-phase tasks |
 | `Cross-skill references` | Explicit delegation to another skill for a real sub-task | `- Run \\`review-security\\` before committing.` | Another skill owns a sub-domain better than restating it | Self-contained skills |
 | `Examples` | Full worked sample of expected outcome/output | `- Input: ... Output: ...` | Any non-trivial output contract | Trivially self-evident skills |
+| `Workflow diagrams` | Inline ASCII diagram showing step flow and decision points | Fenced block of `[Box]`, `|`, `-`, `>`, `v` arrows, e.g. `[Start] --> [Validate] --> [Run]` | Multi-step or branching workflows where a glanceable flow improves comprehension | Simple linear workflows already clear from numbered steps |
+
+## Workflow diagram style guide
+
+When a skill includes a workflow diagram, follow these rules so it renders
+reliably in any CLI:
+
+- **ASCII only** — never Mermaid, images, or unicode box-drawing characters.
+  Keep to `|`, `-`, `>`, `+`, and `v`.
+- **Fenced block** — wrap the diagram in a fenced code block so monospace is
+  preserved.
+- **At most 80 characters per line** — narrow enough for terminal-width readers.
+- **Short box labels** — imperative verbs or nouns (e.g. `[Validate scope]`),
+  never full sentences.
+- **Read left-to-right, top-down** — prefer one branch level over dense joins.
+- **Mirror the numbered workflow** — the diagram is a glanceable summary of the
+  `## Workflow` steps, never a source of truth that contradicts them.
 
 ## Section ordering
 
@@ -92,6 +109,7 @@ A skill passes anatomy review when:
 - [ ] Tool references use `{{TOOL:name}}` tokens, not hardcoded tool names.
 - [ ] Required sections exist and follow canonical ordering.
 - [ ] Optional sections (if present) include what/when/example guidance.
+- [ ] Workflow diagrams (if present) are ASCII-only and follow the workflow diagram style guide.
 - [ ] Verification checklist contains concrete, machine-checkable items.
 - [ ] Supporting docs are split by purpose when `SKILL.md` would exceed ~150 lines.
 
@@ -119,8 +137,26 @@ disable-model-invocation: false
 ## Workflow
 
 1. Gather required context and validate scope boundaries.
-2. Execute deterministic steps in order, recording key decisions.
-3. Produce the required output artifact or terminal response.
+2. Reject early with the reason when validation fails; otherwise continue.
+3. Execute deterministic steps in order, recording key decisions.
+4. Produce the required output artifact or terminal response.
+
+Workflow at a glance (include only when the flow branches):
+
+              [Trigger]
+                  |
+                  v
+          [Gather context]
+                  |
+                  v
+          [Validate scope] --(invalid)--> [Reject early]
+                  |
+              (valid)
+                  v
+      [Run deterministic steps]
+                  |
+                  v
+      [Produce output artifact]
 
 ## Red Flags
 

package/docs/technical-direction/migration-execution-labels.md

@@ -0,0 +1,132 @@
+# Technical Direction: Execution-Label Migration Tooling (two-axis model)
+
+## Problem and target outcome
+
+- Migrate all beads workspaces from `implementation-type:afk|hitl` to `execution:afk|hitl`
+  (strict rename, agent-agnostic) as part of the two-axis workflow model epic.
+- Provide a repo-agnostic tool + skill any workspace can run, and a single-package.json
+  script tooling story across the agent-cortex repo.
+
+## Current-state constraints
+
+- bd CLI is a global binary (`~/.local/bin/bd`); label ops: `bd label list-all [--json]`,
+  `bd list --label-pattern/regex [--json]`, `bd label add/remove` (batch multiple ids).
+- `bd list` supports `--label-pattern`/`--json`; `bd count` does NOT support `--label-pattern`.
+- `bd ready --label-pattern 'stage:*'` works; `bd ready -l execution:afk` verified.
+- 3 script packages exist with per-skill `package.json` + own `pnpm-workspace.yaml` +
+  own `pnpm-lock.yaml` (create-task, validate-agent-dir, run-pipeline-stage). They are NOT
+  members of the root workspace (root glob `skills/*/scripts` does not match the nested
+  `skills/<domain>/<name>/scripts`; root lockfile has zero refs to them).
+- All 3 scripts are stdlib-only (`node:child_process`, `node:fs`, `node:path`, `node:url`).
+- Extensions (`extensions/skill-stats`) have real peer deps on `@earendil-works/pi-coding-agent`
+  — they remain workspace members with their own package.json.
+- `node_modules` gitignored; per-skill modules are installed manually today — a fragility in
+  fresh clones and PI-installed contexts.
+
+## Decisions (locked in planning session)
+
+### D1: Script runtime — all skill scripts become zero-dep `.mjs` with `// @ts-check`
+
+- Every script in `skills/*/*/scripts/` runs with bare `node` (built-ins + shelling out to
+  `bd`). No tsx, no node_modules at runtime, no skill-scripts-dir resolution problem in any
+  installed context.
+- Build-in-publish (Option B) rejected: contradicts the repo's no-compilation PI package
+  model; 3 tiny stdlib-only scripts do not justify dist artifacts.
+- Root keeps `tsx`/`typescript`/`@types/node` for extensions and for `tsc --noEmit`
+  typechecking of `.mjs` via `checkJs`.
+
+### D2: Single package.json (root workspace consolidation)
+
+- Fold the 3 per-skill script packages into the root workspace: delete their `package.json`,
+  `pnpm-workspace.yaml`, `pnpm-lock.yaml`; convert scripts to `.mjs` (D1); root
+  `package.json` owns typecheck/test wiring.
+- Extensions stay as workspace members (`extensions/*` glob) — their package.jsons are
+  semantically meaningful (peer deps on the pi runtime).
+- Fresh-clone/installed-context verification: `pnpm install` at root then
+  `pnpm -r typecheck` + `pnpm -r test` (or root `node --test` wiring) cover all scripts.
+
+### D3: Migration tool shape
+
+- Script: `skills/productivity/migration/scripts/rename-execution-labels.mjs` — zero-dep,
+  `// @ts-check` + JSDoc.
+- Behavior:
+  1. Enumerate: `bd list --label-pattern 'implementation-type:*' --json`.
+  2. Group bead ids by label value (afk | hitl). A bead carrying both gets both execution labels.
+  3. Dry-run (default): print per-bead plan + summary counts; zero writes; exit 0.
+  4. Apply (`--apply`): batched `bd label add execution:<v> <ids...>` then
+     `bd label remove implementation-type:<v> <ids...>` per group.
+  5. Idempotent: re-run finds zero targets → no-op.
+  6. Fail loudly if `bd` unavailable or any subcommand errors.
+- Scope: rename ALL beads carrying `implementation-type:*` (including closed) — the F7
+  acceptance "zero implementation-type:* labels remain" requires it, and bd label history
+  tolerates it.
+
+### D4: Migration skill
+
+- Location: `skills/productivity/migration/SKILL.md` (productivity = workflow tooling).
+- Docs the full sequence for any workspace: preflight (count via `bd label list-all`),
+  dry-run, apply, post-checks (grep stale refs; `bd ready -l execution:afk` smoke), plus
+  pointers to idea-file migration (F2) and skill/doc updates (F3/F4/F5/F6).
+- Repo-agnostic: no agent-cortex-specific paths in the runnable steps.
+
+### D6: npm packaging hygiene (no build step — F9)
+
+- The npm tarball currently ships the whole repo, including `.beads/` (the live task DB),
+  `.github/`, `.changeset/`, `.junie/`, tests, and token-map.json. No `.npmignore`, no
+  `files` field.
+- Rejected: a compile build. Scripts are zero-dep `.mjs` (D1) — nothing to transpile;
+  extensions are TS by pi contract (`index.ts` entrypoint, loader transpiles; the pi runtime
+  import is type-only). Root build script is deliberately a no-op.
+- Chosen: (1) `files` whitelist in package.json — ship only runtime assets (skills/, agents/,
+  extensions/, bin/, lib/, AGENTS.md, plugin.json, README, LICENSE); (2) `prepublishOnly`
+  gate running `pnpm typecheck && pnpm test`; (3) wire `test/cli.test.mjs` into root `test`.
+- Revisit trigger: if an extension ever gains real runtime deps, bundle that extension with
+  esbuild at prepack — not a repo-wide build.
+
+### D5: Knocked-on invocation changes (F4/F5)
+
+- ralph init step 9: `pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx
+  generate-progress.ts` → `node <abs>/generate-progress.mjs`.
+- create-task chore creation: `<skill-scripts>/node_modules/.bin/tsx create-chores.ts` →
+  `node <abs>/create-chores.mjs`.
+
+## Options considered
+
+### Option A: all scripts zero-dep `.mjs` (chosen)
+- Pros: node-only everywhere; no install step; kills resolution problem; `node --test` native.
+- Cons: JSDoc typing instead of TS syntax; small convention shift (`.ts` → `.mjs`).
+
+### Option B: keep `.ts`, build in publish pipeline
+- Pros: full TS syntax.
+- Cons: compile step + dist artifacts contradict no-build PI package; installed contexts must
+  ship/install built output; over-engineered for 3 stdlib-only scripts.
+
+### Option C: per-skill tsx packages (status quo, rejected)
+- Pros: existing pattern.
+- Cons: 3 orphaned mini-workspaces, manual install fragility, resolution doc dance
+  (`<skill-scripts>/node_modules/.bin/tsx`), contradicts single-package.json preference.
+
+## Tradeoffs accepted
+
+- Scripts use JSDoc annotations where types matter; `tsc --noEmit` with `checkJs` keeps a
+  typecheck gate at root.
+- Closed beads get their history labels renamed — accepted for a clean label space.
+
+## Validation plan
+
+- F1-T3: scratch beads workspace (temp dir): create test beads with both labels + a dep pair,
+  dry-run (assert zero writes), apply, verify rename, re-run idempotence, `bd ready -l
+  execution:afk` smoke, then run the migration skill end-to-end once.
+- F8-T3: fresh clone (or temp copy) + `pnpm install` at root; `pnpm -r typecheck` and
+  `pnpm -r test` green; scripts execute via bare `node`.
+
+## Revisit triggers
+
+- A future script needs third-party deps at runtime → revisit D1 (either root dep or
+  per-package re-introduction).
+- New extension with conflicting devDeps → revisit D2 membership rules.
+
+## References
+
+- Code evidence: `skills/*/scripts/package.json` (3 orphaned), root `package.json` +
+  `pnpm-workspace.yaml`, bd CLI help (`bd list`, `bd label`), epic `agnt-ctx-s5xd` notes.

package/extensions/agent-modes/README.md

@@ -34,8 +34,9 @@ contract:
 1. `{{SECTION:name}}` tokens are replaced with the agent's `pi/<name>.md`.
 2. `{{TOOL:key}}` / `{{PATH:key}}` tokens are substituted against the pi column
    of `token-map.json`, with the plugin root resolved from the actual extension
-   location. Tools without a PI equivalent (`ask_user`, `skill`) are omitted
-   from the tool set.
+   location. Tools map through that column (e.g. `ask_user` → `ask_questions`,
+   `skill` → `read`); a tool with a null mapping — any future one — is omitted
+   from the tool set with a warning.
 
 Flat `agents/*.agent.md` files are parsed as a fallback when an agent has no
 composable directory — they are generated output (scripts/build-copilot-agents.mjs)

package/extensions/agent-modes/discover.test.ts

@@ -137,8 +137,8 @@ describe("discoverAgents (composable source format)", () => {
 
     // {{TOOL:bash}} → bash.
     assert.match(plan.prompt, /Run with bash\./);
-    // {{TOOL:ask_user}} → null for pi — token dropped (dangling prose is the author's
-    // responsibility per token-map.README), not left as literal token syntax.
+    // {{TOOL:ask_user}} → ask_questions (pi's native structured-questions tool).
+    assert.match(plan.prompt, /Ask the user with ask_questions\./);
     assert.doesNotMatch(plan.prompt, /\{\{TOOL:ask_user\}\}/);
     // Relative {{PATH:...}} resolves against the actual package root (dir of agents/).
     assert.match(plan.prompt, new RegExp(`Read the plan skill at ${escapeRegExp(fx.dir)}/skills/workflow/plan/SKILL\\.md\\.`));
@@ -147,7 +147,7 @@ describe("discoverAgents (composable source format)", () => {
     assert.doesNotMatch(plan.prompt, /\{\{/);
   });
 
-  it("drops null-mapped tools (ask_user, skill) from the PI tool set", () => {
+  it("maps ask_user → ask_questions and skill → read into the PI tool set", () => {
     const fx = track(makeFixture());
     writeComposableAgent(fx, "plan", {
       frontmatter: {
@@ -159,8 +159,30 @@ describe("discoverAgents (composable source format)", () => {
 
     const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
     assert.equal(agents.length, 1);
-    // ask_user → null (omitted), skill → null (omitted), web_fetch → fetch_content.
-    assert.deepEqual(agents[0].tools, ["bash", "fetch_content"]);
+    // ask_user → ask_questions, skill → read (pi reads skill files), web_fetch → fetch_content.
+    assert.deepEqual(agents[0].tools, ["ask_questions", "bash", "fetch_content", "read"]);
+  });
+
+  it("warns and omits a tool whose pi mapping is null", () => {
+    const fx = track(makeFixture());
+    const NULL_MAP = {
+      tools: { ask_user: { copilot: "ask_user", claude: "AskUserQuestion", pi: null } },
+      paths: {},
+    } as TokenMap;
+    writeComposableAgent(fx, "plan", {
+      frontmatter: {
+        name: "agent-cortex:plan",
+        description: "Planner",
+        tools: ["ask_user", "bash"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, NULL_MAP);
+    assert.equal(agents.length, 1);
+    // With a null pi column the entry is omitted (and warned about), per the contract.
+    // (bash survives so the result is observable — an all-dropped list would be
+    // normalised to DEFAULT_TOOLS, which is "no restriction", not the omit result.)
+    assert.deepEqual(agents[0].tools, ["bash"]);
   });
 
   it("uses the built-in fallback map when token-map.json is unavailable", () => {
@@ -230,8 +252,9 @@ describe("loadTokenMap", () => {
   it("reads the real token-map.json at the package root", () => {
     assert.ok(REAL_TOKEN_MAP);
     assert.equal(typeof REAL_TOKEN_MAP?.tools?.bash?.pi, "string");
-    // ask_user has no PI equivalent per the contract — must stay null.
-    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, null);
+    // ask_user → ask_questions (pi's native structured-questions tool); skill → read.
+    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, "ask_questions");
+    assert.equal(REAL_TOKEN_MAP?.tools?.skill?.pi, "read");
     assert.ok(REAL_TOKEN_MAP?.paths?.agents_dir);
   });
 });

package/extensions/agent-modes/discover.ts

@@ -120,7 +120,7 @@ function prettifyId(id: string): string {
  * Translate a frontmatter tool list into PI tool names.
  *
  * With token-map.json: canonical keys are translated via the pi column; a null
- * mapping means PI has no equivalent (ask_user, skill) and the entry is omitted;
+ * mapping means PI has no equivalent for that tool and the entry is omitted;
  * a name that is not a canonical key passes through untouched (it may be a
  * native PI tool such as `fetch_content`). Without the map, the built-in
  * COPILOT_TO_PI fallback applies and unknown names pass through.

package/extensions/skill-stats/index.test.ts

@@ -331,17 +331,18 @@ describe("loadStore / saveStore", () => {
     const file = join(tmpDir, "test-store.json");
     const original = freshStore();
     original.totalTurns = 42;
+    const recentTs = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString();
     original.skills["test-skill"] = {
       loadedCount: 5,
       invokedCount: 2,
       readCount: 3,
-      lastUsed: "2026-06-07T12:00:00.000Z",
+      lastUsed: recentTs,
       byProject: {
         "/project/a": {
           loadedCount: 3,
           invokedCount: 1,
           readCount: 2,
-          lastUsed: "2026-06-07T12:00:00.000Z",
+          lastUsed: recentTs,
         },
       },
     };

package/lib/cli.mjs

@@ -5,9 +5,10 @@ const SUPPORTED_HARNESSES = ["copilot", "claude", "pi"];
 // malformed options surface as `optionError` on the parsed result; the CLI
 // prints them and exits 1.
 const INSTALL_OPTIONS = {
-  "--dry-run": { key: "dryRun" },
+  "--dry-run": { key: "dryRun", boolean: true },
   "--output": { key: "output" },
   "--plugin-root": { key: "pluginRoot" },
+  "--require-register": { key: "requireRegister", boolean: true },
 };
 
 export function parseArgs(argv) {
@@ -34,8 +35,8 @@ export function parseArgs(argv) {
       if (!spec) {
         return { command: "install", harness, optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
       }
-      if (spec.key === "dryRun") {
-        options.dryRun = true;
+      if (spec.boolean) {
+        options[spec.key] = true;
         continue;
       }
       if (inlineValue !== null) {
@@ -66,9 +67,26 @@ Commands:
   install <harness>   Install agent-cortex for a harness
                       Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}
                       Options (claude):
-                        --output <dir>   Write the plugin subtree to <dir>
-                                         (default: <package root>/claude)
-                        --dry-run        Print what would be generated without writing
+                        (no --output)   Materialise the plugin into
+                                        ~/.agent-cortex/claude, write the
+                                        marketplace manifest at
+                                        ~/.agent-cortex/.claude-plugin/
+                                        marketplace.json, and register it with
+                                        Claude Code via the "claude plugin" CLI
+                                        (marketplace add → install → update,
+                                        idempotent by state: a re-run is the
+                                        update path, repeat install a no-op;
+                                        requires the plugin CLI, v2+)
+                        --output <dir>  Write the plugin subtree to <dir> only —
+                                        no marketplace manifest or registration
+                                        (default: ~/.agent-cortex/claude)
+                        --dry-run       Print what would be generated/registered
+                                        without writing
+                        --require-register
+                                        Fail the install when Claude Code
+                                        registration cannot run (missing CLI,
+                                        pre-v2 build); default warns and prints
+                                        the manual registration commands
                       Options (copilot):
                         --output <dir>   Write the flat *.agent.md files to <dir>
                                          (default: <package root>/agents — the dir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.38.1",
+  "version": "1.40.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -28,13 +28,13 @@
   },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
-    "lint": "pnpm typecheck",
+    "lint": "pnpm typecheck && pnpm check:sync",
+    "check:sync": "node scripts/check-no-sync.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:claude": "node bin/agent-cortex.mjs install claude",
     "build:copilot": "node scripts/build-copilot-agents.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:claude && pnpm build:copilot",
+    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:copilot",
     "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "release": "changeset publish",
     "postinstall": "bash scripts/install-instructions.sh"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.38.1",
+  "version": "1.40.0",
   "author": {
     "name": "jaybeeuu"
   },

package/pnpm-workspace.yaml

@@ -1,6 +1,6 @@
 packages:
   - "."
-  - "skills/*/scripts"
+  - "skills/**/scripts"
   - "extensions/*"
 allowBuilds:
   '@google/genai': false

package/scripts/build-copilot-agents.mjs

@@ -27,4 +27,4 @@ import { installCopilot } from "../bin/installers/copilot.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
-installCopilot({ root: ROOT, output: join(ROOT, "agents") });
+await installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/check-no-sync.mjs

@@ -0,0 +1,49 @@
+// Repo convention: never block the main thread — no `*Sync` functions
+// (fs/child_process/...) in tooling code. Runs via `pnpm lint` (CI) and
+// locally. Scans the toolchain and test dirs: bin/, scripts/, lib/, hooks/,
+// test/. Skill-owned scripts (skills/*/scripts) and extensions are separate
+// follow-up surfaces tracked outside this check.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const SCAN_DIRS = ["bin", "scripts", "lib", "hooks", "test"];
+const EXTENSIONS = new Set([".mjs", ".js", ".ts"]);
+const SELF = "scripts/check-no-sync.mjs";
+
+const SYNC_CALL = /\b\w*Sync\s*\(/;
+
+/** Recursively collect files under dir, skipping this script and node_modules. */
+async function collect(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.name === "node_modules") continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await collect(full)));
+    else if (EXTENSIONS.has(e.name.slice(e.name.lastIndexOf(".")))) out.push(full);
+  }
+  return out;
+}
+
+const offenders = [];
+for (const dir of SCAN_DIRS) {
+  const abs = join(ROOT, dir);
+  for (const file of await collect(abs)) {
+    const rel = relative(ROOT, file);
+    if (rel === SELF) continue;
+    const src = await readFile(file, "utf-8");
+    const hits = src.split("\n").map((line, i) => ({ line: i + 1, text: line })).filter((l) => SYNC_CALL.test(l.text));
+    if (hits.length) offenders.push({ rel, hits });
+  }
+}
+
+if (offenders.length) {
+  console.error("✗ Never block the main thread — *Sync function calls found:");
+  for (const { rel, hits } of offenders) {
+    for (const { line, text } of hits) console.error(`  ${rel}:${line}: ${text.trim()}`);
+  }
+  process.exit(1);
+}
+console.log("✓ no *Sync calls in tooling code (bin/, scripts/, lib/, hooks/, test/)");

package/scripts/lib/compose-agent.mjs

@@ -29,9 +29,19 @@
 //
 // Zero dependencies so it runs on the CI Node (20) and local Node alike.
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Token substitution ──────────────────────────────────────────────────────
 
 const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
@@ -92,22 +102,30 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  * @param {string} harness Harness id: "copilot" | "claude" | "pi"
  * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
  */
-export function composeAgent(root, name, harness, options = {}) {
+export async function composeAgent(root, name, harness, options = {}) {
   const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
   const agentDir = join(root, "agents", name);
-  const frontmatter = parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
-  const tokenMap = loadTokenMap(root);
+  const frontmatter = await parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
+  const tokenMap = await loadTokenMap(root);
 
-  let body = readFileSync(join(agentDir, "agent.md"), "utf-8");
+  let body = await readFile(join(agentDir, "agent.md"), "utf-8");
 
-  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH tokens)
-  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, section) => {
+  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH
+  //    tokens). Single pass over the original body — inserted section content
+  //    is never rescanned (same semantics as the sync replace()).
+  const sectionRe = /\{\{SECTION:([^}]+)\}\}/g;
+  let out = "";
+  let last = 0;
+  for (let m = sectionRe.exec(body); m; m = sectionRe.exec(body)) {
+    const section = m[1];
     const sectionPath = join(agentDir, harness, `${section}.md`);
-    if (!existsSync(sectionPath)) {
+    if (!(await pathExists(sectionPath))) {
       throw new Error(`agent "${name}": missing section "${section}" for harness "${harness}" (${sectionPath})`);
     }
-    return readFileSync(sectionPath, "utf-8").trim();
-  });
+    out += body.slice(last, m.index) + (await readFile(sectionPath, "utf-8")).trim();
+    last = m.index + m[0].length;
+  }
+  body = out + body.slice(last);
 
   // 2. + 3. TOOL/PATH substitution (contextualised for error messages)
   body = substituteTokens(body, harness, tokenMap, {
@@ -127,8 +145,8 @@ const REQUIRED_FIELDS = ["name", "description", "tools"];
 const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
 
 /** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
-function parseFrontmatter(path, name, harness) {
-  const raw = readFileSync(path, "utf-8");
+async function parseFrontmatter(path, name, harness) {
+  const raw = await readFile(path, "utf-8");
   let fm;
   try {
     fm = JSON.parse(raw);
@@ -225,11 +243,11 @@ export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}
 // ─── Token map ───────────────────────────────────────────────────────────────
 
 /** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
-export function loadTokenMap(root) {
+export async function loadTokenMap(root) {
   const path = join(root, "token-map.json");
   let raw;
   try {
-    raw = readFileSync(path, "utf-8");
+    raw = await readFile(path, "utf-8");
   } catch {
     throw new Error(`missing ${path} — the composer requires token-map.json`);
   }