@comfanion/workflow 3.0.0

package/src/opencode/skills/architecture-validation/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: architecture-validation
+description: How to validate architecture for PRD coverage, NFR compliance, and QA artifact presence
+license: MIT
+compatibility: opencode
+metadata:
+  domain: quality-assurance
+  artifacts: docs/validation/architecture-validation-*.md
+---
+
+# Architecture Validation Skill
+
+## When to Use
+
+Use this skill when you need to:
+- Validate architecture before creating epics
+- Ensure all PRD requirements have architectural home
+- Ensure all NFRs have architectural support
+- Check QA artifact (architecture-integration-tests.md) exists
+
+## Prerequisites
+
+- PRD validation must PASS first
+- File: `docs/prd.md`
+
+## Validation Checklist
+
+### Structure Checks
+
+- [ ] File exists at `docs/architecture.md`
+- [ ] Architecture Overview section exists
+- [ ] Module/Service Architecture section exists
+- [ ] Data Architecture section exists
+- [ ] Integration Architecture section exists
+- [ ] Cross-Cutting Concerns section exists
+- [ ] ADRs section exists
+- [ ] NFR Compliance section exists
+
+### PRD Coverage
+
+- [ ] All PRD functional areas have architectural home
+- [ ] Each module has clear responsibility
+- [ ] Each module has defined boundaries
+- [ ] Data ownership is explicit
+
+### NFR Compliance
+
+For each NFR in PRD:
+- [ ] Has concrete architectural support
+- [ ] Support is documented in NFR Compliance section
+- [ ] Implementation approach is clear
+
+### Module Quality
+
+For each module:
+- [ ] Single responsibility defined
+- [ ] Owns specific entities (data ownership)
+- [ ] Consumes/produces events documented
+- [ ] API contracts defined
+- [ ] No circular dependencies
+
+### Pattern Compliance
+
+- [ ] Follows hexagonal architecture
+- [ ] Domain layer has no infrastructure imports
+- [ ] Use case pattern (4 files) documented
+- [ ] Aligns with CLAUDE.md standards
+
+### ADR Checks
+
+- [ ] Major decisions have ADRs
+- [ ] ADRs follow template (Context, Decision, Consequences)
+- [ ] ADRs have status (Accepted/Superseded/Deprecated)
+
+### QA Artifact Check (MANDATORY)
+
+- [ ] File exists: `docs/architecture-integration-tests.md`
+- [ ] Module contracts defined
+- [ ] Event-driven tests specified
+- [ ] API boundary tests specified
+- [ ] NFR verification tests specified
+
+## Dependency Analysis
+
+Check for circular dependencies:
+
+```
+Module A → Module B → Module C → Module A  ❌ CYCLE!
+```
+
+Build dependency graph and verify it's a DAG.
+
+## Validation Report Format
+
+```markdown
+# Architecture Validation Report
+
+**Date:** YYYY-MM-DD
+**Status:** PASS | WARN | FAIL
+**File:** docs/architecture.md
+
+## Prerequisites
+
+| Prerequisite | Status |
+|--------------|--------|
+| prd.md validated | ✅ PASS |
+
+## Summary
+
+| Check Type | Total | Passed | Warnings | Failed |
+|------------|-------|--------|----------|--------|
+| Structure | 8 | 8 | 0 | 0 |
+| PRD Coverage | 4 | 4 | 0 | 0 |
+| NFR Compliance | 12 | 12 | 0 | 0 |
+| Module Quality | 5 | 5 | 0 | 0 |
+| Pattern Compliance | 4 | 4 | 0 | 0 |
+| ADRs | 3 | 3 | 0 | 0 |
+| QA Artifact | 4 | 4 | 0 | 0 |
+
+## QA Artifact Status
+
+| Artifact | Status |
+|----------|--------|
+| `docs/architecture-integration-tests.md` | ✅ Present |
+| Module Contract Tests | Defined |
+| API Boundary Tests | Defined |
+| NFR Verification Tests | Defined |
+
+## Module Dependency Graph
+
+```
+Catalog ──→ (none)
+Inventory ──→ Catalog
+Orders ──→ Catalog, Inventory
+```
+
+**Circular Dependencies:** None ✅
+
+## NFR Compliance Matrix
+
+| NFR ID | Requirement | Architectural Support | Status |
+|--------|-------------|----------------------|--------|
+| NFR-001 | < 200ms response | Redis caching | ✅ |
+| NFR-002 | 99.9% uptime | K8s HA, health checks | ✅ |
+| NFR-003 | 1000 RPS | Horizontal scaling | ✅ |
+
+## ADR Summary
+
+| ADR | Decision | Status |
+|-----|----------|--------|
+| ADR-001 | Use PostgreSQL | Accepted |
+| ADR-002 | Event-driven integration | Accepted |
+| ADR-003 | Modular monolith | Accepted |
+
+## Passed Checks
+
+- [x] All PRD functional areas covered
+- [x] All NFRs have architectural support
+- [x] No circular dependencies
+- [x] QA artifact present
+
+## Warnings
+
+(None)
+
+## Failures
+
+(None if PASS)
+
+## Next Steps
+
+After validation:
+- If PASS, proceed to `/epics`
+```
+
+## If QA Artifact Missing
+
+```markdown
+## FAILURE: QA Artifact Missing
+
+**Required:** `docs/architecture-integration-tests.md`
+**Status:** ❌ NOT FOUND
+
+### Action Required
+
+Create the QA artifact using template:
+`@.opencode/templates/integration-tests-template.md`
+
+This artifact is MANDATORY before proceeding to epics.
+```
+
+## Output
+
+Save to: `docs/validation/architecture-validation-YYYY-MM-DD.md`
+
+## Related Skills
+
+- `architecture-design` - For fixing architecture issues
+- `adr-writing` - For documenting decisions

