opencode-metis 0.1.0

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

@@ -0,0 +1,88 @@
+# PLAN Validation Checklist
+
+Use this checklist to validate Implementation Plan completeness before execution.
+
+## Structure Validation
+
+- [ ] **All required sections are complete** - No empty or placeholder sections
+- [ ] **No [NEEDS CLARIFICATION] markers remain** - All markers replaced with content
+- [ ] **Template structure preserved** - No sections added, removed, or reorganized
+
+## Context Priming
+
+- [ ] **Specification paths correct** - PRD and SDD file paths exist and are valid
+- [ ] **Key decisions extracted** - Critical choices from SDD are highlighted
+- [ ] **Project commands documented** - Actual commands from project setup
+- [ ] **Pattern links provided** - References to relevant pattern documentation
+
+## Phase Structure
+
+- [ ] **All implementation phases defined** - Complete coverage of the feature
+- [ ] **Each phase follows TDD structure**:
+  - Prime Context (read specs, load patterns)
+  - Write Tests (behavior verification first)
+  - Implement (code to pass tests)
+  - Validate (quality gates)
+- [ ] **Phase boundaries are logical** - Clear separation of concerns
+
+## Task Quality
+
+- [ ] **Tasks are actionable** - Clear what needs to be done
+- [ ] **Tasks are atomic** - Can be completed independently (where not dependent)
+- [ ] **No time estimates included** - Focus on WHAT, not HOW LONG
+- [ ] **Activity hints provided** - `[activity: type]` for specialist selection
+
+## Dependencies
+
+- [ ] **Dependencies between phases clear** - What must complete before what
+- [ ] **No circular dependencies** - Phases can be ordered linearly
+- [ ] **Parallel work tagged** - `[parallel: true]` where applicable
+- [ ] **Component tags for multi-component** - `[component: name]` where needed
+
+## Specification Traceability
+
+- [ ] **Every phase references SDD** - `[ref: SDD/Section X]`
+- [ ] **Every test references PRD criteria** - `[ref: PRD/Section Y]`
+- [ ] **All PRD requirements covered** - Nothing from PRD is missing
+- [ ] **All SDD components covered** - Nothing from architecture is skipped
+
+## Validation Steps
+
+- [ ] **Each phase has validation step** - T\*.4 Validate present in each phase
+- [ ] **Code review included** - Quality gate for code standards
+- [ ] **Automated tests included** - Test execution gate
+- [ ] **Specification compliance included** - Business acceptance gate
+
+## Final Phase
+
+- [ ] **Integration tests defined** - Cross-component testing
+- [ ] **E2E tests defined** - Complete user flow testing
+- [ ] **Performance validation included** - If performance requirements exist
+- [ ] **Security validation included** - If security requirements exist
+- [ ] **All PRD requirements verified** - Final acceptance criteria check
+
+## Practical Validation
+
+- [ ] **Project commands match setup** - Commands work in the actual project
+- [ ] **File paths are realistic** - Directories and files match codebase
+- [ ] **A developer could follow independently** - No assumed knowledge
+
+## No-Go Items
+
+These should NOT appear in a PLAN:
+
+- [ ] **No time estimates** - Hours, days, sprints
+- [ ] **No resource assignments** - Who does what
+- [ ] **No implementation code** - Actual code snippets (examples in SDD)
+- [ ] **No scope expansion** - Tasks beyond PRD/SDD scope
+
+## Completion Criteria
+
+✅ **PLAN is complete when:**
+
+- All checklist items pass
+- User has reviewed and approved the task breakdown
+- Every PRD requirement maps to at least one task
+- Every SDD component is covered by phases
+- A developer can start implementation immediately
+- Ready for `/implement` execution

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

