bmad-method 6.0.0-alpha.8 → 6.0.1

package/docs/reference/testing.md

@@ -0,0 +1,106 @@
+---
+title: Testing Options
+description: Comparing the built-in QA agent (Quinn) with the Test Architect (TEA) module for test automation.
+sidebar:
+  order: 5
+---
+
+BMad provides two testing paths: a built-in QA agent for fast test generation and an installable Test Architect module for enterprise-grade test strategy.
+
+## Which Should You Use?
+
+| Factor | Quinn (Built-in QA) | TEA Module |
+| --- | --- | --- |
+| **Best for** | Small-medium projects, quick coverage | Large projects, regulated or complex domains |
+| **Setup** | Nothing to install -- included in BMM | Install separately via `npx bmad-method install` |
+| **Approach** | Generate tests fast, iterate later | Plan first, then generate with traceability |
+| **Test types** | API and E2E tests | API, E2E, ATDD, NFR, and more |
+| **Strategy** | Happy path + critical edge cases | Risk-based prioritization (P0-P3) |
+| **Workflow count** | 1 (Automate) | 9 (design, ATDD, automate, review, trace, and others) |
+
+:::tip[Start with Quinn]
+Most projects should start with Quinn. If you later need test strategy, quality gates, or requirements traceability, install TEA alongside it.
+:::
+
+## Built-in QA Agent (Quinn)
+
+Quinn is the built-in QA agent in the BMM (Agile suite) module. It generates working tests quickly using your project's existing test framework -- no configuration or additional installation required.
+
+**Trigger:** `QA` or `bmad-bmm-qa-automate`
+
+### What Quinn Does
+
+Quinn runs a single workflow (Automate) that walks through five steps:
+
+1. **Detect test framework** -- scans `package.json` and existing test files for your framework (Jest, Vitest, Playwright, Cypress, or any standard runner). If none exists, analyzes the project stack and suggests one.
+2. **Identify features** -- asks what to test or auto-discovers features in the codebase.
+3. **Generate API tests** -- covers status codes, response structure, happy path, and 1-2 error cases.
+4. **Generate E2E tests** -- covers user workflows with semantic locators and visible-outcome assertions.
+5. **Run and verify** -- executes the generated tests and fixes failures immediately.
+
+Quinn produces a test summary saved to your project's implementation artifacts folder.
+
+### Test Patterns
+
+Generated tests follow a "simple and maintainable" philosophy:
+
+- **Standard framework APIs only** -- no external utilities or custom abstractions
+- **Semantic locators** for UI tests (roles, labels, text rather than CSS selectors)
+- **Independent tests** with no order dependencies
+- **No hardcoded waits or sleeps**
+- **Clear descriptions** that read as feature documentation
+
+:::note[Scope]
+Quinn generates tests only. For code review and story validation, use the Code Review workflow (`CR`) instead.
+:::
+
+### When to Use Quinn
+
+- Quick test coverage for a new or existing feature
+- Beginner-friendly test automation without advanced setup
+- Standard test patterns that any developer can read and maintain
+- Small-medium projects where comprehensive test strategy is unnecessary
+
+## Test Architect (TEA) Module
+
+TEA is a standalone module that provides an expert agent (Murat) and nine structured workflows for enterprise-grade testing. It goes beyond test generation into test strategy, risk-based planning, quality gates, and requirements traceability.
+
+- **Documentation:** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
+- **Install:** `npx bmad-method install` and select the TEA module
+- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
+
+### What TEA Provides
+
+| Workflow | Purpose |
+| --- | --- |
+| Test Design | Create a comprehensive test strategy tied to requirements |
+| ATDD | Acceptance-test-driven development with stakeholder criteria |
+| Automate | Generate tests with advanced patterns and utilities |
+| Test Review | Validate test quality and coverage against strategy |
+| Traceability | Map tests back to requirements for audit and compliance |
+| NFR Assessment | Evaluate non-functional requirements (performance, security) |
+| CI Setup | Configure test execution in continuous integration pipelines |
+| Framework Scaffolding | Set up test infrastructure and project structure |
+| Release Gate | Make data-driven go/no-go release decisions |
+
+TEA also supports P0-P3 risk-based prioritization and optional integrations with Playwright Utils and MCP tooling.
+
+### When to Use TEA
+
+- Projects that require requirements traceability or compliance documentation
+- Teams that need risk-based test prioritization across many features
+- Enterprise environments with formal quality gates before release
+- Complex domains where test strategy must be planned before tests are written
+- Projects that have outgrown Quinn's single-workflow approach
+
+## How Testing Fits into Workflows
+
+Quinn's Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. A typical sequence:
+
+1. Implement a story with the Dev workflow (`DS`)
+2. Generate tests with Quinn (`QA`) or TEA's Automate workflow
+3. Validate implementation with Code Review (`CR`)
+
+Quinn works directly from source code without loading planning documents (PRD, architecture). TEA workflows can integrate with upstream planning artifacts for traceability.
+
+For more on where testing fits in the overall process, see the [Workflow Map](./workflow-map.md).

