AKILI
Cut development time in half without sacrificing quality: constitution-first, spec-driven development for AI agents across Claude Code, OpenCode, and Google Antigravity.
SDD (Spec-Driven Development) is the principle behind AKILI: before any code is written, you agree on a specification — requirements, design, and acceptance criteria — and both people and AI agents build from that contract. It turns AI-assisted work into something traceable, auditable, and repeatable, instead of relying on one-off prompts. AKILI applies that contract constitution-first: the project's product, UX, and technical foundations are written once, up front, and every later spec is checked against them.
Most developers use AI reactively — pasting prompts and hoping for working code. AKILI replaces that with a disciplined, constitution-first process. AKILI adds spec-to-code traceability: every shipped line of code traces back to the requirement and the task that asked for it. Durable product context and governed releases stay in 100% local methodology files. Every change moves through an explicit lifecycle, from constitution to archive, so velocity never costs quality or accrues technical debt.
A Leader → Implementer → Reviewer harness replaces the single-agent loop: a Leader plans the work, an Implementer writes the code, and a Reviewer audits the result blind — with no access to the Implementer's reasoning — catching hallucinations before they merge. When a review fails repeatedly — or fails fatally — the harness halts and rolls the working tree back automatically (git restore + git clean), so the repository is never left dirty. Native MCP integrations pull business requirements from Jira and design tokens from Figma straight into specs. Which model plays each role is set by tier, not by whichever model happens to be in session, and how much work is handed off at all is bounded at both ends.
AKILI is portable across Claude Code, OpenCode, and Google Antigravity, is CodeGraph-aware, runs on macOS, Linux, and Windows (Node.js 18+), and ships under the MIT license. Install it from NPM and be productive in seconds: akili init runs an interactive setup wizard, the --local flag installs agents isolated per project, and the classic akili install, update, list, and doctor commands keep your setup healthy.
Continuous improvement · 改善
Kaizen: the methodology that learns
Other methodologies execute specs. AKILI learns from every one.
AKILI embeds the Japanese philosophy of Kaizen (改善 — kai, change; zen, better) as an executable Kaizen retrospective, not a slogan: every time a spec is archived, AKILI automatically runs it, measuring the waste (MUDA) in the spec's own evidence — Reviewer rework, pivots, bugs, and severe findings — and distilling lessons with a named root cause and real evidence (Gemba), never speculation.
Those lessons are standardized into the constitution, templates, and agent guides — always human-approved, always in small steps — and recorded in an accumulative log that the next specs read before they start. The team stops repeating mistakes and the methodology improves with every delivery. This is the meaning of its name: akili is Swahili for intelligence, and intelligence that does not learn is not intelligence.
- 1
Measure
Hunt the waste (MUDA) in the spec's evidence: rework, pivots, bugs, and validation warnings.
- 2
Learn
Distill lessons with a named root cause and real evidence (Gemba). Generic lessons are banned.
- 3
Standardize
Propose small edits to the constitution, templates, and guides — always human-approved.
- 4
Repeat
The next spec reads the active lessons before it starts, so mistakes don't come back.
And starts over on every spec
The same structured process I apply to code, applied to strategy: collaborative discovery, framed problems, and traceable decisions.
Innovation strategy workshop · Rome
The spec lifecycle
Constitution
Establish the project-wide foundation — PRD, system design, and detailed design as the durable source of truth.
Propose
Capture the intent for one bounded change as a lightweight, reviewable proposal.
Specify
Turn approved intent into full requirements, technical design, and traceable tasks.
Execute
Implement each task with a Leader → Implementer → Reviewer harness — the Reviewer audits the Implementer blind, and any fail-fast abort rolls back cleanly with git restore + git clean.
Validate
Human review, automated tests, and validation evidence recorded against every requirement.
Archive
Consolidate documentation, sync the design system, and close the spec.
Supporting commands
Five commands for the work outside the six-phase spine
- /akili-test
Test
Writes and runs comprehensive automated unit and integration tests for whatever the current spec just implemented.
- /akili-audit
Audit
Runs spec-to-code drift auditing, comparing the live codebase against the active UX/UI design and technical blueprint to surface where they've diverged.
- /akili-resume
Resume
Scans every active spec after a session break and presents a multi-spec dashboard so work picks back up with full context.
- /akili-quick
Quick
Fast-tracks a trivial, low-risk change with minimal traceability overhead, and escalates automatically to the full lifecycle if the change turns out not to be trivial.
- /akili-seo
SEO
Audits technical SEO and generative-engine visibility (GEO) — how a page reads to search crawlers and to AI answer engines alike.
Model routing
Matching each phase to the model built for it
Capability-tier model routing assigns each phase of AKILI's lifecycle to one of six named capability tiers instead of running everything on one fixed model, so the reasoning depth applied to a task matches what that task actually needs.
T1 · Architect
Deep reasoning for architecture, trade-offs, and intent, plus the live orchestration judgment calls that come up mid-execution.
T2 · Coder
Maximum coding throughput and instruction-following for writing the code and the tests that go with it.
T3 · Auditor
Independent critical review — conformance, bugs, drift — carried out on a model that differs from whichever one wrote the change.
T4 · Context-Ingest
Large-context absorption of legacy code and baseline documentation, where the size of the context window matters more than reasoning depth.
T5 · Fast-Cheap
Cheap, fast structured formatting and summarization for tasks where depth isn't the bottleneck.
T6 · Multimodal
Visual and UI/UX reasoning over images, screenshots, and design references.
The effort dial is a second, independent setting with five levels — low, medium, high, xhigh, and max — that controls how much reasoning a single task gets regardless of which tier is assigned to it: tier is fixed per phase, effort is adjusted per task.
- Low
- Medium
- High
- X-High
- Max
author is not equal to auditorauthor ≠ auditor means the model that writes a change is never the model that reviews it: AKILI's routing registry requires the Coder and Auditor tiers to resolve to different concrete models, and escalates the Reviewer one tier automatically if they would ever collapse into the same one.
ARCHITECT = BUILDER
ARCHITECT = BUILDER keeps the model that reasons through an architecture responsible for building it too, so a trade-off decided at design time survives intact into the code instead of being reinterpreted by whichever model happens to implement it.
Reserve deep reasoning for decisions
Reserving deep reasoning for decisions means the most capable tier goes to propose, specify, verify, and live orchestration — the phases where a wrong call is expensive — while execution and bookkeeping route to faster, cheaper tiers, so cost tracks difficulty instead of every task paying architect-level rates.
Delegation
What ships to an agent, and what stays with the author
Delegation in AKILI is bounded on both ends: a floor that makes handing work off mandatory past a certain size, and a ceiling that makes handing it off wasteful past a certain point.
When delegation is mandatory
- A single-file check stays inline — delegation only starts past this baseline.
- Reading four or more full files calls for spawning a scout instead of reading them inline.
- Writing to two or more non-trivial files calls for handing the work to an Implementer.
- Reviewing a diff calls for a fresh-context Reviewer, never the model that wrote it.
When delegating is waste
- The delegation ceiling marks the point past which handing work to another agent costs more than it saves — one focused subagent beats several for a single modest task.
- Commit to a delegation once it's made instead of re-deriving the same plan a second time.
- Brief a subagent precisely the first time rather than iterating through vague instructions.
- Cap how many subagents run in parallel instead of fanning a task out indefinitely.
- Never delegate your own verification — checking your own work is not something to hand off.
FAQs
How does a project start?
With my AKILI methodology: a discovery session to understand the problem, then an agreed specification (requirements + design) you approve before any code, followed by verifiable incremental delivery. Nothing gets built without an approved spec.
What is SDD (Spec-Driven Development)?
SDD is a way of building software where you first agree on a specification — what will be built, how, and with what acceptance criteria — and then humans and AI agents implement from that contract instead of one-off prompts. The result is traceable, reviewable, and needs far less rework. AKILI is my open-source implementation of SDD.
What is AKILI, your methodology?
AKILI (AKILI-SPECS) is my open-source methodology that puts SDD into practice with an explicit lifecycle — from constitution to archive — and a multi-agent harness where a Leader plans, an Implementer codes, and a Reviewer audits blind. It installs from NPM as akili-specs and is portable across Claude Code, OpenCode, and Google Antigravity.
What stops the methodology's documentation from drifting out of date?
The version this page displays is re-resolved from the published npm package on every deploy, so it re-syncs with each release instead of being a hand-maintained string. Beyond that, every archived spec runs a bounded Kaizen retrospective that measures rework and findings against the evidence, distills a named-root-cause lesson, and folds it into the constitution and templates before the next spec starts.
Why does the Reviewer need to run on a different model than the one that wrote the code?
Because a model auditing its own output tends to defend its own reasoning instead of finding the gaps in it — author ≠ auditor removes that conflict by requiring the Coder and Auditor tiers to resolve to different concrete models, so the review is genuinely independent rather than a second pass by the same author.
Does AKILI lock a team into one AI coding tool?
No — AKILI is portable across Claude Code, OpenCode, and Google Antigravity, runs on macOS, Linux, and Windows with Node.js 18+, and ships under the MIT license, so adopting it doesn't mean betting on a single vendor's tool surviving.