chati-dev 1.4.0 → 2.0.2

package/framework/tasks/qa-planning-test-strategy.md

@@ -0,0 +1,217 @@
+---
+id: qa-planning-test-strategy
+agent: qa-planning
+trigger: orchestrator
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [test-strategy.yaml]
+handoff_to: qa-planning-gate-define
+autonomous_gate: false
+criteria:
+  - Test coverage plan defined for all layers
+  - Risk areas identified and prioritized
+  - Testing pyramid structure established
+---
+
+# Test Strategy
+
+## Purpose
+Define a comprehensive testing strategy covering unit, integration, end-to-end, and manual testing approaches tailored to the project's architecture and risk profile.
+
+## Prerequisites
+- Project brief and detail documents available
+- Architecture document defining system components
+- Phase plan showing implementation timeline
+- Task breakdown with complexity estimates
+
+## Steps
+
+1. **Analyze System Architecture**
+   - Review the architecture document to identify all system layers (CLI, agents, orchestrator, state management, file operations)
+   - Map component dependencies and interaction points
+   - Identify external integrations (MCPs, IDEs, package managers)
+   - Document stateful vs stateless components
+
+2. **Establish Testing Pyramid**
+   - Define unit test coverage targets (70-80% for core logic)
+   - Plan integration test scenarios (agent workflows, file operations, state transitions)
+   - Identify end-to-end test cases (full pipeline runs from /chati to handoff)
+   - Determine manual testing scope (IDE integration, i18n verification)
+
+3. **Categorize Test Types**
+   - **Unit Tests**: Pure functions, validators, parsers, formatters
+   - **Integration Tests**: Agent task execution, file I/O, YAML parsing/writing
+   - **Contract Tests**: MCP interfaces, CLI command structures
+   - **End-to-End Tests**: Complete user workflows (greenfield, brownfield)
+   - **Manual Tests**: IDE compatibility, internationalization, accessibility
+
+4. **Identify Risk Areas**
+   - State management corruption (session.yaml consistency)
+   - File system operations (permissions, race conditions)
+   - Agent handoff logic (transition validation)
+   - Mode governance enforcement (unauthorized transitions)
+   - Multi-language support (i18n edge cases)
+   - Upgrade/migration scenarios (data preservation)
+
+5. **Define Testing Tools and Frameworks**
+   - Unit/Integration: Specify framework (Jest, Vitest, Mocha)
+   - E2E: Define approach (custom scripts, snapshot testing)
+   - SAST: Select static analysis tools
+   - Performance: Identify benchmarking tools
+   - Coverage: Configure threshold enforcement
+
+6. **Plan Test Data Strategy**
+   - Create fixture templates for session states
+   - Define mock responses for MCP tools
+   - Establish test project configurations
+   - Document data cleanup procedures
+
+7. **Establish Test Environments**
+   - **Local Development**: Developer machines with IDE integration
+   - **CI/CD**: Automated pipeline execution environment
+   - **Isolation**: Sandboxed file system for destructive tests
+   - **Matrix**: Multi-IDE, multi-OS compatibility testing
+
+8. **Define Test Execution Order**
+   - Pre-commit: Unit tests + linting
+   - Pre-push: Integration tests
+   - CI: Full suite + SAST + performance
+   - Release: E2E + manual smoke tests
+
+9. **Plan for Non-Functional Testing**
+   - Performance: CLI startup time, agent response time
+   - Security: Input validation, path traversal prevention
+   - Reliability: Error recovery, graceful degradation
+   - Usability: Error message clarity, help text accuracy
+
+10. **Document Testing Standards**
+    - Code coverage minimums by component type
+    - Test naming conventions
+    - Assertion best practices
+    - Mock/stub usage guidelines
+
+11. **Create Test Strategy Document**
+    - Compile all findings into test-strategy.yaml
+    - Include rationale for each decision
+    - Map test types to risk levels
+    - Provide timeline for test implementation
+
+12. **Validate Completeness**
+    - Ensure all architecture components have test coverage
+    - Verify all risk areas are addressed
+    - Confirm testing pyramid is balanced
+    - Check alignment with quality gates (preview next task)
+
+## Decision Points
+
+- **Test Framework Selection**: If project dependencies already include a testing framework, align with existing tooling. Otherwise, recommend based on project type (TypeScript → Vitest/Jest).
+
+- **E2E Scope**: For complex multi-agent workflows, determine if full pipeline E2E tests should be snapshot-based or behavior-based.
+
+- **Manual Test Coverage**: Assess whether IDE compatibility requires manual testing or can be automated through headless IDE APIs.
+
+## Error Handling
+
+**Missing Architecture Document**
+- Request architecture completion before proceeding
+- Cannot define test strategy without system component map
+- Escalate to orchestrator for dependency resolution
+
+**Unclear Risk Profile**
+- Review brief/detail documents for business-critical features
+- Default to high-risk classification for state management, file operations
+- Document assumptions and flag for review
+
+**Tool Compatibility Issues**
+- If selected test frameworks conflict with project dependencies, provide alternatives
+- Document trade-offs in test-strategy.yaml
+- Suggest resolution path to orchestrator
+
+## Output Format
+
+```yaml
+# test-strategy.yaml
+version: 1.0.0
+created: YYYY-MM-DD
+agent: qa-planning
+
+testing_pyramid:
+  unit:
+    target_coverage: 75%
+    tools: [vitest]
+    scope:
+      - Pure functions in validators/
+      - Parsers and formatters
+      - State management utilities
+
+  integration:
+    target_coverage: 60%
+    tools: [vitest]
+    scope:
+      - Agent task execution
+      - File I/O operations
+      - YAML state persistence
+
+  e2e:
+    target_coverage: critical_paths
+    approach: snapshot-based
+    scope:
+      - Complete greenfield workflow
+      - Complete brownfield workflow
+      - Mode transition scenarios
+
+  manual:
+    scope:
+      - IDE compatibility (7 IDEs)
+      - i18n verification (4 languages)
+      - Accessibility audit
+
+risk_areas:
+  critical:
+    - State corruption in session.yaml
+    - Mode governance bypass
+    - File system race conditions
+  high:
+    - Agent handoff validation
+    - MCP integration failures
+    - Upgrade migration errors
+  medium:
+    - i18n edge cases
+    - CLI argument parsing
+    - Error message clarity
+
+tools:
+  unit_integration: vitest
+  sast: eslint-plugin-security
+  performance: hyperfine
+  coverage: c8
+
+environments:
+  local:
+    isolation: true
+    cleanup: automatic
+  ci:
+    matrix:
+      node: [18, 20, 22]
+      os: [ubuntu, macos, windows]
+
+execution_order:
+  pre_commit: [unit, lint]
+  pre_push: [integration]
+  ci: [unit, integration, sast, performance]
+  release: [e2e, manual_smoke]
+
+standards:
+  coverage_minimum:
+    global: 70%
+    core_logic: 80%
+    utilities: 60%
+  naming_convention: describe-it-BDD
+  mock_strategy: prefer-test-doubles
+
+next_steps:
+  - Define quality gates and thresholds
+  - Create detailed coverage plan per module
+  - Build risk matrix mapping
+```