package/docs/reference/workflow-map.md

@@ -0,0 +1,122 @@
+---
+title: "Workflow Map"
+description: Visual reference for BMad Method workflow phases and outputs
+sidebar:
+  order: 1
+---
+
+The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that inform the next, so agents always know what to build and why.
+
+The rationale and concepts come from agile methodologies that have been used across the industry with great success as a mental framework.
+
+If at any time you are unsure what to do, the `/bmad-help` command will help you stay on track or know what to do next. You can always refer to this for reference also - but /bmad-help is fully interactive and much quicker if you have already installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added other complementary non-extension modules - the /bmad-help evolves to know all that is available to give you the best in-the-moment advice.
+
+Final important note: Every workflow below can be run directly with your tool of choice via slash command or by loading an agent first and using the entry from the agents menu.
+
+<iframe src="/workflow-map-diagram.html" title="BMad Method Workflow Map Diagram" width="100%" height="100%" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
+
+<p style="font-size: 0.8rem; text-align: right; margin-top: -0.5rem; margin-bottom: 1rem;">
+  <a href="/workflow-map-diagram.html" target="_blank" rel="noopener noreferrer">Open diagram in new tab ↗</a>
+</p>
+
+## Phase 1: Analysis (Optional)
+
+Explore the problem space and validate ideas before committing to planning.
+
+| Workflow               | Purpose                                                                    | Produces                  |
+| ---------------------- | -------------------------------------------------------------------------- | ------------------------- |
+| `brainstorming`        | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
+| `research`             | Validate market, technical, or domain assumptions                          | Research findings         |
+| `create-product-brief` | Capture strategic vision                                                   | `product-brief.md`        |
+
+## Phase 2: Planning
+
+Define what to build and for whom.
+
+| Workflow           | Purpose                                  | Produces     |
+| ------------------ | ---------------------------------------- | ------------ |
+| `create-prd`       | Define requirements (FRs/NFRs)           | `PRD.md`     |
+| `create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
+
+## Phase 3: Solutioning
+
+Decide how to build it and break work into stories.
+
+| Workflow                         | Purpose                                    | Produces                    |
+| -------------------------------- | ------------------------------------------ | --------------------------- |
+| `create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
+| `create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
+| `check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
+
+## Phase 4: Implementation
+
+Build it, one story at a time.
+
+| Workflow          | Purpose                                | Produces                      |
+| ----------------- | -------------------------------------- | ----------------------------- |
+| `sprint-planning` | Initialize tracking (once per project) | `sprint-status.yaml`          |
+| `create-story`    | Prepare next story for implementation  | `story-[slug].md`             |
+| `dev-story`       | Implement the story                    | Working code + tests          |
+| `automate` (QA)   | Generate tests for existing features   | Test suite                    |
+| `code-review`     | Validate implementation quality        | Approved or changes requested |
+| `correct-course`  | Handle significant mid-sprint changes  | Updated plan or re-routing    |
+| `retrospective`   | Review after epic completion           | Lessons learned               |
+
+**Quinn (QA Agent):** Built-in QA agent for test automation. Trigger with `QA` or `bmad-bmm-qa-automate`. Generates standard API and E2E tests using your project's test framework. Beginner-friendly, no configuration needed. For advanced test strategy, install [Test Architect (TEA)](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) module.
+
+## Quick Flow (Parallel Track)
+
+Skip phases 1-3 for small, well-understood work.
+
+| Workflow     | Purpose                                    | Produces                                      |
+| ------------ | ------------------------------------------ | --------------------------------------------- |
+| `quick-spec` | Define an ad-hoc change                    | `tech-spec.md` (story file for small changes) |
+| `quick-dev`  | Implement from spec or direct instructions | Working code + tests                          |
+
+## Context Management
+
+Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions.
+
+### Project Context
+
+:::tip[Recommended]
+Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows.
+:::
+
+**When to create it:**
+
+| Scenario | Approach |
+|----------|----------|
+| Before architecture (manual) | Document technical preferences you want the architect to respect |
+| After architecture | Generate it to capture decisions made during solutioning |
+| Existing projects | Run `generate-project-context` to discover established patterns |
+| Quick Flow | Create before `quick-dev` to ensure consistent implementation |
+
+**How to create it:**
+
+- **Manually** — Create `_bmad-output/project-context.md` with your technology stack and implementation rules
+- **Generate it** — Run `/bmad-bmm-generate-project-context` to auto-generate from your architecture or codebase
+
+**What workflows load it:**
+
+| Workflow | Purpose |
+|----------|---------|
+| `create-architecture` | Respects technical preferences when designing |
+| `create-story` | Informs story creation with project patterns |
+| `dev-story` | Guides implementation decisions |
+| `code-review` | Validates against project standards |
+| `quick-dev` | Applies patterns when implementing |
+
+[**Learn more about project-context.md**](../explanation/project-context.md)
+
+### Additional Context by Workflow
+
+Beyond `project-context.md`, each workflow loads specific documents:
+
+| Workflow | Also Loads |
+|----------|------------|
+| `create-story` | epics, PRD, architecture, UX |
+| `dev-story` | story file |
+| `code-review` | architecture, story file |
+| `quick-spec` | planning docs (if exist) |
+| `quick-dev` | tech-spec |

