opencode-metis 0.1.0

package/opencode/skill/implementation-planning/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: implementation-planning
+description: "Provides methodology for creating actionable implementation plans with TDD phase structure, task granularity principles, specification compliance gates, and deviation protocols"
+license: MIT
+compatibility: opencode
+metadata:
+  category: analysis
+  version: "1.0"
+---
+
+# Implementation Planning
+
+Roleplay as an implementation plan specialist that creates actionable plans breaking features into executable tasks following TDD principles. Plans enable developers to work independently without requiring clarification.
+
+ImplementationPlanning {
+  Activation {
+    When to use this skill:
+    - Create a new PLAN from the template
+    - Complete phases in an existing implementation-plan.md
+    - Define task sequences and dependencies
+    - Plan TDD cycles (Prime to Test to Implement to Validate)
+    - Work on any `implementation-plan.md` file in docs/specs/
+  }
+
+  SuccessCriteria {
+    A plan is complete when:
+    - [ ] A developer can follow it independently without additional context
+    - [ ] Every task produces a verifiable deliverable (not just an activity)
+    - [ ] All PRD acceptance criteria map to specific tasks
+    - [ ] All SDD components have corresponding implementation tasks
+    - [ ] Dependencies are explicit and no circular dependencies exist
+  }
+
+  Template {
+    Constraints {
+      1. The PLAN template is at [template.md](template.md) -- use this structure exactly
+      2. Read the template from this skill's directory
+      3. Write to spec directory: `docs/specs/[NNN]-[name]/implementation-plan.md`
+    }
+  }
+
+  PlanFocusAreas {
+    Questions {
+      Your plan MUST answer these questions:
+      - **WHAT** produces value? (deliverables, not activities)
+      - **IN WHAT ORDER** do tasks execute? (dependencies and sequencing)
+      - **HOW TO VALIDATE** correctness? (test-first approach)
+      - **WHERE** is each task specified? (links to PRD/SDD sections)
+    }
+
+    Constraints {
+      Keep plans actionable and focused:
+      1. Use task descriptions, sequence, and validation criteria
+      2. Omit time estimates -- focus on what, not when
+      3. Omit resource assignments -- focus on work, not who
+      4. Omit implementation code -- the plan guides, implementation follows
+    }
+  }
+
+  TaskGranularityPrinciple {
+    Definition: Track logical units that produce verifiable outcomes. The TDD cycle is the execution method, not separate tracked items.
+
+    GoodTrackingUnits {
+      Produces outcome:
+      - "Payment Entity" produces working entity with tests
+      - "Stripe Adapter" produces working integration with tests
+      - "Payment Form Component" produces working UI with tests
+    }
+
+    BadTrackingUnits {
+      Too granular:
+      - "Read payment interface contracts" -- Preparation, not deliverable
+      - "Test Payment.validate() rejects negative amounts" -- Part of larger outcome
+      - "Run linting" -- Validation step, not deliverable
+    }
+
+    StructurePattern {
+      ```markdown
+      - [ ] **T1.1 Payment Entity** `[activity: domain-modeling]`
+
+        **Prime**: Read payment interface contracts `[ref: SDD/Section 4.2; lines: 145-200]`
+
+        **Test**: Entity validation rejects negative amounts; supports currency conversion; handles refunds
+
+        **Implement**: Create `src/domain/Payment.ts` with validation logic
+
+        **Validate**: Run unit tests, lint, typecheck
+      ```
+
+      The checkbox tracks "Payment Entity" as a unit. Prime/Test/Implement/Validate are embedded guidance.
+    }
+  }
+
+  TDDPhaseStructure {
+    Definition: Every task follows red-green-refactor within this pattern
+
+    Phase1_PrimeContext {
+      - Read relevant specification sections
+      - Understand interfaces and contracts
+      - Load patterns and examples
+    }
+
+    Phase2_WriteTests_Red {
+      - Test behavior before implementation
+      - Reference PRD acceptance criteria
+      - Cover happy path and edge cases
+    }
+
+    Phase3_Implement_Green {
+      - Build to pass tests
+      - Follow SDD architecture
+      - Use discovered patterns
+    }
+
+    Phase4_Validate_Refactor {
+      - Run automated tests
+      - Check code quality (lint, format)
+      - Verify specification compliance
+    }
+  }
+
+  TaskMetadata {
+    Annotations {
+      ```markdown
+      - [ ] T1.2.1 [Task description] `[ref: SDD/Section 5; lines: 100-150]` `[activity: backend-api]`
+      ```
+    }
+
+    MetadataTable {
+      | Metadata | Description |
+      |----------|-------------|
+      | `[parallel: true]` | Tasks that can run concurrently |
+      | `[component: name]` | For multi-component features |
+      | `[ref: doc/section; lines: X-Y]` | Links to specifications |
+      | `[activity: type]` | Hint for specialist selection |
+    }
+  }
+
+  CyclePattern {
+    DiscoveryPhase {
+      - Read PRD and SDD to understand requirements and design
+      - Identify activities needed for each implementation area
+      - Launch parallel specialist agents to investigate:
+        - Task sequencing and dependencies
+        - Testing strategies
+        - Risk assessment
+        - Validation approaches
+    }
+
+    DocumentationPhase {
+      - Update the PLAN with task definitions
+      - Add specification references (`[ref: ...]`)
+      - Focus only on current phase being defined
+      - Follow template structure exactly
+    }
+
+    ReviewPhase {
+      - Present task breakdown to user
+      - Show dependencies and sequencing
+      - Highlight parallel opportunities
+      - Wait for user confirmation before next phase
+    }
+
+    SelfCheck {
+      Ask yourself each cycle:
+      1. Have I read the relevant PRD and SDD sections?
+      2. Do all tasks trace back to specification requirements?
+      3. Are dependencies between tasks clear?
+      4. Can parallel tasks actually run in parallel?
+      5. Are validation steps included in each phase?
+      6. Have I received user confirmation?
+    }
+  }
+
+  SpecificationCompliance {
+    PhaseValidationTask {
+      Every phase should include a validation task:
+      ```markdown
+      - [ ] **T1.3 Phase Validation** `[activity: validate]`
+
+        Run all phase tests, linting, type checking. Verify against SDD patterns and PRD acceptance criteria.
+      ```
+
+      For complex phases, validation is embedded in each task's **Validate** step.
+    }
+
+    DeviationProtocol {
+      When implementation requires changes from the specification:
+      1. Document the deviation with clear rationale
+      2. Obtain approval before proceeding
+      3. Update SDD when the deviation improves the design
+      4. Record all deviations in the plan for traceability
+    }
+  }
+
+  ValidationChecklist {
+    See [validation.md](validation.md) for the complete checklist. Key gates:
+    - [ ] All specification file paths are correct and exist
+    - [ ] Context priming section is complete
+    - [ ] All implementation phases are defined
+    - [ ] Each phase follows TDD: Prime to Test to Implement to Validate
+    - [ ] Dependencies between phases are clear (no circular dependencies)
+    - [ ] Parallel work is properly tagged with `[parallel: true]`
+    - [ ] Activity hints provided for specialist selection `[activity: type]`
+    - [ ] Every phase references relevant SDD sections
+    - [ ] Every test references PRD acceptance criteria
+    - [ ] Integration and E2E tests defined in final phase
+    - [ ] Project commands match actual project setup
+    - [ ] A developer could follow this plan independently
+  }
+
+  Examples {
+    See [examples/phase-examples.md](examples/phase-examples.md) for reference.
+  }
+}

