akili-specs 2.8.0 → 2.10.0

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

@@ -56,6 +56,8 @@ docs/specs/archive/2026-05-16-bugfix--login-redirect/
 
 ### Step 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** (summarization and bookkeeping). 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 T5 — the registry recommends `/model haiku`; you are on opus"* — 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.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Confirm `docs/specs/$ARGUMENTS/` exists.

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

@@ -19,6 +19,8 @@ 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.
+
 First, read the constitutional documentation baseline in the repository:
 
 1. `docs/prd.md`
@@ -44,6 +46,7 @@ Audit for discrepancies, classifying findings under the following categories:
 * **Visual/Design Token Mismatch:** Colors, typography, spacing, or component structures used in the codebase that violate the styling tokens and design principles declared in `docs/ux-ui/design.md`.
 * **Technical Constraints Violation:** Architectural layout in the codebase that conflicts with patterns (e.g. testing requirements, security rules, file structuring) documented in `docs/trd/trd.md`.
 * **Agent Guide Drift:** Modules whose conventions clearly diverge from the root but lack a child `CLAUDE.md`/`AGENTS.md`, child guides missing from the parent's `## Module Guides` index, guide entries pointing at modules that no longer exist, or root-guide structure descriptions that no longer match the codebase.
+* **Model Registry Drift:** The project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) names models the host tool no longer offers, uses dated model pins where a floating alias exists (violating the alias-first rule) without a recorded reason, is missing tiers or the author ≠ auditor note versus the packaged default in `docs/model-routing.md`, or the Step 8E agent wrappers (`.claude/agents/akili-*.md` / OpenCode agent config) declare models that contradict the registry. Report only — never edit the registry or wrappers during the audit.
 
 ### Step 3: Write Drift Report
 
@@ -87,6 +90,7 @@ A brief overview of the codebase alignment state and major areas of specificatio
 | UX/UI Design / Screen Inventory | [Details] | [Aligned / Drifted] | |
 | TRD (APIs/DB) | [Details] | [Aligned / Drifted] | |
 | Agent Guides (root + `## Module Guides` index) | [Details] | [Aligned / Drifted] | |
+| Model Routing (registry + Step 8E wrappers) | [Details] | [Aligned / Drifted] | |
 
 ## Recommended Next Steps
 Specific actions to resolve the discrepancies (e.g., "Run `/akili-constitution` to enhance baseline", "Update `trd.md` with active REST APIs", or "Schedule a task to implement missing validation tests").

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

@@ -19,6 +19,8 @@ Establish or strengthen the project-wide AKILI-SPECS foundation. This command cr
 
 ### Step 0: Determine Project Mode and Foundation Setup
 
+**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for repository ingestion and **T1 Architect** for baseline synthesis (if no project registry exists yet, use the packaged default in `docs/model-routing.md`). 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. *"Baseline synthesis is T1 — the default registry recommends `/model opus`; 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.
+
 Before classifying the repository, use the `brainstorming` skill to ask the user if this is a new project/MVP starting from 0, or if it is an existing project with an established structure.
 
 Based on the response, classify the repository into one of three modes. The classification is non-destructive — it controls how aggressively the constitution drafts, scans, or preserves existing material.
@@ -34,7 +36,7 @@ For all three modes:
 3. Ensure `docs/specs/general-setup/` exists.
 4. Ensure root `CLAUDE.md` exists or is enhanced.
 5. Ensure root `AGENTS.md` exists or is enhanced.
-6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 7B).
+6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 8B).
 7. Default behavior is to enhance existing project docs in place instead of creating parallel copies.
 
 The constitutional baseline must cover these files:
@@ -210,6 +212,8 @@ When the file already exists, refine it in place instead of replacing establishe
 
 Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 
