@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

package/docs/inspirations.md

@@ -1,33 +0,0 @@
-# Inspirations
-
-A living record of external repos and promoted internal research that inform agent-cortex skill and agent design.
-
-## Internal research docs
-
-- [Gas City research](research/gas-city-research.md)
-- [Skill pattern research notes](research/skill-patterns-research.md)
-- [Skill design research](research/skill-design-research.md)
-- [Skill improvements analysis](research/skill-improvements-analysis.md)
-
-## addyosmani/agent-skills
-
-**URL**: https://github.com/addyosmani/agent-skills  
-**Last reviewed**: 2026-05-26  
-**Type**: Public skill collection (Claude Code / OpenCode)
-
-### Structure patterns worth noting
-
-| Pattern | Description | Adopted? |
-|---|---|---|
-| Consistent skeleton | Every skill follows a shared, predictable section model | Partially |
-| "When NOT to use" | Explicit out-of-scope conditions in every skill | Planned |
-| "Common Rationalizations" | Debunks excuses for skipping process steps | Planned |
-| "Red Flags" | Concrete anti-patterns to detect during execution | Planned |
-| Verification checklist | Completion gate in each skill | Planned |
-| Cross-references | `See Also` links to related skills | Planned |
-
-## Matt Pocock — skills repo
-
-**URL**: https://github.com/mattpocock/skills  
-**Last reviewed**: 2026-05-26  
-**Type**: Public skill collection

package/docs/research/disable-model-invocation.md

