Agent Guidance

This repository packages the AKILI-SPECS methodology for Claude Code, OpenCode, Google Antigravity, OpenAI Codex CLI, Cursor, and Grok Bot.

Repository Purpose

• .claude/ is the canonical source for all six install targets (Claude Code, OpenCode, Antigravity, Codex, Cursor, Grok Bot), not Claude-only config — the installer maps it into each tool's layout, and it lives at that literal path because this repo dogfoods its own methodology in Claude Code sessions. There is no per-tool copy: edits for any target happen here.
• .claude/commands/ contains installable AKILI-SPECS command prompts.
• .claude/skills/ contains installable methodology skills.
• .claude/templates/ contains the default Leader, Implementer, Reviewer, and Tester personas used by the AKILI multi-agent harness, each fenced into AKILI-owned sections (<!-- akili:section id=… since=… -->) with one project block, plus digests.json — the per-release section-hash table scripts/release.js writes and akili doctor --agents reads. /akili-constitution copies the personas into each project's .agents/ directory; akili doctor --agents --fix upgrades deployed copies section by section (see docs/cli.md → Persona Drift).
• bin/akili.js installs commands, skills, and helper resources (including the agent templates and digests.json) into Claude Code, OpenCode, Google Antigravity, OpenAI Codex CLI, Cursor, and Grok Bot config directories, runs doctor --agents against a project's .agents/, and runs akili routing (the model-routing configurator /akili-constitution Step 8C delegates to).
• bin/routing.js is the pure module behind akili routing (flag grammar, tier derivation, registry-section rendering, the six-state AGENTS.md fence replacer, the five host wrapper shapes, buildPlan, and the collectAnswers prompt seam, and the pure keyboard-select reducer behind the interactive prompts); bin/akili.js only collects answers, snapshots the project, and applies the plan. Its inputs ship under .claude/templates/ as model-registry.json and model-routing.section.md, read from the package directory and never installed into a target.
• bin/persona.js holds the pure persona functions behind doctor --agents (parsePersona, sectionStates, applyFix, migratePersona, the digest helpers); bin/akili.js and scripts/release.js require it. test/ holds the node:test suite and its fixtures (npm test; .gitattributes keeps test/fixtures/** byte-exact so CRLF and LF fixtures survive any checkout; test/routing-pty.test.js drives the CLI on a real pseudo-terminal through expect — present on macOS, installed by the Linux CI step, absent on Windows where the suite skips with a printed reason; a failed run's transcripts are kept under AKILI_PTY_LOG_DIR and uploaded by the Linux CI legs as pty-transcripts-*); it is not shipped in the package.
• scripts/ contains helper scripts, including scripts/release.js, which prepares controlled npm package releases.
• Read docs/release-checklist.md before preparing or publishing a package release.
• This repository holds the methodology only and has no cloud infrastructure. The hosted AKILI MCP service lives in a separate private repository: do not add MCP server, AWS or deploy code here.
• README.md documents installation and methodology usage.
• Default Branch: master
• Integration Branch: dev

Development Rules

• Keep command prompts readable and tool-agnostic where possible.
• Do not add project-specific assumptions to reusable commands.
• Keep installer behavior safe: skip existing files by default and require --force to overwrite.
• Branch model: master and dev are protected: changes land only through a pull request with 0 approvals, the six CLI on <os> / Node <18|22> checks green and the branch up to date, enforced for admins too. feat/<name> and fix/<name> branch from dev and open their PR into dev. Agents never commit to or push dev or master directly.
• Do not commit generated .tgz files or node_modules/.
• Do not commit service account keys, npm tokens, .npmrc, or local MCP config containing secrets.
• Spec-to-Code Traceability: Every commit made during /akili-execute must be prefixed with [SPEC:<spec-path>] (e.g. [SPEC:changes/add-remember-me] message). Trivial fast-tracked changes made via /akili-quick use the [SPEC:quick/<name>] prefix plus a one-line entry in docs/specs/quick/quick-log.md.
• Trivial Fast-Track (/akili-quick): Genuinely trivial, low-risk changes (copy edits, color/spacing tweaks using existing design tokens, small static text additions) may skip the full specify → execute → test → validate flow via /akili-quick, which makes the edit in one step and records minimal traceability. It has a strict triviality gate (cosmetic/copy-only, no behavior/data/API/auth/contract change, ≤ ~20 LOC in one component, not a video composition, design-token safe) and must auto-escalate to /akili-specify (Lite) or /akili-propose when a change exceeds that gate. Never route real features or logic changes through /akili-quick.
• Request Classification & Bug Handling: /akili-propose is the single entry point that classifies each request as Bug, Change, or Trivial (inferring from the request, asking one question if ambiguous) and routes it — the methodology adds no per-type command. Bugs follow a Bug Track: diagnose first (reproduction + confirmed root cause via systematic-debugging) in the proposal's Bug Diagnosis section, then /akili-specify runs in Bug Mode, which frames requirements around the corrected behavior and requires a regression test (red before the fix, green after). A purely cosmetic bug may still use /akili-quick; never propose a fix for a guessed root cause.
• Pivot Protocol: If execution invalidates approved specs, the agent must mark tasks blocked ([~]), record pivot details in execution.md, and obtain user sign-off.
• Drift Auditing: Run /akili-audit to detect differences between active codebase reality and the active UX/UI design and TRD.
• CodeGraph Re-indexing: Remind or execute the re-indexing command during /akili-archive to keep CodeGraph databases healthy.
• Agent Guide Inheritance: Root CLAUDE.md/AGENTS.md are the parent; modules with divergent conventions carry thin child guides referenced from a ## Module Guides index in the parent. /akili-execute records ## Constitution Impact notes when tasks create or reshape modules; /akili-archive syncs the guides and the CodeGraph; /akili-audit flags guide drift.
• Multi-Agent Harness: /akili-execute runs each task through a Leader → Implementer → Reviewer loop with a hard 3-attempt rework ceiling; the Reviewer is owed unless the task clears the Review intensity predicate (/akili-execute Step 2.3), and the non-author evidence re-run is never waived. /akili-test runs a Leader → Tester(s) harness where 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), each with a bounded self-correction inner loop and a PASS/FAIL/PRODUCT_BUG output contract. Personas live in .claude/templates/ (source) and project .agents/ (deployed by /akili-constitution). Do not collapse these loops back into a single-agent flow.
• Kaizen Loop (two-phase, branch-safe): /akili-archive runs a bounded retrospective (measure → learn → standardize → record) on every archive via the packaged kaizen skill. The retrospective phase runs on any branch and writes one entry file per spec at the target project's docs/specs/kaizen/<safe-spec-slug>.md, recording each proposed standardization as a pending item. The apply phase runs only on the apply-capable branch (the default branch, or the pinned integration branch when one exists — never both) — reached through the skill's Apply Mode ("apply pending kaizen standardizations"), offered automatically by /akili-archive when it already runs there, and surfaced by /akili-resume — where the HITL menu fires, each approved item is re-verified before writing (a refuted one closes as superseded instead), approved edits to shared files are made, and the ## Active Lessons digest in docs/specs/kaizen-log.md is refreshed; that apply phase is the digest's single writer, and the log's legacy ## Entries section is frozen. Lessons require a root cause + cited evidence; no shared file is ever edited from a spec branch, or from the default branch while an integration pin exists, approved or not; /akili-propose, /akili-specify, /akili-execute, and /akili-resume read only the ## Active Lessons digest. Lessons whose root cause is AKILI itself are recorded as a Kind: upstream pending item and collected into an upstream report at apply time, flipping to upstreamed — apply the same loop when iterating this repo (dogfooding), where Apply Mode runs on an up-to-date dev checkout, its uncommitted edits move to a kaizen/apply-<YYYY-MM-DD> branch with git switch -c before the commit, and they land through a PR into dev. Do not add a separate kaizen command: Apply Mode is an activation of the existing skill.
• Concurrency: one AKILI session per checkout. Additional sessions run on git worktree — this is the conflict case the Delegation Thresholds isolation rule names, and the only one that earns a separate checkout. Two sessions in one tree interleave commits, overwrite each other's tasks.md transitions, and append to the same execution.md until the audit trail stops being an account of what happened. Separately: never run a measurement command — build, benchmark, Lighthouse, E2E — while a delegated agent is active. Measuring feels passive and is not: it competes for node_modules, ports, lockfiles, and build output, so a measurement taken beside a running Implementer is not slow but wrong, and it surfaces as an inexplicable worker error rather than as your own action. Measure in the window after the completion report, when the tree is quiet. Under parallel sessions, commit-message discipline also stops being cosmetic — the message becomes the only surviving record of which session did what, so never let reasoning narration land as a commit message.
• Scope only grows through approval. An ADVISORY finding is recorded and dies there: it may never become a new task in the running spec, and no existing task may be widened to absorb it. Advisories are the least-vetted output of a run, so that path grows scope fastest from the weakest evidence — and a task absent from the approved tasks.md carries no requirement, no design decision, and no budget line. An advisory that genuinely cannot wait is a spec gap: escalate via the Pivot Protocol so the user reopens the spec, rather than routing around the approval gate.
• Skill Governance: the packaged skill set is curated, not accumulated. Every skill under .claude/skills/ declares original author + license and a metadata.binding level — core (hard-wired to a command step), conditional (loaded when the work touches its domain, e.g. UI or animation), or stack (never referenced in command text; reaches agents via the project ## Skill Map scaffolded by /akili-constitution Step 8D and per-task skill lists in tasks.md). New skills must pass the acceptance checklist in docs/skills/governance.md (need + binding + attribution + size + docs/CHANGELOG); a skill referenced by no command and no Skill Map is dead weight and must be removed or re-bound. Adaptation preserves original authorship (adapted-by, never replacing author).
• Model Routing: enforced for subagents, guided for the main loop. Model selection per AKILI-SPECS phase is documented in docs/model-routing.md (capability tiers + a per-tool registry) and scaffolded into each project's root AGENTS.md by /akili-constitution (Step 8C, which runs akili routing). Never add a model: key to command frontmatter and never inject models in the installer — akili routing writes them only at the user's request, into agent wrappers and the project registry, never into commands; a single value cannot serve both Claude Code (opus/sonnet/haiku) and OpenCode (provider/model), and it would break the model-agnostic install. Enforced bindings live only in the Step 8E tool-native agent wrappers (.claude/agents/akili-*.md / OpenCode agent config / .agents/agents/akili-*/agent.md for Antigravity / .codex/agents/akili-*.toml for Codex / .cursor/agents/akili-*.md for Cursor), which pin each persona to its tier's model where the host has a wrapper value for that pick (an Antigravity Gemini 4 Argon pick has none, so that role is skipped and reported); /akili-execute and /akili-test prefer those named agents when present. The Reviewer must run on a different model than the Implementer (author ≠ auditor). Alias-first rule: registries use floating aliases (opus/sonnet/haiku) wherever they exist so model generations change without edits; dated pins require a recorded reason. Commands emit a one-line, never-blocking model checkpoint in their setup step. /akili-audit reports Model Registry Drift; each release refreshes the default registry in docs/model-routing.md.

Skill Usage

When working on tasks in this repository or when using the installed AKILI-SPECS methodology, load and apply the relevant available skills before implementation.

Use the packaged skills in .claude/skills/ as the source of truth. Examples:

• Use systematic-debugging for bugs, test failures, and unexpected behavior.
• Use tdd for test-first implementation of logic-heavy tasks (algorithms, business rules, contracts); the /akili-execute Leader assigns it per task — expected values come from requirements.md scenarios, seams from design.md.
• Use video-production for specs whose Document Control records Deliverable: video; it runs the availability gate for the environment-provided hyperframes skills and maps video activities to AKILI phases (read the matching references/ file for the task).
• Use judgment-day for blind adversarial design reviews during /akili-specify.
• Use kaizen for continuous-improvement retrospectives; /akili-archive loads it in its Kaizen Retrospective step.
• Use software-architect for TRD creation, NFR/quality-attribute identification, architecture style and pattern selection, and robust-vs-lite stack sizing; /akili-constitution loads it in its TRD step and /akili-specify for architecturally significant designs (read only the matching references/ file per task).
• Use diagram-design when a baseline doc (PRD, UX/UI design, TRD) or an architecturally significant design.md carries diagram slots: inline Mermaid is canonical, and an Archify interactive view is linked only when the archify skill is installed; /akili-constitution Steps 3–5, /akili-specify Step 2.1, and /akili-archive Step 2 load it.
• Use cognitive-doc-design when writing human-facing docs (PRD, TRD, requirements, reports, PR descriptions): lead with the answer, progressive disclosure, tables over prose.
• Use caveman for transient agent output only (inter-agent messages and progress narration in /akili-execute and /akili-test): compress style, never documents, HITL gates, or verbatim evidence — cognitive-doc-design owns artifacts; caveman owns transient agent output.
• Use react-doctor and vercel-react-best-practices for React/Next.js changes.
• Use angular-developer for Angular projects, components, services, routing, forms, signals, SSR, accessibility, styling, animations, testing, and CLI tooling.
• Use domain skills such as nestjs-expert, aws-serverless, api-design-principles, or product-manager-toolkit when the task matches.
• Use seo-audit for SEO audits and diagnosis; /akili-seo loads it in its audit phase.
• Use security-audit for repository vulnerability discovery; /akili-security loads it (full audit mode); guidance mode for focused security questions.
• Use social-marketing for social media drafting (LinkedIn, Instagram, Facebook): brand voice, campaigns, calendar and posts; /akili-marketing loads it, and it drafts only, never publishes.
• Use pr-review for read-only pull-request and diff review (lenses, verified findings, one summary comment); /akili-review loads it, and it reviews only, never editing, approving or blocking.

If a task document lists required or recommended skills, follow that list first.

Design Skills

Impeccable decides what and why; the stack decides how. One lead skill per activity; the environment picks the column, the activity the row. Direction is settled before /akili-execute, which builds code-led. Every UI task ends with polish, and the AKILI Reviewer stays the gate.

• impeccable — lead design skill: direction, craft floor, critique, audit, polish (vendored, verbatim).
• impeccable-bridge — AKILI layer: engine gate, phase map, design source of truth, routing matrix.
• ui-ux-pro-max — reference catalog: palettes, font pairings, UX rules.
• frontend-design — fallback for direction and craft when Impeccable is missing (ENV-0 lead only).
• stitch-design — Stitch mockups and screen generation, on request.
• gsap-animation — GSAP motion and scroll-driven animation work.
• tailwind-design-system — Tailwind v4 tokens and component patterns.
• shadcn-ui — shadcn/ui component implementation.

The routing matrix is .claude/skills/impeccable-bridge/references/design-routing.md.

Backend Skills

The method skill decides what and why; the stack skill decides how in this language or framework. One lead per activity and context; supporting skills give inputs, not rules. Stack skills reach agents through the project ## Skill Map and per-task skill lists.

• software-architect — style, NFR scenarios, tactics, patterns, ADRs, robust-vs-lite sizing.
• api-design-principles — REST and GraphQL resource model, versioning, pagination, error responses.
• error-handling-patterns — error-handling philosophies, error categories, circuit breaker, graceful degradation.
• tdd — red-green loop, seams, test anti-patterns (assigned by the Leader).
• systematic-debugging — root cause before fix, four phases.
• nestjs-expert — stack skill: Nest modules, DI, controllers, guards, Jest/Supertest; leads implement on NestJS.
• golang-pro — stack skill: concurrency, interfaces, generics, error wrapping, pprof, table-driven tests; leads implement on Go.
• aws-serverless — stack skill: Lambda handler, API Gateway, SQS patterns, serverless anti-patterns; leads implement on AWS serverless.
• ai-agent-development — stack skill: agent framework and runtime selection, hosting, state, tools, memory, HITL; leads framework-selection for agents.