package/framework/tasks/tasks-acceptance-write.md

@@ -0,0 +1,75 @@
+---
+id: tasks-acceptance-write
+agent: tasks
+trigger: tasks-estimate
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [task-criteria.yaml]
+handoff_to: tasks-consolidate
+autonomous_gate: true
+criteria:
+  - Each task has clear acceptance criteria
+  - Definition of done specified
+  - Test requirements defined
+---
+# Write Acceptance Criteria for Tasks
+
+## Purpose
+Define specific, testable acceptance criteria for each development task.
+
+## Steps
+
+### 1. For Each Task, Define
+- What must be implemented
+- How to verify completion
+- What tests are required
+- Definition of done
+
+### 2. Make Criteria Specific
+Not: "Registration works"
+But: "User can submit valid email and password, account is created in database, JWT returned, user redirected to dashboard"
+
+### 3. Include Test Requirements
+- Unit tests: What functions/methods need coverage
+- Integration tests: What API endpoints need testing
+- E2E tests: What user flows need automation
+
+### 4. Define Definition of Done
+Standard checklist for all tasks:
+- Code written and reviewed
+- Tests written and passing
+- Documentation updated
+- No linting errors
+- Deployed to dev environment
+
+## Output Format
+```yaml
+# task-criteria.yaml
+task_criteria:
+  - task_id: TASK-002
+    acceptance_criteria:
+      - POST /api/auth/register endpoint created
+      - Accepts email and password in request body
+      - Validates email format and password strength
+      - Returns 400 if validation fails with specific errors
+      - Returns 409 if email already exists
+      - Returns 201 with user object and JWT on success
+      - Password is hashed with bcrypt before storage
+    test_requirements:
+      unit_tests:
+        - Test email validation function
+        - Test password validation function
+        - Test password hashing
+      integration_tests:
+        - Test successful registration
+        - Test duplicate email rejection
+        - Test invalid input validation
+    definition_of_done:
+      - Code written
+      - Unit tests passing (>90% coverage)
+      - Integration tests passing
+      - Code reviewed and approved
+      - API documented in OpenAPI spec
+      - Merged to main branch
+```

