Carmack-Council

# The Carmack Council

An ultra-opinionated, multi-agent development framework for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Founded on my personal belief that off-the-shelf Claude Code skills often lead to average results, and stack specific skills based on real world, battle tested engineering principles lead to awesomeness. 

## But why The Carmack Council?

Named after GOAT engineer and all around legend John Carmack, and built on his engineering philosophy: simplicity over cleverness, concrete over abstract, economic over aesthetic.

This skill was built for my own use with no initial intention to actually release it, and as such is tuned to my preferred greenfield stack:

- Next.js App Router
- tRPC
- Prisma
- Neon
- Clerk
- CSS Modules + BEM
- Railway

I have reasons (ranging from solid to near arbitrary) for picking all of these. This is what I used pre-AI because it let me ship fast with decent performance, generous free tiers and good scalability.

Some people hate this stack or elements of it. I'm OK with that. The point is the council concept — adapting it to your stack is straightforward.

The council is chaired by John Carmack and includes 10 domain experts:

| Expert | Domain | Reference Doc | Link |
|--------|--------|--------------|------|
| Troy Hunt | Security | `security.md` | https://www.troyhunt.com/ |
| Martin Fowler | Refactoring / Structure | `refactoring.md` | https://martinfowler.com/ |
| Kent C. Dodds | Frontend Quality | `quality-frontend.md` | https://kentcdodds.com/ |
| Matteo Collina | Backend Quality | `quality-backend.md` | https://nodeland.dev/ |
| Brandur Leach | Postgres Quality | `quality-postgres.md` | https://brandur.org/ |
| Vercel Performance | Performance | External rules | https://vercel.com/ |
| Simon Willison | LLM Pipeline Quality | `quality-llm.md` | https://simonwillison.net/ |
| Karri Saarinen | UI Quality | `quality-ui.md` | https://karrisaarinen.com/ |
| Vitaly Friedman | UX Quality | `quality-ux.md` | https://www.smashingmagazine.com/author/vitaly-friedman/ |
| Kent Beck | Test Quality | `quality-testing.md` | https://kentbeck.com/ |

Every plan, implementation decision and review finding is grounded in the publicly shared expertise of domain leaders who build and design world-class software. Not "best practices." Not docs examples. The strong opinions of engineers and designers whose work is next level.

They're all total ballers. Check out their sites, buy their books, use their products, enroll in their courses.



## The Workflow

```
/spec-writer  →  /council-plan  →  /council-implement  →  /council-review
    ↑                                                           |
    └───────────────────────────────────────────────────────────┘
```

1. **Spec Writer** — Produces structured specifications with Job Stories, Gherkin acceptance criteria, and three-tier boundaries. Adaptive complexity: small changes get 200 words, features get 500–800, products get up to 2,000.

2. **Council Plan** — Carmack chairs 10 domain experts who independently advise on how to build the feature. Interactive discovery with the developer, then parallel subagent dispatch. Produces a sequenced, dependency-ordered implementation plan with no code.

3. **Council Implement** — Executes the plan task by task. Loads each expert's reference document before implementing their task. Verifies (type check, lint, test) after every task. Produces an implementation log.

4. **Council Review** — Ten domain experts independently review the code in parallel, each in their own context window. The Chair merges, deduplicates, and prioritises into P1/P2/P3 findings. Automated checks (tsc, lint, vitest) run first. New conventions surfaced during review are flagged for the user to accept into conventions.md

5. **Test Architect** — Kent Beck's testing philosophy made operational. Three modes: audit existing tests against Beck's 11 principles and surface theatre (mock theatre, assertion-free tests, missing happy paths), specify tests with a traceability matrix mapping every acceptance criterion to a test layer, or fix identified issues directly. Standalone — usable at any point in the workflow.


### The Vercel Performance Expert
The Vercel Performance subagent references ~/.claude/skills/react-best-practices/rules/ — this is a separate Vercel skill, not part of this repo. If you don't have it installed, the Vercel subagent will fail gracefully (no recommendations returned), and the other nine experts will work fine. The review and plan will note "Vercel — no findings" in the breakdown, which is accurate if slightly misleading. you can also just delete the Vercel expert from the Skill.md file

If you want the full 10-expert experience, install the [Vercel React Best Practices](https://github.com/vercel-labs/agent-skills) skill separately. If you don't care about Next.js performance auditing, ignore this entirely — the council works without it.


## Installation

### Quick install

Download individual `.skill` packages from the [`dist/`](dist/) directory:

- [`council-review.skill`](dist/council-review.skill) — Code review with 10 parallel experts
- [`council-plan.skill`](dist/council-plan.skill) — Feature planning with 10 parallel experts
- [`council-implement.skill`](dist/council-implement.skill) — Plan execution with expert-guided implementation
- [`spec-writer.skill`](dist/spec-writer.skill) — Structured specification generation
- [`test-architect.skill`](dist/test-architect.skill) — Test auditing, specification, and fix powered by Beck's principles

Each `.skill` file is a self-contained zip archive with the SKILL.md and all required reference documents bundled inside. Install via Claude Code's skill installation.

### From source

```bash
git clone https://github.com/SamJHudson01/Carmack-Council.git
cd carmack-council
chmod +x scripts/build.sh
./scripts/build.sh
```

This reads each skill's `manifest.json`, copies the declared references from the shared `references/` directory into each skill folder, validates, packages into `.skill` files in `dist/`, and cleans up.

## Repo Structure

```
carmack-council/
├── README.md
├── STACK.md              # Every stack-specific assumption, listed
├── LICENSE               # MIT
├── references/           # Single source of truth for all reference docs
│   ├── security.md
│   ├── quality-backend.md
│   ├── quality-frontend.md
│   ├── quality-postgres.md
│   ├── quality-testing.md
│   ├── quality-llm.md
│   ├── quality-ui.md
│   ├── quality-ux.md
│   ├── refactoring.md
│   └── spec-writer/      # Spec-writer-specific references
│       ├── anti-patterns.md
│       ├── acceptance-criteria-guide.md
│       ├── feature-spec.md
│       ├── product-spec.md
│       ├── small-change.md
│       └── boundary-examples.md
├── skills/
│   ├── council-review/
│   │   ├── SKILL.md
│   │   └── manifest.json
│   ├── council-plan/
│   │   ├── SKILL.md
│   │   └── manifest.json
│   ├── council-implement/
│   │   ├── SKILL.md
│   │   └── manifest.json
│   ├── spec-writer/
│   │   ├── SKILL.md
│   │   └── manifest.json
│   └── test-architect/
│       ├── SKILL.md
│       └── manifest.json
├── scripts/
│   ├── build.sh
│   ├── package_skill.py
│   └── quick_validate.py
└── dist/                 # Pre-built .skill packages
    ├── council-review.skill
    ├── council-plan.skill
    ├── council-implement.skill
    ├── spec-writer.skill
    └── test-architect.skill
```

## Forking for Your Stack

These skills are opinionated for a specific stack (Next.js App Router / tRPC / Prisma / Neon / Clerk / CSS Modules + BEM / Railway). **We ship opinionated — you fork and adapt.**

See [`STACK.md`](STACK.md) for:
- Every stack-specific assumption across all skills and references
- Which files contain each assumption
- A step-by-step guide for adapting to your stack

General approach:
1. Update the Stack Context sections in each SKILL.md
2. Update the subagent prompt templates that reference specific technologie

[truncated…]