Add module tools: setup skill, config system, and builder updates

.github/workflows/publish.yaml

@@ -3,7 +3,7 @@ name: Publish to NPM
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 permissions:
   contents: read
@@ -18,8 +18,8 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies
         run: npm install

.github/workflows/quality.yaml

@@ -1,13 +1,9 @@
 name: Quality & Validation
 
-# Runs comprehensive quality checks on all PRs:
+# Runs quality checks on all PRs:
 # - Prettier (formatting)
-# - ESLint (linting)
 # - markdownlint (markdown quality)
-# - Schema validation (YAML structure)
-# - Agent schema tests (fixture-based validation)
-# - Installation component tests (compilation)
-# - Bundle validation (web bundle integrity)
+# - Documentation build
 
 "on":
   pull_request:
@@ -33,24 +29,6 @@ jobs:
       - name: Prettier format check
         run: npm run format:check
 
-  eslint:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: ".nvmrc"
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: ESLint
-        run: npm run lint
-
   markdownlint:
     runs-on: ubuntu-latest
     steps:
@@ -89,30 +67,3 @@ jobs:
 
       - name: Build documentation
         run: npm run docs:build
-
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: ".nvmrc"
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Validate YAML schemas
-        run: npm run validate:schemas
-
-      - name: Run agent schema validation tests
-        run: npm run test:schemas
-
-      - name: Test agent compilation components
-        run: npm run test:install
-
-      - name: Validate file references
-        run: npm run validate:refs

.gitignore

@@ -18,6 +18,7 @@ build/*.txt
 
 # Environment variables
 .env
+.ruff*
 
 # Python
 __pycache__/

.markdownlint-cli2.yaml

@@ -7,6 +7,7 @@ ignores:
   - CODE_OF_CONDUCT.md
   - _bmad/**
   - _bmad*/**
+  - src/skills/**
   - .*/**
   - z*/**
 

CHANGELOG.md

@@ -14,7 +14,7 @@
 
 ### Removed
 
-- Obsolete sample and manifest files from old skill structure
+- Obsolete sample files from old skill structure
 - Unneeded images from project root
 
 ## [1.0.0] - 2026-03-15

docs/explanation/index.md

@@ -12,6 +12,7 @@ Create world-class AI agents and workflows with the BMad Builder.
 | **[What Are Skills](/explanation/what-are-skills.md)** | The universal building block for everything BMad produces |
 | **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities and memory |
 | **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and utilities |
+| **[Module Configuration](/explanation/module-configuration.md)** | How modules handle user configuration and help registration through a setup skill |
 
 ## Design Patterns
 
@@ -26,5 +27,4 @@ Create world-class AI agents and workflows with the BMad Builder.
 | Resource | Description |
 |----------|-------------|
 | **[Builder Commands](/reference/builder-commands.md)** | All capabilities, modes, and phases for both builders |
-| **[Skill Manifest](/reference/bmad-skill-manifest.md)** | Field reference for bmad-manifest.json |
 | **[Workflow Patterns](/reference/workflow-patterns.md)** | Skill types, structure patterns, and execution models |

docs/explanation/module-configuration.md

@@ -0,0 +1,124 @@
+---
+title: "Module Configuration and the Setup Skill"
+description: How BMad modules handle user configuration through a setup skill, when to use configuration vs. alternatives, and how to register with the help system
+---
+
+Every BMad module can include a **setup skill** that collects user preferences and registers the module's capabilities with the help system. The BMad Builder module's own setup skill (`bmad-builder-setup`) is the reference implementation.
+
+## When You Need Configuration
+
+Most modules should not need configuration at all. Before adding configurable values, consider whether a simpler alternative exists.
+
+| Approach | When to Use |
+| -------- | ----------- |
+| **Sensible defaults** | The variable has one clearly correct answer for most users that could be overridden or updated by the specific skill that needs it the first time it runs |
+| **Agent memory** | Your module follows the agent pattern and the agent can learn preferences through conversation |
+| **Configuration** | The value genuinely varies across projects and cannot be inferred at runtime |
+
+:::tip[Standalone Skills and Agents]
+If you are building a standalone agent or skill — not a multi-capability module — the setup skill overhead is not worth it. A concise overview section at the top of your SKILL.md body, clear comments in script headers, and `--help` flags on any CLI tools give users everything they need to discover and use the skill.
+:::
+
+## What the Setup Skill Does
+
+A setup skill serves two purposes:
+
+| Purpose | What Happens |
+| ------- | ------------ |
+| **Configuration** | Collects user preferences and writes them to shared config files |
+| **Help registration** | Adds the module's capabilities to the project-wide help system so users can discover them |
+
+## Configuration Files
+
+Setup skills write to three files in `{project-root}/_bmad/`:
+
+| File | Scope | Contains |
+| ---- | ----- | -------- |
+| `config.yaml` | Shared, committed to git | Core settings at root level, plus a section per module with metadata and module-specific values |
+| `config.user.yaml` | Personal, gitignored | User-only settings like `user_name` and `communication_language` |
+| `module-help.csv` | Shared, committed to git | One row per capability the module exposes |
+
+Core settings (like `output_folder` and `document_output_language`) live at the root of `config.yaml` and are shared across all modules. Each module also gets its own section keyed by its module code.
+
+## The module.yaml File
+
+Each module declares its identity and configurable variables in an `assets/module.yaml` inside the setup skill. This file drives both the prompts shown to the user and the values written to config.
+
+```yaml
+code: mymod
+name: "My Module"
+description: "What this module does"
+module_version: 1.0.0
+default_selected: false
+module_greeting: >
+  Welcome message shown after setup completes.
+
+my_output_folder:
+  prompt: "Where should output be saved?"
+  default: "{project-root}/_bmad-output/my-module"
+  result: "{project-root}/{value}"
+```
+
+Variables with a `prompt` field are presented to the user during setup. The `default` value is used when the user accepts defaults. Adding `user_setting: true` to a variable routes it to `config.user.yaml` instead of the shared config.
+
+:::caution[Literal Token]
+`{project-root}` is a literal token in config values. Never substitute it with an actual path. It signals to the consuming tool that the value is relative to the project root.
+:::
+
+## Help Registration Without Configuration
+
+You may not need any configurable values but still want to register your module with the help system. This is worth doing when:
+
+- The skill description in SKILL.md frontmatter cannot fully convey what the module offers while staying concise
+- You want to express capability sequencing, phase constraints, or other metadata the CSV supports
+- An agent has many internal capabilities that users should be able to discover
+- Your module has more than about three distinct things it can do
+
+For simpler cases, these alternatives are often sufficient:
+
+| Alternative | What It Provides |
+| ----------- | ---------------- |
+| **SKILL.md overview section** | A concise summary at the top of the skill body — the `--help` system scans this section to present user-facing help, so keep it succinct |
+| **Script header comments** | Describe purpose, usage, and flags at the top of each script |
+
+If these cover your discoverability needs, you can skip the setup skill entirely.
+
+## The module-help.csv File
+
+The CSV asset registers the module's capabilities with the help system. Each row describes one capability that users can discover and invoke.
+
+```csv
+module,agent-name,skill-name,display-name,menu-code,capability,args,description,...
+mymod,,my-skill,My Skill,MS,build-process,,"Does something useful.",...
+```
+
+When the setup skill runs, it merges these rows into the project-wide `_bmad/module-help.csv`, replacing any existing rows for this module. This is how users find your module's commands through the help system.
+
+## Anti-Zombie Pattern
+
+Both merge scripts use an anti-zombie pattern: before writing new values for a module, they remove all existing entries for that module's code. This prevents stale configuration or help entries from persisting across module updates. Running setup a second time is always safe.
+
+## Design Guidance
+
+Configuration is for **basic, project-level settings** — output folders, language preferences, feature toggles. Keep the number of configurable values small.
+
+| Pattern | Configuration Role |
+| ------- | ------------------ |
+| **Agent pattern** | Prefer agent memory for per-user preferences. Use config only for values that must be shared across the project |
+| **Workflow pattern** | Use config for output locations and behavior switches that vary across projects |
+| **Skill-only pattern** | Use config sparingly. If the skill works with sensible defaults, skip config entirely |
+
+Extensive workflow customization — step overrides, conditional branching, template selection — is a separate concern and will be covered in a dedicated document.
+
+## Upcoming Tooling
+
+A module scaffolding tool is planned that will generate the setup skill as part of module creation, along with the marketplace manifest format. Until then, use the BMad Builder module's setup skill as a reference implementation.
+
+Once available, you will be able to generate a setup skill from your existing collection of agents, workflows, and skills with a prompt like:
+
+:::note[Example]
+"Create a setup skill for my module in `./my-module-skills/` that mirrors `bmad-builder-setup` — with its own module name and code (my cool module, mcm), config variables for output folder locations, and help entries inferred from the existing skills in the folder."
+:::
+
+A decent LLM will clone the entire `bmad-builder-setup` skill components amd structure — SKILL.md, scripts, tests — updating only the skill name, description, and the two asset files (`module.yaml` and `module-help.csv`) to reflect your module.
+Take the time to ensure the description that triggers it is correct, along with the module.yaml and module-help.csv

docs/explanation/what-are-bmad-agents.md

@@ -19,7 +19,7 @@ Together these create something that feels less like running a command and more
 
 ## How Memory Works
 
-When an agent launches for the first time in a project, it creates a sidecar memory directory at `_bmad/bmad-memory/<agent-name>/`. On every subsequent launch the agent loads this memory, which is how it remembers your preferences, prior decisions, and anything you told it to retain.
+When an agent launches for the first time in a project, it can create a sidecar memory directory at `_bmad/memory/<agent-name>/`. On every subsequent launch the agent loads this memory, which is how it remembers your preferences, prior decisions, and anything you told it to retain.
 
 Agents can also include a **first-run onboarding** step — a set of questions the agent asks on initial launch so it can configure itself for your needs before you start working together.
 
@@ -42,14 +42,6 @@ You choose the mix when you design the agent. Internal commands keep everything
 
 Agents support a headless (autonomous) wake mode. When activated — for example through a cron job or an orchestrator like Open Claw — the agent skips waiting for user input and attempts to complete its tasks independently. This makes agents suitable for background automation while still being conversational when a human is present.
 
-## Registering With BMad Help
-
-Every agent carries a **manifest** that can declare where it fits in a larger workflow sequence. You specify what the agent should run *before*, what it should run *after*, whether it is required or optional, and what output artifact it produces. The BMad Help system reads these manifests so it can recommend the right agent at the right time.
-
-:::note[Example]
-You build a compliance-review agent and mark it as required before `create-architecture`. When a user asks BMad Help to start architecture, it notices the compliance artifact is missing and says: "Talk to the Compliance Review agent first — I don't see its output yet."
-:::
-
 ## When to Build an Agent vs. a Workflow
 
 | Choose an Agent When | Choose a Workflow When |

docs/explanation/what-are-skills.md

@@ -12,21 +12,14 @@ The BMad Builder produces skills that conform to the open standard and adds a fe
 | Component | Purpose |
 | --------- | ------- |
 | **SKILL.md** | The skill's instructions — persona, capabilities, and behavior rules |
-| **bmad-manifest.json** | Metadata for installation, discovery, sequencing, and BMad Help integration |
-| **prompts/** | Process prompts the skill loads at runtime |
 | **resources/** | Reference data, templates, and guidance documents |
 | **scripts/** | Deterministic validation and analysis scripts |
-| **agents/** | LLM subagent definitions for parallel processing |
 | **templates/** | Building blocks for generated output |
 
-Not every skill needs all of these. A simple utility might be a single `SKILL.md` with a manifest. A complex workflow or agent may use the full structure.
+Not every skill needs all of these. A simple utility might be a single `SKILL.md`. A complex workflow or agent may use the full structure.
 
 ## Ready to Use on Build
 
-Unlike earlier BMad versions that produced YAML and XML files requiring compilation, the builders now output a complete skill folder. Place it in your tool's skills directory — `.claude/skills`, `.codex/skills`, `.agent/skills`, or wherever your tool looks — and it is immediately usable.
-
-## Manifests and Sequencing
-
-Every skill's `bmad-manifest.json` can declare where it fits in a larger process. You specify what it runs **before**, what it runs **after**, whether it is **required** or **optional**, and what **output artifact** it produces. The BMad Help system reads these manifests to recommend the right skill at the right time and flag missing prerequisites.
+The builders output a complete skill folder. Place it in your tool's skills directory — `.claude/skills`, `.codex/skills`, `.agent/skills`, or wherever your tool looks — and it is immediately usable.
 
 See [What Are Agents](/explanation/what-are-bmad-agents.md) and [What Are Workflows](/explanation/what-are-workflows.md) for how agents and workflows each use this foundation differently.

docs/explanation/what-are-workflows.md

@@ -22,7 +22,7 @@ The BMad Builder classifies workflows into three tiers based on complexity.
 
 | Type | Description | Example |
 | ---- | ----------- | ------- |
-| **Simple Utility** | A single-purpose tool that does one thing well | Validate a manifest, convert a file format |
+| **Simple Utility** | A single-purpose tool that does one thing well | Validate a schema, convert a file format |
 | **Simple Workflow** | A short guided process with a few sequential steps | Create a quick tech spec |
 | **Complex Workflow** | A multi-stage process with branching paths, progressive disclosure, and potentially multiple outputs | Create and manage PRDs — covering create, edit, validate, convert, and polish |
 
@@ -51,14 +51,6 @@ Guided mode is no longer the slow multi-step process of earlier BMad versions. I
 
 Like agents, workflows can support a **Headless Mode**. When invoked headless — through a scheduler, orchestrator, or another skill — the workflow skips interactive prompts and completes its process end-to-end without waiting for user input.
 
-## Registering With BMad Help
-
-Workflows carry a **manifest** with sequencing metadata, just like agents. You declare what the workflow runs before, what it runs after, whether it is required or optional, and what output artifact it produces.
-
-:::note[Example]
-You build a `security-review` workflow and mark it as required after `create-prd` and before `create-architecture`. BMad Help will recommend it at the right point in the planning sequence and flag when its output artifact is missing.
-:::
-
 ## When to Build a Workflow vs. an Agent
 
 | Choose a Workflow When | Choose an Agent When |

docs/index.md

@@ -58,7 +58,7 @@ Build better skills with these guides distilled from real-world BMad development
 | ------- | ------- |
 | **[Concepts](/explanation/)** | What agents, workflows, and skills are — and how they relate |
 | **[Design Patterns](/explanation/#design-patterns)** | Progressive disclosure, subagent orchestration, authoring best practices |
-| **[Reference](/reference/)** | Manifest schema, builder commands, workflow patterns |
+| **[Reference](/reference/)** | Builder commands, workflow patterns |
 
 ## Community