Agent workbench (capstone)

settings.json is where you tell Claude Code the rules of the house. It's plain JSON — a set of "key": value pairs wrapped in curly braces. Two sections matter here: permissions (what's allowed) and hooks (what runs automatically).

1. "allow" lists actions Claude may take without asking — run pytest or ruff, read any file (Read(*)), and edit files under src/. The patterns in parentheses scope each permission narrowly.
2. "deny" is the safety rail: it blocks git push and any edit to vendor/. Deny always wins over allow, so risky actions stay in human hands.
3. The "Stop" hook fires when Claude finishes a turn. "matcher": "*" means "on every stop", and it runs one command.
4. That command, pytest -q || echo TESTS-FAILED, runs your tests quietly; the || means "if pytest fails, print TESTS-FAILED" so a failure is loud and visible instead of silent.

What the output means: No visible output on its own — this file just configures Claude Code. Its effect is felt later: blocked pushes, and tests running automatically each time Claude stops.

Try this: Add "Bash(git commit:*)" to the allow list and think about whether you want that. The allow/deny split is exactly where you decide what Claude does on its own versus what needs you.

Before any code, this is a map of the repo you're about to build. Everything Claude reads to behave your way lives in one hidden folder, .claude/, next to your normal project files. A newcomer only needs to know: each file below is one capability, and the capital-K tags (K1, K2, …) point back to the lesson that introduced it.

1. CLAUDE.md sits at the top — plain-English notes (conventions, common commands, guardrails) that Claude reads automatically every session, like an onboarding doc.
2. .claude/settings.json holds permissions (what Claude may or may not do) and hooks (commands that fire automatically at certain moments).
3. commands/, skills/, and agents/ each add one thing: a reusable /review shortcut, a Skill (packaged know-how), and a subagent (a focused helper with its own narrow permissions).
4. mcp/server.py is your own small server that hands Claude project data and actions; .github/workflows/…yml runs a review automatically on every pull request.

What the output means: This is a directory tree, not a program — nothing runs. The ├── and └── lines just show which files live inside which folders (indentation = nesting).

Try this: Picture cloning this repo fresh: the moment you open it, Claude already knows your rules (CLAUDE.md), your limits (settings.json), and your tools. That inheritance-from-one-git pull is the whole point of the workbench.

An MCP server is a small program that exposes your own tools to Claude in a standard way (MCP = Model Context Protocol). Here it's built with FastMCP, a helper that turns ordinary Python functions into tools Claude can call. Once this runs, Claude can look up tickets and deploy status through your systems.

1. mcp = FastMCP("project-tools") creates the server and names it. That name is how Claude will refer to this bundle of tools.
2. query_tracker and read_deploy_log are placeholders (the ... means "you fill this in") — they stand for wherever your real ticket system and deploy logs live.
3. The @mcp.tool() line above a function is a decorator: it registers that function as a callable tool. The docstring right under it ("""List open tickets…""") is not a comment — Claude reads it to decide when to use the tool, so it must describe the purpose plainly.
4. The -> list[dict] and -> dict type hints tell Claude the shape of the answer. Finally mcp.run(transport="stdio") starts the server, talking over standard input/output so Claude Code can connect to it locally.

What the output means: Run directly, this prints nothing and waits — an MCP server is a background service, not a script that finishes. Claude Code starts it and calls its tools on demand.

Try this: Read each tool's docstring as if you were Claude deciding which to call. A vague docstring means the wrong tool gets picked — clear descriptions are how the model routes to the right tool.

A Skill is packaged know-how Claude loads on demand. The file has two parts: a front-matter header (between the --- lines) that tells Claude when to use the Skill, and a Markdown body that says what to do. This one encodes your team's coding and writing conventions.

1. The --- fences mark YAML front-matter — structured metadata. name is the Skill's id.
2. description is the crucial line: Claude reads it to decide whether this Skill applies. "Use whenever writing or editing code, docs, or PR descriptions" is a clear trigger, so the Skill activates at the right moments.
3. Everything below the closing --- is plain Markdown — the actual rules. Bullets keep them scannable: type hints, specific exceptions (never except: pass), docs that lead with the "why".
4. Because it's just text, the Skill is version-controlled with the repo, so the whole team's Claude follows the same conventions automatically.

What the output means: No output — a Skill is instructions, not a program. Its effect shows up in the code and docs Claude writes: they start matching these house rules.

Try this: Add one rule you care about (e.g. "tests live next to the code they test"). The next time Claude edits this repo, that rule is in force — you've taught the whole team's assistant with one line.

This is a GitHub Actions workflow — a YAML recipe GitHub runs automatically. Its job: every time someone opens a pull request, spin up a fresh machine, run Claude in headless mode (no chat window) to review the change, and save the findings. This is your review, automated for the whole team.

1. on: [pull_request] is the trigger — the workflow fires on every PR. The runs-on: ubuntu-latest line gives it a clean Linux machine to work on.
2. actions/checkout@v4 with fetch-depth: 0 downloads the full git history so the diff can be computed against main.
3. ANTHROPIC_API_KEY is read from repo secrets (${{ secrets.… }}) — the key is never written in the file, so it stays private.
4. The run: block is shell: save the PR's changes to /tmp/diff.txt, then claude -p "…" runs one prompt non-interactively, asking the code-reviewer subagent to review that diff and group findings by severity, writing the result to review.md.

What the output means: On each PR, a review.md is produced with the subagent's findings grouped by severity, and cat review.md prints it into the CI logs for anyone to read.

Try this: Notice the same subagent used interactively (K5) is reused here headlessly. Write once, run it both in your editor and in CI — that's the leverage of committing your setup.

This little program checks that your workbench is complete — that every piece from the section (CLAUDE.md, permissions, the Stop hook, a Skill, a subagent, an MCP server, CI review) is actually present. It's a self-test you can run to prove the setup is whole, and unlike the configs above, it really runs.

1. required is a dictionary mapping a short key (like "stop_hook") to a human-readable label. It's the checklist of everything the workbench must have.
2. repo is expected to be a dictionary describing what's present. repo.get(key) returns the value for that key, or None if it's absent — so not repo.get(key) is true for anything missing.
3. The line missing = [desc for key, desc in required.items() if not repo.get(key)] is a list comprehension: it walks the checklist and collects the labels of every piece the repo lacks.
4. return (not missing), missing hands back two things: a True/False "is it ready?" (not missing is True only when the list is empty) and the list of what's still missing. The two calls below test a full repo and a partial one.

What the output means: ready: (True, []) — the full repo passes with nothing missing. partial: (False, [...]) — the partial repo fails and names exactly the four pieces it lacks (the hook, subagent, MCP server, and CI review).

Try this: Delete one key from the full dict and re-run: that piece's label jumps into the missing list and ready flips to False. This is how you'd gate a 'workbench complete' check in CI.