+**Required skill:** load `software-architect` before drafting the TRD and apply its Decision Spine throughout this step — capture NFRs as six-part quality-attribute scenarios with measurable responses, choose tactics, decide the robust-vs-lite tier and architecture style, bind design patterns to named problems, and document with C4 views plus ADRs.
+
 **Use skills when relevant** (stack skills — load only the ones matching the project's stack; the same set feeds the `## Skill Map` in Step 8D):
 
 - `nestjs-expert`
@@ -224,16 +228,18 @@ Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 **Required structure:**
 
 1. System Overview
-2. Domain Modules & Responsibilities
-3. Data Model & Entities
-4. API Surface & Contracts
-5. Backend Workflows & Business Rules
-6. Frontend Architecture & State Boundaries
-7. Integration Points
-8. Security & Authorization Model
-9. Error Handling & Observability
-10. Testing Strategy
-11. Technical Constraints & Assumptions
+2. Architecture Overview & Decisions (C4 Context + Container with legends, style choice, robust-vs-lite tier decision, ADR index)
+3. Quality Attribute Scenarios (Non-Functional Requirements — six-part scenarios with measurable responses and chosen tactics; security, performance, scalability, and availability always evaluated)
+4. Domain Modules & Responsibilities
+5. Data Model & Entities
+6. API Surface & Contracts
+7. Backend Workflows & Business Rules
+8. Frontend Architecture & State Boundaries
+9. Integration Points
+10. Security & Authorization Model
+11. Error Handling & Observability
+12. Testing Strategy
+13. Technical Constraints & Assumptions
 
 ---
 
@@ -241,6 +247,8 @@ Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 
 Create or enhance `docs/infrastructure.md` as the deployment and hosting blueprint.
 
+The infrastructure shape derives from the TRD's robust-vs-lite tier decision (Step 5, `software-architect` skill) — never precedes it. Cite the tier decision and its ADR at the top of the document.
+
 **Required structure:**
 
 1. Target Environment (e.g., AWS, GCP, Vercel, On-prem)
@@ -291,7 +299,7 @@ The update should explain briefly:
 - How module specs should be organized under `docs/specs/`
 - Which skills should be used for common work in the project (the `## Skill Map` added in Step 8D)
 - Whether CodeGraph is initialized and how agents should use it for existing-project analysis
-- Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 7C)
+- Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 8C)
 
 Preserve the repository's existing `CLAUDE.md` and `AGENTS.md` conventions and extend them.
 
@@ -379,21 +387,28 @@ project guides so the project does not depend on the package's `docs/` after ins
    must differ from the Implementer model. `/akili-test` is likewise split into its Leader (T5,
    orchestration) and Tester(s) (T2, test authoring), with a note to prefer a Tester model different
    from the Implementer (author ≠ tester).
-4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`.
-   Fill the Claude Code column for the user's plan (e.g. PRO: Opus reserved for T1/T3, Sonnet as the
-   T2/T4/T6 workhorse, Haiku for T5). Fill the OpenCode column from the user's confirmed roster; if
-   it is unknown, leave clearly-marked `<CONFIRM SLUG>` placeholders rather than guessing.
-5. The instruction: *"To change models, edit only this registry table. Model selection is guidance
-   only — never add `model:` to command frontmatter."*
+4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`, plus
+   an `Updated: <YYYY-MM>` stamp. **Alias-first rule:** the Claude Code column uses floating aliases
+   (`opus`, `sonnet`, `haiku`) — they always resolve to the latest generation, so the registry
+   survives model churn with zero edits; pin a dated model ID only when the user deliberately wants
+   to freeze a version, and record why. Fill the OpenCode column from the user's confirmed roster
+   (slugs are concrete — no alias mechanism); if it is unknown, leave clearly-marked
+   `<CONFIRM SLUG>` placeholders rather than guessing.
+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."*
 
-**Mode-specific policy (mirror Step 7B):**
+**Mode-specific policy (mirror Step 8B):**
 
 - **Brand-new (Seed Setup):** insert the full `## Model Routing` section using the packaged defaults.
 - **Legacy (Discovery Setup):** insert the section and, where detected, annotate the registry with
   the project's actual tooling (e.g. note if the team already standardizes on a specific model).
 - **Active AKILI-SPECS (Safe Update):** **do not overwrite** an existing customized registry. If the section
   is missing, add it; if it exists, only fill gaps (missing tiers, missing author ≠ auditor note)
