akili-specs 2.9.0 → 2.10.1

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

@@ -212,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`
@@ -226,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
 
 ---
 
@@ -243,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)

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

@@ -57,6 +57,8 @@ If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not
 
 The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
 
+**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

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

@@ -179,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

@@ -57,6 +57,7 @@ If `.agents/tester.md` is missing, run `/akili-constitution` first to scaffold i
 
 - 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):**

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.

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,18 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.10.1] - 2026-07-23
+
+### Changed
+
+- **Installer auto-detects installed targets (`bin/akili.js`):** when `--tool` is omitted, `install`, `update`, and `doctor` now scan disk for already-installed targets (`~/.claude`, `~/.config/opencode`, `~/.gemini`) and act on **all** of them instead of silently defaulting to `claude`. A bare `akili update` therefore refreshes every installed tool — fixing the case where new commands (e.g. `akili-quick`, `akili-resume`) landed in Claude Code but never reached OpenCode. An explicit `--tool <name>` still wins; a first-time run with nothing installed still defaults to `claude`. Auto-detected runs print which targets were found, and the update/verify summaries report the resolved tool set and a matching `akili doctor --tool …` hint.
+## [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

package/bin/akili.js

@@ -96,7 +96,9 @@ Commands:
   help      Show this help
 
 Options:
-  --tool <name>        Install target: claude, opencode, antigravity, both, or all. Default: claude
+  --tool <name>        Install target: claude, opencode, antigravity, both, or all.
+                       When omitted, install/update/doctor auto-detect already-installed
+                       targets; if none are found they default to claude.
   --target <path>      Target config directory for selected single tool
   --claude-target      Claude config directory. Default: ~/.claude
   --opencode-target    OpenCode config directory. Default: ~/.config/opencode
@@ -178,9 +180,17 @@ function getArgs() {
     const baseOpencode = values.local ? path.join(process.cwd(), ".config", "opencode") : defaultPaths.opencode;
     const baseAntigravity = values.local ? path.join(process.cwd(), ".gemini") : defaultPaths.antigravity;
 
+    // Whether the user explicitly passed --tool. When they did not, install/
+    // update/doctor auto-detect already-installed targets instead of assuming
+    // the "claude" default (see resolveTools).
+    const toolExplicit =
+      process.argv.includes("--tool") ||
+      process.argv.some((a) => a.startsWith("--tool="));
+
     const args = {
       command,
       tool: values.tool,
+      toolExplicit,
       force: values.force,
       dryRun: values["dry-run"],
       commandsOnly: values["commands-only"],
@@ -230,6 +240,57 @@ function selectedTools(args) {
   return [args.tool];
 }
 
+const ALL_TOOLS = ["claude", "opencode", "antigravity"];
+
+// A tool counts as installed when any of its target directories exists and is
+// non-empty. Checking commands / skills / resources covers --commands-only and
+// --skills-only installs too, not just full ones.
+function isToolInstalled(tool, args) {
+  const { paths } = getToolRegistryInfo(tool, args);
+  const dirs = [...paths.commands, paths.skills, paths.resources];
+  return dirs.some((dir) => {
+    try {
+      return fs.existsSync(dir) && fs.readdirSync(dir).length > 0;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function detectInstalledTools(args) {
+  return ALL_TOOLS.filter((tool) => isToolInstalled(tool, args));
+}
+
+// Resolve which tools an install/update/doctor run should act on. An explicit
+// --tool always wins. Otherwise we auto-detect targets already on disk so a bare
+// `akili update` refreshes every installed tool (e.g. claude AND opencode)
+// instead of silently defaulting to claude only. A first-time run with nothing
+// installed falls back to the default (claude). The resolved list and any
+// auto-detection note are stashed on args for the summary output.
+function resolveTools(args) {
+  if (args.toolExplicit) {
+    args.resolvedTools = selectedTools(args);
+    return args.resolvedTools;
+  }
+  const detected = detectInstalledTools(args);
+  const isJustDefault = detected.length === 1 && detected[0] === args.tool;
+  if (detected.length > 0 && !isJustDefault) {
+    args.autoDetected = detected;
+    args.resolvedTools = detected;
+    return detected;
+  }
+  args.resolvedTools = selectedTools(args);
+  return args.resolvedTools;
+}
+
+// Map a resolved tool list back to a --tool flag value for verify hints.
+function toolFlagFor(tools) {
+  if (tools.length === 1) return tools[0];
+  const set = new Set(tools);
+  if (set.size === 2 && set.has("claude") && set.has("opencode")) return "both";
+  return "all";
+}
+
 function shouldInclude(type, args) {
   if (args.commandsOnly) return type === "commands";
   if (args.skillsOnly) return type === "skills";
@@ -580,8 +641,9 @@ function runUpdate(args) {
   } else {
     console.log(`  Package: updated from v${versionBefore} (${installType} install; new version could not be read)`);
   }
-  console.log(`  Files: reinstalled with --force for ${selectedTools(args).join(", ")} (see Install Summary above)`);
-  console.log(`  Verify: ${colors.cyan}akili doctor --tool ${args.tool}${colors.reset}`);
+  const updatedTools = args.resolvedTools || selectedTools(args);
+  console.log(`  Files: reinstalled with --force for ${updatedTools.join(", ")}${args.autoDetected ? " (auto-detected)" : ""} (see Install Summary above)`);
+  console.log(`  Verify: ${colors.cyan}akili doctor --tool ${toolFlagFor(updatedTools)}${colors.reset}`);
 }
 
 function summaryCounts(result) {
@@ -589,7 +651,15 @@ function summaryCounts(result) {
 }
 
 function runInstall(args) {
-  const tools = selectedTools(args);
+  const tools = resolveTools(args);
+  if (args.autoDetected) {
+    console.log(
+      `\n${colors.cyan}Auto-detected installed target(s): ${args.autoDetected.join(", ")}${colors.reset}`
+    );
+    console.log(
+      `  Refreshing all detected targets. Pass ${colors.yellow}--tool <name>${colors.reset} to override.`
+    );
+  }
   const results = [];
 
   for (const tool of tools) {
@@ -626,7 +696,7 @@ function runInstall(args) {
   if (args.dryRun) {
     console.log(`  - Re-run without ${colors.yellow}--dry-run${colors.reset} to apply the changes above.`);
   } else {
-    console.log(`  - Verify the installation with ${colors.cyan}akili doctor --tool ${args.tool}${colors.reset}.`);
+    console.log(`  - Verify the installation with ${colors.cyan}akili doctor --tool ${toolFlagFor(tools)}${colors.reset}.`);
   }
 }
 
@@ -755,7 +825,16 @@ function doctorTool(tool, args) {
 function runDoctor(args) {
   const results = [];
 
-  for (const tool of selectedTools(args)) {
+  const tools = resolveTools(args);
+  if (args.autoDetected) {
+    console.log(
+      `\n${colors.cyan}Auto-detected installed target(s): ${args.autoDetected.join(", ")}${colors.reset}`
+    );
+    console.log(
+      `  Checking all detected targets. Pass ${colors.yellow}--tool <name>${colors.reset} to override.`
+    );
+  }
+  for (const tool of tools) {
     results.push({ tool, ...doctorTool(tool, args) });
   }
 
@@ -875,6 +954,7 @@ async function runInteractiveInit() {
   const args = {
     command: "install",
     tool: tool,
+    toolExplicit: true,
     force: false,
     dryRun: false,
     commandsOnly: false,

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 |

package/docs/skills/software-architect.md

@@ -0,0 +1,32 @@
+# `software-architect`
+
+**Author:** Juan Carlos Cadavid — [jcadavid.com](https://jcadavid.com)
+
+## Purpose
+
+Makes the agent operate as a **senior software architect** during TRD and design work. Its differentiator is the **Decision Spine** — Scenario → Tactic → Tier & Style → Pattern → View & Record: non-functional requirements are captured as six-part, measurable quality-attribute scenarios (SEI format); tactics answer each scenario; a **robust-vs-lite gate** sizes the architecture (and therefore the infrastructure) with evidence; design patterns enter only bound to named problems; everything lands as C4 views and compact ADRs. Inspired by SEI's *Software Architecture in Practice* and *Documenting Software Architectures*, the C4 model (Simon Brown), the Refactoring.Guru pattern catalog, Clean/Hexagonal architecture, and Google Cloud's agentic AI guides.
+
+## Use When
+
+- `/akili-constitution` reaches **Step 5 (TRD)** — automatic, required; Step 6 (Infrastructure) derives its shape from the tier decision.
+- `/akili-specify` Phase 2 designs an architecturally significant feature (new module/service, integration, data-flow, or NFR impact).
+- The user asks for architecture review, NFR identification, stack sizing, or design-pattern guidance.
+
+## Core Rules
+
+- **No NFR without a measure** — every scenario ends in a testable response measure; "fast/secure/scalable" without numbers is banned output.
+- **Minimum NFR sweep** — security, performance, scalability, availability always evaluated explicitly; "not architecturally significant" is valid, silence is not.
+- **Start lite, escalate with evidence** — robust choices (microservices, polyglot data, multi-agent AI) require a scenario whose measure the lite option cannot meet, recorded as an ADR.
+- **No pattern without a named problem** — each pattern cites the tactic it implements and the simpler alternative it beat.
+- **Every diagram has a legend**; C4 Context + Container are the default view set.
+- **Token frugality** — progressive disclosure via `references/` (NFR scenarios & tactics, architecture styles, design patterns, views & ADRs, agentic AI); conceptual designs only, no implementation code in documents.
+
+## Best Paired Commands
+
+- `/akili-constitution` — runs the full spine in Step 5; hands the tier decision to Step 6.
+- `/akili-specify` — feature-scale spine in Phase 2 `design.md`; its scenario→tactic→pattern traceability is what `judgment-day` audits.
+- `/akili-test` — scenario response measures become non-functional test candidates.
+
+## Source
+
+- `../../.claude/skills/software-architect/SKILL.md`

package/package.json

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