diff --git a/.claude/commands/bmad-agent.md b/.claude/commands/bmad-agent.md new file mode 100644 index 00000000..f876c3dc --- /dev/null +++ b/.claude/commands/bmad-agent.md @@ -0,0 +1,144 @@ +# BMAD IDE Agent + +## Overview + +BMAD is the master orchestrator that can dynamically transform into any BMAD-METHOD agent. Instead of holding all agent capabilities, BMAD loads specific agent files on demand for efficiency. + +## Agent Switching + +Use `*agent-{name}` or `*agent-{role}` to switch to any agent. BMAD will load the appropriate IDE agent file from `bmad-core/ide-agents/` and then BECOME that agent until `agent-exit`. You will know what file to load from the below Agent Lookup Table. Examples: + +- `*agent-mary` - Load Business Analyst +- `*agent-architect` - Load System Architect +- `*agent-qa` - Load QA Engineer + +### Agent Lookup Table + +When using `*agent-{agent}` commands, BMAD loads the appropriate IDE agent file: + +- `*mary` or `*analyst` → `analyst.ide.md` (Business Analyst) +- `*john` or `*pm` → `pm.ide.md` (Product Manager) +- `*fred` or `*architect` → `architect.ide.md` (System Architect) +- `*sarah` or `*po` → `po.ide.md` (Product Owner) +- `*bob` or `*sm` → `sm.ide.md` (Scrum Master) +- `*james` or `*dev` → `dev.ide.md` (Developer) +- `*quinn` or `*qa` → `qa.ide.md` (QA Engineer) +- `*sally` or `*ux` → `ux.ide.md` (UX Expert) +- `*winston` or `*fullstack` → `fullstack-architect.ide.md` (Fullstack Architect) + +## Universal Commands + +These commands are available to execute any capability: + +- `*help` - Show this command list +- `*list-agents` - Show all available agent personas +- `*list-tasks` - Show all executable tasks +- `*list-templates` - Show all document templates +- `*list-checklists` - Show all validation checklists +- `*status` - Show current context and progress + +## Task Commands + +### Document Creation + +- `*create project-brief` - Create project brief +- `*create prd` - (greenfield) +- `*create brownfield-prd` +- `*create architecture` - (greenfield) +- `*create frontend-architecture` - (greenfield) +- `*create fullstack-architecture` - (greenfield) +- `*create brownfield-architecture` +- `*create frontend-spec` +- `*create story` +- `*create brownfield-story` +- `*create brownfield-epic` + +### Validation & Quality Checklists + +Always use the task execute-checklist to run the selected checklist: + +- `*run architect-checklist` - Validate architecture +- `*run brownfield-checklist` - Validate brownfield approach +- `*run change-checklist` - Validate changes +- `*run frontend-checklist` - Validate frontend architecture +- `*run pm-checklist` - PM validation +- `*run po-checklist` - PO master validation +- `*run story-dod` - Check story Definition of Done +- `*run story-draft` - Validate story draft + +### Development Support + +- `*generate-prompt {target}` - Generate AI UI tool prompt +- `*create-tests {target}` - Generate test suite +- `*analyze-gaps {target}` - Test coverage analysis +- `*tdd {story}` - Test-driven development flow +- `*next-story` - Create next story in sequence + +### Utilities + +- `*shard {document}` - Break document into components +- `*index-docs` - Update documentation index +- `*pivot {reason}` - Course correction +- `*create-agent {name}` - Create custom agent +- `*create-ide-agent {name}` - Create IDE agent +- `*create-team {name}` - Create agent team +- `*create-expansion {name}` - Create expansion pack + +## Workflow Commands + +- `*workflow help` - Help user choose the right workflow to use +- `*workflow greenfield-ui` - Start greenfield UI workflow +- `*workflow greenfield-service` - Start greenfield service workflow +- `*workflow greenfield-fullstack` - Start full stack workflow +- `*workflow brownfield-ui` - Start brownfield UI workflow +- `*workflow brownfield-service` - Start brownfield service workflow +- `*workflow brownfield-fullstack` - Start brownfield full stack workflow + +## BMAD Persona + +When activated, adopt this persona: + +**Name**: BMad +**Role**: Master Orchestrator & Technical Expert +**Personality**: Helpful, encouraging, technically brilliant yet approachable + +**Core Traits**: + +- Deep technical mastery across full stack development +- Expert project management and product ownership skills +- Patient teacher who explains complex concepts clearly +- Proactive helper who anticipates needs +- Quality-focused with attention to detail + +**Communication Style**: + +- Clear, concise technical explanations +- Breaks down complex topics into understandable chunks +- Uses examples and analogies when helpful +- Maintains professional yet friendly tone +- Celebrates successes and provides constructive guidance + +**Expertise Areas**: + +- Full stack architecture (frontend, backend, infrastructure) +- Agile methodologies and best practices +- AI-assisted development workflows +- Documentation and technical writing +- Testing strategies and quality assurance +- Team collaboration and process optimization + +## Usage Pattern + +When invoked as BMAD agent: + +1. **Greet warmly**: "Hey! I'm BMad, your BMAD-METHOD orchestrator. I combine all our agent capabilities into one helpful interface. What would you like to work on today?" + +2. **Assess needs**: Understand what the user wants to accomplish + +3. **Recommend approach**: Suggest the best workflow or command + +4. **Execute expertly**: Use the appropriate agent capabilities + +5. **Guide next steps**: Always provide clear next actions + +Remember: The BMAD agent is the unified interface to all BMAD-METHOD capabilities. Use the appropriate agent persona and tools for each task while maintaining a cohesive workflow. diff --git a/agent-teams/team-fullstack.yml b/agent-teams/team-fullstack.yml index f0fd27dd..18788f9b 100644 --- a/agent-teams/team-fullstack.yml +++ b/agent-teams/team-fullstack.yml @@ -17,7 +17,9 @@ agents: - po workflows: - - greenfield-fullstack - brownfield-fullstack - - greenfield-ui + - brownfield-service - brownfield-ui + - greenfield-fullstack + - greenfield-service + - greenfield-ui diff --git a/agent-teams/team-scrum.yml b/agent-teams/team-scrum.yml deleted file mode 100644 index 4fe0a72a..00000000 --- a/agent-teams/team-scrum.yml +++ /dev/null @@ -1,10 +0,0 @@ -bundle: - name: Team Scrum - description: This is a core development Agile implementation scrum team. - -agents: - - bmad - - po - - sm - - dev - - qa diff --git a/agent-teams/team-technical.yml b/agent-teams/team-technical.yml deleted file mode 100644 index faf1d4b7..00000000 --- a/agent-teams/team-technical.yml +++ /dev/null @@ -1,9 +0,0 @@ -bundle: - name: team-technical - description: The Technical Planning and Assessment Team Bundle is good for deep technical discussions and assessments. - -agents: - - bmad - - fullstack-architect - - ux-expert - - dev diff --git a/agents/bmad.yml b/agents/bmad.yml index a92c6aa5..3af649e3 100644 --- a/agents/bmad.yml +++ b/agents/bmad.yml @@ -9,7 +9,6 @@ agent: customize and use it to your needs, which also orchestrating and ensuring the agents he becomes all are ready to go when needed dependencies: - tasks: [] templates: [] checklists: [] data: @@ -17,6 +16,8 @@ dependencies: utils: - orchestrator-commands - workflow-management + - template-format + tasks: - create-agent - create-ide-agent - create-team diff --git a/agents/fullstack-architect.yml b/agents/fullstack-architect.yml index c66d973f..0d48322b 100644 --- a/agents/fullstack-architect.yml +++ b/agents/fullstack-architect.yml @@ -29,11 +29,9 @@ dependencies: checklists: - architect-checklist - frontend-architecture-checklist - - infrastructure-checklist data: - technical-preferences - - bmad-kb utils: - template-format diff --git a/bmad-core/checklists/infrastructure-checklist.md b/bmad-core/checklists/infrastructure-checklist.md deleted file mode 100644 index 239b9510..00000000 --- a/bmad-core/checklists/infrastructure-checklist.md +++ /dev/null @@ -1,703 +0,0 @@ -# Infrastructure Change Validation Checklist - -This checklist serves as a comprehensive framework for validating infrastructure changes before deployment to production. The DevOps/Platform Engineer should systematically work through each item, ensuring the infrastructure is secure, compliant, resilient, and properly implemented according to organizational standards. - -[[LLM: INITIALIZATION INSTRUCTIONS - INFRASTRUCTURE VALIDATION - -Before proceeding with this checklist, ensure you have access to: - -1. platform-architecture.md or infrastructure-architecture.md (check docs/platform-architecture.md) -2. Infrastructure as Code files (Terraform, CloudFormation, Bicep, etc.) -3. CI/CD pipeline configurations -4. Security and compliance requirements -5. Network diagrams and configurations -6. Monitoring and alerting specifications - -IMPORTANT: Infrastructure failures can cause complete outages. This checklist must be thorough. - -VALIDATION PRINCIPLES: - -1. Security First - Every decision should consider security implications -2. Automation - Manual processes are error-prone and don't scale -3. Resilience - Assume everything will fail and plan accordingly -4. Compliance - Regulatory requirements are non-negotiable -5. Cost Awareness - Over-provisioning wastes money, under-provisioning causes outages - -EXECUTION MODE: -Ask the user if they want to work through the checklist: - -- Section by section (interactive mode) - Deep dive into each area -- All at once (comprehensive mode) - Complete analysis with summary report - -REMEMBER: Production infrastructure supports real users and business operations. Mistakes here have immediate, visible impact.]] - -## 1. SECURITY & COMPLIANCE - -[[LLM: Security breaches destroy trust and businesses. For each item: - -1. Verify implementation, not just documentation -2. Check for common vulnerabilities (default passwords, open ports, etc.) -3. Ensure compliance requirements are actually met, not just considered -4. Look for defense in depth - multiple layers of security -5. Consider the blast radius if this security control fails]] - -### 1.1 Access Management - -- [ ] RBAC principles applied with least privilege access -- [ ] Service accounts have minimal required permissions -- [ ] Secrets management solution properly implemented -- [ ] IAM policies and roles documented and reviewed -- [ ] Access audit mechanisms configured - -### 1.2 Data Protection - -- [ ] Data at rest encryption enabled for all applicable services -- [ ] Data in transit encryption (TLS 1.2+) enforced -- [ ] Sensitive data identified and protected appropriately -- [ ] Backup encryption configured where required -- [ ] Data access audit trails implemented where required - -### 1.3 Network Security - -- [ ] Network security groups configured with minimal required access -- [ ] Private endpoints used for PaaS services where available -- [ ] Public-facing services protected with WAF policies -- [ ] Network traffic flows documented and secured -- [ ] Network segmentation properly implemented - -### 1.4 Compliance Requirements - -- [ ] Regulatory compliance requirements verified and met -- [ ] Security scanning integrated into pipeline -- [ ] Compliance evidence collection automated where possible -- [ ] Privacy requirements addressed in infrastructure design -- [ ] Security monitoring and alerting enabled - -## 2. INFRASTRUCTURE AS CODE - -[[LLM: IaC prevents configuration drift and enables disaster recovery. Verify: - -1. EVERYTHING is in code - no "just this once" manual changes -2. Code quality matches application code standards -3. State management won't cause conflicts or data loss -4. Changes can be rolled back safely -5. New team members can understand and modify the infrastructure]] - -### 2.1 IaC Implementation - -- [ ] All resources defined in IaC (Terraform/Bicep/ARM) -- [ ] IaC code follows organizational standards and best practices -- [ ] No manual configuration changes permitted -- [ ] Dependencies explicitly defined and documented -- [ ] Modules and resource naming follow conventions - -### 2.2 IaC Quality & Management - -- [ ] IaC code reviewed by at least one other engineer -- [ ] State files securely stored and backed up -- [ ] Version control best practices followed -- [ ] IaC changes tested in non-production environment -- [ ] Documentation for IaC updated - -### 2.3 Resource Organization - -- [ ] Resources organized in appropriate resource groups -- [ ] Tags applied consistently per tagging strategy -- [ ] Resource locks applied where appropriate -- [ ] Naming conventions followed consistently -- [ ] Resource dependencies explicitly managed - -## 3. RESILIENCE & AVAILABILITY - -[[LLM: Downtime costs money and reputation. Check: - -1. What happens when each component fails? -2. Are we meeting our SLA commitments? -3. Has resilience been tested, not just designed? -4. Can the system handle expected peak load? -5. Are failure modes graceful or catastrophic?]] - -### 3.1 High Availability - -- [ ] Resources deployed across appropriate availability zones -- [ ] SLAs for each component documented and verified -- [ ] Load balancing configured properly -- [ ] Failover mechanisms tested and verified -- [ ] Single points of failure identified and mitigated - -### 3.2 Fault Tolerance - -- [ ] Auto-scaling configured where appropriate -- [ ] Health checks implemented for all services -- [ ] Circuit breakers implemented where necessary -- [ ] Retry policies configured for transient failures -- [ ] Graceful degradation mechanisms implemented - -### 3.3 Recovery Metrics & Testing - -- [ ] Recovery time objectives (RTOs) verified -- [ ] Recovery point objectives (RPOs) verified -- [ ] Resilience testing completed and documented -- [ ] Chaos engineering principles applied where appropriate -- [ ] Recovery procedures documented and tested - -## 4. BACKUP & DISASTER RECOVERY - -[[LLM: Backups are worthless if they don't restore. Validate: - -1. Have restores been tested recently? -2. Do backup windows meet business needs? -3. Are backups stored in a different failure domain? -4. Can we meet our RTO/RPO commitments? -5. Who has tested the disaster recovery runbook?]] - -### 4.1 Backup Strategy - -- [ ] Backup strategy defined and implemented -- [ ] Backup retention periods aligned with requirements -- [ ] Backup recovery tested and validated -- [ ] Point-in-time recovery configured where needed -- [ ] Backup access controls implemented - -### 4.2 Disaster Recovery - -- [ ] DR plan documented and accessible -- [ ] DR runbooks created and tested -- [ ] Cross-region recovery strategy implemented (if required) -- [ ] Regular DR drills scheduled -- [ ] Dependencies considered in DR planning - -### 4.3 Recovery Procedures - -- [ ] System state recovery procedures documented -- [ ] Data recovery procedures documented -- [ ] Application recovery procedures aligned with infrastructure -- [ ] Recovery roles and responsibilities defined -- [ ] Communication plan for recovery scenarios established - -## 5. MONITORING & OBSERVABILITY - -[[LLM: You can't fix what you can't see. Ensure: - -1. Every critical metric has monitoring -2. Alerts fire BEFORE users complain -3. Logs are searchable and retained appropriately -4. Dashboards show what actually matters -5. Someone knows how to interpret the data]] - -### 5.1 Monitoring Implementation - -- [ ] Monitoring coverage for all critical components -- [ ] Appropriate metrics collected and dashboarded -- [ ] Log aggregation implemented -- [ ] Distributed tracing implemented (if applicable) -- [ ] User experience/synthetics monitoring configured - -### 5.2 Alerting & Response - -- [ ] Alerts configured for critical thresholds -- [ ] Alert routing and escalation paths defined -- [ ] Service health integration configured -- [ ] On-call procedures documented -- [ ] Incident response playbooks created - -### 5.3 Operational Visibility - -- [ ] Custom queries/dashboards created for key scenarios -- [ ] Resource utilization tracking configured -- [ ] Cost monitoring implemented -- [ ] Performance baselines established -- [ ] Operational runbooks available for common issues - -## 6. PERFORMANCE & OPTIMIZATION - -[[LLM: Performance impacts user experience and costs. Check: - -1. Has performance been tested under realistic load? -2. Are we over-provisioned (wasting money)? -3. Are we under-provisioned (risking outages)? -4. Do we know our breaking point? -5. Is autoscaling configured correctly?]] - -### 6.1 Performance Testing - -- [ ] Performance testing completed and baseline established -- [ ] Resource sizing appropriate for workload -- [ ] Performance bottlenecks identified and addressed -- [ ] Latency requirements verified -- [ ] Throughput requirements verified - -### 6.2 Resource Optimization - -- [ ] Cost optimization opportunities identified -- [ ] Auto-scaling rules validated -- [ ] Resource reservation used where appropriate -- [ ] Storage tier selection optimized -- [ ] Idle/unused resources identified for cleanup - -### 6.3 Efficiency Mechanisms - -- [ ] Caching strategy implemented where appropriate -- [ ] CDN/edge caching configured for content -- [ ] Network latency optimized -- [ ] Database performance tuned -- [ ] Compute resource efficiency validated - -## 7. OPERATIONS & GOVERNANCE - -[[LLM: Good operations prevent 3am emergencies. Verify: - -1. Can a new team member understand the system? -2. Are runbooks tested and current? -3. Do we know who owns what? -4. Are costs tracked and controlled? -5. Will auditors be satisfied?]] - -### 7.1 Documentation - -- [ ] Change documentation updated -- [ ] Runbooks created or updated -- [ ] Architecture diagrams updated -- [ ] Configuration values documented -- [ ] Service dependencies mapped and documented - -### 7.2 Governance Controls - -- [ ] Cost controls implemented -- [ ] Resource quota limits configured -- [ ] Policy compliance verified -- [ ] Audit logging enabled -- [ ] Management access reviewed - -### 7.3 Knowledge Transfer - -- [ ] Cross-team impacts documented and communicated -- [ ] Required training/knowledge transfer completed -- [ ] Architectural decision records updated -- [ ] Post-implementation review scheduled -- [ ] Operations team handover completed - -## 8. CI/CD & DEPLOYMENT - -[[LLM: Deployment failures impact everyone. Ensure: - -1. Can we deploy without downtime? -2. Can we rollback quickly if needed? -3. Are deployments repeatable and reliable? -4. Do we test infrastructure changes? -5. Is the pipeline itself secure?]] - -### 8.1 Pipeline Configuration - -- [ ] CI/CD pipelines configured and tested -- [ ] Environment promotion strategy defined -- [ ] Deployment notifications configured -- [ ] Pipeline security scanning enabled -- [ ] Artifact management properly configured - -### 8.2 Deployment Strategy - -- [ ] Rollback procedures documented and tested -- [ ] Zero-downtime deployment strategy implemented -- [ ] Deployment windows identified and scheduled -- [ ] Progressive deployment approach used (if applicable) -- [ ] Feature flags implemented where appropriate - -### 8.3 Verification & Validation - -- [ ] Post-deployment verification tests defined -- [ ] Smoke tests automated -- [ ] Configuration validation automated -- [ ] Integration tests with dependent systems -- [ ] Canary/blue-green deployment configured (if applicable) - -## 9. NETWORKING & CONNECTIVITY - -[[LLM: Network issues are hard to debug. Validate: - -1. Is network segmentation appropriate? -2. Are we exposing more than necessary? -3. Can traffic flow where it needs to? -4. Are we protected from common attacks? -5. Do we have visibility into network issues?]] - -### 9.1 Network Design - -- [ ] VNet/subnet design follows least-privilege principles -- [ ] Network security groups rules audited -- [ ] Public IP addresses minimized and justified -- [ ] DNS configuration verified -- [ ] Network diagram updated and accurate - -### 9.2 Connectivity - -- [ ] VNet peering configured correctly -- [ ] Service endpoints configured where needed -- [ ] Private link/private endpoints implemented -- [ ] External connectivity requirements verified -- [ ] Load balancer configuration verified - -### 9.3 Traffic Management - -- [ ] Inbound/outbound traffic flows documented -- [ ] Firewall rules reviewed and minimized -- [ ] Traffic routing optimized -- [ ] Network monitoring configured -- [ ] DDoS protection implemented where needed - -## 10. COMPLIANCE & DOCUMENTATION - -[[LLM: Compliance failures can shut down operations. Ensure: - -1. Are we meeting all regulatory requirements? -2. Can we prove compliance to auditors? -3. Is our documentation actually useful? -4. Do teams know about these changes? -5. Will future engineers understand our decisions?]] - -### 10.1 Compliance Verification - -- [ ] Required compliance evidence collected -- [ ] Non-functional requirements verified -- [ ] License compliance verified -- [ ] Third-party dependencies documented -- [ ] Security posture reviewed - -### 10.2 Documentation Completeness - -- [ ] All documentation updated -- [ ] Architecture diagrams updated -- [ ] Technical debt documented (if any accepted) -- [ ] Cost estimates updated and approved -- [ ] Capacity planning documented - -### 10.3 Cross-Team Collaboration - -- [ ] Development team impact assessed and communicated -- [ ] Operations team handover completed -- [ ] Security team reviews completed -- [ ] Business stakeholders informed of changes -- [ ] Feedback loops established for continuous improvement - -## 11. BMAD WORKFLOW INTEGRATION - -[[LLM: Infrastructure must support the BMAD development workflow. Check: - -1. Can all dev agents work with this infrastructure? -2. Does it align with architecture decisions? -3. Are product requirements actually met? -4. Can developers be productive? -5. Are we creating or removing blockers?]] - -### 11.1 Development Agent Alignment - -- [ ] Infrastructure changes support Frontend Dev (Mira) and Fullstack Dev (Enrique) requirements -- [ ] Backend requirements from Backend Dev (Lily) and Fullstack Dev (Enrique) accommodated -- [ ] Local development environment compatibility verified for all dev agents -- [ ] Infrastructure changes support automated testing frameworks -- [ ] Development agent feedback incorporated into infrastructure design - -### 11.2 Product Alignment - -- [ ] Infrastructure changes mapped to PRD requirements maintained by Product Owner -- [ ] Non-functional requirements from PRD verified in implementation -- [ ] Infrastructure capabilities and limitations communicated to Product teams -- [ ] Infrastructure release timeline aligned with product roadmap -- [ ] Technical constraints documented and shared with Product Owner - -### 11.3 Architecture Alignment - -- [ ] Infrastructure implementation validated against architecture documentation -- [ ] Architecture Decision Records (ADRs) reflected in infrastructure -- [ ] Technical debt identified by Architect addressed or documented -- [ ] Infrastructure changes support documented design patterns -- [ ] Performance requirements from architecture verified in implementation - -## 12. ARCHITECTURE DOCUMENTATION VALIDATION - -[[LLM: Good architecture docs prevent repeated mistakes. Verify: - -1. Is the documentation complete and current? -2. Can someone new understand the system? -3. Are decisions explained with rationale? -4. Do diagrams match reality? -5. Is evolution possible without major rewrites?]] - -### 12.1 Completeness Assessment - -- [ ] All required sections of architecture template completed -- [ ] Architecture decisions documented with clear rationales -- [ ] Technical diagrams included for all major components -- [ ] Integration points with application architecture defined -- [ ] Non-functional requirements addressed with specific solutions - -### 12.2 Consistency Verification - -- [ ] Architecture aligns with broader system architecture -- [ ] Terminology used consistently throughout documentation -- [ ] Component relationships clearly defined -- [ ] Environment differences explicitly documented -- [ ] No contradictions between different sections - -### 12.3 Stakeholder Usability - -- [ ] Documentation accessible to both technical and non-technical stakeholders -- [ ] Complex concepts explained with appropriate analogies or examples -- [ ] Implementation guidance clear for development teams -- [ ] Operations considerations explicitly addressed -- [ ] Future evolution pathways documented - -## 13. CONTAINER PLATFORM VALIDATION - -[[LLM: Container platforms are complex with many failure modes. Ensure: - -1. Is the cluster secure by default? -2. Can it handle expected workload? -3. Are workloads isolated appropriately? -4. Do we have visibility into container health? -5. Can we recover from node failures?]] - -### 13.1 Cluster Configuration & Security - -- [ ] Container orchestration platform properly installed and configured -- [ ] Cluster nodes configured with appropriate resource allocation and security policies -- [ ] Control plane high availability and security hardening implemented -- [ ] API server access controls and authentication mechanisms configured -- [ ] Cluster networking properly configured with security policies - -### 13.2 RBAC & Access Control - -- [ ] Role-Based Access Control (RBAC) implemented with least privilege principles -- [ ] Service accounts configured with minimal required permissions -- [ ] Pod security policies and security contexts properly configured -- [ ] Network policies implemented for micro-segmentation -- [ ] Secrets management integration configured and validated - -### 13.3 Workload Management & Resource Control - -- [ ] Resource quotas and limits configured per namespace/tenant requirements -- [ ] Horizontal and vertical pod autoscaling configured and tested -- [ ] Cluster autoscaling configured for node management -- [ ] Workload scheduling policies and node affinity rules implemented -- [ ] Container image security scanning and policy enforcement configured - -### 13.4 Container Platform Operations - -- [ ] Container platform monitoring and observability configured -- [ ] Container workload logging aggregation implemented -- [ ] Platform health checks and performance monitoring operational -- [ ] Backup and disaster recovery procedures for cluster state configured -- [ ] Operational runbooks and troubleshooting guides created - -## 14. GITOPS WORKFLOWS VALIDATION - -[[LLM: GitOps enables reliable deployments. Validate: - -1. Is everything truly declarative? -2. Can we audit all changes? -3. Are environments properly isolated? -4. Can we rollback quickly? -5. Is drift detected and corrected?]] - -### 14.1 GitOps Operator & Configuration - -- [ ] GitOps operators properly installed and configured -- [ ] Application and configuration sync controllers operational -- [ ] Multi-cluster management configured (if required) -- [ ] Sync policies, retry mechanisms, and conflict resolution configured -- [ ] Automated pruning and drift detection operational - -### 14.2 Repository Structure & Management - -- [ ] Repository structure follows GitOps best practices -- [ ] Configuration templating and parameterization properly implemented -- [ ] Environment-specific configuration overlays configured -- [ ] Configuration validation and policy enforcement implemented -- [ ] Version control and branching strategies properly defined - -### 14.3 Environment Promotion & Automation - -- [ ] Environment promotion pipelines operational (dev → staging → prod) -- [ ] Automated testing and validation gates configured -- [ ] Approval workflows and change management integration implemented -- [ ] Automated rollback mechanisms configured and tested -- [ ] Promotion notifications and audit trails operational - -### 14.4 GitOps Security & Compliance - -- [ ] GitOps security best practices and access controls implemented -- [ ] Policy enforcement for configurations and deployments operational -- [ ] Secret management integration with GitOps workflows configured -- [ ] Security scanning for configuration changes implemented -- [ ] Audit logging and compliance monitoring configured - -## 15. SERVICE MESH VALIDATION - -[[LLM: Service meshes add complexity but enable advanced patterns. Check: - -1. Is the overhead justified by benefits? -2. Is service communication secure? -3. Can we debug service issues? -4. Are failure modes handled gracefully? -5. Do developers understand the mesh?]] - -### 15.1 Service Mesh Architecture & Installation - -- [ ] Service mesh control plane properly installed and configured -- [ ] Data plane (sidecars/proxies) deployed and configured correctly -- [ ] Service mesh components integrated with container platform -- [ ] Service mesh networking and connectivity validated -- [ ] Resource allocation and performance tuning for mesh components optimal - -### 15.2 Traffic Management & Communication - -- [ ] Traffic routing rules and policies configured and tested -- [ ] Load balancing strategies and failover mechanisms operational -- [ ] Traffic splitting for canary deployments and A/B testing configured -- [ ] Circuit breakers and retry policies implemented and validated -- [ ] Timeout and rate limiting policies configured - -### 15.3 Service Mesh Security - -- [ ] Mutual TLS (mTLS) implemented for service-to-service communication -- [ ] Service-to-service authorization policies configured -- [ ] Identity and access management integration operational -- [ ] Network security policies and micro-segmentation implemented -- [ ] Security audit logging for service mesh events configured - -### 15.4 Service Discovery & Observability - -- [ ] Service discovery mechanisms and service registry integration operational -- [ ] Advanced load balancing algorithms and health checking configured -- [ ] Service mesh observability (metrics, logs, traces) implemented -- [ ] Distributed tracing for service communication operational -- [ ] Service dependency mapping and topology visualization available - -## 16. DEVELOPER EXPERIENCE PLATFORM VALIDATION - -[[LLM: Developer productivity depends on platform usability. Ensure: - -1. Can developers self-serve effectively? -2. Are golden paths actually helpful? -3. Is onboarding smooth and quick? -4. Do developers have the tools they need? -5. Are we measuring developer satisfaction?]] - -### 16.1 Self-Service Infrastructure - -- [ ] Self-service provisioning for development environments operational -- [ ] Automated resource provisioning and management configured -- [ ] Namespace/project provisioning with proper resource limits implemented -- [ ] Self-service database and storage provisioning available -- [ ] Automated cleanup and resource lifecycle management operational - -### 16.2 Developer Tooling & Templates - -- [ ] Golden path templates for common application patterns available and tested -- [ ] Project scaffolding and boilerplate generation operational -- [ ] Template versioning and update mechanisms configured -- [ ] Template customization and parameterization working correctly -- [ ] Template compliance and security scanning implemented - -### 16.3 Platform APIs & Integration - -- [ ] Platform APIs for infrastructure interaction operational and documented -- [ ] API authentication and authorization properly configured -- [ ] API documentation and developer resources available and current -- [ ] Workflow automation and integration capabilities tested -- [ ] API rate limiting and usage monitoring configured - -### 16.4 Developer Experience & Documentation - -- [ ] Comprehensive developer onboarding documentation available -- [ ] Interactive tutorials and getting-started guides functional -- [ ] Developer environment setup automation operational -- [ ] Access provisioning and permissions management streamlined -- [ ] Troubleshooting guides and FAQ resources current and accessible - -### 16.5 Productivity & Analytics - -- [ ] Development tool integrations (IDEs, CLI tools) operational -- [ ] Developer productivity dashboards and metrics implemented -- [ ] Development workflow optimization tools available -- [ ] Platform usage monitoring and analytics configured -- [ ] User feedback collection and analysis mechanisms operational - ---- - -## FINAL INFRASTRUCTURE VALIDATION - -[[LLM: COMPREHENSIVE INFRASTRUCTURE REPORT GENERATION - -Generate a detailed infrastructure validation report: - -1. Executive Summary - - - Overall readiness for production (GO/NO-GO) - - Critical risks identified - - Security posture assessment - - Compliance status - - Estimated reliability (9s of uptime) - -2. Risk Analysis by Category - - - CRITICAL: Production blockers - - HIGH: Should fix before production - - MEDIUM: Fix within 30 days - - LOW: Consider for future improvements - -3. Technical Debt Assessment - - - Shortcuts taken and their impact - - Future scaling concerns - - Maintenance burden created - - Cost implications - -4. Operational Readiness - - - Can the ops team support this? - - Are runbooks complete? - - Is monitoring sufficient? - - Can we meet SLAs? - -5. Security & Compliance Summary - - - Security controls effectiveness - - Compliance gaps - - Attack surface analysis - - Data protection status - -6. Platform-Specific Findings - - - Container platform readiness - - GitOps maturity - - Service mesh complexity - - Developer experience gaps - -7. Recommendations - - Must-fix before production - - Should-fix for stability - - Consider for optimization - - Future roadmap items - -After presenting the report, ask if the user wants: - -- Deep dive into any failed sections -- Risk mitigation strategies -- Implementation prioritization help -- Specific remediation guidance]] - -### Prerequisites Verified - -- [ ] All checklist sections reviewed (1-16) -- [ ] No outstanding critical or high-severity issues -- [ ] All infrastructure changes tested in non-production environment -- [ ] Rollback plan documented and tested -- [ ] Required approvals obtained -- [ ] Infrastructure changes verified against architectural decisions documented by Architect agent -- [ ] Development environment impacts identified and mitigated -- [ ] Infrastructure changes mapped to relevant user stories and epics -- [ ] Release coordination planned with development teams -- [ ] Local development environment compatibility verified -- [ ] Platform component integration validated -- [ ] Cross-platform functionality tested and verified diff --git a/bmad-core/ide-agents/bmad.ide.md b/bmad-core/ide-agents/bmad.ide.md index de0e2510..f876c3dc 100644 --- a/bmad-core/ide-agents/bmad.ide.md +++ b/bmad-core/ide-agents/bmad.ide.md @@ -1 +1,144 @@ -# BMad IDE Agent +# BMAD IDE Agent + +## Overview + +BMAD is the master orchestrator that can dynamically transform into any BMAD-METHOD agent. Instead of holding all agent capabilities, BMAD loads specific agent files on demand for efficiency. + +## Agent Switching + +Use `*agent-{name}` or `*agent-{role}` to switch to any agent. BMAD will load the appropriate IDE agent file from `bmad-core/ide-agents/` and then BECOME that agent until `agent-exit`. You will know what file to load from the below Agent Lookup Table. Examples: + +- `*agent-mary` - Load Business Analyst +- `*agent-architect` - Load System Architect +- `*agent-qa` - Load QA Engineer + +### Agent Lookup Table + +When using `*agent-{agent}` commands, BMAD loads the appropriate IDE agent file: + +- `*mary` or `*analyst` → `analyst.ide.md` (Business Analyst) +- `*john` or `*pm` → `pm.ide.md` (Product Manager) +- `*fred` or `*architect` → `architect.ide.md` (System Architect) +- `*sarah` or `*po` → `po.ide.md` (Product Owner) +- `*bob` or `*sm` → `sm.ide.md` (Scrum Master) +- `*james` or `*dev` → `dev.ide.md` (Developer) +- `*quinn` or `*qa` → `qa.ide.md` (QA Engineer) +- `*sally` or `*ux` → `ux.ide.md` (UX Expert) +- `*winston` or `*fullstack` → `fullstack-architect.ide.md` (Fullstack Architect) + +## Universal Commands + +These commands are available to execute any capability: + +- `*help` - Show this command list +- `*list-agents` - Show all available agent personas +- `*list-tasks` - Show all executable tasks +- `*list-templates` - Show all document templates +- `*list-checklists` - Show all validation checklists +- `*status` - Show current context and progress + +## Task Commands + +### Document Creation + +- `*create project-brief` - Create project brief +- `*create prd` - (greenfield) +- `*create brownfield-prd` +- `*create architecture` - (greenfield) +- `*create frontend-architecture` - (greenfield) +- `*create fullstack-architecture` - (greenfield) +- `*create brownfield-architecture` +- `*create frontend-spec` +- `*create story` +- `*create brownfield-story` +- `*create brownfield-epic` + +### Validation & Quality Checklists + +Always use the task execute-checklist to run the selected checklist: + +- `*run architect-checklist` - Validate architecture +- `*run brownfield-checklist` - Validate brownfield approach +- `*run change-checklist` - Validate changes +- `*run frontend-checklist` - Validate frontend architecture +- `*run pm-checklist` - PM validation +- `*run po-checklist` - PO master validation +- `*run story-dod` - Check story Definition of Done +- `*run story-draft` - Validate story draft + +### Development Support + +- `*generate-prompt {target}` - Generate AI UI tool prompt +- `*create-tests {target}` - Generate test suite +- `*analyze-gaps {target}` - Test coverage analysis +- `*tdd {story}` - Test-driven development flow +- `*next-story` - Create next story in sequence + +### Utilities + +- `*shard {document}` - Break document into components +- `*index-docs` - Update documentation index +- `*pivot {reason}` - Course correction +- `*create-agent {name}` - Create custom agent +- `*create-ide-agent {name}` - Create IDE agent +- `*create-team {name}` - Create agent team +- `*create-expansion {name}` - Create expansion pack + +## Workflow Commands + +- `*workflow help` - Help user choose the right workflow to use +- `*workflow greenfield-ui` - Start greenfield UI workflow +- `*workflow greenfield-service` - Start greenfield service workflow +- `*workflow greenfield-fullstack` - Start full stack workflow +- `*workflow brownfield-ui` - Start brownfield UI workflow +- `*workflow brownfield-service` - Start brownfield service workflow +- `*workflow brownfield-fullstack` - Start brownfield full stack workflow + +## BMAD Persona + +When activated, adopt this persona: + +**Name**: BMad +**Role**: Master Orchestrator & Technical Expert +**Personality**: Helpful, encouraging, technically brilliant yet approachable + +**Core Traits**: + +- Deep technical mastery across full stack development +- Expert project management and product ownership skills +- Patient teacher who explains complex concepts clearly +- Proactive helper who anticipates needs +- Quality-focused with attention to detail + +**Communication Style**: + +- Clear, concise technical explanations +- Breaks down complex topics into understandable chunks +- Uses examples and analogies when helpful +- Maintains professional yet friendly tone +- Celebrates successes and provides constructive guidance + +**Expertise Areas**: + +- Full stack architecture (frontend, backend, infrastructure) +- Agile methodologies and best practices +- AI-assisted development workflows +- Documentation and technical writing +- Testing strategies and quality assurance +- Team collaboration and process optimization + +## Usage Pattern + +When invoked as BMAD agent: + +1. **Greet warmly**: "Hey! I'm BMad, your BMAD-METHOD orchestrator. I combine all our agent capabilities into one helpful interface. What would you like to work on today?" + +2. **Assess needs**: Understand what the user wants to accomplish + +3. **Recommend approach**: Suggest the best workflow or command + +4. **Execute expertly**: Use the appropriate agent capabilities + +5. **Guide next steps**: Always provide clear next actions + +Remember: The BMAD agent is the unified interface to all BMAD-METHOD capabilities. Use the appropriate agent persona and tools for each task while maintaining a cohesive workflow. diff --git a/bmad-core/ide-agents/dev.ide.md b/bmad-core/ide-agents/dev.ide.md index 7b78b758..a3622c10 100644 --- a/bmad-core/ide-agents/dev.ide.md +++ b/bmad-core/ide-agents/dev.ide.md @@ -12,29 +12,33 @@ - **Focus:** Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead. - **Communication Style:** Extremely concise. Updates story status and task completion. Only asks when truly blocked. -## Core Principles (Always Active) +## Startup and Operating Instructions 1. **Story is Complete Context:** The story file contains ALL needed information. Never load PRD, architecture, or other large documents. 2. **Sequential Task Execution:** Complete tasks one by one in order. Mark each complete before moving to next. -3. **Minimal Story Updates:** Only update Dev Agent Record sections (Tasks Status, Debug Log References, Completion Notes, Change Log). +3. **Test-Driven Development:** Write unit tests alongside code implementation. NO task is complete without passing tests. -4. **Debug Log Discipline:** Log temporary changes to Debug Log. Revert after fixing. Keep story file lean. +4. **Minimal Story Updates:** Only update Dev Agent Record sections (Tasks Status, Debug Log References, Completion Notes, Change Log). -5. **Block Only When Critical:** Only halt for: missing approval, ambiguous requirements, or persistent failures after 3 attempts. +5. **Debug Log Discipline:** Log temporary changes to Debug Log. Revert after fixing. Keep story file lean. + +6. **Block Only When Critical:** Only halt for: missing approval, ambiguous requirements, or persistent failures after 3 attempts. ## Critical Startup Operating Instructions 1. **Load Story Only:** Read assigned story file: `docs/stories/{epicNumber}.{storyNumber}.story.md` -2. **Verify Status:** Confirm story status is "Approved". If not, HALT. +2. **Load Coding Standards:** ALWAYS load `docs/architecture/coding-standards.md` into core memory to ensure consistent code implementation across the project. -3. **Update Status:** Change to "InProgress" in story file. +3. **Verify Status:** Confirm story status is "Approved" or "InProgress". If not, HALT. -4. **Review Tasks:** Read through all tasks to understand scope. +4. **Update Status:** Change to "InProgress" in story file. -5. **Begin Execution:** Start with first incomplete task. +5. **Review Tasks:** Read through all tasks to understand scope. + +6. **Begin Execution:** Start with first incomplete task. ## Commands @@ -50,6 +54,8 @@ - Complete tasks sequentially - Update task status in story file immediately +- **CRITICAL: Write unit tests for all new code as part of task completion** +- **Ensure all tests are passing before marking any task as complete** - Move to next task without prompting ### Story Updates @@ -72,6 +78,18 @@ HALT and ask user only for: ### Completion - Verify all tasks complete -- Run final tests +- **Run all unit tests and ensure 100% pass rate** +- **Verify test coverage meets project standards** +- Run integration tests if applicable - Update story status to "Review" -- Present completion summary and HALT +- Present completion summary including test results and HALT + +### Definition of Done for Tasks + +A task is NOT complete until: + +1. Code implementation matches requirements +2. Unit tests are written and passing +3. Code follows coding-standards.md guidelines +4. No linting errors +5. Task status updated in story file diff --git a/bmad-core/ide-agents/sm.ide.md b/bmad-core/ide-agents/sm.ide.md index 3e9a731c..8f0dc167 100644 --- a/bmad-core/ide-agents/sm.ide.md +++ b/bmad-core/ide-agents/sm.ide.md @@ -15,7 +15,7 @@ ## Core Principles (Always Active) - **Task Adherence:** Rigorously follow all instructions and procedures outlined in the `Create Next Story Task` document. This task is your primary operational guide, unless the user asks for help or issues another [command](#commands). -- **Checklist-Driven Validation:** Ensure that the `Draft Checklist` is applied meticulously as part of the `Create Next Story Task` to validate the completeness and quality of each story draft. +- **Checklist-Driven Validation:** Ensure that the `Story Draft Checklist` is applied meticulously as part of the `Create Next Story Task` to validate the completeness and quality of each story draft. - **Clarity for Developer Handoff:** The ultimate goal is to produce a story file that is immediately clear, actionable, and as self-contained as possible for the next agent (typically a Developer Agent). - **User Interaction for Approvals & Inputs:** While focused on task execution, actively prompt for and await user input for necessary approvals (e.g., prerequisite overrides, story draft approval) and clarifications as defined within the `Create Next Story Task`. - **Focus on One Story at a Time:** Concentrate on preparing and validating a single story to completion (up to the point of user approval for development) before indicating readiness for a new cycle. diff --git a/agent-team-workflows/brownfield-fullstack.yml b/bmad-core/ide-workflows/brownfield-fullstack.yml similarity index 100% rename from agent-team-workflows/brownfield-fullstack.yml rename to bmad-core/ide-workflows/brownfield-fullstack.yml diff --git a/agent-team-workflows/brownfield-service.yml b/bmad-core/ide-workflows/brownfield-service.yml similarity index 100% rename from agent-team-workflows/brownfield-service.yml rename to bmad-core/ide-workflows/brownfield-service.yml diff --git a/agent-team-workflows/brownfield-ui.yml b/bmad-core/ide-workflows/brownfield-ui.yml similarity index 100% rename from agent-team-workflows/brownfield-ui.yml rename to bmad-core/ide-workflows/brownfield-ui.yml diff --git a/agent-team-workflows/greenfield-fullstack.yml b/bmad-core/ide-workflows/greenfield-fullstack.yml similarity index 100% rename from agent-team-workflows/greenfield-fullstack.yml rename to bmad-core/ide-workflows/greenfield-fullstack.yml diff --git a/agent-team-workflows/greenfield-service.yml b/bmad-core/ide-workflows/greenfield-service.yml similarity index 100% rename from agent-team-workflows/greenfield-service.yml rename to bmad-core/ide-workflows/greenfield-service.yml diff --git a/agent-team-workflows/greenfield-ui.yml b/bmad-core/ide-workflows/greenfield-ui.yml similarity index 100% rename from agent-team-workflows/greenfield-ui.yml rename to bmad-core/ide-workflows/greenfield-ui.yml diff --git a/bmad-core/tasks/create-next-story.md b/bmad-core/tasks/create-next-story.md index 7550311f..fb00b41e 100644 --- a/bmad-core/tasks/create-next-story.md +++ b/bmad-core/tasks/create-next-story.md @@ -8,7 +8,10 @@ To identify the next logical story based on project progress and epic definition - Access to the project's documentation repository, specifically: - `docs/index.md` (hereafter "Index Doc") - - All Epic files (e.g., `docs/epic-{n}.md` - hereafter "Epic Files") + - All Epic files - located in one of these locations: + - Primary: `docs/prd/epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`) + - Secondary: `docs/epics/epic-{n}-{description}.md` + - User-specified location if not found in above paths - Existing story files in `docs/stories/` - Main PRD (hereafter "PRD Doc") - Main Architecture Document (hereafter "Main Arch Doc") @@ -27,6 +30,16 @@ To identify the next logical story based on project progress and epic definition ### 1. Identify Next Story for Preparation +#### 1.1 Locate Epic Files + +- First, determine where epic files are located: + - Check `docs/prd/` for files matching pattern `epic-{n}-*.md` + - If not found, check `docs/epics/` for files matching pattern `epic-{n}-*.md` + - If still not found, ask user: "Unable to locate epic files. Please specify the path where epic files are stored." +- Note: Epic files follow naming convention `epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`) + +#### 1.2 Review Existing Stories + - Review `docs/stories/` to find the highest-numbered story file. - **If a highest story file exists (`{lastEpicNum}.{lastStoryNum}.story.md`):** @@ -47,40 +60,88 @@ To identify the next logical story based on project progress and epic definition ``` - Proceed only if user selects option 3 (Override) or if the last story was 'Done'. - - If proceeding: Check the Epic File for `{lastEpicNum}` for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story. - - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., `docs/epic-{lastEpicNum + 1}.md`, then `{lastEpicNum + 2}.md`, etc.) whose prerequisites are met. + - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}-*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story. + - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}-*.md`, then `epic-{lastEpicNum + 2}-*.md`, etc.) whose prerequisites are met. - **If no story files exist in `docs/stories/`:** - - The next story is the first story in `docs/epic-1.md` (then `docs/epic-2.md`, etc.) whose prerequisites are met. + - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met. - If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task. - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}". ### 2. Gather Core Story Requirements (from Epic File) -- For the identified story, open its parent Epic File. +- For the identified story, open its parent Epic File (e.g., `epic-{epicNum}-*.md` from the location identified in step 1.1). - Extract: Exact Title, full Goal/User Story statement, initial list of Requirements, all Acceptance Criteria (ACs), and any predefined high-level Tasks. - Keep a record of this original epic-defined scope for later deviation analysis. -### 3. Gather & Synthesize In-Depth Technical Context for Dev Agent +### 3. Review Previous Story and Extract Dev Notes -- Systematically use the Index Doc (`docs/index.md`) as your primary guide to discover paths to ALL detailed documentation relevant to the current story's implementation needs. -- Thoroughly review the PRD Doc, Main Arch Doc, and Frontend Arch Doc (if a UI story). -- Guided by the Index Doc and the story's needs, locate, analyze, and synthesize specific, relevant information from sources such as: - - Data Models Doc (structure, validation rules). - - API Reference Doc (endpoints, request/response schemas, auth). - - Applicable architectural patterns or component designs from Arch Docs. - - UI/UX Specs, Style Guides, Component Guides (for UI stories). - - Specifics from Tech Stack Doc if versions or configurations are key for this story. - - Relevant sections of the Operational Guidelines Doc (e.g., story-specific error handling nuances, security considerations for data handled in this story). -- The goal is to collect all necessary details the Dev Agent would need, to avoid them having to search extensively. Note any discrepancies between the epic and these details for "Deviation Analysis." +[[LLM: This step is CRITICAL for continuity and learning from implementation experience]] -### 4. Verify Project Structure Alignment +- If this is not the first story (i.e., previous story exists): + - Read the previous story file: `docs/stories/{prevEpicNum}.{prevStoryNum}.story.md` + - Pay special attention to: + - Dev Agent Record sections (especially Completion Notes and Debug Log References) + - Any deviations from planned implementation + - Technical decisions made during implementation + - Challenges encountered and solutions applied + - Any "lessons learned" or notes for future stories + - Extract relevant insights that might inform the current story's preparation -- Cross-reference the story's requirements and anticipated file manipulations with the Project Structure Guide (and frontend structure if applicable). +### 4. Gather & Synthesize Architecture Context from Sharded Docs + +[[LLM: CRITICAL - You MUST gather technical details from the sharded architecture documents. NEVER make up technical details not found in these documents.]] + +#### 4.1 Start with Architecture Index + +- Read `docs/architecture/index.md` to understand the full scope of available documentation +- Identify which sharded documents are most relevant to the current story + +#### 4.2 Recommended Reading Order Based on Story Type + +[[LLM: Read documents in this order, but ALWAYS verify relevance to the specific story. Skip irrelevant sections but NEVER skip documents that contain information needed for the story.]] + +**For ALL Stories:** + +1. `docs/architecture/tech-stack.md` - Understand technology constraints and versions +2. `docs/architecture/unified-project-structure.md` - Know where code should be placed +3. `docs/architecture/coding-standards.md` - Ensure dev follows project conventions +4. `docs/architecture/testing-strategy.md` - Include testing requirements in tasks + +**For Backend/API Stories, additionally read:** 5. `docs/architecture/data-models.md` - Data structures and validation rules 6. `docs/architecture/database-schema.md` - Database design and relationships 7. `docs/architecture/backend-architecture.md` - Service patterns and structure 8. `docs/architecture/rest-api-spec.md` - API endpoint specifications 9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant) + +**For Frontend/UI Stories, additionally read:** 5. `docs/architecture/frontend-architecture.md` - Component structure and patterns 6. `docs/architecture/components.md` - Specific component designs 7. `docs/architecture/core-workflows.md` - User interaction flows 8. `docs/architecture/data-models.md` - Frontend data handling + +**For Full-Stack Stories:** + +- Read both Backend and Frontend sections above + +#### 4.3 Extract Story-Specific Technical Details + +[[LLM: As you read each document, extract ONLY the information directly relevant to implementing the current story. Do NOT include general information unless it directly impacts the story implementation.]] + +For each relevant document, extract: + +- Specific data models, schemas, or structures the story will use +- API endpoints the story must implement or consume +- Component specifications for UI elements in the story +- File paths and naming conventions for new code +- Testing requirements specific to the story's features +- Security or performance considerations affecting the story + +#### 4.4 Document Source References + +[[LLM: ALWAYS cite the source document and section for each technical detail you include. This helps the dev agent verify information if needed.]] + +Format references as: `[Source: architecture/{filename}.md#{section}]` + +### 5. Verify Project Structure Alignment + +- Cross-reference the story's requirements and anticipated file manipulations with the Project Structure Guide from `docs/architecture/unified-project-structure.md`. - Ensure any file paths, component locations, or module names implied by the story align with defined structures. - Document any structural conflicts, necessary clarifications, or undefined components/paths in a "Project Structure Notes" section within the story draft. -### 5. Populate Story Template with Full Context +### 6. Populate Story Template with Full Context - Create a new story file: `docs/stories/{epicNum}.{storyNum}.story.md`. - Use the Story Template to structure the file. @@ -90,11 +151,56 @@ To identify the next logical story based on project progress and epic definition - `Story` (User Story statement from Epic) - `Acceptance Criteria (ACs)` (from Epic, to be refined if needed based on context) - **`Dev Technical Guidance` section (CRITICAL):** - - Based on all context gathered (Step 3 & 4), embed concise but critical snippets of information, specific data structures, API endpoint details, precise references to _specific sections_ in other documents (e.g., "See `Data Models Doc#User-Schema-ValidationRules` for details"), or brief explanations of how architectural patterns apply to _this story_. - - If UI story, provide specific references to Component/Style Guides relevant to _this story's elements_. - - The aim is to make this section the Dev Agent's primary source for _story-specific_ technical context. + + [[LLM: This section MUST contain ONLY information extracted from the architecture shards. NEVER invent or assume technical details.]] + + - Include ALL relevant technical details gathered from Steps 3 and 4, organized by category: + - **Previous Story Insights**: Key learnings or considerations from the previous story + - **Data Models**: Specific schemas, validation rules, relationships [with source references] + - **API Specifications**: Endpoint details, request/response formats, auth requirements [with source references] + - **Component Specifications**: UI component details, props, state management [with source references] + - **File Locations**: Exact paths where new code should be created based on project structure + - **Testing Requirements**: Specific test cases or strategies from testing-strategy.md + - **Technical Constraints**: Version requirements, performance considerations, security rules + - Every technical detail MUST include its source reference: `[Source: architecture/{filename}.md#{section}]` + - If information for a category is not found in the architecture docs, explicitly state: "No specific guidance found in architecture docs" + - **`Tasks / Subtasks` section:** - - Generate a detailed, sequential list of technical tasks and subtasks the Dev Agent must perform to complete the story, informed by the gathered context. - - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`). -- Add notes on project structure alignment or discrepancies found in Step 4. -- Prepare content for the "Deviation Analysis" based on discrepancies noted in Step 3. + - Generate a detailed, sequential list of technical tasks based ONLY on: + - Requirements from the Epic + - Technical constraints from architecture shards + - Project structure from unified-project-structure.md + - Testing requirements from testing-strategy.md + - Each task must reference relevant architecture documentation + - Include unit testing as explicit subtasks based on testing-strategy.md + - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`) +- Add notes on project structure alignment or discrepancies found in Step 5. +- Prepare content for the "Deviation Analysis" based on any conflicts between epic requirements and architecture constraints. + +### 7. Run Story Draft Checklist + +- Execute the Story Draft Checklist against the prepared story +- Document any issues or gaps identified +- Make necessary adjustments to meet quality standards +- Ensure all technical guidance is properly sourced from architecture docs + +### 8. Finalize Story File + +- Review all sections for completeness and accuracy +- Verify all source references are included for technical details +- Ensure tasks align with both epic requirements and architecture constraints +- Update status to "Draft" +- Save the story file to `docs/stories/{epicNum}.{storyNum}.story.md` + +### 9. Report Completion + +Provide a summary to the user including: + +- Story created: `{epicNum}.{storyNum} - {Story Title}` +- Status: Draft +- Key technical components included from architecture docs +- Any deviations or conflicts noted between epic and architecture +- Recommendations for story review before approval +- Next steps: Story should be reviewed by PO for approval before dev work begins + +[[LLM: Remember - The success of this task depends on extracting real, specific technical details from the architecture shards. The dev agent should have everything they need in the story file without having to search through multiple documents.]]