package/framework/tasks/tasks-consolidate.md

@@ -0,0 +1,57 @@
+---
+id: tasks-consolidate
+agent: tasks
+trigger: tasks-acceptance-write
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [tasks-final.yaml]
+handoff_to: qa-planning
+autonomous_gate: true
+criteria:
+  - All task artifacts consolidated
+  - Work breakdown structure complete
+  - Ready for QA planning
+---
+# Consolidate Task List
+
+## Purpose
+Merge all task artifacts into final comprehensive task breakdown.
+
+## Steps
+
+### 1. Combine All Task Data
+Merge: tasks-list.yaml, estimates.yaml, task-criteria.yaml
+
+### 2. Create Work Breakdown Structure
+Organize tasks hierarchically:
+- Phase → Feature → Tasks
+
+### 3. Add Sprint Planning Hints
+Suggest which tasks could be grouped into sprints.
+
+### 4. Generate Final Task List
+Complete, ready for development.
+
+## Output Format
+```yaml
+# tasks-final.yaml
+timestamp: 2026-02-13T18:00:00Z
+total_tasks: 67
+total_estimated_hours: 480
+[All task details consolidated]
+sprint_suggestions:
+  sprint_1:
+    focus: Database schema and authentication backend
+    tasks: [TASK-001, TASK-002, TASK-005, TASK-006]
+    estimated_hours: 60
+  sprint_2:
+    focus: Authentication UI and post backend
+    tasks: [TASK-003, TASK-004, TASK-010, TASK-011]
+    estimated_hours: 72
+next_phase: qa_planning
+handoff_note: |
+  Complete task breakdown with 67 atomic tasks, estimated at 480 hours
+  including buffer. Tasks organized by module with clear acceptance criteria.
+  Ready for QA Planning agent to define test strategy.
+```

package/framework/tasks/tasks-decompose.md

@@ -0,0 +1,80 @@
+---
+id: tasks-decompose
+agent: tasks
+trigger: phases
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [tasks-list.yaml]
+handoff_to: tasks-estimate
+autonomous_gate: true
+criteria:
+  - All features decomposed into atomic tasks
+  - Each task is independently deliverable
+  - Task granularity appropriate (1-5 days each)
+---
+# Decompose Features into Atomic Tasks
+
+## Purpose
+Break down each feature into small, independently deliverable development tasks.
+
+## Prerequisites
+- `mvp-scope.yaml` with MVP features
+- `architecture-final.yaml` for technical structure
+
+## Steps
+
+### 1. For Each MVP Feature, Create Tasks
+Example: FR-001 (User registration) becomes:
+- Design database schema for users table
+- Implement registration API endpoint
+- Add password hashing with bcrypt
+- Create registration form UI
+- Add client-side validation
+- Add server-side validation
+- Write unit tests for registration logic
+- Write integration tests for API
+- Write E2E test for registration flow
+
+### 2. Ensure Tasks are Atomic
+Each task should:
+- Be completable in 1-5 days
+- Have clear definition of done
+- Be independently testable
+- Not require other incomplete tasks (except explicit dependencies)
+
+### 3. Organize by Module
+Group tasks by technical module (auth, posts, search, ui, etc.)
+
+### 4. Add Task Dependencies
+Task B depends on Task A if it cannot start until A is complete.
+
+## Output Format
+```yaml
+# tasks-list.yaml
+tasks:
+  - id: TASK-001
+    title: Design users table schema
+    module: database
+    description: Create database schema for users table with id, email, password_hash, timestamps
+    feature: FR-001
+    priority: P0
+    dependencies: []
+    estimated_days: 1
+  - id: TASK-002
+    title: Implement user registration API endpoint
+    module: auth
+    description: Create POST /api/auth/register endpoint with validation
+    feature: FR-001
+    priority: P0
+    dependencies: [TASK-001]
+    estimated_days: 2
+  - id: TASK-003
+    title: Create registration form UI
+    module: frontend
+    description: Build registration page with form, validation, error handling
+    feature: FR-001
+    priority: P0
+    dependencies: [TASK-002]
+    estimated_days: 3
+```

package/framework/tasks/tasks-estimate.md

@@ -0,0 +1,66 @@
+---
+id: tasks-estimate
+agent: tasks
+trigger: tasks-decompose
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [estimates.yaml]
+handoff_to: tasks-acceptance-write
+autonomous_gate: true
+criteria:
+  - All tasks estimated with T-shirt sizing or days
+  - Total effort calculated
+  - Estimates include buffer for unknowns
+---
+# Estimate Task Complexity
+
+## Purpose
+Estimate effort for each task using T-shirt sizes or day estimates.
+
+## Steps
+
+### 1. Review Each Task
+Assess complexity based on:
+- Technical difficulty
+- Unknowns and risks
+- Dependencies on external systems
+- Team familiarity with technology
+
+### 2. Assign T-Shirt Size
+- XS: <1 day, trivial
+- S: 1-2 days, straightforward
+- M: 3-5 days, moderate complexity
+- L: 6-10 days, complex (consider breaking down)
+- XL: >10 days (must break down)
+
+### 3. Convert to Day Estimates
+Provide specific day estimates for planning.
+
+### 4. Add Buffer
+20-30% buffer for unknowns, bugs, learning.
+
+### 5. Calculate Totals
+Sum by module, by phase, and overall.
+
+## Output Format
+```yaml
+# estimates.yaml
+task_estimates:
+  - task_id: TASK-001
+    size: S
+    estimated_days: 1
+    confidence: high
+  - task_id: TASK-002
+    size: M
+    estimated_days: 3
+    confidence: medium
+  - task_id: TASK-003
+    size: M
+    estimated_days: 3
+    confidence: high
+totals:
+  raw_estimate: 400 hours
+  with_20_percent_buffer: 480 hours
+  with_30_percent_buffer: 520 hours
+```

package/framework/tasks/ux-a11y-check.md

@@ -0,0 +1,49 @@
+---
+id: ux-a11y-check
+agent: ux
+trigger: ux-component-map
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [a11y-report.yaml]
+handoff_to: ux-consolidate
+autonomous_gate: true
+criteria:
+  - WCAG 2.1 AA requirements documented
+  - Accessibility patterns defined for key interactions
+  - Screen reader considerations documented
+---
+# Accessibility Audit and Requirements
+
+## Purpose
+Define accessibility requirements to meet WCAG 2.1 AA compliance.
+
+## Steps
+Document:
+- Semantic HTML requirements
+- ARIA labels for interactive elements
+- Keyboard navigation support
+- Color contrast requirements (4.5:1 for text)
+- Focus management
+- Screen reader announcements
+- Alt text for images
+- Form error announcements
+
+## Output Format
+```yaml
+# a11y-report.yaml
+wcag_compliance: AA
+requirements:
+  - All interactive elements keyboard accessible (Tab, Enter, Escape)
+  - Focus visible with clear outline
+  - Color contrast 4.5:1 minimum for text
+  - Alt text for all images
+  - ARIA labels for icon buttons
+  - Form errors announced to screen readers
+  - Skip links for main content
+  - Heading hierarchy maintained (h1, h2, h3)
+testing:
+  - Lighthouse accessibility audit >90
+  - Manual keyboard navigation test
+  - Screen reader test (NVDA/JAWS)
+```

