bmad-plus 0.5.0 → 0.7.0

package/src/bmad-plus/packs/pack-dev-studio/shared/bwml-spec.md

@@ -0,0 +1,328 @@
+# BMAD+ Workflow Markup Language (BWML) — Specification v1.0
+
+> **Pack:** Dev Studio
+> **Purpose:** Define the BMAD+ proprietary workflow DSL that surpasses BMAD-METHOD v6 XML format
+> **Created by:** Laurent Rochetta — https://github.com/lrochetta/BMAD-PLUS
+> **License:** MIT
+
+---
+
+## Overview
+
+BWML (BMAD+ Workflow Markup Language) is an XML-based DSL optimized for LLM execution. It extends the concepts from BMAD-METHOD v6 with advanced orchestration primitives: multi-agent delegation, parallel execution, validation gates, memory persistence, anti-regression guards, and structured artifact emission.
+
+LLMs parse XML natively and reliably. BWML leverages this with semantically meaningful tags that guide deterministic execution while preserving LLM reasoning flexibility.
+
+---
+
+## Core Elements (inherited from BMAD v6, enhanced)
+
+### `<workflow>` — Root container
+```xml
+<workflow id="dev-story" version="1.0" agent="oholiab">
+  <!-- All steps live here -->
+</workflow>
+```
+
+### `<phase>` — Named execution phase (NEW)
+Groups steps into logical phases with optional gating.
+```xml
+<phase name="analysis" gate="required">
+  <step>...</step>
+  <step>...</step>
+</phase>
+```
+- `gate="required"` — Must complete before next phase
+- `gate="optional"` — Can be skipped
+
+### `<step>` — Numbered execution step
+```xml
+<step n="1" goal="Load project context" tag="init">
+  <action>...</action>
+</step>
+```
+
+### `<action>` — Single action to execute
+```xml
+<action>Read the complete story file</action>
+<action if="no stories found">HALT: inform user</action>
+```
+
+### `<check>` — Conditional branch
+```xml
+<check if="sprint_status file exists">
+  <action>Load sprint data</action>
+</check>
+```
+
+### `<critical>` — Must-follow rule (violation = HALT)
+```xml
+<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
+```
+
+### `<output>` — Formatted user-facing output
+```xml
+<output>✅ **Context Loaded** — Story and project context ready</output>
+```
+
+### `<ask>` — Prompt user for input
+```xml
+<ask>Which story would you like to develop?</ask>
+```
+
+### `<goto>` — Jump to step or anchor
+```xml
+<goto step="9">Completion sequence</goto>
+<goto anchor="task_check" />
+```
+
+### `<anchor>` — Jump target
+```xml
+<anchor id="task_check" />
+```
+
+---
+
+## BMAD+ Extensions (NEW — our competitive advantage)
+
+### `<agent>` — Invoke another BMAD+ agent inline
+Enables cross-agent orchestration without leaving the workflow.
+```xml
+<agent name="bezalel" task="Review this architecture decision">
+  <context>Current PRD and technical constraints</context>
+  <expect>Architecture recommendation with trade-offs</expect>
+</agent>
+```
+- `name` — BMAD+ agent to invoke (Torah personas or pack agents)
+- `task` — What to ask the agent
+- `<context>` — What context to pass
+- `<expect>` — Expected output format
+
+### `<parallel>` — Execute multiple actions concurrently
+```xml
+<parallel>
+  <action>Run unit tests</action>
+  <action>Run linting checks</action>
+  <action>Validate acceptance criteria</action>
+</parallel>
+```
+
+### `<loop>` — Iterative execution with break conditions
+```xml
+<loop over="incomplete_tasks" as="task">
+  <action>Implement {{task}}</action>
+  <action>Run tests for {{task}}</action>
+  <validate>All tests pass for {{task}}</validate>
+  <action>Mark {{task}} complete</action>
+  <break if="HALT condition triggered" />
+</loop>
+```
+
+### `<validate>` — Built-in validation gate with pass/fail
+```xml
+<validate id="dod-check" severity="blocking">
+  <criterion>All tasks marked [x]</criterion>
+  <criterion>All acceptance criteria satisfied</criterion>
+  <criterion>Full test suite passes with 0 failures</criterion>
+  <criterion>No regressions detected</criterion>
+  <on-fail>HALT — Do NOT proceed until all criteria pass</on-fail>
+  <on-pass>Continue to next step</on-pass>
+</validate>
+```
+
+### `<guard>` — Anti-regression protection
+Prevents common AI mistakes explicitly.
+```xml
+<guard type="anti-regression">
+  Never delete existing code without explicit user approval
+</guard>
+<guard type="scope">
+  Only modify files listed in the story spec
+</guard>
+<guard type="quality">
+  Never mark a task complete without running tests
+</guard>
+```
+
+### `<emit>` — Produce structured artifacts
+```xml
+<emit type="story-status" format="yaml">
+  story_key: {{story_key}}
+  status: review
+  completed_tasks: {{completed_count}}
+  date: {{date}}
+</emit>
+```
+- `type` — Artifact type (story-status, report, checklist, etc.)
+- `format` — Output format (yaml, markdown, json)
+
+### `<context>` — Load external context
+```xml
+<context source="file" path="**/project-context.md" />
+<context source="file" path="architecture.md" optional="true" />
+<context source="memory" key="last-sprint-decisions" />
+```
+
+### `<memory>` — Persist/recall across sessions
+```xml
+<memory action="store" key="sprint-velocity" value="{{calculated_velocity}}" />
+<memory action="recall" key="last-review-findings" />
+```
+
+### `<escalate>` — Escalation to human or higher agent
+```xml
+<escalate to="user" severity="high">
+  Architecture decision required: monolith vs microservices.
+  Trade-offs documented in {{arch_doc_path}}.
+</escalate>
+<escalate to="bezalel" severity="medium">
+  Implementation diverges from architecture — review needed.
+</escalate>
+```
+
+### `<retry>` — Auto-retry with limits
+```xml
+<retry max="3" backoff="progressive">
+  <action>Run failing test suite</action>
+  <action>Fix identified issues</action>
+  <on-exhaust>HALT — 3 consecutive failures, request human guidance</on-exhaust>
+</retry>
+```
+
+### `<fallback>` — Graceful degradation
+```xml
+<fallback>
+  <try>
+    <agent name="miriam" task="Analyze market data" />
+  </try>
+  <catch>
+    <action>Perform analysis directly using available context</action>
+  </catch>
+</fallback>
+```
+
+### `<metric>` — Track quantitative progress
+```xml
+<metric name="test-coverage" target="80%" current="{{coverage}}" />
+<metric name="tasks-completed" value="{{done}}/{{total}}" />
+```
+
+---
+
+## Composition Example
+
+```xml
+<workflow id="dev-story" version="1.0" agent="oholiab">
+  <critical>Execute ALL steps in exact order; do NOT skip</critical>
+  <critical>Never stop for "milestones" or "session boundaries"</critical>
+  
+  <guard type="anti-regression">
+    Never delete existing functionality without explicit approval
+  </guard>
+  <guard type="scope">
+    Only modify files specified in the story tasks
+  </guard>
+
+  <phase name="initialization" gate="required">
+    <step n="1" goal="Find and load story">
+      <context source="file" path="sprint-status.yaml" optional="true" />
+      <check if="story_path provided">
+        <action>Load story file directly</action>
+        <goto anchor="implementation" />
+      </check>
+      <check if="sprint status exists">
+        <action>Find first ready-for-dev story</action>
+      </check>
+      <escalate to="user" if="no ready stories found">
+        No stories available. Options: create-story, validate existing, or specify path.
+      </escalate>
+    </step>
+  </phase>
+
+  <phase name="implementation" gate="required">
+    <anchor id="implementation" />
+    <loop over="incomplete_tasks" as="task">
+      <step goal="Implement {{task}} following TDD">
+        <!-- RED -->
+        <action>Write FAILING tests first</action>
+        <validate severity="info">Tests fail as expected</validate>
+        
+        <!-- GREEN -->
+        <action>Implement MINIMAL code to pass tests</action>
+        <validate severity="blocking">All tests pass</validate>
+        
+        <!-- REFACTOR -->
+        <action>Improve code structure, keep tests green</action>
+        <validate severity="blocking">No regressions after refactor</validate>
+        
+        <action>Mark {{task}} [x] in story file</action>
+        <metric name="tasks-completed" value="{{done}}/{{total}}" />
+      </step>
+      
+      <retry max="3">
+        <action>Fix any failing tests</action>
+        <on-exhaust>
+          <escalate to="user">3 consecutive failures on {{task}}</escalate>
+        </on-exhaust>
+      </retry>
+    </loop>
+  </phase>
+
+  <phase name="completion" gate="required">
+    <step goal="Story completion and review">
+      <validate id="definition-of-done" severity="blocking">
+        <criterion>All tasks marked [x]</criterion>
+        <criterion>All acceptance criteria satisfied</criterion>
+        <criterion>Full test suite passes</criterion>
+        <criterion>File list complete</criterion>
+        <criterion>Dev notes documented</criterion>
+        <on-fail>HALT — Complete remaining items</on-fail>
+      </validate>
+      
+      <emit type="story-update" format="yaml">
+        status: review
+        completed: {{date}}
+      </emit>
+      
+      <output>✅ Story {{story_key}} complete and ready for review</output>
+      
+      <escalate to="user" severity="info">
+        Recommended: run code-review with a DIFFERENT LLM
+      </escalate>
+    </step>
+  </phase>
+</workflow>
+```
+
+---
+
+## BWML vs BMAD v6 Comparison
+
+| Feature | BMAD v6 | BWML (BMAD+) |
+|---------|---------|--------------|
+| Steps & Actions | ✅ | ✅ |
+| Conditional checks | ✅ | ✅ |
+| Goto/Anchors | ✅ | ✅ |
+| Critical rules | ✅ | ✅ |
+| User prompts | ✅ | ✅ |
+| **Phases with gates** | ❌ | ✅ |
+| **Multi-agent delegation** | ❌ | ✅ `<agent>` |
+| **Parallel execution** | ❌ | ✅ `<parallel>` |
+| **Loops with break** | ❌ | ✅ `<loop>` |
+| **Validation gates** | ❌ | ✅ `<validate>` |
+| **Anti-regression guards** | ❌ | ✅ `<guard>` |
+| **Artifact emission** | ❌ | ✅ `<emit>` |
+| **Context loading** | ❌ | ✅ `<context>` |
+| **Memory persistence** | ❌ | ✅ `<memory>` |
+| **Escalation** | ❌ | ✅ `<escalate>` |
+| **Auto-retry** | ❌ | ✅ `<retry>` |
+| **Graceful fallback** | ❌ | ✅ `<fallback>` |
+| **Progress metrics** | ❌ | ✅ `<metric>` |
+| Python dependency | ✅ Required | ❌ None |
+| TOML config | ✅ Required | ❌ Self-contained |
+
+---
+
+## Attribution
+
+BWML is inspired by the workflow DSL in [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) v6.6.0 by BMad Code, LLC (MIT License). Extended with BMAD+ proprietary orchestration primitives by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).

package/src/bmad-plus/packs/pack-dev-studio/shared/module-help.csv

@@ -0,0 +1,32 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
+BMad Method,bmad-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
+BMad Method,bmad-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
+BMad Method,bmad-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
+BMad Method,bmad-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
+BMad Method,bmad-agent-tech-writer,Write Document,WD,"Describe in detail what you want, and the agent will follow documentation best practices. Multi-turn conversation with subprocess for research/review.",write,,anytime,,,false,project-knowledge,document
+BMad Method,bmad-agent-tech-writer,Update Standards,US,Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.,update-standards,,anytime,,,false,_bmad/_memory/tech-writer-sidecar,standards
+BMad Method,bmad-agent-tech-writer,Mermaid Generate,MG,Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.,mermaid,,anytime,,,false,planning_artifacts,mermaid diagram
+BMad Method,bmad-agent-tech-writer,Validate Document,VD,Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.,validate,[path],anytime,,,false,planning_artifacts,validation report
+BMad Method,bmad-agent-tech-writer,Explain Concept,EC,Create clear technical explanations with examples and diagrams for complex concepts.,explain,[topic],anytime,,,false,project_knowledge,explanation
+BMad Method,bmad-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,1-analysis,,,false,planning_artifacts,brainstorming session
+BMad Method,bmad-market-research,Market Research,MR,Market analysis competitive landscape customer needs and trends.,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
+BMad Method,bmad-domain-research,Domain Research,DR,Industry domain deep dive subject matter expertise and terminology.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
+BMad Method,bmad-technical-research,Technical Research,TR,Technical feasibility architecture options and implementation approaches.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
+BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,1-analysis,,,false,planning_artifacts,product brief
+BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,1-analysis,,,false,planning_artifacts,prfaq document
+BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
+BMad Method,bmad-create-ux-design,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
+BMad Method,bmad-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,,3-solutioning,,,true,planning_artifacts,architecture
+BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-create-architecture,,true,planning_artifacts,epics and stories
+BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report
+BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
+BMad Method,bmad-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,bmad-sprint-planning,,false,,
+BMad Method,bmad-create-story,Create Story,CS,Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.,create,,4-implementation,bmad-sprint-planning,bmad-create-story:validate,true,implementation_artifacts,story
+BMad Method,bmad-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,bmad-create-story:create,bmad-dev-story,false,implementation_artifacts,story validation report
+BMad Method,bmad-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,,4-implementation,bmad-create-story:validate,,true,,
+BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,,4-implementation,bmad-dev-story,,false,,
+BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,4-implementation,,,false,,
+BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite
+BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
+BMad Method,bmad-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report

package/src/bmad-plus/packs/pack-dev-studio/upstream-sync.yaml

@@ -0,0 +1,81 @@
+# Pack Dev Studio — upstream-sync.yaml
+# Tracks the source commit and version from BMAD-METHOD for future updates
+
+upstream:
+  repository: https://github.com/bmad-code-org/BMAD-METHOD
+  version: "6.6.0"
+  commit: "0f852a38ac7c0ac30340b3aedc3aba4505b7c14a"
+  synced_at: "2026-05-17"
+  license: MIT
+
+adaptations:
+  format: "BMAD+ BWML (Workflow Markup Language)"
+  personas:
+    Mary: Miriam (מרים)
+    Paige: Huldah (חולדה)
+    John: Yosef (יוסף)
+    Sally: Rachel (רחל)
+    Winston: Bezalel (בצלאל)
+    Amelia: Oholiab (אהליאב)
+  removed_dependencies:
+    - customize.toml (3-layer TOML config system)
+    - resolve_customization.py (Python variable resolver)
+    - resolve_config.py (Python config merger)
+    - analyze_sources.py (Python source analyzer)
+    - config.yaml (per-project config)
+  added:
+    - BWML specification (shared/bwml-spec.md)
+    - Dev Studio orchestrator
+    - Torah-inspired persona naming
+    - BMAD+ pack integration (module.yaml, CLI, i18n)
+
+source_mapping:
+  categories/analysis:
+    - src/bmm-skills/1-analysis/bmad-agent-analyst → analyst-agent.md
+    - src/bmm-skills/1-analysis/bmad-agent-tech-writer → tech-writer-agent.md
+    - src/bmm-skills/1-analysis/bmad-product-brief → product-brief.md
+    - src/bmm-skills/1-analysis/bmad-prfaq → prfaq.md
+    - src/bmm-skills/1-analysis/bmad-document-project → document-project.md
+    - src/bmm-skills/1-analysis/research/bmad-market-research → market-research.md
+    - src/bmm-skills/1-analysis/research/bmad-domain-research → domain-research.md
+    - src/bmm-skills/1-analysis/research/bmad-technical-research → technical-research.md
+  categories/planning:
+    - src/bmm-skills/2-plan-workflows/bmad-agent-pm → pm-agent.md
+    - src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer → ux-designer-agent.md
+    - src/bmm-skills/2-plan-workflows/bmad-create-prd → create-prd.md
+    - src/bmm-skills/2-plan-workflows/bmad-create-ux-design → create-ux-design.md
+    - src/bmm-skills/2-plan-workflows/bmad-edit-prd → edit-prd.md
+    - src/bmm-skills/2-plan-workflows/bmad-prd → prd.md
+    - src/bmm-skills/2-plan-workflows/bmad-validate-prd → validate-prd.md
+  categories/architecture:
+    - src/bmm-skills/3-solutioning/bmad-agent-architect → architect-agent.md
+    - src/bmm-skills/3-solutioning/bmad-create-architecture → create-architecture.md + steps/
+    - src/bmm-skills/3-solutioning/bmad-create-epics-and-stories → create-epics-stories.md
+    - src/bmm-skills/3-solutioning/bmad-check-implementation-readiness → implementation-readiness.md
+    - src/bmm-skills/3-solutioning/bmad-generate-project-context → generate-project-context.md
+  categories/implementation:
+    - src/bmm-skills/4-implementation/bmad-agent-dev → dev-agent.md
+    - src/bmm-skills/4-implementation/bmad-dev-story → dev-story.md + checklist
+    - src/bmm-skills/4-implementation/bmad-create-story → create-story.md
+    - src/bmm-skills/4-implementation/bmad-sprint-planning → sprint-planning.md
+    - src/bmm-skills/4-implementation/bmad-sprint-status → sprint-status.md
+    - src/bmm-skills/4-implementation/bmad-code-review → code-review.md + steps/
+    - src/bmm-skills/4-implementation/bmad-quick-dev → quick-dev.md
+    - src/bmm-skills/4-implementation/bmad-correct-course → correct-course.md
+    - src/bmm-skills/4-implementation/bmad-checkpoint-preview → checkpoint-preview.md
+    - src/bmm-skills/4-implementation/bmad-investigate → investigate.md
+    - src/bmm-skills/4-implementation/bmad-qa-generate-e2e-tests → qa-e2e-tests.md
+    - src/bmm-skills/4-implementation/bmad-retrospective → retrospective.md
+  categories/utilities:
+    - src/core-skills/bmad-distillator → distillator.md
+    - src/core-skills/bmad-party-mode → party-mode.md
+    - src/core-skills/bmad-brainstorming → brainstorming.md
+    - src/core-skills/bmad-editorial-review-prose → editorial-review-prose.md
+    - src/core-skills/bmad-editorial-review-structure → editorial-review-structure.md
+    - src/core-skills/bmad-review-adversarial-general → adversarial-review.md
+    - src/core-skills/bmad-review-edge-case-hunter → edge-case-hunter.md
+    - src/core-skills/bmad-advanced-elicitation → advanced-elicitation.md
+    - src/core-skills/bmad-shard-doc → shard-doc.md
+    - src/core-skills/bmad-index-docs → index-docs.md
+    - src/core-skills/bmad-help → bmad-help.md
+    - src/core-skills/bmad-customize → customize.md

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

@@ -0,0 +1,106 @@
+# Pack Memory — Persistent Brain for BMAD+
+
+> 🧠 Give your AI agents a memory that persists across sessions, projects, and time.
+
+## What is Pack Memory?
+
+Pack Memory adds a **persistent brain** to BMAD+. Every decision logged, every lesson learned, every pattern discovered — they all survive between sessions. Your agents get smarter over time.
+
+### Two Levels of Memory
+
+| Level | Location | Scope |
+|-------|----------|-------|
+| **Project Memory** | `.agents/memory/` | Decisions, lessons, patterns for ONE project |
+| **Global Brain** | `~/.bmad-plus/brain/` | Cross-project knowledge, user preferences, project index |
+
+### The Golden Rule
+
+> If info applies to **1 project** → project memory. If **2+ projects** → global brain.
+
+## Features
+
+### 🧠 Persistent Memory
+- `decisions.md` — ADR-style architectural decisions with rationale
+- `lessons.md` — Things that burned you, logged immediately, never repeated
+- `patterns.md` — Validated solutions that work, ready to reuse
+- `context.md` — Living project state, auto-updated by agents
+- `sessions/` — Session handoffs for seamless context transfer
+
+### 🔍 Project Scanner
+- Scan any directory (or entire disk) to discover projects
+- Auto-detect tech stack from project markers
+- Interactive validation — you confirm each project before indexing
+- Build a complete portfolio index in your global brain
+
+### 🛡️ Karpathy Guardrails
+Four behavioral principles (from Andrej Karpathy, 132K ⭐) woven into every agent:
+1. **Think Before Coding** — Surface assumptions, don't guess
+2. **Simplicity First** — Minimum code, nothing speculative
+3. **Surgical Changes** — Touch only what you must
+4. **Goal-Driven Execution** — Define success criteria, verify
+
+### 🤖 Zecher Agent (זכר)
+Dedicated memory agent that can:
+- Consolidate and deduplicate memory entries
+- Scan and index projects interactively
+- Reconstruct context when starting a cold session
+- Run memory health checks
+
+## Installation
+
+```bash
+npx bmad-plus install
+# Select "🧠 Memory — Persistent Brain" in the pack menu
+```
+
+### Brain Detection
+
+If you already have a brain directory (`_brain/`, `~/.claude/memory/`, etc.), BMAD+ will:
+- ✅ **Detect it** automatically
+- ✅ **Link to it** — no duplication
+- ❌ **Never overwrite** your existing memory
+
+## Quick Start
+
+After installation:
+
+```
+# Scan your projects
+"Zecher, scan projects in D:\travail\DEV"
+
+# Start remembering
+"Atlas, create a PRD for..."    ← decisions auto-logged
+"Forge, implement story S1"     ← patterns auto-detected
+
+# Recall context
+"Zecher, where were we?"        ← instant context reconstruction
+
+# Maintain memory
+"Zecher, health check"          ← verify integrity
+"Zecher, consolidate memory"    ← deduplicate & archive
+```
+
+## File Structure
+
+```
+pack-memory/
+├── README.md                     ← This file
+├── memory-orchestrator.md        ← Pack entry point
+├── zecher-agent.md               ← Memory Agent (Zecher)
+├── shared/
+│   ├── karpathy-guardrails.md    ← Behavioral guardrails
+│   └── memory-protocol.md       ← Read/write protocol
+└── templates/
+    ├── decisions.md
+    ├── lessons.md
+    ├── patterns.md
+    ├── context.md
+    ├── session-handoff.md
+    └── identity.yaml
+```
+
+## Credits
+
+- Memory architecture inspired by Laurent Rochetta's `_brain/` methodology
+- Behavioral guardrails adapted from [Andrej Karpathy](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License)
+- BMAD+ by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS)

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

@@ -0,0 +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
+```