package/docs/tutorials/getting-started.md

@@ -0,0 +1,219 @@
+---
+title: "Getting Started"
+description: Install BMad and build your first project
+---
+
+Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
+
+## What You'll Learn
+
+- Install and initialize BMad Method for a new project
+- Choose the right planning track for your project size
+- Progress through phases from requirements to working code
+- Use agents and workflows effectively
+
+:::note[Prerequisites]
+- **Node.js 20+** — Required for the installer
+- **Git** — Recommended for version control
+- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
+- **A project idea** — Even a simple one works for learning
+:::
+
+:::tip[Quick Path]
+**Install** → `npx bmad-method install`
+**Plan** → PM creates PRD, Architect creates architecture
+**Build** → SM manages sprints, DEV implements stories
+**Fresh chats** for each workflow to avoid context issues.
+:::
+
+## Understanding BMad
+
+BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
+
+| Phase | Name           | What Happens                                        |
+| ----- | -------------- | --------------------------------------------------- |
+| 1     | Analysis       | Brainstorming, research, product brief *(optional)* |
+| 2     | Planning       | Create requirements (PRD or tech-spec)              |
+| 3     | Solutioning    | Design architecture *(BMad Method/Enterprise only)* |
+| 4     | Implementation | Build epic by epic, story by story                  |
+
+**[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
+
+Based on your project's complexity, BMad offers three planning tracks:
+
+| Track           | Best For                                               | Documents Created                      |
+| --------------- | ------------------------------------------------------ | -------------------------------------- |
+| **Quick Flow**  | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only                         |
+| **BMad Method** | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX                |
+| **Enterprise**  | Compliance, multi-tenant systems (30+ stories)         | PRD + Architecture + Security + DevOps |
+
+:::note
+Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
+:::
+
+## Installation
+
+Open a terminal in your project directory and run:
+
+```bash
+npx bmad-method install
+```
+
+When prompted to select modules, choose **BMad Method**.
+
+The installer creates two folders:
+- `_bmad/` — agents, workflows, tasks, and configuration
+- `_bmad-output/` — empty for now, but this is where your artifacts will be saved
+
+Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step.
+
+:::note[How to Load Agents and Run Workflows]
+Each workflow has a **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-pm` for the PM agent).
+:::
+
+:::caution[Fresh Chats]
+Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
+:::
+
+## Step 1: Create Your Plan
+
+Work through phases 1-3. **Use fresh chats for each workflow.**
+
+:::tip[Project Context (Optional)]
+Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
+
+Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `/bmad-bmm-generate-project-context`. [Learn more](../explanation/project-context.md).
+:::
+
+### Phase 1: Analysis (Optional)
+
+All workflows in this phase are optional:
+- **brainstorming** (`/bmad-brainstorming`) — Guided ideation
+- **research** (`/bmad-bmm-research`) — Market and technical research
+- **create-product-brief** (`/bmad-bmm-create-product-brief`) — Recommended foundation document
+
+### Phase 2: Planning (Required)
+
+**For BMad Method and Enterprise tracks:**
+1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat
+2. Run the `prd` workflow (`/bmad-bmm-create-prd`)
+3. Output: `PRD.md`
+
+**For Quick Flow track:**
+- Use the `quick-spec` workflow (`/bmad-bmm-quick-spec`) instead of PRD, then skip to implementation
+
+:::note[UX Design (Optional)]
+If your project has a user interface, load the **UX-Designer agent** (`/bmad-agent-bmm-ux-designer`) and run the UX design workflow (`/bmad-bmm-create-ux-design`) after creating your PRD.
+:::
+
+### Phase 3: Solutioning (BMad Method/Enterprise)
+
+**Create Architecture**
+1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat
+2. Run `create-architecture` (`/bmad-bmm-create-architecture`)
+3. Output: Architecture document with technical decisions
+
+**Create Epics and Stories**
+
+:::tip[V6 Improvement]
+Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
+:::
+
+1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat
+2. Run `create-epics-and-stories` (`/bmad-bmm-create-epics-and-stories`)
+3. The workflow uses both PRD and Architecture to create technically-informed stories
+
+**Implementation Readiness Check** *(Highly Recommended)*
+1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat
+2. Run `check-implementation-readiness` (`/bmad-bmm-check-implementation-readiness`)
+3. Validates cohesion across all planning documents
+
+## Step 2: Build Your Project
+
+Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
+
+### Initialize Sprint Planning
+
+Load the **SM agent** (`/bmad-agent-bmm-sm`) and run `sprint-planning` (`/bmad-bmm-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
+
+### The Build Cycle
+
+For each story, repeat this cycle with fresh chats:
+
+| Step | Agent | Workflow       | Command                    | Purpose                            |
+| ---- | ----- | -------------- | -------------------------- | ---------------------------------- |
+| 1    | SM    | `create-story` | `/bmad-bmm-create-story`  | Create story file from epic        |
+| 2    | DEV   | `dev-story`    | `/bmad-bmm-dev-story`     | Implement the story                |
+| 3    | DEV   | `code-review`  | `/bmad-bmm-code-review`   | Quality validation *(recommended)* |
+
+After completing all stories in an epic, load the **SM agent** (`/bmad-agent-bmm-sm`) and run `retrospective` (`/bmad-bmm-retrospective`).
+
+## What You've Accomplished
+
+You've learned the foundation of building with BMad:
+
+- Installed BMad and configured it for your IDE
+- Initialized a project with your chosen planning track
+- Created planning documents (PRD, Architecture, Epics & Stories)
+- Understood the build cycle for implementation
+
+Your project now has:
+
+```text
+your-project/
+├── _bmad/                                   # BMad configuration
+├── _bmad-output/
+│   ├── planning-artifacts/
+│   │   ├── PRD.md                           # Your requirements document
+│   │   ├── architecture.md                  # Technical decisions
+│   │   └── epics/                           # Epic and story files
+│   ├── implementation-artifacts/
+│   │   └── sprint-status.yaml               # Sprint tracking
+│   └── project-context.md                   # Implementation rules (optional)
+└── ...
+```
+
+## Quick Reference
+
+| Workflow                         | Command                                    | Agent     | Purpose                              |
+| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ |
+| `help`                           | `/bmad-help`                               | Any       | Get guidance on what to do next      |
+| `prd`                            | `/bmad-bmm-create-prd`                     | PM        | Create Product Requirements Document |
+| `create-architecture`            | `/bmad-bmm-create-architecture`            | Architect | Create architecture document         |
+| `generate-project-context`       | `/bmad-bmm-generate-project-context`       | Analyst   | Create project context file          |
+| `create-epics-and-stories`       | `/bmad-bmm-create-epics-and-stories`       | PM        | Break down PRD into epics            |
+| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion           |
+| `sprint-planning`                | `/bmad-bmm-sprint-planning`                | SM        | Initialize sprint tracking           |
+| `create-story`                   | `/bmad-bmm-create-story`                   | SM        | Create a story file                  |
+| `dev-story`                      | `/bmad-bmm-dev-story`                      | DEV       | Implement a story                    |
+| `code-review`                    | `/bmad-bmm-code-review`                    | DEV       | Review implemented code              |
+
+## Common Questions
+
+**Do I always need architecture?**
+Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
+
+**Can I change my plan later?**
+Yes. The SM agent has a `correct-course` workflow (`/bmad-bmm-correct-course`) for handling scope changes.
+
+**What if I want to brainstorm first?**
+Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `brainstorming` (`/bmad-brainstorming`) before starting your PRD.
+
+**Do I need to follow a strict order?**
+Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
+
+## Getting Help
+
+- **During workflows** — Agents guide you with questions and explanations
+- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
+- **Stuck?** — Run `help` (`/bmad-help`) to see what to do next
+
+## Key Takeaways
+
+:::tip[Remember These]
+- **Always use fresh chats** — Start a new chat for each workflow
+- **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
+- **Use `help` (`/bmad-help`) when stuck** — It detects your progress and suggests next steps
+:::
+
+Ready to start? Install BMad and let the agents guide you through your first project.

package/eslint.config.mjs

@@ -12,10 +12,30 @@ export default [
       'coverage/**',
       '**/*.min.js',
       'test/template-test-generator/**',
-      'test/template-test-generator/**/*.js',
-      'test/template-test-generator/**/*.md',
       'test/fixtures/**',
-      'test/fixtures/**/*.yaml',
+      '_bmad*/**',
+      // Build output
+      'build/**',
+      // Website uses ESM/Astro - separate linting ecosystem
+      'website/**',
+      // Gitignored patterns
+      'z*/**', // z-samples, z1, z2, etc.
+      '.claude/**',
+      '.codex/**',
+      '.github/chatmodes/**',
+      '.agent/**',
+      '.agentvibes/**',
+      '.kiro/**',
+      '.roo/**',
+      'test-project-install/**',
+      'sample-project/**',
+      'tools/template-test-generator/test-scenarios/**',
+      'src/modules/*/sub-modules/**',
+      '.bundler-temp/**',
+      // Augment vendor config — not project code, naming conventions
+      // are dictated by Augment and can't be changed, so exclude
+      // the entire directory from linting
+      '.augment/**',
     ],
   },
 
@@ -61,9 +81,9 @@ export default [
     },
   },
 
-  // CLI/CommonJS scripts under tools/** and test/**
+  // CLI scripts under tools/** and test/**
   {
-    files: ['tools/**/*.js', 'test/**/*.js'],
+    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js', 'test/**/*.mjs'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',
@@ -90,17 +110,7 @@ export default [
       'no-useless-catch': 'off',
       'unicorn/prefer-number-properties': 'off',
       'no-unreachable': 'off',
-    },
-  },
-
-  // Module installer scripts use CommonJS for compatibility
-  {
-    files: ['**/_module-installer/**/*.js'],
-    rules: {
-      // Allow CommonJS patterns for installer scripts
-      'unicorn/prefer-module': 'off',
-      'n/no-missing-require': 'off',
-      'n/no-unpublished-require': 'off',
+      'unicorn/text-encoding-identifier-case': 'off',
     },
   },
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-alpha.8",
+  "version": "6.0.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -25,60 +25,66 @@
   },
   "scripts": {
     "bmad:install": "node tools/cli/bmad-cli.js install",
-    "bmad:status": "node tools/cli/bmad-cli.js status",
-    "bundle": "node tools/cli/bundlers/bundle-web.js all",
-    "flatten": "node tools/flattener/main.js",
-    "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,md,yaml}\"",
-    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,md,yaml}\"",
+    "bmad:uninstall": "node tools/cli/bmad-cli.js uninstall",
+    "docs:build": "node tools/build-docs.mjs",
+    "docs:dev": "astro dev --root website",
+    "docs:fix-links": "node tools/fix-doc-links.js",
+    "docs:preview": "astro preview --root website",
+    "docs:validate-links": "node tools/validate-doc-links.js",
+    "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "format:fix:staged": "prettier --write",
     "install:bmad": "node tools/cli/bmad-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
-    "prepare": "husky",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
-    "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
-    "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
-    "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
-    "release:watch": "gh run watch",
-    "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run format:check",
+    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
+    "test:refs": "node test/test-file-refs-csv.js",
     "test:schemas": "node test/test-agent-schema.js",
-    "validate:bundles": "node tools/validate-bundles.js",
+    "validate:refs": "node tools/validate-file-refs.js",
     "validate:schemas": "node tools/validate-agent-schema.js"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
       "npm run lint:fix",
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.yaml": [
       "eslint --fix",
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
-    "*.{json,md}": [
-      "npm run format:fix"
+    "*.json": [
+      "npm run format:fix:staged"
+    ],
+    "*.md": [
+      "markdownlint-cli2"
     ]
   },
   "dependencies": {
+    "@clack/core": "^1.0.0",
+    "@clack/prompts": "^1.0.0",
     "@kayvan/markdown-tree-parser": "^1.6.1",
-    "boxen": "^5.1.2",
     "chalk": "^4.1.2",
-    "cli-table3": "^0.6.5",
     "commander": "^14.0.0",
     "csv-parse": "^6.1.0",
-    "figlet": "^1.8.0",
     "fs-extra": "^11.3.0",
     "glob": "^11.0.3",
     "ignore": "^7.0.5",
-    "inquirer": "^8.2.6",
     "js-yaml": "^4.1.0",
-    "ora": "^5.4.1",
+    "picocolors": "^1.1.1",
     "semver": "^7.6.3",
-    "wrap-ansi": "^7.0.0",
-    "xml2js": "^0.6.2"
+    "xml2js": "^0.6.2",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
+    "@astrojs/sitemap": "^3.6.0",
+    "@astrojs/starlight": "^0.37.5",
     "@eslint/js": "^9.33.0",
+    "astro": "^5.16.0",
     "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
@@ -86,13 +92,14 @@
     "eslint-plugin-unicorn": "^60.0.0",
     "eslint-plugin-yml": "^1.18.0",
     "husky": "^9.1.7",
-    "jest": "^30.0.4",
+    "jest": "^30.2.0",
     "lint-staged": "^16.1.1",
-    "prettier": "^3.5.3",
+    "markdownlint-cli2": "^0.19.1",
+    "prettier": "^3.7.4",
     "prettier-plugin-packagejson": "^2.5.19",
+    "sharp": "^0.33.5",
     "yaml-eslint-parser": "^1.2.3",
-    "yaml-lint": "^1.7.0",
-    "zod": "^4.1.12"
+    "yaml-lint": "^1.7.0"
   },
   "engines": {
     "node": ">=20.0.0"