bmad-plus 0.7.5 → 0.8.0

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"
+```

package/src/bmad-plus/packs/pack-memory/templates/context.md

@@ -1,39 +1,39 @@
----
-title: Project Context
-description: Living state of this project — auto-updated by agents
-created: "{{date}}"
-project: "{{project_name}}"
-last_updated: "{{date}}"
----
-
-# Project Context
-
-> This file is the **living state** of the project. It is read by agents at session start and updated at session end.
-
-## Project Identity
-
-- **Name**: {{project_name}}
-- **Path**: {{project_path}}
-- **Stack**: (to be detected or filled by user)
-- **Status**: active
-- **Created**: {{date}}
-
-## Current Focus
-
-<!-- What matters right now -->
-
-## Recent Changes
-
-<!-- Last 5 significant changes, most recent first -->
-
-## Architecture Notes
-
-<!-- Key architectural decisions and constraints -->
-
-## Known Issues
-
-<!-- Active bugs or tech debt to be aware of -->
-
-## Open Questions
-
-<!-- Things that need human decision -->
+---
+title: Project Context
+description: Living state of this project — auto-updated by agents
+created: "{{date}}"
+project: "{{project_name}}"
+last_updated: "{{date}}"
+---
+
+# Project Context
+
+> This file is the **living state** of the project. It is read by agents at session start and updated at session end.
+
+## Project Identity
+
+- **Name**: {{project_name}}
+- **Path**: {{project_path}}
+- **Stack**: (to be detected or filled by user)
+- **Status**: active
+- **Created**: {{date}}
+
+## Current Focus
+
+<!-- What matters right now -->
+
+## Recent Changes
+
+<!-- Last 5 significant changes, most recent first -->
+
+## Architecture Notes
+
+<!-- Key architectural decisions and constraints -->
+
+## Known Issues
+
+<!-- Active bugs or tech debt to be aware of -->
+
+## Open Questions
+
+<!-- Things that need human decision -->

package/src/bmad-plus/packs/pack-memory/templates/decisions.md

@@ -1,25 +1,25 @@
----
-title: Decisions
-description: ADR-style log of architectural and strategic decisions
-created: "{{date}}"
-project: "{{project_name}}"
----
-
-# Decisions
-
-Architectural and strategic decisions for this project. One entry per decision, short and actionable.
-
-## Format
-
-```
-### YYYY-MM-DD — <short title>
-- **Context**: why the decision was needed
-- **Decision**: what was chosen
-- **Rationale**: why
-- **Consequences**: what this unlocks / forecloses
-- **Status**: active / superseded / rolled-back
-```
-
----
-
-<!-- Decisions will be appended below by BMAD+ agents -->
+---
+title: Decisions
+description: ADR-style log of architectural and strategic decisions
+created: "{{date}}"
+project: "{{project_name}}"
+---
+
+# Decisions
+
+Architectural and strategic decisions for this project. One entry per decision, short and actionable.
+
+## Format
+
+```
+### YYYY-MM-DD — <short title>
+- **Context**: why the decision was needed
+- **Decision**: what was chosen
+- **Rationale**: why
+- **Consequences**: what this unlocks / forecloses
+- **Status**: active / superseded / rolled-back
+```
+
+---
+
+<!-- Decisions will be appended below by BMAD+ agents -->

package/src/bmad-plus/packs/pack-memory/templates/identity.yaml

@@ -1,39 +1,39 @@
-# BMAD+ User Identity
-# This file stores your preferences across all BMAD+ projects.
-# It is read by agents at session start to personalize their behavior.
-# Location: ~/.bmad-plus/brain/identity.yaml
-
-user_name: "{{user_name}}"
-communication_language: "{{language}}"
-created: "{{date}}"
-
-# How you prefer agents to communicate
-style:
-  verbosity: "concise"           # concise | detailed | minimal
-  code_comments: "essential"     # essential | verbose | none
-  explain_level: "expert"        # beginner | intermediate | expert
-
-# Your default tech preferences
-stack:
-  # Agents will prefer these unless project-specific overrides exist
-  # Fill in as you work — agents will suggest additions
-  # Example:
-  # frontend: "Next.js 15"
-  # backend: "Node.js + Express"
-  # database: "PostgreSQL"
-  # hosting: "Hetzner VPS"
-
-# Known AI tools in your environment
-ai_tools: []
-  # - claude-code
-  # - antigravity
-  # - cursor
-  # - codex-cli
-
-# Anti-regression rules (agents MUST follow)
-rules:
-  - "Never rewrite entire files — surgical edits only"
-  - "Never delete existing code without explicit approval"
-  - "Always read existing file before modifying"
-  - "Dates in ISO 8601 (YYYY-MM-DD), never relative"
-  - "Never commit without explicit permission"
+# BMAD+ User Identity
+# This file stores your preferences across all BMAD+ projects.
+# It is read by agents at session start to personalize their behavior.
+# Location: ~/.bmad-plus/brain/identity.yaml
+
+user_name: "{{user_name}}"
+communication_language: "{{language}}"
+created: "{{date}}"
+
+# How you prefer agents to communicate
+style:
+  verbosity: "concise"           # concise | detailed | minimal
+  code_comments: "essential"     # essential | verbose | none
+  explain_level: "expert"        # beginner | intermediate | expert
+
+# Your default tech preferences
+stack:
+  # Agents will prefer these unless project-specific overrides exist
+  # Fill in as you work — agents will suggest additions
+  # Example:
+  # frontend: "Next.js 15"
+  # backend: "Node.js + Express"
+  # database: "PostgreSQL"
+  # hosting: "Hetzner VPS"
+
+# Known AI tools in your environment
+ai_tools: []
+  # - claude-code
+  # - antigravity
+  # - cursor
+  # - codex-cli
+
+# Anti-regression rules (agents MUST follow)
+rules:
+  - "Never rewrite entire files — surgical edits only"
+  - "Never delete existing code without explicit approval"
+  - "Always read existing file before modifying"
+  - "Dates in ISO 8601 (YYYY-MM-DD), never relative"
+  - "Never commit without explicit permission"