akili-specs 2.13.0 → 2.13.1

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

@@ -247,7 +247,7 @@ Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 
 ### Step 6: Create or Enhance the Infrastructure Document
 
-Create or enhance `docs/infrastructure.md` as the deployment and hosting blueprint.
+Create or enhance `docs/infrastructure.md` as the environments blueprint — from the developer's laptop to PROD.
 
 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.
 
@@ -258,9 +258,30 @@ The infrastructure shape derives from the TRD's robust-vs-lite tier decision (St
 3. Deployment Strategy (e.g., CI/CD, Terraform, CDK)
 4. Network & Security Architecture
 5. Infrastructure Rules & Constraints
+6. Local Environment (the contract below)
 
 If this information is missing during the initial setup or discovery phase, explicitly ask the user for the intended infrastructure specifications before drafting this document.
 
+#### Step 6B: The Local Environment Contract
+
+Scaffold a `## Local Environment` section that captures how to start the project's local stack (database, backend, frontend). The methodology defines a **contract, not a tool** — Docker Compose is the recommended primary route, but the contract must always document a fallback for users without Docker:
+
+| Element | What to record |
+|---------|----------------|
+| Primary route (recommended) | e.g. `docker compose up -d` |
+| Fallback route (no Docker) | e.g. `npm run dev` per service + a local or cloud dev database |
+| Pre-check | e.g. `docker info` — on failure (daemon off, not installed), surface it and offer: start Docker, or use the fallback. Never block silently |
+| Seed / reset data | explicit commands |
+| Health check | how to verify the stack is up |
+| URLs / ports | frontend, backend, database |
+
+Mode-specific behavior:
+
+- **Legacy / Active:** derive the contract from evidence — existing `docker-compose*.yml`, `Makefile`, `package.json` scripts, README run instructions. Do not invent commands; ask the user to confirm anything ambiguous.
+- **Brand-new:** offer to scaffold a development compose file (db + backend + frontend) matching the TRD stack. If the user declines or has no Docker, record the native fallback as the primary route.
+
+**Boundary rule (record it in the section):** the local environment is **disposable** — agents may freely start, seed, and reset it to verify work. Deployments to cloud/PROD are **governed** — they follow this document's sections 1–5 (components, IaC, CI/CD defined at constitution time) and are never improvised by agents.
+
 ---
 
 ### Step 7: Create or Enhance General Setup Templates
@@ -302,6 +323,7 @@ The update should explain briefly:
 - Which skills should be used for common work in the project (the `## Skill Map` added in Step 8D)
 - Whether CodeGraph is initialized and how agents should use it for existing-project analysis
 - Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 8C)
+- How to start the local stack: point at the `## Local Environment` contract in `docs/infrastructure.md` (Step 6B) — agents consult it instead of guessing start commands
 
 Preserve the repository's existing `CLAUDE.md` and `AGENTS.md` conventions and extend them.
 

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

@@ -133,6 +133,7 @@ loop:
 - Re-read the requirements and scenarios covered by the task.
 - Identify the smallest safe change that satisfies the task.
 - Identify the verification command listed in the task.
+- **Environment-dependent verification:** if the verification needs a running stack (integration behavior, manual smoke, anything hitting the database or a live server), consult the `## Local Environment` contract in `docs/infrastructure.md` and run its **pre-check** now — before spawning the Implementer. If the primary route is unavailable (e.g. the Docker daemon is off), ask the user whether to start it or proceed via the contract's fallback route; pass the resolved start/health-check commands in the Implementer's brief. If no contract exists, note the gap and recommend `/akili-constitution` (Step 6B) after the run.
 
 #### 2.2 — Spawn Implementer
 

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

@@ -100,6 +100,7 @@ The Leader decides the count from the spec's depth and the independence of the s
 
 1. Partition the work into concrete **suites**: backend unit, frontend unit, integration, E2E — only those the spec actually needs.
 2. For each suite, assemble a **context slice**: the target requirements + scenarios, the negative/strict rules to assert, the repo test command, and the relevant skills.
+   - **Integration/E2E suites additionally get the `## Local Environment` contract** from `docs/infrastructure.md` (start, seed/reset, health-check commands and URLs) so Testers never guess how to bring the stack up. Run the contract's **pre-check at planning time** — if the primary route is unavailable (e.g. Docker daemon off), resolve it with the user (start it, or use the fallback route) before spawning suites, not mid-suite. If no contract exists, note the gap in the test report and recommend `/akili-constitution` (Step 6B).
 3. Apply the **Deployment Rule** to decide inline vs delegated, and parallel vs sequential.
 4. **Select each suite's skills as Leader — you own the decision, not a fixed list.** The spec's task skills and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) are your **defaults, not a pass-through**: judge each suite's actual nature and augment, narrow, or override them (conditional skills like `systematic-debugging` for failure-heavy suites or `ui-ux-pro-max` for UI-heavy E2E; stack skills come from the Skill Map). When you deviate from the spec's list, record a one-line reason in the test report's Summary.
 5. **Set each suite's effort** (the *Effort dial* in `## Model Routing`, orthogonal to the tier): default `medium` for a T2 Tester, `low` for a trivial single-assertion suite, `xhigh` for complex integration/concurrency suites, `max` for correctness-critical coverage. Where the tool exposes a per-spawn effort knob, set it; otherwise steer depth in the suite's context slice. Never `max` a cheaper tier — escalate the tier instead.

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

@@ -87,6 +87,8 @@ Prefer the commands defined by the repo rather than assuming a fixed stack.
 
 If no command exists, record the gap and recommend the smallest useful command to add.
 
