chati-dev 1.4.0 → 2.0.1

package/framework/tasks/architect-stack-selection.md

@@ -0,0 +1,53 @@
+---
+id: architect-stack-selection
+agent: architect
+trigger: architect-design
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [stack-selection.yaml]
+handoff_to: architect-api-design
+autonomous_gate: true
+criteria:
+  - Specific technologies chosen for each layer
+  - Choices justified with technical reasoning
+  - Compatibility verified
+---
+# Select Technology Stack
+
+## Purpose
+Choose specific technologies for each architectural layer based on requirements and constraints.
+
+## Steps
+From brief: React frontend, Supabase backend (BaaS), PostgreSQL database.
+
+Expand with specific versions and libraries:
+- Frontend: React 18.2, Vite 5.x, TypeScript 5.x, TanStack Query, React Hook Form, Zod
+- Backend: Supabase (auth, database, storage)
+- Database: PostgreSQL 15+ (via Supabase)
+- UI: Tailwind CSS, Headless UI
+- Testing: Vitest, React Testing Library, Playwright
+
+Document rationale for each choice.
+
+## Output Format
+```yaml
+# stack-selection.yaml
+frontend:
+  framework: React 18.2 (team expertise, large ecosystem)
+  build_tool: Vite 5 (fast HMR, modern)
+  language: TypeScript 5 (type safety)
+  state: TanStack Query (server state caching)
+  forms: React Hook Form (performance)
+  validation: Zod (runtime validation, type inference)
+  ui: Tailwind CSS (utility-first, rapid development)
+backend:
+  platform: Supabase (BaaS, addresses team skill gap)
+  auth: Supabase Auth (JWT-based)
+  database: PostgreSQL 15 (via Supabase)
+  storage: Supabase Storage (image uploads)
+testing:
+  unit: Vitest (Vite-native, fast)
+  integration: React Testing Library
+  e2e: Playwright (cross-browser)
+```

package/framework/tasks/brief-consolidate.md

