akili-specs 2.11.0 → 2.12.0

package/.claude/commands/akili-audit.md

@@ -19,7 +19,7 @@ Detect and report drift between the project's specifications (PRD, UX/UI Design,
 
 ### Step 0: Read Project Specifications
 
-**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for the scan and **T3 Auditor** for judging drift. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"This phase is T4+T3 — the registry recommends `/model sonnet`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for the scan and **T3 Auditor** for judging drift — recommend the deeper tier's model since the judging is where quality is decided. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps those tiers to a model different from the current session model, tell the user in one line — e.g. *"This phase is T4+T3 — the registry recommends `/model opus` (T3 judging; `sonnet` suffices for the scan); you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
 
 First, read the constitutional documentation baseline in the repository:
 
@@ -50,7 +50,7 @@ Audit for discrepancies, classifying findings under the following categories:
 
 ### Step 3: Write Drift Report
 
-Create or update:
+Create or update (writing per `cognitive-doc-design`: lead with the verdict, tables over prose):
 
 ```text
 docs/specs/drift-report.md

package/.claude/commands/akili-constitution.md

@@ -401,6 +401,15 @@ project guides so the project does not depend on the package's `docs/` after ins
 5. The instruction: *"To change models, edit only this registry table. Never pin a dated model name
    where a floating alias exists. Model selection is guidance only in command prompts — never add
    `model:` to command frontmatter; enforced bindings live only in the Step 8E agent wrappers."*
+6. A compact **Effort dial** subsection (mirroring the packaged `docs/model-routing.md` → *Effort
+   dial*): effort is the second, **per-task** routing dimension, orthogonal to the tier — the tier
+   picks the model, effort picks how hard it thinks on *this* task. Include: (a) the effort-by-signal
+   table (trivial/mechanical → `low`; standard scope → `medium`; complex — algorithm, concurrency,
+   security, ambiguity → `xhigh`; correctness-critical → `max`); (b) default effort by role (T1
+   propose/specify/Leader `high`; T2 Implementer/Tester `medium`, flex by task; T3 Reviewer `high`;
+   T5 archive `low`); (c) the rework rule (*bump effort one level on every retry*); and (d) the
+   tier↔effort rule (*never `max` a cheaper tier — escalate the tier instead*). The
+   `/akili-execute` and `/akili-test` Leaders read this subsection to set each worker's effort.
 
 **Mode-specific policy (mirror Step 8B):**
 
@@ -481,7 +490,9 @@ this step — the guidance-only flow keeps working.
 - **OpenCode:** create the equivalent project agent definitions (`.opencode/agent/akili-*.md` or
   the `agent` block of `opencode.json`, matching the user's OpenCode version) with `model:` set to
   the registry's OpenCode slugs (default: implementer `opencode-go/glm-5.2`, reviewer
-  `opencode-go/deepseek-v4-pro`, leader `opencode-go/kimi-k3` (T1 — orchestration judgment)).
+  `opencode-go/deepseek-v4-pro`, leader `opencode-go/kimi-k3` (T1 — orchestration judgment),
+  tester `opencode-go/deepseek-v4-flash` — the T2 fallback rather than the T2 primary, so the
+  Tester lands on a **different model than the Implementer** (author ≠ tester)).
 
 - **Google Antigravity:** no per-agent model binding exists — skip wrapper generation and note in
   the summary that Antigravity stays on guidance-only routing.
@@ -489,7 +500,9 @@ this step — the guidance-only flow keeps working.
 **Rules:**
 
 1. The Reviewer wrapper's model MUST differ from the Implementer wrapper's model. If the registry
-   collapses them, escalate the Reviewer one tier before writing the wrappers.
+   collapses them, escalate the Reviewer one tier before writing the wrappers. The Tester wrapper
+   should also **prefer** a model different from the Implementer's (author ≠ tester — a preference,
+   not a hard rule); if they collapse, note it in the summary rather than blocking.
 2. Wrappers reference `.agents/<role>.md`; they never duplicate persona content. Editing a persona
    requires no wrapper change; changing a model requires editing only the wrapper (or re-running
    this step).

package/.claude/commands/akili-propose.md

@@ -133,7 +133,7 @@ Ask focused questions only when the proposal would otherwise depend on unstable
 
 ### Step 2: Write `proposal.md`
 
-Create a concise proposal with this structure:
+Create a concise proposal following `cognitive-doc-design` (lead with the answer, progressive disclosure, tables over prose) with this structure:
 
 1. Document Control (include `Type: Bug | Change | Trivial`)
 2. Intent

package/.claude/commands/akili-quick.md

@@ -41,7 +41,7 @@ Before making any edit, confirm the change qualifies as trivial. A change is eli
 - **No behavior change:** no new or modified logic, control flow, conditionals, state, or side effects.
 - **No data / API / auth / contract change:** no schema, endpoint, request/response shape, permission, or shared-package surface change.
 - **Small and local:** roughly **≤ ~20 LOC** and confined to **one component/file** (or a couple of tightly related files).
-- **Design-token safe:** any color/spacing/typography change uses an existing approved token from `docs/ux-ui/design.md` — not a new hardcoded value.
+- **Design-token safe:** any color/spacing/typography change uses an existing approved token from `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`) — not a new hardcoded value.
 
 ### Automatic Escalation
 
@@ -66,7 +66,7 @@ Keep context small — this is a trivial change, not a full spec run.
 
 1. Read only what the change needs:
    - the target file(s) for the change
-   - `docs/ux-ui/design.md` **only if** the change involves a color, spacing, typography, or other design token (to use the approved token)
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`) **only if** the change involves a color, spacing, typography, or other design token (to use the approved token)
    - root `CLAUDE.md` / `AGENTS.md` only if repo conventions are unclear for the edit
 2. **CodeGraph over full reads:** if `.codegraph/` exists, use `codegraph_search` to locate the exact symbol/component instead of scanning files.
 3. Do **not** read the full constitution set, `docs/prd.md`, or `docs/trd/trd.md` for a trivial edit.

