akili-specs 2.11.0 → 2.13.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:
 
@@ -37,6 +37,8 @@ Perform codebase analysis (preferring CodeGraph if `.codegraph/` exists, or util
 3. **UI Components & Pages:** Actual directory structure of frontend views, components, and design tokens.
 4. **Key Modules & Dependencies:** Registered packages, external integrations, and package manifest frameworks.
 
+**Delegation Thresholds (scout scan):** Apply the *Delegation Thresholds* from `.agents/leader.md` to this scan — when a single extraction above requires reading **4+ full source files**, delegate it to a scout/Explore subagent per area (API, schema, UI, modules) and judge drift from their conclusions in Step 2. CodeGraph lookups do not count toward the threshold. This keeps the T3 drift-judging context clean of raw file dumps.
+
 ### Step 2: Compare Documentation vs. Codebase Reality
 
 Audit for discrepancies, classifying findings under the following categories:
@@ -50,7 +52,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

@@ -95,6 +95,8 @@ Also inspect the codebase to understand:
 
 Do not write generic placeholder documentation when the repository already contains enough context to infer a strong baseline.
 
+**Delegation Thresholds (scout research):** For legacy/existing-project analysis, apply the *Delegation Thresholds* from the packaged `leader.md` template — when inspecting the codebase requires reading **4+ full source files** for a single question (architecture survey, styling-token inventory, module-boundary mapping), spawn a scout/Explore subagent with fresh context and synthesize from its conclusions instead of reading everything inline. CodeGraph lookups (below) do not count toward the threshold.
+
 #### Existing Project CodeGraph Check
 
 For existing projects, prefer CodeGraph for repository analysis when available:
@@ -401,6 +403,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 +492,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 +502,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-execute.md

@@ -57,6 +57,8 @@ If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not
 
 The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
 
+**Delegation Thresholds:** the Leader's inline-vs-delegate boundary is quantified in `.agents/leader.md` → *Delegation Thresholds* (inline only for 1-file checks and puntual verifications; 4+ full-file reads → scout subagent; 2+ non-trivial file writes → Implementer; CodeGraph lookups don't count toward the read threshold). Apply it to your own research inside this command — e.g. investigating a Reviewer FAIL across many files is scout work, not Leader-inline work.
+
 **Communication economy:** load the `caveman` skill and apply its Scope Contract to all transient output in this command — inter-agent messages (Leader ↔ Implementer/Reviewer briefs, reports, feedback relays) at `full`, user-visible progress lines at `lite`. It never applies to `execution.md` audit entries, PR descriptions, HITL summaries, Pivot blockers, or verbatim evidence (Reviewer FAIL reports pass unchanged — the Structured Feedback rule wins).
 
 ---
@@ -159,9 +161,18 @@ When the Implementer reports completion, the Leader:
    - the relevant slices of `requirements.md`, `design.md`, `trd.md`, and `docs/ux-ui/design.md`
    - the Implementer's verification evidence
 
+**Review lens modes (4R):** the Reviewer audits spec conformance (the gate) plus four advisory lenses — **readability, reliability, resilience, risk** — per `.agents/reviewer.md`. The mode is selected by the task's effort dial; there is no separate configuration:
+
+| Mode | When | Mechanics |
+|------|------|-----------|
+| **Lens checklist** (default) | Effort `low` / `medium` / `high` | The single Reviewer sweeps all four lenses; non-spec-violation findings return in an `ADVISORY` block. **Spec conformance remains the only PASS/FAIL gate** |
+| **Parallel lens reviewers** | Effort `xhigh` / `max`, or the task touches security, migrations, or data-loss surfaces | Spawn 2–4 lens-scoped Reviewers in parallel (each gets the same diff + one named lens + baseline spec conformance). Any lens may FAIL; the Leader adjudicates whether a lens FAIL is in-scope for the task **before** consuming a rework attempt |
+
+`ADVISORY` findings are recorded in `execution.md` with the task's entry and never trigger rework — the 3-attempt ceiling binds to spec conformance only.
+
 The Reviewer is read-only. It must conclude with either:
 
