bmad-plus 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to BMAD+ will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.23.1] - 2026-10-19
+
+### Added
+
+- **Documentation, in four languages.** The website now carries 52 reference and guide pages for each of English, French, Spanish and German (`/docs/<section>/<page>/`, with a Markdown mirror per page): the ten packs and their agents, every CLI command with its flags, exit codes and errors, `config.yaml`, the project layout, the adapters, the install, update and uninstall lifecycle, intake, swarms, Nexus, memory, review and acceptance, data handling, trust and ownership, a glossary, a FAQ and troubleshooting. Pages are data (`website/docs-pages/<id>.js`), checked by a validator (blocks, links, anchors, example ids), rendered with a sidebar, breadcrumbs, previous and next links, an on-this-page list, search and a copy button on every command, and indexed in the sitemap, `llms.txt`, `llms-full.txt` and per-language search files. The earlier single guide at `/docs/` is unchanged.
+- **A rebuilt landing page** (all four languages): the story in five moves, the ten packs, a searchable roster of the 48 agents, ask-first intake and swarms, the CLI, supported tools, trust and data handling, and a video player that appears only when a presentation video is published. Counts come from the registry at build time (`website/registry-facts.js`), not from typed numbers; the page respects `prefers-reduced-motion` and `prefers-color-scheme`.
+- **Six presentation videos** (`overview`, `ask-then-swarm`, `ten-packs`, `atelier-design`, `install-and-keep-memory`, `nexus-parallel`; between 51 and 83 seconds each) with English and French narration, captions and transcripts in English, French, Spanish and German, shown on the landing and on the documentation pages that cover the same topic. `website/media/manifest.json` describes them; a video is rendered only when its poster and a source file exist, and only manifest-referenced files are deployed. The terminal footage in them is replayed from real command transcripts (19 silent clips in `website/media/screencasts/`, renderer `tools/media/screencast/`); the swarm tallies on screen are demo data and say so. Assembly notes: `website/media/BUILD.md`.
+- Website checks: `check-docs.js` (the registry and every page), `check-browser-docs.js` (Playwright and axe on the documentation) and unit suites for the docs framework and the landing; `check-browser.js --bundled` runs the Chromium that ships with Playwright.
+- **A seventh video, the case study** ("AI said done. Was it?", English and French voice, four caption languages, described transcripts): kinetic typography, three generated 3D clips with a moving camera, four terminal clips recorded from the published 0.23.0 package, a synthesised sound design and a 9:16 cut for social networks (not shipped). The assembler gains per-shot hard cuts, ASS animation presets, a progress bar and sound events (`website/media/tools/fx.js`, `scripts/<id>.fx.json`).
+
+### Changed
+
+- **npm description and keywords.** The description now names the ten packs, intake, swarms under a budget, safe updates and the seven AI coding tools; keywords cover the supported tools and the main capabilities.
+- **README credits.** The credits ledger separates what Laurent Rochetta wrote (Core extensions, Dev Studio, Maker, Design, Memory, SEO, Backup, Animated), what derives from BMAD-METHOD (Core personas) and what is adapted from other open-source projects (Shield, OSINT, Karpathy guardrails). Dev Studio is credited as original BMAD+ instructions with a lineage clause. The README and its French, Spanish and German mirrors move together; the measured test count is 1896.
+- **Mobile performance of the landing, after the rebuild had cost it.** The described transcripts (44 KB of the page) are published as their own small pages and fetched on first open, with a link as the no-script fallback; every media URL is content-hashed and served `immutable`; the six gallery posters load as their player nears the viewport and all posters are 800 px wide instead of 1280 px (94 KB to 46 KB); the landing loads one stylesheet instead of two. Measured with Lighthouse (Moto G Power, slow 4G): the landing HTML drops from 200 KB to 158 KB and the first load from 313 KB to 181 KB. The documentation search form no longer shifts the layout when script reveals it (layout shift 0.06 to 0.08 on every documentation page, now 0).
+- **HTML is served compressible.** The `no-transform` directive is gone from the HTML routes: it kept Cloudflare from compressing the pages (the 200 KB landing reached phones raw) and cost the mobile performance score. The email-address protection it also gave is now enforced by construction: `check-search` fails the build on any `@` in page text outside `<!--email_off-->`, and `check-search --live` accepts Cloudflare dropping the markers but fails on an HTML page that arrives uncompressed.
+- **`review scope --workspace` defaults its base to `HEAD`** (it was `HEAD~1`, which failed on a one-commit repository and pulled the last commit into a review of uncommitted work). An explicit `--base` still wins; without `--workspace` the default is unchanged.
+- The publication candidate check now carries the documentation framework and every page module (`CANDIDATE_WEBSITE_FILES`, `website/docs-pages/`), and its Node tests include the docs suites.
+
+### Fixed
+
+- **Shipped instructions that named things that do not exist.** The Animated pack extracts frames with the documented FFmpeg commands instead of a `scripts/extract_frames.py` the npm package never contained, and Google Fonts is an explicit, disclosed choice for a generated site (system fonts by default). Shield documents the installer flag `--packs`. The installer's getting-started guide names commands that exist (`/seo full`, `/backup`, the Animated activation phrase) in every language. The Maker integration guide is registry-first (`registry.yaml`, `npm run build`, `generate-adapters --adopt`).
+- **OSINT instructions call the scripts the pack ships** (`apify.py run`, `volley.py search|merge`, `status`) instead of `.sh` wrappers that do not exist, and the Twitter script that was never shipped is dropped. No OSINT key is required: each script checks only its own key, one key from any provider is enough, and `optional_keys` lists every key the scripts read.
+- **Zecher scan depth** is 4, as `bmad-plus scan` declares.
+- **A plain `npx bmad-plus update` no longer installs an older release in silence.** `npx` runs a cached or project-local copy before it asks the registry, so the update installed that copy's version (a 0.22.0 cache installed 0.22.0 while 0.23.0 was published). `update` now asks the registry through the existing update check (cached, off when the project policy is `off`) and, when the copy it runs is older than the published release, warns and names `npx bmad-plus@latest update` and `update --latest`. The README, the installer's closing guide, the generated adapter notes and the `update` reference page give `npx bmad-plus@latest update`. A copy that is already old cannot learn this: run `npx bmad-plus@latest update` once.
+- **One refusal for an `--auto` update the policy does not allow.** `update --auto` and `update --latest --auto` both fail with `Update refused: automatic-updates-not-authorized.`; the legacy-inventory and local-conflict refusals use the same `Update refused:` form instead of `Automatic update refused:`.
+- **`_bmad/config.yaml` is plain YAML under every supported js-yaml.** The installer no longer passes `forceQuotes`, which js-yaml 5.2.x answers with tagged scalars (`!!bool 'true'`, `!!int '3'`); 5.5 wrote plain values, so the file differed with the parser that happened to be installed.
+- **Nexus errors carry the `Nexus:` prefix once**, not `Nexus: Nexus:`.
+- **The generated instruction files say what to do without a local CLI**: when npx cannot find `bmad-plus`, skip the version check without mentioning it (never install a CLI for it).
+- **Shield names PCI DSS v4.0.1** in the pack README, the orchestrator table, the skill list, the agent header and the website listings, as the agent itself defaults to.
+- **The swarm skills say three kinds** (`panel`, `jury`, `fanout`), as their tables list; a test keeps the number and the table together.
+- **The Backup pack's Bash variants print the archive size**, as its rule and its PowerShell variants already did.
+- **Shield counts 27 frameworks**, matching its 27 specialist agents (DPDPA joins the compliance tags); the pack list of the installer, the generated instruction files and the README now agree.
+- **Content truth, after an independent review of the documentation.** Pages for packs, agents, concepts, reference, guides, security and the FAQ were re-checked against the source: replayed terminals and inline fixtures instead of invented output, real menu collisions, the registry-first Maker template, a plain `config.yaml`, one glossary applied in French, Spanish and German, and no duplicated example prompts. Commands run right after the first install use `npx bmad-plus`; the `--no-install` form is explained where it appears and states its prerequisite (`npm install --save-dev bmad-plus`).
+- **Described transcripts for the six videos** (WCAG 1.2.3 and 1.2.5): beside the transcript, a second disclosure lists every shot with its start time, what the picture shows (commands, captions and burned-in titles quoted exactly, written from the extracted frames and the screencasts) and the narration heard from there, in English, French, Spanish and German. The files are generated by `website/media/tools/descriptions.js`, checked for drift by `descriptions.test.js`, rendered inline on the landing and in the documentation (and in the Markdown mirrors of the docs), and covered by the keyboard checks of `check-browser.js`. The Spanish and German narration scripts now match the corrected captions they sit beside.
+- **Accessibility fixes** found by the same review: a skip link that lands on the page's `h1`, row headers on tables, named headings and landmarks, container-query layouts that hold at narrow widths, caption policy in `media.js`, and a dedicated browser check (`check-browser-a11y.js`) beside the axe runs.
+- **French typography.** French pages (HTML, JSON-LD and Markdown mirrors) are typeset at build time: no-break space before `:`, narrow no-break space before `;`, `!`, `?` and around guillemets, and typographic apostrophes; code, URLs and English passages are left alone.
+- **Captions re-cut.** All 24 VTT files are cut to at most 2 lines of 42 characters and 6 seconds per cue at phrase boundaries; the French captions are verbatim with the spoken narration (WCAG 1.2.2), and the manifest transcripts follow them. A site test compares captions with the narration scripts.
+- **Re-recorded installer clips.** The pack picker in the `ten-packs` and `install-and-keep-memory` videos now shows Shield with 27 frameworks; the storyboards say the swarm tallies are demo data.
+
+## [0.23.0] - 2026-10-17
+
+### Added
+
+- **Pack intake** (`bmad-plus intake check|plan|record|render`, skill `bmad-plus-intake`). A pack declares the questions it needs answered before it acts (`intake.yaml`: sections, kinds, must-haves with the risk of not knowing, defaults, the artifact each answer feeds). `plan` says what is still missing and the next batch to ask, must-haves first and a few at a time; `record` writes only what the user gave, marks what they do not know, and never invents; `render` writes the brief that becomes the contract for everything the pack does next. The build validates every declared intake with the same contract the CLI uses.
+- **Swarm runtime** (`bmad-plus swarm init|briefs|check|save|tally|inspect|plan`, skill `bmad-plus-swarm`). A pack declares a swarm (a panel dealt deterministically from a profile, a jury of listed lenses, or a fanout of units with disjoint write scopes); the CLI deals the cards under a seed, renders one brief per unit, validates each sub-agent's answer file, tallies rates, counts, verbatim quotes and numbers over valid answers only, and exports a fanout as a durable Nexus plan. A new `swarm` block in `_bmad/config.yaml` sets the budget of sub-agents a run may use before the host asks (26 by default) and keeps paid media generation out of any budget. The host spawns the sub-agents; the CLI never calls a model and never answers for a unit.
+- **Skill packs in the registry.** `uses_skills` names the skills an agent drives (rendered on its roster line as `drives:`); `external_module` takes a pack's skills from a pinned npm package the installer copies into `.agents/skills/` with a version check; `pipelines` declares ordered workflow or agent steps with a checkpoint gate each, rendered step by step in the generated instructions; `intake` names the pack's intake file. All four are validated at build time.
+- **Design pack (Atelier).** The design engine published as `design-skill` (three skills: `design`, `design-review`, `redesign`, with their reference modules) joins every installation as a referenced package, driven by the Atelier persona through an intake first. The pack ships a sealed evaluation, a shipping test and its trigger block; `pack-animated` stays until the brand-site pack supersedes it.
+- **Trigger gate** (`npm run check:triggers`, Platform workflow). `role-triggers.yaml` may only name Core agents, pack personas and declared pipelines; a role needs patterns, and a pattern repeated within one agent is refused.
+
+### Changed
+
+- Nexus runs a pack's declared pipeline after its intake and runs swarms through `bmad-plus swarm` within the configured budget; autopilot's Discovery starts with the intake of every pack involved. The generated instructions tell an agent to read the `SKILL.md` of every skill it drives before acting.
+- `bmad-plus install` lists every selected pack's files before writing any, so an unresolvable external module leaves the project untouched.
+
+### Fixed
+
+- `bmad-plus uninstall` removes the skills copied from an external module (found by the 0.23.0 acceptance run: the three Atelier skills stayed in `.agents/skills/` after uninstall). Edited copies stay, as for every other managed file, and nothing is removed when the package can no longer be compared.
+
 ## [0.22.0] - 2026-09-29
 
 ### Added

package/README.md

@@ -1,15 +1,17 @@
 # BMAD+
 
-[![Version](https://img.shields.io/badge/version-0.22.0-blue)](https://www.npmjs.com/package/bmad-plus)
+[![Version](https://img.shields.io/badge/version-0.23.1-blue)](https://www.npmjs.com/package/bmad-plus)
 
-**Version 0.22.0** · Node.js `>=20.0.0` · MIT
+**Version 0.23.1** · Node.js `>=20.0.0` · MIT
 
-Project-local AI development workflows with clear roles, shared context, safe updates and coding-tool adapters
+Ten packs of project-local AI roles and workflows (design, SEO, GRC, OSINT, memory) with ask-first intake, swarms under a budget, safe updates and adapters for seven AI coding tools
 
 [Website](https://bmad-plus.rochetta.fr/) · [Get started](https://bmad-plus.rochetta.fr/docs/#start) · [Examples](https://bmad-plus.rochetta.fr/docs/#examples) · [What’s new](https://bmad-plus.rochetta.fr/docs/#news)
 
 BMAD+ installs project instructions, roles and workflows for your existing AI coding tool. Default execution is host-managed: your tool supplies the model, permissions, command execution and any parallel-agent capability. Nexus can also launch an explicitly planned local command or Codex CLI process under a foreground supervisor, record its result and require independent checks before acceptance. Host permissions still apply; there is no background scheduler or universal host lifecycle integration. Model subscriptions and API access are separate.
 
+BMAD+ ships ten packs. Ask first: `bmad-plus intake` asks a pack’s questions a few at a time, proposes defaults, records what you do not know and renders the brief the pack then works from. Swarms: `bmad-plus swarm` deals simulated units, briefs one sub-agent each, validates every answer and counts only the valid ones, within a budget you set. Atelier, the design engine of the Design pack, builds, audits and redesigns interfaces under checkable rules.
+
 Adapters: Claude Code, Gemini CLI, Antigravity, Cursor, Codex CLI, OpenCode, Aider.
 
 ## Get started
@@ -35,7 +37,7 @@ Run the installer. Select the adapters for the AI tools you use and the packs yo
 **In your project terminal:**
 
 ```sh
-npx bmad-plus@0.22.0 install
+npx bmad-plus@0.23.1 install
 ```
 
 The installer creates the agent instructions, shared project spine and selected tool adapters. Optional packs may need additional runtimes or API access.
@@ -93,11 +95,12 @@ Read the changes and test results. The assistant follows the permissions and cap
 | OSINT | Investigation workflows for gathering public information and assessing sources. |
 | Maker | A workflow to design, validate and package your own BMAD+ agents. |
 | Shield | Specialized compliance and governance workflows, including GDPR and ISO 27001. |
-| SEO | Technical scanning, content analysis and search optimization workflows with supporting tools. |
+| SEO | Classic SEO and GEO, visibility in AI-generated answers: technical inspection and performance (Scout), content quality, structured data and AI-search readiness (Judge), scoring, strategy and reporting (Chief). |
 | Memory | Project notes, decision records and session handoffs that preserve useful context. |
 | Dev Studio | Specialized roles and workflows for product planning, design, engineering and documentation. |
 | Backup | Instructions and utilities for timestamped backups, restoration and rotation. |
 | Animated | A focused workflow for creating video-driven scrolling websites. |
+| Design | Atelier, the design engine: build, audit and redesign interfaces under checkable rules, with an intake first. |
 
 ## Examples
 
@@ -151,6 +154,16 @@ Zecher, update this project’s memory from the changes and checks we actually c
 
 Expected result: a concise current context, a dated session handoff and a restart prompt that identifies the next unfinished task.
 
+### Design a screen with Atelier
+
+Use with the optional Design pack installed. Atelier asks its questions first, then follows checkable rules.
+
+```text
+Atelier, run the design read for the invoice list of my app, build the screen, and end with the pre-flight verdict.
+```
+
+Expected result: the recorded design read, the screen with every state covered, and the pre-flight verdict quoted as the last line.
+
 ### Read a test run without guessing
 
 Use when a person has completed or stopped an acceptance run.
@@ -171,18 +184,18 @@ Read AGENTS.md and the available project memory. Summarize the last verified sta
 
 Expected result: a short, evidence-based restart. Project notes are useful context and still need to be checked against the current work.
 
-## What’s new in 0.22.0
+## What’s new in 0.23.1
 
-What leaves your machine, declared and checked
+A truer site, steadier commands
 
-BMAD+ now declares every way it sends data or starts a process, and its CI refuses anything undeclared. The recipe page and the SEO report load nothing from other sites, OSINT calls are HTTPS-only, and Shield gains an evidence-bound assurance case and an AI processing register. Nothing changes in how you install or update.
+The documentation site is rebuilt in four languages with seven videos. Several commands now behave exactly as their pages say: refusals read the same everywhere, a workspace review starts from HEAD, and the config file is plain YAML. Installing and updating work as before.
 
-- The registry states what BMAD+ sends, to whom, when and with which consent; SECURITY.md shows it and the installed agent instructions summarise it. A build check fails when a network call or a started process is not declared. BMAD+ has no telemetry, and the update check can be turned off.
-- The acceptance page no longer loads Google Fonts or anything from another site, so opening it tells no one you did. The build refuses a page that would, and a real browser checks every request of a run. The SEO HTML report opens offline too.
-- The Google API key of the SEO pack travels in a request header, never in a URL, and is hidden from error messages. OSINT provider calls refuse anything but HTTPS and never follow a redirect to another host.
-- SEO screenshots reach only the address that was checked: Chromium resolves nothing else, and redirects or resources pointing elsewhere are blocked and listed.
-- Shield: bmad-plus assurance builds a security case whose evidence can only be a check that actually ran, recorded in a tamper-evident ledger; bmad-plus ai-register keeps a register of the AI tools a project uses and warns about any it has not recorded; six review rules name the compliance controls a change touches.
-- The MCP server closes SSE streams cleanly when a client leaves or the server stops, and accepts token dates with a time-zone offset.
+- The website now carries 52 documentation pages, each in English, French, Spanish and German, a rebuilt landing page and seven presentation videos with captions and described transcripts, including a case study of how the site itself was rebuilt with a swarm of agents.
+- An --auto update that the policy does not allow is refused with the same message everywhere: Update refused: automatic-updates-not-authorized. The refusals for a legacy ownership inventory and for local conflicts use the same Update refused: form.
+- bmad-plus review scope --workspace starts from HEAD when you give no --base, so reviewing uncommitted work no longer fails or drags in the last commit.
+- _bmad/config.yaml is written as plain YAML (auto_role_activation: true, not a tagged !!bool 'true') whichever supported js-yaml version wrote it.
+- The generated instruction files tell the assistant to skip the version check, without mentioning it, when npx finds no local copy of bmad-plus; Nexus errors carry the Nexus: prefix once instead of twice.
+- Shield names PCI DSS v4.0.1 everywhere, the swarm skills say there are three kinds, the Backup pack’s Bash variant prints the archive size like its PowerShell variant, and the npm description, keywords and README credits are refreshed.
 
 ## Version History
 
@@ -190,9 +203,9 @@ These dates identify reviewed CHANGELOG notes, not npm publication dates. The we
 
 | Version | Release-notes date | Reviewed summary |
 | --- | --- | --- |
+| 0.23.1 | 2026-10-19 | The documentation site is rebuilt in four languages with seven videos. Several commands now behave exactly as their pages say: refusals read the same everywhere, a workspace review starts from HEAD, and the config file is plain YAML. Installing and updating work as before. |
+| 0.23.0 | 2026-10-17 | A pack now declares the questions it needs answered before it acts, and Nexus can run a swarm of sub-agents, a simulated panel or a jury, within a budget you set. Atelier, the design engine, joins as the tenth pack. Installing and updating work as before. |
 | 0.22.0 | 2026-09-29 | BMAD+ now declares every way it sends data or starts a process, and its CI refuses anything undeclared. The recipe page and the SEO report load nothing from other sites, OSINT calls are HTTPS-only, and Shield gains an evidence-bound assurance case and an AI processing register. Nothing changes in how you install or update. |
-| 0.21.0 | 2026-09-28 | A review now records why it stopped and what it used, writes a check a CI step can read, and resumes on the scope it sealed. The SEO fetcher connects only to addresses it has validated, and the MCP server moves to the official SDK on Python 3.12. Nothing changes in how you install or update. |
-| 0.20.0 | 2026-09-28 | bmad-plus review now hands the reviewer the rules that apply to the changed files, fixes the depth of a review before it starts, compares a review with an earlier one without calling an unchecked finding fixed, and masks credentials in what it writes. Nothing changes in how you install or update. |
 
 [Release history and update guide](https://bmad-plus.rochetta.fr/docs/#changelog) · [All published npm versions](https://www.npmjs.com/package/bmad-plus?activeTab=versions)
 
@@ -214,14 +227,21 @@ Translations: [Français](readme-international/README.fr.md) · [Español](readm
 **Creator**
 - **BMAD+** Created by [Laurent Rochetta](https://github.com/lrochetta) ([LinkedIn](https://www.linkedin.com/in/laurentrochetta/))
 
-**Original Packs** (created by Laurent Rochetta)
-- **Dev Studio** — 6 specialized SDLC agents: Miriam (business analyst), Huldah (tech writer), Yosef (product manager), Rachel (UX designer), Bezalel (system architect), Oholiab (senior engineer) — 38 workflows covering the full lifecycle from brainstorming to deployment
-- **SEO Engine** — 3 agents (Scout, Chief, Judge), 6-phase audit pipeline, PageSpeed perfection loop, Google Search Console & GA4 integrations
-- **Memory Pack** — Zecher agent for persistent cross-session brain with project scanner
-
-**External Sources & Inspirations**
-- **BMAD-METHOD** by [bmad-code-org](https://github.com/bmad-code-org/BMAD-METHOD) — Original multi-agent methodology (MIT)
-- **Shield GRC** — 27 compliance agents + 11 workflows adapted from [Hemant Naik's GRC skills](https://github.com/Sushegaad/Claude-Skills-Governance-Risk-and-Compliance) (MIT)
-- **OSINT Pipeline** based on [smixs/osint-skill](https://github.com/smixs/osint-skill) (MIT)
+**Written by Laurent Rochetta**
+- **Core extensions** — Autopilot, Parallel and Sync (0.1.0), the Nexus durable execution (0.15.0), human acceptance recipes (`uat`, 0.16.0), checkable reviews (0.19.0), and in 0.23.0 the pack intake (`bmad-plus intake`) and the swarm runtime (`bmad-plus swarm`) with the registry fields and the trigger gate that feed them
+- **Dev Studio** — 6 specialized SDLC agents: Miriam (business analyst), Huldah (tech writer), Yosef (product manager), Rachel (UX designer), Bezalel (system architect), Oholiab (senior engineer) — 38 workflows, written as original BMAD+ instructions; the persona names and workflow lineage acknowledge BMAD-METHOD 6.6.0 (MIT). The pack ledger is `src/bmad-plus/packs/pack-dev-studio/upstream-sync.yaml`
+- **Maker** — design, build, validate and package your own BMAD+ agents (2026-03-17)
+- **Design** — Atelier, built on the author’s own public npm package [design-skill](https://github.com/lrochetta/design-skill) (MIT): the package supplies the three skills and their rules, BMAD+ adds the persona, the intake and the routing
+- **Memory** — Zecher agent for persistent cross-session memory, with a project scanner and brain detection; the Karpathy guardrails it carries are adapted, see below
+- **SEO** — 3 agents (Scout, Chief, Judge), 6-phase audit pipeline, PageSpeed perfection loop, Google Search Console & GA4 integrations; version 2.0 rebuilt the first SEO audit agent, written under Oveanet, and kept its PageSpeed playbook
+- **Backup** and **Animated** — timestamped project backups, and video-driven scrolling websites; written under Oveanet, Laurent Rochetta’s company, and merged into BMAD+ in 0.2.0 (2026-03-18) together with the first SEO agent
+
+**Derived from BMAD-METHOD** (MIT)
+- **BMAD-METHOD** by [bmad-code-org](https://github.com/bmad-code-org/BMAD-METHOD) — original multi-agent methodology (MIT); BMAD+ is an independent derivative, not an official release
+- **Core** — Atlas, Forge, Sentinel and Nexus: BMAD+ began as a fork of BMAD-METHOD 6.2.0 and was extended by Laurent Rochetta (see Core extensions above). The four personas follow its persona format and keep part of the wording of its analyst (Atlas), architect (Forge), QA (Sentinel) and scrum master (Nexus) personas; merging roles into one switchable persona and auto-activation are BMAD+ additions
+
+**Adapted from other open-source projects**
+- **Shield** — 27 compliance agents + 11 workflows adapted from [Hemant Naik's GRC skills](https://github.com/Sushegaad/Claude-Skills-Governance-Risk-and-Compliance) (MIT), with their 79 reference files; the GDPR and EU AI Act workflows also draw on the architecture of the [Lawve.ai](https://lawve.ai) skills catalog (Oliver Schmidt-Prietz). The orchestrator, cross-framework mapping, report templates, assurance case, AI processing register and compliance review rules are BMAD+ additions
+- **OSINT** — pipeline and Python helpers adapted from [smixs/osint-skill](https://github.com/smixs/osint-skill) (MIT); the lawful-basis gate and the legal notice are BMAD+ additions
 - **Apify integration** — OSINT helper and inspiration from [Apify agent skills](https://github.com/apify/agent-skills) (upstream declares Apache-2.0; see notices)
-- **Karpathy Guardrails** — Memory Pack adaptation of [community guidelines by forrestchang](https://github.com/multica-ai/andrej-karpathy-skills), inspired by Andrej Karpathy (MIT declared upstream)
+- **Karpathy Guardrails** — Memory adaptation of [community guidelines by forrestchang](https://github.com/multica-ai/andrej-karpathy-skills), inspired by Andrej Karpathy (MIT declared upstream)

package/SECURITY.md

@@ -65,7 +65,7 @@ Security researchers who report valid vulnerabilities will be credited in the CH
 - Production npm dependencies are audited before each release; high and critical findings block publication
 - Maintained Python requirements are audited in CI and block publication on known findings
 - The private legacy MCP ML stack has a separate, visible advisory audit and migration backlog; its findings do not describe the npm runtime
-- Minimal dependency footprint (6 runtime dependencies)
+- Minimal dependency footprint (7 runtime dependencies; `design-skill` contributes the skill files BMAD+ copies at install and a linker CLI that BMAD+ never runs)
 - Bundled source notices are included in [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md); npm runtime dependency licenses are recorded in the release SBOM
 
 ### Distribution Security

package/osint-agent-package/agents/osint-investigator.md

@@ -17,7 +17,7 @@ You must fully embody this agent's persona and follow all activation instruction
       </step>
       <step n="3">Remember: user's name is {user_name}</step>
       <step n="4">READ the OSINT skill file at {project-root}/.agents/skills/bmad-osint-investigate/osint/SKILL.md to understand the full investigation pipeline</step>
-      <step n="5">Run the diagnostic script first if possible: bash {project-root}/.agents/skills/bmad-osint-investigate/osint/scripts/diagnose.sh — report available tools to the user</step>
+      <step n="5">Run the diagnostic script first if possible: python3 {project-root}/.agents/skills/bmad-osint-investigate/osint/scripts/diagnose.py — report available tools to the user</step>
       <step n="6">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
       <step n="7">Let {user_name} know they can invoke the `bmad-help` skill at any time to get advice on what to do next</step>
       <step n="8">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
@@ -41,7 +41,7 @@ You must fully embody this agent's persona and follow all activation instruction
       <r>Display Menu items as the item dictates and in the order given.</r>
       <r>Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
       <r>ALL investigation output files should be saved to {output_folder}/osint-reports/ with the target name and date as filename</r>
-      <r>ALWAYS run diagnose.sh BEFORE any investigation to know which tools/APIs are available</r>
+      <r>ALWAYS run diagnose.py BEFORE any investigation to know which tools/APIs are available</r>
       <r>FOLLOW the budget rules: spend ≤$0.50 without asking, ASK permission above that</r>
       <r>NEVER hardcode API tokens — always load from environment variables</r>
       <r>For each fact discovered, assign a confidence grade: A (3+ sources), B (2 sources), C (1 source), D (unverified)</r>
@@ -84,7 +84,7 @@ You must fully embody this agent's persona and follow all activation instruction
     <item cmd="FB or fuzzy match on facebook">[FB] 📘 Facebook Scrape: Extract Facebook profile data via Bright Data MCP (requires BRIGHTDATA_MCP_URL).</item>
     <item cmd="PP or fuzzy match on psychoprofile or personality">[PP] 🧠 Psychoprofile: Build MBTI/Big Five personality analysis from existing content (YouTube, blogs, posts).</item>
     <item cmd="CE or fuzzy match on contact or email or phone">[CE] 📞 Contact Enrichment: Find email, phone, and other contact info for a person using Apify enrichment actors.</item>
-    <item cmd="DG or fuzzy match on diagnose or diagnostic or tools">[DG] 🔧 Diagnose Tools: Run diagnose.sh to check which APIs and tools are available.</item>
+    <item cmd="DG or fuzzy match on diagnose or diagnostic or tools">[DG] 🔧 Diagnose Tools: Run diagnose.py to check which APIs and tools are available.</item>
     <item cmd="PM or fuzzy match on party-mode" exec="skill:bmad-party-mode">[PM] Start Party Mode</item>
     <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
   </menu>

package/osint-agent-package/skills/bmad-osint-investigate/osint/SKILL.md

@@ -83,25 +83,25 @@ All API keys via environment variables. Never hardcode tokens.
 
 ## Scripts
 
-Run from skill dir: `bash scripts/<name>.sh`.
+Run from the skill directory (`.agents/skills/bmad-osint-investigate/osint/` once installed): `python3 scripts/<name>.py` (`python` on Windows).
 Each validates env vars, exits with descriptive error + URL to get the key.
 
 **Search & Research:**
-- `diagnose.sh` — run FIRST. Capability map of all tools.
-- `perplexity.sh` — `search <query>` | `sonar <query>` (AI answer) | `deep <query>` (deep research)
-- `tavily.sh` — `search <query>` (basic $0.005) | `deep <query>` (advanced) | `extract <url>`
-- `exa.sh` — `search <query>` | `company <name>` | `people <name>` | `crawl <url>` | `deep <prompt>`
-- `first-volley.sh "Name" "context"` — parallel search, all engines at once.
-- `merge-volley.sh <outdir>` — deduplicate and merge first-volley results.
+- `diagnose.py` — run FIRST. Capability map of all tools.
+- `perplexity.py` — `search <query>` | `sonar <query>` (AI answer) | `deep <query>` (deep research)
+- `tavily.py` — `search <query>` (basic $0.005) | `deep <query>` (advanced) | `extract <url>`
+- `exa.py` — `search <query>` | `company <name>` | `people <name>` | `crawl <url>` | `deep <prompt>`
+- `volley.py search "Name" "context"` — parallel search, all engines at once.
+- `volley.py merge <outdir>` — deduplicate and merge first-volley results.
 
 **Scraping:**
-- `apify.sh` — `linkedin <url>` | `instagram <handle>` | `run` | `results` | `store-search`
-- `run-actor.sh` — **universal Apify runner (55+ actors).** Embedded from [apify/agent-skills](https://github.com/apify/agent-skills).
-  Quick answer: `bash scripts/run-actor.sh "actor/id" '{"input":"json"}'`
-  Export: `bash scripts/run-actor.sh "actor/id" '{"input":"json"}' --output /tmp/out.csv`
-- `jina.sh` — `read <url>` | `search <query>` | `deepsearch <query>`
-- `parallel.sh` — `search <query>` | `extract <url>`
-- `brightdata.sh` — `scrape <url>` | `scrape-batch` | `search` | `search-geo <cc>` | `search-yandex`
+- `apify.py` — `linkedin <url>` | `instagram <handle>` | `run` | `results` | `status` | `store-search`
+- `apify.py run` — **universal Apify actor runner (55+ actors).**
+  Quick answer: `python3 scripts/apify.py run "actor/id" '{"input":"json"}'`
+  Export: `python3 scripts/apify.py run "actor/id" '{"input":"json"}' --output /tmp/out.csv`
+- `jina.py` — `read <url>` | `search <query>` | `deepsearch <query>`
+- `parallel.py` — `search <query>` | `extract <url>`
+- `brightdata.py` — `scrape <url>` | `scrape-batch` | `search` | `search-geo <cc>` | `search-yandex`
 
 ## Research Escalation Flow
 
@@ -112,14 +112,14 @@ Each validates env vars, exits with descriptive error + URL to get the key.
 Запускай ВСЕ параллельно:
 ```bash
 # Perplexity Sonar — AI ответ с цитатами
-bash skills/osint/scripts/perplexity.sh sonar "Who is <Name>, <context>"
+python3 scripts/perplexity.py sonar "Who is <Name>, <context>"
 # Brave Search — классический поиск
 web_search "<Name> <company> <role>"
 # Tavily — agent-optimized search с AI answer
-bash skills/osint/scripts/tavily.sh search "<Name> <context>"
+python3 scripts/tavily.py search "<Name> <context>"
 # Exa — семантический поиск + company/people research
-bash skills/osint/scripts/exa.sh search "<Name> <context>"
-bash skills/osint/scripts/exa.sh people "<Name>"
+python3 scripts/exa.py search "<Name> <context>"
+python3 scripts/exa.py people "<Name>"
 ```
 → Получаешь: быстрые факты, ссылки, контекст.
 → Решение: достаточно? → Phase 6. Нужно больше? → Level 2.
@@ -129,8 +129,8 @@ bash skills/osint/scripts/exa.sh people "<Name>"
 ```bash
 # Читай найденные URL
 web_fetch "<url_from_perplexity>"
-bash skills/osint/scripts/jina.sh read "<url>"
-bash skills/osint/scripts/parallel.sh extract "<url>"
+python3 scripts/jina.py read "<url>"
+python3 scripts/parallel.py extract "<url>"
 ```
 → Получаешь: подтверждённые факты, cross-reference.
 → Совпадает? → дополняй досье. Нужно глубже? → Level 3.
@@ -139,11 +139,11 @@ bash skills/osint/scripts/parallel.sh extract "<url>"
 Подключай scraping для соцсетей:
 ```bash
 # LinkedIn
-bash skills/osint/scripts/apify.sh linkedin "<url>"
+python3 scripts/apify.py linkedin "<url>"
 # Instagram
-bash skills/osint/scripts/apify.sh instagram "<handle>"
+python3 scripts/apify.py instagram "<handle>"
 # Facebook, заблокированные сайты
-bash skills/osint/scripts/brightdata.sh scrape "<url>"
+python3 scripts/brightdata.py scrape "<url>"
 ```
 → Получаешь: структурированные профили, фото, связи.
 
@@ -152,13 +152,13 @@ bash skills/osint/scripts/brightdata.sh scrape "<url>"
 Запускай ВСЕ параллельно (30-60 сек каждый):
 ```bash
 # Perplexity Deep Research
-bash skills/osint/scripts/perplexity.sh deep "<detailed research prompt about Name>"
+python3 scripts/perplexity.py deep "<detailed research prompt about Name>"
 # Exa Deep Research
-bash skills/osint/scripts/exa.sh deep "<detailed prompt>"
+python3 scripts/exa.py deep "<detailed prompt>"
 # Parallel AI Deep Search
-bash skills/osint/scripts/parallel.sh search "<detailed query>"
+python3 scripts/parallel.py search "<detailed query>"
 # Jina DeepSearch
-bash skills/osint/scripts/jina.sh deepsearch "<query>"
+python3 scripts/jina.py deepsearch "<query>"
 ```
 
 **Правило:** Level 4 промпт должен быть РАЗВЁРНУТЫМ — включай всё что уже знаешь
@@ -198,7 +198,7 @@ The main agent is the coordinator — it does NOT scrape itself.
 
 ## Phase 0: Tooling Self-Check
 
-1. Execute `bash skills/osint/scripts/diagnose.sh`.
+1. Execute `python3 scripts/diagnose.py`.
 2. Log available vs missing tools.
 3. Check internal tools: `tg.py` (Telegram history), `himalaya` (email), vault contacts.
 4. If Bright Data unavailable → Facebook and LinkedIn deep scrape limited. Inform user.
@@ -212,19 +212,19 @@ The main agent is the coordinator — it does NOT scrape itself.
 1. Parse user input. Extract identifiers: names, handles, URLs, companies, locations.
 2. **Perplexity fast pass:**
    ```bash
-   bash skills/osint/scripts/perplexity.sh search "Who is <Name>, <context>"
+   python3 scripts/perplexity.py search "Who is <Name>, <context>"
    ```
 3. **Brave + Parallel in parallel:**
    ```bash
    web_search "<Name> <company>"
-   bash skills/osint/scripts/first-volley.sh "Full Name" "context"
+   python3 scripts/volley.py search "Full Name" "context"
    ```
 4. **Review Perplexity citations** — fetch and verify top sources:
    ```bash
    web_fetch "<citation_url_1>"
    web_fetch "<citation_url_2>"
    ```
-5. Parse & merge: `bash skills/osint/scripts/merge-volley.sh /tmp/osint-<timestamp>`.
+5. Parse & merge: `python3 scripts/volley.py merge /tmp/osint-<timestamp>`.
 6. Collect all identifiers into seed list. Deduplicate.
 7. Flag name collisions (common names → verify with company/location cross-reference).
 8. **Decision point:** enough context? → skip to Phase 4. Need social media? → Phase 2. Need deep dive? → Level 4 (deep research).
@@ -307,21 +307,21 @@ Read `references/platforms.md` ONLY when needing URL patterns or extraction sign
 
 Tool priority (primary → fallback). **If primary fails, switch immediately. Never retry same tool.**
 
-- LinkedIn: `apify.sh linkedin` → `brightdata.sh scrape` → `jina.sh read`
-- Instagram: `apify.sh instagram` → `brightdata.sh scrape`
-- Instagram deep: `run-actor.sh "apify/instagram-tagged-scraper"` (who tags them), `apify/instagram-comment-scraper` (sentiment)
-- Facebook personal: `brightdata.sh scrape` → none (only Bright Data works)
-- Facebook pages/groups: `run-actor.sh "apify/facebook-pages-scraper"` → `brightdata.sh scrape`
-- TikTok: `run-actor.sh "clockworks/tiktok-profile-scraper"` → `clockworks/tiktok-scraper` (comprehensive)
-- TikTok discovery: `run-actor.sh "clockworks/tiktok-user-search-scraper"` (find by keywords)
-- YouTube: `run-actor.sh "streamers/youtube-channel-scraper"` → `jina.sh read` → `brightdata.sh scrape`
-- Telegram channels: `web_fetch t.me/s/{channel}` → `jina.sh read`
-- Twitter/X: `python3 scripts/twitter.py tweet <url>` → `jina.sh read`
-- Google Maps (businesses): `run-actor.sh "compass/crawler-google-places"`
-- Contact enrichment: `run-actor.sh "vdrmota/contact-info-scraper"` (extract emails/phones from any URL)
-- Any site: `jina.sh read` → `brightdata.sh scrape`
-
-**run-actor.sh** = universal Apify runner (embedded, 55+ actors). See `references/tools.md` for full actor catalog.
+- LinkedIn: `apify.py linkedin` → `brightdata.py scrape` → `jina.py read`
+- Instagram: `apify.py instagram` → `brightdata.py scrape`
+- Instagram deep: `apify.py run "apify/instagram-tagged-scraper"` (who tags them), `apify/instagram-comment-scraper` (sentiment)
+- Facebook personal: `brightdata.py scrape` → none (only Bright Data works)
+- Facebook pages/groups: `apify.py run "apify/facebook-pages-scraper"` → `brightdata.py scrape`
+- TikTok: `apify.py run "clockworks/tiktok-profile-scraper"` → `clockworks/tiktok-scraper` (comprehensive)
+- TikTok discovery: `apify.py run "clockworks/tiktok-user-search-scraper"` (find by keywords)
+- YouTube: `apify.py run "streamers/youtube-channel-scraper"` → `jina.py read` → `brightdata.py scrape`
+- Telegram channels: `web_fetch t.me/s/{channel}` → `jina.py read`
+- Twitter/X: `jina.py read` (no dedicated Twitter script is shipped)
+- Google Maps (businesses): `apify.py run "compass/crawler-google-places"`
+- Contact enrichment: `apify.py run "vdrmota/contact-info-scraper"` (extract emails/phones from any URL)
+- Any site: `jina.py read` → `brightdata.py scrape`
+
+**apify.py run** = universal Apify runner (55+ actors). See `references/tools.md` for full actor catalog.
 
 Read `references/tools.md` ONLY when troubleshooting a failed tool.
 
@@ -339,7 +339,7 @@ If initial searches return unusually little for someone who should have a footpr
 
 1. **Wayback Machine:** `web_fetch "https://web.archive.org/web/2024*/target-url"` — deleted profiles, old bios
 2. **Google Cache:** `web_search "cache:domain.com/path"` — recently removed pages
-3. **Yandex Cache:** `brightdata.sh search-yandex "Name"` — Yandex indexes CIS deeper and caches longer
+3. **Yandex Cache:** `brightdata.py search-yandex "Name"` — Yandex indexes CIS deeper and caches longer
 4. **Username variations:** try transliteration (Иванов → ivanov, ivanoff), birth year suffixes, company abbreviations
 5. **Reverse image search:** if photo found, check for other profiles using same avatar
 6. **Conference archives:** speaker bios often survive after profiles are deleted
@@ -467,10 +467,10 @@ If internal intelligence was used, add a separate **"из переписки"**
 
 - **All tools return empty**: target has minimal digital presence. Try Bright Data Yandex search (better for CIS region), search by company + role instead of name.
 - **Wrong person keeps appearing**: add company name, city, or role to all queries. Use quotes around full name.
-- **LinkedIn blocked**: use `brightdata.sh scrape` as primary instead of Apify.
-- **Apify actor dead/changed**: check `apify.sh store-search "linkedin scraper"` for alternatives. Actors on Apify are volatile — always have a Bright Data fallback.
-- **Depth Score stuck at 6-7**: likely missing press/media articles or internal intel. Search industry publications (AdIndex, Sostav, Forbes, Kommersant for Russian market). Try `jina.sh deepsearch`. Check Telegram history.
-- **No social media found**: person may use pseudonyms. Search by email, phone, or company employee page. Search Apify store: `bash scripts/apify.sh store-search "people search"`. If `mcpc` installed: `APIFY_TOKEN=$APIFY_API_TOKEN mcpc --json mcp.apify.com --header "Authorization: Bearer $APIFY_TOKEN" tools-call search-actors keywords:="people search" limit:=10`. Check Telegram contacts by phone.
+- **LinkedIn blocked**: use `brightdata.py scrape` as primary instead of Apify.
+- **Apify actor dead/changed**: check `apify.py store-search "linkedin scraper"` for alternatives. Actors on Apify are volatile — always have a Bright Data fallback.
+- **Depth Score stuck at 6-7**: likely missing press/media articles or internal intel. Search industry publications (AdIndex, Sostav, Forbes, Kommersant for Russian market). Try `jina.py deepsearch`. Check Telegram history.
+- **No social media found**: person may use pseudonyms. Search by email, phone, or company employee page. Search Apify store: `python3 scripts/apify.py store-search "people search"`. If `mcpc` installed: `APIFY_TOKEN=$APIFY_API_TOKEN mcpc --json mcp.apify.com --header "Authorization: Bearer $APIFY_TOKEN" tools-call search-actors keywords:="people search" limit:=10`. Check Telegram contacts by phone.
 - **TikTok scraper fails**: try `clockworks/free-tiktok-scraper` (free tier) as fallback. TikTok usernames often differ from other platforms — search by real name via `clockworks/tiktok-user-search-scraper`.
 - **Need emails from website**: use `vdrmota/contact-info-scraper` — it crawls the site and extracts all contact info.
 - **Rate limited (429)**: back off 5s, then 15s. Switch to fallback tool. Never retry immediately.

package/osint-agent-package/skills/bmad-osint-investigate/osint/references/content-extraction.md

@@ -16,7 +16,7 @@ A person talking for 20 minutes on camera reveals more than 100 LinkedIn posts.
 ```bash
 # Search for channel
 web_search "site:youtube.com <Name> <context>"
-bash skills/osint/scripts/exa.sh search "<Name> youtube channel"
+python3 scripts/exa.py search "<Name> youtube channel"
 ```
 
 ### Channel metadata
@@ -24,7 +24,7 @@ bash skills/osint/scripts/exa.sh search "<Name> youtube channel"
 # Fetch channel page - subscriber count, video count, about
 web_fetch "https://www.youtube.com/@<handle>"
 # Or channel page
-bash skills/osint/scripts/jina.sh read "https://www.youtube.com/@<handle>/about"
+python3 scripts/jina.py read "https://www.youtube.com/@<handle>/about"
 ```
 
 ### Transcript extraction (CRITICAL)
@@ -33,12 +33,12 @@ Pick 3-5 most viewed or most recent videos. Extract transcripts:
 # Fetch video page - title, description, comments
 web_fetch "https://www.youtube.com/watch?v=<id>"
 # Get auto-generated transcript via Jina
-bash skills/osint/scripts/jina.sh read "https://www.youtube.com/watch?v=<id>"
+python3 scripts/jina.py read "https://www.youtube.com/watch?v=<id>"
 ```
 
 If transcripts unavailable via fetch, try:
 ```bash
-bash skills/osint/scripts/brightdata.sh scrape "https://www.youtube.com/watch?v=<id>"
+python3 scripts/brightdata.py scrape "https://www.youtube.com/watch?v=<id>"
 ```
 
 ### What to extract from YouTube:
@@ -60,7 +60,7 @@ bash skills/osint/scripts/brightdata.sh scrape "https://www.youtube.com/watch?v=
 Search for podcast appearances:
 ```bash
 web_search "<Name> podcast interview"
-bash skills/osint/scripts/exa.sh search "<Name> podcast episode guest"
+python3 scripts/exa.py search "<Name> podcast episode guest"
 ```
 
 Podcast interviews are gold - the host asks personal questions.
@@ -70,9 +70,9 @@ Look for: origin story, career pivots, failures mentioned, mentors named.
 
 ```bash
 web_fetch "<personal-site>"
-bash skills/osint/scripts/jina.sh read "<blog-url>"
+python3 scripts/jina.py read "<blog-url>"
 # Crawl multiple pages
-bash skills/osint/scripts/exa.sh crawl "<blog-url>"
+python3 scripts/exa.py crawl "<blog-url>"
 ```
 
 Extract: writing style, topics, frequency, tone evolution over time.

package/osint-agent-package/skills/bmad-osint-investigate/osint/references/platforms.md

@@ -59,7 +59,7 @@
 
 **Finding channels:**
 - Brave: `site:youtube.com "<Name>" channel`
-- Exa: `exa.sh search "<Name> youtube"`
+- Exa: `exa.py search "<Name> youtube"`
 - Check LinkedIn/Instagram bios for YouTube links
 
 **Key signals:**
@@ -77,7 +77,7 @@ See `references/content-extraction.md`. 3-5 transcripts minimum when channel fou
 
 **Finding appearances:**
 - Brave: `"<Name>" podcast interview guest`
-- Exa: `exa.sh search "<Name> podcast episode"`
+- Exa: `exa.py search "<Name> podcast episode"`
 
 **Key signals:**
 - Personal questions from host → origin story, failures, mentors