package/.claude/commands/akili-resume.md

@@ -23,6 +23,8 @@ No arguments required. The command scans `docs/specs/` automatically.
 
 ### Step 0: Scan Active Specs
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** — file scanning and summarization; reasoning depth is not the bottleneck. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"Resume is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode). Never block on this; continuing on the current model is always allowed (and switching is rarely worth it for a single scan).
+
 1. List all directories under `docs/specs/` (excluding `archive/`).
 2. For each spec directory, read available files to determine current phase:
    - `proposal.md` exists → proposed

package/.claude/commands/akili-seo.md

@@ -214,7 +214,7 @@ Record each failure as a finding using the skill's Issue / Impact / Evidence / F
 
 ### Phase 3: Write `seo-audit-report.md`
 
-Generate `docs/specs/$SPEC_PATH/seo-audit-report.md` using `docs/specs/general-setup/validation-report.md` as the format source where it fits.
+Generate `docs/specs/$SPEC_PATH/seo-audit-report.md` using `docs/specs/general-setup/validation-report.md` as the format source where it fits, writing per `cognitive-doc-design` (lead with the verdict, tables over prose).
 
 Required sections:
 

package/.claude/commands/akili-test.md

@@ -101,10 +101,8 @@ The Leader decides the count from the spec's depth and the independence of the s
 1. Partition the work into concrete **suites**: backend unit, frontend unit, integration, E2E — only those the spec actually needs.
 2. For each suite, assemble a **context slice**: the target requirements + scenarios, the negative/strict rules to assert, the repo test command, and the relevant skills.
 3. Apply the **Deployment Rule** to decide inline vs delegated, and parallel vs sequential.
-4. Assign skills per suite as needed:
-   - `nestjs-expert`, `systematic-debugging` — backend
-   - `vercel-react-best-practices`, `react-doctor` — frontend
-   - `ui-ux-pro-max` (fallback `frontend-design`) — UI-heavy E2E
+4. **Select each suite's skills as Leader — you own the decision, not a fixed list.** The spec's task skills and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) are your **defaults, not a pass-through**: judge each suite's actual nature and augment, narrow, or override them (conditional skills like `systematic-debugging` for failure-heavy suites or `ui-ux-pro-max` for UI-heavy E2E; stack skills come from the Skill Map). When you deviate from the spec's list, record a one-line reason in the test report's Summary.
+5. **Set each suite's effort** (the *Effort dial* in `## Model Routing`, orthogonal to the tier): default `medium` for a T2 Tester, `low` for a trivial single-assertion suite, `xhigh` for complex integration/concurrency suites, `max` for correctness-critical coverage. Where the tool exposes a per-spawn effort knob, set it; otherwise steer depth in the suite's context slice. Never `max` a cheaper tier — escalate the tier instead.
 
 ### Phase 2: Execute Suites (Tester per suite)
 
@@ -115,7 +113,8 @@ For each suite, the assigned Tester (or the Leader inline) must:
 - Map every test back to its requirement and scenario.
 - Run the suite and apply the **bounded self-correction inner loop** (max 3 attempts):
   - fix genuine **test defects** and re-run;
-  - keep a failing test that reveals a genuine **product defect** red, and report it as `STATUS: PRODUCT_BUG` instead of rewriting it to pass.
+  - keep a failing test that reveals a genuine **product defect** red, and report it as `STATUS: PRODUCT_BUG` instead of rewriting it to pass;
+  - on each retry, **bump the effort one level** (`medium` → `high` → `xhigh`) — a fix that failed is usually under-thinking, not missing instructions.
 - Prefer unit tests for internal logic, integration tests for cross-module/API behavior, and E2E only for critical user journeys — not every small component state.
 
 Each Tester concludes with exactly one status — `PASS`, `FAIL`, or `PRODUCT_BUG` — plus a per-scenario coverage slice, per `.agents/tester.md`.
@@ -131,7 +130,7 @@ Recommended matrix columns:
 
 ### Phase 4: Generate Test Report (Leader)
 
-Create `docs/specs/$ARGUMENTS/test-report.md`.
+Create `docs/specs/$ARGUMENTS/test-report.md`. Write it following `cognitive-doc-design`: lead with the answer (overall status first), progressive disclosure, tables over prose.
 
 **Automated Test Parsing Option:** If the repository uses standard testing frameworks (like Jest or Vitest) and has a AKILI test parsing helper installed (e.g. `akili/scripts/parse_tests.js`), you may run the tests outputting to JSON (e.g. `jest --json --outputFile=jest-results.json` or `vitest --reporter=json --outputFile=test-results.json`) and run:
 `node <path-to-akili>/scripts/parse_tests.js jest-results.json`

package/.claude/commands/akili-validate.md

@@ -108,13 +108,8 @@ For every requirement in `requirements.md`, verify:
 
 Use skills as needed:
 
-- `nestjs-expert`
-- `react-doctor`
-- `api-design-principles`
-- `tailwind-design-system`
-- `frontend-design`
-- `ui-ux-pro-max` if available for UX/UI-heavy validation
-- `systematic-debugging` when failures or inconsistencies appear
+- **Stack skills come from the project's `## Skill Map`** (root `AGENTS.md`/`CLAUDE.md`) — load the entries matching the code under validation; do not assume a fixed list.
+- Conditional skills by situation: `ui-ux-pro-max` (fallback `frontend-design`) for UX/UI-heavy validation; `systematic-debugging` when failures or inconsistencies appear.
 
 Check for:
 
@@ -139,7 +134,7 @@ If `proposal.md` exists, also verify that final behavior remains aligned with th
 
 ### Phase 7: Generate Validation Report
 
-Create `docs/specs/$ARGUMENTS/validation-report.md`.
+Create `docs/specs/$ARGUMENTS/validation-report.md`. Write it following `cognitive-doc-design`: lead with the verdict, progressive disclosure, tables over prose.
 
 The report must include:
 

