akili-specs

 █████╗ ██╗  ██╗██╗██╗     ██╗
██╔══██╗██║ ██╔╝██║██║     ██║
███████║█████╔╝ ██║██║     ██║
██╔══██║██╔═██╗ ██║██║     ██║
██║  ██║██║  ██╗██║███████╗██║
╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝╚═╝

Portable Claude Code, OpenCode, and Google Antigravity configuration for the AKILI-SPECS methodology.

AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted development. It keeps product intent, UX direction, technical design, implementation tasks, tests, and validation evidence in repository documentation so humans and agents can work from the same durable context.

Docs

→ Documentation Hub: full AKILI documentation
→ Flow: constitution-to-archive lifecycle
→ Model Routing: capability-tier model selection per AKILI-SPECS phase (Claude Code + OpenCode)
→ Commands: slash command reference
→ Skills: packaged skill reference
→ CLI: akili install/update/list/doctor reference
→ OpenSpec Comparison: what AKILI borrows and how it differs
→ Release Checklist: controlled npm release process

Repository Structure

• .claude/commands/ — custom AKILI-SPECS command prompts
• .claude/skills/ — required and preferred skills used by the methodology
• .claude/templates/ — default Leader, Implementer, Reviewer, and Tester personas used by the multi-agent harness (deployed into project .agents/)
• docs/ — human-facing documentation for the flow, CLI, commands, skills, and release process
• scripts/ — helper scripts referenced by commands (e.g. gsc_verify.py)
• .mcp.json.example — reference MCP server configuration (e.g. gsc)
• dotfiles/ — environment snapshots for Neovim and tmux

Contents

• .claude/commands/
  • akili-constitution.md
  • akili-propose.md
  • akili-specify.md
  • akili-execute.md
  • akili-test.md
  • akili-validate.md
  • akili-archive.md
  • akili-audit.md
  • akili-resume.md
  • akili-seo.md
• .claude/skills/
  • angular-developer
  • api-design-principles
  • aws-serverless
  • brainstorming
  • cognitive-doc-design
  • error-handling-patterns
  • frontend-design
  • gsap-animation
  • judgment-day
  • kaizen
  • nestjs-expert
  • product-manager-toolkit
  • react-doctor
  • seo-audit
  • shadcn-ui
  • stitch-design
  • systematic-debugging
  • tailwind-design-system
  • ui-ux-pro-max
  • vercel-react-best-practices
• .claude/templates/
  • leader.md
  • implementer.md
  • reviewer.md
  • tester.md
• docs/
  • flow.md
  • cli.md
  • commands/
  • skills/
  • openspec-comparison.md

Install

Install the methodology with the bundled CLI. The installer can target Claude, OpenCode, Google Antigravity, or multiple tools.

Prerequisites

• Node.js 18 or newer
• pnpm, npm, or another Node package runner
• Claude Code, OpenCode, and/or Google Antigravity installed, depending on where you want to use the methodology

Step 1: Choose The Target Tool

Step 2: Install

Interactive Installation (Recommended): Run the init command to launch the interactive setup wizard, which will ask you about the tool and whether you want a global or local installation:

npx akili-specs init

Manual Installation via Flags:

Install globally for Claude (default):

npx akili-specs install

Install globally for OpenCode:

npx akili-specs install --tool opencode

Install locally to the current project workspace:

npx akili-specs install --tool both --local

Step 3: Verify The Installation

Check Claude installation:

npx akili-specs doctor --tool claude

Check OpenCode installation:

npx akili-specs doctor --tool opencode

Check Antigravity installation:

npx akili-specs doctor --tool antigravity

Check all:

npx akili-specs doctor --tool all

Expected result: every command, skill, and helper resource shows OK.

Step 4: Restart Your Tool

Restart Claude Code, OpenCode, or Antigravity after installation. Running sessions may not pick up new commands or skills until the tool restarts.

Step 5: Confirm Commands Are Available

