@jaybeeuu/agent-cortex 1.38.1 → 1.39.0

package/docs/ideas/subagent-visibility.md

@@ -0,0 +1,72 @@
+# Idea: subagent-visibility
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+The bundled `subagent` extension delegates work to separate `pi` processes with isolated
+context windows. It streams output live, shows per-agent usage stats (turns, tokens, cost), and
+supports abort — but after a run there's no retained record of what each subagent actually did
+(files touched, decisions, blockers), and while a run is in flight there's no richer
+dashboard-level view of what each agent is up to. There's also no way to influence a running
+subagent: you can only watch or Ctrl+C the whole thing. For the ralph-style parallel dispatches
+(up to 5 concurrent chores) this is a real blind spot.
+
+## Who benefits
+The author, whenever running parallel subagent work (ralph pipeline chores, parallel research).
+A live dashboard helps during runs; persisted per-run reports turn subagent work into a
+reviewable after-action record (which also complements the HITL/summary flow). Mid-run steering
+reduces wasted tokens from subagents heading the wrong way and having to restart.
+
+## Proposed outcome
+Expand (or adopt, if a store extension fits) subagent tooling to give:
+
+1. **Live dashboard** — richer TUI during runs: per-agent status (phase, current tool call,
+   files touched), so you can see what each parallel subagent is doing without digging into
+   streamed output.
+2. **Persisted reports** — a per-run record per subagent (what it did, files changed,
+   decisions, blockers), stored for after-action review. Persistence should follow the repo
+   convention: write to `~/.pi/agent-cortex/`, tagged with project path for per-project slicing.
+3. **Mid-run steering** — send a message to a running subagent to change its direction
+   ("skip that, focus on X") rather than killing and restarting.
+
+Decision from the interview: **evaluate the pi extension store first** — if a maintained
+extension already covers dashboard + reports (and ideally steering), adopt it; otherwise expand
+the bundled `subagent` extension. Building is a fallback, not the default.
+
+## Validity check
+- Evidence we already have: the bundled `subagent` extension is a working base — it already
+  spawns `pi` subprocesses, streams, and collects usage data, so the hooks for a dashboard and
+  reports exist in some form. The repo has a data convention (`~/.pi/agent-cortex/`, per-project
+  tagging) that reports would slot into.
+- Riskiest assumption: that mid-run steering is technically feasible — subagents run as separate
+  `pi` processes, so steering likely needs a message channel (e.g. a FIFO / IPC pipe into the
+  running process, or a PI-native way to inject input). If the process model doesn't allow input
+  mid-run, the interaction half collapses to "abort and re-dispatch with corrected instruction".
+- What would invalidate this idea: if store extensions are all visibility-only (no steering) and
+  the process model rules out mid-run input, the remaining value is dashboard + reports only.
+  Also, if subagents use private pipes that block reading live state cheaply, the dashboard may
+  be constrained to what the streamer already shows.
+
+## Constraints
+- Keep it lightweight and consistent with the repo's extension conventions (no internal LLM
+  calls in the extension itself).
+- Should compose with ralph's parallel dispatch (up to 5 concurrent chores) without making the
+  TUI unusable.
+- Steering must be safe: a message is advisory input to the subagent, not a force-kill;
+  abort stays available.
+
+## Next validation step
+Two-part check before building: (1) search the pi extension store for subagent/dashboard/steering
+extensions and evaluate against this wishlist; (2) verify whether a running `pi` subagent
+process accepts input mid-run (checked against how the subagent extension spawns processes and
+whether PI exposes any IPC/input channel) — this decides whether steering is scoped in.
+
+## Notes
+Recorded 2026-08-25. Interview decisions: visibility = both live dashboard AND persisted
+per-run reports; interaction = mid-run steering (not approve-gates, not pause/resume); path =
+evaluate store first, fall back to expanding the bundled `subagent` extension. Complements
+`unified-ci-pipeline` (pipeline visibility) and the ralph parallelism work in this repo.

package/docs/ideas/task-session-context.md

@@ -0,0 +1,89 @@
+# Idea: task-session-context
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+Coding sessions accumulate context turn by turn: every question, every tool call, every
+tangent stays in the window until it's manually compacted or the session is restarted. Keeping
+the context small and relevant is an active management burden — the author has to notice the
+bloat, decide what matters, and intervene. Long conversations either burn tokens or require
+frequent manual resets that drop useful memory.
+
+## Who benefits
+The author, daily. Removing context management from the loop means sessions stay small and
+focused no matter how long the overall thread runs. It also produces a durable, reviewable log
+of work: each task's bead + summary memory is an audit trail of what was done and why.
+
+## Proposed outcome
+A workflow organised around **tasks** instead of sessions. Whenever the user does something
+discrete — asks a new question, records an idea, fleshes out a piece of work — it **begins a
+task**:
+
+1. **Task = blank session with memory context.** The task starts a fresh, self-contained
+   session. It does NOT get every turn and tool call of the parent conversation — only access
+   to the accumulated **memories** of what came before (a summary/compressed view, not the raw
+   transcript).
+2. **Self-contained execution.** The task works on its own: it takes action, and **records
+   memories along the way** as it produces outcomes.
+3. **Single summary memory on completion.** The last thing a task does is write one summary
+   memory capturing its outcome. These memories are additive — the running memory store grows as
+   tasks complete.
+4. **Fresh session continues the thread.** Once the task completes, a new session starts with
+   access to the memories — including the new summary — so to the user it feels like one
+   continuous thread, but each underlying session stays small.
+
+**Ties into beads (bd):** "the completion of a bead is the completion of a task". A bead becomes
+the log of work completed: the task's outcome is recorded on/with the bead, the fresh session
+starts, and the bead is accompanied by **referential memory** (a pointer/memory entry that links
+the outcome to the bead). So the bead doubles as the durable record AND the context-boundary
+marker: starting a bead is the trigger for task-session separation.
+
+**The bead is the artifact — the session is disposable.** Once a task is complete, the whole
+conversation context is no longer needed; the bead is the artifact. The current conversation is
+the live example: recording this idea is a task, and when it's done the transcript of every turn
+and tool call can be discarded — what remains is the record plus its summary/referential memory.
+This is the load-bearing philosophical point of the idea: sessions exist to serve tasks, not the
+other way around. Context is an implementation detail of a single task; the bead is the durable
+unit of history.
+
+The mechanism likely needs: a memory store (per-project, e.g. under `~/.pi/agent-cortex/` or a
+records convention), a session-scoping rule (what memories a fresh task session is seeded with),
+the summary-writing step, and the bead ↔ memory linkage.
+
+## Validity check
+- Evidence we already have: the repo already runs on beads as the unit of work (bd), and the
+  ralph pipeline already treats beads as self-contained executable units — so task-per-bead
+  separation is a natural extension of an existing pattern. Existing ideas
+  (`record-ideas-as-beads`, `pi-task-memory`, `extension-manifests`) all push in the direction of
+  making agent-cortex the declared, memory-rich source of truth.
+- Riskiest assumption: that a fresh session seeded with *memories only* (no raw transcript) is
+  sufficient context for a task — the compression of a conversation into memories must not lose
+  the specifics a task needs. Also: whether the harness (pi/Claude) even supports programmatic
+  session spawning with a seed context cleanly enough for this to feel seamless.
+- What would invalidate this idea: if memory-as-context proves lossy in a way that keeps tasks
+  mis-executing (then the blank-session model needs the raw transcript after all, defeating the
+  point); or if the session boundary machinery (start/stop/spawn with seed) fights the harness.
+
+## Constraints
+- Sessions must stay small — this is the whole point; memory is the interface, not the transcript.
+- Memories are additive and durable; the summary memory is the handoff contract between tasks.
+- The bead is the work log AND the context boundary: no task completion without its summary
+  memory and bead record.
+- Must not break the existing task loops (ralph pipeline stages, HITL handoffs) — it should
+  compose with them, not fork them.
+
+## Next validation step
+Flesh-out session (proposed by the author): nail down the trigger rules (what counts as "begin a
+task"), the memory store schema and what a "memory" is vs a summary, how a fresh session gets
+seeded, and how the bead carries the summary + referential memory. Then a spike: one task
+completing with summary → fresh session seeded → verify the thread feels continuous.
+
+## Notes
+Recorded 2026-08-25. The author explicitly wants to flesh this out later — this record captures
+the working concept. It connects several existing ideas: `record-ideas-as-beads` (beads as the
+unit of everything), `pi-task-memory` (memory as a first-class mechanism), and
+`subagent-visibility` (visibility into what task sessions do).

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/lib/cli.mjs

@@ -66,9 +66,15 @@ 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)   Generate the plugin subtree AND register it
+                                        with Claude Code via the "claude plugin" CLI
+                                        (marketplace add → install → update) — requires
+                                        the plugin CLI (Claude Code v2+)
+                        --output <dir>  Write the plugin subtree to <dir> only — no
+                                        runtime registration (default: <package
+                                        root>/claude)
+                        --dry-run       Print what would be generated/registered
+                                        without writing
                       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.39.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -31,7 +31,7 @@
     "lint": "pnpm typecheck",
     "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:claude": "node bin/agent-cortex.mjs install claude",
+    "build:claude": "node bin/agent-cortex.mjs install claude --output 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",

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.39.0",
   "author": {
     "name": "jaybeeuu"
   },

package/pnpm-workspace.yaml

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

package/skills/engineering/design-an-interface/SKILL.md

@@ -1,94 +1,114 @@
 ---
 name: design-an-interface
-description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
+description: "Generate multiple radically different interface designs for a module via parallel sub-agents, then compare and synthesize. Use when designing an API, exploring interface options, or \"design it twice\"."
 ---
 
 # Design an Interface
 
-Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+## When to use
 
-## Workflow
-
-### 1. Gather Requirements
+- The user wants to design an API, module boundary, or public interface.
+- The user asks to explore interface options or compare module shapes.
+- The user mentions "design it twice" or says the first idea is unlikely to be the best.
+- An interface design step needs a guided parallel exploration — `improve-codebase-architecture` invokes this skill for its multi-design step.
 
-Before designing, understand:
+## When NOT to use
 
-- [ ] What problem does this module solve?
-- [ ] Who are the callers? (other modules, external users, tests)
-- [ ] What are the key operations?
-- [ ] Any constraints? (performance, compatibility, existing patterns)
-- [ ] What should be hidden inside vs exposed?
+- The user wants a single justified recommendation with tradeoff analysis — use `technical-direction` instead.
+- The module's shape is already fixed by an upstream contract or framework, so exploring alternatives is wasted effort.
+- The question is about implementation strategy, not interface shape.
 
-Ask: "What does this module need to do? Who will use it?"
+## Philosophy / rationale
 
-### 2. Generate Designs (Parallel Sub-Agents)
+- **Your first idea is unlikely to be the best.** "Design It Twice" (John Ousterhout, *A Philosophy of Software Design*) holds that the first design is almost never the strongest. Generating multiple radically different candidates forces the comparison that finds the best shape.
+- **Contrast, not volume, creates insight.** Similar designs from parallel agents only confirm one idea. Each agent is assigned a different constraint so divergence is guaranteed by construction.
+- **Interface shape is the whole problem here.** The process stops at the interface — implementation effort is irrelevant to the comparison, because a good interface usually makes the implementation easier, not harder. Judging designs by implementation cost rewards shallow modules.
 
-Spawn 3+ sub-agents simultaneously using {{TOOL:task}}. Each must produce a **radically different** approach.
+## Workflow
 
-```
-Prompt template for each sub-agent:
+1. **Gather requirements.** Before designing, pin down:
+   - What problem does the module solve?
+   - Who are the callers (other modules, external users, tests)?
+   - What are the key operations?
+   - What constraints apply (performance, compatibility, existing patterns)?
+   - What should be hidden inside vs exposed?
 
-Design an interface for: [module description]
+   Ask: "What does this module need to do? Who will use it?"
 
-Requirements: [gathered requirements]
+2. **Generate designs with parallel sub-agents.** Spawn 3+ sub-agents simultaneously with {{TOOL:task}}, each assigned a **different** constraint to guarantee radical difference. Use this prompt template per agent:
 
-Constraints for this design: [assign a different constraint to each agent]
-- Agent 1: "Minimize method count - aim for 1-3 methods max"
-- Agent 2: "Maximize flexibility - support many use cases"
-- Agent 3: "Optimize for the most common case"
-- Agent 4: "Take inspiration from [specific paradigm/library]"
+   ```
+   Design an interface for: [module description]
 
-Output format:
-1. Interface signature (types/methods)
-2. Usage example (how caller uses it)
-3. What this design hides internally
-4. Trade-offs of this approach
-```
+   Requirements: [gathered requirements]
 
-### 3. Present Designs
+   Constraints for this design: [assign a different constraint to each agent]
+   - Agent 1: "Minimize method count — aim for 1-3 methods max"
+   - Agent 2: "Maximize flexibility — support many use cases"
+   - Agent 3: "Optimize for the most common case"
+   - Agent 4: "Take inspiration from [specific paradigm/library]"
 
-Show each design with:
+   Output format:
+   1. Interface signature (types/methods)
+   2. Usage example (how a caller uses it)
+   3. What this design hides internally
+   4. Trade-offs of this approach
+   ```
 
-1. **Interface signature** - types, methods, params
-2. **Usage examples** - how callers actually use it in practice
-3. **What it hides** - complexity kept internal
+   Collect each agent's output with {{TOOL:read_agent}} when it finishes.
 
-Present designs sequentially so user can absorb each approach before comparison.
+3. **Present designs.** Show each design sequentially — signature, usage examples, what it hides — so the user absorbs each approach before any comparison happens.
 
-### 4. Compare Designs
+4. **Compare designs.** Compare in prose, not tables, on:
+   - **Interface simplicity** — fewer methods, simpler params
+   - **General-purpose vs specialized** — flexibility vs focus
+   - **Implementation efficiency** — does the shape allow efficient internals?
+   - **Depth** — small interface hiding significant complexity (deep module, good) vs large interface with thin implementation (shallow module, avoid)
+   - **Ease of correct use** vs ease of misuse
 
-After showing all designs, compare them on:
+   Highlight where the designs diverge most — that divergence is where the decision lives.
 
-- **Interface simplicity**: fewer methods, simpler params
-- **General-purpose vs specialized**: flexibility vs focus
-- **Implementation efficiency**: does shape allow efficient internals?
-- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
-- **Ease of correct use** vs **ease of misuse**
+5. **Synthesize.** Ask: "Which design best fits your primary use case?" and "What elements from other designs are worth incorporating?" Often the best design combines insights from multiple options.
 
-Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+## Red Flags
 
-### 5. Synthesize
+- **Sub-agents converging on similar designs** — if two agents produce near-identical shapes, re-run with sharper, more opposed constraints. Similarity means the contrast step lost its value.
+- **Skipping comparison** — jumping from presentation to a favorite design discards the whole point of exploring alternatives.
+- **Sliding into implementation** — this process concerns interface shape only. Implementation details belong in a follow-up task.
+- **Judging designs by implementation effort** — a design that looks harder to build may still be the deeper, better interface.
 
-Often the best design combines insights from multiple options. Ask:
+## Common Rationalizations
 
-- "Which design best fits your primary use case?"
-- "Any elements from other designs worth incorporating?"
+| Rationalization | Rebuttal |
+|---|---|
+| "My first design is probably fine" | That is exactly the assumption "design it twice" exists to break. Generate the alternatives before committing. |
+| "The agents will just produce similar things, so why bother" | Similarity is a failure mode you control — assign opposed constraints so divergence is guaranteed by construction. |
+| "I can compare these myself, no need to present each one" | Sequential presentation forces you to articulate what each design actually is before judging it, which is where the insight comes from. |
 
-## Evaluation Criteria
+## Phase-gate checklists
 
-From "A Philosophy of Software Design":
+- [ ] Phase 1 complete: requirements gathered and constraints listed
+- [ ] Phase 2 complete: 3+ designs returned, each constrained differently
+- [ ] Phase 3 complete: all designs presented sequentially
+- [ ] Phase 4 complete: comparison shared and divergence highlighted
+- [ ] Phase 5 complete: candidate synthesized with user input
 
-**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+## Cross-skill references
 
-**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+- `improve-codebase-architecture` invokes this skill for its multi-design step (step 5 of its workflow).
+- Run `grill-with-docs` when the module's domain terminology is unsettled — design names should match the ubiquitous language.
 
-**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+## Examples
 
-**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+Input: "Design the interface for a rate limiter module"
+Output: four radically different interface sketches (minimal-method, flexible, common-case-optimized, paradigm-inspired), presented sequentially, compared on simplicity, depth, and trade-offs, then synthesized into one recommended shape with the user.
 
-## Anti-Patterns
+## Verification checklist
 
-- Don't let sub-agents produce similar designs - enforce radical difference
-- Don't skip comparison - the value is in contrast
-- Don't implement - this is purely about interface shape
-- Don't evaluate based on implementation effort
+- [ ] Requirements captured before any sub-agent is spawned
+- [ ] At least 3 sub-agents spawned, each with a distinct constraint
+- [ ] Each design reports signature, usage example, hidden complexity, and trade-offs
+- [ ] Designs presented sequentially before any comparison
+- [ ] Comparison covers simplicity, generality, efficiency, depth, and ease of correct use
+- [ ] Synthesis asks the user which design fits their primary use case
+- [ ] No implementation work performed — interface shape only