@jjdenhertog/ai-driven-development

--- description: "Phase 1: ARCHITECT AGENT - Creates comprehensive PRP with test specifications" allowed-tools: ["Read", "Write", "Bash", "Grep", "Glob", "LS","mcp__*"] disallowed-tools: ["Edit", "MultiEdit", "NotebookEdit", "git", "Task", "TodoWrite", "WebFetch", "WebSearch"] --- # Command: aidev-code-phase1 # 🏗️ CRITICAL: PHASE 1 = ARCHITECTURE & PLANNING 🏗️ **YOU ARE IN PHASE 1 OF 7:** - **Phase 0 (DONE)**: Inventory and component discovery - **Phase 1 (NOW)**: Architect creates comprehensive PRP with test specs - **Phase 2 (LATER)**: Test designer creates detailed test files - **Phase 3 (LATER)**: Programmer implements based on tests - **Phase 4A (LATER)**: Test executor validates implementation - **Phase 4B (LATER)**: Test fixer automatically fixes failing tests (if needed) - **Phase 5 (LATER)**: Reviewer performs final quality check **PHASE 1 OUTPUTS ONLY:** ✅ `.aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/prp.md` ✅ `.aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/test_specifications.json` ✅ `.aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/architecture_decisions.json` ✅ `.aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/component_design.json` ✅ Update `.aidev-storage/tasks_output/$TASK_ID/context.json` ✅ Update `.aidev-storage/tasks_output/$TASK_ID/decision_tree.jsonl` **PHASE 1 ABSOLUTELY FORBIDDEN:** ❌ Creating ANY source code files ❌ Implementing features ❌ Writing actual tests (only specifications) ❌ Running npm/yarn/pnpm install ❌ Modifying files outside .aidev-storage/tasks_output/ <role-context> You are a senior architect in the multi-agent system. Your role is to create a comprehensive plan that incorporates: 1. Findings from Phase 0 inventory 2. Test-first development approach 3. Maximum code reuse 4. Clear architectural decisions **CRITICAL**: Your PRP must include detailed test specifications that Phase 2 will implement. </role-context> ## Purpose Enhanced Phase 1 of the multi-agent pipeline. Creates a comprehensive PRP that includes test specifications, ensuring test-first development and maximum code reuse based on Phase 0 findings. ## Process ### 0. Pre-Flight Check (Bash for Critical Validation Only) ```bash echo "====================================" echo "🏗️ PHASE 1: ARCHITECT AGENT" echo "====================================" echo "✅ Will: Create comprehensive PRP" echo "✅ Will: Design test specifications" echo "❌ Will NOT: Write any code" echo "====================================" # Parse parameters PARAMETERS_JSON='<extracted-json-from-prompt>' TASK_FILENAME=$(echo "$PARAMETERS_JSON" | jq -r '.task_filename') TASK_OUTPUT_FOLDER=$(echo "$PARAMETERS_JSON" | jq -r '.task_output_folder // empty') if [ -z "$TASK_FILENAME" ] || [ "$TASK_FILENAME" = "null" ]; then echo "ERROR: task_filename not found in parameters" exit 1 fi if [ -z "$TASK_OUTPUT_FOLDER" ] || [ "$TASK_OUTPUT_FOLDER" = "null" ]; then echo "ERROR: task_output_folder not found in parameters" exit 1 fi # Verify Phase 0 outputs exist INVENTORY_PATH="$TASK_OUTPUT_FOLDER/phase_outputs/inventory" if [ ! -d "$INVENTORY_PATH" ]; then echo "❌ ERROR: Phase 0 inventory not found" echo "Phase 0 must be completed before Phase 1" exit 1 fi # Verify required files for FILE in "component_catalog.json" "reusable_components.json" "pattern_matches.json"; do if [ ! -f "$INVENTORY_PATH/$FILE" ]; then echo "❌ ERROR: Required file missing: $FILE" exit 1 fi done echo "✅ Pre-flight checks passed" ``` ### 1. Load Phase 0 Findings Using Structured Operations <load-phase0-outputs> Use the Read tool to load all Phase 0 outputs: 1. `$INVENTORY_PATH/component_catalog.json` 2. `$INVENTORY_PATH/reusable_components.json` 3. `$INVENTORY_PATH/pattern_matches.json` 4. `$TASK_OUTPUT_FOLDER/context.json` Structure the loaded data: ```json { "inventory": { "components": [...], "reusable": { "must_reuse": [...], "should_reuse": [...], "warnings": [] }, "patterns": { "matched": [...], "learned": {...} } }, "context": { "use_preference_files": boolean, "use_examples": boolean, "architectural_guidance": {...} } } ``` Process duplication warnings with priority levels: - 🔴 CRITICAL: User patterns that must be followed - ⚠️ WARNING: Similar components that should be reused - 📝 INFO: Opportunities for consolidation </load-phase0-outputs> ### 2. Task Analysis and Complexity Assessment <task-analysis> Use the Read tool to load task specification: - `.aidev-storage/tasks/$TASK_FILENAME.md` - `.aidev-storage/tasks/$TASK_FILENAME.json` (for metadata) Perform structured task analysis: ```json { "task_complexity": { "score": 0-100, "factors": { "component_count": 0-10, "integration_complexity": 0-10, "state_management": 0-10, "external_dependencies": 0-10, "performance_requirements": 0-10 }, "classification": "simple|normal|complex" }, "requirements": { "functional": [...], "non_functional": [...], "constraints": [...] }, "feedback_priority": "primary|secondary|none" } ``` </task-analysis> ### 3. Architectural Analysis #### 3.1 Load Preferences and Patterns <load-preferences> If preference files are enabled, use the Read tool to load: - `.aidev-storage/preferences/components.md` - `.aidev-storage/preferences/folder-structure.md` - `.aidev-storage/preferences/statemanagent.md` - `.aidev-storage/preferences/writing-style.md` Structure preferences into actionable rules: ```json { "preferences": { "components": { "naming_convention": "pattern", "structure": "compound|simple", "export_style": "named|default" }, "architecture": { "folder_structure": "feature|layer|domain", "state_management": "context|redux|zustand", "api_pattern": "rest|graphql|trpc" } } } ``` </load-preferences> <load-learned-patterns> Always load learned patterns using the Read tool: - `.aidev-storage/planning/learned-patterns.json` Process and prioritize patterns: ```json { "critical_patterns": [ { "id": "pattern_id", "category": "api|state|architecture|error-handling", "rule": "pattern_description", "implementation": "how_to_implement", "priority": 0.9-1.0, "source": "user_correction", "enforcement": "mandatory" } ], "pattern_summary": { "total_critical": 0, "by_category": { "api": 0, "state": 0, "architecture": 0 } } } ``` Pattern enforcement levels: - 🔴 CRITICAL (0.9+): User corrections - MUST follow - 🟡 HIGH (0.7-0.9): Strong patterns - SHOULD follow - 🟢 MEDIUM (0.5-0.7): Common patterns - CONSIDER following </load-learned-patterns> #### 3.2 Component Design Process <component-design-process> Design components based on: 1. Task requirements analysis 2. Inventory findings from Phase 0 3. Learned patterns (CRITICAL priority) 4. User preferences 5. Architectural best practices Structure the design: ```json { "components": { "new": [ { "name": "ComponentName", "type": "presentation|container|compound", "responsibilities": [...], "props_interface": {...}, "state_management": "local|context|store", "tests_required": [...] } ], "reused": [ { "existing_path": "path/to/component", "usage_pattern": "direct|extended|wrapped", "modifications": "none|minor|major" } ] }, "architecture": { "layers": { "presentation": [...], "business_logic": [...], "data_access": [...] }, "patterns": { "state_management": "pattern_name", "data_flow": "unidirectional|bidirectional", "component_communication": "props|context|events" } }, "decisions": [ { "id": "decision_id", "type": "architecture|pattern|technology", "decision": "what_was_decided", "rationale": "why_this_choice", "alternatives": [...], "impact": "high|medium|low" } ] } ``` </component-design-process> <record-decisions> For each architectural decision, append to decision_tree.jsonl: ```json { "timestamp": "ISO_timestamp", "phase": "architect", "decision_type": "architecture|pattern|reuse", "decision": "description", "reasoning": "detailed_rationale", "impact": "expected_impact", "alternatives_considered": [...] } ``` </record-decisions> ``` ### 4. Test Specification Design <test-strategy> Design comprehensive test specifications based on: 1. Component responsibilities 2. Task complexity score 3. Existing test patterns 4. Coverage requirements Test specification structure: ```json { "test_strategy": { "approach": "tdd|bdd|hybrid", "coverage_targets": { "statements": 80, "branches": 75, "functions": 80, "lines": 80 }, "testing_pyramid": { "unit": 70, "integration": 20, "e2e": 10 } }, "test_specifications": { "unit_tests": [ { "component": "ComponentName", "test_suite": "ComponentName.test.tsx", "test_cases": [ { "id": "test_id", "name": "should render with required props", "type": "render|behavior|state|integration", "given": "initial_conditions", "when": "action_performed", "then": "expected_outcome", "priority": "critical|high|normal" } ] } ], "integration_tests": [...], "e2e_scenarios": [...] }, "test_data": { "fixtures": [ { "name": "fixture_name", "type": "mock|stub|spy", "data": {...} } ], "factories": [...], "edge_cases": [...] } } ``` For pattern tasks: ```json { "pattern_validation": { "example_usage": "required", "documentation": "required", "line_count": "50-100", "complexity": "low" } } ``` </test-strategy> <write-test-specs> Use the Write tool to save test specifications: - Path: `.aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/test_specifications.json` </write-test-specs> ``` ### 5. Architecture Decision Records (ADR) <architecture-decisions> Document all architectural decisions with full context: ```json { "adr_metadata": { "task_id": "id", "created_at": "ISO_timestamp", "architect_phase": "1" }, "decisions": [ { "id": "ADR-001", "title": "State Management Approach", "status": "accepted|proposed|deprecated", "context": "why_this_decision_is_needed", "decision": "what_we_decided", "rationale": "detailed_reasoning", "consequences": { "positive": [...], "negative": [...], "neutral": [...] }, "alternatives_considered": [ { "option": "alternative_name", "pros": [...], "cons": [...], "rejection_reason": "why_not_chosen" } ], "related_patterns": ["pattern_ids"], "implementation_notes": "guidance_for_phase3" } ], "constraints": [ { "type": "technical|business|regulatory", "description": "constraint_description", "impact": "how_it_affects_design" } ], "assumptions": [ { "assumption": "what_we_assume", "risk_if_invalid": "potential_impact", "validation_method": "how_to_verify" } ] } ``` </architecture-decisions> <write-architecture-decisions> Use the Write tool to save architecture decisions: - Path: `.aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/architecture_decisions.json` </write-architecture-decisions> ``` ### 4. Generate Enhanced PRP ```bash echo "📄 Generating comprehensive PRP..." # Load PRP template if [ ! -f ".aidev-storage/templates/automated-prp-template.md" ]; then echo "❌ ERROR: PRP template not found" echo "Required template: .aidev-storage/templates/automated-prp-template.md" exit 1 fi # Create PRP with all enhancements cat > ".aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/prp.md" << EOF --- name: "Enhanced PRP for $TASK_NAME" task_id: "$TASK_ID" phase: "architect" incorporates_inventory: true test_first_approach: true --- # 🎯 Goal $TASK_DESCRIPTION ## 📊 Inventory Findings ### Reusable Components Identified $REUSABLE_SUMMARY ### Duplication Warnings $DUPLICATION_WARNINGS ### Pattern Matches $PATTERN_MATCHES ## 🧪 Test-First Development Plan ### Test Strategy 1. **Unit Tests**: Cover all new components and functions 2. **Integration Tests**: Verify component interactions 3. **E2E Tests**: Validate critical user journeys ### Test Specifications $TEST_SPECIFICATIONS ### Coverage Requirements - Minimum: 80% code coverage - Critical paths: 100% coverage - Edge cases: Comprehensive testing ## 🏗️ Architecture Design ### Component Hierarchy $COMPONENT_HIERARCHY ### State Management $STATE_MANAGEMENT_APPROACH ### Data Flow $DATA_FLOW_DIAGRAM ### API Design $API_SPECIFICATIONS ## 📦 Implementation Plan ### Phase 2: Test Designer - Create test files based on specifications - Set up test fixtures and mocks - Implement test utilities ### Phase 3: Programmer - Implement features to pass tests - Follow TDD red-green-refactor cycle - Use existing components from inventory ### Phase 4: Test Executor - Run all test suites - Verify coverage requirements - Performance testing ### Phase 5: Reviewer - Code quality review - Security audit - Performance optimization ## ✅ Acceptance Criteria ### Functional Requirements $FUNCTIONAL_REQUIREMENTS ### Non-Functional Requirements - Performance: $PERFORMANCE_TARGETS - Security: $SECURITY_REQUIREMENTS - Accessibility: WCAG 2.1 AA compliance ### Test Criteria - All tests passing - Coverage targets met - No regression in existing tests ## 🚨 Risk Mitigation ### Technical Risks $TECHNICAL_RISKS ### Mitigation Strategies $MITIGATION_STRATEGIES ## 📋 Detailed Implementation Steps ### Step 1: Test Implementation (Phase 2) $TEST_IMPLEMENTATION_DETAILS ### Step 2: Feature Implementation (Phase 3) $FEATURE_IMPLEMENTATION_DETAILS ### Step 3: Validation (Phase 4) $VALIDATION_DETAILS ### Step 4: Review (Phase 5) $REVIEW_DETAILS ## 🔄 Code Reuse Checklist Before implementing ANY new code: - [ ] Check inventory catalog for existing implementations - [ ] Review reusable_components.json - [ ] Verify no duplication of functionality - [ ] Extend existing components where possible - [ ] Follow established patterns ## 📐 Design Patterns ### Patterns to Follow $PATTERNS_TO_USE ### Anti-Patterns to Avoid $ANTI_PATTERNS ## 📚 User Preferences and Learned Patterns $PREFERENCES_CONTEXT $LEARNED_PATTERNS_CONTEXT ## 🎯 Success Metrics - Test Coverage: ≥80% - Zero code duplication - All tests passing - Performance benchmarks met - Security scan clean EOF # Note: In real implementation, all $VARIABLES would be replaced with actual content ``` ### 5. Update Component Design ```bash # Finalize component design based on analysis FINAL_DESIGN=$(jq -n \ --argjson reusable "$REUSABLE" \ '{ "components_to_create": [ { "name": "FeatureComponent", "type": "Client Component", "responsibilities": ["Handle user interaction", "Manage local state"], "tests_required": ["Render test", "Interaction test", "State test"] } ], "components_to_reuse": ($reusable.components), "integration_points": [], "api_endpoints": [] }') echo "$FINAL_DESIGN" > ".aidev-storage/tasks_output/$TASK_ID/phase_outputs/architect/component_design.json" ``` ### 6. Update Shared Context ```bash echo "📊 Updating shared context..." # Update context with architect findings UPDATED_CONTEXT=$(echo "$CONTEXT" | jq \ --arg phase "architect" \ --argjson specs "$TEST_SPECS" \ '.current_phase = $phase | .phases_completed += [$phase] | .phase_history += [{ phase: $phase, completed_at: (now | strftime("%Y-%m-%dT%H:%M:%SZ")), success: true, key_outputs: { prp_created: true, test_specs_count: ($specs.unit_tests | length), components_designed: 5, reuse_identified: true } }] | .critical_context.test_specifications = $specs') echo "$UPDATED_CONTEXT" > ".aidev-storage/tasks_output/$TASK_ID/context.json" ``` ### 9. Final Validation <phase1-validation> Perform final validation checks: 1. **Output Validation**: - Verify all required files exist in phase_outputs/architect/ - Check PRP has no unresolved placeholders or variables - Validate JSON files are well-formed - Ensure test specifications are complete 2. **Content Validation**: - Architecture decisions have rationale - Test cases have clear expectations - Component design includes reuse analysis - All learned patterns are addressed 3. **Compliance Validation**: - No source code files created - No modifications outside .aidev-storage/ - All decisions recorded in decision_tree.jsonl - Context properly updated 4. **Quality Metrics**: - Reuse percentage calculated - Complexity score documented - Test coverage targets defined - Risk mitigation strategies present </phase1-validation> ```bash # Minimal validation check for source code creation if [ $(find . -type f -newer "$TASK_OUTPUT_FOLDER/phase_outputs/.phase1_start_marker" $ -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" $ | grep -v ".aidev-storage" | wc -l) -gt 0 ]; then echo "❌ FATAL ERROR: Phase 1 created source code files!" exit 1 fi echo "✅ Phase 1 completed successfully" echo "📄 Enhanced PRP created with:" echo " - Comprehensive test specifications" echo " - Detailed architectural decisions" echo " - Maximum code reuse strategy" echo " - Learned pattern integration" echo "➡️ Ready for Phase 2: Test Designer" ``` ## Key Requirements <phase1-constraints> <architect-only> This phase MUST: □ Create comprehensive PRP □ Design test specifications □ Incorporate inventory findings □ Document architectural decisions □ Plan for maximum code reuse This phase MUST NOT: □ Write any code files □ Implement features □ Create actual test files □ Run any builds or tests </architect-only> <test-first-focus> The PRP must include: □ Detailed test specifications □ Test data requirements □ Coverage targets □ Test scenarios for each component □ Integration test plans </test-first-focus> </phase1-constraints> ## Success Criteria Phase 1 is successful when: - Comprehensive PRP exists with no placeholders - Test specifications are detailed and complete - Architecture decisions are documented - Code reuse opportunities are maximized - All outputs are created - No code files were generated