-  without changing the user's pinned models.
+  without changing the user's pinned models. Additionally, **flag stale entries**: compare the
+  project registry against the packaged default in `docs/model-routing.md` and list (do not edit)
+  entries that name models the tool no longer offers or dated pins that an alias would now cover —
+  the user decides whether to refresh them.
 
 Confirm the user's available models before writing concrete identifiers: which tier they run in
 Claude Code (and their plan's rate limits) and which models their OpenCode roster exposes.
@@ -428,6 +443,58 @@ is how they reach the agents.
 
 ---
 
+### Step 8E: Bind Personas to Models (Tool-Native Agent Wrappers)
+
+Offer to generate **tool-native agent definitions** that bind the `.agents/` personas to the models
+in the `## Model Routing` registry (Step 8C). This turns model routing from guidance into
+enforcement for the multi-agent fan-out — where most tokens are spent — and makes
+**author ≠ auditor structural**: the Reviewer wrapper is pinned to a different model than the
+Implementer wrapper in configuration, not by human discipline.
+
+Ask the user first (one question): *"Bind the AKILI personas to models with native agent wrappers,
+so the Implementer/Reviewer/Tester automatically run on their tier's model?"* If declined, skip
+this step — the guidance-only flow keeps working.
+
+**Per tool:**
+
+- **Claude Code:** create project-level `.claude/agents/akili-leader.md`, `akili-implementer.md`,
+  `akili-reviewer.md`, and `akili-tester.md`. Each wrapper is thin:
+
+  ```markdown
+  ---
+  name: akili-implementer
+  description: AKILI Implementer — executes one spec task with strict scope and verification.
+  model: sonnet
+  ---
+  Read `.agents/implementer.md` in the project root and adopt it fully as your persona and
+  operating contract before doing anything else.
+  ```
+
+  Models come from the registry's Claude Code column as **aliases** (default: leader `haiku`,
+  implementer `sonnet`, reviewer `opus`, tester `sonnet`). Never copy the persona body into the
+  wrapper — `.agents/` stays the single source of truth.
+
+- **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.1`, reviewer
+  `opencode-go/deepseek-v4-pro`, leader `opencode-go/deepseek-v4-flash`).
+
+- **Google Antigravity:** no per-agent model binding exists — skip wrapper generation and note in
+  the summary that Antigravity stays on guidance-only routing.
+
+**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.
+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).
+3. **Mode policy:** Brand-new/Legacy — create the wrappers when accepted. Active AKILI-SPECS —
+   never overwrite existing wrapper files; create only missing ones and flag model drift between
+   existing wrappers and the current registry.
+
+---
+
 ### Step 9: Present and Confirm
 
 After drafting or enhancing the documents, generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) covering:

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

@@ -52,17 +52,21 @@ If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not
 
 **Delegation mechanism by tool:**
 
-- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
-- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/`.
+- **Claude Code / OpenCode:** if the project has tool-native AKILI agent wrappers (scaffolded by `/akili-constitution` Step 8E — e.g. `.claude/agents/akili-implementer.md` / `akili-reviewer.md` with `model:` bindings from the `## Model Routing` registry), **spawn those named agents** so each role runs on its tier's model and author ≠ auditor is enforced by configuration. Otherwise, spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/` (no per-agent model binding — guidance-only routing).
 
 The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
 
+**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).
+
 ---
 
 ## Behavior
 
 ### Step 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** for you as Leader — the Implementer/Reviewer route through the Step 8E agent wrappers (their own tier models) when present. 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. *"The Leader loop is T5 — the registry recommends `/model haiku`; you are on opus"* — 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.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Read the project constitutional docs (IN THIS ORDER):

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

@@ -55,6 +55,8 @@ Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unle
 
 ### Step 0: Resolve Path And Load Context
 
+**Model checkpoint:** This phase runs best on **T1 Architect** (deep reasoning). 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 T1 — the registry recommends `/model opus`; you are on sonnet"* — 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.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Resolve `$SPEC_PATH` using the path rules above.

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

@@ -60,6 +60,8 @@ State clearly which criterion failed and which command to run instead. Never sil
 
 ### Step 0: Load Minimal Context
 
+**Model checkpoint:** This phase runs best on **T2 Coder** (small direct edit, light verification). 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 T2 — the registry recommends `/model sonnet`; you are on opus"* — 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.
+
 Keep context small — this is a trivial change, not a full spec run.
 
 1. Read only what the change needs:

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

@@ -74,6 +74,8 @@ If any prerequisite is missing, stop and report exactly what is missing and how
 
 ### Phase 0: Setup
 
+**Model checkpoint:** This phase runs best on **T3 Auditor** for audit findings and **T5 Fast-Cheap** for setup/formatting. 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. *"The audit phase is T3 — the registry recommends `/model opus`; 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.
+
 1. Resolve the spec path. If `$ARGUMENTS` is a bare domain, set `SPEC_PATH = seo/<domain>`. Otherwise treat `$ARGUMENTS` as the literal spec path.
 2. Create directory `docs/specs/$SPEC_PATH/` if it does not exist.
 3. Read the constitutional templates and project context as defined in `akili-specify`:

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

@@ -61,6 +61,8 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
 
 ### Step 0: Setup
 
+**Model checkpoint:** This phase runs best on **T1 Architect** for requirements/design (re-check at Phase 3: **T5 Fast-Cheap** for the tasks split, **T6 Multimodal** when visual design is in scope). 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. *"Phases 1–2 are T1 — the registry recommends `/model opus`; 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.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Create directory `docs/specs/$ARGUMENTS/` if it does not exist.
@@ -177,6 +179,8 @@ Wait for the user's response before moving on.
 
 Use `brainstorming` to explore trade-offs before writing.
 