In your tool of choice, confirm AKILI commands are available (either as slash commands or workflows):

/akili-constitution
/akili-propose
/akili-specify
/akili-execute
/akili-test
/akili-validate
/akili-archive
/akili-seo

Then start a project with:

/akili-constitution

Or, if the project already has a strong baseline:

/akili-propose add-my-feature

Local Checkout Install

If you are installing from this repository before publishing to npm, run:

node bin/akili.js install
node bin/akili.js install --tool opencode
node bin/akili.js install --tool both

Verify local checkout install:

node bin/akili.js doctor --tool both

Global Install

If you prefer a persistent global CLI:

npm install -g akili-specs
akili install
akili install --tool opencode
akili doctor --tool opencode

Install Paths

Default targets:

Claude:   ~/.claude
OpenCode: ~/.config/opencode

For Claude, the installer writes:

~/.claude/commands/
~/.claude/skills/
~/.claude/akili/scripts/
~/.claude/akili/templates/      (leader, implementer, reviewer, tester personas used by /akili-constitution)
~/.claude/akili/.mcp.json.example

For OpenCode, the installer writes:

~/.config/opencode/commands/
~/.config/opencode/skills/
~/.config/opencode/akili/scripts/
~/.config/opencode/akili/templates/
~/.config/opencode/akili/.mcp.json.example

OpenCode loads global command markdown files from ~/.config/opencode/commands/ and skills from ~/.config/opencode/skills/. Restart OpenCode after install or update so it loads the new files.

Updating

Update Claude:

npx akili-specs update --tool claude --force

Update OpenCode:

npx akili-specs update --tool opencode --force

Update both:

npx akili-specs update --tool both --force

Use --force when you want packaged files to replace older installed files. Without --force, existing files are skipped.

Releasing Package Updates

Repository changes do not update the published npm package automatically. Every published package update must have a new version.

Release policy:

• Commit repository changes separately from release version changes.
• Add CHANGELOG.md notes before preparing a release.
• Use npm run release:status to detect drift between local release files, npm, tags, and GitHub Releases.
• The Release Status GitHub Actions workflow runs the same drift check on pushes, pull requests, and manual dispatches.
• Publish only from a clean working tree after verification passes.
• Confirm npm authentication before publishing.
• Do not claim npm is updated until publish and smoke tests succeed.
• If publish fails, fix the blocker and retry the same unpublished version.

Use semantic versioning:

Controlled release flow:

1. Make repo changes.
2. Add notes under CHANGELOG.md > Unreleased.
3. Commit the changes.
4. Prepare the next version:

npm run release:patch

Or use release:minor / release:major when appropriate.

The release script updates package.json, moves the Unreleased changelog notes into a dated version section, and creates releases/vX.Y.Z.md.

Then verify and publish:

npm run verify:cli
npm run pack:dry-run
npm run release:status
git diff --check
git add package.json CHANGELOG.md releases/vX.Y.Z.md
git commit -m "chore(release): vX.Y.Z"
git tag vX.Y.Z
npm whoami --registry=https://registry.npmjs.org/
npm publish --access public --registry=https://registry.npmjs.org/

After publish, smoke test:

npx akili-specs@X.Y.Z list
npx akili-specs@X.Y.Z install --tool both --dry-run
npm view akili-specs version --registry=https://registry.npmjs.org/
npm run release:status

CLI Commands

See the full CLI Reference for options, install paths, examples, safety rules, and troubleshooting.

Useful options:

akili install --dry-run
akili install --tool claude --target ./.claude
akili install --tool opencode --target ./.config/opencode
akili install --tool both --claude-target ./.claude --opencode-target ./.config/opencode
akili update --force
akili update --tool both --force
akili doctor --commands-only
akili doctor --tool opencode --skills-only

Installer safety rules:

• existing files are skipped by default
• use --force to overwrite existing files
• use --dry-run to preview changes
• use --tool claude, --tool opencode, or --tool both to choose the destination
• use --target <path> to install a single selected tool somewhere custom
• use --claude-target <path> and --opencode-target <path> with --tool both

The helper resources under the target akili/ folder support commands such as /akili-seo, including the bundled Google Search Console verification helper.

Troubleshooting

If commands do not appear:

• run akili doctor --tool <claude|opencode|both>
• restart Claude Code or OpenCode
• confirm you installed into the expected target path
• rerun install with --force if old files should be replaced

If you want to preview installation without writing files:

akili install --tool both --dry-run

Manual Install

If you do not want to use the CLI, copy the repository .claude/commands and .claude/skills folders into your tool configuration location.

Typical global install target:

• ~/.claude/commands/
• ~/.claude/skills/

Typical OpenCode global install target:

• ~/.config/opencode/commands/
• ~/.config/opencode/skills/

Example:

cp -R .claude/commands/* ~/.claude/commands/
cp -R .claude/skills/* ~/.claude/skills/

Manual OpenCode example:

mkdir -p ~/.config/opencode/commands ~/.config/opencode/skills
cp -R .claude/commands/* ~/.config/opencode/commands/
cp -R .claude/skills/* ~/.config/opencode/skills/

Dotfiles

The repository also includes editor and terminal configuration snapshots under dotfiles/:

• dotfiles/.config/nvim/
• dotfiles/.tmux/
• dotfiles/.tmux.conf

These are stored as portable references or backup material for the environment used with this methodology.

Restore Neovim

mkdir -p ~/.config
cp -R dotfiles/.config/nvim ~/.config/

Restore tmux

cp dotfiles/.tmux.conf ~/.tmux.conf
cp -R dotfiles/.tmux ~/.tmux

If you prefer a lighter restore, keep ~/.tmux.conf and reinstall plugins separately instead of copying the full plugin snapshot.

Start Here

See the full Flow documentation for artifacts, review gates, project modes, and spec folder shape.

Use this flow for normal feature work:

1. /akili-constitution - create or strengthen the project baseline.
2. /akili-propose <change-name-or-spec-path> - capture intent, scope, and reviewable direction.
3. /akili-specify <spec-path> - define one feature, module, bugfix, or enhancement.
4. /akili-execute <spec-path> - implement the next approved task.
5. /akili-test <spec-path> - prove the behavior with tests and traceability.
6. /akili-validate <spec-path> - audit conformance before calling the work done.
7. /akili-archive <spec-path> - preserve completed work and remove it from active specs.

Run /akili-constitution first in a new repository, after a major product pivot, or when the baseline docs are missing. For an established repository with a good baseline, start at /akili-propose <change-name> or /akili-specify <spec-path>.

/akili-constitution classifies the repository into one of three project modes:

• Brand-new (Seed Setup): little or no code or durable docs. Creates the baseline from user intent, chosen stack, assumptions, and open questions, and copies default .agents/ personas verbatim.
• Legacy (Discovery Setup): real code exists but the AKILI-SPECS baseline does not. Inspects code, docs, architecture, tests, package manifests, and routes before drafting baseline docs, and customizes .agents/ personas to the detected stack and design tokens.
• Active AKILI-SPECS (Safe Update): the AKILI-SPECS baseline and possibly customized .agents/ already exist. Upgrades weak sections, fills missing files, and extends .agents/ non-destructively — never overwrites custom persona rules.

For all three modes, /akili-constitution creates or enhances root CLAUDE.md and root AGENTS.md so Claude Code, OpenCode, and Google Antigravity receive the same project guidance.

For existing projects, CodeGraph is an optional acceleration path. If .codegraph/ exists, agents should use it for semantic code exploration, symbol lookup, callers/callees, and impact checks. If .codegraph/ is missing and the codegraph CLI is available, the agent should ask whether to run codegraph init -i. If CodeGraph is unavailable or declined, the methodology continues with normal Glob, Grep, and file reads.

Use /akili-propose when the change needs review before full specification. For very small, obvious work, you may start directly with /akili-specify <spec-path>.

Command Map

See the full Command Reference for detailed pages per command.

How To Choose The Right Depth

Use the lightest documentation that still makes the work clear and verifiable.

Lite mode does not skip rigor. It keeps the documents short, but every requirement still needs a testable scenario and every task still needs a done criterion. /akili-quick is the one path that skips the spec documents entirely — reserved for genuinely trivial changes, with a strict gate that escalates anything bigger.

Core Concepts

The Kaizen Loop

Other methodologies execute specs. AKILI learns from every spec.

AKILI embeds the Japanese Kaizen philosophy of continuous improvement (改善 — kai change, zen better) as an executable step, powered by the packaged kaizen skill (authored by Juan Carlos Cadavid, inspired by the Kaizen Institute glossary, Robert Maurer's small-steps method, and INTI's Emprendiendo Kaizen). Every /akili-archive automatically runs a bounded retrospective — no extra command, no extra ceremony:

┌─────────┐    ┌─────────┐    ┌──────────────┐    ┌──────────┐
│ MEASURE │ ─▶ │  LEARN  │ ─▶ │ STANDARDIZE  │ ─▶ │  REPEAT  │
│ rework, │    │ 0–3 root│    │ constitution │    │ next spec│
│ pivots, │    │ -cause  │    │ templates,   │    │ reads the│
│ bugs    │    │ lessons │    │ guides (HITL)│    │ lessons  │
└─────────┘    └─────────┘    └──────────────┘    └──────────┘
        every /akili-archive · logged in docs/specs/kaizen-log.md

• Measure: hunt MUDA (waste) in the spec's own evidence — Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation warnings, drift.
• Learn: distill 0–3 lessons with a named root cause and cited evidence (Gemba: real facts, never speculation). Generic lessons are banned.
• Standardize: propose 1–3 line edits to constitution guides, spec templates, design tokens, or agent personas — always human-approved. Small steps, never rewrites.
• Record: append to the accumulative docs/specs/kaizen-log.md; a capped ## Active Lessons digest is then read by /akili-propose, /akili-specify, and /akili-execute so past mistakes shape new work, and shown by /akili-resume.

The loop improves on two levels: Product lessons harden the project you are building, while Methodology lessons (root causes in AKILI itself) are flagged for upstreaming — so the methodology learns from every tool built with it. This is the meaning behind the name: akili is Swahili for intelligence, and intelligence that does not learn is not intelligence.

Spec Folder Shape

Each feature or change should live in one folder:

docs/specs/<spec-path>/
├── proposal.md           # created by /akili-propose, optional but recommended
├── requirements.md
├── design.md
├── tasks.md
├── execution.md          # created by /akili-execute
├── test-report.md        # created by /akili-test
├── validation-report.md  # created by /akili-validate
└── archive-summary.md    # created by /akili-archive before moving

Choose paths that describe the domain and intent:

docs/specs/loan/
docs/specs/enhancements/renewals/
docs/specs/admin/user-management/
docs/specs/bugfix/login-redirect/
docs/specs/changes/add-remember-me/

When /akili-propose add-remember-me receives a bare change name, it defaults to docs/specs/changes/add-remember-me/. When it receives a nested path such as bugfix/login-redirect, it uses that path directly.

Requirement Delta Preview

Proposals can include a lightweight delta preview. This makes reviews faster for brownfield work:

## Requirement Delta Preview

### ADDED Requirements

- The system SHALL allow users to opt into extended sessions.

### MODIFIED Requirements

- Session expiration changes from a fixed timeout to configurable timeout policies.

### REMOVED Requirements

- Legacy session persistence behavior is removed after migration.

During /akili-specify, these previews become full requirements, scenarios, design decisions, and tasks.

Writing Good Requirements

Write requirements as behavior contracts, not implementation plans.

Use this shape when possible:

### Requirement: Session Expiration

The system SHALL expire inactive user sessions after the configured timeout.

#### Scenario: Idle timeout

- GIVEN an authenticated user has an active session
- WHEN the session remains inactive past the configured timeout
- THEN the system invalidates the session
- AND the user must authenticate again before accessing protected pages
- BUT it must NOT invalidate the session if a keep-alive ping was received
- AND IT MUST log the expiration event in the audit trail

Good requirements are:

• observable by a user, system, API client, or operator
• measurable enough to test
• equipped with rigorous negative constraints (BUT it must NOT) and strict validations (AND IT MUST) for boundary cases
• independent from internal class names or library choices
• linked to at least one implementation task
• covered by test evidence or an explicit accepted gap

Review Points

Before implementation, review:

• whether the problem and scope are clear
• whether every requirement has at least one scenario
• whether design decisions explain trade-offs instead of only listing files
• whether tasks are small enough to execute independently
• whether every task has verification criteria

Before completion, review:

• whether all intended tasks are complete
• whether tests cover the key scenarios
• whether validation found unresolved failures
• whether the spec should be updated based on implementation discoveries

Practical Example

For a new admin user-management feature:

/akili-constitution
/akili-propose admin/user-management
/akili-specify admin/user-management
/akili-execute admin/user-management
/akili-test admin/user-management
/akili-validate admin/user-management
/akili-archive admin/user-management

For a small login redirect bugfix in an established repo:

/akili-specify bugfix/login-redirect
/akili-execute bugfix/login-redirect
/akili-test bugfix/login-redirect
/akili-validate bugfix/login-redirect
/akili-archive bugfix/login-redirect

For a reviewable named change using the default changes/ path:

/akili-propose add-remember-me
/akili-specify changes/add-remember-me
/akili-execute changes/add-remember-me
/akili-test changes/add-remember-me
/akili-validate changes/add-remember-me
/akili-archive changes/add-remember-me

Planned Improvements Inspired By OpenSpec

OpenSpec has useful ideas that fit this methodology well. Some are now supported through /akili-propose and /akili-archive. Remaining planned improvements:

See OpenSpec Comparison for the current AKILI comparison and documentation-pattern notes.

• automated sync lifecycle for completed specs
• schema-style workflow templates for feature, bugfix, migration, SEO, and research-first work
• broader command portability beyond Claude-specific command files

Auxiliary commands

• /akili-audit — Detect and report drift between the project's specifications (PRD, UX/UI Design, TRD) and the actual implementation. Produces docs/specs/drift-report.md with a conformance score, categorized discrepancies (High/Medium/Low), a conformance matrix, and recommended remediation paths. Run independently or after major implementation milestones.

• /akili-resume — Resume work after a session break by scanning all active specs under docs/specs/ and presenting a multi-spec dashboard. Shows current phase, progress bars, last action, blockers, and recommends the next command. If only one spec is active, goes directly to a detailed briefing. No arguments required.

• /akili-seo <site-domain> — SEO setup & audit via Google Search Console. Verifies a domain through DNS TXT using a service account, adds the property to GSC, then audits index coverage, sitemaps, structured data, search analytics, server-side render, internal linking, and on-page SEO (titles, metas, headings, canonicals, hreflang) using the packaged seo-audit skill. Produces seo-setup-report.md and seo-audit-report.md under docs/specs/seo/<domain>/, including a copy-paste implementation prompt for fixing every High-severity finding.

  Dependencies bundled with this repo:

  • scripts/gsc_verify.py — Site Verification API helper (token + verify), because the gsc MCP only wraps Search Console, not Site Verification.
  • .mcp.json.example — reference MCP server entry for @mikusnuz/gsc-mcp.

  Setup once per environment:

  1. Enable Site Verification API and Search Console API in your Google Cloud project.
  2. Create a service account, download its JSON key, store outside the repo.
  3. Install Python deps: pip install google-auth google-api-python-client.
  4. Copy the gsc block from .mcp.json.example into your global ~/.claude.json (or a project .mcp.json) and set GSC_SERVICE_ACCOUNT_KEY_PATH to the absolute path of the key.

Spec Paths

Commands accept a relative path under docs/specs/, not only a flat module name.

Examples:

• loan
• enhancements/renewals
• admin/user-management

Dependencies

Included skills cover the default methodology path, including ui-ux-pro-max.

Fallback rule:

• when ui-ux-pro-max is unavailable, use frontend-design + stitch-design for UX/UI design work and frontend-design for UI validation/testing support.

Skill governance: the skill set is curated, not accumulated. Every packaged skill declares its original author and license plus how AKILI binds it into the flow (core — hard-wired to a command step; conditional — loaded when the work touches its domain; stack — selected per project via the ## Skill Map that /akili-constitution writes into the project guides). New skills enter only through the acceptance checklist in docs/skills/governance.md. Curation and adaptation by Juan Carlos Cadavid, always preserving original authorship.

Methodology Contract

• User-Facing Summaries: All major commands (/akili-propose, /akili-specify, /akili-execute, /akili-validate, /akili-test, /akili-constitution) generate a short, digestible summary on the screen before proceeding to the next step, ensuring developers always understand what the agent just did.
• /akili-constitution establishes the project baseline docs (docs/prd.md, docs/ux-ui/design.md, docs/trd/trd.md, docs/infrastructure.md) and docs/specs/general-setup/ templates, and scaffolds the project .agents/ harness (Leader, Implementer, Reviewer, Tester).
• /akili-propose creates a lightweight proposal before full specification. Evaluates massive instructions for Scope Chunking to split work into manageable modules. Integrates with Figma MCP and Jira MCP to extract visual context, requirements, and user stories.
• /akili-specify must follow those templates when generating module specs. Enforces Human-in-the-loop (HITL) approval pauses after Requirements, Design, and Tasks. Promotes rigorous BDD scenarios (BUT it must NOT, AND IT MUST), allows blind adversarial design reviews via the judgment-day skill, outputs a final Lines of Code (LOC) estimate to recommend a safe Pull Request strategy, and explicitly injects Design Impact rules (from Figma contexts) into UI tasks and components.
• /akili-execute orchestrates a Leader → Implementer → Reviewer rework loop (max 3 retries) to implement tasks from an approved spec path.
• /akili-test runs a Leader → Tester(s) harness: the Leader partitions testing into suites and delegates each to a Tester subagent (inline for trivial/Lite work; one Tester per independent suite, in parallel, otherwise). It validates requirement-to-test traceability, explicitly checking for negative constraints and strict boundaries.
• /akili-validate audits implementation conformance against the spec (including rigorous boundary validations) and constitutional baseline.
• /akili-archive preserves completed specs under docs/specs/archive/ after validation, runs the Kaizen retrospective (measure → learn → standardize → record) appending to docs/specs/kaizen-log.md, syncs agent guides (child CLAUDE.md/AGENTS.md + the parent ## Module Guides index) from the spec's ## Constitution Impact notes, and recommends a CodeGraph re-index.
• /akili-seo operates outside the main spec lifecycle: it provisions Google Search Console ownership for a domain and produces a standalone SEO audit under docs/specs/seo/<domain>/. Run it any time after deployment; rerun after major content or schema changes.

Multi-Agent Harness Engineering

/akili-execute and /akili-test are not single-agent scripts. Each is a coordinated set of specialized roles that share the same spec, the same constitution, and the same audit trail. The harness exists to remove confirmation bias from review and testing (an independent auditor/tester instead of the same agent that wrote the code), to keep each role's context window small and focused, and to enforce design-token and constitutional discipline through a hard PASS/FAIL gate.

Roles live in the project's .agents/ directory (scaffolded by /akili-constitution):

The Leader runs each task through this loop:

Leader picks the next task → spawns Implementer with task + persona
Implementer writes code and runs verification → reports back
Leader extracts git diff → spawns Reviewer with diff + persona
Reviewer emits STATUS: PASS or STATUS: FAIL

if PASS  → update tasks.md, append execution.md, commit, advance
if FAIL  → log feedback; if attempts < 3, respawn Implementer with the Reviewer's findings
if 3 consecutive FAILs → HALT, mark task [~], present full audit trail for human guidance

Guardrails:

• Maximum retries. A hard ceiling of 3 rework attempts per task prevents infinite loops and token waste.
• Structured feedback. The Reviewer's report is passed back unchanged to the next Implementer spawn — no paraphrasing.
• Pivot protocol. If discovery proves the spec itself is wrong (not the implementation), the loop stops immediately and a ## Pivot Record is opened in execution.md for user sign-off — rework retries are not consumed on a broken spec.
• Cross-tool. .agents/ is pure Markdown + YAML frontmatter and is resolved relative to the active workspace, so the same harness runs under Claude Code, OpenCode, and Google Antigravity (the latter invokes invoke_subagent using the same persona files).

/akili-test — Leader → Tester(s): The same Leader pattern drives testing, but delegation is token-aware. The Leader partitions the work into suites and applies a Deployment Rule: Lite depth or a single trivial suite runs inline (no subagent spawn — spawning would cost more tokens than it saves); Standard/Full depth or multiple independent suites get one Tester per suite, spawned in parallel when they touch different files, and sequentially when they share files/fixtures. Each Tester receives only its suite's requirements, scenarios, and test command — never the full spec set — and its context is discarded on completion, so per-suite contexts never accumulate. A Tester runs a bounded 3-attempt inner loop and distinguishes a test defect (fix the test) from a product defect (keep the test red, report PRODUCT_BUG). Ideally a Tester runs on a different model than the Implementer that wrote the code (author ≠ tester).

/akili-constitution classifies the repository into one of three modes and seeds .agents/ accordingly:

Capability-Tier Model Routing

Not every model is best at every job. AKILI routes each AKILI-SPECS phase to the model matched to its dominant demand using six capability tiers — Architect, Coder, Auditor, Context-Ingest, Fast-Cheap, and Multimodal. A single editable registry binds each tier to a concrete model per tool, so model upgrades are a one-line edit rather than a rewrite.

This is guidance-first and model-agnostic: no model: frontmatter is added to commands and the installer injects nothing. You switch models yourself (Claude Code /model, OpenCode model selector), and /akili-constitution scaffolds a ## Model Routing registry into each project's AGENTS.md / CLAUDE.md.

Key principles: ARCHITECT = BUILDER (the model that designs also builds), author ≠ auditor (the Reviewer runs on a different model than the Implementer), reserve deep-reasoning models for /akili-propose and /akili-validate, and use fast/cheap models for the tasks split and /akili-archive.

See docs/model-routing.md for the tiers, the full phase→tier mapping, and the default registry for Claude Code (PRO) and OpenCode Go.

Host Assumptions

• The host Claude environment can ask follow-up questions to the user during command execution.
• The host environment can load local skills referenced by the commands.
• Repository-specific build, lint, and test commands should be preferred over hardcoded stack assumptions.

Notes

• Commands were sourced from the current global Claude command setup.
• Skills were copied with their bundled references and helper assets.
• This repository stores the current methodology baseline so it can be reused or versioned independently.
• Dotfiles are snapshots of the working environment and may include plugin source copies for portability.

Authorship

The AKILI-SPECS methodology is created and maintained by Juan Carlos Cadavid — jcadavid.com.

Every command in .claude/commands/ and every agent role template in .claude/templates/ carries this authorship notice. The project is released under the MIT License: you are free to use, modify, and redistribute it, provided the copyright and attribution notices are kept intact.