package/src/opencode/skills/archiving/SKILL.md

@@ -0,0 +1,191 @@
+---
+description: Manages document lifecycle - archives outdated docs while preserving history
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    "*": deny
+    "ls *": allow
+    "cat *": allow
+    "tree *": allow
+    "mkdir *": allow
+    "mv *": allow
+    "cp *": allow
+    "date *": allow
+---
+
+# Document Archivist
+
+You are a Documentation Lifecycle Manager responsible for maintaining document hygiene. You archive outdated documents, preserve history, and ensure the docs directory stays current and relevant.
+
+## Core Principle
+
+**Documents are never deleted, only archived.** Every document has history value.
+
+## Archive Structure
+
+```
+docs/archive/
+├── README.md                    # Archive index and policies
+├── research/                    # Archived research
+│   └── [topic]-YYYY-MM-DD.md
+├── prd/                         # Archived PRD versions
+│   └── prd-vX.Y-YYYY-MM-DD.md
+├── architecture/                # Archived architecture versions
+│   └── architecture-vX.Y-YYYY-MM-DD.md
+├── modules/                     # Archived module docs
+│   └── [module]/
+├── coding-standards/            # Archived standards
+│   └── [file]-YYYY-MM-DD.md
+└── sprint-artifacts/            # Archived sprints (completed)
+    └── sprint-N/
+```
+
+## Archiving Rules
+
+### When to Archive
+
+| Document Type | Archive When |
+|--------------|--------------|
+| Research | Superseded by new research, > 1 year old |
+| PRD | Major version change, scope pivot |
+| Architecture | Major redesign, tech stack change |
+| Module docs | Module deprecated or merged |
+| Coding standards | Standards significantly changed |
+| Sprint artifacts | Sprint completed + retrospective done |
+
+### Archive Process
+
+1. **Add archive metadata** to the document:
+   ```markdown
+   ---
+   archived: true
+   archived_date: YYYY-MM-DD
+   archived_reason: [reason]
+   superseded_by: [path to new doc]  # if applicable
+   ---
+   ```
+
+2. **Rename with date suffix**:
+   - `document.md` → `document-YYYY-MM-DD.md`
+
+3. **Move to archive**:
+   - From: `docs/[path]/document.md`
+   - To: `docs/archive/[path]/document-YYYY-MM-DD.md`
+
+4. **Update references**:
+   - Update any docs that linked to archived doc
+   - Add "Archived" note with link to new version
+
+5. **Update archive index**:
+   - Add entry to `docs/archive/README.md`
+
+## Archive Metadata Template
+
+Add to top of document before archiving:
+
+```markdown
+---
+archived: true
+archived_date: 2026-01-23
+archived_reason: "Superseded by v2.0 after architecture redesign"
+superseded_by: "../architecture.md"
+original_path: "docs/architecture.md"
+original_version: "1.5"
+---
+
+# [Original Title] (ARCHIVED)
+
+> **ARCHIVED:** This document was archived on 2026-01-23.
+> **Reason:** Superseded by v2.0 after architecture redesign
+> **Current Version:** [architecture.md](../architecture.md)
+
+---
+
+[Original content below]
+```
+
+## Archive Index (README.md)
+
+```markdown
+# Documentation Archive
+
+This directory contains archived documents that are no longer current
+but preserved for historical reference.
+
+## Archive Policy
+
+- Documents are archived, never deleted
+- Each archived doc includes reason and date
+- Superseding documents are linked
+- Archive is searchable by date and type
+
+## Recently Archived
+
+| Document | Type | Archived | Reason |
+|----------|------|----------|--------|
+| [doc](./path) | PRD | 2026-01-23 | v2.0 released |
+
+## Archive by Type
+
+### PRD Versions
+| Version | Date | Reason | Link |
+|---------|------|--------|------|
+
+### Architecture Versions
+| Version | Date | Reason | Link |
+|---------|------|--------|------|
+
+### Research
+| Topic | Date | Reason | Link |
+|-------|------|--------|------|
+
+### Module Documentation
+| Module | Date | Reason | Link |
+|--------|------|--------|------|
+
+### Coding Standards
+| File | Date | Reason | Link |
+|------|------|--------|------|
+
+## Retrieval
+
+To find archived documents:
+1. Check this index
+2. Search by date in folder names
+3. Use git history for pre-archive versions
+```
+
+## Commands
+
+### Archive Single Document
+```bash
+# Move and rename
+mv docs/research/topic.md docs/archive/research/topic-$(date +%Y-%m-%d).md
+```
+
+### Archive Sprint (after completion)
+```bash
+# Move entire sprint folder
+mv docs/sprint-artifacts/sprint-N docs/archive/sprint-artifacts/sprint-N
+```
+
+## Validation Before Archiving
+
+- [ ] Document has archive metadata added
+- [ ] Superseding document exists (if applicable)
+- [ ] References to archived doc updated
+- [ ] Archive index updated
+- [ ] No broken links in main docs
+
+## What NOT to Archive
+
+- Current sprint artifacts (until sprint complete)
+- Active research (until superseded)
+- Current PRD/Architecture (until new version approved)
+- Templates (these don't get archived)

package/src/opencode/skills/changelog/SKILL.md

@@ -0,0 +1,280 @@
+# Changelog Skill
+
+> **Purpose**: Maintain changelogs for repository and documents
+> **Used by**: All agents, Dev agent (mandatory)
+
+## Two Types of Changelog
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| **Repository** | `CHANGELOG.md` | Track code/feature changes |
+| **Document** | Each doc file | Track document revisions |
+
+---
+
+## Repository CHANGELOG
+
+### Format: Keep a Changelog
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Add product catalog API with CRUD operations
+- Add Kafka event publishing for order changes
+
+### Changed
+- Change price field from float to decimal
+
+### Fixed
+- Fix race condition in inventory reservation (#234)
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- Add bulk import for products (EPIC:E08)
+```
+
+### Categories (in order)
+
+| Category | What to include |
+|----------|-----------------|
+| **Added** | New features, endpoints, modules |
+| **Changed** | Changes to existing functionality |
+| **Deprecated** | Features to be removed in future |
+| **Removed** | Removed features |
+| **Fixed** | Bug fixes |
+| **Security** | Security vulnerability fixes |
+
+### Entry Format
+
+```markdown
+- {Verb} {what} {context} ({reference})
+
+Examples:
+- Add user registration API endpoint
+- Add pagination to product list (STORY:S05-04)
+- Change order status from string to enum (BREAKING)
+- Fix null pointer in payment processing (#123)
+- Security: Fix SQL injection in search query (CVE-2024-XXX)
+```
+
+### When to Update
+
+| Event | Action |
+|-------|--------|
+| Story completed | Add entry to `[Unreleased]` |
+| Sprint completed | Keep in `[Unreleased]` |
+| Release | Move `[Unreleased]` → `[X.Y.Z] - date` |
+| Hotfix | Add to `[Unreleased]` + release |
+
+### Versioning (SemVer)
+
+```
+MAJOR.MINOR.PATCH
+
+1.0.0 → 1.0.1  (patch: bug fix)
+1.0.1 → 1.1.0  (minor: new feature)
+1.1.0 → 2.0.0  (major: breaking change)
+```
+
+| Change Type | Version Bump |
+|-------------|--------------|
+| Bug fix | PATCH |
+| New feature (backward compatible) | MINOR |
+| Breaking change | MAJOR |
+| Security fix | PATCH (or MINOR if API change) |
+
+---
+
+## Document Changelog
+
+### Format
+
+Add to end of every document:
+
+```markdown
+---
+
+## Changelog
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.2 | 2024-01-20 | @architect | Add NFR section, update diagrams |
+| 1.1 | 2024-01-15 | @pm | Add FR-015 to FR-020, clarify scope |
+| 1.0 | 2024-01-10 | @pm | Initial approved version |
+| 0.2 | 2024-01-08 | @analyst | Add user personas, journeys |
+| 0.1 | 2024-01-05 | @pm | Initial draft |
+```
+
+### Entry Format
+
+```markdown
+| {version} | {date} | @{author} | {changes summary} |
+```
+
+### Version Numbering for Documents
+
+```
+0.x - Draft (not approved)
+1.0 - First approved version
+1.x - Minor updates (additions, clarifications)
+2.0 - Major revision (scope change, restructure)
+```
+
+### When to Update
+
+**At END of work session** - not on every small change!
+
+```
+Session Start
+  ├── Make change 1
+  ├── Make change 2
+  ├── Make change 3
+  └── ...
+Session End
+  └── Add ONE changelog entry summarizing all changes
+```
+
+### What to Log
+
+Summarize session work in one entry:
+
+| Session Work | Changelog Entry |
+|--------------|-----------------|
+| Added 3 sections, fixed 2 typos | "Add security, NFR, risks sections; Fix typos in FR-001, FR-003" |
+| Major restructure | "Restructure: Split FR into domains; Add traceability matrix" |
+| Small fixes | "Minor: Clarify scope; Update metrics" |
+
+---
+
+## Integration with Workflow
+
+### Story Completion → CHANGELOG
+
+```markdown
+## Story completed: CATALOG-S05-03
+
+### Added to CHANGELOG.md:
+- Add product search API with filters (CATALOG-S05-03)
+- Add Elasticsearch integration for full-text search
+```
+
+### Document Update → Document Changelog
+
+```markdown
+## PRD Updated
+
+| 1.3 | 2024-01-20 | @pm | Add FR-021 payment retry logic |
+```
+
+### Dev Workflow Integration
+
+```xml
+<step n="7" goal="Update changelog after story completion">
+  <action>Read current CHANGELOG.md</action>
+  <action>Add entries to [Unreleased] section</action>
+  <action>Use format: "- {Verb} {what} ({story-id})"</action>
+  <action>Save CHANGELOG.md</action>
+</step>
+```
+
+---
+
+## Templates
+
+### Repository CHANGELOG.md
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- 
+
+### Changed
+- 
+
+### Fixed
+- 
+
+## [0.1.0] - {{date}}
+
+### Added
+- Initial project setup
+- Basic documentation structure
+```
+
+### Document Changelog Section
+
+```markdown
+---
+
+## Changelog
+
+<!-- UPDATE AT END OF SESSION -->
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1 | {{date}} | @{{user}} | Initial draft |
+
+<!-- 
+Update at END of work session (not on every change)
+Summarize all changes in one entry
+-->
+```
+
+---
+
+## Automation
+
+### Git Commit → Changelog Entry
+
+```bash
+# Commit message format
+feat: Add product search API
+
+# Auto-generates:
+### Added
+- Add product search API
+```
+
+### Conventional Commits Mapping
+
+| Prefix | Category |
+|--------|----------|
+| `feat:` | Added |
+| `fix:` | Fixed |
+| `docs:` | Changed (docs) |
+| `refactor:` | Changed |
+| `perf:` | Changed (performance) |
+| `security:` | Security |
+| `BREAKING:` | Changed (breaking) |
+
+---
+
+## Validation Checklist
+
+### Repository CHANGELOG
+
+- [ ] `[Unreleased]` section exists
+- [ ] Entries start with verb
+- [ ] Entries reference story/issue ID
+- [ ] Categories in correct order
+- [ ] Dates in ISO format (YYYY-MM-DD)
+
+### Document Changelog
+
+- [ ] Changelog section at end of document
+- [ ] Version number updated
+- [ ] Date is current
+- [ ] Author identified
+- [ ] Changes are specific