@@ -0,0 +1,249 @@
+---
+id: brief-consolidate
+agent: brief
+trigger: brief-constraint-identify
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [brief.yaml]
+handoff_to: detail
+autonomous_gate: false
+criteria:
+  - All requirements consolidated and prioritized
+  - MVP scope clearly defined
+  - User approval obtained
+  - Completeness score >= 95%
+---
+# Consolidate Brief Document
+
+## Purpose
+Compile all requirements gathering work into a comprehensive brief document for user approval.
+
+## Prerequisites
+- `requirements-raw.yaml`
+- `validation-report.yaml`
+- `stakeholder-map.yaml`
+- `constraints.yaml`
+
+## Steps
+
+### 1. Load All Artifacts
+Read all prerequisite files and verify completeness.
+
+### 2. Create Executive Summary
+5-7 sentence overview covering:
+- Project vision and goals
+- Target users
+- Key features
+- Success criteria
+- Timeline and budget
+
+### 3. Consolidate Requirements
+Merge and deduplicate requirements from all sources:
+- Functional requirements with priorities
+- Non-functional requirements with metrics
+- All resolved constraints
+- Success criteria
+
+### 4. Define MVP Scope
+Clearly separate:
+- **MVP (Phase 1)**: Must-have features for launch
+- **Phase 2**: Important but can wait
+- **Future**: Nice-to-have, long-term vision
+
+### 5. Document Personas
+Include all validated personas with:
+- Goals and pain points
+- User journeys (high-level)
+- Priority ranking
+
+### 6. Include Stakeholder Map
+Reference key stakeholders and decision makers.
+
+### 7. Document Assumptions and Risks
+- All assumptions made
+- Key risks identified
+- Mitigation strategies
+
+### 8. Calculate Completeness Score
+Verify all required elements present:
+- Functional requirements (20%)
+- Non-functional requirements (15%)
+- Constraints (15%)
+- Personas (15%)
+- Success criteria (15%)
+- MVP scope (20%)
+
+### 9. Present to User for Approval
+- Show executive summary
+- Highlight MVP scope
+- Point out key trade-offs made
+- Ask for explicit approval
+
+### 10. Generate Final Brief
+Create polished, presentation-ready document.
+
+## Decision Points
+- **User Requests Changes**: Iterate on requirements before proceeding
+- **Unclear Priorities**: Ask user to rank requirements
+
+## Error Handling
+- **Incomplete Data**: Request missing information before finalizing
+- **User Unavailable for Approval**: Document and proceed with flag
+
+## Output Format
+```yaml
+# brief.yaml
+timestamp: 2026-02-13T14:00:00Z
+status: approved
+approved_by: Product Owner
+approved_at: 2026-02-13T14:00:00Z
+
+executive_summary: |
+  Building a modern blogging platform for content creators to publish and
+  manage posts, integrated with existing WordPress content via API. Target
+  users are bloggers and site administrators. MVP includes user authentication,
+  post creation/editing, full-text search, and WordPress integration. Success
+  measured by 1000 users in first month and 4.5/5 satisfaction rating.
+  3-month timeline with $60k budget and 2-developer team using React +
+  Supabase.
+
+project_vision: |
+  Create an intuitive, fast blogging platform that empowers content creators
+  to focus on writing while providing powerful tools for discovery and engagement.
+
+functional_requirements:
+  mvp:
+    - FR-001: User registration with email/password
+    - FR-002: User login with JWT authentication
+    - FR-003: Create blog posts with title, content, tags, and images
+    - FR-004: Edit and delete own posts
+    - FR-005: Full-text search by keyword, tag, or author
+    - FR-006: View post details
+    - FR-007: Integration with WordPress API to display existing content
+  phase_2:
+    - FR-008: Admin moderation interface
+    - FR-009: Comment system
+    - FR-010: User profiles and bios
+    - FR-011: Post analytics and views
+  future:
+    - FR-012: Social sharing
+    - FR-013: Email notifications
+    - FR-014: Draft auto-save
+    - FR-015: Rich text editor with embeds
+
+non_functional_requirements:
+  performance:
+    - NFR-001: Page load time <2 seconds (P0)
+    - NFR-002: Search results in <1 second (P1)
+  scalability:
+    - NFR-003: Support 10,000 concurrent users (P1)
+  security:
+    - NFR-004: HTTPS for all connections (P0)
+    - NFR-005: Password hashing with bcrypt (P0)
+    - NFR-006: GDPR compliant (P0)
+    - NFR-007: XSS and SQL injection protection (P0)
+  usability:
+    - NFR-008: Mobile responsive (P0)
+    - NFR-009: Accessible (WCAG 2.1 AA) (P1)
+  reliability:
+    - NFR-010: 99.5% uptime (P1)
+
+constraints:
+  technical:
+    - React frontend (team expertise)
+    - Supabase backend (BaaS to address team skill gap)
+    - WordPress API integration (existing content)
+  timeline:
+    - MVP launch: May 13, 2026 (3 months)
+  budget:
+    - Development: $60,000 (600 hours @ $100/hr)
+    - Hosting: $200/month
+  team:
+    - 2 React developers
+    - No backend expertise
+  regulatory:
+    - GDPR compliance required
+
+personas:
+  - name: Sarah (Content Creator)
+    role: Blogger
+    goals: [Write easily, Reach audience, Build following]
+    pain_points: [Slow tools, Complex formatting, Poor analytics]
+    priority: primary
+  - name: Mike (Administrator)
+    role: Site Admin
+    goals: [Maintain quality, Manage users, Monitor health]
+    pain_points: [Manual moderation, Limited tools]
+    priority: secondary
+  - name: Emily (Reader)
+    role: Visitor
+    goals: [Discover content, Easy reading, Save favorites]
+    pain_points: [Hard to find content, Cluttered UI]
+    priority: primary
+
+success_criteria:
+  business:
+    - 1000 registered users in first month
+    - 500 published posts in first month
+  technical:
+    - <2s average page load time
+    - 99.5% uptime
+    - Zero critical security vulnerabilities
+  user:
+    - 4.5/5 user satisfaction rating
+    - <5 minutes to publish first post (new user)
+
+assumptions:
+  - WordPress API is stable and documented
+  - Supabase free tier sufficient for MVP
+  - Team available full-time (100 hours/month each)
+  - No major requirement changes during development
+
+risks:
+  - risk: Team unfamiliar with Supabase
+    mitigation: 1-week learning phase, thorough documentation review
+  - risk: WordPress API changes
+    mitigation: Implement adapter pattern for easy updates
+  - risk: Scope creep
+    mitigation: Strict MVP scope, feature freeze after approval
+
+mvp_scope:
+  included:
+    - User authentication (registration, login, JWT)
+    - Post management (create, edit, delete, view)
+    - Full-text search
+    - WordPress integration (read-only)
+    - Mobile responsive UI
+  excluded:
+    - Comments (phase 2)
+    - Admin moderation (phase 2)
+    - Analytics (phase 2)
+    - Social features (future)
+
+estimated_effort:
+  total_hours: 480
+  breakdown:
+    setup_and_infrastructure: 40 hours
+    authentication: 60 hours
+    post_management: 120 hours
+    search: 60 hours
+    wordpress_integration: 40 hours
+    ui_ux: 100 hours
+    testing: 60 hours
+  buffer: 120 hours (20%)
+
+timeline:
+  start_date: 2026-02-14
+  mvp_launch: 2026-05-13
+  duration_weeks: 12
+
+completeness_score: 96
+approval_status: approved
+next_phase: detail
+handoff_note: |
+  Brief approved. MVP scope defined and constrained to fit 3-month timeline
+  with 2-developer team. Key trade-off: Using Supabase BaaS to address
+  backend skill gap. Next step: Detail agent to expand into full PRD with
+  technical specifications.
+```

package/framework/tasks/brief-constraint-identify.md

@@ -0,0 +1,277 @@
+---
+id: brief-constraint-identify
+agent: brief
+trigger: brief-stakeholder-map
+phase: clarity
+requires_input: true
+parallelizable: false
+outputs: [constraints.yaml]
+handoff_to: brief-consolidate
+autonomous_gate: true
+criteria:
+  - All constraint types identified
+  - Constraint conflicts resolved
+  - Realistic feasibility assessment
+---
+# Identify and Resolve Constraint Conflicts
+
+## Purpose
+Identify all project constraints, detect conflicts, and work with user to resolve them.
+
+## Prerequisites
+- `validation-report.yaml` with initial constraints
+- `stakeholder-map.yaml` for authority on constraint resolution
+
+## Steps
+
+### 1. Consolidate All Constraints
+From previous artifacts, gather:
+- Technical constraints
+- Timeline constraints
+- Budget constraints
+- Team constraints
+- Regulatory/compliance constraints
+- Business constraints
+
+### 2. Analyze Each Constraint Type
+
+**Technical Constraints**:
+- Must-use technologies
+- Integration requirements
+- Platform requirements
+- Data constraints
+- Infrastructure limitations
+
+**Timeline Constraints**:
+- Hard deadlines (launch date, regulatory deadline)
+- Soft deadlines (preferred dates)
+- Milestones
+- Dependencies on external events
+
+**Budget Constraints**:
+- Development budget (hours × rate)
+- Infrastructure budget (hosting, services)
+- Third-party service costs (APIs, SaaS)
+- One-time vs. recurring costs
+
+**Team Constraints**:
+- Team size and composition
+- Skill levels and gaps
+- Availability (full-time, part-time, contract)
+- Timezone distribution
+
+**Regulatory Constraints**:
+- GDPR, CCPA (data privacy)
+- HIPAA (healthcare)
+- PCI-DSS (payments)
+- SOC2 (security)
+- Industry-specific regulations
+
+### 3. Detect Constraint Conflicts
+Common conflicts:
+- **Time vs. Scope**: Not enough time to build all features
+- **Budget vs. Quality**: Budget doesn't support proper testing
+- **Team Skills vs. Tech Stack**: Team doesn't know required technologies
+- **Timeline vs. Quality**: Rush leads to technical debt
+- **Multiple Hard Deadlines**: Can't meet all simultaneously
+
+### 4. Assess Constraint Flexibility
+For each constraint, determine:
+- **Fixed**: Cannot change (legal deadline, existing API)
+- **Negotiable**: Can discuss changes (MVP scope, timeline)
+- **Flexible**: Can easily adjust (nice-to-have features)
+
+### 5. Calculate Feasibility
+Estimate if project is feasible given constraints:
+- Required effort (hours) vs. available capacity (team × hours)
+- Required timeline vs. estimated development time
+- Required budget vs. estimated costs
+- Required skills vs. available skills
+
+If infeasible, flag with recommended adjustments.
+
+### 6. Present Conflicts to User
+For each conflict:
+- Describe the conflict
+- Explain the impact if not resolved
+- Provide 2-3 resolution options with trade-offs
+- Recommend preferred option
+
+### 7. Collect User Decisions
+- Which constraints are truly fixed?
+- Which can be relaxed?
+- How to resolve each conflict?
+- What are acceptable trade-offs?
+
+### 8. Update Constraint List
+- Mark fixed vs. flexible
+- Document resolutions
+- Note any assumptions made
+
+### 9. Re-assess Feasibility
+- After resolutions, is project now feasible?
+- If not, escalate to stakeholders for major decisions
+
+### 10. Document Final Constraints
+- Clear, unambiguous constraint list
+- All conflicts resolved
+- Feasibility confirmed
+
+## Decision Points
+- **Infeasible Project**: If project cannot be done within constraints, recommend scope reduction or constraint relaxation
+- **Major Conflict**: If conflict requires stakeholder decision, facilitate that conversation
+
+## Error Handling
+- **Unrealistic Expectations**: Gently educate user on typical timelines/costs
+- **Unwilling to Compromise**: Document the risk and proceed (user responsibility)
+
+## Output Format
+```yaml
+# constraints.yaml
+timestamp: 2026-02-13T13:45:00Z
+
+all_constraints:
+  technical:
+    - id: CT-001
+      constraint: Must integrate with existing WordPress blog API
+      flexibility: fixed
+      impact: high
+      reason: Business requirement, existing content must be accessible
+    - id: CT-002
+      constraint: Must use React for frontend
+      flexibility: negotiable
+      impact: medium
+      reason: Team expertise, but could learn Vue if needed
+  timeline:
+    - id: CT-003
+      constraint: MVP launch by May 13, 2026 (3 months)
+      flexibility: negotiable
+      impact: high
+      reason: Marketing campaign scheduled, but can adjust
+  budget:
+    - id: CT-004
+      constraint: Development budget is $60,000 (600 hours @ $100/hr)
+      flexibility: negotiable
+      impact: high
+      reason: Allocated budget for Q1-Q2, could request more if justified
+    - id: CT-005
+      constraint: Hosting budget is $200/month
+      flexibility: fixed
+      impact: medium
+      reason: Recurring budget approved, hard to change
+  team:
+    - id: CT-006
+      constraint: Team of 2 React developers, no backend experience
+      flexibility: fixed
+      impact: high
+      reason: Current team, hiring not possible short-term
+  regulatory:
+    - id: CT-007
+      constraint: Must be GDPR compliant for EU users
+      flexibility: fixed
+      impact: high
+      reason: Legal requirement
+
+detected_conflicts:
+  - conflict_id: CONF-001
+    description: Timeline too aggressive for scope
+    constraints_involved: [CT-003, functional requirements FR-001 through FR-008]
+    impact: Project will miss deadline or deliver incomplete features
+    severity: high
+    resolution_options:
+      - option: Reduce MVP scope to core features only (FR-001, FR-002, FR-005)
+        pros: Can meet timeline, focused MVP
+        cons: Deferred features delay user value
+        recommended: true
+      - option: Extend timeline to 5 months
+        pros: All features delivered with quality
+        cons: Misses marketing campaign
+        recommended: false
+      - option: Hire contractor for additional capacity
+        pros: Accelerate development
+        cons: Increases budget, onboarding overhead
+        recommended: false
+    user_decision: Reduce scope to core features
+    resolution: MVP scope reduced to user auth, posting, and search. Admin moderation and comments deferred to phase 2.
+
+  - conflict_id: CONF-002
+    description: Team lacks backend skills but project requires full-stack
+    constraints_involved: [CT-006, architecture requirements]
+    impact: Backend development will be slow, potential quality issues
+    severity: high
+    resolution_options:
+      - option: Use Backend-as-a-Service (Firebase, Supabase, AWS Amplify)
+        pros: Reduces backend complexity, team can focus on React
+        cons: Vendor lock-in, recurring costs
+        recommended: true
+      - option: Hire backend contractor
+        pros: Expert backend implementation
+        cons: Increases budget, coordination overhead
+        recommended: false
+      - option: Team learns backend while building
+        pros: Team skill development
+        cons: Slower development, higher bug risk
+        recommended: false
+    user_decision: Use Supabase (BaaS)
+    resolution: Supabase chosen for auth, database, and API. Team focuses on React frontend.
+
+  - conflict_id: CONF-003
+    description: Budget may not support 3-month intensive development
+    constraints_involved: [CT-004, CT-003]
+    impact: May run out of budget before completion
+    severity: medium
+    resolution_options:
+      - option: Reduce scope to fit budget
+        pros: Stays within budget
+        cons: Fewer features
+        recommended: true
+      - option: Request budget increase
+        pros: Full feature set
+        cons: Requires approval, may not be granted
+        recommended: false
+    user_decision: Reduced scope fits within budget
+    resolution: Scope reduction (CONF-001) brings estimated effort to 480 hours, fits within 600-hour budget with buffer.
+
+resolved_conflicts: 3
+remaining_conflicts: 0
+
+feasibility_assessment:
+  before_resolution:
+    required_effort_hours: 720
+    available_capacity_hours: 600 (2 devs × 3 months × 100 hours/month)
+    feasibility: infeasible
+    gap: 120 hours
+  after_resolution:
+    required_effort_hours: 480
+    available_capacity_hours: 600
+    feasibility: feasible
+    buffer: 120 hours (20%)
+    confidence: high
+
+final_constraints:
+  fixed:
+    - WordPress integration (CT-001)
+    - Hosting budget $200/month (CT-005)
+    - Team size 2 developers (CT-006)
+    - GDPR compliance (CT-007)
+  negotiable:
+    - React frontend (CT-002) - chosen, but could have been Vue
+    - Timeline 3 months (CT-003) - could extend if needed
+  flexible:
+    - Feature scope - reduced to MVP
+    - Development budget (CT-004) - could request more if justified
+
+assumptions:
+  - Supabase free tier sufficient for MVP, will upgrade as needed
+  - Developers available 100 hours/month each (full-time equivalent)
+  - No major requirements changes during development
+  - WordPress API is well-documented and stable
+
+risk_mitigations:
+  - 20% time buffer for unknowns and bugs
+  - Weekly checkpoint meetings to track progress
+  - Feature flags to enable/disable incomplete features
+  - Plan for soft launch before marketing campaign
+
+next_step: consolidate_brief
+```