+If the feature is architecturally significant (a new module or service, a new integration or data flow, a persistence or communication-topology change, or any stated NFR impact), load `software-architect` and apply its Decision Spine: NFR scenarios with measurable responses, tactics, robust-vs-lite sizing, pattern selection bound to named problems, and ADR-style design decisions.
+
 If the work includes meaningful UI/UX impact, use this skill preference:
 
 - `ui-ux-pro-max` if available

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

@@ -50,13 +50,14 @@ If `.agents/tester.md` is missing, run `/akili-constitution` first to scaffold i
 
 **Delegation mechanism by tool:**
 
-- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
-- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md`.
+- **Claude Code / OpenCode:** if the project has a tool-native `akili-tester` agent wrapper (scaffolded by `/akili-constitution` Step 8E with a `model:` binding from the `## Model Routing` registry), **spawn that named agent** so each Tester runs on its tier's model — preferring a model different from the Implementer's (author ≠ tester). Otherwise, spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md` (no per-agent model binding — guidance-only routing).
 
 **Token discipline — thin context per Tester (this is the core saving):**
 
 - Give each Tester **only its slice**: its assigned suite, the specific requirements + Given/When/Then scenarios that suite must prove, and the project's test command. Never hand a Tester the full `requirements.md`/`design.md`/`tasks.md` unless a scenario genuinely needs it.
 - Each Tester's context is discarded when it finishes, so per-suite contexts never accumulate in one growing window.
+- Load the `caveman` skill and apply its Scope Contract: Leader→Tester context slices and Tester structured reports use `full` compression; `test-report.md`, `PRODUCT_BUG` escalations to the user, and verbatim evidence (requirement and Given/When/Then scenario text quoted in slices, test output, `STATUS:` lines, error strings) are never compressed.
 - The Leader writes no tests itself unless the Deployment Rule below says to run inline, or a Tester exhausts its inner loop and the user approves a Leader fallback.
 
 **Deployment Rule (how many Testers to spawn):**
@@ -76,6 +77,8 @@ The Leader decides the count from the spec's depth and the independence of the s
 
 ### Phase 0: Load Context (Leader)
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** for you as Leader — Testers route through the `akili-tester` wrapper (T2) when present. 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. *"The Leader loop is T5 — the registry recommends `/model haiku`; you are on opus"* — 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.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Read project-level context (IN THIS ORDER):

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

@@ -49,6 +49,8 @@ Use these result levels consistently:
 
 ### Phase 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T3 Auditor** — and it MUST resolve to a different model than the one that implemented the work (author ≠ auditor). 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 T3 — the registry recommends `/model opus`; you are on sonnet, which also implemented the spec"* — 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.
+
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
 1. Read constitutional context (IN THIS ORDER):

package/.claude/skills/caveman/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: caveman
+description: "Trigger: token efficiency, 'less tokens', 'be brief', caveman mode, inter-agent communication in /akili-execute and /akili-test. Ultra-compressed communication style (~65% fewer output tokens, measured upstream) for TRANSIENT agent output only — technical substance stays, fluff dies. Never applies to persistent documents (cognitive-doc-design territory) or HITL approval gates."
+license: MIT
+metadata:
+  author: Julius Brussee
+  source: https://github.com/juliusbrussee/caveman
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core
+  version: "1.0"
+---
+
+# Caveman — Token-Economy Communication for Transient Agent Output
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+In AKILI, output-token waste is **MUDA** (see `kaizen`). This skill is the preventive tactic: it compresses the style of *transient* agent output — the chatter nobody rereads — while the documents humans live with stay under `cognitive-doc-design`.
+
+## Scope Contract (the AKILI boundary — read first)
+
+| Output | Caveman? | Level |
+|---|---|---|
+| Inter-agent messages (Leader ↔ Implementer / Reviewer / Tester): task briefs, completion reports, status relays — the verbatim zones below always win (Reviewer/Tester reports relay unchanged) | **Yes** | `full` |
+| Progress narration and status lines shown to the user mid-run | **Yes** | `lite` |
+| Persistent artifacts: PRD, TRD, `requirements.md`, `design.md`, `tasks.md`, `execution.md` audit entries, `test-report.md`, PR descriptions, Kaizen log | **No** — `cognitive-doc-design` owns artifacts | off |
+| HITL approval gates: option menus, blocker questions, end-of-task summaries the user decides on | **No** — decision quality > token savings | off |
+| Security warnings, irreversible-action confirmations, Pivot Protocol blockers | **No** (upstream Auto-Clarity rule) | off |
+| Verbatim evidence: requirement text and Given/When/Then acceptance criteria quoted in briefs/slices, error strings, Reviewer findings passed to rework, test output, code, commands | **Never compressed or paraphrased** | n/a |
+
+One sentence to remember: *`cognitive-doc-design` owns artifacts; `caveman` owns transient agent output.*
+
+## Rules (upstream, preserved)
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). No tool-call narration, no decorative tables/emoji, no dumping long raw error logs unless asked — quote shortest decisive line. Standard tech acronyms OK (DB/API/HTTP); **never invent abbreviations** (cfg/impl/req/res/fn) — tokenizer splits them same as full word: zero tokens saved, reader still decodes. No causal arrows (→) — own token, saves nothing. Technical terms exact. Code blocks unchanged. Errors quoted exact.
+
+Preserve the user's dominant language — compress the style, not the language (Spanish user gets Spanish caveman). Keep technical terms, code, API names, CLI commands, commit-type keywords, and exact error strings verbatim.
+
+No self-reference: never announce or name the style, no "caveman mode on".
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+- Not: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..."
+- Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Intensity Levels (upstream; AKILI uses `lite` and `full`)
+
+| Level | What changes |
+|---|---|
+| **lite** | No filler/hedging. Keep articles + full sentences. Professional but tight |
+| **full** | Drop articles, fragments OK, short synonyms. No tool-call narration, no decorative tables/emoji, no raw log dumps. Standard acronyms OK; no invented abbreviations |
+| **ultra** | Strip conjunctions when unambiguous; one word when one word enough. Not used by AKILI defaults — allowed only if the user explicitly asks |
+| wenyan-* | Classical-Chinese register variants from upstream; not used by AKILI |
+
+Example — "Why React component re-render?"
+- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
+- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+
+## Auto-Clarity (upstream, preserved and extended)
+
+Drop caveman when: security warnings; irreversible-action confirmations; multi-step sequences where fragment order risks misread; compression itself creates ambiguity (`"migrate table drop column backup first"` — order unclear); the user asks to clarify or repeats a question. **AKILI extension:** every HITL pause is an Auto-Clarity zone by definition. Resume caveman after the clear part is done.
+
+## AKILI-SPECS Integration
+
+| AKILI moment | This skill's job |
+|---|---|
+| `/akili-execute` | Leader→Implementer briefs, Implementer completion reports, Leader relay of Reviewer feedback: `full`. Progress lines: `lite`. `execution.md` audit entries, PR descriptions, HITL summaries and Pivot blockers: **off** |
+| `/akili-test` | Leader→Tester context slices and Tester structured reports: `full`. `test-report.md` and PRODUCT_BUG escalations to the user: **off** |
+| Every other command | Not loaded. Documents and user-facing methodology output are `cognitive-doc-design` territory |
+| `kaizen` | Token savings from compressed inter-agent chatter are measurable MUDA reduction; a retrospective may cite them |
+
+Adaptation rules: the Structured Feedback rule of `/akili-execute` wins over compression — Reviewer FAIL reports pass to the next Implementer **unchanged, never paraphrased**; a Tester's `STATUS:` lines and evidence quotes are verbatim zones; when in doubt whether output is transient or persistent, treat it as persistent (off).

package/.claude/skills/cognitive-doc-design/SKILL.md

@@ -32,6 +32,8 @@ Use it especially for:
 
 The AKILI templates in `docs/specs/general-setup/` win over the default Documentation Shape below — apply the Critical Patterns inside their structure.
 
+**Boundary with `caveman`:** this skill owns *persistent artifacts* (documents humans reread — PRDs, TRDs, specs, reports, PR descriptions); `caveman` owns *transient agent output* (inter-agent messages, progress narration in `/akili-execute` and `/akili-test`). Never apply caveman compression to a document this skill governs, and never pad transient chatter with document structure.
+
 ## Critical Patterns
 
 | Pattern | Rule |

