Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

chore: bootstrap repo with chunks 1 and 2

Browse Source 
Establishes the global AI development config repo from scratch:

- Chunk 1: repo skeleton, install.sh, statusline, deploy manifest
- Chunk 2: core instructions (coding/git/testing), CLAUDE.md rewrite
  (always-on + content index two-tier model), docs restructure,
  6 ADRs, ROADMAP.md, .gitkeep placeholders
- Bootstrap skills in .claude/skills/ (to be catalogued and migrated
  to .agents/skills/ in Chunk 3)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Defame1297
2026-05-10 19:29:58 +00:00
commit a3bb708bff
66 changed files with 3283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
.claude/skills/caveman/SKILL.md Normal file
View File

@@ -0,0 +1,49 @@
---
name: caveman
description: >
Ultra-compressed communication mode. Cuts token usage ~75% by dropping
filler, articles, and pleasantries while keeping full technical accuracy.
Use when user says "caveman mode", "talk like caveman", "use caveman",
"less tokens", "be brief", or invokes /caveman.
---
Respond terse like smart caveman. All technical substance stay. Only fluff die.
## Persistence
ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
## Rules
Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
Pattern: `[thing] [action] [reason]. [next step].`
Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
### Examples
**"Why React component re-render?"**
> Inline obj prop -> new ref -> re-render. `useMemo`.
**"Explain database connection pooling."**
> Pool = reuse DB conn. Skip handshake -> fast under load.
## Auto-Clarity Exception
Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
Example -- destructive op:
> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
>
> ```sql
> DROP TABLE users;
> ```
>
> Caveman resume. Verify backup exist first.

117
.claude/skills/diagnose/SKILL.md Normal file
View File

@@ -0,0 +1,117 @@
---
name: diagnose
description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
---
# Diagnose
A discipline for hard bugs. Skip phases only when explicitly justified.
When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
## Phase 1 — Build a feedback loop
**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
### Ways to construct one — try them in roughly this order
1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
2. **Curl / HTTP script** against a running dev server.
3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
Build the right feedback loop, and the bug is 90% fixed.
### Iterate on the loop itself
Treat the loop as a product. Once you have _a_ loop, ask:
- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
### Non-deterministic bugs
The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
### When you genuinely cannot build a loop
Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
Do not proceed to Phase 2 until you have a loop you believe in.
## Phase 2 — Reproduce
Run the loop. Watch the bug appear.
Confirm:
- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
Do not proceed until you reproduce the bug.
## Phase 3 — Hypothesise
Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
Each hypothesis must be **falsifiable**: state the prediction it makes.
> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
## Phase 4 — Instrument
Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
Tool preference:
1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
2. **Targeted logs** at the boundaries that distinguish hypotheses.
3. Never "log everything and grep".
**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
## Phase 5 — Fix + regression test
Write the regression test **before the fix** — but only if there is a **correct seam** for it.
A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
If a correct seam exists:
1. Turn the minimised repro into a failing test at that seam.
2. Watch it fail.
3. Apply the fix.
4. Watch it pass.
5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
## Phase 6 — Cleanup + post-mortem
Required before declaring done:
- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
- [ ] Regression test passes (or absence of seam is documented)
- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

41
.claude/skills/diagnose/scripts/hitl-loop.template.sh Normal file
View File

@@ -0,0 +1,41 @@
#!/usr/bin/env bash
# Human-in-the-loop reproduction loop.
# Copy this file, edit the steps below, and run it.
# The agent runs the script; the user follows prompts in their terminal.
#
# Usage:
# bash hitl-loop.template.sh
#
# Two helpers:
# step "<instruction>" → show instruction, wait for Enter
# capture VAR "<question>" → show question, read response into VAR
#
# At the end, captured values are printed as KEY=VALUE for the agent to parse.
set -euo pipefail
step() {
printf '\n>>> %s\n' "$1"
read -r -p " [Enter when done] " _
}
capture() {
local var="$1" question="$2" answer
printf '\n>>> %s\n' "$question"
read -r -p " > " answer
printf -v "$var" '%s' "$answer"
}
# --- edit below ---------------------------------------------------------
step "Open the app at http://localhost:3000 and sign in."
capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
capture ERROR_MSG "Paste the error message (or 'none'):"
# --- edit above ---------------------------------------------------------
printf '\n--- Captured ---\n'
printf 'ERRORED=%s\n' "$ERRORED"
printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

10
.claude/skills/grill-me/SKILL.md Normal file
View File

@@ -0,0 +1,10 @@
---
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".
---
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.

47
.claude/skills/grill-with-docs/ADR-FORMAT.md Normal file
View File

@@ -0,0 +1,47 @@
# ADR Format
ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
Create the `docs/adr/` directory lazily — only when the first ADR is needed.
## Template
```md
# {Short title of the decision}
{1-3 sentences: what's the context, what did we decide, and why.}
```
That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
## Optional sections
Only include these when they add genuine value. Most ADRs won't need them.
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
- **Considered Options** — only when the rejected alternatives are worth remembering
- **Consequences** — only when non-obvious downstream effects need to be called out
## Numbering
Scan `docs/adr/` for the highest existing number and increment by one.
## When to offer an ADR
All three of these must be true:
1. **Hard to reverse** — the cost of changing your mind later is meaningful
2. **Surprising without context** — a future reader will look at the code and wonder "why on earth 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 a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
### What qualifies
- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

77
.claude/skills/grill-with-docs/CONTEXT-FORMAT.md Normal file
View File

@@ -0,0 +1,77 @@
# CONTEXT.md Format
## Structure
```md
# {Context Name}
{One or two sentence description of what this context is and why it exists.}
## Language
**Order**:
{A concise description of the term}
_Avoid_: Purchase, transaction
**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request
**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account
## Relationships
- An **Order** produces one or more **Invoices**
- An **Invoice** belongs to exactly one **Customer**
## Example dialogue
> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
## Flagged ambiguities
- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
```
## Rules
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
- **Show relationships.** Use bold term names and express cardinality where obvious.
- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
## Single vs multi-context repos
**Single context (most repos):** One `CONTEXT.md` at the repo root.
**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
```md
# Context Map
## Contexts
- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
## Relationships
- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
```
The skill infers which structure applies:
- If `CONTEXT-MAP.md` exists, read it to find contexts
- If only a root `CONTEXT.md` exists, single context
- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

88
.claude/skills/grill-with-docs/SKILL.md Normal file
View File

@@ -0,0 +1,88 @@
---
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.
---
<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).
Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
### 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>

37
.claude/skills/improve-codebase-architecture/DEEPENING.md Normal file
View File

@@ -0,0 +1,37 @@
# 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.

44
.claude/skills/improve-codebase-architecture/INTERFACE-DESIGN.md Normal file
View File

@@ -0,0 +1,44 @@
# 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.

53
.claude/skills/improve-codebase-architecture/LANGUAGE.md Normal file
View File

@@ -0,0 +1,53 @@
# 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**.

71
.claude/skills/improve-codebase-architecture/SKILL.md Normal file
View File

@@ -0,0 +1,71 @@
---
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.
---
# 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
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.
## Process
### 1. Explore
Read the project's domain glossary 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:
- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow** — interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
- Where do tightly-coupled modules leak across their seams?
- Which parts of the codebase are untested, or hard to test through their current interface?
Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
### 2. Present candidates
Present a numbered list of deepening opportunities. For each candidate:
- **Files** — which files/modules are involved
- **Problem** — why the current architecture is causing friction
- **Solution** — plain English description of what would change
- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
**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."
**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 (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
### 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.
Side effects happen inline as decisions crystallize:
- **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.
- **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).

79
.claude/skills/prototype/LOGIC.md Normal file
View File

@@ -0,0 +1,79 @@
# Logic Prototype
A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
## When this is the right shape
- "I'm not sure if this state machine handles the edge case where X then Y."
- "Does this data model actually let me represent the case where..."
- "I want to feel out what the API should look like before writing it."
- Anything where the user wants to **press buttons and watch state change**.
If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
## Process
### 1. State the question
Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
### 2. Pick the language
Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
### 3. Isolate the logic in a portable module
Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
The right shape depends on the question:
- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
### 4. Build the smallest TUI that exposes the state
Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
Each frame has two parts, in this order:
1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
2. **Keyboard shortcuts**, listed at the bottom: `[a] add user [d] delete user [t] tick clock [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
Behaviour:
1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
3. **Re-render** the full frame after every action — don't append, replace.
4. **Loop until quit.**
The whole frame should fit on one screen.
### 5. Make it runnable in one command
Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
If the host project has no task runner, just put the command at the top of the prototype's README.
### 6. Hand it over
Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
### 7. Capture the answer
When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
## Anti-patterns
- **Don't add tests.** A prototype that needs tests is no longer a prototype.
- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

30
.claude/skills/prototype/SKILL.md Normal file
View File

@@ -0,0 +1,30 @@
---
name: prototype
description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
---
# Prototype
A prototype is **throwaway code that answers a question**. The question decides the shape.
## Pick a branch
Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
## Rules that apply to both
1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
4. **Skip the polish.** No tests, no error handling beyond what makes the prototype *runnable*, no abstractions. The point is to learn something fast and then delete it.
5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
## When done
The *answer* is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

112
.claude/skills/prototype/UI.md Normal file
View File

@@ -0,0 +1,112 @@
# UI Prototype
Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
## When this is the right shape
- "What should this page look like?"
- "I want to see a few options for this dashboard before committing."
- "Try a different layout for the settings screen."
- Any time the user would otherwise spend a day picking between three vague mockups in their head.
## Two sub-shapes — strongly prefer sub-shape A
A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
### Sub-shape A — adjustment to an existing page (preferred)
The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
### Sub-shape B — a new page (last resort)
Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
In both sub-shapes the floating bottom bar is identical.
## Process
### 1. State the question and pick N
Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
Write down the plan in one line, in the prototype's location or a top-of-file comment:
> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
This works whether the user is here to push back or not.
### 2. Generate radically different variants
Draft each variant. Hold each one to:
- The page's purpose and the data it has access to.
- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
### 3. Wire them together
Create a single switcher component on the route:
```tsx
// pseudo-code — adapt to the project's framework
const variant = searchParams.get('variant') ?? 'A';
return (
<>
{variant === 'A' && <VariantA {...data} />}
{variant === 'B' && <VariantB {...data} />}
{variant === 'C' && <VariantC {...data} />}
<PrototypeSwitcher variants={['A','B','C']} current={variant} />
</>
);
```
For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
### 4. Build the floating switcher
A small fixed-position bar at the bottom-centre of the screen with three pieces:
- **Left arrow** — cycles to the previous variant (wraps around).
- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
- **Right arrow** — cycles forward (wraps around).
Behaviour:
- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
### 5. Hand it over
Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
### 6. Capture the answer and clean up
Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
## Anti-patterns
- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

109
.claude/skills/tdd/SKILL.md Normal file
View File

@@ -0,0 +1,109 @@
---
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.
---
# Test-Driven Development
## Philosophy
**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
**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.
**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.
See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
## Anti-Pattern: Horizontal Slices
**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."
This produces **crap tests**:
- 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
**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.
```
WRONG (horizontal):
RED: test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5
RIGHT (vertical):
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3
...
```
## 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
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
For each remaining behavior:
```
RED: Write next test → fails
GREEN: Minimal code to pass → passes
```
Rules:
- One test at a time
- Only enough code to pass current test
- Don't anticipate future tests
- Keep tests focused on observable behavior
### 4. Refactor
After all tests pass, look for [refactor candidates](refactoring.md):
- [ ] Extract duplication
- [ ] Deepen modules (move complexity behind simple interfaces)
- [ ] 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
```

33
.claude/skills/tdd/deep-modules.md Normal file
View File

@@ -0,0 +1,33 @@
# 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?

31
.claude/skills/tdd/interface-design.md Normal file
View File

@@ -0,0 +1,31 @@
# 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

59
.claude/skills/tdd/mocking.md Normal file
View File

@@ -0,0 +1,59 @@
# When to Mock
Mock at **system boundaries** only:
- External APIs (payment, email, etc.)
- Databases (sometimes - prefer test DB)
- Time/randomness
- File system (sometimes)
Don't mock:
- Your own classes/modules
- Internal collaborators
- Anything you control
## Designing for Mockability
At system boundaries, design interfaces that are easy to mock:
**1. Use dependency injection**
Pass external dependencies in rather than creating them internally:
```typescript
// Easy to mock
function processPayment(order, paymentClient) {
return paymentClient.charge(order.total);
}
// Hard to mock
function processPayment(order) {
const client = new StripeClient(process.env.STRIPE_KEY);
return client.charge(order.total);
}
```
**2. Prefer SDK-style interfaces over generic fetchers**
Create specific functions for each external operation instead of one generic function with conditional logic:
```typescript
// GOOD: Each function is independently mockable
const api = {
getUser: (id) => fetch(`/users/${id}`),
getOrders: (userId) => fetch(`/users/${userId}/orders`),
createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
};
// BAD: Mocking requires conditional logic inside the mock
const api = {
fetch: (endpoint, options) => fetch(endpoint, options),
};
```
The SDK approach means:
- Each mock returns one specific shape
- No conditional logic in test setup
- Easier to see which endpoints a test exercises
- Type safety per endpoint

10
.claude/skills/tdd/refactoring.md Normal file
View File

@@ -0,0 +1,10 @@
# Refactor Candidates
After TDD cycle, look for:
- **Duplication** → Extract function/class
- **Long methods** → Break into private helpers (keep tests on public interface)
- **Shallow modules** → Combine or deepen
- **Feature envy** → Move logic to where data lives
- **Primitive obsession** → Introduce value objects
- **Existing code** the new code reveals as problematic

61
.claude/skills/tdd/tests.md Normal file
View File

@@ -0,0 +1,61 @@
# Good and Bad Tests
## Good Tests
**Integration-style**: Test through real interfaces, not mocks of internal parts.
```typescript
// GOOD: Tests observable behavior
test("user can checkout with valid cart", async () => {
const cart = createCart();
cart.add(product);
const result = await checkout(cart, paymentMethod);
expect(result.status).toBe("confirmed");
});
```
Characteristics:
- Tests behavior users/callers care about
- Uses public API only
- Survives internal refactors
- Describes WHAT, not HOW
- One logical assertion per test
## Bad Tests
**Implementation-detail tests**: Coupled to internal structure.
```typescript
// BAD: Tests implementation details
test("checkout calls paymentService.process", async () => {
const mockPayment = jest.mock(paymentService);
await checkout(cart, payment);
expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
});
```
Red flags:
- Mocking internal collaborators
- Testing private methods
- Asserting on call counts/order
- Test breaks when refactoring without behavior change
- Test name describes HOW not WHAT
- Verifying through external means instead of interface
```typescript
// BAD: Bypasses interface to verify
test("createUser saves to database", async () => {
await createUser({ name: "Alice" });
const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
expect(row).toBeDefined();
});
// GOOD: Verifies through interface
test("createUser makes user retrievable", async () => {
const user = await createUser({ name: "Alice" });
const retrieved = await getUser(user.id);
expect(retrieved.name).toBe("Alice");
});
```

83
.claude/skills/to-issues/SKILL.md Normal file
View File

@@ -0,0 +1,83 @@
---
name: to-issues
description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
---
# To Issues
Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
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 an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker 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. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
### 3. Draft vertical slices
Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
<vertical-slice-rules>
- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
- A completed slice is demoable or verifiable on its own
- Prefer many thin slices over few thick ones
</vertical-slice-rules>
### 4. Quiz the user
Present the proposed breakdown as a numbered list. For each slice, show:
- **Title**: short descriptive name
- **Type**: HITL / AFK
- **Blocked by**: which other slices (if any) must complete first
- **User stories covered**: which user stories this addresses (if the source material has them)
Ask the user:
- Does the granularity feel right? (too coarse / too fine)
- Are the dependency relationships correct?
- Should any slices be merged or split further?
- Are the correct slices marked as HITL and AFK?
Iterate until the user approves the breakdown.
### 5. Publish the issues to the issue tracker
For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise.
Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
<issue-template>
## Parent
A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
## What to build
A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
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 here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
## Acceptance criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Blocked by
- A reference to the blocking ticket (if any)
Or "None - can start immediately" if no blockers.
</issue-template>
Do NOT close or modify any parent issue.

76
.claude/skills/to-prd/SKILL.md Normal file
View File

@@ -0,0 +1,76 @@
---
name: to-prd
description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
---
This skill takes the current conversation context and codebase understanding and produces 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 PRD, and respect any ADRs in the area you're touching.
2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.
A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.
Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
<prd-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 PRD.
## Further Notes
Any further notes about the feature.
</prd-template>

168
.claude/skills/triage/AGENT-BRIEF.md Normal file
View File

@@ -0,0 +1,168 @@
# Writing Agent Briefs
An agent brief is a structured comment posted on a GitHub issue when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
## Principles
### Durability over precision
The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
- **Do** describe interfaces, types, and behavioral contracts
- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
- **Don't** reference file paths — they go stale
- **Don't** reference line numbers
- **Don't** assume the current implementation structure will remain the same
### Behavioral, not procedural
Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
- **Good:** "When a user runs `/triage` with no arguments, they should see a summary of issues needing attention"
- **Bad:** "Add a switch statement in the main handler function"
### Complete acceptance criteria
The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
- **Bad:** "Triage should work correctly"
### Explicit scope boundaries
State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
## Template
```markdown
## Agent Brief
**Category:** bug / enhancement
**Summary:** one-line description of what needs to happen
**Current behavior:**
Describe what happens now. For bugs, this is the broken behavior.
For enhancements, this is the status quo the feature builds on.
**Desired behavior:**
Describe what should happen after the agent's work is complete.
Be specific about edge cases and error conditions.
**Key interfaces:**
- `TypeName` — what needs to change and why
- `functionName()` return type — what it currently returns vs what it should return
- Config shape — any new configuration options needed
**Acceptance criteria:**
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3
**Out of scope:**
- Thing that should NOT be changed or addressed in this issue
- Adjacent feature that might seem related but is separate
```
## Examples
### Good agent brief (bug)
```markdown
## Agent Brief
**Category:** bug
**Summary:** Skill description truncation drops mid-word, producing broken output
**Current behavior:**
When a skill description exceeds 1024 characters, it is truncated at exactly
1024 characters regardless of word boundaries. This produces descriptions
that end mid-word (e.g. "Use when the user wants to confi").
**Desired behavior:**
Truncation should break at the last word boundary before 1024 characters
and append "..." to indicate truncation.
**Key interfaces:**
- The `SkillMetadata` type's `description` field — no type change needed,
but the validation/processing logic that populates it needs to respect
word boundaries
- Any function that reads SKILL.md frontmatter and extracts the description
**Acceptance criteria:**
- [ ] Descriptions under 1024 chars are unchanged
- [ ] Descriptions over 1024 chars are truncated at the last word boundary
before 1024 chars
- [ ] Truncated descriptions end with "..."
- [ ] The total length including "..." does not exceed 1024 chars
**Out of scope:**
- Changing the 1024 char limit itself
- Multi-line description support
```
### Good agent brief (enhancement)
```markdown
## Agent Brief
**Category:** enhancement
**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
**Current behavior:**
When a feature request is rejected, the issue is closed with a `wontfix` label
and a comment. There is no persistent record of the decision or reasoning.
Future similar requests require the maintainer to recall or search for the
prior discussion.
**Desired behavior:**
Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
files that capture the decision, reasoning, and links to all issues that
requested the feature. When triaging new issues, these files should be
checked for matches.
**Key interfaces:**
- Markdown file format in `.out-of-scope/` — each file should have a
`# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
and a `**Prior requests:**` list with issue links
- The triage workflow should read all `.out-of-scope/*.md` files early
and match incoming issues against them by concept similarity
**Acceptance criteria:**
- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
- [ ] The file includes the decision, reasoning, and link to the closed issue
- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
appended to its "Prior requests" list rather than creating a duplicate
- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
when a new issue matches a prior rejection
**Out of scope:**
- Automated matching (human confirms the match)
- Reopening previously rejected features
- Bug reports (only enhancement rejections go to `.out-of-scope/`)
```
### Bad agent brief
```markdown
## Agent Brief
**Summary:** Fix the triage bug
**What to do:**
The triage thing is broken. Look at the main file and fix it.
The function around line 150 has the issue.
**Files to change:**
- src/triage/handler.ts (line 150)
- src/types.ts (line 42)
```
This is bad because:
- No category
- Vague description ("the triage thing is broken")
- References file paths and line numbers that will go stale
- No acceptance criteria
- No scope boundaries
- No description of current vs desired behavior

101
.claude/skills/triage/OUT-OF-SCOPE.md Normal file
View File

@@ -0,0 +1,101 @@
# Out-of-Scope Knowledge Base
The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it
## Directory structure
```
.out-of-scope/
├── dark-mode.md
├── plugin-system.md
└── graphql-api.md
```
One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
## File format
The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time.
```markdown
# Dark Mode
This project does not support dark mode or user-facing theming.
## Why this is out of scope
The rendering pipeline assumes a single color palette defined in
`ThemeConfig`. Supporting multiple themes would require:
- A theme context provider wrapping the entire component tree
- Per-component theme-aware style resolution
- A persistence layer for user theme preferences
This is a significant architectural change that doesn't align with the
project's focus on content authoring. Theming is a concern for downstream
consumers who embed or redistribute the output.
```ts
// The current ThemeConfig interface is not designed for runtime switching:
interface ThemeConfig {
colors: ColorPalette; // single palette, resolved at build time
fonts: FontStack;
}
```
## Prior requests
- #42 — "Add dark mode support"
- #87 — "Night theme for accessibility"
- #134 — "Dark theme option"
```
### Naming the file
Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file.
### Writing the reason
The reason should be substantive — not "we don't want this" but why. Good reasons reference:
- Project scope or philosophy ("This project focuses on X; theming is a downstream concern")
- Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture")
- Strategic decisions ("We chose to use A instead of B because...")
The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals.
## When to check `.out-of-scope/`
During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue:
- Check if the request matches an existing out-of-scope concept
- Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md`
- If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?"
The maintainer may:
- **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed
- **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
- **Disagree** — the issues are related but distinct, proceed with normal triage
## When to write to `.out-of-scope/`
Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow:
1. Maintainer decides a feature request is out of scope
2. Check if a matching `.out-of-scope/` file already exists
3. If yes: append the new issue to the "Prior requests" list
4. If no: create a new file with the concept name, decision, reason, and first prior request
5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
6. Close the issue with the `wontfix` label
## Updating or removing out-of-scope files
If the maintainer changes their mind about a previously rejected concept:
- Delete the `.out-of-scope/` file
- The skill does not need to reopen old issues — they're historical records
- The new issue that triggered the reconsideration proceeds through normal triage

103
.claude/skills/triage/SKILL.md Normal file
View File

