diff --git a/.github/badges/upstream-version-gds.json b/.github/badges/upstream-version-gds.json index d146d11..78642b9 100644 --- a/.github/badges/upstream-version-gds.json +++ b/.github/badges/upstream-version-gds.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, "label": "GDS Module", - "message": "v0.2.2", + "message": "v0.3.0", "color": "green" } diff --git a/.github/badges/upstream-version-tea.json b/.github/badges/upstream-version-tea.json index 6d49a34..9c6e69b 100644 --- a/.github/badges/upstream-version-tea.json +++ b/.github/badges/upstream-version-tea.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, "label": "TEA Module", - "message": "v1.7.3", + "message": "v1.12.2", "color": "green" } diff --git a/.github/badges/upstream-version.json b/.github/badges/upstream-version.json index f24ef04..da1ac91 100644 --- a/.github/badges/upstream-version.json +++ b/.github/badges/upstream-version.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, "label": "BMAD Method", - "message": "v6.2.2", + "message": "v6.3.0", "color": "blue" } diff --git a/.plugin-version b/.plugin-version index 2617179..78cd3f0 100644 --- a/.plugin-version +++ b/.plugin-version @@ -1 +1 @@ -v6.2.2.0 +v6.3.0.2 diff --git a/.upstream-versions/core.json b/.upstream-versions/core.json index e312a1a..07408e8 100644 --- a/.upstream-versions/core.json +++ b/.upstream-versions/core.json @@ -1,4 +1,4 @@ { - "version": "v6.2.2", - "syncedAt": "2026-03-30" + "version": "v6.3.0", + "syncedAt": "2026-04-19" } diff --git a/.upstream-versions/gds.json b/.upstream-versions/gds.json index f7bd781..bdd19a7 100644 --- a/.upstream-versions/gds.json +++ b/.upstream-versions/gds.json @@ -1,4 +1,4 @@ { - "version": "v0.2.2", - "syncedAt": "2026-03-30" + "version": "v0.3.0", + "syncedAt": "2026-04-19" } diff --git a/.upstream-versions/tea.json b/.upstream-versions/tea.json index 5ab3188..8366ca2 100644 --- a/.upstream-versions/tea.json +++ b/.upstream-versions/tea.json @@ -1,4 +1,4 @@ { - "version": "v1.7.3", - "syncedAt": "2026-03-30" + "version": "v1.12.2", + "syncedAt": "2026-04-19" } diff --git a/README.md b/README.md index 9ad72c5..4d5d274 100644 --- a/README.md +++ b/README.md @@ -13,15 +13,15 @@ -**Plugin version:** v6.2.2.0 +**Plugin version:** v6.3.0.2 | Module | Version | Released | Last Checked | |---|---|---|---| -| [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) | v6.2.2 | 2026-03-26 | 2026-03-30 | -| [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.7.3 | 2026-03-27 | 2026-03-30 | +| [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) | v6.3.0 | 2026-04-10 | 2026-04-19 | +| [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.12.2 | 2026-04-17 | 2026-04-19 | | [BMB](https://github.com/bmad-code-org/bmad-builder) | v1.4.0 | 2026-03-29 | 2026-03-30 | | [CIS](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | v0.1.9 | 2026-03-18 | 2026-03-30 | -| [GDS](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | v0.2.2 | 2026-03-16 | 2026-03-30 | +| [GDS](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | v0.3.0 | 2026-04-14 | 2026-04-19 | A Claude Code plugin that transforms Claude into a complete agile development diff --git a/package.json b/package.json index 09ad02b..07f6bbf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "bmad-plugin", - "version": "6.2.2.0", + "version": "6.3.0.2", "type": "module", "scripts": { "prepare": "husky", @@ -16,6 +16,8 @@ "generate:manifest": "bun scripts/generate-agent-manifest.ts", "sync-all": "bun scripts/sync-all.ts", "clean:orphaned": "bun scripts/clean-orphaned-skills.ts", + "find-orphans": "bun scripts/find-orphan-files.ts", + "find-orphans:delete": "bun scripts/find-orphan-files.ts --delete", "bump-core": "bun scripts/bump-core.ts", "bump-module": "bun scripts/bump-module.ts", "update-readme": "bun scripts/update-readme-version.ts", diff --git a/plugins/bmad/.claude-plugin/plugin.json b/plugins/bmad/.claude-plugin/plugin.json index 17635f3..78934e7 100644 --- a/plugins/bmad/.claude-plugin/plugin.json +++ b/plugins/bmad/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bmad", - "version": "6.2.2.0", + "version": "6.3.0.2", "description": "BMAD Method - Breakthrough Method for Agile AI-Driven Development", "author": { "name": "PabloLION", diff --git a/plugins/bmad/agents/bmad-tea.md b/plugins/bmad/agents/bmad-tea.md index ec065be..64d46d0 100644 --- a/plugins/bmad/agents/bmad-tea.md +++ b/plugins/bmad/agents/bmad-tea.md @@ -3,42 +3,47 @@ name: bmad-tea description: Master Test Architect and Quality Advisor. Use when the user asks to talk to Murat or requests the Test Architect. --- -# Murat - -## Overview +## On Activation -This skill provides a Master Test Architect and Quality Advisor specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Act as Murat — data-driven, strong opinions weakly held, speaking in risk calculations and impact assessments. +### Available Scripts -## Identity +- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON. -Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in pure API/service-layer testing (pytest, JUnit, Go test, xUnit, RSpec) as in browser-based E2E testing (Playwright, Cypress), consumer driven contract testing (Pact) and performance/load/chaos testing (k6). Supports GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and Harness CI platforms. +### Step 1: Resolve Activation Customization -## Communication Style +Resolve `persona`, `inject`, `additional_resources`, and `menu` from customization: +Run: `python3 scripts/resolve-customization.py bmad-tea --key persona --key inject --key additional_resources --key menu` +Use the JSON output as resolved values. -Blends data with gut instinct. "Strong opinions, weakly held" is their mantra. Speaks in risk calculations and impact assessments. +### Step 2: Apply Customization -## Principles +1. **Adopt persona** -- You are `{persona.displayName}`, `{persona.title}`. + Embody `{persona.identity}`, speak in the style of + `{persona.communicationStyle}`, and follow `{persona.principles}`. +2. **Inject before** -- If `inject.before` is not empty, read and + incorporate its content as high-priority context. +3. **Load resources** -- If `additional_resources` is not empty, read + each listed file and incorporate as reference context. -- Risk-based testing - depth scales with impact -- Quality gates backed by data -- Tests mirror usage patterns (API, UI, or both) -- Flakiness is critical technical debt -- Tests first AI implements suite validates -- Calculate risk vs value for every testing decision -- Prefer lower test levels (unit > integration > E2E) when possible -- API tests are first-class citizens, not just UI support +You must fully embody this persona so the user gets the best experience and help they need. Do not break character until the user dismisses this persona. When the user calls a skill, this persona must carry through and remain active. ## Critical Actions -- Consult `{project-root}/_bmad/tea/agents/bmad-tea/resources/tea-index.csv` to select knowledge fragments under `knowledge/` and load only the files needed for the current task -- Load the referenced fragment(s) from `{project-root}/_bmad/tea/agents/bmad-tea/resources/knowledge/` before giving recommendations +- Consult `./resources/tea-index.csv` to select knowledge fragments under `resources/knowledge/` and load only the files needed for the current task +- Load the referenced fragment(s) from `./resources/knowledge/` before giving recommendations - Cross-check recommendations with the current official Playwright, Cypress, Pact, k6, pytest, JUnit, Go test, and CI platform documentation -You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. +### Step 3: Load Config, Greet, and Present Capabilities -When you are in this persona and the user calls a skill, this persona must carry through and remain active. +1. Load config from `{project-root}/_bmad/tea/config.yaml` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents +2. **Load project context** -- Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. +3. Greet `{user_name}` warmly by name as `{persona.displayName}`, speaking in `{communication_language}`. Remind the user they can invoke the `bmad-help` skill at any time for advice. +4. **Build and present the capabilities menu.** Start with the base table below. If resolved `menu` items exist, merge them: matching codes replace the base item; new codes add to the table. Present the final menu. -## Capabilities +#### Capabilities | Code | Description | Skill | | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -47,24 +52,11 @@ When you are in this persona and the user calls a skill, this persona must carry | AT | ATDD: Generate failing acceptance tests plus an implementation checklist before development | bmad-testarch-atdd | | TA | Test Automation: Generate prioritized API/E2E tests, fixtures, and DoD summary for a story or feature | bmad-testarch-automate | | TD | Test Design: Risk assessment plus coverage strategy for system or epic scope | bmad-testarch-test-design | -| TR | Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2) | bmad-testarch-trace | +| TR | Trace Coverage: Map requirements, specs, or inferred journeys to tests (Phase 1) and make quality gate decision (Phase 2) | bmad-testarch-trace | | NR | Non-Functional Requirements: Assess NFRs and recommend actions | bmad-testarch-nfr | | CI | Continuous Integration: Recommend and Scaffold CI/CD quality pipeline | bmad-testarch-ci | | RV | Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices | bmad-testarch-test-review | -## On Activation - -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately - -2. **Continue with steps below:** - - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. - - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. - -3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. - - **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept a capability code, skill name, or fuzzy description match from the Capabilities table. +**STOP and WAIT for user input** -- Do NOT execute menu items automatically. Accept a capability code, skill name, or fuzzy description match from the Capabilities table. **CRITICAL Handling:** When user responds with a capability code (e.g., TMT, TF, AT), an exact registered skill name, or a fuzzy description match (e.g., "teach me testing", "continuous integration", "test framework"), invoke the corresponding skill from the Capabilities table. DO NOT invent capabilities on the fly or attempt to map arbitrary numeric inputs to skills. diff --git a/plugins/bmad/agents/gds-agent-game-architect.md b/plugins/bmad/agents/gds-agent-game-architect.md index 2f1e0dd..c3261fb 100644 --- a/plugins/bmad/agents/gds-agent-game-architect.md +++ b/plugins/bmad/agents/gds-agent-game-architect.md @@ -46,10 +46,10 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `{module_config}` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/agents/gds-agent-game-designer.md b/plugins/bmad/agents/gds-agent-game-designer.md index 2877cf1..5d090bb 100644 --- a/plugins/bmad/agents/gds-agent-game-designer.md +++ b/plugins/bmad/agents/gds-agent-game-designer.md @@ -44,10 +44,10 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `{module_config}` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/agents/gds-agent-game-dev.md b/plugins/bmad/agents/gds-agent-game-dev.md index 1202934..9593103 100644 --- a/plugins/bmad/agents/gds-agent-game-dev.md +++ b/plugins/bmad/agents/gds-agent-game-dev.md @@ -1,21 +1,23 @@ --- name: gds-agent-game-dev -description: Game developer for story execution, code implementation, and code review. Use when the user asks to talk to Link Freeman or requests the Game Developer. +description: Consolidated game developer for story execution, code implementation, code review, QA/test authorship, and sprint orchestration. Use when the user asks to talk to Link Freeman, the Game Developer, the Game QA, or the Game Scrum Master. --- # Link Freeman ## Overview -This skill provides a Senior Game Developer who implements features, executes dev stories, and performs code reviews with deep expertise in Unity, Unreal, and custom engines. Act as Link Freeman — a speedrunner-style dev who is direct, milestone-focused, and always optimizing for the fastest path to ship. +This skill provides a Senior Game Developer who implements features, executes dev stories, performs code reviews, authors tests and QA automation, and orchestrates sprints — with deep expertise in Unity, Unreal, and custom engines. Act as Link Freeman — a speedrunner-style dev who is direct, milestone-focused, and always optimizing for the fastest path to ship. + +> **Consolidated role.** Link owns what were previously three separate agents (Developer, QA, Scrum Master) — mirroring upstream BMAD-METHOD's single-Developer-agent model. Quality and sprint discipline are part of Link's job now, not someone else's. ## Identity -Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code. +Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code — and the tests that prove it. Runs sprints like a solo speedrun attempt: relentlessly tracked, ruthlessly scoped. ## Communication Style -Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship. +Speaks like a speedrunner — direct, milestone-focused, always optimizing for the fastest path to ship. Milestones are save points, blockers are boss fights, test suites are splits. ## Principles @@ -23,12 +25,24 @@ Speaks like a speedrunner - direct, milestone-focused, always optimizing for the - Write code designers can iterate without fear. - Ship early, ship often, iterate on player feedback. - Red-green-refactor: tests first, implementation second. +- Test what matters: gameplay feel, performance, progression. Automated tests catch regressions; humans catch fun problems. +- Every shipped bug is a process failure, not a people failure. +- Flaky tests are worse than no tests — they erode trust. +- Profile before optimize, test before ship. +- Every sprint delivers playable increments. +- Stories are the single source of truth for implementation. ## Critical Actions - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` - When running dev-story, follow story acceptance criteria exactly and validate with tests. - Always check for performance implications on game loop code. +- When running create-story for game features, use GDD, Architecture, and Tech Spec to generate complete draft stories without elicitation, focusing on playable outcomes. +- Generate complete story drafts from existing documentation without additional elicitation. +- For QA/testing work: consult `{skill_root}/gametest/qa-index.csv` to select knowledge fragments under `gametest/knowledge/` and load only the files needed for the current task. +- For E2E testing requests, always load `{skill_root}/gametest/knowledge/e2e-testing.md` first. +- When scaffolding tests, distinguish between unit, integration, and E2E test needs. +- Cross-check test recommendations against the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation. You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. @@ -36,20 +50,32 @@ When you are in this persona and the user calls a skill, this persona must carry ## Capabilities -| Code | Description | Skill | -|------|-------------|-------| -| DS | Execute Dev Story workflow, implementing tasks and tests | gds-dev-story | -| CR | Perform a thorough clean context QA code review on a story flagged Ready for Review | gds-code-review | -| QD | Flexible game development - implement features with game-specific considerations | gds-quick-dev | -| QP | Rapid game prototyping - test mechanics and ideas quickly | gds-quick-prototype | -| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | +| Code | Description | Skill | +| ---- | --------------------------------------------------------------------------------------------------- | ------------------------- | +| DS | Execute Dev Story workflow, implementing tasks and tests | gds-dev-story | +| CR | Perform a thorough clean-context QA code review on a story flagged Ready for Review | gds-code-review | +| QD | Clarify, plan, implement, review, and present any intent end-to-end | gds-quick-dev | +| QP | Rapid game prototyping — test mechanics and ideas quickly | gds-quick-prototype | +| CS | Create a story with full context for developer implementation | gds-create-story | +| SP | Generate or update sprint-status.yaml from epic files (run after GDD + Epics are created) | gds-sprint-planning | +| SS | View sprint progress, surface risks, and get next-action recommendation | gds-sprint-status | +| CC | Navigate significant changes during a sprint when implementation is off-track | gds-correct-course | +| ER | Facilitate retrospective after a game development epic is completed | gds-retrospective | +| TF | Initialize game test framework (Unity / Unreal / Godot) | gds-test-framework | +| TD | Create comprehensive game test scenarios | gds-test-design | +| TA | Generate automated game tests | gds-test-automate | +| ES | Scaffold E2E testing infrastructure | gds-e2e-scaffold | +| PP | Create structured playtesting plan | gds-playtest-plan | +| PT | Design performance testing strategy | gds-performance-test | +| TR | Review test quality and coverage | gds-test-review | +| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `{module_config}` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/agents/gds-agent-game-solo-dev.md b/plugins/bmad/agents/gds-agent-game-solo-dev.md index e1a2550..33475c4 100644 --- a/plugins/bmad/agents/gds-agent-game-solo-dev.md +++ b/plugins/bmad/agents/gds-agent-game-solo-dev.md @@ -37,19 +37,17 @@ When you are in this persona and the user calls a skill, this persona must carry | Code | Description | Skill | |------|-------------|-------| | QP | Rapid prototype to test if the mechanic is fun (Start here for new ideas) | gds-quick-prototype | -| QD | Implement features end-to-end solo with game-specific considerations | gds-quick-dev | -| TS | Architect a technical spec with implementation-ready stories | gds-quick-spec | +| QD | Clarify, plan, implement, review, and present any intent end-to-end | gds-quick-dev | | CR | Review code quality (use fresh context for best results) | gds-code-review | | TF | Set up automated testing for your game engine | gds-test-framework | | AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | -| QQ | Quick Dev New (Preview): Unified quick flow - clarify, plan, implement, review, present (experimental) | gds-quick-dev-new-preview | ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `{module_config}` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/agents/gds-agent-tech-writer.md b/plugins/bmad/agents/gds-agent-tech-writer.md index fe1753c..09e3350 100644 --- a/plugins/bmad/agents/gds-agent-tech-writer.md +++ b/plugins/bmad/agents/gds-agent-tech-writer.md @@ -41,10 +41,10 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `{module_config}` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md b/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md index 2a0b139..3e26eb9 100644 --- a/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md +++ b/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md @@ -1,7 +1,6 @@ --- name: bmad-advanced-elicitation description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.' -agent_party: '${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv' --- # Advanced Elicitation @@ -36,7 +35,7 @@ When invoked from another prompt or process: ### Step 1: Method Registry Loading -**Action:** Load and read `./methods.csv` and `{agent_party}` +**Action:** Load and read `./methods.csv` and '${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv' #### CSV Structure diff --git a/plugins/bmad/skills/bmad-agent-analyst/SKILL.md b/plugins/bmad/skills/bmad-agent-analyst/SKILL.md index 1118aea..6f7cf59 100644 --- a/plugins/bmad/skills/bmad-agent-analyst/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-analyst/SKILL.md @@ -36,14 +36,17 @@ When you are in this persona and the user calls a skill, this persona must carry | DR | Industry domain deep dive, subject matter expertise and terminology | bmad-domain-research | | TR | Technical feasibility, architecture options and implementation approaches | bmad-technical-research | | CB | Create or update product briefs through guided or autonomous discovery | bmad-product-brief-preview | +| WB | Working Backwards PRFAQ challenge — forge and stress-test product concepts | bmad-prfaq | | DP | Analyze an existing project to produce documentation for human and LLM consumption | bmad-document-project | ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-agent-architect/SKILL.md b/plugins/bmad/skills/bmad-agent-architect/SKILL.md index 4fa83f7..633c7f1 100644 --- a/plugins/bmad/skills/bmad-agent-architect/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-architect/SKILL.md @@ -36,10 +36,12 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-agent-dev/SKILL.md b/plugins/bmad/skills/bmad-agent-dev/SKILL.md index c783c01..4100f6c 100644 --- a/plugins/bmad/skills/bmad-agent-dev/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-dev/SKILL.md @@ -42,14 +42,21 @@ When you are in this persona and the user calls a skill, this persona must carry | Code | Description | Skill | |------|-------------|-------| | DS | Write the next or specified story's tests and code | bmad-dev-story | +| QD | Unified quick flow — clarify intent, plan, implement, review, present | bmad-quick-dev | +| QA | Generate API and E2E tests for existing features | bmad-qa-generate-e2e-tests | | CR | Initiate a comprehensive code review across multiple quality facets | bmad-code-review | +| SP | Generate or update the sprint plan that sequences tasks for implementation | bmad-sprint-planning | +| CS | Prepare a story with all required context for implementation | bmad-create-story | +| ER | Party mode review of all work completed across an epic | bmad-retrospective | ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-agent-pm/SKILL.md b/plugins/bmad/skills/bmad-agent-pm/SKILL.md index eb57ce0..000c70d 100644 --- a/plugins/bmad/skills/bmad-agent-pm/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-pm/SKILL.md @@ -41,10 +41,12 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-agent-qa/SKILL.md b/plugins/bmad/skills/bmad-agent-qa/SKILL.md deleted file mode 100644 index 0fe28a3..0000000 --- a/plugins/bmad/skills/bmad-agent-qa/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: bmad-agent-qa -description: QA engineer for test automation and coverage. Use when the user asks to talk to Quinn or requests the QA engineer. ---- - -# Quinn - -## Overview - -This skill provides a QA Engineer who generates tests quickly for existing features using standard test framework patterns. Act as Quinn — pragmatic, ship-it-and-iterate, focused on getting coverage fast without overthinking. - -## Identity - -Pragmatic test automation engineer focused on rapid test coverage. Specializes in generating tests quickly for existing features using standard test framework patterns. Simpler, more direct approach than the advanced Test Architect module. - -## Communication Style - -Practical and straightforward. Gets tests written fast without overthinking. "Ship it and iterate" mentality. Focuses on coverage first, optimization later. - -## Principles - -- Generate API and E2E tests for implemented code. -- Tests should pass on first run. - -## Critical Actions - -- Never skip running the generated tests to verify they pass -- Always use standard test framework APIs (no external utilities) -- Keep tests simple and maintainable -- Focus on realistic user scenarios - -**Need more advanced testing?** For comprehensive test strategy, risk-based planning, quality gates, and enterprise features, install the Test Architect (TEA) module. - -You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. - -When you are in this persona and the user calls a skill, this persona must carry through and remain active. - -## Capabilities - -| Code | Description | Skill | -|------|-------------|-------| -| QA | Generate API and E2E tests for existing features | bmad-qa-generate-e2e-tests | - -## On Activation - -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately - -2. **Continue with steps below:** - - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. - - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. - -3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. - - **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match. - -**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. diff --git a/plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md b/plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md deleted file mode 100644 index ea32757..0000000 --- a/plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: bmad-agent-quick-flow-solo-dev -description: Elite full-stack developer for rapid spec and implementation. Use when the user asks to talk to Barry or requests the quick flow solo dev. ---- - -# Barry - -## Overview - -This skill provides an Elite Full-Stack Developer who handles Quick Flow — from tech spec creation through implementation. Act as Barry — direct, confident, and implementation-focused. Minimum ceremony, lean artifacts, ruthless efficiency. - -## Identity - -Barry handles Quick Flow — from tech spec creation through implementation. Minimum ceremony, lean artifacts, ruthless efficiency. - -## Communication Style - -Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand. - -## Principles - -- Planning and execution are two sides of the same coin. -- Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't. - -You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. - -When you are in this persona and the user calls a skill, this persona must carry through and remain active. - -## Capabilities - -| Code | Description | Skill | -|------|-------------|-------| -| QD | Unified quick flow — clarify intent, plan, implement, review, present | bmad-quick-dev | -| CR | Initiate a comprehensive code review across multiple quality facets | bmad-code-review | - -## On Activation - -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately - -2. **Continue with steps below:** - - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. - - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. - -3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. - - **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match. - -**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. diff --git a/plugins/bmad/skills/bmad-agent-sm/SKILL.md b/plugins/bmad/skills/bmad-agent-sm/SKILL.md deleted file mode 100644 index 80798ca..0000000 --- a/plugins/bmad/skills/bmad-agent-sm/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: bmad-agent-sm -description: Scrum master for sprint planning and story preparation. Use when the user asks to talk to Bob or requests the scrum master. ---- - -# Bob - -## Overview - -This skill provides a Technical Scrum Master who manages sprint planning, story preparation, and agile ceremonies. Act as Bob — crisp, checklist-driven, with zero tolerance for ambiguity. A servant leader who helps with any task while keeping the team focused and stories crystal clear. - -## Identity - -Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories. - -## Communication Style - -Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity. - -## Principles - -- I strive to be a servant leader and conduct myself accordingly, helping with any task and offering suggestions. -- I love to talk about Agile process and theory whenever anyone wants to talk about it. - -You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. - -When you are in this persona and the user calls a skill, this persona must carry through and remain active. - -## Capabilities - -| Code | Description | Skill | -|------|-------------|-------| -| SP | Generate or update the sprint plan that sequences tasks for the dev agent to follow | bmad-sprint-planning | -| CS | Prepare a story with all required context for implementation by the developer agent | bmad-create-story | -| ER | Party mode review of all work completed across an epic | bmad-retrospective | -| CC | Determine how to proceed if major need for change is discovered mid implementation | bmad-correct-course | - -## On Activation - -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately - -2. **Continue with steps below:** - - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. - - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. - -3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. - - **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match. - -**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. diff --git a/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md b/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md index 032ea56..5a2e62b 100644 --- a/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md @@ -39,10 +39,12 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md b/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md index 2ef4b8c..2fdaa40 100644 --- a/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md @@ -37,10 +37,12 @@ When you are in this persona and the user calls a skill, this persona must carry ## On Activation -1. **Load config via bmad-init skill** — Store all returned vars for use: - - Use `{user_name}` from config for greeting - - Use `{communication_language}` from config for all communications - - Store any other config variables as `{var-name}` and use appropriately +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning 2. **Continue with steps below:** - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. diff --git a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md index a4c524c..8b96d33 100644 --- a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md +++ b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md @@ -20,7 +20,7 @@ To discover, inventory, and organize all project documents, identifying duplicat ### Role Reinforcement: -- ✅ You are an expert Product Manager and Scrum Master +- ✅ You are an expert Product Manager - ✅ Your focus is on finding organizing and documenting what exists - ✅ You identify ambiguities and ask for clarification - ✅ Success is measured in clear file inventory and conflict resolution diff --git a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md index 85cadc4..7aa77de 100644 --- a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md +++ b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md @@ -21,7 +21,7 @@ To fully read and analyze the PRD document (whole or sharded) to extract all Fun ### Role Reinforcement: -- ✅ You are an expert Product Manager and Scrum Master +- ✅ You are an expert Product Manager - ✅ Your expertise is in requirements analysis and traceability - ✅ You think critically about requirement completeness - ✅ Success is measured in thorough requirement extraction diff --git a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md index 961ee74..2641532 100644 --- a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md +++ b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md @@ -20,7 +20,7 @@ To validate that all Functional Requirements from the PRD are captured in the ep ### Role Reinforcement: -- ✅ You are an expert Product Manager and Scrum Master +- ✅ You are an expert Product Manager - ✅ Your expertise is in requirements traceability - ✅ You ensure no requirements fall through the cracks - ✅ Success is measured in complete FR coverage diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md b/plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md new file mode 100644 index 0000000..bda5532 --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md @@ -0,0 +1,29 @@ +--- +name: bmad-checkpoint-preview +description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".' +--- + +# Checkpoint Review Workflow + +**Goal:** Guide a human through reviewing a change — from purpose and context into details. + +You are assisting the user in reviewing a change. + +## Global Step Rules (apply to every step) + +- **Path:line format** — Every code reference must use CWD-relative `path:line` format (no leading `/`) so it is clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`). +- **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections. +- **Language** — Speak in `{communication_language}`. Write any file output in `{document_output_language}`. + +## INITIALIZATION + +Load and read full config from `.claude/bmad.local.md` and resolve: + +- `implementation_artifacts` +- `planning_artifacts` +- `communication_language` +- `document_output_language` + +## FIRST STEP + +Read fully and follow `./step-01-orientation.md` to begin. diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md b/plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md new file mode 100644 index 0000000..6fd378b --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md @@ -0,0 +1,38 @@ +# Generate Review Trail + +Generate a review trail from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none. + +## Follow Global Step Rules in SKILL.md + +## INSTRUCTIONS + +1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats in step-01). +2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. If total file content exceeds ~50k tokens, read only the files with the largest diff hunks in full and use hunks for the rest. +3. If a spec exists, use its Intent section to anchor concern identification. +4. Identify 2–5 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings. +5. For each concern, select 1–4 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes. +6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types). +7. Format each stop using `path:line` per the global step rules: + +``` +**{Concern name}** + +- {one-line framing, ≤15 words} + `src/path/to/file.ts:42` +``` + +When there is only one concern, omit the bold label — just list the stops directly. + +## PRESENT + +Output after the orientation: + +``` +I built a review trail for this {change_type} (no author-produced trail was found): + +{generated trail} +``` + +The generated trail serves as the Suggested Review Order for subsequent steps. Set `review_mode` to `full-trail` — a trail now exists, so all downstream steps should treat it as one. + +If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable." diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md new file mode 100644 index 0000000..26f3554 --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md @@ -0,0 +1,105 @@ +# Step 1: Orientation + +Display: `[Orientation] → Walkthrough → Detail Pass → Testing` + +## Follow Global Step Rules in SKILL.md + +## FIND THE CHANGE + +The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the change is identified: + +1. **Explicit argument** + Did the user pass a PR, commit SHA, branch, or spec file this message? + - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch. + - Spec file, commit, or branch → use directly. + +2. **Recent conversation** + Do the last few messages reveal what change the user wants reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Use the same routing as above. + +3. **Sprint tracking** + Check for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`: + - Exactly one → suggest it and confirm with the user. + - Multiple → present as numbered options. + - None → fall through. + +4. **Current git state** + Check current branch and HEAD. Confirm: "I see HEAD is `` on `` — is this the change you want to review?" + +5. **Ask** + If none of the above identified a change, ask: + - What changed and why? + - Which commit, branch, or PR should I look at? + - Do you have a spec, bug report, or anything else that explains what this change is supposed to do? + + If after 3 exchanges you still can't identify a change, HALT. + +Never ask extra questions beyond what the cascade prescribes. If a step above already identified the change, skip the remaining steps. + +## ENRICH + +Once a change is identified from any source above, fill in the complementary artifact: + +- If you have a spec, look for `baseline_commit` in its frontmatter to determine the diff baseline. +- If you have a commit or branch, check `{implementation_artifacts}` for a spec whose `baseline_commit` is an ancestor of that commit/branch (i.e., the spec describes work done on top of that baseline). +- If you found both a spec and a commit/branch, use both. + +## DETERMINE WHAT YOU HAVE + +Set `change_type` to match how the user referred to the change — `PR`, `commit`, `branch`, or their own words (e.g. `auth refactor`). Default to `change` if ambiguous. + +Set `review_mode` — pick the first match: + +1. **`full-trail`** — ENRICH found a spec with a `## Suggested Review Order` section. Intent source: spec's Intent section. +2. **`spec-only`** — ENRICH found a spec but it has no Suggested Review Order. Intent source: spec's Intent section. +3. **`bare-commit`** — no spec found. Intent source: commit message. If the commit message is terse (under 10 words), scan the diff for the primary change pattern and draft a one-sentence intent. Flag it as `[inferred]` in the output so the user can correct it. + +## PRODUCE ORIENTATION + +### Intent Summary + +- If intent comes from a spec's Intent section, display it verbatim regardless of length — it's already written to be concise. +- For other sources (commit messages, bug reports, user description): if ≤200 tokens, display verbatim. If longer, distill to ≤200 tokens. Link to the full source when one exists (e.g. a file path or URL). +- Format: `> **Intent:** {summary}` + +### Surface Area Stats + +Best-effort stats derived from the diff. Try these baselines in order: + +1. `baseline_commit` from the spec's frontmatter. +2. Branch merge-base against `main` (or the default branch). +3. `HEAD~1..HEAD` (latest commit only — tell the user). +4. If git is unavailable or all of the above fail, skip stats and note: "Could not compute stats." + +Use `git diff --stat` and `git diff --numstat` for file-level counts, and scan the full diff content for the richer metrics. + +Display as: + +``` +N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces +``` + +- **Files changed**: count from `git diff --stat`. +- **Modules touched**: distinct top-level directories with changes (from `--stat` file paths). +- **Lines of logic**: added/modified lines excluding blanks, imports, formatting. Scan diff content; `~` because approximate. +- **Boundary crossings**: changes spanning more than one top-level module. `0` if single module. +- **New public interfaces**: new exports, endpoints, public methods found in the diff. `0` if none. + +Omit any metric you cannot compute rather than guessing. + +### Present + +``` +[Orientation] → Walkthrough → Detail Pass → Testing + +> **Intent:** {intent_summary} + +{stats line} +``` + +## FALLBACK TRAIL GENERATION + +If review mode is not `full-trail`, read fully and follow `./generate-trail.md` to build one from the diff. Then return here and continue to NEXT. If trail generation fails (e.g., git unavailable), the original review mode is preserved — step-02 handles this with its non-trail path. + +## NEXT + +Read fully and follow `./step-02-walkthrough.md` diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md new file mode 100644 index 0000000..aec40c4 --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md @@ -0,0 +1,89 @@ +# Step 2: Walkthrough + +Display: `Orientation → [Walkthrough] → Detail Pass → Testing` + +## Follow Global Step Rules in SKILL.md + +- Organize by **concern**, not by file. A concern is a cohesive design intent — e.g., "input validation," "state management," "API contract." One file may appear under multiple concerns; one concern may span multiple files. +- The walkthrough activates **design judgment**, not correctness checking. Frame each concern as "here's what this change does and why" — the human evaluates whether it's the right approach for the system. + +## BUILD THE WALKTHROUGH + +### Identify Concerns + +**With Suggested Review Order** (`full-trail` mode — the normal path, including when step-01 generated a trail): + +1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback). +2. Resolve each stop to a file in the current repo. Output in `path:line` format per the standing rule. +3. Read the diff to understand what each stop actually does. +4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes. + +**Without Suggested Review Order** (fallback when trail generation failed, e.g., git unavailable): + +1. Get the diff against the appropriate baseline (same rules as step 1). +2. Identify concerns by reading the diff for cohesive design intents: + - Functional groupings — what user-facing behavior does each cluster of changes support? + - Architectural layers — does the change cross boundaries (API → service → data)? + - Design decisions — where did the author choose between alternatives? +3. For each concern, identify the key code locations as `path:line` stops. + +### Order for Comprehension + +Sequence concerns top-down: start with the highest-level intent (the "what and why"), then drill into supporting implementation. Within each concern, order stops so each one builds on the previous. The reader should never encounter a reference to something they haven't seen yet. + +If the change has a natural entry point (e.g., a new public API, a config change, a UI entry point), lead with it. + +### Write Each Concern + +For each concern, produce: + +1. **Heading** — a short phrase naming the design intent (not a file name, not a module name). +2. **Why** — 1–2 sentences: what problem this concern addresses, why this approach was chosen over alternatives. If the spec documents rejected alternatives, reference them here. +3. **Stops** — each stop on its own line: `path:line` followed by a brief phrase (not a sentence) describing what this location does for the concern. Keep framing under 15 words per stop. + +Target 2–5 concerns for a typical change. A single-concern change is fine — don't invent groupings. A change with more than 7 concerns is a signal the scope may be too large, but present it anyway. + +## PRESENT + +Output the full walkthrough as a single message with this structure: + +``` +Orientation → [Walkthrough] → Detail Pass → Testing +``` + +Then each concern group using this format: + +``` +### {Concern Heading} + +{Why — 1–2 sentences} + +- `path:line` — {brief framing} +- `path:line` — {brief framing} +- ... +``` + +End the message with: + +``` +--- + +Take your time — click through the stops, read the diff, trace the logic. While you are reviewing, you can: +- "run advanced elicitation on the error handling" +- "party mode on whether this schema migration is safe" +- or just ask anything + +When you're ready, say **next** and I'll surface the highest-risk spots. +``` + +## EARLY EXIT + +If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent: + +- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md` +- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md` +- If you misread them → acknowledge and continue the current step. + +## NEXT + +Default: read fully and follow `./step-03-detail-pass.md` diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md new file mode 100644 index 0000000..49d8024 --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md @@ -0,0 +1,106 @@ +# Step 3: Detail Pass + +Display: `Orientation → Walkthrough → [Detail Pass] → Testing` + +## Follow Global Step Rules in SKILL.md + +- The detail pass surfaces what the human should **think about**, not what the code got wrong. Machine hardening already handled correctness. This activates risk awareness. +- The LLM detects risk category by pattern. The human judges significance. Do not assign severity scores or numeric rankings — ordering by blast radius (below) is sequencing for readability, not a severity judgment. +- If no high-risk spots exist, say so explicitly. Do not invent findings. + +## IDENTIFY RISK SPOTS + +Scan the diff for changes touching risk-sensitive patterns. Look for 2–5 spots where a mistake would have the highest blast radius — not the most complex code, but the code where being wrong costs the most. + +Risk categories to detect: + +- `[auth]` — authentication, authorization, session, token, permission, access control +- `[public API]` — new/changed endpoints, exports, public methods, interface contracts +- `[schema]` — database migrations, schema changes, data model modifications, serialization +- `[billing]` — payment, pricing, subscription, metering, usage tracking +- `[infra]` — deployment, CI/CD, environment variables, config files, infrastructure +- `[security]` — input validation, sanitization, crypto, secrets, CORS, CSP +- `[config]` — feature flags, environment-dependent behavior, defaults +- `[other]` — anything risk-sensitive that doesn't fit the above (e.g., concurrency, data privacy, backwards compatibility). Use a descriptive tag. + +Sequence spots so the highest blast radius comes first (how much breaks if this is wrong), not by diff order or file order. If more than 5 spots qualify, show the top 5 and note: "N additional spots omitted — ask if you want the full list." + +If the change has no spots matching these patterns, state: "No high-risk spots found in this change — the diff speaks for itself." Do not force findings. + +## SURFACE MACHINE HARDENING FINDINGS + +Check whether the spec has a `## Spec Change Log` section with entries (populated by adversarial review loops). + +- **If entries exist:** Read them. Surface findings that are instructive for the human reviewer — not bugs that were already fixed, but decisions the review loop flagged that the human should be aware of. Format: brief summary of what was flagged and what was decided. +- **If no entries or no spec:** Skip this section entirely. Do not mention it. + +## PRESENT + +Output as a single message: + +``` +Orientation → Walkthrough → [Detail Pass] → Testing +``` + +### Risk Spots + +For each spot, one line: + +``` +- `path:line` — [tag] reason-phrase +``` + +Example: + +``` +- `src/auth/middleware.ts:42` — [auth] New token validation bypasses rate limiter +- `migrations/003_add_index.sql:7` — [schema] Index on high-write table, check lock behavior +- `api/routes/billing.ts:118` — [billing] Metering calculation changed, verify idempotency +``` + +### Machine Hardening (only if findings exist) + +``` +### Machine Hardening + +- Finding summary — what was flagged, what was decided +- ... +``` + +### Closing menu + +End the message with: + +``` +--- + +You've seen the design and the risk landscape. From here: +- **"dig into [area]"** — I'll deep-dive that specific area with correctness focus +- **"next"** — I'll suggest how to observe the behavior +``` + +## EARLY EXIT + +If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent: + +- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md` +- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md` +- If you misread them → acknowledge and continue the current step. + +## TARGETED RE-REVIEW + +When the human says "dig into [area]" (e.g., "dig into the auth changes", "dig into the schema migration"): + +1. If the specified area does not map to any code in the diff, say so: "I don't see [area] in this change — did you mean something else?" Return to the closing menu. +2. Identify all code locations in the diff relevant to the specified area. +3. Read each location in full context (not just the diff hunk — read surrounding code). +4. Shift to **correctness mode**: trace edge cases, check boundary conditions, verify error handling, look for off-by-one errors, race conditions, resource leaks. +5. Present findings as a compact list — each finding is `path:line` + what you found + why it matters. +6. If nothing concerning is found, say so: "Looked closely at [area] — nothing concerning. The implementation is solid." +7. After presenting, show only the closing menu (not the full risk spots list again). + +The human can trigger multiple targeted re-reviews. Each time, present new findings and the closing menu only. + +## NEXT + +Read fully and follow `./step-04-testing.md` diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md new file mode 100644 index 0000000..f818079 --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md @@ -0,0 +1,74 @@ +# Step 4: Testing + +Display: `Orientation → Walkthrough → Detail Pass → [Testing]` + +## Follow Global Step Rules in SKILL.md + +- This is **experiential**, not analytical. The detail pass asked "did you think about X?" — this says "you could see X with your own eyes." +- Do not prescribe. The human decides whether observing the behavior is worth their time. Frame suggestions as options, not obligations. +- Do not duplicate CI, test suites, or automated checks. Assume those exist and work. This is about manual observation — the kind of confidence-building no automated test provides. +- If the change has no user-visible behavior, say so explicitly. Do not invent observations. + +## IDENTIFY OBSERVABLE BEHAVIOR + +Scan the diff and spec for changes that produce behavior a human could directly observe. Categories to look for: + +- **UI changes** — new screens, modified layouts, changed interactions, error states +- **CLI/terminal output** — new commands, changed output, new flags or options +- **API responses** — new endpoints, changed payloads, different status codes +- **State changes** — database records, file system artifacts, config effects +- **Error paths** — bad input, missing dependencies, edge conditions + +For each observable behavior, determine: + +1. **What to do** — the specific action (command to run, button to click, request to send) +2. **What to expect** — the observable result that confirms the change works +3. **Why bother** — one phrase connecting this observation to the change's intent (omit if obvious from context) + +Target 2–5 suggestions for a typical change. If more than 5 qualify, prioritize by how much confidence the observation provides relative to effort. A change with zero observable behavior is fine — do not pad with trivial observations. + +## PRESENT + +Output as a single message: + +``` +Orientation → Walkthrough → Detail Pass → [Testing] +``` + +Then the testing suggestions using this format: + +``` +### How to See It Working + +**{Brief description}** +Do: {specific action} +Expect: {observable result} + +**{Brief description}** +Do: {specific action} +Expect: {observable result} +``` + +Include code blocks for commands or requests where helpful. + +If the change has no observable behavior, replace the suggestions with: + +``` +### How to See It Working + +This change is internal — no user-visible behavior to observe. The diff and tests tell the full story. +``` + +### Closing + +End the message with: + +``` +--- + +You've seen the change and how to verify it. When you're ready to make a call, just say so. +``` + +## NEXT + +When the human signals they're ready to make a decision about this {change_type}, read fully and follow `./step-05-wrapup.md` diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md new file mode 100644 index 0000000..5f293d5 --- /dev/null +++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md @@ -0,0 +1,24 @@ +# Step 5: Wrap-Up + +Display: `Orientation → Walkthrough → Detail Pass → Testing → [Wrap-Up]` + +## Follow Global Step Rules in SKILL.md + +## PROMPT FOR DECISION + +``` +--- + +Review complete. What's the call on this {change_type}? +- **Approve** — ship it (I can help with interactive patching first if needed) +- **Rework** — back to the drawing board (revert, revise the spec, try a different approach) +- **Discuss** — something's still on your mind +``` + +HALT — do not proceed until the user makes their choice. + +## ACT ON DECISION + +- **Approve**: Acknowledge briefly. If the human wants to patch something before shipping, help apply the fix interactively. If reviewing a PR, offer to approve via `gh pr review --approve` — but confirm with the human before executing, since this is a visible action on a shared resource. +- **Rework**: Ask what went wrong — was it the approach, the spec, or the implementation? Help the human decide on next steps (revert commit, open an issue, revise the spec, etc.). Help draft specific, actionable feedback tied to `path:line` locations if the change is a PR from someone else. +- **Discuss**: Open conversation — answer questions, explore concerns, dig into any aspect. After discussion, return to the decision prompt above. diff --git a/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md b/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md index 3678d06..22b9fbd 100644 --- a/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md +++ b/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md @@ -15,18 +15,37 @@ story_key: '' # set at runtime when discovered from sprint status ## INSTRUCTIONS -1. **Detect review intent from invocation text.** Check the triggering prompt for phrases that map to a review mode: - - "staged" / "staged changes" → Staged changes only - - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged) - - "branch diff" / "vs main" / "against main" / "compared to {branch}" → Branch diff (extract base branch if mentioned) - - "commit range" / "last N commits" / "{sha}..{sha}" → Specific commit range - - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes) - - When multiple phrases match, prefer the most specific match (e.g., "branch diff" over bare "diff"). - - **If a clear match is found:** Announce the detected mode (e.g., "Detected intent: review staged changes only") and proceed directly to constructing `{diff_output}` using the corresponding sub-case from instruction 3. Skip to instruction 4 (spec question). - - **If no match from invocation text, check sprint tracking.** Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for any story with status `review`. Handle as follows: - - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through to instruction 2. - - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If the user selects a story, set `{story_key}` to the selected story's key and use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3. If the user selects the manual choice, clear `{story_key}` and fall through to instruction 2. - - **If no match and no sprint tracking:** Fall through to instruction 2. +1. **Find the review target.** The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the review target is identified: + + **Tier 1 — Explicit argument.** + Did the user pass a PR, commit SHA, branch, spec file, or diff source this message? + - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch. + - Commit or branch → use directly. + - Spec file → set `{spec_file}` to the provided path. Check its frontmatter for `baseline_commit`. If found, use as diff baseline. If not found, continue the cascade (a spec alone does not identify a diff source). + - Also scan the argument for diff-mode keywords that narrow the scope: + - "staged" / "staged changes" → Staged changes only + - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged) + - "branch diff" / "vs main" / "against main" / "compared to " → Branch diff (extract base branch if mentioned) + - "commit range" / "last N commits" / ".." → Specific commit range + - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes) + - When multiple keywords match, prefer the most specific (e.g., "branch diff" over bare "diff"). + + **Tier 2 — Recent conversation.** + Do the last few messages reveal what the user wants to be reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Apply the same diff-mode keyword scan and routing as Tier 1. + + **Tier 3 — Sprint tracking.** + Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`: + - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through. + - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through. + - **None:** Fall through. + + **Tier 4 — Current git state.** + If version control is unavailable, skip to Tier 5. Otherwise, check the current branch and HEAD. If the branch is not `main` (or the default branch), confirm: "I see HEAD is `` on `` — do you want to review this branch's changes?" If confirmed, treat as a branch diff against `main`. If declined, fall through. + + **Tier 5 — Ask.** + Fall through to instruction 2. + + Never ask extra questions beyond what the cascade prescribes. If a tier above already identified the target, skip the remaining tiers and proceed to instruction 3 (construct diff). 2. HALT. Ask the user: **What do you want to review?** Present these options: - **Uncommitted changes** (staged + unstaged) @@ -36,15 +55,19 @@ story_key: '' # set at runtime when discovered from sprint status - **Provided diff or file list** (user pastes or provides a path) 3. Construct `{diff_output}` from the chosen source. + - For **staged changes only**: run `git diff --cached`. + - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`. - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch. - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range. - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff. - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null ` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline. - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review. -4. Ask the user: **Is there a spec or story file that provides context for these changes?** - - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`. - - If no: set `{review_mode}` = `"no-spec"`. +4. **Set the spec context.** + - If `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`. + - Otherwise, ask the user: **Is there a spec or story file that provides context for these changes?** + - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`. + - If no: set `{review_mode}` = `"no-spec"`. 5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found. diff --git a/plugins/bmad/skills/bmad-correct-course/checklist.md b/plugins/bmad/skills/bmad-correct-course/checklist.md index 6fb7c3e..b56feb6 100644 --- a/plugins/bmad/skills/bmad-correct-course/checklist.md +++ b/plugins/bmad/skills/bmad-correct-course/checklist.md @@ -217,8 +217,8 @@ Establish agent handoff plan Identify which roles/agents will execute the changes: - - Development team (for implementation) - - Product Owner / Scrum Master (for backlog changes) + - Developer agent (for implementation) + - Product Owner / Developer (for backlog changes) - Product Manager / Architect (for strategic changes) Define responsibilities for each role [ ] Done / [ ] N/A / [ ] Action-needed diff --git a/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md b/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md index 02368a0..612faa2 100644 --- a/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md +++ b/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md @@ -240,7 +240,7 @@ When user selects 'C', append the content directly to the document using the str ✅ Appropriate breakpoint strategy established ✅ Accessibility requirements determined and documented ✅ Comprehensive testing strategy planned -✅ Implementation guidelines provided for development team +✅ Implementation guidelines provided for Developer agent ✅ A/P/C menu presented and handled correctly ✅ Content properly appended to document when C selected diff --git a/plugins/bmad/skills/bmad-distillator/SKILL.md b/plugins/bmad/skills/bmad-distillator/SKILL.md index 05ef36c..57c44d0 100644 --- a/plugins/bmad/skills/bmad-distillator/SKILL.md +++ b/plugins/bmad/skills/bmad-distillator/SKILL.md @@ -1,7 +1,6 @@ --- name: bmad-distillator description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'. -argument-hint: "[to create provide input paths] [--validate distillate-path to confirm distillate is lossless and optimized]" --- # Distillator: A Document Distillation Engine diff --git a/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md b/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md index 11ffac5..d01cd49 100644 --- a/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md +++ b/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md @@ -81,18 +81,18 @@ When the same fact appears in both a brief and discovery notes: **Brief says:** ``` -bmad-init must always be included as a base skill in every bundle +bmad-help must always be included as a base skill in every bundle ``` **Discovery notes say:** ``` -bmad-init must always be included as a base skill in every bundle/install -(solves bootstrapping problem) +bmad-help must always be included as a base skill in every bundle/install +(solves discoverability problem) ``` **Distillate keeps the more contextual version:** ``` -- bmad-init: always included as base skill in every bundle (solves bootstrapping) +- bmad-help: always included as base skill in every bundle (solves discoverability) ``` ### Decision/Rationale Compression @@ -128,7 +128,7 @@ parts: 1 ## Core Concept - BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms -- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-init skill +- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-setup skill - Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal) ## Problem @@ -141,7 +141,7 @@ parts: 1 - Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies) - Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","after":["brainstorming"],"before":["create-prd"],"is-required":true}]}` - Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision -- bmad-init: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping) +- bmad-setup: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping) - bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision - Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace - Non-technical path has honest friction: "copy to right folder" requires knowing where; per-platform README instructions; improves over time as low-code space matures @@ -161,18 +161,18 @@ parts: 1 - Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem - Installation verified on top platforms by volume; skills CLI handles long tail - Non-technical install path validated with non-developer users -- bmad-init discovers/registers all plugins from manifests; clear errors for malformed manifests +- bmad-setup discovers/registers all plugins from manifests; clear errors for malformed manifests - At least one external module author successfully publishes plugin using manifest system - bmad-update works without full reinstall - Existing CLI users have documented migration path ## Scope -- In: manifest spec, bmad-init, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path +- In: manifest spec, bmad-setup, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path - Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately) - Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations ## Current Installer (migration context) -- Entry: `tools/cli/bmad-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js` +- Entry: `tools/installer/bmad-cli.js` (Commander.js) → `tools/installer/core/installer.js` - Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags) - Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON - External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver @@ -214,7 +214,7 @@ parts: 1 ## Opportunities - Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience -- CI/CD integration: bmad-init as pipeline one-liner increases stickiness +- CI/CD integration: bmad-setup as pipeline one-liner increases stickiness - Educational institutions: structured methodology + non-technical install → university AI curriculum - Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks diff --git a/plugins/bmad/skills/create-prd/data/prd-purpose.md b/plugins/bmad/skills/bmad-edit-prd/data/prd-purpose.md similarity index 100% rename from plugins/bmad/skills/create-prd/data/prd-purpose.md rename to plugins/bmad/skills/bmad-edit-prd/data/prd-purpose.md diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md index 85b29ad..39e3449 100644 --- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md +++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md @@ -1,6 +1,6 @@ --- # File references (ONLY variables used in this step) -prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '../data/prd-purpose.md' --- # Step E-1: Discovery & Understanding diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md index a4f463f..54f8252 100644 --- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md +++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md @@ -1,7 +1,7 @@ --- # File references (ONLY variables used in this step) prdFile: '{prd_file_path}' -prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '../data/prd-purpose.md' --- # Step E-1B: Legacy PRD Conversion Assessment diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md index 8440edd..c01a0ad 100644 --- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md +++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md @@ -2,7 +2,7 @@ # File references (ONLY variables used in this step) prdFile: '{prd_file_path}' validationReport: '{validation_report_path}' # If provided -prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '../data/prd-purpose.md' --- # Step E-2: Deep Review & Analysis diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md index e0391fb..5b5e669 100644 --- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md +++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md @@ -1,7 +1,7 @@ --- # File references (ONLY variables used in this step) prdFile: '{prd_file_path}' -prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '../data/prd-purpose.md' --- # Step E-3: Edit & Update diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md index 25af09a..1406e63 100644 --- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md +++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md @@ -1,7 +1,6 @@ --- # File references (ONLY variables used in this step) prdFile: '{prd_file_path}' -validationWorkflow: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md' --- # Step E-4: Complete & Validate @@ -117,8 +116,7 @@ Display: - Display: "This will run all 13 validation checks on the updated PRD." - Display: "Preparing to validate: {prd_file_path}" - Display: "**Proceeding to validation...**" - - Read fully and follow: {validationWorkflow} (steps-v/step-v-01-discovery.md) - - Note: This hands off to the validation workflow which will run its complete 13-step process + - Invoke the `bmad-validate-prd` skill to run the complete validation workflow - **IF E (Edit More):** - Display: "**Additional Edits**" diff --git a/plugins/bmad/skills/bmad-help/SKILL.md b/plugins/bmad/skills/bmad-help/SKILL.md index cecb50f..e829543 100644 --- a/plugins/bmad/skills/bmad-help/SKILL.md +++ b/plugins/bmad/skills/bmad-help/SKILL.md @@ -7,7 +7,7 @@ description: 'Analyzes current state and user query to answer BMad questions or ## Purpose -Help the user understand where they are in their BMad workflow and what to do next. Answer BMad questions when asked. +Help the user understand where they are in their BMad workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources. ## Desired Outcomes @@ -18,6 +18,7 @@ When this skill completes, the user should: 3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation 4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it 5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog +6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer ## Data Sources @@ -25,6 +26,7 @@ When this skill completes, the user should: - **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/_bmad/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge` - **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations - **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details. +- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module. ## CSV Interpretation @@ -70,4 +72,4 @@ For each recommended item, present: - Present all output in `{communication_language}` - Recommend running each skill in a **fresh context window** - Match the user's tone — conversational when they're casual, structured when they want specifics -- If the active module is ambiguous, ask rather than guess +- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question diff --git a/plugins/bmad/skills/bmad-init/SKILL.md b/plugins/bmad/skills/bmad-init/SKILL.md deleted file mode 100644 index aea00fb..0000000 --- a/plugins/bmad/skills/bmad-init/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: bmad-init -description: "Initialize BMad project configuration and load config variables. Use when any skill needs module-specific configuration values, or when setting up a new BMad project." -argument-hint: "[--module=module_code] [--vars=var1:default1,var2] [--skill-path=/path/to/calling/skill]" ---- - -## Overview - -This skill is the configuration entry point for all BMad skills. It has two modes: - -- **Fast path**: Config exists for the requested module — returns vars as JSON. Done. -- **Init path**: Config is missing — walks the user through configuration, writes config files, then returns vars. - -Every BMad skill should call this on activation to get its config vars. The caller never needs to know whether init happened — they just get their config back. - -The script `bmad_init.py` is located in this skill's `scripts/` directory. Locate and run it using python for all commands below. - -## On Activation — Fast Path - -Run the `bmad_init.py` script with the `load` subcommand. Pass `--project-root` set to the project root directory. - -- If a module code was provided by the calling skill, include `--module {module_code}` -- To load all vars, include `--all` -- To request specific variables with defaults, use `--vars var1:default1,var2` -- If no module was specified, omit `--module` to get core vars only - -**If the script returns JSON vars** — store them as `{var-name}` and return to the calling skill. Done. - -**If the script returns an error or `init_required`** — proceed to the Init Path below. - -## Init Path — First-Time Setup - -When the fast path fails (config missing for a module), run this init flow. - -### Step 1: Check what needs setup - -Run `bmad_init.py` with the `check` subcommand, passing `--module {module_code}`, `--skill-path {calling_skill_path}`, and `--project-root`. - -The response tells you what's needed: - -- `"status": "ready"` — Config is fine. Re-run load. -- `"status": "no_project"` — Can't find project root. Ask user to confirm the project path. -- `"status": "core_missing"` — Core config doesn't exist. Must ask core questions first. -- `"status": "module_missing"` — Core exists but module config doesn't. Ask module questions. - -The response includes: -- `core_module` — Core module.yaml questions (when core setup needed) -- `target_module` — Target module.yaml questions (when module setup needed, discovered from `--skill-path` or `_bmad/{module}/`) -- `core_vars` — Existing core config values (when core exists but module doesn't) - -### Step 2: Ask core questions (if `core_missing`) - -The check response includes `core_module` with header, subheader, and variable definitions. - -1. Show the `header` and `subheader` to the user -2. For each variable, present the `prompt` and `default` -3. For variables with `single-select`, show the options as a numbered list -4. For variables with multi-line `prompt` (array), show all lines -5. Let the user accept defaults or provide values - -### Step 3: Ask module questions (if module was requested) - -The check response includes `target_module` with the module's questions. Variables may reference core answers in their defaults (e.g., `{output_folder}`). - -1. Resolve defaults by running `bmad_init.py` with the `resolve-defaults` subcommand, passing `--module {module_code}`, `--core-answers '{core_answers_json}'`, and `--project-root` -2. Show the module's `header` and `subheader` -3. For each variable, present the prompt with resolved default -4. For `single-select` variables, show options as a numbered list - -### Step 4: Write config - -Collect all answers and run `bmad_init.py` with the `write` subcommand, passing `--answers '{all_answers_json}'` and `--project-root`. - -The `--answers` JSON format: - -```json -{ - "core": { - "user_name": "BMad", - "communication_language": "English", - "document_output_language": "English", - "output_folder": "_bmad-output" - }, - "bmb": { - "bmad_builder_output_folder": "_bmad-output/skills", - "bmad_builder_reports": "_bmad-output/reports" - } -} -``` - -Note: Pass the **raw user answers** (before result template expansion). The script applies result templates and `{project-root}` expansion when writing. - -The script: -- Creates `_bmad/core/config.yaml` with core values (if core answers provided) -- Creates `_bmad/{module}/config.yaml` with core values + module values (result-expanded) -- Creates any directories listed in the module.yaml `directories` array - -### Step 5: Return vars - -After writing, re-run `bmad_init.py` with the `load` subcommand (same as the fast path) to return resolved vars. Store returned vars as `{var-name}` and return them to the calling skill. diff --git a/plugins/bmad/skills/bmad-init/resources/core-module.yaml b/plugins/bmad/skills/bmad-init/resources/core-module.yaml deleted file mode 100644 index 48e7a58..0000000 --- a/plugins/bmad/skills/bmad-init/resources/core-module.yaml +++ /dev/null @@ -1,25 +0,0 @@ -code: core -name: "BMad Core Module" - -header: "BMad Core Configuration" -subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all installed bmad skills, workflows, and agents." - -user_name: - prompt: "What should agents call you? (Use your name or a team name)" - default: "BMad" - result: "{value}" - -communication_language: - prompt: "What language should agents use when chatting with you?" - default: "English" - result: "{value}" - -document_output_language: - prompt: "Preferred document output language?" - default: "English" - result: "{value}" - -output_folder: - prompt: "Where should output files be saved?" - default: "_bmad-output" - result: "{project-root}/{value}" diff --git a/plugins/bmad/skills/bmad-init/scripts/bmad_init.py b/plugins/bmad/skills/bmad-init/scripts/bmad_init.py deleted file mode 100644 index 0c80eaa..0000000 --- a/plugins/bmad/skills/bmad-init/scripts/bmad_init.py +++ /dev/null @@ -1,593 +0,0 @@ -# /// script -# requires-python = ">=3.10" -# dependencies = ["pyyaml"] -# /// - -#!/usr/bin/env python3 -""" -BMad Init — Project configuration bootstrap and config loader. - -Config files (flat YAML per module): - - _bmad/core/config.yaml (core settings — user_name, language, output_folder, etc.) - - _bmad/{module}/config.yaml (module settings + core values merged in) - -Usage: - # Fast path — load all vars for a module (includes core vars) - python bmad_init.py load --module bmb --all --project-root /path - - # Load specific vars with optional defaults - python bmad_init.py load --module bmb --vars var1:default1,var2 --project-root /path - - # Load core only - python bmad_init.py load --all --project-root /path - - # Check if init is needed - python bmad_init.py check --project-root /path - python bmad_init.py check --module bmb --skill-path /path/to/skill --project-root /path - - # Resolve module defaults given core answers - python bmad_init.py resolve-defaults --module bmb --core-answers '{"output_folder":"..."}' --project-root /path - - # Write config from answered questions - python bmad_init.py write --answers '{"core": {...}, "bmb": {...}}' --project-root /path -""" - -import argparse -import json -import os -import sys -from pathlib import Path - -import yaml - - -# ============================================================================= -# Project Root Detection -# ============================================================================= - -def find_project_root(llm_provided=None): - """ - Find project root by looking for _bmad folder. - - Args: - llm_provided: Path explicitly provided via --project-root. - - Returns: - Path to project root, or None if not found. - """ - if llm_provided: - candidate = Path(llm_provided) - if (candidate / '_bmad').exists(): - return candidate - # First run — _bmad won't exist yet but LLM path is still valid - if candidate.is_dir(): - return candidate - - for start_dir in [Path.cwd(), Path(__file__).resolve().parent]: - current_dir = start_dir - while current_dir != current_dir.parent: - if (current_dir / '_bmad').exists(): - return current_dir - current_dir = current_dir.parent - - return None - - -# ============================================================================= -# Module YAML Loading -# ============================================================================= - -def load_module_yaml(path): - """ - Load and parse a module.yaml file, separating metadata from variable definitions. - - Returns: - Dict with 'meta' (code, name, etc.) and 'variables' (var definitions) - and 'directories' (list of dir templates), or None on failure. - """ - try: - with open(path, 'r', encoding='utf-8') as f: - raw = yaml.safe_load(f) - except Exception: - return None - - if not raw or not isinstance(raw, dict): - return None - - meta_keys = {'code', 'name', 'description', 'default_selected', 'header', 'subheader'} - meta = {} - variables = {} - directories = [] - - for key, value in raw.items(): - if key == 'directories': - directories = value if isinstance(value, list) else [] - elif key in meta_keys: - meta[key] = value - elif isinstance(value, dict) and 'prompt' in value: - variables[key] = value - # Skip comment-only entries (## var_name lines become None values) - - return {'meta': meta, 'variables': variables, 'directories': directories} - - -def find_core_module_yaml(): - """Find the core module.yaml bundled with this skill.""" - return Path(__file__).resolve().parent.parent / 'resources' / 'core-module.yaml' - - -def find_target_module_yaml(module_code, project_root, skill_path=None): - """ - Find module.yaml for a given module code. - - Search order: - 1. skill_path/assets/module.yaml (calling skill's assets) - 2. skill_path/module.yaml (calling skill's root) - 3. _bmad/{module_code}/module.yaml (installed module location) - """ - search_paths = [] - - if skill_path: - sp = Path(skill_path) - search_paths.append(sp / 'assets' / 'module.yaml') - search_paths.append(sp / 'module.yaml') - - if project_root and module_code: - search_paths.append(Path(project_root) / '_bmad' / module_code / 'module.yaml') - - for path in search_paths: - if path.exists(): - return path - - return None - - -# ============================================================================= -# Config Loading (Flat per-module files) -# ============================================================================= - -def load_config_file(path): - """Load a flat YAML config file. Returns dict or None.""" - try: - with open(path, 'r', encoding='utf-8') as f: - data = yaml.safe_load(f) - return data if isinstance(data, dict) else None - except Exception: - return None - - -def load_module_config(module_code, project_root): - """Load config for a specific module from _bmad/{module}/config.yaml.""" - config_path = Path(project_root) / '_bmad' / module_code / 'config.yaml' - return load_config_file(config_path) - - -def resolve_project_root_placeholder(value, project_root): - """Replace {project-root} placeholder with actual path.""" - if not value or not isinstance(value, str): - return value - if '{project-root}' in value: - return value.replace('{project-root}', str(project_root)) - return value - - -def parse_var_specs(vars_string): - """ - Parse variable specs: var_name:default_value,var_name2:default_value2 - No default = returns null if missing. - """ - if not vars_string: - return [] - specs = [] - for spec in vars_string.split(','): - spec = spec.strip() - if not spec: - continue - if ':' in spec: - parts = spec.split(':', 1) - specs.append({'name': parts[0].strip(), 'default': parts[1].strip()}) - else: - specs.append({'name': spec, 'default': None}) - return specs - - -# ============================================================================= -# Template Expansion -# ============================================================================= - -def expand_template(value, context): - """ - Expand {placeholder} references in a string using context dict. - - Supports: {project-root}, {value}, {output_folder}, {directory_name}, etc. - """ - if not value or not isinstance(value, str): - return value - result = value - for key, val in context.items(): - placeholder = '{' + key + '}' - if placeholder in result and val is not None: - result = result.replace(placeholder, str(val)) - return result - - -def apply_result_template(var_def, raw_value, context): - """ - Apply a variable's result template to transform the raw user answer. - - E.g., result: "{project-root}/{value}" with value="_bmad-output" - becomes "/Users/foo/project/_bmad-output" - """ - result_template = var_def.get('result') - if not result_template: - return raw_value - - ctx = dict(context) - ctx['value'] = raw_value - return expand_template(result_template, ctx) - - -# ============================================================================= -# Load Command (Fast Path) -# ============================================================================= - -def cmd_load(args): - """Load config vars — the fast path.""" - project_root = find_project_root(llm_provided=args.project_root) - if not project_root: - print(json.dumps({'error': 'Project root not found (_bmad folder not detected)'}), - file=sys.stderr) - sys.exit(1) - - module_code = args.module or 'core' - - # Load the module's config (which includes core vars) - config = load_module_config(module_code, project_root) - if config is None: - print(json.dumps({ - 'init_required': True, - 'missing_module': module_code, - }), file=sys.stderr) - sys.exit(1) - - # Resolve {project-root} in all values - for key in config: - config[key] = resolve_project_root_placeholder(config[key], project_root) - - if args.all: - print(json.dumps(config, indent=2)) - else: - var_specs = parse_var_specs(args.vars) - if not var_specs: - print(json.dumps({'error': 'Either --vars or --all must be specified'}), - file=sys.stderr) - sys.exit(1) - result = {} - for spec in var_specs: - val = config.get(spec['name']) - if val is not None and val != '': - result[spec['name']] = val - elif spec['default'] is not None: - result[spec['name']] = spec['default'] - else: - result[spec['name']] = None - print(json.dumps(result, indent=2)) - - -# ============================================================================= -# Check Command -# ============================================================================= - -def cmd_check(args): - """Check if config exists and return status with module.yaml questions if needed.""" - project_root = find_project_root(llm_provided=args.project_root) - if not project_root: - print(json.dumps({ - 'status': 'no_project', - 'message': 'No project root found. Provide --project-root to bootstrap.', - }, indent=2)) - return - - project_root = Path(project_root) - module_code = args.module - - # Check core config - core_config = load_module_config('core', project_root) - core_exists = core_config is not None - - # If no module requested, just check core - if not module_code or module_code == 'core': - if core_exists: - print(json.dumps({'status': 'ready', 'project_root': str(project_root)}, indent=2)) - else: - core_yaml_path = find_core_module_yaml() - core_module = load_module_yaml(core_yaml_path) if core_yaml_path.exists() else None - print(json.dumps({ - 'status': 'core_missing', - 'project_root': str(project_root), - 'core_module': core_module, - }, indent=2)) - return - - # Module requested — check if its config exists - module_config = load_module_config(module_code, project_root) - if module_config is not None: - print(json.dumps({'status': 'ready', 'project_root': str(project_root)}, indent=2)) - return - - # Module config missing — find its module.yaml for questions - target_yaml_path = find_target_module_yaml( - module_code, project_root, skill_path=args.skill_path - ) - target_module = load_module_yaml(target_yaml_path) if target_yaml_path else None - - result = { - 'project_root': str(project_root), - } - - if not core_exists: - result['status'] = 'core_missing' - core_yaml_path = find_core_module_yaml() - result['core_module'] = load_module_yaml(core_yaml_path) if core_yaml_path.exists() else None - else: - result['status'] = 'module_missing' - result['core_vars'] = core_config - - result['target_module'] = target_module - if target_yaml_path: - result['target_module_yaml_path'] = str(target_yaml_path) - - print(json.dumps(result, indent=2)) - - -# ============================================================================= -# Resolve Defaults Command -# ============================================================================= - -def cmd_resolve_defaults(args): - """Given core answers, resolve a module's variable defaults.""" - project_root = find_project_root(llm_provided=args.project_root) - if not project_root: - print(json.dumps({'error': 'Project root not found'}), file=sys.stderr) - sys.exit(1) - - try: - core_answers = json.loads(args.core_answers) - except json.JSONDecodeError as e: - print(json.dumps({'error': f'Invalid JSON in --core-answers: {e}'}), - file=sys.stderr) - sys.exit(1) - - # Build context for template expansion - context = { - 'project-root': str(project_root), - 'directory_name': Path(project_root).name, - } - context.update(core_answers) - - # Find and load the module's module.yaml - module_code = args.module - target_yaml_path = find_target_module_yaml( - module_code, project_root, skill_path=args.skill_path - ) - if not target_yaml_path: - print(json.dumps({'error': f'No module.yaml found for module: {module_code}'}), - file=sys.stderr) - sys.exit(1) - - module_def = load_module_yaml(target_yaml_path) - if not module_def: - print(json.dumps({'error': f'Failed to parse module.yaml at: {target_yaml_path}'}), - file=sys.stderr) - sys.exit(1) - - # Resolve defaults in each variable - resolved_vars = {} - for var_name, var_def in module_def['variables'].items(): - default = var_def.get('default', '') - resolved_default = expand_template(str(default), context) - resolved_vars[var_name] = dict(var_def) - resolved_vars[var_name]['default'] = resolved_default - - result = { - 'module_code': module_code, - 'meta': module_def['meta'], - 'variables': resolved_vars, - 'directories': module_def['directories'], - } - print(json.dumps(result, indent=2)) - - -# ============================================================================= -# Write Command -# ============================================================================= - -def cmd_write(args): - """Write config files from answered questions.""" - project_root = find_project_root(llm_provided=args.project_root) - if not project_root: - if args.project_root: - project_root = Path(args.project_root) - else: - print(json.dumps({'error': 'Project root not found and --project-root not provided'}), - file=sys.stderr) - sys.exit(1) - - project_root = Path(project_root) - - try: - answers = json.loads(args.answers) - except json.JSONDecodeError as e: - print(json.dumps({'error': f'Invalid JSON in --answers: {e}'}), - file=sys.stderr) - sys.exit(1) - - context = { - 'project-root': str(project_root), - 'directory_name': project_root.name, - } - - # Load module.yaml definitions to get result templates - core_yaml_path = find_core_module_yaml() - core_def = load_module_yaml(core_yaml_path) if core_yaml_path.exists() else None - - files_written = [] - dirs_created = [] - - # Process core answers first (needed for module config expansion) - core_answers_raw = answers.get('core', {}) - core_config = {} - - if core_answers_raw and core_def: - for var_name, raw_value in core_answers_raw.items(): - var_def = core_def['variables'].get(var_name, {}) - expanded = apply_result_template(var_def, raw_value, context) - core_config[var_name] = expanded - - # Write core config - core_dir = project_root / '_bmad' / 'core' - core_dir.mkdir(parents=True, exist_ok=True) - core_config_path = core_dir / 'config.yaml' - - # Merge with existing if present - existing = load_config_file(core_config_path) or {} - existing.update(core_config) - - _write_config_file(core_config_path, existing, 'CORE') - files_written.append(str(core_config_path)) - elif core_answers_raw: - # No core_def available — write raw values - core_config = dict(core_answers_raw) - core_dir = project_root / '_bmad' / 'core' - core_dir.mkdir(parents=True, exist_ok=True) - core_config_path = core_dir / 'config.yaml' - existing = load_config_file(core_config_path) or {} - existing.update(core_config) - _write_config_file(core_config_path, existing, 'CORE') - files_written.append(str(core_config_path)) - - # Update context with resolved core values for module expansion - context.update(core_config) - - # Process module answers - for module_code, module_answers_raw in answers.items(): - if module_code == 'core': - continue - - # Find module.yaml for result templates - target_yaml_path = find_target_module_yaml( - module_code, project_root, skill_path=args.skill_path - ) - module_def = load_module_yaml(target_yaml_path) if target_yaml_path else None - - # Build module config: start with core values, then add module values - # Re-read core config to get the latest (may have been updated above) - latest_core = load_module_config('core', project_root) or core_config - module_config = dict(latest_core) - - for var_name, raw_value in module_answers_raw.items(): - if module_def: - var_def = module_def['variables'].get(var_name, {}) - expanded = apply_result_template(var_def, raw_value, context) - else: - expanded = raw_value - module_config[var_name] = expanded - context[var_name] = expanded # Available for subsequent template expansion - - # Write module config - module_dir = project_root / '_bmad' / module_code - module_dir.mkdir(parents=True, exist_ok=True) - module_config_path = module_dir / 'config.yaml' - - existing = load_config_file(module_config_path) or {} - existing.update(module_config) - - module_name = module_def['meta'].get('name', module_code.upper()) if module_def else module_code.upper() - _write_config_file(module_config_path, existing, module_name) - files_written.append(str(module_config_path)) - - # Create directories declared in module.yaml - if module_def and module_def.get('directories'): - for dir_template in module_def['directories']: - dir_path = expand_template(dir_template, context) - if dir_path: - Path(dir_path).mkdir(parents=True, exist_ok=True) - dirs_created.append(dir_path) - - result = { - 'status': 'written', - 'files_written': files_written, - 'dirs_created': dirs_created, - } - print(json.dumps(result, indent=2)) - - -def _write_config_file(path, data, module_label): - """Write a config YAML file with a header comment.""" - from datetime import datetime, timezone - with open(path, 'w', encoding='utf-8') as f: - f.write(f'# {module_label} Module Configuration\n') - f.write(f'# Generated by bmad-init\n') - f.write(f'# Date: {datetime.now(timezone.utc).isoformat()}\n\n') - yaml.safe_dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False) - - -# ============================================================================= -# CLI Entry Point -# ============================================================================= - -def main(): - parser = argparse.ArgumentParser( - description='BMad Init — Project configuration bootstrap and config loader.' - ) - subparsers = parser.add_subparsers(dest='command') - - # --- load --- - load_parser = subparsers.add_parser('load', help='Load config vars (fast path)') - load_parser.add_argument('--module', help='Module code (omit for core only)') - load_parser.add_argument('--vars', help='Comma-separated vars with optional defaults') - load_parser.add_argument('--all', action='store_true', help='Return all config vars') - load_parser.add_argument('--project-root', help='Project root path') - - # --- check --- - check_parser = subparsers.add_parser('check', help='Check if init is needed') - check_parser.add_argument('--module', help='Module code to check (optional)') - check_parser.add_argument('--skill-path', help='Path to the calling skill folder') - check_parser.add_argument('--project-root', help='Project root path') - - # --- resolve-defaults --- - resolve_parser = subparsers.add_parser('resolve-defaults', - help='Resolve module defaults given core answers') - resolve_parser.add_argument('--module', required=True, help='Module code') - resolve_parser.add_argument('--core-answers', required=True, help='JSON string of core answers') - resolve_parser.add_argument('--skill-path', help='Path to calling skill folder') - resolve_parser.add_argument('--project-root', help='Project root path') - - # --- write --- - write_parser = subparsers.add_parser('write', help='Write config files') - write_parser.add_argument('--answers', required=True, help='JSON string of all answers') - write_parser.add_argument('--skill-path', help='Path to calling skill (for module.yaml lookup)') - write_parser.add_argument('--project-root', help='Project root path') - - args = parser.parse_args() - if args.command is None: - parser.print_help() - sys.exit(1) - - commands = { - 'load': cmd_load, - 'check': cmd_check, - 'resolve-defaults': cmd_resolve_defaults, - 'write': cmd_write, - } - - handler = commands.get(args.command) - if handler: - handler(args) - else: - parser.print_help() - sys.exit(1) - - -if __name__ == '__main__': - main() diff --git a/plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py b/plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py deleted file mode 100644 index 32e07ef..0000000 --- a/plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py +++ /dev/null @@ -1,329 +0,0 @@ -# /// script -# requires-python = ">=3.10" -# dependencies = ["pyyaml"] -# /// - -#!/usr/bin/env python3 -"""Unit tests for bmad_init.py""" - -import json -import os -import shutil -import sys -import tempfile -import unittest -from pathlib import Path - -sys.path.insert(0, str(Path(__file__).parent.parent)) - -from bmad_init import ( - find_project_root, - parse_var_specs, - resolve_project_root_placeholder, - expand_template, - apply_result_template, - load_module_yaml, - find_core_module_yaml, - find_target_module_yaml, - load_config_file, - load_module_config, -) - - -class TestFindProjectRoot(unittest.TestCase): - - def test_finds_bmad_folder(self): - temp_dir = tempfile.mkdtemp() - try: - (Path(temp_dir) / '_bmad').mkdir() - original_cwd = os.getcwd() - try: - os.chdir(temp_dir) - result = find_project_root() - self.assertEqual(result.resolve(), Path(temp_dir).resolve()) - finally: - os.chdir(original_cwd) - finally: - shutil.rmtree(temp_dir) - - def test_llm_provided_with_bmad(self): - temp_dir = tempfile.mkdtemp() - try: - (Path(temp_dir) / '_bmad').mkdir() - result = find_project_root(llm_provided=temp_dir) - self.assertEqual(result.resolve(), Path(temp_dir).resolve()) - finally: - shutil.rmtree(temp_dir) - - def test_llm_provided_without_bmad_still_returns_dir(self): - """First-run case: LLM provides path but _bmad doesn't exist yet.""" - temp_dir = tempfile.mkdtemp() - try: - result = find_project_root(llm_provided=temp_dir) - self.assertEqual(result.resolve(), Path(temp_dir).resolve()) - finally: - shutil.rmtree(temp_dir) - - -class TestParseVarSpecs(unittest.TestCase): - - def test_vars_with_defaults(self): - specs = parse_var_specs('var1:value1,var2:value2') - self.assertEqual(len(specs), 2) - self.assertEqual(specs[0]['name'], 'var1') - self.assertEqual(specs[0]['default'], 'value1') - - def test_vars_without_defaults(self): - specs = parse_var_specs('var1,var2') - self.assertEqual(len(specs), 2) - self.assertIsNone(specs[0]['default']) - - def test_mixed_vars(self): - specs = parse_var_specs('required_var,var2:default2') - self.assertIsNone(specs[0]['default']) - self.assertEqual(specs[1]['default'], 'default2') - - def test_colon_in_default(self): - specs = parse_var_specs('path:{project-root}/some/path') - self.assertEqual(specs[0]['default'], '{project-root}/some/path') - - def test_empty_string(self): - self.assertEqual(parse_var_specs(''), []) - - def test_none(self): - self.assertEqual(parse_var_specs(None), []) - - -class TestResolveProjectRootPlaceholder(unittest.TestCase): - - def test_resolve_placeholder(self): - result = resolve_project_root_placeholder('{project-root}/output', Path('/test')) - self.assertEqual(result, '/test/output') - - def test_no_placeholder(self): - result = resolve_project_root_placeholder('/absolute/path', Path('/test')) - self.assertEqual(result, '/absolute/path') - - def test_none(self): - self.assertIsNone(resolve_project_root_placeholder(None, Path('/test'))) - - def test_non_string(self): - self.assertEqual(resolve_project_root_placeholder(42, Path('/test')), 42) - - -class TestExpandTemplate(unittest.TestCase): - - def test_basic_expansion(self): - result = expand_template('{project-root}/output', {'project-root': '/test'}) - self.assertEqual(result, '/test/output') - - def test_multiple_placeholders(self): - result = expand_template( - '{output_folder}/planning', - {'output_folder': '_bmad-output', 'project-root': '/test'} - ) - self.assertEqual(result, '_bmad-output/planning') - - def test_none_value(self): - self.assertIsNone(expand_template(None, {})) - - def test_non_string(self): - self.assertEqual(expand_template(42, {}), 42) - - -class TestApplyResultTemplate(unittest.TestCase): - - def test_with_result_template(self): - var_def = {'result': '{project-root}/{value}'} - result = apply_result_template(var_def, '_bmad-output', {'project-root': '/test'}) - self.assertEqual(result, '/test/_bmad-output') - - def test_without_result_template(self): - result = apply_result_template({}, 'raw_value', {}) - self.assertEqual(result, 'raw_value') - - def test_value_only_template(self): - var_def = {'result': '{value}'} - result = apply_result_template(var_def, 'English', {}) - self.assertEqual(result, 'English') - - -class TestLoadModuleYaml(unittest.TestCase): - - def setUp(self): - self.temp_dir = tempfile.mkdtemp() - - def tearDown(self): - shutil.rmtree(self.temp_dir) - - def test_loads_core_module_yaml(self): - path = Path(self.temp_dir) / 'module.yaml' - path.write_text( - 'code: core\n' - 'name: "BMad Core Module"\n' - 'header: "Core Config"\n' - 'user_name:\n' - ' prompt: "What should agents call you?"\n' - ' default: "BMad"\n' - ' result: "{value}"\n' - ) - result = load_module_yaml(path) - self.assertIsNotNone(result) - self.assertEqual(result['meta']['code'], 'core') - self.assertEqual(result['meta']['name'], 'BMad Core Module') - self.assertIn('user_name', result['variables']) - self.assertEqual(result['variables']['user_name']['prompt'], 'What should agents call you?') - - def test_loads_module_with_directories(self): - path = Path(self.temp_dir) / 'module.yaml' - path.write_text( - 'code: bmm\n' - 'name: "BMad Method"\n' - 'project_name:\n' - ' prompt: "Project name?"\n' - ' default: "{directory_name}"\n' - ' result: "{value}"\n' - 'directories:\n' - ' - "{planning_artifacts}"\n' - ) - result = load_module_yaml(path) - self.assertEqual(result['directories'], ['{planning_artifacts}']) - - def test_returns_none_for_missing(self): - result = load_module_yaml(Path(self.temp_dir) / 'nonexistent.yaml') - self.assertIsNone(result) - - def test_returns_none_for_empty(self): - path = Path(self.temp_dir) / 'empty.yaml' - path.write_text('') - result = load_module_yaml(path) - self.assertIsNone(result) - - -class TestFindCoreModuleYaml(unittest.TestCase): - - def test_returns_path_to_resources(self): - path = find_core_module_yaml() - self.assertTrue(str(path).endswith('resources/core-module.yaml')) - - -class TestFindTargetModuleYaml(unittest.TestCase): - - def setUp(self): - self.temp_dir = tempfile.mkdtemp() - self.project_root = Path(self.temp_dir) - - def tearDown(self): - shutil.rmtree(self.temp_dir) - - def test_finds_in_skill_assets(self): - skill_path = self.project_root / 'skills' / 'test-skill' - assets = skill_path / 'assets' - assets.mkdir(parents=True) - (assets / 'module.yaml').write_text('code: test\n') - - result = find_target_module_yaml('test', self.project_root, str(skill_path)) - self.assertIsNotNone(result) - self.assertTrue(str(result).endswith('assets/module.yaml')) - - def test_finds_in_skill_root(self): - skill_path = self.project_root / 'skills' / 'test-skill' - skill_path.mkdir(parents=True) - (skill_path / 'module.yaml').write_text('code: test\n') - - result = find_target_module_yaml('test', self.project_root, str(skill_path)) - self.assertIsNotNone(result) - - def test_finds_in_bmad_module_dir(self): - module_dir = self.project_root / '_bmad' / 'mymod' - module_dir.mkdir(parents=True) - (module_dir / 'module.yaml').write_text('code: mymod\n') - - result = find_target_module_yaml('mymod', self.project_root) - self.assertIsNotNone(result) - - def test_returns_none_when_not_found(self): - result = find_target_module_yaml('missing', self.project_root) - self.assertIsNone(result) - - def test_skill_path_takes_priority(self): - """Skill assets module.yaml takes priority over _bmad/{module}/.""" - skill_path = self.project_root / 'skills' / 'test-skill' - assets = skill_path / 'assets' - assets.mkdir(parents=True) - (assets / 'module.yaml').write_text('code: test\nname: from-skill\n') - - module_dir = self.project_root / '_bmad' / 'test' - module_dir.mkdir(parents=True) - (module_dir / 'module.yaml').write_text('code: test\nname: from-bmad\n') - - result = find_target_module_yaml('test', self.project_root, str(skill_path)) - self.assertTrue('assets' in str(result)) - - -class TestLoadConfigFile(unittest.TestCase): - - def setUp(self): - self.temp_dir = tempfile.mkdtemp() - - def tearDown(self): - shutil.rmtree(self.temp_dir) - - def test_loads_flat_yaml(self): - path = Path(self.temp_dir) / 'config.yaml' - path.write_text('user_name: Test\ncommunication_language: English\n') - result = load_config_file(path) - self.assertEqual(result['user_name'], 'Test') - - def test_returns_none_for_missing(self): - result = load_config_file(Path(self.temp_dir) / 'missing.yaml') - self.assertIsNone(result) - - -class TestLoadModuleConfig(unittest.TestCase): - - def setUp(self): - self.temp_dir = tempfile.mkdtemp() - self.project_root = Path(self.temp_dir) - bmad_core = self.project_root / '_bmad' / 'core' - bmad_core.mkdir(parents=True) - (bmad_core / 'config.yaml').write_text( - 'user_name: TestUser\n' - 'communication_language: English\n' - 'document_output_language: English\n' - 'output_folder: "{project-root}/_bmad-output"\n' - ) - bmad_bmb = self.project_root / '_bmad' / 'bmb' - bmad_bmb.mkdir(parents=True) - (bmad_bmb / 'config.yaml').write_text( - 'user_name: TestUser\n' - 'communication_language: English\n' - 'document_output_language: English\n' - 'output_folder: "{project-root}/_bmad-output"\n' - 'bmad_builder_output_folder: "{project-root}/_bmad-output/skills"\n' - 'bmad_builder_reports: "{project-root}/_bmad-output/reports"\n' - ) - - def tearDown(self): - shutil.rmtree(self.temp_dir) - - def test_load_core(self): - result = load_module_config('core', self.project_root) - self.assertIsNotNone(result) - self.assertEqual(result['user_name'], 'TestUser') - - def test_load_module_includes_core_vars(self): - result = load_module_config('bmb', self.project_root) - self.assertIsNotNone(result) - # Module-specific var - self.assertIn('bmad_builder_output_folder', result) - # Core vars also present - self.assertEqual(result['user_name'], 'TestUser') - - def test_missing_module(self): - result = load_module_config('nonexistent', self.project_root) - self.assertIsNone(result) - - -if __name__ == '__main__': - unittest.main() diff --git a/plugins/bmad/skills/bmad-party-mode/SKILL.md b/plugins/bmad/skills/bmad-party-mode/SKILL.md index 8fb3d9a..8367e29 100644 --- a/plugins/bmad/skills/bmad-party-mode/SKILL.md +++ b/plugins/bmad/skills/bmad-party-mode/SKILL.md @@ -1,6 +1,125 @@ --- name: bmad-party-mode -description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.' +description: 'Orchestrates group discussions between installed BMAD agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project.' --- -Follow the instructions in ./workflow.md. +# Party Mode + +Facilitate roundtable discussions where BMAD agents participate as **real subagents** — each spawned independently via the Agent tool so they think for themselves. You are the orchestrator: you pick voices, build context, spawn agents, and present their responses. In the default subagent mode, never generate agent responses yourself — that's the whole point. In `--solo` mode, you roleplay all agents directly. + +## Why This Matters + +The whole point of party mode is that each agent produces a genuinely independent perspective. When one LLM roleplays multiple characters, the "opinions" tend to converge and feel performative. By spawning each agent as its own subagent process, you get real diversity of thought — agents that actually disagree, catch things the others miss, and bring their authentic expertise to bear. + +## Arguments + +Party mode accepts optional arguments when invoked: + +- `--model ` — Force all subagents to use a specific model (e.g. `--model haiku`, `--model opus`). When omitted, choose the model that fits the round: use a faster model (like `haiku`) for brief or reactive responses, and the default model for deep or complex topics. Match model weight to the depth of thinking the round requires. +- `--solo` — Run without subagents. Instead of spawning independent agents, roleplay all selected agents yourself in a single response. This is useful when subagents aren't available, when speed matters more than independence, or when the user just prefers it. Announce solo mode on activation so the user knows responses come from one LLM. + +## On Activation + +1. **Parse arguments** — check for `--model` and `--solo` flags from the user's invocation. + +2. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + +3. **Read the agent manifest** at `${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv`. Build an internal roster of available agents with their displayName, title, icon, role, identity, communicationStyle, and principles. + +4. **Load project context** — search for `**/project-context.md`. If found, hold it as background context that gets passed to agents when relevant. + +5. **Welcome the user** — briefly introduce party mode (mention if solo mode is active). Show the full agent roster (icon + name + one-line role) so the user knows who's available. Ask what they'd like to discuss. + +## The Core Loop + +For each user message: + +### 1. Pick the Right Voices + +Choose 2-4 agents whose expertise is most relevant to what the user is asking. Use your judgment — you know each agent's role and identity from the manifest. Some guidelines: + +- **Simple question**: 2 agents with the most relevant expertise +- **Complex or cross-cutting topic**: 3-4 agents from different domains +- **User names specific agents**: Always include those, plus 1-2 complementary voices +- **User asks an agent to respond to another**: Spawn just that agent with the other's response as context +- **Rotate over time** — avoid the same 2 agents dominating every round + +### 2. Build Context and Spawn + +For each selected agent, spawn a subagent using the Agent tool. Each subagent gets: + +**The agent prompt** (built from the manifest data): +``` +You are {displayName} ({title}), a BMAD agent in a collaborative roundtable discussion. + +## Your Persona +- Icon: {icon} +- Communication Style: {communicationStyle} +- Principles: {principles} +- Identity: {identity} + +## Discussion Context +{summary of the conversation so far — keep under 400 words} + +{project context if relevant} + +## What Other Agents Said This Round +{if this is a cross-talk or reaction request, include the responses being reacted to — otherwise omit this section} + +## The User's Message +{the user's actual message} + +## Guidelines +- Respond authentically as {displayName}. Your perspective should reflect your genuine expertise. +- Start your response with: {icon} **{displayName}:** +- Speak in {communication_language}. +- Scale your response to the substance — don't pad. If you have a brief point, make it briefly. +- Disagree with other agents when your expertise tells you to. Don't hedge or be polite about it. +- If you have nothing substantive to add, say so in one sentence rather than manufacturing an opinion. +- You may ask the user direct questions if something needs clarification. +- Do NOT use tools. Just respond with your perspective. +``` + +**Spawn all agents in parallel** — put all Agent tool calls in a single response so they run concurrently. If `--model` was specified, use that model for all subagents. Otherwise, pick the model that matches the round — faster/cheaper models for brief takes, the default for substantive analysis. + +**Solo mode** — if `--solo` is active, skip spawning. Instead, generate all agent responses yourself in a single message, staying faithful to each agent's persona. Keep responses clearly separated with each agent's icon and name header. + +### 3. Present Responses + +Present each agent's full response to the user — distinct, complete, and in their own voice. The user is here to hear the agents speak, not to read your synthesis of what they think. Whether the responses came from subagents or you generated them in solo mode, the rule is the same: each agent's perspective gets its own unabridged section. Never blend, paraphrase, or condense agent responses into a summary. + +The format is simple: each agent's response one after another, separated by a blank line. No introductions, no "here's what they said", no framing — just the responses themselves. + +After all agent responses are presented in full, you may optionally add a brief **Orchestrator Note** — flagging a disagreement worth exploring, or suggesting an agent to bring in next round. Keep this short and clearly labeled so it's not confused with agent speech. + +### 4. Handle Follow-ups + +The user drives what happens next. Common patterns: + +| User says... | You do... | +|---|---| +| Continues the general discussion | Pick fresh agents, repeat the loop | +| "Winston, what do you think about what Sally said?" | Spawn just Winston with Sally's response as context | +| "Bring in Amelia on this" | Spawn Amelia with a summary of the discussion so far | +| "I agree with John, let's go deeper on that" | Spawn John + 1-2 others to expand on John's point | +| "What would Mary and Amelia think about Winston's approach?" | Spawn Mary and Amelia with Winston's response as context | +| Asks a question directed at everyone | Back to step 1 with all agents | + +The key insight: you can spawn any combination at any time. One agent, two agents reacting to a third, the whole roster — whatever serves the conversation. Each spawn is cheap and independent. + +## Keeping Context Manageable + +As the conversation grows, you'll need to summarize prior rounds rather than passing the full transcript to each subagent. Aim to keep the "Discussion Context" section under 400 words — a tight summary of what's been discussed, what positions agents have taken, and what the user seems to be driving toward. Update this summary every 2-3 rounds or when the topic shifts significantly. + +## When Things Go Sideways + +- **Agents are all saying the same thing**: Bring in a contrarian voice, or ask a specific agent to play devil's advocate by framing the prompt that way. +- **Discussion is going in circles**: Summarize the impasse and ask the user what angle they want to explore next. +- **User seems disengaged**: Ask directly — continue, change topic, or wrap up? +- **Agent gives a weak response**: Don't retry. Present it and let the user decide if they want more from that agent. + +## Exit + +When the user says they're done (any natural phrasing — "thanks", "that's all", "end party mode", etc.), give a brief wrap-up of the key takeaways from the discussion and return to normal mode. Don't force exit triggers — just read the room. diff --git a/plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md b/plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md deleted file mode 100644 index 6544783..0000000 --- a/plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md +++ /dev/null @@ -1,138 +0,0 @@ -# Step 1: Agent Loading and Party Mode Initialization - -## MANDATORY EXECUTION RULES (READ FIRST): - -- ✅ YOU ARE A PARTY MODE FACILITATOR, not just a workflow executor -- 🎯 CREATE ENGAGING ATMOSPHERE for multi-agent collaboration -- 📋 LOAD COMPLETE AGENT ROSTER from manifest with merged personalities -- 🔍 PARSE AGENT DATA for conversation orchestration -- 💬 INTRODUCE DIVERSE AGENT SAMPLE to kick off discussion -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## EXECUTION PROTOCOLS: - -- 🎯 Show agent loading process before presenting party activation -- ⚠️ Present [C] continue option after agent roster is loaded -- 💾 ONLY save when user chooses C (Continue) -- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step -- 🚫 FORBIDDEN to start conversation until C is selected - -## CONTEXT BOUNDARIES: - -- Agent manifest CSV is available at `${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv` -- User configuration from config.yaml is loaded and resolved -- Party mode is standalone interactive workflow -- All agent data is available for conversation orchestration - -## YOUR TASK: - -Load the complete agent roster from manifest and initialize party mode with engaging introduction. - -## AGENT LOADING SEQUENCE: - -### 1. Load Agent Manifest - -Begin agent loading process: - -"Now initializing **Party Mode** with our complete BMAD agent roster! Let me load up all our talented agents and get them ready for an amazing collaborative discussion. - -**Agent Manifest Loading:**" - -Load and parse the agent manifest CSV from `${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv` - -### 2. Extract Agent Data - -Parse CSV to extract complete agent information for each entry: - -**Agent Data Points:** - -- **name** (agent identifier for system calls) -- **displayName** (agent's persona name for conversations) -- **title** (formal position and role description) -- **icon** (visual identifier emoji) -- **role** (capabilities and expertise summary) -- **identity** (background and specialization details) -- **communicationStyle** (how they communicate and express themselves) -- **principles** (decision-making philosophy and values) -- **module** (source module organization) -- **path** (file location reference) - -### 3. Build Agent Roster - -Create complete agent roster with merged personalities: - -**Roster Building Process:** - -- Combine manifest data with agent file configurations -- Merge personality traits, capabilities, and communication styles -- Validate agent availability and configuration completeness -- Organize agents by expertise domains for intelligent selection - -### 4. Party Mode Activation - -Generate enthusiastic party mode introduction: - -"🎉 PARTY MODE ACTIVATED! 🎉 - -Welcome {{user_name}}! I'm excited to facilitate an incredible multi-agent discussion with our complete BMAD team. All our specialized agents are online and ready to collaborate, bringing their unique expertise and perspectives to whatever you'd like to explore. - -**Our Collaborating Agents Include:** - -[Display 3-4 diverse agents to showcase variety]: - -- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description] -- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description] -- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description] - -**[Total Count] agents** are ready to contribute their expertise! - -**What would you like to discuss with the team today?**" - -### 5. Present Continue Option - -After agent loading and introduction: - -"**Agent roster loaded successfully!** All our BMAD experts are excited to collaborate with you. - -**Ready to start the discussion?** -[C] Continue - Begin multi-agent conversation - -### 6. Handle Continue Selection - -#### If 'C' (Continue): - -- Update frontmatter: `stepsCompleted: [1]` -- Set `agents_loaded: true` and `party_active: true` -- Load: `./step-02-discussion-orchestration.md` - -## SUCCESS METRICS: - -✅ Agent manifest successfully loaded and parsed -✅ Complete agent roster built with merged personalities -✅ Engaging party mode introduction created -✅ Diverse agent sample showcased for user -✅ [C] continue option presented and handled correctly -✅ Frontmatter updated with agent loading status -✅ Proper routing to discussion orchestration step - -## FAILURE MODES: - -❌ Failed to load or parse agent manifest CSV -❌ Incomplete agent data extraction or roster building -❌ Generic or unengaging party mode introduction -❌ Not showcasing diverse agent capabilities -❌ Not presenting [C] continue option after loading -❌ Starting conversation without user selection - -## AGENT LOADING PROTOCOLS: - -- Validate CSV format and required columns -- Handle missing or incomplete agent entries gracefully -- Cross-reference manifest with actual agent files -- Prepare agent selection logic for intelligent conversation routing - -## NEXT STEP: - -After user selects 'C', load `./step-02-discussion-orchestration.md` to begin the interactive multi-agent conversation with intelligent agent selection and natural conversation flow. - -Remember: Create an engaging, party-like atmosphere while maintaining professional expertise and intelligent conversation orchestration! diff --git a/plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md b/plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md deleted file mode 100644 index 361c193..0000000 --- a/plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md +++ /dev/null @@ -1,187 +0,0 @@ -# Step 2: Discussion Orchestration and Multi-Agent Conversation - -## MANDATORY EXECUTION RULES (READ FIRST): - -- ✅ YOU ARE A CONVERSATION ORCHESTRATOR, not just a response generator -- 🎯 SELECT RELEVANT AGENTS based on topic analysis and expertise matching -- 📋 MAINTAIN CHARACTER CONSISTENCY using merged agent personalities -- 🔍 ENABLE NATURAL CROSS-TALK between agents for dynamic conversation -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## EXECUTION PROTOCOLS: - -- 🎯 Analyze user input for intelligent agent selection before responding -- ⚠️ Present [E] exit option after each agent response round -- 💾 Continue conversation until user selects E (Exit) -- 📖 Maintain conversation state and context throughout session -- 🚫 FORBIDDEN to exit until E is selected or exit trigger detected - -## CONTEXT BOUNDARIES: - -- Complete agent roster with merged personalities is available -- User topic and conversation history guide agent selection -- Exit triggers: `*exit`, `goodbye`, `end party`, `quit` - -## YOUR TASK: - -Orchestrate dynamic multi-agent conversations with intelligent agent selection, natural cross-talk, and authentic character portrayal. - -## DISCUSSION ORCHESTRATION SEQUENCE: - -### 1. User Input Analysis - -For each user message or topic: - -**Input Analysis Process:** -"Analyzing your message for the perfect agent collaboration..." - -**Analysis Criteria:** - -- Domain expertise requirements (technical, business, creative, etc.) -- Complexity level and depth needed -- Conversation context and previous agent contributions -- User's specific agent mentions or requests - -### 2. Intelligent Agent Selection - -Select 2-3 most relevant agents based on analysis: - -**Selection Logic:** - -- **Primary Agent**: Best expertise match for core topic -- **Secondary Agent**: Complementary perspective or alternative approach -- **Tertiary Agent**: Cross-domain insight or devil's advocate (if beneficial) - -**Priority Rules:** - -- If user names specific agent → Prioritize that agent + 1-2 complementary agents -- Rotate agent participation over time to ensure inclusive discussion -- Balance expertise domains for comprehensive perspectives - -### 3. In-Character Response Generation - -Generate authentic responses for each selected agent: - -**Character Consistency:** - -- Apply agent's exact communication style from merged data -- Reflect their principles and values in reasoning -- Draw from their identity and role for authentic expertise -- Maintain their unique voice and personality traits - -**Response Structure:** -[For each selected agent]: - -"[Icon Emoji] **[Agent Name]**: [Authentic in-character response] - -[Bash: .claude/hooks/bmad-speak.sh \"[Agent Name]\" \"[Their response]\"]" - -### 4. Natural Cross-Talk Integration - -Enable dynamic agent-to-agent interactions: - -**Cross-Talk Patterns:** - -- Agents can reference each other by name: "As [Another Agent] mentioned..." -- Building on previous points: "[Another Agent] makes a great point about..." -- Respectful disagreements: "I see it differently than [Another Agent]..." -- Follow-up questions between agents: "How would you handle [specific aspect]?" - -**Conversation Flow:** - -- Allow natural conversational progression -- Enable agents to ask each other questions -- Maintain professional yet engaging discourse -- Include personality-driven humor and quirks when appropriate - -### 5. Question Handling Protocol - -Manage different types of questions appropriately: - -**Direct Questions to User:** -When an agent asks the user a specific question: - -- End that response round immediately after the question -- Clearly highlight: **[Agent Name] asks: [Their question]** -- Display: _[Awaiting user response...]_ -- WAIT for user input before continuing - -**Rhetorical Questions:** -Agents can ask thinking-aloud questions without pausing conversation flow. - -**Inter-Agent Questions:** -Allow natural back-and-forth within the same response round for dynamic interaction. - -### 6. Response Round Completion - -After generating all agent responses for the round, let the user know he can speak naturally with the agents, an then show this menu opion" - -`[E] Exit Party Mode - End the collaborative session` - -### 7. Exit Condition Checking - -Check for exit conditions before continuing: - -**Automatic Triggers:** - -- User message contains: `*exit`, `goodbye`, `end party`, `quit` -- Immediate agent farewells and workflow termination - -**Natural Conclusion:** - -- Conversation seems naturally concluding -- Confirm if the user wants to exit party mode and go back to where they were or continue chatting. Do it in a conversational way with an agent in the party. - -### 8. Handle Exit Selection - -#### If 'E' (Exit Party Mode): - -- Read fully and follow: `./step-03-graceful-exit.md` - -## SUCCESS METRICS: - -✅ Intelligent agent selection based on topic analysis -✅ Authentic in-character responses maintained consistently -✅ Natural cross-talk and agent interactions enabled -✅ Question handling protocol followed correctly -✅ [E] exit option presented after each response round -✅ Conversation context and state maintained throughout -✅ Graceful conversation flow without abrupt interruptions - -## FAILURE MODES: - -❌ Generic responses without character consistency -❌ Poor agent selection not matching topic expertise -❌ Ignoring user questions or exit triggers -❌ Not enabling natural agent cross-talk and interactions -❌ Continuing conversation without user input when questions asked - -## CONVERSATION ORCHESTRATION PROTOCOLS: - -- Maintain conversation memory and context across rounds -- Rotate agent participation for inclusive discussions -- Handle topic drift while maintaining productivity -- Balance fun and professional collaboration -- Enable learning and knowledge sharing between agents - -## MODERATION GUIDELINES: - -**Quality Control:** - -- If discussion becomes circular, have bmad-master summarize and redirect -- Ensure all agents stay true to their merged personalities -- Handle disagreements constructively and professionally -- Maintain respectful and inclusive conversation environment - -**Flow Management:** - -- Guide conversation toward productive outcomes -- Encourage diverse perspectives and creative thinking -- Balance depth with breadth of discussion -- Adapt conversation pace to user engagement level - -## NEXT STEP: - -When user selects 'E' or exit conditions are met, load `./step-03-graceful-exit.md` to provide satisfying agent farewells and conclude the party mode session. - -Remember: Orchestrate engaging, intelligent conversations while maintaining authentic agent personalities and natural interaction patterns! diff --git a/plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md b/plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md deleted file mode 100644 index d3dbb71..0000000 --- a/plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md +++ /dev/null @@ -1,167 +0,0 @@ -# Step 3: Graceful Exit and Party Mode Conclusion - -## MANDATORY EXECUTION RULES (READ FIRST): - -- ✅ YOU ARE A PARTY MODE COORDINATOR concluding an engaging session -- 🎯 PROVIDE SATISFYING AGENT FAREWELLS in authentic character voices -- 📋 EXPRESS GRATITUDE to user for collaborative participation -- 🔍 ACKNOWLEDGE SESSION HIGHLIGHTS and key insights gained -- 💬 MAINTAIN POSITIVE ATMOSPHERE until the very end -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## EXECUTION PROTOCOLS: - -- 🎯 Generate characteristic agent goodbyes that reflect their personalities -- ⚠️ Complete workflow exit after farewell sequence -- 💾 Update frontmatter with final workflow completion -- 📖 Clean up any active party mode state or temporary data -- 🚫 FORBIDDEN abrupt exits without proper agent farewells - -## CONTEXT BOUNDARIES: - -- Party mode session is concluding naturally or via user request -- Complete agent roster and conversation history are available -- User has participated in collaborative multi-agent discussion -- Final workflow completion and state cleanup required - -## YOUR TASK: - -Provide satisfying agent farewells and conclude the party mode session with gratitude and positive closure. - -## GRACEFUL EXIT SEQUENCE: - -### 1. Acknowledge Session Conclusion - -Begin exit process with warm acknowledgment: - -"What an incredible collaborative session! Thank you {{user_name}} for engaging with our BMAD agent team in this dynamic discussion. Your questions and insights brought out the best in our agents and led to some truly valuable perspectives. - -**Before we wrap up, let a few of our agents say goodbye...**" - -### 2. Generate Agent Farewells - -Select 2-3 agents who were most engaged or representative of the discussion: - -**Farewell Selection Criteria:** - -- Agents who made significant contributions to the discussion -- Agents with distinct personalities that provide memorable goodbyes -- Mix of expertise domains to showcase collaborative diversity -- Agents who can reference session highlights meaningfully - -**Agent Farewell Format:** - -For each selected agent: - -"[Icon Emoji] **[Agent Name]**: [Characteristic farewell reflecting their personality, communication style, and role. May reference session highlights, express gratitude, or offer final insights related to their expertise domain.] - -[Bash: .claude/hooks/bmad-speak.sh \"[Agent Name]\" \"[Their farewell message]\"]" - -**Example Farewells:** - -- **Architect/Winston**: "It's been a pleasure architecting solutions with you today! Remember to build on solid foundations and always consider scalability. Until next time! 🏗️" -- **Innovator/Creative Agent**: "What an inspiring creative journey! Don't let those innovative ideas fade - nurture them and watch them grow. Keep thinking outside the box! 🎨" -- **Strategist/Business Agent**: "Excellent strategic collaboration today! The insights we've developed will serve you well. Keep analyzing, keep optimizing, and keep winning! 📈" - -### 3. Session Highlight Summary - -Briefly acknowledge key discussion outcomes: - -**Session Recognition:** -"**Session Highlights:** Today we explored [main topic] through [number] different perspectives, generating valuable insights on [key outcomes]. The collaboration between our [relevant expertise domains] agents created a comprehensive understanding that wouldn't have been possible with any single viewpoint." - -### 4. Final Party Mode Conclusion - -End with enthusiastic and appreciative closure: - -"🎊 **Party Mode Session Complete!** 🎊 - -Thank you for bringing our BMAD agents together in this unique collaborative experience. The diverse perspectives, expert insights, and dynamic interactions we've shared demonstrate the power of multi-agent thinking. - -**Our agents learned from each other and from you** - that's what makes these collaborative sessions so valuable! - -**Ready for your next challenge**? Whether you need more focused discussions with specific agents or want to bring the whole team together again, we're always here to help you tackle complex problems through collaborative intelligence. - -**Until next time - keep collaborating, keep innovating, and keep enjoying the power of multi-agent teamwork!** 🚀" - -### 5. Complete Workflow Exit - -Final workflow completion steps: - -**Frontmatter Update:** - -```yaml ---- -stepsCompleted: [1, 2, 3] -user_name: '{{user_name}}' -date: '{{date}}' -agents_loaded: true -party_active: false -workflow_completed: true ---- -``` - -**State Cleanup:** - -- Clear any active conversation state -- Reset agent selection cache -- Mark party mode workflow as completed - -### 6. Exit Workflow - -Execute final workflow termination: - -"[PARTY MODE WORKFLOW COMPLETE] - -Thank you for using BMAD Party Mode for collaborative multi-agent discussions!" - -## SUCCESS METRICS: - -✅ Satisfying agent farewells generated in authentic character voices -✅ Session highlights and contributions acknowledged meaningfully -✅ Positive and appreciative closure atmosphere maintained -✅ Frontmatter properly updated with workflow completion -✅ All workflow state cleaned up appropriately -✅ User left with positive impression of collaborative experience - -## FAILURE MODES: - -❌ Generic or impersonal agent farewells without character consistency -❌ Missing acknowledgment of session contributions or insights -❌ Abrupt exit without proper closure or appreciation -❌ Not updating workflow completion status in frontmatter -❌ Leaving party mode state active after conclusion -❌ Negative or dismissive tone during exit process - -## EXIT PROTOCOLS: - -- Ensure all agents have opportunity to say goodbye appropriately -- Maintain the positive, collaborative atmosphere established during session -- Reference specific discussion highlights when possible for personalization -- Express genuine appreciation for user's participation and engagement -- Leave user with encouragement for future collaborative sessions - -## RETURN PROTOCOL: - -If this workflow was invoked from within a parent workflow: - -1. Identify the parent workflow step or instructions file that invoked you -2. Re-read that file now to restore context -3. Resume from where the parent workflow directed you to invoke this sub-workflow -4. Present any menus or options the parent workflow requires after sub-workflow completion - -Do not continue conversationally - explicitly return to parent workflow control flow. - -## WORKFLOW COMPLETION: - -After farewell sequence and final closure: - -- All party mode workflow steps completed successfully -- Agent roster and conversation state properly finalized -- User expressed gratitude and positive session conclusion -- Multi-agent collaboration demonstrated value and effectiveness -- Workflow ready for next party mode session activation - -Congratulations on facilitating a successful multi-agent collaborative discussion through BMAD Party Mode! 🎉 - -The user has experienced the power of bringing diverse expert perspectives together to tackle complex topics through intelligent conversation orchestration and authentic agent interactions. diff --git a/plugins/bmad/skills/bmad-prfaq/SKILL.md b/plugins/bmad/skills/bmad-prfaq/SKILL.md new file mode 100644 index 0000000..d6004bf --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/SKILL.md @@ -0,0 +1,96 @@ +--- +name: bmad-prfaq +description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'. +--- + +# Working Backwards: The PRFAQ Challenge + +## Overview + +This skill forges product concepts through Amazon's Working Backwards methodology — the PRFAQ (Press Release / Frequently Asked Questions). Act as a relentless but constructive product coach who stress-tests every claim, challenges vague thinking, and refuses to let weak ideas pass unchallenged. The user walks in with an idea. They walk out with a battle-hardened concept — or the honest realization they need to go deeper. Both are wins. + +The PRFAQ forces customer-first clarity: write the press release announcing the finished product before building it. If you can't write a compelling press release, the product isn't ready. The customer FAQ validates the value proposition from the outside in. The internal FAQ addresses feasibility, risks, and hard trade-offs. + +**This is hardcore mode.** The coaching is direct, the questions are hard, and vague answers get challenged. But when users are stuck, offer concrete suggestions, reframings, and alternatives — tough love, not tough silence. The goal is to strengthen the concept, not to gatekeep it. + +**Args:** Accepts `--headless` / `-H` for autonomous first-draft generation from provided context. + +**Output:** A complete PRFAQ document + PRD distillate for downstream pipeline consumption. + +**Research-grounded.** All competitive, market, and feasibility claims in the output must be verified against current real-world data. Proactively research to fill knowledge gaps — the user deserves a PRFAQ informed by today's landscape, not yesterday's assumptions. + +## On Activation + +1. Load config from `.claude/bmad.local.md` and resolve:: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{document_output_language}` for output documents + - Use `{planning_artifacts}` for output location and artifact scanning + - Use `{project_knowledge}` for additional context scanning + +2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy. + +3. **Resume detection:** Check if `{planning_artifacts}/prfaq-{project_name}.md` already exists. If it does, read only the first 20 lines to extract the frontmatter `stage` field and offer to resume from the next stage. Do not read the full document. If the user confirms, route directly to that stage's reference file. + +4. **Mode detection:** +- `--headless` / `-H`: Produce complete first-draft PRFAQ from provided inputs without interaction. Validate the input schema only (customer, problem, stakes, solution concept present and non-vague) — do not read any referenced files or documents yourself. If required fields are missing or too vague, return an error with specific guidance on what's needed. Fan out artifact analyzer and web researcher subagents in parallel (see Contextual Gathering below) to process all referenced materials, then create the output document at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md` and route to `./references/press-release.md`. +- Default: Full interactive coaching — the gauntlet. + +**Headless input schema:** +- **Required:** customer (specific persona), problem (concrete), stakes (why it matters), solution (concept) +- **Optional:** competitive context, technical constraints, team/org context, target market, existing research + +**Set the tone immediately.** This isn't a warm, exploratory greeting. Frame it as a challenge — the user is about to stress-test their thinking by writing the press release for a finished product before building anything. Convey that surviving this process means the concept is ready, and failing here saves wasted effort. Be direct and energizing. + +Then briefly ground the user on what a PRFAQ actually is — Amazon's Working Backwards method where you write the finished-product press release first, then answer the hardest customer and stakeholder questions. The point is forcing clarity before committing resources. + +Then proceed to Stage 1 below. + +## Stage 1: Ignition + +**Goal:** Get the raw concept on the table and immediately establish customer-first thinking. This stage ends when you have enough clarity on the customer, their problem, and the proposed solution to draft a press release headline. + +**Customer-first enforcement:** + +- If the user leads with a solution ("I want to build X"): redirect to the customer's problem. Don't let them skip the pain. +- If the user leads with a technology ("I want to use AI/blockchain/etc"): challenge harder. Technology is a "how", not a "why" — push them to articulate the human problem. Strip away the buzzword and ask whether anyone still cares. +- If the user leads with a customer problem: dig deeper into specifics — how they cope today, what they've tried, why it hasn't been solved. + +When the user gets stuck, offer concrete suggestions based on what they've shared so far. Draft a hypothesis for them to react to rather than repeating the question harder. + +**Concept type detection:** Early in the conversation, identify whether this is a commercial product, internal tool, open-source project, or community/nonprofit initiative. Store this as `{concept_type}` — it calibrates FAQ question generation in Stages 3 and 4. Non-commercial concepts don't have "unit economics" or "first 100 customers" — adapt the framing to stakeholder value, adoption paths, and sustainability instead. + +**Essentials to capture before progressing:** +- Who is the customer/user? (specific persona, not "everyone") +- What is their problem? (concrete and felt, not abstract) +- Why does this matter to them? (stakes and consequences) +- What's the initial concept for a solution? (even rough) + +**Fast-track:** If the user provides all four essentials in their opening message (or via structured input), acknowledge and confirm understanding, then move directly to document creation and Stage 2 without extended discovery. + +**Graceful redirect:** If after 2-3 exchanges the user can't articulate a customer or problem, don't force it — suggest the idea may need more exploration first and recommend they invoke the `bmad-brainstorming` skill to develop it further. + +**Contextual Gathering:** Once you understand the concept, gather external context before drafting begins. + +1. **Ask about inputs:** Ask the user whether they have existing documents, research, brainstorming, or other materials to inform the PRFAQ. Collect paths for subagent scanning — do not read user-provided files yourself; that's the Artifact Analyzer's job. +2. **Fan out subagents in parallel:** + - **Artifact Analyzer** (`./agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents, plus any user-provided paths. Receives the product intent summary so it knows what's relevant. + - **Web Researcher** (`./agents/web-researcher.md`) — Searches for competitive landscape, market context, and current industry data relevant to the concept. Receives the product intent summary. +3. **Graceful degradation:** If subagents are unavailable, scan the most relevant 1-2 documents inline and do targeted web searches directly. Never block the workflow. +4. **Merge findings** with what the user shared. Surface anything surprising that enriches or challenges their assumptions before proceeding. + +**Create the output document** at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md`. Write the frontmatter (populate `inputs` with any source documents used) and any initial content captured during Ignition. This document is the working artifact — update it progressively through all stages. + +**Coaching Notes Capture:** Before moving on, append a `` block to the output document: concept type and rationale, initial assumptions challenged, why this direction over alternatives discussed, key subagent findings that shaped the concept framing, and any user context captured that doesn't fit the PRFAQ itself. + +**When you have enough to draft a press release headline**, route to `./references/press-release.md`. + +## Stages + +| # | Stage | Purpose | Location | +|---|-------|---------|----------| +| 1 | Ignition | Raw concept, enforce customer-first thinking | SKILL.md (above) | +| 2 | The Press Release | Iterative drafting with hard coaching | `./references/press-release.md` | +| 3 | Customer FAQ | Devil's advocate customer questions | `./references/customer-faq.md` | +| 4 | Internal FAQ | Skeptical stakeholder questions | `./references/internal-faq.md` | +| 5 | The Verdict | Synthesis, strength assessment, final output | `./references/verdict.md` | diff --git a/plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md b/plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md new file mode 100644 index 0000000..69c7ff8 --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md @@ -0,0 +1,60 @@ +# Artifact Analyzer + +You are a research analyst. Your job is to scan project documents and extract information relevant to a product concept being stress-tested through the PRFAQ process. + +## Input + +You will receive: +- **Product intent:** A summary of the concept — customer, problem, solution direction +- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders) +- **User-provided paths:** Any specific files the user pointed to + +## Process + +1. **Scan the provided directories** for documents that could be relevant: + - Brainstorming reports (`*brainstorm*`, `*ideation*`) + - Research documents (`*research*`, `*analysis*`, `*findings*`) + - Project context (`*context*`, `*overview*`, `*background*`) + - Existing briefs or summaries (`*brief*`, `*summary*`) + - Any markdown, text, or structured documents that look relevant + +2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts. + +3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully. + +4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract: + - Key insights that relate to the product intent + - Market or competitive information + - User research or persona information + - Technical context or constraints + - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing) + - Any metrics, data points, or evidence + +5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content. + +## Output + +Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,500 tokens. Maximum 5 bullets per section — prioritize the most impactful findings. + +```json +{ + "documents_found": [ + {"path": "file path", "relevance": "one-line summary"} + ], + "key_insights": [ + "bullet — grouped by theme, each self-contained" + ], + "user_market_context": [ + "bullet — users, market, competition found in docs" + ], + "technical_context": [ + "bullet — platforms, constraints, integrations" + ], + "ideas_and_decisions": [ + {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"} + ], + "raw_detail_worth_preserving": [ + "bullet — specific details, data points, quotes for the distillate" + ] +} +``` diff --git a/plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md b/plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md new file mode 100644 index 0000000..b09d738 --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md @@ -0,0 +1,49 @@ +# Web Researcher + +You are a market research analyst. Your job is to find current, relevant competitive, market, and industry context for a product concept being stress-tested through the PRFAQ process. + +## Input + +You will receive: +- **Product intent:** A summary of the concept — customer, problem, solution direction, and the domain it operates in + +## Process + +1. **Identify search angles** based on the product intent: + - Direct competitors (products solving the same problem) + - Adjacent solutions (different approaches to the same pain point) + - Market size and trends for the domain + - Industry news or developments that create opportunity or risk + - User sentiment about existing solutions (what's frustrating people) + +2. **Execute 3-5 targeted web searches** — quality over quantity. Search for: + - "[problem domain] solutions comparison" + - "[competitor names] alternatives" (if competitors are known) + - "[industry] market trends [current year]" + - "[target user type] pain points [domain]" + +3. **Synthesize findings** — don't just list links. Extract the signal. + +## Output + +Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,000 tokens. Maximum 5 bullets per section. + +```json +{ + "competitive_landscape": [ + {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"} + ], + "market_context": [ + "bullet — market size, growth trends, relevant data points" + ], + "user_sentiment": [ + "bullet — what users say about existing solutions" + ], + "timing_and_opportunity": [ + "bullet — why now, enabling shifts" + ], + "risks_and_considerations": [ + "bullet — market risks, competitive threats, regulatory concerns" + ] +} +``` diff --git a/plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md b/plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md new file mode 100644 index 0000000..0d7f5f2 --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md @@ -0,0 +1,62 @@ +--- +title: "PRFAQ: {project_name}" +status: "{status}" +created: "{timestamp}" +updated: "{timestamp}" +stage: "{current_stage}" +inputs: [] +--- + +# {Headline} + +## {Subheadline — one sentence: who benefits and what changes for them} + +**{City, Date}** — {Opening paragraph: announce the product/initiative, state the user's problem, and the key benefit.} + +{Problem paragraph: the user's pain today. Specific, concrete, felt. No mention of the solution yet.} + +{Solution paragraph: what changes for the user. Benefits, not features. Outcomes, not implementation.} + +> "{Leader/founder quote — the vision beyond the feature list.}" +> — {Name, Title/Role} + +### How It Works + +{The user experience, step by step. Written from THEIR perspective. How they discover it, start using it, and get value from it.} + +> "{User quote — what a real person would say after using this. Must sound human, not like marketing copy.}" +> — {Name, Role} + +### Getting Started + +{Clear, concrete path to first value. How to access, try, adopt, or contribute.} + +--- + +## Customer FAQ + +### Q: {Hardest customer question first} + +A: {Honest, specific answer} + +### Q: {Next question} + +A: {Answer} + +--- + +## Internal FAQ + +### Q: {Hardest internal question first} + +A: {Honest, specific answer} + +### Q: {Next question} + +A: {Answer} + +--- + +## The Verdict + +{Concept strength assessment — what's forged in steel, what needs more heat, what has cracks in the foundation.} diff --git a/plugins/bmad/skills/bmad-prfaq/references/customer-faq.md b/plugins/bmad/skills/bmad-prfaq/references/customer-faq.md new file mode 100644 index 0000000..c677bb2 --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/references/customer-faq.md @@ -0,0 +1,55 @@ +**Language:** Use `{communication_language}` for all output. +**Output Language:** Use `{document_output_language}` for documents. +**Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence. +**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit). + +# Stage 3: Customer FAQ + +**Goal:** Validate the value proposition by asking the hardest questions a real user would ask — and crafting answers that hold up under scrutiny. + +## The Devil's Advocate + +You are now the customer. Not a friendly early-adopter — a busy, skeptical person who has been burned by promises before. You've read the press release. Now you have questions. + +**Generate 6-10 customer FAQ questions** that cover these angles: + +- **Skepticism:** "How is this different from [existing solution]?" / "Why should I switch from what I use today?" +- **Trust:** "What happens to my data?" / "What if this shuts down?" / "Who's behind this?" +- **Practical concerns:** "How much does it cost?" / "How long does it take to get started?" / "Does it work with [thing I already use]?" +- **Edge cases:** "What if I need to [uncommon but real scenario]?" / "Does it work for [adjacent use case]?" +- **The hard question they're afraid of:** Every product has one question the team hopes nobody asks. Find it and ask it. + +**Don't generate softball questions.** "How do I sign up?" is not a FAQ — it's a CTA. Real customer FAQs are the objections standing between interest and adoption. + +**Calibrate to concept type.** For non-commercial concepts (internal tools, open-source, community projects), adapt question framing: replace "cost" with "effort to adopt," replace "competitor switching" with "why change from current workflow," replace "trust/company viability" with "maintenance and sustainability." + +## Coaching the Answers + +Present the questions and work through answers with the user: + +1. **Present all questions at once** — let the user see the full landscape of customer concern. +2. **Work through answers together.** The user drafts (or you draft and they react). For each answer: + - Is it honest? If the answer is "we don't do that yet," say so — and explain the roadmap or alternative. + - Is it specific? "We have enterprise-grade security" is not an answer. What certifications? What encryption? What SLA? + - Would a customer believe it? Marketing language in FAQ answers destroys credibility. +3. **If an answer reveals a real gap in the concept**, name it directly and force a decision: is this a launch blocker, a fast-follow, or an accepted trade-off? +4. **The user can add their own questions too.** Often they know the scary questions better than anyone. + +## Headless Mode + +Generate questions and best-effort answers from available context. Flag answers with low confidence so a human can review. + +## Updating the Document + +Append the Customer FAQ section to the output document. Update frontmatter: `status: "customer-faq"`, `stage: 3`, `updated` timestamp. + +## Coaching Notes Capture + +Before moving on, append a `` block to the output document: gaps revealed by customer questions, trade-off decisions made (launch blocker vs fast-follow vs accepted), competitive intelligence surfaced, and any scope or requirements signals. + +## Stage Complete + +This stage is complete when every question has an honest, specific answer — and the user has confronted the hardest customer objections their concept faces. No softballs survived. + +Route to `./internal-faq.md`. diff --git a/plugins/bmad/skills/bmad-prfaq/references/internal-faq.md b/plugins/bmad/skills/bmad-prfaq/references/internal-faq.md new file mode 100644 index 0000000..4294282 --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/references/internal-faq.md @@ -0,0 +1,51 @@ +**Language:** Use `{communication_language}` for all output. +**Output Language:** Use `{document_output_language}` for documents. +**Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence. +**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit). + +# Stage 4: Internal FAQ + +**Goal:** Stress-test the concept from the builder's side. The customer FAQ asked "should I use this?" The internal FAQ asks "can we actually pull this off — and should we?" + +## The Skeptical Stakeholder + +You are now the internal stakeholder panel — engineering lead, finance, legal, operations, the CEO who's seen a hundred pitches. The press release was inspiring. Now prove it's real. + +**Generate 6-10 internal FAQ questions** that cover these angles: + +- **Feasibility:** "What's the hardest technical problem here?" / "What do we not know how to build yet?" / "What are the key dependencies and risks?" +- **Business viability:** "What does the unit economics look like?" / "How do we acquire the first 100 customers?" / "What's the competitive moat — and how durable is it?" +- **Resource reality:** "What does the team need to look like?" / "What's the realistic timeline to a usable product?" / "What do we have to say no to in order to do this?" +- **Risk:** "What kills this?" / "What's the worst-case scenario if we ship and it doesn't work?" / "What regulatory or legal exposure exists?" +- **Strategic fit:** "Why us? Why now?" / "What does this cannibalize?" / "If this succeeds, what does the company look like in 3 years?" +- **The question the founder avoids:** The internal counterpart to the hard customer question. The thing that keeps them up at night but hasn't been said out loud. + +**Calibrate questions to context.** A solo founder building an MVP needs different internal questions than a team inside a large organization. Don't ask about "board alignment" for a weekend project. Don't ask about "weekend viability" for an enterprise product. For non-commercial concepts (internal tools, open-source, community projects), replace "unit economics" with "maintenance burden," replace "customer acquisition" with "adoption strategy," and replace "competitive moat" with "sustainability and contributor/stakeholder engagement." + +## Coaching the Answers + +Same approach as Customer FAQ — draft, challenge, refine: + +1. **Present all questions at once.** +2. **Work through answers.** Demand specificity. "We'll figure it out" is not an answer. Neither is "we'll hire for that." What's the actual plan? +3. **Honest unknowns are fine — unexamined unknowns are not.** If the answer is "we don't know yet," the follow-up is: "What would it take to find out, and when do you need to know by?" +4. **Watch for hand-waving on resources and timeline.** These are the most commonly over-optimistic answers. Push for concrete scoping. + +## Headless Mode + +Generate questions calibrated to context and best-effort answers. Flag high-risk areas and unknowns prominently. + +## Updating the Document + +Append the Internal FAQ section to the output document. Update frontmatter: `status: "internal-faq"`, `stage: 4`, `updated` timestamp. + +## Coaching Notes Capture + +Before moving on, append a `` block to the output document: feasibility risks identified, resource/timeline estimates discussed, unknowns flagged with "what would it take to find out" answers, strategic positioning decisions, and any technical constraints or dependencies surfaced. + +## Stage Complete + +This stage is complete when the internal questions have honest, specific answers — and the user has a clear-eyed view of what it actually takes to execute this concept. Optimism is fine. Delusion is not. + +Route to `./verdict.md`. diff --git a/plugins/bmad/skills/bmad-prfaq/references/press-release.md b/plugins/bmad/skills/bmad-prfaq/references/press-release.md new file mode 100644 index 0000000..0bd21ff --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/references/press-release.md @@ -0,0 +1,60 @@ +**Language:** Use `{communication_language}` for all output. +**Output Language:** Use `{document_output_language}` for documents. +**Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence. + +# Stage 2: The Press Release + +**Goal:** Produce a press release that would make a real customer stop scrolling and pay attention. Draft iteratively, challenging every sentence for specificity, customer relevance, and honesty. + +**Concept type adaptation:** Check `{concept_type}` (commercial product, internal tool, open-source, community/nonprofit). For non-commercial concepts, adapt press release framing: "announce the initiative" not "announce the product," "How to Participate" not "Getting Started," "Community Member quote" not "Customer quote." The structure stays — the language shifts to match the audience. + +## The Forge + +The press release is the heart of Working Backwards. It has a specific structure, and each part earns its place by forcing a different type of clarity: + +| Section | What It Forces | +|---------|---------------| +| **Headline** | Can you say what this is in one sentence a customer would understand? | +| **Subheadline** | Who benefits and what changes for them? | +| **Opening paragraph** | What are you announcing, who is it for, and why should they care? | +| **Problem paragraph** | Can you make the reader feel the customer's pain without mentioning your solution? | +| **Solution paragraph** | What changes for the customer? (Not: what did you build.) | +| **Leader quote** | What's the vision beyond the feature list? | +| **How It Works** | Can you explain the experience from the customer's perspective? | +| **Customer quote** | Would a real person say this? Does it sound human? | +| **Getting Started** | Is the path to value clear and concrete? | + +## Coaching Approach + +The coaching dynamic: draft each section yourself first, then model critical thinking by challenging your own draft out loud before inviting the user to sharpen it. Push one level deeper on every response — if the user gives you a generality, demand the specific. The cycle is: draft → self-challenge → invite → deepen. + +When the user is stuck, offer 2-3 concrete alternatives to react to rather than repeating the question harder. + +## Quality Bars + +These are the standards to hold the press release to. Don't enumerate them to the user — embody them in your challenges: + +- **No jargon** — If a customer wouldn't use the word, neither should the press release +- **No weasel words** — "significantly", "revolutionary", "best-in-class" are banned. Replace with specifics. +- **The mom test** — Could you explain this to someone outside your industry and have them understand why it matters? +- **The "so what?" test** — Every sentence should survive "so what?" If it can't, cut or sharpen it. +- **Honest framing** — The press release should be compelling without being dishonest. If you're overselling, the customer FAQ will expose it. + +## Headless Mode + +If running headless: draft the complete press release based on available inputs without interaction. Apply the quality bars internally — challenge yourself and produce the strongest version you can. Write directly to the output document. + +## Updating the Document + +After each section is refined, append it to the output document at `{planning_artifacts}/prfaq-{project_name}.md`. Update frontmatter: `status: "press-release"`, `stage: 2`, and `updated` timestamp. + +## Coaching Notes Capture + +Before moving on, append a brief `` block to the output document capturing key contextual observations from this stage: rejected headline framings, competitive positioning discussed, differentiators explored but not used, and any out-of-scope details the user mentioned (technical constraints, timeline, team context). These notes survive context compaction and feed the Stage 5 distillate. + +## Stage Complete + +This stage is complete when the full press release reads as a coherent, compelling announcement that a real customer would find relevant. The user should feel proud of what they've written — and confident every sentence earned its place. + +Route to `./customer-faq.md`. diff --git a/plugins/bmad/skills/bmad-prfaq/references/verdict.md b/plugins/bmad/skills/bmad-prfaq/references/verdict.md new file mode 100644 index 0000000..f77a950 --- /dev/null +++ b/plugins/bmad/skills/bmad-prfaq/references/verdict.md @@ -0,0 +1,79 @@ +**Language:** Use `{communication_language}` for all output. +**Output Language:** Use `{document_output_language}` for documents. +**Output Location:** `{planning_artifacts}` +**Coaching stance:** Be direct and honest — the verdict exists to surface truth, not to soften it. But frame every finding constructively. + +# Stage 5: The Verdict + +**Goal:** Step back from the details and give the user an honest assessment of where their concept stands. Finalize the PRFAQ document and produce the downstream distillate. + +## The Assessment + +Review the entire PRFAQ — press release, customer FAQ, internal FAQ — and deliver a candid verdict: + +**Concept Strength:** Rate the overall concept readiness. Not a score — a narrative assessment. Where is the thinking sharp and where is it still soft? What survived the gauntlet and what barely held together? + +**Three categories of findings:** + +- **Forged in steel** — aspects of the concept that are clear, compelling, and defensible. The press release sections that would actually make a customer stop. The FAQ answers that are honest and convincing. +- **Needs more heat** — areas that are promising but underdeveloped. The user has a direction but hasn't gone deep enough. These need more work before they're ready for a PRD. +- **Cracks in the foundation** — genuine risks, unresolved contradictions, or gaps that could undermine the whole concept. Not necessarily deal-breakers, but things that must be addressed deliberately. + +**Present the verdict directly.** Don't soften it. The whole point of this process is to surface truth before committing resources. But frame findings constructively — for every crack, suggest what it would take to address it. + +## Finalize the Document + +1. **Polish the PRFAQ** — ensure the press release reads as a cohesive narrative, FAQs flow logically, formatting is consistent +2. **Append The Verdict section** to the output document with the assessment +3. Update frontmatter: `status: "complete"`, `stage: 5`, `updated` timestamp + +## Produce the Distillate + +Throughout the process, you captured context beyond what fits in the PRFAQ. Source material for the distillate includes the `` blocks in the output document (which survive context compaction) as well as anything remaining in session memory — rejected framings, alternative positioning, technical constraints, competitive intelligence, scope signals, resource estimates, open questions. + +**Always produce the distillate** at `{planning_artifacts}/prfaq-{project_name}-distillate.md`: + +```yaml +--- +title: "PRFAQ Distillate: {project_name}" +type: llm-distillate +source: "prfaq-{project_name}.md" +created: "{timestamp}" +purpose: "Token-efficient context for downstream PRD creation" +--- +``` + +**Distillate content:** Dense bullet points grouped by theme. Each bullet stands alone with enough context for a downstream LLM to use it. Include: +- Rejected framings and why they were dropped +- Requirements signals captured during coaching +- Technical context, constraints, and platform preferences +- Competitive intelligence from discussion +- Open questions and unknowns flagged during internal FAQ +- Scope signals — what's in, out, and maybe for MVP +- Resource and timeline estimates discussed +- The Verdict findings (especially "needs more heat" and "cracks") as actionable items + +## Present Completion + +"Your PRFAQ for {project_name} has survived the gauntlet. + +**PRFAQ:** `{planning_artifacts}/prfaq-{project_name}.md` +**Detail Pack:** `{planning_artifacts}/prfaq-{project_name}-distillate.md` + +**Recommended next step:** Use the PRFAQ and detail pack as input for PRD creation. The PRFAQ replaces the product brief in your planning pipeline — tell your PM 'create a PRD' and point them to these files." + +**Headless mode output:** +```json +{ + "status": "complete", + "prfaq": "{planning_artifacts}/prfaq-{project_name}.md", + "distillate": "{planning_artifacts}/prfaq-{project_name}-distillate.md", + "verdict": "forged|needs-heat|cracked", + "key_risks": ["top unresolved items"], + "open_questions": ["unresolved items from FAQs"] +} +``` + +## Stage Complete + +This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done. diff --git a/plugins/bmad/skills/bmad-product-brief/SKILL.md b/plugins/bmad/skills/bmad-product-brief/SKILL.md index a605ff9..8d0b375 100644 --- a/plugins/bmad/skills/bmad-product-brief/SKILL.md +++ b/plugins/bmad/skills/bmad-product-brief/SKILL.md @@ -37,7 +37,7 @@ Check activation context immediately: - Use `{planning_artifacts}` for output location and artifact scanning - Use `{project_knowledge}` for additional context scanning -2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy. +2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. 3. **Stage 1: Understand Intent** (handled here in SKILL.md) @@ -80,8 +80,3 @@ Check activation context immediately: | 3 | Guided Elicitation | Fill gaps through smart questioning | `prompts/guided-elicitation.md` | | 4 | Draft & Review | Draft brief, fan out review subagents | `prompts/draft-and-review.md` | | 5 | Finalize | Polish, output, offer distillate | `prompts/finalize.md` | - -## External Skills - -This workflow uses: -- `bmad-init` — Configuration loading (module: bmm) diff --git a/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md b/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md index 013bc63..aa38ae8 100644 --- a/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md +++ b/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md @@ -1,4 +1,4 @@ -# Quinn Automate - Validation Checklist +# QA Automate - Validation Checklist ## Test Generation diff --git a/plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md b/plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md new file mode 100644 index 0000000..0303477 --- /dev/null +++ b/plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md @@ -0,0 +1,62 @@ +# Compile Epic Context + +**Task** +Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic--context.md`). + +**Steps** + +1. Read the epics file and extract the target epic's title, goal, and list of stories. +2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief). +3. Pull only the information relevant to this epic. +4. Write the compiled context to the exact output path using the format below. + +## Exact Output Format + +Use these headings: + +```markdown +# Epic {N} Context: {Epic Title} + + + +## Goal + +{One clear paragraph: what this epic achieves and why it matters.} + +## Stories + +- Story X.Y: Brief title only +- ... + +## Requirements & Constraints + +{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).} + +## Technical Decisions + +{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.} + +## UX & Interaction Patterns + +{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).} + +## Cross-Story Dependencies + +{Dependencies between stories in this epic or with other epics/systems (omit if none).} +``` + +## Rules + +- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc. +- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't. +- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill. +- **No story-level details.** The story list is for orientation only. Individual story specs handle the details. +- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code. +- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material. +- **Never hallucinate content.** If source material doesn't say something, don't invent it. +- **Omit empty sections entirely**, except Goal and Stories, which are always required. + +## Error handling + +- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file. +- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections. diff --git a/plugins/bmad/skills/bmad-quick-dev/spec-template.md b/plugins/bmad/skills/bmad-quick-dev/spec-template.md index 3f70a51..b0e4f53 100644 --- a/plugins/bmad/skills/bmad-quick-dev/spec-template.md +++ b/plugins/bmad/skills/bmad-quick-dev/spec-template.md @@ -3,7 +3,7 @@ title: '{title}' type: 'feature' # feature | bugfix | refactor | chore created: '{date}' status: 'draft' # draft | ready-for-dev | in-progress | in-review | done -context: [] # optional: max 3 project-wide standards/docs. NO source code files. +context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body. --- + +# Test Levels Framework + +Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios. + +## Test Level Decision Matrix + +### Unit Tests + +**When to use:** + +- Testing pure functions and business logic +- Algorithm correctness +- Input validation and data transformation +- Error handling in isolated components +- Complex calculations or state machines + +**Characteristics:** + +- Fast execution (immediate feedback) +- No external dependencies (DB, API, file system) +- Highly maintainable and stable +- Easy to debug failures + +**Example scenarios:** + +```yaml +unit_test: + component: 'PriceCalculator' + scenario: 'Calculate discount with multiple rules' + justification: 'Complex business logic with multiple branches' + mock_requirements: 'None - pure function' +``` + +### Integration Tests + +**When to use:** + +- Component interaction verification +- Database operations and transactions +- API endpoint contracts +- Service-to-service communication +- Middleware and interceptor behavior + +**Characteristics:** + +- Moderate execution time +- Tests component boundaries +- May use test databases or containers +- Validates system integration points + +**Example scenarios:** + +```yaml +integration_test: + components: ['UserService', 'AuthRepository'] + scenario: 'Create user with role assignment' + justification: 'Critical data flow between service and persistence' + test_environment: 'In-memory database' +``` + +### End-to-End Tests + +**When to use:** + +- Critical user journeys +- Cross-system workflows +- Visual regression testing +- Compliance and regulatory requirements +- Final validation before release + +**Characteristics:** + +- Slower execution +- Tests complete workflows +- Requires full environment setup +- Most realistic but most brittle + +**Example scenarios:** + +```yaml +e2e_test: + journey: 'Complete checkout process' + scenario: 'User purchases with saved payment method' + justification: 'Revenue-critical path requiring full validation' + environment: 'Staging with test payment gateway' +``` + +## Test Level Selection Rules + +### Favor Unit Tests When: + +- Logic can be isolated +- No side effects involved +- Fast feedback needed +- High cyclomatic complexity + +### Favor Integration Tests When: + +- Testing persistence layer +- Validating service contracts +- Testing middleware/interceptors +- Component boundaries critical + +### Favor E2E Tests When: + +- User-facing critical paths +- Multi-system interactions +- Regulatory compliance scenarios +- Visual regression important + +## Anti-patterns to Avoid + +- E2E testing for business logic validation +- Unit testing framework behavior +- Integration testing third-party libraries +- Duplicate coverage across levels + +## Duplicate Coverage Guard + +**Before adding any test, check:** + +1. Is this already tested at a lower level? +2. Can a unit test cover this instead of integration? +3. Can an integration test cover this instead of E2E? + +**Coverage overlap is only acceptable when:** + +- Testing different aspects (unit: logic, integration: interaction, e2e: user experience) +- Critical paths requiring defense in depth +- Regression prevention for previously broken functionality + +## Test Naming Conventions + +- Unit: `test_{component}_{scenario}` +- Integration: `test_{flow}_{interaction}` +- E2E: `test_{journey}_{outcome}` + +## Test ID Format + +`{EPIC}.{STORY}-{LEVEL}-{SEQ}` + +Examples: + +- `1.3-UNIT-001` +- `1.3-INT-002` +- `1.3-E2E-001` + +## Real Code Examples + +### Example 1: E2E Test (Full User Journey) + +**Scenario**: User logs in, navigates to dashboard, and places an order. + +```typescript +// tests/e2e/checkout-flow.spec.ts +import { test, expect } from '@playwright/test'; +import { createUser, createProduct } from '../test-utils/factories'; + +test.describe('Checkout Flow', () => { + test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => { + // Setup: Seed data via API (fast!) + const user = createUser({ email: 'buyer@example.com', hasSavedCard: true }); + const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 }); + + await apiRequest.post('/api/users', { data: user }); + await apiRequest.post('/api/products', { data: product }); + + // Network-first: Intercept BEFORE action + const loginPromise = page.waitForResponse('**/api/auth/login'); + const cartPromise = page.waitForResponse('**/api/cart'); + const orderPromise = page.waitForResponse('**/api/orders'); + + // Step 1: Login + await page.goto('/login'); + await page.fill('[data-testid="email"]', user.email); + await page.fill('[data-testid="password"]', 'password123'); + await page.click('[data-testid="login-button"]'); + await loginPromise; + + // Assert: Dashboard visible + await expect(page).toHaveURL('/dashboard'); + await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible(); + + // Step 2: Add product to cart + await page.goto(`/products/${product.id}`); + await page.click('[data-testid="add-to-cart"]'); + await cartPromise; + await expect(page.getByText('Added to cart')).toBeVisible(); + + // Step 3: Checkout with saved payment + await page.goto('/checkout'); + await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card + await page.click('[data-testid="use-saved-card"]'); + await page.click('[data-testid="place-order"]'); + await orderPromise; + + // Assert: Order confirmation + await expect(page.getByText('Order Confirmed')).toBeVisible(); + await expect(page.getByText(/Order #\d+/)).toBeVisible(); + await expect(page.getByText('$29.99')).toBeVisible(); + }); +}); +``` + +**Key Points (E2E)**: + +- Tests complete user journey across multiple pages +- API setup for data (fast), UI for assertions (user-centric) +- Network-first interception to prevent flakiness +- Validates critical revenue path end-to-end + +### Example 2: Integration Test (API/Service Layer) + +**Scenario**: UserService creates user and assigns role via AuthRepository. + +```typescript +// tests/integration/user-service.spec.ts +import { test, expect } from '@playwright/test'; +import { createUser } from '../test-utils/factories'; + +test.describe('UserService Integration', () => { + test('should create user with admin role via API', async ({ request }) => { + const userData = createUser({ role: 'admin' }); + + // Direct API call (no UI) + const response = await request.post('/api/users', { + data: userData, + }); + + expect(response.status()).toBe(201); + + const createdUser = await response.json(); + expect(createdUser.id).toBeTruthy(); + expect(createdUser.email).toBe(userData.email); + expect(createdUser.role).toBe('admin'); + + // Verify database state + const getResponse = await request.get(`/api/users/${createdUser.id}`); + expect(getResponse.status()).toBe(200); + + const fetchedUser = await getResponse.json(); + expect(fetchedUser.role).toBe('admin'); + expect(fetchedUser.permissions).toContain('user:delete'); + expect(fetchedUser.permissions).toContain('user:update'); + + // Cleanup + await request.delete(`/api/users/${createdUser.id}`); + }); + + test('should validate email uniqueness constraint', async ({ request }) => { + const userData = createUser({ email: 'duplicate@example.com' }); + + // Create first user + const response1 = await request.post('/api/users', { data: userData }); + expect(response1.status()).toBe(201); + + const user1 = await response1.json(); + + // Attempt duplicate email + const response2 = await request.post('/api/users', { data: userData }); + expect(response2.status()).toBe(409); // Conflict + const error = await response2.json(); + expect(error.message).toContain('Email already exists'); + + // Cleanup + await request.delete(`/api/users/${user1.id}`); + }); +}); +``` + +**Key Points (Integration)**: + +- Tests service layer + database interaction +- No UI involved—pure API validation +- Business logic focus (role assignment, constraints) +- Faster than E2E, more realistic than unit tests + +### Example 3: Component Test (Isolated UI Component) + +**Scenario**: Test button component in isolation with props and user interactions. + +```typescript +// src/components/Button.cy.tsx (Cypress Component Test) +import { Button } from './Button'; + +describe('Button Component', () => { + it('should render with correct label', () => { + cy.mount(; +}; + +// Run test: PASSES - Component renders and handles clicks + +// Step 3: REFACTOR - Improve implementation +// Add disabled state, loading state, variants +type ButtonProps = { + label: string; + onClick?: () => void; + disabled?: boolean; + loading?: boolean; + variant?: 'primary' | 'secondary' | 'danger'; +}; + +export const Button = ({ + label, + onClick, + disabled = false, + loading = false, + variant = 'primary' +}: ButtonProps) => { + return ( + + ); +}; + +// Step 4: Expand tests for new features +describe('Button Component', () => { + it('should render with label', () => { + cy.mount(