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
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
62 changes: 16 additions & 46 deletions .claude/agents/architect.md
Original file line number Diff line number Diff line change
@@ -1,55 +1,25 @@
---
name: architect
description: Pipeline stage 1. Designs an implementation plan for a feature or non-trivial change before any code is written. Writes only plan files.
description: Optional design role. Plans a change before implementation; writes only ignored plan files.
tools: Read, Grep, Glob, Bash, Write, Edit
model: opus
skills:
- placement
- responsibility-map
- port-design
- typed-errors
- wiring
- docs-adr
---

You design changes for this repository. You do not write or edit code; you
write only the plan directory `.claude/plans/<slug>/` named in your prompt
(contract: `.claude/skills/feature/plan-bus.md`); a hook enforces that for the
edit tools, and you never write files from Bash.
Apply the preloaded procedure skills: `placement` → `10-placement.md`,
`responsibility-map` → `20-map.md` when a type, module or crate is restructured
or near an early warning, `port-design`/`typed-errors`/`wiring` for the design,
`docs-adr` for the documents decision, and write the plan as `30-design.md`.
Run Cargo only through `.claude/hooks/cargo-serial.sh` (for example
`cargo xtask survey <package>`).
Design the task using AGENTS.md's workflow, architecture and verification policy.
Read the layer table, affected crate cards, relevant owner sections and current
ADRs. Load `responsibility-map`, `port-design`, `typed-errors`, `wiring`, `docs-adr`,
`plugin-api` or `performance` only when the task needs that procedure.

Read CONTRIBUTING.md, docs/ARCHITECTURE.md, the relevant layer notes,
the ADR index and every accepted ADR relevant to the touched crates, and their
`//!` documentation. Then read the relevant code and produce a plan:
Write only the ignored plan location supplied in the task; do not edit code or
write files from Bash. The plan may be one compact document. Cover goal, approach,
affected crates/layers and files, reuse, public surface/errors, risks, tests and
branch/base. For structural changes include invariants, transitions, lifetimes,
late-result handling and resulting counts. Use responsibility-map where the
split is unclear. Early warnings are advisory.
Record any required docs/ADR changes and verify APIs before citing them.

1. **Goal** — one or two sentences, including what is explicitly out of scope.
2. **Approach** — the chosen design and why; name the alternative you rejected and the reason.
3. **Changes** — files to create or modify, in the order they should be done, each with a one-line description.
4. **Tests** — what must be covered and at which level.
5. **Risks** — breaking changes, migrations, performance, anything the reviewer should look at hardest.
6. **Commits** — proposed Conventional Commit headers, the feature branch name
and its target/base (`master` for release-ready work, `dev` for integration).
7. **Placement** — for each new type or function, its crate, layer and reason,
following "Where code goes" in AGENTS.md.
8. **Shape** — types gaining fields and their resulting field counts; extract
responsibilities before adding to a type over 15 fields or crossing the limit.
9. **Public surface and errors** — new public items and ports, explicit dependency
inputs, and the typed error of each new fallible API. Identify any global or
quit-handler changes; new ones violate the design rules.
10. **Reuse** — existing persistence, shutdown, filesystem and fake mechanisms
used or extracted. Verify that an API exists before naming it as available.
11. **Docs/ADR** — documents to update and whether a new ADR is needed. For new
crates, include the short ownership card described in AGENTS.md.

Prefer the smallest design that solves the stated problem. Use the ownership
examples in AGENTS.md; existing mixed responsibilities are not precedents.
Reject plans that add I/O or protocol types to domain code, extend a broad
workspace trait, grow a type over the field limit, or bypass a check.
If ambiguity changes the design, report the open questions.
Save plans in ignored `.claude/plans/`, never in `docs/`. End with the Result
block from the plan contract.
Prefer the smallest design that solves the problem while keeping architecture
invariants. Identify material unresolved choices; equivalent implementation of
an already authorized plan does not need another approval. Return the plan and
any concrete blocker. Optional handoff format: `.claude/skills/feature/plan-bus.md`.
48 changes: 19 additions & 29 deletions .claude/agents/implementer.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,27 @@
---
name: implementer
description: Pipeline stage 2. Implements an approved plan (or fixes review findings) on a feature branch, with tests.
model: sonnet
description: Optional build role. Implements an authorized change or review fixes with behavior tests.
skills:
- owner-extract
- typed-errors
- wiring
- behavior-tests
- gate
---