The routing matrix is .claude/skills/software-architect/references/backend-routing.md.

CodeGraph

This repository has CodeGraph initialized under .codegraph/ for faster semantic code exploration.

• Use CodeGraph for existing-project analysis, symbol lookup, call flow, and impact checks when .codegraph/ exists.
• Do not commit generated CodeGraph database files; .codegraph/.gitignore excludes local database artifacts.
• Keep .codegraph/config.json focused on repository source and methodology scripts, not large snapshots or generated outputs.
• If CodeGraph is unavailable in another project, continue with normal Glob, Grep, and file reads.

Release Rules

Repository changes do not automatically update the npm package. A package update requires a version bump and publish.

Release governance:

• Do not publish directly from uncommitted changes.
• Every package-affecting repo change must have CHANGELOG.md notes before release preparation.
• Every stable npm update must use scripts/release.js through npm run release:patch, npm run release:minor, or npm run release:major. Prereleases use npm run release:next only (see Prereleases (next)).
• Publish only after verification passes and npm authentication is confirmed for a package maintainer.
• Do not claim npm is updated until npm publish succeeds and a post-publish smoke test confirms the published version.
• If publish fails, keep the release commit, document the blocker, and do not create a replacement version unless the failed version was actually published.
• Use npm run release:status before and after publishing to detect drift between npm, tags, GitHub Releases, and local release files.
• Keep the Release Status GitHub Actions workflow aligned with npm run release:status.

