akili-specs 2.1.0

package/docs/commands/akili-test.md

@@ -0,0 +1,65 @@
+# `/akili-test`
+
+Run or create tests for a spec path and produce requirement-level evidence.
+
+## Usage
+
+```text
+/akili-test <spec-path>
+```
+
+## Use When
+
+- Implementation tasks are complete or ready for verification.
+- You need a requirement-to-test matrix.
+- Manual gaps must be documented explicitly.
+
+## Inputs
+
+Reads:
+
+- `docs/specs/<spec-path>/requirements.md`
+- `docs/specs/<spec-path>/design.md`
+- `docs/specs/<spec-path>/tasks.md`
+- project-level constitution docs and agent guidance
+
+## Outputs
+
+Creates or updates:
+
+```text
+docs/specs/<spec-path>/test-report.md
+```
+
+The report includes:
+
+- commands run and results
+- backend unit test evidence
+- frontend unit test evidence
+- integration test evidence
+- E2E test evidence
+- requirement-to-test matrix
+- scenario coverage status
+- failures and remediation
+- accepted gaps with reasons
+
+## Skills Commonly Used
+
+- `nestjs-expert`
+- `systematic-debugging`
+- `vercel-react-best-practices`
+- `react-doctor`
+- `ui-ux-pro-max`
+- `frontend-design`
+
+## Key Rule
+
+Testing must prove the behavior promised in `requirements.md`, not only increase test count.
+
+## Next Step
+
+After test evidence is recorded:
+
+```text
+/akili-validate <spec-path>
+```

package/docs/commands/akili-validate.md

@@ -0,0 +1,64 @@
+# `/akili-validate`
+
+Audit whether implementation matches the approved spec and constitutional baseline.
+
+## Usage
+
+```text
+/akili-validate <spec-path>
+```
+
+## Use When
+
+- Implementation and test evidence are ready for final conformance review.
+- You need a clear PASS/WARN/FAIL/BLOCKED report.
+- You want to know whether a spec is archive-ready.
+
+## Inputs
+
+Reads:
+
+- `proposal.md` when present
+- `requirements.md`
+- `design.md`
+- `tasks.md`
+- `execution.md` when present
+- `test-report.md` when present
+- constitution docs and agent guidance
+
+## Outputs
+
+Creates or updates:
+
+```text
+docs/specs/<spec-path>/validation-report.md
+```
+
+## Result Levels
+
+| Result | Meaning |
+|---|---|
+| PASS | Requirement, task, or check is satisfied with evidence |
+| WARN | Acceptable but risky, missing evidence, or minor drift |
+| FAIL | Does not satisfy the requirement, task, or check |
+| BLOCKED | Validation could not complete because context, tooling, or access is missing |
+
+## Checks
+
+- task completion and execution notes
+- expected file existence
+- build, lint, and type-check integrity
+- requirement coverage
+- test evidence summary
+- architecture and design conformance
+- UI/UX, API, security, accessibility, error handling, and observability as relevant
+
+## Next Step
+
+If archive-ready:
+
+```text
+/akili-archive <spec-path>
+```
+
+If not archive-ready, fix the critical findings or update the spec with accepted drift before archiving.

package/docs/flow.md

