An AI workflow that
holds its shape
How the bigin-skills harness turns an AI coding assistant from
something that produces plausible code into something that produces
reviewable, specified, verified changes — and what you have to do to get that.
The problem this actually solves
Not "make the AI smarter" — make its output something you can review, and something the next session can pick up.
An unconstrained coding agent is good at producing code that looks right. That is precisely the failure mode: it is plausible, it is large, and the ways it diverges from what you wanted only surface at review — when fixing them means a rewrite rather than a sentence.
Three specific things go wrong, and each has a mechanism in this plugin pointed at it:
- It starts before the shape is agreed. You get a large diff built on an assumption nobody stated. → the spec gate.
- It marks its own homework. "I implemented the feature and it works" is a self-report, not evidence. → an independent verifier that never sees that self-report.
- It forgets, expensively. Every session re-derives the same context, and re-derives it differently. → a knowledge bundle with an index-first read protocol.
What you get for it
Scoped to an approved plan, with an explicit "not in scope" line that makes creep visible.
Three execution tiers. Mechanical work doesn't pay for the top model, and you pick the ladder.
Deterministic scripts, not prose. Including one that stops the others being switched off.
What it costs you
Be clear-eyed about this. The harness adds a decision point before non-trivial work: you read a spec and approve it. That is real friction, and it is the entire mechanism — an agent that never has to stop is an agent that never has to be right about scope. What it does not add is per-session overhead: the always-loaded footprint is a few thousand characters, and it is budget-checked at commit time so it stays that way.
Five concepts that explain the rest
Learn these and the individual skills stop needing separate explanation.
The spec gate
Before non-trivial work, the agent writes a short spec and waits for your
approval. Approved, it becomes PLAN.md — the artifact
everything downstream refers to. Bug fixes, copy changes, config tweaks and
changes under ~20 lines skip it entirely.
The two fields that carry the weight are Security considerations and Not in scope. The first is economics: a threat named at spec time is a sentence, the same threat found at review is a rewrite. The second is what makes "stop and ask" enforceable later — without it, scope creep has nothing to violate.
Independent verification
After implementation, a fresh verifier subagent audits the
diff against PLAN.md. It is passed the diff itself, never the
implementer's summary of what it did — that self-report is exactly what the
independence exists to route around. On a fail, the original implementer is
resumed with the issue list; a new verifier checks the next round.
Capped at three rounds, then it stops and asks you.
Two axes, not one
Model choice answers "could it do this at all." Effort answers "did it check its work." They are scored separately, because a change can be mechanically trivial and still need heavy checking — a one-line edit to a contract, or a migration. Scoring them together means overpaying for the model or underpaying for the checking.
Where a fact lives
Four surfaces, one question each. Putting a fact in the wrong one is the most common way this convention degrades, because the wrong home has no mechanism to expire it.
| Surface | Answers | Lifetime |
|---|---|---|
| knowledge/ | What is the system, and why? | Outlives sprints; expires on behavior change |
| .claude/rules/ | How do we work here? | Outlives projects; changes by decision |
| graphify-out/ | Where is the code, what connects? | Regenerated; expires every commit |
| PLAN.md | What are we doing right now? | Deleted at task end |
The always-loaded budget
Everything in CLAUDE.md and every unscoped rule file is read on
every turn of every session. So rules are scoped by path where
possible, and the total is checked by a script at commit time. This is why
the generated CLAUDE.md is short by design and why deep detail
lives in reference files that load only when needed.
Setting up a repo
One conversation, a handful of decisions, then one command each contributor runs once.
Install the plugin
/plugin marketplace add tammai/bigin-skills
/plugin install bigin-skills@biginnpx skills add tammai/bigin-skillsRun the harness setup
Say it in plain language — the skill triggers on intent, not a command name:
Set up the harness in this repoYou will be asked a small number of decisions. These are the ones worth thinking about:
| Decision | Recommendation |
|---|---|
| MODEL_ROUTING | Take the default opus-centric. Move later if verifier failures become routine. |
| KNOWLEDGE_BUNDLE | Yes for anything long-lived. It is the piece that compounds. |
| CI_PROVIDER | Yes if you have CI. The same checks run at commit and in CI, so they can't diverge. |
| GRAPH | Optional, and safe to defer. Most value on a large existing codebase. |
Activate the gates — once per clone, per contributor
git config core.hooksPath scripts/git-hooksRead what it wrote
Open the generated CLAUDE.md. It is deliberately short, and it
is what every session in this repo sees before anything else. If something
in it is wrong for your team, fix it now — it is cheaper than any
correction you will make later.
The daily loop
Six steps. Two always need an answer from you, a third does when the work is big enough, and the rest run on their own.
/code-review, or
both — and only then is the plan distilled and deleted.
Starting work
Say what you want. The workflow triggers on intent:
Add rate limiting to the public API endpoints
Fix the double-submit bug on the checkout formWhat you do at each step
Scope — read one sentence, before any code
What is changing, and why, in a single line. If it doesn't match what you meant, say so now: this is the cheapest correction available anywhere in the loop.
Spec gate — you read it and approve it
The one interruption that happens every time. Read the spec properly, and check Not in scope especially — it is the line that governs everything after it. If the request was underspecified you get up to three clarifying questions instead; answer them rather than waving them through.
PLAN.md — the working contract on disk
Nothing required from you. The approved spec plus a task table are written to disk, and the tasks are mirrored into the task list so you can watch progress without opening the file. PLAN.md stays the source of truth; the mirror is disposable.
Implement — the routed tier does the work
One possible confirmation. If scoring lands on the deep tier you are asked before it spawns — the most expensive tier and the biggest behavior swing, so it is the one pause worth having. Quick and standard spawn without asking.
Verify — a fresh agent, reading the diff only
Nothing required from you. A brand-new subagent audits the diff against PLAN.md — it is handed the diff itself, never the implementer's account of what it did, which is the whole reason the check is worth anything. On a fail the same implementer is resumed with the issue list, and another new verifier checks the next round. Three rounds maximum, then it stops and asks you.
Review and Cleanup — one decision
Review first, and it is your call how. A human pass, /code-review, or both — it is offered, never run automatically. Say yes to the AI pass for anything touching auth, money, or data you can't reconstruct; a human pass is worth it wherever the consequence of being wrong lands on someone outside the team. If the change touches auth, sessions, secrets, PII, or untrusted input, /security-review is offered alongside it.
Cleanup only runs once review is resolved — clean, or explicitly declined. If the task established a decision, invariant, or constraint, a specific knowledge/ edit is proposed; then PLAN.md is deleted, because it is a working file rather than documentation. "Nothing durable here" is the correct answer most of the time — routine work doesn't produce concepts.
Knowledge that compounds
The part with the slowest payback and the highest ceiling.
Two kinds, one bundle
knowledge/ holds concept files answering what the
system is and why — decisions, contracts, boundaries, constraints
that outlive a sprint. Two populations live there with different lifecycles:
- Your own system
- Written by the cleanup step and by end-of-sprint distillation. Tracks your code; expires when behavior changes. Verified by human review in the PR.
- A third-party library
- Written by
/knowledge-distillfrom the library's own repo at a pinned commit, then audited by a subagent against that clone. Expires when the dependency moves a minor version — enforced by a commit-time drift guard.
The library case exists because models have a training cutoff and libraries don't. A pinned, audited bundle is what stops an agent confidently writing an API that was removed two versions ago.
knowledge/. "AuthService
calls TokenStore" is true until the next refactor and nothing will catch
it. Concept files point at sources of truth — the code, the
OpenAPI file, a rule — and never duplicate them.
The optional code graph
If you enable it, graphify parses your code into a graph of
symbols and their relationships, answering where questions
at zero token cost — what calls this, what breaks if I change it. It is
structure, never intent, and a source read always wins a disagreement.
The two are complements, and they fail differently. A stale concept file lies about intent, which only a human can catch — so it is defended by review and a validator. A stale graph lies about location, which a parser can re-derive in under a second — so it is defended by rebuilding.
When something blocks you
Each message names its own way out, and each one is real.
Gates are deterministic scripts running before a tool call or at commit time. Being blocked is the system working — the useful question is which gate, and what it wants.
| Message | What to do |
|---|---|
| PLAN.md missing or not approved | Approve a spec, or keep the change under 20 lines. Tests, docs and config are exempt. |
| PLAN.md is for branch 'X' | A leftover plan. Finish it, update its Branch: line, or delete it. |
| Not a Conventional Commit | Rewrite the subject: feat:, fix(api):, under 100 characters. |
| fix commit with no test | Stage the regression test, or add [no-test] with the reason. |
| --no-verify is blocked | Fix what is failing. This one has no override, deliberately. |
| Canary token detected | Stop. Not a false positive — see below. |
Why there is no bypass
--no-verify and force-pushes are blocked by a guard that runs
before the shell does. Every other gate is only as strong as the inability
to skip it, so that one is load-bearing. --force-with-lease is
allowed, because it refuses when the remote moved under you — which is the
actual damage --force does.
If a gate is wrong for your repo, change the gate — its allowlist, its threshold, the rule file — as a reviewed edit. That change shows up in a diff. A bypass doesn't.
The injection gate
Three stages defend against prompt injection arriving through fetched content. A scanner flags suspicious tool output; the next risky tool call asks for confirmation. Separately, a per-session random token is seeded with an instruction never to reproduce it — and any tool call containing it is denied outright. That third stage is not a heuristic: a session-unique UUID appearing in a tool call is proof the context is being exfiltrated. Treat the task as compromised and stop.
Best practices and recommendations
What actually determines whether this works for a team, in rough order of impact.
Do these
- Read the spec properly, once. Thirty seconds here is the highest-leverage half-minute in the workflow. Approving specs unread reproduces exactly the problem the gate exists to prevent, with extra steps.
- Make everyone run the hooks-path command. Put it in your README's setup section. A contributor who skipped it has no gates and no way to notice.
- Start on the default ladder. Move to
frontieronly when verifier failures on standard-tier work become routine. One bad round is the loop working, not evidence of an under-powered tier. - Answer "nothing durable" honestly at cleanup. A bundle full of per-task narrative is worse than a small one, because the index stops being scannable.
- Fix the root cause upstream. When output is consistently wrong, the cause is usually an under-specified plan or a missing convention — not an under-powered model.
Avoid these
- Don't reach for the full spec because a task feels big. It is for an explicit request or a rubric score — and it auto-routes implementation to the most expensive tier, so casual use is expensive twice.
- Don't raise effort to fix quality. High is the ceiling by standing decision. The checking a higher setting would buy is already supplied by the verify loop; buying it twice yields slow, hedged output.
- Don't widen a gate's allowlist to unblock yourself. Especially not to include CI config — a workflow file executes with access to your secrets and defines which gates run at all.
- Don't let rules accumulate. Every addition to always-loaded context is paid on every turn of every session forever. End-of-sprint distillation enforces this: each addition must name what it replaces.
- Don't skip the branch line on a plan. It is what stops yesterday's plan silently governing today's task.
Rolling it out to a team
One repo first, for a sprint
Pick something real but not load-bearing. You want the gates to fire in anger before you have opinions about them.
Tune the rules, not the gates
Most friction is a convention that doesn't match how your team works. Fix it in .claude/rules/, where it is scoped and cheap.
Add the knowledge bundle when the first "why is it like this" appears
It compounds, but only if entries are earned. Starting it empty and letting the cleanup step feed it beats bulk-writing concepts up front.
Run an end-of-sprint distillation
This is the mechanism that keeps the harness from bloating over a year. It compresses rather than appends, and it stops for your approval before writing anything.
Appendix · Reference
Where to go when this handbook has stopped being enough.
Deeper guides
| Document | Covers |
|---|---|
| docs/USER_GUIDE.md | The task-oriented walkthrough, skill by skill |
| docs/SPEC-GATE.md | Both spec formats, and exactly what the guard measures |
| docs/ROUTING.md | Tier scoring, the three ladders, the verification bar |
| docs/GATES.md | Every guard, the injection gate, unblocking |
| docs/KNOWLEDGE.md | The bundle: what it holds, what keeps it honest |
| docs/GRAPHIFY.md | The optional code graph |
| README.md | Full reference — every profile, every generated file |
Glossary
- Harness
- The generated files that govern AI work in a repo:
CLAUDE.md,.claude/rules/, and the commit-time gates. - Spec gate
- The requirement that non-trivial work has an approved
PLAN.mdbefore any edit lands. - Tier
- Which subagent executes a task — quick, standard, or deep — chosen by capability scoring.
- Verification bar
- How carefully a change must be checked. Scored separately from the tier, and it never changes which model runs.
- Ladder
- A profile mapping each tier to a model and an effort level. Three of them;
opus-centricis the default. - Concept file
- One Markdown file in
knowledge/describing a single invariant, contract, or domain idea. - Drift guard
- A commit-time check comparing a library bundle's pinned version against the dependency your project actually declares.
- Guard
- A deterministic Node script wired to a hook, blocking a tool call or a commit. Fails closed.
Getting unstuck
- A gate fired and you don't know why →
docs/GATES.md - Work routed to a tier you didn't expect → check which verification-bar trigger fired
- An agent wrote a stale library API → distil a pinned bundle for it
- Sessions keep re-deriving the same context → that is what
knowledge/is for