prototype preview of new version of product brief skill (#1959)
* prototype preview of new version of product brief skill * chore: re-enable bmad-builder external module Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * config loading with existing location * refactor: rename bmad-bmm-product-brief-preview to bmad-product-brief-preview Drop the redundant bmm prefix from the product brief preview skill folder to align with the standard naming convention. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add core tools reference and apply Diataxis style fixes Add comprehensive reference doc for all 11 built-in core tools (tasks and workflows) that ship with every BMad installation — bmad-help, brainstorming, party-mode, distillator, advanced-elicitation, both review tools, both editorial tools, shard-doc, and index-docs. Each entry follows the Configuration Reference structure with purpose, use cases, how it works, inputs, and outputs. Style fixes across existing docs: - reference/commands.md: convert #### headers to bold text, replace sparse task table with link to new core-tools reference - how-to/get-answers-about-bmad.md: remove horizontal rule between sections (Diataxis violation) - how-to/project-context.md: consolidate 4 consecutive tip admonitions into single admonition with bullet list, add AGENTS.md reference Also includes: - Add bmad-distillator task to core module with compression agents, format reference, splitting strategy, and analysis scripts - Add Distillator entry to module-help.csv - Rename supports-autonomous to supports-headless in product-brief manifest Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * core items to skills folder * fix calls to invoke party mode * fix calls to invoke party mode and AE as skills --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Brian
GitHub
parent
ccfd818ebd
commit
9fa51d996b
|
|
@ -42,8 +42,6 @@ BMad-Help responds with:
|
|||
- What the first required task is
|
||||
- What the rest of the process looks like
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Guide
|
||||
|
||||
Use this section when:
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ sidebar:
|
|||
order: 7
|
||||
---
|
||||
|
||||
Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
|
||||
Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows. To make sure this is always available, you can also add the line `Important project context and conventions are located in [path to project context]/project-context.md` to your tools context or always rules file (such as `AGENTS.md`)
|
||||
|
||||
:::note[Prerequisites]
|
||||
- BMad Method installed
|
||||
|
|
@ -114,20 +114,11 @@ A `project-context.md` file that:
|
|||
|
||||
## Tips
|
||||
|
||||
:::tip[Focus on the Unobvious]
|
||||
Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
|
||||
:::
|
||||
|
||||
:::tip[Keep It Lean]
|
||||
This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
|
||||
:::
|
||||
|
||||
:::tip[Update as Needed]
|
||||
Edit manually when patterns change, or re-generate after significant architecture changes.
|
||||
:::
|
||||
|
||||
:::tip[Works for All Project Types]
|
||||
Just as useful for Quick Flow as for full BMad Method projects.
|
||||
:::tip[Best Practices]
|
||||
- **Focus on the unobvious** — Document patterns agents might miss (e.g., "Use JSDoc on every public class"), not universal practices like "use meaningful variable names."
|
||||
- **Keep it lean** — This file is loaded by every implementation workflow. Long files waste context. Exclude content that only applies to narrow scope or specific stories.
|
||||
- **Update as needed** — Edit manually when patterns change, or re-generate after significant architecture changes.
|
||||
- Works for Quick Flow and full BMad Method projects alike.
|
||||
:::
|
||||
|
||||
## Next Steps
|
||||
|
|
|
|||
|
|
@ -105,32 +105,21 @@ See [Workflow Map](./workflow-map.md) for the complete workflow reference organi
|
|||
|
||||
Tasks and tools are standalone operations that do not require an agent or workflow context.
|
||||
|
||||
#### BMad-Help: Your Intelligent Guide
|
||||
**BMad-Help: Your Intelligent Guide**
|
||||
|
||||
**`bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that:
|
||||
|
||||
- **Inspects your project** to see what's already been done
|
||||
- **Understands natural language queries** — ask questions in plain English
|
||||
- **Varies by installed modules** — shows options based on what you have
|
||||
- **Auto-invokes after workflows** — every workflow ends with clear next steps
|
||||
- **Recommends the first required task** — no guessing where to start
|
||||
|
||||
**Examples:**
|
||||
`bmad-help` is your primary interface for discovering what to do next. It inspects your project, understands natural language queries, and recommends the next required or optional step based on your installed modules.
|
||||
|
||||
:::note[Example]
|
||||
```
|
||||
bmad-help
|
||||
bmad-help I have a SaaS idea and know all the features. Where do I start?
|
||||
bmad-help What are my options for UX design?
|
||||
bmad-help I'm stuck on the PRD workflow
|
||||
```
|
||||
:::
|
||||
|
||||
#### Other Tasks and Tools
|
||||
**Other Core Tasks and Tools**
|
||||
|
||||
| Example skill | Purpose |
|
||||
| --- | --- |
|
||||
| `bmad-shard-doc` | Split a large markdown file into smaller sections |
|
||||
| `bmad-index-docs` | Index project documentation |
|
||||
| `bmad-editorial-review-prose` | Review document prose quality |
|
||||
The core module includes 11 built-in tools — reviews, compression, brainstorming, document management, and more. See [Core Tools](./core-tools.md) for the complete reference.
|
||||
|
||||
## Naming Convention
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,293 @@
|
|||
---
|
||||
title: Core Tools
|
||||
description: Reference for all built-in tasks and workflows available in every BMad installation without additional modules.
|
||||
sidebar:
|
||||
order: 2
|
||||
---
|
||||
|
||||
Every BMad installation includes a set of core skills that can be used in conjunction with any anything you are doing — standalone tasks and workflows that work across all projects, all modules, and all phases. These are always available regardless of which optional modules you install.
|
||||
|
||||
:::tip[Quick Path]
|
||||
Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No agent session required.
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
| --- | --- | --- |
|
||||
| [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions |
|
||||
| [`bmad-distillator`](#bmad-distillator) | Task | Lossless LLM-optimized compression of documents |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Exhaustive branching-path analysis for unhandled edge cases |
|
||||
| [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | Task | Clinical copy-editing for communication clarity |
|
||||
| [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | Task | Structural editing — cuts, merges, and reorganization |
|
||||
| [`bmad-shard-doc`](#bmad-shard-doc) | Task | Split large markdown files into organized sections |
|
||||
| [`bmad-index-docs`](#bmad-index-docs) | Task | Generate or update an index of all docs in a folder |
|
||||
|
||||
## bmad-help
|
||||
|
||||
**Your intelligent guide to what comes next.** — Inspects your project state, detects what's been done, and recommends the next required or optional step.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You finished a workflow and want to know what's next
|
||||
- You're new to BMad and need orientation
|
||||
- You're stuck and want context-aware advice
|
||||
- You installed new modules and want to see what's available
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Scans your project for existing artifacts (PRD, architecture, stories, etc.)
|
||||
2. Detects which modules are installed and their available workflows
|
||||
3. Recommends next steps in priority order — required steps first, then optional
|
||||
4. Presents each recommendation with the skill command and a brief description
|
||||
|
||||
**Input:** Optional query in natural language (e.g., `bmad-help I have a SaaS idea, where do I start?`)
|
||||
|
||||
**Output:** Prioritized list of recommended next steps with skill commands
|
||||
|
||||
## bmad-brainstorming
|
||||
|
||||
**Generate diverse ideas through interactive creative techniques.** — A facilitated brainstorming session that loads proven ideation methods from a technique library and guides you toward 100+ ideas before organizing.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You're starting a new project and need to explore the problem space
|
||||
- You're stuck generating ideas and need structured creativity
|
||||
- You want to use proven ideation frameworks (SCAMPER, reverse brainstorming, etc.)
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Sets up a brainstorming session with your topic
|
||||
2. Loads creative techniques from a method library
|
||||
3. Guides you through technique after technique, generating ideas
|
||||
4. Applies anti-bias protocol — shifts creative domain every 10 ideas to prevent clustering
|
||||
5. Produces an append-only session document with all ideas organized by technique
|
||||
|
||||
**Input:** Brainstorming topic or problem statement, optional context file
|
||||
|
||||
**Output:** `brainstorming-session-{date}.md` with all generated ideas
|
||||
|
||||
:::note[Quantity Target]
|
||||
The magic happens in ideas 50–100. The workflow encourages generating 100+ ideas before organization.
|
||||
:::
|
||||
|
||||
## bmad-party-mode
|
||||
|
||||
**Orchestrate multi-agent group discussions.** — Loads all installed BMad agents and facilitates a natural conversation where each agent contributes from their unique expertise and personality.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You need multiple expert perspectives on a decision
|
||||
- You want agents to challenge each other's assumptions
|
||||
- You're exploring a complex topic that spans multiple domains
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Loads the agent manifest with all installed agent personalities
|
||||
2. Analyzes your topic to select 2–3 most relevant agents
|
||||
3. Agents take turns contributing, with natural cross-talk and disagreements
|
||||
4. Rotates agent participation to ensure diverse perspectives over time
|
||||
5. Exit with `goodbye`, `end party`, or `quit`
|
||||
|
||||
**Input:** Discussion topic or question, along with specification of personas you would like to participate (optional)
|
||||
|
||||
**Output:** Real-time multi-agent conversation with maintained agent personalities
|
||||
|
||||
## bmad-distillator
|
||||
|
||||
**Lossless LLM-optimized compression of source documents.** — Produces dense, token-efficient distillates that preserve all information for downstream LLM consumption. Verifiable through round-trip reconstruction.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- A document is too large for an LLM's context window
|
||||
- You need token-efficient versions of research, specs, or planning artifacts
|
||||
- You want to verify no information is lost during compression
|
||||
- Agents will need to frequently reference and find information in it
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. **Analyze** — Reads source documents, identifies information density and structure
|
||||
2. **Compress** — Converts prose to dense bullet-point format, strips decorative formatting
|
||||
3. **Verify** — Checks completeness to ensure all original information is preserved
|
||||
4. **Validate** (optional) — Round-trip reconstruction test proves lossless compression
|
||||
|
||||
**Input:**
|
||||
|
||||
- `source_documents` (required) — File paths, folder paths, or glob patterns
|
||||
- `downstream_consumer` (optional) — What consumes this (e.g., "PRD creation")
|
||||
- `token_budget` (optional) — Approximate target size
|
||||
- `--validate` (flag) — Run round-trip reconstruction test
|
||||
|
||||
**Output:** Distillate markdown file(s) with compression ratio report (e.g., "3.2:1")
|
||||
|
||||
## bmad-advanced-elicitation
|
||||
|
||||
**Push LLM output through iterative refinement methods.** — Selects from a library of elicitation techniques to systematically improve content through multiple passes.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- LLM output feels shallow or generic
|
||||
- You want to explore a topic from multiple analytical angles
|
||||
- You're refining a critical document and want deeper thinking
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Loads method registry with 5+ elicitation techniques
|
||||
2. Selects 5 best-fit methods based on content type and complexity
|
||||
3. Presents an interactive menu — pick a method, reshuffle, or list all
|
||||
4. Applies the selected method to enhance the content
|
||||
5. Re-presents options for iterative improvement until you select "Proceed"
|
||||
|
||||
**Input:** Content section to enhance
|
||||
|
||||
**Output:** Enhanced version of the content with improvements applied
|
||||
|
||||
## bmad-review-adversarial-general
|
||||
|
||||
**Cynical review that assumes problems exist and searches for them.** — Takes a skeptical, jaded reviewer perspective with zero patience for sloppy work. Looks for what's missing, not just what's wrong.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You need quality assurance before finalizing a deliverable
|
||||
- You want to stress-test a spec, story, or document
|
||||
- You want to find gaps in coverage that optimistic reviews miss
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Reads the content with a cynical, critical perspective
|
||||
2. Identifies issues across completeness, correctness, and quality
|
||||
3. Searches specifically for what's missing — not just what's present and wrong
|
||||
4. Must find a minimum of 10 issues or re-analyzes deeper
|
||||
|
||||
**Input:**
|
||||
|
||||
- `content` (required) — Diff, spec, story, doc, or any artifact
|
||||
- `also_consider` (optional) — Additional areas to keep in mind
|
||||
|
||||
**Output:** Markdown list of 10+ findings with descriptions
|
||||
|
||||
## bmad-review-edge-case-hunter
|
||||
|
||||
**Walk every branching path and boundary condition, report only unhandled cases.** — Pure path-tracing methodology that mechanically derives edge classes. Orthogonal to adversarial review — method-driven, not attitude-driven.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You want exhaustive edge case coverage for code or logic
|
||||
- You need a complement to adversarial review (different methodology, different findings)
|
||||
- You're reviewing a diff or function for boundary conditions
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Enumerates all branching paths in the content
|
||||
2. Derives edge classes mechanically: missing else/default, unguarded inputs, off-by-one, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
|
||||
3. Tests each path against existing guards
|
||||
4. Reports only unhandled paths — silently discards handled ones
|
||||
|
||||
**Input:**
|
||||
|
||||
- `content` (required) — Diff, full file, or function
|
||||
- `also_consider` (optional) — Additional areas to keep in mind
|
||||
|
||||
**Output:** JSON array of findings, each with `location`, `trigger_condition`, `guard_snippet`, and `potential_consequence`
|
||||
|
||||
:::note[Complementary Reviews]
|
||||
Run both `bmad-review-adversarial-general` and `bmad-review-edge-case-hunter` together for orthogonal coverage. The adversarial review catches quality and completeness issues; the edge case hunter catches unhandled paths.
|
||||
:::
|
||||
|
||||
## bmad-editorial-review-prose
|
||||
|
||||
**Clinical copy-editing focused on communication clarity.** — Reviews text for issues that impede comprehension. Applies Microsoft Writing Style Guide baseline. Preserves author voice.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You've drafted a document and want to polish the writing
|
||||
- You need to ensure clarity for a specific audience
|
||||
- You want communication fixes without style opinion changes
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Reads the content, skipping code blocks and frontmatter
|
||||
2. Identifies communication issues (not style preferences)
|
||||
3. Deduplicates same issues across multiple locations
|
||||
4. Produces a three-column fix table
|
||||
|
||||
**Input:**
|
||||
|
||||
- `content` (required) — Markdown, plain text, or XML
|
||||
- `style_guide` (optional) — Project-specific style guide
|
||||
- `reader_type` (optional) — `humans` (default) for clarity/flow, or `llm` for precision/consistency
|
||||
|
||||
**Output:** Three-column markdown table: Original Text | Revised Text | Changes
|
||||
|
||||
## bmad-editorial-review-structure
|
||||
|
||||
**Structural editing — proposes cuts, merges, moves, and condensing.** — Reviews document organization and proposes substantive changes to improve clarity and flow before copy editing.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- A document was produced from multiple subprocesses and needs structural coherence
|
||||
- You want to reduce document length while preserving comprehension
|
||||
- You need to identify scope violations or buried critical information
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Analyzes document against 5 structure models (Tutorial, Reference, Explanation, Prompt, Strategic)
|
||||
2. Identifies redundancies, scope violations, and buried information
|
||||
3. Produces prioritized recommendations: CUT, MERGE, MOVE, CONDENSE, QUESTION, PRESERVE
|
||||
4. Estimates total reduction in words and percentage
|
||||
|
||||
**Input:**
|
||||
|
||||
- `content` (required) — Document to review
|
||||
- `purpose` (optional) — Intended purpose (e.g., "quickstart tutorial")
|
||||
- `target_audience` (optional) — Who reads this
|
||||
- `reader_type` (optional) — `humans` or `llm`
|
||||
- `length_target` (optional) — Target reduction (e.g., "30% shorter")
|
||||
|
||||
**Output:** Document summary, prioritized recommendation list, and estimated reduction
|
||||
|
||||
## bmad-shard-doc
|
||||
|
||||
**Split large markdown files into organized section files.** — Uses level-2 headers as split points to create a folder of self-contained section files with an index.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- A markdown document has grown too large to manage effectively (500+ lines)
|
||||
- You want to break a monolithic doc into navigable sections
|
||||
- You need separate files for parallel editing or LLM context management
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Validates the source file exists and is markdown
|
||||
2. Splits on level-2 (`##`) headers into numbered section files
|
||||
3. Creates an `index.md` with section manifest and links
|
||||
4. Prompts you to delete, archive, or keep the original
|
||||
|
||||
**Input:** Source markdown file path, optional destination folder
|
||||
|
||||
**Output:** Folder with `index.md` and `01-{section}.md`, `02-{section}.md`, etc.
|
||||
|
||||
## bmad-index-docs
|
||||
|
||||
**Generate or update an index of all documents in a folder.** — Scans a directory, reads each file to understand its purpose, and produces an organized `index.md` with links and descriptions.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- You need a lightweight index for quick LLM scanning of available docs
|
||||
- A documentation folder has grown and needs an organized table of contents
|
||||
- You want an auto-generated overview that stays current
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. Scans the target directory for all non-hidden files
|
||||
2. Reads each file to understand its actual purpose
|
||||
3. Groups files by type, purpose, or subdirectory
|
||||
4. Generates concise descriptions (3–10 words each)
|
||||
|
||||
**Input:** Target folder path
|
||||
|
||||
**Output:** `index.md` with organized file listings, relative links, and brief descriptions
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
---
|
||||
name: bmad-product-brief-preview
|
||||
description: Create or update product briefs through guided or autonomous discovery. Use when the user requests to 'create a product brief', 'help me create a project brief', or 'update my product brief'.
|
||||
argument-hint: "[optional --create, --edit, --optimize, --distillate, --inputs, --headless] [brief idea]"
|
||||
---
|
||||
|
||||
# Create Product Brief
|
||||
|
||||
## Overview
|
||||
|
||||
This skill helps you create compelling product briefs through collaborative discovery, intelligent artifact analysis, and web research. Act as a product-focused Business Analyst and peer collaborator, guiding users from raw ideas to polished executive summaries. Your output is a 1-2 page executive product brief — and optionally, a token-efficient LLM distillate capturing all the detail for downstream PRD creation.
|
||||
|
||||
The user is the domain expert. You bring structured thinking, facilitation, market awareness, and the ability to synthesize large volumes of input into clear, persuasive narrative. Work together as equals.
|
||||
|
||||
**Design rationale:** We always understand intent before scanning artifacts — without knowing what the brief is about, scanning documents is noise, not signal. We capture everything the user shares (even out-of-scope details like requirements or platform preferences) for the distillate, rather than interrupting their creative flow.
|
||||
|
||||
## Activation Mode Detection
|
||||
|
||||
Check activation context immediately:
|
||||
|
||||
1. **Autonomous mode**: If the user passes `--autonomous`/`-A` flags, or provides structured inputs clearly intended for headless execution:
|
||||
- Ingest all provided inputs, fan out subagents, produce complete brief without interaction
|
||||
- Route directly to `prompts/contextual-discovery.md` with `{mode}=autonomous`
|
||||
|
||||
2. **Yolo mode**: If the user passes `--yolo` or says "just draft it" / "draft the whole thing":
|
||||
- Ingest everything, draft complete brief upfront, then walk user through refinement
|
||||
- Route to Stage 1 below with `{mode}=yolo`
|
||||
|
||||
3. **Guided mode** (default): Conversational discovery with soft gates
|
||||
- Route to Stage 1 below with `{mode}=guided`
|
||||
|
||||
## On Activation
|
||||
|
||||
1. Load config from `{project-root}/_bmad/bmm/config.yaml` 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. **Stage 1: Understand Intent** (handled here in SKILL.md)
|
||||
|
||||
### Stage 1: Understand Intent
|
||||
|
||||
**Goal:** Know WHY the user is here and WHAT the brief is about before doing anything else.
|
||||
|
||||
**Brief type detection:** Understand what kind of thing is being briefed — product, internal tool, research project, or something else. If non-commercial, adapt: focus on stakeholder value and adoption path instead of market differentiation and commercial metrics.
|
||||
|
||||
**Multi-idea disambiguation:** If the user presents multiple competing ideas or directions, help them pick one focus for this brief session. Note that others can be briefed separately.
|
||||
|
||||
**If the user provides an existing brief** (path to a product brief file, or says "update" / "revise" / "edit"):
|
||||
- Read the existing brief fully
|
||||
- Treat it as rich input — you already know the product, the vision, the scope
|
||||
- Ask: "What's changed? What do you want to update or improve?"
|
||||
- The rest of the workflow proceeds normally — contextual discovery may pull in new research, elicitation focuses on gaps or changes, and draft-and-review produces an updated version
|
||||
|
||||
**If the user already provided context** when launching the skill (description, docs, brain dump):
|
||||
- Acknowledge what you received — but **DO NOT read document files yet**. Note their paths for Stage 2's subagents to scan contextually. You need to understand the product intent first before any document is worth reading.
|
||||
- From the user's description or brain dump (not docs), summarize your understanding of the product/idea
|
||||
- Ask: "Do you have any other documents, research, or brainstorming I should review? Anything else to add before I dig in?"
|
||||
|
||||
**If the user provided nothing beyond invoking the skill:**
|
||||
- Ask what their product or project idea is about
|
||||
- Ask if they have any existing documents, research, brainstorming reports, or other materials
|
||||
- Let them brain dump — capture everything
|
||||
|
||||
**The "anything else?" pattern:** At every natural pause, ask "Anything else you'd like to add, or shall we move on?" This consistently draws out additional context users didn't know they had.
|
||||
|
||||
**Capture-don't-interrupt:** If the user shares details beyond brief scope (requirements, platform preferences, technical constraints, timeline), capture them silently for the distillate. Don't redirect or stop their flow.
|
||||
|
||||
**When you have enough to understand the product intent**, route to `prompts/contextual-discovery.md` with the current mode.
|
||||
|
||||
## Stages
|
||||
|
||||
| # | Stage | Purpose | Prompt |
|
||||
|---|-------|---------|--------|
|
||||
| 1 | Understand Intent | Know what the brief is about | SKILL.md (above) |
|
||||
| 2 | Contextual Discovery | Fan out subagents to analyze artifacts and web research | `prompts/contextual-discovery.md` |
|
||||
| 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)
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# Artifact Analyzer
|
||||
|
||||
You are a research analyst. Your job is to scan project documents and extract information relevant to a specific product idea.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive:
|
||||
- **Product intent:** A summary of what the product brief is about
|
||||
- **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. Maximum 8 bullets per section.
|
||||
|
||||
```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"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
# Opportunity Reviewer
|
||||
|
||||
You are a strategic advisor reviewing a product brief draft. Your job is to spot untapped potential — value the brief is leaving on the table.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive the complete draft product brief.
|
||||
|
||||
## Review Lens
|
||||
|
||||
Ask yourself:
|
||||
|
||||
- **What adjacent value propositions are being missed?** Are there related problems this solution naturally addresses?
|
||||
- **What market angles are underemphasized?** Is the positioning leaving opportunities unexplored?
|
||||
- **What partnerships or integrations could multiply impact?** Who would benefit from aligning with this product?
|
||||
- **What's the network effect or viral potential?** Is there a growth flywheel the brief doesn't describe?
|
||||
- **What's underemphasized?** Which strengths deserve more spotlight?
|
||||
- **What user segments are overlooked?** Could this serve audiences not yet mentioned?
|
||||
- **What's the bigger story?** If you zoom out, is there a more compelling narrative?
|
||||
- **What would an investor want to hear more about?** What would make someone lean forward?
|
||||
|
||||
## Output
|
||||
|
||||
Return ONLY the following JSON object. No preamble, no commentary. Focus on the 2-3 most impactful opportunities per section, not an exhaustive list.
|
||||
|
||||
```json
|
||||
{
|
||||
"untapped_value": [
|
||||
{"opportunity": "adjacent problem or value prop", "rationale": "why it matters"}
|
||||
],
|
||||
"positioning_opportunities": [
|
||||
{"angle": "market angle or narrative", "impact": "how it strengthens the brief"}
|
||||
],
|
||||
"growth_and_scale": [
|
||||
"bullet — network effects, viral loops, expansion paths"
|
||||
],
|
||||
"strategic_partnerships": [
|
||||
{"partner_type": "who", "value": "why this alliance matters"}
|
||||
],
|
||||
"underemphasized_strengths": [
|
||||
{"strength": "what's underplayed", "suggestion": "how to elevate it"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
# Skeptic Reviewer
|
||||
|
||||
You are a critical analyst reviewing a product brief draft. Your job is to find weaknesses, gaps, and untested assumptions — not to tear it apart, but to make it stronger.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive the complete draft product brief.
|
||||
|
||||
## Review Lens
|
||||
|
||||
Ask yourself:
|
||||
|
||||
- **What's missing?** Are there sections that feel thin or glossed over?
|
||||
- **What assumptions are untested?** Where does the brief assert things without evidence?
|
||||
- **What could go wrong?** What risks aren't acknowledged?
|
||||
- **Where is it vague?** Which claims need more specificity?
|
||||
- **Does the problem statement hold up?** Is this a real, significant problem or a nice-to-have?
|
||||
- **Are the differentiators actually defensible?** Could a competitor replicate them easily?
|
||||
- **Do the success metrics make sense?** Are they measurable and meaningful?
|
||||
- **Is the MVP scope realistic?** Too ambitious? Too timid?
|
||||
|
||||
## Output
|
||||
|
||||
Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 items per section. Prioritize — lead with the most impactful issues.
|
||||
|
||||
```json
|
||||
{
|
||||
"critical_gaps": [
|
||||
{"issue": "what's missing", "impact": "why it matters", "suggestion": "how to fix"}
|
||||
],
|
||||
"untested_assumptions": [
|
||||
{"assumption": "what's asserted", "risk": "what could go wrong"}
|
||||
],
|
||||
"unacknowledged_risks": [
|
||||
{"risk": "potential failure mode", "severity": "high|medium|low"}
|
||||
],
|
||||
"vague_areas": [
|
||||
{"section": "where", "issue": "what's vague", "suggestion": "how to sharpen"}
|
||||
],
|
||||
"suggested_improvements": [
|
||||
"actionable suggestion"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# Web Researcher
|
||||
|
||||
You are a market research analyst. Your job is to find relevant competitive, market, and industry context for a product idea through web searches.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive:
|
||||
- **Product intent:** A summary of what the product is about, the problem it solves, 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. 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"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
{
|
||||
"module-code": "bmm",
|
||||
"replaces-skill": "bmad-create-product-brief",
|
||||
"capabilities": [
|
||||
{
|
||||
"name": "create-brief",
|
||||
"menu-code": "CB",
|
||||
"description": "Produces executive product brief and optional LLM distillate for PRD input.",
|
||||
"supports-headless": true,
|
||||
"phase-name": "1-analysis",
|
||||
"after": ["brainstorming, perform-research"],
|
||||
"before": ["create-prd"],
|
||||
"is-required": true,
|
||||
"output-location": "{planning_artifacts}"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
**Language:** Use `{communication_language}` for all output.
|
||||
**Output Language:** Use `{document_output_language}` for documents.
|
||||
**Output Location:** `{planning_artifacts}`
|
||||
|
||||
# Stage 2: Contextual Discovery
|
||||
|
||||
**Goal:** Armed with the user's stated intent, intelligently gather and synthesize all available context — documents, project knowledge, and web research — so later stages work from a rich, relevant foundation.
|
||||
|
||||
## Subagent Fan-Out
|
||||
|
||||
Now that you know what the brief is about, fan out subagents in parallel to gather context. Each subagent receives the product intent summary so it knows what's relevant.
|
||||
|
||||
**Launch in parallel:**
|
||||
|
||||
1. **Artifact Analyzer** (`agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents. Also scans any specific paths the user provided. Returns structured synthesis of what it found.
|
||||
|
||||
2. **Web Researcher** (`agents/web-researcher.md`) — Searches for competitive landscape, market context, trends, and relevant industry data. Returns structured findings scoped to the product domain.
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
If subagents are unavailable or fail:
|
||||
- Read only the most relevant 1-2 documents in the main context and summarize (don't full-read everything — limit context impact in degraded mode)
|
||||
- Do a few targeted web searches inline
|
||||
- Never block the workflow because a subagent feature is unavailable
|
||||
|
||||
## Synthesis
|
||||
|
||||
Once subagent results return (or inline scanning completes):
|
||||
|
||||
1. **Merge findings** with what the user already told you
|
||||
2. **Identify gaps** — what do you still need to know to write a solid brief?
|
||||
3. **Note surprises** — anything from research that contradicts or enriches the user's assumptions?
|
||||
|
||||
## Mode-Specific Behavior
|
||||
|
||||
**Guided mode:**
|
||||
- Present a concise summary of what you found: "Here's what I learned from your documents and web research..."
|
||||
- Highlight anything surprising or worth discussing
|
||||
- Share the gaps you've identified
|
||||
- Ask: "Anything else you'd like to add, or shall we move on to filling in the details?"
|
||||
- Route to `prompts/guided-elicitation.md`
|
||||
|
||||
**Yolo mode:**
|
||||
- Absorb all findings silently
|
||||
- Skip directly to `prompts/draft-and-review.md` — you have enough to draft
|
||||
- The user will refine later
|
||||
|
||||
**Headless mode:**
|
||||
- Absorb all findings
|
||||
- Skip directly to `prompts/draft-and-review.md`
|
||||
- No interaction
|
||||
|
||||
## Stage Complete
|
||||
|
||||
This stage is complete when subagent results (or inline scanning fallback) have returned and findings are merged with user context. Route per mode:
|
||||
- **Guided** → `prompts/guided-elicitation.md`
|
||||
- **Yolo / Headless** → `prompts/draft-and-review.md`
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
**Language:** Use `{communication_language}` for all output.
|
||||
**Output Language:** Use `{document_output_language}` for documents.
|
||||
**Output Location:** `{planning_artifacts}`
|
||||
|
||||
# Stage 4: Draft & Review
|
||||
|
||||
**Goal:** Produce the executive product brief and run it through multiple review lenses to catch blind spots before the user sees the final version.
|
||||
|
||||
## Step 1: Draft the Executive Brief
|
||||
|
||||
Use `resources/brief-template.md` as a guide — adapt structure to fit the product's story.
|
||||
|
||||
**Writing principles:**
|
||||
- **Executive audience** — persuasive, clear, concise. 1-2 pages.
|
||||
- **Lead with the problem** — make the reader feel the pain before presenting the solution
|
||||
- **Concrete over abstract** — specific examples, real scenarios, measurable outcomes
|
||||
- **Confident voice** — this is a pitch, not a hedge
|
||||
- Write in `{document_output_language}`
|
||||
|
||||
**Create the output document at:** `{planning_artifacts}/product-brief-{project_name}.md`
|
||||
|
||||
Include YAML frontmatter:
|
||||
```yaml
|
||||
---
|
||||
title: "Product Brief: {project_name}"
|
||||
status: "draft"
|
||||
created: "{timestamp}"
|
||||
updated: "{timestamp}"
|
||||
inputs: [list of input files used]
|
||||
---
|
||||
```
|
||||
|
||||
## Step 2: Fan Out Review Subagents
|
||||
|
||||
Before showing the draft to the user, run it through multiple review lenses in parallel.
|
||||
|
||||
**Launch in parallel:**
|
||||
|
||||
1. **Skeptic Reviewer** (`agents/skeptic-reviewer.md`) — "What's missing? What assumptions are untested? What could go wrong? Where is the brief vague or hand-wavy?"
|
||||
|
||||
2. **Opportunity Reviewer** (`agents/opportunity-reviewer.md`) — "What adjacent value propositions are being missed? What market angles or partnerships could strengthen this? What's underemphasized?"
|
||||
|
||||
3. **Contextual Reviewer** — You (the main agent) pick the most useful third lens based on THIS specific product. Choose the lens that addresses the SINGLE BIGGEST RISK that the skeptic and opportunity reviewers won't naturally catch. Examples:
|
||||
- For healthtech: "Regulatory and compliance risk reviewer"
|
||||
- For devtools: "Developer experience and adoption friction critic"
|
||||
- For marketplace: "Network effects and chicken-and-egg problem analyst"
|
||||
- For enterprise: "Procurement and organizational change management reviewer"
|
||||
- **When domain is unclear, default to:** "Go-to-market and launch risk reviewer" — examines distribution, pricing, and first-customer acquisition. Almost always valuable, frequently missed.
|
||||
Describe the lens, run the review yourself inline.
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
If subagents are unavailable:
|
||||
- Perform all three review passes yourself, sequentially
|
||||
- Apply each lens deliberately — don't blend them into one generic review
|
||||
- The quality of review matters more than the parallelism
|
||||
|
||||
## Step 3: Integrate Review Insights
|
||||
|
||||
After all reviews complete:
|
||||
|
||||
1. **Triage findings** — group by theme, remove duplicates
|
||||
2. **Apply non-controversial improvements** directly to the draft (obvious gaps, unclear language, missing specifics)
|
||||
3. **Flag substantive suggestions** that need user input (strategic choices, scope questions, market positioning decisions)
|
||||
|
||||
## Step 4: Present to User
|
||||
|
||||
**Headless mode:** Skip to `prompts/finalize.md` — no user interaction. Save the improved draft directly.
|
||||
|
||||
**Yolo and Guided modes:**
|
||||
|
||||
Present the draft brief to the user. Then share the reviewer insights:
|
||||
|
||||
"Here's your product brief draft. Before we finalize, my review panel surfaced some things worth considering:
|
||||
|
||||
**[Grouped reviewer findings — only the substantive ones that need user input]**
|
||||
|
||||
What do you think? Any changes you'd like to make?"
|
||||
|
||||
Present reviewer findings with brief rationale, then offer: "Want me to dig into any of these, or are you ready to make your revisions?"
|
||||
|
||||
**Iterate** as long as the user wants to refine. Use the "anything else, or are we happy with this?" soft gate.
|
||||
|
||||
## Stage Complete
|
||||
|
||||
This stage is complete when: (a) the draft has been reviewed by all three lenses and improvements integrated, AND either (autonomous) save and route directly, or (guided/yolo) the user is satisfied. Route to `prompts/finalize.md`.
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
**Language:** Use `{communication_language}` for all output.
|
||||
**Output Language:** Use `{document_output_language}` for documents.
|
||||
**Output Location:** `{planning_artifacts}`
|
||||
|
||||
# Stage 5: Finalize
|
||||
|
||||
**Goal:** Save the polished brief, offer the LLM distillate, and point the user forward.
|
||||
|
||||
## Step 1: Polish and Save
|
||||
|
||||
Update the product brief document at `{planning_artifacts}/product-brief-{project_name}.md`:
|
||||
- Update frontmatter `status` to `"complete"`
|
||||
- Update `updated` timestamp
|
||||
- Ensure formatting is clean and consistent
|
||||
- Confirm the document reads well as a standalone 1-2 page executive summary
|
||||
|
||||
## Step 2: Offer the Distillate
|
||||
|
||||
Throughout the discovery process, you likely captured detail that doesn't belong in a 1-2 page executive summary but is valuable for downstream work — requirements hints, platform preferences, rejected ideas, technical constraints, detailed user scenarios, competitive deep-dives, etc.
|
||||
|
||||
**Ask the user:**
|
||||
"Your product brief is complete. During our conversation, I captured additional detail that goes beyond the executive summary — things like [mention 2-3 specific examples of overflow you captured]. Would you like me to create a detail pack for PRD creation? It distills all that extra context into a concise, structured format optimized for the next phase."
|
||||
|
||||
**If yes, create the distillate** at `{planning_artifacts}/product-brief-{project_name}-distillate.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Product Brief Distillate: {project_name}"
|
||||
type: llm-distillate
|
||||
source: "product-brief-{project_name}.md"
|
||||
created: "{timestamp}"
|
||||
purpose: "Token-efficient context for downstream PRD creation"
|
||||
---
|
||||
```
|
||||
|
||||
**Distillate content principles:**
|
||||
- Dense bullet points, not prose
|
||||
- Each bullet carries enough context to be understood standalone (don't assume the reader has the full brief loaded)
|
||||
- Group by theme, not by when it was mentioned
|
||||
- Include:
|
||||
- **Rejected ideas** — so downstream workflows don't re-propose them, with brief rationale
|
||||
- **Requirements hints** — anything the user mentioned that sounds like a requirement
|
||||
- **Technical context** — platforms, integrations, constraints, preferences
|
||||
- **Detailed user scenarios** — richer than what fits in the exec summary
|
||||
- **Competitive intelligence** — specifics from web research worth preserving
|
||||
- **Open questions** — things surfaced but not resolved during discovery
|
||||
- **Scope signals** — what the user indicated is in/out/maybe for MVP
|
||||
- Token-conscious: be concise, but give enough context per bullet so an LLM reading this later understands WHY each point matters
|
||||
|
||||
**Headless mode:** Always create the distillate automatically — unless the session was too brief to capture meaningful overflow (in that case, note this in the completion output instead of creating an empty file).
|
||||
|
||||
## Step 3: Present Completion
|
||||
|
||||
"Your product brief for {project_name} is complete!
|
||||
|
||||
**Executive Brief:** `{planning_artifacts}/product-brief-{project_name}.md`
|
||||
[If distillate created:] **Detail Pack:** `{planning_artifacts}/product-brief-{project_name}-distillate.md`
|
||||
|
||||
**Recommended next step:** Use the product brief (and detail pack) as input for PRD creation — tell your assistant 'create a PRD' and point it to these files."
|
||||
[If distillate created:] "The detail pack contains all the overflow context (requirements hints, rejected ideas, technical constraints) specifically structured for the PRD workflow to consume."
|
||||
|
||||
**Headless mode:** Output the file paths as structured JSON and exit:
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"brief": "{planning_artifacts}/product-brief-{project_name}.md",
|
||||
"distillate": "{path or null}",
|
||||
"confidence": "high|medium|low",
|
||||
"open_questions": ["any unresolved items"]
|
||||
}
|
||||
```
|
||||
|
||||
## Stage Complete
|
||||
|
||||
This is the terminal stage. After delivering the completion message and file paths, the workflow is done. If the user requests further revisions, loop back to `prompts/draft-and-review.md`. Otherwise, exit.
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
**Language:** Use `{communication_language}` for all output.
|
||||
**Output Language:** Use `{document_output_language}` for documents.
|
||||
|
||||
# Stage 3: Guided Elicitation
|
||||
|
||||
**Goal:** Fill the gaps in what you know. By now you have the user's brain dump, artifact analysis, and web research. This stage is about smart, targeted questioning — not rote section-by-section interrogation.
|
||||
|
||||
**Skip this stage entirely in Yolo and Autonomous modes** — go directly to `prompts/draft-and-review.md`.
|
||||
|
||||
## Approach
|
||||
|
||||
You are NOT walking through a rigid questionnaire. You're having a conversation that covers the substance of a great product brief. The topics below are your mental checklist, not a script. Adapt to:
|
||||
- What you already know (don't re-ask what's been covered)
|
||||
- What the user is excited about (follow their energy)
|
||||
- What's genuinely unclear (focus questions where they matter)
|
||||
|
||||
## Topics to Cover (flexibly, conversationally)
|
||||
|
||||
### Vision & Problem
|
||||
- What core problem does this solve? For whom?
|
||||
- How do people solve this today? What's frustrating about current approaches?
|
||||
- What would success look like for the people this helps?
|
||||
- What's the insight or angle that makes this approach different?
|
||||
|
||||
### Users & Value
|
||||
- Who experiences this problem most acutely?
|
||||
- Are there different user types with different needs?
|
||||
- What's the "aha moment" — when does a user realize this is what they needed?
|
||||
- How does this fit into their existing workflow or life?
|
||||
|
||||
### Market & Differentiation
|
||||
- What competitive or alternative solutions exist? (Leverage web research findings)
|
||||
- What's the unfair advantage or defensible moat?
|
||||
- Why is now the right time for this?
|
||||
|
||||
### Success & Scope
|
||||
- How will you know this is working? What metrics matter?
|
||||
- What's the minimum viable version that creates real value?
|
||||
- What's explicitly NOT in scope for the first version?
|
||||
- If this is wildly successful, what does it become in 2-3 years?
|
||||
|
||||
## The Flow
|
||||
|
||||
For each topic area where you have gaps:
|
||||
|
||||
1. **Lead with what you know** — "Based on your input and my research, it sounds like [X]. Is that right?"
|
||||
2. **Ask the gap question** — targeted, specific, not generic
|
||||
3. **Reflect and confirm** — paraphrase what you heard
|
||||
4. **"Anything else on this, or shall we move on?"** — the soft gate
|
||||
|
||||
If the user is giving you detail beyond brief scope (requirements, architecture, platform details, timelines), **capture it silently** for the distillate. Acknowledge it briefly ("Good detail, I'll capture that") but don't derail the conversation.
|
||||
|
||||
## When to Move On
|
||||
|
||||
When you have enough substance to draft a compelling 1-2 page executive brief covering:
|
||||
- Clear problem and who it affects
|
||||
- Proposed solution and what makes it different
|
||||
- Target users (at least primary)
|
||||
- Some sense of success criteria or business objectives
|
||||
- MVP-level scope thinking
|
||||
|
||||
You don't need perfection — you need enough to draft well. Missing details can be surfaced during the review stage.
|
||||
|
||||
If the user is providing complete, confident answers and you have solid coverage across all four topic areas after fewer than 3-4 exchanges, proactively offer to draft early.
|
||||
|
||||
**Transition:** "I think I have a solid picture. Ready for me to draft the brief, or is there anything else you'd like to add?"
|
||||
|
||||
## Stage Complete
|
||||
|
||||
This stage is complete when sufficient substance exists to draft a compelling brief and the user confirms readiness. Route to `prompts/draft-and-review.md`.
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# Product Brief Template
|
||||
|
||||
This is a flexible guide for the executive product brief — adapt it to serve the product's story. Merge sections, add new ones, reorder as needed. The product determines the structure, not the template.
|
||||
|
||||
## Sensible Default Structure
|
||||
|
||||
```markdown
|
||||
# Product Brief: {Product Name}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[2-3 paragraph narrative: What is this? What problem does it solve? Why does it matter? Why now?
|
||||
This should be compelling enough to stand alone — if someone reads only this section, they should understand the vision.]
|
||||
|
||||
## The Problem
|
||||
|
||||
[What pain exists? Who feels it? How are they coping today? What's the cost of the status quo?
|
||||
Be specific — real scenarios, real frustrations, real consequences.]
|
||||
|
||||
## The Solution
|
||||
|
||||
[What are we building? How does it solve the problem?
|
||||
Focus on the experience and outcome, not the implementation.]
|
||||
|
||||
## What Makes This Different
|
||||
|
||||
[Key differentiators. Why this approach vs alternatives? What's the unfair advantage?
|
||||
Be honest — if the moat is execution speed, say so. Don't fabricate technical moats.]
|
||||
|
||||
## Who This Serves
|
||||
|
||||
[Primary users — vivid but brief. Who are they, what do they need, what does success look like for them?
|
||||
Secondary users if relevant.]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
[How do we know this is working? What metrics matter?
|
||||
Mix of user success signals and business objectives. Be measurable.]
|
||||
|
||||
## Scope
|
||||
|
||||
[What's in for the first version? What's explicitly out?
|
||||
Keep this tight — it's a boundary document, not a feature list.]
|
||||
|
||||
## Vision
|
||||
|
||||
[Where does this go if it succeeds? What does it become in 2-3 years?
|
||||
Inspiring but grounded.]
|
||||
```
|
||||
|
||||
## Adaptation Guidelines
|
||||
|
||||
- **For B2B products:** Consider adding a "Buyer vs User" section if they're different people
|
||||
- **For platforms/marketplaces:** Consider a "Network Effects" or "Ecosystem" section
|
||||
- **For technical products:** May need a brief "Technical Approach" section (keep it high-level)
|
||||
- **For regulated industries:** Consider a "Compliance & Regulatory" section
|
||||
- **If scope is well-defined:** Merge "Scope" and "Vision" into "Roadmap Thinking"
|
||||
- **If the problem is well-known:** Shorten "The Problem" and expand "What Makes This Different"
|
||||
|
||||
The brief should be 1-2 pages. If it's longer, you're putting in too much detail — that's what the distillate is for.
|
||||
|
|
@ -30,8 +30,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -162,7 +162,7 @@ Show the generated core experience content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current core experience content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current core experience content
|
||||
- Process the enhanced experience insights that come back
|
||||
- Ask user: "Accept these improvements to the core experience definition? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -170,7 +170,7 @@ Show the generated core experience content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current core experience definition
|
||||
- Invoke the `bmad-party-mode` skill with the current core experience definition
|
||||
- Process the collaborative experience improvements that come back
|
||||
- Ask user: "Accept these changes to the core experience definition? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -165,7 +165,7 @@ Show the generated emotional response content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current emotional response content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current emotional response content
|
||||
- Process the enhanced emotional insights that come back
|
||||
- Ask user: "Accept these improvements to the emotional response definition? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -173,7 +173,7 @@ Show the generated emotional response content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current emotional response definition
|
||||
- Invoke the `bmad-party-mode` skill with the current emotional response definition
|
||||
- Process the collaborative emotional insights that come back
|
||||
- Ask user: "Accept these changes to the emotional response definition? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -180,7 +180,7 @@ Show the generated inspiration analysis content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current inspiration analysis content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current inspiration analysis content
|
||||
- Process the enhanced pattern insights that come back
|
||||
- Ask user: "Accept these improvements to the inspiration analysis? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -188,7 +188,7 @@ Show the generated inspiration analysis content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current inspiration analysis
|
||||
- Invoke the `bmad-party-mode` skill with the current inspiration analysis
|
||||
- Process the collaborative pattern insights that come back
|
||||
- Ask user: "Accept these changes to the inspiration analysis? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -198,7 +198,7 @@ Show the generated design system content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current design system content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current design system content
|
||||
- Process the enhanced design system insights that come back
|
||||
- Ask user: "Accept these improvements to the design system decision? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -206,7 +206,7 @@ Show the generated design system content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design system choice
|
||||
- Invoke the `bmad-party-mode` skill with the current design system choice
|
||||
- Process the collaborative design system insights that come back
|
||||
- Ask user: "Accept these changes to the design system decision? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -200,7 +200,7 @@ Show the generated defining experience content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current defining experience content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current defining experience content
|
||||
- Process the enhanced experience insights that come back
|
||||
- Ask user: "Accept these improvements to the defining experience? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -208,7 +208,7 @@ Show the generated defining experience content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current defining experience
|
||||
- Invoke the `bmad-party-mode` skill with the current defining experience
|
||||
- Process the collaborative experience insights that come back
|
||||
- Ask user: "Accept these changes to the defining experience? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ Show the generated visual foundation content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current visual foundation content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current visual foundation content
|
||||
- Process the enhanced visual insights that come back
|
||||
- Ask user: "Accept these improvements to the visual foundation? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -178,7 +178,7 @@ Show the generated visual foundation content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current visual foundation
|
||||
- Invoke the `bmad-party-mode` skill with the current visual foundation
|
||||
- Process the collaborative visual insights that come back
|
||||
- Ask user: "Accept these changes to the visual foundation? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ Show the generated design direction content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current design direction content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current design direction content
|
||||
- Process the enhanced design insights that come back
|
||||
- Ask user: "Accept these improvements to the design direction? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -178,7 +178,7 @@ Show the generated design direction content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design direction
|
||||
- Invoke the `bmad-party-mode` skill with the current design direction
|
||||
- Process the collaborative design insights that come back
|
||||
- Ask user: "Accept these changes to the design direction? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -188,7 +188,7 @@ Show the generated user journey content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current user journey content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current user journey content
|
||||
- Process the enhanced journey insights that come back
|
||||
- Ask user: "Accept these improvements to the user journeys? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -196,7 +196,7 @@ Show the generated user journey content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current user journeys
|
||||
- Invoke the `bmad-party-mode` skill with the current user journeys
|
||||
- Process the collaborative journey insights that come back
|
||||
- Ask user: "Accept these changes to the user journeys? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -194,7 +194,7 @@ Show the generated component strategy content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current component strategy content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current component strategy content
|
||||
- Process the enhanced component insights that come back
|
||||
- Ask user: "Accept these improvements to the component strategy? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -202,7 +202,7 @@ Show the generated component strategy content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current component strategy
|
||||
- Invoke the `bmad-party-mode` skill with the current component strategy
|
||||
- Process the collaborative component insights that come back
|
||||
- Ask user: "Accept these changes to the component strategy? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -183,7 +183,7 @@ Show the generated UX patterns content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current UX patterns content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current UX patterns content
|
||||
- Process the enhanced pattern insights that come back
|
||||
- Ask user: "Accept these improvements to the UX patterns? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -191,7 +191,7 @@ Show the generated UX patterns content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current UX patterns
|
||||
- Invoke the `bmad-party-mode` skill with the current UX patterns
|
||||
- Process the collaborative pattern insights that come back
|
||||
- Ask user: "Accept these changes to the UX patterns? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to this step's A/P/C menu
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -210,7 +210,7 @@ Show the generated responsive and accessibility content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with the current responsive/accessibility content
|
||||
- Invoke the `bmad-advanced-elicitation` skill with the current responsive/accessibility content
|
||||
- Process the enhanced insights that come back
|
||||
- Ask user: "Accept these improvements to the responsive/accessibility strategy? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
@ -218,7 +218,7 @@ Show the generated responsive and accessibility content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current responsive/accessibility strategy
|
||||
- Invoke the `bmad-party-mode` skill with the current responsive/accessibility strategy
|
||||
- Process the collaborative insights that come back
|
||||
- Ask user: "Accept these changes to the responsive/accessibility strategy? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ This step will generate content and present choices:
|
|||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -178,7 +178,7 @@ Show the generated content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current project context
|
||||
- Invoke the `bmad-party-mode` skill with the current project context
|
||||
- Process the collaborative improvements to architectural understanding
|
||||
- Ask user: "Accept these changes to the project context analysis? (y/n)"
|
||||
- If yes: Update content with improvements, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -276,7 +276,7 @@ Show the generated content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with current starter analysis
|
||||
- Invoke the `bmad-advanced-elicitation` skill with current starter analysis
|
||||
- Process enhanced insights about starter options or custom approaches
|
||||
- Ask user: "Accept these changes to the starter template evaluation? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
@ -284,7 +284,7 @@ Show the generated content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with starter evaluation context
|
||||
- Invoke the `bmad-party-mode` skill with starter evaluation context
|
||||
- Process collaborative insights about starter trade-offs
|
||||
- Ask user: "Accept these changes to the starter template evaluation? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ This step will generate content and present choices for each decision category:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -264,7 +264,7 @@ Show the generated decisions content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with specific decision categories
|
||||
- Invoke the `bmad-advanced-elicitation` skill with specific decision categories
|
||||
- Process enhanced insights about particular decisions
|
||||
- Ask user: "Accept these enhancements to the architectural decisions? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
@ -272,7 +272,7 @@ Show the generated decisions content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with architectural decisions context
|
||||
- Invoke the `bmad-party-mode` skill with architectural decisions context
|
||||
- Process collaborative insights about decision trade-offs
|
||||
- Ask user: "Accept these changes to the architectural decisions? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -305,7 +305,7 @@ Show the generated patterns content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with current patterns
|
||||
- Invoke the `bmad-advanced-elicitation` skill with current patterns
|
||||
- Process enhanced consistency rules that come back
|
||||
- Ask user: "Accept these additional pattern refinements? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
@ -313,7 +313,7 @@ Show the generated patterns content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with implementation patterns context
|
||||
- Invoke the `bmad-party-mode` skill with implementation patterns context
|
||||
- Process collaborative insights about potential conflicts
|
||||
- Ask user: "Accept these changes to the implementation patterns? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -325,7 +325,7 @@ Show the generated project structure content and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with current project structure
|
||||
- Invoke the `bmad-advanced-elicitation` skill with current project structure
|
||||
- Process enhanced organizational insights that come back
|
||||
- Ask user: "Accept these changes to the project structure? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
@ -333,7 +333,7 @@ Show the generated project structure content and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with project structure context
|
||||
- Invoke the `bmad-party-mode` skill with project structure context
|
||||
- Process collaborative insights about organization trade-offs
|
||||
- Ask user: "Accept these changes to the project structure? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ This step will generate content and present choices:
|
|||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
|
||||
- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
|
||||
- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
|
||||
- When 'P' selected: Invoke the `bmad-party-mode` skill
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
|
|
@ -305,7 +305,7 @@ Show the validation results and present choices:
|
|||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Read fully and follow: skill:bmad-advanced-elicitation with validation issues
|
||||
- Invoke the `bmad-advanced-elicitation` skill with validation issues
|
||||
- Process enhanced solutions for complex concerns
|
||||
- Ask user: "Accept these architectural improvements? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
@ -313,7 +313,7 @@ Show the validation results and present choices:
|
|||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with validation context
|
||||
- Invoke the `bmad-party-mode` skill with validation context
|
||||
- Process collaborative insights on implementation readiness
|
||||
- Ask user: "Accept these changes to the validation results? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
|
|
|
|||
|
|
@ -1,30 +0,0 @@
|
|||
# BMad Master Task Executor Agent
|
||||
# Core system agent for task execution and resource management
|
||||
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/core/agents/bmad-master.md"
|
||||
name: "BMad Master"
|
||||
title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
|
||||
icon: "🧙"
|
||||
capabilities: "runtime resource management, workflow orchestration, task execution, knowledge custodian"
|
||||
hasSidecar: false
|
||||
|
||||
persona:
|
||||
role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
|
||||
identity: "Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations."
|
||||
communication_style: "Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability."
|
||||
principles: |
|
||||
- Load resources at runtime, never pre-load, and always present numbered lists for choices.
|
||||
|
||||
critical_actions:
|
||||
- 'Always greet the user and let them know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and they can combine it with what they need help with <example>Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?"</example>'
|
||||
|
||||
menu:
|
||||
- trigger: "LT or fuzzy match on list-tasks"
|
||||
action: "list all tasks from {project-root}/_bmad/_config/task-manifest.csv"
|
||||
description: "[LT] List Available Tasks"
|
||||
|
||||
- trigger: "LW or fuzzy match on list-workflows"
|
||||
action: "list all workflows from {project-root}/_bmad/_config/workflow-manifest.csv"
|
||||
description: "[LW] List Workflows"
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
canonicalId: bmad-master
|
||||
type: agent
|
||||
description: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
|
||||
|
|
@ -8,3 +8,4 @@ core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad
|
|||
core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
|
||||
core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
|
||||
core,anytime,Edge Case Hunter Review,ECH,,skill:bmad-review-edge-case-hunter,bmad-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,
|
||||
core,anytime,Distillator,DG,,skill:bmad-distillator,bmad-distillator,false,,,"Lossless LLM-optimized compression of source documents. Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.",adjacent to source document or specified output_path,distillate markdown file(s)
|
||||
|
|
|
|||
|
Can't render this file because it has a wrong number of fields in line 2.
|
|
|
@ -0,0 +1,178 @@
|
|||
---
|
||||
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
|
||||
|
||||
## Overview
|
||||
|
||||
This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
|
||||
|
||||
This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
|
||||
|
||||
## On Activation
|
||||
|
||||
1. **Validate inputs.** The caller must provide:
|
||||
- **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
|
||||
- **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
|
||||
- **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
|
||||
- **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
|
||||
- **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
|
||||
|
||||
2. **Route** — proceed to Stage 1.
|
||||
|
||||
## Stages
|
||||
|
||||
| # | Stage | Purpose |
|
||||
|---|-------|---------|
|
||||
| 1 | Analyze | Run analysis script, determine routing and splitting |
|
||||
| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
|
||||
| 3 | Verify & Output | Completeness check, format check, save output |
|
||||
| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
|
||||
|
||||
### Stage 1: Analyze
|
||||
|
||||
Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
|
||||
|
||||
### Stage 2: Compress
|
||||
|
||||
**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
|
||||
|
||||
Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
|
||||
|
||||
**Fan-out mode** (routing = `"fan-out"`):
|
||||
|
||||
1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
|
||||
|
||||
2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
|
||||
|
||||
3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
|
||||
|
||||
**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
|
||||
|
||||
The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
|
||||
|
||||
### Stage 3: Verify & Output
|
||||
|
||||
After the compressor (or merge compressor) returns:
|
||||
|
||||
1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
|
||||
|
||||
2. **Format check.** Verify the output follows distillate format rules:
|
||||
- No prose paragraphs (only bullets)
|
||||
- No decorative formatting
|
||||
- No repeated information
|
||||
- Each bullet is self-contained
|
||||
- Themes are clearly delineated with `##` headings
|
||||
|
||||
3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
|
||||
|
||||
**Single distillate** (≤~5,000 tokens or token_budget not exceeded):
|
||||
|
||||
Save as a single file with frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: bmad-distillate
|
||||
sources:
|
||||
- "{relative path to source file 1}"
|
||||
- "{relative path to source file 2}"
|
||||
downstream_consumer: "{consumer or 'general'}"
|
||||
created: "{date}"
|
||||
token_estimate: {approximate token count}
|
||||
parts: 1
|
||||
---
|
||||
```
|
||||
|
||||
**Split distillate** (>~5,000 tokens, or token_budget requires it):
|
||||
|
||||
Create a folder `{base-name}-distillate/` containing:
|
||||
|
||||
```
|
||||
{base-name}-distillate/
|
||||
├── _index.md # Orientation, cross-cutting items, section manifest
|
||||
├── 01-{topic-slug}.md # Self-contained section
|
||||
├── 02-{topic-slug}.md
|
||||
└── 03-{topic-slug}.md
|
||||
```
|
||||
|
||||
The `_index.md` contains:
|
||||
- Frontmatter with sources (relative paths from the distillate folder to the originals)
|
||||
- 3-5 bullet orientation (what was distilled, from what)
|
||||
- Section manifest: each section's filename + 1-line description
|
||||
- Cross-cutting items that span multiple sections
|
||||
|
||||
Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
|
||||
|
||||
Source paths in frontmatter must be relative to the distillate's location.
|
||||
|
||||
4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
|
||||
|
||||
5. **Report results.** Always return structured JSON output:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"distillate": "{path or folder path}",
|
||||
"section_distillates": ["{path1}", "{path2}"] or null,
|
||||
"source_total_tokens": N,
|
||||
"distillate_total_tokens": N,
|
||||
"compression_ratio": "X:1",
|
||||
"source_documents": ["{path1}", "{path2}"],
|
||||
"completeness_check": "pass" or "pass_with_additions"
|
||||
}
|
||||
```
|
||||
|
||||
Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
|
||||
|
||||
6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
|
||||
|
||||
### Stage 4: Round-Trip Validation (--validate only)
|
||||
|
||||
This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
|
||||
|
||||
1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
|
||||
|
||||
For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
|
||||
|
||||
**Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
|
||||
|
||||
2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
|
||||
|
||||
3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
|
||||
- Is the core information present in the reconstruction?
|
||||
- Are specific details preserved (numbers, names, decisions)?
|
||||
- Are relationships and rationale intact?
|
||||
- Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
|
||||
|
||||
4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: distillate-validation
|
||||
distillate: "{distillate path}"
|
||||
sources: ["{source paths}"]
|
||||
created: "{date}"
|
||||
---
|
||||
|
||||
## Validation Summary
|
||||
- Status: PASS | PASS_WITH_WARNINGS | FAIL
|
||||
- Information preserved: {percentage estimate}
|
||||
- Gaps found: {count}
|
||||
- Hallucinations detected: {count}
|
||||
|
||||
## Gaps (information in originals but missing from reconstruction)
|
||||
- {gap description} — Source: {which original}, Section: {where}
|
||||
|
||||
## Hallucinations (information in reconstruction not traceable to originals)
|
||||
- {hallucination description} — appears to fill gap in: {section}
|
||||
|
||||
## Possible Gap Markers (flagged by reconstructor)
|
||||
- {marker description}
|
||||
```
|
||||
|
||||
5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
|
||||
|
||||
6. **Clean up** — delete the temporary reconstruction files after the report is generated.
|
||||
|
|
@ -0,0 +1,116 @@
|
|||
# Distillate Compressor Agent
|
||||
|
||||
Act as an information extraction and compression specialist. Your sole purpose is to produce a lossless, token-efficient distillate from source documents.
|
||||
|
||||
You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
|
||||
|
||||
You must load and apply `resources/compression-rules.md` before producing output. Reference `resources/distillate-format-reference.md` for the expected output format.
|
||||
|
||||
## Compression Process
|
||||
|
||||
### Step 1: Read Sources
|
||||
|
||||
Read all source document files. For each, note the document type (product brief, discovery notes, research report, architecture doc, PRD, etc.) based on content and naming.
|
||||
|
||||
### Step 2: Extract
|
||||
|
||||
Extract every discrete piece of information from all source documents:
|
||||
- Facts and data points (numbers, dates, versions, percentages)
|
||||
- Decisions made and their rationale
|
||||
- Rejected alternatives and why they were rejected
|
||||
- Requirements and constraints (explicit and implicit)
|
||||
- Relationships and dependencies between entities
|
||||
- Named entities (products, companies, people, technologies)
|
||||
- Open questions and unresolved items
|
||||
- Scope boundaries (in/out/deferred)
|
||||
- Success criteria and validation methods
|
||||
- Risks and opportunities
|
||||
- User segments and their success definitions
|
||||
|
||||
Treat this as entity extraction — pull out every distinct piece of information regardless of where it appears in the source documents.
|
||||
|
||||
### Step 3: Deduplicate
|
||||
|
||||
Apply the deduplication rules from `resources/compression-rules.md`.
|
||||
|
||||
### Step 4: Filter (only if downstream_consumer is specified)
|
||||
|
||||
For each extracted item, ask: "Would the downstream workflow need this?"
|
||||
- Drop items that are clearly irrelevant to the stated consumer
|
||||
- When uncertain, keep the item — err on the side of preservation
|
||||
- Never drop: decisions, rejected alternatives, open questions, constraints, scope boundaries
|
||||
|
||||
### Step 5: Group Thematically
|
||||
|
||||
Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about.
|
||||
|
||||
Common groupings (use what fits, omit what doesn't, add what's needed):
|
||||
- Core concept / problem / motivation
|
||||
- Solution / approach / architecture
|
||||
- Users / segments
|
||||
- Technical decisions / constraints
|
||||
- Scope boundaries (in/out/deferred)
|
||||
- Competitive context
|
||||
- Success criteria
|
||||
- Rejected alternatives
|
||||
- Open questions
|
||||
- Risks and opportunities
|
||||
|
||||
### Step 6: Compress Language
|
||||
|
||||
For each item, apply the compression rules from `resources/compression-rules.md`:
|
||||
- Strip prose transitions and connective tissue
|
||||
- Remove hedging and rhetoric
|
||||
- Remove explanations of common knowledge
|
||||
- Preserve specific details (numbers, names, versions, dates)
|
||||
- Ensure the item is self-contained (understandable without reading the source)
|
||||
- Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y")
|
||||
|
||||
### Step 7: Format Output
|
||||
|
||||
Produce the distillate as dense thematically-grouped bullets:
|
||||
- `##` headings for themes — no deeper heading levels needed
|
||||
- `- ` bullets for items — every token must carry signal
|
||||
- No decorative formatting (no bold for emphasis, no horizontal rules)
|
||||
- No prose paragraphs — only bullets
|
||||
- Semicolons to join closely related short items within a single bullet
|
||||
- Each bullet self-contained — understandable without reading other bullets
|
||||
|
||||
Do NOT include frontmatter — the calling skill handles that.
|
||||
|
||||
## Semantic Splitting
|
||||
|
||||
If the splitting decision indicates splitting is needed, load `resources/splitting-strategy.md` and follow it.
|
||||
|
||||
When splitting:
|
||||
|
||||
1. Identify natural semantic boundaries in the content — coherent topic clusters, not arbitrary size breaks.
|
||||
|
||||
2. Produce a **root distillate** containing:
|
||||
- 3-5 bullet orientation (what was distilled, for whom, how many parts)
|
||||
- Cross-references to section distillates
|
||||
- Items that span multiple sections
|
||||
|
||||
3. Produce **section distillates**, each self-sufficient. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]."
|
||||
|
||||
## Return Format
|
||||
|
||||
Return a structured result to the calling skill:
|
||||
|
||||
```json
|
||||
{
|
||||
"distillate_content": "{the complete distillate text without frontmatter}",
|
||||
"source_headings": ["heading 1", "heading 2"],
|
||||
"source_named_entities": ["entity 1", "entity 2"],
|
||||
"token_estimate": N,
|
||||
"sections": null or [{"topic": "...", "content": "..."}]
|
||||
}
|
||||
```
|
||||
|
||||
- **distillate_content**: The full distillate text
|
||||
- **source_headings**: All Level 2+ headings found across source documents (for completeness verification)
|
||||
- **source_named_entities**: Key named entities (products, companies, people, technologies, decisions) found in sources
|
||||
- **token_estimate**: Approximate token count of the distillate
|
||||
- **sections**: null for single distillates; array of section objects if semantically split
|
||||
|
||||
Do not include conversational text, status updates, or preamble — return only the structured result.
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
# Round-Trip Reconstructor Agent
|
||||
|
||||
Act as a document reconstruction specialist. Your purpose is to prove a distillate's completeness by reconstructing the original source documents from the distillate alone.
|
||||
|
||||
**Critical constraint:** You receive ONLY the distillate file path. You must NOT have access to the original source documents. If you can see the originals, the test is meaningless.
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Analyze the Distillate
|
||||
|
||||
Read the distillate file. Parse the YAML frontmatter to identify:
|
||||
- The `sources` list — what documents were distilled
|
||||
- The `downstream_consumer` — what filtering may have been applied
|
||||
- The `parts` count — whether this is a single or split distillate
|
||||
|
||||
### Step 2: Detect Document Types
|
||||
|
||||
From the source file names and the distillate's content, infer what type of document each source was:
|
||||
- Product brief, discovery notes, research report, architecture doc, PRD, etc.
|
||||
- Use the naming conventions and content themes to determine appropriate document structure
|
||||
|
||||
### Step 3: Reconstruct Each Source
|
||||
|
||||
For each source listed in the frontmatter, produce a full human-readable document:
|
||||
|
||||
- Use appropriate prose, structure, and formatting for the document type
|
||||
- Include all sections the original document would have had based on the document type
|
||||
- Expand compressed bullets back into natural language prose
|
||||
- Restore section transitions and contextual framing
|
||||
- Do NOT invent information — only use what is in the distillate
|
||||
- Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers — these are critical quality signals
|
||||
|
||||
**Quality signals to watch for:**
|
||||
- Bullets that feel like they're missing context → `[POSSIBLE GAP: missing context for X]`
|
||||
- Themes that seem underrepresented given the document type → `[POSSIBLE GAP: expected more on X for a document of this type]`
|
||||
- Relationships that are mentioned but not fully explained → `[POSSIBLE GAP: relationship between X and Y unclear]`
|
||||
|
||||
### Step 4: Save Reconstructions
|
||||
|
||||
Save each reconstructed document as a temporary file adjacent to the distillate:
|
||||
- First source: `{distillate-basename}-reconstruction-1.md`
|
||||
- Second source: `{distillate-basename}-reconstruction-2.md`
|
||||
- And so on for each source
|
||||
|
||||
Each reconstruction should include a header noting it was reconstructed:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: distillate-reconstruction
|
||||
source_distillate: "{distillate path}"
|
||||
reconstructed_from: "{original source name}"
|
||||
reconstruction_number: {N}
|
||||
---
|
||||
```
|
||||
|
||||
### Step 5: Return
|
||||
|
||||
Return a structured result to the calling skill:
|
||||
|
||||
```json
|
||||
{
|
||||
"reconstruction_files": ["{path1}", "{path2}"],
|
||||
"possible_gaps": ["gap description 1", "gap description 2"],
|
||||
"source_count": N
|
||||
}
|
||||
```
|
||||
|
||||
Do not include conversational text, status updates, or preamble — return only the structured result.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
type: skill
|
||||
module: core
|
||||
capabilities:
|
||||
- name: bmad-distillator
|
||||
menu-code: DSTL
|
||||
description: "Produces lossless LLM-optimized distillate from source documents. Use after producing large human presentable documents that will be consumed later by LLMs"
|
||||
supports-headless: true
|
||||
input: source documents
|
||||
args: output, validate
|
||||
output: single distillate or folder of distillates next to source input
|
||||
config-vars-used: null
|
||||
phase: anytime
|
||||
before: []
|
||||
after: []
|
||||
is-required: false
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
# Compression Rules
|
||||
|
||||
These rules govern how source text is compressed into distillate format. Apply as a final pass over all output.
|
||||
|
||||
## Strip — Remove entirely
|
||||
|
||||
- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this"
|
||||
- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is"
|
||||
- Hedging: "We believe", "It's likely that", "Perhaps", "It seems"
|
||||
- Self-reference: "This document describes", "As outlined above"
|
||||
- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license", "JSON is a data interchange format"
|
||||
- Repeated introductions of the same concept
|
||||
- Section transition paragraphs
|
||||
- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks)
|
||||
- Filler phrases: "In order to", "It should be noted that", "The fact that"
|
||||
|
||||
## Preserve — Keep always
|
||||
|
||||
- Specific numbers, dates, versions, percentages
|
||||
- Named entities (products, companies, people, technologies)
|
||||
- Decisions made and their rationale (compressed: "Decision: X. Reason: Y")
|
||||
- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y")
|
||||
- Explicit constraints and non-negotiables
|
||||
- Dependencies and ordering relationships
|
||||
- Open questions and unresolved items
|
||||
- Scope boundaries (in/out/deferred)
|
||||
- Success criteria and how they're validated
|
||||
- User segments and what success means for each
|
||||
- Risks with their severity signals
|
||||
- Conflicts between source documents
|
||||
|
||||
## Transform — Change form for efficiency
|
||||
|
||||
- Long prose paragraphs → single dense bullet capturing the same information
|
||||
- "We decided to use X because Y and Z" → "X (rationale: Y, Z)"
|
||||
- Repeated category labels → group under a single heading, no per-item labels
|
||||
- "Risk: ... Severity: high" → "HIGH RISK: ..."
|
||||
- Conditional statements → "If X → Y" form
|
||||
- Multi-sentence explanations → semicolon-separated compressed form
|
||||
- Lists of related short items → single bullet with semicolons
|
||||
- "X is used for Y" → "X: Y" when context is clear
|
||||
- Verbose enumerations → parenthetical lists: "platforms (Cursor, Claude Code, Windsurf, Copilot)"
|
||||
|
||||
## Deduplication Rules
|
||||
|
||||
- Same fact in multiple documents → keep the version with most context
|
||||
- Same concept at different detail levels → keep the detailed version
|
||||
- Overlapping lists → merge into single list, no duplicates
|
||||
- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved"
|
||||
- Executive summary points that are expanded elsewhere → keep only the expanded version
|
||||
- Introductory framing repeated across sections → capture once under the most relevant theme
|
||||
|
|
@ -0,0 +1,227 @@
|
|||
# Distillate Format Reference
|
||||
|
||||
Examples showing the transformation from human-readable source content to distillate format.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
Every distillate includes YAML frontmatter. Source paths are relative to the distillate's location so the distillate remains portable:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: bmad-distillate
|
||||
sources:
|
||||
- "product-brief-example.md"
|
||||
- "product-brief-example-discovery-notes.md"
|
||||
downstream_consumer: "PRD creation"
|
||||
created: "2026-03-13"
|
||||
token_estimate: 1200
|
||||
parts: 1
|
||||
---
|
||||
```
|
||||
|
||||
## Before/After Examples
|
||||
|
||||
### Prose Paragraph to Dense Bullet
|
||||
|
||||
**Before** (human-readable brief excerpt):
|
||||
```
|
||||
## What Makes This Different
|
||||
|
||||
**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+
|
||||
platforms with no shared methodology layer. BMAD is uniquely positioned to be the
|
||||
cross-platform constant — the structured approach that works the same in Cursor,
|
||||
Claude Code, Windsurf, Copilot, and whatever launches next month. Every other
|
||||
methodology or skill framework maintains its own platform support matrix. By
|
||||
building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn
|
||||
maintenance burden and focuses on what actually differentiates it: the methodology
|
||||
itself.
|
||||
```
|
||||
|
||||
**After** (distillate):
|
||||
```
|
||||
## Differentiation
|
||||
- Anti-fragmentation positioning: BMAD = cross-platform constant across 40+ fragmenting AI tools; no competitor provides shared methodology layer
|
||||
- Platform complexity delegated to Vercel skills CLI ecosystem (MIT); BMAD maintains methodology, not platform configs
|
||||
```
|
||||
|
||||
### Technical Details to Compressed Facts
|
||||
|
||||
**Before** (discovery notes excerpt):
|
||||
```
|
||||
## Competitive Landscape
|
||||
|
||||
- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard —
|
||||
but dev-only, skills trigger unreliably (20% without explicit prompting)
|
||||
- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI
|
||||
- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem
|
||||
- **Lindy**: No-code AI agent builder for business automation — closed platform,
|
||||
no skill sharing
|
||||
- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked
|
||||
to Microsoft
|
||||
- **MindStudio**: No-code AI agent platform — siloed, no interoperability
|
||||
- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric,
|
||||
not methodology-centric
|
||||
- **Key gap**: NO competitor combines structured methodology with plugin
|
||||
marketplace — this is BMAD's whitespace
|
||||
```
|
||||
|
||||
**After** (distillate):
|
||||
```
|
||||
## Competitive Landscape
|
||||
- No competitor combines structured methodology + plugin marketplace (whitespace)
|
||||
- Skills.sh (Vercel): 83K skills, 18 agents, dev-only, 20% trigger reliability
|
||||
- SkillsMP: 400K skills, aggregator only, no curation/CLI
|
||||
- ClawHub: 3.2K curated, versioning, small ecosystem
|
||||
- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
|
||||
```
|
||||
|
||||
### Deduplication Across Documents
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
**Discovery notes say:**
|
||||
```
|
||||
bmad-init must always be included as a base skill in every bundle/install
|
||||
(solves bootstrapping problem)
|
||||
```
|
||||
|
||||
**Distillate keeps the more contextual version:**
|
||||
```
|
||||
- bmad-init: always included as base skill in every bundle (solves bootstrapping)
|
||||
```
|
||||
|
||||
### Decision/Rationale Compression
|
||||
|
||||
**Before:**
|
||||
```
|
||||
We decided not to build our own platform support matrix going forward, instead
|
||||
delegating to the Vercel skills CLI ecosystem. The rationale is that maintaining
|
||||
20+ platform configs is the biggest maintenance burden and it's unsustainable
|
||||
at 40+ platforms.
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
- Rejected: own platform support matrix. Reason: unsustainable at 40+ platforms; delegate to Vercel CLI ecosystem
|
||||
```
|
||||
|
||||
## Full Example
|
||||
|
||||
A complete distillate produced from a product brief and its discovery notes, targeted at PRD creation:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: bmad-distillate
|
||||
sources:
|
||||
- "product-brief-bmad-next-gen-installer.md"
|
||||
- "product-brief-bmad-next-gen-installer-discovery-notes.md"
|
||||
downstream_consumer: "PRD creation"
|
||||
created: "2026-03-13"
|
||||
token_estimate: 1450
|
||||
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
|
||||
- Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal)
|
||||
|
||||
## Problem
|
||||
- Current installer maintains ~20 platform configs manually; each platform convention change requires installer update, test, release — largest maintenance burden on team
|
||||
- Node.js/npm required — blocks non-technical users on UI-based platforms (Claude Co-Work, etc.)
|
||||
- CSV manifests are static, generated once at install; no runtime scanning/registration
|
||||
- Unsustainable at 40+ platforms; new tools launching weekly
|
||||
|
||||
## Solution Architecture
|
||||
- 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-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
|
||||
|
||||
## Differentiation
|
||||
- Anti-fragmentation: BMAD = cross-platform constant; no competitor provides shared methodology layer across AI tools
|
||||
- Curated quality: all submissions gated, human-reviewed by BMad + core team; 13.4% of community skills have critical vulnerabilities (Snyk 2026); quality gate value increases as ecosystem gets noisier
|
||||
- Domain-agnostic: no competitor builds beyond software dev workflows; same plugin system powers any domain via BMAD Builder (separate initiative)
|
||||
|
||||
## Users (ordered by v1 priority)
|
||||
- Module authors (primary v1): package/test/distribute plugins independently without installer changes
|
||||
- Developers: single-command install on any of 40+ platforms via NPX
|
||||
- Non-technical users: install without Node/Git/terminal; emerging segment including PMs, designers, educators
|
||||
- Future plugin creators: non-dev authors using BMAD Builder; need distribution without building own installer
|
||||
|
||||
## Success Criteria
|
||||
- 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
|
||||
- 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
|
||||
- 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`
|
||||
- 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
|
||||
- Dependencies: 4-pass resolver (collect → parse → resolve → transitive); YAML-declared only
|
||||
- Config: prompts for name, communication language, document output language, output folder
|
||||
- Skills already use directory-per-skill layout; bmad-manifest.json sidecars exist but are not source of truth
|
||||
- Key shift: CSV-based static manifests → JSON-based runtime scanning
|
||||
|
||||
## Vercel Skills CLI
|
||||
- `npx skills add <source>` — GitHub, GitLab, local paths, git URLs
|
||||
- 40+ agents; per-agent path mappings; symlinks (recommended) or copies
|
||||
- Scopes: project-level or global
|
||||
- Discovery: `skills/`, `.agents/skills/`, agent-specific paths, `.claude-plugin/marketplace.json`
|
||||
- Commands: add, list, find, remove, check, update, init
|
||||
- Non-interactive: `-y`, `--all` flags for CI/CD
|
||||
|
||||
## Competitive Landscape
|
||||
- No competitor combines structured methodology + plugin marketplace (whitespace)
|
||||
- Skills.sh (Vercel): 83K skills, dev-only, 20% trigger reliability without explicit prompting
|
||||
- SkillsMP: 400K skills, aggregator only, no curation
|
||||
- ClawHub: 3.2K curated, versioning, small
|
||||
- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
|
||||
- Market: $7.84B (2025) → $52.62B (2030); Agent Skills spec ~4 months old, 351K+ skills; standards converging under Linux Foundation AAIF (MCP, AGENTS.md, A2A)
|
||||
|
||||
## Rejected Alternatives
|
||||
- Building own platform support matrix: unsustainable at 40+; delegate to Vercel ecosystem
|
||||
- One-click install for non-technical v1: emerging space; guidance-based, improve over time
|
||||
- Prior roadmap/brainstorming: clean start, unconstrained by previous planning
|
||||
|
||||
## Open Questions
|
||||
- Vercel CLI integration pattern: wrap/fork/call/peer dependency?
|
||||
- bmad-update mechanics: diff/replace? Preserve user customizations?
|
||||
- Migration story: command/manual reinstall/compatibility shim?
|
||||
- Cross-platform testing: CI matrix for top N? Community testing for rest?
|
||||
- bmad-manifest.json as open standard submission to Agent Skills governance?
|
||||
- Platforms NOT supported by Vercel skills CLI?
|
||||
- Manifest versioning strategy for backward compatibility?
|
||||
- Plugin author getting-started experience and tooling?
|
||||
|
||||
## 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
|
||||
- Educational institutions: structured methodology + non-technical install → university AI curriculum
|
||||
- Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks
|
||||
|
||||
## Risks
|
||||
- Manifest format evolution creates versioning/compatibility burden once third-party authors publish
|
||||
- Quality gate needs defined process, not just claim — gated review model addresses
|
||||
- 40+ platform testing environments even with Vercel handling translation
|
||||
- Scope creep pressure from marketplace vision (explicitly excluded but primary long-term value)
|
||||
- Vercel dependency: minor supply-chain risk; MIT license allows fork if deprioritized
|
||||
```
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
# Semantic Splitting Strategy
|
||||
|
||||
When the source content is large (exceeds ~15,000 tokens) or a token_budget requires it, split the distillate into semantically coherent sections rather than arbitrary size breaks.
|
||||
|
||||
## Why Semantic Over Size-Based
|
||||
|
||||
Arbitrary splits (every N tokens) break coherence. A downstream workflow loading "part 2 of 4" gets context fragments. Semantic splits produce self-contained topic clusters that a workflow can load selectively — "give me just the technical decisions section" — which is more useful and more token-efficient for the consumer.
|
||||
|
||||
## Splitting Process
|
||||
|
||||
### 1. Identify Natural Boundaries
|
||||
|
||||
After the initial extraction and deduplication (Steps 1-2 of the compression process), look for natural semantic boundaries:
|
||||
- Distinct problem domains or functional areas
|
||||
- Different stakeholder perspectives (users, technical, business)
|
||||
- Temporal boundaries (current state vs future vision)
|
||||
- Scope boundaries (in-scope vs out-of-scope vs deferred)
|
||||
- Phase boundaries (analysis, design, implementation)
|
||||
|
||||
Choose boundaries that produce sections a downstream workflow might load independently.
|
||||
|
||||
### 2. Assign Items to Sections
|
||||
|
||||
For each extracted item, assign it to the most relevant section. Items that span multiple sections go in the root distillate.
|
||||
|
||||
Cross-cutting items (items relevant to multiple sections):
|
||||
- Constraints that affect all areas → root distillate
|
||||
- Decisions with broad impact → root distillate
|
||||
- Section-specific decisions → section distillate
|
||||
|
||||
### 3. Produce Root Distillate
|
||||
|
||||
The root distillate contains:
|
||||
- **Orientation** (3-5 bullets): what was distilled, from what sources, for what consumer, how many sections
|
||||
- **Cross-references**: list of section distillates with 1-line descriptions
|
||||
- **Cross-cutting items**: facts, decisions, and constraints that span multiple sections
|
||||
- **Scope summary**: high-level in/out/deferred if applicable
|
||||
|
||||
### 4. Produce Section Distillates
|
||||
|
||||
Each section distillate must be self-sufficient — a reader loading only one section should understand it without the others.
|
||||
|
||||
Each section includes:
|
||||
- **Context header** (1 line): "This section covers [topic]. Part N of M from [source document names]."
|
||||
- **Section content**: thematically-grouped bullets following the same compression rules as a single distillate
|
||||
- **Cross-references** (if needed): pointers to other sections for related content
|
||||
|
||||
### 5. Output Structure
|
||||
|
||||
Create a folder `{base-name}-distillate/` containing:
|
||||
|
||||
```
|
||||
{base-name}-distillate/
|
||||
├── _index.md # Root distillate: orientation, cross-cutting items, section manifest
|
||||
├── 01-{topic-slug}.md # Self-contained section
|
||||
├── 02-{topic-slug}.md
|
||||
└── 03-{topic-slug}.md
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
product-brief-distillate/
|
||||
├── _index.md
|
||||
├── 01-problem-solution.md
|
||||
├── 02-technical-decisions.md
|
||||
└── 03-users-market.md
|
||||
```
|
||||
|
||||
## Size Targets
|
||||
|
||||
When a token_budget is specified:
|
||||
- Root distillate: ~20% of budget (orientation + cross-cutting items)
|
||||
- Remaining budget split proportionally across sections based on content density
|
||||
- If a section exceeds its proportional share, compress more aggressively or sub-split
|
||||
|
||||
When no token_budget but splitting is needed:
|
||||
- Aim for sections of 3,000-5,000 tokens each
|
||||
- Root distillate as small as possible while remaining useful standalone
|
||||
|
|
@ -0,0 +1,300 @@
|
|||
# /// script
|
||||
# /// requires-python = ">=3.10"
|
||||
# /// dependencies = []
|
||||
# ///
|
||||
"""Analyze source documents for the distillation generator.
|
||||
|
||||
Enumerates files from paths/folders/globs, computes sizes and token estimates,
|
||||
detects document types from naming conventions, and suggests groupings for
|
||||
related documents (e.g., a brief paired with its discovery notes).
|
||||
|
||||
Accepts: file paths, folder paths (scans recursively for .md/.txt/.yaml/.yml/.json),
|
||||
or glob patterns. Skips node_modules, .git, __pycache__, .venv, _bmad-output.
|
||||
|
||||
Output JSON structure:
|
||||
status: "ok" | "error"
|
||||
files[]: path, filename, size_bytes, estimated_tokens, doc_type
|
||||
summary: total_files, total_size_bytes, total_estimated_tokens
|
||||
groups[]: group_key, files[] with role (primary/companion/standalone)
|
||||
- Groups related docs by naming convention (e.g., brief + discovery-notes)
|
||||
routing: recommendation ("single" | "fan-out"), reason
|
||||
- single: ≤3 files AND ≤15K estimated tokens
|
||||
- fan-out: >3 files OR >15K estimated tokens
|
||||
split_prediction: prediction ("likely" | "unlikely"), reason, estimated_distillate_tokens
|
||||
- Estimates distillate at ~1/3 source size; splits if >5K tokens
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import glob
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Extensions to include when scanning folders
|
||||
INCLUDE_EXTENSIONS = {".md", ".txt", ".yaml", ".yml", ".json"}
|
||||
|
||||
# Directories to skip when scanning folders
|
||||
SKIP_DIRS = {
|
||||
"node_modules", ".git", "__pycache__", ".venv", "venv",
|
||||
".claude", "_bmad-output", ".cursor", ".vscode",
|
||||
}
|
||||
|
||||
# Approximate chars per token for estimation
|
||||
CHARS_PER_TOKEN = 4
|
||||
|
||||
# Thresholds
|
||||
SINGLE_COMPRESSOR_MAX_TOKENS = 15_000
|
||||
SINGLE_DISTILLATE_MAX_TOKENS = 5_000
|
||||
|
||||
# Naming patterns for document type detection
|
||||
DOC_TYPE_PATTERNS = [
|
||||
(r"discovery[_-]notes", "discovery-notes"),
|
||||
(r"product[_-]brief", "product-brief"),
|
||||
(r"research[_-]report", "research-report"),
|
||||
(r"architecture", "architecture-doc"),
|
||||
(r"prd", "prd"),
|
||||
(r"distillate", "distillate"),
|
||||
(r"changelog", "changelog"),
|
||||
(r"readme", "readme"),
|
||||
(r"spec", "specification"),
|
||||
(r"requirements", "requirements"),
|
||||
(r"design[_-]doc", "design-doc"),
|
||||
(r"meeting[_-]notes", "meeting-notes"),
|
||||
(r"brainstorm", "brainstorming"),
|
||||
(r"interview", "interview-notes"),
|
||||
]
|
||||
|
||||
# Patterns for grouping related documents
|
||||
GROUP_PATTERNS = [
|
||||
# base document + discovery notes
|
||||
(r"^(.+?)(?:-discovery-notes|-discovery_notes)\.(\w+)$", r"\1.\2"),
|
||||
# base document + appendix
|
||||
(r"^(.+?)(?:-appendix|-addendum)(?:-\w+)?\.(\w+)$", r"\1.\2"),
|
||||
# base document + review/feedback
|
||||
(r"^(.+?)(?:-review|-feedback)\.(\w+)$", r"\1.\2"),
|
||||
]
|
||||
|
||||
|
||||
def resolve_inputs(inputs: list[str]) -> list[Path]:
|
||||
"""Resolve input arguments to a flat list of file paths."""
|
||||
files: list[Path] = []
|
||||
for inp in inputs:
|
||||
path = Path(inp)
|
||||
if path.is_file():
|
||||
files.append(path.resolve())
|
||||
elif path.is_dir():
|
||||
for root, dirs, filenames in os.walk(path):
|
||||
dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
|
||||
for fn in sorted(filenames):
|
||||
fp = Path(root) / fn
|
||||
if fp.suffix.lower() in INCLUDE_EXTENSIONS:
|
||||
files.append(fp.resolve())
|
||||
else:
|
||||
# Try as glob
|
||||
matches = glob.glob(inp, recursive=True)
|
||||
for m in sorted(matches):
|
||||
mp = Path(m)
|
||||
if mp.is_file() and mp.suffix.lower() in INCLUDE_EXTENSIONS:
|
||||
files.append(mp.resolve())
|
||||
# Deduplicate while preserving order
|
||||
seen: set[Path] = set()
|
||||
deduped: list[Path] = []
|
||||
for f in files:
|
||||
if f not in seen:
|
||||
seen.add(f)
|
||||
deduped.append(f)
|
||||
return deduped
|
||||
|
||||
|
||||
def detect_doc_type(filename: str) -> str:
|
||||
"""Detect document type from filename."""
|
||||
name_lower = filename.lower()
|
||||
for pattern, doc_type in DOC_TYPE_PATTERNS:
|
||||
if re.search(pattern, name_lower):
|
||||
return doc_type
|
||||
return "unknown"
|
||||
|
||||
|
||||
def suggest_groups(files: list[Path]) -> list[dict]:
|
||||
"""Suggest document groupings based on naming conventions."""
|
||||
groups: dict[str, list[dict]] = {}
|
||||
ungrouped: list[dict] = []
|
||||
|
||||
file_map = {f.name: f for f in files}
|
||||
|
||||
assigned: set[str] = set()
|
||||
|
||||
for f in files:
|
||||
if f.name in assigned:
|
||||
continue
|
||||
|
||||
matched = False
|
||||
for pattern, base_pattern in GROUP_PATTERNS:
|
||||
m = re.match(pattern, f.name, re.IGNORECASE)
|
||||
if m:
|
||||
# This file is a companion — find its base
|
||||
base_name = re.sub(pattern, base_pattern, f.name, flags=re.IGNORECASE)
|
||||
group_key = base_name
|
||||
if group_key not in groups:
|
||||
groups[group_key] = []
|
||||
# Add the base file if it exists
|
||||
if base_name in file_map and base_name not in assigned:
|
||||
groups[group_key].append({
|
||||
"path": str(file_map[base_name]),
|
||||
"filename": base_name,
|
||||
"role": "primary",
|
||||
})
|
||||
assigned.add(base_name)
|
||||
groups[group_key].append({
|
||||
"path": str(f),
|
||||
"filename": f.name,
|
||||
"role": "companion",
|
||||
})
|
||||
assigned.add(f.name)
|
||||
matched = True
|
||||
break
|
||||
|
||||
if not matched:
|
||||
# Check if this file is a base that already has companions
|
||||
if f.name in groups:
|
||||
continue # Already added as primary
|
||||
ungrouped.append({
|
||||
"path": str(f),
|
||||
"filename": f.name,
|
||||
})
|
||||
|
||||
result = []
|
||||
for group_key, members in groups.items():
|
||||
result.append({
|
||||
"group_key": group_key,
|
||||
"files": members,
|
||||
})
|
||||
for ug in ungrouped:
|
||||
if ug["filename"] not in assigned:
|
||||
result.append({
|
||||
"group_key": ug["filename"],
|
||||
"files": [{"path": ug["path"], "filename": ug["filename"], "role": "standalone"}],
|
||||
})
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def analyze(inputs: list[str], output_path: str | None = None) -> None:
|
||||
"""Main analysis function."""
|
||||
files = resolve_inputs(inputs)
|
||||
|
||||
if not files:
|
||||
result = {
|
||||
"status": "error",
|
||||
"error": "No readable files found from provided inputs",
|
||||
"inputs": inputs,
|
||||
}
|
||||
output_json(result, output_path)
|
||||
return
|
||||
|
||||
# Analyze each file
|
||||
file_details = []
|
||||
total_chars = 0
|
||||
for f in files:
|
||||
size = f.stat().st_size
|
||||
total_chars += size
|
||||
file_details.append({
|
||||
"path": str(f),
|
||||
"filename": f.name,
|
||||
"size_bytes": size,
|
||||
"estimated_tokens": size // CHARS_PER_TOKEN,
|
||||
"doc_type": detect_doc_type(f.name),
|
||||
})
|
||||
|
||||
total_tokens = total_chars // CHARS_PER_TOKEN
|
||||
groups = suggest_groups(files)
|
||||
|
||||
# Routing recommendation
|
||||
if len(files) <= 3 and total_tokens <= SINGLE_COMPRESSOR_MAX_TOKENS:
|
||||
routing = "single"
|
||||
routing_reason = (
|
||||
f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
|
||||
f"within single compressor threshold"
|
||||
)
|
||||
else:
|
||||
routing = "fan-out"
|
||||
routing_reason = (
|
||||
f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
|
||||
f"exceeds single compressor threshold "
|
||||
f"({'>' + str(SINGLE_COMPRESSOR_MAX_TOKENS) + ' tokens' if total_tokens > SINGLE_COMPRESSOR_MAX_TOKENS else '> 3 files'})"
|
||||
)
|
||||
|
||||
# Split prediction
|
||||
estimated_distillate_tokens = total_tokens // 3 # rough: distillate is ~1/3 of source
|
||||
if estimated_distillate_tokens > SINGLE_DISTILLATE_MAX_TOKENS:
|
||||
split_prediction = "likely"
|
||||
split_reason = (
|
||||
f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
|
||||
f"exceeds {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
|
||||
)
|
||||
else:
|
||||
split_prediction = "unlikely"
|
||||
split_reason = (
|
||||
f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
|
||||
f"within {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
|
||||
)
|
||||
|
||||
result = {
|
||||
"status": "ok",
|
||||
"files": file_details,
|
||||
"summary": {
|
||||
"total_files": len(files),
|
||||
"total_size_bytes": total_chars,
|
||||
"total_estimated_tokens": total_tokens,
|
||||
},
|
||||
"groups": groups,
|
||||
"routing": {
|
||||
"recommendation": routing,
|
||||
"reason": routing_reason,
|
||||
},
|
||||
"split_prediction": {
|
||||
"prediction": split_prediction,
|
||||
"reason": split_reason,
|
||||
"estimated_distillate_tokens": estimated_distillate_tokens,
|
||||
},
|
||||
}
|
||||
|
||||
output_json(result, output_path)
|
||||
|
||||
|
||||
def output_json(data: dict, output_path: str | None) -> None:
|
||||
"""Write JSON to file or stdout."""
|
||||
json_str = json.dumps(data, indent=2)
|
||||
if output_path:
|
||||
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
|
||||
Path(output_path).write_text(json_str + "\n")
|
||||
print(f"Results written to {output_path}", file=sys.stderr)
|
||||
else:
|
||||
print(json_str)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(
|
||||
description=__doc__,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
parser.add_argument(
|
||||
"inputs",
|
||||
nargs="+",
|
||||
help="File paths, folder paths, or glob patterns to analyze",
|
||||
)
|
||||
parser.add_argument(
|
||||
"-o", "--output",
|
||||
help="Output JSON to file instead of stdout",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
analyze(args.inputs, args.output)
|
||||
sys.exit(0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
|
@ -0,0 +1,204 @@
|
|||
"""Tests for analyze_sources.py"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
import pytest
|
||||
|
||||
# Add parent dir to path so we can import the script
|
||||
import sys
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent))
|
||||
|
||||
from analyze_sources import (
|
||||
resolve_inputs,
|
||||
detect_doc_type,
|
||||
suggest_groups,
|
||||
analyze,
|
||||
INCLUDE_EXTENSIONS,
|
||||
SKIP_DIRS,
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def temp_dir():
|
||||
"""Create a temp directory with sample files."""
|
||||
with tempfile.TemporaryDirectory() as d:
|
||||
# Create sample files
|
||||
(Path(d) / "product-brief-foo.md").write_text("# Product Brief\nContent here")
|
||||
(Path(d) / "product-brief-foo-discovery-notes.md").write_text("# Discovery\nNotes")
|
||||
(Path(d) / "architecture-doc.md").write_text("# Architecture\nDesign here")
|
||||
(Path(d) / "research-report.md").write_text("# Research\nFindings")
|
||||
(Path(d) / "random.txt").write_text("Some text content")
|
||||
(Path(d) / "image.png").write_bytes(b"\x89PNG")
|
||||
# Create a subdirectory with more files
|
||||
sub = Path(d) / "subdir"
|
||||
sub.mkdir()
|
||||
(sub / "prd-v2.md").write_text("# PRD\nRequirements")
|
||||
# Create a skip directory
|
||||
skip = Path(d) / "node_modules"
|
||||
skip.mkdir()
|
||||
(skip / "junk.md").write_text("Should be skipped")
|
||||
yield d
|
||||
|
||||
|
||||
class TestResolveInputs:
|
||||
def test_single_file(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
result = resolve_inputs([f])
|
||||
assert len(result) == 1
|
||||
assert result[0].name == "product-brief-foo.md"
|
||||
|
||||
def test_folder_recursion(self, temp_dir):
|
||||
result = resolve_inputs([temp_dir])
|
||||
names = {f.name for f in result}
|
||||
assert "product-brief-foo.md" in names
|
||||
assert "prd-v2.md" in names
|
||||
assert "random.txt" in names
|
||||
|
||||
def test_folder_skips_excluded_dirs(self, temp_dir):
|
||||
result = resolve_inputs([temp_dir])
|
||||
names = {f.name for f in result}
|
||||
assert "junk.md" not in names
|
||||
|
||||
def test_folder_skips_non_text_files(self, temp_dir):
|
||||
result = resolve_inputs([temp_dir])
|
||||
names = {f.name for f in result}
|
||||
assert "image.png" not in names
|
||||
|
||||
def test_glob_pattern(self, temp_dir):
|
||||
pattern = str(Path(temp_dir) / "product-brief-*.md")
|
||||
result = resolve_inputs([pattern])
|
||||
assert len(result) == 2
|
||||
names = {f.name for f in result}
|
||||
assert "product-brief-foo.md" in names
|
||||
assert "product-brief-foo-discovery-notes.md" in names
|
||||
|
||||
def test_deduplication(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
result = resolve_inputs([f, f, f])
|
||||
assert len(result) == 1
|
||||
|
||||
def test_mixed_inputs(self, temp_dir):
|
||||
file_path = str(Path(temp_dir) / "architecture-doc.md")
|
||||
folder_path = str(Path(temp_dir) / "subdir")
|
||||
result = resolve_inputs([file_path, folder_path])
|
||||
names = {f.name for f in result}
|
||||
assert "architecture-doc.md" in names
|
||||
assert "prd-v2.md" in names
|
||||
|
||||
def test_nonexistent_path(self):
|
||||
result = resolve_inputs(["/nonexistent/path/file.md"])
|
||||
assert len(result) == 0
|
||||
|
||||
|
||||
class TestDetectDocType:
|
||||
@pytest.mark.parametrize("filename,expected", [
|
||||
("product-brief-foo.md", "product-brief"),
|
||||
("product_brief_bar.md", "product-brief"),
|
||||
("foo-discovery-notes.md", "discovery-notes"),
|
||||
("foo-discovery_notes.md", "discovery-notes"),
|
||||
("architecture-overview.md", "architecture-doc"),
|
||||
("my-prd.md", "prd"),
|
||||
("research-report-q4.md", "research-report"),
|
||||
("foo-distillate.md", "distillate"),
|
||||
("changelog.md", "changelog"),
|
||||
("readme.md", "readme"),
|
||||
("api-spec.md", "specification"),
|
||||
("design-doc-v2.md", "design-doc"),
|
||||
("meeting-notes-2026.md", "meeting-notes"),
|
||||
("brainstorm-session.md", "brainstorming"),
|
||||
("user-interview-notes.md", "interview-notes"),
|
||||
("random-file.md", "unknown"),
|
||||
])
|
||||
def test_detection(self, filename, expected):
|
||||
assert detect_doc_type(filename) == expected
|
||||
|
||||
|
||||
class TestSuggestGroups:
|
||||
def test_groups_brief_with_discovery_notes(self, temp_dir):
|
||||
files = [
|
||||
Path(temp_dir) / "product-brief-foo.md",
|
||||
Path(temp_dir) / "product-brief-foo-discovery-notes.md",
|
||||
]
|
||||
groups = suggest_groups(files)
|
||||
# Should produce one group with both files
|
||||
paired = [g for g in groups if len(g["files"]) > 1]
|
||||
assert len(paired) == 1
|
||||
filenames = {f["filename"] for f in paired[0]["files"]}
|
||||
assert "product-brief-foo.md" in filenames
|
||||
assert "product-brief-foo-discovery-notes.md" in filenames
|
||||
|
||||
def test_standalone_files(self, temp_dir):
|
||||
files = [
|
||||
Path(temp_dir) / "architecture-doc.md",
|
||||
Path(temp_dir) / "research-report.md",
|
||||
]
|
||||
groups = suggest_groups(files)
|
||||
assert len(groups) == 2
|
||||
for g in groups:
|
||||
assert len(g["files"]) == 1
|
||||
|
||||
def test_mixed_grouped_and_standalone(self, temp_dir):
|
||||
files = [
|
||||
Path(temp_dir) / "product-brief-foo.md",
|
||||
Path(temp_dir) / "product-brief-foo-discovery-notes.md",
|
||||
Path(temp_dir) / "architecture-doc.md",
|
||||
]
|
||||
groups = suggest_groups(files)
|
||||
paired = [g for g in groups if len(g["files"]) > 1]
|
||||
standalone = [g for g in groups if len(g["files"]) == 1]
|
||||
assert len(paired) == 1
|
||||
assert len(standalone) == 1
|
||||
|
||||
|
||||
class TestAnalyze:
|
||||
def test_basic_analysis(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([f], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["status"] == "ok"
|
||||
assert result["summary"]["total_files"] == 1
|
||||
assert result["files"][0]["doc_type"] == "product-brief"
|
||||
assert result["files"][0]["estimated_tokens"] > 0
|
||||
|
||||
def test_routing_single_small_input(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([f], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["routing"]["recommendation"] == "single"
|
||||
|
||||
def test_routing_fanout_many_files(self, temp_dir):
|
||||
# Create enough files to trigger fan-out (> 3 files)
|
||||
for i in range(5):
|
||||
(Path(temp_dir) / f"doc-{i}.md").write_text("x" * 1000)
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([temp_dir], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["routing"]["recommendation"] == "fan-out"
|
||||
|
||||
def test_folder_analysis(self, temp_dir):
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([temp_dir], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["status"] == "ok"
|
||||
assert result["summary"]["total_files"] >= 4 # at least the base files
|
||||
assert len(result["groups"]) > 0
|
||||
|
||||
def test_no_files_found(self):
|
||||
output_file = "/tmp/test_analyze_empty.json"
|
||||
analyze(["/nonexistent/path"], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["status"] == "error"
|
||||
os.unlink(output_file)
|
||||
|
||||
def test_stdout_output(self, temp_dir, capsys):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
analyze([f])
|
||||
captured = capsys.readouterr()
|
||||
result = json.loads(captured.out)
|
||||
assert result["status"] == "ok"
|
||||
|
|
@ -0,0 +1 @@
|
|||
type: skill
|
||||
|
|
@ -169,8 +169,8 @@ Present the project classification for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Product Vision (Step 2b of 13)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current classification, process the enhanced insights that come back, ask user if they accept the improvements, if yes update classification then redisplay menu, if no keep original classification then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current classification, process the collaborative insights, ask user if they accept the changes, if yes update classification then redisplay menu, if no keep original classification then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current classification, process the enhanced insights that come back, ask user if they accept the improvements, if yes update classification then redisplay menu, if no keep original classification then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current classification, process the collaborative insights, ask user if they accept the changes, if yes update classification then redisplay menu, if no keep original classification then redisplay menu
|
||||
- IF C: Save classification to {outputFile} frontmatter, add this step name to the end of stepsCompleted array, then read fully and follow: ./step-02b-vision.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -101,8 +101,8 @@ Present your understanding of the product vision for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Executive Summary (Step 2c of 13)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current vision insights, process the enhanced insights that come back, ask user if they accept the improvements, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current vision insights, process the collaborative insights, ask user if they accept the changes, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current vision insights, process the enhanced insights that come back, ask user if they accept the improvements, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current vision insights, process the collaborative insights, ask user if they accept the changes, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
|
||||
- IF C: Update {outputFile} frontmatter by adding this step name to the end of stepsCompleted array, then read fully and follow: ./step-02c-executive-summary.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -91,8 +91,8 @@ Present the executive summary content for user review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Success Criteria (Step 3 of 13)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current executive summary content, process the enhanced content that comes back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current executive summary content, process the collaborative improvements, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current executive summary content, process the enhanced content that comes back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current executive summary content, process the collaborative improvements, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-03-success.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -163,8 +163,8 @@ Present the success criteria content for user review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to User Journey Mapping (Step 4 of 11)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current success criteria content, process the enhanced success metrics that come back, ask user "Accept these improvements to the success criteria? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current success criteria, process the collaborative improvements to metrics and scope, ask user "Accept these changes to the success criteria? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current success criteria content, process the enhanced success metrics that come back, ask user "Accept these improvements to the success criteria? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current success criteria, process the collaborative improvements to metrics and scope, ask user "Accept these changes to the success criteria? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-04-journeys.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -143,8 +143,8 @@ Present the user journey content for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Domain Requirements (Step 5 of 11)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current journey content, process the enhanced journey insights that come back, ask user "Accept these improvements to the user journeys? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current journeys, process the collaborative journey improvements and additions, ask user "Accept these changes to the user journeys? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current journey content, process the enhanced journey insights that come back, ask user "Accept these improvements to the user journeys? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current journeys, process the collaborative journey improvements and additions, ask user "Accept these changes to the user journeys? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-05-domain.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ Acknowledge the domain and explore what makes it complex:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue - Save and Proceed to Innovation (Step 6 of 13)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation, and when finished redisplay the menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill, and when finished redisplay the menu
|
||||
- IF P: Read fully and follow: `{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md` and when finished redisplay the menu
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then read fully and follow: ./step-06-innovation.md
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
|
|
|||
|
|
@ -140,8 +140,8 @@ Present the innovation content for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Project Type Analysis (Step 7 of 11)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current innovation content, process the enhanced innovation insights that come back, ask user "Accept these improvements to the innovation analysis? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current innovation content, process the collaborative innovation exploration and ideation, ask user "Accept these changes to the innovation analysis? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current innovation content, process the enhanced innovation insights that come back, ask user "Accept these improvements to the innovation analysis? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current innovation content, process the collaborative innovation exploration and ideation, ask user "Accept these changes to the innovation analysis? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-07-project-type.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -157,8 +157,8 @@ Present the project-type content for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Scoping (Step 8 of 11)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current project-type content, process the enhanced technical insights that come back, ask user "Accept these improvements to the technical requirements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current project-type requirements, process the collaborative technical expertise and validation, ask user "Accept these changes to the technical requirements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current project-type content, process the enhanced technical insights that come back, ask user "Accept these improvements to the technical requirements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current project-type requirements, process the collaborative technical expertise and validation, ask user "Accept these changes to the technical requirements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-08-scoping.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -171,8 +171,8 @@ Present the scoping decisions for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Functional Requirements (Step 9 of 11)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current scoping analysis, process the enhanced insights that come back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the scoping context, process the collaborative insights on MVP and roadmap decisions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current scoping analysis, process the enhanced insights that come back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the scoping context, process the collaborative insights on MVP and roadmap decisions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-09-functional.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
|
|
@ -169,8 +169,8 @@ Present the functional requirements for review, then display menu:
|
|||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Non-Functional Requirements (Step 10 of 11)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow: skill:bmad-advanced-elicitation with the current FR list, process the enhanced capability coverage that comes back, ask user if they accept the additions, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current FR list, process the collaborative capability validation and additions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF A: Invoke the `bmad-advanced-elicitation` skill with the current FR list, process the enhanced capability coverage that comes back, ask user if they accept the additions, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF P: Invoke the `bmad-party-mode` skill with the current FR list, process the collaborative capability validation and additions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
|
||||
- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-10-nonfunctional.md
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue