akili-specs 2.8.0 → 2.10.0

package/.claude/skills/software-architect/references/architecture-styles.md

@@ -0,0 +1,67 @@
+# Architecture Styles & the Robust-vs-Lite Matrix
+
+Style is chosen **after** scenarios and tactics exist (Decision Spine step 3). A style is a vocabulary of components/connectors plus constraints; it earns its place by satisfying the scenario set at the lowest complexity that works.
+
+## Style Catalog — when each one wins
+
+| Style | Core idea | Choose when scenarios show… | Watch out |
+|---|---|---|---|
+| **Layered / N-tier** | Presentation / business / data separation, dependencies point down | Simple CRUD systems, small teams, uniform scaling | Layer skipping, "lasagna" of anemic layers |
+| **Hexagonal (Ports & Adapters)** | Domain core surrounded by ports (interfaces) and adapters (tech) | Modifiability scenarios: swap DB/API/provider without touching business rules | Overkill for pure pipelines/scripts |
+| **Clean Architecture** | Entities → Use Cases → Interface Adapters → Frameworks; Dependency Rule points inward, framework-independent domain | Long-lived products, testability scenarios (domain testable without infra), multiple delivery mechanisms | Ceremony on tiny services; don't create 4 layers for a webhook |
+| **Modular Monolith** | One deployable, hard module boundaries (enforced imports), per-module data ownership | Team ≤ ~8, uniform availability target, fast iteration + future split option | Boundary erosion — enforce with lint/build rules |
+| **Microservices** | Independently deployable services, own data, contract-based communication | Independent scaling of hot paths, >1 team per deployable cadence, divergent availability/regulatory isolation | Distributed monolith; needs observability + delivery maturity first |
+| **Event-Driven** | Producers/consumers via broker; choreography or orchestration | Async workflows, spiky load absorption, audit trails, fan-out | Eventual consistency is an ADR; idempotency + DLQs mandatory |
+| **Serverless** | Functions + managed services, scale-to-zero | Spiky/unpredictable load, cost scenarios favoring pay-per-use, small ops team | Cold starts vs latency measures; vendor coupling is an accepted ADR |
+| **CQRS / Event Sourcing** | Split write/read models; state as event log | Read/write asymmetry proven by measures; audit/replay requirements | The most-regretted premature escalation; demand hard evidence |
+
+Styles compose: a serverless system with a hexagonal core, or microservices where each service is internally clean, are normal outcomes. Name the composition in the TRD.
+
+## Robust-vs-Lite Decision Matrix (expanded)
+
+Score each axis from the scenario set; the tier is decided per axis, not globally — a lite structure with robust data is valid.
+
+| Axis | LITE default | Escalate to ROBUST when (scenario evidence) | ADR must state |
+|---|---|---|---|
+| Structure | Modular monolith (hexagonal/clean inside) | Hot path needs independent scaling; team topology exceeds one deploy cadence | Split boundaries + contract ownership |
+| Compute | Serverless (Lambda) or one managed runtime (ECS/App Runner) | Sustained high utilization (serverless cost crossover), long-running/stateful work, cold starts break latency measures | Cost crossover math, latency data |
+| Data | One primary DB + cache | Polyglot proven by access patterns; regulatory isolation; write/read asymmetry | Consistency model per store |
+| Async | Direct calls; one queue for the genuinely async | Multi-step sagas, streaming volumes, cross-service choreography | Failure/compensation model |
+| Delivery | One pipeline, trunk-based, IaC from day one | Many services × environments; progressive delivery needed by availability scenarios | Promotion + rollback strategy |
+| AI | Single agent, managed API | Multi-agent only when task decomposition is proven (see `agentic-ai.md`) | Token cost order-of-magnitude |
+
+Anti-rule: never escalate two axes "while we're at it." Each escalation cites its own scenario.
+
+## Reference Stack Mapping (AKILI default expertise: AWS + Node.js/TypeScript)
+
+Use the project's declared stack and `## Skill Map` first. When the project is greenfield and the user's ecosystem applies, these are the calibrated defaults — deviations (Go for CPU-bound hot paths, Python for ML/data) go through an ADR:
+
+| Concern | LITE | ROBUST |
+|---|---|---|
+| API/backend | Lambda + API Gateway (Node/TS), or NestJS on a single runtime | NestJS services on ECS/EKS; Go for measured hot paths; FastAPI for ML-adjacent services |
+| Frontend | Next.js / Astro (content) on managed hosting | Next.js/Angular with edge rendering, feature-flagged progressive delivery |
+| Relational data | Single MySQL (RDS) / managed Postgres | Aurora, read replicas, partitioning; Oracle when the org mandates it |
+| NoSQL | DynamoDB single-table for known access patterns | DynamoDB + streams; MongoDB for document-flexible domains |
+| Async | SQS (+ one DLQ) | EventBridge/SNS fan-out, Step Functions sagas, Kinesis streaming |
+| AI/RAG | Bedrock (or OpenAI/Anthropic API) + S3 Vectors | Bedrock multi-model routing, OpenSearch vector store, dedicated inference |
+| IaC | CDK/SAM, one stack per app | CDK multi-stack/multi-account, pipelines per service |
+
+## Clean/Hexagonal Layer Mapping for Node.js/TypeScript
+
+The Dependency Rule: source dependencies point inward only; the domain imports nothing from outer layers; data crossing boundaries is plain structures.
+
+```
+src/
+  domain/          # entities, value objects, domain services, ports (interfaces) — zero framework imports
+  application/     # use cases orchestrating domain; transaction boundaries; input/output DTOs
+  infrastructure/  # adapters: repositories (MySQL/Dynamo/Mongo), external APIs, message producers
+  interfaces/      # delivery: HTTP controllers/resolvers (NestJS/Fastify), CLI, queue consumers
+```
+
+- NestJS: modules per bounded context; providers implement domain ports; controllers stay thin (map transport ↔ use case DTOs).
+- Serverless: each handler is an `interfaces/` adapter invoking a use case — business logic never lives in the handler file.
+- Test consequence (testability tactic): domain + application test with in-memory port fakes, no infra needed.
+
+## Style → Scenario Traceability Block (TRD requirement)
+
+End the Architecture Overview with a compact table: `Scenario ID → Tactic → Style/axis decision it justified`. If a style decision has no scenario row, it is preference — delete it or find its scenario.

package/.claude/skills/software-architect/references/design-patterns.md

@@ -0,0 +1,70 @@
+# Design Patterns — Selection, Principles, and the Tactic→Pattern Bridge
+
+Patterns enter a design only at Decision Spine step 4: bound to a named problem, implementing a chosen tactic, with the simpler alternative stated. Catalog basis: the Refactoring.Guru catalog (Alexander Shvets) — 22 of the 23 GoF patterns (Interpreter omitted).
+
+## Design Principles (the review checklist above any pattern)
+
+1. **Encapsulate what varies** — isolate the changing part behind a boundary before reaching for a pattern name.
+2. **Program to an interface, not an implementation.**
+3. **Favor composition over inheritance.**
+4. **SOLID:** Single Responsibility · Open/Closed · Liskov Substitution · Interface Segregation · Dependency Inversion (the Dependency Rule of clean/hexagonal is DIP at architecture scale).
+
+If a principle solves it, stop there — a pattern nobody needs is complexity (MUDA).
+
+## Selection Table — problem → pattern
+
+### Creational (object creation)
+| You need to… | Pattern | Note |
+|---|---|---|
+| Decouple client from concrete classes it instantiates | **Factory Method** | First stop; evolves into the ones below |
+| Create families of related objects consistently | **Abstract Factory** | Often composed of factory methods |
+| Build complex objects step-by-step (many optional params) | **Builder** | Kills telescoping constructors |
+| Clone configured objects instead of rebuilding | **Prototype** | |
+| Exactly one instance, controlled access | **Singleton** | In DI ecosystems (NestJS), prefer container-scoped providers |
+
+### Structural (composition)
+| You need to… | Pattern | Note |
+|---|---|---|
+| Make an incompatible interface fit (legacy, 3rd-party SDK) | **Adapter** | The workhorse of hexagonal `infrastructure/` |
+| Vary abstraction and implementation independently (2 dimensions) | **Bridge** | Prevents class explosion (e.g. notification kind × channel) |
+| Part-whole trees treated uniformly | **Composite** | |
+| Add responsibilities dynamically without subclassing | **Decorator** | Middleware/interceptors are this |
+| One simple door to a complex subsystem | **Facade** | Use-case classes often act as facades |
+| Share heavy immutable state across many instances | **Flyweight** | Rare in business apps |
+| Control access: lazy, cache, guard, remote | **Proxy** | Repositories with caching layers |
+
+### Behavioral (interaction & responsibility)
+| You need to… | Pattern | Note |
+|---|---|---|
+| Pass a request through potential handlers | **Chain of Responsibility** | Validation/auth pipelines |
+| Requests as objects (queue, log, undo, retry) | **Command** | Natural fit for queue-driven work |
+| Traverse a collection without exposing structure | **Iterator** | Built into JS/TS; rarely hand-rolled |
+| Centralize chatty peer-to-peer communication | **Mediator** | Orchestrators, event buses in-process |
+| Snapshot/restore state without breaking encapsulation | **Memento** | |
+| Notify dependents on state change (pub/sub) | **Observer** | In-process events; at system scale → event-driven style |
+| Behavior changes with internal state (kill state conditionals) | **State** | Order/workflow lifecycles |
+| Interchangeable algorithms behind one interface | **Strategy** | Pricing rules, retry policies, LLM model routing |
+| Algorithm skeleton with overridable steps | **Template Method** | Prefer Strategy (composition) when possible |
+| Add operations across a class hierarchy without touching it | **Visitor** | Last resort; heavy coupling to hierarchy |
+
+## Tactic → Pattern Bridge (connects step 2 to step 4)
+
+| Tactic (from `nfr-scenarios.md`) | Patterns that implement it |
+|---|---|
+| Prevent ripple / intermediary | Facade, Bridge, Mediator, Proxy, Adapter |
+| Defer binding | Strategy, Abstract Factory, Dependency Injection (DIP), plugin registration |
+| Encapsulation / swap providers | Adapter + port interfaces (hexagonal), Bridge |
+| Retry / failover / degradation | Command (retryable units), Proxy (circuit breaker), Chain of Responsibility (fallbacks) |
+| Caching / multiple copies | Proxy (cache-aside), Flyweight |
+| Rate limiting / arbitration | Decorator or Proxy on the entry port; Command queues |
+| Audit / undo / replay | Command + Memento; at system scale → event sourcing (ADR!) |
+| Workflow state control | State, Template Method → Strategy |
+| Test doubles / seams | All port-based patterns (Adapter, Strategy) via DIP |
+
+## Justification Format (what lands in the document)
+
+For each pattern decision, one compact line in Design Decisions:
+
+`[Problem] → [Pattern] implementing [Tactic] for [Scenario ID] — simpler alternative rejected: [X, reason]`
+
+Evolution guidance: start with the simplest member of a family (Factory Method before Abstract Factory; Strategy before a full plugin system) and record the trigger that would justify upgrading. Patterns are design-level reuse — cheaper than framework lock-in, more durable than copied code.

package/.claude/skills/software-architect/references/nfr-scenarios.md