@@ -0,0 +1,255 @@
+# AKILI Flow
+
+AKILI keeps durable product, design, implementation, test, and validation context in repository files so agents do not have to infer the same project reality every session.
+
+The workflow is inspired by OpenSpec's artifact-guided pattern, but AKILI adds a project constitution step, Claude/OpenCode skills, and explicit validation evidence before archive.
+
+## Philosophy
+
+```text
+→ constitution before feature work
+→ reviewable intent before implementation
+→ behavior requirements before code
+→ small verified tasks over broad rewrites
+→ evidence before archive
+```
+
+## Primary Lifecycle
+
+```text
+You: /akili-constitution
+AI:  Creates or strengthens the project baseline:
+     ✓ docs/prd.md
+     ✓ docs/ux-ui/design.md
+     ✓ docs/trd/trd.md
+     ✓ docs/specs/general-setup/
+     ✓ CLAUDE.md and AGENTS.md
+
+You: /akili-propose add-remember-me
+AI:  Creates docs/specs/changes/add-remember-me/proposal.md
+     ✓ problem, scope, non-goals
+     ✓ affected systems
+     ✓ requirement delta preview
+     ✓ approach options and recommendation
+
+You: /akili-specify changes/add-remember-me
+AI:  Creates or updates:
+     ✓ requirements.md
+     ✓ design.md
+     ✓ tasks.md
+
+You: /akili-execute changes/add-remember-me
+AI:  Runs the Leader → Implementer → Reviewer harness on the next approved task
+     ✓ Implementer writes code and runs verification
+     ✓ Reviewer audits the diff and emits STATUS: PASS or STATUS: FAIL
+     ✓ Up to 3 rework attempts on FAIL, then HALT for human guidance
+     ✓ updates tasks.md
+     ✓ appends execution.md with full PASS/FAIL audit trail
+     ✓ commits with [SPEC:<spec-path>] and records verification evidence
+
+You: /akili-test changes/add-remember-me
+AI:  Creates test-report.md with requirement-to-test traceability (supports automated parsing via `scripts/parse_tests.js`)
+
+You: /akili-validate changes/add-remember-me
+AI:  Creates validation-report.md with PASS/WARN/FAIL/BLOCKED findings
+
+You: /akili-archive changes/add-remember-me
+AI:  Moves completed work into docs/specs/archive/ and refreshes CodeGraph
+
+Independent Auditing:
+You: /akili-audit
+AI:  Scans codebase and detects drift against baselines, generating docs/specs/drift-report.md
+```
+
+## Project Modes
+
+`/akili-constitution` begins by classifying the repository into one of three modes. Each mode adjusts how aggressively the constitution drafts, scans, or preserves existing material — and how the project `.agents/` harness is scaffolded.
+
+| Mode | Meaning | Constitution Behavior | `.agents/` Behavior |
+|---|---|---|---|
+| Brand-new (Seed Setup) | Little or no application code, no AKILI-SPECS docs, starting from scratch | Draft baseline from user intent, chosen stack, assumptions, and open questions | Copy default Leader / Implementer / Reviewer personas verbatim |
+| Legacy (Discovery Setup) | Real code, package manifests, routes, tests exist; AKILI-SPECS baseline missing or skeletal | Inspect repository reality (CodeGraph preferred) before drafting; synthesize baseline from evidence | Copy defaults then customize with detected stack, design tokens, lint and test commands |
+| Active AKILI-SPECS (Safe Update) | AKILI-SPECS baseline and possibly customized `.agents/` already in place | Upgrade weak sections, fill missing files, preserve custom rules | Never overwrite existing personas — append only the minimal upgrade blocks needed |
+
+For Legacy and Active-AKILI-SPECS modes, CodeGraph is preferred when `.codegraph/` exists. If CodeGraph is missing but the CLI is available, the agent should ask before running `codegraph init -i`. If CodeGraph is unavailable or declined, normal file and content searches are used.
+
+## Artifacts
+
+| Artifact | Created By | Purpose |
+|---|---|---|
+| `docs/prd.md` | `/akili-constitution` | Product purpose, personas, goals, scope, success metrics |
+| `docs/ux-ui/design.md` | `/akili-constitution` | UX system, flows, screen inventory, tokens, accessibility expectations |
+| `docs/trd/trd.md` | `/akili-constitution` | Technical architecture, modules, data, APIs, integrations, testing strategy |
+| `docs/specs/general-setup/` | `/akili-constitution` | Project-specific templates for future specs |
+| `docs/specs/<spec-path>/proposal.md` | `/akili-propose` | Reviewable intent, scope, options, and risks |
+| `docs/specs/<spec-path>/requirements.md` | `/akili-specify` | Behavior contracts and scenarios |
+| `docs/specs/<spec-path>/design.md` | `/akili-specify` | Implementation approach and trade-offs |
+| `docs/specs/<spec-path>/tasks.md` | `/akili-specify` | Small executable tasks with verification |
+| `docs/specs/<spec-path>/execution.md` | `/akili-execute` | Task execution history and evidence |
+| `docs/specs/<spec-path>/test-report.md` | `/akili-test` | Requirement-to-test matrix and coverage gaps |
+| `docs/specs/<spec-path>/validation-report.md` | `/akili-validate` | Final conformance audit |
+| `docs/specs/drift-report.md` | `/akili-audit` | Conformance auditing of documentation vs. codebase reality |
+| `docs/specs/archive/.../archive-summary.md` | `/akili-archive` | Historical closure record |
+
+## Review Gates
+
+AKILI keeps humans in control at each important transition.
+
+| Gate | Before Moving On, Confirm |
+|---|---|
+| Constitution | Baseline docs reflect the actual product and architecture |
+| Proposal | Problem, scope, non-goals, and recommended approach are approved |
+| Requirements | Observable behavior and scenarios are testable |
+| Design | Technical approach fits the current repository |
+| Tasks | Work is small enough to execute and verify incrementally |
+| Execution | Each completed task has verification evidence |
+| Testing | Key requirements have automated or accepted manual evidence |
+| Validation | No unresolved FAIL findings remain |
+| Archive | Warnings and follow-ups are accepted |
+
+## Documentation Depth
+
+Use the lightest documentation that still makes the work clear and verifiable.
+
+| Depth | Use For | Capture |
+|---|---|---|
+| Lite | Small bugfixes, copy updates, narrow UI tweaks | Problem, scenario, focused task, verification command |
+| Standard | Normal features and enhancements | Requirements, scenarios, design decisions, tasks, tests |
+| Full | Risky, cross-cutting, API, data, auth, migration, or SEO work | Alternatives, rollout, risks, observability, rollback, explicit traceability |
+
+Lite mode does not skip rigor. Requirements still need scenarios, tasks still need done criteria, and validation still needs evidence.
+
+## Spec Folder Shape
+
+```text
+docs/specs/<spec-path>/
+├── proposal.md
+├── requirements.md
+├── design.md
+├── tasks.md
+├── execution.md
+├── test-report.md
+├── validation-report.md
+└── archive-summary.md
+```
+
+Common spec paths:
+
+```text
+docs/specs/changes/add-remember-me/
+docs/specs/enhancements/renewals/
+docs/specs/admin/user-management/
+docs/specs/bugfix/login-redirect/
+docs/specs/seo/example.com/
+```
+
+## Shortcut Paths
+
+For a small, obvious change in a repository with a strong baseline, you may start at `/akili-specify <spec-path>`.
+
+For unclear, risky, cross-functional, or stakeholder-sensitive work, start at `/akili-propose <change-name-or-spec-path>`.
+
+For a new repository, stale documentation, or a major product pivot, start at `/akili-constitution`.
+
+---
+
+## Advanced Engineering Capabilities
+
+To support robust, long-term development cycles, AKILI includes the following specialized workflows:
+
+### 1. Spec-to-Code Traceability (Git & Comments)
+To establish high-traceability between spec files and source code:
+* **Commit Messages:** Every commit made during `/akili-execute` must be prefixed with `[SPEC:<spec-path>]` (e.g. `git commit -m "[SPEC:changes/add-remember-me] implement secure cookie storage"`).
+* **Comment Tracing:** For complex algorithms, API entry points, or core models, developers/agents should place a reference comment: `// @akili-spec <spec-path>`.
+
+### 2. Specification Drift Auditing (`/akili-audit`)
+Run `/akili-audit` independently to verify that the active codebase reflects active documentation. The command produces `docs/specs/drift-report.md` detailing:
+* **Stale Specifications:** Documented endpoints/modules missing from code.
+* **Undocumented Code:** Active code additions completely missing from the PRD, UX/UI design, or TRD docs.
+* **Styling/Architecture Violations:** Active code violating styling tokens or engineering guidelines.
+* **Agent Guide Drift:** Modules lacking a needed child `CLAUDE.md`/`AGENTS.md`, child guides missing from the parent's `## Module Guides` index, or root-guide structure descriptions that no longer match the codebase.
+
+### 3. The Pivot Protocol
+If discovery during `/akili-execute` invalidates requirements or design rules:
+1. Mark the current task in `tasks.md` as `[~]` (blocked).
+2. Append a `## Pivot Record: <Task ID>` under `execution.md` explaining the conflict, technical constraints, and proposed options.
+3. Update `requirements.md`, `design.md`, and/or `tasks.md` in the spec folder.
+4. Obtain user sign-off on the pivot before resuming execution.
+
+### 4. CodeGraph Refresh Trigger
+When compiling the `archive-summary.md` and moving folders to the archive via `/akili-archive`:
+* The agent detects if `.codegraph/` configuration folders are present.
+* The agent reminds or executes the re-indexing command (e.g., `codegraph index`) to guarantee semantic search utilities remain highly functional for subsequent sessions.
+
+### 5. Automated Test Reporting (`scripts/parse_tests.js`)
+Rather than manually compiling assertion results during `/akili-test`:
+1. Execute tests outputting to JSON (e.g. `jest --json --outputFile=jest-results.json` or `vitest --reporter=json`).
+2. Run `node <path-to-akili>/scripts/parse_tests.js jest-results.json` to generate the AKILI matrix table automatically for inclusion inside `test-report.md`.
+
+### 6. Multi-Agent Harness (`/akili-execute` Triad)
+
+`/akili-execute` is implemented as a multi-agent orchestration rather than a single-agent script. The Leader role does not write production code; it delegates implementation and audit to two subordinate roles, then enforces a strict PASS/FAIL gate before the task advances.
+
+**Roles** — all three live in the project's `.agents/` directory, scaffolded by `/akili-constitution`:
+
+| Role | File | Responsibilities |
+|---|---|---|
+| Leader | `.agents/leader.md` | Picks the next eligible task, delegates work, enforces the rework loop, updates `tasks.md` and `execution.md`, commits with `[SPEC:<spec-path>]` |
+| Implementer | `.agents/implementer.md` | Writes code strictly within task scope, applies design tokens from `docs/ux-ui/design.md`, runs the verification command before reporting |
+| Reviewer | `.agents/reviewer.md` | Read-only diff audit against requirements, design tokens, and the TRD; outputs a structured PASS or FAIL with *Discovered Issue*, *Violated Rule*, and *Remediation Suggestion* |
+
+**Loop:**
+
+```text
+Leader picks the next task → spawns Implementer with task + persona
+Implementer writes code, runs verification → reports back
+Leader extracts git diff → spawns Reviewer with diff + persona
+Reviewer returns STATUS: PASS, STATUS: FAIL, or STATUS: FATAL_FAIL
+
+if PASS → update tasks.md, append execution.md, commit, advance
+if FAIL and attempts < 3 → respawn Implementer with the Reviewer's structured findings
+if FATAL_FAIL → abort loop immediately, mark task [~], trigger Pivot Protocol
+if 3 consecutive FAILs → HALT, mark task [~], present audit trail
+```
+
+**Why this exists:**
+
+- **Eliminates confirmation bias.** The same agent that writes code does not also approve it.
+- **Keeps each context tight.** Each role sees only the slice of spec it needs.
+- **Hard PASS/FAIL gate.** Design tokens, requirements conformance, and stability are enforced before the task is marked `[x]`.
+
+**Guardrails & Token Optimization:**
+
+- **Maximum retries.** A hard ceiling of 3 rework attempts per task.
+- **Fail-Fast (FATAL_FAIL).** Reviewer aborts the loop on critical architectural violations to save tokens.
+- **Diff-Only Review.** The Reviewer reads only the git diff to drastically reduce context window size.
+- **Structured feedback.** The Reviewer's FAIL report is forwarded unchanged to the next Implementer spawn.
+- **Pivot Protocol takes precedence.** If discovery proves the spec itself is wrong, the loop stops immediately; rework retries are not consumed on a broken spec.
+
+**Cross-tool compatibility:**
+
+The `.agents/` directory is pure Markdown + YAML frontmatter and is resolved relative to the active workspace, so the harness runs under Claude Code, OpenCode, and Google Antigravity. Antigravity invokes `invoke_subagent` with prompts read from `.agents/`; Claude Code and OpenCode delegate via sub-prompt contexts seeded with the persona files.
+
+### 7. Capability-Tier Model Routing
+
+Each AKILI-SPECS phase has a different dominant demand, so AKILI routes phases to models by **capability
+tier** rather than using one model everywhere. Six tiers — **T1 Architect, T2 Coder, T3 Auditor,
+T4 Context-Ingest, T5 Fast-Cheap, T6 Multimodal** — map to the phases:
+
+| Phase / Role | Tier |
+|---|---|
+| `/akili-constitution` | T4 + T1 |
+| `/akili-propose`, `/akili-specify` (requirements/design) | T1 |
+| `/akili-specify` (tasks) | T5 |
+| `/akili-specify` (UX/UI design) | T6 |
+| `/akili-execute` Leader / Implementer / Reviewer | T5 / T2 / T3 |
+| `/akili-test` | T2 |
+| `/akili-validate` | T3 |
+| `/akili-audit` | T4 + T3 |
+| `/akili-archive` | T5 |
+
+A single editable registry binds each tier to a concrete model **per tool** (Claude Code and
+OpenCode). `/akili-constitution` (Step 7C) scaffolds a `## Model Routing` copy of that registry into
+the project's `AGENTS.md` / `CLAUDE.md`. It is **guidance only** — no `model:` frontmatter, no
+installer changes — and it enforces **author ≠ auditor** (Reviewer model ≠ Implementer model). See
+[model-routing.md](model-routing.md) for the tiers, principles, and the default registry.

