Steer from the right control surface, and let agents work where they are reliable.
Approve the blueprint of your feature: every decision that matters, in a form you can read in full. Agents then build it and review their own work until it matches, without you reading the code, except where you decide a mistake would cost too much.
Control Surface is a chain of Claude Code skills and agents you install in your project.
curl -fsSL https://raw.githubusercontent.com/PittsCraft/control-surface/main/install.py | python3 -Run it at the root of your project. It needs Claude Code, git and Python 3.11 or newer, plus the GitHub CLI for the pull request. It installs the chain in .claude/ and needs no configuration.
A control surface is the level you steer the work from. Too high, at the product specs, is vibe coding. Too low, in the code itself, is reviewing everything. With a strong enough harness, the blueprint is the right one.
- You describe a need and steer from a blueprint. The blueprint is the only thing you have to read, and the contract the work is judged against. It is frozen when you approve it.
- Agents draw the detailed plan and build the code. A fresh agent for each step, which reads files and never a conversation.
- Consistency is ensured, not hoped for. A cross-check proves the blueprint hides nothing the plan does. Reviews go on until the code matches the blueprint, each criterion with its proof. A change that would make the blueprint false comes back to you.
- Your harness makes agents reliable. The harness is your project's own gates: its tests, lint, architecture and type checks. The loop runs them before every review and after every fix, and nothing goes on while one is red. The stronger your gates, the more you can delegate.
- Where a mistake would cost you most, read the code yourself. Declare your critical zones in your
AGENTS.mdorCLAUDE.md: the blueprint names those a plan touches, and when the work conforms, the PR description lists the files changed there, for you to read.
The blueprint is as long as the feature needs and no longer, with a diagram wherever one is clearer than prose. It always opens with the idea, the acceptance criteria and the scope, and closes with the sensitive zones; between them, it is cut for your feature, by flow, by component or by decision. It shows what will be built, never the order of construction: that stays in the plan.
You review it yourself. You never edit it by hand: you ask for a change in the conversation and an agent draws the next revision, and launching /surface-execute approves the one you read.
Two commands, and three moments when the loop hands back to you: the blueprint would have to change, the loop no longer converges, or the work conforms.
| You | The chain |
|---|---|
/surface-plan <your need> |
explores the code, asks its questions one at a time, draws the plan and the blueprint, opens a draft PR |
| Read the blueprint, ask for changes | draws the next revision, and asks again |
/surface-execute |
takes it as your approval, then builds, runs your gates, reviews and fixes until it conforms |
| Decide, when the loop hands back | goes on from your answer |
| Mark the PR ready, merge | never does it for you |
/surface-status tells you where every plan stands, at any time. If a session dies, relaunch the same command: the whole state lives in your repository.
- Guide: every step in detail, permissions, the conformity check in your CI, settings, updates.
- ARCHITECTURE.md: how the chain is built, and its invariants.
docs/adr/: the decisions whose history matters.- CONTRIBUTING.md: to work on the chain itself.
The diagrams are drawn with Excalidraw: their sources are the .excalidraw files of docs/images/.
MIT, see LICENSE.