bmad-overlay 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.1
+
+Documentation cleanup and packaging polish.
+
+Included:
+
+- simplified user-facing README
+- npm-first installation docs
+- anonymized publishable path examples
+
+## 0.1.0
+
+Initial portable release candidate.
+
+Included:
+
+- multi-mode installer
+- BMAD customization merge
+- runtime controller
+- stage runner
+- explicit BMAD agent mapping
+- Codex / Claude Code executor support with fallback

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,82 @@
+# Publishing `bmad-overlay`
+
+## Goal
+
+Maintain and validate the published npm package for `bmad-overlay`.
+
+Public command:
+
+```bash
+npx bmad-overlay --target /path/to/project --mode full --merge-bmad true
+```
+
+## Package State
+
+npm package:
+
+- `https://www.npmjs.com/package/bmad-overlay`
+
+Current package file:
+
+- `overlay/package.json`
+
+Published package name:
+
+- `bmad-overlay`
+
+Current bin entries:
+
+- `bmad-overlay`
+- `bmad-overlay-merge-bmad`
+
+## Publish Checklist
+
+1. Verify installer behavior on a clean target project.
+2. Verify `--mode codex`, `--mode claude-code`, `--mode bmad`, and `--mode full`.
+3. Verify `--merge-bmad true`.
+4. Verify generated wrapper scripts.
+5. Verify `overlay-applied/agent-map.yaml`.
+6. Verify no project-local absolute paths are embedded.
+8. Run `npm run pack:check`.
+
+## Suggested Publish Flow
+
+From `overlay/`:
+
+```bash
+npm run pack:check
+npm pack
+npm publish --access public
+```
+
+## Public Release Scope
+
+The public release should promise:
+
+- portable overlay install
+- explicit setup modes
+- BMAD customization merge
+- runtime and stage runner included
+
+It should not promise:
+
+- fully networked worker execution in every environment
+- zero-config BMAD merge for arbitrary customized files
+- provider-specific quality parity between Codex and Claude Code
+
+## Post-Publish Validation
+
+Run on a clean directory:
+
+```bash
+npx bmad-overlay --target ./test-project --mode full --merge-bmad true
+```
+
+Then verify:
+
+- `overlay/`
+- `docs/`
+- `scripts/overlay-*.sh`
+- `.overlay/setup.json`
+- `overlay-applied/`
+- `_bmad/_config/agents/*.customize.yaml` if merge enabled

package/QUICKSTART.md

@@ -0,0 +1,69 @@
+# Quickstart
+
+## Install Into A Project
+
+Recommended npm install:
+
+```bash
+npx bmad-overlay --target /path/to/project --mode full --merge-bmad true
+```
+
+Package:
+
+- `https://www.npmjs.com/package/bmad-overlay`
+
+Local install from this repo:
+
+```bash
+node overlay/install/install-overlay.mjs --target /path/to/project --mode full --merge-bmad true
+```
+
+Shell wrapper:
+
+```bash
+./overlay/install/install-overlay.sh /path/to/project full true
+```
+
+## Modes
+
+- `codex`: runtime plus Codex-facing setup
+- `claude-code`: runtime plus Claude Code-facing setup
+- `bmad`: BMAD customization and mapping setup
+- `full`: all of the above
+
+## Run The Overlay
+
+From the target project:
+
+```bash
+scripts/overlay-run-auto.sh "Create a SaaS for appointment booking"
+```
+
+Provider-specific:
+
+```bash
+scripts/overlay-run-codex.sh "Create a SaaS for appointment booking"
+scripts/overlay-run-claude.sh "Create a SaaS for appointment booking"
+```
+
+## Check State
+
+```bash
+scripts/overlay-status.sh
+```
+
+Primary state files:
+
+- `docs/studio/current-stage.yaml`
+- `docs/studio/run-manifest.md`
+
+## BMAD Step
+
+If BMAD is present and merge is enabled:
+
+1. Review merged files in `_bmad/_config/agents/`
+2. Re-run:
+
+```bash
+npx bmad-method install
+```

package/README.md

@@ -0,0 +1,84 @@
+# bmad-overlay
+
+`bmad-overlay` installe une surcouche d'orchestration BMAD dans un projet existant.
+
+L'objectif est simple:
+
+- preparer le projet
+- ajouter les fichiers et scripts utiles
+- utiliser un point d'entree unique pour piloter le workflow
+
+Package npm:
+
+- `https://www.npmjs.com/package/bmad-overlay`
+
+## Prerequis
+
+- un projet cible
+- BMAD deja installe si tu veux activer le merge BMAD
+
+## Installation
+
+Commande recommandee:
+
+```bash
+npx bmad-overlay --target /path/to/project --mode full --merge-bmad true
+```
+
+Exemple:
+
+```bash
+npx bmad-overlay --target ./my-project --mode full --merge-bmad true
+```
+
+## Modes
+
+- `codex`: prepare le projet pour un usage Codex
+- `claude-code`: prepare le projet pour un usage Claude Code
+- `bmad`: ajoute la couche de mapping et de customization BMAD
+- `full`: installe tout
+
+## Ce que la commande ajoute
+
+- `overlay/`
+- `docs/`
+- des scripts `scripts/overlay-*.sh`
+- les fichiers de setup overlay
+- le merge BMAD si `--merge-bmad true` est active
+
+## Utilisation
+
+Depuis le projet cible:
+
+```bash
+scripts/overlay-run-auto.sh "Create a SaaS for appointment booking"
+```
+
+Selon le provider:
+
+```bash
+scripts/overlay-run-codex.sh "Create a SaaS for appointment booking"
+scripts/overlay-run-claude.sh "Create a SaaS for appointment booking"
+```
+
+Verifier l'etat courant:
+
+```bash
+scripts/overlay-status.sh
+```
+
+## Fichiers utiles
+
+- `docs/studio/current-stage.yaml`
+- `docs/studio/run-manifest.md`
+
+## Documentation
+
+- [Quickstart](./QUICKSTART.md)
+- [Installation](./install/INSTALL.md)
+- [Publish](./PUBLISH.md)
+
+## Installation manuelle
+
+L'installation manuelle existe, mais elle est reservee aux cas avances.
+Le parcours standard doit passer par `npx bmad-overlay`.

package/agents/orchestrator.md

@@ -0,0 +1,94 @@
+# Overlay Orchestrator
+
+## Mission
+
+Be the single visible entrypoint for the user.
+Delegate internally when useful, but keep the workflow continuous and low-interruption.
+
+## Responsibilities
+
+- classify incoming requests
+- choose `quick` or `structured`
+- identify the relevant feature docs
+- determine which BMAD role should act next
+- consolidate outcomes into a single user-facing thread
+- serialize cross-phase execution
+- assign disjoint write scopes to internal workers
+- prevent multiple agents from editing the same synthesis artifacts simultaneously
+
+## Mandatory protocol
+
+1. Read `docs/index.md`
+2. If the request maps to a feature, read its local docs
+3. Check `_bmad-output` for relevant BMAD artifacts
+4. Decide whether the task is planning, architecture, implementation, QA, or documentation
+5. Decide which single council is active
+6. Delegate with explicit write ownership
+7. Wait for council synthesis before opening the next council
+8. Ensure continuation docs are updated before closing
+
+## Concurrency Rules
+
+### Phase serialization
+
+Only one cross-phase council may own the main synthesis path at a time:
+
+- Analyst Council
+- PM Council
+- Architecture Council
+- Delivery Council
+- QA / Review Council
+
+The orchestrator must not open a downstream council until the upstream council has emitted:
+
+- its synthesis artifact
+- its handoff artifact
+- its explicit next-stage recommendation
+
+### Worker write-scope rule
+
+Within a council, workers may run in parallel only if their write scopes are disjoint.
+
+Examples:
+
+- allowed: separate seat notes
+- allowed: frontend and backend implementation in different ownership areas
+- not allowed: two workers editing the same synthesis file
+- not allowed: multiple workers editing the same handoff artifact
+
+### Lead-only synthesis rule
+
+Every council has exactly one lead allowed to write:
+
+- the council synthesis
+- the council handoff
+- the final council decision
+
+All other seats produce inputs for the lead, not direct edits to the authoritative synthesis.
+
+### Escalation to serialization
+
+If write scopes become unclear, the orchestrator must serialize the remaining work instead of parallelizing it.
+
+## Artifact Ownership Rule
+
+The orchestrator owns:
+
+- stage activation
+- worker assignment
+- final merge decisions
+- continuity enforcement
+
+Council leads own:
+
+- stage synthesis
+- stage handoff
+
+Seat workers own:
+
+- their own seat output only
+
+## Escalation threshold
+
+Do not escalate for local execution ambiguity.
+Escalate only for product ambiguity, conflicting authority, or major architectural impact.

package/config/agent-map.yaml

@@ -0,0 +1,40 @@
+stages:
+  analysis:
+    lead_agent: "bmad-analyst"
+    seats:
+      market-analyst: "bmad-analyst"
+      user-problem-analyst: "bmad-analyst"
+      feasibility-analyst: "bmad-analyst"
+      adversarial-analyst: "bmad-analyst"
+  pm:
+    lead_agent: "bmad-pm"
+    seats:
+      mvp-pm: "bmad-pm"
+      growth-pm: "bmad-pm"
+      risk-pm: "bmad-pm"
+      ux-pm: "bmad-pm"
+  architecture:
+    lead_agent: "bmad-architect"
+    seats:
+      application-architect: "bmad-architect"
+      data-architect: "bmad-architect"
+      delivery-architect: "bmad-architect"
+      constraint-reviewer: "bmad-architect"
+  delivery:
+    lead_agent: "bmad-dev"
+    seats:
+      story-planner: "bmad-sm"
+      dependency-planner: "bmad-architect"
+      dev-representative: "bmad-dev"
+      frontend-dev: "bmad-dev"
+      backend-dev: "bmad-dev"
+      data-dev: "bmad-dev"
+      integration-dev: "bmad-dev"
+      quick-fix-dev: "bmad-quick-flow-solo-dev"
+  qa-review:
+    lead_agent: "bmad-qa"
+    seats:
+      qa-engineer: "bmad-qa"
+      edge-case-reviewer: "bmad-qa"
+      docs-continuity-reviewer: "bmad-tech-writer"
+      release-gatekeeper: "bmad-qa"

package/customizations/bmm-dev.customize.yaml

@@ -0,0 +1,25 @@
+# Merge this content into _bmad/_config/agents/bmm-dev.customize.yaml
+
+critical_actions:
+  - 'Before implementation, read docs/index.md and the feature-local docs when available.'
+  - 'Do not ask the user for information that can be inferred from docs, stories, project-context, or the codebase.'
+  - 'Before finishing, update the feature journal and handoff.'
+
+memories:
+  - 'Implementation must leave a continuation trail for the next agent.'
+  - 'Handoff quality is part of done.'
+
+menu:
+  - trigger: implement-from-docs
+    action: '#implement-from-docs'
+    description: Implement using the project documentation as the source of truth
+
+prompts:
+  - id: implement-from-docs
+    content: |
+      Implement the requested feature with minimal interruption.
+      1. Read docs/index.md
+      2. Read the relevant feature docs
+      3. Read _bmad-output/project-context.md if present
+      4. Implement
+      5. Update journal.md and handoff.md with files changed, decisions, and next steps

package/customizations/bmm-pm.customize.yaml

@@ -0,0 +1,24 @@
+# Merge this content into _bmad/_config/agents/bmm-pm.customize.yaml
+
+critical_actions:
+  - 'Read docs/index.md before any planning activity.'
+  - 'If a feature is in scope, read docs/features/<feature>/index.md and handoff.md before asking the user anything.'
+  - 'Only ask the user questions when the answer cannot be derived from docs, _bmad-output artifacts, or the codebase.'
+
+memories:
+  - 'This project uses a documentation-first continuation model.'
+  - 'Every planning output should reference where the next agent must continue reading.'
+
+menu:
+  - trigger: resume-feature
+    action: '#resume-feature'
+    description: Resume a feature from project docs before planning
+
+prompts:
+  - id: resume-feature
+    content: |
+      Resume the requested feature.
+      1. Read docs/index.md
+      2. Locate the feature folder in docs/features/
+      3. Read index.md, handoff.md, and journal.md
+      4. Summarize current state, unresolved questions, and next recommended action

package/customizations/bmm-qa.customize.yaml

@@ -0,0 +1,23 @@
+# Merge this content into _bmad/_config/agents/bmm-qa.customize.yaml
+
+critical_actions:
+  - 'Review docs before code review so documentation and code stay aligned.'
+  - 'Flag missing handoff or stale journal state as delivery risks.'
+
+memories:
+  - 'Documentation drift is a quality issue.'
+  - 'Feature continuity is part of review.'
+
+menu:
+  - trigger: sync-docs
+    action: '#sync-docs'
+    description: Validate that docs and code remain aligned
+
+prompts:
+  - id: sync-docs
+    content: |
+      Validate documentation continuity.
+      1. Read docs/index.md
+      2. Read the target feature docs
+      3. Compare with changed files and tests
+      4. Report any mismatch, stale handoff, or undocumented decision

package/install/INSTALL.md

@@ -0,0 +1,151 @@
+# Installation du portable overlay
+
+## Objectif
+
+Installer cette surcouche dans un autre projet sans modifier le coeur de BMAD.
+
+## Prerequis
+
+- BMAD deja installe dans le projet cible
+- dossiers `_bmad` et `_bmad-output` presents
+
+Package npm:
+
+- `https://www.npmjs.com/package/bmad-overlay`
+
+## Ce que l'overlay ajoute
+
+- un point d'entree orchestrateur
+- des regles documentaires communes
+- des snippets de customisation BMAD
+- une structure `docs/` orientee reprise par agents
+- un contrat d'intake commun
+
+## Modes de setup explicites
+
+L'overlay peut etre installe dans 4 modes:
+
+- `codex`
+  - prepare le runtime et les wrappers pour Codex
+- `claude-code`
+  - prepare `CLAUDE.md`, le runtime et les wrappers Claude Code
+- `bmad`
+  - prepare les snippets et le mapping vers les agents BMAD existants
+- `full`
+  - installe les 3 couches ensemble
+
+Le mapping BMAD utilise:
+
+- `analysis` -> `bmad-analyst`
+- `pm` -> `bmad-pm`
+- `architecture` -> `bmad-architect`
+- `delivery` -> `bmad-dev` / `bmad-sm` / `bmad-quick-flow-solo-dev`
+- `qa-review` -> `bmad-qa` / `bmad-tech-writer`
+
+Voir:
+
+- `overlay/config/agent-map.yaml`
+
+## Installation recommandee
+
+Commande standard:
+
+```bash
+npx bmad-overlay --target ./projet-cible --mode full --merge-bmad true
+```
+
+Cette commande doit couvrir le parcours normal:
+
+- installer l'overlay dans le projet cible
+- preparer `docs/` et les fichiers de bootstrap
+- ajouter les wrappers `scripts/overlay-*.sh`
+- appliquer le merge BMAD si demande
+
+## Installation manuelle
+
+Utiliser ce mode seulement pour le developpement, le debug ou une integration tres controlee.
+
+1. Copier le dossier `overlay/` dans le projet cible
+2. Copier `overlay/templates/CLAUDE.md` vers `CLAUDE.md`
+3. Copier les templates `docs/` si le projet n'a pas deja une structure documentaire
+4. Fusionner les snippets de `overlay/customizations/` dans `_bmad/_config/agents/`
+5. Rejouer l'installation BMAD pour appliquer les customizations:
+
+```bash
+npx bmad-method install
+```
+
+## Installation semi-automatique
+
+Depuis le repo qui contient cet overlay:
+
+```bash
+./overlay/install/install-overlay.sh ./projet-cible full
+```
+
+Le script:
+
+- copie l'overlay
+- cree `docs/` s'il manque
+- cree `CLAUDE.md` si le mode le demande
+- genere des wrappers `scripts/overlay-*.sh`
+- copie les snippets BMAD et le mapping d'agents si le mode le demande
+- ecrit `.overlay/setup.json`
+
+Exemples:
+
+```bash
+./overlay/install/install-overlay.sh ./projet-cible codex
+./overlay/install/install-overlay.sh ./projet-cible claude-code
+./overlay/install/install-overlay.sh ./projet-cible bmad
+./overlay/install/install-overlay.sh ./projet-cible full
+```
+
+## Installation via NPX
+
+Le point d'entree public est:
+
+```bash
+npx bmad-overlay --target ./projet-cible --mode full
+```
+
+Le binaire npm est defini dans:
+
+- `overlay/package.json`
+
+## Merge BMAD plus propre
+
+L'overlay fournit maintenant un mergeur idempotent pour les fichiers:
+
+- `_bmad/_config/agents/bmm-pm.customize.yaml`
+- `_bmad/_config/agents/bmm-dev.customize.yaml`
+- `_bmad/_config/agents/bmm-qa.customize.yaml`
+
+Usage direct:
+
+```bash
+node overlay/install/merge-bmad-customizations.mjs --target ./projet-cible
+```
+
+Ou via l'installeur:
+
+```bash
+node overlay/install/install-overlay.mjs --target ./projet-cible --mode full --merge-bmad true
+```
+
+Ou via le wrapper shell:
+
+```bash
+./overlay/install/install-overlay.sh ./projet-cible full true
+```
+
+Le merge:
+
+- ajoute les actions, memories, menu et prompts overlay
+- evite les doublons exacts
+- ne remplace pas la persona ni les champs agent existants
+
+## Limite volontaire
+
+Le merge BMAD reste optionnel et explicite.
+Cela evite d'ecraser des `.customize.yaml` deja adaptes dans un projet existant.

package/install/check-package.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "child_process";
+import path from "path";
+import process from "process";
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const cacheDir = "/tmp/bmad-overlay-npm-cache";
+
+try {
+  execFileSync("npm", ["pack", "--dry-run"], {
+    cwd: ROOT,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      NPM_CONFIG_CACHE: cacheDir,
+    },
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}