bmad-plus 0.8.0 → 0.9.1

package/src/bmad-plus/packs/pack-memory/memory-orchestrator.md

@@ -1,79 +1,79 @@
-# Pack Memory — Orchestrator
-
-> Manages the persistent memory system for BMAD+ projects.
-
-## Overview
-
-Pack Memory provides a two-level persistent brain for BMAD+:
-- **Project memory** (`.agents/memory/`) — decisions, lessons, patterns specific to one project
-- **Global brain** (`~/.bmad-plus/brain/`) — cross-project knowledge that grows over time
-
-## Agent
-
-| Agent | Hebrew | Role |
-|-------|--------|------|
-| **Zecher** | זכר (remembrance) | Memory archivist — consolidation, scanning, recall |
-
-## Activation
-
-Pack Memory activates automatically when installed:
-- At session start: agents load project memory + global identity
-- During session: agents write decisions/lessons/patterns on trigger
-- At session end: session handoff is persisted
-
-Manual activation via Zecher:
-- `"Zecher, scan projects in D:\travail\DEV"` — discover and index all projects
-- `"Zecher, consolidate memory"` — deduplicate, archive stale, promote
-- `"Zecher, where were we?"` — reconstruct context from last session
-- `"Zecher, health check"` — verify memory integrity
-
-## Memory Protocol
-
-See `shared/memory-protocol.md` for the complete read/write protocol.
-
-## Behavioral Guardrails
-
-See `shared/karpathy-guardrails.md` for the 4 Karpathy principles with memory integration.
-
-## Files
-
-```
-pack-memory/
-├── README.md                           ← You are here
-├── memory-orchestrator.md              ← This file
-├── zecher-agent.md                     ← Memory Agent (Zecher)
-├── shared/
-│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory hooks
-│   └── memory-protocol.md             ← Complete read/write protocol
-└── templates/
-    ├── decisions.md                    ← ADR template
-    ├── lessons.md                      ← Lessons template
-    ├── patterns.md                     ← Patterns template
-    ├── context.md                      ← Living project context
-    ├── session-handoff.md              ← Session handoff template
-    └── identity.yaml                   ← User preferences (global brain)
-```
-
-## Cohabitation Warning
-
-> ⚠️ If you have an existing brain directory (`_brain/`, `~/.claude/memory/`, etc.),
-> BMAD+ will detect it and **link to it** instead of creating a duplicate.
-> Your existing memory will NOT be overwritten.
-
-## Installation Behavior
-
-When Pack Memory is selected during `npx bmad-plus install`:
-
-1. **Brain detection** — Scans for existing brain directories
-2. **Project memory** — Creates `.agents/memory/` with templates
-3. **Global brain** — Creates `~/.bmad-plus/brain/` if it doesn't exist
-4. **Identity setup** — Generates `identity.yaml` from user's install answers
-5. **Guardrails injection** — Makes `karpathy-guardrails.md` available to all agents
-
-## CLI Commands (planned)
-
-```
-npx bmad-plus scan [path]      — Scan and index projects interactively
-npx bmad-plus memory status    — Show memory health report
-npx bmad-plus memory export    — Export brain as portable archive
-```
+# Pack Memory — Orchestrator
+
+> Manages the persistent memory system for BMAD+ projects.
+
+## Overview
+
+Pack Memory provides a two-level persistent brain for BMAD+:
+- **Project memory** (`.agents/memory/`) — decisions, lessons, patterns specific to one project
+- **Global brain** (`~/.bmad-plus/brain/`) — cross-project knowledge that grows over time
+
+## Agent
+
+| Agent | Hebrew | Role |
+|-------|--------|------|
+| **Zecher** | זכר (remembrance) | Memory archivist — consolidation, scanning, recall |
+
+## Activation
+
+Pack Memory activates automatically when installed:
+- At session start: agents load project memory + global identity
+- During session: agents write decisions/lessons/patterns on trigger
+- At session end: session handoff is persisted
+
+Manual activation via Zecher:
+- `"Zecher, scan projects in D:\travail\DEV"` — discover and index all projects
+- `"Zecher, consolidate memory"` — deduplicate, archive stale, promote
+- `"Zecher, where were we?"` — reconstruct context from last session
+- `"Zecher, health check"` — verify memory integrity
+
+## Memory Protocol
+
+See `shared/memory-protocol.md` for the complete read/write protocol.
+
+## Behavioral Guardrails
+
+See `shared/karpathy-guardrails.md` for the 4 Karpathy principles with memory integration.
+
+## Files
+
+```
+pack-memory/
+├── README.md                           ← You are here
+├── memory-orchestrator.md              ← This file
+├── zecher-agent.md                     ← Memory Agent (Zecher)
+├── shared/
+│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory hooks
+│   └── memory-protocol.md             ← Complete read/write protocol
+└── templates/
+    ├── decisions.md                    ← ADR template
+    ├── lessons.md                      ← Lessons template
+    ├── patterns.md                     ← Patterns template
+    ├── context.md                      ← Living project context
+    ├── session-handoff.md              ← Session handoff template
+    └── identity.yaml                   ← User preferences (global brain)
+```
+
+## Cohabitation Warning
+
+> ⚠️ If you have an existing brain directory (`_brain/`, `~/.claude/memory/`, etc.),
+> BMAD+ will detect it and **link to it** instead of creating a duplicate.
+> Your existing memory will NOT be overwritten.
+
+## Installation Behavior
+
+When Pack Memory is selected during `npx bmad-plus install`:
+
+1. **Brain detection** — Scans for existing brain directories
+2. **Project memory** — Creates `.agents/memory/` with templates
+3. **Global brain** — Creates `~/.bmad-plus/brain/` if it doesn't exist
+4. **Identity setup** — Generates `identity.yaml` from user's install answers
+5. **Guardrails injection** — Makes `karpathy-guardrails.md` available to all agents
+
+## CLI Commands (planned)
+
+```
+npx bmad-plus scan [path]      — Scan and index projects interactively
+npx bmad-plus memory status    — Show memory health report
+npx bmad-plus memory export    — Export brain as portable archive
+```

package/src/bmad-plus/packs/pack-memory/shared/karpathy-guardrails.md

@@ -1,86 +1,86 @@
-# Karpathy Guardrails — BMAD+ Agent Behavioral Guidelines
-
-> Adapted from [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (132K ⭐, MIT License)
-> Enhanced with BMAD+ memory integration
-
----
-
-## G1 — Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, **ask**.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-- **Check `.agents/memory/decisions.md`** for prior decisions on this topic before deciding again.
-- **Check `.agents/memory/lessons.md`** for known pitfalls before proceeding.
-
-## G2 — Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-- **Check `.agents/memory/patterns.md`** — a pattern that already solved this might exist.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-## G3 — Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-**Memory integration**: If you discover something surprising, **log it immediately** in `.agents/memory/lessons.md`.
-
-## G4 — Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-**Memory integration**: Log non-obvious architectural decisions in `.agents/memory/decisions.md` with rationale.
-
----
-
-## When These Guidelines Are Working
-
-- Fewer unnecessary changes in diffs — only requested changes appear
-- Fewer rewrites due to overcomplication — code is simple the first time
-- Clarifying questions come BEFORE implementation — not after mistakes
-- Clean, minimal PRs — no drive-by refactoring or "improvements"
-- **Persistent learning** — the same mistake never happens twice because it's in lessons.md
-
----
-
-## Attribution
-
-Behavioral principles by [Andrej Karpathy](https://x.com/karpathy) via [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License).
-Memory integration by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).
+# Karpathy Guardrails — BMAD+ Agent Behavioral Guidelines
+
+> Adapted from [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (132K ⭐, MIT License)
+> Enhanced with BMAD+ memory integration
+
+---
+
+## G1 — Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, **ask**.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- **Check `.agents/memory/decisions.md`** for prior decisions on this topic before deciding again.
+- **Check `.agents/memory/lessons.md`** for known pitfalls before proceeding.
+
+## G2 — Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+- **Check `.agents/memory/patterns.md`** — a pattern that already solved this might exist.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## G3 — Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+**Memory integration**: If you discover something surprising, **log it immediately** in `.agents/memory/lessons.md`.
+
+## G4 — Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**Memory integration**: Log non-obvious architectural decisions in `.agents/memory/decisions.md` with rationale.
+
+---
+
+## When These Guidelines Are Working
+
+- Fewer unnecessary changes in diffs — only requested changes appear
+- Fewer rewrites due to overcomplication — code is simple the first time
+- Clarifying questions come BEFORE implementation — not after mistakes
+- Clean, minimal PRs — no drive-by refactoring or "improvements"
+- **Persistent learning** — the same mistake never happens twice because it's in lessons.md
+
+---
+
+## Attribution
+
+Behavioral principles by [Andrej Karpathy](https://x.com/karpathy) via [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License).
+Memory integration by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).

package/src/bmad-plus/packs/pack-memory/shared/memory-protocol.md

@@ -1,143 +1,143 @@
-# Memory Protocol — When and How Agents Use Memory
-
-> This protocol defines when BMAD+ agents should read from and write to the persistent memory system.
-
----
-
-## Memory Locations
-
-### Project Memory (per-project)
-```
-<project>/.agents/memory/
-├── decisions.md        ← Architectural decisions for THIS project
-├── lessons.md          ← Mistakes and surprises in THIS project
-├── patterns.md         ← Validated patterns in THIS project
-├── context.md          ← Living state (auto-updated)
-└── sessions/           ← Session handoffs
-    └── YYYY-MM-DD-<topic>.md
-```
-
-### Global Brain (cross-project)
-```
-~/.bmad-plus/brain/
-├── identity.yaml       ← User preferences (stack, style, rules)
-├── decisions.md        ← Cross-project decisions
-├── lessons.md          ← Cross-project lessons
-├── patterns.md         ← Reusable patterns
-├── stack-preferences.md ← Default tech choices
-└── projects/           ← Index of all BMAD+ projects
-    └── <hash>.yaml     ← Per-project metadata
-```
-
----
-
-## Protocol: Session Start (READ)
-
-Every agent MUST perform this sequence at the start of a meaningful session:
-
-1. **Read `identity.yaml`** (global) — Know the user's preferences
-2. **Read `context.md`** (project) — Understand current state
-3. **Read `decisions.md`** (project) — Don't re-decide what's already decided
-4. **Read `lessons.md`** (project) — Don't repeat known mistakes
-5. **Optionally read latest `sessions/`** — If resuming work
-
-> If a file doesn't exist, skip it silently. Memory is always optional.
-
----
-
-## Protocol: During Session (WRITE on trigger)
-
-### Trigger → decisions.md
-**When**: A non-obvious architectural or strategic choice is made.
-**What**: ADR-style entry (Context, Decision, Rationale, Consequences, Status).
-**Rule**: If you'd explain "why" to a colleague, it's a decision worth logging.
-
-### Trigger → lessons.md
-**When**: Something unexpected happens, a bug is caused by a non-obvious issue, or an assumption proved wrong.
-**What**: Context, Impact, Lesson (the rule to follow next time).
-**Rule**: Log IMMEDIATELY — don't wait for session end.
-
-### Trigger → patterns.md
-**When**: A solution works well and could be reused in other contexts.
-**What**: Problem, Shape, Trade-off, Status (candidate → validated).
-**Rule**: Only promote to global patterns.md if used in 2+ projects.
-
-### Trigger → context.md
-**When**: The project state changes meaningfully (new module, stack change, architecture shift).
-**What**: Update the relevant section.
-**Rule**: Keep it concise — this file should be readable in 30 seconds.
-
----
-
-## Protocol: Session End (PERSIST)
-
-If meaningful work was done:
-
-1. **Write session handoff** → `sessions/YYYY-MM-DD-<topic>.md`
-2. **Update `context.md`** → Reflect new reality
-3. **Review pending lessons** → Any surprise worth logging?
-4. **Cross-project check** → Any lesson/pattern that applies to ALL projects? → Copy to global brain.
-
----
-
-## The Golden Rule
-
-> **If info applies to 1 project → project memory. If 2+ projects → global brain.**
-
----
-
-## Merge Safety
-
-When reinstalling BMAD+ or updating:
-- **NEVER overwrite** decisions.md, lessons.md, patterns.md
-- **NEVER delete** sessions/ directory
-- **Safe to overwrite**: context.md template (user regenerates), identity.yaml template only if no user edits
-- **Install manifest** (`.bmad-plus-install.json`) tracks what was installed, brain detection prevents overwrites
-
----
-
-## Project Scanner Protocol
-
-The `bmad-plus scan` command follows this protocol:
-
-1. **Scan** target directory recursively for project markers (package.json, Cargo.toml, .git, etc.)
-2. **Analyze** each discovered project (detect stack, status, last modified)
-3. **Present** findings to user in interactive table
-4. **User validates** each project (confirm, skip, edit metadata)
-5. **Index** validated projects in `~/.bmad-plus/brain/projects/<hash>.yaml`
-6. **Generate** project-level memory stubs if requested
-
-### Project Detection Markers (priority order)
-```
-package.json          → Node.js / JavaScript
-Cargo.toml            → Rust
-requirements.txt      → Python
-pyproject.toml        → Python
-go.mod                → Go
-composer.json         → PHP
-Gemfile               → Ruby
-*.sln / *.csproj      → .NET
-pom.xml               → Java
-build.gradle          → Java/Kotlin
-.git                  → Any (version controlled)
-AGENTS.md             → Already agent-aware
-.agents/              → Already BMAD+ installed
-```
-
-### Project Metadata (per scan)
-```yaml
-# ~/.bmad-plus/brain/projects/<hash>.yaml
-path: "D:\\travail\\DEV\\my-project"
-name: "my-project"
-hash: "a1b2c3d4"  # SHA256 of absolute path
-stack:
-  primary: "Node.js"
-  framework: "Next.js 15"
-  database: "PostgreSQL"
-status: "active"          # active / paused / archived / unknown
-last_modified: "2026-05-17"
-last_scanned: "2026-05-17"
-bmad_installed: true
-packs_installed: ["core", "memory", "dev-studio"]
-notes: "CRM client project"
-```
+# Memory Protocol — When and How Agents Use Memory
+
+> This protocol defines when BMAD+ agents should read from and write to the persistent memory system.
+
+---
+
+## Memory Locations
+
+### Project Memory (per-project)
+```
+<project>/.agents/memory/
+├── decisions.md        ← Architectural decisions for THIS project
+├── lessons.md          ← Mistakes and surprises in THIS project
+├── patterns.md         ← Validated patterns in THIS project
+├── context.md          ← Living state (auto-updated)
+└── sessions/           ← Session handoffs
+    └── YYYY-MM-DD-<topic>.md
+```
+
+### Global Brain (cross-project)
+```
+~/.bmad-plus/brain/
+├── identity.yaml       ← User preferences (stack, style, rules)
+├── decisions.md        ← Cross-project decisions
+├── lessons.md          ← Cross-project lessons
+├── patterns.md         ← Reusable patterns
+├── stack-preferences.md ← Default tech choices
+└── projects/           ← Index of all BMAD+ projects
+    └── <hash>.yaml     ← Per-project metadata
+```
+
+---
+
+## Protocol: Session Start (READ)
+
+Every agent MUST perform this sequence at the start of a meaningful session:
+
+1. **Read `identity.yaml`** (global) — Know the user's preferences
+2. **Read `context.md`** (project) — Understand current state
+3. **Read `decisions.md`** (project) — Don't re-decide what's already decided
+4. **Read `lessons.md`** (project) — Don't repeat known mistakes
+5. **Optionally read latest `sessions/`** — If resuming work
+
+> If a file doesn't exist, skip it silently. Memory is always optional.
+
+---
+
+## Protocol: During Session (WRITE on trigger)
+
+### Trigger → decisions.md
+**When**: A non-obvious architectural or strategic choice is made.
+**What**: ADR-style entry (Context, Decision, Rationale, Consequences, Status).
+**Rule**: If you'd explain "why" to a colleague, it's a decision worth logging.
+
+### Trigger → lessons.md
+**When**: Something unexpected happens, a bug is caused by a non-obvious issue, or an assumption proved wrong.
+**What**: Context, Impact, Lesson (the rule to follow next time).
+**Rule**: Log IMMEDIATELY — don't wait for session end.
+
+### Trigger → patterns.md
+**When**: A solution works well and could be reused in other contexts.
+**What**: Problem, Shape, Trade-off, Status (candidate → validated).
+**Rule**: Only promote to global patterns.md if used in 2+ projects.
+
+### Trigger → context.md
+**When**: The project state changes meaningfully (new module, stack change, architecture shift).
+**What**: Update the relevant section.
+**Rule**: Keep it concise — this file should be readable in 30 seconds.
+
+---
+
+## Protocol: Session End (PERSIST)
+
+If meaningful work was done:
+
+1. **Write session handoff** → `sessions/YYYY-MM-DD-<topic>.md`
+2. **Update `context.md`** → Reflect new reality
+3. **Review pending lessons** → Any surprise worth logging?
+4. **Cross-project check** → Any lesson/pattern that applies to ALL projects? → Copy to global brain.
+
+---
+
+## The Golden Rule
+
+> **If info applies to 1 project → project memory. If 2+ projects → global brain.**
+
+---
+
+## Merge Safety
+
+When reinstalling BMAD+ or updating:
+- **NEVER overwrite** decisions.md, lessons.md, patterns.md
+- **NEVER delete** sessions/ directory
+- **Safe to overwrite**: context.md template (user regenerates), identity.yaml template only if no user edits
+- **Install manifest** (`.bmad-plus-install.json`) tracks what was installed, brain detection prevents overwrites
+
+---
+
+## Project Scanner Protocol
+
+The `bmad-plus scan` command follows this protocol:
+
+1. **Scan** target directory recursively for project markers (package.json, Cargo.toml, .git, etc.)
+2. **Analyze** each discovered project (detect stack, status, last modified)
+3. **Present** findings to user in interactive table
+4. **User validates** each project (confirm, skip, edit metadata)
+5. **Index** validated projects in `~/.bmad-plus/brain/projects/<hash>.yaml`
+6. **Generate** project-level memory stubs if requested
+
+### Project Detection Markers (priority order)
+```
+package.json          → Node.js / JavaScript
+Cargo.toml            → Rust
+requirements.txt      → Python
+pyproject.toml        → Python
+go.mod                → Go
+composer.json         → PHP
+Gemfile               → Ruby
+*.sln / *.csproj      → .NET
+pom.xml               → Java
+build.gradle          → Java/Kotlin
+.git                  → Any (version controlled)
+AGENTS.md             → Already agent-aware
+.agents/              → Already BMAD+ installed
+```
+
+### Project Metadata (per scan)
+```yaml
+# ~/.bmad-plus/brain/projects/<hash>.yaml
+path: "D:\\travail\\DEV\\my-project"
+name: "my-project"
+hash: "a1b2c3d4"  # SHA256 of absolute path
+stack:
+  primary: "Node.js"
+  framework: "Next.js 15"
+  database: "PostgreSQL"
+status: "active"          # active / paused / archived / unknown
+last_modified: "2026-05-17"
+last_scanned: "2026-05-17"
+bmad_installed: true
+packs_installed: ["core", "memory", "dev-studio"]
+notes: "CRM client project"
+```