@comfanion/workflow 4.1.2 → 4.3.0

package/src/opencode/skills/adr-writing/template.md

@@ -0,0 +1,130 @@
+# ADR-{{N}}: {{title}}
+
+```yaml
+id: ADR-{{N}}
+status: proposed | accepted | deprecated | superseded
+date: {{date}}
+deciders: [{{names}}]
+supersedes: ADR-{{X}}  # if applicable
+```
+
+---
+
+## Context
+
+{{describe_the_situation_and_problem}}
+
+We need to decide {{what_decision_is_needed}} because {{why_decision_is_needed_now}}.
+
+**Forces:**
+- {{force_1}} — {{tension_it_creates}}
+- {{force_2}} — {{tension_it_creates}}
+
+**Constraints:**
+- {{constraint}}
+
+<!-- e.g.
+We need to choose the primary database for the Task module. The decision affects data modeling, query patterns, and operational complexity.
+
+We need to decide now because development starts next sprint and database choice impacts schema design.
+
+**Forces:**
+- Need ACID transactions for task assignments — pushes toward relational DB
+- May need flexible attributes later — pushes toward document DB
+- Team expertise is primarily SQL — reduces risk with familiar tech
+
+**Constraints:**
+- Must run on existing Kubernetes cluster
+- Budget limits exclude managed services over $500/month
+-->
+
+---
+
+## Decision
+
+**We will {{chosen_approach}}.**
+
+{{brief_explanation_of_what_this_means_in_practice}}
+
+---
+
+## Options Considered
+
+### Option 1: {{name}}
+
+{{brief_description}}
+
+| Pros | Cons |
+|------|------|
+| {{pro}} | {{con}} |
+| {{pro}} | {{con}} |
+
+### Option 2: {{name}}
+
+{{brief_description}}
+
+| Pros | Cons |
+|------|------|
+| {{pro}} | {{con}} |
+
+### Option 3: {{name}} ✓ CHOSEN
+
+{{brief_description}}
+
+| Pros | Cons |
+|------|------|
+| {{pro}} | {{con}} |
+
+**Why chosen:** {{rationale}}
+
+<!-- e.g.
+### Option 1: MongoDB
+
+Document database with flexible schema.
+
+| Pros | Cons |
+|------|------|
+| Flexible schema | No ACID across documents |
+| Good for nested data | Team unfamiliar |
+
+### Option 2: PostgreSQL ✓ CHOSEN
+
+Relational database with JSON support.
+
+| Pros | Cons |
+|------|------|
+| ACID transactions | Schema migrations needed |
+| Team expertise | Less flexible than document DB |
+| JSON columns for flexibility | |
+
+**Why chosen:** ACID transactions critical for task assignments. Team expertise reduces risk. JSON columns provide flexibility where needed.
+-->
+
+---
+
+## Consequences
+
+### Positive
+- {{benefit}}
+- {{benefit}}
+
+### Negative
+- {{drawback}}
+- {{mitigation_if_any}}
+
+### Risks
+- {{risk}} — mitigated by {{approach}}
+
+---
+
+## Implementation Notes
+
+{{any_specific_guidance_for_implementation}}
+
+---
+
+## References
+
+→ Architecture: `{{path}}`
+→ Related ADR: → ADR: `ADR-{{X}}`
+→ Affected Units: → Unit: `{{unit}}`

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

@@ -26,11 +26,107 @@ Always check project standards: `@CLAUDE.md`
 
 ## Template
 
-Use template at: `@.opencode/templates/architecture-template.md`
+Use template at: `@.opencode/skills/architecture-design/template.md`
+
+## Architecture Document Structure (v2)
+
+### 1. Executive Summary
+
+Brief prose with:
+- What the system is
+- Architecture pattern + why chosen
+- Key domains with module counts
+- Critical business rules
+- Scale targets
+
+### 2. Decision Summary
+
+| Category | Decision | Rationale |
+|----------|----------|-----------|
+| Architecture | Hexagonal | Organizational standard |
+| Database | PostgreSQL per module | Service isolation |
+
+### 3. System Context
+
+ASCII diagram showing:
+- External systems
+- Main system boundary
+- Internal modules
+- Storage layer
+
+### 4. Modules Overview
+
+For each domain, then each module:
+
+```markdown
+### {{Domain}} ({{N}} modules)
+
+#### {{Module}}
+
+**Purpose:** {{single_responsibility}}
+
+**Internal Services:**
+
+| Service | Responsibilities | Storage |
+|---------|-----------------|---------|
+
+**Database Schema:**
+```
+table_name    # field descriptions
+```
+
+**Events:**
+- **Produces:** Event1, Event2
+- **Consumes:** Event3
+
+**Notes:**
+- Important details
+```
+
+### 5. Data Architecture
+
+| Module | Primary DB | Cache | Other |
+|--------|-----------|-------|-------|
+
+With entity relations diagram.
+
+### 6. Integration
+
+External systems table + internal communication table.
+
+### 7. Cross-Cutting Concerns
+
+- Security (AuthN, AuthZ)
+- Observability (Logging, Metrics, Tracing)
+- Error Handling table
+
+### 8. NFR Compliance
+
+| NFR | Requirement | How Addressed |
+|-----|-------------|---------------|
+
+### 9. References
+
+```
+→ PRD: `docs/prd.md`
+→ ADRs: `docs/architecture/adr/`
+```
+
+## Unit Documentation
+
+For each module/domain/entity, create separate Unit document.
+
+Use: `@.opencode/skills/unit-writing/template.md`
+
+Reference in architecture:
+```
+→ Unit: `catalog`
+→ Unit: `Task`
+```
 
 ## Architecture Principles
 
-### 1. Hexagonal Architecture (Ports & Adapters)
+### Hexagonal Architecture
 
 ```
 ┌─────────────────────────────────────────────────────┐
@@ -47,33 +143,9 @@ Use template at: `@.opencode/templates/architecture-template.md`
 └─────────────────────────────────────────────────────┘
 
 Dependency Direction: Infrastructure → Application → Domain
-                      (NEVER reverse!)
 ```
 
-### 2. Module Structure
-
-```
-module/
-├── domain/              # Business logic ONLY
-│   ├── aggregate/       # Entities with business rules
-│   ├── valueobject/     # Immutable value objects
-│   ├── service/         # Domain services
-│   ├── repository/      # Repository INTERFACES (ports)
-│   └── event/           # Domain events
-├── application/         # Use cases
-│   └── usecase/
-│       └── CreateEntity/
-│           ├── inport.go    # Interface
-│           ├── dto.go       # Command & Result
-│           ├── handler.go   # Orchestration
-│           └── mappers.go   # Explicit mapping
-└── infrastructure/      # Adapters
-    ├── repo/            # DB implementations
-    ├── http/            # HTTP handlers
-    └── kafka/           # Event publishers
-```
-
-### 3. Module Boundaries
+### Module Boundaries
 
 Each module must have:
 - **Single responsibility** - One business capability
@@ -81,75 +153,17 @@ Each module must have:
 - **Defined interfaces** - API contracts for communication
 - **No cross-module imports** - Communicate via Kafka/HTTP only
 