package/.claude/skills/react-doctor/SKILL.md

@@ -5,6 +5,7 @@ version: 1.0.0
 metadata:
   author: Million.dev (millionco)
   source: https://github.com/millionco/react-doctor
+  license: MIT
   adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: stack

package/.claude/skills/shadcn-ui/SKILL.md

@@ -4,7 +4,8 @@ description: Provides complete shadcn/ui component library patterns including in
 allowed-tools: Read, Write, Bash, Edit, Glob
 metadata:
   author: community (origin unverified)
-  curated-by: "Juan Carlos Cadavid — jcadavid.com"
+  license: "unverified — no upstream source to check; treat as all-rights-reserved until origin is identified"
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: stack
   version: "1.0"

package/.claude/skills/stitch-design/SKILL.md

@@ -8,6 +8,7 @@ allowed-tools:
 metadata:
   author: Google (google-labs-code)
   source: https://github.com/google-labs-code/stitch-skills
+  license: Apache-2.0
   adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: conditional

package/.claude/templates/implementer.md

@@ -12,7 +12,8 @@ Your sole responsibility is to implement the technical scope of the active task
 
 1.  **Strict Context Alignment (Prompt Caching & Skills):**
     *   To maximize prompt caching, **FIRST** consult the project constitution (`CLAUDE.md`, `AGENTS.md`, `docs/trd/trd.md`, `docs/ux-ui/design.md`) in a consistent order before reading task-specific files.
-    *   **Skill Loading:** If the Leader assigns you specific skills (e.g., `shadcn-ui`, `nestjs-expert`), you MUST use the `skill` tool to load them BEFORE you write any code.
+    *   **Skill Loading:** If the Leader assigns you specific skills (e.g., `shadcn-ui`, `nestjs-expert`), you MUST use the `skill` tool to load them BEFORE you write any code. **The Leader's skill assignment supersedes the task's recommended list** — the Leader actively selects skills per task; load what it assigns, not what the task file says.
+    *   **Effort:** Honor the Leader's effort/depth instruction for this task (the *Effort dial* in `## Model Routing`) — think as hard as the brief asks: quick and mechanical for trivial work, deep and careful when the brief flags the task as complex or correctness-critical.
     *   Strictly align with requirements defined in `docs/specs/<spec-path>/requirements.md`.
     *   Follow the technical blueprint in `docs/specs/<spec-path>/design.md`.
 2.  **Incremental Focus (No Scope Creep):**

package/.claude/templates/leader.md

@@ -64,6 +64,20 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 
 ---
 
+## 🧪 When Orchestrating `/akili-test` (Leader → Tester harness)
+
+The same Leader judgment applies when you orchestrate testing — only the workers change:
+
+1. **Partition** the spec's testing into concrete suites (backend unit, frontend unit, integration, E2E — only those the spec needs) and apply `/akili-test`'s Deployment Rule (inline vs delegated).
+2. **Select each Tester's skills and effort** exactly as you do for Implementers (Instruction #3): the spec's list and the `## Skill Map` are defaults you may override; set per-suite effort (`medium` default, flex by suite difficulty) and record deviations in the test report's Summary.
+3. **author ≠ tester:** prefer spawning each Tester on a **different model than the Implementer** that wrote the production code (reduces confirmation bias). A preference, not a hard rule — note it when they collapse.
+4. **Adjudicate results:** a `PRODUCT_BUG` from a Tester is evidence, not noise — carry it through as a failure with remediation; never let a Tester rewrite a red test to pass.
+5. You write no tests yourself except where `/akili-test`'s Deployment Rule says to run a trivial suite inline.
+
+The full test-orchestration contract (phases, Deployment Rule, report format) lives in `/akili-test`; this section makes your authority consistent across both harnesses.
+
+---
+
 ## 📝 Reporting To The User
 
 After each task completes (whether on first pass or after self-correction), report:

package/.claude/templates/reviewer.md