package/.claude/skills/software-architect/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: software-architect
+description: "Trigger: TRD creation, architecture design, non-functional requirements (NFR), quality attributes (security, performance, scalability, availability), architecture styles (hexagonal, clean architecture, microservices, serverless, modular monolith), design patterns (adapter, bridge, builder, GoF), C4 diagrams, ADRs, robust-vs-lite stack sizing. Senior software architect skill: capture NFRs as testable scenarios, choose tactics, size the architecture tier, select patterns, document with C4 + ADRs."
+license: MIT
+metadata:
+  author: Juan Carlos Cadavid — jcadavid.com
+  binding: core
+  version: "1.0"
+  inspired-by: "SEI quality-attribute scenarios & tactics (Bass/Clements/Kazman, Software Architecture in Practice), Documenting Software Architectures: Views and Beyond (Clements et al., SEI), the C4 model (Simon Brown), Refactoring.Guru design patterns catalog (Alexander Shvets), Clean Architecture (Robert C. Martin), Hexagonal/Ports & Adapters (Alistair Cockburn), Google Cloud agentic AI architecture guides"
+---
+
+# Software Architect — The AKILI Architecture & NFR Skill
+
+This skill makes the agent operate as a **senior software architect**: the role accountable for translating business needs into system structure, identifying non-functional requirements before they become production incidents, selecting technology deliberately, and leaving every decision documented and justified. Architecture is decided by evidence, never by fashion.
+
+> Requirements without measures are wishes. Patterns without problems are decoration. Infrastructure without a tier decision is gambling.
+
+This file is the **core + router**: the decision method every architecture task needs, plus a table telling you which `references/` file to load. Read the core, then load exactly the reference(s) the task requires — never all of them.
+
+## Activation Contract
+
+Load this skill when:
+
+- `/akili-constitution` reaches **Step 5 (TRD)** — the primary, automatic trigger. Step 6 (Infrastructure) inherits its tier decision.
+- `/akili-specify` Phase 2 designs an **architecturally significant** feature: a new module or service, a new integration or data flow, a change to persistence or communication topology, or any stated NFR impact.
+- The user asks for architecture review, NFR identification, technology/stack selection, or design-pattern guidance.
+
+Not for trivial changes: `/akili-quick` work and single-component edits never need this skill.
+
+## The Decision Spine (the AKILI method)
+
+Every architecture engagement walks the same five steps, in order. Each step's output feeds the next; skipping a step means a later decision has no justification.
+
+| # | Step | Question it answers | Output |
+|---|---|---|---|
+| 1 | **Scenario** | What must the system *withstand*? | NFRs as six-part quality-attribute scenarios with **measurable responses** |
+| 2 | **Tactic** | What design decision satisfies each scenario? | Named tactics per attribute (e.g. replication, encapsulation, caching, rate limiting) |
+| 3 | **Tier & Style** | How much architecture do these tactics justify? | Robust-vs-lite tier decision + architecture style (hexagonal, clean, microservices…) |
+| 4 | **Pattern** | Which proven structures implement the style? | Design patterns bound to named problems, with rejected alternatives |
+| 5 | **View & Record** | How does everyone else understand it? | C4 diagrams (with legend), ADRs for hard-to-undo decisions, TRD sections |
+
+The spine is traceable in both directions: every pattern points back to a tactic, every tactic to a scenario, every scenario to a business driver. A reviewer (or `judgment-day`) must be able to ask "why does this exist?" at any node and get an answer from the document, not from memory.
+
+## The Robust-vs-Lite Gate (Step 3 detail)
+
+Default to **LITE**. Escalate to **ROBUST** only when a scenario's response measure cannot be met without it — and record the escalation as an ADR.
+
+| Axis | LITE (default) | ROBUST (needs evidence) |
+|---|---|---|
+| Structure | Modular monolith, clean/hexagonal layering inside one deployable | Microservices / event-driven topology |
+| Compute | Serverless or single managed runtime | Containers/orchestration, dedicated clusters |
+| Data | One primary database + cache | Polyglot persistence, CQRS, event sourcing |
+| Async | Direct calls + one queue where needed | Broker topology, sagas, streaming |
+| AI | Single agent, managed LLM API | Multi-agent orchestration, self-hosted models |
+
+Escalation triggers (any one, evidenced by a scenario): independent scaling of hot paths; team count > deployables; divergent availability targets per module; regulatory isolation; response measures a monolith demonstrably cannot meet. **"We might need it later" is not a trigger** — record it under Technical Constraints & Assumptions as a revisit condition instead. The tier decision is what `docs/infrastructure.md` (constitution Step 6) derives its shape from.
+
+## Routing — load the matching reference
+
+| If the task involves… | Read |
+|---|---|
+| Capturing/refining NFRs, quality-attribute scenarios, tactics per attribute (availability, performance, security, modifiability, scalability, observability, cost) | `references/nfr-scenarios.md` |
+| Choosing architecture style — hexagonal, clean, modular monolith, microservices, event-driven, serverless, CQRS — and the robust-vs-lite matrix, incl. Node.js/TypeScript layer mapping | `references/architecture-styles.md` |
+| Selecting or justifying design patterns (22-pattern GoF-based catalog), SOLID/design principles, tactic→pattern bridge | `references/design-patterns.md` |
+| Documenting: C4 levels, choosing views per stakeholder, view template, ADR template, interface specs | `references/views-documentation.md` |
+| AI/LLM system architecture: agent patterns (single, ReAct, sequential, coordinator…), component decisions (framework, memory, tools, runtime), RAG/vector storage | `references/agentic-ai.md` |
+
+A full TRD normally needs `nfr-scenarios.md` + `architecture-styles.md`, and `views-documentation.md` when drawing views; load `design-patterns.md` only when module design starts, and `agentic-ai.md` only when the system embeds LLM/agent behavior.
+
+## Hard Rules
+
+1. **No NFR without a measure.** Every quality-attribute scenario ends in a response measure a tester could verify (number, threshold, or observable condition). "The system must be fast/secure/scalable" never appears in a document this skill touched.
+2. **Minimum NFR sweep.** Always evaluate security, performance, scalability, and availability explicitly — plus modifiability, observability, and cost when the system will live longer than a prototype. Explicitly marking an attribute "not architecturally significant here" is valid output; silence is not.
+3. **No pattern without a named problem.** A design pattern enters the design only bound to the problem it solves and the tactic it implements; state the simpler alternative it beat.
+4. **Start lite, escalate with evidence** through the Robust-vs-Lite Gate; escalations become ADRs.
+5. **ADRs for the hard-to-undo.** Decisions that are expensive to reverse, took real evaluation effort, or will confuse future readers get an ADR (issue → decision → alternatives → argument → implications). Never defer rationale.
+6. **Every diagram has a legend.** C4 levels Context and Container are the default; Component only for complex containers; Code level almost never.
+7. **Respect the stack, then challenge it.** Read the project's declared stack and `## Skill Map` first; propose deviations (e.g. Go for a hot path, Python for ML) only through an ADR with a scenario as evidence.
+8. **Token frugality (MUDA).** Conceptual designs only — no implementation code in TRD/design documents. Load only the references the task needs. Reuse existing document sections instead of restating them.
+
+## Output Contract — where the spine lands in the TRD
+
+| Spine output | TRD home (`docs/trd/trd.md`) |
+|---|---|
+| C4 Context + Container, style choice, tier decision | `Architecture Overview & Decisions` |
+| Six-part scenarios + chosen tactics | `Quality Attribute Scenarios (Non-Functional Requirements)` |
+| ADR log (compact table + per-ADR entries) | `Architecture Overview & Decisions` |
+| Pattern selections with justification | `Domain Modules & Responsibilities` / feature `design.md` §Design Decisions |
+| Security scenarios & tactics detail | `Security & Authorization Model` |
+| Observability scenarios detail | `Error Handling & Observability` |
+| Tier consequences for deployment | `docs/infrastructure.md` (Step 6 input) |
+
+In `/akili-specify`, the same outputs land in `design.md`: Architecture Overview, Design Decisions (ADR-style), and requirement-linked NFR scenarios.
+
+## AKILI-SPECS Integration
+
+| AKILI moment | This skill's job |
+|---|---|
+| `/akili-constitution` Step 5 (TRD) | Run the full Decision Spine; produce Architecture Overview & Decisions + Quality Attribute Scenarios sections; sweep the minimum NFR set against the PRD |
+| `/akili-constitution` Step 6 (Infrastructure) | Hand over the tier decision — infrastructure shape derives from robust-vs-lite, never precedes it |
+| `/akili-specify` Phase 2 (design.md) | Spine on feature scale: scenarios for the feature's NFR deltas, patterns for its module design, ADR-style Design Decisions |
+| `judgment-day` review gate | The spine's traceability (scenario → tactic → pattern) is what the judges audit; keep every link explicit in the document |
+| `/akili-execute` | Not loaded — implementers receive decisions through the TRD/design docs, not by re-running this skill |
+
+Adaptation rules: PRD business goals are the only valid source of scenario stimuli (no invented requirements); the project `## Skill Map` and declared stack constrain style choices before preference does; scenario measures become test candidates for `/akili-test`'s non-functional checks.
+
+## References (attribution)
+
+Method synthesized and authored by Juan Carlos Cadavid for AKILI-SPECS, standing on: SEI quality-attribute scenarios and tactics (Bass, Clements & Kazman — *Software Architecture in Practice*), *Documenting Software Architectures: Views and Beyond* (Clements et al.), the C4 model (Simon Brown), the Refactoring.Guru pattern catalog (Alexander Shvets), Clean Architecture (Robert C. Martin), Hexagonal Architecture (Alistair Cockburn), and Google Cloud's agentic AI architecture guides.

