Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions .claude/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,16 +51,16 @@ documents and is **re-entrant** (re-run to refine, not restart).

### Phase commands

| Command | Model | Question it answers | Owns |
|---|---|---|---|
| `/init` | sonnet | What files do we need? | `CLAUDE.md`, `docs/` skeleton, `README.md` stub, `.gitignore` |
| `/explore` | opus | What problem, for whom, why? | `docs/PROJECT.md` |
| `/design` | opus | How do we build it? | `docs/ARCHITECTURE.md`, `docs/SPEC.md` |
| `/plan` | opus | In what order, as what tasks? | `docs/STORIES.md`, `docs/PLAN.md` |
| `/spec` | sonnet | Pending BDD specs from stories | spec files (via `bdd-specs` skill) |
| `/build-loop` | sonnet | Build it. | the code + git history |
| `/document` | sonnet | Do the docs still match reality? | `README.md`, `docs/ARCHITECTURE.md` prose, `docs/MEMORY.md` |
| `/quick-fix` | sonnet | Trivial fix on the current branch β€” no plan, no stories. | the code |
| Command | Question it answers | Owns |
|---|---|---|
| `/init` | What files do we need? | `CLAUDE.md`, `docs/` skeleton, `README.md` stub, `.gitignore` |
| `/explore` | What problem, for whom, why? | `docs/PROJECT.md` |
| `/design` | How do we build it? | `docs/ARCHITECTURE.md`, `docs/SPEC.md` |
| `/plan` | In what order, as what tasks? | `docs/STORIES.md`, `docs/PLAN.md` |
| `/spec` | Pending BDD specs from stories | spec files (via `bdd-specs` skill) |
| `/build-loop` | Build it. | the code + git history |
| `/document` | Do the docs still match reality? | `README.md`, `docs/ARCHITECTURE.md` prose, `docs/MEMORY.md` |
| `/quick-fix` | Trivial fix on the current branch β€” no plan, no stories. | the code |

`docs/MEMORY.md` is the project's decision log β€” every phase *appends* dated
entries; `/document` curates it. It is distinct from the `~/.claude` memory
Expand All @@ -76,10 +76,10 @@ Small commands that defer to the `git-workflow` skill β€” direct, detailed, no
ceremony. Plain git only: PRs and issues are opened in the Gitea web UI
(the skill ships copy-paste body templates for both).

| Command | Model | Purpose |
| Command | Purpose |
|---|---|---|
| `/git-commit` | haiku | Stage and commit using Conventional Commits; branch-or-trunk by size. |
| `/git-merge` | haiku | Merge current branch into `main` safely β€” checks, confirms, merges. |
| `/git-commit` | Stage and commit using Conventional Commits; branch-or-trunk by size. |
| `/git-merge` | Merge current branch into `main` safely β€” checks, confirms, merges. |

## Agents

Expand All @@ -88,7 +88,7 @@ ceremony. Plain git only: PRs and issues are opened in the Gitea web UI
| Agent | Model | Tools | Role |
|---|---|---|---|
| `builder` | sonnet | Read, Write, Edit, Glob, Grep, Bash, Skill | Implements one PLAN.md task. Stays in its files. Never commits unless told. |
| `reviewer` | opus | Read, Glob, Grep, Bash, Skill (**no** Write/Edit) | Read-only gate. Returns `PASS` or `FAIL` with findings. A gate that can fix itself isn't a gate. |
| `reviewer` | inherit | Read, Glob, Grep, Bash, Skill (**no** Write/Edit) | Read-only gate. Returns `PASS` or `FAIL` with findings. A gate that can fix itself isn't a gate. |

The reviewer is intentionally stronger than the builder.

Expand All @@ -114,7 +114,7 @@ confirm a clean git working tree. Stop and report if any of these fail.
β”‚ reports a diff. Does NOT commit. β”‚
β”‚ β”‚ β”‚
β”‚ β–Ό β”‚
β”‚ 2. REVIEW β†’ reviewer subagent (opus) β”‚
β”‚ 2. REVIEW β†’ reviewer subagent (inherit) β”‚
β”‚ read-only; runs the matching security β”‚
β”‚ skill (security-api / security-web) + β”‚
β”‚ simplify; returns PASS or FAIL. β”‚
Expand Down Expand Up @@ -195,8 +195,10 @@ controls when it triggers, plus optional `references/` and `templates/`.
preserves completed work (e.g. `/plan` never drops `- [x]` tasks).
- **Stop, don't guess.** A phase missing its input (no PLAN.md, a SPEC full of
`TODO`) stops and points back to the owning command instead of inventing.
- **Model choice is deliberate.** Heavy thinking β†’ opus (`/explore`, `/design`,
`/plan`, reviewer). Execution β†’ sonnet. Quick git plumbing β†’ haiku.
- **Commands inherit the session model.** No command pins a model, so the
phases run on whatever you launched Claude Code with. The `builder` agent
is pinned to the `sonnet` alias (execution); the `reviewer` inherits the
session model so the gate is never weaker than the session.

