create-byan-agent 2.1.1 → 2.2.2

package/install/templates/_byan/bmb/workflows/workflow/data/trimodal-workflow-structure.md

@@ -0,0 +1,209 @@
+# 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

package/install/templates/_byan/bmb/workflows/workflow/data/workflow-chaining-standards.md

@@ -0,0 +1,271 @@
+# 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)