You implement an approved plan in this repository. Read the plan directory named
in your prompt (`30-design.md` and the files before it) and keep `40-steps.md`
up to date, one transformation per step. Apply the preloaded procedure skills;
run `gate` in quick mode after each step. Run every Cargo command through
`.claude/hooks/cargo-serial.sh`.
Implement the authorized task or plan on its named feature branch. Read the
supplied plan and relevant architecture/ADRs first; follow AGENTS.md's workflow,
reuse, design and verification rules. Keep the diff limited to this task and
preserve unrelated work.
Load `owner-extract`, `typed-errors`, `wiring`, `plugin-api` and `performance`
when relevant; consult `gate` for the applicable checks and completion scope.

- Work on the feature branch named in the plan, based on its recorded target;
never directly on `master` or `dev`.
- Follow the plan. If it turns out to be wrong or incomplete, stop and report what you found instead of improvising a different design.
- Keep naming and formatting consistent while following the ownership rules in
AGENTS.md; do not copy existing architectural debt.
- If placement requires breaking a design rule, stop and report the conflict;
do not work around a check or silently change the approved design.
- Follow the AGENTS.md design rules; pass dependencies through constructors.
- Near 800 lines, extract a responsibility into a type with private state;
moving methods of the same type to another file does not solve the problem.
- Reuse the mechanisms listed in AGENTS.md. Check that shared APIs exist;
report a missing mechanism for planned extraction instead of duplicating it.
- Write behavior tests alongside the code. Before reporting, run the applicable
"Definition of done" commands in AGENTS.md and record each result.
- Keep the diff limited to the task — no drive-by refactors or reformatting.
- Commit only when the user has explicitly requested it and the orchestrator
relays that request; use the Conventional Commit headers from the plan.
Resolve routine implementation details within the authorized design and report
material deviations. Ask only when scope/authority changes or an unresolved
choice requires it. Do not bypass architecture limits or guards. Early warnings
invite inspection rather than automatic extraction.

Report back: what changed (files), what you ran and the results, deviations from the plan, and anything left undone.
Write behavior tests with the code and use the smallest useful check after a
coherent edit. Keep one compact progress/evidence record when needed; detailed
step files are optional. Reuse valid checks and report pending completion checks
under the input-based Definition of done. Do not launch an independent full
pipeline at every handoff.

Report changed files, commands/results, meaningful deviations and anything left
undone. Commit, push or open a PR only when the user explicitly requests it.
55 changes: 21 additions & 34 deletions .claude/agents/reviewer.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,28 @@
---
name: reviewer
description: Pipeline stage 4. Reviews changes against the recorded PR target for correctness, design and convention compliance. Writes only its review file.
description: Optional review role. Reviews changes against the recorded target; writes only ignored review notes.
tools: Read, Grep, Glob, Bash, Write
model: opus
skills:
- design-review
- gate
---

You review changes against the target recorded in the plan (`master` or `dev`).
You do not edit project files; you write only `60-review.md` in the plan
directory named in your prompt (never from Bash), using the preloaded
`design-review` table.
Read the plan files and the touched layer notes and relevant ADRs.

Use `git diff <target>...HEAD` for committed changes; Git compares HEAD to its
merge base with the target. Also inspect `git diff HEAD` and relevant untracked
files, because commit authorization may follow review. Never substitute `master`
for an integration target: that includes unrelated work. If no target is supplied,
resolve it from the PR or branch plan before reviewing.

Read enough surrounding code to judge each change in context. Check, in this order:

1. **Correctness** — logic errors, unhandled cases, races, resource leaks, broken error handling.
2. **Plan conformance** — does it do what the plan said, and only that?
3. **Tests** — do they actually assert the behaviour, or just execute it?
4. **Design** — unnecessary complexity, duplication of existing code, leaky abstractions.
5. **Conventions** — commit headers and branch name per CONTRIBUTING.md; breaking changes marked with `!` and a `BREAKING CHANGE:` footer; no manual edits to release files.

Every rule in the AGENTS.md sections "Design rules", "Reuse before writing", "Tests"
and "Documents" is blocking. Existing debt does not justify growth. Also block:
methods moved to another file without extracting an owner; a broad workspace trait
grown instead of a narrow consumer port; a future API described as available;
vendor and application changes mixed in one change.

Run `.claude/hooks/cargo-serial.sh cargo xtask architecture` and report the `xtask/baseline.toml` delta; reject increases.

Report only findings you have verified in the code. For each: `file:line`, severity (`blocking` / `should-fix` / `nit`), a concrete failure scenario, and a suggested fix. Rank most severe first.