package/opencode/skill/implementation-planning/examples/phase-examples.md

@@ -0,0 +1,217 @@
+# Implementation Phase Examples
+
+Reference examples for structuring implementation phases with grouped task tracking.
+
+## Core Principle
+
+**Track logical units that produce verifiable outcomes.** Each checkbox represents a deliverable, not a step in the process. The TDD cycle (Prime → Test → Implement → Validate) is embedded guidance within each task.
+
+---
+
+## Example: Foundation Phase
+
+```markdown
+### Phase 1: Payment Domain Foundation
+
+Establishes core domain entities, repository patterns, and database schema.
+
+- [ ] **T1.1 Payment Entity** `[activity: domain-modeling]`
+
+  **Prime**: Read payment interface contracts and validation rules `[ref: SDD/Section 4.2; lines: 145-200]`
+
+  **Test**: Entity validation rejects negative amounts; supports multiple currencies; calculates fees correctly; handles partial refunds
+
+  **Implement**: Create `src/domain/Payment.ts` with Amount value object and validation logic
+
+  **Validate**: Run unit tests, lint, typecheck
+
+- [ ] **T1.2 Payment Repository** `[activity: data-architecture]`
+
+  **Prime**: Review existing repository patterns and database schema `[ref: docs/patterns/repository-pattern.md]` `[ref: SDD/Section 4.3]`
+
+  **Test**: CRUD operations work correctly; queries filter by status and date range; handles concurrent updates
+
+  **Implement**: Create `src/repositories/PaymentRepository.ts` with PostgreSQL adapter; create migration for payments table
+
+  **Validate**: Run integration tests against test database
+
+- [ ] **T1.3 Phase Validation** `[activity: validate]`
+
+  Run all unit and integration tests. Verify entity matches SDD data model. Lint and typecheck pass.
+```
+
+**Task count**: 3 tracked items (vs ~12 with granular tracking)
+
+---
+
+## Example: Parallel Tasks
+
+```markdown
+### Phase 2: API and Integration Layer
+
+API endpoints and external service integration. These can be developed in parallel.
+
+- [ ] **T2.1 Payment API Endpoints** `[parallel: true]` `[component: backend]`
+
+  **Prime**: Read API specification and authentication requirements `[ref: SDD/Section 4.4]`
+
+  **Test**: POST /payments creates payment and returns 201; GET /payments/:id returns payment or 404; validation errors return 422 with details
+
+  **Implement**: Create `src/controllers/PaymentController.ts` with create, get, list routes
+
+  **Validate**: API contract tests pass; authentication enforced
+
+- [ ] **T2.2 Stripe Integration** `[parallel: true]` `[component: backend]`
+
+  **Prime**: Read Stripe integration pattern and webhook handling `[ref: docs/interfaces/stripe-payment-integration.md]`
+
+  **Test**: Charges created with correct amount; webhook validates signature; handles declined cards gracefully
+
+  **Implement**: Create `src/adapters/StripePaymentAdapter.ts` with charge and refund methods
+
+  **Validate**: Integration tests pass with Stripe test mode
+
+- [ ] **T2.3 Phase Validation** `[activity: validate]`
+
+  Run all API and integration tests. Verify endpoints match OpenAPI spec. Lint and typecheck pass.
+```
+
+**Task count**: 3 tracked items (vs ~10 with granular tracking)
+
+---
+
+## Example: Multi-Component Feature
+
+```markdown
+### Phase 3: Frontend Integration
+
+UI components and state management for the payment flow.
+
+- [ ] **T3.1 Payment Form Component** `[component: frontend]`
+
+  **Prime**: Read UI specifications and form validation rules `[ref: SDD/Section 5.1]`
+
+  **Test**: Form renders with all fields; validates card number format; submits on valid input; shows error states
+
+  **Implement**: Create `src/components/PaymentForm.tsx` with Stripe Elements integration
+
+  **Validate**: Component tests pass; accessibility audit passes
+
+- [ ] **T3.2 Payment State Management** `[component: frontend]`
+
+  **Prime**: Read state management pattern and async handling `[ref: docs/patterns/state-management.md]`
+
+  **Test**: Loading states during API calls; success state updates UI; error state shows message; retry logic works
+
+  **Implement**: Create `src/store/paymentSlice.ts` with async thunks for API calls
+
+  **Validate**: State transitions match flow diagram; reducer tests pass
+
+- [ ] **T3.3 Payment Flow Integration** `[depends: T3.1, T3.2]`
+
+  **Prime**: Review complete user journey from cart to confirmation
+
+  **Test**: E2E flow from form submission to confirmation page; handles payment failures; shows receipt
+
+  **Implement**: Wire PaymentForm to payment state; connect to backend API; add confirmation page
+
+  **Validate**: E2E test passes; manual QA of happy path and error cases
+```
+
+**Task count**: 3 tracked items (vs ~12 with granular tracking)
+
+---
+
+## Example: Final Validation Phase
+
+```markdown
+### Phase 4: Integration & Validation
+
+Full system validation with all components working together.
+
+- [ ] **T4.1 Integration Testing** `[activity: integration-test]`
+
+  Verify cross-component integration: API ↔ Database, Frontend ↔ API, Payment ↔ Stripe
+
+- [ ] **T4.2 E2E User Flows** `[activity: e2e-test]`
+
+  Verify complete user journeys: happy path payment `[ref: PRD/Section 3.1]`; payment failure handling `[ref: PRD/Section 3.2]`; payment history display `[ref: PRD/Section 3.3]`
+
+- [ ] **T4.3 Quality Gates** `[activity: validate]`
+
+  Performance: API response < 200ms p95 `[ref: SDD/Section 10]`; Security: input validation verified; Coverage: > 80% line coverage
+
+- [ ] **T4.4 Specification Compliance** `[activity: business-acceptance]`
+
+  All PRD acceptance criteria verified `[ref: PRD/Section 4]`; implementation follows SDD design; documentation updated for API changes
+```
+
+**Task count**: 4 tracked items (vs ~15 with granular tracking)
+
+---
+
+## Activity Type Reference
+
+Common activity types for specialist selection:
+
+| Activity | Description |
+|----------|-------------|
+| `domain-modeling` | Business entity and rule design |
+| `data-architecture` | Database schema, migrations, queries |
+| `api-development` | REST/GraphQL endpoint implementation |
+| `component-development` | UI component implementation |
+| `backend-implementation` | General backend code |
+| `frontend-implementation` | General frontend code |
+| `integration-test` | Cross-component integration testing |
+| `e2e-test` | End-to-end user flow testing |
+| `validate` | Quality gates and compliance checks |
+| `business-acceptance` | PRD criteria verification |
+
+---
+
+## What Makes Good Implementation Plans
+
+1. **Logical Unit Tracking** - Each checkbox produces a verifiable outcome
+2. **Embedded TDD Guidance** - Prime/Test/Implement/Validate as text, not checkboxes
+3. **Specification Links** - Every task traces to PRD/SDD
+4. **Parallel Opportunities** - Independent work clearly marked
+5. **No Time Estimates** - Focus on sequence, not duration
+6. **Activity Hints** - Guide specialist selection
+7. **Phase Validation** - Quality gates at phase boundaries
+
+## Comparison: Before and After
+
+**Before (granular - 9 tracked items):**
+```markdown
+- [ ] T1.1 Prime Context
+    - [ ] T1.1.1 Read payment interface contracts
+    - [ ] T1.1.2 Review repository patterns
+- [ ] T1.2 Write Tests
+    - [ ] T1.2.1 Unit tests for Payment entity
+    - [ ] T1.2.2 Unit tests for PaymentRepository
+- [ ] T1.3 Implement
+    - [ ] T1.3.1 Create Payment entity
+    - [ ] T1.3.2 Create PaymentRepository
+- [ ] T1.4 Validate
+    - [ ] T1.4.1 Run tests
+```
+
+**After (grouped - 3 tracked items):**
+```markdown
+- [ ] **T1.1 Payment Entity** `[activity: domain-modeling]`
+  **Prime**: Read payment contracts `[ref: SDD/Section 4.2]`
+  **Test**: Validation rules, currency support, fee calculation
+  **Implement**: Create `src/domain/Payment.ts`
+  **Validate**: Unit tests, lint, typecheck
+
+- [ ] **T1.2 Payment Repository** `[activity: data-architecture]`
+  **Prime**: Review repository patterns `[ref: docs/patterns/repository-pattern.md]`
+  **Test**: CRUD operations, query filters, concurrency
+  **Implement**: Create repository and migration
+  **Validate**: Integration tests
+
+- [ ] **T1.3 Phase Validation** `[activity: validate]`
+  Run all tests, verify against SDD, lint and typecheck pass
+```
+
+Same detail, 67% fewer todowrite operations.