@@ -4,7 +4,7 @@ You are the specialized **Specification Reviewer** agentic team member in the AK
 
 Your sole responsibility is to perform an independent, objective audit of the git diff produced by the **Implementer**. You act as a strict gatekeeper to ensure code matches specifications, conforms to design tokens, and preserves repository stability.
 
-> **Recommended model tier:** T3 Auditor (deep, independent review). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. You **MUST** run on a **different model than the Implementer** — author ≠ auditor is a correctness constraint, not a preference. If only one model is available, escalate to the deepest-reasoning model for this audit.
+> **Recommended model tier:** T3 Auditor (deep, independent review) at **default effort `high`** — auditor thoroughness is the point; do not skim (see the *Effort dial* in `## Model Routing`). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. You **MUST** run on a **different model than the Implementer** — author ≠ auditor is a correctness constraint, not a preference. If only one model is available, escalate to the deepest-reasoning model for this audit.
 
 ---
 

package/.claude/templates/tester.md

@@ -13,7 +13,8 @@ Your sole responsibility is to author and execute the **one test suite** assigne
 1.  **Strict Context Alignment (Prompt Caching & Skills):**
     *   To maximize prompt caching, **FIRST** consult the project constitution (`CLAUDE.md`, `AGENTS.md`, `docs/trd/trd.md`, `docs/ux-ui/design.md`) in a consistent order before reading task-specific files.
     *   Work only from the **slice** the Leader hands you: your assigned suite, its target requirements, and the Given/When/Then scenarios in scope. Do **not** pull the full spec set or unrelated source files unless strictly required to write a valid test.