## Usage

Expand Down
2 changes: 1 addition & 1 deletion .claude/agents/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: reviewer
description: Read-only code + security gate for a single built task (C#/.NET first-class; TypeScript for UI code). Returns PASS or FAIL with findings. Dispatched by /build-loop.
tools: Read, Glob, Grep, Bash, Skill
model: opus
model: inherit
---

You are the gate between a built task and git history. You review the builder's
Expand Down
5 changes: 2 additions & 3 deletions .claude/commands/build-loop.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Drive a PLAN.md to completion task-by-task β€” builder builds, reviewer gates, commit only on pass.
argument-hint: [path-to-PLAN.md]
model: claude-sonnet-4-6
---

# build-loop
Expand Down Expand Up @@ -34,15 +33,15 @@ code or review it yourself β€” you dispatch and gate.
For each task still unchecked (`- [ ]`), in order, top to bottom:

1. **Build.** Dispatch a `builder` subagent (Agent tool,
`subagent_type: builder`, model **sonnet**). Give it: the exact task text,
`subagent_type: builder`, model **sonnet** (alias; tracks the current generation)). Give it: the exact task text,
the relevant section of PLAN.md, the files it owns, and an instruction to
invoke the project's language + DB skills (`csharp-best-practices` for C#,
`typescript-best-practices` for TS, `postgres-dba` for schema work) and
run the existing specs (`dotnet test` / `bun test` / project test command)
before reporting back. The builder **does not commit**.

2. **Review.** Dispatch a `reviewer` subagent (Agent tool,
`subagent_type: reviewer`, model **opus** β€” reviewer must be β‰₯ builder).
`subagent_type: reviewer`, model **inherit** β€” the reviewer runs on the session model, so it is always β‰₯ the builder).
It invokes the matching security skill (`security-api` for backend code,
`security-web` for UI code) and `simplify`, reads the builder's diff, and
returns a verdict: `PASS` or `FAIL` with specific findings.
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/design.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Interview the solution β€” architecture, schema, platform. Owns ARCHITECTURE.md + SPEC.md.
argument-hint: [area to focus, optional]
model: claude-opus-4-7
---

# design
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/document.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Reconcile docs with reality β€” README, DEPLOYMENT values, ARCHITECTURE prose, MEMORY log. Run anytime.
argument-hint: [area to focus, optional]
model: claude-sonnet-4-6
---

# document
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/explore.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Interview the idea β€” problem, who, why, scope. Owns docs/PROJECT.md.
argument-hint: [one-line idea]
model: claude-opus-4-7
---

# explore
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/git-commit.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Stage and commit current changes using Conventional Commits, branch-or-trunk by size. Uses the `git-workflow` skill.
argument-hint: [optional summary or scope hint]
model: claude-haiku-4-5-20251001
---

# commit
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/init.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Scaffold the project files I like β€” CLAUDE.md and the /docs skeleton.
argument-hint: [project name]
model: claude-sonnet-4-6
---

# init
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/plan.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Slice SPEC into stories and an ordered task DAG. Owns STORIES.md + PLAN.md.
argument-hint: [scope to plan, optional]
model: claude-opus-4-7
---

# plan
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/quick-fix.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Make a small, obvious fix directly on the current branch. No sprint, no PLAN, no stories.
argument-hint: <describe the fix>
model: claude-sonnet-4-6
---

# quick-fix
Expand Down
1 change: 0 additions & 1 deletion .claude/commands/spec.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
description: Generate executable BDD specs from STORIES.md via the bdd-specs skill. Stories-first, idempotent, pending by default.
argument-hint: [scope or story id, optional]
model: claude-sonnet-4-6
---

# spec
Expand Down
9 changes: 9 additions & 0 deletions .claude/settings.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,15 @@
"command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.env|*.env.*) echo \"refuse: $f is an env file\" >&2; exit 2;; esac; exit 0"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "c=$(jq -r '.tool_input.command // empty'); case \"$c\" in *'git tag'*-l*|*'git tag'*--list*|*'git tag --contains'*) exit 0;; *'gh pr merge'*|*'gh release create'*|*'git tag'*|*'git push'*--tags*|*'git push'*' main'*|*'git push'*':main'*|*'git push'*'HEAD:refs/heads/main'*) echo 'refuse: merge / tag / release / push to main needs Dean'\\''s per-action consent (MERGE RULE, gh-#751). Hand him the command instead.' >&2; exit 2;; esac; exit 0"
}
]
}
],
"Stop": []
Expand Down
Loading