akili-specs 2.5.0 → 2.6.0

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

@@ -1,5 +1,5 @@
 ---
-description: Archive a completed spec task, sync agent guides and CodeGraph, and keep the TRD current.
+description: Archive a completed spec task, run the Kaizen retrospective, sync agent guides and CodeGraph, and keep the TRD current.
 ---
 
 # Archive AKILI-SPECS Spec
@@ -8,7 +8,7 @@ Archive a completed AKILI-SPECS spec path after implementation, testing, and val
 
 Archiving preserves the full decision trail. It keeps active `docs/specs/` easier to scan while retaining proposal, requirements, design, tasks, execution notes, test evidence, and validation evidence for future review.
 
-> **Recommended model tier:** T5 Fast-Cheap. This is a format-following and file-moving job; a deep reasoning model is not required.
+> **Recommended model tier:** T5 Fast-Cheap. This is a format-following and file-moving job; a deep reasoning model is not required. The Kaizen Learn sub-step (Step 4.2) is a judgment task — if convenient, run it on a T3 Auditor model; otherwise keep the whole command on T5 and keep lessons few.
 
 ## Usage
 
@@ -71,6 +71,10 @@ docs/specs/archive/2026-05-16-bugfix--login-redirect/
    - `execution.md` if present
    - `test-report.md` if present
    - `validation-report.md` if present
+4. Read Kaizen inputs (each only if it exists):
+   - `docs/specs/kaizen-log.md`
+   - `docs/specs/drift-report.md`
+   - `docs/specs/quick/quick-log.md` (only if this spec escalated from `/akili-quick`)
 
 ### Step 1: Check Archive Readiness
 
@@ -119,13 +123,35 @@ Before moving the folder, sync the project constitution with what the spec actua
    - Follow the inheritance convention from `/akili-constitution` Step 7 — if the project has no `## Module Guides` index yet, add it rather than inventing a parallel structure.
 3. **CodeGraph Refresh Hook:** Check if `.codegraph/` exists in the repository root. If it does, recommend that the user or environment runs a fresh CodeGraph indexing/update (e.g. running `codegraph index` or equivalent) so the graph reflects the new or reshaped modules.
 
-### Step 4: Move Folder
+### Step 4: Kaizen Retrospective
+
+Before moving the folder, **load the `kaizen` skill and follow its loop contract**: one bounded continuous-improvement pass over the completed spec — **Measure → Learn → Standardize → Record**. The pass reads only files already loaded in Step 0, produces at most 3 lessons and one log entry, and must never block the archive.
+
+#### 4.1 — Measure
+
+Extract the improvement signals listed in the skill's Measure table from the spec's own evidence: Reviewer FAIL rework attempts, HALTs and FATAL_FAILs, `## Pivot Record` blocks, PRODUCT_BUG findings, severe judgment-day findings, validation FAIL/WARN counts, `/akili-quick` escalations, and drift attributable to this spec.
+
+If every signal is clean, record a one-line **clean run** entry in Step 4.4 and skip 4.2–4.3.
+
+#### 4.2 — Learn
+
+Distill **0 to 3** lessons following the skill's hard rules: every lesson names a root cause and cites its evidence (file + section); generic lessons are banned; prefer zero lessons over filler; a repeated root cause increments recurrence and raises severity instead of duplicating. Classify each lesson's target as **Product** (this project) or **Methodology** (the root cause is AKILI itself).
+
+#### 4.3 — Standardize (HITL)
+
+For each lesson, propose exactly one minimal edit (1–3 lines) to the most durable home (constitution guides, `docs/specs/general-setup/` templates, `docs/ux-ui/design.md`, or `.agents/` personas — append-only). Methodology lessons get no local edit; record them for upstreaming to the AKILI methodology repository. Present the skill's approval menu (Apply all / Apply selected / Defer all / Type something); recommend "Apply all" when any High-severity lesson exists, otherwise "Defer all". **Every edit outside the kaizen log requires this approval.**
+
+#### 4.4 — Record
+
+Create or update `docs/specs/kaizen-log.md` using the skill's Kaizen Log Format: prepend the new entry under `## Entries`, refresh `## Active Lessons` (10 rows max, retire institutionalized lessons).
+
+### Step 5: Move Folder
 
 1. Ensure `docs/specs/archive/` exists.
 2. Move `docs/specs/$ARGUMENTS/` to `docs/specs/archive/YYYY-MM-DD-$SAFE_NAME/`.
 3. If the target archive folder already exists, do not overwrite it. Add a numeric suffix such as `-2` and report the final path.
 
-### Step 5: Report To User
+### Step 6: Report To User
 
 Present:
 
@@ -135,6 +161,7 @@ Present:
 4. unresolved follow-ups, if any
 5. whether the active spec directory is now clean
 6. constitution sync summary: guides created or updated, parent index entries touched, and whether a CodeGraph re-index is recommended
+7. Kaizen summary: metrics captured, lessons recorded (IDs), standardization actions applied or deferred, and any Methodology lessons suggested for upstreaming to the AKILI repo
 
 ## Error Handling
 
@@ -143,3 +170,5 @@ Present:
 - If validation has unresolved FAIL findings, recommend fixing or explicitly accepting risk before archive.
 - If moving the folder fails, leave the original folder in place and report the reason.
 - Do not delete spec folders as part of archiving; only move them into `docs/specs/archive/`.
+- The Kaizen retrospective must never block the archive. If retrospective inputs are missing or the user declines, append a metrics-only (or clean-run) entry to `docs/specs/kaizen-log.md` and continue to Step 5.
+- Never edit files outside `docs/specs/kaizen-log.md` without explicit user approval in Step 4.3.

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

@@ -75,6 +75,7 @@ The Leader does not write production code itself unless the rework loop is exhau
    - `docs/specs/$ARGUMENTS/design.md`
    - `docs/specs/$ARGUMENTS/tasks.md`
 3. Read `docs/specs/$ARGUMENTS/execution.md` if it exists.