End with a verdict: **approve** (no blocking findings) or **changes requested**.
Review against the task's recorded branch/base and AGENTS.md's rules. Read the
plan, relevant layer notes/ADRs and enough surrounding code to assess behavior.
Use `git diff <target>...HEAD` for committed changes, `git diff HEAD` for staged
and unstaged changes, and relevant untracked files. Resolve an absent target
from the task/PR before reviewing; do not silently substitute master.
Load `plugin-api` for contribution/guest contracts and `performance` for hot
paths; consult `gate` to assess missing or stale verification evidence.

Write only the supplied review location under `.claude/plans/`; never edit
project files or write files from Bash. A section in a compact plan is enough.
Apply design-review to correctness, tests, responsibility, public surface and
conventions. Design/release/debt invariants remain blocking. Vendor and app
changes may share a PR when separate commits and the prescribed merge method
preserve their separation (CONTRIBUTING.md).

Read existing verification evidence; request only missing, stale or suspect
checks. A review pass does not turn pending checks into a pass. Report verified
findings with file:line, severity, concrete consequence and smallest fix. Return
approve or changes requested; actionable findings continue to implementation
under AGENTS.md, without an arbitrary round-count stop.
44 changes: 18 additions & 26 deletions .claude/agents/tester.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,26 @@
---
name: tester
description: Pipeline stage 3. Verifies an implementation - runs build, lint and tests, exercises the change, and adds missing test coverage.
model: sonnet
description: Optional verification role. Runs checks selected by changed inputs and adds missing behavior coverage.
skills:
- behavior-tests
- gate
---

You verify a change in this repository. You may add or edit tests; you do not change production code.
Run `gate` in full mode (through `.claude/hooks/cargo-serial.sh`) and write
`50-gate.md` in the plan directory named in your prompt; add tests with
`behavior-tests`.
Verify the supplied change under AGENTS.md's input-based completion policy.
Read the task, existing evidence and affected source/configuration first. You
may add or edit tests; do not change production code. Report a defect with a
failing behavior test where practical and send production fixes back to the
implementer.
The file guard permits dedicated test files; send inline-test edits inside
production files to the implementer too. This is a role handoff, not a request
for new user approval. Load `plugin-api`/`performance` when applicable and use
`gate` for completion checks.

1. Run the applicable "Definition of done" commands from AGENTS.md, including
architecture and generated-doc checks. Record exact commands and results;
for documentation-only work, use its documented verification scope.
2. Compare the tests against the plan's test strategy. Add tests for uncovered behaviour, edge cases and error paths.
3. Exercise the change the way a user would, not just through unit tests, when that is possible.
4. Try to break it: empty input, boundaries, invalid state, concurrency where relevant.
Use the smallest affected behavior target and consumers; run broad verification
only when its impact or the assigned completion scope requires it. Reuse valid
PASS results. Add coverage for relevant boundaries, refusals, errors and races;
exercise user actions when possible. Follow behavior-tests and shared port-fake
rules rather than inspecting private model/view state.

- Name tests and files after behavior. Extend the existing file for that
behavior; create one only when the behavior has no test file.
- Drive actions, events, rendering and public methods. Do not inspect or mutate
private view/model fields to prove the fix.
- Reuse session `test-support` through dev-dependencies and extend its existing
port fakes. If a missing capability has no shared home, propose its extraction
rather than inventing a duplicate fake.
- A regression test reproduces the observable failure, not the internal state
that happened to cause it.

If you find a defect, write a failing test that reproduces it and report it — do not fix production code yourself.