@@ -1,82 +0,0 @@
-# `disable-model-invocation` across harnesses
-
-Decision record for the frontmatter field this repo uses to keep rare or destructive
-skills out of automatic model routing (bead `agnt-ctx-yf24`).
-
-**Verdict:** rely on it for pi and Claude Code.
-
-## What the field does
-
-`disable-model-invocation: true` removes a skill from the list the model is offered.
-The user can still invoke it explicitly. It does not summarise, rewrite, or
-otherwise change how the body loads, which is what `docs/skills/skill-anatomy.md`
-previously implied.
-
-## Preservation and honouring
-
-| Harness | Field survives materialisation | Loader honours it | Evidence |
-| --- | --- | --- | --- |
-| pi 1.4.0 | Yes — byte-identical copy | Yes — hidden from the prompt, `/skill:name` still works | `bin/installers/pi.mjs:182-204`, `scripts/lib/compose-agent.mjs:69-95`; `dist/core/skills.js:262` (parse) and `:279` (filter); `docs/skills.md:53` |
-| Claude Code 2.1.294 | Yes — byte-identical copy | Yes — Claude cannot invoke it, `/skill-name` still works | `bin/installers/claude.mjs:160-201`, same token helper; [Claude Code skills docs](https://code.claude.com/docs/en/skills) ("Control who invokes a skill") |
-
-Both materialisers copy `SKILL.md` as text and rewrite only `{{TOOL:...}}` /
-`{{PATH:...}}` tokens, so frontmatter keys they do not know pass through untouched —
-nothing re-serialises YAML. Verified by installing both harnesses into
-`/var/tmp/dmi-check` and diffing `skills/productivity/teach/SKILL.md` (the repo's
-only current user of the field): both copies are byte-identical to the source.
-`claude plugin validate /var/tmp/dmi-check/claude/skills` passes, i.e. Claude Code's
-own validator accepts the field rather than warning about it.
-
-pi was probed against the materialised tree with its own loader: 32 skills loaded,
-31 advertised, `teach` parsed with `disableModelInvocation: true` and absent from
-`formatSkillsForPrompt` output.
-
-## Per-harness detail
-
-**pi.** Documented and implemented. `docs/skills.md:53`: "Set
-`disable-model-invocation: true` in frontmatter when a skill should be available only
-through its explicit command", with the frontmatter table listing it as "Hide the
-skill from automatic model selection".
-
-**Claude Code.** Documented, and the docs are explicit about the enforcement: "Claude
-can't invoke the skill on its own … If Claude tries anyway, Claude Code blocks the
-call and instructs it not to reproduce the deploy steps another way", and it "removes
-the skill from Claude's context entirely".
-
-Two Claude-specific caveats:
-
-- The field is a Claude Code extension, not part of the
-  [Agent Skills spec](https://agentskills.io/specification), whose six fields
-  (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`)
-  are otherwise exhaustive. Claude Code ignores unknown fields, but packing or
-  uploading a skill to claude.ai (or through the Skills API) "fails with a hard error
-  instead of ignoring the field". Our plugin path is unaffected; a skill we ever
-  publish to claude.ai must drop the field.
-- `skillOverrides` does not apply to plugin skills, and our install is a plugin. The
-  frontmatter field itself still applies there — only that settings-based alternative
-  is unavailable.
-
-## Options for "explicit invocation only", evaluated
-
-| Option | Portable? | Enforced? | Verdict |
-| --- | --- | --- | --- |
-| `disable-model-invocation: true` | pi + Claude Code yes | Yes | **Recommended** where suppressing auto-routing is the point and the explicit path is a human typing `/name` |
-| Naming convention (e.g. `manual-*`) | Yes | No — no harness reads names | Rejected: a human signal we already get from the body |
-| `metadata:` block | Yes (spec-legal) | No — pi and Claude read top-level keys only | Rejected: documentation that looks like enforcement |
-| Keep such skills out of `skills/` | Yes | Yes, by not shipping the skill | Rejected: gives up the per-harness install entirely |
-
-## Recommendation
-
-Use the field when the danger is fuzzy automatic matching and the intended explicit
-path is a human typing `/skill-name`: that is the case for a migration skill whose
-`--apply` renames labels workspace-wide.
-
-## Reproducing
-
-```sh
-node bin/agent-cortex.mjs install claude  --output /var/tmp/dmi-check/claude
-node bin/agent-cortex.mjs install pi      --output /var/tmp/dmi-check/pi
-diff skills/productivity/teach/SKILL.md /var/tmp/dmi-check/claude/skills/teach/SKILL.md
-diff skills/productivity/teach/SKILL.md /var/tmp/dmi-check/pi/skills/productivity/teach/SKILL.md
-claude plugin validate /var/tmp/dmi-check/claude/skills
-```

package/docs/research/gas-city-research.md

@@ -1,256 +0,0 @@
-# Gas City Research Notes
-
-This is a promoted research note.
-
-
-Research conducted 2026-05-03/04. Source: `gastownhall/gascity` and related `gastownhall/*` repos.
-
----
-
-## What is Gas City?
-
-Gas City is a Go-based multi-agent orchestration SDK (`gc` CLI, v1.0.0, released 2026-04-21, MIT licence).
-It manages **live interactive agent sessions** (Claude Code, Codex CLI, etc. running in tmux) rather than
-making raw LLM API calls. It is not a replacement for LLM API access — it is a rack manager for persistent
-agent processes.
-
-Gas City is built on the **MEOW stack** (Molecular Expression of Work) — the same `bd` (beads) tooling
-already in use in this repo.
-
----
-
-## The MEOW Stack
-
-MEOW = **Molecular Expression of Work**. A layered work-decomposition and tracking infrastructure:
-
-```
-Formulas / Orders    ← TOML templates defining workflow shape + when it fires
-       ↑
-Molecules / Wisps    ← durable chained bead workflows; instances of formulas
-       ↑
-Epics                ← hierarchical bead grouping (parent/child beads)
-       ↑
-Beads                ← atomic git-backed work units (the bd CLI)
-```
-
-**Core insight:** work is the primitive, not orchestration. The controller is a thin layer on top of the
-MEOW stack. Work definition and tracking is what matters; orchestration shape is configurable on top.
-
-**GUPP (Gas Town Universal Propulsion Principle):** *"If you find something on your hook, you run it."*
-Agents are stateless pistons; the bead store is the engine.
-
----
-
-## Key Concepts
-
-### Rigs
-A **rig** is an external project directory (git repo) registered with a city. Each rig gets its own beads
-database, agent hooks, and pack expansion. One city can manage multiple rigs (multiple repos) — this is
-the primary multi-repo use case.
-
-```toml
-# city.toml
-[[rigs]]
-name = "my-api"
-
-[[rigs]]
-name = "my-frontend"
-```
-
-### City
-A deployment of packs + rigs under one controller. The controller runs as a persistent Go process managing
-all sessions in all rigs.
-
-### Packs / Formulas
-Reusable TOML configuration bundles. A **formula** is a TOML workflow template defining steps and
-dependencies. A **molecule** is an instance of a formula — materialised as beads in the store.
-
-### Convergence
-The outer retry loop. When a wisp closes, the controller's `HandleWispClosed()` (a 9-step deterministic
-Go algorithm) evaluates a gate and decides: `iterate` (new wisp), `approved` (done), `no_convergence`
-(blocked), or `waiting_manual` (human required).
-
-### Orders
-Scheduled formula dispatch. Five trigger types: `cooldown`, `cron`, `condition` (shell exit 0), `event`
-(bead.closed on city bus), `manual`. Can dispatch a formula to an agent pool, or run a shell script
-directly (`exec` orders — no LLM involved).
-
----
-
-## What Gas City Gives Us
-
-| Capability | Status |
-|---|---|
-| Multi-repo orchestration (rigs) | ✅ Native — primary use case |
-| Rack / dashboard (`gc status`, SPA) | ✅ Built-in |
-| Agent lifecycle (crash recovery, idle-kill, restart) | ✅ Built-in |
-| Worktree isolation (per-agent git branch) | ✅ `isolation = "worktree"` in agent config |
-| Concurrent feature work (multiple agents, multiple branches) | ✅ Via pool + worktree isolation |
-| Scheduling / reactive triggers (Orders) | ✅ 5 trigger types |
-| Deterministic workflow routing | ✅ Controller is Go state machine (no LLM in routing path) |
-| Formula-based step sequencing | ✅ TOML DAG, `needs` dependencies, executed by `bd` |
-| Feature backlog isolation (separate bead stores) | ⚠️ Requires separate rigs; not automatic |
-| Cross-repo bead dependencies | ❌ Not supported — issue #587, milestone `1.0+`, no timeline |
-| Native loops in formulas | ❌ Formulas are DAGs; loops require the convergence engine |
-
----
-
-## Architecture: Determinism vs. Agents
-
-Gas City has a sharp boundary. The Go controller owns all routing; LLMs only do work and emit a verdict.
-
-```
-Agent works through formula steps
-    → writes convergence.agent_verdict = "approve" | "block"
-    → closes wisp
-
-Controller HandleWispClosed() [pure Go, 9-step algorithm]
-    → reads verdict (scoped to this wisp by agent_verdict_wisp)
-    → runs gate shell script (exit 0 = pass, exit 1 = fail)
-    → ActionApproved  → state=terminated, done
-    → ActionIterate   → pour new wisp, re-dispatch to agent
-    → ActionNoConvergence → state=terminated, blocked
-    → ActionWaitingManual → human must gc conv approve
-```
-
-**ACL enforcement:** agents can only write `convergence.agent_verdict` and
-`convergence.agent_verdict_wisp`. All other `convergence.*` keys require a controller token — agents
-cannot fake state transitions.
-
-**Exec orders** bypass agents entirely — a shell script runs directly on the controller. Fully
-deterministic, no LLM.
-
-### Compared to LangGraph / Temporal
-
-- Like Temporal: the convergence handler is crash-safe and idempotent (speculative-pour-before-commit).
-- Unlike LangGraph: there is no Go-level `add_edge(A, B)` for application steps. Step ordering is
-  declared in TOML and executed by `bd`'s dependency graph — static, not dynamic code.
-- The session reconciler and convergence state machine are code-defined graphs; the intra-molecule step
-  DAG is `bd`-managed.
-
----
-
-## Multi-Feature Concurrent Work
-
-**Three Jira tickets, one repo:**
-
-1. Create a bead per ticket
-2. Configure a coder pool with `isolation = "worktree"`
-3. Gas City auto-creates a git worktree per agent instance (`.gc/worktrees/<rig>/<agent>/`) on a unique
-   branch (`gc/coder-<timestamp>`)
-4. Agents work concurrently on separate branches; beads are in the shared rig store
-5. Each branch → PR → merge independently; git resolves file conflicts at merge time
-
-**Sub-task breakdown (architect → coder pattern):**
-
-1. Create an epic bead for the ticket (HITL: spend time with an agent decomposing into child beads)
-2. Child beads are labelled for the coder pool
-3. One coder agent claims the epic, works child beads sequentially in its worktree/branch
-4. Separate agents handle other tickets concurrently
-
-**True backlog isolation** (separate bead stores per feature) requires registering each feature worktree
-as its own rig — doable, more setup, only needed for truly independent multi-ticket sub-backlogs.
-
----
-
-## Worktrees: What's Automatic vs. Manual
-
-`isolation = "worktree"` in an agent's config causes Gas City to automatically:
-- Run `git worktree add .gc/worktrees/<rig>/<agent>/ -b gc/<agent>-<timestamp>`
-- Place a `.beads/redirect` file in the worktree pointing back to the shared rig bead store
-- Store `work_dir` in the bead metadata for restart recovery
-
-You do NOT manually run `git worktree add`. The controller handles it.
-
----
-
-## Bead Store Isolation Notes
-
-- One `.beads/` database per rig directory — strictly enforced
-- Worktrees share the parent rig's bead store via `.beads/redirect`
-- Two cities registering the same rig path silently share the same bead DB (acknowledged bug, issue #587)
-- `dolt_host`/`dolt_port` overrides exist as a manual escape hatch for pointing rigs at different stores
-- Concurrent workstreams within one rig: use labels (`pool:feature-a`, `pool:feature-b`) — same DB,
-  logically partitioned
-
----
-
-## Implications for agent-cortex / ralph / run-beads
-
-### Formulas for the TDD pipeline
-
-The run-beads TDD pipeline (test-writing → coding → test-reviewing → verifying → reviewing → fixing →
-documenting) maps naturally to a formula:
-
-```toml
-[[steps]]
-id = "test-writing"
-title = "Write failing tests"
-
-[[steps]]
-id = "coding"
-title = "Make the tests pass"
-needs = ["test-writing"]
-
-[[steps]]
-id = "test-reviewing"
-title = "Review the tests"
-needs = ["coding"]
-
-[[steps]]
-id = "verifying"
-title = "Run the test suite"
-needs = ["test-reviewing"]
-
-[[steps]]
-id = "reviewing"
-title = "Code review"
-needs = ["verifying"]
-
-[[steps]]
-id = "documenting"
-title = "Document the changes"
-needs = ["reviewing"]
-```
-
-`bd` handles the step ordering via the dependency graph. Each step is a bead that unlocks when the
-previous closes. No LLM in the sequencing path.
-
-**The loop** (retry if gate fails) requires Gas City's convergence engine — `bd` alone executes DAGs, not
-loops. Until Gas City is adopted, ralph (or an equivalent outer loop) is still needed for this.
-
-### What moves to the deterministic layer
-
-With Gas City:
-- Step sequencing → formula `needs` dependencies (TOML, `bd`)
-- Pass/fail routing → gate shell scripts (run tests, typecheck, lint)
-- Retry loop → convergence engine (Go, deterministic)
-- `generate-progress.ts` → largely replaceable by `gc status` / `bd` queries
-- Ralph's dispatch table → formula + gate config
-
-### The remaining gap
-
-Cross-repo dependencies (e.g. "don't merge the API until the frontend bead closes") are not natively
-supported. Workaround: a `condition` Order that shell-polls the upstream rig's `bd` state.
-
----
-
-## Community / Maturity
-
-- Version: v1.0.0 (stable, 2026-04-21) — 610 commits in the v0.15.1→1.0.0 sprint
-- Language: Go (1.25+)
-- `gastownhall/beads` (the `bd` CLI): 23,049 ⭐, 1,510 forks
-- Daily commit cadence; team self-hosts using Gas City (highest-signal feedback loop)
-- MIT licence
-- Active milestones: `1.0+`
-
----
-
-## Open Issues Relevant to Us
-
-| Issue | Title | Status |
-|---|---|---|
-| #587 | Multi-city rig and bead-state separation (Pack/City v2) | Open, accepted, no design yet |
-| #907 | Hardcoded 'hq' DB name prevents multi-city Dolt sharing | Open, `1.0+` |
-
-[Inspirations](../inspirations.md)

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

@@ -1,286 +0,0 @@
-# Skill Design Research: Recommendations for agent-cortex
-
-This is a promoted research note.
-
-
-*Researched: 2026-05-26 — compares `mattpocock/skills` (commit b8be62f) against this repo's skills, cross-referenced with empirical prompt-engineering literature.*
-
----
-
-## 1. Executive Summary
-
-Three parallel research streams were combined:
-
-1. **Structural analysis** of `mattpocock/skills` (14 active skills, authored by Matt Pocock)
-2. **Inventory** of the 31 skills in this repo (`agent-cortex`)
-3. **Literature review** of prompt/skill design research (Anthropic, Google, 10+ papers)
-
-The headline finding: **agent-cortex skills are well-structured but systematically over-long, under-exampled, and too passive in their body text.** The mattpocock repo is ahead on progressive disclosure, cross-skill composability, and opinionated philosophy. The research literature backs all three of those design choices.
-
----
-
-## 2. Comparison: mattpocock/skills vs agent-cortex
-
-### 2.1 Structure
-
-| Dimension | mattpocock/skills | agent-cortex | Delta |
-|---|---|---|---|
-| YAML front-matter | `name`, `description`, optional `argument-hint`, `disable-model-invocation` | `name`, `description` | Missing 2 fields |
-| Description format | "What it does. Use when [natural-language triggers]." | Same — consistent | ✅ Aligned |
-| Body sections | No enforced schema; phase headers, checklists, philosophy, anti-patterns | No enforced schema; varies widely | Similar |
-| Typical SKILL.md length | 7–160 lines; strict 100-line soft cap | 29–169 lines; soft cap documented but not enforced | agent-cortex skews longer |
-| Progressive disclosure | `REFERENCE.md` + named supporting `.md` files linked inline | `REFERENCE.md` on 3 skills only | Under-used in agent-cortex |
-| Named supporting docs | `tests.md`, `mocking.md`, `ADR-FORMAT.md`, `CONTEXT-FORMAT.md`, `DEEPENING.md`, etc. | None — overflow goes to `REFERENCE.md` only | mattpocock more granular |
-| Checklists | Used as explicit phase gates (`- [ ]`) | Rare | Missing in agent-cortex |
-| Cross-skill references | Explicit inline calls: "run `/grill-with-docs`" | Implicit — no inline cross-refs | agent-cortex weaker |
-| Shared vocabulary file | `CONTEXT.md` at repo root; skills told to read it | None | Missing in agent-cortex |
-| Skill manifest | Flat JSON array of skill paths | Same | ✅ Aligned |
-| `disable-model-invocation` | Used for pure prompt-injection skills | Used by `teach`; semantics now documented in `docs/skills/skill-anatomy.md` | Field adopted; rationale corrected |
-| Missing SKILL.md | 0 | 1 (`prd-to-epics`) | Bug in agent-cortex |
-
-### 2.2 Tone and Voice
-
-| Dimension | mattpocock/skills | agent-cortex | Delta |
-|---|---|---|---|
-| Body voice | Imperative, 2nd person ("Read the full issue. Ask.") | Mixed — imperative in some, descriptive in others | Inconsistent in agent-cortex |
-| Emphasis style | **bold** for key decisions; minimal CAPS | Occasional ALL-CAPS (`CRITICAL`, `MUST`) | Over-emphasis in agent-cortex |
-| Conciseness | Punchy; no filler; "say it once" | Some skills have verbose rationale paragraphs | agent-cortex wordier |
-| Examples | Inline code blocks, before/after contrasts, XML output templates | Sparse — only a handful of skills include examples | agent-cortex under-exampled |
-| Philosophy | Explicitly baked in (Kent Beck references, banned practices with `DO NOT`) | Workflow-focused; philosophy largely absent | agent-cortex skips the "why" |
-| Anti-pattern sections | Common (`## Anti-Pattern:`, before/after code blocks) | Absent | Missing in agent-cortex |
-| Negative instructions | Mixed: "DO NOT write all tests first" (hard gate) + positive framing elsewhere | Heavy use of "do not", "never", "don't" | agent-cortex over-uses negatives |
-
-### 2.3 Description Field Quality
-
-Both repos follow the same two-part format: capability sentence + `"Use when..."`. The mattpocock descriptions tend to list *exact user vocabulary* (quoted phrases: `"diagnose this"`, `"let me play with it"`) which is more precise as a routing signal. agent-cortex descriptions are sometimes more abstract.
-
-**mattpocock example** (precise triggers):
-> "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 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 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.
-
----
-
-## 3. Evidence-Backed Recommendations
-
-### Rec 1 — Progressive Disclosure: Split overlong skills
-
-**Evidence**: Anthropic Claude Code best practices: *"Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"* LIMA (Zhou et al., NeurIPS 2023) confirms quality beats quantity — 1,000 curated examples matched GPT-4; adding more degraded focus. Schulhoff et al. (ACL 2024, arXiv:2406.06608) found structure + clarity most consistently effective across 58 techniques.
-
-**Current state**: 11 of 28 agent-cortex skills exceed 100 lines (`run-beads` is 169, `style-code` 151). Only 3 have `REFERENCE.md`.
-
-**Recommendation**: Split all skills over ~100 lines. Prefer *named, purpose-specific files* over a catch-all `REFERENCE.md`:
-- `REFERENCE.md` — rarely-needed edge cases
-- `EXAMPLES.md` — worked examples (if multiple)
-- `FORMAT.md` — output schemas / templates
-- `WORKFLOW.md` — detailed step expansions
-
-Candidates to split immediately: `run-beads`, `style-code`, `tdd`, `ralph`.
-
----
-
-### Rec 2 — Consistent Imperative Voice in Skill Bodies
-
-**Evidence**: The "26 Principles" paper (Bsharat et al., arXiv:2312.16171, VILA Lab 2024) tested 26 prompting principles on GPT-3.5/4 and LLaMA, finding an average **57.7% quality improvement** on GPT-4. Direct command framing (Principle 16) and specificity (Principle 5) had the largest gains on large models. Anthropic explicitly: *"treat the model as a brilliant but new employee who lacks context on your norms"* — this framing implies 2nd-person imperative.
-
-**Current state**: agent-cortex mixes voices. Some skills are tight and imperative (`review-security`); others narrate what the skill *will* do rather than commanding the agent to do it.
-
-**Recommendation**:
-- Skill body: imperative, 2nd person. "Run `gitleaks protect --staged`", not "The skill runs gitleaks."
-- Description field: third-person declarative. "Scans git changes for secrets."
-- Remove all-caps emphasis (`CRITICAL`, `MUST`). Anthropic Claude Code notes: *"Where you might have said 'CRITICAL: You MUST use this tool when...', you can use more normal prompting like 'Use this tool when...'"* — over-emphasis backfires with modern models.
-
----
-
-### Rec 3 — Replace Negative Instructions with Positive Framing
-
-**Evidence**: Anthropic Prompting Best Practices gives an explicit side-by-side:
-> ❌ `"Do not use markdown in your response"`
-> ✅ `"Your response should be composed of smoothly flowing prose paragraphs."`
-
-The "26 Principles" paper lists "affirmative instructions, no 'don't'" as Principle 3 with consistent cross-model gains. Mechanistically, negative instructions require the model to hold a prohibited concept in working memory and suppress it — more error-prone than activating the desired pattern directly.
-
-**Current state**: agent-cortex skills have frequent negative phrasing: "Do not work a HITL bead", "Don't commit without scanning", "Never use relative paths."
-
-**Recommendation**:
-
-| Instead of | Use |
-|---|---|
-| "Do not work a HITL bead" | "Inform the user it requires human action and stop" |
-| "Never use relative paths" | "Use absolute paths — agents may change CWD mid-session" |
-| "Don't commit without scanning" | "Always run `review-security` before committing" |
-
-Reserve "do not" for hard correctness/safety constraints that genuinely need an explicit backstop. For stylistic preferences, positive framing only.
-
----
-
-### Rec 4 — Include Rationale for Non-Obvious Rules
-
-**Evidence**: Anthropic best practices: *"Providing context or motivation behind your instructions, such as explaining why such behavior is important, can help Claude better understand your goals and deliver more targeted responses. Claude is smart enough to generalize from the explanation."* Chain-of-Thought (Wei et al., NeurIPS 2022, arXiv:2201.11903) showed that *reasoning traces* — not just input→output — dramatically outperform bare instructions. The "26 Principles" paper Principles 2 and 5 (explain purpose, specify stakes) were among the highest-impact on GPT-4.
-
-**Current state**: agent-cortex skills state rules but rarely explain them. A reader (or agent) encountering "Use absolute paths" won't know why.
-
-**Recommendation**: Add one-sentence rationale for any non-obvious rule. Pattern:
-
-```markdown
-Use absolute paths — agents may change CWD mid-session, breaking relative references.
-```
-
-Do **not** write paragraphs of rationale. One sentence is enough; the model generalises from it.
-
----
-
-### Rec 5 — Add Worked Examples to Key Skills
-
-**Evidence**: Chain-of-Thought (Wei et al., NeurIPS 2022): *"prompting a 540B-parameter language model with just 8 chain-of-thought exemplars achieves state-of-the-art accuracy on GSM8K, surpassing even fine-tuned GPT-3."* Anthropic: *"A few well-crafted examples can dramatically improve accuracy and consistency."* Recommendation: 3–5 examples, wrapped in `<example>` tags, covering diverse cases. APE (Zhou et al., ICLR 2023, arXiv:2211.01910) found example-seeded instructions outperformed hand-written instructions on 19/24 tasks. Selective Annotation (Su et al., arXiv:2209.01975) showed *diverse* examples give a 12.9% relative gain over random ones.
-
-**Current state**: most agent-cortex skills have no worked examples. `run-beads` has a `---REPORT---` output template; `review-security` shows exact commands. These are the strongest skills.
-
-**Recommendation**: For each skill, identify what the agent produces as output and include 1 complete worked example. For CLI-heavy skills, show exact commands with substitution markers. For decision-heavy skills, add a decision table.
-
-```markdown
-## Example Output
-
----REPORT---
-Bead: bd-42 "Add login page"
-Status: ✅ done
-PR: https://github.com/org/repo/pull/99
----
-```
-
-Extract to `EXAMPLES.md` if more than ~30 lines.
-
----
-
-### Rec 6 — Add Explicit Phase Gates (Checklists)
-
-**Evidence**: Schulhoff et al. (ACL 2024) found structured verification steps consistently reduce hallucination and task-deviation. Anthropic Building Effective Agents: *"Give Claude a way to verify its work."* The mattpocock `diagnose` and `tdd` skills use `- [ ]` checklists as explicit gates between phases — the agent cannot proceed without the checklist being satisfied.
-
-**Current state**: agent-cortex multi-phase skills (`ralph`, `run-beads`, `tdd`) describe phases in prose but have no explicit verification gates.
-
-**Recommendation**: For any multi-phase skill, add a short checklist at the end of each phase:
-
-```markdown
-## Phase 1 — Explore
-
-- Read the bead description and all linked files
-- Identify the affected modules
-- [ ] Can you describe the change in one sentence?
-- [ ] Do you know which files will change?
-
-Move to Phase 2 only when both boxes are checked.
-```
-
----
-
-### Rec 7 — Sharpen Description Trigger Vocabulary
-
-**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 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:
-
-```yaml
-description: >
-  Break a piece of work into a tracked task with a full implementation pipeline.
-  Use when the user says "create a task", "let's track this", "add a bead", "file this 
-  as a ticket", or wants to turn a conversation into actionable work.
-```
-
----
-
-### Rec 8 — Establish Composability via Explicit Cross-References
-
-**Evidence**: Anthropic Building Effective Agents promotes "orchestration" patterns where agents compose tools rather than re-implementing logic. mattpocock's skills reference each other by name inline (e.g., "run `/grill-with-docs`"), creating a composable skill library. Meta-prompting (Suzgun et al., arXiv:2401.12954) found high-level orchestration instructions (+17.1%) outperform monolithic step-by-step skills.
-
-**Current state**: agent-cortex skills are largely self-contained monoliths. `ralph` calls `run-beads` but this is the only explicit cross-reference.
-
-**Recommendation**: Where a skill currently duplicates logic from another skill, replace the duplication with an explicit invocation: *"Run the `review-security` skill before committing."* Document the skill dependency graph informally in `AGENTS.md`.
-
----
-
-### Rec 9 — Add `argument-hint` to Input-Driven Skills
-
-**Evidence**: Anthropic tool design (Building Effective Agents, Appendix 2): *"Is it obvious how to use this tool? ... This is especially important when using many similar tools."* The `argument-hint` front-matter field (present in mattpocock's plugin schema) surfaces a prompt to the user at invocation time — preventing input ambiguity before the skill runs.
-
-**Current state**: agent-cortex plugin schema doesn't include `argument-hint`. Skills like `write-a-ticket`, `run-beads` take implicit input that could benefit from a hint.
-
-**Recommendation**: Add `argument-hint` support to `plugin.json` schema and add hints to skills that take input:
-
-```yaml
-argument-hint: "Describe the bug or paste the error message"
-```
-
----
-
-### Rec 10 — Fix prd-to-epics Missing SKILL.md
-
-**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.
-
----
-
-## 4. Prioritised Change List
-
-| Priority | Change | Effort | Evidence strength |
-|---|---|---|---|
-| P0 | Fix missing `prd-to-epics/SKILL.md` | Low | N/A — broken |
-| P1 | Split skills > 100 lines (7 candidates) | Medium | Strong — Anthropic production data |
-| P1 | Convert negative instructions to positive framing | Low | Strong — 26 Principles paper, Anthropic |
-| P1 | Sharpen description trigger vocabulary (use user-vocab) | Low | Strong — FLAN, Anthropic tool use docs |
-| P2 | Add imperative voice to passive skill bodies | Medium | Strong — 26 Principles paper |
-| P2 | Remove ALL-CAPS emphasis | Low | Medium — Anthropic Claude Code guide |
-| P2 | Add 1-sentence rationale to non-obvious rules | Low | Strong — CoT, 26 Principles |
-| P2 | Add worked examples to output-producing skills | Medium | Strong — Wei et al. CoT, Anthropic |
-| P3 | Add phase-gate checklists to multi-phase skills | Medium | Medium — Schulhoff survey, mattpocock pattern |
-| P3 | Add explicit cross-skill references | Low | Medium — Meta-prompting paper |
-| P3 | Add `argument-hint` support and populate | Medium | Medium — Anthropic tool design |
-
----
-
-## 5. What mattpocock Does That We Should Consider Adopting Wholesale
-
-These are patterns present in `mattpocock/skills` that have no equivalent here and are backed by evidence:
-
-1. **`CONTEXT.md` at repo root** — a shared domain glossary that all skills read. Prevents terminology drift across skills and gives the agent grounding in project domain terms. (The `grill-with-docs` skill builds this automatically.)
-
-2. **Philosophy sections in skills** — `tdd` doesn't just describe TDD, it argues *why* horizontal slicing is wrong. This bakes intent into the skill so the agent handles novel cases correctly (backed by CoT rationale evidence).
-
-3. **`disable-model-invocation: true`** — hides a skill from automatic model routing so only an explicit `/skill-name` invocation reaches it. See `docs/research/disable-model-invocation.md` for per-harness behaviour and caveats.
-
-4. **Composability by design** — skills reference each other by slash-command inline. This keeps each skill shorter and creates a network of reusable primitives rather than monolithic blobs.
-
----
-
-## 6. What We Do Well That mattpocock Doesn't
-
-1. **Richer plugin manifest** — MCP server declarations, richer metadata.
-2. **Bundled scripts** — `run-beads`, `create-task`, `review-security`, `record-idea` all include deterministic scripts that reduce regeneration of boilerplate. mattpocock has this for `diagnose` and `git-guardrails` only.
-3. **Task tracking integration** — `bd` / beads integration is deeply embedded across skills; mattpocock uses GitHub Issues directly without an equivalent agent-native tracker.
-4. **HITL/AFK distinction** — explicitly modelled and surfaced in `run-beads`, `classify-bead`, etc. mattpocock's `to-issues` introduces the concept but doesn't enforce it system-wide.
-
----
-
-## Sources
-
-| Source | Key Findings Used |
-|---|---|
-| Anthropic Prompting Best Practices | Positive framing, numbered steps, XML tags, 3–5 examples, rationale inclusion, query placement (+30%) |
-| Anthropic Building Effective Agents | Tool documentation = system prompt importance; ACI design; poka-yoke; verification criteria |
-| Anthropic Claude Code Best Practices | Conciseness critical; bloated files → ignored rules; positive examples > negative instructions; no ALL-CAPS |
-| Google Vertex AI Clear Instructions | Specificity + constraints → precise output |
-| Bsharat et al. (2024) arXiv:2312.16171 | 26 prompting principles; avg +57.7% quality / +36.4% correctness on GPT-4 |
-| Wei et al. (2022) arXiv:2201.11903 (CoT) | 8 CoT examples beat fine-tuned models; reasoning traces > bare instructions |
-| Wei et al. (2021) arXiv:2109.01652 (FLAN) | Natural-language commands generalise better than passive descriptions |
-| Zhou et al. (2022) arXiv:2211.01910 (APE) | Example-seeded instructions beat human instructions on 19/24 tasks |
-| Zhou et al. (2023) arXiv:2305.11206 (LIMA) | 1,000 curated examples ≈ GPT-4 quality; quality >> volume |
-| Suzgun et al. (2024) arXiv:2401.12954 | High-level orchestration +17.1% vs standard prompting |
-| Schulhoff et al. (2024) arXiv:2406.06608 | ACL survey of 58 techniques; structure + clarity most consistently effective |
-| mattpocock/skills (commit b8be62f) | Structural reference; progressive disclosure; composability; checklists |
-
-[Inspirations](../inspirations.md)