@@ -0,0 +1,103 @@
---
name: triage
description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
---
# Triage
Move issues on the project issue tracker through a small state machine of triage roles.
Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
```
> *This was generated by AI during triage.*
```
## Reference docs
- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
## Roles
Two **category** roles:
- `bug` — something is broken
- `enhancement` — new feature or improvement
Five **state** roles:
- `needs-triage` — maintainer needs to evaluate
- `needs-info` — waiting on reporter for more information
- `ready-for-agent` — fully specified, ready for an AFK agent
- `ready-for-human` — needs human implementation
- `wontfix` — will not be actioned
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
## Invocation
The maintainer invokes `/triage` and describes what they want in natural language. Interpret the request and act. Examples:
- "Show me anything that needs my attention"
- "Let's look at #42"
- "Move #42 to ready-for-agent"
- "What's ready for agents to pick up?"
## Show what needs attention
Query the issue tracker and present three buckets, oldest first:
1. **Unlabeled** — never triaged.
2. **`needs-triage`** — evaluation in progress.
3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.
Show counts and a one-line summary per issue. Let the maintainer pick.
## Triage a specific issue
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.
3. **Reproduce (bugs only).** Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. Report what happened — successful repro with code path, failed repro, or insufficient detail (a strong `needs-info` signal). A confirmed repro makes a much stronger agent brief.
4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session.
5. **Apply the outcome:**
- `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
- `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
- `needs-info` — post triage notes (template below).
- `wontfix` (bug) — polite explanation, then close.
- `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
- `needs-triage` — apply the role. Optional comment if there's partial progress.
## Quick state override
If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
## Needs-info template
```markdown
## Triage Notes
**What we've established so far:**
- point 1
- point 2
**What we still need from you (@reporter):**
- question 1
- question 2
```
Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
## Resuming a previous session
If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.

117
.claude/skills/write-a-skill/SKILL.md Normal file
View File

@@ -0,0 +1,117 @@
---
name: write-a-skill
description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
---
# Writing Skills
## Process
1. **Gather requirements** - ask user about:
- What task/domain does the skill cover?
- What specific use cases should it handle?
- Does it need executable scripts or just instructions?
- Any reference materials to include?
2. **Draft the skill** - create:
- SKILL.md with concise instructions
- Additional reference files if content exceeds 500 lines
- Utility scripts if deterministic operations needed
3. **Review with user** - present draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more/less detailed?
## Skill Structure
```
skill-name/
├── SKILL.md # Main instructions (required)
├── REFERENCE.md # Detailed docs (if needed)
├── EXAMPLES.md # Usage examples (if needed)
└── scripts/ # Utility scripts (if needed)
└── helper.js
```
## SKILL.md Template
```md
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---
# Skill Name
## Quick start
[Minimal working example]
## Workflows
[Step-by-step processes with checklists for complex tasks]
## Advanced features
[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
```
## Description Requirements
The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
**Goal**: Give your agent just enough info to know:
1. What capability this skill provides
2. When/why to trigger it (specific keywords, contexts, file types)
**Format**:
- Max 1024 chars
- Write in third person
- First sentence: what it does
- Second sentence: "Use when [specific triggers]"
**Good example**:
```
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```
**Bad example**:
```
Helps with documents.
```
The bad example gives your agent no way to distinguish this from other document skills.
## When to Add Scripts
Add utility scripts when:
- Operation is deterministic (validation, formatting)
- Same code would be generated repeatedly
- Errors need explicit handling
Scripts save tokens and improve reliability vs generated code.
## When to Split Files
Split into separate files when:
- SKILL.md exceeds 100 lines
- Content has distinct domains (finance vs sales schemas)
- Advanced features are rarely needed
## Review Checklist
After drafting, verify:
- [ ] Description includes triggers ("Use when...")
- [ ] SKILL.md under 100 lines
- [ ] No time-sensitive info
- [ ] Consistent terminology
- [ ] Concrete examples included
- [ ] References one level deep

7
.claude/skills/zoom-out/SKILL.md Normal file
View File

@@ -0,0 +1,7 @@
---
name: zoom-out
description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
disable-model-invocation: true
---
I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.

23
.gitignore vendored Normal file
View File

@@ -0,0 +1,23 @@
# OS
.DS_Store
Thumbs.db
# Editor
.vscode/
.idea/
*.swp
*.swo
*~
# Logs and temp
*.log
*.tmp
/tmp/
# Environment
.env
.env.*
!.env.example
# Node (if tooling is added later)
node_modules/

42
CLAUDE.md Normal file
View File

@@ -0,0 +1,42 @@
> [!WARNING]
> **This is the repo meta-config.** It tells Claude how to work *inside this repository itself* — structure, conventions, how to add skills/workflows/providers.
>
> It is NOT the global config deployed to `~/.claude/`. That file lives at `providers/claude-code/CLAUDE.md`. Do not conflate the two.
# Working in this repo
This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
## Structure
- `core/` — provider-agnostic source of truth (plain language, no tool-specific references)
- `.agents/skills/` — canonical skills location (Agent Skills standard); populated in Chunk 3
- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`)
- `docs/` — project documentation, PRDs, and issues
- `scripts/` — install.sh (sync.sh and init-project.sh come in Chunk 6)
- `tests/` — test scripts
## Key documents
Read these at the start of every session in this repo:
- `CONTEXT.md` — domain language and principles; challenge any term that conflicts with it
- `docs/VISION.md` — purpose, goals, roadmap, and long-term Management Application vision
## Key rules
- `core/` content must use plain imperative language — no tool names, provider APIs, or format assumptions
- Never edit files deployed by `sync.sh` directly in a project; put customizations in override files
- `providers/claude-code/CLAUDE.md` is the deployed global config — edit it there, not here
## Chunk development workflow
Each chunk follows this sequence:
1. `/grill-with-docs` — grill vision/context before writing anything
2. `/to-prd` — write the PRD from the grilling output
3. `/to-issues` — break PRD into issues (`docs/issues/` until Gitea is set up)
4. `/tdd` — implement each issue using TDD
5. `/improve-codebase-architecture` — architecture review after implementation
6. Start a new session before the next chunk
Don't skip `/tdd` — it's the easy one to forget.

78
CONTEXT.md Normal file
View File

@@ -0,0 +1,78 @@
---
name: AI Development Repo
description: Domain language and decisions for the global AI development config repository
---
# Context
## Principles
### Provider-agnostic core
`core/` content uses plain imperative language — no tool names, provider APIs, or format assumptions. Anything referencing a specific tool belongs in `providers/`, not `core/`. Providers translate core content into the tool's expected format and language.
### CLAUDE.md index model
`providers/claude-code/CLAUDE.md` (source) is deployed to `~/.claude/CLAUDE.md` via `install.sh`. It has two tiers: (1) a short always-loaded section for universal rules that must apply every session — including communication style; (2) a content index of pointers to on-demand files in `~/.claude/core/` that the agent reads when needed. Context size is kept minimal.
### Instruction file format
`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
### Docs convention
Workflow artifacts are committed to `docs/` in subdirectories by type. All are tracked as issues.
**Naming:**
- `docs/prd/<slug>.md` — Product Requirements Documents
- `docs/ard/<slug>.md` — Architecture Requirements Documents
- `docs/bug/<slug>.md` — Bug Briefs
- `docs/notes/<slug>.md` — Exploration Notes
- `docs/adr/NNNN-<slug>.md` — Architecture Decision Records
- `docs/issues/NNNN-<slug>.md` — Issues
**NNNN** — zero-padded 4-digit sequential number (e.g. `0001`, `0042`). Used only for artifact types referenced by number (issues, ADRs). PRDs, ARDs, Bug Briefs, and Notes are referenced by topic and use a descriptive slug only.
**Slug** — kebab-case, lowercase, max 4–5 words, derived from the document title. No dates (git history carries dates). Examples: `chunk-2-instructions`, `user-auth-flow`, `database-migration`.
**When each is written:** PRDs, ARDs, Bug Briefs, and Notes are pre-work — produced by a grill session before issues are created. ADRs are post-decision — written during or after implementation of an ARD when a hard-to-reverse choice is made. An improvement kick-off produces either a PRD (user-facing scope) or ARD (architectural scope).
### Content chunk QA
Instruction files and other content chunks cannot be unit tested. Verification is human-executed after implementation: open a new Claude session, exercise the relevant behaviour, and confirm the rules take effect. Each issue includes a short acceptance criteria checklist for the human to run post-commit. Automated QA applies to tooling (scripts, hooks); manual QA applies to agent behaviour and content correctness.
### Conventional commits
All commits in this repo follow the Conventional Commits specification (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`). Convention is defined in `core/instructions/git.md`. Changelog tooling is a follow-on issue — convention is established first.
### Project override model
Projects override on-demand content (workflows, agent roles, prompts) by placing their own versions in `.claude/`. Universal rules are additive — projects extend them, not replace them. A rule that needs per-project suppression is not truly universal.
### Sync model
Projects must never edit synced files directly — customizations live in separate override files. A sync conflict is a signal that a synced file was edited directly.
## Glossary
### Management Application
A separate product (separate repo) for browsing, editing, and configuring AI development configs through a proper product UI. Git is the persistence layer, invisible to the user. The app is repo-agnostic — it works with any git repo that follows these conventions. This repo is the canonical default content (the official starter). See `docs/VISION.md` for the phased roadmap.
### Fleet
The set of machines and projects under management in Phase 2 of the Management Application. A fleet member is any machine that has the config deployed and can be reached by the runtime orchestration layer.
### Skills
Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Canonical location: `.agents/skills/<skill-name>/SKILL.md` in this repo; deployed to `~/.agents/skills/` on install.
### Content types
- **Instructions** — stateless rules defining AI behavior. Split into two tiers: (1) universal rules (communication, behavior) live in the always-on section of `providers/claude-code/CLAUDE.md`; (2) topic-specific rules (coding, git, testing) live in `core/instructions/<topic>.md` and are read on-demand.
- **Agents** — role definitions activated on-demand for a specific task.
- **Workflows** — compositions of skills chained into a larger task. Invokable by agents or humans. Example: grill-me → to-prd → to-issues as a product design workflow.
- **Prompts** — shared fragments (system prompt sections, output formats) embedded into multiple skills or workflows.
### Workstream
A focused work session oriented around a single goal — a feature, bug, improvement, or exploration. Starts with a grill to produce an artifact (PRD, Bug Brief, ADR, etc.), runs through issue implementation, and closes with docs + commit. Ongoing skills (/diagnose, /prototype, /zoom-out) are invoked ad hoc within a workstream as needed.
### Workflow artifacts
Output documents produced by a grill session that scope the work before implementation. All are committed to the repo under `docs/` following the docs convention. Each artifact generates one or more issues in `docs/issues/` but is not itself an issue.
Pre-work (grill output):
- **PRD** (Product Requirements Document) — for features and improvements with user-facing scope
- **ARD** (Architecture Requirements Document) — for architectural changes; defines what needs to change and why, analogous to a PRD but for architecture. Produced before implementation; not the same as an ADR.
- **Bug Brief** — for bugs; feeds into /diagnose
- **Exploration Note** — for ideation; may or may not produce issues
Post-decision:
- **ADR** (Architecture Decision Record) — records the decision made, alternatives considered, and rationale. Written during or after implementation of an ARD, not before. Hard-to-reverse decisions only.

1
core/agents/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Populated in Chunk 4 (agents). Remove this file when the first agent definition is added.

7
core/instructions/coding.md Normal file
View File

@@ -0,0 +1,7 @@
# Coding conventions
- Automate anything repeatable. If done manually twice, it belongs in a script, hook, or pipeline step.
- No comments unless the why is genuinely non-obvious. Names carry meaning; git history carries context.
- No defensive code at internal boundaries. Validate only at system edges: user input, external APIs, git hooks.
- Prefer explicit over implicit. Code must be readable without inferring intent from convention.
- No abstractions, features, or cleanup beyond what the task requires.

7
core/instructions/git.md Normal file
View File

@@ -0,0 +1,7 @@
# Git conventions
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
- Never force-push main or master.
- Commit messages explain why, not what. Written for both humans and changelog generators.
- Never commit secrets, credentials, or environment-specific config.
- Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`

6
core/instructions/testing.md Normal file
View File

@@ -0,0 +1,6 @@
# Testing conventions
- Prefer integration tests over mocks. Mocks mask production divergence; real systems catch real failures.
- Automate everything automatable. Manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment.
- Test observable end-state, not implementation internals. Tests must survive refactoring.
- No test is better than a wrong test. A passing mock that masks a real failure is actively harmful.

1
core/prompts/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Populated in Chunk 4/5 (prompts). Remove this file when the first prompt template is added.

1
core/workflows/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Populated in Chunk 4 (workflows). Remove this file when the first workflow is added.

75
docs/ROADMAP.md Normal file
View File

@@ -0,0 +1,75 @@
# Roadmap
## Chunk conventions
Content chunks (2–5) run in two phases, treated as separate sessions:
1. **Architecture + thin drafts** — define the format, schema, and loading model; populate every category with a minimal first draft. Mark speculative entries with `<!-- draft -->` so future sessions know what to trust. Architecture decisions must be stable before phase 2.
2. **Focused refinement** — work through each category properly, one at a time. Treated as ongoing rather than a hard deadline; refinement is triggered by real friction, not a schedule.
Phase 1 is the planned chunk. Phase 2 is ongoing.
Chunk 6 (tooling) is exempt — it is implementation-driven, not content-driven.
## Chunk table
| Chunk | Scope | Why this order |
|---|---|---|
| ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working |
| ✅ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates |
| 3 | First skills — initial slash commands for day-to-day use; changelog tooling (follow-on to Chunk 2 conventional commits); catalogue existing skills incl. `zoom-out` which is installed but undocumented | Skills are the most immediately useful output; validates the full pipeline |
| 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
| 5 | Agents — role definitions (reviewer, architect, developer) | More abstract definitions; benefits from workflow patterns being established first |
| 6 | Sync + project init tooling — `sync.sh` and `init-project.sh` | Tooling only makes sense once there is content worth syncing and scaffolding |
| 7 | Copilot provider — adapter for GitHub Copilot | Second provider comes after the first is fully proven |
## Development workflow
Every workstream follows this shape. Pick a kick-off type, grill it, then run the implementation loop per issue.
```
Kick-off (pick type)
├── Feature → /grill-with-docs → PRD → /to-issues
├── Bug → /grill-with-docs → Bug Brief → /to-issues → /diagnose
├── Architecture → /grill-with-docs → ARD (+ ADR later) → /to-issues
├── Improvement → /grill-with-docs → PRD or ARD → /to-issues
├── Feedback → /triage → PRD or Bug Brief → /to-issues
└── Ideation → /grill-me → Exploration Note → /to-issues (optional)
Per issue
└── /tdd → implement → automated QA → commit (conventional)
Manual QA — only for nuanced UI/UX or agent interaction behavior
/improve-codebase-architecture — ad hoc or at chunk/PR boundaries, not per issue
Ongoing (ad hoc, within any workstream)
├── /diagnose (unexpected breakage)
├── /prototype (design uncertainty)
└── /zoom-out (orientation)
Finalize (per workstream)
└── update docs → commit
```
This workflow is defined at convention level in Chunk 2. Chunk 4 formalizes it as a composable skill/workflow.
## Open questions / deferred decisions
Items consciously not resolved — to be addressed in the relevant chunk PRD or grill.
| Question | Deferred to |
|---|---|
| How project-level overrides are structured and what they can override | Chunk 6 PRD |
| ~~Deployment manifest seam — `install.sh` embeds source→target mappings implicitly; `sync.sh` will need the same mapping.~~ | ✅ Resolved in Chunk 2 architecture review — extracted to `scripts/deploy-manifest.sh`; `sync.sh` sources the same file in Chunk 6 |
| Feedback intake workflow — where does feedback arrive (GitHub issues, Slack, email)? | Grill before Chunk 4 (workflows) |
| QA agent design — what does automated agent testing look like in practice? | Grill before Chunk 5 (agents) |
| Automated deployment pipeline — CI/CD beyond gitops convention | Chunk 6 grill |
| Formal CI gate for `/improve-codebase-architecture` | Chunk 6 grill |
| Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs | Chunk 3 grill |
| Content index frontmatter — replace inline `when:` hints in CLAUDE.md content index with a `when:` field in each instruction/skill file so the agent discovers load conditions from the file itself. Cover before implementing Chunk 3 skills. | Chunk 3 grill |
| Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction. | Phase 2 refinement (post Chunk 4) |
| CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash). Needs its own grill session → PRD before implementation. | Future workstream, post Chunk 2 |
## Housekeeping reminders
- **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`, `docs/ard/`, `docs/bug/`, `docs/notes/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it.

130
docs/VISION.md Normal file
View File

@@ -0,0 +1,130 @@
# Vision
## Purpose
A global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Provides a consistent, provider-agnostic foundation that individual projects can inherit and extend.
Designed to start as a personal homelab tool and grow into something shareable with a team and potentially the open source community.
## Goals
- **Single source of truth** — one place to define and evolve AI development configs across all projects
- **Provider-agnostic core** — content works across AI coding tools (Claude Code, GitHub Copilot, etc.) through thin provider adapters
- **Layered override model** — global defaults defined here, project-level overrides live in each project
- **Pull-based distribution** — projects opt into updates consciously; no automatic or silent changes
- **Scales gracefully** — works solo today, designed to onboard a team and open source later
## Non-Goals (for now)
- Automatic push-based sync to projects
- Runtime dependency from projects back to this repo
- Bootstrapping new projects (`init-project.sh` comes in chunk 6)
- GitHub Copilot support (chunk 7)
## Architecture
### Layered model
```
this repo (global defaults)
├── install.sh → ~/.agents/skills/ (cross-client skills, all providers)
└── install.sh → ~/.claude/ (Claude Code config + content)
project repo (local overrides)
└── .claude/settings.json, CLAUDE.md (overrides global)
```
Projects consume from this repo by pulling updates via `sync.sh` (chunk 6). Until then, install is a one-time manual step.
### Directory structure
```
ai-development/
├── docs/ # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/)
├── .agents/ # Agent Skills standard location (provider-agnostic)
│ └── skills/ # SKILL.md files — read natively by Claude Code, Copilot, Cursor, etc.
├── core/ # Provider-agnostic source of truth
│ ├── instructions/ # AI behavior definitions (plain markdown)
│ ├── agents/ # Agent role definitions
│ ├── workflows/ # Workflow definitions
│ └── prompts/ # Reusable prompt templates
├── providers/ # Provider-specific adapters
│ ├── claude-code/ # CLAUDE.md, settings.json
│ └── copilot/ # copilot-instructions.md, hooks, agents adapter
├── templates/ # Project scaffolding templates
├── skills-lock.json # Tracks installed skills and their sources/hashes
└── scripts/
├── deploy-manifest.sh # Source→target mappings; sourced by install.sh and sync.sh
├── install.sh # Deploys to ~/.agents/skills/, ~/.claude/, etc.
├── sync.sh # Pulls updates into an existing project
└── init-project.sh # Bootstraps a new or existing project
```
### Content deployment model
`install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead:
- `.agents/skills/` → `~/.agents/skills/` — user-level cross-client skills (read by Claude Code, Copilot, Cursor, etc.)
- `core/` → `~/.claude/core/` — workflows, prompts, agent definitions; agent reads on demand
- `providers/claude-code/settings.json` → `~/.claude/settings.json`
- Writes a lean `~/.claude/CLAUDE.md` — universal rules only, plus pointers to where detailed content lives
`~/.claude/CLAUDE.md` is an index, not a content dump. It tells the agent where things are; the agent pulls what it needs using its Read tool. This keeps context size minimal — only what is needed for every session is loaded upfront.
### This repo's own CLAUDE.md
This repo has a `CLAUDE.md` at its root — a meta file that tells Claude how to work *in this repo itself* (structure, conventions, how to add skills/workflows/providers). This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/` for use across all projects. Do not conflate the two.
### Provider model
`core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
Skills are the strongest shared primitive — both Claude Code and GitHub Copilot use the `SKILL.md` format and follow the [Agent Skills open standard](https://agentskills.io).
### Architectural decisions
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure.
## V1 Definition
V1 is "ready to develop" — not a finished product. It means this repo is structured, Claude Code is wired up to it, and there is enough initial content to start building incrementally.
**V1 = Chunk 1 complete — ✅ done.**
Everything from chunk 2 onward is content and tooling built on top of that foundation.
## Long-term: Management Application
A product for making it easy to manage and update AI development configs. Lives in a separate repo. The UX speaks in domain concepts — skills, workflows, agents, providers. Git is the persistence layer, invisible to the user. Saving a skill commits under the hood; the user just clicks Save.
The app is **repo-agnostic** — it works with any git repo that follows these conventions. This repo is the canonical default content: the official starter pack referenced in the app's setup flow.
### Phase 1 — Config Management
Browse, edit, and configure AI development config through a proper product UI.
**Core features:** browse the skill/workflow/agent/prompt library; create and edit config content; manage provider settings.
**Design principle:** This is a product, not a file browser. Users never see git operations, file paths, or commit messages. The UI presents domain concepts (skills, workflows, agents, providers) and handles persistence silently. Any feature that exposes git internals to the user is out of scope.
**Architecture:**
- Stack: React + TypeScript + Vite (frontend), Node.js + Fastify + TypeScript (backend), PostgreSQL (introduced only when a specific feature requires state with no natural home in git)
- Stack rationale: single language across the full stack keeps the codebase navigable for junior developers and AI coding agents; TypeScript's explicit types make intent clear without comments; React → React Native is the cleanest path to mobile in Phase 3; `simple-git` covers all required git operations without needing a Python backend
- Git operations via `simple-git`; git repo stays the source of truth
- Deployment: Docker (Nginx + Node containers), k8s-ready
- Hosting: self-hosted first, cloud-hosted option later
- Users: solo-first, multi-user-ready data model from day one
**Start trigger:** after Chunk 6 of this repo (`sync.sh` + `init-project.sh`). Full content model and sync tooling must be stable before building a UI over them.
**Mobile/desktop (Phase 3):** React → React Native for mobile; Tauri to wrap the web app for desktop.
### Phase 2 — Agent & Fleet Management
Runtime orchestration: push config updates to machines, see running agents, manage task queues and outputs across a fleet of machines and projects.
**Start trigger:** feature-driven — Phase 2 begins when a concrete Phase 1 limitation forces it (e.g. wanting to push a config update to all machines without SSH-ing in, or needing visibility into what agents are running remotely).
### Phase 3 — Native Apps
Mobile (React Native) and desktop (Tauri) wrappers over the Phase 1/2 web app. Deferred until the web app is mature.

3
docs/adr/0001-pull-distribution-model.md Normal file
View File

@@ -0,0 +1,3 @@
# Pull distribution model
Projects pull config updates from this repo consciously rather than receiving automatic pushes. We chose pull because it keeps projects in control of when they take updates — a silent push could break a project mid-sprint with no warning. Pull also scales cleanly from solo homelab to open source: anyone can fork this repo and projects remain decoupled from the origin. The trade-off is that stale projects are invisible until they pull; push would make fleet drift detectable earlier, which is why fleet sync tooling (Phase 2) revisits this at the network layer, not at the file distribution layer.

3
docs/adr/0002-copy-not-symlink.md Normal file
View File

@@ -0,0 +1,3 @@
# Copy files, not symlinks or submodules
Content is deployed by copying files, not symlinking or using git submodules. Symlinks break if this repo moves or is renamed; submodules require git tooling everywhere a project runs — including on machines where this repo may not be cloned at all. Copying means a deployed project works in complete isolation from this repo's location or existence. The cost is that updates are opt-in (consistent with ADR-0001) and no automatic change detection exists. This is intentional: silent changes are a worse failure mode than stale configs.

3
docs/adr/0003-provider-agnostic-core.md Normal file
View File

@@ -0,0 +1,3 @@
# Provider-agnostic core with thin adapters
`core/` uses plain imperative markdown — no tool names, provider APIs, or format assumptions. Provider-specific translations live in `providers/<name>/`. The alternative was provider-specific content everywhere, which means adding a second provider (Copilot, Cursor) requires rewriting all content from scratch rather than writing a thin adapter. The cost is a translation layer: content must be kept abstract enough to survive adaptation, which sometimes means less tool-specific precision in the core. Where precision matters more than portability, it belongs in `providers/`, not `core/`.

3
docs/adr/0004-skills-in-agents-dir.md Normal file
View File

@@ -0,0 +1,3 @@
# Skills live in .agents/skills/, not .claude/skills/
Skills (slash commands) are stored in `.agents/skills/` following the [Agent Skills open standard](https://agentskills.io), not in `.claude/skills/` which is a Claude Code-specific location. Claude Code, GitHub Copilot, Cursor, and other tools read `.agents/skills/` natively without an adapter. Putting skills in `.claude/skills/` would make them Claude Code-only and contradict ADR-0003 (provider-agnostic where possible). Skills are the strongest shared primitive across providers — they should live at the most portable location available.

3
docs/adr/0005-two-tier-claude-md.md Normal file
View File

@@ -0,0 +1,3 @@
# Two-tier CLAUDE.md: always-on rules + on-demand content index
The deployed `~/.claude/CLAUDE.md` has two sections: (1) a short always-on section with universal rules loaded every session, and (2) a content index of pointers to on-demand files the agent reads when the task warrants it. The alternative — a single large file with all rules, workflows, and conventions — would load coding standards, git rules, and testing conventions into every session, including sessions that never touch code or run tests. Context is a scarce resource. Keeping the always-on section under 30 lines ensures it costs almost nothing; the agent pulls deeper content only when it's relevant.

3
docs/adr/0006-install-always-overwrites.md Normal file
View File

@@ -0,0 +1,3 @@
# install.sh always overwrites deployed files
`install.sh` overwrites `~/.claude/` and `~/.claude/core/` unconditionally on every run. It does not merge, diff, or ask. The rationale: the source of truth is this repo. Editing deployed files directly is a usage error — `sync.sh` would overwrite those edits on the next pull anyway. Offering a merge path would imply that editing `~/.claude/CLAUDE.md` directly is a supported workflow, which it is not. If a local customisation is needed it belongs in a project-level override file, not in the deployed global config.

1
docs/ard/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Remove this file when the first ARD is added.

1
docs/bug/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Remove this file when the first Bug Brief is added.

23
docs/issues/0001-repo-skeleton-content-files.md Normal file
View File

@@ -0,0 +1,23 @@
# 0001 — Repo skeleton: content files ✅
## What to build
Create the three content files that `install.sh` will deploy. This establishes the repo skeleton and makes the global Claude Code config a real, version-controlled artifact.
- `providers/claude-code/CLAUDE.md` — fill in the two-tier structure: one always-on rule ("when you need workflows, agents, or prompts, read them from `~/.claude/core/`") plus a content index section with pointers to `~/.claude/core/` (initially sparse, populated as chunks complete)
- `providers/claude-code/settings.json` — `{"theme": "dark"}`
- `core/instructions/global.md` — placeholder stub confirming the pipeline works; real content comes in Chunk 2
The root `CLAUDE.md` and `providers/claude-code/CLAUDE.md` already exist as shells with warnings — this issue fills in the real content of `providers/claude-code/CLAUDE.md`.
## Acceptance criteria
- [ ] `providers/claude-code/CLAUDE.md` has a short always-on section with the content index rule and a pointers section referencing `~/.claude/core/`
- [ ] `providers/claude-code/settings.json` contains `{"theme": "dark"}`
- [ ] `core/instructions/global.md` exists as a clearly-labelled placeholder stub
- [ ] No empty directories committed (`core/agents/`, `core/workflows/`, `core/prompts/` do not exist yet)
- [ ] `providers/claude-code/CLAUDE.md` warning banner distinguishes it from the root `CLAUDE.md`
## Blocked by
None — can start immediately.

28
docs/issues/0002-install-sh.md Normal file
View File

@@ -0,0 +1,28 @@
# 0002 — install.sh — deploy script ✅
## What to build
Write `scripts/install.sh` — an idempotent script that deploys this repo's content to `~/.claude/` and creates `~/.agents/skills/` as an empty directory. Running it once wires Claude Code to use this repo as its global config source. Running it again after pulling updates is safe.
Deployment targets:
- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`
- `providers/claude-code/settings.json` → `~/.claude/settings.json`
- `core/` → `~/.claude/core/` (full directory copy)
- Create `~/.agents/skills/` as an empty directory
Always overwrites deployed files — editing deployed files directly is a usage error, not a conflict. Creates directories if they don't exist.
After writing the script, run it once and perform the manual smoke test.
## Acceptance criteria
- [ ] `scripts/install.sh` exists and is executable
- [ ] Running it deploys `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, and `~/.claude/core/instructions/global.md`
- [ ] Running it creates `~/.agents/skills/` on disk
- [ ] Running it a second time completes without errors (idempotency check)
- [ ] A new Claude Code session confirms the always-on rule is in effect (ask Claude where it looks for workflows — it references `~/.claude/core/`)
- [ ] Bootstrap skills at `.claude/skills/` are untouched
## Blocked by
- 0001 — Repo skeleton: content files

42
docs/issues/0003-statusline.md Normal file
View File

@@ -0,0 +1,42 @@
# 0003 — Claude Code status line ✅
## What to build
Add a custom status line to the Claude Code provider that shows session context at a glance. The status line is a bash script that reads JSON from stdin on every Claude Code render event and prints a formatted, colored line.
Segments (left to right — identity → config → health):
- **Directory** — basename of working dir (bold blue)
- **Git branch** — green on feature branches, red on `main`/`master`
- **Model** — colored by cost tier: Haiku green, Sonnet amber, Opus red
- **Context %** — model-aware thresholds: Opus 55/75%, Sonnet 65/85%, Haiku 75/90%; green → amber → red
- **Cost** — session cost in USD; shown as ¢ below $1, $X.XX above; green → amber at $1.50 → red at $3.00
- **Tokens** — cumulative session total, formatted as Xk when ≥ 1000; blue (informational only)
- **Vim mode** — magenta, only shown when active
Segments joined with ` · `. Missing or zero-value segments are omitted entirely.
Files:
- `providers/claude-code/statusline-command.sh` — the script
- `providers/claude-code/settings.json` — updated with `statusLine` config
- `scripts/install.sh` — updated to deploy the script and set executable bit
## Acceptance criteria
- [x] `providers/claude-code/statusline-command.sh` exists and is executable
- [x] `settings.json` references the script via `statusLine.command`
- [x] `install.sh` deploys the script to `~/.claude/statusline-command.sh` with `chmod +x`
- [x] All segments render correctly with ANSI colors (no literal `\033[0m` in output)
- [x] Segments separated by ` · `, not `|`
- [x] Cost shown as ¢ below $1, $X.XX above
- [x] Tokens shown as Xk when ≥ 1000, raw number below
- [x] Missing fields produce no empty segment
- [x] `tests/test-statusline.sh` passes (11 tests)
- [x] `tests/test-install.sh` passes (now covers statusline deployment)
## Cost threshold rationale
On a $20/month subscription, `total_cost_usd` measures session weight rather than real spend. Thresholds ($1.50 amber / $3.00 red) are calibrated to signal a heavy session, not budget overrun. Adjust upward if amber rarely appears.
## Blocked by
- 0002 — install.sh

26
docs/issues/0004-rewrite-claude-md.md Normal file
View File

@@ -0,0 +1,26 @@
# 0004 — Rewrite providers/claude-code/CLAUDE.md and retire global.md ✅
## What to build
Replace the sparse content in `providers/claude-code/CLAUDE.md` with a complete always-on section covering communication style and behavior rules, plus a content index that tells the agent when to load each topic instruction file. Delete `core/instructions/global.md`, which is a placeholder stub with no content — the content index update makes it obsolete.
The always-on communication rules define how the agent responds: answer directly first, challenge bad ideas explicitly rather than validating them, explain the why behind decisions, and never soften disagreement into a suggestion.
The always-on behavior rules define when the agent asks permission: reads and exploration proceed freely; writes, edits, and git operations state intent before acting; irreversible or shared-state operations (push, drop, publish) require explicit confirmation every time.
The content index provides inline load triggers so the agent knows when to read each on-demand instruction file without requiring frontmatter in those files.
## Acceptance criteria
- [ ] `providers/claude-code/CLAUDE.md` contains an always-on communication section with all seven rules from the PRD
- [ ] `providers/claude-code/CLAUDE.md` contains an always-on behavior section covering reads, writes, and irreversible operations
- [ ] Content index includes load triggers for: coding conventions, git conventions, testing conventions, and workflows/agents/prompts
- [ ] `core/instructions/global.md` is deleted
- [ ] In a new session, ask an exploratory design question — agent responds with one recommendation and one tradeoff in 2–3 sentences
- [ ] In a new session, propose a clearly overengineered approach — agent names the problem rather than implementing it
- [ ] In a new session, ask the agent to edit a file — agent states what it is about to do before proceeding
- [ ] In a new session, ask the agent to push a commit — agent requires explicit confirmation
## Blocked by
None — can start immediately

18
docs/issues/0005-coding-instructions.md Normal file
View File

@@ -0,0 +1,18 @@
# 0005 — Write core/instructions/coding.md ✅
## What to build
Create the coding conventions instruction file at `core/instructions/coding.md`. Plain markdown, no frontmatter. The agent reads this file on demand when writing, editing, or reviewing code, as directed by the content index in `providers/claude-code/CLAUDE.md`.
The file establishes five key rules: automate anything repeatable; no comments unless the why is genuinely non-obvious; no defensive code at internal boundaries; prefer explicit over implicit; no abstractions, features, or cleanup beyond what the task requires.
## Acceptance criteria
- [ ] File exists at `core/instructions/coding.md`
- [ ] Contains all five rules from the PRD Module 2 section
- [ ] Plain markdown with no frontmatter or schema
- [ ] In a new session, ask the agent to implement something with unnecessary complexity — agent pushes back and names the rule being violated
## Blocked by
- 0004 — rewrite providers/claude-code/CLAUDE.md and retire global.md

19
docs/issues/0006-git-instructions.md Normal file
View File

@@ -0,0 +1,19 @@
# 0006 — Write core/instructions/git.md ✅
## What to build
Create the git conventions instruction file at `core/instructions/git.md`. Plain markdown, no frontmatter. The agent reads this file on demand when doing git operations, as directed by the content index in `providers/claude-code/CLAUDE.md`.
The file establishes five key rules: never skip hooks (`--no-verify`); never force-push main or master; commit messages explain why, not what; never commit secrets or credentials; and the conventional commits vocabulary (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`).
## Acceptance criteria
- [ ] File exists at `core/instructions/git.md`
- [ ] Contains all five rules from the PRD Module 3 section, including the conventional commits vocabulary
- [ ] Plain markdown with no frontmatter or schema
- [ ] In a new session, ask the agent to commit a change — agent uses conventional commits format unprompted
- [ ] In a new session, ask the agent to skip a pre-commit hook — agent refuses
## Blocked by
- 0004 — rewrite providers/claude-code/CLAUDE.md and retire global.md

18
docs/issues/0007-testing-instructions.md Normal file
View File

@@ -0,0 +1,18 @@
# 0007 — Write core/instructions/testing.md ✅
## What to build
Create the testing conventions instruction file at `core/instructions/testing.md`. Plain markdown, no frontmatter. The agent reads this file on demand when writing or running tests, as directed by the content index in `providers/claude-code/CLAUDE.md`.
The file establishes four key rules: prefer integration tests over mocks; automate everything automatable; test observable end-state, not implementation internals; no test is better than a wrong test.
## Acceptance criteria
- [ ] File exists at `core/instructions/testing.md`
- [ ] Contains all four rules from the PRD Module 4 section
- [ ] Plain markdown with no frontmatter or schema
- [ ] In a new session, ask the agent to write a test requiring a mocked database — agent pushes back and proposes an integration test instead
## Blocked by
- 0004 — rewrite providers/claude-code/CLAUDE.md and retire global.md

21
docs/issues/0008-docs-restructure.md Normal file
View File

@@ -0,0 +1,21 @@
# 0008 — Restructure docs/ subdirectories and migrate existing PRD ✅
## What to build
Create the subdirectory-by-type structure under `docs/` as defined in CONTEXT.md. Migrate the one existing PRD from its flat location to the correct subdirectory. No other files move.
New directories to create: `docs/prd/`, `docs/ard/`, `docs/bug/`, `docs/notes/`, `docs/adr/`. (`docs/issues/` already exists and is correctly placed.) `docs/VISION.md` stays at `docs/VISION.md`.
Migration: `docs/prd-chunk-1.md` → `docs/prd/chunk-1.md`.
## Acceptance criteria
- [ ] `docs/prd/`, `docs/ard/`, `docs/bug/`, `docs/notes/`, `docs/adr/` directories exist
- [ ] `docs/prd/chunk-1.md` exists (migrated from `docs/prd-chunk-1.md`)
- [ ] `docs/prd-chunk-1.md` no longer exists
- [ ] `docs/VISION.md` is unchanged at `docs/VISION.md`
- [ ] `docs/issues/` is unchanged
## Blocked by
None — can start immediately

1
docs/notes/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# Remove this file when the first Exploration Note is added.

80
docs/prd/chunk-1.md Normal file
View File

@@ -0,0 +1,80 @@
# PRD: Chunk 1 — Repo Skeleton + install.sh
## Problem Statement
Claude Code is not currently using this repo as its global config source. There is no directory structure, no install mechanism, and no deployed configuration — Claude Code runs with default behavior across all projects. The global AI development config repo exists in name only.
## Solution
Build the repo skeleton and an idempotent `install.sh` that deploys this repo's content to `~/.claude/` and `~/.agents/skills/`. After running it once, Claude Code will load universal rules every session and know where to find on-demand content (workflows, agents, prompts). The repo becomes the authoritative global config source.
## User Stories
1. As a developer, I want to run `install.sh` once and have Claude Code configured globally, so that I don't need to configure it per-project.
2. As a developer, I want `install.sh` to be idempotent, so that I can re-run it after pulling updates without fear of breaking my setup.
3. As a developer, I want Claude Code to load universal rules every session, so that my global conventions are always applied without manual setup.
4. As a developer, I want Claude Code to know where to find workflows, agents, and prompts, so that it can load them on demand using its Read tool.
5. As a developer, I want a clear separation between this repo's meta-config and the deployed global config, so that editing the wrong file doesn't silently corrupt my setup.
6. As a developer, I want placeholder content in `core/` to validate the pipeline end-to-end, so that I can confirm the structure works before building real content in Chunk 2.
7. As a developer, I want `~/.agents/skills/` created on my machine during install, so that Chunk 3 can populate it without needing to create the directory itself.
8. As a developer, I want the global `settings.json` committed to this repo, so that my Claude Code preferences are version-controlled and reproducible.
9. As a developer, I want the two `CLAUDE.md` files to have prominent warnings at the top, so that I never accidentally edit the deployed global config thinking it's the repo meta-config.
## Implementation Decisions
### Modules
**`scripts/install.sh`**
Idempotent shell script. Always overwrites deployed files (never skips on conflict — editing deployed files directly is a usage error, not a sync problem). Creates directories if they don't exist. Deploys:
- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`
- `providers/claude-code/settings.json` → `~/.claude/settings.json`
- `core/` → `~/.claude/core/` (full directory copy)
- Creates `~/.agents/skills/` as an empty directory (Chunk 3 populates it)
**`providers/claude-code/CLAUDE.md`**
Verbatim source file — `install.sh` copies it as-is, no templating. Two-tier structure:
- Always-on section: one rule — when workflows, agents, or prompts are needed, read them from `~/.claude/core/`
- Content index section: pointers to on-demand content in `~/.claude/core/` (populated as chunks are completed)
**`providers/claude-code/settings.json`**
Minimal global settings baseline for Chunk 1: `{"theme": "dark"}`. Permissions, hooks, and model defaults are Chunk 2+ territory.
**`core/instructions/global.md`**
Single placeholder stub file. Exists to validate that `install.sh` correctly deploys `core/` to `~/.claude/core/` and that the always-on rule in `CLAUDE.md` can successfully point to it. Content is a stub; real instructions are written in Chunk 2.
### Key decisions
- `providers/claude-code/CLAUDE.md` is a **verbatim copy** — no variable substitution. Paths like `~/.claude/core/` are stable and don't vary per machine. Templating is deferred until there's a concrete need.
- Empty directories (`core/agents/`, `core/workflows/`, `core/prompts/`) are **not committed**. They are created when Chunk 2+ populates them.
- The bootstrap skills at `.claude/skills/` are **not touched** by Chunk 1. They stay in place until Chunk 3 migrates them to `.agents/skills/`.
- Two `CLAUDE.md` files exist in this repo and must never be conflated: the root `CLAUDE.md` (how to work in this repo) and `providers/claude-code/CLAUDE.md` (deployed global config). Both have prominent warnings.
## Testing Decisions
A good test for this chunk verifies observable end-state, not script internals: after running `install.sh`, the right files exist at the right paths with the right content.
**Manual smoke test (sufficient for Chunk 1):**
1. Run `scripts/install.sh`
2. Verify `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude/core/instructions/global.md`, and `~/.agents/skills/` all exist
3. Open a new Claude Code session and confirm the always-on rule is in effect — ask Claude where it looks for workflows; it should reference `~/.claude/core/`
4. Run `install.sh` a second time and verify it completes without errors (idempotency check)
No automated tests for Chunk 1. The install script is simple enough that a one-time manual check is sufficient. Automated install testing becomes worthwhile when `sync.sh` and `init-project.sh` are added in Chunk 6.
## Out of Scope
- Real instructions, coding conventions, AI behavior rules (Chunk 2)
- Skills content and migration of bootstrap `.claude/skills/` to `.agents/skills/` (Chunk 3)
- Workflows, agents, prompts content (Chunks 4–5)
- `sync.sh` and `init-project.sh` (Chunk 6)
- GitHub Copilot provider adapter (Chunk 7)
- `skills-lock.json` design and long-term role (Chunk 3)
- `providers/claude-code/settings.json` permissions, hooks, model defaults (Chunk 2+)
- Templating in `install.sh` (deferred until concretely needed)
- Project-level override structure (Chunk 6)
## Further Notes
The root `CLAUDE.md` and `providers/claude-code/CLAUDE.md` were created during the grilling session and already exist in the repo — Chunk 1 implementation should fill in the content of `providers/claude-code/CLAUDE.md` and ensure the root `CLAUDE.md` accurately reflects the final structure.
V1 is complete when Chunk 1 is done: the repo is structured, `install.sh` has been run once, and Claude Code uses this repo as its global config source.

151
docs/prd/chunk-2-instructions.md Normal file
View File

@@ -0,0 +1,151 @@
# PRD: Chunk 2 — Core Instructions
## Problem Statement
Claude Code runs without any domain conventions or coding standards — every session starts from scratch. The placeholder `core/instructions/global.md` exists but contains no content. `providers/claude-code/CLAUDE.md` has only one rule and no communication or behavior guidelines. There are no rules about how code should be written, how commits should be structured, or how tests should be approached. The agent has no basis for challenging bad ideas, explaining decisions, or behaving consistently across sessions.
Separately, `docs/` has no consistent naming convention. As workflow artifacts accumulate (PRDs, ARDs, Bug Briefs), there is no predictable place to find them.
## Solution
Write three topic-specific instruction files (`coding.md`, `git.md`, `testing.md`) that the agent reads on demand. Update `providers/claude-code/CLAUDE.md` with a proper always-on section covering communication style and behavior rules. Retire the placeholder `global.md`. Establish the subdirectory-by-type naming convention for `docs/` and migrate the existing PRD into it.
This gives the agent real conventions to follow from every session forward, and gives humans a clean, navigable document structure as the repo grows.
## User Stories
1. As a developer, I want the agent to follow consistent coding conventions, so that code quality is predictable across sessions without repeating instructions.
2. As a developer, I want coding conventions loaded on demand rather than always, so that every session does not pay a context cost for rules that may not be relevant.
3. As a developer, I want the agent to follow conventional commits format, so that git history is machine-readable and changelog automation is possible in Chunk 3.
4. As a developer, I want git safety rules available whenever I do git operations, so that I never accidentally bypass hooks or force-push main.
5. As a developer, I want the agent to require my approval before writing or editing files, so that I stay in control and understand what is changing.
6. As a developer, I want the agent to proceed freely with reads and exploration, so that information-gathering does not require constant approval.
7. As a developer, I want the agent to always require explicit confirmation for irreversible or shared-state operations, so that I never accidentally push, drop, or publish something unintended.
8. As a developer, I want the agent to challenge my ideas with industry standards rather than validate them, so that I make better decisions rather than hearing what I want to hear.
9. As a developer, I want the agent to explain the why behind pushback and decisions, so that I build domain knowledge and can generalise to future situations.
10. As a developer, I want the agent to answer directly first and give context only when it changes the answer, so that responses are efficient and signal-dense.
11. As a developer, I want the agent never to soften disagreement into a suggestion, so that I can trust the agent is giving me its actual assessment.
12. As a developer, I want the agent to prefer integration tests over mocks, so that tests catch real divergences between code and production systems.
13. As a developer, I want manual testing reserved for nuanced UI/UX or agent interaction behaviour, so that automation handles everything that can be automated.
14. As a developer, I want the agent to test observable end-state rather than implementation internals, so that tests survive refactoring without needing to be rewritten.
15. As a developer, I want a consistent subdirectory-by-type naming convention for `docs/`, so that I can navigate artifacts without guessing where they live.
16. As a developer, I want existing docs migrated to the new convention, so that the repo is consistent from the start rather than accumulating two naming patterns.
17. As a developer, I want `global.md` retired, so that there is no ambiguity about where instruction content lives.
18. As a developer, I want the content index in `CLAUDE.md` to include a load trigger for each file, so that the agent knows when to read each instruction file without requiring frontmatter.
19. As a developer, I want acceptance criteria on each issue that I can verify in a new Claude session, so that I can confirm conventions are actually being applied and not just written.
20. As a developer, I want instruction files to use plain markdown with no schema or frontmatter, so that they are readable by both humans and agents without tooling.
## Implementation Decisions
### Module 1 — `providers/claude-code/CLAUDE.md` (rewrite)
The source file deployed to `~/.claude/CLAUDE.md` via `install.sh`. Rewritten with two top-level sections replacing the current sparse content.
**Always-on / Communication:**
- Answer directly first; context only if it changes the answer
- Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds
- Never validate an approach because the user seems confident about it
- When disagreeing, say so clearly — do not soften into a suggestion
- For exploratory questions: one recommendation, one tradeoff, 2–3 sentences
- Never say "it depends" without immediately stating what it depends on
- Explain the why behind decisions — assume the user is learning, not just executing
**Always-on / Behavior:**
- Reads, searches, exploration: proceed without asking
- Writes, edits, deletes, git operations: state what you are about to do and why in one sentence; wait for approval before proceeding
- Irreversible or shared-state operations (push, force-push, drop, publish): require explicit confirmation every time, regardless of prior context
**On-demand content index** (inline load triggers to guide agent judgment):
- Coding conventions — when writing, editing, or reviewing code
- Git conventions — when doing git operations
- Testing conventions — when writing or running tests
- Workflows / agents / prompts — read from `~/.claude/core/` when invoked
### Module 2 — `core/instructions/coding.md` (new, thin draft)
Plain markdown. On-demand. Read when writing, editing, or reviewing code.
Key rules for the thin draft:
- Automate anything repeatable — if done manually twice, it belongs in a script, hook, or pipeline step
- No comments unless the why is genuinely non-obvious — names carry meaning, git history carries context
- No defensive code at internal boundaries — validate only at system edges (user input, external APIs, git hooks)
- Prefer explicit over implicit — agents reading code must not need to infer intent from convention
- No abstractions, features, or cleanup beyond what the task requires
### Module 3 — `core/instructions/git.md` (new, thin draft)
Plain markdown. On-demand. Read when doing git operations. Includes conventional commits convention.
Key rules for the thin draft:
- Never skip hooks (`--no-verify`) — hooks are the automated QA gate; bypassing them breaks the pipeline
- Never force-push main or master
- Commit messages explain why, not what — written for both humans and changelog generators
- Never commit secrets, credentials, or environment-specific config
- Conventional commits categories: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
### Module 4 — `core/instructions/testing.md` (new, thin draft)
Plain markdown. On-demand. Read when writing or running tests.
Key rules for the thin draft:
- Prefer integration tests over mocks — mocks mask production divergence; real systems catch real failures
- Automate everything automatable — manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment
- Test observable end-state, not implementation internals — tests must survive refactoring
- No test is better than a wrong test — a passing mock that masks a real failure is actively harmful
### Module 5 — `core/instructions/global.md` (retire)
Delete this file. It is a placeholder stub with no content. The content index in `providers/claude-code/CLAUDE.md` will be updated to point to the three topic files instead. `install.sh` copies `core/` wholesale, so deletion automatically removes the deployed file on next install.
### Module 6 — `docs/` restructure
Create subdirectories by artifact type. Migrate the one existing PRD.
New structure:
```
docs/
├── prd/ ← PRDs (this PRD is the first)
├── ard/ ← Architecture Requirements Documents
├── bug/ ← Bug Briefs
├── notes/ ← Exploration Notes
├── adr/ ← Architecture Decision Records (NNNN-slug)
├── issues/ ← Issues (NNNN-slug, already correct)
└── VISION.md ← stays at root of docs/
```
Migration: `docs/prd-chunk-1.md` → `docs/prd/chunk-1.md`. No other files need moving.
### install.sh
No changes required. It copies `core/` wholesale and deploys `providers/claude-code/CLAUDE.md` verbatim. Adding new files to `core/instructions/` and deleting `global.md` takes effect automatically on next install run.
## Testing Decisions
Instruction files and CLAUDE.md content cannot be unit tested. A well-formed file is not the same as an effective file — the test is whether the agent actually follows the rule in a real session.
**Approach:** Each issue carries a short acceptance criteria checklist. After committing the issue, the developer opens a new Claude session and exercises the relevant behaviour. The issue is closed only when the behaviour is confirmed.
**What a good test looks like:**
- Trigger the scenario the rule covers (e.g. ask Claude to implement something with unnecessary complexity; expect pushback citing the rule)
- Confirm the agent's response matches the intended behaviour
- Do not test that the file was written correctly — test that the behaviour changed
**Prior art:** Chunk 1 used the same approach — manual smoke test in a new session to verify the always-on rule was in effect. Chunk 2 formalises this as per-issue acceptance criteria.
No automated tests for this chunk. Automated QA applies to tooling (scripts, hooks); behavioural QA for content is always human-executed.
## Out of Scope
- Changelog tooling (Chunk 3 follow-on to the conventional commits convention)
- Frontmatter or load-trigger hints in instruction files themselves — deferred until there is evidence agents are loading the wrong files in practice (Chunk 2 Phase 2 refinement)
- Security floor, scope discipline, tool preference in the always-on CLAUDE.md section — separate future workstream with its own grill and PRD
- Loosening the agent behavior confirmation model for automation — deferred to post Chunk 4 once skills and workflows are proven
- Additional instruction categories beyond coding, git, and testing — Phase 2 refinement, triggered by real friction
- The `docs/VISION.md` file path does not change — it stays at `docs/VISION.md`, not moved into a subdirectory
## Further Notes
- `install.sh` copies `core/` wholesale — adding or removing files in `core/instructions/` automatically affects what is deployed on the next install run. No install script changes are needed for this chunk.
- This PRD is itself the first artifact written under the new `docs/prd/` convention. The migration of `docs/prd-chunk-1.md` is a Chunk 2 deliverable, not a precondition for writing this PRD.
- The behavior confirmation model (writes require stating intent and approval) is intentionally conservative. It reflects the current context: a junior developer interacting directly with the agent. It will loosen post Chunk 4 when automated agents replace direct interaction for routine tasks.
- The inline load triggers in the content index ("when writing, editing, or reviewing code") are a lightweight substitute for frontmatter. They are noted as a known interim approach and will be revisited if agents load wrong files in practice.

31
providers/claude-code/CLAUDE.md Normal file
View File

@@ -0,0 +1,31 @@
> [!WARNING]
> **This is the global Claude Code config deployed to `~/.claude/`.** It is installed by `install.sh` and governs Claude's behavior across all projects.
>
> It is NOT the repo meta-config. That file lives at the root `CLAUDE.md` and tells Claude how to work inside this repo. Do not conflate the two.
# Always-on rules
## Communication
- Answer directly first. Give context only if it changes the answer.
- Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds.
- Never validate an approach because the user seems confident about it.
- When disagreeing, say so clearly. Do not soften disagreement into a suggestion.
- For exploratory questions: one recommendation, one tradeoff, 2–3 sentences.
- Never say "it depends" without immediately stating what it depends on.
- Explain the why behind decisions — assume the user is learning, not just executing.
## Behavior
- Reads, searches, exploration: proceed without asking.
- Writes, edits, deletes, git operations: state what you are about to do and why in one sentence, then proceed.
- Irreversible or shared-state operations (push, force-push, drop, publish): require explicit confirmation every time, regardless of prior context.
# Content index
Read these files on demand:
- **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code
- **Git conventions** (`~/.claude/core/instructions/git.md`) — when doing git operations
- **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests
- **Workflows / agents / prompts** (`~/.claude/core/`) — read from here when invoked

7
providers/claude-code/settings.json Normal file
View File

@@ -0,0 +1,7 @@
{
"theme": "dark",
"statusLine": {
"type": "command",
"command": "bash ~/.claude/statusline-command.sh"
}
}

101
providers/claude-code/statusline-command.sh Executable file
View File

@@ -0,0 +1,101 @@
#!/usr/bin/env bash
# Session cost thresholds (USD) — on a $20 subscription these signal session weight,
# not real spend. Calibrate upward if you rarely see amber.
COST_AMBER=1.50
COST_RED=3.00
input=$(cat)
# --- Raw values from Claude Code ---
working_dir=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // empty')
model_name=$(echo "$input" | jq -r '.model.display_name // empty')
context_used_pct=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // empty')
input_tokens=$(echo "$input" | jq -r '.context_window.total_input_tokens // 0')
output_tokens=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
vim_mode=$(echo "$input" | jq -r '.vim.mode // empty')
dir_name=$(basename "$working_dir")
git_branch=""
if [ -n "$working_dir" ] && git -C "$working_dir" rev-parse --is-inside-work-tree 2>/dev/null | grep -q true; then
git_branch=$(git -C "$working_dir" -c core.fsync=none symbolic-ref --short HEAD 2>/dev/null)
fi
# --- Colors ($'...' interprets \033 as actual ESC character) ---
COLOR_RESET=$'\033[0m'
COLOR_BOLD_BLUE=$'\033[1;34m' # dir — identity, always stable
COLOR_BLUE=$'\033[0;34m' # tokens — informational, no urgency
COLOR_CYAN=$'\033[0;36m' # model — configuration, always stable
COLOR_GREEN=$'\033[0;32m' # healthy / within limits
COLOR_AMBER=$'\033[0;33m' # attention / approaching a limit
COLOR_RED=$'\033[0;31m' # urgent / act now
COLOR_MAGENTA=$'\033[0;35m' # vim mode — modal state indicator
# --- Branch: red on main/master (you are on trunk — danger), green on feature branches ---
branch_color="$COLOR_GREEN"
if [[ "$git_branch" == "main" || "$git_branch" == "master" ]]; then
branch_color="$COLOR_RED"
fi
# --- Model tier: color and context thresholds both reflect cost per token.
# Opus ~$15/MTok → red label, warn at 55/75%
# Sonnet ~$3/MTok → amber label (mid-tier), warn at 65/85%
# Haiku ~$0.80/MTok → green label, can fill further at 75/90%
if [[ "$model_name" == *"Opus"* ]]; then model_color="$COLOR_RED"; CTX_AMBER=55; CTX_RED=75
elif [[ "$model_name" == *"Haiku"* ]]; then model_color="$COLOR_GREEN"; CTX_AMBER=75; CTX_RED=90
else model_color="$COLOR_AMBER"; CTX_AMBER=65; CTX_RED=85
fi
# --- Token count: cumulative session total, formatted as Xk when >= 1000 ---
total_tokens=$(( input_tokens + output_tokens ))
if [ "$total_tokens" -ge 1000 ]; then
tokens_display=$(awk "BEGIN { printf \"%.0fk\", $total_tokens / 1000 }")
else
tokens_display="$total_tokens"
fi
# --- Context color: driven by model-aware thresholds above ---
context_color="$COLOR_GREEN"
context_pct=0
if [ -n "$context_used_pct" ]; then
context_pct=$(printf '%.0f' "$context_used_pct")
[ "$context_pct" -ge "$CTX_AMBER" ] && context_color="$COLOR_AMBER"
[ "$context_pct" -ge "$CTX_RED" ] && context_color="$COLOR_RED"
fi
# --- Cost: color and display format ---
cost_color="$COLOR_GREEN"
cost_display=""
if [ -n "$cost_usd" ] && [ "$cost_usd" != "0" ]; then
cost_color=$(awk -v c="$cost_usd" -v amber="$COST_AMBER" -v red="$COST_RED" 'BEGIN {
if (c >= red) print "\033[0;31m"
else if (c >= amber) print "\033[0;33m"
else print "\033[0;32m"
}')
# Show cents (¢) below $1 for precision; dollars above
cost_display=$(awk -v c="$cost_usd" 'BEGIN {
if (c < 1.00) printf "%.0f\xC2\xA2", c * 100
else printf "$%.2f", c
}')
fi
# --- Assemble: identity (where) → config (what) → health (context → cost → tokens) ---
parts=()
[ -n "$dir_name" ] && parts+=("${COLOR_BOLD_BLUE}${dir_name}${COLOR_RESET}")
[ -n "$git_branch" ] && parts+=("${branch_color}${git_branch}${COLOR_RESET}")
[ -n "$model_name" ] && parts+=("${model_color}${model_name}${COLOR_RESET}")
[ -n "$context_used_pct" ] && parts+=("${context_color}context ${context_pct}%${COLOR_RESET}")
[ -n "$cost_display" ] && parts+=("${cost_color}${cost_display}${COLOR_RESET}")
[ "$total_tokens" -gt 0 ] && parts+=("${COLOR_BLUE}${tokens_display} tokens${COLOR_RESET}")
[ -n "$vim_mode" ] && parts+=("${COLOR_MAGENTA}${vim_mode}${COLOR_RESET}")
# --- Join with ' · ' separator and print ---
output=""
for part in "${parts[@]}"; do
[ -z "$output" ] && output="$part" || output="${output} · ${part}"
done
printf '%s' "$output"

25
scripts/deploy-manifest.sh Normal file
View File

@@ -0,0 +1,25 @@
#!/usr/bin/env bash
# Deployment manifest — sourced by install.sh and sync.sh (Chunk 6).
# All paths: src relative to REPO_ROOT, dest relative to HOME.
# Format: "src:dest"
# Individual files — copied verbatim
DEPLOY_FILES=(
"providers/claude-code/CLAUDE.md:.claude/CLAUDE.md"
"providers/claude-code/settings.json:.claude/settings.json"
)
# Files that also need the executable bit set
DEPLOY_EXECUTABLES=(
"providers/claude-code/statusline-command.sh:.claude/statusline-command.sh"
)
# Directories — destination is fully replaced on each deploy (rm -rf + cp -r)
DEPLOY_DIRS=(
"core:.claude/core"
)
# Empty directories to create if absent
DEPLOY_EMPTY_DIRS=(
".agents/skills"
)

44
scripts/install.sh Executable file
View File

@@ -0,0 +1,44 @@
#!/usr/bin/env bash
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
# shellcheck source=deploy-manifest.sh
source "$REPO_ROOT/scripts/deploy-manifest.sh"
echo "Installing from $REPO_ROOT..."
for entry in "${DEPLOY_FILES[@]}"; do
dest="$HOME/${entry##*:}"
mkdir -p "$(dirname "$dest")"
cp "$REPO_ROOT/${entry%%:*}" "$dest"
done
for entry in "${DEPLOY_EXECUTABLES[@]}"; do
dest="$HOME/${entry##*:}"
mkdir -p "$(dirname "$dest")"
cp "$REPO_ROOT/${entry%%:*}" "$dest"
chmod +x "$dest"
done
for entry in "${DEPLOY_DIRS[@]}"; do
dest="$HOME/${entry##*:}"
rm -rf "$dest"
mkdir -p "$dest"
cp -r "$REPO_ROOT/${entry%%:*}/." "$dest/"
done
for dir in "${DEPLOY_EMPTY_DIRS[@]}"; do
mkdir -p "$HOME/$dir"
done
echo ""
echo "Deployed:"
for entry in "${DEPLOY_FILES[@]}" "${DEPLOY_EXECUTABLES[@]}"; do
echo " ~/${entry##*:}"
done
for entry in "${DEPLOY_DIRS[@]}"; do
echo " ~/${entry##*:}/"
done
for dir in "${DEPLOY_EMPTY_DIRS[@]}"; do
echo " ~/$dir/ (directory created)"
done

77
skills-lock.json Normal file
View File

@@ -0,0 +1,77 @@
{
"version": 1,
"skills": {
"caveman": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/productivity/caveman/SKILL.md",
"computedHash": "934433479903febc585bf6deb5f0cebc63137e3f86b7babe0aab1ecb94d6d7a4"
},
"diagnose": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/diagnose/SKILL.md",
"computedHash": "15939a26f86edec2d4862042b8564e5a062cb81d04e047a0cea6305c8830b5f5"
},
"grill-me": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/productivity/grill-me/SKILL.md",
"computedHash": "784f0dbb7403b0f00324bce9a112f715342777a0daee7bbb7385f9c6f0a170ea"
},
"grill-with-docs": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/grill-with-docs/SKILL.md",
"computedHash": "31a5b1ae116558bf7d3f633f442835f54bd7645923d4f45c7823e52a97317666"
},
"improve-codebase-architecture": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/improve-codebase-architecture/SKILL.md",
"computedHash": "c77b86b4332919499608f9af1880074e1fec65a59b95c70c27a9f39cd137865e"
},
"prototype": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/prototype/SKILL.md",
"computedHash": "aa9d68879fb51af13d47247b5fb73474324e38985ead454e6ea85b64344b7485"
},
"tdd": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/tdd/SKILL.md",
"computedHash": "15a7b5e36383ebadb2dec5e586679e55e9663d292da418926b8da6fc0ef27d84"
},
"to-issues": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/to-issues/SKILL.md",
"computedHash": "47f648f3414848ccfc62cb41d2828b7e575fb5e7cbd6c4bdf630c063b5dc5e82"
},
"to-prd": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/to-prd/SKILL.md",
"computedHash": "6d741474efd4bc3db55fabc2722ed78ca9c374cabcb6212936d79d4fd4a30fcb"
},
"triage": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/triage/SKILL.md",
"computedHash": "2b6efb6da12d92551772fcc04acf331f4e0e6f7bd9d4cb23ce0b301e0b128feb"
},
"write-a-skill": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/productivity/write-a-skill/SKILL.md",
"computedHash": "b44d8aab2ead83c716e01af4c9a24ccc4575ce70ad58ec4f1749fb88c9cc82ba"
},
"zoom-out": {
"source": "mattpocock/skills",
"sourceType": "github",
"skillPath": "skills/engineering/zoom-out/SKILL.md",
"computedHash": "8357aeaece3b709c442eab67e64b86844e05e2f1ea95b109565eba50b6def36e"
}
}
}

224
tests/test-chunk2.sh Executable file
View File

@@ -0,0 +1,224 @@
#!/usr/bin/env bash
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PASS=0
FAIL=0
pass() { echo " PASS: $1"; PASS=$((PASS + 1)); }
fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); }
# Returns 0 if pattern found in file
contains() { grep -qE "$1" "$2" 2>/dev/null; }
# ─── 0004: providers/claude-code/CLAUDE.md rewrite ───────────────────────────
#
# Automated: structure and distinctive concepts only.
# Behavioral tests (does the agent actually follow the rules?) must be run
# manually in a fresh Claude session — see MANUAL TEST PLAN at end of file.
echo "--- 0004: CLAUDE.md rewrite ---"
CLAUDE="$REPO_ROOT/providers/claude-code/CLAUDE.md"
[[ -f "$CLAUDE" ]] \
&& pass "CLAUDE.md exists" \
|| { fail "CLAUDE.md missing"; }
# Communication rules — check for distinctive, stable concepts
contains "directly" "$CLAUDE" \
&& pass "communication: answer-directly rule present" \
|| fail "communication: answer-directly rule missing"
contains "[Cc]hallenge" "$CLAUDE" \
&& pass "communication: challenge-bad-ideas rule present" \
|| fail "communication: challenge-bad-ideas rule missing"
contains "it depends" "$CLAUDE" \
&& pass "communication: no-bare-it-depends rule present" \
|| fail "communication: no-bare-it-depends rule missing"
contains "[Ss]often" "$CLAUDE" \
&& pass "communication: no-softening rule present" \
|| fail "communication: no-softening rule missing"
# Behavior rules
contains "[Ii]rreversible" "$CLAUDE" \
&& pass "behavior: irreversible-ops confirmation rule present" \
|| fail "behavior: irreversible-ops confirmation rule missing"
# Content index — must reference each on-demand file
contains "coding" "$CLAUDE" \
&& pass "content index: coding conventions trigger present" \
|| fail "content index: coding conventions trigger missing"
contains "git" "$CLAUDE" \
&& pass "content index: git conventions trigger present" \
|| fail "content index: git conventions trigger missing"
contains "testing" "$CLAUDE" \
&& pass "content index: testing conventions trigger present" \
|| fail "content index: testing conventions trigger missing"
# global.md must be retired — no longer referenced in content index
! contains "global\.md" "$CLAUDE" \
&& pass "content index: global.md reference removed" \
|| fail "content index: global.md still referenced"
# global.md file must be deleted
[[ ! -f "$REPO_ROOT/core/instructions/global.md" ]] \
&& pass "core/instructions/global.md deleted" \
|| fail "core/instructions/global.md still exists"
echo ""
# ─── 0005: core/instructions/coding.md ───────────────────────────────────────
echo "--- 0005: coding.md ---"
CODING="$REPO_ROOT/core/instructions/coding.md"
[[ -f "$CODING" ]] \
&& pass "coding.md exists" \
|| fail "coding.md missing"
contains "[Aa]utomat" "$CODING" \
&& pass "rule: automate repeatable things" \
|| fail "rule: automate repeatable things missing"
contains "[Cc]omment" "$CODING" \
&& pass "rule: no comments unless why is non-obvious" \
|| fail "rule: comment rule missing"
contains "[Dd]efensive" "$CODING" \
&& pass "rule: no defensive code at internal boundaries" \
|| fail "rule: defensive code rule missing"
contains "[Ee]xplicit" "$CODING" \
&& pass "rule: prefer explicit over implicit" \
|| fail "rule: explicit over implicit missing"
contains "[Aa]bstraction" "$CODING" \
&& pass "rule: no abstractions beyond task" \
|| fail "rule: no-abstractions rule missing"
echo ""
# ─── 0006: core/instructions/git.md ──────────────────────────────────────────
echo "--- 0006: git.md ---"
GIT="$REPO_ROOT/core/instructions/git.md"
[[ -f "$GIT" ]] \
&& pass "git.md exists" \
|| fail "git.md missing"
contains "\-\-no\-verify" "$GIT" \
&& pass "rule: never skip hooks (--no-verify)" \
|| fail "rule: --no-verify rule missing"
contains "[Ff]orce.push" "$GIT" \
&& pass "rule: never force-push main" \
|| fail "rule: force-push rule missing"
contains "feat:" "$GIT" \
&& pass "rule: conventional commits vocabulary present" \
|| fail "rule: conventional commits vocabulary missing"
contains "[Ss]ecret" "$GIT" \
&& pass "rule: never commit secrets" \
|| fail "rule: secrets rule missing"
contains "[Ww]hy" "$GIT" \
&& pass "rule: commit messages explain why" \
|| fail "rule: why-not-what rule missing"
echo ""
# ─── 0007: core/instructions/testing.md ──────────────────────────────────────
echo "--- 0007: testing.md ---"
TESTING="$REPO_ROOT/core/instructions/testing.md"
[[ -f "$TESTING" ]] \
&& pass "testing.md exists" \
|| fail "testing.md missing"
contains "[Ii]ntegration" "$TESTING" \
&& pass "rule: prefer integration tests" \
|| fail "rule: integration test preference missing"
contains "[Mm]ock" "$TESTING" \
&& pass "rule: mocks addressed" \
|| fail "rule: mock guidance missing"
contains "[Rr]efactor" "$TESTING" \
&& pass "rule: tests survive refactoring" \
|| fail "rule: refactor-survival rule missing"
contains "[Aa]utomat" "$TESTING" \
&& pass "rule: automate everything automatable" \
|| fail "rule: automation rule missing"
echo ""
# ─── 0008: docs/ restructure ─────────────────────────────────────────────────
echo "--- 0008: docs/ restructure ---"
for dir in prd ard bug notes adr; do
[[ -d "$REPO_ROOT/docs/$dir" ]] \
&& pass "docs/$dir/ exists" \
|| fail "docs/$dir/ missing"
done
[[ -f "$REPO_ROOT/docs/prd/chunk-1.md" ]] \
&& pass "docs/prd/chunk-1.md exists (migrated)" \
|| fail "docs/prd/chunk-1.md missing"
[[ ! -f "$REPO_ROOT/docs/prd-chunk-1.md" ]] \
&& pass "docs/prd-chunk-1.md removed from docs root" \
|| fail "docs/prd-chunk-1.md still at docs root"
[[ -f "$REPO_ROOT/docs/VISION.md" ]] \
&& pass "docs/VISION.md unchanged" \
|| fail "docs/VISION.md missing"
[[ -d "$REPO_ROOT/docs/issues" ]] \
&& pass "docs/issues/ unchanged" \
|| fail "docs/issues/ missing"
echo ""
echo "Results: $PASS passed, $FAIL failed"
echo ""
echo "─────────────────────────────────────────────────────"
echo "MANUAL TEST PLAN (run in a fresh Claude session)"
echo "─────────────────────────────────────────────────────"
echo ""
echo "0004 — CLAUDE.md behavior"
echo " 1. Ask an exploratory design question."
echo " Expect: 1 recommendation + 1 tradeoff in 2-3 sentences."
echo " 2. Propose a clearly overengineered approach."
echo " Expect: agent names the problem, does not implement it."
echo " 3. Ask the agent to edit a file."
echo " Expect: agent states intent in one sentence before proceeding."
echo " 4. Ask the agent to push a commit."
echo " Expect: agent requires explicit confirmation."
echo ""
echo "0005 — coding.md behavior"
echo " 5. Ask for something with unnecessary complexity."
echo " Expect: agent pushes back and names the rule being violated."
echo ""
echo "0006 — git.md behavior"
echo " 6. Ask agent to commit a change."
echo " Expect: conventional commits format used unprompted."
echo " 7. Ask agent to skip a pre-commit hook."
echo " Expect: agent refuses."
echo ""
echo "0007 — testing.md behavior"
echo " 8. Ask agent to write a test requiring a mocked database."
echo " Expect: agent pushes back and proposes an integration test."
echo ""
[[ $FAIL -eq 0 ]]

71
tests/test-install.sh Executable file
View File

@@ -0,0 +1,71 @@
#!/usr/bin/env bash
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PASS=0
FAIL=0
pass() { echo " PASS: $1"; PASS=$((PASS + 1)); }
fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); }
TEMP_HOME="$(mktemp -d)"
trap 'rm -rf "$TEMP_HOME"' EXIT
echo "Running install.sh..."
HOME="$TEMP_HOME" bash "$REPO_ROOT/scripts/install.sh" > /dev/null
echo ""
echo "--- providers/claude-code/ → ~/.claude/ ---"
while IFS= read -r -d '' src; do
rel="${src#"$REPO_ROOT/providers/claude-code/"}"
dest="$TEMP_HOME/.claude/$rel"
if diff -q "$src" "$dest" > /dev/null 2>&1; then
pass "$rel deployed and matches source"
else
fail "$rel — missing or differs from source"
fi
done < <(find "$REPO_ROOT/providers/claude-code" -type f -print0)
echo ""
echo "--- core/ → ~/.claude/core/ ---"
while IFS= read -r -d '' src; do
rel="${src#"$REPO_ROOT/core/"}"
dest="$TEMP_HOME/.claude/core/$rel"
if diff -q "$src" "$dest" > /dev/null 2>&1; then
pass "$rel deployed and matches source"
else
fail "$rel — missing or differs from source"
fi
done < <(find "$REPO_ROOT/core" -type f -print0)
echo ""
echo "--- no orphaned files in core/ ---"
while IFS= read -r -d '' deployed; do
rel="${deployed#"$TEMP_HOME/.claude/core/"}"
src="$REPO_ROOT/core/$rel"
if [[ -f "$src" ]]; then
pass "core/$rel has a source file"
else
fail "core/$rel is orphaned — deleted from source but still deployed"
fi
done < <(find "$TEMP_HOME/.claude/core" -type f -print0)
echo ""
echo "--- directories ---"
if [[ -d "$TEMP_HOME/.agents/skills" ]]; then
pass "~/.agents/skills/ created"
else
fail "~/.agents/skills/ not found"
fi
echo ""
echo "--- idempotency ---"
if HOME="$TEMP_HOME" bash "$REPO_ROOT/scripts/install.sh" > /dev/null 2>&1; then
pass "second run exits zero"
else
fail "second run failed"
fi
echo ""
echo "Results: $PASS passed, $FAIL failed"
[[ $FAIL -eq 0 ]]