package/.claude/skills/software-architect/references/agentic-ai.md

@@ -0,0 +1,59 @@
+# Agentic AI Architecture — Patterns & Component Decisions
+
+For systems embedding LLM/agent behavior. The Decision Spine applies unchanged: token cost, latency, and accuracy are **quality-attribute scenarios** like any other — write measures first, then pick the pattern. The Robust-vs-Lite gate is strictest here because agent complexity multiplies token spend.
+
+## Pattern Catalog — cheapest that meets the measure wins
+
+### Single-agent (LITE — the default)
+| Pattern | Idea | Choose when |
+|---|---|---|
+| **Single Agent** | One model + tools + system prompt, end-to-end | Start here. Most assistant/automation features |
+| **ReAct loop** | Think → act → observe until done | Dynamic environments, multi-step tool use; accuracy > latency |
+
+### Multi-agent (ROBUST — each needs a scenario)
+| Pattern | Idea | Choose when | Cost profile |
+|---|---|---|---|
+| **Sequential** | Linear pipeline, output → input | Fixed repeatable stages (ingest → classify → draft) | Low |
+| **Parallel** | Independent subagents, results synthesized | Decomposable subtasks; latency reduction | Medium |
+| **Loop** | Repeat until exit condition | Iterative refinement; **hard termination guard required** | Runaway risk |
+| **Review-Critique** | Generator + critic gate | High-accuracy output (audited code, compliance text) | +1 model call per cycle |
+| **Coordinator** | Central agent routes to specialists dynamically | Adaptive triage; heterogeneous requests | High (routing calls) |
+| **Hierarchical** | Recursive decomposition tree | Open-ended research-class problems | Very high |
+| **Swarm** | Peer-to-peer agents, no orchestrator | Almost never justified in products | Highest |
+
+### Cross-cutting
+- **Human-in-the-Loop** — approval pauses at defined points; mandatory for high-stakes/irreversible actions (a security tactic, not an option).
+- **Custom logic orchestration** — deterministic code decides the flow, agents fill steps; prefer this over agent-decides-everything when the workflow is known (cheaper, testable, debuggable).
+
+Escalation rule: Single Agent → add tools → ReAct → Sequential/Custom logic → one specialized multi-agent pattern. Each step is an ADR citing the measure the previous step failed.
+
+## Component Decision Axes
+
+| Axis | LITE | ROBUST | Decision driver (scenario) |
+|---|---|---|---|
+| Model access | Managed API: Bedrock, OpenAI, Anthropic | Multi-model routing; fine-tuned/self-hosted | Cost/latency measures; data-residency security scenarios |
+| Model choice | One capable default model | Router: small model first, escalate on confidence | Cost ceiling per request |
+| Tools | Few function tools in-process | MCP servers / API-gateway-governed tools | Tool reuse across agents; governance requirements |
+| Memory (short) | In-context only | Externalized session state (Redis/DynamoDB) | Horizontal scaling scenario — any multi-instance deploy forces this |
+| Memory (long) / RAG | S3 Vectors + Bedrock KB, single index | OpenSearch vector store, hybrid search, reranking | Corpus size, recall measures, filter complexity |
+| Runtime | Lambda / managed agent runtime | Containers (ECS/EKS) for long-running or stateful agents | Execution time limits, streaming needs |
+| Guardrails | Provider-level (Bedrock Guardrails) + input validation | Dedicated eval/guard pipeline, red-team suite | Security & compliance scenarios |
+
+AWS-first defaults (per AKILI expertise): Bedrock for orchestration/models, S3 Vectors for lite RAG, OpenSearch for robust retrieval, Step Functions for deterministic orchestration of agent steps; OpenAI/Anthropic APIs when the project's ecosystem or model requirements dictate.
+
+## LLM-Specific NFR Scenarios (write these explicitly)
+
+- **Cost:** `1000 requests/day → agent pipeline ⇒ ≤ $X/month; alarm at 80%` — token budget is a response measure.
+- **Latency:** p95 including model calls; streaming-first for user-facing paths.
+- **Accuracy/quality:** eval-set pass rate ≥ X% before deploy; regression evals in CI.
+- **Safety/security:** prompt-injection resistance on tool-using paths (treat all retrieved/user content as untrusted input to tools); PII redaction before external model calls; auditable trace of every tool invocation (non-repudiation tactic).
+- **Availability:** provider outage behavior — degrade to smaller model / cached answers / honest failure (graceful-degradation tactic + circuit breaker on the provider port).
+- **Determinism boundary:** which steps must be reproducible (temperature 0, seeded, or code) vs creative — record as variability.
+
+## Architecture Rules for LLM Systems
+
+1. The model provider sits behind a **port** (hexagonal): swapping Bedrock ↔ OpenAI ↔ Anthropic touches one adapter — this is the modifiability tactic that pays for itself first.
+2. Prompts and model config are **versioned artifacts** (config/defer-binding tactic), not string literals in code.
+3. Every agent action is **observable**: correlation ID from user request through every model/tool call (traces are also the audit log).
+4. Multi-agent is a distributed system: apply the same rigor — idempotency, timeouts, budgets-as-bulkheads (max tokens/steps per request).
+5. In the C4 container view, model providers and vector stores are external systems/containers with labeled protocols; the trust boundary between them and user data is drawn explicitly.