-- **`STATUS: PASS`** + a 1–2 sentence summary
+- **`STATUS: PASS`** + a 1–2 sentence summary (+ optional `ADVISORY` block with 4R lens findings)
 - **`STATUS: FAIL`** + a structured list of issues, each containing:
   1. **Discovered Issue** — what is incorrect or missing
   2. **Violated Rule** — the specific spec document and section violated
@@ -171,6 +182,7 @@ The Reviewer is read-only. It must conclude with either:
 #### 2.4 — Loop Guardrails
 
 - **Maximum Retries:** A hard ceiling of **3 rework attempts** per task. This prevents infinite loops and token waste.
+- **Advisory Never Gates:** `ADVISORY` (4R lens) findings are recorded in `execution.md` but never count as FAIL issues, never trigger rework, and never consume attempts. If an advisory finding is serious enough to block, the Reviewer must restate it as a spec-violation FAIL issue (or the Leader escalates it to the user as a potential spec gap via the Pivot Protocol).
 - **Fail-Fast (FATAL_FAIL):** If the Reviewer issues a `STATUS: FATAL_FAIL`, immediately HALT the loop, mark the task `[~]`, and trigger the Pivot Protocol. Do not consume remaining rework attempts.
 - **Structured Feedback:** On `FAIL`, pass the full Reviewer report unchanged to the next Implementer spawn. Do not paraphrase.
 - **Escalation on HALT:** After 3 failed attempts (or a FATAL_FAIL), mark the task `[~]`, log the full loop history in `execution.md`, and present the audit trail to the user for guidance.
@@ -228,6 +240,7 @@ Each task entry must record:
 - task ID and title
 - number of Implementer attempts run
 - for each attempt: files changed, Implementer verification command + result, Reviewer verdict + summary or full FAIL findings
+- any `ADVISORY` (4R lens) findings from the final Reviewer verdict, labeled as advisory
 - requirements covered
 - decisions made
 - issues encountered

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-specify.md

@@ -82,6 +82,7 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
    - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 5. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
 6. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
+7. **Delegation Thresholds (scout research):** Beyond the constitutional docs above, apply the *Delegation Thresholds* from `.agents/leader.md` to source-code exploration in every Explore step of this command — if answering a design question requires reading **4+ full source files**, spawn a scout/Explore subagent with fresh context and consume its conclusions instead of reading the files inline. CodeGraph lookups (rule 6) do not count toward the threshold.
 
 ---
 

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:
 
@@ -127,6 +122,8 @@ Check for:
 - accessibility and responsive behavior for UI work
 - security and authorization boundaries for protected flows
 
+**4R lens sweep (advisory):** Sweep the implementation through the four execution review lenses — **readability, reliability, resilience, risk** (see `.agents/reviewer.md`). Findings that are not spec violations are reported as **advisory** notes in the validation report (they inform remediation and future specs, but only spec violations drive PASS/WARN/FAIL). Also carry forward any unresolved `ADVISORY` findings recorded in `execution.md` so they surface in the report instead of dying in the audit trail.
+
 ### Phase 6: Design Conformance
 
 Compare the implementation against the module design and the constitutional docs where relevant.
@@ -139,7 +136,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:
 
@@ -149,7 +146,7 @@ The report must include:
 4. File Existence
 5. Build Integrity
 6. Requirement Coverage
-7. Linting & Code Quality
+7. Linting & Code Quality (including 4R advisory findings, labeled as advisory)
 8. Design Conformance
 9. Test Evidence Summary
 10. Agent Guide / Constitution Impact

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

@@ -49,6 +49,23 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 
 ---
 