-    *   **Skill Loading:** If the Leader assigns skills (e.g. `nestjs-expert`, `react-doctor`, `vercel-react-best-practices`, `systematic-debugging`, `ui-ux-pro-max`), load them with the `skill` tool **before** writing tests.
+    *   **Skill Loading:** If the Leader assigns skills (e.g. `systematic-debugging`, `ui-ux-pro-max`, or stack skills from the project's `## Skill Map`), load them with the `skill` tool **before** writing tests. The Leader's assignment supersedes any list in the spec.
+    *   **Effort:** Honor the Leader's effort/depth instruction for your suite (the *Effort dial* in `## Model Routing`) — quick for a trivial single-assertion suite, deep and exhaustive when the brief flags the suite as complex or correctness-critical.
 2.  **Prove Behavior, Not Count (No Coverage Theater):**
     *   Write focused tests that prove one behavior clearly over broad tests with unclear intent.
     *   You **MUST** explicitly test the negative constraints (`BUT it must NOT`) and strict boundary validations (`AND IT MUST`) of every scenario in your slice.

package/CHANGELOG.md

@@ -10,6 +10,15 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.12.0] - 2026-07-24
+
+### Changed
+
+- **Methodology audit — effort dial and Leader authority propagated to their remaining surfaces.** A four-front audit (commands, personas, skills governance, docs coherence) after v2.11.0 found the new capabilities had landed in `/akili-execute` but not its siblings. Fixed: **(a)** `/akili-constitution` Step 8C now scaffolds the **Effort dial** into each project's `## Model Routing` (item 6: effort-by-signal table, per-role defaults, rework escalation, tier↔effort rule) — previously `/akili-execute` referenced a section fresh projects never had; **(b)** `/akili-test` gains per-suite **effort selection** (Phase 1), **effort escalation on the Tester inner loop**, and the same active skill-selection authority as execute; **(c)** worker personas now acknowledge the dial — `implementer.md`/`tester.md` honor the Leader's effort brief (and state the Leader's skill assignment supersedes the task list), `reviewer.md` states its default effort `high`; **(d)** `leader.md` gains a **"When Orchestrating `/akili-test`"** section (was execute-only — never mentioned Testers or author ≠ tester); **(e)** Step 8E adds the missing **OpenCode tester wrapper default** (`opencode-go/deepseek-v4-flash` — the T2 *fallback* rather than the primary, so the Tester lands on a different model than the Implementer) plus a soft author ≠ tester guard in Rule 1.
+- **Command-consistency fixes from the audit.** `/akili-resume` gains the standardized model checkpoint every sibling has, and joins the phase→tier table as an explicit T5 row; `/akili-audit`'s checkpoint now surfaces `opus` for the T3 drift-judging portion (it only named the T4 scan model); `cognitive-doc-design` is now cited by all five report-producing commands that lacked it (`propose`/`audit`/`seo`/`validate`/`test`); `/akili-quick` gains the `docs/system-design/design.md` legacy fallback every other design-reader carries.
+- **Skills governance: rule-vs-practice contradiction resolved with documented carve-outs.** The absolute "stack skills never hard-referenced in command text" rule contradicted four command sites. `governance.md` now distinguishes **load-directing** (violation) from three carve-outs: the constitution's candidate-pool/bootstrap lists, no-map fallback lists that defer to the Skill Map first, and Skill-Map-deferring illustrative examples. The two genuine violations were purged: `/akili-validate` and `/akili-test` now point stack-skill selection at the project `## Skill Map` instead of fixed lists. `docs/skills/README.md` aligned.
+- **Skill attribution completed.** `react-doctor` (`license: MIT`) and `stitch-design` (`license: Apache-2.0`) — both verified against their upstream repositories; `shadcn-ui`'s off-schema `curated-by` normalized to `adapted-by` with an explicit unverified-license warning.
+- **Stale docs corrected.** `README.md` no longer claims fast/cheap models handle the tasks split (the exact belief v2.11.0 reversed — now: deep reasoning for propose/specify incl. `tasks.md`/validate/Leader, fast/cheap only for archive+formatting, plus the Effort dial); README and `docs/cli.md` now document the v2.10.1 installer **auto-detect** behavior (bare `install`/`update`/`doctor` act on all installed targets); README's Contents lists all 22 skills (added `caveman`, `software-architect`); `docs/commands/README.md` includes Antigravity; `model-routing.md` wording fix ("the strongest open models").
 ## [2.11.0] - 2026-07-24
 
 ### Changed

package/README.md

@@ -79,6 +79,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `api-design-principles`
   - `aws-serverless`
   - `brainstorming`
+  - `caveman`
   - `cognitive-doc-design`
   - `error-handling-patterns`
   - `frontend-design`
@@ -90,6 +91,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `react-doctor`
   - `seo-audit`
   - `shadcn-ui`
+  - `software-architect`
   - `stitch-design`
   - `systematic-debugging`
   - `tailwind-design-system`
@@ -138,7 +140,9 @@ npx akili-specs init
 
 **Manual Installation via Flags:**
 
-Install globally for Claude (default):
+Install without `--tool` — the installer **auto-detects targets already installed on disk**
+(`~/.claude`, `~/.config/opencode`, `~/.gemini`) and acts on all of them; on a first-time run with
+nothing installed it defaults to Claude:
 
 ```bash
 npx akili-specs install
@@ -810,7 +814,9 @@ selector), and `/akili-constitution` scaffolds a `## Model Routing` registry int
 
 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`.
+`/akili-propose`, `/akili-specify` (including the `tasks.md` decomposition), `/akili-validate`, and
+the `/akili-execute`/`/akili-test` Leader, and use fast/cheap models only for `/akili-archive` and
+pure setup/formatting steps. An **Effort dial** adds a second, per-task dimension on top of the tier.
 
 See **[docs/model-routing.md](docs/model-routing.md)** for the tiers, the full phase→tier mapping,
 and the default registry for Claude Code (PRO) and OpenCode Go.

package/docs/cli.md

@@ -26,7 +26,10 @@ npx akili-specs install --tool both
 npx akili-specs install --tool all
 ```
 
-Claude is the default target:
+When `--tool` is omitted, `install`, `update`, and `doctor` **auto-detect already-installed
+targets** on disk (`~/.claude`, `~/.config/opencode`, `~/.gemini`) and act on all of them — so a
+bare `akili update` refreshes every installed tool, not just Claude. A first-time run with nothing
+installed defaults to Claude. An explicit `--tool <name>` always wins:
 
 ```bash
 npx akili-specs install
@@ -67,6 +70,7 @@ Every command closes with a clear end-of-run summary:
 
 | Option | Applies To | Purpose |
 |---|---|---|
+| *(no `--tool`)* | install, update, doctor | **Auto-detect installed targets** and act on all of them; default to Claude when none found |
 | `--tool claude` | install, update, doctor | Target Claude Code config |
 | `--tool opencode` | install, update, doctor | Target OpenCode config |
 | `--tool antigravity` | install, update, doctor | Target Google Antigravity config |

package/docs/commands/README.md

@@ -1,6 +1,6 @@
 # Command Reference
 
-AKILI commands are installed as slash-command prompts for Claude Code and OpenCode. The installable source files live in `.claude/commands/`.
+AKILI commands are installed as slash-command prompts for Claude Code, OpenCode, and Google Antigravity (as workflows). The installable source files live in `.claude/commands/`.
 
 ## Command Map
 

package/docs/model-routing.md

@@ -87,6 +87,7 @@ model than the Implementer (author ≠ tester).
 | `/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. (Kaizen Learn sub-step: T3 optional.) |
+| `/akili-resume` | T5 | File scanning + dashboard summarization — reasoning depth is not the bottleneck. |
 | `/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
@@ -130,7 +131,7 @@ unchanged (e.g. when the top family moves from one generation to the next, `opus
 Users on plans that expose a frontier model above Opus (Fable 5 / Mythos 5) can pin it for T1/T3 —
 see **Frontier escalation tier** below.
 
-**OpenCode Go.** The two strongest open models anchor the two highest-leverage tiers:
+**OpenCode Go.** The strongest open models anchor the highest-leverage tiers:
 
 - **GLM-5.2 → T2 Coder.** A-tier open coder (753B, GPQA 91.2), successor to GLM-5.1, purpose-built
   for long autonomous coding runs — the recommended **default OpenCode workhorse**. (This row was

package/docs/skills/README.md

@@ -10,7 +10,7 @@ The skill set is **curated, not accumulated**: every skill declares its original
 |---|---|
 | `core` | Hard-wired to a precise command step — the command loads it by name |
 | `conditional` | Loaded when the work touches its domain (UI, animation) |
-| `stack` | Selected per project via the `## Skill Map` scaffolded by `/akili-constitution`; never hardcoded in command text |
+| `stack` | Selected per project via the `## Skill Map` scaffolded by `/akili-constitution`; never load-directed in command text (candidate-pool lists in the Skill Map builder and Skill-Map-deferring examples are documented carve-outs — see `governance.md`) |
 
 ## Skill Inventory
 

package/docs/skills/governance.md

@@ -26,7 +26,7 @@ Rules of thumb:
 
 - A skill earns `core` only when a command step would be *wrong* without it (a retrospective without `kaizen` is not the AKILI archive).
 - `conditional` skills are stack-agnostic capabilities that many but not all specs need (UI, animation).
-- `stack` skills must never be hard-referenced in command text — commands stay tool- and framework-agnostic. They reach the agent through the project Skill Map and per-task skill lists.
+- `stack` skills must never be **load-directed** in command text (a command step telling the agent to load a named stack skill) — commands stay tool- and framework-agnostic. They reach the agent through the project Skill Map and per-task skill lists. **Three documented carve-outs:** (1) the Skill Map *builder* in `/akili-constitution` (Step 8D, and the Step 5 TRD bootstrap that feeds it — constitution runs *before* the map exists) may enumerate the packaged stack skills as the candidate pool it selects from; (2) an explicit **no-map fallback list** that defers to the Skill Map first ("prefer the `## Skill Map` when it exists; otherwise pick from: …") is acceptable; (3) purely *illustrative* examples ("e.g. `nestjs-expert`") that explicitly defer to the task list / Skill Map are acceptable. A step that says "use these skills:" followed by stack-skill names, with **no** Skill Map deferral, is a violation.
 
 ## Frontmatter Schema
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {