@poolzin/pool-bot 2026.3.11 → 2026.3.14

package/extensions/agency-agents/agents/strategy/playbooks/phase-3-build.md

@@ -0,0 +1,286 @@
+# 🔨 Phase 3 Playbook — Build & Iterate
+
+> **Duration**: 2-12 weeks (varies by scope) | **Agents**: 15-30+ | **Gate Keeper**: Agents Orchestrator
+
+---
+
+## Objective
+
+Implement all features through continuous Dev↔QA loops. Every task is validated before the next begins. This is where the bulk of the work happens — and where NEXUS's orchestration delivers the most value.
+
+## Pre-Conditions
+
+- [ ] Phase 2 Quality Gate passed (foundation verified)
+- [ ] Sprint Prioritizer backlog available with RICE scores
+- [ ] CI/CD pipeline operational
+- [ ] Design system and component library ready
+- [ ] API scaffold with auth system ready
+
+## The Dev↔QA Loop — Core Mechanic
+
+The Agents Orchestrator manages every task through this cycle:
+
+```
+FOR EACH task IN sprint_backlog (ordered by RICE score):
+
+  1. ASSIGN task to appropriate Developer Agent (see assignment matrix)
+  2. Developer IMPLEMENTS task
+  3. Evidence Collector TESTS task
+     - Visual screenshots (desktop, tablet, mobile)
+     - Functional verification against acceptance criteria
+     - Brand consistency check
+  4. IF verdict == PASS:
+       Mark task complete
+       Move to next task
+     ELIF verdict == FAIL AND attempts < 3:
+       Send QA feedback to Developer
+       Developer FIXES specific issues
+       Return to step 3
+     ELIF attempts >= 3:
+       ESCALATE to Agents Orchestrator
+       Orchestrator decides: reassign, decompose, defer, or accept
+  5. UPDATE pipeline status report
+```
+
+## Agent Assignment Matrix
+
+### Primary Developer Assignment
+
+| Task Category | Primary Agent | Backup Agent | QA Agent |
+|--------------|--------------|-------------|----------|
+| **React/Vue/Angular UI** | Frontend Developer | Rapid Prototyper | Evidence Collector |
+| **REST/GraphQL API** | Backend Architect | Senior Developer | API Tester |
+| **Database operations** | Backend Architect | — | API Tester |
+| **Mobile (iOS/Android)** | Mobile App Builder | — | Evidence Collector |
+| **ML model/pipeline** | AI Engineer | — | Test Results Analyzer |
+| **CI/CD/Infrastructure** | DevOps Automator | Infrastructure Maintainer | Performance Benchmarker |
+| **Premium/complex feature** | Senior Developer | Backend Architect | Evidence Collector |
+| **Quick prototype/POC** | Rapid Prototyper | Frontend Developer | Evidence Collector |
+| **WebXR/immersive** | XR Immersive Developer | — | Evidence Collector |
+| **visionOS** | visionOS Spatial Engineer | macOS Spatial/Metal Engineer | Evidence Collector |
+| **Cockpit controls** | XR Cockpit Interaction Specialist | XR Interface Architect | Evidence Collector |
+| **CLI/terminal tools** | Terminal Integration Specialist | — | API Tester |
+| **Code intelligence** | LSP/Index Engineer | — | Test Results Analyzer |
+| **Performance optimization** | Performance Benchmarker | Infrastructure Maintainer | Performance Benchmarker |
+
+### Specialist Support (activated as needed)
+
+| Specialist | When to Activate | Trigger |
+|-----------|-----------------|---------|
+| UI Designer | Component needs visual refinement | Developer requests design guidance |
+| Whimsy Injector | Feature needs delight/personality | UX review identifies opportunity |
+| Visual Storyteller | Visual narrative content needed | Content requires visual assets |
+| Brand Guardian | Brand consistency concern | QA finds brand deviation |
+| XR Interface Architect | Spatial interaction design needed | XR feature requires UX guidance |
+| Data Analytics Reporter | Deep data analysis needed | Feature requires analytics integration |
+
+## Parallel Build Tracks
+
+For NEXUS-Full deployments, four tracks run simultaneously:
+
+### Track A: Core Product Development
+```
+Managed by: Agents Orchestrator (Dev↔QA loop)
+Agents: Frontend Developer, Backend Architect, AI Engineer,
+        Mobile App Builder, Senior Developer
+QA: Evidence Collector, API Tester, Test Results Analyzer
+
+Sprint cadence: 2-week sprints
+Daily: Task implementation + QA validation
+End of sprint: Sprint review + retrospective
+```
+
+### Track B: Growth & Marketing Preparation
+```
+Managed by: Project Shepherd
+Agents: Growth Hacker, Content Creator, Social Media Strategist,
+        App Store Optimizer
+
+Sprint cadence: Aligned with Track A milestones
+Activities:
+- Growth Hacker → Design viral loops and referral mechanics
+- Content Creator → Build launch content pipeline
+- Social Media Strategist → Plan cross-platform campaign
+- App Store Optimizer → Prepare store listing (if mobile)
+```
+
+### Track C: Quality & Operations
+```
+Managed by: Agents Orchestrator
+Agents: Evidence Collector, API Tester, Performance Benchmarker,
+        Workflow Optimizer, Experiment Tracker
+
+Continuous activities:
+- Evidence Collector → Screenshot QA for every task
+- API Tester → Endpoint validation for every API task
+- Performance Benchmarker → Periodic load testing
+- Workflow Optimizer → Process improvement identification
+- Experiment Tracker → A/B test setup for validated features
+```
+
+### Track D: Brand & Experience Polish
+```
+Managed by: Brand Guardian
+Agents: UI Designer, Brand Guardian, Visual Storyteller,
+        Whimsy Injector
+
+Triggered activities:
+- UI Designer → Component refinement when QA identifies visual issues
+- Brand Guardian → Periodic brand consistency audit
+- Visual Storyteller → Visual narrative assets as features complete
+- Whimsy Injector → Micro-interactions and delight moments
+```
+
+## Sprint Execution Template
+
+### Sprint Planning (Day 1)
+
+```
+Sprint Prioritizer activates:
+1. Review backlog with updated RICE scores
+2. Select tasks for sprint based on team velocity
+3. Assign tasks to developer agents
+4. Identify dependencies and ordering
+5. Set sprint goal and success criteria
+
+Output: Sprint Plan with task assignments
+```
+
+### Daily Execution (Day 2 to Day N-1)
+
+```
+Agents Orchestrator manages:
+1. Current task status check
+2. Dev↔QA loop execution
+3. Blocker identification and resolution
+4. Progress tracking and reporting
+
+Status report format:
+- Tasks completed today: [list]
+- Tasks in QA: [list]
+- Tasks in development: [list]
+- Blocked tasks: [list with reason]
+- QA pass rate: [X/Y]
+```
+
+### Sprint Review (Day N)
+
+```
+Project Shepherd facilitates:
+1. Demo completed features
+2. Review QA evidence for each task
+3. Collect stakeholder feedback
+4. Update backlog based on learnings
+
+Participants: All active agents + stakeholders
+Output: Sprint Review Summary
+```
+
+### Sprint Retrospective
+
+```
+Workflow Optimizer facilitates:
+1. What went well?
+2. What could improve?
+3. What will we change next sprint?
+4. Process efficiency metrics
+
+Output: Retrospective Action Items
+```
+
+## Orchestrator Decision Logic
+
+### Task Failure Handling
+
+```
+WHEN task fails QA:
+  IF attempt == 1:
+    → Send specific QA feedback to developer
+    → Developer fixes ONLY the identified issues
+    → Re-submit for QA
+    
+  IF attempt == 2:
+    → Send accumulated QA feedback
+    → Consider: Is the developer agent the right fit?
+    → Developer fixes with additional context
+    → Re-submit for QA
+    
+  IF attempt == 3:
+    → ESCALATE
+    → Options:
+      a) Reassign to different developer agent
+      b) Decompose task into smaller sub-tasks
+      c) Revise approach/architecture
+      d) Accept with known limitations (document)
+      e) Defer to future sprint
+    → Document decision and rationale
+```
+
+### Parallel Task Management
+
+```
+WHEN multiple tasks have no dependencies:
+  → Assign to different developer agents simultaneously
+  → Each runs independent Dev↔QA loop
+  → Orchestrator tracks all loops concurrently
+  → Merge completed tasks in dependency order
+
+WHEN task has dependencies:
+  → Wait for dependency to pass QA
+  → Then assign dependent task
+  → Include dependency context in handoff
+```
+
+## Quality Gate Checklist
+
+| # | Criterion | Evidence Source | Status |
+|---|-----------|----------------|--------|
+| 1 | All sprint tasks pass QA (100% completion) | Evidence Collector screenshots per task | ☐ |
+| 2 | All API endpoints validated | API Tester regression report | ☐ |
+| 3 | Performance baselines met (P95 < 200ms) | Performance Benchmarker report | ☐ |
+| 4 | Brand consistency verified (95%+ adherence) | Brand Guardian audit | ☐ |
+| 5 | No critical bugs (zero P0/P1 open) | Test Results Analyzer summary | ☐ |
+| 6 | All acceptance criteria met | Task-by-task verification | ☐ |
+| 7 | Code review completed for all PRs | Git history evidence | ☐ |
+
+## Gate Decision
+
+**Gate Keeper**: Agents Orchestrator
+
+- **PASS**: Feature-complete application → Phase 4 activation
+- **CONTINUE**: More sprints needed → Continue Phase 3
+- **ESCALATE**: Systemic issues → Studio Producer intervention
+
+## Handoff to Phase 4
+
+```markdown
+## Phase 3 → Phase 4 Handoff Package
+
+### For Reality Checker:
+- Complete application (all features implemented)
+- All QA evidence from Dev↔QA loops
+- API Tester regression results
+- Performance Benchmarker baseline data
+- Brand Guardian consistency audit
+- Known issues list (if any accepted limitations)
+
+### For Legal Compliance Checker:
+- Data handling implementation details
+- Privacy policy implementation
+- Consent management implementation
+- Security measures implemented
+
+### For Performance Benchmarker:
+- Application URLs for load testing
+- Expected traffic patterns
+- Performance budgets from architecture
+
+### For Infrastructure Maintainer:
+- Production environment requirements
+- Scaling configuration needs
+- Monitoring alert thresholds
+```
+
+---
+
+*Phase 3 is complete when all sprint tasks pass QA, all API endpoints are validated, performance baselines are met, and no critical bugs remain open.*

package/extensions/agency-agents/agents/strategy/playbooks/phase-4-hardening.md

@@ -0,0 +1,332 @@
+# 🛡️ Phase 4 Playbook — Quality & Hardening
+
+> **Duration**: 3-7 days | **Agents**: 8 | **Gate Keeper**: Reality Checker (sole authority)
+
+---
+
+## Objective
+
+The final quality gauntlet. The Reality Checker defaults to "NEEDS WORK" — you must prove production readiness with overwhelming evidence. This phase exists because first implementations typically need 2-3 revision cycles, and that's healthy.
+
+## Pre-Conditions
+
+- [ ] Phase 3 Quality Gate passed (all tasks QA'd)
+- [ ] Phase 3 Handoff Package received
+- [ ] All features implemented and individually verified
+
+## Critical Mindset
+
+> **The Reality Checker's default verdict is NEEDS WORK.**
+> 
+> This is not pessimism — it's realism. Production readiness requires:
+> - Complete user journeys working end-to-end
+> - Cross-device consistency (desktop, tablet, mobile)
+> - Performance under load (not just happy path)
+> - Security validation (not just "we added auth")
+> - Specification compliance (every requirement, not most)
+>
+> A B/B+ rating on first pass is normal and expected.
+
+## Agent Activation Sequence
+
+### Step 1: Evidence Collection (Day 1-2, All Parallel)
+
+#### 📸 Evidence Collector — Comprehensive Visual Evidence
+```
+Activate Evidence Collector for comprehensive system evidence on [PROJECT].
+
+Deliverables required:
+1. Full screenshot suite:
+   - Desktop (1920x1080) — every page/view
+   - Tablet (768x1024) — every page/view
+   - Mobile (375x667) — every page/view
+2. Interaction evidence:
+   - Navigation flows (before/after clicks)
+   - Form interactions (empty, filled, submitted, error states)
+   - Modal/dialog interactions
+   - Accordion/expandable content
+3. Theme evidence:
+   - Light mode — all pages
+   - Dark mode — all pages
+   - System preference detection
+4. Error state evidence:
+   - 404 pages
+   - Form validation errors
+   - Network error handling
+   - Empty states
+
+Format: Screenshot Evidence Package with test-results.json
+Timeline: 2 days
+```
+
+#### 🔌 API Tester — Full API Regression
+```
+Activate API Tester for complete API regression on [PROJECT].
+
+Deliverables required:
+1. Endpoint regression suite:
+   - All endpoints tested (GET, POST, PUT, DELETE)
+   - Authentication/authorization verification
+   - Input validation testing
+   - Error response verification
+2. Integration testing:
+   - Cross-service communication
+   - Database operation verification
+   - External API integration
+3. Edge case testing:
+   - Rate limiting behavior
+   - Large payload handling
+   - Concurrent request handling
+   - Malformed input handling
+
+Format: API Test Report with pass/fail per endpoint
+Timeline: 2 days
+```
+
+#### ⚡ Performance Benchmarker — Load Testing
+```
+Activate Performance Benchmarker for load testing on [PROJECT].
+
+Deliverables required:
+1. Load test at 10x expected traffic:
+   - Response time distribution (P50, P95, P99)
+   - Throughput under load
+   - Error rate under load
+   - Resource utilization (CPU, memory, network)
+2. Core Web Vitals measurement:
+   - LCP (Largest Contentful Paint) < 2.5s
+   - FID (First Input Delay) < 100ms
+   - CLS (Cumulative Layout Shift) < 0.1
+3. Database performance:
+   - Query execution times
+   - Connection pool utilization
+   - Index effectiveness
+4. Stress test results:
+   - Breaking point identification
+   - Graceful degradation behavior
+   - Recovery time after overload
+
+Format: Performance Certification Report
+Timeline: 2 days
+```
+
+#### ⚖️ Legal Compliance Checker — Final Compliance Audit
+```
+Activate Legal Compliance Checker for final compliance audit on [PROJECT].
+
+Deliverables required:
+1. Privacy compliance verification:
+   - Privacy policy accuracy
+   - Consent management functionality
+   - Data subject rights implementation
+   - Cookie consent implementation
+2. Security compliance:
+   - Data encryption (at rest and in transit)
+   - Authentication security
+   - Input sanitization
+   - OWASP Top 10 check
+3. Regulatory compliance:
+   - GDPR requirements (if applicable)
+   - CCPA requirements (if applicable)
+   - Industry-specific requirements
+4. Accessibility compliance:
+   - WCAG 2.1 AA verification
+   - Screen reader compatibility
+   - Keyboard navigation
+
+Format: Compliance Certification Report
+Timeline: 2 days
+```
+
+### Step 2: Analysis (Day 3-4, Parallel, after Step 1)
+
+#### 📊 Test Results Analyzer — Quality Metrics Aggregation
+```
+Activate Test Results Analyzer for quality metrics aggregation on [PROJECT].
+
+Input: ALL Step 1 reports
+Deliverables required:
+1. Aggregate quality dashboard:
+   - Overall quality score
+   - Category breakdown (visual, functional, performance, security, compliance)
+   - Issue severity distribution
+   - Trend analysis (if multiple test cycles)
+2. Issue prioritization:
+   - Critical issues (must fix before production)
+   - High issues (should fix before production)
+   - Medium issues (fix in next sprint)
+   - Low issues (backlog)
+3. Risk assessment:
+   - Production readiness probability
+   - Remaining risk areas
+   - Recommended mitigations
+
+Format: Quality Metrics Dashboard
+Timeline: 1 day
+```
+
+#### 🔄 Workflow Optimizer — Process Efficiency Review
+```
+Activate Workflow Optimizer for process efficiency review on [PROJECT].
+
+Input: Phase 3 execution data + Step 1 findings
+Deliverables required:
+1. Process efficiency analysis:
+   - Dev↔QA loop efficiency (first-pass rate, average retries)
+   - Bottleneck identification
+   - Time-to-resolution for different issue types
+2. Improvement recommendations:
+   - Process changes for Phase 6 operations
+   - Automation opportunities
+   - Quality improvement suggestions
+
+Format: Optimization Recommendations Report
+Timeline: 1 day
+```
+
+#### 🏗️ Infrastructure Maintainer — Production Readiness Check
+```
+Activate Infrastructure Maintainer for production readiness on [PROJECT].
+
+Deliverables required:
+1. Production environment validation:
+   - All services healthy and responding
+   - Auto-scaling configured and tested
+   - Load balancer configuration verified
+   - SSL/TLS certificates valid
+2. Monitoring validation:
+   - All critical metrics being collected
+   - Alert rules configured and tested
+   - Dashboard access verified
+   - Log aggregation working
+3. Disaster recovery validation:
+   - Backup systems operational
+   - Recovery procedures documented and tested
+   - Failover mechanisms verified
+4. Security validation:
+   - Firewall rules reviewed
+   - Access controls verified
+   - Secrets management confirmed
+   - Vulnerability scan clean
+
+Format: Infrastructure Readiness Report
+Timeline: 1 day
+```
+
+### Step 3: Final Judgment (Day 5-7, Sequential)
+
+#### 🔍 Reality Checker — THE FINAL VERDICT
+```
+Activate Reality Checker for final integration testing on [PROJECT].
+
+MANDATORY PROCESS — DO NOT SKIP:
+
+Step 1: Reality Check Commands
+- Verify what was actually built (ls, grep for claimed features)
+- Cross-check claimed features against specification
+- Run comprehensive screenshot capture
+- Review all evidence from Step 1 and Step 2
+
+Step 2: QA Cross-Validation
+- Review Evidence Collector findings
+- Cross-reference with API Tester results
+- Verify Performance Benchmarker data
+- Confirm Legal Compliance Checker findings
+
+Step 3: End-to-End System Validation
+- Test COMPLETE user journeys (not individual features)
+- Verify responsive behavior across ALL devices
+- Check interaction flows end-to-end
+- Review actual performance data
+
+Step 4: Specification Reality Check
+- Quote EXACT text from original specification
+- Compare with ACTUAL implementation evidence
+- Document EVERY gap between spec and reality
+- No assumptions — evidence only
+
+VERDICT OPTIONS:
+- READY: Overwhelming evidence of production readiness (rare first pass)
+- NEEDS WORK: Specific issues identified with fix list (expected)
+- NOT READY: Major architectural issues requiring Phase 1/2 revisit
+
+Format: Reality-Based Integration Report
+Default: NEEDS WORK unless proven otherwise
+```
+
+## Quality Gate — THE FINAL GATE
+
+| # | Criterion | Threshold | Evidence Required |
+|---|-----------|-----------|-------------------|
+| 1 | User journeys complete | All critical paths working end-to-end | Reality Checker screenshots |
+| 2 | Cross-device consistency | Desktop + Tablet + Mobile all working | Responsive screenshots |
+| 3 | Performance certified | P95 < 200ms, LCP < 2.5s, uptime > 99.9% | Performance Benchmarker report |
+| 4 | Security validated | Zero critical vulnerabilities | Security scan + compliance report |
+| 5 | Compliance certified | All regulatory requirements met | Legal Compliance Checker report |
+| 6 | Specification compliance | 100% of spec requirements implemented | Point-by-point verification |
+| 7 | Infrastructure ready | Production environment validated | Infrastructure Maintainer report |
+
+## Gate Decision
+
+**Sole authority**: Reality Checker
+
+### If READY (proceed to Phase 5):
+```markdown
+## Phase 4 → Phase 5 Handoff Package
+
+### For Launch Team:
+- Reality Checker certification report
+- Performance certification
+- Compliance certification
+- Infrastructure readiness report
+- Known limitations (if any)
+
+### For Growth Hacker:
+- Product ready for users
+- Feature list for marketing messaging
+- Performance data for credibility
+
+### For DevOps Automator:
+- Production deployment approved
+- Blue-green deployment plan
+- Rollback procedures confirmed
+```
+
+### If NEEDS WORK (return to Phase 3):
+```markdown
+## Phase 4 → Phase 3 Return Package
+
+### Fix List (from Reality Checker):
+1. [Critical Issue 1]: [Description + evidence + fix instruction]
+2. [Critical Issue 2]: [Description + evidence + fix instruction]
+3. [High Issue 1]: [Description + evidence + fix instruction]
+...
+
+### Process:
+- Issues enter Dev↔QA loop (Phase 3 mechanics)
+- Each fix must pass Evidence Collector QA
+- When all fixes complete → Return to Phase 4 Step 3
+- Reality Checker re-evaluates with updated evidence
+
+### Expected: 2-3 revision cycles is normal
+```
+
+### If NOT READY (return to Phase 1/2):
+```markdown
+## Phase 4 → Phase 1/2 Return Package
+
+### Architectural Issues Identified:
+1. [Fundamental Issue]: [Why it can't be fixed in Phase 3]
+2. [Structural Problem]: [What needs to change at architecture level]
+
+### Recommended Action:
+- [ ] Revise system architecture (Phase 1)
+- [ ] Rebuild foundation (Phase 2)
+- [ ] Descope and redefine (Phase 1)
+
+### Studio Producer Decision Required
+```
+
+---
+
+*Phase 4 is complete when the Reality Checker issues a READY verdict with overwhelming evidence. NEEDS WORK is the expected first-pass result — it means the system is working but needs polish.*