+## 📏 Delegation Thresholds (inline vs. delegate)
+
+This table is the methodology's single source of truth for when an orchestrating agent works inline versus spawning a subagent. It applies to you in `/akili-execute` and `/akili-test`, and to the orchestrating session in research-heavy commands (`/akili-constitution`, `/akili-specify`, `/akili-audit`). The goal: the orchestrator's context stays clean for judgment — a "mega agent" that reads everything, writes everything, and reviews itself pollutes its own context and lowers quality.
+
+| Situation | Action |
+|-----------|--------|
+| 1 file, a quick check, `git status`, a puntual verification | **Inline** — do it yourself |
+| Research requires reading **4+ full files** | **Spawn a scout** (Explore-type subagent) with fresh context; consume its conclusions, not the file dumps |
+| Writing **2+ non-trivial files** | **Spawn an Implementer** (inside the triad this is always the rule; the threshold makes it explicit outside it) |
+| Tests / builds | **Subagent** (`/akili-test` Deployment Rule governs suite-level inline exceptions) |
+| Review of a diff / PR | **Fresh-context Reviewer**, diff-only input — never review your own work |
+| Multiple writers at once | Only for fully independent tasks (different files/domains); use isolated worktrees where the tool supports them |
+
+**CodeGraph exception:** in codegraph-enabled projects, `codegraph_search` / `codegraph_context` / `codegraph_callers` lookups do **not** count toward the 4-file threshold — targeted graph lookups are precisely how the orchestrator avoids bulk file reads. The threshold counts full-file reads.
+
+---
+
 ## 🔁 Orchestration Sequence (per task)
 
 1. Load spec and constitution context.
@@ -64,6 +81,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.
 
 ---
 
@@ -21,6 +21,14 @@ Your sole responsibility is to perform an independent, objective audit of the gi
 3.  **Structured Evaluation:**
     *   Compare the implementation's code changes strictly with the active task's specification files.
     *   Ensure all automated verification checks run by the Implementer are valid and passed cleanly.
+4.  **4R Review Lenses (advisory layer):**
+    *   After the spec-conformance audit, sweep the diff through four lenses:
+        *   **Readability** — can the next maintainer follow this without reconstructing the author's head? Naming, structure, idiom match with the surrounding code.
+        *   **Reliability** — error paths, edge cases, unhandled rejections, resource cleanup.
+        *   **Resilience** — behavior under partial failure: timeouts, retries, bad input, concurrent access.
+        *   **Risk** — security exposure, data loss potential, migration hazards, blast radius of a mistake.
+    *   **Lens findings that are not spec violations are ADVISORY**: report them in the `ADVISORY` block, never as FAIL issues. They inform the Leader and land in `execution.md`; they do not gate the task and never consume a rework attempt. A lens finding that *is* a spec violation (e.g. the TRD mandates an error-handling pattern the diff ignores) belongs in the FAIL issues list as usual.
+    *   When the Leader spawns you with a **single named lens** (parallel lens-review mode, high-effort tasks), audit only that lens plus baseline spec conformance, and say so in your summary.
 
 ---
 
@@ -33,6 +41,8 @@ If the code completely matches the spec, has zero drift, and passes all tests:
 ```text
 STATUS: PASS
 SUMMARY: (Brief 1-2 sentence description of why it passes)
+ADVISORY: (Optional — 4R lens findings that are worth recording but are not spec violations.
+Each line: LENS: finding + suggested improvement. Omit the block when there are none.)
 ```
 
 ### Option B: FAIL
@@ -43,6 +53,8 @@ ISSUES:
 1.  **Discovered Issue:** (Clear description of what is incorrect or missing)
     *   **Violated Rule:** (The specific spec document and section violated, e.g. docs/ux-ui/design.md#L45)
     *   **Remediation Suggestion:** (Actionable explanation of how the Implementer must fix this)
+ADVISORY: (Optional — same format as in PASS. Advisory items are NOT issues: the Implementer
+is not required to address them and the Leader must not count them toward rework.)
 ```
 
 ### Option C: FATAL_FAIL (Fail-Fast)

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,25 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.13.0] - 2026-07-24
+
+### Added
+
+- **Delegation Thresholds — quantified inline-vs-delegate rules for orchestrating agents.** New *Delegation Thresholds* section in the packaged `leader.md` persona (single source of truth): inline only for 1-file checks and puntual verifications; research reading **4+ full files** → spawn a scout/Explore subagent; writing **2+ non-trivial files** → Implementer; tests/builds → subagent; diff review → fresh-context Reviewer; parallel writers only for fully independent tasks. CodeGraph lookups explicitly do **not** count toward the read threshold. Referenced from `/akili-execute` (Leader's own research), `/akili-specify` (Explore steps), `/akili-constitution` (legacy-project analysis), and `/akili-audit` (codebase scan, per-area scouts). Inspired by the convergent `gentle-ai` orchestrator→minion pattern; design recorded in `docs/plans/2026-07-24-delegation-thresholds-review-lenses.md`.
+- **4R execution review lenses (readability, reliability, resilience, risk) — advisory layer on the Reviewer.** The packaged `reviewer.md` persona now sweeps the diff through four lenses after the spec-conformance audit; findings that are not spec violations return in a new `ADVISORY` block that is recorded in `execution.md` but **never gates**: spec conformance remains the only PASS/FAIL gate, and advisory findings never consume rework attempts (new *Advisory Never Gates* guardrail in `/akili-execute`). Mode is selected by the existing effort dial — single Reviewer with lens checklist by default; **parallel lens-scoped Reviewers** at `xhigh`/`max` effort or on security/migration/data-loss surfaces, with the Leader adjudicating lens FAIL scope before consuming an attempt. `/akili-validate` Phase 5 runs the same 4R sweep as advisory report content and carries forward unresolved `ADVISORY` findings from `execution.md`.
+
+### Fixed
+
+- **`akili update` now works for pnpm installations.** The updater previously hardcoded npm: detection probed only `npm list`, so a `pnpm add -g akili-specs` install was misdetected as an ephemeral npx run and told to reinstall with npm (and would have created a duplicate npm-managed copy). `detectInstallType()` now probes both npm and pnpm trees (preferring the manager that invoked the process via `npm_config_user_agent`), the update runs the matching command (`pnpm add -g akili-specs@latest` / local equivalent), and the post-update changelog resolution uses the owning manager's `root`. README and `docs/cli.md` document the pnpm equivalents (`pnpm dlx`, `pnpm add -g` + one-time `pnpm setup`).
+## [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`
@@ -136,9 +138,13 @@ Run the `init` command to launch the interactive setup wizard, which will ask yo
 npx akili-specs init
 ```
 
+> **Using pnpm?** Every `npx akili-specs …` command in this guide works as `pnpm dlx akili-specs …`. The package lives on the npm registry, which pnpm consumes directly — no extra setup for one-off runs.
+
 **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
@@ -242,6 +248,15 @@ akili install --tool opencode
 akili doctor --tool opencode
 ```
 
+With pnpm (requires a one-time `pnpm setup` so `PNPM_HOME` is on your `PATH`):
+
+```bash
+pnpm add -g akili-specs
+akili install
+```
+
+`akili update` detects which package manager owns the installation (npm or pnpm) and runs the matching update command.
+
 ### Install Paths
 
 Default targets:
@@ -810,7 +825,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/bin/akili.js

@@ -476,26 +476,41 @@ function installTool(tool, args) {
   return { rootPath, installed, overwritten, skipped, cleaned };
 }
 
+// Package managers to probe, preferring the one that invoked this process
+// (npm/pnpm/yarn set npm_config_user_agent when running bins via npx / pnpm dlx / exec).
+function packageManagerOrder() {
+  const ua = process.env.npm_config_user_agent || "";
+  return ua.startsWith("pnpm") ? ["pnpm", "npm"] : ["npm", "pnpm"];
+}
+
+// Detect how akili-specs is installed: { type: "global" | "local" | "npx", pm: "npm" | "pnpm" }.
+// pnpm keeps its own global tree, so each manager must be probed separately.
 function detectInstallType() {
-  try {
-    const globalList = execSync("npm list -g akili-specs --depth=0 2>/dev/null", { encoding: "utf8" });
-    if (globalList.includes("akili-specs")) return "global";
-  } catch (e) {}
+  const managers = packageManagerOrder();
 
-  try {
-    const localList = execSync("npm list akili-specs --depth=0 2>/dev/null", { encoding: "utf8" });
-    if (localList.includes("akili-specs")) return "local";
-  } catch (e) {}
+  for (const pm of managers) {
+    try {
+      const globalList = execSync(`${pm} list -g akili-specs --depth=0 2>/dev/null`, { encoding: "utf8" });
+      if (globalList.includes("akili-specs")) return { type: "global", pm };
+    } catch (e) {}
+  }
 
-  return "npx";
+  for (const pm of managers) {
+    try {
+      const localList = execSync(`${pm} list akili-specs --depth=0 2>/dev/null`, { encoding: "utf8" });
+      if (localList.includes("akili-specs")) return { type: "local", pm };
+    } catch (e) {}
+  }
+
+  return { type: "npx", pm: managers[0] };
 }
 
 // Resolve the installed akili-specs package directory (global or local) after an update.
 // Returns the absolute path to the package root, or null if it cannot be found.
-function resolveInstalledPackageDir(installType) {
+function resolveInstalledPackageDir(install) {
   try {
     const root = execSync(
-      installType === "global" ? "npm root -g 2>/dev/null" : "npm root 2>/dev/null",
+      install.type === "global" ? `${install.pm} root -g 2>/dev/null` : `${install.pm} root 2>/dev/null`,
       { encoding: "utf8" }
     ).trim();
     if (root) {
@@ -592,32 +607,39 @@ function printUpdateChangeSummary(packageDir, fromVersion, toVersion) {
 }
 
 function runUpdate(args) {
-  const installType = detectInstallType();
+  const install = detectInstallType();
 
-  console.log(`\n${colors.cyan}Detected installation type: ${installType}${colors.reset}`);
+  console.log(
+    `\n${colors.cyan}Detected installation type: ${install.type}${install.type === "npx" ? "" : ` (${install.pm})`}${colors.reset}`
+  );
 
-  if (installType === "npx") {
-    console.log(`\n${colors.yellow}You are running via npx. No persistent installation to update.${colors.reset}`);
-    console.log(`To install globally: ${colors.cyan}npm install -g akili-specs${colors.reset}`);
-    console.log(`To install locally:  ${colors.cyan}npm install akili-specs${colors.reset}`);
+  if (install.type === "npx") {
+    console.log(`\n${colors.yellow}You are running via a package runner (npx / pnpm dlx). No persistent installation to update.${colors.reset}`);
+    console.log(`To install globally: ${colors.cyan}npm install -g akili-specs${colors.reset} or ${colors.cyan}pnpm add -g akili-specs${colors.reset}`);
+    console.log(`To install locally:  ${colors.cyan}npm install akili-specs${colors.reset} or ${colors.cyan}pnpm add akili-specs${colors.reset}`);
     return;
   }
 
   // Capture the version before updating so we can show what changed afterward.
   const versionBefore = currentVersion;
 
-  console.log(`\n${colors.yellow}Updating npm package...${colors.reset}`);
+  console.log(`\n${colors.yellow}Updating package via ${install.pm}...${colors.reset}`);
+
+  const updateCommand =
+    install.pm === "pnpm"
+      ? install.type === "global"
+        ? "pnpm add -g akili-specs@latest"
+        : "pnpm add akili-specs@latest"
+      : install.type === "global"
+        ? "npm install -g akili-specs@latest"
+        : "npm install akili-specs@latest";
 
   try {
-    if (installType === "global") {
-      execSync("npm install -g akili-specs@latest", { stdio: "inherit" });
-    } else {
-      execSync("npm install akili-specs@latest", { stdio: "inherit" });
-    }
+    execSync(updateCommand, { stdio: "inherit" });
 
-    console.log(`\n${colors.green}npm package updated successfully.${colors.reset}`);
+    console.log(`\n${colors.green}Package updated successfully via ${install.pm}.${colors.reset}`);
   } catch (e) {
-    console.error(`\n${colors.red}Failed to update npm package.${colors.reset}`);
+    console.error(`\n${colors.red}Failed to update package (ran: ${updateCommand}).${colors.reset}`);
     process.exit(1);
   }
 
@@ -628,18 +650,19 @@ function runUpdate(args) {
   // After reinstalling, read the freshly installed version and show the changelog
   // between the old and new versions. The running process still has the old code
   // loaded, so we read version + CHANGELOG from the installed package on disk.
-  const packageDir = resolveInstalledPackageDir(installType);
+  const packageDir = resolveInstalledPackageDir(install);
   const versionAfter = packageDir ? readInstalledVersion(packageDir) : null;
   printUpdateChangeSummary(packageDir, versionBefore, versionAfter);
 
   console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
   console.log(`${colors.cyan}Update Summary${colors.reset}`);
+  const installLabel = `${install.type} install via ${install.pm}`;
   if (versionAfter && versionAfter !== versionBefore) {
-    console.log(`  Package: ${versionBefore} → ${colors.green}${versionAfter}${colors.reset} (${installType} install)`);
+    console.log(`  Package: ${versionBefore} → ${colors.green}${versionAfter}${colors.reset} (${installLabel})`);
   } else if (versionAfter) {
-    console.log(`  Package: already up to date at ${colors.green}v${versionAfter}${colors.reset} (${installType} install)`);
+    console.log(`  Package: already up to date at ${colors.green}v${versionAfter}${colors.reset} (${installLabel})`);
   } else {
-    console.log(`  Package: updated from v${versionBefore} (${installType} install; new version could not be read)`);
+    console.log(`  Package: updated from v${versionBefore} (${installLabel}; new version could not be read)`);
   }
   const updatedTools = args.resolvedTools || selectedTools(args);
   console.log(`  Files: reinstalled with --force for ${updatedTools.join(", ")}${args.autoDetected ? " (auto-detected)" : ""} (see Install Summary above)`);

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
@@ -39,6 +42,8 @@ npm install -g akili-specs
 akili install --tool all
 ```
 
+pnpm works everywhere npm does: `pnpm dlx akili-specs …` for one-off runs, `pnpm add -g akili-specs` for a global install (after a one-time `pnpm setup`).
+
 To install directly into the local project workspace instead of globally, use the `--local` flag:
 
 ```bash
@@ -51,7 +56,7 @@ akili install --tool both --local
 |---|---|
 | `akili init` | Interactive setup wizard for installation |
 | `akili install` | Install commands, skills, and helper resources |
-| `akili update` | Update the npm package to the latest version, reinstall files, and print a changelog summary of what changed |
+| `akili update` | Update the package to the latest version (via the package manager that owns the install — npm or pnpm), reinstall files, and print a changelog summary of what changed |
 | `akili list` | List packaged commands, skills, and helper resources |
 | `akili doctor` | Check whether expected files are installed |
 | `akili help` | Show help |
@@ -67,6 +72,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/plans/2026-07-24-delegation-thresholds-review-lenses.md

@@ -0,0 +1,79 @@
+# Proposal: Delegation Thresholds + Execution Review Lenses
+
+**Status:** Implemented (2026-07-24) — shipped in the release following v2.12.0; see `CHANGELOG.md` → Unreleased
+**Date:** 2026-07-24
+**Author:** Leader session (reviewed against `gentle-ai` orchestrator→minion pattern)
+
+Adopt two practices observed in a convergent SDD methodology (`gentle-ai` / `sdd-orchestrator`) that AKILI-SPECS currently lacks: **quantified inline-vs-delegate thresholds** for the orchestrating agent, and **concrete review lenses (4R)** layered onto the execution Reviewer. Both are additive — no existing gate, loop guardrail, or persona contract changes.
+
+## Decision summary
+
+| # | Change | Where it lands | Risk |
+|---|--------|----------------|------|
+| 1 | Delegation Thresholds rule block | `.claude/templates/leader.md`, `/akili-execute`, `/akili-specify`, `/akili-constitution`, `/akili-audit` | Low — codifies existing instinct as numbers |
+| 2 | 4R review lenses (readability, reliability, resilience, risk) | `.claude/templates/reviewer.md`, `/akili-execute` Step 2.3, `/akili-validate` | Low–medium — widens Reviewer scope; mitigated by keeping spec-conformance as the only blocking gate by default |
+
+## 1. Delegation Thresholds
+
+### Problem
+
+The Leader triad in `/akili-execute` always delegates, but the methodology gives no numeric guidance for the orchestrator's *own* work in research-heavy commands (`/akili-constitution`, `/akili-specify`, `/akili-audit`). Today the orchestrating agent reads everything inline, polluting its context — exactly the "mega agente leyendo todo" anti-pattern.
+
+### Proposed rule block
+
+Add a shared **Delegation Thresholds** section (single source of truth in `.claude/templates/leader.md`, referenced — not copied — by the commands):
+
+| Situation | Action |
+|-----------|--------|
+| 1 file, quick check, `git status`, puntual verification | Inline — do it yourself |
+| Research requires reading **4+ files** | Spawn a scout/Explore subagent with fresh context; consume its conclusions, not the file dumps |
+| Writing **2+ non-trivial files** | Spawn an Implementer (already the rule inside `/akili-execute`; now explicit everywhere) |
+| Tests/builds | Subagent (`/akili-test` already complies) |
+| Review of a diff/PR | Fresh-context Reviewer, diff-only input (already the rule; restated here for completeness) |
+| Parallel writers | Only for fully independent tasks; isolated worktrees if the tool supports them (existing Step 1.4 rule, unchanged) |
+
+### Rationale
+
+- Cheap, actionable heuristic: the agent doesn't have to judge "is my context getting big?" — it counts files.
+- CodeGraph note: in codegraph-enabled projects, a `codegraph_context`/`codegraph_search` lookup does **not** count toward the 4-file threshold — that is precisely what the graph is for. The threshold counts full-file reads.
+
+## 2. Execution Review Lenses (4R)
+
+### Problem
+
+The execution Reviewer audits **spec conformance** only. That is stronger than a generic reviewer on traceability, but mono-lens: a diff can pass spec conformance while being unreadable, fragile, or risky. `judgment-day` covers multi-perspective review, but only at design time (`/akili-specify`), not at execution time.
+
+### Proposed design
+
+Two modes, selected by the existing **effort dial** — no new configuration surface:
+
+| Mode | When | Mechanics |
+|------|------|-----------|
+| **Lens checklist** (default) | Effort `low`/`medium`/`high` | The single Reviewer's brief adds a 4R checklist — readability, reliability, resilience, risk — reported as advisory findings. **Spec conformance remains the only PASS/FAIL gate.** 4R findings that are not spec violations go to `execution.md` as `ADVISORY`, never trigger a rework attempt |
+| **Parallel lens reviewers** | Effort `xhigh`/`max`, or task tagged security/migration/data-loss | Spawn 2–4 lens-scoped Reviewers in parallel (each gets the diff + one lens). Any lens may return FAIL; the Leader adjudicates whether a lens FAIL is in-scope for the task before consuming a rework attempt |
+
+### Guardrails (why this won't bloat the loop)
+
+- Advisory findings never consume rework attempts — the 3-attempt ceiling still binds to spec conformance only.
+- Parallel mode is opt-in via the effort dial, which the Leader already sets per task; no default token-cost increase.
+- The Reviewer stays read-only and diff-only; lenses change *what it looks for*, not *what it receives*.
+
+## Out of scope
+
+- No change to `judgment-day` (design-time review is already multi-perspective).
+- No change to the rework loop structure, FATAL_FAIL, or Pivot Protocol.
+- No new agent personas — lenses are briefs, not files.
+
+## Implementation checklist
+
+- [x] Add **Delegation Thresholds** section to `.claude/templates/leader.md` (source of truth).
+- [x] Reference the thresholds from `/akili-execute` (Multi-Agent Triad section), `/akili-specify`, `/akili-constitution`, `/akili-audit` (research steps).
+- [x] Add 4R lens checklist + `ADVISORY` output contract to `.claude/templates/reviewer.md`.
+- [x] Update `/akili-execute` Step 2.3 with the two-mode lens table and effort-dial trigger.
+- [x] Update `/akili-validate` to include 4R advisory reporting in its final audit (Phase 5 sweep + report section 7).
+- [x] `CHANGELOG.md` → `Unreleased` entry (methodology change → next release is **minor**).
+- [ ] Smoke: run `/akili-execute` on a sample spec and confirm ADVISORY findings land in `execution.md` without consuming attempts (pending first real-project run).
+
+## Next step
+
+Live-fire smoke on the next real `/akili-execute` run, then release as part of the next **minor** version.

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.13.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {