@jaybeeuu/agent-cortex 2.1.0 → 2.3.0

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

@@ -1,117 +0,0 @@
-# Skill Improvements: Lessons from addyosmani/agent-skills
-
-This is a promoted research note.
-
-
-> Source: https://github.com/addyosmani/agent-skills  
-> Reviewed: 2026-05-26
-
-## Summary
-
-Compared our skills with addyosmani/agent-skills across structure, tone, and evidence-backed
-patterns. Their skills are consistently richer (200–350 lines vs our 50–170), follow a strict
-shared skeleton, and include several patterns backed by LLM research that we currently lack.
-
----
-
-## What they do that we don't
-
-### 1. "Common Rationalizations" table
-
-Every skill includes a table debunking common excuses for not following it:
-
-| Rationalization | Reality |
-|---|---|
-| "Tests slow me down" | Tests slow you now. They speed you up every change later. |
-
-**Evidence**: LLM sycophancy research (Perez et al.; Anthropic Constitutional AI) shows models
-rationalise away inconvenient instructions. Naming these in the prompt preemptively counters
-the behaviour.
-
----
-
-### 2. "When NOT to use" sections
-
-Every skill explicitly states when _not_ to invoke it:
-
-> "When NOT to use: Single-line fixes, typo corrections, or changes where requirements are
-> unambiguous and self-contained."
-
-**Evidence**: Wang et al. (SuperNaturalInstructions, 2022) — explicit out-of-scope boundaries
-reduce false-positive invocations and improve precision.
-
----
-
-### 3. "Red Flags" list
-
-Concrete, detectable anti-patterns named inline:
-
-- "Bug fixes without reproduction tests"
-- "Tests that pass on the first run"
-
-**Evidence**: Contrastive examples (positive + negative) improve instruction adherence. Naming
-failure modes alongside correct behaviour helps models self-correct.
-
----
-
-### 4. Verification checklists at the end
-
-Every skill ends with a checkbox list:
-
-```
-- [ ] Every new behavior has a corresponding test
-- [ ] All tests pass: `npm test`
-```
-
-**Evidence**: Wei et al. (Chain-of-Thought, 2022) — decomposing into explicit steps reduces
-omission errors and improves task completion reliability.
-
----
-
-### 5. Concrete code/output examples
-
-Skills show realistic before/after examples, not just abstract descriptions.
-
-**Evidence**: Brown et al. (GPT-3, 2020) — few-shot examples consistently outperform abstract
-prose descriptions for in-context learning.
-
----
-
-### 6. 100-line limit is too restrictive
-
-Our `write-a-skill` caps SKILL.md at 100 lines. The addyosmani skills are 200–350 lines and
-their richness (rationalizations, red flags, examples, checklists) directly follows from that
-budget. The constraint is working against us.
-
-**Proposed change**: "prefer under 150 lines; overflow rarely-needed reference detail into
-REFERENCE.md" — keeping SKILL.md as the primary working document rather than gutting it.
-
----
-
-## What we do better
-
-- **Workflow depth**: `run-beads` + `ralph` encode a full pipeline (test-writing → coding →
-  verifying → reviewing → fixing → documenting) that the external skills can't match.
-- **Philosophy**: `tdd` has a more rigorous treatment of vertical slicing and horizontal-slice
-  anti-patterns than the external TDD skill.
-- **Domain specificity**: our skills are tightly integrated with `bd`, worktrees, and the ralph
-  orchestrator — that's genuine value the external repo can't offer.
-- **Progressive disclosure**: `REFERENCE.md` + `EXAMPLES.md` support already documented.
-
----
-
-## Bead IDs
-
-| Improvement | Status |
-|---|---|
-| Common Rationalizations tables | Planned |
-| When NOT to use sections | Planned |
-| Red Flags sections | Planned |
-| Verification checklists | Planned |
-| Concrete examples | Planned |
-| Reconsider 100-line limit | Done (raised to 150) |
-| ASCII workflow diagrams | Done (ASCII-only style guide in skill-anatomy.md) |
-| Cross-references between skills | Planned |
-| Consistent skeleton template | Partially adopted |
-
-[Inspirations](../inspirations.md)

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

@@ -1,24 +0,0 @@
-# Skill Pattern Research Notes
-
-A promoted research note collecting evidence behind recurring skill structure patterns.
-
-## Patterns and evidence
-
-1. **Explicit scope boundaries improve instruction following**
-   - Super-NaturalInstructions (Wang et al., 2022): broad, explicit instruction framing improves task generalization.
-2. **Concrete examples outperform abstract-only guidance**
-   - GPT-3 paper (Brown et al., 2020): few-shot examples consistently improve downstream behavior.
-3. **Checklists reduce skipped steps**
-   - Chain-of-Thought prompting (Wei et al., 2022): structured intermediate prompts improve completion reliability.
-4. **Constrained behavior framing lowers unsafe compliance**
-   - Constitutional AI (Bai et al., 2022) and sycophancy analyses (Perez et al., 2022): explicit refusal/constraint framing improves adherence.
-
-## References
-
-- https://arxiv.org/abs/2204.02311
-- https://arxiv.org/abs/2005.14165
-- https://arxiv.org/abs/2201.11903
-- https://arxiv.org/abs/2212.08073
-- https://arxiv.org/abs/2211.03873
-
-[Inspirations](../inspirations.md)

package/docs/skills/skill-anatomy.md

@@ -1,200 +0,0 @@
-# Skill Anatomy
-
-This document is the **canonical skill anatomy** for `agent-cortex` skills.
-Use it as the source of truth for `SKILL.md` structure, language, and review quality gates.
-
-## Front-matter spec
-
-Required fields:
-- `name`: kebab-case skill identifier.
-- `description`: max 1024 characters.
-
-Frontmatter is machine-validated: `pnpm lint` runs `check:skills`, which fails on a
-frontmatter block that would make pi silently drop the skill.
-
-Optional fields:
-- `argument-hint`: input prompt shown to users at invocation.
-- `disable-model-invocation`: hides the skill from automatic model routing; explicit
-  `/skill-name` invocation still works. Set it when the danger is a fuzzy description
-  match, e.g. a skill whose steps are destructive. Preserved and honoured by pi and
-  Claude Code. See `docs/research/disable-model-invocation.md`.
-
-## Description format rules
-
-- Target ≤200 characters even though max is 1024.
-- Write in third-person declarative voice.
-- Sentence 1: what the skill does.
-- Sentence 2: starts with `Use when ...`.
-- Include 2-4 natural user trigger phrases (quoted) such as "diagnose this" or "something is broken".
-- Prefer user vocabulary over internal jargon.
-
-## Voice and tone rules
-
-- Write the body in imperative second-person: "Run X", "Check Y", "Report Z".
-- Use positive framing; reserve "do not" only for hard safety/correctness boundaries.
-- Add one rationale sentence for non-obvious rules so behavior generalizes in novel cases.
-- Avoid ALL-CAPS emphasis.
-
-## Tool references
-
-Reference agent tools by `{{TOOL:name}}` token (canonical authoring name), never a
-hardcoded harness-specific name such as `bash`, `task`, or `read_agent` — installers
-substitute the per-harness name from `token-map.json` at install time. Add any new tool
-to the map's `tools` section in the same change; unknown tokens are hard errors. See
-`token-map.README.md` for the full authoring rules.
-
-## Required sections
-
-Every skill must include:
-1. `## When to use`
-2. `## Workflow` (numbered steps)
-3. `## Verification checklist` (`- [ ]` items)
-
-## Optional sections
-
-For each optional section, define **what it is**, include an **example snippet**, and state **when to include** and **when to omit**.
-
-| Section | What it is | Example snippet | When to include | When to omit |
-|---|---|---|---|---|
-| `When NOT to use` | Explicit out-of-scope invocation boundaries | `- When NOT to use: single-line typo fixes with no process risk.` | Skills with similar neighbors where invocation precision matters | Truly unique one-purpose utility skills |
-| `Red Flags` | Detectable anti-patterns the agent should self-correct during execution | `- Red flag: skipping boundary validation to save time.` | Discipline-enforcement skills (security, TDD, review) | Simple utility wrappers |
-| `Common Rationalizations` | Excuses models use to skip process with rebuttals | `| "This is small" | Small changes still need invariants checked. |` | Process-critical skills where shortcut pressure is common | Mechanical one-step skills |
-| `Philosophy / rationale` | Why the method exists and what trade-offs it protects | `- We front-load validation because downstream rollback cost is higher.` | Opinionated skills expected to handle novel variants | Purely mechanical instructions |
-| `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
-
-### When to use
-
-State concrete invocation triggers using natural language phrases users actually type.
-
-### When NOT to use
-
-Place this section immediately after `When to use` whenever present.
-
-### Workflow
-
-Provide ordered, deterministic steps with observable outcomes.
-
-### Verification checklist
-
-Provide completion gates that are testable and stage-scoped.
-
-## File layout and progressive disclosure
-
-- Target ~150 lines for `SKILL.md`.
-- Split long docs into purpose-named support files:
-  - `EXAMPLES.md` for worked examples.
-  - `FORMAT.md` for schemas/templates.
-  - `REFERENCE.md` for rare edge cases.
-- Use slash-command references when another skill should be invoked.
-
-## Acceptance criteria checklist
-
-A skill passes anatomy review when:
-- [ ] Front matter uses required fields and valid description format.
-- [ ] 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.
-
-## Annotated template
-
-```md
----
-name: skill-name
-description: This skill performs a specific capability. Use when a user asks for a matching workflow such as "triage this", "investigate this", or "prepare a handoff".
-argument-hint: Optional prompt shown to users when extra input is needed.
-disable-model-invocation: false
----
-
-# Skill Name
-
-## When to use
-
-- Trigger phrases users actually say, e.g. "triage this failure".
-- Include 2-4 concrete patterns.
-
-## When NOT to use
-
-- Out-of-scope cases that should route elsewhere.
-
-## Workflow
-
-1. Gather required context and validate scope boundaries.
-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
-
-- Red flag: skipping validation of unknown external input.
-
-## Common Rationalizations
-
-| Rationalization | Rebuttal |
-|---|---|
-| "This is too small for process" | Process protects against regressions regardless of size. |
-
-## Philosophy / rationale
-
-- We optimize for explicit boundaries because they reduce rework and improve reliability.
-
-## Phase-gate checklist
-
-- [ ] Phase 1 complete and baseline checks captured.
-- [ ] Phase 2 complete and contract validation passed.
-
-## Cross-skill references
-
-- Run `review-security` before committing any externally exposed change.
-
-## Examples
-
-Input: "Investigate this flaky suite"
-Output: concise root-cause summary, failing tests list, and next action.
-
-## Verification checklist
-
-- [ ] Output matches requested format.
-- [ ] Required tests/lints were run and results recorded.
-- [ ] No unrelated files were changed.
-```

package/docs/technical-direction/harness-config.md

@@ -1,177 +0,0 @@
-# Technical Direction: Harness config and third-party extensions
-
-## Status
-
-**Partly superseded (2026-10-24) by the staged-package model** (`agnt-ctx-7kru`). Two premises
-below no longer hold:
-
-- **The pi half landed without bundling.** `agent-cortex install pi` stages a self-contained
-  package at `~/.agent-cortex/pi` and copies the required third-party packages — resolved
-  through Node's own resolution — into that tree's `node_modules/`, instead of declaring
-  `bundledDependencies` in the published tarball. pi loads a local directory and resolves no
-  npm packages itself, so a tarball's `node_modules/` reached nobody; bundling also forced a
-  repo-wide `node-linker=hoisted`, surrendering pnpm's isolated resolution for the workspace.
-- **pi's own settings are no longer installer output.** The installer writes nothing into
-  `~/.pi/agent`; it registers the staged package by driving pi's own `pi install` /
-  `pi remove` commands, which own `settings.json` → `packages[]`. `pi/settings.json` and
-  `pi/keybindings.json` are reference templates. Registration's invariant is **one
-  agent-cortex source**: a source pointing at a raw agent-cortex checkout is removed first,
-  and one that survives `pi remove` fails the run rather than leave two sources configured
-  that both load.
-
-`pi.packages` and `lib/pi-packages.mjs` are deleted, so the bespoke-pi-mechanism problem this
-memo was written to settle is closed. The Claude analysis stands; Copilot CLI is no longer a
-deploy target (`agnt-ctx-2rl`).
-
-## Problem and target outcome
-
-- **What we are solving.** agent-cortex ships agents and skills to two harnesses (pi, Claude
-  Code) and needs a declared, reproducible set of *third-party* extensions those agents depend
-  on (pi packages / Claude plugins). Two bespoke mechanisms currently exist and
-  disagree: `main` declares packages in `package.json` → `pi.packages` and provisions them from
-  `lib/pi-packages.mjs`; the unmerged pi-harness epic (`agnt-ctx-dfq3`) declares them in
-  `pi.extensions.json` / `claude.extensions.json` and provisions them via `agent-cortex ext
-  install`. **Neither file is read by any harness** — both are agent-cortex inventions.
-- **Target outcome.** One idiomatic mechanism per harness: extensions the agents *require* are
-  resolved by the harness's native dependency field; extensions that are *optional* are declared
-  in the harness's committed settings template. No bespoke manifest format survives.
-- **Why now.** The epic is unmerged and diverging from `main` (7 commits behind), and PR #142
-  (`ext prune`) was closed as redundant with the harnesses' own package management. Keeping both
-  models means keeping the drift the original idea set out to remove.
-
-## Current-state constraints
-
-- **Public package.** `publishConfig.access: public`, npm `@jaybeeuu/agent-cortex@1.40.0` — every
-  bundled dependency or committed template affects anyone who installs the package, not just the
-  author.
-- **pi is idiomatic two ways.** Machine state is `~/.pi/agent/settings.json` → `packages[]`, owned
-  by `pi install/remove/list`. A package's own resource declarations live in `package.json` → `pi`
-  (`extensions`, `skills`, `prompts`, `themes`); third-party pi packages are depended on via
-  `dependencies` + `bundledDependencies` and referenced through `node_modules/…`. **There is no
-  `pi.packages` field** — pi ignores it.
-- **Claude is idiomatic two ways.** Machine state is `~/.claude/settings.json` → `enabledPlugins`
-  + `extraKnownMarketplaces`. A plugin declares other plugins in `.claude-plugin/plugin.json` →
-  `dependencies`, which Claude Code resolves and auto-installs.
-- **The epic already built two-thirds of the target.** Unmerged commit `afab2c6` (F3) materialises
-  `pi/settings.json` + `pi/keybindings.json` from committed templates with merge-keep-personal and
-  the CLI owning `packages`; `1ff212d` (F4) makes bundled pi extensions load via package
-  registration. Only `1e0e970` (F5, the bespoke manifests) is off-direction.
-- **Unknowns resolved during this memo:** pi bundling is feasible (see Validation plan); Claude
-  dependency auto-install is real but cross-marketplace needs an allowlist; Claude currently
-  declares **zero** third-party plugins.
-
-## Options considered
-
-### Option A: one bespoke config per harness
-
-- **Approach.** A `config/<harness>.json` (or the epic's `*.extensions.json`) holds settings and
-  the extension list; the CLI provisions from it.
-- **Pros.** Uniform across harnesses; full control; explicit single place to look.
-- **Cons.** A third format that neither harness reads; duplicates the native `packages` /
-  `enabledPlugins` fields; re-creates the manifest-vs-machine drift the idea exists to remove.
-- **Risks.** The redundancy that made `ext prune` (F6) not worth building.
-
-### Option B: native dependency fields + committed settings templates *(recommended)*
-
-- **Approach.** Required extensions → `dependencies` + `bundledDependencies` (pi) and
-  `.claude-plugin/plugin.json` `dependencies` (Claude). Optional extensions → the harness's own
-  committed settings template (`pi/settings.json` `packages`; `claude/settings.json`
-  `enabledPlugins` + `extraKnownMarketplaces`), materialised with merge-keep-personal. Drop the
-  bespoke manifests, the `ext install`/`ext prune` family, and the separate diff command —
-  `agent-cortex install <harness>` reconciles.
-- **Pros.** Idiomatic; no bespoke format; each harness resolves its own required deps; the
-  optional list lives in the file the harness already reads, so `pi list` / `claude plugin list
-  --json` are the exact machine-state comparison; drift self-heals on install.
-- **Cons.** pi bundling shifts update cadence to agent-cortex releases and grows the tarball;
-  Claude cross-marketplace deps need an allowlist; the committed template also carries personal
-  settings.
-- **Risks.** Loading TS extensions from bundled `node_modules/`; maintaining the Claude
-  cross-marketplace allowlist.
-
-### Option C: fully delegate to the harnesses
-
-- **Approach.** pi bundles its deps, Claude auto-installs plugin deps, `install` only registers;
-  there is no optional layer at all.
-- **Pros.** Least code; no declaration surface to maintain.
-- **Cons.** No way to declare the optional/opt-in personal toolset; the original problem —
-  "the toolset isn't reproducible or documented" — goes unsolved for everything not strictly
-  required.
-- **Risks.** Silently drops the reproducibility goal.
-
-## Recommendation
-
-**Option B.** It is the only option that satisfies both halves of the problem: *required*
-extensions resolve through the harness's own mechanism (so an agent's tools can't be missing),
-and *optional* ones stay declared and reproducible without inventing a format the harnesses
-ignore. It also deletes the most code — the two competing bespoke models, `lib/pi-packages.mjs`,
-and the `ext` command family — rather than adding a third.
-
-Alternatives were not chosen because: **A** keeps a third format and the drift it causes; **C**
-abandons the declared-toolset goal that started the work.
-
-**Concrete disposition:** salvage the epic's F3 (`afab2c6`) and F4 (`1ff212d`) — they *are* the
-settings-template and bundled-dependency mechanisms — drop F5/F6 (`1e0e970` and PR #142), close
-the epic, and delete `pi.packages` + `lib/pi-packages.mjs` from `main`.
-
-## Tradeoffs accepted
-
-- **pi bundling changes update cadence.** Bundled pi packages are pinned by agent-cortex's
-  `package.json` ranges and update when agent-cortex releases, not via `pi update`. Accepted: it
-  makes the required toolset a property of agent-cortex rather than of the machine.
-- **Tarball size.** `pi-web-access` pulls 5 runtime deps (readability, linkedom, p-limit, turndown,
-  unpdf). Accepted for the required set; the optional set stays provisioned, not bundled.
-- **Claude cross-marketplace allowlist.** If a required Claude plugin lives in another
-  marketplace, agent-cortex's `marketplace.json` must list it in
-  `allowCrossMarketplaceDependenciesOn`. Accepted; currently moot (zero declared plugins).
-- **Committed personal settings.** `pi/settings.json` already carries models/theme; the template
-  model makes the repo own the whole pi settings surface. Accepted; F3's merge preserves personal
-  keys and only `packages` is CLI-owned.
-- **No dedicated diff command.** A read-only `status` is deferred until drift is shown to hurt.
-
-## Validation plan
-
-Run before implementation (three already run during this memo):
-
-1. **Can `pi-questions` / `pi-web-access` be bundled and load from `node_modules/`?** ✅ *Ran.*
-   `pi-questions@0.3.4` is a single extension file with no deps or install-time state;
-   `pi-web-access@0.10.7` is an extension + skills with 5 runtime deps. Both are conventional pi
-   packages — bundling is feasible. Success signal: a scratch package depending on both loads
-   `ask_questions` / `fetch_content` in a fresh pi session.
-2. **Does Claude's `plugin.json` `dependencies` auto-install from agent-cortex's marketplace?**
-   ✅ *Ran.* Yes, but cross-marketplace deps require `allowCrossMarketplaceDependenciesOn` in the
-   root `marketplace.json`, and version constraints need `{plugin-name}--v{version}` git tags.
-3. **Does F3 reconcile `packages` when the template drops one?** ✅ *Ran.* Yes — the CLI owns
-   `packages` outright, so removing an entry from the template removes it on next install. The
-   documented limitation is the reverse (ad-hoc `pi install` entries don't persist), which is
-   intended.
-
-Still to run before shipping: a scratch end-to-end install on a clean `HOME` proving a required
-pi extension loads from `node_modules/` and an optional one is materialised from the template.
-
-## Revisit triggers
-
-- pi or Claude ship a first-class *optional* dependency field, making the settings template
-  unnecessary.
-- Claude still declares zero third-party plugins after the migration — then Claude parity is
-  speculative and should be dropped rather than maintained.
-- Bundling `pi-web-access`'s native-ish dependency tree (unpdf, linkedom) proves brittle or
-  unacceptable on a fresh machine.
-- Drift between the committed template and the machine becomes a recurring annoyance — add the
-  deferred read-only `status`.
-
-## References
-
-- pi docs, *Settings* and *Packages* (installed at
-  `…/@earendil-works/pi-coding-agent@0.85.1/docs/settings.md`, `…/docs/packages.md`): `packages`
-  array is the machine store; the `pi` manifest keys are `extensions`/`skills`/`prompts`/`themes`;
-  other pi packages are bundled and referenced through `node_modules/`.
-- Claude Code, *Constrain plugin dependency versions* — https://code.claude.com/docs/en/plugin-dependencies
-  (auto-install, cross-marketplace allowlist, tag naming).
-- Claude Code, *Settings* — https://code.claude.com/docs/en/settings (`enabledPlugins`,
-  `extraKnownMarketplaces`).
-- Code evidence (as of 2026-09 — `pi.packages` and `lib/pi-packages.mjs` were removed in
-  `agnt-ctx-7kru.1`, see Status): `package.json` (`pi.packages`), `lib/pi-packages.mjs` (main's
-  provisioner);
-  `pi.extensions.json`, `claude.extensions.json`, `lib/extension-manifest.mjs` (epic F5, `1e0e970`);
-  `bin/installers/pi.mjs` settings materialisation (epic F3, `afab2c6`);
-  `docs/ideas/extension-manifests.md` (the originating idea).