Ignore and untrack BMad directories
This commit is contained in:
Max
@@ -1,152 +0,0 @@
|
||||
# Workflow Architecture
|
||||
|
||||
**Purpose:** Core structural patterns for BMAD workflows.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
workflow-folder/
|
||||
├── workflow.md # Entry point, configuration
|
||||
├── steps-c/ # Create flow steps
|
||||
│ ├── step-01-init.md
|
||||
│ ├── step-02-[name].md
|
||||
│ └── step-N-[name].md
|
||||
├── steps-e/ # Edit flow (if needed)
|
||||
├── steps-v/ # Validate flow (if needed)
|
||||
├── data/ # Shared reference files
|
||||
└── templates/ # Output templates (if needed)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## workflow.md File Standards
|
||||
|
||||
**CRITICAL:** The workflow.md file MUST be lean. It is the entry point and should NOT contain:
|
||||
|
||||
- ❌ **Listing of all steps** - This defeats progressive disclosure
|
||||
- ❌ **Detailed descriptions of what each step does** - Steps are self-documenting
|
||||
- ❌ **Validation checklists** - These belong in steps-v/, not workflow.md
|
||||
- ❌ **Implementation details** - These belong in step files
|
||||
|
||||
**The workflow.md SHOULD contain:**
|
||||
- ✅ Frontmatter: name, description, web_bundle
|
||||
- ✅ Goal: What the workflow accomplishes
|
||||
- ✅ Role: Who the AI embodies when running this workflow
|
||||
- ✅ Meta-context: Background about the architecture (if demonstrating a pattern)
|
||||
- ✅ Core architecture principles (step-file design, JIT loading, etc.)
|
||||
- ✅ Initialization/routing: How to start and which step to load first
|
||||
|
||||
**Progressive Disclosure Rule:**
|
||||
Users should ONLY know about the current step they're executing. The workflow.md routes to the first step, and each step routes to the next. No step lists in workflow.md!
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Micro-File Design
|
||||
- Each step is a focused file (~80-200 lines)
|
||||
- One concept per step
|
||||
- Self-contained instructions
|
||||
|
||||
### 2. Just-In-Time Loading
|
||||
- Only current step file is in memory
|
||||
- Never load future steps until user selects 'C'
|
||||
- Progressive disclosure - LLM stays focused
|
||||
|
||||
### 3. Sequential Enforcement
|
||||
- Steps execute in order
|
||||
- No skipping, no optimization
|
||||
- Each step completes before next loads
|
||||
|
||||
### 4. State Tracking
|
||||
For continuable workflows:
|
||||
```yaml
|
||||
stepsCompleted: ['step-01-init', 'step-02-gather', 'step-03-design']
|
||||
lastStep: 'step-03-design'
|
||||
lastContinued: '2025-01-02'
|
||||
```
|
||||
|
||||
Each step appends its name to `stepsCompleted` before loading next.
|
||||
|
||||
---
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Fresh Start
|
||||
```
|
||||
workflow.md → step-01-init.md → step-02-[name].md → ... → step-N-final.md
|
||||
```
|
||||
|
||||
### Continuation (Resumed)
|
||||
```
|
||||
workflow.md → step-01-init.md (detects existing) → step-01b-continue.md → [appropriate next step]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Variables
|
||||
|
||||
### Standard (All Workflows)
|
||||
```yaml
|
||||
workflow_path: '{project-root}/_bmad/[module]/workflows/[name]'
|
||||
thisStepFile: './step-[N]-[name].md'
|
||||
nextStepFile: './step-[N+1]-[name].md'
|
||||
outputFile: '{output_folder}/[output].md'
|
||||
```
|
||||
|
||||
### Module-Specific
|
||||
```yaml
|
||||
# BMB example:
|
||||
bmb_creations_output_folder: '{project-root}/_bmad/bmb-creations'
|
||||
```
|
||||
|
||||
### Critical Rules
|
||||
- ONLY variables used in step body go in frontmatter
|
||||
- All file references use `{variable}` format
|
||||
- Paths within workflow folder are relative
|
||||
|
||||
---
|
||||
|
||||
## Menu Pattern
|
||||
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select:** [A] [action] [P] [action] [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {task}, then redisplay menu
|
||||
- IF P: Execute {task}, then redisplay menu
|
||||
- IF C: Save to {outputFile}, update frontmatter, then load {nextStepFile}
|
||||
- IF Any other: help user, then redisplay menu
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
```
|
||||
|
||||
**A/P not needed in:** Step 1 (init), validation sequences, simple data gathering
|
||||
|
||||
---
|
||||
|
||||
## Output Pattern
|
||||
|
||||
Every step writes to a document BEFORE loading next step:
|
||||
|
||||
1. **Plan-then-build:** Steps append to plan.md → build step consumes plan
|
||||
2. **Direct-to-final:** Steps append directly to final document
|
||||
|
||||
See: `output-format-standards.md`
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
- 🛑 NEVER load multiple step files simultaneously
|
||||
- 📖 ALWAYS read entire step file before execution
|
||||
- 🚫 NEVER skip steps or optimize the sequence
|
||||
- 💾 ALWAYS update frontmatter when step completes
|
||||
- ⏸️ ALWAYS halt at menus and wait for input
|
||||
- 📋 NEVER create mental todos from future steps
|
||||
@@ -1,19 +0,0 @@
|
||||
propose,type,tool_name,description,url,requires_install
|
||||
always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/_bmad/core/workflows/party-mode/workflow.md,no
|
||||
always,workflow,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
|
||||
always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/_bmad/core/tasks/brainstorming.xml,no
|
||||
always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
|
||||
always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no
|
||||
always,llm-tool-feature,sub-agents,"Allows LLM to create and manage specialized sub-agents that handle specific tasks or modules within larger workflows, improving efficiency through parallel processing and modular task delegation.",,no
|
||||
always,llm-tool-feature,sub-processes,"Enables LLM to initiate and manage subprocesses that operate independently, allowing for parallel processing of complex tasks and improved resource utilization during long-running operations.",,no
|
||||
always,tool-memory,sidecar-file,"Creates a persistent history file that gets written during workflow execution and loaded on future runs, enabling continuity through session-to-session state management. Used for agent or workflow initialization with previous session context, learning from past interactions, and maintaining progress across multiple executions.",,no
|
||||
example,tool-memory,vector-database,"Stores and retrieves semantic information through embeddings for intelligent memory access, enabling workflows to find relevant past experiences, patterns, or context based on meaning rather than exact matches. Useful for complex learning systems, pattern recognition, and semantic search across workflow history.",https://github.com/modelcontextprotocol/servers/tree/main/src/rag-agent,yes
|
||||
example,mcp,context-7,"A curated knowledge base of API documentation and third-party tool references, enabling LLM to access accurate and current information for integration and development tasks when specific technical documentation is needed.",https://github.com/modelcontextprotocol/servers/tree/main/src/context-7,yes
|
||||
example,mcp,playwright,"Provides capabilities for LLM to perform web browser automation including navigation, form submission, data extraction, and testing actions on web pages, facilitating automated web interactions and quality assurance.",https://github.com/modelcontextprotocol/servers/tree/main/src/playwright,yes
|
||||
example,workflow,security-auditor,"Analyzes workflows and code for security vulnerabilities, compliance issues, and best practices violations, providing detailed security assessments and remediation recommendations for production-ready systems.",,no
|
||||
example,task,code-review,"Performs systematic code analysis with peer review perspectives, identifying bugs, performance issues, style violations, and architectural problems through adversarial review techniques.",,no
|
||||
example,mcp,git-integration,"Enables direct Git repository operations including commits, branches, merges, and history analysis, allowing workflows to interact with version control systems for code management and collaboration.",https://github.com/modelcontextprotocol/servers/tree/main/src/git,yes
|
||||
example,mcp,database-connector,"Provides direct database connectivity for querying, updating, and managing data across multiple database types, enabling workflows to interact with structured data sources and perform data-driven operations.",https://github.com/modelcontextprotocol/servers/tree/main/src/postgres,yes
|
||||
example,task,api-testing,"Automated API endpoint testing with request/response validation, authentication handling, and comprehensive reporting for REST, GraphQL, and other API types through systematic test generation.",,no
|
||||
example,workflow,deployment-manager,"Orchestrates application deployment across multiple environments with rollback capabilities, health checks, and automated release pipelines for continuous integration and delivery workflows.",,no
|
||||
example,task,data-validator,"Validates data quality, schema compliance, and business rules through comprehensive data profiling with detailed reporting and anomaly detection for data-intensive workflows.",,no
|
||||
|
@@ -1,81 +0,0 @@
|
||||
# CSV Data File Standards
|
||||
|
||||
**Purpose:** When workflows need structured data that LLMs cannot generate.
|
||||
|
||||
---
|
||||
|
||||
## When to Use CSV
|
||||
|
||||
Use CSV for data that is:
|
||||
- Domain-specific and not in training data
|
||||
- Too large for prompt context
|
||||
- Needs structured lookup/reference
|
||||
- Must be consistent across sessions
|
||||
|
||||
**Don't use for:**
|
||||
- Web-searchable information
|
||||
- Common programming syntax
|
||||
- General knowledge
|
||||
- Things LLMs can generate
|
||||
|
||||
---
|
||||
|
||||
## CSV Structure
|
||||
|
||||
```csv
|
||||
category,name,pattern,description
|
||||
"collaboration","Think Aloud Protocol","user speaks thoughts → facilitator captures","Make thinking visible during work"
|
||||
"creative","SCAMPER","substitute→combine→adapt→modify→put→eliminate→reverse","Systematic creative thinking"
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Header row required, descriptive column names
|
||||
- Consistent data types per column
|
||||
- UTF-8 encoding
|
||||
- All columns must be used in workflow
|
||||
|
||||
---
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Method Registry
|
||||
Advanced Elicitation uses CSV to select techniques dynamically:
|
||||
```csv
|
||||
category,name,pattern
|
||||
collaboration,Think Aloud,user speaks thoughts → facilitator captures
|
||||
advanced,Six Thinking Hats,view problem from 6 perspectives
|
||||
```
|
||||
|
||||
### 2. Knowledge Base Index
|
||||
Map keywords to document locations for surgical lookup:
|
||||
```csv
|
||||
keywords,document_path,section
|
||||
"nutrition,macros",data/nutrition-reference.md,## Daily Targets
|
||||
```
|
||||
|
||||
### 3. Configuration Lookup
|
||||
Map scenarios to parameters:
|
||||
```csv
|
||||
scenario,required_steps,output_sections
|
||||
"2D Platformer",step-01,step-03,step-07,movement,physics,collision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Keep files small (<1MB if possible)
|
||||
- No unused columns
|
||||
- Document each CSV's purpose
|
||||
- Validate data quality
|
||||
- Use efficient encoding (codes vs full descriptions)
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For each CSV file:
|
||||
- [ ] Purpose is essential (can't be generated by LLM)
|
||||
- [ ] All columns are used somewhere
|
||||
- [ ] Properly formatted (consistent, UTF-8)
|
||||
- [ ] Documented with examples
|
||||
@@ -1,225 +0,0 @@
|
||||
# Frontmatter Standards
|
||||
|
||||
**Purpose:** Variables, paths, and frontmatter rules for workflow steps.
|
||||
|
||||
---
|
||||
|
||||
## Golden Rules
|
||||
|
||||
1. **Only variables USED in the step** may be in frontmatter
|
||||
2. **All file references MUST use `{variable}` format** - no hardcoded paths
|
||||
3. **Paths within workflow folder MUST be relative** - NO `workflow_path` variable allowed
|
||||
|
||||
---
|
||||
|
||||
## Standard Variables (Always Available)
|
||||
|
||||
| Variable | Example Value |
|
||||
| ---------------------------- | ------------------------------------ |
|
||||
| `{project-root}` | `/Users/user/dev/BMAD-METHOD` |
|
||||
| `{project_name}` | `my-project` |
|
||||
| `{output_folder}` | `/Users/user/dev/BMAD-METHOD/output` |
|
||||
| `{user_name}` | `Brian` |
|
||||
| `{communication_language}` | `english` |
|
||||
| `{document_output_language}` | `english` |
|
||||
|
||||
---
|
||||
|
||||
## Module-Specific Variables
|
||||
|
||||
Workflows in a MODULE can access additional variables from its `module.yaml`.
|
||||
|
||||
**BMB Module example:**
|
||||
```yaml
|
||||
bmb_creations_output_folder: '{project-root}/_bmad/bmb-creations'
|
||||
```
|
||||
|
||||
**Standalone workflows:** Only have access to standard variables.
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Structure
|
||||
|
||||
### Required Fields
|
||||
```yaml
|
||||
---
|
||||
name: 'step-[N]-[name]'
|
||||
description: '[what this step does]'
|
||||
---
|
||||
```
|
||||
|
||||
### File References - ONLY variables used in this step
|
||||
```yaml
|
||||
---
|
||||
# Step to step (SAME folder) - use ./filename.md
|
||||
nextStepFile: './step-02-vision.md'
|
||||
|
||||
# Step to template (PARENT folder) - use ../filename.md
|
||||
productBriefTemplate: '../product-brief.template.md'
|
||||
|
||||
# Step to data (SUBFOLDER) - use ./data/filename.md
|
||||
someData: './data/config.csv'
|
||||
|
||||
# Output files - use variable
|
||||
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
|
||||
|
||||
# External references - use {project-root}
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Rule: Unused Variables Forbidden
|
||||
|
||||
### ❌ VIOLATION - Variable defined but never used
|
||||
```yaml
|
||||
---
|
||||
outputFile: '{output_folder}/output.md'
|
||||
thisStepFile: './step-01-init.md' # ❌ NEVER USED in body
|
||||
workflowFile: './workflow.md' # ❌ NEVER USED in body
|
||||
---
|
||||
# Step body never mentions {thisStepFile} or {workflowFile}
|
||||
```
|
||||
|
||||
### ✅ CORRECT - Only variables that are used
|
||||
```yaml
|
||||
---
|
||||
outputFile: '{output_folder}/output.md'
|
||||
nextStepFile: './step-02-foo.md'
|
||||
---
|
||||
# Step body uses {outputFile} and {nextStepFile}
|
||||
```
|
||||
|
||||
**Detection Rule:** For EVERY variable in frontmatter, search the step body for `{variableName}`. If not found, it's a violation.
|
||||
|
||||
---
|
||||
|
||||
## Path Rules - NO EXCEPTIONS
|
||||
|
||||
### 1. Step to Step (SAME folder) = ./filename.md
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
nextStepFile: './step-02.md'
|
||||
nextStepFile: '{project-root}/_bmad/bmm/workflows/foo/steps/step-02.md'
|
||||
|
||||
# ✅ CORRECT
|
||||
nextStepFile: './step-02-vision.md'
|
||||
```
|
||||
|
||||
### 2. Step to Template (PARENT folder) = ../filename.md
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
someTemplate: '{workflow_path}/templates/template.md'
|
||||
|
||||
# ✅ CORRECT
|
||||
someTemplate: '../template.md'
|
||||
```
|
||||
|
||||
### 3. Step to Subfolder = ./subfolder/file.md
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
dataFile: '{workflow_path}/data/config.csv'
|
||||
|
||||
# ✅ CORRECT
|
||||
dataFile: './data/config.csv'
|
||||
```
|
||||
|
||||
### 4. External References = {project-root}/...
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
```
|
||||
|
||||
### 5. Output Files = Use folder variable
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
outputFile: '{planning_artifacts}/workflow-output-{project_name}.md'
|
||||
outputFile: '{output_folder}/output.md'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ❌ FORBIDDEN Patterns
|
||||
|
||||
These patterns are **NEVER ALLOWED** in workflow step frontmatter:
|
||||
|
||||
| Pattern | Why It's Wrong |
|
||||
| ------------------------------------- | ----------------------------------------------------- |
|
||||
| `workflow_path: '{project-root}/...'` | Use relative paths instead |
|
||||
| `thisStepFile: './step-XX.md'` | Almost never used - remove unless actually referenced |
|
||||
| `workflowFile: './workflow.md'` | Almost never used - remove unless actually referenced |
|
||||
| `./...` | Use `./step-XX.md` (same folder) |
|
||||
| `{workflow_path}/templates/...` | Use `../template.md` (parent folder) |
|
||||
| `{workflow_path}/data/...` | Use `./data/file.md` (subfolder) |
|
||||
|
||||
---
|
||||
|
||||
## Variable Naming
|
||||
|
||||
Use `snake_case` with descriptive prefixes:
|
||||
|
||||
| Pattern | Usage | Example |
|
||||
| -------------- | ------------------- | ---------------------------- |
|
||||
| `{*_File}` | File references | `outputFile`, `nextStepFile` |
|
||||
| `{*_Task}` | Task references | `advancedElicitationTask` |
|
||||
| `{*_Workflow}` | Workflow references | `partyModeWorkflow` |
|
||||
| `{*_Template}` | Templates | `productBriefTemplate` |
|
||||
| `{*_Data}` | Data files | `dietaryData` |
|
||||
|
||||
---
|
||||
|
||||
## Defining New Variables
|
||||
|
||||
Steps can define NEW variables that future steps will use.
|
||||
|
||||
**Step 01 defines:**
|
||||
```yaml
|
||||
---
|
||||
targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
|
||||
---
|
||||
# Uses {targetWorkflowPath} in body
|
||||
```
|
||||
|
||||
**Step 02 uses:**
|
||||
```yaml
|
||||
---
|
||||
targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
|
||||
workflowPlanFile: '{targetWorkflowPath}/plan.md'
|
||||
---
|
||||
# Uses {targetWorkflowPath} and {workflowPlanFile} in body
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Continuable Workflow Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
stepsCompleted: ['step-01-init', 'step-02-gather', 'step-03-design']
|
||||
lastStep: 'step-03-design'
|
||||
lastContinued: '2025-01-02'
|
||||
date: '2025-01-01'
|
||||
---
|
||||
```
|
||||
|
||||
**Step tracking:** Each step appends its NAME to `stepsCompleted`.
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For EVERY step frontmatter, verify:
|
||||
|
||||
- [ ] `name` present, kebab-case format
|
||||
- [ ] `description` present
|
||||
- [ ] Extract ALL variable names from frontmatter (between `---` markers)
|
||||
- [ ] For EACH variable, search body: is `{variableName}` present?
|
||||
- [ ] If variable NOT in body → ❌ VIOLATION, remove from frontmatter
|
||||
- [ ] All step-to-step paths use `./filename.md` format (same folder)
|
||||
- [ ] All parent-folder paths use `../filename.md` format
|
||||
- [ ] All subfolder paths use `./subfolder/filename.md` format
|
||||
- [ ] NO `{workflow_path}` variable exists
|
||||
- [ ] External paths use `{project-root}` variable
|
||||
- [ ] Module variables only used if workflow belongs to that module
|
||||
@@ -1,269 +0,0 @@
|
||||
# Input Document Discovery Standards
|
||||
|
||||
**Purpose:** How workflows discover, validate, and select input documents from prior workflows or external sources.
|
||||
|
||||
---
|
||||
|
||||
## Discovery Patterns
|
||||
|
||||
### Pattern 1: Prior Workflow Output
|
||||
**Use when:** Workflow is part of a sequence (e.g., PRD → Architecture → Epics)
|
||||
|
||||
**Example:** BMM module pipeline - each of these are a workflow with many steps:
|
||||
```
|
||||
brainstorming → research → brief → PRD → UX → architecture → epics → sprint-planning
|
||||
```
|
||||
|
||||
Each workflow checks for output from prior workflow(s).
|
||||
|
||||
### Pattern 2: Module Folder Search
|
||||
**Use when:** Documents stored in known project location
|
||||
|
||||
**Example:** Manager review workflow searches `{project_folder}/employee-notes/`
|
||||
|
||||
### Pattern 3: User-Specified Paths
|
||||
**Use when:** User provides document locations
|
||||
|
||||
**Example:** Tax workflow asks for financial statement paths
|
||||
|
||||
### Pattern 4: Pattern-Based Discovery
|
||||
**Use when:** Search by file naming pattern
|
||||
|
||||
**Example:** Find all `*-brief.md` files in `{planning_artifacts}/`
|
||||
|
||||
---
|
||||
|
||||
## Discovery Step Pattern
|
||||
|
||||
**When:** Step 1 (init) or Step 2 (discovery)
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
# Input discovery variables
|
||||
inputDocuments: [] # Populated with discovered docs
|
||||
requiredInputCount: 1 # Minimum required to proceed
|
||||
optionalInputCount: 0 # Additional docs user may provide
|
||||
moduleInputFolder: '{planning_artifacts}' # Where to search
|
||||
inputFilePatterns: # File patterns to match
|
||||
- '*-prd.md'
|
||||
- '*-ux.md'
|
||||
---
|
||||
```
|
||||
|
||||
**Discovery Logic:**
|
||||
```markdown
|
||||
## 1. Check for Known Prior Workflow Outputs
|
||||
|
||||
Search in order:
|
||||
1. {module_output_folder}/[known-prior-workflow-output].md
|
||||
2. {project_folder}/[standard-locations]/
|
||||
3. {planning_artifacts}/
|
||||
4. User-provided paths
|
||||
|
||||
## 2. Pattern-Based Search
|
||||
|
||||
If no known prior workflow, search by patterns:
|
||||
- Look for files matching {inputFilePatterns}
|
||||
- Search in {moduleInputFolder}
|
||||
- Search in {project_folder}/docs/
|
||||
|
||||
## 3. Present Findings to User
|
||||
|
||||
"Found these documents that may be relevant:
|
||||
- [1] prd-my-project.md (created 3 days ago)
|
||||
- [2] ux-research.md (created 1 week ago)
|
||||
- [3] competitor-analysis.md
|
||||
|
||||
Which would you like to use? You can select multiple, or provide additional paths."
|
||||
|
||||
## 4. Confirm and Load
|
||||
|
||||
User confirms selection → Load selected documents
|
||||
Add to {inputDocuments} array in output frontmatter
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required vs Optional Inputs
|
||||
|
||||
### Required Inputs
|
||||
Workflow cannot proceed without these.
|
||||
|
||||
**Example:** Architecture workflow requires PRD
|
||||
|
||||
```markdown
|
||||
## INPUT REQUIREMENT:
|
||||
|
||||
This workflow requires a Product Requirements Document to proceed.
|
||||
|
||||
Searching for PRD in:
|
||||
- {bmm_creations_output_folder}/prd-*.md
|
||||
- {planning_artifacts}/*-prd.md
|
||||
- {project_folder}/docs/*-prd.md
|
||||
|
||||
[If found:]
|
||||
"Found PRD: prd-my-project.md. Use this?"
|
||||
[If not found:]
|
||||
"No PRD found. This workflow requires a PRD to continue.
|
||||
Please provide the path to your PRD, or run the PRD workflow first."
|
||||
```
|
||||
|
||||
### Optional Inputs
|
||||
Workflow can proceed without these, but user may include.
|
||||
|
||||
**Example:** UX workflow can use research docs if available
|
||||
|
||||
```markdown
|
||||
## OPTIONAL INPUTS:
|
||||
|
||||
This workflow can incorporate research documents if available.
|
||||
|
||||
Searching for research in:
|
||||
- {bmm_creations_output_folder}/research-*.md
|
||||
- {project_folder}/research/
|
||||
|
||||
[If found:]
|
||||
"Found these research documents:
|
||||
- [1] user-interviews.md
|
||||
- [2] competitive-analysis.md
|
||||
Include any? (None required to proceed)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Workflow Chaining
|
||||
|
||||
**For modules with sequential workflows:**
|
||||
|
||||
**Frontmatter in workflow.md:**
|
||||
```yaml
|
||||
---
|
||||
## INPUT FROM PRIOR WORKFLOFS
|
||||
|
||||
### Required Inputs:
|
||||
- {module_output_folder}/prd-{project_name}.md
|
||||
|
||||
### Optional Inputs:
|
||||
- {module_output_folder}/ux-research-{project_name}.md
|
||||
- {project_folder}/docs/competitor-analysis.md
|
||||
---
|
||||
```
|
||||
|
||||
**Step 1 discovery:**
|
||||
```markdown
|
||||
## 1. Discover Prior Workflow Outputs
|
||||
|
||||
Check for required inputs:
|
||||
1. Look for {module_output_folder}/prd-{project_name}.md
|
||||
2. If missing → Error: "Please run PRD workflow first"
|
||||
3. If found → Confirm with user
|
||||
|
||||
Check for optional inputs:
|
||||
1. Search {module_output_folder}/ for research-*.md
|
||||
2. Search {project_folder}/docs/ for *-analysis.md
|
||||
3. Present findings to user
|
||||
4. Add selections to {inputDocuments}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Input Validation
|
||||
|
||||
After discovery, validate inputs:
|
||||
|
||||
```markdown
|
||||
## INPUT VALIDATION:
|
||||
|
||||
For each discovered document:
|
||||
1. Load and read frontmatter
|
||||
2. Check workflowType field (should match expected)
|
||||
3. Check completeness (stepsCompleted should be complete)
|
||||
4. Check date (warn if document is very old)
|
||||
|
||||
[If validation fails:]
|
||||
"Document prd-my-project.md appears incomplete.
|
||||
Last step: step-06 (of 11)
|
||||
Recommend completing PRD workflow before proceeding.
|
||||
Proceed anyway? [Y]es [N]o"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multiple Input Selection
|
||||
|
||||
**When user can select multiple documents:**
|
||||
|
||||
```markdown
|
||||
## Document Selection
|
||||
|
||||
"Found these relevant documents:
|
||||
[1] prd-my-project.md (3 days ago) ✓ Recommended
|
||||
[2] prd-v1.md (2 months ago) ⚠ Older version
|
||||
[3] ux-research.md (1 week ago)
|
||||
|
||||
Enter numbers to include (comma-separated), or 'none' to skip:
|
||||
> 1, 3
|
||||
|
||||
Selected: prd-my-project.md, ux-research.md"
|
||||
```
|
||||
|
||||
**Track in frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
inputDocuments:
|
||||
- path: '{output_folder}/prd-my-project.md'
|
||||
type: 'prd'
|
||||
source: 'prior-workflow'
|
||||
selected: true
|
||||
- path: '{output_folder}/ux-research.md'
|
||||
type: 'research'
|
||||
source: 'prior-workflow'
|
||||
selected: true
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Search Path Variables
|
||||
|
||||
Common module variables for input discovery:
|
||||
|
||||
| Variable | Purpose |
|
||||
| ------------------------ | -------------------------- |
|
||||
| `{module_output_folder}` | Prior workflow outputs |
|
||||
| `{planning_artifacts}` | General planning docs |
|
||||
| `{project_folder}/docs` | Project documentation |
|
||||
| `{product_knowledge}` | Product-specific knowledge |
|
||||
| `{user_documents}` | User-provided location |
|
||||
|
||||
---
|
||||
|
||||
## Discovery Step Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: 'step-01-init'
|
||||
description: 'Initialize and discover input documents'
|
||||
|
||||
# Input Discovery
|
||||
inputDocuments: []
|
||||
requiredInputCount: 1
|
||||
moduleInputFolder: '{module_output_folder}'
|
||||
inputFilePatterns:
|
||||
- '*-prd.md'
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For input discovery:
|
||||
- [ ] Required inputs defined in step frontmatter
|
||||
- [ ] Search paths defined (module variables or patterns)
|
||||
- [ ] User confirmation before using documents
|
||||
- [ ] Validation of document completeness
|
||||
- [ ] Clear error messages when required inputs missing
|
||||
- [ ] Support for multiple document selection
|
||||
- [ ] Optional inputs clearly marked as optional
|
||||
@@ -1,50 +0,0 @@
|
||||
# Intent vs Prescriptive Spectrum
|
||||
|
||||
**Principle:** Workflows lean toward **intent** (goals) not **prescription** (exact wording). The more intent-based, the more adaptive and creative the LLM can be.
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each
|
||||
|
||||
### Intent-Based (Default)
|
||||
**Use for:** Most workflows - creative, exploratory, collaborative
|
||||
**Step instruction:** "Help the user understand X using multi-turn conversation. Probe to get good answers. Ask 1-2 questions at a time, not a laundry list."
|
||||
**LLM figures out:** Exact wording, question order, how to respond
|
||||
|
||||
### Prescriptive (Exception)
|
||||
**Use for:** Compliance, safety, legal, medical, regulated industries
|
||||
**Step instruction:** "Say exactly: 'Do you currently experience fever, cough, or fatigue?' Wait for response. Then ask exactly: 'When did symptoms begin?'"
|
||||
**LLM follows:** Exact script, specific order, no deviation
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Intent-Based (Good for most)
|
||||
```
|
||||
"Guide the user through discovering their ideal nutrition plan.
|
||||
Use multi-turn conversation. Ask 1-2 questions at a time.
|
||||
Think about their responses before asking follow-ups.
|
||||
Probe to understand preferences, restrictions, goals."
|
||||
```
|
||||
|
||||
### Prescriptive (Only when required)
|
||||
```
|
||||
"Medical intake - ask exactly:
|
||||
1. 'Do you have any of these symptoms: fever, cough, fatigue?'
|
||||
2. 'When did symptoms begin?'
|
||||
3. 'Have you traveled recently in the last 14 days?'
|
||||
Follow sequence precisely. Do not deviate."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step Writing Tips
|
||||
|
||||
- **Default to intent** - give goals, not scripts
|
||||
- **Use "think"** - "Think about their response before..."
|
||||
- **Multi-turn** - "Use conversation, not interrogation"
|
||||
- **Progressive** - "Ask 1-2 questions at a time"
|
||||
- **Probe** - "Ask follow-ups to understand deeper"
|
||||
|
||||
Only use prescriptive when compliance/regulation requires it.
|
||||
@@ -1,167 +0,0 @@
|
||||
# Menu Handling Standards
|
||||
|
||||
**CRITICAL:** Every menu MUST have a handler section. No exceptions.
|
||||
|
||||
---
|
||||
|
||||
## Reserved Letters
|
||||
|
||||
| Letter | Purpose | After Execution |
|
||||
| ------ | -------------------- | ------------------------------ |
|
||||
| **A** | Advanced Elicitation | Redisplay menu |
|
||||
| **P** | Party Mode | Redisplay menu |
|
||||
| **C** | Continue/Accept | Save → update → load next step |
|
||||
| **X** | Exit/Cancel | End workflow |
|
||||
|
||||
**Custom letters** allowed (L/R/F/etc.) but don't conflict with reserved.
|
||||
|
||||
---
|
||||
|
||||
## Required Structure
|
||||
|
||||
### Section 1: Display
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select:** [A] [action] [P] [action] [C] Continue"
|
||||
```
|
||||
|
||||
### Section 2: Handler (MANDATORY)
|
||||
```markdown
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other: help user, then [Redisplay Menu Options](#n-present-menu-options)
|
||||
```
|
||||
|
||||
### Section 3: Execution Rules
|
||||
```markdown
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When To Include A/P
|
||||
|
||||
### DON'T Include A/P:
|
||||
- Step 1 (init) - no content to refine yet
|
||||
- Step 2 if only loading documents
|
||||
- Validation sequences - auto-flow instead
|
||||
- Simple data gathering
|
||||
|
||||
### DO Include A/P:
|
||||
- Collaborative content creation
|
||||
- User might want alternatives
|
||||
- Quality gate before proceeding
|
||||
- Creative exploration valuable
|
||||
|
||||
---
|
||||
|
||||
## Menu Patterns
|
||||
|
||||
### Pattern 1: Standard A/P/C
|
||||
```markdown
|
||||
Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other: help user, then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
```
|
||||
|
||||
### Pattern 2: C Only (No A/P)
|
||||
```markdown
|
||||
Display: "**Select:** [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other: help user, then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
```
|
||||
|
||||
**Use for:** Step 1, document discovery, simple progression
|
||||
|
||||
### Pattern 3: Auto-Proceed (No Menu)
|
||||
```markdown
|
||||
Display: "**Proceeding to [next step]...**"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- After [completion condition], immediately load, read entire file, then execute {nextStepFile}
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- This is an [auto-proceed reason] step with no user choices
|
||||
- Proceed directly to next step after setup
|
||||
```
|
||||
|
||||
**Use for:** Init steps, validation sequences
|
||||
|
||||
### Pattern 4: Branching
|
||||
```markdown
|
||||
Display: "**Select:** [L] Load Existing [N] Create New [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF L: Load existing document, then load, read entire file, then execute {stepForExisting}
|
||||
- IF N: Create new document, then load, read entire file, then execute {stepForNew}
|
||||
- IF C: Save content to {outputFile}, update frontmatter, check {condition}, then load appropriate step
|
||||
- IF Any other: help user, then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- Branching options load different steps based on user choice
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Violations
|
||||
|
||||
### ❌ DON'T:
|
||||
```markdown
|
||||
# Missing Handler Section
|
||||
Display: "**Select:** [C] Continue"
|
||||
[NO HANDLER - CRITICAL ERROR!]
|
||||
|
||||
# A/P in Step 1 (doesn't make sense)
|
||||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
|
||||
|
||||
# Forgetting redisplay
|
||||
- IF A: Execute {advancedElicitationTask}
|
||||
# Should end with: ", and when finished redisplay the menu"
|
||||
|
||||
# Missing halt instruction
|
||||
#### EXECUTION RULES:
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
# MISSING: "ALWAYS halt and wait for user input after presenting menu"
|
||||
```
|
||||
|
||||
### ✅ DO:
|
||||
- Handler section immediately follows Display
|
||||
- "Halt and wait" in EXECUTION RULES
|
||||
- Non-C options specify "redisplay menu"
|
||||
- A/P only when appropriate for step type
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For every menu:
|
||||
- [ ] Display section present
|
||||
- [ ] Handler section immediately follows
|
||||
- [ ] EXECUTION RULES section present
|
||||
- [ ] "Halt and wait" instruction included
|
||||
- [ ] A/P options appropriate for step type
|
||||
- [ ] Non-C options redisplay menu
|
||||
- [ ] C option: save → update → load next
|
||||
- [ ] All file references use variables
|
||||
@@ -1,188 +0,0 @@
|
||||
# Output Format Standards
|
||||
|
||||
**Purpose:** How workflows produce documents and handle step output.
|
||||
|
||||
---
|
||||
|
||||
## Golden Rule
|
||||
|
||||
**Every step MUST output to a document BEFORE loading the next step.**
|
||||
|
||||
Two patterns:
|
||||
1. **Direct-to-Final:** Steps append to final document
|
||||
2. **Plan-then-Build:** Steps append to plan → build step consumes plan
|
||||
|
||||
---
|
||||
|
||||
## Menu C Option Sequence
|
||||
|
||||
When user selects **C (Continue)**:
|
||||
1. **Append/Write** to document (plan or final)
|
||||
2. **Update frontmatter** (append this step to `stepsCompleted`)
|
||||
3. **THEN** load next step
|
||||
|
||||
```markdown
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Patterns
|
||||
|
||||
### Pattern 1: Plan-then-Build
|
||||
|
||||
**Use when:** Design/plan before building/creating
|
||||
|
||||
```
|
||||
Step 1 (init) → Creates plan.md from template
|
||||
Step 2 (gather) → Appends requirements to plan.md
|
||||
Step 3 (design) → Appends design decisions to plan.md
|
||||
Step 4 (review) → Appends review/approval to plan.md
|
||||
Step 5 (build) → READS plan.md, CREATES final artifacts
|
||||
```
|
||||
|
||||
**Plan frontmatter:**
|
||||
```yaml
|
||||
workflowName: [name]
|
||||
creationDate: [date]
|
||||
stepsCompleted: ['step-01-init', 'step-02-gather']
|
||||
status: PLANNING_COMPLETE
|
||||
```
|
||||
|
||||
**Example:** Workflow creation - steps append to plan, build step generates files
|
||||
|
||||
### Pattern 2: Direct-to-Final
|
||||
|
||||
**Use when:** Each step contributes to final deliverable
|
||||
|
||||
```
|
||||
Step 1 (init) → Creates final-doc.md from minimal template
|
||||
Step 2 (section) → Appends Section 1
|
||||
Step 3 (section) → Appends Section 2
|
||||
Step 4 (section) → Appends Section 3
|
||||
Step 5 (polish) → Optimizes entire document
|
||||
```
|
||||
|
||||
**Example:** Meal prep nutrition plan - each step adds a section
|
||||
|
||||
---
|
||||
|
||||
## Four Template Types
|
||||
|
||||
### 1. Free-Form (RECOMMENDED)
|
||||
|
||||
**Characteristics:** Minimal template, progressive append, final polish
|
||||
|
||||
**Template:**
|
||||
```yaml
|
||||
---
|
||||
stepsCompleted: []
|
||||
lastStep: ''
|
||||
date: ''
|
||||
user_name: ''
|
||||
---
|
||||
|
||||
# {{document_title}}
|
||||
|
||||
[Content appended progressively by workflow steps]
|
||||
```
|
||||
|
||||
**Use when:** Most workflows - flexible, collaborative
|
||||
|
||||
### 2. Structured
|
||||
|
||||
**Characteristics:** Single template with placeholders, clear sections
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
# {{title}}
|
||||
|
||||
## {{section_1}}
|
||||
[Content to be filled]
|
||||
|
||||
## {{section_2}}
|
||||
[Content to be filled]
|
||||
```
|
||||
|
||||
**Use when:** Reports, proposals, documentation
|
||||
|
||||
### 3. Semi-Structured
|
||||
|
||||
**Characteristics:** Core required sections + optional additions
|
||||
|
||||
**Use when:** Forms, checklists, meeting minutes
|
||||
|
||||
### 4. Strict
|
||||
|
||||
**Characteristics:** Multiple templates, exact field definitions
|
||||
|
||||
**Use when:** Rarely - compliance, legal, regulated
|
||||
|
||||
---
|
||||
|
||||
## Template Syntax
|
||||
|
||||
```markdown
|
||||
{{variable}} # Handlebars style (preferred)
|
||||
[variable] # Bracket style (also supported)
|
||||
```
|
||||
|
||||
**Keep templates lean** - structure only, not content.
|
||||
|
||||
---
|
||||
|
||||
## Step-to-Output Mapping
|
||||
|
||||
Steps should be in ORDER of document appearance:
|
||||
|
||||
```
|
||||
Step 1: Init (creates doc)
|
||||
Step 2: → ## Section 1
|
||||
Step 3: → ## Section 2
|
||||
Step 4: → ## Section 3
|
||||
Step 5: → ## Section 4
|
||||
Step 6: Polish (optimizes entire doc)
|
||||
```
|
||||
|
||||
**Critical:** Use ## Level 2 headers for main sections - allows document splitting if needed.
|
||||
|
||||
---
|
||||
|
||||
## Final Polish Step
|
||||
|
||||
For free-form workflows, include a polish step that:
|
||||
1. Loads entire document
|
||||
2. Reviews for flow and coherence
|
||||
3. Reduces duplication
|
||||
4. Ensures proper ## Level 2 headers
|
||||
5. Improves transitions
|
||||
6. Keeps general order but optimizes readability
|
||||
|
||||
---
|
||||
|
||||
## Output File Patterns
|
||||
|
||||
```yaml
|
||||
# Single output
|
||||
outputFile: '{output_folder}/document-{project_name}.md'
|
||||
|
||||
# Time-stamped
|
||||
outputFile: '{output_folder}/document-{project_name}-{timestamp}.md'
|
||||
|
||||
# User-specific
|
||||
outputFile: '{output_folder}/document-{user_name}-{project_name}.md'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For workflow output design:
|
||||
- [ ] Output format type selected
|
||||
- [ ] Template created if needed
|
||||
- [ ] Steps ordered to match document structure
|
||||
- [ ] Each step outputs to document (except init/final)
|
||||
- [ ] Level 2 headers for main sections
|
||||
- [ ] Final polish step for free-form workflows
|
||||
- [ ] Frontmatter tracking for continuable workflows
|
||||
- [ ] Templates use consistent placeholder syntax
|
||||
@@ -1,235 +0,0 @@
|
||||
# Step File Rules
|
||||
|
||||
**Purpose:** Quick reference for step file structure and compliance. See linked data files for detailed standards.
|
||||
|
||||
---
|
||||
|
||||
## File Size Limits
|
||||
|
||||
| Metric | Value |
|
||||
| ----------- | -------- |
|
||||
| Recommended | < 200 lines |
|
||||
| Absolute Maximum | 250 lines |
|
||||
|
||||
**If exceeded:** Split into multiple steps or extract content to `/data/` files.
|
||||
|
||||
---
|
||||
|
||||
## Required Step Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: 'step-[N]-[name]'
|
||||
description: '[what this step does]'
|
||||
|
||||
# File References (ONLY variables used in this step!)
|
||||
[file references in {variable} format]
|
||||
---
|
||||
|
||||
# Step [N]: [Name]
|
||||
|
||||
## STEP GOAL:
|
||||
[Single sentence: what this step accomplishes]
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
### Universal Rules:
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
|
||||
### Role Reinforcement:
|
||||
- ✅ You are a [specific role]
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring [expertise], user brings [theirs]
|
||||
- ✅ Together we produce something better
|
||||
|
||||
### Step-Specific Rules:
|
||||
- 🎯 Focus only on [specific task]
|
||||
- 🚫 FORBIDDEN to [prohibited action]
|
||||
- 💬 Approach: [how to engage]
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
- 🎯 [Protocol 1]
|
||||
- 💾 [Protocol 2 - save/update]
|
||||
- 📖 [Protocol 3 - tracking]
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
- Available context: [what's available]
|
||||
- Focus: [what to focus on]
|
||||
- Limits: [boundaries]
|
||||
- Dependencies: [what this depends on]
|
||||
|
||||
## Sequence of Instructions:
|
||||
### 1. [Action]
|
||||
[Instructions]
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
[Menu section - see menu-handling-standards.md]
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
|
||||
### ✅ SUCCESS:
|
||||
[Success criteria]
|
||||
### ❌ SYSTEM FAILURE:
|
||||
[Failure criteria]
|
||||
**Master Rule:** Skipping steps is FORBIDDEN.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules (Quick Reference)
|
||||
|
||||
### Frontmatter
|
||||
- ✅ Only variables USED in the step body
|
||||
- ✅ All file references use `{variable}` format
|
||||
- ✅ Relative paths within workflow folder
|
||||
- See: `frontmatter-standards.md`
|
||||
|
||||
### Menus
|
||||
- ✅ Handler section MUST follow display
|
||||
- ✅ "Halt and wait" in execution rules
|
||||
- ✅ A/P options only when appropriate
|
||||
- ✅ Non-C options redisplay menu
|
||||
- See: `menu-handling-standards.md`
|
||||
|
||||
### Progressive Disclosure
|
||||
- ✅ Only load next step when user selects 'C'
|
||||
- ✅ Read entire step file before execution
|
||||
- ✅ Don't create mental todos from future steps
|
||||
|
||||
### Continuable Workflows
|
||||
- ✅ Append step number to `stepsCompleted`
|
||||
- ✅ Don't hardcode full array
|
||||
- See: `workflow-type-criteria.md`
|
||||
|
||||
---
|
||||
|
||||
## Data Files Reference
|
||||
|
||||
| File | Purpose |
|
||||
| ----------------------- | --------------------------------------------- |
|
||||
| `frontmatter-standards.md` | Variables, paths, frontmatter rules |
|
||||
| `menu-handling-standards.md` | Menu patterns, handler requirements |
|
||||
| `output-format-standards.md` | Document output, template types |
|
||||
| `workflow-type-criteria.md` | Continuable, module, tri-modal decisions |
|
||||
| `step-type-patterns.md` | Templates for init/middle/final/branch steps |
|
||||
| `trimodal-workflow-structure.md` | Create/Edit/Validate folder structure |
|
||||
|
||||
---
|
||||
|
||||
## Step Type Reference
|
||||
|
||||
| Step Type | Template/Reference |
|
||||
| ------------------- | ------------------------------------------- |
|
||||
| Init (non-continuable) | Auto-proceed, no continuation logic |
|
||||
| Init (continuable) | `step-01-init-continuable-template.md` |
|
||||
| Continuation (01b) | `step-1b-template.md` |
|
||||
| Middle (standard) | A/P/C menu, collaborative content |
|
||||
| Middle (simple) | C only menu, no A/P |
|
||||
| Branch/Conditional | Custom menu options, routing to different steps |
|
||||
| Validation sequence | Auto-proceed through checks |
|
||||
| Final | No next step, completion message |
|
||||
|
||||
See: `step-type-patterns.md`
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Variables
|
||||
|
||||
### Standard (Always Available)
|
||||
- `{project-root}`
|
||||
- `{project_name}`
|
||||
- `{output_folder}`
|
||||
- `{user_name}`
|
||||
- `{communication_language}`
|
||||
- `{document_output_language}`
|
||||
|
||||
### Module-Specific (e.g., BMB)
|
||||
- `{bmb_creations_output_folder}`
|
||||
|
||||
### User-Defined
|
||||
- New variables can be defined in steps for future steps
|
||||
|
||||
See: `frontmatter-standards.md`
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For every step file:
|
||||
|
||||
- [ ] File < 200 lines (250 max)
|
||||
- [ ] `name` and `description` in frontmatter
|
||||
- [ ] All frontmatter variables are used
|
||||
- [ ] File references use `{variable}` format
|
||||
- [ ] Relative paths within workflow folder
|
||||
- [ ] Handler section follows menu display
|
||||
- [ ] "Halt and wait" in execution rules
|
||||
- [ ] A/P options appropriate for step type
|
||||
- [ ] C option saves and loads next step
|
||||
- [ ] Non-C options redisplay menu
|
||||
- [ ] StepsCompleted appended (if continuable)
|
||||
- [ ] Success/failure metrics present
|
||||
|
||||
---
|
||||
|
||||
## Quick Menu Reference
|
||||
|
||||
```markdown
|
||||
### N. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select:** [A] [action A] [P] [action P] [C] Continue"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
|
||||
- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
|
||||
- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- After other menu items execution, return to this menu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Violations
|
||||
|
||||
| ❌ Violation | ✅ Fix |
|
||||
| ------------------------------------- | ---------------------------------------------- |
|
||||
| Unused variable in frontmatter | Remove unused variables |
|
||||
| Hardcoded file path | Use `{variable}` format |
|
||||
| A/P menu in step 1 | Remove A/P (inappropriate for init) |
|
||||
| Missing handler section | Add handler after menu display |
|
||||
| No "halt and wait" instruction | Add to EXECUTION RULES |
|
||||
| Hardcoded `stepsCompleted: [1,2,3]` | Append: "update stepsCompleted to add this step" |
|
||||
| File > 250 lines | Split into multiple steps or extract to /data/ |
|
||||
| Absolute path for same-folder ref | Use relative path or `{workflow_path}` |
|
||||
|
||||
---
|
||||
|
||||
## When to Extract to Data Files
|
||||
|
||||
Extract step content to `/data/` when:
|
||||
- Step file exceeds 200 lines
|
||||
- Content is reference material
|
||||
- Content is reused across steps
|
||||
- Content is domain-specific (examples, patterns)
|
||||
|
||||
**Data file types:**
|
||||
- `.md` - Reference documentation
|
||||
- `.csv` - Structured data for lookup
|
||||
- `examples/` - Reference implementations
|
||||
|
||||
---
|
||||
|
||||
## Tri-Modal Workflow Note
|
||||
|
||||
For Create/Edit/Validate workflows:
|
||||
- Each mode has its own `steps-c/`, `steps-e/`, `steps-v/` folder
|
||||
- NO shared step files (`s-*.md`) between modes
|
||||
- All modes share `/data/` folder
|
||||
- This prevents confusion and routing errors
|
||||
|
||||
See: `trimodal-workflow-structure.md`
|
||||
@@ -1,311 +0,0 @@
|
||||
# Step Type Patterns
|
||||
|
||||
**Purpose:** Templates for different step types.
|
||||
|
||||
---
|
||||
|
||||
## Core Step Structure
|
||||
|
||||
All steps share this skeleton:
|
||||
```markdown
|
||||
---
|
||||
name: 'step-[N]-[name]'
|
||||
description: '[what it does]'
|
||||
[file references - relative path and only if used in this steps file]
|
||||
---
|
||||
|
||||
# Step [N]: [Name]
|
||||
|
||||
## STEP GOAL:
|
||||
[Single sentence goal]
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
### Universal Rules:
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read complete step file before action
|
||||
- 🔄 CRITICAL: When loading next with 'C', read entire file
|
||||
- 📋 YOU ARE A FACILITATOR, not content generator
|
||||
|
||||
### Role Reinforcement:
|
||||
- ✅ You are [specific role]
|
||||
- ✅ Collaborative dialogue, not command-response
|
||||
- ✅ You bring [expertise], user brings [theirs]
|
||||
|
||||
### Step-Specific Rules:
|
||||
- 🎯 Focus only on [specific task]
|
||||
- 🚫 FORBIDDEN to [prohibited action]
|
||||
- 💬 Approach: [how to engage]
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
- 🎯 Follow the MANDATORY SEQUENCE exactly
|
||||
- 💾 [Additional protocol]
|
||||
- 📖 [Additional protocol]
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
- Available context: [what's available]
|
||||
- Focus: [what to focus on]
|
||||
- Limits: [boundaries]
|
||||
- Dependencies: [what this depends on]
|
||||
|
||||
## MANDATORY SEQUENCE
|
||||
|
||||
**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
|
||||
|
||||
### 1. [First action]
|
||||
[Instructions]
|
||||
|
||||
### N. Present MENU OPTIONS
|
||||
[Menu section - see menu-handling-standards.md]
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
|
||||
### ✅ SUCCESS: [criteria]
|
||||
### ❌ SYSTEM FAILURE: [criteria]
|
||||
**Master Rule:** Skipping steps is FORBIDDEN.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step Types
|
||||
|
||||
### 1. Init Step (Non-Continuable)
|
||||
|
||||
**Use:** Single-session workflow
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
name: 'step-01-init'
|
||||
description: 'Initialize [workflow]'
|
||||
nextStepFile: './step-02-[name].md'
|
||||
outputFile: '{output_folder}/[output].md'
|
||||
templateFile: '../templates/[template].md'
|
||||
---
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- No continuation detection
|
||||
- Auto-proceeds to step 2
|
||||
- No A/P menu
|
||||
- Creates output from template
|
||||
|
||||
**Menu:** Auto-proceed (no user choice)
|
||||
|
||||
### 2. Init Step (Continuable)
|
||||
|
||||
**Use:** Multi-session workflow
|
||||
|
||||
**Frontmatter:** Add `continueFile` reference
|
||||
```yaml
|
||||
continueFile: './step-01b-continue.md'
|
||||
```
|
||||
|
||||
**Logic:**
|
||||
```markdown
|
||||
## 1. Check for Existing Workflow
|
||||
- Look for {outputFile}
|
||||
- If exists AND has stepsCompleted → STOP, load {continueFile}
|
||||
- If not exists → continue to setup
|
||||
```
|
||||
|
||||
**Reference:** `step-01-init-continuable-template.md`
|
||||
|
||||
### 3. Continuation Step (01b)
|
||||
|
||||
**Use:** Paired with continuable init
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
name: 'step-01b-continue'
|
||||
description: 'Handle workflow continuation'
|
||||
outputFile: '{output_folder}/[output].md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
---
|
||||
```
|
||||
|
||||
**Logic:**
|
||||
1. Read `stepsCompleted` array from output
|
||||
2. Read last completed step file to find nextStep
|
||||
3. Welcome user back
|
||||
4. Route to appropriate step
|
||||
|
||||
**Reference:** `step-1b-template.md`
|
||||
|
||||
### 4. Middle Step (Standard)
|
||||
|
||||
**Use:** Collaborative content generation
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
name: 'step-[N]-[name]'
|
||||
nextStepFile: './step-[N+1]-[name].md'
|
||||
outputFile: '{output_folder}/[output].md'
|
||||
advancedElicitationTask: '{project-root}/.../advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/.../party-mode/workflow.md'
|
||||
---
|
||||
```
|
||||
|
||||
**Menu:** A/P/C pattern
|
||||
|
||||
### 5. Middle Step (Simple)
|
||||
|
||||
**Use:** Data gathering, no refinement needed
|
||||
|
||||
**Menu:** C only (no A/P)
|
||||
|
||||
### 6. Branch Step
|
||||
|
||||
**Use:** User choice determines next path
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
nextStepFile: './step-[default].md'
|
||||
altStepFile: './step-[alternate].md'
|
||||
```
|
||||
|
||||
**Menu:** Custom letters (L/R/etc.) with branching logic
|
||||
|
||||
### 7. Validation Sequence Step
|
||||
|
||||
**Use:** Multiple checks without user interruption
|
||||
|
||||
**Menu:** Auto-proceed to next validation
|
||||
|
||||
**Pattern:**
|
||||
```markdown
|
||||
## 1. Perform validation check
|
||||
[Check logic]
|
||||
|
||||
## 2. Write results to {outputFile}
|
||||
Append findings
|
||||
|
||||
## 3. Proceed to next validation
|
||||
Display: "**Proceeding to next check...**"
|
||||
→ Immediately load {nextValidationStep}
|
||||
```
|
||||
|
||||
### 8. Init Step (With Input Discovery)
|
||||
|
||||
**Use:** Workflow that requires documents from prior workflows or external sources
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
name: 'step-01-init'
|
||||
description: 'Initialize and discover input documents'
|
||||
inputDocuments: []
|
||||
requiredInputCount: 1
|
||||
moduleInputFolder: '{module_output_folder}'
|
||||
inputFilePatterns:
|
||||
- '*-prd.md'
|
||||
- '*-ux.md'
|
||||
---
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Discovers documents from prior workflows
|
||||
- Searches by folder, pattern, or user-provided paths
|
||||
- Validates inputs are complete
|
||||
- User confirms which documents to use
|
||||
- Auto-proceeds when required inputs found
|
||||
|
||||
**Logic:**
|
||||
```markdown
|
||||
## 1. Discover Required Inputs
|
||||
Search {moduleInputFolder} for {inputFilePatterns}
|
||||
Search {project_folder}/docs/ for {inputFilePatterns}
|
||||
|
||||
## 2. Present Findings
|
||||
"Found these documents:
|
||||
[1] prd-my-project.md (3 days ago) ✓
|
||||
[2] ux-research.md (1 week ago)
|
||||
Which would you like to use?"
|
||||
|
||||
## 3. Validate and Load
|
||||
Check workflowType, stepsCompleted, date
|
||||
Load selected documents
|
||||
Add to {inputDocuments} array
|
||||
|
||||
## 4. Auto-Proceed
|
||||
If all required inputs found → proceed to step 2
|
||||
If missing → Error with guidance
|
||||
```
|
||||
|
||||
**Reference:** `input-discovery-standards.md`
|
||||
|
||||
### 9. Final Polish Step
|
||||
|
||||
**Use:** Optimizes document built section-by-section
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
name: 'step-[N]-polish'
|
||||
description: 'Optimize and finalize document'
|
||||
outputFile: '{output_folder}/[document].md'
|
||||
---
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Loads entire document
|
||||
- Reviews for flow and coherence
|
||||
- Reduces duplication
|
||||
- Ensures proper ## Level 2 headers
|
||||
- Improves transitions
|
||||
- Keeps general order but optimizes readability
|
||||
|
||||
**Logic:**
|
||||
```markdown
|
||||
## 1. Load Complete Document
|
||||
Read {outputFile} entirely
|
||||
|
||||
## 2. Document Optimization
|
||||
Review entire document for:
|
||||
1. Flow and coherence
|
||||
2. Duplication (remove while preserving essential info)
|
||||
3. Proper ## Level 2 section headers
|
||||
4. Smooth transitions between sections
|
||||
5. Overall readability
|
||||
|
||||
## 3. Optimize
|
||||
Make improvements while maintaining:
|
||||
- General order of sections
|
||||
- Essential information
|
||||
- User's voice and intent
|
||||
|
||||
## 4. Final Output
|
||||
Save optimized document
|
||||
Mark workflow complete
|
||||
```
|
||||
|
||||
**Use for:** Free-form output workflows (most document-producing workflows)
|
||||
|
||||
### 10. Final Step
|
||||
|
||||
**Use:** Last step, completion
|
||||
|
||||
**Frontmatter:** No `nextStepFile`
|
||||
|
||||
**Logic:**
|
||||
- Update frontmatter to mark workflow complete
|
||||
- Provide final summary
|
||||
- No next step
|
||||
|
||||
---
|
||||
|
||||
## Step Size Guidelines
|
||||
|
||||
| Type | Recommended | Maximum |
|
||||
| --------------------- | ----------- | ------- |
|
||||
| Init | < 100 | 150 |
|
||||
| Init (with discovery) | < 150 | 200 |
|
||||
| Continuation | < 150 | 200 |
|
||||
| Middle (simple) | < 150 | 200 |
|
||||
| Middle (complex) | < 200 | 250 |
|
||||
| Branch | < 150 | 200 |
|
||||
| Validation sequence | < 100 | 150 |
|
||||
| Final polish | < 150 | 200 |
|
||||
| Final | < 150 | 200 |
|
||||
|
||||
**If exceeded:** Split into multiple steps or extract to `/data/` files.
|
||||
@@ -1,386 +0,0 @@
|
||||
# Subprocess Optimization Patterns
|
||||
|
||||
**Purpose:** Context-saving and performance patterns for subprocess/subagent usage in BMAD workflows.
|
||||
|
||||
---
|
||||
|
||||
## Golden Rules
|
||||
|
||||
1. **Subprocess when operations benefit from parallelization or context isolation**
|
||||
2. **Return ONLY findings to parent, not full file contents** (massive context savings)
|
||||
3. **Always provide graceful fallback** for LLMs without subprocess capability
|
||||
4. **Match pattern to operation type** - grep/regex, deep analysis, or data operations
|
||||
|
||||
---
|
||||
|
||||
## The Three Patterns
|
||||
|
||||
### Pattern 1: Single Subprocess for Grep/Regex Across Many Files
|
||||
|
||||
**Use when:** You can run one command across many files and just need matches/failures
|
||||
|
||||
**Context savings:** Massive - returns only matching lines, not full file contents
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
**Launch a subprocess that:**
|
||||
|
||||
1. Runs grep/regex across all target files
|
||||
2. Extracts only matching lines or failures
|
||||
3. Returns structured findings to parent
|
||||
|
||||
```bash
|
||||
# Example: Find hardcoded paths across all files
|
||||
for file in steps-c/*.md; do
|
||||
grep -n "{project-root}/" "$file" || echo "No matches in: $file"
|
||||
done
|
||||
```
|
||||
|
||||
**Subprocess returns to parent:**
|
||||
```json
|
||||
{
|
||||
"violations": [
|
||||
{"file": "step-02.md", "line": 45, "match": "{project-root}/_bmad/bmb/..."}
|
||||
],
|
||||
"summary": {"total_files_checked": 10, "violations_found": 3}
|
||||
}
|
||||
```
|
||||
|
||||
**❌ BAD - Loads all files into parent:**
|
||||
```markdown
|
||||
"For EACH file, load the file and search for {project-root}/"
|
||||
# Parent context gets 10 full files × 200 lines = 2000 lines loaded
|
||||
```
|
||||
|
||||
**✅ GOOD - Single subprocess returns only matches:**
|
||||
```markdown
|
||||
"Launch a subprocess to grep all files for {project-root}/, return only matches"
|
||||
# Parent context gets only matching lines = ~50 lines returned
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Separate Subprocess Per File for Deep Analysis
|
||||
|
||||
**Use when:** You need to read and understand each file's prose, logic, quality, or flow
|
||||
|
||||
**Context savings:** High - each subprocess returns analysis, not full content
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
**DO NOT BE LAZY - For EACH file, launch a subprocess that:**
|
||||
|
||||
1. Loads that file
|
||||
2. Reads and analyzes content deeply (prose, logic, flow, quality)
|
||||
3. Returns structured analysis findings to parent for aggregation
|
||||
|
||||
**Subprocess returns to parent:**
|
||||
```json
|
||||
{
|
||||
"file": "step-03-inquiry.md",
|
||||
"analysis": {
|
||||
"instruction_style": "Intent-based ✅",
|
||||
"collaborative_quality": "Good - asks 1-2 questions at a time",
|
||||
"issues": ["Line 67: Laundry list of 7 questions detected"]
|
||||
},
|
||||
"optimization_opportunities": ["Could use Pattern 1 for menu validation checks"]
|
||||
}
|
||||
```
|
||||
|
||||
**Example use cases:**
|
||||
- Instruction style validation (read prose, classify intent vs prescriptive)
|
||||
- Collaborative quality assessment (analyze question patterns)
|
||||
- Frontmatter compliance (check each variable is used)
|
||||
- Step type validation (verify step follows its type pattern)
|
||||
|
||||
**❌ BAD - Parent loads all files:**
|
||||
```markdown
|
||||
"Load every step file and analyze its instruction style"
|
||||
# Parent context: 10 files × 200 lines = 2000 lines
|
||||
```
|
||||
|
||||
**✅ GOOD - Per-file subprocess returns analysis:**
|
||||
```markdown
|
||||
"DO NOT BE LAZY - For EACH step file, launch a subprocess to analyze instruction style, return findings"
|
||||
# Parent context: 10 structured analysis objects = ~200 lines
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Subprocess for Data File Operations
|
||||
|
||||
**Use when:** Loading reference data, finding fuzzy/best matches, summarizing key findings from large datasets
|
||||
|
||||
**Context savings:** Massive - returns only matching rows or summaries, not entire data file
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
**Launch a subprocess that:**
|
||||
|
||||
1. Loads the data file (reference docs, CSV, knowledge base)
|
||||
2. Performs lookup, matching, or summarization
|
||||
3. Returns ONLY relevant rows or key findings to parent
|
||||
|
||||
**Subprocess returns to parent:**
|
||||
```json
|
||||
{
|
||||
"matches": [
|
||||
{"row": 42, "rule": "Frontmatter variables must be used in body", "applies": true},
|
||||
{"row": 87, "rule": "Relative paths for same-folder refs", "applies": true}
|
||||
],
|
||||
"summary": {"total_rules": 150, "applicable_rules": 2}
|
||||
}
|
||||
```
|
||||
|
||||
**Example use cases:**
|
||||
- **Reference rules lookup**: Load 500-line standards file, return only applicable rules
|
||||
- **CSV fuzzy matching**: Load product database, find best matching category
|
||||
- **Document summarization**: Review 10 documents, extract only key requirements
|
||||
- **Knowledge base search**: Search large knowledge base, return only top matches
|
||||
|
||||
**❌ BAD - Parent loads entire data file:**
|
||||
```markdown
|
||||
"Load {dataFile} with 500 rules and find applicable ones"
|
||||
# Parent context: All 500 rules loaded (5000+ lines)
|
||||
```
|
||||
|
||||
**✅ GOOD - Subprocess returns only matches:**
|
||||
```markdown
|
||||
"Launch subprocess to load {dataFile}, find applicable rules, return only those"
|
||||
# Parent context: Only 2 applicable rules returned (~50 lines)
|
||||
```
|
||||
|
||||
**Advanced example - Document review:**
|
||||
```markdown
|
||||
**Review 10 requirement documents to extract key details:**
|
||||
|
||||
"DO NOT BE LAZY - For EACH document, launch a subprocess that:
|
||||
1. Loads that document
|
||||
2. Extracts key requirements, decisions, constraints
|
||||
3. Returns structured summary to parent
|
||||
|
||||
**Subprocess returns:**
|
||||
```json
|
||||
{
|
||||
"document": "prd-requirements.md",
|
||||
"key_findings": {
|
||||
"requirements": ["User auth", "Data export", "API integration"],
|
||||
"decisions": ["Use JWT", "PostgreSQL", "REST API"],
|
||||
"constraints": ["HIPAA compliant", "Max 100ms response"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# Parent gets summaries, not 10 full documents
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Parallel Execution Opportunities
|
||||
|
||||
**Use when:** Multiple independent operations could run simultaneously
|
||||
|
||||
**Performance gain:** Reduced total execution time via parallelization
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
**Launch subprocesses in parallel that:**
|
||||
|
||||
1. Each subprocess handles one independent operation
|
||||
2. All subprocesses run simultaneously
|
||||
3. Parent aggregates results when all complete
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Instead of sequential (3× time):
|
||||
"Check frontmatter, then check menu, then check step types"
|
||||
|
||||
# Use parallel (1× time):
|
||||
"Launch 3 subprocesses in parallel:
|
||||
- Subprocess 1: Check frontmatter compliance
|
||||
- Subprocess 2: Check menu compliance
|
||||
- Subprocess 3: Check step type compliance
|
||||
Aggregate all findings"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Graceful Fallback Pattern
|
||||
|
||||
**CRITICAL:** Always ensure LLMs without subprocess capability can still execute
|
||||
|
||||
**Universal Rule:**
|
||||
```markdown
|
||||
- ⚙️ If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
### Step-Specific Rules:
|
||||
- 🎯 Use subprocess optimization when available - [pattern description]
|
||||
- 💬 If subprocess unavailable, perform operations in main thread
|
||||
|
||||
### Execution:
|
||||
- LLMs with subprocess: Launch subprocess, aggregate findings
|
||||
- LLMs without subprocess: Perform same operations sequentially in main context
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Return Pattern for Subprocesses
|
||||
|
||||
**Subprocesses must either:**
|
||||
|
||||
**Option A: Update report directly**
|
||||
```markdown
|
||||
"Subprocess loads validation report, appends findings, saves"
|
||||
# Parent doesn't need to aggregate
|
||||
```
|
||||
|
||||
**Option B: Return structured findings to parent**
|
||||
```markdown
|
||||
"Subprocess returns JSON findings to parent for aggregation"
|
||||
# Parent compiles all subprocess results into report
|
||||
```
|
||||
|
||||
**✅ GOOD - Structured return:**
|
||||
```json
|
||||
{
|
||||
"file": "step-02.md",
|
||||
"violations": ["..."],
|
||||
"opportunities": ["..."],
|
||||
"priority": "HIGH"
|
||||
}
|
||||
```
|
||||
|
||||
**❌ BAD - Returns full content:**
|
||||
```markdown
|
||||
"Subprocess loads file and returns full content to parent"
|
||||
# Defeats purpose - parent gets full context anyway
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Pattern
|
||||
|
||||
| Pattern | Use When | Context Savings | Example |
|
||||
| -------- | -------- | --------------- | ------- |
|
||||
| **Pattern 1: Single subprocess for grep/regex** | Finding patterns across many files | Massive (1000:1 ratio) | Validate frontmatter across all steps |
|
||||
| **Pattern 2: Per-file subprocess for deep analysis** | Understanding prose, logic, quality | High (10:1 ratio) | Instruction style validation |
|
||||
| **Pattern 3: Data file operations** | Loading reference data, matching, summarizing | Massive (100:1 ratio) | Find applicable rules from standards |
|
||||
| **Pattern 4: Parallel execution** | Independent operations that can run simultaneously | Performance gain | Frontmatter + Menu + Step type checks |
|
||||
|
||||
---
|
||||
|
||||
## Step File Integration
|
||||
|
||||
**How to add subprocess patterns to step files:**
|
||||
|
||||
### 1. Universal Rule (add to all steps)
|
||||
```markdown
|
||||
### Universal Rules:
|
||||
- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
|
||||
```
|
||||
|
||||
### 2. Step-Specific Rules (pattern-specific)
|
||||
```markdown
|
||||
### Step-Specific Rules:
|
||||
- 🎯 [Brief: which pattern applies]
|
||||
- 💬 Subprocess must either update report OR return findings to parent
|
||||
- 🚫 DO NOT BE LAZY - [specific "do not be lazy" guidance if applicable]
|
||||
```
|
||||
|
||||
### 3. Command Sequence (detailed pattern)
|
||||
```markdown
|
||||
### 1. [Operation Name]
|
||||
|
||||
**[Appropriate subprocess directive]:**
|
||||
|
||||
For [Pattern 1 - grep/regex]:
|
||||
"Launch a subprocess that runs [command] across all files, returns [results]"
|
||||
|
||||
For [Pattern 2 - per-file analysis]:
|
||||
"DO NOT BE LAZY - For EACH file, launch a subprocess that [analyzes], returns [findings]"
|
||||
|
||||
For [Pattern 3 - data ops]:
|
||||
"Launch a subprocess that loads [data file], performs [operation], returns [results]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Subprocess Loading Reference Data (Meta-Pattern!)
|
||||
|
||||
**Context-saving optimization:**
|
||||
|
||||
When a step needs to understand subprocess patterns with examples, load this reference file in a subprocess:
|
||||
|
||||
```markdown
|
||||
### Step-Specific Rules:
|
||||
- 🎯 Analyze subprocess optimization opportunities - use subprocess to load reference patterns for detailed examples
|
||||
- 💬 Subprocess loads {subprocessPatterns} to understand patterns deeply, returns specific opportunities
|
||||
- 🚫 If subprocess unavailable: Load {subprocessPatterns} in main context
|
||||
|
||||
**Execution:**
|
||||
- With subprocess: Launch subprocess to load this file, understand patterns, identify opportunities
|
||||
- Without subprocess: Load this file in main context (larger context but still functional)
|
||||
```
|
||||
|
||||
**This step file (step-08b) demonstrates this pattern!**
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For subprocess optimization in step files:
|
||||
|
||||
- [ ] Universal fallback rule present
|
||||
- [ ] Step-specific rules mention which pattern applies
|
||||
- [ ] Command sequence uses appropriate subprocess directive
|
||||
- [ ] "DO NOT BE LAZY" language included for Pattern 2
|
||||
- [ ] Return pattern specified (update report OR return to parent)
|
||||
- [ ] Graceful fallback addressed
|
||||
- [ ] Context savings estimated (if applicable)
|
||||
- [ ] Pattern matches operation type (grep/regex, deep analysis, or data ops)
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### ❌ Loading full files into parent
|
||||
```markdown
|
||||
"For EACH file, load the file, analyze it, and add to report"
|
||||
# Defeats purpose - parent gets full context
|
||||
```
|
||||
|
||||
### ❌ Subprocess returns raw content
|
||||
```markdown
|
||||
"Subprocess loads file and returns content to parent"
|
||||
# Parent gets full content anyway
|
||||
```
|
||||
|
||||
### ❌ No graceful fallback
|
||||
```markdown
|
||||
"Use subprocess to [operation]"
|
||||
# LLMs without subprocess cannot proceed
|
||||
```
|
||||
|
||||
### ❌ Wrong pattern for operation
|
||||
```markdown
|
||||
"Launch a subprocess per file to grep for pattern"
|
||||
# Should use Pattern 1 (single subprocess for all files)
|
||||
```
|
||||
|
||||
### ❌ Missing return specification
|
||||
```markdown
|
||||
"Launch a subprocess to analyze files"
|
||||
# Unclear what subprocess returns to parent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- `step-file-rules.md` - When to extract content to data files
|
||||
- `step-08b-subprocess-optimization.md` - Validation step that identifies optimization opportunities
|
||||
- `../steps-v/step-02b-path-violations.md` - Example of Pattern 1 (grep across files)
|
||||
- `../steps-v/step-08b-subprocess-optimization.md` - Example of Pattern 2 (per-file analysis)
|
||||
@@ -1,209 +0,0 @@
|
||||
# Tri-Modal Workflow Structure
|
||||
|
||||
**Purpose:** The golden rule standard for complex critical workflows that require create, validate, and edit capabilities.
|
||||
|
||||
---
|
||||
|
||||
## The Golden Rule
|
||||
|
||||
**For complex critical workflows: Implement tri-modal structure (create/validate/edit) with cross-mode integration.**
|
||||
|
||||
This pattern ensures:
|
||||
- Quality through standalone validation
|
||||
- Maintainability through dedicated edit mode
|
||||
- Flexibility through conversion paths for non-compliant input
|
||||
|
||||
**Cross-mode integration patterns:**
|
||||
- Create → Validation (handoff after build)
|
||||
- Edit → Validation (verify changes)
|
||||
- Edit → Create/conversion (for non-compliant input)
|
||||
- Validation → Edit (fix issues found)
|
||||
- All modes run standalone via workflow.md routing
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
workflow-name/
|
||||
├── workflow.md # Entry point with mode routing
|
||||
├── data/ # SHARED standards and reference
|
||||
│ ├── [domain]-standards.md
|
||||
│ └── [domain]-patterns.md
|
||||
├── steps-c/ # Create (self-contained)
|
||||
│ ├── step-00-conversion.md # Entry for non-compliant input
|
||||
│ ├── step-01-init.md
|
||||
│ └── step-N-complete.md
|
||||
├── steps-e/ # Edit (self-contained)
|
||||
│ ├── step-01-assess.md # Checks compliance, routes if needed
|
||||
│ └── step-N-complete.md
|
||||
└── steps-v/ # Validate (self-contained, runs standalone)
|
||||
└── step-01-validate.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode Responsibilities
|
||||
|
||||
### Create Mode (steps-c/)
|
||||
|
||||
**Primary:** Build new entities from scratch
|
||||
**Secondary:** Convert non-compliant input via step-00-conversion
|
||||
|
||||
**Key patterns:**
|
||||
- step-00-conversion: Loads non-compliant input, extracts essence, creates plan with `conversionFrom` metadata
|
||||
- Final step routes to validation (optional but recommended)
|
||||
- Confirmation step checks `conversionFrom` to verify coverage vs new workflow
|
||||
|
||||
### Edit Mode (steps-e/)
|
||||
|
||||
**Primary:** Modify existing compliant entities
|
||||
**Secondary:** Detect non-compliance and route to conversion
|
||||
|
||||
**Key patterns:**
|
||||
- step-01-assess: Checks compliance first
|
||||
- Non-compliant → Offer route to step-00-conversion (not step-01-discovery)
|
||||
- Post-edit → Offer validation (reuse validation workflow)
|
||||
- During edits → Check standards, offer to fix non-compliance
|
||||
|
||||
### Validate Mode (steps-v/)
|
||||
|
||||
**Primary:** Standalone validation against standards
|
||||
**Secondary:** Generates actionable reports
|
||||
|
||||
**Key patterns:**
|
||||
- Runs standalone (invoked via -v flag or direct call)
|
||||
- Auto-proceeds through all checks
|
||||
- Generates report with issue severity
|
||||
- Report consumed by edit mode for fixes
|
||||
|
||||
---
|
||||
|
||||
## workflow.md Routing Pattern
|
||||
|
||||
```yaml
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Mode Determination
|
||||
|
||||
**Check invocation:**
|
||||
- "create" / -c → mode = create
|
||||
- "validate" / -v → mode = validate
|
||||
- "edit" / -e → mode = edit
|
||||
|
||||
**If create mode:** Ask "From scratch or convert existing?"
|
||||
- From scratch → steps-c/step-01-init.md
|
||||
- Convert → steps-c/step-00-conversion.md
|
||||
|
||||
**If unclear:** Ask user to select mode
|
||||
|
||||
### 2. Route to First Step
|
||||
|
||||
**IF mode == create:**
|
||||
Route to appropriate create entry (init or conversion)
|
||||
|
||||
**IF mode == validate:**
|
||||
Prompt for path → load steps-v/step-01-validate.md
|
||||
|
||||
**IF mode == edit:**
|
||||
Prompt for path → load steps-e/step-01-assess.md
|
||||
```
|
||||
|
||||
**Critical:** workflow.md is lean. No step listings. Only routing logic.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Mode Integration Points
|
||||
|
||||
### 1. Edit → Create (Non-Compliant Detection)
|
||||
|
||||
**In edit step-01-assess:**
|
||||
```yaml
|
||||
Check workflow compliance:
|
||||
- Compliant → Continue to edit steps
|
||||
- Non-compliant → Offer conversion
|
||||
- IF user accepts: Load steps-c/step-00-conversion.md with sourceWorkflowPath
|
||||
```
|
||||
|
||||
### 2. Create/Edit → Validation
|
||||
|
||||
**Both create and edit can invoke validation:**
|
||||
```yaml
|
||||
# In create final step or edit post-edit step
|
||||
Offer: "Run validation?"
|
||||
- IF yes: Load ../steps-v/step-01-validate.md
|
||||
- Validation runs standalone, returns report
|
||||
- Resume create/edit with validation results
|
||||
```
|
||||
|
||||
### 3. Validation → Edit
|
||||
|
||||
**After validation generates report:**
|
||||
```yaml
|
||||
# User can invoke edit mode with report as input
|
||||
"Fix issues found?"
|
||||
- IF yes: Load steps-e/step-01-assess.md with validationReport path
|
||||
```
|
||||
|
||||
### 4. Conversion Coverage Tracking
|
||||
|
||||
**In create step-10-confirmation:**
|
||||
```yaml
|
||||
Check workflowPlan metadata:
|
||||
- IF conversionFrom exists:
|
||||
- Load original workflow
|
||||
- Compare each step/instruction
|
||||
- Report coverage percentage
|
||||
- ELSE (new workflow):
|
||||
- Validate all plan requirements implemented
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Tri-Modal
|
||||
|
||||
**Use Tri-Modal for:**
|
||||
- Complex workflows requiring quality assurance
|
||||
- Workflows that will be maintained over time
|
||||
- Workflows where non-compliant input may be offered
|
||||
- Critical workflows where standards compliance matters
|
||||
|
||||
**Use Create-Only for:**
|
||||
- Simple one-off workflows
|
||||
- Experimental workflows
|
||||
- Workflows unlikely to need editing or validation
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Standards for Cross-Mode References
|
||||
|
||||
**Never inline file paths. Always use frontmatter variables:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Create mode step calling validation
|
||||
validationWorkflow: '../steps-v/step-01-validate.md'
|
||||
---
|
||||
|
||||
# Edit mode step routing to conversion
|
||||
conversionStep: '../steps-c/step-00-conversion.md'
|
||||
---
|
||||
|
||||
# Create conversion step receiving from edit
|
||||
sourceWorkflowPath: '{targetWorkflowPath}' # Passed from edit
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For tri-modal workflow design:
|
||||
- [ ] Each mode has self-contained steps folder
|
||||
- [ ] No shared step files (shared data in /data/ only)
|
||||
- [ ] workflow.md has lean routing (no step listings)
|
||||
- [ ] Edit mode checks compliance, routes to conversion if needed
|
||||
- [ ] Create mode has step-00-conversion for non-compliant input
|
||||
- [ ] Create/Edit can invoke validation workflow
|
||||
- [ ] Validation runs standalone and generates reports
|
||||
- [ ] Confirmation step checks `conversionFrom` metadata
|
||||
@@ -1,271 +0,0 @@
|
||||
# Workflow Chaining Standards
|
||||
|
||||
**Purpose:** How workflows connect in sequences within modules, passing outputs as inputs to next workflows.
|
||||
|
||||
---
|
||||
|
||||
## Module Workflow Pipeline
|
||||
|
||||
**Example:** BMM Module - Idea to Implementation
|
||||
|
||||
```
|
||||
brainstorming → research → brief → PRD → UX → architecture → epics → sprint-planning
|
||||
↓
|
||||
implement-story → review → repeat
|
||||
```
|
||||
|
||||
Each workflow:
|
||||
1. Checks for required inputs from prior workflows
|
||||
2. Validates inputs are complete
|
||||
3. Produces output for next workflow
|
||||
4. Recommends next workflow in sequence
|
||||
|
||||
---
|
||||
|
||||
## Input/Output Contract
|
||||
|
||||
### Output Contract (What Each Workflow Produces)
|
||||
|
||||
**Every workflow should:**
|
||||
1. Create output document with predictable filename
|
||||
2. Include `workflowType` in frontmatter for identification
|
||||
3. Mark `stepsCompleted: [all steps]` when complete
|
||||
4. Store in known location (`{module_output_folder}`)
|
||||
|
||||
**Example frontmatter:**
|
||||
```yaml
|
||||
---
|
||||
workflowType: 'prd'
|
||||
stepsCompleted: ['step-01-init', ..., 'step-11-complete']
|
||||
project_name: 'my-project'
|
||||
date: '2025-01-02'
|
||||
nextWorkflow: 'create-ux'
|
||||
previousWorkflow: 'create-brief'
|
||||
---
|
||||
```
|
||||
|
||||
### Input Contract (What Each Workflow Consumes)
|
||||
|
||||
**Every workflow should:**
|
||||
1. Define required inputs in Step 1
|
||||
2. Search in `{module_output_folder}` for prior outputs
|
||||
3. Validate inputs are complete
|
||||
4. Allow user to select from discovered documents
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Input Discovery Pattern
|
||||
|
||||
```markdown
|
||||
## 1. Discover Required Inputs
|
||||
|
||||
### Required Inputs:
|
||||
- {module_output_folder}/prd-{project_name}.md
|
||||
|
||||
### Search:
|
||||
1. Look for prd-{project_name}.md in {module_output_folder}
|
||||
2. If found → validate completeness
|
||||
3. If missing or incomplete → error with guidance
|
||||
|
||||
"Error: This workflow requires a completed PRD.
|
||||
Expected location: {module_output_folder}/prd-{project_name}.md
|
||||
To fix: Run the PRD workflow first, or provide the path to your PRD."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Step: Next Workflow Recommendation
|
||||
|
||||
```markdown
|
||||
## Next Steps
|
||||
|
||||
Based on your completed [workflow], recommended next workflows:
|
||||
|
||||
1. **[next-workflow-name]** - [why it's next]
|
||||
2. **[alternative-workflow]** - [when to use this instead]
|
||||
|
||||
Would you like to:
|
||||
- Run [next-workflow-name] now?
|
||||
- Run a different workflow?
|
||||
- Exit for now?
|
||||
```
|
||||
|
||||
**Update output frontmatter:**
|
||||
```yaml
|
||||
nextWorkflow: 'create-ux'
|
||||
nextWorkflowRecommended: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-Workflow Status Tracking
|
||||
|
||||
**Optional:** Module can maintain `workflow-status.yaml`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
current_workflow: 'create-prd'
|
||||
completed_workflows:
|
||||
- brainstorming
|
||||
- research
|
||||
- brief
|
||||
pending_workflows:
|
||||
- create-ux
|
||||
- create-architecture
|
||||
- create-epics
|
||||
- sprint-planning
|
||||
outputs:
|
||||
brief: '{module_output_folder}/brief-{project_name}.md'
|
||||
prd: '{module_output_folder}/prd-{project_name}.md'
|
||||
---
|
||||
```
|
||||
|
||||
**Workflow checks this file to:**
|
||||
- Validate sequence (don't run UX before PRD)
|
||||
- Find output locations
|
||||
- Track overall progress
|
||||
|
||||
---
|
||||
|
||||
## Branching Workflows
|
||||
|
||||
**Some workflows have multiple valid next steps:**
|
||||
|
||||
```markdown
|
||||
## Next Steps
|
||||
|
||||
Based on your project type:
|
||||
|
||||
**For software projects:**
|
||||
- create-architecture - Technical architecture
|
||||
- create-epics - Break down into epics
|
||||
|
||||
**For data projects:**
|
||||
- data-modeling - Database schema design
|
||||
- etl-pipeline - Data pipeline design
|
||||
|
||||
Which workflow would you like to run next?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required vs Optional Sequences
|
||||
|
||||
### Required Sequence
|
||||
**PRD must come before Architecture:**
|
||||
|
||||
```yaml
|
||||
# In architecture workflow.md
|
||||
## PREREQUISITE:
|
||||
This workflow requires a completed PRD.
|
||||
|
||||
## INITIALIZATION:
|
||||
IF prd-{project_name}.md exists AND is complete:
|
||||
→ Proceed with architecture workflow
|
||||
ELSE:
|
||||
→ Error: "Please complete PRD workflow first"
|
||||
```
|
||||
|
||||
### Optional Sequence
|
||||
**UX research helps Architecture but isn't required:**
|
||||
|
||||
```yaml
|
||||
# In architecture workflow.md
|
||||
## OPTIONAL INPUTS:
|
||||
UX research documents can inform technical decisions.
|
||||
|
||||
IF ux-research-{project_name}.md exists:
|
||||
→ "Found UX research. Include findings in architecture design?"
|
||||
ELSE:
|
||||
→ "No UX research found. Continuing without it."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Filename Conventions for Chaining
|
||||
|
||||
**Standard pattern:** `{workflow-name}-{project-name}.md`
|
||||
|
||||
| Workflow | Output Filename Pattern |
|
||||
|----------| ---------------------- |
|
||||
| brainstorming | `brainstorming-{project_name}.md` |
|
||||
| brief | `brief-{project_name}.md` |
|
||||
| PRD | `prd-{project_name}.md` |
|
||||
| UX | `ux-design-{project_name}.md` |
|
||||
| architecture | `architecture-{project_name}.md` |
|
||||
| epics | `epics-{project_name}.md` |
|
||||
|
||||
**Predictable filenames enable:**
|
||||
- Automatic discovery
|
||||
- Clear dependencies
|
||||
- Easy validation
|
||||
|
||||
---
|
||||
|
||||
## Module-Level Workflow Registry
|
||||
|
||||
**Module can define `workflows.yaml`:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
module: 'bmm'
|
||||
workflows:
|
||||
brainstorming:
|
||||
output: 'brainstorming-{project_name}.md'
|
||||
next: ['research']
|
||||
research:
|
||||
output: 'research-{project_name}.md'
|
||||
next: ['brief']
|
||||
brief:
|
||||
output: 'brief-{project_name}.md'
|
||||
next: ['prd']
|
||||
prd:
|
||||
output: 'prd-{project_name}.md'
|
||||
next: ['create-ux', 'create-architecture']
|
||||
create-ux:
|
||||
output: 'ux-design-{project_name}.md'
|
||||
next: ['create-architecture']
|
||||
create-architecture:
|
||||
output: 'architecture-{project_name}.md'
|
||||
next: ['create-epics']
|
||||
create-epics:
|
||||
output: 'epics-{project_name}.md'
|
||||
next: ['sprint-planning']
|
||||
---
|
||||
```
|
||||
|
||||
**Workflows read this to:**
|
||||
- Know what outputs exist
|
||||
- Know valid next steps
|
||||
- Know output filenames
|
||||
|
||||
---
|
||||
|
||||
## Cross-Module Dependencies
|
||||
|
||||
**Workflows can depend on outputs from other modules:**
|
||||
|
||||
```yaml
|
||||
# In BMGD narrative workflow
|
||||
## INPUT REQUIREMENTS:
|
||||
|
||||
### Required:
|
||||
- {bmm_output_folder}/prd-{project_name}.md
|
||||
- {bmm_output_folder}/architecture-{project_name}.md
|
||||
|
||||
### From BMGD:
|
||||
- {bmgd_output_folder}/gdd-{project_name}.md (Game Design Document)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
For workflow chaining:
|
||||
- [ ] Output filename follows convention
|
||||
- [ ] Frontmatter includes `workflowType`
|
||||
- [ ] `stepsCompleted` marked complete when done
|
||||
- [ ] Required inputs clearly defined
|
||||
- [ ] Input validation with helpful errors
|
||||
- [ ] Next workflow recommendations in final step
|
||||
- [ ] Module registry (if using sequence tracking)
|
||||
@@ -1,276 +0,0 @@
|
||||
# Novel Workflow Examples
|
||||
|
||||
**Purpose:** Illustrative examples of workflows across diverse domains to demonstrate the range of what users can create.
|
||||
|
||||
---
|
||||
|
||||
## Understanding Workflow Structure
|
||||
|
||||
**Each arrow (→) in the "Flow" column represents a potential step file.**
|
||||
|
||||
```
|
||||
Flow: Discovery → Assessment → Strategy → Shopping List → Prep Schedule
|
||||
↓ ↓ ↓ ↓ ↓
|
||||
step-01- step-02- step-03- step-04- step-05-
|
||||
discovery assessment strategy shopping-list prep-schedule
|
||||
```
|
||||
|
||||
**Each step file contains internal structure:**
|
||||
- STEP GOAL
|
||||
- MANDATORY EXECUTION RULES
|
||||
- EXECUTION PROTOCOLS
|
||||
- MANDATORY SEQUENCE (numbered sub-steps)
|
||||
- Menu options
|
||||
- Success/failure metrics
|
||||
|
||||
**Key insight:** A simple workflow might have 3-4 step files. A complex workflow might have 10+. Each step file is a focused, self-contained instruction.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Personalized Meal Plan Generator
|
||||
|
||||
**Domain:** Health & Fitness
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** (each → = step file) | Discovery → Assessment → Strategy → Shopping List → Prep Schedule |
|
||||
| **Step Files** | ~5 files: step-01-discovery, step-02-assessment, step-03-strategy, step-04-shopping, step-05-prep |
|
||||
| **Output** | Direct-to-final document, each step appends a section |
|
||||
| **Intent/Prescriptive** | Intent-based - Facilitates discovery of preferences |
|
||||
| **Planning** | No - builds final meal plan directly |
|
||||
| **Continuable** | Yes - Can be 200+ tokens, users may need multiple sessions |
|
||||
| **Structure** | Linear, 5 steps, no branching |
|
||||
| **Conversation** | Open-ended with progressive questioning (1-2 at a time, probe preferences) |
|
||||
|
||||
**Description:** Helps users create personalized weekly meal plans based on dietary restrictions, health goals, and cooking habits.
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Year-End Tax Organizer
|
||||
|
||||
**Domain:** Finance
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** (each → = step file) | Input Discovery → Document Categorization → Missing Document Alert → Final Summary |
|
||||
| **Step Files** | 4 files: step-01-input-discovery, step-02-categorize, step-03-missing-alerts, step-04-summary |
|
||||
| **Output** | Analysis-only + checklist of missing docs |
|
||||
| **Intent/Prescriptive** | Highly Prescriptive - Tax compliance, exact categories |
|
||||
| **Planning** | N/A |
|
||||
| **Continuable** | No - Simple single-session checklist |
|
||||
| **Structure** | Linear, 4 steps |
|
||||
| **Conversation** | Focused - specific questions, document what user provides |
|
||||
|
||||
**Description:** Organizes financial documents for tax preparation, categorizes income/deductions, alerts to missing documents.
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Employee Termination Checklist
|
||||
|
||||
**Domain:** Legal / HR / Compliance
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** (each → = step file) | Context → Regulatory Check → Document Requirements → Notification Timeline → Final Checklist |
|
||||
| **Step Files** | 5 files: step-01-context, step-02-regulatory, step-03-documents, step-04-timeline, step-05-checklist. Some steps branch internally based on reason/location. |
|
||||
| **Output** | Direct-to-final compliance checklist |
|
||||
| **Intent/Prescriptive** | Highly Prescriptive - Legal compliance, state-specific |
|
||||
| **Planning** | No |
|
||||
| **Continuable** | No - Focused, single-session |
|
||||
| **Structure** | Branching - Different paths within steps based on: reason, location, employee count |
|
||||
| **Conversation** | Focused - specific classification questions, present requirements |
|
||||
|
||||
**Description:** Generates legally-compliant termination checklists that vary by state, termination reason, and employee count.
|
||||
|
||||
---
|
||||
|
||||
## Example 4: Tabletop RPG Campaign Builder
|
||||
|
||||
**Domain:** Entertainment / Games
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** (each → = step file) | Session Concept → NPC Creation → Scene Setup → Key Beats → Generate → [Repeat for next session] |
|
||||
| **Step Files** | 4 core files: step-01-concept, step-02-npc, step-03-scene, step-04-beats, step-05-generate. Same files reused each session. |
|
||||
| **Output** | Per-session document, maintains campaign continuity |
|
||||
| **Intent/Prescriptive** | Intent-based - Creative facilitation |
|
||||
| **Planning** | No - Each session builds directly to playable content |
|
||||
| **Continuable** | Yes - Campaign has many sessions over months |
|
||||
| **Structure** | Repeating loop - Same steps, new content each session |
|
||||
| **Conversation** | Open-ended creative facilitation, "What if..." prompts |
|
||||
|
||||
**Description:** Helps Game Masters create individual RPG session content while tracking campaign continuity across multiple sessions.
|
||||
|
||||
---
|
||||
|
||||
## Example 5: Course Syllabus Creator
|
||||
|
||||
**Domain:** Education
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** | Course Type → Learning Objectives → Module Breakdown → Assessment → [Branch: academic] → Accreditation → [Branch: vocational] → Certification → Final |
|
||||
| **Output** | Direct-to-final syllabus document |
|
||||
| **Intent/Prescriptive** | Balanced - Framework prescriptive, content flexible |
|
||||
| **Planning** | No |
|
||||
| **Continuable** | Yes - Complex syllabus may require multiple sessions |
|
||||
| **Structure** | Branching - Course type determines different sections |
|
||||
| **Conversation** | Mixed - Framework questions (prescriptive) + content discovery (intent) |
|
||||
|
||||
**Description:** Creates course syllabi that adapt based on course type (academic, vocational, self-paced) with appropriate accreditation requirements.
|
||||
|
||||
---
|
||||
|
||||
## Example 6: SOP Writer
|
||||
|
||||
**Domain:** Business Process
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** | Process Selection → Scope Definition → Documentation → Review → [Generate] → "Create another?" → If yes, repeat |
|
||||
| **Output** | Each SOP is independent, stored in `{sop_folder}/` |
|
||||
| **Intent/Prescriptive** | Prescriptive - SOPs must be exact, unambiguous |
|
||||
| **Planning** | No - Each SOP generated directly |
|
||||
| **Continuable** | No - Single SOP per run, but workflow is repeatable |
|
||||
| **Structure** | Repeating - Can create multiple SOPs in one session |
|
||||
| **Conversation** | Focused on process details - "Walk me through step 1" |
|
||||
|
||||
**Description:** Generates Standard Operating Procedure documents for business processes. Can create multiple SOPs in one session, each stored independently.
|
||||
|
||||
---
|
||||
|
||||
## Example 7: Novel Outliner
|
||||
|
||||
**Domain:** Creative Writing
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** | Structure Selection → Character Arcs → Beat Breakdown → Pacing Review → Final Polish |
|
||||
| **Output** | Free-form with Final Polish step to ensure flow and coherence |
|
||||
| **Intent/Prescriptive** | Intent-based - "What does your character want?" |
|
||||
| **Planning** | No - Builds outline directly |
|
||||
| **Continuable** | Yes - Long-form creative work, sessions span weeks |
|
||||
| **Structure** | Branching - Different flows based on structure choice |
|
||||
| **Conversation** | Open-ended creative coaching, provocations |
|
||||
|
||||
**Description:** Helps authors create novel outlines with proper story structure (3-Act, Hero's Journey, etc.), character arcs, and beat sheets.
|
||||
|
||||
---
|
||||
|
||||
## Example 8: Wedding Itinerary Coordinator
|
||||
|
||||
**Domain:** Event Planning
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** | Venue Type → Vendor Coordination → Timeline → Guest Experience → [Branch: hybrid] → Virtual Setup → Day-of Schedule |
|
||||
| **Output** | Direct-to-final itinerary |
|
||||
| **Intent/Prescriptive** | Intent-based - Facilitates couple's vision |
|
||||
| **Planning** | No |
|
||||
| **Continuable** | Yes - Wedding planning takes months |
|
||||
| **Structure** | Branching - Venue type affects required sections |
|
||||
| **Conversation** | Open-ended discovery of preferences, budget, constraints |
|
||||
|
||||
**Description:** Creates detailed wedding day itineraries, adapting to venue type (indoor/outdoor/hybrid) and guest experience goals.
|
||||
|
||||
---
|
||||
|
||||
## Example 9: Annual Life Review
|
||||
|
||||
**Domain:** Personal Development
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** | Input Discovery (last year's goals) → Life Areas Assessment → Reflections → Goal Setting → Action Planning → Final Polish |
|
||||
| **Output** | Free-form with Final Polish, discovers prior review first |
|
||||
| **Intent/Prescriptive** | Intent-based - Coaching questions |
|
||||
| **Planning** | No - Direct to life plan document |
|
||||
| **Continuable** | Yes - Deep reflection may need multiple sessions |
|
||||
| **Structure** | Linear with Input Discovery at start |
|
||||
| **Conversation** | Open-ended coaching, progressive questioning |
|
||||
|
||||
**Description:** Annual review workflow that discovers prior year's goals, facilitates reflection across life areas, and sets intentional goals for coming year.
|
||||
|
||||
---
|
||||
|
||||
## Example 10: Room Renovation Planner
|
||||
|
||||
**Domain:** Home Improvement
|
||||
|
||||
| Aspect | Details |
|
||||
|--------|---------|
|
||||
| **Flow** | Room Type → Budget Assessment → Phase Planning → Materials → Contractor Timeline → [Branch: DIY] → Instructions |
|
||||
| **Output** | Direct-to-final renovation plan |
|
||||
| **Intent/Prescriptive** | Balanced - Code compliance prescriptive, design intent-based |
|
||||
| **Planning** | No |
|
||||
| **Continuable** | Yes - Complex planning, multi-session |
|
||||
| **Structure** | Branching - Room type and DIY vs pro affect content |
|
||||
| **Conversation** | Mixed - "What's your budget?" + "Describe your vision" |
|
||||
|
||||
**Description:** Creates room-specific renovation plans with material selection, contractor coordination, and optional DIY instructions.
|
||||
|
||||
---
|
||||
|
||||
## Pattern Analysis
|
||||
|
||||
### Structure Types
|
||||
|
||||
| Type | Count | Examples |
|
||||
|------|-------|----------|
|
||||
| Linear | 5 | Meal Plan, Tax, Termination, Life Review, Renovation |
|
||||
| Branching | 5 | Termination, Syllabus, Novel, Wedding, Renovation |
|
||||
| Repeating Loop | 2 | RPG Campaign, SOP Writer |
|
||||
|
||||
### Intent Spectrum
|
||||
|
||||
| Type | Count | Examples |
|
||||
|------|-------|----------|
|
||||
| Intent-based | 7 | Meal Plan, RPG Campaign, Syllabus (partial), Novel, Wedding, Life Review, Renovation (partial) |
|
||||
| Prescriptive | 1 | Tax, Termination, SOP |
|
||||
| Balanced | 2 | Syllabus, Renovation |
|
||||
|
||||
### Continuable vs Single-Session
|
||||
|
||||
| Type | Count | Examples |
|
||||
|------|-------|----------|
|
||||
| Continuable | 7 | Meal Plan, RPG Campaign, Syllabus, Novel, Wedding, Life Review, Renovation |
|
||||
| Single-Session | 3 | Tax, Termination, SOP (repeatable but single-output) |
|
||||
|
||||
### Output Patterns
|
||||
|
||||
| Type | Count | Examples |
|
||||
|------|-------|----------|
|
||||
| Direct-to-Final | 9 | All except Tax |
|
||||
| Analysis Only | 1 | Tax |
|
||||
| With Final Polish | 1 | Novel |
|
||||
| Input Discovery | 1 | Life Review |
|
||||
| Repeating Output | 2 | RPG Campaign (sessions), SOP Writer (multiple SOPs) |
|
||||
|
||||
---
|
||||
|
||||
## Key Insights
|
||||
|
||||
1. **Continuable workflows are the norm** - 7 of 10 examples are continuable
|
||||
2. **Intent-based dominates** - 7 of 10 are primarily intent-based facilitation
|
||||
3. **Branching is common** - 5 of 10 have conditional paths based on user choices
|
||||
4. **Input discovery matters** - Workflows in sequences (like BMM pipeline) need to find prior documents
|
||||
5. **Final polish is critical** - Complex documents built section-by-section need optimization step
|
||||
6. **Repeating loops exist** - Some workflows generate multiple outputs per session or repeat across sessions
|
||||
7. **Mixed conversation styles** - Most use focused questions for data, open-ended for creative
|
||||
|
||||
---
|
||||
|
||||
## Workflow Design Questions
|
||||
|
||||
When creating a new workflow, ask:
|
||||
|
||||
1. **Domain:** What problem space does this operate in?
|
||||
2. **Output:** What does this workflow produce? (Document, checklist, analysis, physical output?)
|
||||
3. **Intent:** Is this prescriptive (compliance) or intent-based (creative)?
|
||||
4. **Planning:** Plan-then-build or direct-to-final?
|
||||
5. **Continuable:** Could this take multiple sessions or consume many tokens?
|
||||
6. **Structure:** Linear, branching, or repeating loop?
|
||||
7. **Inputs:** Does this require documents from prior workflows or external sources?
|
||||
8. **Chaining:** Is this part of a module sequence? What comes before/after?
|
||||
9. **Polish:** Does the final output need optimization for flow and coherence?
|
||||
10. **Conversation:** Focused questions or open-ended facilitation?
|
||||
@@ -1,172 +0,0 @@
|
||||
# Workflow Type Criteria
|
||||
|
||||
**Purpose:** Key decisions when designing a workflow.
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions
|
||||
|
||||
1. **Module affiliation** - Standalone or part of a module?
|
||||
2. **Continuable** - Can it span multiple sessions?
|
||||
3. **Edit/Validate support** - Will it have edit and validate flows?
|
||||
4. **Document output** - Does it produce a document?
|
||||
|
||||
---
|
||||
|
||||
## 1. Module Affiliation
|
||||
|
||||
### Standalone Workflow
|
||||
- NOT part of any module
|
||||
- Stored in user's custom location
|
||||
- Only standard variables available
|
||||
|
||||
### Module-Based Workflow
|
||||
- Part of a specific module (e.g., BMB)
|
||||
- Has access to module-specific variables
|
||||
- Stored in module's workflows directory
|
||||
|
||||
**BMB additional variable:** `{bmb_creations_output_folder}`
|
||||
|
||||
---
|
||||
|
||||
## 2. Continuable or Single-Session?
|
||||
|
||||
### Continuable (Multi-Session)
|
||||
**Use when:** Workflow might consume MASSIVE tokens, complex, many steps
|
||||
|
||||
**Required:**
|
||||
- `step-01-init.md` with continuation detection
|
||||
- `step-01b-continue.md` for resuming
|
||||
- `stepsCompleted` tracking in output frontmatter
|
||||
|
||||
**Frontmatter:**
|
||||
```yaml
|
||||
stepsCompleted: ['step-01-init', 'step-02-gather']
|
||||
lastStep: 'step-02-gather'
|
||||
lastContinued: '2025-01-02'
|
||||
```
|
||||
|
||||
**Rule:** Each step appends its NAME to `stepsCompleted`
|
||||
|
||||
### Single-Session
|
||||
**Use when:** Simple, quick (<15 min), token-efficient
|
||||
|
||||
**Required:**
|
||||
- Standard `step-01-init.md` (no continuation logic)
|
||||
- No `stepsCompleted` tracking needed
|
||||
|
||||
---
|
||||
|
||||
## 3. Edit/Validate Support
|
||||
|
||||
### Create-Only
|
||||
```
|
||||
workflow-folder/
|
||||
├── workflow.md
|
||||
├── data/
|
||||
└── steps-c/
|
||||
├── step-01-init.md
|
||||
└── step-N-final.md
|
||||
```
|
||||
|
||||
**Use when:** Simple workflows, experimental, one-off
|
||||
|
||||
### Create + Edit + Validate (Tri-Modal)
|
||||
```
|
||||
workflow-folder/
|
||||
├── workflow.md
|
||||
├── data/ # SHARED
|
||||
├── steps-c/ # Create
|
||||
├── steps-e/ # Edit
|
||||
└── steps-v/ # Validate
|
||||
```
|
||||
|
||||
**Key:**
|
||||
- Each mode is SELF-CONTAINED
|
||||
- NO shared step files between modes
|
||||
- DATA folder is SHARED (prevents drift)
|
||||
- Duplicative steps OK (better than confusion)
|
||||
|
||||
**Use when:** Complex workflows that will be maintained
|
||||
|
||||
---
|
||||
|
||||
## 4. Document Output
|
||||
|
||||
### Document-Producing
|
||||
- Creates persistent output file
|
||||
- Uses templates for structure
|
||||
- Each step contributes to document
|
||||
- Consider final polish step
|
||||
|
||||
### Non-Document
|
||||
- Performs actions without persistent output
|
||||
- May produce temporary files
|
||||
- Focus on execution, not creation
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
START: Creating a workflow
|
||||
│
|
||||
├─ Part of a module?
|
||||
│ ├─ YES → Module-based (include module variables)
|
||||
│ └─ NO → Standalone (standard variables only)
|
||||
│
|
||||
├─ Could this take multiple sessions / lots of tokens?
|
||||
│ ├─ YES → Continuable (add step-01b-continue.md)
|
||||
│ └─ NO → Single-session (simpler init)
|
||||
│
|
||||
└─ Will users need to edit/validate this workflow?
|
||||
├─ YES → Tri-modal (steps-c/, steps-e/, steps-v/)
|
||||
└─ NO → Create-only (steps-c/ only)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask User
|
||||
|
||||
**Module:**
|
||||
"Is this workflow standalone or part of a specific module (BMB, BMM, CIS, BMGD)?"
|
||||
|
||||
**Continuable:**
|
||||
"Could this workflow consume many tokens or require multiple sessions?
|
||||
- If YES: Add continuation support
|
||||
- If NO: Keep it simple for single-session"
|
||||
|
||||
**Edit/Validate:**
|
||||
"Will this workflow need edit and validate capabilities, or just create?
|
||||
- Create only: Simpler, faster
|
||||
- Create + Edit + Validate: More robust, maintainable"
|
||||
|
||||
**Document:**
|
||||
"Does this workflow produce a document/output file?"
|
||||
- If YES: Use free-form template (recommended)
|
||||
- If NO: What does it produce?
|
||||
|
||||
---
|
||||
|
||||
## Output Format Decision
|
||||
|
||||
| Workflow Type | Init Template | Output Format |
|
||||
| ----------------------- | ------------------------ | ------------- |
|
||||
| Continuable + Document | step-01-init-continuable | Free-form |
|
||||
| Single-Session + Document| Standard init | Free-form |
|
||||
| Continuable + No Doc | step-01-init-continuable | N/A |
|
||||
| Single-Session + No Doc | Standard init | N/A |
|
||||
|
||||
**Free-form template** (recommended):
|
||||
```yaml
|
||||
---
|
||||
stepsCompleted: []
|
||||
lastStep: ''
|
||||
date: ''
|
||||
user_name: ''
|
||||
---
|
||||
|
||||
# {{document_title}}
|
||||
|
||||
[Content appended progressively]
|
||||
```
|
||||
Reference in New Issue
Block a user