@comfanion/workflow 3.0.0

package/src/opencode/opencode.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  "instructions": [
+    ".opencode/FLOW.yaml",
+    "docs/requirements/requirements.md",
+    "docs/prd.md",
+    "docs/architecture.md"
+  ],
+  
+  "agent": {
+    "build": {
+      "mode": "primary",
+      "description": "Default development agent with full tool access",
+      "model": "anthropic/claude-sonnet-4-20250514"
+    },
+    "plan": {
+      "mode": "primary",
+      "description": "Planning agent - analyzes without making changes",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "permission": {
+        "edit": "ask",
+        "bash": "ask"
+      }
+    }
+  },
+  
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "rm -rf *": "deny",
+      "git push --force*": "ask",
+      "git reset --hard*": "ask"
+    }
+  }
+}

package/src/opencode/skills/acceptance-criteria/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: acceptance-criteria
+description: How to write testable acceptance criteria using Given/When/Then format
+license: MIT
+compatibility: opencode
+metadata:
+  domain: quality-assurance
+  format: gherkin
+---
+
+# Acceptance Criteria Writing Skill
+
+## When to Use
+
+Use this skill when you need to:
+- Write acceptance criteria for FRs in PRD
+- Write AC for epics and stories
+- Define testable behavior specifications
+- Create QA test scenarios
+
+## Given/When/Then Format
+
+### Structure
+
+```gherkin
+Given [precondition/context]
+When [action/trigger]
+Then [expected outcome]
+And [additional outcome]
+```
+
+### Example
+
+```gherkin
+AC1: Successful product creation
+Given a merchant is authenticated
+And the merchant has permission to create products
+When the merchant submits a valid product with:
+  - name: "Test Product"
+  - price: 100.00 UAH
+  - SKU: "TEST-001"
+Then a new product is created with status "pending"
+And the product is assigned a unique ID
+And an event "product.created" is published
+```
+
+## AC Quality Checklist
+
+Each acceptance criterion must be:
+- [ ] **Testable** - Can be verified as pass/fail
+- [ ] **Independent** - Doesn't depend on other AC execution order
+- [ ] **Specific** - Exact expected behavior, not vague
+- [ ] **Complete** - Covers one complete scenario
+
+## Types of Acceptance Criteria
+
+### 1. Happy Path AC
+Normal, successful flow.
+
+```gherkin
+Given valid input
+When action performed
+Then success result
+```
+
+### 2. Edge Case AC
+Boundary conditions.
+
+```gherkin
+Given input at boundary (min/max/empty)
+When action performed
+Then appropriate handling
+```
+
+### 3. Error Case AC
+Invalid input or failure scenarios.
+
+```gherkin
+Given invalid input
+When action attempted
+Then error returned with message
+And no side effects occur
+```
+
+### 4. Security AC
+Authorization and authentication.
+
+```gherkin
+Given user without permission
+When action attempted
+Then access denied (403)
+```
+
+### 5. Performance AC
+Non-functional behavior.
+
+```gherkin
+Given 1000 concurrent requests
+When action performed
+Then response time < 200ms p95
+```
+
+## AC for Different Artifacts
+
+### PRD Level (High-level)
+
+```markdown
+## FR-001: Product Creation
+
+**Acceptance Criteria:**
+- [ ] Merchant can create product with required fields
+- [ ] Product validation rejects invalid data
+- [ ] Created product appears in product list
+- [ ] Product creation event is published
+```
+
+### Epic Level (Feature-level)
+
+```markdown
+## Acceptance Criteria
+
+- [ ] All CRUD operations for products work
+- [ ] Validation rules are enforced
+- [ ] Events are published for all state changes
+- [ ] API follows REST conventions
+- [ ] Unit test coverage > 80%
+```
+
+### Story Level (Detailed)
+
+```markdown
+## Acceptance Criteria
+
+### AC1: Create product with valid data
+**Given** authenticated merchant with "product:create" permission
+**When** POST /api/v1/products with valid payload
+**Then** 201 Created returned
+**And** product has generated UUID
+**And** product status is "pending"
+**And** "product.created" event published to Kafka
+
+### AC2: Reject invalid product data
+**Given** authenticated merchant
+**When** POST /api/v1/products with missing "name"
+**Then** 400 Bad Request returned
+**And** error response contains validation details
+**And** no product is created
+
+### AC3: Reject unauthorized access
+**Given** authenticated user without "product:create" permission
+**When** POST /api/v1/products
+**Then** 403 Forbidden returned
+```
+
+## Common Mistakes to Avoid
+
+1. **Too vague**: "System works correctly" → Define WHAT "correctly" means
+2. **Multiple scenarios in one AC**: Split into separate ACs
+3. **Implementation details**: "Use PostgreSQL" → Focus on WHAT, not HOW
+4. **Missing error cases**: Always include negative scenarios
+5. **No measurable outcome**: "Fast response" → "< 200ms"
+
+## AC Templates
+
+### CRUD Operations
+
+```gherkin
+# Create
+Given valid [entity] data
+When POST /api/v1/[entities]
+Then 201 Created with [entity] details
+
+# Read
+Given existing [entity] with ID
+When GET /api/v1/[entities]/{id}
+Then 200 OK with [entity] details
+
+# Update
+Given existing [entity] with ID
+When PUT /api/v1/[entities]/{id} with updates
+Then 200 OK with updated [entity]
+
+# Delete
+Given existing [entity] with ID
+When DELETE /api/v1/[entities]/{id}
+Then 204 No Content
+And [entity] no longer retrievable
+```
+
+### Validation
+
+```gherkin
+Given [entity] with invalid [field]
+When create/update attempted
+Then 400 Bad Request
+And error identifies [field] and reason
+```
+
+### Authorization
+
+```gherkin
+Given user with role [role]
+When accessing [resource]
+Then [allowed/denied] based on permissions
+```
+
+## Related Skills
+
+- `story-writing` - For complete user stories
+- `epic-writing` - For epic-level AC
+- `prd-writing` - For FR-level AC
+- `integration-testing` - For test implementation

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

@@ -0,0 +1,241 @@
+---
+name: adr-writing
+description: How to write Architecture Decision Records (ADRs) documenting technical decisions and rationale
+license: MIT
+compatibility: opencode
+metadata:
+  domain: software-architecture
+  artifacts: docs/architecture/adr/
+---
+
+# ADR Writing Skill
+
+## When to Use
+
+Use this skill when you need to:
+- Document a significant architectural decision
+- Record the rationale behind a technical choice
+- Track decision history over time
+- Communicate decisions to the team
+
+## When to Write an ADR
+
+Write an ADR when:
+- Choosing between multiple valid approaches
+- Making a decision that affects multiple modules
+- Selecting a technology or framework
+- Defining a pattern to follow consistently
+- Making a trade-off between quality attributes
+
+## ADR Template
+
+```markdown
+# ADR-NNN: [Decision Title]
+
+**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+**Date:** YYYY-MM-DD
+**Deciders:** [Names of people involved]
+**Technical Story:** [Link to epic/story if applicable]
+
+## Context
+
+[Describe the situation that led to this decision. What is the problem?
+What forces are at play? What constraints exist?]
+
+## Decision
+
+[State the decision clearly. What are we going to do?]
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Neutral
+- [Side effect that is neither good nor bad]
+
+## Alternatives Considered
+
+### Alternative 1: [Name]
+[Brief description]
+- **Pros:** [advantages]
+- **Cons:** [disadvantages]
+- **Rejected because:** [reason]
+
+### Alternative 2: [Name]
+[Brief description]
+- **Pros:** [advantages]
+- **Cons:** [disadvantages]
+- **Rejected because:** [reason]
+
+## References
+
+- [Link to relevant documentation]
+- [Link to research or benchmarks]
+
+## Notes
+
+[Any additional context, caveats, or follow-up actions]
+```
+
+## Naming Convention
+
+```
+ADR-NNN-short-description.md
+
+Examples:
+- ADR-001-use-postgresql.md
+- ADR-002-event-driven-integration.md
+- ADR-003-modular-monolith-architecture.md
+```
+
+## Status Lifecycle
+
+```
+Proposed → Accepted → (Deprecated | Superseded)
+```
+
+- **Proposed:** Under discussion
+- **Accepted:** Decision made and in effect
+- **Deprecated:** No longer relevant (system changed)
+- **Superseded:** Replaced by a newer ADR
+
+## Good ADR Examples
+
+### Example: Database Choice
+
+```markdown
+# ADR-001: Use PostgreSQL as Primary Database
+
+**Status:** Accepted
+**Date:** 2026-01-15
+**Deciders:** Tech Lead, Architect
+
+## Context
+
+We need a primary database for the marketplace system.
+Requirements:
+- ACID transactions for orders
+- Complex queries for product search
+- JSON support for flexible attributes
+- Proven reliability at scale
+
+## Decision
+
+Use PostgreSQL 17+ with AWS RDS.
+
+## Consequences
+
+### Positive
+- Strong ACID guarantees
+- Excellent JSON/JSONB support
+- GIN indexes for full-text search
+- Team expertise exists
+
+### Negative
+- Requires careful schema design
+- Scaling writes is harder than NoSQL
+- AWS RDS costs
+
+## Alternatives Considered
+
+### MySQL
+- Pros: Simpler, cheaper
+- Cons: Weaker JSON support, fewer features
+- Rejected: JSON operations are critical for us
+
+### MongoDB
+- Pros: Flexible schema, easy scaling
+- Cons: No ACID across documents, eventual consistency
+- Rejected: Need strong consistency for orders
+```
+
+### Example: Integration Pattern
+
+```markdown
+# ADR-002: Event-Driven Integration Between Modules
+
+**Status:** Accepted
+**Date:** 2026-01-16
+**Deciders:** Architect, Tech Lead
+
+## Context
+
+Modules need to communicate. Options:
+1. Direct API calls (synchronous)
+2. Event-driven (asynchronous)
+3. Shared database (anti-pattern)
+
+## Decision
+
+Use Kafka for event-driven integration between modules.
+Modules publish domain events, others subscribe.
+
+## Consequences
+
+### Positive
+- Loose coupling between modules
+- Better scalability
+- Natural audit trail
+- Resilient to failures
+
+### Negative
+- Eventual consistency complexity
+- Need idempotent consumers
+- Additional infrastructure (Kafka)
+- Harder to debug
+
+## Alternatives Considered
+
+### Direct HTTP Calls
+- Rejected: Creates tight coupling, cascading failures
+```
+
+## Directory Structure
+
+```
+docs/architecture/adr/
+├── ADR-001-use-postgresql.md
+├── ADR-002-event-driven-integration.md
+├── ADR-003-modular-monolith.md
+├── ADR-004-hexagonal-architecture.md
+└── README.md  # Index of all ADRs
+```
+
+## ADR Index (README.md)
+
+```markdown
+# Architecture Decision Records
+
+| ADR | Title | Status | Date |
+|-----|-------|--------|------|
+| [ADR-001](ADR-001-use-postgresql.md) | Use PostgreSQL | Accepted | 2026-01-15 |
+| [ADR-002](ADR-002-event-driven-integration.md) | Event-driven integration | Accepted | 2026-01-16 |
+| [ADR-003](ADR-003-modular-monolith.md) | Modular monolith | Accepted | 2026-01-17 |
+```
+
+## Quality Checklist
+
+Before finalizing ADR:
+- [ ] Context explains the problem clearly
+- [ ] Decision is stated unambiguously
+- [ ] Consequences include both positive and negative
+- [ ] At least 2 alternatives were considered
+- [ ] Alternatives explain why they were rejected
+- [ ] Status is set correctly
+- [ ] Date and deciders are recorded
+
+## Output
+
+Save to: `docs/architecture/adr/ADR-NNN-description.md`
+Update: `docs/architecture/adr/README.md` (index)
+
+## Related Skills
+
+- `architecture-design` - For overall architecture
+- `architecture-validation` - For validating ADRs exist

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

@@ -0,0 +1,183 @@
+---
+name: architecture-design
+description: How to design system architecture following hexagonal/DDD patterns with proper module boundaries
+license: MIT
+compatibility: opencode
+metadata:
+  domain: software-architecture
+  patterns: hexagonal, ddd, modular-monolith
+  artifacts: docs/architecture.md
+---
+
+# Architecture Design Skill
+
+## When to Use
+
+Use this skill when you need to:
+- Design new system architecture
+- Define module/service boundaries
+- Create data ownership model
+- Design integration points
+- Document architectural decisions
+
+## Reference
+
+Always check project standards: `@CLAUDE.md`
+
+## Template
+
+Use template at: `@.opencode/templates/architecture-template.md`
+
+## Architecture Principles
+
+### 1. Hexagonal Architecture (Ports & Adapters)
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Infrastructure                     │
+│  ┌───────────────────────────────────────────────┐  │
+│  │                  Application                   │  │
+│  │  ┌─────────────────────────────────────────┐  │  │
+│  │  │                 Domain                   │  │  │
+│  │  │  (Business Logic - NO dependencies!)     │  │  │
+│  │  └─────────────────────────────────────────┘  │  │
+│  │           Use Cases (Orchestration)           │  │
+│  └───────────────────────────────────────────────┘  │
+│        Adapters (HTTP, DB, Kafka, External)         │
+└─────────────────────────────────────────────────────┘
+
+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
+
+Each module must have:
+- **Single responsibility** - One business capability
+- **Explicit data ownership** - Clear which entities it owns
+- **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
+```
+
+### 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
+```
+
+### 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
+
+Before completing:
+- [ ] All PRD functional areas have architectural home
+- [ ] All NFRs have concrete architectural support
+- [ ] Module boundaries are clear
+- [ ] Data ownership is explicit (each entity has ONE owner)
+- [ ] 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
+
+## Output
+
+Save to: `docs/architecture.md`
+
+## Related Skills
+
+- `adr-writing` - For architecture decisions
+- `data-modeling` - For database design
+- `api-design` - For REST API contracts
+- `event-design` - For Kafka event schemas
+- `architecture-validation` - For validation