start_project · state
Begin a ledger for a scope, or read the current state of a context (read-only) — blockers, decisions, gaps, next move.
Craft
Keep the state of building something explicit.
Most of the real state of a project lives in chat threads and people's heads: the blocker you are circling, the decision you half-made, the gap you keep meaning to close. It evaporates between sessions. Craft is a small, file-backed ledger that holds that state on disk — contexts, blockers, decisions, gaps, and how the pieces recompose — so a person or an agent can pick the work back up exactly where it was.
In the workflow you already have
It fits Agile — and it puts every role in the loop, not just devs.
Craft does not ask your team to abandon how it works. Sprints, standups, backlogs, retros — the cadence stays. Craft is the shared memory underneath it: the place where the blockers, decisions, and gaps your team already talks about become durable, typed, and — this is the new part — legible to the agents working alongside you. It slots into the rails you already trust instead of asking you to lay new ones.
| What your team already does | Where it lives in Craft |
|---|---|
| Standup impediments | typed blockers with a lane, a closure condition, and an owner — not a line in a thread that scrolls away |
| Backlog & acceptance gaps | gaps with a severity and an owner-route |
| The decisions a team makes (and forgets) | open / closed decisions — the question, the options, the choice, the rationale, the evidence |
| Definition of done / story rollup | recomposition — a child fits back into its parent, with evidence, before it closes |
| Retro residue | open gaps and blockers stay visible until closed, waived, deferred, or routed |
Every role gets a lane.
Agentic development has mostly meant agents writing code — a tool for devs. Craft is built for the whole team. Its lanes — business, tech, qa, validator, governance — mean a product owner can name a decision, a QA lead can name a validation gap, a designer can name a contract, an ops engineer can name a dependency, and a stakeholder can watch the open decisions — each routed to whoever owns it. The agent reads the same ledger they do. No one has to learn the developer's tools to be in the loop.
AI joins the work; it does not replace the workforce.
The bet behind this is plain: agent roles — product, QA, dev, stakeholder — make better decisions when they share one domain model and one set of governance signals, instead of each holding a private picture. Craft is where that shared state lives, day to day. The agent does not stand in for the product owner or the QA lead. It joins their loop, works from the same record, and hands work back to the human who owns it. That is the relationship we are after: AI in synergy with a company and its people — augmenting the whole team's judgment, not subtracting its headcount. A new way to run software and AI development together, on rails the team already trusts.
Bring this into your team →What it is
A recursive project ledger, in two files.
Craft is a method, not a program. An agent operates it by reading and writing plain files — there is no daemon, no CLI, no runtime. That is deliberate: the value is the discipline and the durable record, not automation.
Every Craft space is two files plus a folder:
.craft/ ledger.yml # the source of truth — typed rows for every piece of state index.json # optional machine index (regenerated by hand from the ledger) artifacts/ # receipts, handoffs, evidence CRAFT.md # a human-readable VIEW of the ledger (never the source of truth)
The ledger holds typed rows: contexts (a unit of work), blockers, enablers, open decisions, gaps, definitions, next moves, child contexts, and recomposition records. Everything carries a stable id and links to what it touches, so the record stays navigable long after the conversation that produced it is gone.
The ledger also keeps quick-lookup indexes — active blockers, open and blocking decisions, active gaps, current next moves — that point back to row ids rather than restating them. Ask for the state of a project and you get the pending work itself, listed per node, not collapsed into counts.
The method
A small set of moves over the ledger.
Each move reads or writes one kind of row. The invariants below are what make the record trustworthy rather than just notes.
describe · add_blocker · add_enabler
Record what is happening, what is in the way, and what unblocks it — each typed and evidenced.
refine_blocker
A raw blocker cannot be resolved directly. It must first be refined into a closure condition — what would actually clear it.
open_decision · decide
Open a decision with options; close it with the selected option, rationale, and evidence. Blocking decisions stop dependent work until closed.
add_gap · add_definition · next
Track what is not yet covered, define local terms, and set the one current next move.
open_child_context · recompose
Open a child context for nested work; close it only by recomposing it back into its parent with evidence of fit.
validate
Return pass / flag / block for a ledger or context, with the residue that remains.
export_ledger
Render CRAFT.md as a linked human view of the ledger. The view never becomes the source of truth.
link
Record a typed relation between rows so the graph stays navigable — decisions to the gaps they close, blockers to the artifacts that clear them.
Typed, not freeform
A blocker has a shape, not a mood.
Every blocker carries a type and a lane, so it routes to whoever can clear it instead of sitting as a worried note. Types name the kind of obstacle — decision, dependency, evidence, design, validation, authority. Lanes name the responsibility — tech, qa, validator, governance, business. The intent is a chain: type + lane → role → the capability or human who owns it. Decisions and gaps are typed the same way, so the ledger is a graph you can route, not a list you re-read.
Invariants
The rules that keep the record honest.
- Raw blockers cannot be resolved directly. A blocker must be refined into a closure condition before it can close — or be explicitly waived by a human or governance decision. Either way, "done" always names what made it done.
- A child context closes only by recomposition. Nested work cannot quietly disappear; it must prove it fits back into its parent.
- The view is never the source of truth.
CRAFT.mdis generated fromledger.yml; edits go to the ledger. - Route-shape evidence is not execution evidence. A plan that is well-formed is not the same as work that ran. Craft keeps the two distinct.
- Local definitions stay local. Craft records a term for a project; it does not promote it to a canonical, system-wide definition. It respects single ownership by abstaining.
Recursion & recomposition
The same shape at every altitude.
A context can open a child context: a nested unit with its own blockers, decisions, and gaps. The child runs the same moves as its parent — the method applies to itself at a smaller scale.
A child does not close by being abandoned. It closes by recomposition: a record carrying a fit summary (how the child's result fits the parent), the parent's next move, and the evidence for both. This is what separates a child's progress from the parent's readiness — a child can pass while the parent stays flagged, and the ledger shows exactly why.
root context (gate: flag) ├── blocker → refined → closure condition ├── child context "resolve the API contract" (gate: pass) │ ├── open_decision → decide (narrow adapter) │ └── recompose → fits parent; parent next move set └── gap "seed data" (still open → root stays flag)
This is also why the residue stays visible: what is not yet resolved — the open gap, the unrefined blocker, the blocking decision — remains in the ledger until it is closed, waived, deferred, or routed to whoever owns it. Nothing is "done" by being forgotten.
Worked example
From a wild start to a recomposed, validated ledger.
A small end-to-end run, the way Craft actually records it.
- start_project — begin the ledger; record the purpose and the first next move.
- add_blocker — "we can't ship without an evidence trail" — typed, with a lane and evidence.
- open_child_context — spin off "design the API contract" as its own nested context.
- open_decision → decide — inside the child, choose a narrow-contract adapter, with rationale and evidence.
- refine_blocker — turn the raw blocker into a closure condition: "evidence trail exists when each step writes a receipt."
- add_gap — note "seed data missing" with a severity and an owner-route.
- next — set the parent's current move.
- recompose — the child fits back into the parent; the child passes, the root stays flag because the gap is still open.
- validate — pass / flag / block, with the residue listed.
- export_ledger — the agent writes
CRAFT.mdas the human view, with quick links to blockers, decisions, gaps, and next moves.
Where it fits
One concrete place the system keeps its residue.
CyberAlchemy treats "what isn't resolved yet" as something to track, not hide. Craft is a small, file-backed instance of that discipline — not the system's enforcement engine.
Residue you can point at
Open gaps, unrefined blockers, and blocking decisions are the project's residue — what the work hasn't closed yet. Craft makes them typed, linked rows you can return to, instead of notes that scroll away.
Self-application
The same moves apply to a project and to a child of that project. The method runs on itself at a smaller altitude — the recursion is real, not a metaphor.
It coordinates; it does not execute
Craft records where work stands and routes it to the capability that owns it. It receives that capability's verdict — it never overwrites it. A plan being well-shaped is kept distinct from work having run.
Local stays local
Craft holds a project's own definitions and decisions. It does not elevate them to canonical, system-wide truth. The restraint is the feature: one ledger never silently becomes everyone's source of truth.
Honest status
What is built, and what is not.
The method and the record
The operating contract, a versioned ledger schema, worked examples, and the moves above — operated by an agent over plain files. It is in active use: more than 20 live .craft/ledger.yml ledgers track actual projects across the system today. Promotion to a canonical, finished tool is still deferred.
Automation
There is no automated command runner, no full ledger renderer, no runtime. Those are deliberately deferred — Craft is a discipline an agent follows, held as a candidate, not yet promoted to a finished tool. We would rather ship the honest method than a half-built runtime. If building that runtime — or putting Craft to work on real projects — is your kind of problem, let's talk.
Build it with me →Part of CyberAlchemy — see the whole system · Saturn · the paper.