+**Environment boot smoke (optional):** when `docs/infrastructure.md` has a `## Local Environment` contract and the spec's behavior warrants it, boot the stack per the contract (pre-check first; fallback route if the primary is unavailable) and confirm the health check passes. Record boot failure as **FAIL**, a missing contract as a **WARN** gap recommending `/akili-constitution` (Step 6B).
+
 ### Phase 4: Requirement Coverage Verification
 
 For every requirement in `requirements.md`, verify:

package/CHANGELOG.md

@@ -10,6 +10,11 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.13.1] - 2026-07-24
+
+### Added
+
+- **Local Environment contract — the constitutional baseline now captures how to start the local stack.** `/akili-constitution` Step 6 evolves `docs/infrastructure.md` from a deployment-only blueprint into an environments blueprint (laptop → PROD): new **Step 6B** scaffolds a `## Local Environment` section as a **contract, not a tool** — Docker Compose as the recommended primary route plus a mandatory no-Docker fallback, a pre-check (e.g. `docker info`; on failure offer to start Docker or use the fallback, never block silently), seed/reset commands, health check, and URLs/ports. Legacy projects derive the contract from evidence (compose files, `package.json` scripts); brand-new projects are offered a dev compose scaffold. The section records the **boundary rule**: the local environment is disposable (agents may start/seed/reset it freely) while cloud/PROD deployments stay governed by the blueprint's components/IaC/CI-CD sections and are never improvised by agents. Consumers: `/akili-execute` Step 2.1 (environment-dependent verification consults the contract and runs the pre-check before spawning the Implementer), `/akili-test` Phase 1 (integration/E2E context slices carry the contract; pre-check resolves at planning time, not mid-suite), `/akili-validate` Phase 3 (optional boot smoke — boot failure FAIL, missing contract WARN), and the Step 8 root guides point agents at the contract. Design recorded in `docs/plans/2026-07-24-local-environment-contract.md`.
 ## [2.13.0] - 2026-07-24
 
 ### Added

package/docs/plans/2026-07-24-local-environment-contract.md

@@ -0,0 +1,53 @@
+# Proposal: Local Environment Contract
+
+**Status:** Implemented (2026-07-24) — see `CHANGELOG.md` → Unreleased
+**Date:** 2026-07-24
+**Author:** Leader session
+
+Add a **Local Environment contract** to the constitutional baseline: a tool-agnostic section in `docs/infrastructure.md` that captures how to start the project's local stack (database, backend, frontend) — with Docker Compose as the recommended primary route and a documented no-Docker fallback. Agents (Implementer, Tester, validators) consume the contract instead of guessing start commands from `package.json`.
+
+## Decision summary
+
+| # | Decision | Rationale |
+|---|----------|-----------|
+| 1 | The methodology defines a **contract, not a tool** | Docker Compose is the recommended primary route, but not every user has Docker (or has it running); the contract always documents a fallback |
+| 2 | Lives in `docs/infrastructure.md` as `## Local Environment` | The doc evolves from "deployment blueprint" to "environments blueprint — laptop to PROD"; one home, no new file |
+| 3 | Pre-check before use, never block | `docker info` fails (daemon off / not installed) → tell the user and offer: start Docker, or use the fallback route |
+| 4 | Local is disposable; cloud is governed | Agents may freely start/reset the local environment; deployments to cloud/PROD follow the existing infrastructure blueprint (TRD tier → components → ADR) and are **never improvised by agents** |
+| 5 | No `/akili-deploy` automation for now | Deploys are high-risk; the governed blueprint + checklist yields more than premature automation |
+
+## The contract (scaffolded shape)
+
+| Element | Example |
+|---------|---------|
+| Primary route (recommended) | `docker compose up -d` |
+| Fallback route (no Docker) | `npm run dev` + local Postgres or a cloud dev database |
+| Pre-check | `docker info` — on failure, surface it and use/offer the fallback |
+| Seed / reset data | explicit commands |
+| Health check | how to know the stack is up |
+| URLs / ports | frontend, backend, database |
+
+## Where it lands
+
+| Surface | Change |
+|---------|--------|
+| `/akili-constitution` Step 6 | Scaffold `## Local Environment` into `docs/infrastructure.md`; legacy mode derives it from evidence (existing compose files, `package.json` scripts); brand-new mode offers to scaffold a dev compose file; states the local-vs-cloud boundary rule |
+| `/akili-constitution` Step 8 | Root guides briefly point agents at the contract |
+| `/akili-execute` Step 2.1 | Tasks whose verification needs a running environment consult the contract + run the pre-check before spawning the Implementer |
+| `/akili-test` Phase 1 | Integration/E2E suites get the contract in their context slice; pre-check happens at planning, not mid-suite |
+| `/akili-validate` Phase 3 | Build Integrity may include an environment boot smoke per the contract |
+
+## Out of scope
+
+- No changes to the cloud/PROD sections of `docs/infrastructure.md` (Step 6 structure items 1–5 unchanged).
+- No `/akili-deploy` command.
+- No requirement that projects adopt Docker — the contract is satisfied by any documented primary + fallback pair.
+
+## Implementation checklist
+
+- [x] `/akili-constitution` Step 6: `## Local Environment` scaffold + legacy derivation + dev-compose offer + boundary rule.
+- [x] `/akili-constitution` Step 8: root-guide reference to the contract.
+- [x] `/akili-execute` Step 2.1: consult contract + pre-check for environment-dependent verification.
+- [x] `/akili-test` Phase 1: contract in integration/E2E context slices.
+- [x] `/akili-validate` Phase 3: optional boot smoke.
+- [x] `CHANGELOG.md` → Unreleased.

package/package.json

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