diff --git a/src/core/messenger/messenger-config.yaml b/src/core/messenger/messenger-config.yaml new file mode 100644 index 00000000..3ed11ee0 --- /dev/null +++ b/src/core/messenger/messenger-config.yaml @@ -0,0 +1,162 @@ +# Inter-Agent Messenger Configuration +# Enables formal handoff protocols between agents + +name: inter-agent-messenger +version: "1.0.0" +description: "Formal handoff and communication protocols between BMAD agents" + +# Message queue location +queue_dir: "{project-root}/_bmad-output/messenger" +queue_file: "{queue_dir}/message-queue.yaml" +archive_dir: "{queue_dir}/archive" + +# Message types +message_types: + handoff: + description: "Transfer work from one agent to another" + required_fields: + - from_agent + - to_agent + - artifact_path + - context_summary + - next_actions + priority: high + + review: + description: "Request review of completed work" + required_fields: + - from_agent + - to_agent + - artifact_path + - review_type + priority: medium + + clarify: + description: "Request clarification on requirements or decisions" + required_fields: + - from_agent + - to_agent + - question + - context + priority: high + + escalate: + description: "Escalate issue to user attention" + required_fields: + - from_agent + - issue + - severity + - recommendation + priority: critical + + notify: + description: "Inform other agents of status or decisions" + required_fields: + - from_agent + - to_agents # Can be list or "all" + - message + priority: low + + collaborate: + description: "Request collaborative input from multiple agents" + required_fields: + - from_agent + - to_agents + - topic + - deadline + priority: medium + +# Standard routing rules +routing: + # Phase 1 → Phase 2 handoffs + analyst_to_pm: + trigger: "Product brief complete" + from: analyst + to: pm + payload: + - product_brief_path + - key_insights + - recommended_priorities + + pm_to_architect: + trigger: "PRD complete" + from: pm + to: architect + payload: + - prd_path + - priority_features + - technical_constraints + - timeline_expectations + + pm_to_ux: + trigger: "PRD complete with UI" + from: pm + to: ux-designer + payload: + - prd_path + - user_personas + - key_user_flows + + # Phase 2 → Phase 3 handoffs + architect_to_sm: + trigger: "Architecture approved" + from: architect + to: sm + payload: + - architecture_path + - tech_decisions + - component_boundaries + - api_contracts + + ux_to_sm: + trigger: "UX design complete" + from: ux-designer + to: sm + payload: + - ux_design_path + - component_library + - interaction_patterns + + # Phase 3 → Phase 4 handoffs + sm_to_dev: + trigger: "Story ready for dev" + from: sm + to: dev + payload: + - story_path + - acceptance_criteria + - technical_notes + - dependencies + + dev_to_tea: + trigger: "Implementation complete" + from: dev + to: tea + payload: + - story_path + - files_changed + - test_coverage + - review_request + + # Review flows + tea_to_dev: + trigger: "Review complete with issues" + from: tea + to: dev + payload: + - review_findings + - severity_breakdown + - required_actions + +# Priority levels +priorities: + critical: 1 + high: 2 + medium: 3 + low: 4 + +# Message retention +retention: + active_messages_max: 100 + archive_after_days: 7 + delete_archived_after_days: 30 diff --git a/src/core/messenger/messenger.md b/src/core/messenger/messenger.md new file mode 100644 index 00000000..a31ff3e5 --- /dev/null +++ b/src/core/messenger/messenger.md @@ -0,0 +1,212 @@ +# Inter-Agent Messenger System + +## Overview + +The Inter-Agent Messenger enables formal handoff protocols between BMAD agents. It provides structured communication for work transitions, review requests, clarifications, and escalations. + +## Architecture + +``` +┌─────────────┐ ┌─────────────────┐ ┌─────────────┐ +│ Agent A │───▶│ Message Queue │───▶│ Agent B │ +│ (sender) │ │ (YAML file) │ │ (receiver) │ +└─────────────┘ └─────────────────┘ └─────────────┘ + │ + ▼ + ┌─────────────┐ + │ Archive │ + └─────────────┘ +``` + +## Message Types + +### handoff +Transfer work from one agent to another with full context. + +**Example:** +```yaml +type: handoff +from: pm +to: architect +payload: + artifact_path: "_bmad-output/planning-artifacts/prd.md" + context_summary: "PRD complete for user auth feature" + next_actions: + - Review technical requirements + - Identify infrastructure needs + - Propose architecture patterns +``` + +### review +Request review of completed work. + +**Example:** +```yaml +type: review +from: dev +to: tea +payload: + artifact_path: "_bmad-output/implementation-artifacts/stories/1-2-user-login.md" + review_type: "code-review" + files_changed: + - src/auth/login.ts + - src/auth/login.test.ts +``` + +### clarify +Request clarification on requirements or decisions. + +**Example:** +```yaml +type: clarify +from: dev +to: architect +payload: + question: "Should authentication use JWT or session cookies?" + context: "Story 1-2 requires user login but auth method not specified in architecture" +``` + +### escalate +Escalate issue to user attention (critical). + +**Example:** +```yaml +type: escalate +from: dev +to: user +payload: + issue: "Blocking dependency conflict between React 18 and legacy charting library" + severity: "blocker" + recommendation: "Either upgrade charting library or downgrade to React 17" + impact: "Cannot proceed with Epic 2 until resolved" +``` + +### notify +Inform agents of status or decisions. + +**Example:** +```yaml +type: notify +from: architect +to_agents: all +payload: + message: "Architecture decision: Using PostgreSQL with Prisma ORM" + decision_doc: "_bmad-output/planning-artifacts/architecture.md#database" +``` + +### collaborate +Request collaborative input from multiple agents. + +**Example:** +```yaml +type: collaborate +from: pm +to_agents: + - architect + - ux-designer + - tea +payload: + topic: "Feature complexity assessment for real-time collaboration" + deadline: "2025-01-16T17:00:00Z" + context: "Client requesting WebSocket-based real-time editing" +``` + +## Standard Handoff Routes + +### Phase 1 → Phase 2 + +| From | To | Trigger | Payload | +|------|-----|---------|---------| +| analyst | pm | Product brief complete | brief_path, key_insights | +| pm | architect | PRD complete | prd_path, priority_features | +| pm | ux-designer | PRD with UI complete | prd_path, user_personas | + +### Phase 2 → Phase 3 + +| From | To | Trigger | Payload | +|------|-----|---------|---------| +| architect | sm | Architecture approved | architecture_path, tech_decisions | +| ux-designer | sm | UX design complete | ux_path, component_library | + +### Phase 3 → Phase 4 + +| From | To | Trigger | Payload | +|------|-----|---------|---------| +| sm | dev | Story ready | story_path, acceptance_criteria | +| dev | tea | Implementation complete | story_path, files_changed | +| tea | dev | Review with issues | review_findings, required_actions | + +## Priority Levels + +| Priority | Value | Use Case | +|----------|-------|----------| +| critical | 1 | Blockers, escalations | +| high | 2 | Handoffs, clarifications | +| medium | 3 | Reviews, collaborations | +| low | 4 | Notifications | + +## Usage + +### Sending a Message + +```xml + + handoff + pm + architect + + artifact_path: "_bmad-output/planning-artifacts/prd.md" + context_summary: "PRD complete, ready for architecture" + next_actions: + - Review technical requirements + - Design system architecture + + +``` + +### Receiving Messages + +```xml + + architect + handoff + +``` + +## Queue File Structure + +```yaml +# _bmad-output/messenger/message-queue.yaml +messages: + - message_id: "MSG-20250115-a1b2" + type: "handoff" + from: "pm" + to: "architect" + priority: "high" + created: "2025-01-15T10:30:00Z" + status: "pending" + payload: + artifact_path: "_bmad-output/planning-artifacts/prd.md" + context_summary: "PRD complete" + next_actions: + - Review requirements + - Design architecture + + - message_id: "MSG-20250115-c3d4" + type: "notify" + from: "architect" + to_agents: "all" + priority: "low" + created: "2025-01-15T11:00:00Z" + status: "read" + payload: + message: "Using PostgreSQL with Prisma" +``` + +## Best Practices + +1. **Always include context** - Don't assume receiving agent knows the background +2. **Use appropriate priority** - Reserve critical for true blockers +3. **Include artifact paths** - Reference documents, not content +4. **Specify next actions** - Clear handoff means faster pickup +5. **Check messages at workflow start** - Agents should check queue before beginning work diff --git a/src/core/messenger/receive-message.xml b/src/core/messenger/receive-message.xml new file mode 100644 index 00000000..0dc5373e --- /dev/null +++ b/src/core/messenger/receive-message.xml @@ -0,0 +1,68 @@ + + + Receive and process messages from the messenger queue + + + {project-root}/_bmad/core/messenger/messenger-config.yaml + {project-root}/_bmad-output/messenger/message-queue.yaml + {project-root}/_bmad-output/messenger/archive + + + + + + + + + + + Load queue from {queue_file} + Return: "No messages in queue" + + + + Filter messages where: + - to == {agent} OR + - to_agents contains {agent} OR + - to_agents == "all" + + Filter by status == "pending" + Filter by type == {type_filter} + Sort by priority (critical first), then by created (oldest first) + + + + Return: "No pending messages for {agent}" + For each message: + - Display message summary + - If mark_read == true, update status to "read" + + + + + Save updated queue to {queue_file} + + + + Return list of messages with full payloads + + Messages for {agent}: {count} + + {for each message} + --- + [{priority}] {type} from {from_agent} + ID: {message_id} + Received: {created} + + {payload_summary} + --- + {end for} + + + + + + + + + diff --git a/src/core/messenger/send-message.xml b/src/core/messenger/send-message.xml new file mode 100644 index 00000000..18b58d37 --- /dev/null +++ b/src/core/messenger/send-message.xml @@ -0,0 +1,72 @@ + + + Send a message between BMAD agents using the messenger system + + + {project-root}/_bmad/core/messenger/messenger-config.yaml + {project-root}/_bmad-output/messenger/message-queue.yaml + + + + + + + + + + + + + + Load messenger config from {config_source} + Validate type is one of: handoff, review, clarify, escalate, notify, collaborate + Check required_fields for message type are present in payload + HALT with validation error message + + + + Generate unique message_id: "MSG-{timestamp}-{random4}" + Build message object: + ```yaml + message_id: "{message_id}" + type: "{type}" + from: "{from_agent}" + to: "{to_agent}" or "{to_agents}" + priority: "{priority}" + created: "{timestamp}" + status: "pending" + payload: {payload} + ``` + + + + + Check if {queue_dir} exists + Create directory {queue_dir} + + + + Load existing queue from {queue_file} (or create empty if not exists) + Append new message to messages array + Sort messages by priority (critical first) + Save updated queue to {queue_file} + + + + Return message_id and status + + Message sent successfully. + ID: {message_id} + Type: {type} + From: {from_agent} + To: {to_agent} + Priority: {priority} + + + + + + + + + diff --git a/src/core/pipeline/orchestrator.xml b/src/core/pipeline/orchestrator.xml new file mode 100644 index 00000000..32a2780b --- /dev/null +++ b/src/core/pipeline/orchestrator.xml @@ -0,0 +1,194 @@ + + + Orchestrate multi-stage agent pipelines with dependency management + + + {project-root}/_bmad/core/pipeline/pipeline-config.yaml + {project-root}/_bmad-output/pipelines + + + + + + + + + + + + + + + Ask user for pipeline source: + 1. Use template (show available templates) + 2. Define custom pipeline + + + + List templates from config: full_sdlc, quick_flow, analysis_only, design_review, test_suite + User selects template + Copy template stages to new pipeline definition + + + + Ask for pipeline name + Ask for stages (agent, parallel, depends_on, outputs) + Build pipeline definition + + + Generate pipeline_id: "PIPE-{YYYYMMDD}-{name}" + Create pipeline file: {pipeline_dir}/{pipeline_id}.yaml + Initialize all stages as "pending" + + + Pipeline created: {pipeline_id} + Stages: {stage_count} + Estimated duration: {estimate} + + Run with: PIPELINE run {pipeline_id} + + + + + + Load pipeline from {pipeline_id}.yaml + Validate pipeline definition (agents exist, dependencies valid) + Set pipeline status to "running" + Initialize execution state tracking + + + Find stages where: + - Status == "pending" AND + - All depends_on stages are "completed" + + Mark found stages as "queued" + + + + + Launch agents in parallel using Task tool with run_in_background=true + Track agent_ids for each stage + + + + Launch agent using Task tool with run_in_background=false + Wait for completion + + + + + For parallel stages: Use TaskOutput to collect results + Update stage status based on result (completed/failed) + Store outputs in {pipeline_dir}/outputs/{stage_name}/ + + + + Mark pipeline as "failed" + Mark dependent stages as "skipped" + HALT: "Pipeline failed at stage: {stage_name}" + + + + Mark dependent stages as "skipped" + Continue with non-dependent stages + + + Update pipeline file with current state + + + Mark pipeline as "completed" + + Pipeline completed: {pipeline_id} + + Results: + {for each stage} + - {stage_name}: {status} ({duration}) + {end for} + + Outputs saved to: {pipeline_dir}/outputs/ + + + + + + Load pipeline from {pipeline_id}.yaml (or active-pipeline.yaml) + Calculate progress percentage + + + Pipeline: {pipeline_id} + Status: {overall_status} + Progress: [{progress_bar}] {percentage}% + + Stages: + {for each stage} + [{status_icon}] {stage_name} + Agents: {agents} + Duration: {duration or "pending"} + Output: {output_path or "n/a"} + {end for} + + {if running} + Currently executing: {current_stage} + Estimated remaining: {remaining_estimate} + {end if} + + + + + + Scan {pipeline_dir} for pipeline files + Load templates from config + + + Available Templates: + {for each template} + - {template_name}: {description} + Stages: {stage_names} + {end for} + + Existing Pipelines: + {for each pipeline} + - {pipeline_id}: {status} ({created_date}) + {end for} + + + + + + Load running pipeline + Send abort signal to running agents + Mark running stages as "aborted" + Mark pipeline as "aborted" + + + Pipeline {pipeline_id} aborted. + Completed stages: {completed_count} + Aborted stages: {aborted_count} + + + + + + Load failed/aborted pipeline + Identify failed/aborted stages + Ask user: Retry failed stages or skip? + + + Reset failed stages to "pending" + Continue with run logic + + + + Mark failed stages as "skipped" + Continue with remaining stages + + + + + + + + + + + diff --git a/src/core/pipeline/pipeline-config.yaml b/src/core/pipeline/pipeline-config.yaml new file mode 100644 index 00000000..bcf7a9a5 --- /dev/null +++ b/src/core/pipeline/pipeline-config.yaml @@ -0,0 +1,157 @@ +# Pipeline Orchestrator Configuration +# Enables multi-agent pipelines with parallel and sequential execution + +name: pipeline-orchestrator +version: "1.0.0" +description: "Orchestrate multi-stage agent pipelines with dependency management" + +# Pipeline storage +pipeline_dir: "{project-root}/_bmad-output/pipelines" +active_pipeline_file: "{pipeline_dir}/active-pipeline.yaml" +pipeline_archive_dir: "{pipeline_dir}/archive" + +# Execution modes +execution_modes: + sequential: + description: "Execute stages one after another" + use_when: "Each stage depends on previous output" + parallel: + description: "Execute independent stages simultaneously" + use_when: "Stages have no dependencies on each other" + hybrid: + description: "Mix of parallel and sequential based on dependencies" + use_when: "Complex pipelines with partial dependencies" + +# Pipeline templates +templates: + full_sdlc: + name: "Full SDLC Pipeline" + description: "Complete software development lifecycle" + stages: + - name: analysis + agents: [analyst] + parallel: false + outputs: [product_brief] + - name: requirements + agents: [pm] + parallel: false + depends_on: [analysis] + outputs: [prd] + - name: design + agents: [architect, ux-designer] + parallel: true + depends_on: [requirements] + outputs: [architecture, ux_design] + - name: planning + agents: [sm] + parallel: false + depends_on: [design] + outputs: [epics_and_stories] + - name: implementation + agents: [dev] + parallel: false + depends_on: [planning] + outputs: [code, tests] + - name: review + agents: [tea] + parallel: false + depends_on: [implementation] + outputs: [review_report] + + quick_flow: + name: "Quick Flow Pipeline" + description: "Rapid development with minimal ceremony" + stages: + - name: spec + agents: [quick-flow-solo-dev] + parallel: false + outputs: [tech_spec] + - name: implement + agents: [quick-flow-solo-dev] + parallel: false + depends_on: [spec] + outputs: [code, tests] + + analysis_only: + name: "Analysis Pipeline" + description: "Product analysis and requirements" + stages: + - name: research + agents: [analyst] + parallel: false + outputs: [research_findings] + - name: brief + agents: [analyst] + parallel: false + depends_on: [research] + outputs: [product_brief] + - name: requirements + agents: [pm] + parallel: false + depends_on: [brief] + outputs: [prd] + + design_review: + name: "Design Review Pipeline" + description: "Architecture and UX design with review" + stages: + - name: architecture + agents: [architect] + parallel: false + outputs: [architecture] + - name: ux + agents: [ux-designer] + parallel: false + depends_on: [architecture] + outputs: [ux_design] + - name: review + agents: [analyst, pm] + parallel: true + depends_on: [architecture, ux] + outputs: [design_review] + + test_suite: + name: "Test Suite Pipeline" + description: "Comprehensive testing workflow" + stages: + - name: test_design + agents: [tea] + parallel: false + outputs: [test_plan] + - name: test_impl + agents: [tea] + parallel: false + depends_on: [test_design] + outputs: [test_suite] + - name: security + agents: [tea] + parallel: false + depends_on: [test_impl] + outputs: [security_report] + - name: trace + agents: [tea] + parallel: false + depends_on: [test_impl] + outputs: [traceability_matrix] + +# Stage status values +status_values: + - pending # Not yet started + - queued # Ready to start (dependencies met) + - running # Currently executing + - completed # Finished successfully + - failed # Finished with errors + - skipped # Skipped (dependency failed) + - blocked # Waiting for dependencies + +# Error handling +error_handling: + on_stage_failure: "halt" # halt, skip_dependents, retry + max_retries: 2 + retry_delay_seconds: 30 + +# Output management +output_management: + intermediate_outputs_dir: "{pipeline_dir}/outputs" + preserve_intermediate: true + compress_on_complete: false diff --git a/src/core/pipeline/pipeline.md b/src/core/pipeline/pipeline.md new file mode 100644 index 00000000..d7d4e345 --- /dev/null +++ b/src/core/pipeline/pipeline.md @@ -0,0 +1,249 @@ +# Pipeline Orchestrator + +## Overview + +The Pipeline Orchestrator enables multi-stage agent pipelines with automatic dependency management. It supports sequential, parallel, and hybrid execution modes. + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ PIPELINE ORCHESTRATOR │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ Stage 1 │───▶│ Stage 2 │───▶│ Stage 3 │ (Sequential) │ +│ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ ┌─────────┐ │ +│ │ Stage A │─┐ │ +│ └─────────┘ │ ┌─────────┐ │ +│ ├─▶│ Stage D │ (Parallel → Sequential) │ +│ ┌─────────┐ │ └─────────┘ │ +│ │ Stage B │─┘ │ +│ └─────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +## Commands + +### PIPELINE create + +Create a new pipeline from template or custom definition. + +``` +PIPELINE create +PIPELINE create --template full_sdlc +PIPELINE create --name "Custom Pipeline" +``` + +### PIPELINE run + +Execute a pipeline. + +``` +PIPELINE run PIPE-20250115-myproject +PIPELINE run --active +``` + +### PIPELINE status + +Show pipeline status. + +``` +PIPELINE status +PIPELINE status PIPE-20250115-myproject +``` + +**Example output:** +``` +Pipeline: PIPE-20250115-myproject +Status: running +Progress: [████████░░░░░░░░░░░░] 40% + +Stages: +[✓] analysis + Agents: analyst + Duration: 12m 34s + Output: pipelines/outputs/analysis/ + +[✓] requirements + Agents: pm + Duration: 18m 22s + Output: pipelines/outputs/requirements/ + +[►] design + Agents: architect, ux-designer (parallel) + Duration: 8m 15s (running) + Output: pending + +[○] planning + Agents: sm + Duration: pending + Output: n/a + +Currently executing: design +Estimated remaining: ~45 minutes +``` + +### PIPELINE list + +List available pipelines and templates. + +``` +PIPELINE list +``` + +### PIPELINE abort + +Abort a running pipeline. + +``` +PIPELINE abort PIPE-20250115-myproject +``` + +### PIPELINE resume + +Resume a failed or paused pipeline. + +``` +PIPELINE resume PIPE-20250115-myproject +``` + +## Pipeline Templates + +### full_sdlc +Complete software development lifecycle. + +```yaml +stages: + - analysis (analyst) + - requirements (pm) → depends on analysis + - design (architect + ux-designer, parallel) → depends on requirements + - planning (sm) → depends on design + - implementation (dev) → depends on planning + - review (tea) → depends on implementation +``` + +### quick_flow +Rapid development with minimal ceremony. + +```yaml +stages: + - spec (quick-flow-solo-dev) + - implement (quick-flow-solo-dev) → depends on spec +``` + +### analysis_only +Product analysis and requirements. + +```yaml +stages: + - research (analyst) + - brief (analyst) → depends on research + - requirements (pm) → depends on brief +``` + +### design_review +Architecture and UX design with review. + +```yaml +stages: + - architecture (architect) + - ux (ux-designer) → depends on architecture + - review (analyst + pm, parallel) → depends on architecture, ux +``` + +### test_suite +Comprehensive testing workflow. + +```yaml +stages: + - test_design (tea) + - test_impl (tea) → depends on test_design + - security (tea) → depends on test_impl + - trace (tea) → depends on test_impl +``` + +## Custom Pipeline Definition + +```yaml +pipeline_id: "PIPE-20250115-custom" +name: "Custom Pipeline" +description: "My custom pipeline" +created: "2025-01-15T10:00:00Z" +status: "pending" + +stages: + - name: "stage1" + agents: ["analyst"] + parallel: false + depends_on: [] + outputs: ["analysis_report"] + status: "pending" + + - name: "stage2" + agents: ["architect", "ux-designer"] + parallel: true + depends_on: ["stage1"] + outputs: ["architecture", "ux_design"] + status: "pending" + + - name: "stage3" + agents: ["dev"] + parallel: false + depends_on: ["stage2"] + outputs: ["implementation"] + status: "pending" +``` + +## Execution Flow + +1. **Initialize**: Load pipeline definition, validate agents exist +2. **Queue**: Find stages with all dependencies completed +3. **Execute**: Run queued stages (parallel or sequential based on config) +4. **Collect**: Gather outputs from completed stages +5. **Update**: Update pipeline state file +6. **Repeat**: Continue until all stages complete or failure + +## Error Handling + +| Mode | Behavior | +|------|----------| +| halt | Stop pipeline on first failure | +| skip_dependents | Skip stages that depend on failed stage | +| retry | Retry failed stage (up to max_retries) | + +## Output Management + +Pipeline outputs are stored in: +``` +_bmad-output/ +└── pipelines/ + ├── PIPE-20250115-myproject.yaml # Pipeline state + └── outputs/ + ├── analysis/ + │ └── product-brief.md + ├── requirements/ + │ └── prd.md + └── design/ + ├── architecture.md + └── ux-design.md +``` + +## Integration with Token Isolation + +When executing stages: +1. Each agent runs in isolated subprocess (via Task tool) +2. Outputs written to pipeline output directory +3. Only status summaries return to orchestrator +4. Token budget preserved across multi-stage pipelines + +## Best Practices + +1. **Use templates** for common workflows +2. **Define dependencies explicitly** for correct execution order +3. **Enable parallel** only for truly independent stages +4. **Monitor progress** with status command +5. **Archive completed** pipelines to maintain clean state diff --git a/src/core/token-isolation/spawn-agent.xml b/src/core/token-isolation/spawn-agent.xml new file mode 100644 index 00000000..7b6d42a8 --- /dev/null +++ b/src/core/token-isolation/spawn-agent.xml @@ -0,0 +1,66 @@ + + + Spawn an agent in an isolated subprocess with token isolation + + + {project-root}/_bmad/core/config.yaml + {project-root}/_bmad/bmm/config.yaml:token_management + + + + + + + + + + + + + + Verify agent_type is valid (exists in agent-manifest.csv) + Verify prompt is not empty + Set default model to sonnet if not specified + + + + Load agent persona from {project-root}/_bmad/_config/agent-manifest.csv + Load any agent customizations from {project-root}/_bmad/_config/agents/ + Construct full agent prompt with persona + task prompt + + + + Use specified output path + + Generate path: {output_folder}/temp/{agent_type}-{timestamp}.md + + Append output instructions to prompt: + "Write your complete output to: {output_file} + Return only a brief summary (under 500 words) to this conversation." + + + + + Use Task tool with: + - description: "{agent_type}: {task_description}" + - prompt: {constructed_prompt} + - subagent_type: "general-purpose" + - model: {model} + - run_in_background: {run_in_background} + + + + + Wait for agent completion + Return agent_id for later retrieval + Return summary and output file path to caller + + + + + + + + + + diff --git a/src/core/token-isolation/token-isolation.md b/src/core/token-isolation/token-isolation.md new file mode 100644 index 00000000..dcd88575 --- /dev/null +++ b/src/core/token-isolation/token-isolation.md @@ -0,0 +1,103 @@ +# Token Isolation Architecture + +## Overview + +Token isolation prevents context bloat in multi-agent scenarios by running agents in isolated subprocesses. Each agent gets its own 150K token context window without consuming the main session's tokens. + +## Architecture Diagram + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ TOKEN ISOLATION ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ Main Session (150K tokens preserved) │ +│ │ │ +│ ▼ Task Tool spawns subprocess │ +│ ┌────────────────────┐ │ +│ │ Agent Instance │ ◄── Own 150K token context │ +│ │ (subprocess) │ ◄── Doesn't consume main session │ +│ └─────────┬──────────┘ │ +│ │ │ +│ ▼ Only summary returns │ +│ "Task complete. Output: temp/raw/file.md" │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +## Core Rules + +1. **ALWAYS** use Task tool to invoke agents (preserves main session tokens) +2. Agents write to files, not return full content to main session +3. Use `run_in_background: true` for parallel independent agents +4. Sequential agents receive previous output via content injection +5. Summaries returned to main session must be < 2000 tokens + +## Agent Execution Template + +```javascript +Task({ + description: "agent-name: brief task description", + prompt: agentPrompt, + subagent_type: "general-purpose", + model: "sonnet", // or "haiku" for quick tasks + run_in_background: false // true for parallel +}); +``` + +## Collaboration Patterns + +### Sequential Pattern +``` +Agent A → Agent B → Agent C +``` +Use when each step depends on previous output. + +### Parallel Pattern +``` +Agent A ─┐ +Agent B ─┼→ Synthesis +Agent C ─┘ +``` +Use when analyses are independent. + +### Debate Pattern +``` +Proposer ↔ Challenger → Refined Output +``` +Use for critical decisions requiring adversarial review. + +### War Room Pattern +``` +All Agents → Intensive Collaboration → Solution +``` +Use for complex urgent problems. + +## Output Management + +### File-Based Output +Agents should write outputs to: +- `{output_folder}/temp/` - Temporary working files +- `{output_folder}/raw/` - Raw agent outputs +- `{output_folder}/final/` - Validated final outputs + +### Summary Protocol +When an agent completes: +1. Write full output to designated file +2. Return only: status, file path, key findings (< 2000 tokens) +3. Main session can read file if details needed + +## Token Budget Tracking + +| Threshold | Action | +|-----------|--------| +| 0-80% | Normal operation | +| 80-90% | Warning: Consider wrapping up | +| 90-100% | Critical: Summarize and hand off | +| 100%+ | HALT: Must spawn new subprocess | + +## Best Practices + +1. **Pre-plan agent work** - Know what each agent needs to do +2. **Minimize cross-agent data** - Pass file references, not content +3. **Use haiku for simple tasks** - Reduces cost and latency +4. **Batch related work** - One agent, multiple related tasks +5. **Checkpoint frequently** - Save progress to files regularly diff --git a/src/core/tools/code-metrics.xml b/src/core/tools/code-metrics.xml new file mode 100644 index 00000000..ed31c137 --- /dev/null +++ b/src/core/tools/code-metrics.xml @@ -0,0 +1,111 @@ + + + Analyze codebase for size, complexity, and quality metrics + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Find all files matching include patterns + Exclude directories from exclude list + Build file list for analysis + + + + For each file, count total, code, blank, comment lines + Aggregate totals by file type + + + + Parse functions/methods in each file + Calculate cyclomatic complexity per function + Identify deeply nested code blocks + + + + Detect duplicate code blocks + Find long functions (> 50 lines) + Find large files (> 500 lines) + Count TODO/FIXME comments + + + + Format metrics according to output parameter + Include recommendations for concerning metrics + + + + + ``` + Code Metrics Report + =================== + Project: {project_name} + Path: {path} + Date: {date} + + Size Metrics: + - Total Files: {total_files} + - Lines of Code: {lines_of_code} + - Blank Lines: {blank_lines} + - Comment Lines: {comment_lines} + - Comment Ratio: {comment_ratio}% + + Complexity Metrics: + - Avg Cyclomatic Complexity: {avg_complexity} + - Max Complexity: {max_complexity} ({max_complexity_file}) + - Deep Nesting Issues: {deep_nesting_count} + + Quality Metrics: + - Duplicate Code Blocks: {duplicate_count} + - Long Functions (>50 lines): {long_functions_count} + - Large Files (>500 lines): {large_files_count} + - TODO/FIXME Count: {todo_count} + + Structure: + - Avg File Size: {avg_file_size} lines + - Avg Function Size: {avg_function_size} lines + + Breakdown by Language: + {for each language} + - {language}: {file_count} files, {line_count} lines + {end for} + + Recommendations: + {recommendations} + ``` + + diff --git a/src/core/tools/context-extractor.xml b/src/core/tools/context-extractor.xml new file mode 100644 index 00000000..498d5362 --- /dev/null +++ b/src/core/tools/context-extractor.xml @@ -0,0 +1,123 @@ + + + Extract key context from codebase for AI agent consumption (patterns, conventions, critical files) + + + + + + + + + + Key directories and their purposes + + Directory listing (depth 3) + README.md + package.json / setup.py / Cargo.toml + + + + + Common patterns used in the codebase + + Import patterns + Naming conventions + Error handling patterns + Async patterns + + + + + Key dependencies and their usage + + package.json dependencies + Import frequency analysis + + + + + Coding conventions and style + + .eslintrc / .prettierrc + tsconfig.json / jsconfig.json + editorconfig + Observed patterns in code + + + + + Most important files to understand + + Entry points (index, main, app) + Configuration files + Type definitions + Shared utilities + + + + + + + List directories up to depth 3 + Identify key directory patterns (src, lib, tests, etc.) + Note technology indicators (package.json, Cargo.toml, etc.) + + + + Find entry files (index.ts, main.py, main.go, etc.) + Extract high-level architecture from imports + + + + Parse linter/formatter configs + Sample 10 representative files for pattern analysis + Identify naming conventions (camelCase, snake_case, etc.) + + + + Extract key dependencies from package manager files + Identify most-imported modules + Note framework/library choices + + + + Compile findings within max_tokens budget + Prioritize most critical information + Format for AI agent consumption + + + + + ```markdown + # Project Context + + ## Technology Stack + - Language: {language} + - Framework: {framework} + - Key Libraries: {libraries} + + ## Project Structure + ``` + {directory_tree} + ``` + + ## Entry Points + {entry_points} + + ## Coding Conventions + - Naming: {naming_convention} + - Formatting: {formatting_rules} + - Imports: {import_pattern} + + ## Key Patterns + {patterns} + + ## Critical Files + {critical_files} + + ## Dependencies + {key_dependencies} + ``` + + diff --git a/src/core/tools/dependency-check.xml b/src/core/tools/dependency-check.xml new file mode 100644 index 00000000..77718755 --- /dev/null +++ b/src/core/tools/dependency-check.xml @@ -0,0 +1,68 @@ + + + Scan project dependencies for outdated packages and known vulnerabilities + + + + + + + + + + + + + + + + + + + + + Scan {path} for package manager files + Identify primary package manager from detected files + Report: "No supported package manager detected" + + + + Execute audit command for detected package manager + Capture stdout and stderr + Parse output for vulnerabilities + + + + Run outdated check command (e.g., npm outdated, pip list --outdated) + Parse output for package versions + + + + Filter by severity_threshold + Format output according to output_format + + + + + ``` + Dependency Check Report + ======================= + Project: {project_name} + Package Manager: {package_manager} + Date: {date} + + Vulnerabilities: + - Critical: {critical_count} + - High: {high_count} + - Medium: {medium_count} + - Low: {low_count} + + Outdated Packages: {outdated_count} + + Top Issues: + 1. {top_issue_1} + 2. {top_issue_2} + 3. {top_issue_3} + ``` + + diff --git a/src/core/tools/schema-validator.xml b/src/core/tools/schema-validator.xml new file mode 100644 index 00000000..a78d4518 --- /dev/null +++ b/src/core/tools/schema-validator.xml @@ -0,0 +1,81 @@ + + + Validate JSON/YAML files against schemas (JSON Schema, OpenAPI, etc.) + + + + + + + + + + + + + + + + + + Read file content + Detect file format (JSON or YAML) + Parse content into object + Return: "Syntax error: {error_message}" + + + + + Check for $schema property (JSON Schema) + Check for openapi property (OpenAPI) + Check for asyncapi property (AsyncAPI) + Default to json-schema if detected + + + + + + Load schema from {schema} path + + + Use built-in schema for detected type + + + + + Run validation against schema + Collect all validation errors + Format error messages with line numbers (if possible) + + + + Return: "Valid {schema_type} document" + Return: "Validation errors: {errors}" + + + + + ``` + Schema Validation Report + ======================== + File: {file} + Schema Type: {schema_type} + Status: {valid|invalid} + + {if errors} + Errors ({error_count}): + {for each error} + - Line {line}: {path} + {message} + {end for} + {end if} + + {if warnings} + Warnings ({warning_count}): + {for each warning} + - {path}: {message} + {end for} + {end if} + ``` + + diff --git a/src/core/workflows/session-manager/instructions.md b/src/core/workflows/session-manager/instructions.md new file mode 100644 index 00000000..3af8d4ea --- /dev/null +++ b/src/core/workflows/session-manager/instructions.md @@ -0,0 +1,263 @@ +# Session Manager Instructions + +## Overview + +The Session Manager provides persistent state management across conversations with token isolation, progress tracking, and context preservation. + +## Session ID Format + +``` +{PREFIX}{YYYYMM}-{CLIENT}-{PROJECT} +``` + +Examples: +- `SES202501-ACME-AUDIT` - Default session for ACME audit project +- `ENG202501-TESLA-API` - Engineering session for Tesla API project +- `TST202501-INTERNAL-REWRITE` - Testing session for internal rewrite + +## Commands + +### SESSION start + +Start a new session with structured identification. + +**Usage:** +``` +SESSION start +SESSION start --client ACME --project AUDIT +SESSION start --prefix ENG --client TESLA --project API +``` + +**Workflow:** +1. Check if active session exists + - If yes, prompt: "Active session found: {id}. Close it first? [y/n]" +2. Generate session ID using format: `{PREFIX}{YYYYMM}-{CLIENT}-{PROJECT}` +3. Create session file at `{sessions_dir}/{session_id}.yaml` +4. Set as active session in `active-session.yaml` +5. Initialize session state: + ```yaml + session_id: "{session_id}" + created: "{timestamp}" + status: "active" + client: "{client}" + project: "{project}" + tokens: + initial: 0 + current: 0 + saved: 0 + agents_spawned: [] + artifacts: [] + milestones: [] + context_summary: "" + ``` +6. Display confirmation with session ID + +### SESSION resume + +Resume an existing session with context restoration. + +**Workflow:** +1. Load `active-session.yaml` to get current session ID +2. If no active session, prompt: "No active session. Start new? [y/n]" +3. Load session file `{sessions_dir}/{session_id}.yaml` +4. Display session summary: + ``` + Resuming Session: {session_id} + Status: {status} + Started: {created} + Milestones: {milestone_count} + Artifacts: {artifact_count} + Token Usage: {current}/{max} + + Last Context: + {context_summary} + ``` +5. Restore session variables to working memory + +### SESSION status + +Show current session status with visual indicators. + +**Visual Status Indicators:** +| Indicator | Meaning | +|-----------|---------| +| :green_circle: | Active / On Track | +| :yellow_circle: | At Risk / Warning (>80% tokens) | +| :red_circle: | Blocked / Failed | +| :pause_button: | Paused | +| :white_check_mark: | Completed | + +**Output Format:** +``` +Session: {session_id} {status_indicator} +Duration: {duration} +Tokens: {current}/{max} ({percentage}%) +Progress Bar: [████████░░] 80% + +Milestones: +- [x] Initial setup +- [x] Requirements gathered +- [ ] Implementation started + +Recent Artifacts: +- docs/prd.md (created 2h ago) +- docs/architecture.md (modified 1h ago) + +Agents Spawned This Session: {count} +Token Savings from Isolation: {saved_tokens} +``` + +### SESSION close + +Close current session and archive. + +**Workflow:** +1. Load active session +2. Generate context summary (key decisions, outcomes, next steps) +3. Update session status to "closed" +4. Move session file to `{session_archive_dir}/` +5. Clear `active-session.yaml` +6. Display closure summary with learnings + +### SESSION list + +List all sessions with status. + +**Output:** +``` +Active Sessions: + SES202501-ACME-AUDIT :green_circle: (3 days) + +Archived Sessions: + ENG202412-TESLA-API :white_check_mark: (closed 2024-12-28) + TST202412-INTERNAL-MVP :white_check_mark: (closed 2024-12-15) +``` + +### SESSION tokens + +Show detailed token usage report. + +**Output:** +``` +Token Usage Report: {session_id} + +Main Session: + Used: 45,000 / 150,000 (30%) + Remaining: 105,000 + +Subprocess Agents: + analyst: 32,000 tokens (isolated) + architect: 28,000 tokens (isolated) + dev: 85,000 tokens (isolated) + +Total Consumed (if no isolation): 190,000 +Actual Main Session: 45,000 +Tokens Saved: 145,000 (76% savings) +``` + +### SESSION savings + +Show token savings from isolation architecture. + +**Output:** +``` +Token Isolation Savings + +Without Isolation: + All agent work in main context: 190,000 tokens + Would exceed limit by: 40,000 tokens + +With Isolation: + Main session: 45,000 tokens + Agents in subprocesses: 145,000 tokens (not counted) + +Savings: 145,000 tokens (76%) +Status: :green_circle: Within budget +``` + +### SESSION switch + +Switch to a different session. + +**Workflow:** +1. Save current session state +2. Load specified session +3. Restore context +4. Update active-session.yaml + +## Session File Structure + +```yaml +# {session_id}.yaml +session_id: "SES202501-ACME-AUDIT" +created: "2025-01-15T10:30:00Z" +last_updated: "2025-01-15T14:45:00Z" +status: "active" # active, paused, closed + +# Identification +client: "ACME" +project: "AUDIT" +prefix: "SES" + +# Token tracking +tokens: + initial: 0 + current: 45000 + peak: 52000 + saved_by_isolation: 145000 + +# Agent tracking +agents_spawned: + - id: "agent-123" + type: "analyst" + started: "2025-01-15T10:35:00Z" + completed: "2025-01-15T10:42:00Z" + tokens_used: 32000 + output_file: "_bmad-output/temp/analyst-123.md" + +# Artifacts produced +artifacts: + - path: "docs/prd.md" + created: "2025-01-15T11:00:00Z" + agent: "pm" + - path: "docs/architecture.md" + created: "2025-01-15T12:30:00Z" + agent: "architect" + +# Progress tracking +milestones: + - name: "Requirements Complete" + completed: "2025-01-15T11:30:00Z" + - name: "Architecture Approved" + completed: "2025-01-15T13:00:00Z" + - name: "Implementation Started" + completed: null + +# Context for resume +context_summary: | + Working on ACME security audit project. + PRD complete, architecture approved. + Currently implementing Epic 1: User Authentication. + Next: Complete story 1-2-user-login. + +# Session notes +notes: + - "Client prefers OAuth2 over JWT" + - "Performance requirement: <200ms response time" +``` + +## Integration with Token Isolation + +When spawning agents via Task tool: +1. Record agent spawn in session +2. Track output file location +3. Calculate token savings +4. Update session totals + +## Best Practices + +1. **Always start a session** before beginning substantial work +2. **Update milestones** as you complete major phases +3. **Close sessions** when work is complete to maintain clean state +4. **Use meaningful names** for client/project identification +5. **Review savings** periodically to understand isolation benefits diff --git a/src/core/workflows/session-manager/session-template.yaml b/src/core/workflows/session-manager/session-template.yaml new file mode 100644 index 00000000..9563c36c --- /dev/null +++ b/src/core/workflows/session-manager/session-template.yaml @@ -0,0 +1,81 @@ +# Session Template +# Copy and customize for new sessions + +session_id: "{PREFIX}{YYYYMM}-{CLIENT}-{PROJECT}" +created: "{timestamp}" +last_updated: "{timestamp}" +status: "active" + +# Identification +client: "{CLIENT}" +project: "{PROJECT}" +prefix: "{PREFIX}" +description: "" + +# Token tracking +tokens: + initial: 0 + current: 0 + peak: 0 + saved_by_isolation: 0 + warning_threshold: 120000 + max_limit: 150000 + +# Agent tracking +agents_spawned: [] +# Example entry: +# - id: "agent-abc123" +# type: "analyst" +# started: "2025-01-15T10:35:00Z" +# completed: "2025-01-15T10:42:00Z" +# tokens_used: 32000 +# output_file: "_bmad-output/temp/analyst-abc123.md" +# status: "completed" # running, completed, failed + +# Artifacts produced +artifacts: [] +# Example entry: +# - path: "docs/prd.md" +# type: "document" +# created: "2025-01-15T11:00:00Z" +# modified: "2025-01-15T11:30:00Z" +# agent: "pm" +# description: "Product Requirements Document" + +# Progress tracking +milestones: [] +# Example entry: +# - name: "Requirements Complete" +# target_date: "2025-01-15" +# completed: "2025-01-15T11:30:00Z" +# notes: "All stakeholder requirements gathered" + +# Current work context +current_focus: + epic: "" + story: "" + task: "" + blocker: "" + +# Context for resume (AI-generated summary) +context_summary: | + Session initialized. Ready to begin work. + +# Decision log +decisions: [] +# Example entry: +# - date: "2025-01-15" +# decision: "Use PostgreSQL for primary database" +# rationale: "Team expertise, ACID compliance needs" +# made_by: "architect" + +# Session notes +notes: [] +# Example entry: +# - timestamp: "2025-01-15T10:30:00Z" +# note: "Client prefers OAuth2 over JWT" +# source: "user" + +# Tags for filtering +tags: [] +# Example: ["security", "audit", "enterprise"] diff --git a/src/core/workflows/session-manager/workflow.yaml b/src/core/workflows/session-manager/workflow.yaml new file mode 100644 index 00000000..86701da4 --- /dev/null +++ b/src/core/workflows/session-manager/workflow.yaml @@ -0,0 +1,52 @@ +# Session Manager Workflow +name: session-manager +description: "Persistent session management with token isolation, state tracking, and context preservation across conversations" +author: "BMAD" +version: "1.0.0" + +# Configuration sources +config_source: "{project-root}/_bmad/core/config.yaml" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +output_folder: "{config_source}:output_folder" +date: system-generated + +# Session storage +sessions_dir: "{project-root}/_bmad-output/sessions" +active_session_file: "{sessions_dir}/active-session.yaml" +session_archive_dir: "{sessions_dir}/archive" + +# Workflow components +installed_path: "{project-root}/_bmad/core/workflows/session-manager" +instructions: "{installed_path}/instructions.md" + +# Session ID format: {PREFIX}{YYYYMM}-{CLIENT}-{PROJECT} +session_prefixes: + default: "SES" + engineering: "ENG" + analysis: "ANA" + design: "DES" + testing: "TST" + +standalone: true + +# Commands +commands: + - name: "start" + description: "Start a new session" + args: "--client NAME --project NAME --prefix PREFIX" + - name: "resume" + description: "Resume the active session" + - name: "status" + description: "Show current session status and token usage" + - name: "close" + description: "Close current session and archive" + - name: "list" + description: "List all sessions (active and archived)" + - name: "tokens" + description: "Show detailed token usage report" + - name: "savings" + description: "Show token savings from isolation" + - name: "switch" + description: "Switch to a different session" + args: "SESSION_ID" diff --git a/src/modules/bmm/workflows/3-solutioning/create-api-spec/api-checklist.md b/src/modules/bmm/workflows/3-solutioning/create-api-spec/api-checklist.md new file mode 100644 index 00000000..5205f4b2 --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/create-api-spec/api-checklist.md @@ -0,0 +1,117 @@ +# API Design Checklist + +## Resource Design +- [ ] Resources use plural nouns (users, orders, products) +- [ ] Resource names are lowercase with hyphens (user-profiles) +- [ ] Relationships expressed via nesting or links +- [ ] No verbs in resource paths (use HTTP methods instead) + +## HTTP Methods +- [ ] GET for reading (no side effects) +- [ ] POST for creating new resources +- [ ] PUT for full resource replacement +- [ ] PATCH for partial updates +- [ ] DELETE for removing resources +- [ ] HEAD for metadata requests (if needed) +- [ ] OPTIONS for CORS preflight (automatic) + +## Status Codes +- [ ] 200 OK for successful GET/PUT/PATCH +- [ ] 201 Created for successful POST +- [ ] 204 No Content for successful DELETE +- [ ] 400 Bad Request for malformed requests +- [ ] 401 Unauthorized for missing/invalid auth +- [ ] 403 Forbidden for insufficient permissions +- [ ] 404 Not Found for missing resources +- [ ] 409 Conflict for state conflicts +- [ ] 422 Unprocessable Entity for validation errors +- [ ] 429 Too Many Requests for rate limiting +- [ ] 500 Internal Server Error (avoid exposing details) + +## Request Design +- [ ] Content-Type headers required for POST/PUT/PATCH +- [ ] Accept headers for content negotiation +- [ ] Query parameters for filtering/sorting/pagination +- [ ] Path parameters for resource identifiers +- [ ] Request body validation documented + +## Response Design +- [ ] Consistent envelope structure (data, meta, links, error) +- [ ] Timestamps in ISO 8601 format +- [ ] IDs as strings (UUIDs recommended) +- [ ] Pagination for list endpoints +- [ ] HATEOAS links where appropriate + +## Pagination +- [ ] Page-based or cursor-based pagination +- [ ] Default and maximum limits defined +- [ ] Total count available +- [ ] Navigation links included + +## Filtering & Sorting +- [ ] Filter syntax documented +- [ ] Sortable fields specified +- [ ] Default sort order defined +- [ ] Multiple sort fields supported + +## Authentication +- [ ] Auth method documented (Bearer, API Key, OAuth2) +- [ ] Token format specified (JWT structure) +- [ ] Token expiration documented +- [ ] Refresh token flow if applicable + +## Authorization +- [ ] Per-endpoint permissions documented +- [ ] Role-based access defined +- [ ] Resource ownership rules clear + +## Versioning +- [ ] Versioning strategy chosen (URL, header, parameter) +- [ ] Major version in URL (/v1/, /v2/) +- [ ] Deprecation policy documented +- [ ] Breaking changes defined + +## Error Handling +- [ ] Error response format consistent +- [ ] Error codes meaningful and documented +- [ ] Validation errors include field details +- [ ] No sensitive info in error messages + +## Security +- [ ] HTTPS required +- [ ] Rate limiting implemented +- [ ] CORS properly configured +- [ ] Input validation on all fields +- [ ] SQL injection prevention +- [ ] No sensitive data in URLs + +## Documentation +- [ ] OpenAPI 3.0+ specification complete +- [ ] All endpoints documented +- [ ] Request/response examples provided +- [ ] Authentication documented +- [ ] Error codes listed + +## Testing +- [ ] Mock server available +- [ ] Example requests for each endpoint +- [ ] Postman/Insomnia collection exported +- [ ] SDK generation tested + +--- + +## Quick Validation + +```bash +# Validate OpenAPI spec +npx @stoplight/spectral-cli lint api-spec.yaml + +# Alternative validation +npx swagger-cli validate api-spec.yaml + +# Generate types (TypeScript) +npx openapi-typescript api-spec.yaml -o types.d.ts + +# Start mock server +npx @stoplight/prism-cli mock api-spec.yaml +``` diff --git a/src/modules/bmm/workflows/3-solutioning/create-api-spec/instructions.md b/src/modules/bmm/workflows/3-solutioning/create-api-spec/instructions.md new file mode 100644 index 00000000..ae7b85b3 --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/create-api-spec/instructions.md @@ -0,0 +1,309 @@ +# API Design Workflow Instructions + +## Overview + +Design APIs using a contract-first approach. This workflow produces OpenAPI 3.0+ specifications, mock server configurations, and client SDK generation guidance. + +## Workflow Steps + +### Step 1: Context Loading + +**Load existing documentation:** +1. Load PRD for feature requirements +2. Load Architecture document for system design +3. Load project-context.md for coding standards +4. Identify existing API patterns (if any) + +### Step 2: API Style Selection + +**Ask user for API style:** +``` +API Style Selection + +Available styles: +1. [rest] RESTful API (OpenAPI 3.0+) +2. [graphql] GraphQL Schema +3. [grpc] gRPC/Protocol Buffers +4. [websocket] WebSocket Event Schema + +Select style [1-4]: +``` + +### Step 3: Resource Identification + +**For REST APIs, identify resources:** +1. Extract nouns from PRD (users, orders, products, etc.) +2. Map to REST resources +3. Identify relationships (1:1, 1:N, N:N) +4. Determine resource hierarchy + +**Questions to ask:** +- What are the main entities in this system? +- How do entities relate to each other? +- What operations are needed for each entity? +- Are there any batch operations required? + +### Step 4: Endpoint Design + +**For each resource, design endpoints:** + +| Operation | Method | Path Pattern | Example | +|-----------|--------|--------------|---------| +| List | GET | /resources | GET /users | +| Create | POST | /resources | POST /users | +| Read | GET | /resources/{id} | GET /users/123 | +| Update | PUT/PATCH | /resources/{id} | PATCH /users/123 | +| Delete | DELETE | /resources/{id} | DELETE /users/123 | +| Nested | GET | /resources/{id}/subs | GET /users/123/orders | + +**Naming conventions:** +- Use plural nouns for resources +- Use kebab-case for multi-word resources +- Use path parameters for identifiers +- Use query parameters for filtering/pagination + +### Step 5: Request/Response Design + +**For each endpoint, define:** + +1. **Request body schema** (POST/PUT/PATCH) + - Required vs optional fields + - Data types and formats + - Validation rules (min/max, pattern, enum) + +2. **Response schema** + - Success response structure + - Error response structure + - Pagination format + +3. **Headers** + - Authentication headers + - Content-Type + - Custom headers + +**Standard response format:** +```json +{ + "data": { ... }, + "meta": { + "page": 1, + "limit": 20, + "total": 100 + }, + "links": { + "self": "/users?page=1", + "next": "/users?page=2" + } +} +``` + +**Standard error format:** +```json +{ + "error": { + "code": "VALIDATION_ERROR", + "message": "Request validation failed", + "details": [ + { "field": "email", "message": "Invalid email format" } + ] + } +} +``` + +### Step 6: Authentication & Authorization + +**Define security scheme:** +```yaml +securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + apiKey: + type: apiKey + in: header + name: X-API-Key + oauth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: /oauth/authorize + tokenUrl: /oauth/token + scopes: + read: Read access + write: Write access +``` + +**Apply security to endpoints:** +- Public endpoints (no auth) +- Authenticated endpoints (user token) +- Admin-only endpoints (role-based) + +### Step 7: Generate OpenAPI Specification + +**Create OpenAPI 3.0+ document:** + +```yaml +openapi: 3.0.3 +info: + title: {project_name} API + version: 1.0.0 + description: | + {api_description} + +servers: + - url: https://api.example.com/v1 + description: Production + - url: https://staging-api.example.com/v1 + description: Staging + - url: http://localhost:3000/v1 + description: Development + +paths: + /resources: + get: + summary: List resources + operationId: listResources + tags: + - Resources + parameters: + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/limit' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceList' + +components: + schemas: + Resource: + type: object + properties: + id: + type: string + format: uuid + name: + type: string + required: + - id + - name + + parameters: + page: + name: page + in: query + schema: + type: integer + default: 1 + limit: + name: limit + in: query + schema: + type: integer + default: 20 + maximum: 100 +``` + +### Step 8: API Documentation + +**Generate API design document with:** + +1. **Overview** + - API purpose and scope + - Base URL and versioning strategy + - Authentication methods + +2. **Quick Start** + - Getting API credentials + - Making first request + - Common patterns + +3. **Resource Reference** + - Detailed endpoint documentation + - Request/response examples + - Error codes + +4. **Best Practices** + - Rate limiting guidance + - Pagination recommendations + - Error handling + +### Step 9: Mock Server Guidance + +**Provide mock server setup:** + +```bash +# Using Prism (OpenAPI) +npm install -g @stoplight/prism-cli +prism mock api-spec.yaml + +# Using json-server (simple) +npm install -g json-server +json-server --watch db.json + +# Using MSW (frontend mocking) +npm install msw --save-dev +``` + +**Include sample mock data:** +```json +{ + "users": [ + { "id": "1", "name": "Alice", "email": "alice@example.com" }, + { "id": "2", "name": "Bob", "email": "bob@example.com" } + ] +} +``` + +### Step 10: SDK Generation Guidance + +**Client SDK generation options:** + +```bash +# OpenAPI Generator +npx @openapitools/openapi-generator-cli generate \ + -i api-spec.yaml \ + -g typescript-axios \ + -o ./sdk + +# Available generators: +# - typescript-axios +# - typescript-fetch +# - python +# - go +# - java +# - csharp +``` + +**Type generation (TypeScript):** +```bash +# Using openapi-typescript +npx openapi-typescript api-spec.yaml -o types.d.ts +``` + +### Step 11: Validation Checklist + +Before completing: +- [ ] All PRD features have corresponding endpoints +- [ ] Resource naming follows conventions +- [ ] Request/response schemas complete +- [ ] Authentication defined for protected endpoints +- [ ] Error responses documented +- [ ] Pagination implemented for list endpoints +- [ ] OpenAPI spec validates (use swagger-cli validate) +- [ ] Examples provided for complex endpoints + +### Step 12: Output Files + +**Save to:** +- OpenAPI spec: `{output_file}` (api-spec.yaml) +- API design doc: `{output_doc}` (api-design.md) + +**Notify user with:** +- Summary of endpoints created +- Link to specification file +- Mock server quick start +- Next steps (implementation, SDK generation) diff --git a/src/modules/bmm/workflows/3-solutioning/create-api-spec/openapi.template.yaml b/src/modules/bmm/workflows/3-solutioning/create-api-spec/openapi.template.yaml new file mode 100644 index 00000000..8f77ab32 --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/create-api-spec/openapi.template.yaml @@ -0,0 +1,467 @@ +openapi: 3.0.3 +info: + title: "{{project_name}} API" + version: "{{api_version}}" + description: | + {{api_description}} + + ## Authentication + {{auth_description}} + + ## Rate Limiting + {{rate_limit_description}} + + contact: + name: API Support + email: api@example.com + license: + name: MIT + url: https://opensource.org/licenses/MIT + +servers: + - url: https://api.{{domain}}/v{{major_version}} + description: Production + - url: https://staging-api.{{domain}}/v{{major_version}} + description: Staging + - url: http://localhost:{{port}}/v{{major_version}} + description: Development + +tags: + # Define tags for each resource group + - name: Authentication + description: Authentication and authorization endpoints + - name: Users + description: User management operations + # Add more tags as needed + +paths: + # Authentication endpoints + /auth/login: + post: + summary: Authenticate user + operationId: login + tags: + - Authentication + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/LoginRequest' + responses: + '200': + description: Authentication successful + content: + application/json: + schema: + $ref: '#/components/schemas/AuthResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '422': + $ref: '#/components/responses/ValidationError' + + /auth/logout: + post: + summary: Logout user + operationId: logout + tags: + - Authentication + security: + - bearerAuth: [] + responses: + '204': + description: Logout successful + '401': + $ref: '#/components/responses/Unauthorized' + + # Resource template - copy and customize + /resources: + get: + summary: List resources + operationId: listResources + tags: + - Resources + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/sort' + - $ref: '#/components/parameters/filter' + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceListResponse' + '401': + $ref: '#/components/responses/Unauthorized' + + post: + summary: Create resource + operationId: createResource + tags: + - Resources + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateResourceRequest' + responses: + '201': + description: Resource created + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '422': + $ref: '#/components/responses/ValidationError' + + /resources/{id}: + parameters: + - $ref: '#/components/parameters/resourceId' + + get: + summary: Get resource by ID + operationId: getResource + tags: + - Resources + security: + - bearerAuth: [] + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + + patch: + summary: Update resource + operationId: updateResource + tags: + - Resources + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateResourceRequest' + responses: + '200': + description: Resource updated + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/ValidationError' + + delete: + summary: Delete resource + operationId: deleteResource + tags: + - Resources + security: + - bearerAuth: [] + responses: + '204': + description: Resource deleted + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: JWT authentication token + + apiKey: + type: apiKey + in: header + name: X-API-Key + description: API key for service-to-service calls + + parameters: + page: + name: page + in: query + description: Page number for pagination + schema: + type: integer + minimum: 1 + default: 1 + + limit: + name: limit + in: query + description: Number of items per page + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + + sort: + name: sort + in: query + description: Sort field and direction (e.g., -createdAt for descending) + schema: + type: string + example: "-createdAt" + + filter: + name: filter + in: query + description: Filter expression + schema: + type: string + example: "status:active" + + resourceId: + name: id + in: path + required: true + description: Resource identifier + schema: + type: string + format: uuid + + schemas: + # Authentication schemas + LoginRequest: + type: object + required: + - email + - password + properties: + email: + type: string + format: email + password: + type: string + format: password + minLength: 8 + + AuthResponse: + type: object + properties: + accessToken: + type: string + refreshToken: + type: string + expiresIn: + type: integer + description: Token expiry in seconds + tokenType: + type: string + default: Bearer + + # Resource schemas (template) + Resource: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + name: + type: string + minLength: 1 + maxLength: 255 + description: + type: string + status: + type: string + enum: [active, inactive, archived] + default: active + createdAt: + type: string + format: date-time + readOnly: true + updatedAt: + type: string + format: date-time + readOnly: true + required: + - name + + CreateResourceRequest: + allOf: + - $ref: '#/components/schemas/Resource' + - type: object + required: + - name + + UpdateResourceRequest: + type: object + properties: + name: + type: string + description: + type: string + status: + type: string + enum: [active, inactive, archived] + + ResourceResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Resource' + + ResourceListResponse: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Resource' + meta: + $ref: '#/components/schemas/PaginationMeta' + links: + $ref: '#/components/schemas/PaginationLinks' + + # Pagination + PaginationMeta: + type: object + properties: + page: + type: integer + limit: + type: integer + total: + type: integer + totalPages: + type: integer + + PaginationLinks: + type: object + properties: + self: + type: string + format: uri + first: + type: string + format: uri + prev: + type: string + format: uri + nullable: true + next: + type: string + format: uri + nullable: true + last: + type: string + format: uri + + # Error schemas + Error: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + + responses: + Unauthorized: + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + error: + code: UNAUTHORIZED + message: Authentication required + + Forbidden: + description: Permission denied + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + error: + code: FORBIDDEN + message: Permission denied + + NotFound: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + error: + code: NOT_FOUND + message: Resource not found + + ValidationError: + description: Validation error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + error: + code: VALIDATION_ERROR + message: Request validation failed + details: + - field: email + message: Invalid email format + + RateLimitExceeded: + description: Rate limit exceeded + headers: + X-RateLimit-Limit: + schema: + type: integer + X-RateLimit-Remaining: + schema: + type: integer + X-RateLimit-Reset: + schema: + type: integer + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + error: + code: RATE_LIMIT_EXCEEDED + message: Too many requests diff --git a/src/modules/bmm/workflows/3-solutioning/create-api-spec/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/create-api-spec/workflow.yaml new file mode 100644 index 00000000..2728385a --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/create-api-spec/workflow.yaml @@ -0,0 +1,39 @@ +# API Design Workflow +name: create-api-spec +description: "Contract-first API design workflow producing OpenAPI 3.0+ specifications with mock server guidance and client SDK generation recommendations" +author: "BMAD" +version: "1.0.0" + +# Configuration sources +config_source: "{project-root}/_bmad/bmm/config.yaml" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +user_skill_level: "{config_source}:user_skill_level" +document_output_language: "{config_source}:document_output_language" +planning_artifacts: "{config_source}:planning_artifacts" +output_folder: "{planning_artifacts}" +date: system-generated + +# Workflow components +installed_path: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-api-spec" +instructions: "{installed_path}/instructions.md" +template: "{installed_path}/openapi.template.yaml" +checklist: "{installed_path}/api-checklist.md" + +# Input references +prd_doc: "{planning_artifacts}/*prd*.md" +architecture_doc: "{planning_artifacts}/*architecture*.md" +project_context: "**/project-context.md" + +# Output +output_file: "{output_folder}/api-spec.yaml" +output_doc: "{output_folder}/api-design.md" + +# API styles supported +api_styles: + - rest # RESTful API + - graphql # GraphQL schema + - grpc # Protocol Buffers + - websocket # WebSocket events + +standalone: true diff --git a/src/modules/bmm/workflows/testarch/security-audit/instructions.md b/src/modules/bmm/workflows/testarch/security-audit/instructions.md new file mode 100644 index 00000000..7222a8dc --- /dev/null +++ b/src/modules/bmm/workflows/testarch/security-audit/instructions.md @@ -0,0 +1,269 @@ +# Security Audit Workflow Instructions + +## Overview + +Conduct a comprehensive security audit of the codebase covering OWASP Top 10 vulnerabilities, dependency security, secret detection, and authentication/authorization patterns. + +## Workflow Steps + +### Step 1: Scope Determination + +**Ask user for audit scope:** +``` +Security Audit Scope Selection + +Available scopes: +1. [full] Complete security audit (recommended) +2. [owasp] OWASP Top 10 vulnerability focus +3. [deps] Dependency vulnerabilities only +4. [secrets] Secret detection only +5. [auth] Authentication/authorization review +6. [api] API security assessment + +Select scope [1-6] or enter scope name: +``` + +### Step 2: Context Loading + +**Load project context:** +1. Load architecture document for understanding system design +2. Load project-context.md for coding standards and patterns +3. Identify technology stack (framework, language, dependencies) +4. Note any existing security configurations + +### Step 3: OWASP Top 10 Assessment + +**For each vulnerability category:** + +#### A01:2021 - Broken Access Control +- [ ] Check for missing access controls on functions +- [ ] Review CORS configuration +- [ ] Verify principle of least privilege +- [ ] Check for insecure direct object references (IDOR) +- [ ] Review JWT/session validation + +#### A02:2021 - Cryptographic Failures +- [ ] Check for hardcoded secrets +- [ ] Verify HTTPS enforcement +- [ ] Review encryption algorithms used +- [ ] Check password hashing (bcrypt, argon2) +- [ ] Verify secure random number generation + +#### A03:2021 - Injection +- [ ] SQL injection in database queries +- [ ] NoSQL injection patterns +- [ ] Command injection in system calls +- [ ] LDAP injection +- [ ] XPath injection + +#### A04:2021 - Insecure Design +- [ ] Review authentication flows +- [ ] Check for business logic flaws +- [ ] Verify rate limiting implementation +- [ ] Review error handling patterns + +#### A05:2021 - Security Misconfiguration +- [ ] Default credentials check +- [ ] Unnecessary features enabled +- [ ] Error messages exposing info +- [ ] Security headers missing +- [ ] Debug mode in production + +#### A06:2021 - Vulnerable Components +- [ ] Outdated dependencies +- [ ] Known CVEs in dependencies +- [ ] Unmaintained packages +- [ ] License compliance issues + +#### A07:2021 - Authentication Failures +- [ ] Weak password policies +- [ ] Missing brute-force protection +- [ ] Session management issues +- [ ] Multi-factor authentication gaps + +#### A08:2021 - Software Integrity Failures +- [ ] CI/CD pipeline security +- [ ] Unsigned code/packages +- [ ] Insecure deserialization +- [ ] Missing integrity checks + +#### A09:2021 - Logging & Monitoring Failures +- [ ] Insufficient logging +- [ ] Missing audit trails +- [ ] No alerting mechanisms +- [ ] Log injection vulnerabilities + +#### A10:2021 - Server-Side Request Forgery +- [ ] Unvalidated URL parameters +- [ ] Internal service exposure +- [ ] DNS rebinding risks + +### Step 4: Dependency Vulnerability Scan + +**Scan dependencies for known vulnerabilities:** + +```bash +# Node.js +npm audit +npx better-npm-audit audit + +# Python +pip-audit +safety check + +# Go +govulncheck ./... + +# General +trivy fs . +grype . +``` + +**Document findings:** +- CVE identifier +- Severity (Critical/High/Medium/Low) +- Affected package and version +- Fix version available +- Remediation path + +### Step 5: Secret Detection + +**Scan for exposed secrets:** + +Patterns to detect: +- API keys (AWS, GCP, Azure, etc.) +- Database connection strings +- Private keys (RSA, SSH) +- OAuth tokens +- JWT secrets +- Password literals +- Environment variable leaks + +**Tools:** +```bash +# Gitleaks +gitleaks detect --source . --verbose + +# TruffleHog +trufflehog filesystem . + +# detect-secrets +detect-secrets scan +``` + +**Check locations:** +- Source code files +- Configuration files +- Environment files (.env, .env.*) +- Docker files +- CI/CD configurations +- Git history + +### Step 6: Authentication/Authorization Review + +**Authentication checks:** +- Password storage mechanism +- Session management +- Token handling (JWT, OAuth) +- MFA implementation +- Password reset flow +- Account lockout policy + +**Authorization checks:** +- Role-based access control (RBAC) +- Attribute-based access control (ABAC) +- API endpoint protection +- Resource-level permissions +- Admin panel security + +### Step 7: API Security Assessment + +**Review API endpoints for:** +- Authentication requirements +- Rate limiting +- Input validation +- Output encoding +- CORS configuration +- API versioning +- Documentation exposure + +**Check for:** +- Mass assignment vulnerabilities +- Excessive data exposure +- Broken function level authorization +- Improper inventory management + +### Step 8: Generate Report + +**Create security audit report with:** + +```markdown +# Security Audit Report + +**Date:** {date} +**Scope:** {audit_scope} +**Auditor:** {user_name} + TEA Agent + +## Executive Summary +{brief_overview_of_findings} + +## Risk Summary +| Severity | Count | +|----------|-------| +| Critical | X | +| High | X | +| Medium | X | +| Low | X | + +## Findings + +### Critical Findings +{detailed_critical_issues} + +### High Severity Findings +{detailed_high_issues} + +### Medium Severity Findings +{detailed_medium_issues} + +### Low Severity Findings +{detailed_low_issues} + +## Recommendations +{prioritized_remediation_steps} + +## Appendix +- Full OWASP checklist results +- Dependency scan output +- Secret detection results +``` + +### Step 9: Remediation Guidance + +**For each finding, provide:** +1. Clear description of the vulnerability +2. Location in codebase (file:line) +3. Risk assessment (likelihood + impact) +4. Remediation steps +5. Code example of fix (where applicable) +6. References (CWE, OWASP, CVE) + +### Step 10: Validation Checklist + +Before completing audit: +- [ ] All scope items assessed +- [ ] Findings documented with evidence +- [ ] Severity ratings justified +- [ ] Remediation steps actionable +- [ ] Report saved to output location +- [ ] No false positives in critical findings + +## Output + +Save report to: `{output_file}` + +Notify user of completion with: +- Summary of findings +- Link to full report +- Top 3 priority items to address +- Offer to help with remediation diff --git a/src/modules/bmm/workflows/testarch/security-audit/owasp-checklist.md b/src/modules/bmm/workflows/testarch/security-audit/owasp-checklist.md new file mode 100644 index 00000000..64d61a7d --- /dev/null +++ b/src/modules/bmm/workflows/testarch/security-audit/owasp-checklist.md @@ -0,0 +1,215 @@ +# OWASP Top 10 (2021) Security Checklist + +## A01:2021 - Broken Access Control + +### Access Control Checks +- [ ] All endpoints require authentication unless explicitly public +- [ ] Authorization checked on every request (not just UI) +- [ ] Deny by default policy implemented +- [ ] CORS properly configured with allowlisted origins +- [ ] Directory listing disabled on web servers +- [ ] Metadata files (.git, .svn) not accessible +- [ ] Rate limiting implemented on sensitive endpoints + +### IDOR Prevention +- [ ] Object references are indirect or validated +- [ ] User can only access their own resources +- [ ] Admin functions properly protected +- [ ] API endpoints validate ownership + +### Session Security +- [ ] Session invalidated on logout +- [ ] Session timeout implemented +- [ ] Session fixation prevented +- [ ] Concurrent session limits (if required) + +--- + +## A02:2021 - Cryptographic Failures + +### Data Protection +- [ ] Sensitive data identified and classified +- [ ] Data encrypted at rest +- [ ] Data encrypted in transit (TLS 1.2+) +- [ ] No sensitive data in URLs +- [ ] Secure cookies (HttpOnly, Secure, SameSite) + +### Password Security +- [ ] Passwords hashed with bcrypt/argon2/scrypt +- [ ] No MD5/SHA1 for passwords +- [ ] Salt unique per password +- [ ] Work factor appropriate (>=10 for bcrypt) + +### Key Management +- [ ] No hardcoded secrets in code +- [ ] Secrets in environment variables or vault +- [ ] Encryption keys rotated periodically +- [ ] Secure random number generation + +--- + +## A03:2021 - Injection + +### SQL Injection +- [ ] Parameterized queries used everywhere +- [ ] ORM/query builder used correctly +- [ ] No string concatenation in queries +- [ ] Input validation on all user data + +### NoSQL Injection +- [ ] MongoDB queries use proper operators +- [ ] No eval() on user input +- [ ] Input sanitized for NoSQL patterns + +### Command Injection +- [ ] No shell commands with user input +- [ ] If needed, strict allowlist validation +- [ ] Escape special characters + +### XSS Prevention +- [ ] Output encoding on all user data +- [ ] Content-Security-Policy header set +- [ ] Dangerous HTML stripped or sanitized +- [ ] Template engines auto-escape + +--- + +## A04:2021 - Insecure Design + +### Threat Modeling +- [ ] Security requirements documented +- [ ] Threat model exists for critical flows +- [ ] Security user stories in backlog + +### Business Logic +- [ ] Rate limiting on business operations +- [ ] Transaction limits enforced server-side +- [ ] Workflow state validated + +### Error Handling +- [ ] Generic error messages to users +- [ ] Detailed errors only in logs +- [ ] No stack traces in production + +--- + +## A05:2021 - Security Misconfiguration + +### Server Configuration +- [ ] Unnecessary features disabled +- [ ] Default accounts removed/changed +- [ ] Directory browsing disabled +- [ ] Error pages customized + +### Security Headers +- [ ] Content-Security-Policy +- [ ] X-Content-Type-Options: nosniff +- [ ] X-Frame-Options or CSP frame-ancestors +- [ ] Strict-Transport-Security +- [ ] X-XSS-Protection (legacy browsers) +- [ ] Referrer-Policy + +### Cloud/Container Security +- [ ] Least privilege IAM roles +- [ ] Security groups properly configured +- [ ] Container images scanned +- [ ] No root processes in containers + +--- + +## A06:2021 - Vulnerable Components + +### Dependency Management +- [ ] Dependencies up to date +- [ ] No known CVEs in dependencies +- [ ] Automated vulnerability scanning +- [ ] Lock files committed (package-lock, yarn.lock) + +### Update Process +- [ ] Regular dependency updates scheduled +- [ ] Security updates prioritized +- [ ] Breaking changes tested before deploy + +--- + +## A07:2021 - Authentication Failures + +### Password Policies +- [ ] Minimum length >= 8 characters +- [ ] No common password check +- [ ] Breach database check (optional) +- [ ] Account lockout after failures + +### Multi-Factor Authentication +- [ ] MFA available for sensitive accounts +- [ ] MFA recovery process secure +- [ ] TOTP/WebAuthn preferred over SMS + +### Session Management +- [ ] Strong session IDs (>=128 bits) +- [ ] Session regeneration on privilege change +- [ ] Secure session storage + +--- + +## A08:2021 - Software Integrity Failures + +### CI/CD Security +- [ ] Build pipeline secured +- [ ] Dependency sources verified +- [ ] Signed commits (optional) +- [ ] Artifact integrity verified + +### Deserialization +- [ ] No unsafe deserialization of user data +- [ ] Type checking before deserialization +- [ ] Integrity checks on serialized data + +--- + +## A09:2021 - Logging & Monitoring Failures + +### Logging +- [ ] Authentication events logged +- [ ] Access control failures logged +- [ ] Input validation failures logged +- [ ] Sensitive data NOT logged + +### Monitoring +- [ ] Alerts for suspicious activity +- [ ] Log aggregation implemented +- [ ] Incident response plan exists + +--- + +## A10:2021 - Server-Side Request Forgery + +### URL Validation +- [ ] User-supplied URLs validated +- [ ] Allowlist of permitted domains +- [ ] No access to internal services +- [ ] DNS rebinding prevented + +### Network Segmentation +- [ ] Internal services not exposed +- [ ] Firewall rules block unnecessary traffic + +--- + +## Severity Rating Guide + +| Severity | CVSS Score | Examples | +|----------|------------|----------| +| Critical | 9.0-10.0 | RCE, Auth bypass, Data breach | +| High | 7.0-8.9 | SQL injection, Privilege escalation | +| Medium | 4.0-6.9 | XSS, CSRF, Info disclosure | +| Low | 0.1-3.9 | Minor info leak, Missing headers | + +--- + +## References + +- [OWASP Top 10](https://owasp.org/Top10/) +- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) diff --git a/src/modules/bmm/workflows/testarch/security-audit/security-report.template.md b/src/modules/bmm/workflows/testarch/security-audit/security-report.template.md new file mode 100644 index 00000000..7cab9672 --- /dev/null +++ b/src/modules/bmm/workflows/testarch/security-audit/security-report.template.md @@ -0,0 +1,194 @@ +# Security Audit Report + +**Project:** {{project_name}} +**Date:** {{date}} +**Scope:** {{audit_scope}} +**Auditor:** {{user_name}} + TEA Agent + +--- + +## Executive Summary + +{{executive_summary}} + +--- + +## Risk Summary + +| Severity | Count | Status | +|----------|-------|--------| +| Critical | {{critical_count}} | {{critical_status}} | +| High | {{high_count}} | {{high_status}} | +| Medium | {{medium_count}} | {{medium_status}} | +| Low | {{low_count}} | {{low_status}} | + +**Overall Risk Level:** {{overall_risk}} + +--- + +## Technology Stack + +| Component | Technology | Version | +|-----------|------------|---------| +| Framework | {{framework}} | {{framework_version}} | +| Language | {{language}} | {{language_version}} | +| Database | {{database}} | {{database_version}} | +| Authentication | {{auth_method}} | - | + +--- + +## Critical Findings + +{{#each critical_findings}} +### {{this.id}}: {{this.title}} + +**Severity:** CRITICAL +**Category:** {{this.category}} +**Location:** `{{this.location}}` + +**Description:** +{{this.description}} + +**Evidence:** +``` +{{this.evidence}} +``` + +**Impact:** +{{this.impact}} + +**Remediation:** +{{this.remediation}} + +**References:** +- {{this.references}} + +--- +{{/each}} + +## High Severity Findings + +{{#each high_findings}} +### {{this.id}}: {{this.title}} + +**Severity:** HIGH +**Category:** {{this.category}} +**Location:** `{{this.location}}` + +**Description:** +{{this.description}} + +**Remediation:** +{{this.remediation}} + +--- +{{/each}} + +## Medium Severity Findings + +{{#each medium_findings}} +### {{this.id}}: {{this.title}} + +**Severity:** MEDIUM +**Category:** {{this.category}} +**Location:** `{{this.location}}` + +**Description:** +{{this.description}} + +**Remediation:** +{{this.remediation}} + +--- +{{/each}} + +## Low Severity Findings + +{{#each low_findings}} +### {{this.id}}: {{this.title}} + +**Severity:** LOW +**Category:** {{this.category}} + +**Description:** +{{this.description}} + +**Remediation:** +{{this.remediation}} + +--- +{{/each}} + +## Dependency Vulnerabilities + +| Package | Version | CVE | Severity | Fix Version | +|---------|---------|-----|----------|-------------| +{{#each dependency_vulns}} +| {{this.package}} | {{this.version}} | {{this.cve}} | {{this.severity}} | {{this.fix_version}} | +{{/each}} + +--- + +## Secret Detection Results + +| Type | File | Line | Status | +|------|------|------|--------| +{{#each secrets_found}} +| {{this.type}} | {{this.file}} | {{this.line}} | {{this.status}} | +{{/each}} + +--- + +## OWASP Coverage + +| Category | Status | Findings | +|----------|--------|----------| +| A01 - Broken Access Control | {{a01_status}} | {{a01_count}} | +| A02 - Cryptographic Failures | {{a02_status}} | {{a02_count}} | +| A03 - Injection | {{a03_status}} | {{a03_count}} | +| A04 - Insecure Design | {{a04_status}} | {{a04_count}} | +| A05 - Security Misconfiguration | {{a05_status}} | {{a05_count}} | +| A06 - Vulnerable Components | {{a06_status}} | {{a06_count}} | +| A07 - Authentication Failures | {{a07_status}} | {{a07_count}} | +| A08 - Software Integrity Failures | {{a08_status}} | {{a08_count}} | +| A09 - Logging & Monitoring Failures | {{a09_status}} | {{a09_count}} | +| A10 - SSRF | {{a10_status}} | {{a10_count}} | + +--- + +## Recommendations + +### Immediate Actions (Critical/High) + +1. {{immediate_action_1}} +2. {{immediate_action_2}} +3. {{immediate_action_3}} + +### Short-term Actions (Medium) + +1. {{short_term_action_1}} +2. {{short_term_action_2}} + +### Long-term Improvements (Low/Hardening) + +1. {{long_term_action_1}} +2. {{long_term_action_2}} + +--- + +## Appendix A: Tools Used + +- Dependency Scanner: {{dep_scanner}} +- Secret Scanner: {{secret_scanner}} +- Static Analysis: {{static_analysis}} + +## Appendix B: Files Reviewed + +{{#each files_reviewed}} +- `{{this}}` +{{/each}} + +--- + +**Report Generated:** {{timestamp}} +**Next Audit Recommended:** {{next_audit_date}} diff --git a/src/modules/bmm/workflows/testarch/security-audit/workflow.yaml b/src/modules/bmm/workflows/testarch/security-audit/workflow.yaml new file mode 100644 index 00000000..539a4eef --- /dev/null +++ b/src/modules/bmm/workflows/testarch/security-audit/workflow.yaml @@ -0,0 +1,40 @@ +# Security Audit Workflow +name: testarch-security-audit +description: "Comprehensive security audit covering OWASP Top 10, dependency vulnerabilities, secret detection, and authentication/authorization review" +author: "BMAD" +version: "1.0.0" + +# Configuration sources +config_source: "{project-root}/_bmad/bmm/config.yaml" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +user_skill_level: "{config_source}:user_skill_level" +document_output_language: "{config_source}:document_output_language" +planning_artifacts: "{config_source}:planning_artifacts" +implementation_artifacts: "{config_source}:implementation_artifacts" +output_folder: "{implementation_artifacts}" +date: system-generated + +# Workflow components +installed_path: "{project-root}/_bmad/bmm/workflows/testarch/security-audit" +instructions: "{installed_path}/instructions.md" +checklist: "{installed_path}/owasp-checklist.md" +report_template: "{installed_path}/security-report.template.md" + +# Input references +architecture_doc: "{planning_artifacts}/*architecture*.md" +project_context: "**/project-context.md" + +# Output +output_file: "{output_folder}/security-audit-report-{date}.md" + +# Audit scope options +audit_scopes: + - full # Complete security audit + - owasp # OWASP Top 10 focus + - deps # Dependency vulnerabilities only + - secrets # Secret detection only + - auth # Authentication/authorization only + - api # API security only + +standalone: true