+   - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 4. Read the agent personas:
    - `.agents/leader.md`
    - `.agents/implementer.md`
@@ -133,6 +134,7 @@ Delegate to the Implementer with:
 - the project constitution references (`CLAUDE.md`, `AGENTS.md`, `docs/ux-ui/design.md`)
 - the recommended skill list from the task (e.g. `ui-ux-pro-max`, `react-doctor`, `nestjs-expert`)
 - any prior Reviewer feedback when this is a rework attempt
+- any Active Lessons from `docs/specs/kaizen-log.md` relevant to the task's domain (pass only the matching rows, never the full log)
 - the verification command to run before reporting completion
 
 The Implementer must keep changes minimal and within task scope, follow the design spec exactly unless the spec is clearly incomplete or contradictory, and run the verification before reporting completion.

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

@@ -65,6 +65,7 @@ Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unle
    - `docs/specs/general-setup/`
    - package-level `CLAUDE.md` files
 4. Read nearby or related specs under `docs/specs/`.
+   - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 5. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
 
 ### Step 1: Classify Request Type & Route
@@ -143,6 +144,8 @@ Create a concise proposal with this structure:
 13. Success Criteria
 14. Next Step
 
+If an Active Lesson from `docs/specs/kaizen-log.md` applies to this change's domain, reflect it in Scope or Risks and cite its ID (e.g. `KZ-003`).
+
 ### Visual Reference
 
 Capture whatever visual source backs this change so `/akili-specify` can convert it into requirements, design, and tasks. Use the state that applies:

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

@@ -78,6 +78,12 @@ If **multiple specs** are active, present a dashboard:
 Which spec do you want to resume? (or "all" for full briefing)
 ```
 
+If `docs/specs/kaizen-log.md` exists, append a Kaizen footer line to either format, reading ONLY the `## Active Lessons` table:
+
+```markdown
+Kaizen: 3 active lessons (latest: KZ-003 — empty-state tokens before list UI)
+```
+
 ### Step 3: Provide Full Briefing (if requested)
 
 If the user selects "all" or if there's only one spec, provide a detailed briefing for each:

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

@@ -74,6 +74,7 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
    - A generated mockup under `docs/specs/$ARGUMENTS/mockup/`, `.stitch/designs`, or a `.stitch/DESIGN.md` reference → read those artifacts (screens, HTML, design tokens) and use `stitch-design` to interpret them.
    - Any mockup produced during `/akili-propose` counts as visual design context for the `Design Impact` steps below, exactly like a Figma link.
 4. Read nearby or dependent specs under `docs/specs/` that overlap with the requested path.
+   - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 5. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
 6. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
 
@@ -189,7 +190,7 @@ Use additional technical skills as needed:
 
 #### Step 2.2 — Write
 
-Generate `design.md` using `docs/specs/general-setup/design.md` as the format source.
+Generate `design.md` using `docs/specs/general-setup/design.md` as the format source. Apply relevant Active Lessons from `docs/specs/kaizen-log.md` and cite the lesson ID next to the design decision it shaped.
 
 Minimum content:
 

package/.claude/skills/kaizen/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: kaizen
+description: "Trigger: kaizen, retrospective, continuous improvement, mejora continua, /akili-archive Kaizen step. Run the bounded Kaizen retrospective: Measure → Learn → Standardize → Record."
+license: MIT
+metadata:
+  author: Juan Carlos Cadavid — jcadavid.com
+  version: "1.0"
+  inspired-by: "Kaizen Institute glossary (kaizen.com), 'El Método Kaizen' (small-steps approach, Robert Maurer), 'Emprendiendo Kaizen' (INTI, 2019, ISBN 978-950-532-415-6)"
+---
+
+# Kaizen — The AKILI Continuous-Improvement Skill
+
+Kaizen (改善, *kai* = change, *zen* = better) is the Japanese philosophy of continuous improvement through small, disciplined, daily steps. This skill turns that philosophy into an executable retrospective for AI-assisted development: every archived spec must leave the project — and the methodology itself — slightly better than it found them.
+
+> Other methodologies execute specs. AKILI learns from every spec.
+
+## Activation Contract
+
+Load this skill when:
+
+- `/akili-archive` reaches its **Kaizen Retrospective** step (the primary, automatic trigger), or
+- the user explicitly requests a kaizen retrospective / continuous-improvement pass over a spec or project.
+
+The retrospective is **bounded**: one pass, at most 3 lessons, one log entry. It must never block the archive or any other command that invoked it.
+
+## Philosophy → Engineering Mapping
+
+Each Kaizen concept maps to a concrete AKILI mechanism. Use this vocabulary in reports so the improvement culture stays visible.
+
+| Concept | Meaning | In AKILI |
+|---|---|---|
+| **Kai + Zen** | Small changes that make things better, every day, forever | Every `/akili-archive` is an improvement opportunity; the loop never "finishes" |
+| **Small steps** (Maurer) | Improvements so small they cannot fail or trigger resistance | Standardization edits are 1–3 lines; never rewrite a document to institutionalize a lesson |
+| **Small questions** (Maurer) | Gentle questions unlock root causes better than big alarming ones | Learn step asks: *"What is the smallest rule that would have prevented this rework?"* |
+| **PDCA** (Deming) | Plan → Do → Check → Act | Plan = the spec; Do = execute/test; Check = validate + **Measure**; Act = **Standardize**. The retrospective closes the cycle the pipeline opened |
+| **MUDA** | Waste: any activity that adds no value | Rework attempts (defects), pivots (planning waste), token waste (oversized context, re-reading), stale docs (drift = inventory waste), quick-escalations (misrouted work). **Measure = hunt MUDA** |
+| **Jidoka** | Stop the line the moment a defect appears | AKILI already practices it: the Tester keeps a test red on `PRODUCT_BUG`; the harness HALTs on `FATAL_FAIL`. Name it in reports — the methodology owns this concept |
+| **Gemba / 3 GEN** | Real place, real thing, real facts — never speculate | Every lesson must cite evidence from the actual artifacts (`execution.md`, `test-report.md`, `validation-report.md`); use **5W1H** to reach root cause |
+| **LUP** (one-point lesson) | One lesson, one page, instantly teachable | The `## Active Lessons` digest row: one lesson, one line, one owner document |
+| **Standardize & repeat** | A fix becomes a standard, then the next improvement begins | Applied lessons live in constitution guides/templates; the digest retires them once institutionalized |
+
+## The Loop Contract
+
+Run the four phases in order. Read only artifacts already loaded by the invoking command.
+
+### 1. Measure
+
+Extract improvement signals from the spec's own evidence:
+
+| Signal | Source |
+|---|---|
+| Reviewer FAIL rework attempts, HALTs, FATAL_FAILs | `execution.md` task entries |
+| Pivots | `execution.md` `## Pivot Record` blocks |
+| PRODUCT_BUG findings | `test-report.md` |
+| Severe judgment-day findings | `design.md` / specify review notes, if recorded |
+| Validation FAIL / WARN counts | `validation-report.md` |
+| Escalations from `/akili-quick` into this spec | `docs/specs/quick/quick-log.md`, if applicable |
+| Drift attributable to this spec | `docs/specs/drift-report.md`, if present |
+
+If every signal is clean (zero rework, no pivots, no product bugs, no severe findings), record a one-line **clean run** entry in phase 4 and skip phases 2–3. A clean spec teaches nothing new — say so.
+
+### 2. Learn
+
+Distill **0 to 3** lessons. Hard rules:
+
+- Every lesson names a **root cause** (apply 5W1H) and cites its evidence — file + section, e.g. `execution.md — Task 4, attempts 1–2 (Violated Rule: design.md#tokens)`. Gemba: real facts only.
+- Generic lessons are banned ("write better tests", "be more careful"). A lesson must change what a future command concretely does.
+- Prefer **zero lessons** over filler.
+- If the same root cause already exists in `## Active Lessons`, do not duplicate it — increment its recurrence note and raise its severity (a repeat is a strong standardization signal).
+- Classify each lesson's **target**:
+  - **Product** (default): the root cause lives in this project — its guides, templates, design tokens, or personas.
+  - **Methodology**: the root cause is AKILI itself — an ambiguous command step, a template gap, a missing skill. These lessons make the methodology learn from every tool built with it.
+
+### 3. Standardize (HITL)
+
+For each lesson, propose **exactly one** minimal edit (1–3 lines) targeting the most durable home:
+
+- root `CLAUDE.md` / `AGENTS.md` (or a child module guide) — behavioral rules
+- `docs/specs/general-setup/` templates — spec-authoring rules
+- `docs/ux-ui/design.md` — missing tokens or visual rules
+- `.agents/` personas — harness-role rules (append-only, never rewrite)
+- **Methodology lessons:** no local edit — record the proposal in the log and recommend upstreaming it to the AKILI methodology repository.
+
+Assign a severity: **High** = caused a HALT, pivot, or PRODUCT_BUG; **Medium** = caused rework or a severe finding; **Low** = friction only. Then present the menu:
+
+1. **Apply all** (make every proposed edit now)
+2. **Apply selected** (user picks by lesson ID)
+3. **Defer all** (record proposals in the log; apply in a later spec)
+4. **Type something** (adjust a proposal before applying)
+
+Recommend option 1 when any High-severity lesson exists, otherwise option 3. Appending to the kaizen log is automatic; **every edit outside the log requires this approval**.
+
+### 4. Record
+
+Create or update `docs/specs/kaizen-log.md` (it lives outside spec folders so it survives archiving):
+
+1. If the file does not exist, create it with the header and both sections from the format below.
+2. Prepend the new entry under `## Entries` (newest first).
+3. Refresh `## Active Lessons`: add new lessons; keep the table at **10 rows or fewer**; retire lessons whose rule now lives in the constitution or templates (mark `Retired` — the guide carries the rule from now on).
+
+## Kaizen Log Format
+
+```markdown
+# Kaizen Log
+
+Continuous-improvement record for this project, updated automatically by
+`/akili-archive` (Kaizen Retrospective, powered by the `kaizen` skill).
+Other AKILI commands read only the `## Active Lessons` table below —
+keep it at 10 rows or fewer.
+
+## Active Lessons
+
+| ID | Lesson | Source Spec | Severity | Target | Standardized In | Status |
+|---|---|---|---|---|---|---|
+| KZ-003 | Define empty-state design tokens before any UI task that renders lists | changes/add-remember-me | Medium | Product | docs/specs/general-setup/design.md | Applied |
+| KZ-002 | DTO boundary validations must be written as `AND IT MUST` constraints in requirements, never left implicit | bugfix/login-redirect | High | Product | docs/specs/general-setup/requirements.md | Applied |
+
+## Entries
+
+### 2026-07-20 — changes/add-remember-me
+
+**Metrics**
+
+| Signal | Value | Source |
+|---|---|---|
+| Tasks executed | 8 | tasks.md |
+| Reviewer FAIL rework attempts | 3 (Task 4 x2, Task 7 x1) | execution.md |
+| HALTs / FATAL_FAILs | 0 | execution.md |
+| Pivots | 1 (Task 5 — storage approach) | execution.md — ## Pivot Record: Task 5 |
+| PRODUCT_BUGs | 1 (resolved) | test-report.md |
+| Judgment-day severe findings | 2 | design.md review notes |
+| Validation FAIL / WARN | 0 / 2 | validation-report.md |
+
+**Lessons**
+
+- **KZ-003 — Empty-state tokens were missing from the design phase.** (Product, Medium)
+  - Root cause: `design.md` specified list components without empty-state tokens, so the
+    Implementer improvised styles and the Reviewer failed Task 4 twice on token compliance.
+  - Evidence: execution.md — Task 4, attempts 1–2 (Violated Rule: design.md#tokens).
+  - Standardization: add an empty-state token check to the Design Impact checklist in
+    `docs/specs/general-setup/design.md`. → **Applied 2026-07-20 (user-approved)**
+
+### 2026-07-19 — bugfix/session-refresh — clean run
+
+No rework, pivots, product bugs, or severe findings. No lessons recorded.
+```
+
+## Hard Rules
+
+- **Never block the archive** (or any invoking command). Missing inputs or a declined menu → append a metrics-only or clean-run entry and continue.
+- **Never edit files outside `docs/specs/kaizen-log.md` without explicit HITL approval** in phase 3.
+- Digest capped at **10 Active Lessons**; retire institutionalized lessons instead of letting the table grow.
+- At most **3 lessons per retrospective**; prefer zero over filler.
+- Standardization edits are **1–3 lines**; never rewrite whole documents.
+- Consumers (`/akili-propose`, `/akili-specify`, `/akili-execute`, `/akili-resume`) read **only** the `## Active Lessons` digest, never `## Entries`.

package/CHANGELOG.md

@@ -10,6 +10,16 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.6.0] - 2026-07-20
+
+### Added
+- **The Kaizen Loop in `/akili-archive`:** every archive now runs a bounded continuous-improvement retrospective — **Measure** (rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, drift) → **Learn** (0–3 root-cause lessons with cited evidence; generic lessons banned) → **Standardize** (minimal 1–3 line edits to constitution guides, general-setup templates, design tokens, or `.agents/` personas — always HITL-approved) → **Record** (append to the new accumulative `docs/specs/kaizen-log.md`, with a capped `## Active Lessons` digest). No new command: Kaizen is a step inside `/akili-archive` and never blocks archiving. Lessons target the **Product** or the **Methodology** itself (flagged for upstreaming to this repo).
+- **New packaged `kaizen` skill** (`.claude/skills/kaizen/SKILL.md`), authored by Juan Carlos Cadavid — jcadavid.com, inspired by the Kaizen Institute glossary, Robert Maurer's small-steps method, and INTI's *Emprendiendo Kaizen* (2019). It encodes the philosophy-to-engineering mapping (PDCA, MUDA, Jidoka, Gemba/3 GEN, 5W1H, LUP), the loop contract, and the kaizen-log format.
+- **Kaizen-aware commands:** `/akili-propose`, `/akili-specify`, and `/akili-execute` read the `## Active Lessons` digest so past mistakes shape new specs and task delegation; `/akili-resume` shows the active-lesson count in its dashboard.
+## [2.5.1] - 2026-07-19
+
+### Added
+- **`akili update` now shows what changed:** After updating the npm package and reinstalling files, `akili update` prints a `What changed (<old> → <new>)` summary sourced from the installed package's `CHANGELOG.md`, listing every version section between the previously installed version and the new one. If the package was already up to date, it says so instead.
 ## [2.5.0] - 2026-07-19
 
 ### Added