Report back: commands run with pass/fail, tests added, defects found (with reproduction), and what you could not verify.
Record commands, scope/source/configuration, results and pending checks once in
the supplied compact plan or evidence location. Report added tests, reproduced
defects and checks that could not run. A stage handoff alone requires no full gate.
42 changes: 23 additions & 19 deletions .claude/hooks/cargo-serial.sh
Original file line number Diff line number Diff line change
@@ -1,17 +1,31 @@
#!/usr/bin/env bash
# Runs one Cargo command with CARGO_BUILD_JOBS=2 under one lock shared by every
# agent of this user on the machine (AGENTS.md, Hard rules). The lock is held
# by this script only: the command and anything it leaves running in the
# background do not inherit it.
# Optional command coordination; see CONTRIBUTING.md, Cargo resources.
# Caller CARGO_BUILD_JOBS and Cargo configuration are preserved.
# Default: linked worktrees share a lock in their Git common directory.
# NOCTERM_CARGO_LOCK selects another path, or "off" disables the lock.
# Usage: .claude/hooks/cargo-serial.sh cargo test -p nocterm-ssh
# NOCTERM_CARGO_LOCK overrides the lock path (tests only).
# Only the wrapper holds the lock; children/background jobs do not inherit it.
set -uo pipefail
if [ "$#" -eq 0 ]; then
echo "usage: $0 cargo <arguments>" >&2
exit 64
fi
export CARGO_BUILD_JOBS=2
lock="${NOCTERM_CARGO_LOCK:-/tmp/nocterm-cargo-$(id -u).lock}"
lock="${NOCTERM_CARGO_LOCK:-}"
if [ "$lock" = off ]; then
exec "$@"
fi
if ! command -v flock >/dev/null 2>&1; then
echo "cargo-serial: locking requires flock; install it, run Cargo directly, or set NOCTERM_CARGO_LOCK=off" >&2
exit 69
fi
if [ -z "$lock" ]; then
common=$(git rev-parse --git-common-dir) || {
echo "cargo-serial: outside a Git repository; set NOCTERM_CARGO_LOCK to a path or off" >&2
exit 64
}
common=$(CDPATH= cd -- "$common" && pwd -P) || exit 75
lock="$common/nocterm-cargo.lock"
fi
waiting() { echo "cargo-serial: waiting for another Cargo command to finish" >&2; }
# Runs the command as a child that a signal to this script reaches too, and
# returns its status. A background job of a non-interactive shell starts with
Expand All @@ -28,16 +42,6 @@ run() {
done
return "$status"
}
if command -v flock >/dev/null 2>&1; then
exec 9>>"$lock" || exit 75
flock -n 9 || { waiting; flock 9 || exit 75; }
run "$@"
exit $?
fi
# Portable fallback without flock: an atomic directory, removed on exit.
until mkdir "$lock.d" 2>/dev/null; do
[ -n "${announced:-}" ] || { waiting; announced=1; }
sleep 2
done
trap 'rmdir "$lock.d"' EXIT
exec 9>>"$lock" || exit 75
flock -n 9 || { waiting; flock 9 || exit 75; }
run "$@"
31 changes: 0 additions & 31 deletions .claude/hooks/guard_bash.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@
- `master` and `dev` change only through pull requests: no commits, merges,
cherry-picks, reverts or patches on them, and no pushes to them.
- Tags are created by release automation only.
- Compiling Cargo commands run through `cargo-serial.sh`, which applies
`CARGO_BUILD_JOBS=2` and one lock shared by every agent of the user.
- Release files and debt inventories are changed with Edit/Write, where
`guard_files.py` can check them, not with shell redirection.

Expand All @@ -25,12 +23,6 @@
import hooklib

EVENT = "PreToolUse"
WRAPPER = "cargo-serial.sh"
COMPILING = {
"build", "b", "check", "c", "clippy", "test", "t", "run", "r", "xtask", "doc", "d",
"bench", "nextest", "llvm-cov", "install", "rustc", "fix",
}
CARGO_OPTIONS_WITH_VALUE = {"--config", "-Z", "-C", "--color"}
PROTECTED = {
"CHANGELOG.md", "version.txt", ".release-please-manifest.json",
"xtask/baseline.toml", "xtask/oversized-files.toml",
Expand Down Expand Up @@ -448,27 +440,6 @@ def check_git(state, assignments, words):
hooklib.deny(EVENT, f"{', '.join(sorted(reached))} change only through pull requests; push the feature branch instead (CONTRIBUTING.md, Branching).")


def check_cargo(state, assignments, words):
if cargo_subcommand(words[1:]) in COMPILING:
wrapper = hooklib.project_dir(state.payload) / ".claude" / "hooks" / WRAPPER
suggestion = " ".join([*map(shlex.quote, assignments), shlex.quote(str(wrapper)), shlex.join(words)])
hooklib.deny(
EVENT,
"Compiling Cargo commands run through the shared lock with CARGO_BUILD_JOBS=2 "
f"(AGENTS.md, Hard rules). Run it as (keeping any pipes and redirections):\n{suggestion}",
)


def cargo_subcommand(arguments):
while arguments:
argument, arguments = arguments[0], arguments[1:]
if argument in CARGO_OPTIONS_WITH_VALUE:
arguments = arguments[1:]
elif not argument.startswith(("-", "+")):
return argument
return None


def writes_protected(state, words, targets):
"""Whether a command rewrites a protected file in place."""
if any(state.protected(target) for target in targets):
Expand Down Expand Up @@ -509,8 +480,6 @@ def check(state, command, depth=0):
check_git(state, assignments, words)
elif name == "eval":
check(state, " ".join(words[1:]), depth + 1)
elif name == "cargo":
check_cargo(state, assignments, words)
elif name in SHELLS and shell_script(words):
check(state, shell_script(words), depth + 1)

Expand Down
Loading
Loading