@@ -0,0 +1,272 @@
+---
+name: implementation-verification
+description: "Verify that implementation matches specifications exactly, checking interface contracts, architecture decisions, data models, and business logic compliance"
+license: MIT
+compatibility: opencode
+metadata:
+  category: analysis
+  version: "1.0"
+---
+
+# Implementation Verification
+
+Roleplay as a specification compliance validator that ensures implementations match documented requirements exactly.
+
+ImplementationVerification {
+  Activation {
+    When to use this skill:
+    - Verify SDD compliance during implementation
+    - Check interface contracts match specifications
+    - Validate architecture decisions are followed
+    - Detect deviations from documented requirements
+    - Report compliance status at checkpoints
+  }
+
+  CorePrinciple {
+    Constraints {
+      1. Every implementation must match the specification exactly
+      2. Deviations require explicit acknowledgment before proceeding
+      3. Include file:line for every finding -- no generic observations
+    }
+  }
+
+  SpecificationDocumentHierarchy {
+    ```
+    docs/specs/[NNN]-[name]/
+      product-requirements.md   # WHAT and WHY (business requirements)
+      solution-design.md        # HOW (technical design, interfaces, patterns)
+      implementation-plan.md    # WHEN (execution sequence, phases)
+    ```
+  }
+
+  ComplianceVerificationProcess {
+    PreImplementationCheck {
+      Before implementing any task:
+      1. Extract SDD references from PLAN.md task: `[ref: SDD/Section X.Y]`
+      2. Read referenced sections from solution-design.md
+      3. Identify requirements:
+         - Interface contracts
+         - Data structures
+         - Business logic flows
+         - Architecture decisions
+         - Quality requirements
+    }
+
+    DuringImplementation {
+      For each task, verify:
+      - [ ] Interface contracts match -- Function signatures, parameters, return types
+      - [ ] Data structures align -- Schema, types, relationships as specified
+      - [ ] Business logic follows -- Defined flows and rules from SDD
+      - [ ] Architecture respected -- Patterns, layers, dependencies as designed
+      - [ ] Quality met -- Performance, security requirements from SDD
+    }
+
+    PostImplementationValidation {
+      After task completion:
+      1. Compare implementation to specification
+      2. Document any deviations found
+      3. Classify deviations by severity
+      4. Report compliance status
+    }
+  }
+
+  DeviationClassification {
+    CriticalDeviations {
+      Definition: Must fix before proceeding
+      - Interface contract violations
+      - Missing required functionality
+      - Security requirement breaches
+      - Breaking architectural constraints
+    }
+
+    NotableDeviations {
+      Definition: Require acknowledgment
+      - Implementation differs but functionally equivalent
+      - Enhancement beyond specification
+      - Simplified approach with same outcome
+    }
+
+    AcceptableVariations {
+      Definition: Can proceed
+      - Internal implementation details differ
+      - Optimizations within spec boundaries
+      - Naming/style variations
+    }
+  }
+
+  InterfaceVerification {
+    APIEndpoints {
+      ```
+      Verifying: POST /api/users
+      SDD Spec: Section 4.2.1
+
+      Request Schema:
+        PASS body.email: string (required)
+        PASS body.password: string (min 8 chars)
+        FAIL body.role: missing (spec requires optional role param)
+
+      Response Schema:
+        PASS 201: { id, email, createdAt }
+        PASS 400: { error: string }
+        NOTE 409: Added conflict handling (not in spec, beneficial)
+      ```
+    }
+
+    DataModels {
+      ```
+      Verifying: User Model
+      SDD Spec: Section 3.1.2
+
+      Fields:
+        PASS id: UUID (primary key)
+        PASS email: string (unique)
+        PASS passwordHash: string
+        NOTE lastLoginAt: timestamp (added, not in spec)
+        FAIL role: enum (missing from implementation)
+
+      Relationships:
+        PASS hasMany: sessions
+        PASS belongsTo: organization
+      ```
+    }
+  }
+
+  ArchitectureDecisionVerification {
+    Format {
+      For each ADR in SDD:
+      ```
+      ADR-1: [Decision Title]
+      Implementation Status:
+
+      Decision: [What was decided]
+      Evidence: [Where implemented]
+      Compliance: [Matched / Deviated]
+
+      If deviated:
+        Deviation: [What differs]
+        Impact: [Consequences]
+        Action: [Fix / Accept with rationale]
+      ```
+    }
+  }
+
+  TraceabilityMatrix {
+    Build a requirements-to-implementation map:
+    ```
+    +-------------------+-----------------------+--------+
+    | Requirement       | Implementation        | Status |
+    +-------------------+-----------------------+--------+
+    | PRD-1: User auth  | src/auth/login.ts     | PASS   |
+    | PRD-2: Validation | src/validators/*.ts   | PASS   |
+    | SDD-3: Repo layer | src/repositories/*.ts | PASS   |
+    | SDD-4: Rate limit | NOT FOUND             | FAIL   |
+    +-------------------+-----------------------+--------+
+    ```
+  }
+
+  ValidationCommands {
+    Run these at checkpoints:
+    ```bash
+    # Type checking (if TypeScript)
+    npm run typecheck
+
+    # Linting
+    npm run lint
+
+    # Test suite
+    npm test
+
+    # Build verification
+    npm run build
+    ```
+  }
+
+  ComplianceGates {
+    BeforeProceedingToNextPhase {
+      All must be true:
+      - [ ] All critical deviations resolved
+      - [ ] Notable deviations acknowledged by user
+      - [ ] Validation commands pass
+      - [ ] SDD coverage for phase is complete
+    }
+
+    BeforeFinalCompletion {
+      - [ ] All phases compliant
+      - [ ] All interfaces verified
+      - [ ] All architecture decisions respected
+      - [ ] Quality requirements met
+      - [ ] User confirmed any variations
+    }
+  }
+
+  ReportFormats {
+    PerTaskReport {
+      ```
+      Specification Compliance: [Task Name]
+
+      SDD Reference: Section [X.Y]
+
+      Requirements Checked:
+      PASS Interface: [function/endpoint] matches signature
+      PASS Data: [model/schema] matches structure
+      PASS Logic: [flow/rule] implemented correctly
+      NOTE Enhancement: [description] - beyond spec but compatible
+      FAIL Deviation: [description] - requires fix
+
+      Status: [COMPLIANT / DEVIATION FOUND / NEEDS REVIEW]
+      ```
+    }
+
+    PhaseCompletionReport {
+      ```
+      Phase [X] Specification Compliance Summary
+
+      Tasks Validated: [N]
+      - Fully Compliant: [X]
+      - With Acceptable Variations: [Y]
+      - With Notable Deviations: [Z]
+      - Critical Issues: [W]
+
+      SDD Sections Covered:
+      - Section 2.1: Compliant
+      - Section 2.2: Compliant
+      - Section 3.1: Variation documented
+
+      Critical Issues (if any):
+      1. [Description and required fix]
+
+      Recommendation: [PROCEED / FIX REQUIRED / USER REVIEW]
+      ```
+    }
+  }
+
+  IntegrationWithOtherSkills {
+    Works alongside:
+    - `skill({ name: "specification-validation" })` -- Comprehensive spec quality checks
+    - `skill({ name: "drift-detection" })` -- Spec-implementation alignment monitoring
+    - `skill({ name: "constitution-validation" })` -- Governance compliance
+    - `skill({ name: "specification-management" })` -- Read spec metadata and locate documents
+  }
+
+  QuickReference {
+    AlwaysCheck {
+      - Interface signatures match exactly
+      - Required fields are present
+      - Business logic follows specified flows
+      - Architecture patterns are respected
+    }
+
+    DocumentDeviations {
+      - What differs from spec
+      - Why it differs (if known)
+      - Impact assessment
+      - Recommended action
+    }
+
+    GateCompliance {
+      - Critical = must fix
+      - Notable = must acknowledge
+      - Acceptable = can proceed
+    }
+  }
+}

