From 5e0249ae3cf34b72b2f64f12eced789aac827ea0 Mon Sep 17 00:00:00 2001 From: Luke Mainwaring Date: Thu, 16 Jul 2026 14:19:47 -0400 Subject: [PATCH 1/6] chore: make .agents/skills the canonical skills directory .claude/skills is now a symlink into .agents/skills (previously the reverse), so agent-neutral tooling reads the real path and Claude Code follows the link. Co-Authored-By: Claude Fable 5 --- .agents/skills | 1 - {.claude => .agents}/skills/create-pr/SKILL.md | 0 {.claude => .agents}/skills/explain-code/SKILL.md | 0 {.claude => .agents}/skills/grill-me/SKILL.md | 0 {.claude => .agents}/skills/grill-with-docs/ADR-FORMAT.md | 0 {.claude => .agents}/skills/grill-with-docs/CONTEXT-FORMAT.md | 0 {.claude => .agents}/skills/grill-with-docs/SKILL.md | 0 {.claude => .agents}/skills/handoff/SKILL.md | 0 .../skills/improve-codebase-architecture/DEEPENING.md | 0 .../skills/improve-codebase-architecture/HTML-REPORT.md | 0 .../skills/improve-codebase-architecture/INTERFACE-DESIGN.md | 0 .../skills/improve-codebase-architecture/LANGUAGE.md | 0 .../skills/improve-codebase-architecture/SKILL.md | 0 {.claude => .agents}/skills/tdd/SKILL.md | 0 {.claude => .agents}/skills/tdd/deep-modules.md | 0 {.claude => .agents}/skills/tdd/interface-design.md | 0 {.claude => .agents}/skills/tdd/mocking.md | 0 {.claude => .agents}/skills/tdd/refactoring.md | 0 {.claude => .agents}/skills/tdd/tests.md | 0 {.claude => .agents}/skills/updating-deps-auto/SKILL.md | 0 {.claude => .agents}/skills/updating-deps/SKILL.md | 0 .claude/skills | 1 + 22 files changed, 1 insertion(+), 1 deletion(-) delete mode 120000 .agents/skills rename {.claude => .agents}/skills/create-pr/SKILL.md (100%) rename {.claude => .agents}/skills/explain-code/SKILL.md (100%) rename {.claude => .agents}/skills/grill-me/SKILL.md (100%) rename {.claude => .agents}/skills/grill-with-docs/ADR-FORMAT.md (100%) rename {.claude => .agents}/skills/grill-with-docs/CONTEXT-FORMAT.md (100%) rename {.claude => .agents}/skills/grill-with-docs/SKILL.md (100%) rename {.claude => .agents}/skills/handoff/SKILL.md (100%) rename {.claude => .agents}/skills/improve-codebase-architecture/DEEPENING.md (100%) rename {.claude => .agents}/skills/improve-codebase-architecture/HTML-REPORT.md (100%) rename {.claude => .agents}/skills/improve-codebase-architecture/INTERFACE-DESIGN.md (100%) rename {.claude => .agents}/skills/improve-codebase-architecture/LANGUAGE.md (100%) rename {.claude => .agents}/skills/improve-codebase-architecture/SKILL.md (100%) rename {.claude => .agents}/skills/tdd/SKILL.md (100%) rename {.claude => .agents}/skills/tdd/deep-modules.md (100%) rename {.claude => .agents}/skills/tdd/interface-design.md (100%) rename {.claude => .agents}/skills/tdd/mocking.md (100%) rename {.claude => .agents}/skills/tdd/refactoring.md (100%) rename {.claude => .agents}/skills/tdd/tests.md (100%) rename {.claude => .agents}/skills/updating-deps-auto/SKILL.md (100%) rename {.claude => .agents}/skills/updating-deps/SKILL.md (100%) create mode 120000 .claude/skills diff --git a/.agents/skills b/.agents/skills deleted file mode 120000 index 454b842..0000000 --- a/.agents/skills +++ /dev/null @@ -1 +0,0 @@ -../.claude/skills \ No newline at end of file diff --git a/.claude/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md similarity index 100% rename from .claude/skills/create-pr/SKILL.md rename to .agents/skills/create-pr/SKILL.md diff --git a/.claude/skills/explain-code/SKILL.md b/.agents/skills/explain-code/SKILL.md similarity index 100% rename from .claude/skills/explain-code/SKILL.md rename to .agents/skills/explain-code/SKILL.md diff --git a/.claude/skills/grill-me/SKILL.md b/.agents/skills/grill-me/SKILL.md similarity index 100% rename from .claude/skills/grill-me/SKILL.md rename to .agents/skills/grill-me/SKILL.md diff --git a/.claude/skills/grill-with-docs/ADR-FORMAT.md b/.agents/skills/grill-with-docs/ADR-FORMAT.md similarity index 100% rename from .claude/skills/grill-with-docs/ADR-FORMAT.md rename to .agents/skills/grill-with-docs/ADR-FORMAT.md diff --git a/.claude/skills/grill-with-docs/CONTEXT-FORMAT.md b/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md similarity index 100% rename from .claude/skills/grill-with-docs/CONTEXT-FORMAT.md rename to .agents/skills/grill-with-docs/CONTEXT-FORMAT.md diff --git a/.claude/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md similarity index 100% rename from .claude/skills/grill-with-docs/SKILL.md rename to .agents/skills/grill-with-docs/SKILL.md diff --git a/.claude/skills/handoff/SKILL.md b/.agents/skills/handoff/SKILL.md similarity index 100% rename from .claude/skills/handoff/SKILL.md rename to .agents/skills/handoff/SKILL.md diff --git a/.claude/skills/improve-codebase-architecture/DEEPENING.md b/.agents/skills/improve-codebase-architecture/DEEPENING.md similarity index 100% rename from .claude/skills/improve-codebase-architecture/DEEPENING.md rename to .agents/skills/improve-codebase-architecture/DEEPENING.md diff --git a/.claude/skills/improve-codebase-architecture/HTML-REPORT.md b/.agents/skills/improve-codebase-architecture/HTML-REPORT.md similarity index 100% rename from .claude/skills/improve-codebase-architecture/HTML-REPORT.md rename to .agents/skills/improve-codebase-architecture/HTML-REPORT.md diff --git a/.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md b/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md similarity index 100% rename from .claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md rename to .agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md diff --git a/.claude/skills/improve-codebase-architecture/LANGUAGE.md b/.agents/skills/improve-codebase-architecture/LANGUAGE.md similarity index 100% rename from .claude/skills/improve-codebase-architecture/LANGUAGE.md rename to .agents/skills/improve-codebase-architecture/LANGUAGE.md diff --git a/.claude/skills/improve-codebase-architecture/SKILL.md b/.agents/skills/improve-codebase-architecture/SKILL.md similarity index 100% rename from .claude/skills/improve-codebase-architecture/SKILL.md rename to .agents/skills/improve-codebase-architecture/SKILL.md diff --git a/.claude/skills/tdd/SKILL.md b/.agents/skills/tdd/SKILL.md similarity index 100% rename from .claude/skills/tdd/SKILL.md rename to .agents/skills/tdd/SKILL.md diff --git a/.claude/skills/tdd/deep-modules.md b/.agents/skills/tdd/deep-modules.md similarity index 100% rename from .claude/skills/tdd/deep-modules.md rename to .agents/skills/tdd/deep-modules.md diff --git a/.claude/skills/tdd/interface-design.md b/.agents/skills/tdd/interface-design.md similarity index 100% rename from .claude/skills/tdd/interface-design.md rename to .agents/skills/tdd/interface-design.md diff --git a/.claude/skills/tdd/mocking.md b/.agents/skills/tdd/mocking.md similarity index 100% rename from .claude/skills/tdd/mocking.md rename to .agents/skills/tdd/mocking.md diff --git a/.claude/skills/tdd/refactoring.md b/.agents/skills/tdd/refactoring.md similarity index 100% rename from .claude/skills/tdd/refactoring.md rename to .agents/skills/tdd/refactoring.md diff --git a/.claude/skills/tdd/tests.md b/.agents/skills/tdd/tests.md similarity index 100% rename from .claude/skills/tdd/tests.md rename to .agents/skills/tdd/tests.md diff --git a/.claude/skills/updating-deps-auto/SKILL.md b/.agents/skills/updating-deps-auto/SKILL.md similarity index 100% rename from .claude/skills/updating-deps-auto/SKILL.md rename to .agents/skills/updating-deps-auto/SKILL.md diff --git a/.claude/skills/updating-deps/SKILL.md b/.agents/skills/updating-deps/SKILL.md similarity index 100% rename from .claude/skills/updating-deps/SKILL.md rename to .agents/skills/updating-deps/SKILL.md diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 0000000..2b7a412 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file From 49625650e1241b1b5ceffd952d18b6b7da462368 Mon Sep 17 00:00:00 2001 From: Luke Mainwaring Date: Thu, 16 Jul 2026 14:24:28 -0400 Subject: [PATCH 2/6] chore: refresh shared skills, agents, and convention rules - create-pr, grill-me, grill-with-docs, handoff, tdd, improve-codebase-architecture, updating-deps(-auto) updated to current best-practice versions; superseded tdd/architecture companion docs removed (their content now lives in the codebase-design skill) - ADR/CONTEXT format references moved to the domain-modeling skill - code-reviewer agent is now a thin wrapper over the shared code-review-guide skill with a cross-model second opinion - product-advisor gains a read-the-repo-first analysis process - backend rules: Testing + Dependencies sections; fixed stale claim that the project has no pgvector usage - frontend rules: Data fetching section (TanStack wrappers, generated client is read-only) - per-skill agents/openai.yaml shims for cross-agent discovery Co-Authored-By: Claude Fable 5 --- .agents/skills/create-pr/SKILL.md | 55 ++++++++-- .agents/skills/create-pr/agents/openai.yaml | 5 + .../ADR-FORMAT.md | 0 .../CONTEXT-FORMAT.md | 0 .../skills/explain-code/agents/openai.yaml | 3 + .agents/skills/grill-me/SKILL.md | 9 +- .agents/skills/grill-me/agents/openai.yaml | 5 + .agents/skills/grill-with-docs/SKILL.md | 87 +-------------- .../skills/grill-with-docs/agents/openai.yaml | 5 + .agents/skills/handoff/SKILL.md | 3 +- .agents/skills/handoff/agents/openai.yaml | 5 + .../DEEPENING.md | 37 ------- .../HTML-REPORT.md | 6 +- .../INTERFACE-DESIGN.md | 44 -------- .../improve-codebase-architecture/LANGUAGE.md | 53 --------- .../improve-codebase-architecture/SKILL.md | 46 ++++---- .../agents/openai.yaml | 5 + .agents/skills/tdd/SKILL.md | 102 +++++------------- .agents/skills/tdd/agents/openai.yaml | 3 + .agents/skills/tdd/deep-modules.md | 33 ------ .agents/skills/tdd/interface-design.md | 31 ------ .agents/skills/tdd/tests.md | 16 +++ .agents/skills/updating-deps-auto/SKILL.md | 17 ++- .../updating-deps-auto/agents/openai.yaml | 3 + .agents/skills/updating-deps/SKILL.md | 8 +- .../skills/updating-deps/agents/openai.yaml | 3 + .claude/agents/code-reviewer.md | 99 +++-------------- .claude/agents/product-advisor.md | 95 +++++++++------- .claude/agents/vercel-chatbot-template.md | 2 +- .claude/rules/backend/code-conventions.md | 13 ++- .claude/rules/frontend/code-conventions.md | 8 ++ 31 files changed, 263 insertions(+), 538 deletions(-) create mode 100644 .agents/skills/create-pr/agents/openai.yaml rename .agents/skills/{grill-with-docs => domain-modeling}/ADR-FORMAT.md (100%) rename .agents/skills/{grill-with-docs => domain-modeling}/CONTEXT-FORMAT.md (100%) create mode 100644 .agents/skills/explain-code/agents/openai.yaml create mode 100644 .agents/skills/grill-me/agents/openai.yaml create mode 100644 .agents/skills/grill-with-docs/agents/openai.yaml create mode 100644 .agents/skills/handoff/agents/openai.yaml delete mode 100644 .agents/skills/improve-codebase-architecture/DEEPENING.md delete mode 100644 .agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md delete mode 100644 .agents/skills/improve-codebase-architecture/LANGUAGE.md create mode 100644 .agents/skills/improve-codebase-architecture/agents/openai.yaml create mode 100644 .agents/skills/tdd/agents/openai.yaml delete mode 100644 .agents/skills/tdd/deep-modules.md delete mode 100644 .agents/skills/tdd/interface-design.md create mode 100644 .agents/skills/updating-deps-auto/agents/openai.yaml create mode 100644 .agents/skills/updating-deps/agents/openai.yaml diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index e75675b..2b69ed8 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -1,33 +1,55 @@ --- name: create-pr -description: Generate a summary for the current branch changes -allowed-tools: Bash(git:*, gh:*) +description: Summarize the current branch's changes and open a pull request with gh. +allowed-tools: Bash(git:*) Bash(gh:*) disable-model-invocation: true --- # PR Summary -Generate a pull request summary for the current branch. +Open a pull request for the current branch, targeting the repository's default +branch. ## Instructions -1. **If any untracked changes, commit with a clear message based on what changed** +1. **Determine the base branch** (the repo's default branch — `main` here). The + PR always targets this branch; stacked PRs onto a parent feature branch are + not supported. -2. **Analyze changes**: + ```bash + base="$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo main)" + ``` + +2. **If you are on the base branch, create a feature branch first** (a PR cannot + go from the base branch to itself): + + ```bash + [ "$(git branch --show-current)" = "$base" ] && git checkout -b + ``` + +3. **If there are uncommitted changes (staged or unstaged), commit them** with a + clear message describing what changed. Do not add `Co-Authored-By` or + "Generated with Claude Code" lines by hand — Claude Code adds attribution + natively via the `attribution` setting, and hand-writing it fights a user who + has turned it off. + +4. **Analyze the changes** against the base (prefer the pushed ref `origin/$base`, + fall back to the local `$base` if it isn't fetched): ```bash - git log main..HEAD --oneline - git diff main...HEAD --stat + ref="origin/$base"; git rev-parse --verify --quiet "$ref" >/dev/null || ref="$base" + git log "$ref..HEAD" --oneline + git diff "$ref...HEAD" --stat ``` -3. **Generate summary** with: +5. **Generate a summary** with: - Brief description of what changed - List of files modified - Breaking changes (if any) - Testing notes -4. **Format as PR body**: +6. **Format as the PR body**: ```markdown ## Summary @@ -43,6 +65,17 @@ Generate a pull request summary for the current branch. - [ ] [Testing checklist items] ``` -5. **Use `gh pr create` to open a pull request with the above markdown** +7. **Push the branch** (set upstream on first push): + + ```bash + git push -u origin HEAD + ``` + +8. **Open the pull request**, targeting the detected base so the PR target matches + the diff above: + + ```bash + gh pr create --base "$base" --title "" --body "<the markdown from step 6>" + ``` -6. **Return the PR URL when done** +9. **Return the PR URL when done.** diff --git a/.agents/skills/create-pr/agents/openai.yaml b/.agents/skills/create-pr/agents/openai.yaml new file mode 100644 index 0000000..2734881 --- /dev/null +++ b/.agents/skills/create-pr/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Create PR" + short_description: "Summarize the branch and open a PR" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/grill-with-docs/ADR-FORMAT.md b/.agents/skills/domain-modeling/ADR-FORMAT.md similarity index 100% rename from .agents/skills/grill-with-docs/ADR-FORMAT.md rename to .agents/skills/domain-modeling/ADR-FORMAT.md diff --git a/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md b/.agents/skills/domain-modeling/CONTEXT-FORMAT.md similarity index 100% rename from .agents/skills/grill-with-docs/CONTEXT-FORMAT.md rename to .agents/skills/domain-modeling/CONTEXT-FORMAT.md diff --git a/.agents/skills/explain-code/agents/openai.yaml b/.agents/skills/explain-code/agents/openai.yaml new file mode 100644 index 0000000..5c4f98a --- /dev/null +++ b/.agents/skills/explain-code/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Explain Code" + short_description: "Explain code with diagrams and analogies" diff --git a/.agents/skills/grill-me/SKILL.md b/.agents/skills/grill-me/SKILL.md index bd04394..9470cfc 100644 --- a/.agents/skills/grill-me/SKILL.md +++ b/.agents/skills/grill-me/SKILL.md @@ -1,10 +1,7 @@ --- name: grill-me -description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". +description: A relentless interview to sharpen a plan or design. +disable-model-invocation: true --- -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. - -Ask the questions one at a time. - -If a question can be answered by exploring the codebase, explore the codebase instead. +Run a `/grilling` session. diff --git a/.agents/skills/grill-me/agents/openai.yaml b/.agents/skills/grill-me/agents/openai.yaml new file mode 100644 index 0000000..4d6fb0c --- /dev/null +++ b/.agents/skills/grill-me/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Grill Me" + short_description: "Sharpen a plan through interview" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md index 5ea0aa9..bed05d2 100644 --- a/.agents/skills/grill-with-docs/SKILL.md +++ b/.agents/skills/grill-with-docs/SKILL.md @@ -1,88 +1,7 @@ --- name: grill-with-docs -description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. +description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. +disable-model-invocation: true --- -<what-to-do> - -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. - -Ask the questions one at a time, waiting for feedback on each question before continuing. - -If a question can be answered by exploring the codebase, explore the codebase instead. - -</what-to-do> - -<supporting-info> - -## Domain awareness - -During codebase exploration, also look for existing documentation: - -### File structure - -Most repos have a single context: - -``` -/ -├── CONTEXT.md -├── docs/ -│ └── adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ -``` - -If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: - -``` -/ -├── CONTEXT-MAP.md -├── docs/ -│ └── adr/ ← system-wide decisions -├── src/ -│ ├── ordering/ -│ │ ├── CONTEXT.md -│ │ └── docs/adr/ ← context-specific decisions -│ └── billing/ -│ ├── CONTEXT.md -│ └── docs/adr/ -``` - -Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. - -## During the session - -### Challenge against the glossary - -When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" - -### Sharpen fuzzy language - -When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." - -### Discuss concrete scenarios - -When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. - -### Cross-reference with code - -When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" - -### Update CONTEXT.md inline - -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). - -`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. - -### Offer ADRs sparingly - -Only offer to create an ADR when all three are true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will wonder "why did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). - -</supporting-info> +Run a `/grilling` session, using the `/domain-modeling` skill. diff --git a/.agents/skills/grill-with-docs/agents/openai.yaml b/.agents/skills/grill-with-docs/agents/openai.yaml new file mode 100644 index 0000000..5dbe278 --- /dev/null +++ b/.agents/skills/grill-with-docs/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Grill with Docs" + short_description: "Grill a design and write its docs" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/handoff/SKILL.md b/.agents/skills/handoff/SKILL.md index 0aa5b99..043d9e1 100644 --- a/.agents/skills/handoff/SKILL.md +++ b/.agents/skills/handoff/SKILL.md @@ -2,13 +2,14 @@ name: handoff description: Compact the current conversation into a handoff document for another agent to pick up. argument-hint: "What will the next session be used for?" +disable-model-invocation: true --- Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace. Include a "suggested skills" section in the document, which suggests skills that the agent should invoke. -Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. +Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. Redact any sensitive information, such as API keys, passwords, or personally identifiable information. diff --git a/.agents/skills/handoff/agents/openai.yaml b/.agents/skills/handoff/agents/openai.yaml new file mode 100644 index 0000000..6e1d8da --- /dev/null +++ b/.agents/skills/handoff/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Handoff" + short_description: "Compact a conversation into a handoff" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/improve-codebase-architecture/DEEPENING.md b/.agents/skills/improve-codebase-architecture/DEEPENING.md deleted file mode 100644 index ecaf5d7..0000000 --- a/.agents/skills/improve-codebase-architecture/DEEPENING.md +++ /dev/null @@ -1,37 +0,0 @@ -# Deepening - -How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. - -## Dependency categories - -When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam. - -### 1. In-process - -Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed. - -### 2. Local-substitutable - -Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface. - -### 3. Remote but owned (Ports & Adapters) - -Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter. - -Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."* - -### 4. True external (Mock) - -Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter. - -## Seam discipline - -- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection. -- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them. - -## Testing strategy: replace, don't layer - -- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them. -- Write new tests at the deepened module's interface. The **interface is the test surface**. -- Tests assert on observable outcomes through the interface, not internal state. -- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface. diff --git a/.agents/skills/improve-codebase-architecture/HTML-REPORT.md b/.agents/skills/improve-codebase-architecture/HTML-REPORT.md index 8adc368..17f6d2c 100644 --- a/.agents/skills/improve-codebase-architecture/HTML-REPORT.md +++ b/.agents/skills/improve-codebase-architecture/HTML-REPORT.md @@ -39,7 +39,7 @@ Repo name, date, and a compact legend: solid box = module, dashed line = seam, r ## Candidate card -The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms ([LANGUAGE.md](LANGUAGE.md)) without ceremony. +The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony. Each candidate is one `<article>`: @@ -105,7 +105,7 @@ One larger card. Candidate name, one sentence on why, anchor link to its card. T ## Tone -Plain English, concise — but the architectural nouns and verbs come straight from [LANGUAGE.md](LANGUAGE.md). Concision is not an excuse to drift. +Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift. **Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality. @@ -120,4 +120,4 @@ Plain English, concise — but the architectural nouns and verbs come straight f **Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place. -No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one. +No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one. diff --git a/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md b/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md deleted file mode 100644 index 3197723..0000000 --- a/.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +++ /dev/null @@ -1,44 +0,0 @@ -# Interface Design - -When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. - -Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. - -## Process - -### 1. Frame the problem space - -Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: - -- The constraints any new interface would need to satisfy -- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) -- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete - -Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. - -### 2. Spawn sub-agents - -Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. - -Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: - -- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." -- Agent 2: "Maximise flexibility — support many use cases and extension." -- Agent 3: "Optimise for the most common caller — make the default case trivial." -- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." - -Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. - -Each sub-agent outputs: - -1. Interface (types, methods, params — plus invariants, ordering, error modes) -2. Usage example showing how callers use it -3. What the implementation hides behind the seam -4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) -5. Trade-offs — where leverage is high, where it's thin - -### 3. Present and compare - -Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**. - -After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu. diff --git a/.agents/skills/improve-codebase-architecture/LANGUAGE.md b/.agents/skills/improve-codebase-architecture/LANGUAGE.md deleted file mode 100644 index 530c276..0000000 --- a/.agents/skills/improve-codebase-architecture/LANGUAGE.md +++ /dev/null @@ -1,53 +0,0 @@ -# Language - -Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. - -## Terms - -**Module** -Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice. -_Avoid_: unit, component, service. - -**Interface** -Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. -_Avoid_: API, signature (too narrow — those refer only to the type-level surface). - -**Implementation** -What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. - -**Depth** -Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation. - -**Seam** _(from Michael Feathers)_ -A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it. -_Avoid_: boundary (overloaded with DDD's bounded context). - -**Adapter** -A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside). - -**Leverage** -What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests. - -**Locality** -What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere. - -## Principles - -- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface. -- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep. -- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape. -- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. - -## Relationships - -- A **Module** has exactly one **Interface** (the surface it presents to callers and tests). -- **Depth** is a property of a **Module**, measured against its **Interface**. -- A **Seam** is where a **Module**'s **Interface** lives. -- An **Adapter** sits at a **Seam** and satisfies the **Interface**. -- **Depth** produces **Leverage** for callers and **Locality** for maintainers. - -## Rejected framings - -- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead. -- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know. -- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**. diff --git a/.agents/skills/improve-codebase-architecture/SKILL.md b/.agents/skills/improve-codebase-architecture/SKILL.md index c12b263..b56969e 100644 --- a/.agents/skills/improve-codebase-architecture/SKILL.md +++ b/.agents/skills/improve-codebase-architecture/SKILL.md @@ -1,38 +1,28 @@ --- name: improve-codebase-architecture -description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. +description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. +disable-model-invocation: true --- # Improve Codebase Architecture Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability. -## Glossary +This command is _informed_ by the project's domain model and built on a shared design vocabulary: -Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md). - -- **Module** — anything with an interface and an implementation (function, class, package, slice). -- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature. -- **Implementation** — the code inside. -- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation. -- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.") -- **Adapter** — a concrete thing satisfying an interface at a seam. -- **Leverage** — what callers get from depth. -- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place. - -Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): - -- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. -- **The interface is the test surface.** -- **One adapter = hypothetical seam. Two adapters = real seam.** - -This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. +- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary." +- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate. ## Process ### 1. Explore -Read the project's domain glossary and any ADRs in the area you're touching first. +**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look: + +- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below. +- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net. + +Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: @@ -50,7 +40,7 @@ Write a self-contained HTML file to the OS temp directory so nothing lands in th The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual. -For each candidate, the same template as before, but rendered as a card: +For each candidate, render a card with: - **Files** — which files/modules are involved - **Problem** — why the current architecture is causing friction @@ -61,7 +51,7 @@ For each candidate, the same template as before, but rendered as a card: End the report with a **Top recommendation** section: which candidate you'd tackle first and why. -**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." +**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. @@ -71,11 +61,11 @@ Do NOT propose interfaces yet. After the file is written, ask the user: "Which o ### 3. Grilling loop -Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. +Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. -Side effects happen inline as decisions crystallize: +Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go: -- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). -- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. +- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern. diff --git a/.agents/skills/improve-codebase-architecture/agents/openai.yaml b/.agents/skills/improve-codebase-architecture/agents/openai.yaml new file mode 100644 index 0000000..706fdca --- /dev/null +++ b/.agents/skills/improve-codebase-architecture/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Improve Codebase Architecture" + short_description: "Find and grill architecture improvements" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/tdd/SKILL.md b/.agents/skills/tdd/SKILL.md index 7a98941..190a9a6 100644 --- a/.agents/skills/tdd/SKILL.md +++ b/.agents/skills/tdd/SKILL.md @@ -1,92 +1,54 @@ --- name: tdd -description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. +description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests. --- # Test-Driven Development -## Philosophy +TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after. -**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. +When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching. -**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure. +## What a good test is -**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior. +Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure. See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines. -## Anti-Pattern: Horizontal Slices +## Seams — where tests go -**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code." +A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals. -This produces **crap tests**: +**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case. -- Tests written in bulk test _imagined_ behavior, not _actual_ behavior -- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior -- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine -- You outrun your headlights, committing to test structure before understanding the implementation +Ask: "What's the public interface, and which seams should we test?" -**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it. +## Anti-patterns -``` -WRONG (horizontal): - RED: test1, test2, test3, test4, test5 - GREEN: impl1, impl2, impl3, impl4, impl5 +- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed. +- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec. See the "Tautological tests" example in [tests.md](tests.md). +- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you. -RIGHT (vertical): - RED→GREEN: test1→impl1 - RED→GREEN: test2→impl2 - RED→GREEN: test3→impl3 - ... -``` +## Rules of the loop -## Workflow - -### 1. Planning - -When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. - -Before writing any code: - -- [ ] Confirm with user what interface changes are needed -- [ ] Confirm with user which behaviors to test (prioritize) -- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation) -- [ ] Design interfaces for [testability](interface-design.md) -- [ ] List the behaviors to test (not implementation steps) -- [ ] Get user approval on the plan - -Ask: "What should the public interface look like? Which behaviors are most important to test?" - -**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case. - -### 2. Tracer Bullet +- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features. +- **One slice at a time.** One seam, one test, one minimal implementation per cycle. +- **Refactoring is not part of the loop.** Never refactor while RED. It happens after all tests pass — see the Refactor step below — and the `code-review-guide` skill gives the deeper review lens. -Write ONE test that confirms ONE thing about the system: - -``` -RED: Write test for first behavior → test fails -GREEN: Write minimal code to pass → test passes -``` - -This is your tracer bullet - proves the path works end-to-end. - -### 3. Incremental Loop +## Workflow -For each remaining behavior: +### 1. Plan the seams -``` -RED: Write next test → fails -GREEN: Minimal code to pass → passes -``` +- Confirm with the user what interface changes are needed +- Agree the seams under test and which behaviors matter most (see Seams above) +- Identify opportunities for deep modules (small interface, deep implementation) — run the `/codebase-design` skill for the vocabulary and the testability checks +- Get user approval on the plan -Rules: +### 2. Red → green, one slice at a time -- One test at a time -- Only enough code to pass current test -- Don't anticipate future tests -- Keep tests focused on observable behavior +Write ONE test at the first agreed seam — the tracer bullet that proves the path works end-to-end. Minimal code to pass. Then repeat for each remaining behavior, following the rules of the loop. -### 4. Refactor +### 3. Refactor (after green) After all tests pass, look for [refactor candidates](refactoring.md): @@ -95,15 +57,3 @@ After all tests pass, look for [refactor candidates](refactoring.md): - [ ] Apply SOLID principles where natural - [ ] Consider what new code reveals about existing code - [ ] Run tests after each refactor step - -**Never refactor while RED.** Get to GREEN first. - -## Checklist Per Cycle - -``` -[ ] Test describes behavior, not implementation -[ ] Test uses public interface only -[ ] Test would survive internal refactor -[ ] Code is minimal for this test -[ ] No speculative features added -``` diff --git a/.agents/skills/tdd/agents/openai.yaml b/.agents/skills/tdd/agents/openai.yaml new file mode 100644 index 0000000..651b838 --- /dev/null +++ b/.agents/skills/tdd/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "TDD" + short_description: "Test-driven red-green-refactor" diff --git a/.agents/skills/tdd/deep-modules.md b/.agents/skills/tdd/deep-modules.md deleted file mode 100644 index 0d9720c..0000000 --- a/.agents/skills/tdd/deep-modules.md +++ /dev/null @@ -1,33 +0,0 @@ -# Deep Modules - -From "A Philosophy of Software Design": - -**Deep module** = small interface + lots of implementation - -``` -┌─────────────────────┐ -│ Small Interface │ ← Few methods, simple params -├─────────────────────┤ -│ │ -│ │ -│ Deep Implementation│ ← Complex logic hidden -│ │ -│ │ -└─────────────────────┘ -``` - -**Shallow module** = large interface + little implementation (avoid) - -``` -┌─────────────────────────────────┐ -│ Large Interface │ ← Many methods, complex params -├─────────────────────────────────┤ -│ Thin Implementation │ ← Just passes through -└─────────────────────────────────┘ -``` - -When designing interfaces, ask: - -- Can I reduce the number of methods? -- Can I simplify the parameters? -- Can I hide more complexity inside? diff --git a/.agents/skills/tdd/interface-design.md b/.agents/skills/tdd/interface-design.md deleted file mode 100644 index a0a20ca..0000000 --- a/.agents/skills/tdd/interface-design.md +++ /dev/null @@ -1,31 +0,0 @@ -# Interface Design for Testability - -Good interfaces make testing natural: - -1. **Accept dependencies, don't create them** - - ```typescript - // Testable - function processOrder(order, paymentGateway) {} - - // Hard to test - function processOrder(order) { - const gateway = new StripeGateway(); - } - ``` - -2. **Return results, don't produce side effects** - - ```typescript - // Testable - function calculateDiscount(cart): Discount {} - - // Hard to test - function applyDiscount(cart): void { - cart.total -= discount; - } - ``` - -3. **Small surface area** - - Fewer methods = fewer tests needed - - Fewer params = simpler test setup diff --git a/.agents/skills/tdd/tests.md b/.agents/skills/tdd/tests.md index ff22f80..7ab8647 100644 --- a/.agents/skills/tdd/tests.md +++ b/.agents/skills/tdd/tests.md @@ -59,3 +59,19 @@ test("createUser makes user retrievable", async () => { expect(retrieved.name).toBe("Alice"); }); ``` + +**Tautological tests**: Expected value restates the implementation, so the test passes by construction. + +```typescript +// BAD: Expected value is recomputed the way the code computes it +test("calculateTotal sums line items", () => { + const items = [{ price: 10 }, { price: 5 }]; + const expected = items.reduce((sum, i) => sum + i.price, 0); + expect(calculateTotal(items)).toBe(expected); +}); + +// GOOD: Expected value is an independent, known literal +test("calculateTotal sums line items", () => { + expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15); +}); +``` diff --git a/.agents/skills/updating-deps-auto/SKILL.md b/.agents/skills/updating-deps-auto/SKILL.md index 7a64e99..8e8e2b1 100644 --- a/.agents/skills/updating-deps-auto/SKILL.md +++ b/.agents/skills/updating-deps-auto/SKILL.md @@ -99,6 +99,16 @@ uv run --directory backend pre-commit run --all-files If the above fails, run it **again** — pre-commit hooks often fix issues on the first run and pass on the second. +### Backend Tests + +`pre-commit` covers lint, format, and `mypy --strict`, but not behaviour — a dependency bump can pass all three and still break at runtime. Run the test suite: + +```bash +uv run --directory backend pytest -m "not eval" +``` + +The suite is DB-free and provider-free, so it runs in the unattended sandbox with no external services. The coverage floor is intentionally **not** enforced here — CI's test job is the backstop for that on the PR. + ### Frontend ```bash @@ -108,7 +118,7 @@ pnpm -C frontend lint ### Failure Handling -If validation still fails after auto-fix attempts, capture the full error output into a `validation_failures` section. **Do NOT stop.** Proceed to Phase 6 — failures will be flagged in the PR. +If validation (lint, type-check, or unit tests) still fails after auto-fix attempts, capture the full error output into a `validation_failures` section. **Do NOT stop.** Proceed to Phase 6 — failures will be flagged in the PR. A unit-test failure at this stage means the new dependency versions broke behaviour with no code change yet; capture it verbatim so the PR shows exactly which test broke under which bump. ## Phase 5.5: Commit 1 — Dependency Bumps @@ -152,11 +162,12 @@ After applying all refactors, re-run validation to ensure nothing is broken: ```bash uv run --directory backend pre-commit run --all-files +uv run --directory backend pytest -m "not eval" pnpm -C frontend format pnpm -C frontend lint ``` -If the re-validation fails, attempt auto-fix (run pre-commit again, format again). If a specific refactor causes persistent failures, **revert that refactor** using `git checkout -- <file>` and note it as a recommendation in the PR body instead. +If the re-validation fails, attempt auto-fix (run pre-commit again, format again). **A failing unit test here almost always means a refactor changed behaviour** — find the offending refactor and **revert it** with `git checkout -- <file>` rather than editing the test to pass, then re-run. If a specific refactor causes persistent lint/type failures, likewise revert it and note it as a recommendation in the PR body instead. Keep a record of: - **Applied refactors**: what changed and where (for the PR body) @@ -216,7 +227,7 @@ Write the PR body to `.github/update-deps/$(date +%Y-%m-%d)/pr-body.md` with the - X backend deps updated, Y frontend deps updated ## Validation Status -<!-- "All checks passed (pre-commit, frontend lint)" OR "**VALIDATION FAILURES DETECTED** — manual attention required:" followed by error output --> +<!-- "All checks passed (pre-commit, unit tests, frontend lint)" OR "**VALIDATION FAILURES DETECTED** — manual attention required:" followed by error output --> ## Code Review <!-- Summary and verdict from code-reviewer agent --> diff --git a/.agents/skills/updating-deps-auto/agents/openai.yaml b/.agents/skills/updating-deps-auto/agents/openai.yaml new file mode 100644 index 0000000..e3903c4 --- /dev/null +++ b/.agents/skills/updating-deps-auto/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Update Dependencies (Auto)" + short_description: "Unattended dependency update to PR" diff --git a/.agents/skills/updating-deps/SKILL.md b/.agents/skills/updating-deps/SKILL.md index 0c1e830..c81d3b7 100644 --- a/.agents/skills/updating-deps/SKILL.md +++ b/.agents/skills/updating-deps/SKILL.md @@ -112,7 +112,7 @@ test "$(wc -c < docs/vercel-ai-sdk-ui.txt)" -gt 100000 || { echo "ERROR: vercel- ## Phase 5: Validate -Run linting and type checking to catch any issues from the version bumps: +Run linting, type checking, and tests to catch any issues from the version bumps: ### Backend @@ -120,6 +120,12 @@ Run linting and type checking to catch any issues from the version bumps: uv run --directory backend pre-commit run --all-files ``` +`pre-commit` covers lint, format, and `mypy --strict`, but not behaviour. Run the test suite too (DB-free and provider-free; real-LLM evals stay excluded by the default marker): + +```bash +uv run --directory backend pytest -m "not eval" +``` + ### Frontend ```bash diff --git a/.agents/skills/updating-deps/agents/openai.yaml b/.agents/skills/updating-deps/agents/openai.yaml new file mode 100644 index 0000000..ecac223 --- /dev/null +++ b/.agents/skills/updating-deps/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Update Dependencies" + short_description: "Bump all deps and review changelogs" diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md index 6186616..a9cf290 100644 --- a/.claude/agents/code-reviewer.md +++ b/.claude/agents/code-reviewer.md @@ -6,90 +6,15 @@ effort: xhigh tools: Read, Glob, Grep, Bash --- -You are a senior code reviewer for the CortexDJ project—an AI-powered EEG brain-wave classifier that detects emotional states during music listening and curates Spotify playlists from brain-derived mood profiles. Built with FastAPI (Python) and Next.js (TypeScript). - -## Your Role - -Review code changes on the current branch (compared to `main`) for quality, correctness, security, and adherence to project conventions. You catch issues the developer might miss when working solo. - -You are the **general first-pass reviewer**: a broad sanity check before a PR. Deep security audits, QA test execution, and visual/UX review are out of scope here and are handled by dedicated reviews. Keep your security and performance passes at sanity-check depth — flag concerns rather than exhaustively analyzing them. - -## Review Process - -1. **Understand the scope**: Run `git log main..HEAD --oneline` and `git diff main...HEAD --stat` to see what changed -2. **Read the relevant conventions**: Read the `.claude/rules/` convention file(s) for the areas the diff touches (see Project Conventions below) — these are the single source of truth -3. **Read the diffs**: Run `git diff main...HEAD` to see the actual changes -4. **Read full files for context**: When a diff is ambiguous, read the full file to understand surrounding code -5. **Check conventions**: Compare changes against the rule files you read in step 2 -6. **Deliver findings**: Report issues categorized by severity - -## Review Dimensions - -Evaluate changes across these dimensions, in priority order: - -1. **Correctness**: Does the code do what it's supposed to? Logic errors, edge cases, off-by-one errors, missing error handling at system boundaries -2. **Architecture**: Does it follow the project's layering? Thin routes → services for logic → models for DB. Proper use of dependency injection -3. **Convention adherence**: Matches the project's established patterns as documented in the `.claude/rules/` files (see below) -4. **Readability**: Clear naming, reasonable function length, no unnecessary complexity, no unused or duplicated code -5. **Tests**: A pytest suite exists in `backend/tests/` (including `tests/evals/`). Review changed or added tests for correctness and meaningfulness, and flag risky changed logic that has no test at all — but do not demand exhaustive coverage or block on test count -6. **Security** (sanity pass): Obvious injection vulnerabilities (SQL, command, XSS), auth/authz gaps, secrets in code, unsafe deserialization. Flag concerns; a dedicated security review goes deeper -7. **Performance** (sanity pass): Obvious N+1 queries, missing indexes for new query patterns, blocking calls in async context - -Do NOT review for: -- Style / formatting / lint nits — Ruff (auto `--fix` + format) and ultracite run automatically via Claude Code PostToolUse hooks and pre-commit, so these are already enforced; don't spend review effort here -- Minor style preferences in general -- Missing docstrings or comments on self-explanatory code - -## Project Conventions - -The canonical, up-to-date project conventions live in `.claude/rules/`. **Read the relevant file(s) as part of every review** — do not rely on conventions memorized in this prompt, as the rule files evolve. - -- **Always read** (for the stack the diff touches; read both for full-stack changes): - - `.claude/rules/backend/code-conventions.md` - - `.claude/rules/frontend/code-conventions.md` -- **Read when the diff touches that area**: - - `.claude/rules/backend/pydantic-ai.md` — agent, capabilities, tools, or eval changes - - `.claude/rules/backend/modal.md` — training or Modal changes - - `.claude/rules/frontend/vercel-ai-sdk.md` — chat UI / streaming changes - -Review changes against what these files currently say. If a change appears to violate a rule, quote the relevant rule in your finding. - -## Output Format - -Structure your review as: - -### Summary - -One-sentence assessment of the overall change quality. - -### Findings - -Group by severity. Omit empty sections. - -#### Critical -Issues that must be fixed — bugs, security vulnerabilities, data loss risks. -- **[File:line]**: Description of issue and suggested fix - -#### Warnings -Issues that should be fixed — convention violations, architectural concerns, potential edge cases. -- **[File:line]**: Description of issue and suggested fix - -#### Nits -Optional improvements — minor readability tweaks, naming suggestions. -- **[File:line]**: Description and suggestion - -### Verdict - -One of: -- **Ship it** — No critical or warning-level issues -- **Fix and ship** — Minor issues to address, no re-review needed -- **Needs changes** — Critical or significant issues that warrant another look - -## Important Guidelines - -- Be specific: always reference the file and line, quote the problematic code -- Be actionable: explain *why* something is an issue and *how* to fix it -- Be proportionate: don't nitpick clean code. If the changes look good, say so briefly -- Focus on the diff: review what changed, not the entire codebase -- Understand intent: read commit messages to understand what the developer was trying to do before criticizing the approach -- Do not run compound `cd ... && git ...` for git commands in this repo. Assume you are already in the codebase. +Follow the shared review methodology in **`.agents/skills/code-review-guide/SKILL.md`** — it is the +single source of truth for scope, process, dimensions, the verify-before-report pass, the finding +schema and severity taxonomy, noise controls, the output format/verdict, and the default-on +cross-model second opinion (with its SOLO opt-out and graceful degradation). + +Read it now, then review `main...HEAD` exactly as it specifies. Read the relevant `.claude/rules/` +convention files for the stack the diff touches (the guide lists which), and quote a rule whenever a +change violates it. + +You are the Claude side, so your cross-model second opinion calls Codex +(`codex exec "… SOLO mode: do NOT seek a second opinion."`), per the guide. If you were invoked in +SOLO mode, skip the second opinion — this is what prevents infinite recursion. diff --git a/.claude/agents/product-advisor.md b/.claude/agents/product-advisor.md index fa490e6..b526cfa 100644 --- a/.claude/agents/product-advisor.md +++ b/.claude/agents/product-advisor.md @@ -1,44 +1,57 @@ --- name: product-advisor description: "Use this agent when you need to decide what to build next, review project priorities, or align implementation work with the project's vision. It analyzes the current codebase against the goals in README.md and docs/ROADMAP.md to recommend high-impact features. Examples:\\n\\n1. Planning next steps:\\nuser: \"I have a few hours to work on cortexdj. What should I focus on?\"\\nassistant: \"Let me use the product-advisor agent to analyze your project state and recommend what to build next.\"\\n<Task tool call to product-advisor agent>\\n\\n2. Feature prioritization:\\nuser: \"Should I work on Spotify auth or playlist creation first?\"\\nassistant: \"I'll use the product-advisor agent to evaluate these options against your project goals.\"\\n<Task tool call to product-advisor agent>\\n\\n3. Validating alignment:\\nuser: \"I'm thinking of adding user authentication. Does that make sense right now?\"\\nassistant: \"Let me consult the product-advisor agent to see how this aligns with your roadmap priorities.\"\\n<Task tool call to product-advisor agent>\\n\\n4. Proactive guidance after completing a milestone:\\nassistant: \"Now that the streaming chat is working, let me use the product-advisor agent to recommend what to tackle next based on your roadmap.\"\\n<Task tool call to product-advisor agent>" -model: opus +model: inherit +effort: high --- -You are an expert product strategist and technical advisor specializing in AI-powered applications and API integrations. You have deep expertise in prioritizing features for developer-built personal projects that balance learning goals with practical utility. +You are an expert product strategist and technical advisor specializing in +AI-powered applications. You help a solo developer decide what to build next on +CortexDJ — an AI-powered EEG brain-wave classifier that curates Spotify +playlists from brain-derived mood profiles. ## Your Role -You serve as a strategic advisor for the CortexDJ project—an AI-powered EEG brain-wave classifier that curates Spotify playlists from brain-derived mood profiles. Your purpose is to help the developer make informed decisions about what to build next by analyzing the current state of the codebase against the project's documented vision and roadmap. +You are a strategic advisor for *this* project. Your purpose is to help the +developer make informed decisions about what to build next by analyzing the +current state of the codebase against the project's own documented vision, and +to keep recommended work advancing the core vision: an AI agent that classifies +EEG brain states, explains emotional patterns during music listening, and +curates mood-matched Spotify playlists. -## Core Responsibilities - -1. **Gap Analysis**: Compare the current implementation against README.md goals and docs/ROADMAP.md milestones to identify what's missing or incomplete. - -2. **Priority Recommendations**: Suggest the highest-impact next steps based on: - - - Project goals (learning full-stack AI development AND building something useful) - - Current technical foundation and readiness - - Logical sequencing of features (dependencies and prerequisites) - - Time-to-value ratio for a solo developer +## Analysis Process -3. **Strategic Alignment**: Ensure recommended work advances the core vision: an AI agent that classifies EEG brain states, explains emotional patterns during music listening, and curates mood-matched Spotify playlists. +Always start by reading the project's actual intent and state — do not rely on +anything memorized in this prompt: + +1. **Read the vision**: Read `README.md` for the project's purpose and goals. If + `docs/ROADMAP.md` exists, read it for planned milestones. If there is no + roadmap yet, infer direction from the README, `AGENTS.md`, and recent commit + history (`git log --oneline -20`), and consider offering to start a roadmap. +2. **Assess what's present**: Inspect the codebase to learn what actually exists + rather than assuming: + - `backend/pyproject.toml` and `frontend/package.json` for the stack + - `backend/src/cortexdj/{routers,services,models}/` for the backend surface + - `backend/src/cortexdj/agents/capabilities/` and `agents/tools/` for agent tools + - `backend/src/cortexdj/ml/` for the model pipelines + - `frontend/` for the UI +3. **Identify gaps**: Determine what's missing or incomplete relative to the + stated goals. +4. **Recommend actions**: Provide 2-3 prioritized recommendations with clear, + specific rationale. ## Decision Framework When recommending priorities, evaluate options against these criteria: -- **Foundation First**: Core infrastructure (database, API, basic chat) before advanced features -- **Learning Value**: Does this teach important full-stack AI patterns? -- **User Value**: Does this move toward the playlist creation vision? -- **Incremental Progress**: Can it be completed in a reasonable session? -- **Technical Debt**: Does the codebase need cleanup before new features? - -## Analysis Process - -1. **Read Project Documentation**: Always examine README.md for vision/goals and docs/ROADMAP.md for planned milestones -2. **Assess Current State**: Review the codebase structure to understand what's implemented -3. **Identify Gaps**: Determine what's missing relative to stated goals -4. **Recommend Actions**: Provide 2-3 prioritized recommendations with clear rationale +- **Foundation First**: Core infrastructure (data model, API, basic flows) before + advanced features. +- **User Value**: Does this move toward the mood-matched playlist vision? +- **Learning Value**: Does this teach important full-stack AI patterns the + developer wants to build fluency in? +- **Incremental Progress**: Can it be completed in a reasonable working session? +- **Technical Debt**: Does the codebase need cleanup or a refactor before the next + feature lands cleanly? ## Output Format @@ -46,7 +59,7 @@ Structure your recommendations as: ### Current State Summary -Brief assessment of where the project stands. +Brief, concrete assessment of where the project stands. ### Recommended Next Steps @@ -60,21 +73,27 @@ Explain why these priorities serve the project's dual goals of learning and util ### Trade-offs Considered -Note any alternatives you considered and why they ranked lower. +Note alternatives you considered and why they ranked lower. ## Important Guidelines -- Ground all recommendations in the actual project documentation—don't invent features not aligned with stated goals -- Remember this is a personal project: favor practical progress over enterprise patterns -- The developer is the end user—optimize for their specific use case (EEG analysis, brain state classification, mood-driven playlist curation) -- Be specific and actionable—vague advice like "improve the architecture" is not helpful -- Consider the existing tech stack (FastAPI, Pydantic AI, PyTorch/EEGNet, MNE-Python, Next.js, PostgreSQL, spotipy) when recommending features +- Ground every recommendation in the project's actual documentation and code — + don't invent features unaligned with the stated goals. +- This is a personal project: favor practical progress over enterprise patterns. +- The developer is the end user — optimize for their specific use case (EEG + analysis, brain state classification, mood-driven playlist curation). +- Be specific and actionable — vague advice like "improve the architecture" is not + helpful. Name the file, endpoint, model, or capability you'd touch. +- Consider the existing tech stack (FastAPI, Pydantic AI, PyTorch/EEGNet + + CBraMod, MNE-Python, Next.js, PostgreSQL/pgvector, spotipy) when recommending + features. ## Roadmap Maintenance -When appropriate, offer to update docs/ROADMAP.md: +When appropriate, offer to maintain `docs/ROADMAP.md`: -- Mark milestones as complete when implementation is verified -- Add newly identified priorities discovered during analysis -- Always show proposed changes and ask before modifying - Ask: "Would you like me to update the roadmap to reflect this?" +- If it exists: mark milestones complete when implementation is verified, and add + newly identified priorities. +- If it doesn't exist: offer to create one capturing the direction you inferred. +- Always show proposed changes and ask before modifying. Ask: "Would you like me to + update the roadmap to reflect this?" diff --git a/.claude/agents/vercel-chatbot-template.md b/.claude/agents/vercel-chatbot-template.md index cbf27b6..d84d839 100644 --- a/.claude/agents/vercel-chatbot-template.md +++ b/.claude/agents/vercel-chatbot-template.md @@ -58,7 +58,7 @@ Fetch the template's `package.json` and compare against `frontend/package.json`: gh api repos/vercel/chatbot/contents/package.json --jq '.content' | base64 -d | grep -E '"(ai|@ai-sdk/react|next|react)"' ``` -Expect cortexdj to be **at or ahead of** the template on every AI SDK package. State one line — normally: "API-compatible; divergence is structural by design, not version lag." (At last check: template `ai@6.0.116` / `@ai-sdk/react@3.0.118`, cortexdj `ai@^6.0.182` / `@ai-sdk/react@^3.0.184` — cortexdj ahead, same major line → API-compatible.) Only a true **major-version** gap is a real compat flag, since it changes which `useChat` / message-part APIs apply. +Expect cortexdj to be **at or ahead of** the template on every AI SDK package. State one line — normally: "API-compatible; divergence is structural by design, not version lag." Only a true **major-version** gap is a real compat flag, since it changes which `useChat` / message-part APIs apply. ### Step 2 — Fetch the feature's implementation diff --git a/.claude/rules/backend/code-conventions.md b/.claude/rules/backend/code-conventions.md index f173f4c..9c7ea71 100644 --- a/.claude/rules/backend/code-conventions.md +++ b/.claude/rules/backend/code-conventions.md @@ -31,7 +31,7 @@ Python/FastAPI conventions for the CortexDJ backend. ## Data Patterns -- Standard PostgreSQL queries on arousal/valence scores (no pgvector, no embedding similarity) +- Arousal/valence scores are plain columns queried with standard SQL; embedding similarity lives in `TrackAudioEmbedding` (pgvector, HNSW cosine search) and is reached through the retrieval service — don't add ad-hoc vector queries elsewhere - DEAP EEG data stored in `backend/data/deap/`; DB stores session metadata + segment classifications - Agent streams responses via Pydantic AI's streaming interface, proxied through a Vercel AI SDK-compatible SSE endpoint - Agent tools in `agents/tools/`, grouped by capability in `agents/capabilities/` @@ -54,6 +54,17 @@ Python/FastAPI conventions for the CortexDJ backend. - After generating an alembic migration, pause and ask if it looks okay before running `migrate-docker.sh` - Never run downgrade scripts without explicit user request +## Testing + +- Tests live flat under `backend/tests/` — fast, DB-free, provider-free. `conftest.py` sets a dummy `OPENAI_API_KEY` so importing `brain_agent` never needs a real key; tests that invoke the agent use `agent.override` with pydantic-ai `TestModel`. +- Real-LLM evals live in `tests/evals/`, marked `@pytest.mark.eval` and opt-in via `pytest -m eval`; the default run excludes them through `addopts = "-m 'not eval'"`. +- CI's test job enforces the coverage floor; don't run coverage locally unless you're investigating a CI failure. + +## Dependencies + +- Never hand-edit `pyproject.toml` with a remembered version — models pin stale releases from training memory. Run `uv add <package> --directory backend` (add `--dev` for tooling) so the resolver fetches the current compatible release and updates `uv.lock` in one step. +- Don't pin an exact `==` version unless there's a specific reason; let `uv add` write the default lower-bound constraint. + ## Module Conventions Re-export convention for `__init__.py`: diff --git a/.claude/rules/frontend/code-conventions.md b/.claude/rules/frontend/code-conventions.md index a8fd02f..1272d01 100644 --- a/.claude/rules/frontend/code-conventions.md +++ b/.claude/rules/frontend/code-conventions.md @@ -51,6 +51,14 @@ TypeScript/Next.js conventions for the cortexdj frontend. - Do not manually edit files in `components/ui/` unless adding a new shadcn component or customizing an existing variant. +## Data fetching + +- Wrap generated API client calls in TanStack Query hooks (e.g., `useSessionSegments` in + `api/hooks/sessions.ts`) rather than calling the generated client directly from + components; keep the hooks under `api/hooks/`. +- Never hand-edit `api/generated/` — it is regenerated from the backend OpenAPI + schema via `pnpm -C frontend generate-client`. + ## Code Style - Use kebab-case for filenames (e.g., `session-visualization.tsx`, From e6e3f39ed158074269d90f1c97f91702bc9f334b Mon Sep 17 00:00:00 2001 From: Luke Mainwaring <lukemain@sas.upenn.edu> Date: Thu, 16 Jul 2026 14:25:27 -0400 Subject: [PATCH 3/6] feat: add engineering skill suite New skills: grilling, domain-modeling, codebase-design, code-review-guide (shared review methodology used by both harnesses' code-reviewer agents), writing-great-skills, implement, to-spec, to-tickets, and setup-matt-pocock-skills. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --- .agents/skills/code-review-guide/SKILL.md | 194 +++++++++++++++++ .../code-review-guide/agents/openai.yaml | 5 + .agents/skills/codebase-design/DEEPENING.md | 37 ++++ .../skills/codebase-design/DESIGN-IT-TWICE.md | 44 ++++ .agents/skills/codebase-design/SKILL.md | 114 ++++++++++ .../skills/codebase-design/agents/openai.yaml | 3 + .agents/skills/domain-modeling/SKILL.md | 74 +++++++ .../skills/domain-modeling/agents/openai.yaml | 3 + .agents/skills/grilling/SKILL.md | 12 ++ .agents/skills/grilling/agents/openai.yaml | 3 + .agents/skills/implement/SKILL.md | 15 ++ .agents/skills/implement/agents/openai.yaml | 5 + .../skills/setup-matt-pocock-skills/SKILL.md | 116 ++++++++++ .../agents/openai.yaml | 5 + .../skills/setup-matt-pocock-skills/domain.md | 51 +++++ .../issue-tracker-github.md | 34 +++ .../issue-tracker-gitlab.md | 35 +++ .../issue-tracker-local.md | 19 ++ .../setup-matt-pocock-skills/triage-labels.md | 15 ++ .agents/skills/to-spec/SKILL.md | 75 +++++++ .agents/skills/to-spec/agents/openai.yaml | 5 + .agents/skills/to-tickets/SKILL.md | 107 ++++++++++ .agents/skills/to-tickets/agents/openai.yaml | 5 + .../skills/writing-great-skills/GLOSSARY.md | 201 ++++++++++++++++++ .agents/skills/writing-great-skills/SKILL.md | 83 ++++++++ .../writing-great-skills/agents/openai.yaml | 5 + 26 files changed, 1265 insertions(+) create mode 100644 .agents/skills/code-review-guide/SKILL.md create mode 100644 .agents/skills/code-review-guide/agents/openai.yaml create mode 100644 .agents/skills/codebase-design/DEEPENING.md create mode 100644 .agents/skills/codebase-design/DESIGN-IT-TWICE.md create mode 100644 .agents/skills/codebase-design/SKILL.md create mode 100644 .agents/skills/codebase-design/agents/openai.yaml create mode 100644 .agents/skills/domain-modeling/SKILL.md create mode 100644 .agents/skills/domain-modeling/agents/openai.yaml create mode 100644 .agents/skills/grilling/SKILL.md create mode 100644 .agents/skills/grilling/agents/openai.yaml create mode 100644 .agents/skills/implement/SKILL.md create mode 100644 .agents/skills/implement/agents/openai.yaml create mode 100644 .agents/skills/setup-matt-pocock-skills/SKILL.md create mode 100644 .agents/skills/setup-matt-pocock-skills/agents/openai.yaml create mode 100644 .agents/skills/setup-matt-pocock-skills/domain.md create mode 100644 .agents/skills/setup-matt-pocock-skills/issue-tracker-github.md create mode 100644 .agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md create mode 100644 .agents/skills/setup-matt-pocock-skills/issue-tracker-local.md create mode 100644 .agents/skills/setup-matt-pocock-skills/triage-labels.md create mode 100644 .agents/skills/to-spec/SKILL.md create mode 100644 .agents/skills/to-spec/agents/openai.yaml create mode 100644 .agents/skills/to-tickets/SKILL.md create mode 100644 .agents/skills/to-tickets/agents/openai.yaml create mode 100644 .agents/skills/writing-great-skills/GLOSSARY.md create mode 100644 .agents/skills/writing-great-skills/SKILL.md create mode 100644 .agents/skills/writing-great-skills/agents/openai.yaml diff --git a/.agents/skills/code-review-guide/SKILL.md b/.agents/skills/code-review-guide/SKILL.md new file mode 100644 index 0000000..36b49c2 --- /dev/null +++ b/.agents/skills/code-review-guide/SKILL.md @@ -0,0 +1,194 @@ +--- +name: code-review-guide +description: The single source of truth for how to review code changes in CortexDJ — correctness, architecture, conventions, plus a light security/perf and maintainability pass, with verification and a default-on cross-model second opinion. Read by the Claude `code-reviewer` subagent and the Codex `code-reviewer` agent; not auto-invoked. +disable-model-invocation: true +--- + +# Code Review Guide + +The one place that defines **how a review is done here**, so both harnesses review the same +way. The Claude `code-reviewer` subagent (`.claude/agents/code-reviewer.md`) and the Codex +`code-reviewer` agent (`.codex/agents/code-reviewer.toml`) are thin wrappers that follow this +file — edit the methodology here, not in those wrappers. + +You are a senior code reviewer for **CortexDJ** — an AI-powered EEG brain-state classifier that +curates Spotify playlists from brain-derived mood profiles: FastAPI + Pydantic AI (Python) +backend with PyTorch/CBraMod ML pipelines, Next.js (TypeScript) frontend, Vercel AI SDK +streaming chat UI. +You are the **general first-pass reviewer**: a broad sanity check before a PR. Deep security +audits, QA execution, and visual/UX review are out of scope (dedicated reviews handle them) — +keep security and performance at sanity-check depth: flag concerns, don't exhaustively analyze. + +## Scope: what you review + +- **Default scope is the committed branch diff: `main...HEAD`** (three-dot = the merge base, so + you see exactly what this branch *introduces*, not unrelated drift on `main`). Mistakes live + in the delta — review the diff, but **read whole files when the diff alone is ambiguous**. +- **Uncommitted working-tree changes are out of scope here.** For those, the fast tier is the + built-in `/code-review` (Claude) or `codex review --uncommitted` (Codex). Say so if asked to + review uncommitted work. +- If given an explicit target (a ref range like `main...feature`, a PR number, or a path), + review that instead. + +## Skip the deterministic layer — it's already enforced + +Do **not** spend findings on anything the toolchain already guarantees. These run automatically +via PostToolUse hooks and/or pre-commit + CI, so issues here never reach a real diff: + +- **Ruff** — `ruff check --fix` + `ruff format` (auto-rewrites Python; PostToolUse hook + pre-commit). +- **ultracite** — lints `frontend/**` (PostToolUse hook is *check-only*; the fix is `pnpm -C frontend format`). +- **mypy `--strict`** — full type-check (pre-commit + the CI `typecheck` job). +- **pytest + coverage** — the CI `test` job runs the suite and enforces the coverage floor. + +So: no style/format/lint nits, no type-annotation nits, no "add a test for coverage's sake." +Review **logic, design, and convention adherence** — the things tools can't judge. + +## Process + +1. **Scope** — `git log main..HEAD --oneline` and `git diff main...HEAD --stat` to see what changed; read commit messages to understand intent before critiquing. +2. **Conventions** — read the `.claude/rules/` file(s) for the stack the diff touches (see below). These are the canonical, evolving source — read them, don't rely on memory. +3. **Diff** — `git diff main...HEAD`; read full files where the diff is ambiguous. +4. **Draft findings** across the dimensions below. +5. **Verify** every finding (see "Verify before you report") — drop what you can't ground. +6. **Second opinion** — unless in SOLO mode, get the cross-model second opinion and reconcile (see that section). +7. **Report** in the output format below. + +### Conventions to read (read by path; `.claude/rules/` is canonical for both harnesses) + +- **Always** (for the stack the diff touches; both for full-stack): `.claude/rules/backend/code-conventions.md`, `.claude/rules/frontend/code-conventions.md`. +- **When touched**: `.claude/rules/backend/pydantic-ai.md` (agent/capabilities/tools/evals); `.claude/rules/backend/modal.md` (Modal training scripts); `.claude/rules/frontend/vercel-ai-sdk.md` (chat UI / streaming). +- **For net-new code (any stack)**: `.claude/rules/conventions.md` (cross-cutting naming, docstrings, ADRs). + +If a change violates a rule, **quote the rule** in your finding. + +## Dimensions (priority order) + +1. **Correctness** — logic errors, edge cases, off-by-one, missing error handling at system boundaries. +2. **Architecture** — the project's layering: thin routers → `services/` for logic → `models/` for DB; dependency injection (ML models via lifespan + typed deps, never imported directly in routes); ML inference stays in `ml/`, reached through services. +3. **Convention adherence** — matches the `.claude/rules/` files you read. +4. **Maintainability ("code-judo") — FLAG, DON'T BLOCK.** Surface, as Warnings/Nits only, behavior-preserving simplifications that *delete* complexity, files grown large for their role in this codebase, scattered conditionals that want a single typed model, and duplicated helper logic that wants a single home. Match the diff against the **smell baseline** below and name any smell you spot. Never gate the verdict on these — this repo prefers readability over cleverness and asks before architectural changes, so propose, don't demand. +5. **Readability** — clear naming (verb-first/behavioral per `conventions.md`), reasonable function length, no dead or duplicated code. +6. **Tests** — review changed/added tests for meaningfulness; flag risky changed logic with no test at all. Don't demand exhaustive coverage or block on count. +7. **Security (sanity)** — obvious injection (SQL/command/XSS), auth/authz gaps, secrets in code, unsafe deserialization. Flag; the dedicated security review goes deeper. +8. **Performance (sanity)** — obvious N+1 queries, missing indexes for new query patterns, blocking calls in async context. + +## Smell baseline (Fowler, _Refactoring_ ch.3) + +A fixed set of named code smells to match against the diff. These names are deep in every +model's priors — naming the smell ("possible Feature Envy") makes the finding legible. Two +rules bind the baseline: + +- **The repo overrides.** A documented rule in `.claude/rules/` always wins; where it endorses + something the baseline would flag, suppress the smell. +- **Always a judgement call.** Each smell is a labelled heuristic, never a hard violation — + report as 🟡/⚪ per the code-judo rules above, and skip anything tooling already enforces. + +Each smell reads *what it is* → *how to fix*: + +- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky. +- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both. +- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies. +- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that. +- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type. +- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share. +- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module. +- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason. +- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows. +- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object. +- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct. +- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition. + +## Verify before you report (cut false positives) + +A reviewer that cries wolf gets ignored. Before a finding survives: + +- **Adversarially self-critique it** — actively try to *disprove* it by re-reading the actual + code paths involved. If you can't substantiate it, drop it. +- **Ground every behavior claim in source** — a finding needs a real `file:line`, not an + inference from a name. "This looks like it might…" is not a finding. +- **Require a concrete failure scenario** — specific inputs/state → the wrong output or crash. + If you can't describe how it actually breaks, it isn't a Critical/Warning. +- **Separate confidence from severity** — a high-severity bug you're only 60% sure of is still + uncertain; say so, and rank it below a confirmed one. + +## Finding schema (every finding carries these) + +- **Severity** — see taxonomy below. +- **Confidence** — High / Medium / Low (independent of severity). +- **Location** — `path:line`. +- **Issue** — one sentence: what's wrong. +- **Failure scenario** — concrete inputs/state → wrong behavior (required for 🔴/🟡). +- **Fix** — the suggested change. + +## Severity taxonomy + +- 🔴 **Critical** — must fix before merge: bugs, security holes, data-loss risks. +- 🟡 **Warning** — should fix: convention violations, architectural concerns, real edge cases, maintainability flags worth acting on. +- ⚪ **Nit** — optional polish. +- 🟣 **Pre-existing** — a real issue **not introduced by this diff**. Note it so it's not lost, but don't charge it to this PR or let it gate the verdict. + +Rank findings **by severity × confidence, highest first.** + +## Noise controls + +- **Nit cap:** report at most **5** nits; if there are more, list the top 5 and summarize the rest as a count. +- **Re-review convergence:** on a second pass of an already-reviewed branch, **suppress new nits** and report only 🔴/🟡 — don't pile on. +- **Proportionality:** don't nitpick clean code. If it's good, say so briefly. + +## Output format + +### Summary +One sentence on overall change quality. + +### Findings +Grouped by severity (🔴 → 🟡 → ⚪ → 🟣), omitting empty groups, ranked within each group. Each: + +> **[🔴 High] `path:line`** — <issue>. +> *Fails when:* <concrete failure scenario>. +> *Fix:* <suggestion>. +> *(source: claude | codex | both — only when a cross-model second opinion ran)* + +### Verdict +Gated on 🔴/🟡 only (⚪ and 🟣 never block): +- **Ship it** — no 🔴/🟡. +- **Fix and ship** — minor 🟡 to address, no re-review needed. +- **Needs changes** — 🔴 or significant 🟡 that warrant another look. + +Findings are **advisory** — never auto-apply fixes. + +## Cross-model second opinion (ON by default; SOLO to opt out) + +After verifying your own findings, get a second opinion from the *other* model and factor it in. +Two different models (Claude vs gpt-5.x) have different blind spots: agreement is a strong +"this is real" signal that cuts false positives, and the union improves recall — at no API cost, +since both CLIs run on their own subscriptions. + +**Do this by default unless told to skip (see opt-out):** + +1. Run the other agent **once**, on the same `main...HEAD` diff, in **SOLO mode**: + - If you are **Claude** → `codex exec "Follow .agents/skills/code-review-guide/SKILL.md and review the main...HEAD diff — SOLO mode: do NOT seek a second opinion."` + - If you are **Codex** → `claude -p "Follow .agents/skills/code-review-guide/SKILL.md and review the main...HEAD diff — SOLO mode: do NOT seek a second opinion."` +2. **Reconcile** its report into yours: + - Findings **both** raised → mark **High** confidence, source `both`. + - Findings only the **other** model raised → **re-check against the actual code** and keep only if they hold up; tag the source. + - Findings only **you** raised → keep, tagged with your own side (`claude` or `codex`). Don't drop them just because the other model missed them. + - Tag each surviving finding's originating model in the output (`source: …`). +3. Because you are also one of the two reviewers, guard against **home-team bias**: when the two + disagree, decide by **re-reading the code**, not by trusting your own summary. + +**Opt-out (SOLO mode) — skip step entirely when ANY of these is true:** +- The request asks for a *solo / quick / single-model / no second opinion* review. +- **You were invoked in SOLO mode** (the prompt says so). This is mandatory — it is what + **prevents infinite recursion** (your SOLO sub-call must not spawn its own second opinion). + +**Graceful degradation:** before calling the other agent, check it's available +(`command -v codex` / `command -v claude`). If it's missing or unauthenticated, **fall back to a +single-model review and say so explicitly** in the Summary — never error, and never imply you got +a second opinion when you didn't. + +## Guidelines + +- Be specific and actionable: reference `path:line`, quote the problematic code, explain *why* and *how to fix*. +- Focus on the diff, not the whole codebase. +- Understand intent (read commit messages) before criticizing the approach. +- Do not run compound `cd ... && git ...`; assume you're already in the repo root. diff --git a/.agents/skills/code-review-guide/agents/openai.yaml b/.agents/skills/code-review-guide/agents/openai.yaml new file mode 100644 index 0000000..1a22671 --- /dev/null +++ b/.agents/skills/code-review-guide/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Code Review Guide" + short_description: "How code review is done in this repo" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/codebase-design/DEEPENING.md b/.agents/skills/codebase-design/DEEPENING.md new file mode 100644 index 0000000..3938457 --- /dev/null +++ b/.agents/skills/codebase-design/DEEPENING.md @@ -0,0 +1,37 @@ +# Deepening + +How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**. + +## Dependency categories + +When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam. + +### 1. In-process + +Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed. + +### 2. Local-substitutable + +Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface. + +### 3. Remote but owned (Ports & Adapters) + +Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter. + +Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."* + +### 4. True external (Mock) + +Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter. + +## Seam discipline + +- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection. +- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them. + +## Testing strategy: replace, don't layer + +- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them. +- Write new tests at the deepened module's interface. The **interface is the test surface**. +- Tests assert on observable outcomes through the interface, not internal state. +- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface. diff --git a/.agents/skills/codebase-design/DESIGN-IT-TWICE.md b/.agents/skills/codebase-design/DESIGN-IT-TWICE.md new file mode 100644 index 0000000..49a7c42 --- /dev/null +++ b/.agents/skills/codebase-design/DESIGN-IT-TWICE.md @@ -0,0 +1,44 @@ +# Design It Twice + +When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. + +Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. + +## Process + +### 1. Frame the problem space + +Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: + +- The constraints any new interface would need to satisfy +- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) +- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete + +Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. + +### 2. Spawn sub-agents + +Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. + +Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: + +- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." +- Agent 2: "Maximise flexibility — support many use cases and extension." +- Agent 3: "Optimise for the most common caller — make the default case trivial." +- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." + +Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. + +Each sub-agent outputs: + +1. Interface (types, methods, params — plus invariants, ordering, error modes) +2. Usage example showing how callers use it +3. What the implementation hides behind the seam +4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) +5. Trade-offs — where leverage is high, where it's thin + +### 3. Present and compare + +Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**. + +After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu. diff --git a/.agents/skills/codebase-design/SKILL.md b/.agents/skills/codebase-design/SKILL.md new file mode 100644 index 0000000..16620c2 --- /dev/null +++ b/.agents/skills/codebase-design/SKILL.md @@ -0,0 +1,114 @@ +--- +name: codebase-design +description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. +--- + +# Codebase Design + +Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone. + +## Glossary + +Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. + +**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service. + +**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface). + +**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. + +**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation. + +**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context). + +**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside). + +**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests. + +**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere. + +## Deep vs shallow + +**Deep module** = small interface + lots of implementation: + +``` +┌─────────────────────┐ +│ Small Interface │ ← Few methods, simple params +├─────────────────────┤ +│ │ +│ Deep Implementation│ ← Complex logic hidden +│ │ +└─────────────────────┘ +``` + +**Shallow module** = large interface + little implementation (avoid): + +``` +┌─────────────────────────────────┐ +│ Large Interface │ ← Many methods, complex params +├─────────────────────────────────┤ +│ Thin Implementation │ ← Just passes through +└─────────────────────────────────┘ +``` + +When designing an interface, ask: + +- Can I reduce the number of methods? +- Can I simplify the parameters? +- Can I hide more complexity inside? + +## Principles + +- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface. +- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. +- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape. +- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. + +## Designing for testability + +Good interfaces make testing natural: + +1. **Accept dependencies, don't create them.** + + ```typescript + // Testable + function processOrder(order, paymentGateway) {} + + // Hard to test + function processOrder(order) { + const gateway = new StripeGateway(); + } + ``` + +2. **Return results, don't produce side effects.** + + ```typescript + // Testable + function calculateDiscount(cart): Discount {} + + // Hard to test + function applyDiscount(cart): void { + cart.total -= discount; + } + ``` + +3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup. + +## Relationships + +- A **Module** has exactly one **Interface** (the surface it presents to callers and tests). +- **Depth** is a property of a **Module**, measured against its **Interface**. +- A **Seam** is where a **Module**'s **Interface** lives. +- An **Adapter** sits at a **Seam** and satisfies the **Interface**. +- **Depth** produces **Leverage** for callers and **Locality** for maintainers. + +## Rejected framings + +- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead. +- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know. +- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**. + +## Going deeper + +- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing. +- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement. diff --git a/.agents/skills/codebase-design/agents/openai.yaml b/.agents/skills/codebase-design/agents/openai.yaml new file mode 100644 index 0000000..3180715 --- /dev/null +++ b/.agents/skills/codebase-design/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Codebase Design" + short_description: "Vocabulary for deep-module design" diff --git a/.agents/skills/domain-modeling/SKILL.md b/.agents/skills/domain-modeling/SKILL.md new file mode 100644 index 0000000..d0f7e1a --- /dev/null +++ b/.agents/skills/domain-modeling/SKILL.md @@ -0,0 +1,74 @@ +--- +name: domain-modeling +description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. +--- + +# Domain Modeling + +Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.) + +## File structure + +Most repos have a single context: + +``` +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: + +``` +/ +├── CONTEXT-MAP.md +├── docs/ +│ └── adr/ ← system-wide decisions +├── src/ +│ ├── ordering/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ ← context-specific decisions +│ └── billing/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. + +## During the session + +### Challenge against the glossary + +When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" + +### Sharpen fuzzy language + +When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." + +### Discuss concrete scenarios + +When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. + +### Cross-reference with code + +When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" + +### Update CONTEXT.md inline + +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). + +`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. + +### Offer ADRs sparingly + +Only offer to create an ADR when all three are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will wonder "why did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). diff --git a/.agents/skills/domain-modeling/agents/openai.yaml b/.agents/skills/domain-modeling/agents/openai.yaml new file mode 100644 index 0000000..7f1522d --- /dev/null +++ b/.agents/skills/domain-modeling/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Domain Modeling" + short_description: "Build and sharpen a domain model" diff --git a/.agents/skills/grilling/SKILL.md b/.agents/skills/grilling/SKILL.md new file mode 100644 index 0000000..d11226b --- /dev/null +++ b/.agents/skills/grilling/SKILL.md @@ -0,0 +1,12 @@ +--- +name: grilling +description: Interview the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. +--- + +Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. + +Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. + +If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer. + +Do not act on it until I confirm we have reached a shared understanding. diff --git a/.agents/skills/grilling/agents/openai.yaml b/.agents/skills/grilling/agents/openai.yaml new file mode 100644 index 0000000..85b1260 --- /dev/null +++ b/.agents/skills/grilling/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Grilling" + short_description: "Stress-test thinking one question at a time" diff --git a/.agents/skills/implement/SKILL.md b/.agents/skills/implement/SKILL.md new file mode 100644 index 0000000..fad3485 --- /dev/null +++ b/.agents/skills/implement/SKILL.md @@ -0,0 +1,15 @@ +--- +name: implement +description: "Implement a piece of work based on a spec or set of tickets." +disable-model-invocation: true +--- + +Implement the work described by the user in the spec or tickets. + +Use /tdd where possible, at pre-agreed seams. + +Run typechecking regularly, single test files regularly, and the full test suite once at the end. + +Once done, review the work with the `code-reviewer` agent — it follows the `code-review-guide` skill. + +Commit your work to the current branch. diff --git a/.agents/skills/implement/agents/openai.yaml b/.agents/skills/implement/agents/openai.yaml new file mode 100644 index 0000000..f8794dc --- /dev/null +++ b/.agents/skills/implement/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Implement" + short_description: "Build work from a spec or tickets" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/setup-matt-pocock-skills/SKILL.md b/.agents/skills/setup-matt-pocock-skills/SKILL.md new file mode 100644 index 0000000..284c4ed --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/SKILL.md @@ -0,0 +1,116 @@ +--- +name: setup-matt-pocock-skills +description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills. +disable-model-invocation: true +--- + +# Setup Matt Pocock's Skills + +Scaffold the per-repo configuration that the engineering skills assume: + +- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box) +- **Triage labels** — the strings used for the five canonical triage roles +- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them + +This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write. + +## Process + +### 1. Explore + +Look at the current repo to understand its starting state. Read whatever exists; don't assume: + +- `git remote -v` and `.git/config` — is this a GitHub repo? Which one? +- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either? +- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root +- `docs/adr/` and any `src/*/docs/adr/` directories +- `docs/agents/` — does this skill's prior output already exist? +- `.scratch/` — sign that a local-markdown issue tracker convention is already in use +- Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all. +- Monorepo signals — a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. Present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo. + +### 2. Present findings and ask + +Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next. + +Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when `triage` isn't installed, Section C when there's no monorepo). + +**Section A — Issue tracker.** + +> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-spec` and `to-tickets` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo. + +Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer: + +- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI) +- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI) +- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote) +- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose + +Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later. + +**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels. + +If it is installed, ask exactly one question: + +> Do you want to keep the default triage labels? (recommended: **yes**) + +The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates. + +**Section C — Domain docs.** Default to **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. This fits almost every repo; write it without asking. + +Offer **multi-context** — a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files — only when exploration found monorepo signals. Then confirm which layout they want. + +### 3. Confirm and edit + +Show the user a draft of: + +- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules) +- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed) + +Let them edit before writing. + +### 4. Write + +**Pick the file to edit:** + +- If `CLAUDE.md` exists, edit it. +- Else if `AGENTS.md` exists, edit it. +- If neither exists, ask the user which one to create — don't pick for them. + +Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there. + +If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections. + +The block: + +```markdown +## Agent skills + +### Issue tracker + +[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`. + +### Triage labels + +[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`. + +### Domain docs + +[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`. +``` + +Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted. + +Then write the docs files using the seed templates in this skill folder as a starting point: + +- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker +- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker +- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker +- [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed) +- [domain.md](./domain.md) — domain doc consumer rules + layout + +For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description. + +### 5. Done + +Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch. diff --git a/.agents/skills/setup-matt-pocock-skills/agents/openai.yaml b/.agents/skills/setup-matt-pocock-skills/agents/openai.yaml new file mode 100644 index 0000000..65a0da8 --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Setup Matt Pocock Skills" + short_description: "Configure a repo for the skills" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/setup-matt-pocock-skills/domain.md b/.agents/skills/setup-matt-pocock-skills/domain.md new file mode 100644 index 0000000..b548c53 --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/domain.md @@ -0,0 +1,51 @@ +# Domain Docs + +How the engineering skills should consume this repo's domain documentation when exploring the codebase. + +## Before exploring, read these + +- **`CONTEXT.md`** at the repo root, or +- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions. + +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +Single-context repo (most repos): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +Multi-context repo (presence of `CONTEXT-MAP.md` at the root): + +``` +/ +├── CONTEXT-MAP.md +├── docs/adr/ ← system-wide decisions +└── src/ + ├── ordering/ + │ ├── CONTEXT.md + │ └── docs/adr/ ← context-specific decisions + └── billing/ + ├── CONTEXT.md + └── docs/adr/ +``` + +## Use the glossary's vocabulary + +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: + +> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_ diff --git a/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md b/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md new file mode 100644 index 0000000..f0363c0 --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md @@ -0,0 +1,34 @@ +# Issue tracker: GitHub + +Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. + +## Conventions + +- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies. +- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels. +- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters. +- **Comment on an issue**: `gh issue comment <number> --body "..."` +- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."` +- **Close**: `gh issue close <number> --comment "..."` + +Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests.)_ + +When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents: + +- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff. +- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`). +- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`. + +GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`. + +## When a skill says "publish to the issue tracker" + +Create a GitHub issue. + +## When a skill says "fetch the relevant ticket" + +Run `gh issue view <number> --comments`. diff --git a/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md b/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md new file mode 100644 index 0000000..f3498ff --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md @@ -0,0 +1,35 @@ +# Issue tracker: GitLab + +Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations. + +## Conventions + +- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor. +- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output. +- **List issues**: `glab issue list -F json` with appropriate `--label` filters. +- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes". +- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag. +- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close. +- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`. + +Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone. + +## Merge requests as a triage surface + +**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests.)_ + +When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents: + +- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff. +- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work). +- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`. + +Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means. + +## When a skill says "publish to the issue tracker" + +Create a GitLab issue. + +## When a skill says "fetch the relevant ticket" + +Run `glab issue view <number> --comments`. diff --git a/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md b/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md new file mode 100644 index 0000000..15e9de0 --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md @@ -0,0 +1,19 @@ +# Issue tracker: Local Markdown + +Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`. + +## Conventions + +- One feature per directory: `.scratch/<feature-slug>/` +- The spec is `.scratch/<feature-slug>/spec.md` +- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file +- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings) +- Comments and conversation history append to the bottom of the file under a `## Comments` heading + +## When a skill says "publish to the issue tracker" + +Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed). + +## When a skill says "fetch the relevant ticket" + +Read the file at the referenced path. The user will normally pass the path or the issue number directly. diff --git a/.agents/skills/setup-matt-pocock-skills/triage-labels.md b/.agents/skills/setup-matt-pocock-skills/triage-labels.md new file mode 100644 index 0000000..b716855 --- /dev/null +++ b/.agents/skills/setup-matt-pocock-skills/triage-labels.md @@ -0,0 +1,15 @@ +# Triage Labels + +The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| -------------------------- | -------------------- | ---------------------------------------- | +| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | +| `needs-info` | `needs-info` | Waiting on reporter for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. + +Edit the right-hand column to match whatever vocabulary you actually use. diff --git a/.agents/skills/to-spec/SKILL.md b/.agents/skills/to-spec/SKILL.md new file mode 100644 index 0000000..f3cca8d --- /dev/null +++ b/.agents/skills/to-spec/SKILL.md @@ -0,0 +1,75 @@ +--- +name: to-spec +description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +disable-model-invocation: true +--- + +This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know. + +The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. + +## Process + +1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching. + +2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one. + +Check with the user that these seams match their expectations. + +3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. + +<spec-template> + +## Problem Statement + +The problem that the user is facing, from the user's perspective. + +## Solution + +The solution to the problem, from the user's perspective. + +## User Stories + +A LONG, numbered list of user stories. Each user story should be in the format of: + +1. As an <actor>, I want a <feature>, so that <benefit> + +<user-story-example> +1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending +</user-story-example> + +This list of user stories should be extremely extensive and cover all aspects of the feature. + +## Implementation Decisions + +A list of implementation decisions that were made. This can include: + +- The modules that will be built/modified +- The interfaces of those modules that will be modified +- Technical clarifications from the developer +- Architectural decisions +- Schema changes +- API contracts +- Specific interactions + +Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. + +Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + +## Testing Decisions + +A list of testing decisions that were made. Include: + +- A description of what makes a good test (only test external behavior, not implementation details) +- Which modules will be tested +- Prior art for the tests (i.e. similar types of tests in the codebase) + +## Out of Scope + +A description of the things that are out of scope for this spec. + +## Further Notes + +Any further notes about the feature. + +</spec-template> diff --git a/.agents/skills/to-spec/agents/openai.yaml b/.agents/skills/to-spec/agents/openai.yaml new file mode 100644 index 0000000..549e6f7 --- /dev/null +++ b/.agents/skills/to-spec/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "To Spec" + short_description: "Turn a conversation into a spec" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/to-tickets/SKILL.md b/.agents/skills/to-tickets/SKILL.md new file mode 100644 index 0000000..23140c5 --- /dev/null +++ b/.agents/skills/to-tickets/SKILL.md @@ -0,0 +1,107 @@ +--- +name: to-tickets +description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in one file per ticket locally, or native blocking links on a real tracker. +disable-model-invocation: true +--- + +# To Tickets + +Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. + +The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. + +## Process + +### 1. Gather context + +Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments. + +### 2. Explore the codebase (optional) + +If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. + +Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." + +### 3. Draft vertical slices + +Break the work into **tracer bullet** tickets. + +<vertical-slice-rules> + +- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer +- A completed slice is demoable or verifiable on its own +- Each slice is sized to fit in a single fresh context window +- Any prefactoring should be done first + +</vertical-slice-rules> + +Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately. + +**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there. + +### 4. Quiz the user + +Present the proposed breakdown as a numbered list. For each ticket, show: + +- **Title**: short descriptive name +- **Blocked by**: which other tickets (if any) must complete first +- **What it delivers**: the end-to-end behaviour this ticket makes work + +Ask the user: + +- Does the granularity feel right? (too coarse / too fine) +- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it? +- Should any tickets be merged or split further? + +Iterate until the user approves the breakdown. + +### 5. Publish the tickets to the configured tracker + +Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes: + +- **Local files** → write one file per ticket under `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file. +- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction. + +Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom. + +Do NOT close or modify any parent issue. + +<local-ticket-template> + +# <NN> — <Ticket title> + +**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list. + +**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — can start immediately". + +**Status:** ready-for-agent + +- [ ] Acceptance criterion 1 +- [ ] Acceptance criterion 2 + +</local-ticket-template> + +<issue-template> + +## Parent + +A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section). + +## What to build + +The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation. + +## Acceptance criteria + +- [ ] Criterion 1 +- [ ] Criterion 2 + +## Blocked by + +- A reference to each blocking ticket, or "None — can start immediately". + +</issue-template> + +In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + +Work the frontier one ticket at a time with `/implement`, clearing context between tickets. diff --git a/.agents/skills/to-tickets/agents/openai.yaml b/.agents/skills/to-tickets/agents/openai.yaml new file mode 100644 index 0000000..24605a5 --- /dev/null +++ b/.agents/skills/to-tickets/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "To Tickets" + short_description: "Split a plan into tracer-bullet tickets" +policy: + allow_implicit_invocation: false diff --git a/.agents/skills/writing-great-skills/GLOSSARY.md b/.agents/skills/writing-great-skills/GLOSSARY.md new file mode 100644 index 0000000..0269ca8 --- /dev/null +++ b/.agents/skills/writing-great-skills/GLOSSARY.md @@ -0,0 +1,201 @@ +# Glossary — Building Great Skills + +The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; the root virtue is **Predictability**, and every term below is a lever on it. This is the disclosed reference for [`writing-great-skills`](SKILL.md). + +The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_. + +**Bold terms** in any definition are themselves defined in this glossary; find them by their heading. + +## Predictability + +The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals. + +_Avoid_: consistency, reliability, robustness, output-determinism + +## Invocation + +How a skill is reached — and the two loads you pay for the choice. + +### Model-Invoked + +A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load. + +_Avoid_: ability, tool, capability + +### User-Invoked + +A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it. + +_Avoid_: procedure, workflow, command + +### Description + +The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**. + +_Avoid_: frontmatter, summary + +### Context Pointer + +A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails. + +_Avoid_: link, reference, import + +### Context Load + +The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills. + +_Avoid_: token cost, context bloat + +### Cognitive Load + +The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not. + +_Avoid_: human index, burden, overhead + +### Router Skill + +A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply. + +_Avoid_: dispatcher, menu, registry, index, router procedure + +### Granularity + +How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion. + +_Avoid_: chunking, modularity + +## Information Hierarchy + +How a skill's content is arranged, and how far down the ladder each piece sits. + +### Information Hierarchy + +A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs: + +- **Steps** — in-file, primary +- **Reference**, in-file — secondary +- **Reference**, disclosed — behind a **context pointer** + +A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can. + +_Avoid_: structure, organization, layout + +### Steps + +The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague. + +_Avoid_: workflow, instructions, choreography + +### Reference + +Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**. + +_Avoid_: supporting material, docs, background + +### External Reference + +**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other. + +_Avoid_: doc, resource, knowledge base + +### Progressive Disclosure + +Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails. + +_Avoid_: lazy loading, chunking + +### Co-location + +Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many. + +_Avoid_: grouping, clustering, cohesion + +### Sprawl + +_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause. + +_Avoid_: bloat, length, size, verbosity + +## Steering + +The levers that shape the agent's runtime behaviour toward **Predictability**. + +### Branch + +A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none. + +_Avoid_: path, case, fork + +### Leading Word + +A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first. + +A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill. + +_Avoid_: keyword, term, motif + +### Completion Criterion + +The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive. + +_Avoid_: done condition, exit condition, stopping rule + +### Legwork + +The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short. + +_Avoid_: scope, effort, diligence, coverage + +### Post-Completion Steps + +The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two. + +_Avoid_: horizon, fog of war, lookahead + +### Premature Completion + +_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion. + +_Avoid_: premature closure, the rush, rushing, shortcutting + +### Negation + +_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do. + +_Avoid_: ironic rebound, don't-prompting, the pink elephant + +## Pruning + +Keeping a skill lean — each remedy paired with the failure it cures. + +### Single Source of Truth + +The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation. + +_Avoid_: home, canonical location + +### Duplication + +_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning. + +_Avoid_: repetition, redundancy + +### Relevance + +Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour. + +_Avoid_: load-bearing, staleness, freshness + +### Sediment + +_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning. + +_Avoid_: accretion, bloat, cruft, rot + +### No-Op + +_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless. + +A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate. + +_Avoid_: redundant instruction, restating the obvious, belaboring diff --git a/.agents/skills/writing-great-skills/SKILL.md b/.agents/skills/writing-great-skills/SKILL.md new file mode 100644 index 0000000..82abd0d --- /dev/null +++ b/.agents/skills/writing-great-skills/SKILL.md @@ -0,0 +1,83 @@ +--- +name: writing-great-skills +description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. +disable-model-invocation: true +--- + +A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it. + +**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning. + +## Invocation + +Two choices, trading different costs: + +- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…"). +- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped. + +Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load. + +When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each. + +## Writing the description + +A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body: + +- **Front-load the skill's leading word** — the description is where it does its invocation work. +- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches. +- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause. + +## Information hierarchy + +A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material: + +1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**. +2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._ +3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.) + +A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence. + +Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision. + +**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material. + +Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. + +## When to split + +**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts: + +- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it. +- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task. + +## Pruning + +Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. + +Check every line for **relevance**: does it still bear on what the skill does? + +Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten. + +## Leading words + +A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. + +It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably. + +Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include: + +- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop). +- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't). + +You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them. + +## Failure modes + +Use these to diagnose issues the user may be having with the skill. + +- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut). +- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. +- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline. +- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs. +- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique. +- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead. diff --git a/.agents/skills/writing-great-skills/agents/openai.yaml b/.agents/skills/writing-great-skills/agents/openai.yaml new file mode 100644 index 0000000..d677a13 --- /dev/null +++ b/.agents/skills/writing-great-skills/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Writing Great Skills" + short_description: "Principles for predictable skills" +policy: + allow_implicit_invocation: false From 36f0e9c29dcb30921a37300c13c4b0f1fd726ee9 Mon Sep 17 00:00:00 2001 From: Luke Mainwaring <lukemain@sas.upenn.edu> Date: Thu, 16 Jul 2026 14:26:33 -0400 Subject: [PATCH 4/6] feat: add Codex harness mirror (.codex/) hooks.json wires the same three guard/lint hooks (byte-identical copies under .codex/hooks/), and agents/*.toml port the Claude subagents so both CLIs share one methodology. The code-reviewer's cross-model second opinion calls the other CLI from each side. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --- .codex/agents/code-reviewer.toml | 17 +++ .codex/agents/product-advisor.toml | 97 ++++++++++++++++ .codex/agents/vercel-chatbot-template.toml | 125 +++++++++++++++++++++ .codex/hooks.json | 33 ++++++ .codex/hooks/backend-ruff.py | 63 +++++++++++ .codex/hooks/block-generated-edits.py | 52 +++++++++ .codex/hooks/frontend-lint.py | 61 ++++++++++ 7 files changed, 448 insertions(+) create mode 100644 .codex/agents/code-reviewer.toml create mode 100644 .codex/agents/product-advisor.toml create mode 100644 .codex/agents/vercel-chatbot-template.toml create mode 100644 .codex/hooks.json create mode 100644 .codex/hooks/backend-ruff.py create mode 100644 .codex/hooks/block-generated-edits.py create mode 100644 .codex/hooks/frontend-lint.py diff --git a/.codex/agents/code-reviewer.toml b/.codex/agents/code-reviewer.toml new file mode 100644 index 0000000..938fa0c --- /dev/null +++ b/.codex/agents/code-reviewer.toml @@ -0,0 +1,17 @@ +name = "code-reviewer" +description = "Senior general code reviewer for current-branch changes vs `main` — correctness, architecture, project-convention adherence, plus a light security and performance pass. Use proactively before creating a PR, after finishing a feature, or whenever the user asks to review changes. This is a broad first-pass sanity check; deep security audits, QA test execution, and visual/UX review are deferred to dedicated reviews." +model_reasoning_effort = "xhigh" +developer_instructions = """ +Follow the shared review methodology in `.agents/skills/code-review-guide/SKILL.md` — the single +source of truth for scope, process, dimensions, the verify-before-report pass, the finding schema and +severity taxonomy, noise controls, output format/verdict, and the default-on cross-model second +opinion (its SOLO opt-out and graceful degradation). + +Read it now, then review `main...HEAD` exactly as it specifies. Read the relevant `.claude/rules/` +convention files for the stack the diff touches (the guide lists which), and quote a rule whenever a +change violates it. + +You are the Codex side, so your cross-model second opinion calls Claude +(`claude -p "… SOLO mode: do NOT seek a second opinion."`), per the guide. If you were invoked in +SOLO mode, skip the second opinion — this is what prevents infinite recursion. +""" diff --git a/.codex/agents/product-advisor.toml b/.codex/agents/product-advisor.toml new file mode 100644 index 0000000..7bcd9b0 --- /dev/null +++ b/.codex/agents/product-advisor.toml @@ -0,0 +1,97 @@ +name = "product-advisor" +description = '''Use this agent when you need to decide what to build next, review project priorities, or align implementation work with the project's vision. It analyzes the current codebase against the goals in README.md and docs/ROADMAP.md to recommend high-impact features. Examples:\n\n1. Planning next steps:\nuser: "I have a few hours to work on cortexdj. What should I focus on?"\nassistant: "Let me use the product-advisor agent to analyze your project state and recommend what to build next."\n<Task tool call to product-advisor agent>\n\n2. Feature prioritization:\nuser: "Should I work on Spotify auth or playlist creation first?"\nassistant: "I'll use the product-advisor agent to evaluate these options against your project goals."\n<Task tool call to product-advisor agent>\n\n3. Validating alignment:\nuser: "I'm thinking of adding user authentication. Does that make sense right now?"\nassistant: "Let me consult the product-advisor agent to see how this aligns with your roadmap priorities."\n<Task tool call to product-advisor agent>\n\n4. Proactive guidance after completing a milestone:\nassistant: "Now that the streaming chat is working, let me use the product-advisor agent to recommend what to tackle next based on your roadmap."\n<Task tool call to product-advisor agent>''' +model_reasoning_effort = "high" +developer_instructions = """ +You are an expert product strategist and technical advisor specializing in +AI-powered applications. You help a solo developer decide what to build next on +CortexDJ — an AI-powered EEG brain-wave classifier that curates Spotify +playlists from brain-derived mood profiles. + +## Your Role + +You are a strategic advisor for *this* project. Your purpose is to help the +developer make informed decisions about what to build next by analyzing the +current state of the codebase against the project's own documented vision, and +to keep recommended work advancing the core vision: an AI agent that classifies +EEG brain states, explains emotional patterns during music listening, and +curates mood-matched Spotify playlists. + +## Analysis Process + +Always start by reading the project's actual intent and state — do not rely on +anything memorized in this prompt: + +1. **Read the vision**: Read `README.md` for the project's purpose and goals. If + `docs/ROADMAP.md` exists, read it for planned milestones. If there is no + roadmap yet, infer direction from the README, `AGENTS.md`, and recent commit + history (`git log --oneline -20`), and consider offering to start a roadmap. +2. **Assess what's present**: Inspect the codebase to learn what actually exists + rather than assuming: + - `backend/pyproject.toml` and `frontend/package.json` for the stack + - `backend/src/cortexdj/{routers,services,models}/` for the backend surface + - `backend/src/cortexdj/agents/capabilities/` and `agents/tools/` for agent tools + - `backend/src/cortexdj/ml/` for the model pipelines + - `frontend/` for the UI +3. **Identify gaps**: Determine what's missing or incomplete relative to the + stated goals. +4. **Recommend actions**: Provide 2-3 prioritized recommendations with clear, + specific rationale. + +## Decision Framework + +When recommending priorities, evaluate options against these criteria: + +- **Foundation First**: Core infrastructure (data model, API, basic flows) before + advanced features. +- **User Value**: Does this move toward the mood-matched playlist vision? +- **Learning Value**: Does this teach important full-stack AI patterns the + developer wants to build fluency in? +- **Incremental Progress**: Can it be completed in a reasonable working session? +- **Technical Debt**: Does the codebase need cleanup or a refactor before the next + feature lands cleanly? + +## Output Format + +Structure your recommendations as: + +### Current State Summary + +Brief, concrete assessment of where the project stands. + +### Recommended Next Steps + +1. **[Priority 1]**: Description and rationale +2. **[Priority 2]**: Description and rationale +3. **[Priority 3]**: Description and rationale + +### Reasoning + +Explain why these priorities serve the project's dual goals of learning and utility. + +### Trade-offs Considered + +Note alternatives you considered and why they ranked lower. + +## Important Guidelines + +- Ground every recommendation in the project's actual documentation and code — + don't invent features unaligned with the stated goals. +- This is a personal project: favor practical progress over enterprise patterns. +- The developer is the end user — optimize for their specific use case (EEG + analysis, brain state classification, mood-driven playlist curation). +- Be specific and actionable — vague advice like "improve the architecture" is not + helpful. Name the file, endpoint, model, or capability you'd touch. +- Consider the existing tech stack (FastAPI, Pydantic AI, PyTorch/EEGNet + + CBraMod, MNE-Python, Next.js, PostgreSQL/pgvector, spotipy) when recommending + features. + +## Roadmap Maintenance + +When appropriate, offer to maintain `docs/ROADMAP.md`: + +- If it exists: mark milestones complete when implementation is verified, and add + newly identified priorities. +- If it doesn't exist: offer to create one capturing the direction you inferred. +- Always show proposed changes and ask before modifying. Ask: "Would you like me to + update the roadmap to reflect this?" +""" diff --git a/.codex/agents/vercel-chatbot-template.toml b/.codex/agents/vercel-chatbot-template.toml new file mode 100644 index 0000000..0fbfd95 --- /dev/null +++ b/.codex/agents/vercel-chatbot-template.toml @@ -0,0 +1,125 @@ +name = "vercel-chatbot-template" +description = """ +Fetches and analyzes the Vercel chatbot template's (vercel/chatbot) implementation of a UI/UX feature that exists there but not yet in cortexdj, so its React/Tailwind view layer can be reused. Use proactively before building such a feature. Examples:\n\n1. Adding file attachments to the chat input:\nassistant: "cortexdj's input is text-only — let me see how the template implements attachments before building it."\n<Task tool call to vercel-chatbot-template agent>\n\n2. Porting the template's message-actions / tool-accordion composition:\nassistant: "Let me see how the template composes message actions and tool accordions before adapting it into cortexdj."\n<Task tool call to vercel-chatbot-template agent>\n\n3. Adopting a scroll/affordance UX (scroll-to-bottom, message actions):\nassistant: "Let me check the template's built UI for this before writing it from scratch."\n<Task tool call to vercel-chatbot-template agent>""" +developer_instructions = """ +You are a reference agent for the cortexdj project. Your job: fetch the **Vercel chatbot template**'s (`vercel/chatbot` on GitHub) implementation of a UI/UX feature that cortexdj wants but has not built yet, and produce a concrete plan to extract its view layer and re-wire it onto cortexdj's frontend (`frontend/`). + +## Why this agent exists (it is not a stale-upstream tracker) + +cortexdj's frontend was forked from `vercel/chatbot` and stripped down. cortexdj's chat surface **intentionally diverges** from the current template: the template's architecture is coupled to AI SDK Core + Drizzle + artifacts + NextAuth, whereas cortexdj replaces all of those with **Pydantic AI + FastAPI + TanStack Query**. cortexdj is **API-ahead** of the template on every AI SDK package (`ai`, `@ai-sdk/react`, `next`, `react`, `streamdown`) — there is **no version lag**; the divergence is structural and by design. + +So the template is **not** an upstream to catch up to, and this agent is **not** for broad "are we stale / should we re-sync?" audits (that scope made it sprawl). It is a **feature-specific UI-component donor**: when cortexdj needs a feature the template already implements well (file attachments, message actions, tool accordions, scroll affordances, chat-shell composition) but cortexdj has not built, this agent fetches the template's production React/Tailwind and maps out how to lift its view layer onto cortexdj's structure. + +For evolving streaming / transport / SSE-protocol behavior (what cortexdj's FastAPI backend must emit), `https://ai-sdk.dev/` and `.claude/rules/frontend/vercel-ai-sdk.md` are authoritative over the template. + +Scope is **`vercel/chatbot` only**. Never fetch from or reference the separate `vercel/ai-elements` repo. (The template's *own* `components/ai-elements/` directory is in scope — that is part of `vercel/chatbot`.) + +## Docs vs. template — division of labor + +These answer **different** questions; don't conflate them: + +- **`docs/vercel-ai-sdk-ui.txt` + `https://ai-sdk.dev/`** — authoritative for the **SDK API / SSE-stream contract**: AI SDK API shape, `useChat` behavior, message/file/tool part formats, the stream protocol, and backend compatibility with Pydantic AI / Vercel UI streams. Its code blocks are minimal teaching snippets, **not** production components. If the question is "what's the API/contract," cite these — don't re-derive them. +- **This agent + the template** — authoritative for the **built-UI implementation**: the actual JSX, Tailwind, and interaction states of a feature, **and the bridge** that re-wires it onto cortexdj's contract. + +**Sequence:** resolve any contract/protocol question from the docs *before* fetching template code. Only consult the template once the open question is purely "what does the built UI look like, and how do I adapt it." Concrete example: for file attachments the docs give you only the `sendMessage({ text, files })` mechanism; the template gives you the dropzone, thumbnail tray, paste-to-upload, and remove-button UI. You need both — the docs for the wiring, this agent for the component. + +## Hard constraint: AI SDK UI only, no Core + +cortexdj uses **AI SDK UI** (hooks like `useChat`) only. It does NOT use AI SDK Core — LLM orchestration is handled by Pydantic AI on the backend, and `frontend/app/(chat)/api/chat/route.ts` is a thin proxy to FastAPI. The following template areas are **out of scope** — filter them out, never recommend adopting them: + +- `lib/ai/`, `lib/ai/tools/` — server-side Core orchestration, tool definitions +- `lib/db/` — Drizzle schema/queries (cortexdj persists via FastAPI + TanStack Query) +- `artifacts/`, `app/(chat)/api/document|files|history|messages|models|suggestions|vote/` — artifact/persistence/auth APIs +- `app/(auth)/` — NextAuth/better-auth +- The bulk of `app/(chat)/api/chat/route.ts` — it is heavy Core (`streamText`, `createUIMessageStream`). Read it only as a **spec for what the backend SSE must emit**, never as code to port. + +## Process + +### Step 0 — Discover structure live (do this first, every run) + +Do **not** assume a file layout. Enumerate the current tree before fetching anything: + +```bash +gh api 'repos/vercel/chatbot/git/trees/main?recursive=1' --jq '.tree[].path' | grep -E '^(app|components|hooks|lib)/' +``` + +(GitHub redirects from the repo's older `vercel/ai-chatbot` slug; if a `vercel/chatbot` path 404s, retry the same path under `vercel/ai-chatbot`.) + +Orientation hint only (verify against the live tree — do not assume): as of the last refactor the chat loop lived in `hooks/use-active-chat.tsx` (mounted from `app/(chat)/layout.tsx`; the page files `return null`), reusable AI primitives in `components/ai-elements/`, per-tool composition in `components/chat/message.tsx`. Structure drifts — the live tree is the source of truth. + +### Step 1 — Confirm structural divergence (version-compat sanity check) + +Fetch the template's `package.json` and compare against `frontend/package.json`: + +```bash +gh api repos/vercel/chatbot/contents/package.json --jq '.content' | base64 -d | grep -E '"(ai|@ai-sdk/react|next|react)"' +``` + +Expect cortexdj to be **at or ahead of** the template on every AI SDK package. State one line — normally: "API-compatible; divergence is structural by design, not version lag." Only a true **major-version** gap is a real compat flag, since it changes which `useChat` / message-part APIs apply. + +### Step 2 — Fetch the feature's implementation + +```bash +gh api repos/vercel/chatbot/contents/<file_path> --jq '.content' | base64 -d +``` + +Fetch the component(s) that implement the requested net-new feature. Never dump whole directories. + +**If the feature is not visibly present in the live tree from Step 0, say so and stop.** Do not extrapolate a UI the template doesn't have, and do not pivot into a broad audit. Redirect instead: contract/protocol questions → the SDK docs; capabilities the template lacks → AI SDK Core + browser APIs. (E.g. client-side voice/transcription is typically AI SDK Core transcription plus the browser `MediaRecorder` API, **not** a template UI component — don't fabricate one.) + +### Step 3 — Map to cortexdj's structure + +Read the corresponding local files before recommending anything. cortexdj's structure is intentionally divergent (see "Why this agent exists"); key reference points: + +- `frontend/components/chat.tsx` — owns `useChat`; server page → `<Chat initialMessages>` (NOT the template's layout-mounted `use-active-chat` context) +- `frontend/components/multimodal-input.tsx` — the chat input (currently text-only despite the name; the likely host for input-side features like attachments) +- `frontend/components/elements/prompt-input.tsx` — the input primitives (textarea / toolbar / submit) that a template input UI maps onto +- `frontend/components/message.tsx` — per-tool `part.type === "tool-<name>"` switch +- `frontend/components/messages.tsx` — list container +- `frontend/components/elements/` — `tool-call.tsx`, `message.tsx`, `response.tsx`, etc. (cortexdj's name for what the current template calls `components/ai-elements/`) +- `frontend/api/hooks/` — TanStack Query wrappers (`threads.ts`, `sessions.ts`) +- `frontend/lib/types.ts` — the custom `ChatMessage` generic threaded through `useChat` + +cortexdj-specific panels with **no template analog** (don't expect template guidance for these): `brain-context-badge`, `session-visualization`, `emotion-trajectory`, `session-list-panel`, `retrieved-tracks-panel`, `waveform-viz`. + +### Step 4 — Separate the view layer from the template's wiring (the core job) + +The template's feature components are wired into **its own** architecture, which cortexdj does not share. Your job: **extract the reusable view layer (JSX structure, Tailwind, interaction UX) and re-wire it onto cortexdj's `sendMessage({ text, files })` + thin proxy (`frontend/app/(chat)/api/chat/route.ts`) + FastAPI** model — never recommend porting the template's wiring or a wholesale layout migration. Identify and strip dependencies on: + +- `use-active-chat.tsx` context / layout-mounted chat / `page.tsx` returning null +- `DefaultChatTransport` `prepareSendMessagesRequest` request shaping +- `components/ai-elements/*` (template) vs `components/elements/*` (cortexdj) naming/structure +- HITL tool-approval part states / data-stream provider plumbing +- `lib/ai`, `lib/db`, NextAuth — any Core/Drizzle/auth coupling + +Keep: the markup, styling, local component state, accessibility, and UX behavior. + +## Output Format + +### Feature in the template +How the template implements the requested feature — key components, composition, interaction states (with file paths). If it is not present in the tree, say so here and stop. + +### Relevant Code +The most important JSX/Tailwind snippets from the template (include file paths). + +### Version compatibility +One line: cortexdj vs. template AI SDK / Next / React versions — normally "API-compatible; structural divergence by design." Flag only a true major-version gap. + +### Wiring to strip vs. view layer to keep +What in the template component depends on the template's own architecture (Core / `use-active-chat` / transport-shaping / HITL) and must be detached, vs. the markup/styling/UX to preserve. + +### Extract & adapt plan +The concrete plan: which template JSX/CSS to lift; which `frontend/` files to create or modify; and which docs-defined `sendMessage` / SSE contract it relies on (cite `docs/vercel-ai-sdk-ui.txt` / ai-sdk.dev rather than re-deriving). Be specific about file paths, component names, prop types. + +## Guidelines + +- **Discover before assuming structure** — Step 0 every run; never assume a layout, the live tree is the source of truth. +- **Stop if absent** — if the requested feature isn't visibly in the template tree, say so and stop; don't invent it or pivot to a broad "are we stale" audit. +- **Docs answer *what's the contract*; you answer *what's the built UI and how to adapt it*** — resolve contract questions from the docs first; cite them, don't re-derive. +- **Only fetch what's needed** — never dump entire directories. +- **Filter for AI SDK UI patterns** — skip Core/DB/auth/artifacts server-side code. +- **Read local cortexdj files first** — compare before recommending. +- **Extract, don't migrate** — lift the view layer onto cortexdj's structure; never recommend a wholesale architecture change. +- **Be concrete** — specific file paths, component names, prop types. +- **Scope: `vercel/chatbot` only** — never the separate `vercel/ai-elements` repo. +""" diff --git a/.codex/hooks.json b/.codex/hooks.json new file mode 100644 index 0000000..c2ba0b8 --- /dev/null +++ b/.codex/hooks.json @@ -0,0 +1,33 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/block-generated-edits.py\"", + "timeout": 10 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/frontend-lint.py\"", + "timeout": 90 + }, + { + "type": "command", + "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/backend-ruff.py\"", + "timeout": 90 + } + ] + } + ] + } +} diff --git a/.codex/hooks/backend-ruff.py b/.codex/hooks/backend-ruff.py new file mode 100644 index 0000000..ca78d08 --- /dev/null +++ b/.codex/hooks/backend-ruff.py @@ -0,0 +1,63 @@ +#!/usr/bin/env python3 +"""PostToolUse: ruff --fix + ruff format on changed backend Python files. + +Mirrors the ruff steps in .pre-commit-config.yaml (same file scope: +backend/(src|tests)/**.py). mypy --strict is deliberately left to +pre-commit / CI -- it's too slow to run inline on every edit. ruff --fix +rewrites the changed file; unfixable violations exit 2 back to the agent. +""" + +import json +import os +import re +import subprocess +import sys + +# Matches .pre-commit-config.yaml `files: ^backend/(src|tests)/.*.py$` +PATTERN = re.compile(r"/backend/(src|tests)/.*\.py$") + + +def main() -> int: + try: + data = json.load(sys.stdin) + except (json.JSONDecodeError, ValueError): + return 0 + + file_path = (data.get("tool_input") or {}).get("file_path") + if not file_path: + return 0 + + project_dir = data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd() + norm = os.path.abspath(os.path.join(project_dir, file_path)).replace(os.sep, "/") + + if not PATTERN.search(norm): + return 0 + rel_in_backend = norm.split("/backend/", 1)[1] # e.g. src/cortexdj/foo.py + + base = ["uv", "run", "--directory", "backend", "ruff"] + fix = subprocess.run( # noqa: S603 + [*base, "check", "--fix", rel_in_backend], + capture_output=True, + text=True, + cwd=project_dir, + ) + subprocess.run( # noqa: S603 + [*base, "format", rel_in_backend], + capture_output=True, + text=True, + cwd=project_dir, + ) + + if fix.returncode != 0: + out = (fix.stdout + "\n" + fix.stderr).strip() + print( + f"ruff reported unfixable issues in backend/{rel_in_backend}. " + f"Address them, then continue.\n\n{out}", + file=sys.stderr, + ) + return 2 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.codex/hooks/block-generated-edits.py b/.codex/hooks/block-generated-edits.py new file mode 100644 index 0000000..f3ec55f --- /dev/null +++ b/.codex/hooks/block-generated-edits.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python3 +"""PreToolUse: block hand-edits to frontend/api/generated/. + +That directory is regenerated by `pnpm -C frontend generate-client`; manual +edits get clobbered. Enforces the AGENTS.md rule for Claude Code. Exit 2 +blocks the tool call and feeds stderr back to the agent. +""" + +import json +import os +import sys + +GUARDED = "/frontend/api/generated/" + + +def main() -> int: + try: + data = json.load(sys.stdin) + except (json.JSONDecodeError, ValueError): + return 0 # unparseable input -> never block + + tool_input = data.get("tool_input") or {} + # Accept any known path-bearing key so a schema/matcher change does not + # silently disable the guard. If none is present, fail CLOSED: a security + # guard must not allow an edit it could not inspect. + file_path = tool_input.get("file_path") or tool_input.get("notebook_path") + if not file_path: + print( + "Blocked: could not determine the target file path from the tool " + "payload, so the frontend/api/generated/ guard cannot verify this " + "edit is safe. Refusing by default. (See AGENTS.md.)", + file=sys.stderr, + ) + return 2 + + project_dir = data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd() + norm = os.path.abspath(os.path.join(project_dir, file_path)).replace(os.sep, "/") + + if GUARDED in norm: + print( + f"Blocked: {file_path} is under frontend/api/generated/, which is " + "generated from the backend OpenAPI schema. Change the backend " + "endpoint instead, then run `pnpm -C frontend generate-client`. " + "(See AGENTS.md.)", + file=sys.stderr, + ) + return 2 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.codex/hooks/frontend-lint.py b/.codex/hooks/frontend-lint.py new file mode 100644 index 0000000..7694bdd --- /dev/null +++ b/.codex/hooks/frontend-lint.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +"""PostToolUse: ultracite check on the changed frontend file (report-only). + +Mirrors the AGENTS.md "run lint after frontend changes" instruction. Does not +modify files -- on lint errors it exits 2 so the agent sees them and fixes +them (optionally via `pnpm -C frontend format`). No-op for non-frontend or +generated files so it's cheap on every edit. +""" + +import json +import os +import subprocess +import sys + +SKIP = ( + "frontend/api/generated/", + "frontend/node_modules/", + "frontend/.next/", +) +EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".css") + + +def main() -> int: + try: + data = json.load(sys.stdin) + except (json.JSONDecodeError, ValueError): + return 0 + + file_path = (data.get("tool_input") or {}).get("file_path") + if not file_path: + return 0 + + project_dir = data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd() + norm = os.path.abspath(os.path.join(project_dir, file_path)).replace(os.sep, "/") + + if "/frontend/" not in norm or not norm.endswith(EXTS): + return 0 + rel_in_frontend = norm.split("/frontend/", 1)[1] + if any(("frontend/" + rel_in_frontend).startswith(s) for s in SKIP): + return 0 + + proc = subprocess.run( # noqa: S603 + ["pnpm", "-C", "frontend", "exec", "ultracite", "check", rel_in_frontend], + capture_output=True, + text=True, + cwd=project_dir, + ) + if proc.returncode != 0: + out = (proc.stdout + "\n" + proc.stderr).strip() + print( + f"ultracite found issues in frontend/{rel_in_frontend}. Fix them " + "(or run `pnpm -C frontend format` for auto-fixable ones), then " + f"continue.\n\n{out}", + file=sys.stderr, + ) + return 2 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From d54eb4d780e73d237cec6c516cc2f623a8ef42e0 Mon Sep 17 00:00:00 2001 From: Luke Mainwaring <lukemain@sas.upenn.edu> Date: Thu, 16 Jul 2026 14:28:24 -0400 Subject: [PATCH 5/6] ci: add test job with coverage floor and manual eval workflow The test suite (159 tests) was not running in CI at all. New test job runs it DB-free with a 40% coverage floor (baseline ~43%, to be ratcheted up). eval.yml runs the real-LLM pydantic-evals suite on manual dispatch only, needing the OPENAI_API_KEY repo secret. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --- .github/workflows/ci.yml | 40 ++++++++++++++++++++++++++++++++++++ .github/workflows/eval.yml | 42 ++++++++++++++++++++++++++++++++++++++ backend/pyproject.toml | 1 + backend/uv.lock | 40 ++++++++++++++++++++++++++++++++++++ 4 files changed, 123 insertions(+) create mode 100644 .github/workflows/eval.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6acd38a..92a6694 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -54,6 +54,46 @@ jobs: working-directory: ./backend run: uv run mypy --strict src tests + test: + name: Test + runs-on: ubuntu-latest + env: + # Settings require these at import; the tests never connect to a DB. + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: cortexdj + POSTGRES_HOST: localhost + POSTGRES_PORT: "5432" + # Dummy provider key: tests use TestModel/monkeypatch, never a real call. + OPENAI_API_KEY: sk-test-deterministic-no-real-calls + steps: + - uses: actions/checkout@v6 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.13" + + - name: Setup uv + uses: astral-sh/setup-uv@v8.0.0 + with: + enable-cache: true + + - name: Install dependencies + working-directory: ./backend + run: uv sync --frozen --all-groups + + - name: Run tests + coverage + working-directory: ./backend + # Coverage floor at 40% (baseline ~43%); ratchet up as coverage grows. + run: uv run pytest -m "not eval" --cov=cortexdj --cov-report=term-missing --cov-report=xml --cov-fail-under=40 + + - name: Upload coverage report + uses: actions/upload-artifact@v4 + with: + name: coverage-xml + path: backend/coverage.xml + frontend-lint: name: Frontend Lint runs-on: ubuntu-latest diff --git a/.github/workflows/eval.yml b/.github/workflows/eval.yml new file mode 100644 index 0000000..ad39166 --- /dev/null +++ b/.github/workflows/eval.yml @@ -0,0 +1,42 @@ +name: Eval + +# Real-LLM agent evals (pydantic-evals). Kept out of PR CI because they call a +# real provider (cost + flakiness). Run on demand from the Actions tab, or enable +# the nightly schedule below once OPENAI_API_KEY is set as a repository secret. +on: + workflow_dispatch: + # schedule: + # - cron: "0 7 * * *" # nightly 07:00 UTC safety net on main + +jobs: + eval: + name: Agent Evals + runs-on: ubuntu-latest + env: + # Settings require these at import; the evals never connect to the DB. + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: cortexdj + POSTGRES_HOST: localhost + POSTGRES_PORT: "5432" + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + steps: + - uses: actions/checkout@v6 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.13" + + - name: Setup uv + uses: astral-sh/setup-uv@v8.0.0 + with: + enable-cache: true + + - name: Install dependencies + working-directory: ./backend + run: uv sync --frozen --all-groups + + - name: Run evals + working-directory: ./backend + run: uv run pytest -m eval tests/evals/ diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 83dfd95..f7aa593 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -38,6 +38,7 @@ dev = [ "pre-commit>=4.6.0", "pydantic-evals>=2.11.0", "pytest>=9.1.1", + "pytest-cov>=7.1.0", "ruff>=0.15.22", ] diff --git a/backend/uv.lock b/backend/uv.lock index feaf4aa..70caa72 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -530,6 +530,7 @@ dev = [ { name = "pre-commit" }, { name = "pydantic-evals" }, { name = "pytest" }, + { name = "pytest-cov" }, { name = "ruff" }, ] @@ -564,9 +565,34 @@ dev = [ { name = "pre-commit", specifier = ">=4.6.0" }, { name = "pydantic-evals", specifier = ">=2.11.0" }, { name = "pytest", specifier = ">=9.1.1" }, + { name = "pytest-cov", specifier = ">=7.1.0" }, { name = "ruff", specifier = ">=0.15.22" }, ] +[[package]] +name = "coverage" +version = "7.15.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/76/d0/55fe630f4cf94e3fcba868240fad8c8cdd1f764e2a932f8926347e6ec4cd/coverage-7.15.2.tar.gz", hash = "sha256:3df60dc267f0a2ca23cb7a9ab1109c62b9335ffbf519fcfe167157c28c09b81d", size = 927741, upload-time = "2026-07-15T18:56:19.558Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fc/d5/f8c838e6b7282976f7c918884b792df7a0c42c5bba5d99c60ad2d221d56d/coverage-7.15.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:1121caa19159a38b5463eaae4b1e1fde81e525b15ecc5e000cd5b1a108f743a8", size = 221606, upload-time = "2026-07-15T18:54:45.448Z" }, + { url = "https://files.pythonhosted.org/packages/bf/37/97c926376364f66298cc44893b89cdf17b8bc406376497c4061ae4b8a8ff/coverage-7.15.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a300c6934e0989c327b9e8a1e110329da4641149f872bbe9f70168be66da76c1", size = 221982, upload-time = "2026-07-15T18:54:47.341Z" }, + { url = "https://files.pythonhosted.org/packages/b7/30/a36050a6e83c2135ee0776f452ca3948224befc6d7f26acecc082d0c106a/coverage-7.15.2-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:2617f8799d268fabdeef42a7e89ac3a23e1deee9025427db2df970f99a89a578", size = 252972, upload-time = "2026-07-15T18:54:49.2Z" }, + { url = "https://files.pythonhosted.org/packages/31/d3/06b5f1daf95f0f15ab05bd75f26ba5f3c8b33d0bb72f3aaa3cf41d1bad3a/coverage-7.15.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7dc2950a2992cd676d35c20ae63522836deeb034f08874699d14068710af3dc1", size = 255569, upload-time = "2026-07-15T18:54:51.098Z" }, + { url = "https://files.pythonhosted.org/packages/81/1c/9afb3f8de2b8d36960391c48559a2e3ff96594b58099f115921549ea8d0d/coverage-7.15.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9e36686f7a442185db2400b3df171aac520869faf9deb59df687d28659eda2a6", size = 256806, upload-time = "2026-07-15T18:54:53.145Z" }, + { url = "https://files.pythonhosted.org/packages/64/d8/b989f96061a5e32d82fddd1b1b9ff48a7c8f8ae7606f0e80fd9de54b1e33/coverage-7.15.2-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7d29ca7bd67af6e12e74632d65f026eabc1364da5c254494cd914446a28a3ef7", size = 258936, upload-time = "2026-07-15T18:54:55.015Z" }, + { url = "https://files.pythonhosted.org/packages/b8/fa/f99771f5110457c7b511c1935ca49ddf288218eaa84322e028b9334146ae/coverage-7.15.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:db9c8438057e5b0f6a22a0af99c0c1d26b57fbbdbd1be5861ddb8f897fcc3a2d", size = 253178, upload-time = "2026-07-15T18:54:57.527Z" }, + { url = "https://files.pythonhosted.org/packages/f6/96/c098a6044d119c751ceede7be91035fa8310170ec24a6523aff72f0a5793/coverage-7.15.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:63022c4c8dec1d0342f05c3ede99842fe3d007689acc45e86f123a1746e4a026", size = 254934, upload-time = "2026-07-15T18:54:59.41Z" }, + { url = "https://files.pythonhosted.org/packages/b2/a2/1457b3a7a50c8d77500103b97a046db863e2f59a1cf6d2f814595f349885/coverage-7.15.2-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:6c0be82b4d4aa5b2704e08518e2252f3e3d110164bcca826816801052e48a7aa", size = 252898, upload-time = "2026-07-15T18:55:01.338Z" }, + { url = "https://files.pythonhosted.org/packages/6c/0e/76958874c471ecfcdde0d2b2747bb2c61bdbf34a40636f4ce9db9923e643/coverage-7.15.2-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:4510fb9cdf6bb02dfa6af0be4a534b8102d086e22e4a33f8836df663da3d660d", size = 257056, upload-time = "2026-07-15T18:55:03.243Z" }, + { url = "https://files.pythonhosted.org/packages/7c/7c/3d7c4e3bf58baa40327dc7edc2272b17cf02299366d52763db1b0ca1556a/coverage-7.15.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:42ec3d989421b174a2ab607c1539f24127ad362757b7f1c0c0d7a2993f7eb37b", size = 252718, upload-time = "2026-07-15T18:55:05.029Z" }, + { url = "https://files.pythonhosted.org/packages/c8/b8/1cecffed9ce14fb25be9ba42d37b6bb61485c9a3ddd43cd3dde36b6087d8/coverage-7.15.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e8f91bce78e32343af184c3b7fa28fcf5a9e2641f4b6623d392038f804939188", size = 254490, upload-time = "2026-07-15T18:55:06.889Z" }, + { url = "https://files.pythonhosted.org/packages/6c/2c/42984561bc7f4c045dca67516a0c50ee5ef8d84352dbeb5559dc86c4823e/coverage-7.15.2-cp313-cp313-win32.whl", hash = "sha256:434e68d531858205895eb0d74b73d20b84260de426387d53c422a5acda2cf050", size = 223647, upload-time = "2026-07-15T18:55:08.941Z" }, + { url = "https://files.pythonhosted.org/packages/41/9f/39c7c9245efc583beddf89a87683574e663ed93637f3afb6cd7b88405676/coverage-7.15.2-cp313-cp313-win_amd64.whl", hash = "sha256:26c3b04a6377fd7c09800921fa934e3a17c0020439cd59df73e73ae1d4b6a78c", size = 224190, upload-time = "2026-07-15T18:55:10.789Z" }, + { url = "https://files.pythonhosted.org/packages/c7/de/3a2883cf8a213659280ef4b403059e17a9acaeb7fc7fd4105e1226ff2e6d/coverage-7.15.2-cp313-cp313-win_arm64.whl", hash = "sha256:3ed010aa1b69cda8e827aabfca9866216c980e2dca82ab9a78c5f83689964c8b", size = 223583, upload-time = "2026-07-15T18:55:12.678Z" }, + { url = "https://files.pythonhosted.org/packages/ec/82/32e3bd191d498e64f6f911ad55d14006a0861e54869d2d32452326399e65/coverage-7.15.2-py3-none-any.whl", hash = "sha256:eb6bcae8d1a9d305351ecb108232441d11c5cfe9de840a04388ba5d2db8d735c", size = 213375, upload-time = "2026-07-15T18:56:17.305Z" }, +] + [[package]] name = "cryptography" version = "49.0.0" @@ -2865,6 +2891,20 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" }, ] +[[package]] +name = "pytest-cov" +version = "7.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "coverage" }, + { name = "pluggy" }, + { name = "pytest" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b1/51/a849f96e117386044471c8ec2bd6cfebacda285da9525c9106aeb28da671/pytest_cov-7.1.0.tar.gz", hash = "sha256:30674f2b5f6351aa09702a9c8c364f6a01c27aae0c1366ae8016160d1efc56b2", size = 55592, upload-time = "2026-03-21T20:11:16.284Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9d/7a/d968e294073affff457b041c2be9868a40c1c71f4a35fcc1e45e5493067b/pytest_cov-7.1.0-py3-none-any.whl", hash = "sha256:a0461110b7865f9a271aa1b51e516c9a95de9d696734a2f71e3e78f46e1d4678", size = 22876, upload-time = "2026-03-21T20:11:14.438Z" }, +] + [[package]] name = "python-dateutil" version = "2.9.0.post0" From 61126ccdd665326c67e64cbac96eb95610c04506 Mon Sep 17 00:00:00 2001 From: Luke Mainwaring <lukemain@sas.upenn.edu> Date: Thu, 16 Jul 2026 14:29:17 -0400 Subject: [PATCH 6/6] docs: add agent-harness section to AGENTS.md Points agents at the canonical skills directory, the Codex mirror sync rule, the shared code-review methodology, and the skill-authoring and spec-driven workflows. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3d59730..af478ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,3 +104,10 @@ Next.js 16 with App Router. - Editing frontend code in general? See `.claude/rules/frontend/code-conventions.md` first — import-alias scope, shadcn/ui usage, kebab-case filenames, `cn()` from `@/lib/utils`. - Editing backend Python? See `.claude/rules/backend/code-conventions.md` first — filename, typing, and naming conventions. - Writing or naming new code (any stack)? See `.claude/rules/conventions.md` first — behavioral names, intent-carrying docstrings + negative constraints, rationale in ADRs. + +## Agent Harness + +- Skills live canonically in `.agents/skills/` (`.claude/skills` is a symlink into it). Codex parity lives in `.codex/` — `hooks.json`, byte-identical hook copies, and agent TOMLs. **When editing `.claude/hooks/` or `.claude/agents/`, mirror the change in `.codex/`.** +- Reviewing code? The methodology source of truth is `.agents/skills/code-review-guide/SKILL.md` — both the Claude subagent and Codex agent are thin wrappers around it. +- Writing or editing a skill? Read `.agents/skills/writing-great-skills/SKILL.md` first. +- Spec-driven work: `/to-spec` → `/to-tickets` → `/implement`. Run `/setup-matt-pocock-skills` once to configure the issue tracker they use.