package/docs/model-routing.md

@@ -0,0 +1,133 @@
+# Capability-Tier Model Routing
+
+AKILI is model-agnostic: no command, skill, or persona hardcodes a model. This document is the
+**human-facing guidance** for choosing which model runs which AKILI-SPECS phase, so each phase runs on a
+model matched to its dominant computational demand rather than one model doing everything.
+
+It is **guidance-first**: you switch models yourself per tool (Claude Code `/model`, OpenCode
+model selector). Nothing here is injected into command frontmatter or the installer — see
+[Cross-Tool Safety](#cross-tool-safety).
+
+## Philosophy: criteria first, model second
+
+Each AKILI-SPECS phase declares **what it needs** (deep reasoning, coding throughput, independent
+judgment, large context, speed/cost, or vision) before anyone picks a model. The model is derived
+from the need, not the reverse. The registry lists a principal model plus a fallback per tier.
+
+### Guiding principles
+
+- **Match the dominant demand.** Route by the single most important demand of the phase, not by
+  "use the smartest model everywhere."
+- **ARCHITECT = BUILDER.** The model family that reasons about the design should also implement it
+  (`/akili-propose` and the `/akili-execute` Implementer share the workhorse family). Less information
+  is lost between design and code.
+- **author ≠ auditor.** The Reviewer / validator MUST run on a **different model** than the
+  Implementer. An independent auditor catches what the author rationalized away.
+- **Reserve deep-reasoning for propose & verify.** The most expensive reasoning models earn their
+  cost on architecture (`/akili-propose`) and final audit (`/akili-validate`, Reviewer), not on
+  bookkeeping.
+- **Fast & cheap for tasks & archive.** Partitioning a spec into tickets and summarizing closed
+  work are format-following jobs — speed and cost dominate; raw intelligence adds little.
+
+## Capability tiers
+
+Six tiers cover the genuinely distinct demands across the AKILI-SPECS pipeline without proliferating one
+tier per phase (which would defeat the abstraction and churn on every model release).
+
+| Tier | Definition |
+|---|---|
+| **T1 Architect** | Deep reasoning for architecture, trade-offs, and intent — "think hard before code." |
+| **T2 Coder** | Maximum coding throughput and instruction-following for writing and editing code and tests. |
+| **T3 Auditor** | Independent critical review — conformance, bug-finding, drift; must differ from the author model. |
+| **T4 Context-Ingest** | Large-context absorption of legacy codebases and baseline docs — window size over depth. |
+| **T5 Fast-Cheap** | Cheap, fast structured formatting and summarization where reasoning depth is not the bottleneck. |
+| **T6 Multimodal** | Visual / UI-UX design reasoning over images, screenshots, and design references. |
+
+## Phase → tier mapping
+
+The `/akili-execute` triad is split because each role has a different demand — and because
+author ≠ auditor makes the Implementer/Reviewer split a **correctness constraint**, not a
+preference.
+
+| Phase / Role | Tier(s) | Why |
+|---|---|---|
+| `/akili-constitution` | T4 + T1 | Ingest legacy code (long context), then reason to synthesize the baseline. |
+| `/akili-propose` | T1 | Architecture and trade-offs — reserve the deep reasoner. |
+| `/akili-specify` → requirements.md / design.md | T1 | Heavy reasoning + technical writing. |
+| `/akili-specify` → tasks.md | T5 | Fast structured partitioning into tickets. |
+| `/akili-specify` → UX/UI design | T6 | Only when visual design is in scope. |
+| `/akili-execute` → **Leader** | T5 | Orchestration / instruction-following — writes no code. |
+| `/akili-execute` → **Implementer** | T2 | Maximum coding. Shares the workhorse family with propose (ARCHITECT = BUILDER). |
+| `/akili-execute` → **Reviewer** | T3 | Independent audit. **MUST resolve to a different model than the Implementer.** |
+| `/akili-test` | T2 | Test authoring + verification. |
+| `/akili-validate` | T3 | Deep conformance audit. |
+| `/akili-audit` | T4 + T3 | Drift detection over large context, judged critically. |
+| `/akili-archive` | T5 | Cheap, fast summarization of closed work. |
+| `/akili-seo` | T3 + T5 | Audit findings (T3) plus setup/formatting steps (T5). |
+
+**author ≠ auditor enforcement.** In the registry, T2 (Coder) and T3 (Auditor) must resolve to
+**different concrete models**. If they ever collapse to the same model, escalate the Reviewer one
+tier (to the deeper reasoner) to preserve independence.
+
+## Model registry
+
+This is the single editable source of truth. Phases reference **tiers**; only this table names
+concrete models. When models change, edit only this table.
+
+| Tier | Claude Code (PRO) | OpenCode Go | Fallback |
+|---|---|---|---|
+| **T1 Architect** | Opus 4.8 | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / Sonnet 4.6 |
+| **T2 Coder** | Sonnet 4.6 | `opencode-go/glm-5.1` | Haiku 4.5 / `opencode-go/qwen3.7-max` |
+| **T3 Auditor** | Opus 4.8 *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | Sonnet 4.6 / `opencode-go/kimi-k2.6` |
+| **T4 Context-Ingest** | Sonnet 4.6 (1M context) | `opencode-go/deepseek-v4-flash` | Opus 4.8 / `opencode-go/deepseek-v4-pro` |
+| **T5 Fast-Cheap** | Haiku 4.5 | `opencode-go/deepseek-v4-flash` | Sonnet 4.6 / `opencode-go/mimo-v2.5` |
+| **T6 Multimodal** | Sonnet 4.6 (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | Opus 4.8 |
+
+### Why these models
+
+**Claude Code (PRO).** Opus 4.8 carries the tightest PRO rate limits, so it is **reserved for
+T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that most reward deep
+reasoning. **Sonnet 4.6 is the workhorse** for coding (T2), large-context ingestion via its 1M
+window (T4), and vision (T6). **Haiku 4.5** handles fast/cheap formatting, orchestration, and
+summarization (T5). This concentrates scarce Opus budget on architecture and audit and avoids
+exhausting it during execution-heavy work.
+
+**OpenCode Go.** The two strongest open models anchor the two highest-leverage tiers:
+
+- **GLM-5.1 → T2 Coder.** The highest-rated open-source model overall (58.4% SWE-Pro, ahead of
+  GPT-5.4 and Claude Opus 4.6) and purpose-built for long autonomous coding runs. It is the
+  recommended **default OpenCode workhorse** and universal fallback when no specialized model is
+  preferred.
+- **Kimi K2.6 → T1 Architect.** One of the best open models (58.6% SWE-Pro, tied with GPT-5.5); its
+  Agent Swarm is built for multi-step decomposition — ideal for architectural trade-off reasoning
+  and `/akili-explore`-style impact analysis.
+- **DeepSeek V4 Pro → T3 Auditor.** 1M context + a "Think Max" reasoning mode, and crucially a
+  *different* model than the GLM-5.1 coder — satisfying author ≠ auditor for `/akili-validate` and the
+  Reviewer.
+- **DeepSeek V4 Flash → T4 / T5.** 1M context, fastest and cheapest, highest rate limit — right for
+  bulk ingestion and high-frequency formatting.
+- **Qwen3.7 Max → T6.** Best-effort only. Open-source multimodal is weak; for real UI/UX design work
+  prefer Claude Sonnet (vision) or an external Gemini model.
+
+All OpenCode Go slugs are taken from the [OpenCode Go model list](https://opencode.ai/docs/go).
+Confirm them against your own OpenCode configuration and adjust if your roster differs.
+
+## How to apply per tool
+
+- **Claude Code (PRO):** switch with `/model` before running a phase — e.g. `/model opus` for
+  `/akili-propose` and `/akili-validate`, `/model sonnet` for `/akili-execute` and `/akili-test`,
+  `/model haiku` for the tasks split and `/akili-archive`. For the `/akili-execute` triad, run the
+  Implementer on Sonnet and the Reviewer on Opus so author ≠ auditor holds.
+- **OpenCode:** select the `opencode-go/...` model for each phase per the registry. Keep the
+  Reviewer/validator on a different model (`deepseek-v4-pro`) than the Implementer (`glm-5.1`).
+
+## Cross-tool safety
+
+- **No `model:` frontmatter.** Command prompts stay `description:`-only. A single frontmatter value
+  cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`; OpenCode expects
+  `provider/model`), so model choice stays out of the prompts.
+- **No installer changes.** Nothing here is force-injected. `/akili-constitution` scaffolds a project
+  copy of this registry into `AGENTS.md` / `CLAUDE.md` as plain Markdown — identical handling across
+  Claude Code, OpenCode, and Google Antigravity.
+- **Per-project override.** Edit the registry inside your project's `AGENTS.md` / `CLAUDE.md` to
+  pin different models; this package's copy is only the default.

package/docs/openspec-comparison.md

@@ -0,0 +1,42 @@
+# OpenSpec Comparison
+
+OpenSpec is a broader spec-driven development framework with a mature npm CLI, docs site, workflow profiles, and support for many AI tools. AKILI is a smaller methodology package focused on Claude Code and OpenCode with packaged commands, skills, and repository-local documentation conventions.
+
+This repository borrows useful documentation and workflow ideas from OpenSpec while keeping AKILI intentionally scoped to its own command set.
+
+## What We Borrow From OpenSpec
+
+| OpenSpec Pattern | AKILI Equivalent |
+|---|---|
+| README hero and quick docs index | AKILI README hero plus links to `docs/` |
+| Artifact-guided workflow | Constitution, proposal, requirements, design, tasks, execution, test, validation, archive |
+| Slash-command lifecycle | `/akili-*` command set |
+| CLI reference | `docs/cli.md` |
+| Commands reference | `docs/commands/` |
+| Workflows documentation | `docs/flow.md` |
+| Lightweight comparison section | This document |
+
+## Key Differences
+
+| Area | OpenSpec | AKILI |
+|---|---|---|
+| Scope | General-purpose SDD framework across many tools | Methodology package for Claude Code and OpenCode |
+| Initialization | CLI initializes OpenSpec workspace files | `/akili-constitution` creates or strengthens project baseline docs |
+| Baseline | Change/spec artifacts are central | Constitution is central before feature specs |
+| Skills | Uses slash commands and agent instructions | Ships Claude/OpenCode skills alongside commands |
+| Existing projects | Brownfield-friendly workflow | Explicit existing-project constitution mode with optional CodeGraph analysis |
+| Validation | Workflow validation through commands | Dedicated `/akili-test` and `/akili-validate` reports before archive |
+| SEO | Not a core workflow in OpenSpec | `/akili-seo` handles Google Search Console setup and audits |
+| Package target | `@fission-ai/openspec` | `akili-specs` |
+
+## Practical Takeaway
+
+Use OpenSpec if you want a mature, general SDD framework that targets a wide range of tools and workflow profiles.
+
+Use AKILI if you want this opinionated Claude/OpenCode workflow:
+
+```text
+constitution → proposal → spec → execute → test → validate → archive
+```
+
+Use the comparison as design guidance only. The AKILI command prompts in `.claude/commands/` are the implementation source of truth for this package.

package/docs/plans/2026-05-26-multi-agent-sdd-orchestration-design.md

@@ -0,0 +1,105 @@
+# Design Document: AKILI Multi-Agent AKILI-SPECS Orchestration
+**Date:** 2026-05-26  
+**Topic:** Multi-Agent AKILI-SPECS Orchestration (Leader-Implementer-Reviewer Triad)  
+**Status:** Approved  
+
+---
+
+## 1. Executive Summary
+
+This document specifies the integration of a specialized **Leader-Implementer-Reviewer** agentic team into the AKILI Spec-Driven Development (AKILI-SPECS) methodology. 
+
+By shifting from a single-agent execution model to a collaborative, multi-agent triad, AKILI eliminates confirmation bias during code reviews, improves context window efficiency, and guarantees high-fidelity compliance with system design tokens and the project's constitution (`CLAUDE.md`/`AGENTS.md`).
+
+---
+
+## 2. Agent Roles & Folder Structure
+
+We define a hidden directory `.agents/` in the project root to serve as the unified source of truth for the local developer team:
+
+```text
+your-workspace/
+├── .agents/
+│   ├── leader.md        # Orchestration logic, task tracking, and links to CLAUDE.md/AGENTS.md
+│   ├── implementer.md   # Focused coding guidelines, testing standards, design token extraction
+│   └── reviewer.md      # Spec conformance audits, lint/type checks, and design token compliance
+```
+
+### Agent Personas
+1.  **Leader Agent (Orchestrator):** Coordinates the execution, parses `tasks.md`, spawns subagents, monitors retries, and records execution history inside `execution.md`.
+2.  **Implementer Agent (Coder):** Natively equipped with write tools to create and edit files, compile code, and run tests. Focuses strictly on the active task.
+3.  **Reviewer Agent (Auditor):** Natively equipped with read/diff tools. Does **not** modify code. Evaluates the Implementer's diff against requirements, detailed designs, and global style guides.
+
+---
+
+## 3. The Smart Constitution Phase (`/akili-constitution`)
+
+During the constitution phase, the Leader dynamically classifies the repository and sets up the agentic environment without destroying existing configurations:
+
+1.  **Brand New Project (Seed Setup):** Prompts the user for a seed intent, initializes directories, drafts initial baselines (`prd.md`, `design.md`, `detailed-design.md`), and scaffolds the default `.agents/` templates.
+2.  **Legacy Codebase (Discovery Setup):** Deep scans the codebase using CodeGraph or grep to extract components, API contracts, and styling tokens. Synthesizes baselines from this codebase reality and customizes the `.agents/` guidelines matching this tech stack.
+3.  **Active AKILI-SPECS Project (Safe Update):** Reads existing files and custom subagent rules. **It does not overwrite them.** It only upgrades weak sections and updates `.agents/` to support the new multi-agent loop while preserving custom instructions.
+
+---
+
+## 4. Automated Rework Loop (`/akili-execute`)
+
+When `/akili-execute` is triggered, the Leader automatically coordinates the subagent loop in the background:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as You
+    participant L as Leader Agent
+    participant I as Implementer Subagent
+    participant R as Reviewer Subagent
+
+    User->>L: /akili-execute changes/add-remember-me
+    L->>L: Reads next task & .agents/implementer.md
+    L->>I: Spawns Implementer with task context
+    Note over I: Writes code & runs local verifications
+    I-->>L: Reports Task Done & provides verification evidence
+    L->>L: Reads .agents/reviewer.md & extracts git diff
+    L->>R: Spawns Reviewer to audit diff
+    Note over R: Audits diff against specs & constitution
+    
+    alt Review Passes (PASS)
+        R-->>L: PASS: Review Approved
+        L->>L: Updates tasks.md & execution.md
+        L-->>User: Task completed successfully!
+    else Review Fails (FAIL)
+        R-->>L: FAIL: Detailed issues report
+        loop Max 3 Rework Attempts
+            L->>L: Logs fail state in execution.md
+            L->>I: Spawns Implementer with Reviewer's feedback
+            Note over I: Adjusts code & re-verifies
+            I-->>L: Reports Rework Done
+            L->>R: Spawns Reviewer to audit new diff
+            R-->>L: Re-evaluates diff
+            alt Review Passes
+                R-->>L: PASS: Review Approved
+                L->>L: Updates tasks.md
+                L-->>User: Task completed after automated self-correction!
+            end
+        end
+        Note over L: If still failing after 3 attempts:
+        L-->>User: HALT: Rework limit reached. Presents logs for human guidance.
+    end
+```
+
+### Rework Loop Guardrails
+*   **Maximum Retries:** A hard ceiling of **3 rework attempts** is enforced to prevent infinite loops and token waste.
+*   **Structured Feedback:** The Reviewer outputs a structured three-part report: *Discovered Issue*, *Violated Rule*, and *Remediation Suggestion* to guide the Implementer directly.
+*   **Escalation:** If the loop fails all 3 retries, the Leader halts and presents the audit trails for human intervention.
+
+---
+
+## 5. Unified Cross-Tool Compatibility Specs
+
+The `.agents/` directory is standardized to be completely tool-agnostic:
+
+*   **Markdown Frontmatter:** Uses pure Markdown + YAML frontmatter, natively compatible with Antigravity, Claude Code, and OpenCode.
+*   **Standard Path Resolution:** All AKILI commands resolve the `.agents/` path relative to the active terminal's **Current Working Directory (Cwd)**, binding it strictly to the current workspace.
+*   **Subagent Adaptations:**
+    *   *Antigravity:* Calls `invoke_subagent` using prompts read from `.agents/`.
+    *   *Claude Code / OpenCode:* Delegates tasks by triggering sub-prompt contexts seeded with the extracted implementer/reviewer instructions.