@@ -0,0 +1,75 @@
+# NFR Scenarios & Tactics
+
+Non-functional requirements are captured as **quality-attribute scenarios** (SEI six-part format) and satisfied by **tactics** — named design decisions that control the system's response to a stimulus. This file is the scenario template plus the tactics menu per attribute.
+
+## The Six-Part Scenario (the only valid NFR format)
+
+| Part | Meaning | Example (performance) |
+|---|---|---|
+| **Source** | Who/what generates the stimulus | 500 concurrent end users |
+| **Stimulus** | The condition arriving at the system | submit checkout requests |
+| **Environment** | System state when it arrives | normal operation, peak season |
+| **Artifact** | Component(s) affected | order API + payment integration |
+| **Response** | What the system does | process and confirm the order |
+| **Response measure** | The testable threshold | p95 latency ≤ 800 ms, error rate < 0.1% |
+
+Rules:
+
+- Write scenarios one-per-line in compact form: `[Source] → [Stimulus] on [Artifact] during [Environment] ⇒ [Response] measured by [Measure]`.
+- Every scenario must be **architecturally significant** (shapes structure, not just code) and **testable** (the measure feeds `/akili-test`).
+- Derive stimuli from PRD goals and real usage claims only. If the PRD lacks the number, ask or state the assumption explicitly.
+- 3–7 scenarios per attribute that matters; zero for attributes marked "not architecturally significant here" (that marking is itself required output).
+
+Example measures by attribute (calibrate to the project, don't copy blindly): availability — monthly downtime budget, RTO/RPO; performance — p95/p99 latency, throughput at N concurrent users; security — time to detect/revoke, blast radius of a leaked credential; modifiability — "add a payment provider touching ≤ 2 modules"; scalability — 10× load with linear cost, no redesign; cost — monthly ceiling per environment; observability — MTTD < X min for a failing dependency.
+
+## Tactics Menu per Attribute
+
+A tactic is chosen to satisfy a scenario, then implemented by styles/patterns (see `architecture-styles.md`, `design-patterns.md`). Cite the tactic by name in the TRD next to its scenario.
+
+### Availability
+- **Detect faults:** health checks/heartbeat, exception handling, timeouts.
+- **Recover:** retry with backoff, failover/replicas, checkpoints + transaction log, graceful degradation, circuit breaker.
+- **Prevent:** transactions (atomic rollback), bulkheads/isolation, removal from service for maintenance.
+
+### Performance
+- **Control resource demand:** increase computational efficiency, reduce overhead, manage event rate, bound queue sizes, bound execution times.
+- **Manage resources:** introduce concurrency, maintain multiple copies (caching, read replicas, CDN), increase available resources (scale up/out).
+- **Arbitrate resources:** scheduling/priority policies, rate limiting, backpressure.
+
+### Security
+Properties: confidentiality, integrity, non-repudiation, availability, auditability.
+- **Resist:** authentication (tokens, certs, MFA), authorization (per-role/least privilege), encrypt in transit + at rest, validate inputs, limit exposure (private networking, minimal surface).
+- **Detect:** intrusion/anomaly detection, request filtering, audit logging.
+- **Recover:** state restoration, credential rotation/revocation, traceable audit trail for attack identification.
+
+### Modifiability
+- **Localize changes:** semantic coherence (high cohesion / low coupling), anticipate expected changes, generalize modules.
+- **Prevent ripple:** encapsulation, intermediaries (facade, bridge, mediator, strategy, proxy, factory, repository), stable interfaces.
+- **Defer binding:** configuration files, feature flags, runtime registration/plugins, polymorphism, dependency injection.
+
+### Testability
+- Interface/implementation separation, dependency injection for substitutable test doubles, specialized test interfaces, internal state monitoring, deterministic seams (clock/random injected).
+
+### Usability (architectural slice only)
+- Runtime: feedback, cancel/undo support. Design-time: separate UI from application logic (the same tactic as modifiability's semantic coherence — MVC and descendants).
+
+### Scalability (cloud-era extension)
+- Statelessness (externalize session/state), horizontal scaling + load balancing, partitioning/sharding, async decoupling via queues, autoscaling policies, cache hierarchies, read/write splitting.
+
+### Observability (cloud-era extension)
+- Structured logging with correlation IDs, RED/USE metrics, distributed tracing, health/readiness endpoints, alerting on symptoms (SLOs) not causes, dashboards per audience.
+
+### Cost / FinOps (cloud-era extension)
+- Serverless/scale-to-zero for spiky loads, right-sizing + reserved capacity for steady loads, tiered storage lifecycle, cache to cut egress/compute, model routing (small model first) for LLM workloads, budget alarms as deploy artifacts.
+
+## Trade-off Table (always disclose)
+
+Tactics conflict; the TRD must say which side won and why (this feeds `judgment-day`):
+
+| Tension | Typical resolution note |
+|---|---|
+| Performance ↔ Modifiability | Layers/indirection add hops; keep them until a scenario measure fails, then flatten the measured path only |
+| Security ↔ Performance/Usability | Encrypt and authenticate by default; budget the latency in the performance measures |
+| Availability ↔ Cost | Replicas and multi-AZ cost money; the availability scenario's downtime budget justifies (or caps) the spend |
+| Scalability ↔ Consistency | Prefer strong consistency until a scenario demands otherwise; eventual consistency is an ADR, never an accident |
+| Cost ↔ everything | Every ROBUST escalation names its monthly cost order-of-magnitude |

package/.claude/skills/software-architect/references/views-documentation.md

@@ -0,0 +1,65 @@
+# Views & Documentation — C4, View Selection, ADRs, Interfaces
+
+Documenting an architecture = documenting the relevant **views**, then adding what applies across views (rationale, mapping, roadmap). Views are chosen by stakeholder need, never by habit. Basis: C4 (Simon Brown) as notation + SEI Views & Beyond as method.
+
+## C4 — the default notation
+
+| Level | Diagram | Shows | Use |
+|---|---|---|---|
+| 1 | **System Context** | The system as one box + users/personas + neighboring systems. People and systems, not tech | Always — first diagram of every TRD |
+| 2 | **Container** | Separately deployable/runnable units (web app, API, DB, queue, function) + tech choices + comm links | Always |
+| 3 | **Component** | Major building blocks inside ONE container + responsibilities | Only for complex containers |
+| 4 | Code (UML class) | Classes inside a component | Almost never; generate on demand |
+
+Rules: every element carries name + type tag + one-line description (`[Container: NestJS/Node]`); every relationship is a labeled directed arrow; **every diagram has a legend** — shared abstractions matter more than notation. Supplementary diagrams reuse the same elements: a **deployment view** (containers → AWS infrastructure) and, when async flows exist, a **runtime/sequence view** for the 1–3 most critical scenarios. Mermaid is the default renderer in AKILI docs.
+
+## Which views, for whom (selection method)
+
+1. List stakeholders; keep candidate views having at least one vested stakeholder; 2. combine/drop overview-only views; 3. prioritize — 80% done breadth-first beats one perfect view; **never defer rationale**.
+
+| Stakeholder | Needs (detail) |
+|---|---|
+| Developers / AKILI Implementer | Module structure + layer rules (d), their container's components (d), interfaces (d) |
+| Tech lead / future architect | Everything + candid rationale (d) |
+| Ops / infra | Deployment view (d), container view (s) |
+| Testers / AKILI Tester | C&C behavior + interfaces + scenario measures (d) |
+| PM / customer | Context (o), container (o), cost/tier decision (o) |
+
+Quality-attribute → view mapping: performance → runtime + deployment views; security → deployment + data-flow + trust boundaries; modifiability → module/dependency view; availability → deployment + failover behavior. If a scenario matters, some view must let a reader analyze it.
+
+## View documentation template (per view, compact)
+
+1. **Primary presentation** (the diagram, with legend)
+2. **Element catalog** — one line per element: responsibility + key properties
+3. **Context** — what's in/out of scope for this view
+4. **Variability** — variation points and binding times (config, flags, plugins)
+5. **Rationale** — why this shape; link scenario/ADR IDs
+
+Mark unused sections "n/a" — never silently omit. Avoid repetition: define an element once, cross-reference elsewhere.
+
+## ADR — Architecture Decision Record (compact 8-field AKILI profile)
+
+Full SEI template has 12 fields; AKILI uses 8 (drop bureaucracy, keep traceability):
+
+```markdown
+### ADR-NNN: <decision title>
+- **Status:** proposed | accepted | superseded by ADR-MMM
+- **Issue:** the forcing problem (link Scenario IDs)
+- **Decision:** what was chosen
+- **Alternatives:** options seriously considered
+- **Argument:** why this one — cost, TCO, time-to-market, measures
+- **Implications:** new constraints, renegotiated scope, revisit triggers
+- **Related:** ADRs / requirements / affected artifacts
+```
+
+Document a decision when it is hard to undo, took real evaluation effort, is confusing without context, or is unusual enough to be "fixed" by mistake. ROI test: capture now if that's cheaper than rediscovery later. For contested choices, a trade-study table (rows = concerns/scenarios, columns = alternatives, cells = ✓/✗/?) replaces prose.
+
+Keep an ADR index table at the top of Architecture Overview & Decisions: `ID | Title | Status | Scenarios`.
+
+## Interface / contract documentation (per exposed interface)
+
+1. Identity & version · 2. Resources/operations (syntax, semantics, errors) · 3. Data types · 4. Error model (shared) · 5. Variability · 6. Quality characteristics (SLO/SLA: latency, rate limits) · 7. Rationale · 8. Usage examples. In practice: OpenAPI/GraphQL schema covers 1–4; the TRD adds 5–8 — especially 6, where interface SLOs inherit from scenario measures.
+
+## Seven rules for sound documentation (package checklist)
+
+1. Write for the reader · 2. Avoid repetition · 3. Explain every notation (legends) · 4. Standard organization (templates above; mark gaps "TBD") · 5. Record rationale while fresh, including rejected options · 6. Version and release docs; avoid perpetual-draft drift · 7. Review with the real stakeholders (in AKILI: `judgment-day` is the structured review).

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.10.0] - 2026-07-22
+
+### Added
+
+- **New `caveman` skill** (by Julius Brussee, MIT — github.com/juliusbrussee/caveman; adapted for AKILI-SPECS): token-economy communication style (~65% output-token reduction in upstream benchmarks) scoped by an AKILI **Scope Contract** to *transient agent output only* — inter-agent messages in the `/akili-execute` triad and `/akili-test` Leader↔Tester communication at `full`, user-visible progress narration at `lite`. Explicitly OFF for persistent artifacts (PRD/TRD/specs/`execution.md`/`test-report.md`/PRs/Kaizen log — `cognitive-doc-design` territory), HITL approval gates, Pivot/`PRODUCT_BUG` escalations, and verbatim evidence (Reviewer FAIL reports, error strings, test output — the Structured Feedback rule wins). Boundary rule recorded in both skills: *"cognitive-doc-design owns artifacts; caveman owns transient agent output."* Wired into `/akili-execute` (Multi-Agent Triad) and `/akili-test` (Token discipline).
+
+- **New `software-architect` skill** (by Juan Carlos Cadavid — jcadavid.com, MIT; original AKILI authorship): senior-software-architect skill built around the **Decision Spine** — Scenario → Tactic → Tier & Style → Pattern → View & Record. Captures non-functional requirements as six-part, measurable quality-attribute scenarios (SEI format) with a mandatory security/performance/scalability/availability sweep; sizes the architecture through a **robust-vs-lite gate** (evidence-based escalation recorded as ADRs, infrastructure derives from the tier); selects architecture styles (hexagonal, clean, modular monolith, microservices, event-driven, serverless) and GoF design patterns only when bound to named problems; documents with C4 views (legend required) and compact 8-field ADRs. Progressive disclosure via `references/` (nfr-scenarios, architecture-styles, design-patterns, views-documentation, agentic-ai — the latter covering single/multi-agent patterns, RAG/vector decisions, and LLM-specific NFRs). Wired into the methodology: `/akili-constitution` Step 5 (required skill for the TRD; the TRD structure gains `Architecture Overview & Decisions` and `Quality Attribute Scenarios (Non-Functional Requirements)` sections) and Step 6 (infrastructure cites the tier decision), and `/akili-specify` Phase 2 for architecturally significant features. Inspired by SEI (Bass/Clements/Kazman; Views & Beyond), the C4 model (Simon Brown), Refactoring.Guru (Alexander Shvets), Clean/Hexagonal architecture, and Google Cloud agentic AI guides.
+## [2.9.0] - 2026-07-20
+
+### Added
+
+- **Model Routing 2.0 — enforced for subagents, guided for the main loop:**
+  - **Tool-native agent wrappers (`/akili-constitution` Step 8E):** with user approval, the constitution now binds the `.agents/` personas to the Model Routing registry via native agent definitions — `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code (alias-based `model:`) and agent config in OpenCode (provider slugs). `/akili-execute` and `/akili-test` prefer these named agents, so the multi-agent fan-out (where most tokens are spent) routes automatically and **author ≠ auditor becomes structural** — the Reviewer wrapper pins a different model than the Implementer wrapper. Wrappers are thin references to `.agents/`; personas remain the single source of truth. Antigravity stays guidance-only (no per-agent model binding).
+  - **Model checkpoints in every command:** all 10 commands (`propose`, `specify`, `execute`, `test`, `validate`, `archive`, `audit`, `quick`, `seo`, `constitution`) perform a one-line, never-blocking check during setup — if the phase's tier maps to a different model than the current session, the user is told (e.g. "This phase is T1 — the registry recommends `/model opus`") and offered the switch at the first approval pause.
+  - **Model Registry Drift check in `/akili-audit`:** new drift category and Conformance Matrix row — registry entries naming models the tool no longer offers, dated pins where a floating alias exists, missing tiers/author ≠ auditor notes versus the packaged default, and Step 8E wrappers contradicting the registry. Report-only.
+
+### Changed
+
+- **Alias-first model registry (survives model churn):** `docs/model-routing.md` and the Step 8C scaffold now mandate floating aliases (`opus`/`sonnet`/`haiku` in Claude Code — they always resolve to the latest generation, so new model families require zero registry edits); dated model pins require a recorded reason. The default registry was rewritten alias-first with an `Updated:` stamp; OpenCode slugs (no alias mechanism) keep the Fallback column and are covered by the drift check. Safe Update mode now also flags stale registry entries against the packaged default without touching user pins.
 ## [2.8.0] - 2026-07-20
 
 ### Added

package/docs/commands/akili-constitution.md

@@ -63,7 +63,11 @@ The `.agents/` directory is tool-agnostic: pure Markdown + YAML frontmatter, res
 
 ## Model Routing Scaffolding
 
-Step 7C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode). It is guidance only — no `model:` frontmatter is added and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved and only gaps are filled. See [Model Routing](../model-routing.md) for the tiers and the default registry.
+Step 8C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode), following the **alias-first rule** (floating aliases like `opus`/`sonnet`/`haiku` wherever they exist, so the registry survives model generations without edits). No `model:` frontmatter is added to commands and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved, gaps are filled, and stale entries are flagged against the packaged default without touching user pins. See [Model Routing](../model-routing.md) for the tiers and the default registry.
+
+## Model Binding Scaffolding (Tool-Native Agent Wrappers)
+
+Step 8E (with the user's approval) binds the `.agents/` personas to the registry's models via **tool-native agent definitions**: `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code (alias-based `model:` frontmatter) and the equivalent agent config in OpenCode (provider slugs). The wrappers are thin — they reference the `.agents/` persona instead of duplicating it — and make model routing **enforced** for the `/akili-execute` and `/akili-test` fan-out, including a structural author ≠ auditor guarantee (the Reviewer wrapper pins a different model than the Implementer wrapper). Antigravity has no per-agent model binding and stays guidance-only. In Active-AKILI-SPECS mode existing wrappers are never overwritten.
 
 ## Skill Map Scaffolding
 

package/docs/flow.md

@@ -303,11 +303,25 @@ T4 Context-Ingest, T5 Fast-Cheap, T6 Multimodal** — map to the phases:
 | `/akili-audit` | T4 + T3 |
 | `/akili-archive` | T5 |
 
-A single editable registry binds each tier to a concrete model **per tool** (Claude Code and
-OpenCode). `/akili-constitution` (Step 7C) scaffolds a `## Model Routing` copy of that registry into
-the project's `AGENTS.md` / `CLAUDE.md`. It is **guidance only** — no `model:` frontmatter, no
-installer changes — and it enforces **author ≠ auditor** (Reviewer model ≠ Implementer model). See
-[model-routing.md](model-routing.md) for the tiers, principles, and the default registry.
+A single editable registry binds each tier to a model **per tool** (Claude Code and OpenCode),
+using **floating aliases** (`opus`/`sonnet`/`haiku`) wherever they exist so the registry survives
+model generations without edits. `/akili-constitution` (Step 8C) scaffolds a `## Model Routing`
+copy into the project's `AGENTS.md` / `CLAUDE.md`.
+
+Routing operates at two levels:
+
+* **Enforced (subagents):** `/akili-constitution` Step 8E can generate tool-native agent wrappers
+  (`.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code, agent config in
+  OpenCode) that pin each persona to its tier's model. `/akili-execute` and `/akili-test` prefer
+  those named agents — so **author ≠ auditor** (Reviewer model ≠ Implementer model) holds by
+  configuration on the fan-out where most tokens are spent.
+* **Guided (main loop):** every command emits a one-line, never-blocking **model checkpoint** in
+  its setup step when the phase's tier maps to a different model than the current session.
+
+No `model:` frontmatter on commands and no installer changes. `/akili-audit` reports **Model
+Registry Drift** (stale model names, dated pins where an alias exists, wrappers contradicting the
+registry). See [model-routing.md](model-routing.md) for the tiers, principles, and the default
+registry.
 
 ### 8. The Kaizen Loop
 

package/docs/model-routing.md

@@ -4,8 +4,17 @@ AKILI is model-agnostic: no command, skill, or persona hardcodes a model. This d
 **human-facing guidance** for choosing which model runs which AKILI-SPECS phase, so each phase runs on a
 model matched to its dominant computational demand rather than one model doing everything.
 
-It is **guidance-first**: you switch models yourself per tool (Claude Code `/model`, OpenCode
-model selector). Nothing here is injected into command frontmatter or the installer — see
+Routing operates at two levels:
+
+- **Enforced (subagents):** `/akili-constitution` Step 8E can bind the Implementer / Reviewer /
+  Tester / Leader personas to models via **tool-native agent definitions** (see
+  [Enforced routing](#enforced-routing-tool-native-agent-bindings)). This is where most tokens are
+  spent and where author ≠ auditor becomes structural instead of aspirational.
+- **Guided (main loop):** the session model can only be switched by you (Claude Code `/model`,
+  OpenCode model selector). Commands emit a one-line **model checkpoint** when the phase's tier
+  points to a different model than the current session, so the switch happens at the right moment.
+
+Nothing here is injected into command frontmatter or the installer — see
 [Cross-Tool Safety](#cross-tool-safety).
 
 ## Philosophy: criteria first, model second
@@ -75,25 +84,35 @@ tier (to the deeper reasoner) to preserve independence.
 ## Model registry
 
 This is the single editable source of truth. Phases reference **tiers**; only this table names
-concrete models. When models change, edit only this table.
+models. When models change, edit only this table. *Registry updated: 2026-07.*
 
-| Tier | Claude Code (PRO) | OpenCode Go | Fallback |
+**Alias-first rule: never pin a dated model name where a floating alias exists.** Claude Code's
+`opus` / `sonnet` / `haiku` aliases always resolve to the latest version of each family — when
+Anthropic ships a new generation, an alias-based registry needs **zero edits**. Pin a dated ID only
+when you deliberately need to freeze a version, and record why next to the pin. OpenCode slugs are
+concrete (no alias mechanism), which is why they carry the Fallback column and the drift check
+below.
+
+| Tier | Claude Code | OpenCode Go | Fallback |
 |---|---|---|---|
-| **T1 Architect** | Opus 4.8 | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / Sonnet 4.6 |
-| **T2 Coder** | Sonnet 4.6 | `opencode-go/glm-5.1` | Haiku 4.5 / `opencode-go/qwen3.7-max` |
-| **T3 Auditor** | Opus 4.8 *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | Sonnet 4.6 / `opencode-go/kimi-k2.6` |
-| **T4 Context-Ingest** | Sonnet 4.6 (1M context) | `opencode-go/deepseek-v4-flash` | Opus 4.8 / `opencode-go/deepseek-v4-pro` |
-| **T5 Fast-Cheap** | Haiku 4.5 | `opencode-go/deepseek-v4-flash` | Sonnet 4.6 / `opencode-go/mimo-v2.5` |
-| **T6 Multimodal** | Sonnet 4.6 (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | Opus 4.8 |
+| **T1 Architect** | `opus` *(alias — always latest)* | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / `sonnet` |
+| **T2 Coder** | `sonnet` | `opencode-go/glm-5.1` | `haiku` / `opencode-go/qwen3.7-max` |
+| **T3 Auditor** | `opus` *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | `sonnet` / `opencode-go/kimi-k2.6` |
+| **T4 Context-Ingest** | `sonnet` (long context) | `opencode-go/deepseek-v4-flash` | `opus` / `opencode-go/deepseek-v4-pro` |
+| **T5 Fast-Cheap** | `haiku` | `opencode-go/deepseek-v4-flash` | `sonnet` / `opencode-go/mimo-v2.5` |
+| **T6 Multimodal** | `sonnet` (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | `opus` |
 
 ### Why these models
 
-**Claude Code (PRO).** Opus 4.8 carries the tightest PRO rate limits, so it is **reserved for
-T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that most reward deep
-reasoning. **Sonnet 4.6 is the workhorse** for coding (T2), large-context ingestion via its 1M
-window (T4), and vision (T6). **Haiku 4.5** handles fast/cheap formatting, orchestration, and
-summarization (T5). This concentrates scarce Opus budget on architecture and audit and avoids
-exhausting it during execution-heavy work.
+**Claude Code.** The top-family alias (`opus`) carries the tightest plan rate limits, so it is
+**reserved for T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that
+most reward deep reasoning. **`sonnet` is the workhorse** for coding (T2), large-context ingestion
+(T4), and vision (T6). **`haiku`** handles fast/cheap formatting, orchestration, and summarization
+(T5). This concentrates the scarce top-tier budget on architecture and audit and avoids exhausting
+it during execution-heavy work. Because these are aliases, the mapping survives model generations
+unchanged (e.g. when the top family moves from one generation to the next, `opus` follows it).
+Users on plans that expose additional tiers (e.g. a Mythos-class model above Opus) can pin it for
+T1/T3 in their project registry.
 
 **OpenCode Go.** The two strongest open models anchor the two highest-leverage tiers:
 
@@ -115,20 +134,69 @@ exhausting it during execution-heavy work.
 All OpenCode Go slugs are taken from the [OpenCode Go model list](https://opencode.ai/docs/go).
 Confirm them against your own OpenCode configuration and adjust if your roster differs.
 
+## Enforced routing (tool-native agent bindings)
+
+The `/akili-execute` and `/akili-test` fan-out (Implementer, Reviewer, Testers) is where most
+tokens are spent — and a generic subagent **inherits the session model**, which silently breaks
+author ≠ auditor when the whole session runs on one model. Both tools support a `model` field on
+**agent definitions** (never on commands), so `/akili-constitution` Step 8E binds the personas
+there:
+
+| Tool | Native agent location | Model value |
+|---|---|---|
+| Claude Code | `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` (project-level) | Alias from the registry (`model: sonnet`, `model: opus`, `model: haiku`) |
+| OpenCode | Project agent config (`.opencode/agent/*.md` or the `agent` block of `opencode.json`, per your OpenCode version) | Provider slug from the registry (`model: opencode-go/glm-5.1`) |
+| Antigravity | Not supported — `invoke_subagent` has no per-agent model binding | Guidance-only fallback |
+
+Each wrapper is thin: frontmatter (`name`, `description`, `model`) plus a body that instructs the
+agent to read and fully adopt the corresponding `.agents/<role>.md` persona. The persona files in
+`.agents/` remain the tool-agnostic source of truth; the wrappers only add the model binding.
+`/akili-execute` and `/akili-test` prefer these named agents when they exist and fall back to
+generic subagents seeded with the persona content when they don't.
+
+**author ≠ auditor becomes structural:** `akili-reviewer` is pinned to a different model than
+`akili-implementer` in the wrapper files themselves — no human discipline required.
+
+## Model checkpoints (main loop)
+
+The session model cannot be switched programmatically, but the agent knows which model it is
+running on. Every AKILI command performs a one-line **model checkpoint** during setup: read the
+project's `## Model Routing` registry, compare the phase's tier to the current session model, and
+if they differ, tell the user in one line (e.g. *"This phase is T1 — the registry recommends
+`/model opus`; you are on haiku"*) and offer the switch in the phase's first HITL pause. The user
+can always continue on the current model; the checkpoint never blocks.
+
+## Surviving model churn
+
+Models change constantly; the design absorbs that at three layers:
+
+1. **Tiers are the stable layer.** Phases map to T1–T6 and never change when models do.
+2. **Aliases are the default.** The Claude column uses floating aliases that track the latest
+   generation automatically (see the alias-first rule above).
+3. **Drift is detected, not discovered.** `/akili-audit` includes a **Model Registry Drift** check
+   (registry entries naming models the tool no longer offers, or a project registry older than the
+   packaged default), and `/akili-constitution` in Safe Update mode flags stale entries against the
+   packaged default without overwriting user pins. Each AKILI release refreshes this document's
+   default registry.
+
 ## How to apply per tool
 
-- **Claude Code (PRO):** switch with `/model` before running a phase — e.g. `/model opus` for
+- **Claude Code:** switch with `/model` before running a phase — e.g. `/model opus` for
   `/akili-propose` and `/akili-validate`, `/model sonnet` for `/akili-execute` and `/akili-test`,
-  `/model haiku` for the tasks split and `/akili-archive`. For the `/akili-execute` triad, run the
-  Implementer on Sonnet and the Reviewer on Opus so author ≠ auditor holds.
-- **OpenCode:** select the `opencode-go/...` model for each phase per the registry. Keep the
-  Reviewer/validator on a different model (`deepseek-v4-pro`) than the Implementer (`glm-5.1`).
+  `/model haiku` for the tasks split and `/akili-archive` — or simply respond to each command's
+  model checkpoint. With Step 8E bindings in place, the execute/test triad routes itself
+  (Implementer on `sonnet`, Reviewer on `opus`).
+- **OpenCode:** select the `opencode-go/...` model for each phase per the registry, or use the
+  Step 8E agent bindings. Keep the Reviewer/validator on a different model (`deepseek-v4-pro`)
+  than the Implementer (`glm-5.1`).
 
 ## Cross-tool safety
 
-- **No `model:` frontmatter.** Command prompts stay `description:`-only. A single frontmatter value
-  cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`; OpenCode expects
-  `provider/model`), so model choice stays out of the prompts.
+- **No `model:` frontmatter on commands.** Command prompts stay `description:`-only. A single
+  frontmatter value cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`;
+  OpenCode expects `provider/model`), so model choice stays out of the prompts. Model bindings live
+  exclusively in **agent definitions**, which are per-tool, per-project files generated with the
+  user's approval in Step 8E.
 - **No installer changes.** Nothing here is force-injected. `/akili-constitution` scaffolds a project
   copy of this registry into `AGENTS.md` / `CLAUDE.md` as plain Markdown — identical handling across
   Claude Code, OpenCode, and Google Antigravity.

package/docs/skills/README.md

@@ -20,6 +20,7 @@ The skill set is **curated, not accumulated**: every skill declares its original
 | [`api-design-principles`](api-design-principles.md) | stack | Seth Hobson (MIT) | REST and GraphQL API design and review | Skill Map; constitution/specify stack lists |
 | [`aws-serverless`](aws-serverless.md) | stack | vibeship (Apache-2.0) | Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK | Skill Map; constitution/specify stack lists |
 | [`brainstorming`](brainstorming.md) | core | Jesse Vincent — obra (MIT) | Clarifying ideas, scope, options, and trade-offs before implementation | `/akili-constitution` Step 0, `/akili-propose`, `/akili-specify` phases 1–3 |
+| [`caveman`](caveman.md) | core | Julius Brussee (MIT) | Token-economy compression of transient agent output (inter-agent messages `full`, progress lines `lite`) — never documents, HITL gates, or verbatim evidence | `/akili-execute` triad communication; `/akili-test` Leader↔Tester communication |
 | [`cognitive-doc-design`](cognitive-doc-design.md) | core | gentleman-programming (Apache-2.0) | Human-facing docs that reduce cognitive load (lead with the answer, progressive disclosure, tables over prose) | `/akili-constitution`, `/akili-specify`, `/akili-execute` (PR docs), `/akili-archive` |
 | [`error-handling-patterns`](error-handling-patterns.md) | stack | Seth Hobson (MIT) | Exceptions, Result patterns, graceful degradation, reliability | Skill Map; constitution/specify stack lists |
 | [`frontend-design`](frontend-design.md) | conditional | Anthropic (Apache-2.0) | Distinctive frontend UI and UX implementation (fallback when `ui-ux-pro-max` is unavailable) | UI steps of `/akili-constitution`, `/akili-specify`, `/akili-test`, `/akili-validate`, `/akili-seo` |
@@ -31,6 +32,7 @@ The skill set is **curated, not accumulated**: every skill declares its original
 | [`react-doctor`](react-doctor.md) | stack | Million.dev | React diagnostics after changes | Skill Map; `/akili-test`, `/akili-validate`, `/akili-execute` React work |
 | [`seo-audit`](seo-audit.md) | core | Corey Haines (MIT) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo` audit phase (required) |
 | [`shadcn-ui`](shadcn-ui.md) | stack | community (origin unverified) | shadcn/ui components, forms, themes, Tailwind integration | Skill Map; constitution/specify stack lists; persona examples |
+| [`software-architect`](software-architect.md) | core | Juan Carlos Cadavid — jcadavid.com (MIT) | Senior-architect Decision Spine: NFRs as measurable quality-attribute scenarios, tactics, robust-vs-lite tier sizing, architecture styles (hexagonal/clean/microservices), GoF pattern selection, C4 views + ADRs, agentic AI patterns | `/akili-constitution` Step 5 (required) and Step 6 tier handoff; `/akili-specify` Phase 2 for architecturally significant features |
 | [`stitch-design`](stitch-design.md) | conditional | Google — google-labs-code | Stitch prompt enhancement and design generation workflows (fallback UI chain with `frontend-design`) | UI steps of `/akili-constitution`, `/akili-propose`, `/akili-specify` |
 | [`systematic-debugging`](systematic-debugging.md) | core | Jesse Vincent — obra (MIT) | Root-cause investigation for bugs, test failures, unexpected behavior | `/akili-propose` Bug Track, `/akili-specify` Bug Mode, `/akili-test`, `/akili-validate`, `/akili-seo` |
 | [`tailwind-design-system`](tailwind-design-system.md) | stack | Seth Hobson (MIT) | Tailwind CSS v4 tokens, component systems, responsive patterns | Skill Map; constitution/specify stack lists |

package/docs/skills/caveman.md

@@ -0,0 +1,38 @@
+# `caveman`
+
+**Author:** Julius Brussee — [github.com/juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) (MIT)
+**Adapted for AKILI-SPECS by:** Juan Carlos Cadavid — [jcadavid.com](https://jcadavid.com)
+
+## Purpose
+
+Ultra-compressed communication style (~65% fewer output tokens in upstream benchmarks): drop filler, keep substance, fragments OK, code and errors byte-for-byte exact. In AKILI it is the preventive tactic against output-token **MUDA** — scoped strictly to *transient* agent output, the chatter nobody rereads.
+
+## The Scope Contract (the AKILI adaptation)
+
+> `cognitive-doc-design` owns artifacts; `caveman` owns transient agent output.
+
+| Output | Caveman |
+|---|---|
+| Inter-agent messages (Leader ↔ Implementer/Reviewer/Tester) | `full` |
+| User-visible progress narration mid-run | `lite` |
+| Persistent artifacts (PRD, TRD, specs, `execution.md`, `test-report.md`, PRs, Kaizen log) | off |
+| HITL approval gates, Pivot blockers, `PRODUCT_BUG` escalations | off |
+| Verbatim evidence: error strings, Reviewer FAIL reports, test output, code | never touched |
+
+Upstream Auto-Clarity is preserved and extended: security warnings, irreversible-action confirmations, and every HITL pause drop compression automatically. When in doubt whether output is transient or persistent, treat it as persistent (off).
+
+## Use When
+
+- `/akili-execute` — automatic: inter-agent briefs/reports/feedback relays at `full`, progress lines at `lite`; the Structured Feedback rule wins (Reviewer reports pass unchanged).
+- `/akili-test` — automatic: Leader→Tester slices and Tester structured reports at `full`.
+- The user asks for token efficiency ("less tokens", "be brief", "caveman mode") in any context — respecting the Scope Contract.
+
+## Best Paired Commands
+
+- `/akili-execute`, `/akili-test` — where the multi-agent fan-out burns most output tokens.
+- `kaizen` — compressed inter-agent chatter is measurable MUDA reduction; retrospectives may cite the savings.
+
+## Source
+
+- `../../.claude/skills/caveman/SKILL.md`
+- Upstream: https://github.com/juliusbrussee/caveman

package/docs/skills/governance.md

@@ -18,7 +18,7 @@ Every skill declares `metadata.binding` in its `SKILL.md` frontmatter. The bindi
 
 | Binding | Skills |
 |---|---|
-| `core` | `kaizen` (archive), `judgment-day` (specify), `cognitive-doc-design` (all human-facing docs), `brainstorming` (constitution, propose), `product-manager-toolkit` (constitution), `systematic-debugging` (bug flows), `seo-audit` (seo) |
+| `core` | `kaizen` (archive), `judgment-day` (specify), `cognitive-doc-design` (all human-facing docs), `brainstorming` (constitution, propose), `product-manager-toolkit` (constitution), `software-architect` (constitution TRD/infra, specify design), `caveman` (execute/test transient inter-agent output), `systematic-debugging` (bug flows), `seo-audit` (seo) |
 | `conditional` | `ui-ux-pro-max`, `frontend-design`, `stitch-design` (UI work), `gsap-animation` (animation work) |
 | `stack` | `angular-developer`, `nestjs-expert`, `shadcn-ui`, `tailwind-design-system`, `react-doctor`, `vercel-react-best-practices`, `aws-serverless`, `api-design-principles`, `error-handling-patterns` |
 
@@ -49,6 +49,8 @@ metadata:
 
 Attribution is non-negotiable: MIT and Apache-2.0 licenses require preserving the original copyright and license notices. `adapted-by` records curation and AKILI adaptation — it never replaces the original `author`.
 
+**Original-authorship variant:** skills authored originally for AKILI-SPECS (e.g. `kaizen`, `software-architect`) carry `author: Juan Carlos Cadavid — jcadavid.com` and may declare `inspired-by:` (a list of the works the method synthesizes) instead of `source`/`adapted-by`/`adapted-for` — there is no upstream to adapt from, but intellectual influences are still credited.
+
 ## Adaptation Levels
 
 | Level | Who gets it | What it is |