package/opencode/skill/implementation-planning/template.md

@@ -0,0 +1,220 @@
+---
+title: "[NEEDS CLARIFICATION: Feature title]"
+status: draft
+version: "1.0"
+---
+
+# Implementation Plan
+
+## Validation Checklist
+
+### CRITICAL GATES (Must Pass)
+
+- [ ] All `[NEEDS CLARIFICATION: ...]` markers have been addressed
+- [ ] All specification file paths are correct and exist
+- [ ] Each phase follows TDD: Prime → Test → Implement → Validate
+- [ ] Every task has verifiable success criteria
+- [ ] A developer could follow this plan independently
+
+### QUALITY CHECKS (Should Pass)
+
+- [ ] Context priming section is complete
+- [ ] All implementation phases are defined
+- [ ] Dependencies between phases are clear (no circular dependencies)
+- [ ] Parallel work is properly tagged with `[parallel: true]`
+- [ ] Activity hints provided for specialist selection `[activity: type]`
+- [ ] Every phase references relevant SDD sections
+- [ ] Every test references PRD acceptance criteria
+- [ ] Integration & E2E tests defined in final phase
+- [ ] Project commands match actual project setup
+
+---
+
+## Specification Compliance Guidelines
+
+### How to Ensure Specification Adherence
+
+1. **Before Each Phase**: Complete the Pre-Implementation Specification Gate
+2. **During Implementation**: Reference specific SDD sections in each task
+3. **After Each Task**: Run Specification Compliance checks
+4. **Phase Completion**: Verify all specification requirements are met
+
+### Deviation Protocol
+
+When implementation requires changes from the specification:
+1. Document the deviation with clear rationale
+2. Obtain approval before proceeding
+3. Update SDD when the deviation improves the design
+4. Record all deviations in this plan for traceability
+
+## Metadata Reference
+
+- `[parallel: true]` - Tasks that can run concurrently
+- `[component: component-name]` - For multi-component features
+- `[ref: document/section; lines: 1, 2-3]` - Links to specifications, patterns, or interfaces and (if applicable) line(s)
+- `[activity: type]` - Activity hint for specialist agent selection
+
+### Success Criteria
+
+**Validate** = Process verification ("did we follow TDD?")
+**Success** = Outcome verification ("does it work correctly?")
+
+```markdown
+# Single-line format
+- Success: [Criterion] `[ref: PRD/AC-X.Y]`
+
+# Multi-line format
+- Success:
+  - [ ] [Criterion 1] `[ref: PRD/AC-X.Y]`
+  - [ ] [Criterion 2] `[ref: SDD/Section]`
+```
+
+---
+
+## Context Priming
+
+*GATE: Read all files in this section before starting any implementation.*
+
+**Specification**:
+
+[NEEDS CLARIFICATION: Replace with actual paths from your spec directory]
+- `docs/specs/[NNN]-[name]/product-requirements.md` - Product Requirements
+- `docs/specs/[NNN]-[name]/solution-design.md` - Solution Design
+- `docs/{patterns,interfaces,research}/[name].md`  - Optional references
+
+**Key Design Decisions**:
+
+[NEEDS CLARIFICATION: Extract 2-5 critical decisions from the SDD that affect implementation]
+- **ADR-1**: [Decision name] - [One-line summary of what was decided and why]
+- **ADR-2**: [Decision name] - [One-line summary]
+
+**Implementation Context**:
+
+[NEEDS CLARIFICATION: Update implementation-relevant commands to match project setup]
+```bash
+# Testing
+npm test                    # Unit tests
+npm run test:integration    # Integration tests
+
+# Quality
+npm run lint               # Linting
+npm run typecheck          # Type checking
+
+# Full validation
+npm run validate           # All checks
+```
+
+---
+
+## Implementation Phases
+
+Each task follows red-green-refactor: **Prime** (understand context), **Test** (red), **Implement** (green), **Validate** (refactor + verify).
+
+> **Tracking Principle**: Track logical units that produce verifiable outcomes. The TDD cycle is the method, not separate tracked items.
+
+---
+
+### Phase 1: Core Foundation
+
+[NEEDS CLARIFICATION: Describe what this phase delivers - "Establishes X capability" or "Enables Y functionality"]
+
+Establishes the foundational [domain/infrastructure/components] required for subsequent phases.
+
+- [ ] **T1.1 [Primary deliverable name]** `[activity: domain-modeling]`
+
+  1. Prime: Read [entity/component] specification `[ref: SDD/Section X; lines: Y-Z]`
+  2. Test: [Behavior 1]; [Behavior 2]; [Edge case handling]
+  3. Implement: Create `src/[path]/[File].ts` with [key capability]
+  4. Validate: Unit tests pass; lint clean; types check
+  5. Success: [Criterion 1] `[ref: PRD/AC-1.1]`; [Criterion 2] `[ref: SDD/Section]`
+
+- [ ] **T1.2 [Secondary deliverable name]** `[activity: data-architecture]`
+
+  1. Prime: Review [pattern/interface] requirements `[ref: SDD/Section X]`
+  2. Test: [CRUD operations]; [Query patterns]; [Error handling]
+  3. Implement: Create `src/[path]/[File].ts` with [key capability]
+  4. Validate: Integration tests pass; lint clean; types check
+  5. Success: [Criterion 1] `[ref: PRD/AC-1.2]`; [Criterion 2] `[ref: SDD/Section]`
+
+- [ ] **T1.3 Phase Validation** `[activity: validate]`
+
+  - Run all Phase 1 tests. Verify foundation matches SDD data models. Lint and typecheck pass.
+
+---
+
+### Phase 2: [API/Integration/UI] Layer
+
+[NEEDS CLARIFICATION: Describe what this phase delivers. Mark parallel tasks for concurrent execution.]
+
+Builds the [API endpoints/integrations/UI components] that expose Phase 1 capabilities.
+
+- [ ] **T2.1 [Component A]** `[parallel: true]` `[component: backend]`
+
+  1. Prime: Read API specification `[ref: SDD/Section X]`
+  2. Test: [Endpoint behavior]; [Validation]; [Error responses]
+  3. Implement: Create `src/[path]/[Controller].ts` with routes
+  4. Validate: API tests pass; contract matches specification
+  5. Success: [Criterion] `[ref: PRD/AC-2.1]`
+
+- [ ] **T2.2 [Component B]** `[parallel: true]` `[component: backend]`
+
+  1. Prime: Read integration pattern `[ref: docs/interfaces/X.md]`
+  2. Test: [Success flow]; [Failure handling]; [Retry logic]
+  3. Implement: Create `src/[path]/[Adapter].ts` with integration
+  4. Validate: Integration tests pass with test/mock service
+  5. Success:
+      - [Success criterion 1] `[ref: PRD/AC-2.2]`
+      - [Failure handling verified] `[ref: SDD/Error Handling]`
+      - [Retry logic works with backoff] `[ref: docs/patterns/resilience.md]`
+
+- [ ] **T2.3 Phase Validation** `[activity: validate]`
+
+  Run all Phase 2 tests. Verify API contracts match SDD. Lint and typecheck pass.
+
+---
+
+### Phase 3: Final Integration & Validation
+
+Full system validation ensuring all components work together correctly.
+
+- [ ] **T3.1 Integration Testing** `[activity: integration-test]`
+
+  Verify cross-component integration: [Component A] ↔ [Component B]; [Service] ↔ [Database]
+
+  `[ref: SDD/integration points]`
+
+- [ ] **T3.2 E2E User Flows** `[activity: e2e-test]`
+
+  Verify complete user journeys: [Happy path flow]; [Error handling flow]; [Edge case flow]
+
+  `[ref: PRD/acceptance criteria]`
+
+- [ ] **T3.3 Quality Gates** `[activity: validate]`
+
+  - Performance: [Specific metric] < [threshold] `[ref: SDD/Quality Requirements]`
+  - Security: [Specific check] verified
+  - Coverage: > [X]% line coverage
+
+- [ ] **T3.4 Specification Compliance** `[activity: business-acceptance]`
+
+  - All PRD acceptance criteria verified
+  - Implementation follows SDD design
+  - Documentation updated for API/interface changes
+  - Build and deployment verification complete
+
+---
+
+## Plan Verification
+
+Before this plan is ready for implementation, verify:
+
+| Criterion | Status |
+|-----------|--------|
+| A developer can follow this plan without additional clarification | ⬜ |
+| Every task produces a verifiable deliverable | ⬜ |
+| All PRD acceptance criteria map to specific tasks | ⬜ |
+| All SDD components have implementation tasks | ⬜ |
+| Dependencies are explicit with no circular references | ⬜ |
+| Parallel opportunities are marked with `[parallel: true]` | ⬜ |
+| Each task has specification references `[ref: ...]` | ⬜ |
+| Project commands in Context Priming are accurate | ⬜ |