Use this flow (feat/<name> / fix/<name> → dev → master; nothing is committed or pushed to dev or master directly, admins included):

1. Add change notes under CHANGELOG.md > Unreleased; they land on dev through feature PRs.

2. Prepare the release: cut release/vX.Y.Z from an up-to-date dev, then run one of:

   • npm run release:patch
   • npm run release:minor
   • npm run release:major

   Run verification:

   • npm run verify:cli
   • npm run pack:dry-run
   • npm run release:status
   • git diff --check

   Commit the release version update on that branch — the script's git add hint also names .claude/templates/digests.json (the new dense releases entry) and any template whose since= marker it rewrote — and open a PR into dev.

3. Open a PR dev → master and merge it with a merge commit.
4. After it merges, on an up-to-date master, in this order:
   • git tag vX.Y.Z, then git push origin vX.Y.Z
   • confirm npm auth with npm whoami --registry=https://registry.npmjs.org/
   • publish explicitly with npm publish --access public --registry=https://registry.npmjs.org/
   • verify npm view akili-specs dist-tags in its own command
   • gh release create
   • smoke test the published version with npx akili-specs@<version> list
5. Resync dev: branch sync/master-into-dev from dev, run git merge origin/master, open a PR into dev, and merge it with a merge commit. Squash or rebase here would leave master's merge commit outside dev, so the next dev → master PR would not be up to date.

Prereleases (next)

To let users try dev before a stable release, start from an up-to-date dev (on dev, clean working tree, HEAD equal to origin/dev):

1. npm run release:next -- <patch|minor|major> --dry-run and read the plan.
2. Run the same command without --dry-run (optional --otp=<code>).

It publishes X.Y.Z-next.N with --tag next and never touches latest. The version is written to package.json only for the duration of the publish and is never committed. Try it with npm i akili-specs@next.

Use patch for small docs/fixes, minor for new commands or install targets, and major for breaking changes.

Verification

Before committing package or installer changes, run:

npm test
npm run verify:cli
npm run pack:dry-run
git diff --check

When installer behavior changes, also test temporary targets:

node bin/akili.js install --tool all --dry-run
node bin/akili.js doctor --tool all