72
tests/test-statusline.sh Executable file
View File

@@ -0,0 +1,72 @@
#!/usr/bin/env bash
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
SCRIPT="$REPO_ROOT/providers/claude-code/statusline-command.sh"
PASS=0
FAIL=0
pass() { echo " PASS: $1"; PASS=$((PASS + 1)); }
fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); }
# Strip ANSI escape codes so assertions work on plain text
strip_ansi() { sed 's/\x1b\[[0-9;]*m//g'; }
# Pipe JSON to the script and return stripped output
run() { echo "$1" | bash "$SCRIPT" | strip_ansi; }
# Baseline input covering all segments
FULL='{"workspace":{"current_dir":"/home/user/myproject"},"model":{"display_name":"Sonnet 4.6"},"context_window":{"used_percentage":20,"total_input_tokens":15000,"total_output_tokens":5000},"cost":{"total_cost_usd":0.25}}'
echo "--- assembly ---"
out=$(run "$FULL")
echo "$out" | grep -q "myproject" && pass "shows basename of working directory" || fail "dir missing — got: $out"
echo "$out" | grep -q " · " && pass "segments joined with ' · '" || fail "separator missing — got: $out"
echo "$out" | grep -q "Sonnet 4.6" && pass "shows model name" || fail "model name missing — got: $out"
echo "$out" | grep -q "context 20%" && pass "shows context % with 'context' label" || fail "context label wrong — got: $out"
echo ""
echo "--- token formatting ---"
# 15k + 5k = 20k → shown as "20k tokens"
echo "$out" | grep -q "20k tokens" && pass "formats total tokens as Xk when >= 1000" || fail "Xk format wrong — got: $out"
# Sub-1000 total: 500 + 300 = 800 → shown as "800 tokens"
LOW='{"workspace":{"current_dir":"/x"},"context_window":{"total_input_tokens":500,"total_output_tokens":300}}'
out_low=$(run "$LOW")
echo "$out_low" | grep -q "800 tokens" && pass "shows raw count when total tokens < 1000" || fail "sub-1000 format wrong — got: $out_low"
echo ""
echo "--- cost formatting ---"
# 0.25 → 25¢
echo "$out" | grep -q "25¢" && pass "formats sub-dollar cost as cents (¢)" || fail "cents format wrong — got: $out"
# 1.71 → $1.71
DOLLAR='{"workspace":{"current_dir":"/x"},"cost":{"total_cost_usd":1.71},"context_window":{"total_input_tokens":0,"total_output_tokens":0}}'
out_dollar=$(run "$DOLLAR")
echo "$out_dollar" | grep -qF '$1.71' && pass "formats dollar-plus cost as \$X.XX" || fail "dollar format wrong — got: $out_dollar"
echo ""
echo "--- missing fields omitted ---"
# No cost field → no ¢ or $ in output
NO_COST='{"workspace":{"current_dir":"/x"},"context_window":{"total_input_tokens":0,"total_output_tokens":0}}'
out_nocost=$(run "$NO_COST")
! echo "$out_nocost" | grep -qE '[¢$]' && pass "omits cost segment when cost absent" || fail "cost shown unexpectedly — got: $out_nocost"
# Zero tokens → no token segment
ZERO_TOK='{"workspace":{"current_dir":"/x"},"context_window":{"total_input_tokens":0,"total_output_tokens":0}}'
out_zerotok=$(run "$ZERO_TOK")
! echo "$out_zerotok" | grep -q "tokens" && pass "omits token segment when total is zero" || fail "token segment shown unexpectedly — got: $out_zerotok"
echo ""
echo "--- executable bit ---"
[[ -x "$SCRIPT" ]] && pass "statusline-command.sh is executable" || fail "statusline-command.sh is not executable"
echo ""
echo "Results: $PASS passed, $FAIL failed"
[[ $FAIL -eq 0 ]]