package/README.md

@@ -11,9 +11,9 @@
 
 # AKILI
 
-### Supercharge Claude Code, OpenCode, and Google Antigravity with constitution-first spec intelligence
+### Supercharge Claude Code, OpenCode, and Google Antigravity with constitution-first, self-improving spec intelligence
 
-**Durable product context · traceable requirements · governed releases · 100% local methodology files**
+**Durable product context · traceable requirements · governed releases · a methodology that learns from every spec · 100% local methodology files**
 
 <p>
   <a href="https://www.npmjs.com/package/akili-specs"><img alt="npm version" src="https://img.shields.io/npm/v/akili-specs?style=for-the-badge&label=npm"></a>
@@ -507,7 +507,7 @@ See the full [Command Reference](docs/commands/README.md) for detailed pages per
 | `/akili-execute <spec-path>` | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
 | `/akili-test <spec-path>` | Adding or running test evidence | `test-report.md` with requirement-to-test traceability |
 | `/akili-validate <spec-path>` | Checking implementation against the spec | `validation-report.md` with pass, warning, failure, and remediation items |
-| `/akili-archive <spec-path>` | Closing completed work after validation | Archived spec folder under `docs/specs/archive/` with `archive-summary.md`, synced agent guides, CodeGraph re-index reminder |
+| `/akili-archive <spec-path>` | Closing completed work after validation | Archived spec folder under `docs/specs/archive/` with `archive-summary.md`, Kaizen retrospective appended to `docs/specs/kaizen-log.md`, synced agent guides, CodeGraph re-index reminder |
 | `/akili-audit` | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
 | `/akili-resume` | Resuming work after a session break | Multi-spec dashboard with phase, progress, and next command recommendation |
 | `/akili-seo <site-domain>` | Auditing deployed SEO and Search Console state | `seo-setup-report.md`, `seo-audit-report.md` |
@@ -539,6 +539,30 @@ Lite mode does not skip rigor. It keeps the documents short, but every requireme
 | Task | A small executable unit linked to requirements and design sections |
 | Report | Evidence that the implementation was tested and validated |
 | Archive | Completed AKILI-SPECS history moved under `docs/specs/archive/` |
+| Kaizen | The continuous-improvement loop that turns each spec's evidence into lessons and standards |
+
+## The Kaizen Loop
+
+Other methodologies execute specs. **AKILI learns from every spec.**
+
+AKILI embeds the Japanese Kaizen philosophy of continuous improvement (改善 — *kai* change, *zen* better) as an executable step, powered by the packaged `kaizen` skill (authored by [Juan Carlos Cadavid](https://jcadavid.com), inspired by the Kaizen Institute glossary, Robert Maurer's small-steps method, and INTI's *Emprendiendo Kaizen*). Every `/akili-archive` automatically runs a bounded retrospective — no extra command, no extra ceremony:
+
+```text
+┌─────────┐    ┌─────────┐    ┌──────────────┐    ┌──────────┐
+│ MEASURE │ ─▶ │  LEARN  │ ─▶ │ STANDARDIZE  │ ─▶ │  REPEAT  │
+│ rework, │    │ 0–3 root│    │ constitution │    │ next spec│
+│ pivots, │    │ -cause  │    │ templates,   │    │ reads the│
+│ bugs    │    │ lessons │    │ guides (HITL)│    │ lessons  │
+└─────────┘    └─────────┘    └──────────────┘    └──────────┘
+        every /akili-archive · logged in docs/specs/kaizen-log.md
+```
+
+- **Measure:** hunt MUDA (waste) in the spec's own evidence — Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation warnings, drift.
+- **Learn:** distill 0–3 lessons with a named root cause and cited evidence (Gemba: real facts, never speculation). Generic lessons are banned.
+- **Standardize:** propose 1–3 line edits to constitution guides, spec templates, design tokens, or agent personas — always human-approved. Small steps, never rewrites.
+- **Record:** append to the accumulative `docs/specs/kaizen-log.md`; a capped `## Active Lessons` digest is then read by `/akili-propose`, `/akili-specify`, and `/akili-execute` so past mistakes shape new work, and shown by `/akili-resume`.
+
+The loop improves on two levels: **Product** lessons harden the project you are building, while **Methodology** lessons (root causes in AKILI itself) are flagged for upstreaming — so the methodology learns from every tool built with it. This is the meaning behind the name: *akili* is Swahili for intelligence, and intelligence that does not learn is not intelligence.
 
 ## Spec Folder Shape
 
@@ -729,7 +753,7 @@ Fallback rule:
 - `/akili-execute` orchestrates a Leader → Implementer → Reviewer rework loop (max 3 retries) to implement tasks from an approved spec path.
 - `/akili-test` runs a Leader → Tester(s) harness: the Leader partitions testing into suites and delegates each to a Tester subagent (inline for trivial/Lite work; one Tester per independent suite, in parallel, otherwise). It validates requirement-to-test traceability, explicitly checking for negative constraints and strict boundaries.
 - `/akili-validate` audits implementation conformance against the spec (including rigorous boundary validations) and constitutional baseline.
-- `/akili-archive` preserves completed specs under `docs/specs/archive/` after validation, syncs agent guides (child `CLAUDE.md`/`AGENTS.md` + the parent `## Module Guides` index) from the spec's `## Constitution Impact` notes, and recommends a CodeGraph re-index.
+- `/akili-archive` preserves completed specs under `docs/specs/archive/` after validation, runs the Kaizen retrospective (measure → learn → standardize → record) appending to `docs/specs/kaizen-log.md`, syncs agent guides (child `CLAUDE.md`/`AGENTS.md` + the parent `## Module Guides` index) from the spec's `## Constitution Impact` notes, and recommends a CodeGraph re-index.
 - `/akili-seo` operates outside the main spec lifecycle: it provisions Google Search Console ownership for a domain and produces a standalone SEO audit under `docs/specs/seo/<domain>/`. Run it any time after deployment; rerun after major content or schema changes.
 
 ## Multi-Agent Harness Engineering

package/bin/akili.js

@@ -78,7 +78,7 @@ Usage:
 
 Commands:
   install   Install commands, skills, and helper resources
-  update    Update npm package to latest version and reinstall files
+  update    Update npm package to latest version, reinstall files, and show what changed
   doctor    Check whether expected files are installed
   list      List packaged commands, skills, and helper resources
   help      Show this help
@@ -398,6 +398,107 @@ function detectInstallType() {
   return "npx";
 }
 
+// Resolve the installed akili-specs package directory (global or local) after an update.
+// Returns the absolute path to the package root, or null if it cannot be found.
+function resolveInstalledPackageDir(installType) {
+  try {
+    const root = execSync(
+      installType === "global" ? "npm root -g 2>/dev/null" : "npm root 2>/dev/null",
+      { encoding: "utf8" }
+    ).trim();
+    if (root) {
+      const dir = path.join(root, "akili-specs");
+      if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+    }
+  } catch (e) {}
+  return null;
+}
+
+// Read the version from an installed package's package.json.
+function readInstalledVersion(packageDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8")).version;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Parse CHANGELOG.md and return the raw text of every version section strictly
+// newer than `fromVersion` up to and including `toVersion`. Sections look like
+// `## [X.Y.Z] - date`. Returns an array of { version, body } newest-first.
+function changelogSectionsBetween(changelogPath, fromVersion, toVersion) {
+  let text;
+  try {
+    text = fs.readFileSync(changelogPath, "utf8");
+  } catch (e) {
+    return [];
+  }
+
+  const lines = text.split("\n");
+  const sections = [];
+  let current = null;
+
+  const isNewer = (a, b) =>
+    a.localeCompare(b, undefined, { numeric: true, sensitivity: "base" }) > 0;
+
+  for (const line of lines) {
+    const match = line.match(/^##\s+\[([^\]]+)\]/);
+    if (match) {
+      if (current) sections.push(current);
+      current = { version: match[1], bodyLines: [] };
+    } else if (current) {
+      current.bodyLines.push(line);
+    }
+  }
+  if (current) sections.push(current);
+
+  return sections
+    .filter((s) => /^\d+\.\d+\.\d+/.test(s.version)) // skip "Unreleased"
+    .filter((s) => {
+      const newerThanFrom = !fromVersion || isNewer(s.version, fromVersion);
+      const notNewerThanTo = !toVersion || !isNewer(s.version, toVersion);
+      return newerThanFrom && notNewerThanTo;
+    })
+    .map((s) => ({ version: s.version, body: s.bodyLines.join("\n").trim() }));
+}
+
+// Print a concise summary of what changed between two versions, sourced from the
+// installed package's CHANGELOG.md.
+function printUpdateChangeSummary(packageDir, fromVersion, toVersion) {
+  if (!packageDir || !fromVersion || !toVersion) return;
+
+  if (fromVersion === toVersion) {
+    console.log(
+      `\n${colors.cyan}Already on the latest version (${toVersion}). No changelog to show.${colors.reset}`
+    );
+    return;
+  }
+
+  const changelogPath = path.join(packageDir, "CHANGELOG.md");
+  const sections = changelogSectionsBetween(changelogPath, fromVersion, toVersion);
+
+  console.log(
+    `\n${colors.cyan}What changed (${fromVersion} → ${toVersion}):${colors.reset}`
+  );
+
+  if (sections.length === 0) {
+    console.log(`  (No changelog entries found for this range.)`);
+    return;
+  }
+
+  for (const section of sections) {
+    console.log(`\n${colors.green}v${section.version}${colors.reset}`);
+    const body = section.body || "  (No details recorded.)";
+    // Indent each line slightly for readability.
+    console.log(
+      body
+        .split("\n")
+        .map((l) => (l.length ? `  ${l}` : l))
+        .join("\n")
+    );
+  }
+}
+
 function runUpdate(args) {
   const installType = detectInstallType();
 
@@ -410,6 +511,9 @@ function runUpdate(args) {
     return;
   }
 
+  // Capture the version before updating so we can show what changed afterward.
+  const versionBefore = currentVersion;
+
   console.log(`\n${colors.yellow}Updating npm package...${colors.reset}`);
 
   try {
@@ -428,6 +532,13 @@ function runUpdate(args) {
   console.log(`\n${colors.yellow}Reinstalling files with --force...${colors.reset}`);
   args.force = true;
   runInstall(args);
+
+  // After reinstalling, read the freshly installed version and show the changelog
+  // between the old and new versions. The running process still has the old code
+  // loaded, so we read version + CHANGELOG from the installed package on disk.
+  const packageDir = resolveInstalledPackageDir(installType);
+  const versionAfter = packageDir ? readInstalledVersion(packageDir) : null;
+  printUpdateChangeSummary(packageDir, versionBefore, versionAfter);
 }
 
 function runInstall(args) {

package/docs/README.md

@@ -1,6 +1,6 @@
 # AKILI Documentation
 
-AKILI is the documented form of the AKILI-SPECS methodology: a constitution-first, spec-driven workflow for Claude Code and OpenCode.
+AKILI is the documented form of the AKILI-SPECS methodology: a constitution-first, self-improving spec-driven workflow for Claude Code and OpenCode.
 
 Use this documentation when you want the human-facing reference. The installable source prompts and skills remain under `.claude/commands/` and `.claude/skills/`.
 
@@ -26,6 +26,8 @@ Use this documentation when you want the human-facing reference. The installable
 /akili-archive <spec-path>
 ```
 
+Every `/akili-archive` closes with the **Kaizen Loop** — a bounded retrospective (Measure → Learn → Standardize → Record, via the packaged `kaizen` skill) that appends lessons to `docs/specs/kaizen-log.md` so the next spec starts smarter. See [flow.md](flow.md#8-the-kaizen-loop).
+
 Use `/akili-resume` at the start of any session to see a dashboard of all active specs and where each one stands.
 
 Use `/akili-audit` independently to detect drift between specs and codebase reality at any time.

package/docs/cli.md

@@ -51,7 +51,7 @@ akili install --tool both --local
 |---|---|
 | `akili init` | Interactive setup wizard for installation |
 | `akili install` | Install commands, skills, and helper resources |
-| `akili update` | Reinstall packaged commands, skills, and helper resources |
+| `akili update` | Update the npm package to the latest version, reinstall files, and print a changelog summary of what changed |
 | `akili list` | List packaged commands, skills, and helper resources |
 | `akili doctor` | Check whether expected files are installed |
 | `akili help` | Show help |

package/docs/commands/README.md

@@ -13,7 +13,7 @@ AKILI commands are installed as slash-command prompts for Claude Code and OpenCo
 | [`/akili-execute <spec-path>`](akili-execute.md) | Implementing approved tasks via the Leader → Implementer → Reviewer harness | Code/docs changes, updated `tasks.md`, `execution.md` with full PASS/FAIL audit trail |
 | [`/akili-test <spec-path>`](akili-test.md) | Proving behavior with test evidence via the Leader → Tester(s) harness | `test-report.md` |
 | [`/akili-validate <spec-path>`](akili-validate.md) | Auditing conformance before completion | `validation-report.md` |
-| [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` |
+| [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` + Kaizen retrospective entry in `docs/specs/kaizen-log.md` |
 | [`/akili-audit`](akili-audit.md) | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
 | [`/akili-resume`](akili-resume.md) | Resuming work after a session break | Multi-spec dashboard with phase, progress, and next command recommendation |
 | [`/akili-seo <site-domain>`](akili-seo.md) | Setting up GSC ownership and SEO audit evidence | `seo-setup-report.md`, `seo-audit-report.md` |

package/docs/commands/akili-archive.md

@@ -1,6 +1,6 @@
 # `/akili-archive`
 
-Move a completed spec into historical archive after implementation, testing, and validation.
+Move a completed spec into historical archive after implementation, testing, and validation, running the Kaizen retrospective along the way.
 
 ## Usage
 
@@ -58,8 +58,20 @@ Before moving the folder, the command consumes the `## Constitution Impact` note
 - updates root-guide statements the change made stale
 - recommends a CodeGraph re-index when `.codegraph/` exists
 
+## Kaizen Retrospective
+
+Before moving the folder, the command loads the packaged `kaizen` skill and runs one bounded continuous-improvement pass — **Measure → Learn → Standardize → Record**:
+
+- **Measure:** extracts improvement signals from the spec's evidence (Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, quick escalations, drift).
+- **Learn:** distills 0–3 lessons, each with a named root cause and cited evidence; generic lessons are banned. Lessons target the **Product** or the **Methodology** (flagged for upstreaming to the AKILI repo).
+- **Standardize:** proposes 1–3 line edits to constitution guides, `general-setup` templates, design tokens, or `.agents/` personas via an approval menu. Every edit outside the kaizen log requires approval.
+- **Record:** appends the entry to the accumulative `docs/specs/kaizen-log.md` and refreshes its `## Active Lessons` digest (10 rows max), which `/akili-propose`, `/akili-specify`, `/akili-execute`, and `/akili-resume` read.
+
+A clean spec records a one-line clean-run entry. The retrospective never blocks the archive.
+
 ## Guardrails
 
 - Do not delete completed specs.
 - Do not overwrite an existing archive folder.
 - If archive readiness is unclear, ask whether to validate first, proceed with accepted risk, or keep the spec active.
+- The Kaizen retrospective never blocks the archive and never edits files outside `docs/specs/kaizen-log.md` without approval.

package/docs/commands/akili-execute.md

@@ -23,6 +23,7 @@ Reads:
 - `docs/specs/<spec-path>/design.md`
 - `docs/specs/<spec-path>/tasks.md`
 - `docs/specs/<spec-path>/execution.md` when present
+- `docs/specs/kaizen-log.md` when present — only the `## Active Lessons` digest; the Leader passes matching rows to the Implementer per task
 - Constitution docs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`)
 - `CLAUDE.md` and `AGENTS.md`
 - `.agents/leader.md`, `.agents/implementer.md`, `.agents/reviewer.md`

package/docs/commands/akili-propose.md

@@ -53,6 +53,8 @@ Creates or updates:
 docs/specs/<spec-path>/proposal.md
 ```
 
+If `docs/specs/kaizen-log.md` exists, the command reads its `## Active Lessons` digest and reflects applicable lessons in the proposal's Scope or Risks, citing their IDs (e.g. `KZ-003`).
+
 ## Proposal Sections
 
 - Document Control (records `Type: Bug | Change | Trivial`)

package/docs/commands/akili-resume.md

@@ -23,7 +23,7 @@ The command performs a four-step scan:
 
 1. **Scan Active Specs** — lists all directories under `docs/specs/` (excluding `archive/`)
 2. **Determine Phase & Progress** — for each spec, identifies current phase (PROPOSE → SPECIFY → EXECUTE → TEST → VALIDATE → ARCHIVE), task progress, last action, and blockers
-3. **Present Dashboard** — shows a visual dashboard with progress bars and status for each active spec
+3. **Present Dashboard** — shows a visual dashboard with progress bars and status for each active spec; if `docs/specs/kaizen-log.md` exists, appends a Kaizen footer line with the active-lesson count and the latest lesson (read from the `## Active Lessons` digest only)
 4. **Recommend Next Command** — suggests the next command based on current phase
 
 ## Output

package/docs/commands/akili-specify.md

@@ -32,6 +32,7 @@ Reads context from:
 - `docs/ux-ui/design.md`
 - `docs/trd/trd.md`
 - related specs under `docs/specs/`
+- `docs/specs/kaizen-log.md` when present — only the `## Active Lessons` digest; relevant lessons are applied and cited by ID in design decisions
 - root and package-level agent guidance files
 
 ## Outputs

package/docs/flow.md

@@ -54,7 +54,7 @@ You: /akili-validate changes/add-remember-me
 AI:  Creates validation-report.md with PASS/WARN/FAIL/BLOCKED findings
 
 You: /akili-archive changes/add-remember-me
-AI:  Moves completed work into docs/specs/archive/ and refreshes CodeGraph
+AI:  Runs the Kaizen retrospective (appends docs/specs/kaizen-log.md), moves completed work into docs/specs/archive/, and refreshes CodeGraph
 
 Independent Auditing:
 You: /akili-audit
@@ -128,6 +128,7 @@ For Legacy and Active-AKILI-SPECS modes, CodeGraph is preferred when `.codegraph
 | `docs/specs/<spec-path>/test-report.md` | `/akili-test` | Requirement-to-test matrix and coverage gaps |
 | `docs/specs/<spec-path>/validation-report.md` | `/akili-validate` | Final conformance audit |
 | `docs/specs/drift-report.md` | `/akili-audit` | Conformance auditing of documentation vs. codebase reality |
+| `docs/specs/kaizen-log.md` | `/akili-archive` | Accumulated metrics and root-cause lessons; the `## Active Lessons` digest is read by `/akili-propose`, `/akili-specify`, `/akili-execute`, and `/akili-resume` |
 | `docs/specs/archive/.../archive-summary.md` | `/akili-archive` | Historical closure record |
 
 ## Review Gates
@@ -144,7 +145,7 @@ AKILI keeps humans in control at each important transition.
 | Execution | Each completed task has verification evidence |
 | Testing | Key requirements have automated or accepted manual evidence |
 | Validation | No unresolved FAIL findings remain |
-| Archive | Warnings and follow-ups are accepted |
+| Archive | Warnings and follow-ups are accepted; Kaizen lessons are recorded and standardizations approved or deferred |
 
 ## Documentation Depth
 
@@ -307,3 +308,22 @@ OpenCode). `/akili-constitution` (Step 7C) scaffolds a `## Model Routing` copy o
 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.
+
+### 8. The Kaizen Loop
+
+AKILI embeds Kaizen — continuous improvement through small, disciplined steps — as an executable
+retrospective inside `/akili-archive`, powered by the packaged `kaizen` skill (authored by
+Juan Carlos Cadavid — jcadavid.com). Every archive runs one bounded pass:
+
+* **Measure:** hunt waste (MUDA) in the spec's own evidence — Reviewer rework attempts, pivots,
+  PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, drift.
+* **Learn:** distill 0–3 lessons, each with a named root cause and cited evidence. Generic lessons
+  are banned; a clean spec records a one-line clean-run entry instead.
+* **Standardize:** propose 1–3 line edits to constitution guides, `general-setup` templates, design
+  tokens, or `.agents/` personas. **Every edit outside the kaizen log requires human approval.**
+* **Record:** append to the accumulative `docs/specs/kaizen-log.md`. Its capped `## Active Lessons`
+  digest (10 rows max) is the only part other commands read.
+
+Lessons target either the **Product** (this project) or the **Methodology** itself — Methodology
+lessons are flagged for upstreaming to the AKILI repository, so the methodology learns from every
+tool built with it. The retrospective never blocks the archive.

package/docs/model-routing.md

@@ -65,7 +65,7 @@ the suites, and a Tester ideally runs on a different model than the Implementer
 | `/akili-test` → **Tester(s)** | T2 | Test authoring + verification per suite. Prefer a different model than the Implementer (author ≠ tester). |
 | `/akili-validate` | T3 | Deep conformance audit. |
 | `/akili-audit` | T4 + T3 | Drift detection over large context, judged critically. |
-| `/akili-archive` | T5 | Cheap, fast summarization of closed work. |
+| `/akili-archive` | T5 | Cheap, fast summarization of closed work. (Kaizen Learn sub-step: T3 optional.) |
 | `/akili-seo` | T3 + T5 | Audit findings (T3) plus setup/formatting steps (T5). |
 
 **author ≠ auditor enforcement.** In the registry, T2 (Coder) and T3 (Auditor) must resolve to

package/docs/openspec-comparison.md

@@ -27,6 +27,7 @@ This repository borrows useful documentation and workflow ideas from OpenSpec wh
 | Existing projects | Brownfield-friendly workflow | Explicit existing-project constitution mode with optional CodeGraph analysis |
 | Validation | Workflow validation through commands | Dedicated `/akili-test` and `/akili-validate` reports before archive |
 | SEO | Not a core workflow in OpenSpec | `/akili-seo` handles Google Search Console setup and audits |
+| Continuous improvement | Not a core workflow in OpenSpec | The Kaizen Loop: `/akili-archive` runs a bounded retrospective and later commands read the accumulated `## Active Lessons` digest |
 | Package target | `@fission-ai/openspec` | `akili-specs` |
 
 ## Practical Takeaway

package/docs/skills/README.md

@@ -22,6 +22,7 @@ The installable source files live in `.claude/skills/*/SKILL.md`. These pages ar
 | [`gsap-scrolltrigger`](gsap-scrolltrigger.md) | Scroll-driven animation, pinning, scrub, parallax | `/akili-specify`, `/akili-execute` |
 | [`gsap-timeline`](gsap-timeline.md) | Sequenced animations and playback control | `/akili-specify`, `/akili-execute` |
 | [`gsap-utils`](gsap-utils.md) | GSAP utilities such as clamp, mapRange, random, snap, wrap | `/akili-execute` |
+| [`kaizen`](kaizen.md) | Bounded continuous-improvement retrospective (Measure → Learn → Standardize → Record); authored by Juan Carlos Cadavid — jcadavid.com | `/akili-archive` |
 | [`nestjs-expert`](nestjs-expert.md) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
 | [`product-manager-toolkit`](product-manager-toolkit.md) | Product discovery, PRDs, prioritization, customer interview analysis | `/akili-constitution`, `/akili-propose`, `/akili-specify` |
 | [`react-doctor`](react-doctor.md) | React diagnostics after changes | `/akili-test`, `/akili-validate` |

package/docs/skills/kaizen.md

@@ -0,0 +1,30 @@
+# `kaizen`
+
+**Author:** Juan Carlos Cadavid — [jcadavid.com](https://jcadavid.com)
+
+## Purpose
+
+Turns the Japanese Kaizen philosophy of continuous improvement into an executable, bounded retrospective: **Measure → Learn → Standardize → Record**. Every archived spec leaves the project — and the methodology itself — slightly better than it found them. Inspired by the Kaizen Institute glossary (kaizen.com), Robert Maurer's small-steps method, and INTI's *Emprendiendo Kaizen* (2019).
+
+## Use When
+
+- `/akili-archive` reaches its **Kaizen Retrospective** step (the primary, automatic trigger).
+- The user explicitly requests a kaizen retrospective or continuous-improvement pass over a spec or project.
+
+## Core Rules
+
+- **Measure** hunts MUDA (waste) in the spec's own evidence: Reviewer rework attempts, pivots, PRODUCT_BUGs, severe judgment-day findings, validation WARN/FAIL, quick escalations, drift.
+- **Learn** distills 0–3 lessons; each names a root cause (5W1H) and cites evidence (Gemba: real facts, never speculation). Generic lessons are banned; prefer zero over filler. Lessons target the **Product** or the **Methodology** (flagged for upstreaming to the AKILI repo).
+- **Standardize** proposes one minimal edit (1–3 lines) per lesson to the most durable home; every edit outside the kaizen log requires human approval via a numbered menu.
+- **Record** appends to the accumulative `docs/specs/kaizen-log.md`; the `## Active Lessons` digest is capped at 10 rows and institutionalized lessons are retired.
+- The retrospective **never blocks the archive** — missing inputs or a declined menu produce a metrics-only or clean-run entry.
+
+## Best Paired Commands
+
+- `/akili-archive` — runs the retrospective automatically as its Kaizen Retrospective step.
+- `/akili-propose`, `/akili-specify`, `/akili-execute` — read the `## Active Lessons` digest so past mistakes shape new work.
+- `/akili-resume` — shows the active-lesson count in the dashboard.
+
+## Source
+
+- `../../.claude/skills/kaizen/SKILL.md`

package/package.json

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