-## Design Process
-
-### Step 1: Identify Bounded Contexts
-
-From PRD, identify:
-1. Major business capabilities
-2. Data ownership boundaries
-3. Team boundaries (Conway's Law)
-
-### Step 2: Define Module Contracts
-
-For each module:
-```yaml
-module: catalog
-responsibility: Product and category management
-owns:
-  - Product
-  - Category
-  - Attribute
-consumes:
-  - merchant.created (from Merchant module)
-produces:
-  - product.created
-  - product.updated
-  - category.created
-api:
-  - POST /api/v1/products
-  - GET /api/v1/products/{id}
-  - GET /api/v1/categories
-```
+### Reference Format
 
-### Step 3: Design Data Model
-
-For each owned entity:
-- Primary key strategy (UUID recommended)
-- Required fields
-- Indexes (for query patterns)
-- Relationships
-- Audit fields (created_at, updated_at, version)
-
-### Step 4: Design Events
-
-For state changes:
-```yaml
-event: product.created
-version: "1.0"
-payload:
-  product_id: uuid
-  merchant_id: uuid
-  name: string
-  created_at: timestamp
+Always use `→` prefix:
+```
+→ Unit: `catalog`
+→ FR: `FR-001`
+→ ADR: `ADR-001`
+→ PRD: `docs/prd.md`
 ```
 
-### Step 5: Document Decisions (ADRs)
-
-Use skill: `adr-writing`
-
-## NFR Mapping
-
-Map each NFR to architectural solution:
-
-| NFR | Architectural Support |
-|-----|----------------------|
-| Response < 200ms | Caching (Redis), connection pooling |
-| 99.9% availability | K8s HA, health checks, circuit breakers |
-| 1000 RPS | Horizontal scaling, async processing |
-| Data security | TLS, encryption at rest, audit logs |
-
-## Architecture Checklist
+## Validation Checklist
 
 Before completing:
 - [ ] All PRD functional areas have architectural home
@@ -159,25 +173,17 @@ Before completing:
 - [ ] No circular dependencies between modules
 - [ ] Integration points are well-defined
 - [ ] ADRs exist for major decisions
-- [ ] Aligns with CLAUDE.md patterns
-- [ ] Diagrams included (context, container, component)
-
-## Anti-patterns to Avoid
-
-1. **Distributed monolith** - Modules that must deploy together
-2. **Shared database** - Multiple modules accessing same tables
-3. **Circular dependencies** - Module A depends on B depends on A
-4. **God module** - One module doing everything
-5. **Anemic domain** - Business logic in services, not entities
+- [ ] Uses `→` reference format
+- [ ] Unit docs created for key modules
 
 ## Output
 
-Save to: `docs/architecture.md`
+- Main: `docs/architecture.md`
+- Units: `docs/architecture/units/` or inline
+- ADRs: `docs/architecture/adr/`
 
 ## Related Skills
 
 - `adr-writing` - For architecture decisions
-- `data-modeling` - For database design
-- `api-design` - For REST API contracts
-- `event-design` - For Kafka event schemas
+- `unit-writing` - For module/entity documentation
 - `architecture-validation` - For validation

package/src/opencode/skills/architecture-design/template.md

@@ -0,0 +1,212 @@
+# {{project}} — Architecture
+
+```yaml
+id: ARCH-001
+version: 1.0
+status: draft | approved
+date: {{date}}
+author: {{author}}
+```
+
+---
+
+## Executive Summary
+
+{{project}} is a {{type}} for {{purpose}}. The system handles {{core_capabilities}}.
+
+**Architecture Pattern:** {{pattern}} — {{why_this_pattern}}
+
+**Key Domains:**
+1. **{{domain_1}}** ({{modules_count}} modules) — {{description}}
+2. **{{domain_2}}** ({{modules_count}} modules) — {{description}}
+
+**Critical Business Rules:**
+- {{rule_1}}
+- {{rule_2}}
+
+**Scale:**
+- **MVP:** {{scale}}
+- **Growth:** {{scale}}
+
+<!-- e.g.
+TaskFlow is a task management platform for distributed teams.
+
+**Architecture Pattern:** Modular Monolith with Hexagonal Architecture — enables independent scaling while keeping deployment simple
+
+**Key Domains:**
+1. **Task Domain** (2 modules) — Task CRUD, assignments, status workflow
+2. **Team Domain** (2 modules) — Users, roles, permissions
+
+**Critical Business Rules:**
+- One task = one assignee (no shared ownership)
+- Status transitions: todo → in_progress → done
+-->
+
+---
+
+## Decision Summary
+
+| Category | Decision | Rationale |
+|----------|----------|-----------|
+| Architecture | {{decision}} | {{why}} |
+| Database | {{decision}} | {{why}} |
+| Communication | {{decision}} | {{why}} |
+
+<!-- e.g.
+| Architecture | Hexagonal (Ports & Adapters) | Organizational standard |
+| Database | PostgreSQL per module | Service isolation |
+| Communication | REST sync + Kafka async | REST for queries, Kafka for events |
+-->
+
+---
+
+## System Context
+
+```
+     {{external_1}}        {{external_2}}
+          │                     │
+          ▼                     ▼
+┌─────────────────────────────────────────┐
+│              {{project}}                 │
+│                                          │
+│   ┌─────────┐  ┌─────────┐  ┌─────────┐ │
+│   │{{mod_1}}│  │{{mod_2}}│  │{{mod_3}}│ │
+│   └─────────┘  └─────────┘  └─────────┘ │
+│                                          │
+└─────────────────────────────────────────┘
+          │                     │
+          ▼                     ▼
+     {{storage_1}}         {{storage_2}}
+```
+
+---
+
+## Modules Overview
+
+### {{Domain_1}} ({{N}} modules)
+
+#### {{Module_1}}
+
+**Purpose:** {{single_responsibility}}
+
+**Internal Services:**
+
+| Service | Responsibilities | Storage |
+|---------|-----------------|---------|
+| {{service}} | {{what_it_does}} | {{db}} |
+| {{service}} | {{what_it_does}} | {{db}} |
+
+**Database Schema:**
+```
+{{table_1}}    # {{fields_description}}
+{{table_2}}    # {{fields_description}}
+```
+
+**Events:**
+- **Produces:** {{event_1}}, {{event_2}}
+- **Consumes:** {{event_1}}
+
+**Notes:**
+- {{important_detail}}
+
+<!-- e.g.
+#### Task Module
+
+**Purpose:** Task lifecycle management — CRUD, assignments, status transitions
+
+**Internal Services:**
+
+| Service | Responsibilities | Storage |
+|---------|-----------------|---------|
+| tasks | Task CRUD, validation | PostgreSQL |
+| assignments | User-task linking | PostgreSQL |
+| workflow | Status transitions | PostgreSQL |
+
+**Database Schema:**
+```
+tasks           # id, title, description, status, assignee_id, due_date
+task_history    # task_id, field, old_value, new_value, changed_at
+```
+
+**Events:**
+- **Produces:** TaskCreated, TaskUpdated, TaskAssigned, StatusChanged
+- **Consumes:** UserDeactivated (to reassign tasks)
+
+**Notes:**
+- Status flow: todo → in_progress → done (configurable per workspace)
+-->
+
+---
+
+## Data Architecture
+
+### Storage by Module
+
+| Module | Primary DB | Cache | Other |
+|--------|-----------|-------|-------|
+| {{module}} | {{db}} | {{cache}} | {{other}} |
+
+### Key Entity Relations
+
+```
+{{entity_1}} ──< {{entity_2}}
+      │
+      └──── {{entity_3}}
+```
+
+---
+
+## Integration
+
+### External Systems
+
+| System | Protocol | Direction | Purpose |
+|--------|----------|-----------|---------|
+| {{system}} | {{protocol}} | In/Out | {{purpose}} |
+
+**Notes:**
+- {{integration_detail}}
+
+### Internal Communication
+
+| From | To | Method | When |
+|------|-----|--------|------|
+| {{module}} | {{module}} | {{REST/Kafka}} | {{trigger}} |
+
+---
+
+## Cross-Cutting Concerns
+
+### Security
+| Concern | Implementation |
+|---------|---------------|
+| AuthN | {{approach}} |
+| AuthZ | {{approach}} |
+
+### Observability
+- **Logging:** {{tool}}
+- **Metrics:** {{tool}}
+- **Tracing:** {{tool}}
+
+### Error Handling
+| Error Type | HTTP | Strategy |
+|------------|------|----------|
+| Validation | 400 | Return field errors |
+| Not Found | 404 | Return with message |
+| Business Rule | 422 | Return error code |
+
+---
+
+## NFR Compliance
+
+| NFR | Requirement | How Addressed |
+|-----|-------------|---------------|
+| NFR-001 | {{requirement}} | {{solution}} |
+
+---
+
+## References
+
+→ PRD: `{{path}}`
+→ ADRs: `{{path}}`
+→ Diagrams: `{{path}}`

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

@@ -184,7 +184,7 @@ After validation:
 ### Action Required
 
 Create the QA artifact using template:
-`@.opencode/templates/integration-tests-template.md`
+`@.opencode/skills/test-design/template-integration.md`
 
 This artifact is MANDATORY before proceeding to epics.
 ```

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

@@ -0,0 +1,23 @@
+# 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] - YYYY-MM-DD
+
+### Added
+- Initial project setup
+- Basic documentation structure