package/framework/tasks/ux-component-map.md

@@ -0,0 +1,55 @@
+---
+id: ux-component-map
+agent: ux
+trigger: ux-user-flow
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [component-map.yaml]
+handoff_to: ux-a11y-check
+autonomous_gate: true
+criteria:
+  - Component hierarchy documented
+  - Reusable components identified
+  - Component props defined
+---
+# Map UI Component Hierarchy
+
+## Purpose
+Define reusable UI components and their hierarchy.
+
+## Steps
+Identify components:
+- Atoms: Button, Input, Label, Icon
+- Molecules: FormField (Label + Input + Error), PostCard
+- Organisms: Header, PostList, PostForm
+- Templates: AuthLayout, DashboardLayout
+- Pages: HomePage, LoginPage, CreatePostPage
+
+Document props and composition.
+
+## Output Format
+```yaml
+# component-map.yaml
+components:
+  atoms:
+    - name: Button
+      props: [variant, size, onClick, children, disabled]
+    - name: Input
+      props: [type, value, onChange, error, placeholder]
+  molecules:
+    - name: FormField
+      props: [label, type, value, onChange, error]
+      composition: [Label, Input, ErrorMessage]
+    - name: PostCard
+      props: [title, excerpt, author, date, tags]
+      composition: [Card, Heading, Text, TagList]
+  organisms:
+    - name: Header
+      props: [isAuthenticated, user]
+      composition: [Logo, Nav, SearchBar, UserMenu]
+  pages:
+    - name: HomePage
+      layout: MainLayout
+      components: [Header, PostList, Pagination, Footer]
+```

package/framework/tasks/ux-consolidate.md

@@ -0,0 +1,46 @@
+---
+id: ux-consolidate
+agent: ux
+trigger: ux-a11y-check
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [ux-final.yaml]
+handoff_to: phases
+autonomous_gate: true
+criteria:
+  - All UX artifacts consolidated
+  - Design system foundation defined
+  - UX package complete
+---
+# Consolidate UX Documentation
+
+## Purpose
+Merge all UX artifacts into comprehensive UX specification document.
+
+## Steps
+Combine wireframes, user flows, component map, and accessibility requirements.
+
+Add design system foundations:
+- Color palette
+- Typography scale
+- Spacing system
+- Component variants
+
+## Output Format
+```yaml
+# ux-final.yaml
+timestamp: 2026-02-13T17:00:00Z
+[All UX details consolidated]
+design_system:
+  colors:
+    primary: blue-600
+    secondary: gray-700
+    success: green-600
+    error: red-600
+  typography:
+    headings: font-bold
+    body: font-normal
+  spacing: [4px, 8px, 16px, 24px, 32px, 48px, 64px]
+next_phase: phases
+```

package/framework/tasks/ux-user-flow.md

@@ -0,0 +1,46 @@
+---
+id: ux-user-flow
+agent: ux
+trigger: ux-wireframe
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [user-flows.yaml]
+handoff_to: ux-component-map
+autonomous_gate: true
+criteria:
+  - Happy path flows documented for all key user journeys
+  - Error paths documented
+  - Flow diagrams created (text-based)
+---
+# Map User Flows
+
+## Purpose
+Document user journeys through the application including happy paths and error paths.
+
+## Steps
+Map key user flows:
+1. New user registration and first post
+2. Returning user login and post creation
+3. Search for content
+4. Edit existing post
+5. Error scenarios (failed login, validation errors)
+
+## Output Format
+```yaml
+# user-flows.yaml
+flows:
+  - name: New User First Post
+    steps:
+      - User visits / (home)
+      - Clicks "Register"
+      - Fills registration form
+      - Submits → redirected to /dashboard
+      - Clicks "Create Post"
+      - Fills post form
+      - Clicks "Publish" → redirected to /posts/:id
+      - Success! Post is live
+    error_paths:
+      - If email exists: Show error, remain on register page
+      - If validation fails: Show specific errors inline
+```