diff --git a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-analyst.md b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-analyst.md index fadfeff3..a4c7f369 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-analyst.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-analyst.md @@ -2,8 +2,7 @@ activation-instructions: - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below - - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting - - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands + - STEP 3: Greet user with your name/role and immediately run `*help` to display available commands - DO NOT: Load any other agent files during activation - ONLY load dependency files when user selects them for execution via command or request of a task - The agent.customization field ALWAYS takes precedence over any conflicting instructions @@ -17,14 +16,13 @@ agent: name: game-analyst id: game-analyst title: Game Analyst - base_agent: bmad-core/agents/analyst.md icon: 🎮 whenToUse: Use for market research on games, brainstorming game mechanics, competitive analysis, and creating initial game briefs. customization: null persona: role: Insightful Game Analyst & Strategic Partner style: Analytical, creative, data-driven, player-focused - identity: A strategic analyst specializing in the video game market, particularly WeChat Mini-Games. I turn player data and market trends into actionable insights. I inherit my core capabilities from the bmad-core analyst, but my focus is entirely on the gaming domain. + identity: A strategic analyst specializing in the video game market, particularly WeChat Mini-Games. I turn player data and market trends into actionable insights. focus: Market research, competitive analysis, game concept validation, player data analysis, and creating the initial Game Brief. core_principles: - Player-centric analysis @@ -36,15 +34,13 @@ persona: commands: - help: Show numbered list of the following commands to allow selection - brainstorm {topic}: Facilitate structured brainstorming session for game mechanics or features. - - create-competitor-analysis: Create a competitor analysis for a game concept. - create-game-brief: Create a Game Brief to define the initial vision and goals. - - perform-market-research: Conduct market research on a specific game genre or platform. - exit: Say goodbye and abandon this persona. dependencies: data: - - expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md + - development-guidelines.md tasks: - - bmad-core/tasks/create-doc.md + - document-project.md templates: - - expansion-packs/bmad-wechat-mini-game-dev/templates/game-brief-tmpl.yaml + - game-brief-tmpl.yaml ``` diff --git a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-designer.md b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-designer.md index e64534f7..a7734afc 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-designer.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-designer.md @@ -2,8 +2,7 @@ activation-instructions: - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below - - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting - - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands + - STEP 3: Greet user with your name/role and immediately run `*help` to display available commands - DO NOT: Load any other agent files during activation - ONLY load dependency files when user selects them for execution via command or request of a task - The agent.customization field ALWAYS takes precedence over any conflicting instructions @@ -17,14 +16,13 @@ agent: name: game-designer id: game-designer title: Game Designer - base_agent: bmad-core/agents/architect.md icon: 🎮 whenToUse: Use for creating Game Design Documents (GDDs) and designing game mechanics, progression systems, and player experiences. customization: null persona: role: Expert Game Designer & Creative Visionary style: Creative, player-focused, systematic, technical - identity: A visionary game designer who translates product requirements into compelling gameplay experiences. I inherit the document creation capabilities of a System Architect to produce highly detailed and structured Game Design Documents (GDDs). + identity: A visionary game designer who translates product requirements into compelling gameplay experiences. I specialize in creating detailed Game Design Documents (GDDs). focus: Designing core game mechanics, balancing, progression systems, and documenting the complete design for the development team. core_principles: - Player-centric design @@ -39,9 +37,9 @@ commands: - exit: Say goodbye and abandon this persona. dependencies: data: - - expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md + - development-guidelines.md tasks: - - bmad-core/tasks/create-doc.md + - document-project.md templates: - - expansion-packs/bmad-wechat-mini-game-dev/templates/game-design-doc-tmpl.yaml + - game-design-doc-tmpl.yaml ``` diff --git a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-orchestrator.md b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-orchestrator.md index deb74731..62cd83d5 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-orchestrator.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-orchestrator.md @@ -1,21 +1,45 @@ -# Game Orchestrator - -## Role -The Game Orchestrator is the conductor of the game development team. They ensure that all agents are working together harmoniously and efficiently to create a high-quality WeChat mini-game. This role is a blend of a project manager, a scrum master, and a team lead, tailored for an AI agent team. - -## Responsibilities -- **Workflow Management:** Coordinate the day-to-day activities of the agent team, ensuring a smooth and efficient workflow. -- **Process Facilitation:** Facilitate the development process, whether it's an agile methodology like Scrum or a more traditional approach. This includes managing sprints, backlogs, and meetings. -- **Communication Hub:** Act as the central point of communication for the team, ensuring that all agents are aware of project goals, progress, and any changes in direction. -- **Impediment Removal:** Identify and remove any obstacles that are hindering the team's progress. -- **Resource Allocation:** Ensure that agents have the necessary resources and information to complete their tasks. -- **Collaboration:** Foster a collaborative environment where agents can work together effectively. -- **Reporting:** Provide regular status updates to stakeholders on the project's progress. - -## Key Skills -- **Project Management:** Strong project management skills, with experience in planning, execution, and tracking. -- **Agile Methodologies:** Deep understanding of agile principles and practices. -- **Communication:** Exceptional communication, facilitation, and interpersonal skills. -- **Problem-Solving:** Ability to quickly identify and resolve issues. -- **Leadership:** Strong leadership qualities to guide and motivate the agent team. -- **Technical Acumen:** A good understanding of the game development lifecycle and the WeChat Mini Game platform. +```yaml +activation-instructions: + - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition + - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below + - STEP 3: Greet user with your name/role and immediately run `*help` to display available commands + - DO NOT: Load any other agent files during activation + - ONLY load dependency files when user selects them for execution via command or request of a task + - The agent.customization field ALWAYS takes precedence over any conflicting instructions + - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material + - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency + - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency. + - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute + - STAY IN CHARACTER! + - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments. +agent: + name: game-orchestrator + id: game-orchestrator + title: Game Orchestrator & Architect + icon: 🎮 + whenToUse: Use for creating the technical architecture for a game and ensuring the development process runs smoothly. + customization: null +persona: + role: Technical Architect & Team Conductor + style: Systematic, forward-thinking, communicative, pragmatic + identity: A technical leader who designs robust game architectures and orchestrates the development team to ensure efficient and high-quality execution. + focus: Creating the Game Architecture Document, facilitating communication, and removing technical impediments. + core_principles: + - Sound architectural design + - Clear communication + - Proactive problem-solving + - Efficient workflow management + - Technical excellence +# All commands require * prefix when used (e.g., *help) +commands: + - help: Show numbered list of the following commands to allow selection + - create-architecture: Create a Game Architecture Document. + - exit: Say goodbye and abandon this persona. +dependencies: + data: + - development-guidelines.md + tasks: + - document-project.md + templates: + - game-architecture-tmpl.yaml +``` diff --git a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-pm.md b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-pm.md index 7060b399..9fadc23a 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-pm.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-pm.md @@ -2,8 +2,7 @@ activation-instructions: - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below - - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting - - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands + - STEP 3: Greet user with your name/role and immediately run `*help` to display available commands - DO NOT: Load any other agent files during activation - ONLY load dependency files when user selects them for execution via command or request of a task - The agent.customization field ALWAYS takes precedence over any conflicting instructions @@ -17,14 +16,13 @@ agent: name: game-pm id: game-pm title: Game Project Manager - base_agent: bmad-core/agents/pm.md icon: 🎮 whenToUse: Use for creating PRDs for games, managing project timelines, and tracking development progress. customization: null persona: role: Master of Execution & Game Development PM style: Organized, proactive, communicative, results-oriented - identity: A Game Project Manager who specializes in the planning, execution, and delivery of WeChat mini-game projects. I inherit my core capabilities from the bmad-core PM, but my focus is entirely on the game development lifecycle. + identity: A Game Project Manager who specializes in the planning, execution, and delivery of WeChat mini-game projects. focus: Project planning, risk management, team coordination, and creating the Product Requirements Document (PRD). core_principles: - Plan the work, work the plan @@ -39,9 +37,9 @@ commands: - exit: Say goodbye and abandon this persona. dependencies: data: - - expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md + - development-guidelines.md tasks: - - bmad-core/tasks/create-doc.md + - document-project.md templates: - - bmad-core/templates/prd-tmpl.yaml + - prd-tmpl.yaml ``` diff --git a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-po.md b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-po.md index b056ea49..ef81066b 100644 --- a/expansion-packs/bmad-wechat-mini-game-dev/agents/game-po.md +++ b/expansion-packs/bmad-wechat-mini-game-dev/agents/game-po.md @@ -2,8 +2,7 @@ activation-instructions: - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below - - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting - - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands + - STEP 3: Greet user with your name/role and immediately run `*help` to display available commands - DO NOT: Load any other agent files during activation - ONLY load dependency files when user selects them for execution via command or request of a task - The agent.customization field ALWAYS takes precedence over any conflicting instructions @@ -17,14 +16,13 @@ agent: name: game-po id: game-po title: Game Product Owner - base_agent: bmad-core/agents/po.md icon: 🎮 whenToUse: Use for defining the game's vision, managing the backlog, and sharding documents for development. customization: null persona: role: Visionary Game Product Owner & Player Advocate style: Strategic, decisive, communicative, market-aware - identity: The visionary for the WeChat mini-game, responsible for defining the "what" and "why" of the game. I inherit my core capabilities from the bmad-core PO, but my focus is entirely on the game product lifecycle. + identity: The visionary for the WeChat mini-game, responsible for defining the "what" and "why" of the game and ensuring it's a product that players will love and that meets business goals. focus: Product vision, backlog management, feature definition, and sharding planning documents into actionable work for the development team. core_principles: - Champion the player's voice @@ -40,11 +38,10 @@ commands: - exit: Say goodbye and abandon this persona. dependencies: data: - - bmad-core/data/bmad-kb.md - - expansion-packs/bmad-wechat-mini-game-dev/data/development-guidelines.md + - bmad-kb.md + - development-guidelines.md tasks: - - bmad-core/tasks/shard-doc.md - - bmad-core/tasks/execute-checklist.md + - shard-doc.md checklists: - - expansion-packs/bmad-wechat-mini-game-dev/checklists/game-design-checklist.md + - game-design-checklist.md ``` diff --git a/expansion-packs/bmad-wechat-mini-game-dev/tasks/document-project.md b/expansion-packs/bmad-wechat-mini-game-dev/tasks/document-project.md new file mode 100644 index 00000000..f0010679 --- /dev/null +++ b/expansion-packs/bmad-wechat-mini-game-dev/tasks/document-project.md @@ -0,0 +1,346 @@ + + +# Document an Existing Project + +## Purpose + +Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase. + +## Task Instructions + +### 1. Initial Project Analysis + +**CRITICAL:** First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only. + +**IF PRD EXISTS**: + +- Review the PRD to understand what enhancement/feature is planned +- Identify which modules, services, or areas will be affected +- Focus documentation ONLY on these relevant areas +- Skip unrelated parts of the codebase to keep docs lean + +**IF NO PRD EXISTS**: +Ask the user: + +"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options: + +1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas. + +2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share? + +3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example: + - 'Adding payment processing to the user service' + - 'Refactoring the authentication module' + - 'Integrating with a new third-party API' + +4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects) + +Please let me know your preference, or I can proceed with full documentation if you prefer." + +Based on their response: + +- If they choose option 1-3: Use that context to focus documentation +- If they choose option 4 or decline: Proceed with comprehensive analysis below + +Begin by conducting analysis of the existing project. Use available tools to: + +1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization +2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies +3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands +4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation +5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches + +Ask the user these elicitation questions to better understand their needs: + +- What is the primary purpose of this project? +- Are there any specific areas of the codebase that are particularly complex or important for agents to understand? +- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing) +- Are there any existing documentation standards or formats you prefer? +- What level of technical detail should the documentation target? (junior developers, senior developers, mixed team) +- Is there a specific feature or enhancement you're planning? (This helps focus documentation) + +### 2. Deep Codebase Analysis + +CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase: + +1. **Explore Key Areas**: + - Entry points (main files, index files, app initializers) + - Configuration files and environment setup + - Package dependencies and versions + - Build and deployment configurations + - Test suites and coverage + +2. **Ask Clarifying Questions**: + - "I see you're using [technology X]. Are there any custom patterns or conventions I should document?" + - "What are the most critical/complex parts of this system that developers struggle with?" + - "Are there any undocumented 'tribal knowledge' areas I should capture?" + - "What technical debt or known issues should I document?" + - "Which parts of the codebase change most frequently?" + +3. **Map the Reality**: + - Identify ACTUAL patterns used (not theoretical best practices) + - Find where key business logic lives + - Locate integration points and external dependencies + - Document workarounds and technical debt + - Note areas that differ from standard patterns + +**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement + +### 3. Core Documentation Generation + +[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase. + +**CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including: + +- Technical debt and workarounds +- Inconsistent patterns between different parts +- Legacy code that can't be changed +- Integration constraints +- Performance bottlenecks + +**Document Structure**: + +# [Project Name] Brownfield Architecture Document + +## Introduction + +This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements. + +### Document Scope + +[If PRD provided: "Focused on areas relevant to: {enhancement description}"] +[If no PRD: "Comprehensive documentation of entire system"] + +### Change Log + +| Date | Version | Description | Author | +| ------ | ------- | --------------------------- | --------- | +| [Date] | 1.0 | Initial brownfield analysis | [Analyst] | + +## Quick Reference - Key Files and Entry Points + +### Critical Files for Understanding the System + +- **Main Entry**: `src/index.js` (or actual entry point) +- **Configuration**: `config/app.config.js`, `.env.example` +- **Core Business Logic**: `src/services/`, `src/domain/` +- **API Definitions**: `src/routes/` or link to OpenAPI spec +- **Database Models**: `src/models/` or link to schema files +- **Key Algorithms**: [List specific files with complex logic] + +### If PRD Provided - Enhancement Impact Areas + +[Highlight which files/modules will be affected by the planned enhancement] + +## High Level Architecture + +### Technical Summary + +### Actual Tech Stack (from package.json/requirements.txt) + +| Category | Technology | Version | Notes | +| --------- | ---------- | ------- | -------------------------- | +| Runtime | Node.js | 16.x | [Any constraints] | +| Framework | Express | 4.18.2 | [Custom middleware?] | +| Database | PostgreSQL | 13 | [Connection pooling setup] | + +etc... + +### Repository Structure Reality Check + +- Type: [Monorepo/Polyrepo/Hybrid] +- Package Manager: [npm/yarn/pnpm] +- Notable: [Any unusual structure decisions] + +## Source Tree and Module Organization + +### Project Structure (Actual) + +```text +project-root/ +├── src/ +│ ├── controllers/ # HTTP request handlers +│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services) +│ ├── models/ # Database models (Sequelize) +│ ├── utils/ # Mixed bag - needs refactoring +│ └── legacy/ # DO NOT MODIFY - old payment system still in use +├── tests/ # Jest tests (60% coverage) +├── scripts/ # Build and deployment scripts +└── config/ # Environment configs +``` + +### Key Modules and Their Purpose + +- **User Management**: `src/services/userService.js` - Handles all user operations +- **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation +- **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled +- **[List other key modules with their actual files]** + +## Data Models and APIs + +### Data Models + +Instead of duplicating, reference actual model files: + +- **User Model**: See `src/models/User.js` +- **Order Model**: See `src/models/Order.js` +- **Related Types**: TypeScript definitions in `src/types/` + +### API Specifications + +- **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists) +- **Postman Collection**: `docs/api/postman-collection.json` +- **Manual Endpoints**: [List any undocumented endpoints discovered] + +## Technical Debt and Known Issues + +### Critical Technical Debt + +1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests +2. **User Service**: Different pattern than other services, uses callbacks instead of promises +3. **Database Migrations**: Manually tracked, no proper migration tool +4. **[Other significant debt]** + +### Workarounds and Gotchas + +- **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason) +- **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service +- **[Other workarounds developers need to know]** + +## Integration Points and External Dependencies + +### External Services + +| Service | Purpose | Integration Type | Key Files | +| -------- | -------- | ---------------- | ------------------------------ | +| Stripe | Payments | REST API | `src/integrations/stripe/` | +| SendGrid | Emails | SDK | `src/services/emailService.js` | + +etc... + +### Internal Integration Points + +- **Frontend Communication**: REST API on port 3000, expects specific headers +- **Background Jobs**: Redis queue, see `src/workers/` +- **[Other integrations]** + +## Development and Deployment + +### Local Development Setup + +1. Actual steps that work (not ideal steps) +2. Known issues with setup +3. Required environment variables (see `.env.example`) + +### Build and Deployment Process + +- **Build Command**: `npm run build` (webpack config in `webpack.config.js`) +- **Deployment**: Manual deployment via `scripts/deploy.sh` +- **Environments**: Dev, Staging, Prod (see `config/environments/`) + +## Testing Reality + +### Current Test Coverage + +- Unit Tests: 60% coverage (Jest) +- Integration Tests: Minimal, in `tests/integration/` +- E2E Tests: None +- Manual Testing: Primary QA method + +### Running Tests + +```bash +npm test # Runs unit tests +npm run test:integration # Runs integration tests (requires local DB) +``` + +## If Enhancement PRD Provided - Impact Analysis + +### Files That Will Need Modification + +Based on the enhancement requirements, these files will be affected: + +- `src/services/userService.js` - Add new user fields +- `src/models/User.js` - Update schema +- `src/routes/userRoutes.js` - New endpoints +- [etc...] + +### New Files/Modules Needed + +- `src/services/newFeatureService.js` - New business logic +- `src/models/NewFeature.js` - New data model +- [etc...] + +### Integration Considerations + +- Will need to integrate with existing auth middleware +- Must follow existing response format in `src/utils/responseFormatter.js` +- [Other integration points] + +## Appendix - Useful Commands and Scripts + +### Frequently Used Commands + +```bash +npm run dev # Start development server +npm run build # Production build +npm run migrate # Run database migrations +npm run seed # Seed test data +``` + +### Debugging and Troubleshooting + +- **Logs**: Check `logs/app.log` for application logs +- **Debug Mode**: Set `DEBUG=app:*` for verbose logging +- **Common Issues**: See `docs/troubleshooting.md`]] + +### 4. Document Delivery + +1. **In Web UI (Gemini, ChatGPT, Claude)**: + - Present the entire document in one response (or multiple if too long) + - Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md` + - Mention it can be sharded later in IDE if desired + +2. **In IDE Environment**: + - Create the document as `docs/brownfield-architecture.md` + - Inform user this single document contains all architectural information + - Can be sharded later using PO agent if desired + +The document should be comprehensive enough that future agents can understand: + +- The actual state of the system (not idealized) +- Where to find key files and logic +- What technical debt exists +- What constraints must be respected +- If PRD provided: What needs to change for the enhancement +]] + +### 5. Quality Assurance + +CRITICAL: Before finalizing the document: + +1. **Accuracy Check**: Verify all technical details match the actual codebase +2. **Completeness Review**: Ensure all major system components are documented +3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized +4. **Clarity Assessment**: Check that explanations are clear for AI agents +5. **Navigation**: Ensure document has clear section structure for easy reference + +Apply the advanced elicitation task after major sections to refine based on user feedback. + +## Success Criteria + +- Single comprehensive brownfield architecture document created +- Document reflects REALITY including technical debt and workarounds +- Key files and modules are referenced with actual paths +- Models/APIs reference source files rather than duplicating content +- If PRD provided: Clear impact analysis showing what needs to change +- Document enables AI agents to navigate and understand the actual codebase +- Technical constraints and "gotchas" are clearly documented + +## Notes + +- This task creates ONE document that captures the TRUE state of the system +- References actual files rather than duplicating content when possible +- Documents technical debt, workarounds, and constraints honestly +- For brownfield projects with PRD: Provides clear enhancement impact analysis +- The goal is PRACTICAL documentation for AI agents doing real work diff --git a/expansion-packs/bmad-wechat-mini-game-dev/tasks/shard-doc.md b/expansion-packs/bmad-wechat-mini-game-dev/tasks/shard-doc.md new file mode 100644 index 00000000..900616a8 --- /dev/null +++ b/expansion-packs/bmad-wechat-mini-game-dev/tasks/shard-doc.md @@ -0,0 +1,187 @@ + + +# Document Sharding Task + +## Purpose + +- Split a large document into multiple smaller documents based on level 2 sections +- Create a folder structure to organize the sharded documents +- Maintain all content integrity including code blocks, diagrams, and markdown formatting + +## Primary Method: Automatic with markdown-tree + +[[LLM: First, check if markdownExploder is set to true in {root}/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`. + +If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further. + +If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either: + +1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser` +2. Or set markdownExploder to false in {root}/core-config.yaml + +**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**" + +If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should: + +1. Set markdownExploder to true in {root}/core-config.yaml +2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser` + +I will now proceed with the manual sharding process." + +Then proceed with the manual method below ONLY if markdownExploder is false.]] + +### Installation and Usage + +1. **Install globally**: + + ```bash + npm install -g @kayvan/markdown-tree-parser + ``` + +2. **Use the explode command**: + + ```bash + # For PRD + md-tree explode docs/prd.md docs/prd + + # For Architecture + md-tree explode docs/architecture.md docs/architecture + + # For any document + md-tree explode [source-document] [destination-folder] + ``` + +3. **What it does**: + - Automatically splits the document by level 2 sections + - Creates properly named files + - Adjusts heading levels appropriately + - Handles all edge cases with code blocks and special markdown + +If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below. + +--- + +## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method) + +### Task Instructions + +1. Identify Document and Target Location + +- Determine which document to shard (user-provided path) +- Create a new folder under `docs/` with the same name as the document (without extension) +- Example: `docs/prd.md` → create folder `docs/prd/` + +2. Parse and Extract Sections + +CRITICAL AEGNT SHARDING RULES: + +1. Read the entire document content +2. Identify all level 2 sections (## headings) +3. For each level 2 section: + - Extract the section heading and ALL content until the next level 2 section + - Include all subsections, code blocks, diagrams, lists, tables, etc. + - Be extremely careful with: + - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example + - Mermaid diagrams - preserve the complete diagram syntax + - Nested markdown elements + - Multi-line content that might contain ## inside code blocks + +CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]] + +### 3. Create Individual Files + +For each extracted section: + +1. **Generate filename**: Convert the section heading to lowercase-dash-case + - Remove special characters + - Replace spaces with dashes + - Example: "## Tech Stack" → `tech-stack.md` + +2. **Adjust heading levels**: + - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document + - All subsection levels decrease by 1: + + ```txt + - ### → ## + - #### → ### + - ##### → #### + - etc. + ``` + +3. **Write content**: Save the adjusted content to the new file + +### 4. Create Index File + +Create an `index.md` file in the sharded folder that: + +1. Contains the original level 1 heading and any content before the first level 2 section +2. Lists all the sharded files with links: + +```markdown +# Original Document Title + +[Original introduction content if any] + +## Sections + +- [Section Name 1](./section-name-1.md) +- [Section Name 2](./section-name-2.md) +- [Section Name 3](./section-name-3.md) + ... +``` + +### 5. Preserve Special Content + +1. **Code blocks**: Must capture complete blocks including: + + ```language + content + ``` + +2. **Mermaid diagrams**: Preserve complete syntax: + + ```mermaid + graph TD + ... + ``` + +3. **Tables**: Maintain proper markdown table formatting + +4. **Lists**: Preserve indentation and nesting + +5. **Inline code**: Preserve backticks + +6. **Links and references**: Keep all markdown links intact + +7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly + +### 6. Validation + +After sharding: + +1. Verify all sections were extracted +2. Check that no content was lost +3. Ensure heading levels were properly adjusted +4. Confirm all files were created successfully + +### 7. Report Results + +Provide a summary: + +```text +Document sharded successfully: +- Source: [original document path] +- Destination: docs/[folder-name]/ +- Files created: [count] +- Sections: + - section-name-1.md: "Section Title 1" + - section-name-2.md: "Section Title 2" + ... +``` + +## Important Notes + +- Never modify the actual content, only adjust heading levels +- Preserve ALL formatting, including whitespace where significant +- Handle edge cases like sections with code blocks containing ## symbols +- Ensure the sharding is reversible (could reconstruct the original from shards) diff --git a/expansion-packs/bmad-wechat-mini-game-dev/templates/prd-tmpl.yaml b/expansion-packs/bmad-wechat-mini-game-dev/templates/prd-tmpl.yaml new file mode 100644 index 00000000..804f6d45 --- /dev/null +++ b/expansion-packs/bmad-wechat-mini-game-dev/templates/prd-tmpl.yaml @@ -0,0 +1,203 @@ +# +template: + id: prd-template-v2 + name: Product Requirements Document + version: 2.0 + output: + format: markdown + filename: docs/prd.md + title: "{{project_name}} Product Requirements Document (PRD)" + +workflow: + mode: interactive + elicitation: advanced-elicitation + +sections: + - id: goals-context + title: Goals and Background Context + instruction: | + Ask if Project Brief document is available. If NO Project Brief exists, STRONGLY recommend creating one first using project-brief-tmpl (it provides essential foundation: problem statement, target users, success metrics, MVP scope, constraints). If user insists on PRD without brief, gather this information during Goals section. If Project Brief exists, review and use it to populate Goals (bullet list of desired outcomes) and Background Context (1-2 paragraphs on what this solves and why) so we can determine what is and is not in scope for PRD mvp. Either way this is critical to determine the requirements. Include Change Log table. + sections: + - id: goals + title: Goals + type: bullet-list + instruction: Bullet list of 1 line desired outcomes the PRD will deliver if successful - user and project desires + - id: background + title: Background Context + type: paragraphs + instruction: 1-2 short paragraphs summarizing the background context, such as what we learned in the brief without being redundant with the goals, what and why this solves a problem, what the current landscape or need is + - id: changelog + title: Change Log + type: table + columns: [Date, Version, Description, Author] + instruction: Track document versions and changes + + - id: requirements + title: Requirements + instruction: Draft the list of functional and non functional requirements under the two child sections + elicit: true + sections: + - id: functional + title: Functional + type: numbered-list + prefix: FR + instruction: Each Requirement will be a bullet markdown and an identifier sequence starting with FR + examples: + - "FR6: The Todo List uses AI to detect and warn against potentially duplicate todo items that are worded differently." + - id: non-functional + title: Non Functional + type: numbered-list + prefix: NFR + instruction: Each Requirement will be a bullet markdown and an identifier sequence starting with NFR + examples: + - "NFR1: AWS service usage must aim to stay within free-tier limits where feasible." + + - id: ui-goals + title: User Interface Design Goals + condition: PRD has UX/UI requirements + instruction: | + Capture high-level UI/UX vision to guide Design Architect and to inform story creation. Steps: + + 1. Pre-fill all subsections with educated guesses based on project context + 2. Present the complete rendered section to user + 3. Clearly let the user know where assumptions were made + 4. Ask targeted questions for unclear/missing elements or areas needing more specification + 5. This is NOT detailed UI spec - focus on product vision and user goals + elicit: true + choices: + accessibility: [None, WCAG AA, WCAG AAA] + platforms: [Web Responsive, Mobile Only, Desktop Only, Cross-Platform] + sections: + - id: ux-vision + title: Overall UX Vision + - id: interaction-paradigms + title: Key Interaction Paradigms + - id: core-screens + title: Core Screens and Views + instruction: From a product perspective, what are the most critical screens or views necessary to deliver the the PRD values and goals? This is meant to be Conceptual High Level to Drive Rough Epic or User Stories + examples: + - "Login Screen" + - "Main Dashboard" + - "Item Detail Page" + - "Settings Page" + - id: accessibility + title: "Accessibility: {None|WCAG AA|WCAG AAA|Custom Requirements}" + - id: branding + title: Branding + instruction: Any known branding elements or style guides that must be incorporated? + examples: + - "Replicate the look and feel of early 1900s black and white cinema, including animated effects replicating film damage or projector glitches during page or state transitions." + - "Attached is the full color pallet and tokens for our corporate branding." + - id: target-platforms + title: "Target Device and Platforms: {Web Responsive|Mobile Only|Desktop Only|Cross-Platform}" + examples: + - "Web Responsive, and all mobile platforms" + - "iPhone Only" + - "ASCII Windows Desktop" + + - id: technical-assumptions + title: Technical Assumptions + instruction: | + Gather technical decisions that will guide the Architect. Steps: + + 1. Check if {root}/data/technical-preferences.yaml or an attached technical-preferences file exists - use it to pre-populate choices + 2. Ask user about: languages, frameworks, starter templates, libraries, APIs, deployment targets + 3. For unknowns, offer guidance based on project goals and MVP scope + 4. Document ALL technical choices with rationale (why this choice fits the project) + 5. These become constraints for the Architect - be specific and complete + elicit: true + choices: + repository: [Monorepo, Polyrepo] + architecture: [Monolith, Microservices, Serverless] + testing: [Unit Only, Unit + Integration, Full Testing Pyramid] + sections: + - id: repository-structure + title: "Repository Structure: {Monorepo|Polyrepo|Multi-repo}" + - id: service-architecture + title: Service Architecture + instruction: "CRITICAL DECISION - Document the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo)." + - id: testing-requirements + title: Testing Requirements + instruction: "CRITICAL DECISION - Document the testing requirements, unit only, integration, e2e, manual, need for manual testing convenience methods)." + - id: additional-assumptions + title: Additional Technical Assumptions and Requests + instruction: Throughout the entire process of drafting this document, if any other technical assumptions are raised or discovered appropriate for the architect, add them here as additional bulleted items + + - id: epic-list + title: Epic List + instruction: | + Present a high-level list of all epics for user approval. Each epic should have a title and a short (1 sentence) goal statement. This allows the user to review the overall structure before diving into details. + + CRITICAL: Epics MUST be logically sequential following agile best practices: + + - Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality + - Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page - remember this when we produce the stories for the first epic! + - Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed + - Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic. + - Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things. + - Cross Cutting Concerns should flow through epics and stories and not be final stories. For example, adding a logging framework as a last story of an epic, or at the end of a project as a final epic or story would be terrible as we would not have logging from the beginning. + elicit: true + examples: + - "Epic 1: Foundation & Core Infrastructure: Establish project setup, authentication, and basic user management" + - "Epic 2: Core Business Entities: Create and manage primary domain objects with CRUD operations" + - "Epic 3: User Workflows & Interactions: Enable key user journeys and business processes" + - "Epic 4: Reporting & Analytics: Provide insights and data visualization for users" + + - id: epic-details + title: Epic {{epic_number}} {{epic_title}} + repeatable: true + instruction: | + After the epic list is approved, present each epic with all its stories and acceptance criteria as a complete review unit. + + For each epic provide expanded goal (2-3 sentences describing the objective and value all the stories will achieve). + + CRITICAL STORY SEQUENCING REQUIREMENTS: + + - Stories within each epic MUST be logically sequential + - Each story should be a "vertical slice" delivering complete functionality aside from early enabler stories for project foundation + - No story should depend on work from a later story or epic + - Identify and note any direct prerequisite stories + - Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story. + - Ensure each story delivers clear user or business value, try to avoid enablers and build them into stories that deliver value. + - Size stories for AI agent execution: Each story must be completable by a single AI agent in one focused session without context overflow + - Think "junior developer working for 2-4 hours" - stories must be small, focused, and self-contained + - If a story seems complex, break it down further as long as it can deliver a vertical slice + elicit: true + template: "{{epic_goal}}" + sections: + - id: story + title: Story {{epic_number}}.{{story_number}} {{story_title}} + repeatable: true + template: | + As a {{user_type}}, + I want {{action}}, + so that {{benefit}}. + sections: + - id: acceptance-criteria + title: Acceptance Criteria + type: numbered-list + item_template: "{{criterion_number}}: {{criteria}}" + repeatable: true + instruction: | + Define clear, comprehensive, and testable acceptance criteria that: + + - Precisely define what "done" means from a functional perspective + - Are unambiguous and serve as basis for verification + - Include any critical non-functional requirements from the PRD + - Consider local testability for backend/data components + - Specify UI/UX requirements and framework adherence where applicable + - Avoid cross-cutting concerns that should be in other stories or PRD sections + + - id: checklist-results + title: Checklist Results Report + instruction: Before running the checklist and drafting the prompts, offer to output the full updated PRD. If outputting it, confirm with the user that you will be proceeding to run the checklist and produce the report. Once the user confirms, execute the pm-checklist and populate the results in this section. + + - id: next-steps + title: Next Steps + sections: + - id: ux-expert-prompt + title: UX Expert Prompt + instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input. + - id: architect-prompt + title: Architect Prompt + instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.