# Work with verifiable criteria
nool task create --name "Bounded retries for webhook delivery" \
--acceptance "Retries are bounded to 5 with exponential backoff" \
--acceptance "Timeouts and permanent failures are covered by tests" --solidify
nool task pick --id <task-id>
nool task start --id <task-id>
# Intent and scope first; the proposal is checked against both
nool announce intent --intent "Bounded retries for webhook delivery" --target-nodes src/billing/webhooks.ts
nool propose --path src/billing/webhooks.ts --intent "Bounded retries for webhook delivery"
nool solidify --compact
# Done is a receipt against a real knot, not a checkbox
nool task qa --id <task-id>
nool task verify-done --id <task-id> --landed-knot <knot-id> --solidify
nool eval run --set webhook-quality --run-id <run-id>Task subcommand flags follow the installed CLI; run nool task --help for the full lifecycle, including custom state machines.
Velocity without structure fragments the codebase
Teams that adopt coding agents see two curves. Output goes up immediately. A few weeks later, review load, regressions and architectural drift go up too, because agents optimise for the task in front of them and nobody told them where the boundaries are. The research page on the cheap stack describes the ninety-day version of this: fast at first, then a reckoning as ad-hoc agent work accumulates into a codebase no one can reason about. AI engineering as a discipline is the set of practices that keep the first curve without paying the second, and it needs infrastructure, not just better prompts.
Intent first, then implementation
The practice Nool encodes is that every change starts with a stated intent and a bounded scope. A task carries acceptance criteria that can be verified. An agent announces the intent, takes a lease on the scope, and proposes the change under the same intent it announced. The envelope check confirms the implementation stayed inside the declaration; if it did not, the agent must justify the excursion or narrow the change. Reviewed plans bind to the repository state they were reviewed against, so a plan approved on Monday cannot silently be applied to Thursday's code. The cost is small but not zero: the benchmark measured governed throughput as a tie with plain git worktrees and average stall about 0.2 seconds higher.
Evidence, not vibes, for done
Done is a claim, and claims need evidence. In Nool a task moves to Done through a QA checkpoint where its acceptance criteria are verified, and nool task verify-done records a verification receipt against the knot that actually landed. With trusted attestations configured, verification can be automatic: the landed knot must carry a passing verdict for every obligation its paths require, from unit tests to a security scan to an architecture review. nool eval scores a recorded agent run against a named eval set, so the quality of an agent's work is graded on structural criteria such as terminal state, budget, tools used and knots produced, not on whether its summary sounded confident.
Attribution for the long term
The last piece of AI engineering is being able to answer, months later, why the code is the way it is. Every knot carries its intent and causal parents, so nool why explains any change with the reasoning behind it and its ancestors. Findings record what the team learned, scoped and supersedable. nool debug blame walks from a failure back to the knot that caused it, and nool debug bisect narrows a regression with a test command. A codebase built this way stays legible as the proportion of agent-authored code rises, which is the whole point.
Explore before you commit
AI engineering is as much about deciding what to build as about landing it safely. nool explore keeps a structured exploration tree: candidate directions, the evidence gathered for each, and the insights distilled from them, so an investigation an agent ran last week is not repeated by another agent this week. nool try gives any direction an isolated branch to test in, with impact analysis before promotion and discard for the ones that did not pan out. nool assert records an architectural judgment as a durable, revocable knot, so the decision that ended an exploration is as queryable as the code it produced. Exploration leaves a trail, and the trail is what keeps a team from relitigating settled questions.
Frequently asked questions
- Is this only for large teams?
- No. A single engineer with two agents gets the same benefits: intent on every change, an envelope check, and a ledger the next session can read. The coordination features matter more as agents and people multiply.
- What is state-bound execution?
- The principle that a reviewed plan must bind to the repository state it was reviewed against, so it cannot be executed against code that has since changed. The research page explains the mechanism and the failure it prevents.
- How do I measure whether agents are getting better?
- nool eval scores recorded runs against named eval sets. nool usage agent reports bug rate, severity and patterns per agent, and nool insights loops detects repeated failures in agent sessions.
- Does this work with the agents we already use?
- Yes. Claude Code, Codex, Cursor and Gemini CLI all drive Nool through the CLI or the MCP server. Nool does not replace the agent; it governs what the agent lands.
- How do we record architectural decisions so agents respect them?
- With nool assert for judgments that should govern future changes and nool learn for the reasoning behind them. Both are knots in the ledger, both surface in nool context, and an assertion can be revoked explicitly when the architecture moves on.