package/opencode/skill/knowledge-capture/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: knowledge-capture
+description: "Capture and organize business rules, technical patterns, and service interfaces discovered during analysis or implementation into structured documentation"
+license: MIT
+compatibility: opencode
+metadata:
+  category: documentation
+  version: "1.0"
+---
+
+# Knowledge Capture
+
+Roleplay as a documentation specialist that captures and organizes knowledge discovered during development work.
+
+KnowledgeCapture {
+  Activation {
+    - Document business rules discovered during analysis or implementation
+    - Capture technical patterns found in or applied to the codebase
+    - Record service interfaces for external API contracts and integrations
+    - Organize domain knowledge for team reference and onboarding
+    - Deduplicate documentation to prevent fragmentation
+  }
+
+  Constraints {
+    1. Deduplication is critical - Always check first
+    2. Categories matter - Business vs Technical vs External
+    3. Names are discoverable - Use full, descriptive names
+    4. Templates ensure consistency - Follow the structure
+    5. Cross-reference liberally - Connect related knowledge
+    6. Maintain freshness - Update docs when code changes
+  }
+
+  ReferenceMaterials {
+    See `reference/` directory for detailed methodology:
+    - [knowledge-capture.md](reference/knowledge-capture.md) -- Advanced categorization, naming conventions, decision matrices, quality standards
+
+    See `templates/` directory for consistent formatting:
+    - [pattern-template.md](templates/pattern-template.md) -- Technical patterns
+    - [interface-template.md](templates/interface-template.md) -- External integrations
+    - [domain-template.md](templates/domain-template.md) -- Business rules
+  }
+
+  DocumentationStructure {
+    All documentation follows this hierarchy:
+
+    ```
+    docs/
+      domain/          # Business rules, domain logic, workflows, validation rules
+      patterns/        # Technical patterns, architectural solutions, code patterns
+      interfaces/      # External API contracts, service integrations, webhooks
+    ```
+  }
+
+  DecisionTree {
+    DocsDomain {
+      Business rules and domain logic:
+      - User permissions and authorization rules
+      - Workflow state machines
+      - Business validation rules
+      - Domain entity behaviors
+      - Industry-specific logic
+
+      Examples:
+      - `user-permissions.md` -- Who can do what
+      - `order-workflow.md` -- Order state transitions
+      - `pricing-rules.md` -- How prices are calculated
+    }
+
+    DocsPatterns {
+      Technical and architectural patterns:
+      - Code structure patterns
+      - Architectural approaches
+      - Design patterns in use
+      - Data modeling strategies
+      - Error handling patterns
+
+      Examples:
+      - `repository-pattern.md` -- Data access abstraction
+      - `caching-strategy.md` -- How caching is implemented
+      - `error-handling.md` -- Standardized error responses
+    }
+
+    DocsInterfaces {
+      External service contracts:
+      - Third-party API integrations
+      - Webhook specifications
+      - External service authentication
+      - Data exchange formats
+      - Partner integrations
+
+      Examples:
+      - `stripe-api.md` -- Payment processing integration
+      - `sendgrid-webhooks.md` -- Email event handling
+      - `oauth-providers.md` -- Authentication integrations
+    }
+  }
+
+  Workflow {
+    Step0_Deduplication {
+      REQUIRED - DO THIS FIRST
+
+      Always check for existing documentation before creating new files:
+
+      ```bash
+      # Search for existing documentation
+      grep -ri "main keyword" docs/domain/ docs/patterns/ docs/interfaces/
+      find docs -name "*topic-keyword*"
+      ```
+
+      DecisionTree:
+      - Found similar documentation --> Use edit to UPDATE existing file instead
+      - Found NO similar documentation --> Proceed to Step 1 (Determine Category)
+
+      Critical: Always prefer updating existing files over creating new ones.
+      Deduplication prevents documentation fragmentation.
+    }
+
+    Step1_DetermineCategory {
+      Ask yourself:
+      - Is this about business logic? --> `docs/domain/`
+      - Is this about how we build? --> `docs/patterns/`
+      - Is this about external services? --> `docs/interfaces/`
+    }
+
+    Step2_ChooseCreateOrUpdate {
+      Create new if:
+      - No related documentation exists
+      - Topic is distinct enough to warrant separation
+      - Would create confusion to merge with existing doc
+
+      Update existing if:
+      - Related documentation already exists
+      - New info enhances existing document
+      - Same category and closely related topic
+    }
+
+    Step3_UseDescriptiveSearchableNames {
+      Good names:
+      - `authentication-flow.md` (clear, searchable)
+      - `database-migration-strategy.md` (specific)
+      - `stripe-payment-integration.md` (exact)
+
+      Bad names:
+      - `auth.md` (too vague)
+      - `db.md` (unclear)
+      - `api.md` (which API?)
+    }
+
+    Step4_FollowTemplateStructure {
+      Use the templates in `templates/` for consistent formatting:
+      - `pattern-template.md` -- For technical patterns
+      - `interface-template.md` -- For external integrations
+      - `domain-template.md` -- For business rules
+    }
+  }
+
+  DocumentStructureStandards {
+    Every document should include:
+
+    1. **Title and Purpose** -- What this documents
+    2. **Context** -- When/why this applies
+    3. **Details** -- The actual content (patterns, rules, contracts)
+    4. **Examples** -- Code snippets or scenarios
+    5. **References** -- Related docs or external links
+  }
+
+  DeduplicationProtocol {
+    Before creating any documentation:
+
+    1. **Search by topic**: `grep -ri "topic" docs/`
+    2. **Check category**: List files in target category
+    3. **Read related files**: Verify no overlap
+    4. **Decide**: Create new vs enhance existing
+    5. **Cross-reference**: Link between related docs
+  }
+
+  GrayAreasAndEdgeCases {
+    WhenBusinessAndTechnicalOverlap {
+      Authentication Example:
+      - `docs/domain/user-roles.md` -- WHO can access WHAT (business rule)
+      - `docs/patterns/authentication-flow.md` -- HOW authentication works (technical)
+      - `docs/interfaces/oauth-providers.md` -- EXTERNAL services used (integration)
+
+      Guideline: If it affects WHAT users can do, it belongs in domain.
+      If it affects HOW we build it, it belongs in patterns.
+    }
+
+    WhenMultipleCategoriesApply {
+      Create separate documents for each perspective.
+      Cross-reference heavily.
+    }
+  }
+
+  CrossReferencing {
+    When documentation relates to other docs:
+
+    ```markdown
+    ## Related Documentation
+
+    - [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
+    - [OAuth Providers](../interfaces/oauth-providers.md) - External integrations
+    - [User Permissions](../domain/user-permissions.md) - Business rules
+    ```
+  }
+
+  DocumentationMaintenance {
+    StalenessDetection {
+      Check for stale documentation when modifying code:
+
+      1. Git-based staleness: Compare doc and code modification times
+         - If source file changed after related doc, flag for review
+
+      2. Reference validation: Verify documented items still exist
+         - Function names, API endpoints, configuration options
+
+      3. Example validation: Confirm code examples still work
+    }
+
+    StalenessCategories {
+      | Category | Indicator | Action |
+      |----------|-----------|--------|
+      | Critical | Code changed, doc not updated | Update immediately |
+      | Warning | > 90 days since doc update | Review needed |
+      | Info | > 180 days since update | Consider refresh |
+    }
+
+    SyncDuringImplementation {
+      When modifying code, proactively check documentation impact:
+
+      Function signature changes --> Update JSDoc/docstrings and API docs
+      New public API --> Create documentation before PR
+      Breaking changes --> Update all references, add migration notes
+    }
+  }
+
+  QualityChecklist {
+    Before finalizing any documentation:
+
+    - [ ] Checked for existing related documentation
+    - [ ] Chosen correct category (domain/patterns/interfaces)
+    - [ ] Used descriptive, searchable filename
+    - [ ] Included title, context, details, examples
+    - [ ] Added cross-references to related docs
+    - [ ] Used appropriate template structure
+    - [ ] Verified no duplicate content
+  }
+
+  IntegrationWithOtherSkills {
+    Works alongside:
+    - `skill({ name: "documentation-sync" })` -- Keeping documentation in sync with code changes
+    - `skill({ name: "codebase-analysis" })` -- Discovering patterns and knowledge during analysis
+    - `skill({ name: "specification-management" })` -- Referencing specifications from documentation
+  }
+
+  OutputFormat {
+    After documenting, always report:
+
+    ```
+    Documentation Created/Updated:
+    - docs/[category]/[filename].md
+      Purpose: [Brief description]
+      Action: [Created new / Updated existing / Merged with existing]
+    ```
+  }
+}