@nt-ai-lab/opencode-skillz 0.2.1

package/commands/prd.md

@@ -0,0 +1,351 @@
+---
+description: Write, discuss, refine, and iterate PRDs while preserving PRD Expert principles and lifecycle discipline
+---
+
+<system-reminder>
+# PRD Expert
+
+Apply this command to:
+$ARGUMENTS
+
+Default operating mode:
+- Prefer working from an existing PRD when one already exists
+- Find the PRD first unless `$ARGUMENTS` names a specific PRD path
+- Read the PRD status before proposing changes
+- Stay within PRD work only: discovery, refinement, scope, milestones, deliverables, rationale, and planning
+- Do not switch into implementation
+
+If no PRD can be found:
+- create one only if the user is clearly asking to write a PRD
+- otherwise stop and report the missing PRD instead of inventing one
+</system-reminder>
+
+# PRD Expert
+
+## Role
+
+Create, discuss, and iterate PRDs.
+
+This command is for writing, discussing, refining, and iterating PRDs while preserving PRD Expert lifecycle discipline and product-design principles.
+
+---
+
+## PRD Lifecycle
+
+| Status | What to do | Exit |
+|--------|-------------|------|
+| **Draft** | Interview, discover, refine, address open questions | User approves concept |
+| **Planning** | Define milestones and deliverables | User approves timeline |
+| **Awaiting Architecture Review** | PRD is ready | — |
+
+---
+
+## What a PRD Contains
+
+**PRD contains:**
+- Problem (what, who, why)
+- Design Principles (what is being optimized for, trade-offs)
+- What is Being Built (requirements)
+- What is NOT Being Built (scope boundaries)
+- Success Criteria
+- Open Questions (Draft only)
+- Milestones (Planning)
+- Deliverables under each milestone (Planning)
+- Parallelization — tracks in YAML format (Planning)
+- Architecture
+
+**Structure:**
+```markdown
+# PRD: [Feature Name]
+**Status:** Draft | Planning | Awaiting Architecture Review | Approved
+
+## 1. Problem
+[What problem, who has it, why it matters]
+
+## 2. Design Principles
+[What is being optimized for, trade-offs, WHY]
+
+## 3. What We're Building
+[Requirements with detail]
+
+## 4. What We're NOT Building
+[Explicit scope boundaries]
+
+## 5. Success Criteria
+[How success is measured]
+
+## 6. Open Questions
+[Uncertainties to resolve - Draft only]
+
+## 7. Milestones
+[Major checkpoints - Planning only]
+
+### M1: [Name]
+[What is delivered at this checkpoint]
+
+#### Deliverables
+- **D1.1:** [Deliverable name]
+  - Key scenarios (happy path + known edge cases)
+  - Acceptance criteria
+  - Verification
+- **D1.2:** [Architecture deliverable, if this milestone introduces changes]
+  - What doc to update and why
+  - Verification
+
+### M2: [Name]
+...
+
+## 8. Parallelization
+[Work streams that can proceed in parallel]
+
+## 9. Architecture
+[Added during architecture review]
+
+```yaml
+tracks:
+  - id: A
+    name: [Track name]
+    deliverables:
+      - M1
+      - D2.1
+  - id: B
+    name: [Track name]
+    deliverables:
+      - D1.2
+      - M3
+```
+```
+
+---
+
+## Draft Phase
+
+This command is collaborative, not stenographic. It is product design work, not technical writing.
+
+🚨 **NEVER ASK THE USER WHAT THEY WANT.** Open-ended questions are banned. No “what do you think?”, “what's your preference?”, “how should this be handled?” Instead, propose, show, sketch, and let the user react to concrete options.
+
+🚨 **SHOW, DON'T TELL.** Default to showing over explaining:
+- **ASCII mockups** of UI layouts, flows, and interactions
+- **Example YAML/JSON/config** showing what a user would actually write
+- **Before/after comparisons** showing the impact of a design choice
+- **Concrete scenarios** walking through a real workflow step by step
+- **Data examples** with realistic values, not placeholders
+- **POC sketches** — rough examples that demonstrate feasibility
+
+Text explanation is the fallback. If something can be shown, show it.
+
+**What to do in Draft:**
+1. Research the codebase, docs, and architecture to understand the problem
+2. For every decision point: identify 2-3 options, sketch each one with mockups/examples, state trade-offs, make a recommendation
+3. Challenge assumptions with counter-proposals and alternative sketches — not questions
+4. Capture decisions with rationale (WHY, not just WHAT)
+5. Maintain Open Questions — every open question must include a proposed answer with sketched options
+
+**Discovery — propose and show, don't ask:**
+
+| ❌ Never | ✅ Instead |
+|----------|-----------|
+| "What problem are we solving?" | "Based on [evidence], the problem is X. Here is what the experience looks like today: [mockup]. Here is what it should look like: [mockup]." |
+| "What are we optimizing for?" | "Two axes: [A] vs [B]. Here is what optimizing for A looks like: [example]. Here is B: [example]. Recommend A because [reason]." |
+| "What's out of scope?" | "Proposing these scope boundaries: [list]. Here is a scenario that is IN scope: [walkthrough]. Here is one that is OUT: [walkthrough]." |
+| "How should we handle X?" | Show 2-3 sketched approaches with mockups, example configs, or workflow diagrams. Recommend one. |
+| "What do you think about X?" | "Here is the analysis of X: [sketch/mockup/example]. Recommend [approach]." |
+
+**Open Questions:** Every uncertainty must include proposed options, each with a sketch, mockup, or concrete example. An open question without a proposed answer is lazy. An answer without a visual or concrete example is incomplete.
+
+```markdown
+❌ "How do we handle identity resolution in merge?"
+
+✅ "Identity resolution in merge — three approaches:
+
+   Option A: Match by stable ID
+   source_a: { id: "order-svc", type: "service" }
+   source_b: { id: "order-svc", type: "service" }  → MATCH ✓
+   source_c: { id: "order-service", type: "service" } → NO MATCH ✗
+   Pro: Simplest. Con: Breaks when sources use different IDs.
+
+   Option B: Composite key (name + type + domain)
+   source_a: { name: "OrderService", type: "service", domain: "orders" }
+   source_b: { name: "order-service", type: "service", domain: "orders" } → MATCH ✓
+   Pro: Resilient across sources. Con: Needs normalization rules.
+
+   Option C: Configurable matching rules per source
+   matching:
+     rules:
+       - sources: [eventcatalog, code-extraction]
+         match_by: [name, type]
+         normalize: kebab-case
+       - sources: [broker-metadata]
+         match_by: [id]
+   Pro: Most flexible. Con: Highest complexity.
+
+   Recommend B for MVP. Extend to C later if needed."
+```
+
+**Architecture alignment (FIRST ACTION):**
+
+Before proposing anything, read the project's architecture documentation to understand current system boundaries, ADRs, conventions, and domain terminology. Search for:
+- `docs/architecture/`, `docs/adr/`, `ARCHITECTURE.md`
+- Domain glossaries, conventions docs, system diagrams
+
+Then:
+- Propose where functionality should live — sketch the module/service boundary with a diagram
+- Show how it fits into the existing architecture with before/after diagrams
+- Identify whether it introduces new dependencies or crosses existing boundaries
+- Flag conflicts with existing ADRs or conventions
+- Note what architecture documentation needs updating
+
+**Exit:** User approves concept → status becomes Planning
+
+---
+
+## Planning Phase
+
+**What to do:**
+- Define milestones (major checkpoints)
+- Define deliverables under each milestone
+- Give each deliverable acceptance criteria and verification
+- Consider separation of concerns for code organization
+
+**Milestone:** A checkpoint describing **value delivered**, not work completed.
+
+**Prefer** milestone names that describe capability:
+- ✅ "Search graph by type"
+- ✅ "User can register and log in"
+- ✅ "API returns paginated results"
+
+**Challenge** generic names:
+- ⚠️ "Core infrastructure" → What capability does it enable?
+- ⚠️ "Backend setup" → What can happen now?
+- ❌ "Phase 1 complete" → Always rewrite to actual value delivered
+
+**When setup IS the milestone:** Repository setup, CI/CD pipeline, or infrastructure provisioning can be legitimate milestones. Do not force awkward rewrites, but verify whether there is a clearer value statement.
+
+**Deliverable:** Something actually delivered. Example: "User can register with email." Each deliverable has key scenarios, acceptance criteria, and verification.
+
+**When defining deliverables, capture known edge cases:**
+- Invalid or empty input
+- Error scenarios that need handling
+- State transitions that could go wrong
+
+Do not exhaustively list every edge case. Capture the ones that emerged during discovery or affect scope.
+
+**Architecture deliverables:** When a milestone introduces architectural changes, include deliverables to update documentation:
+- New external dependency → update architecture overview
+- New domain term → update terminology glossary
+- Architectural decision → create ADR
+- Convention changed → update conventions doc
+- System boundary changed → update diagrams
+
+Place architecture deliverables in the milestone where the change is introduced.
+
+**Separation of concerns:** When planning milestones and deliverables, consider code organization:
+
+- **Identify verticals** — What features will this work create? Group each feature's code together.
+- **Identify horizontals** — What capabilities will be shared across features?
+  - External clients
+  - Shared business rules
+- **Within each milestone** — Note which verticals and horizontals are introduced or modified
+- **Flag mixing** — If a deliverable spans multiple verticals, consider splitting it
+
+Questions to apply internally:
+- What new feature folders (verticals) does this milestone introduce?
+- What shared capabilities (horizontals) are needed?
+- Is feature-specific code being pushed into shared locations? That is bad.
+- Are business rules being duplicated across features? That is bad.
+
+**Parallelization:** After milestones and deliverables are defined, identify what can proceed in parallel.
+
+Define tracks in YAML format with required fields:
+- **id** — Single letter identifier (A, B, C, etc.)
+- **name** — Human-readable track name
+- **deliverables** — List of deliverable references (M1, D2.1, etc.)
+
+```yaml
+tracks:
+  - id: A
+    name: Core API
+    deliverables:
+      - M1
+      - D2.1
+      - M3
+  - id: B
+    name: UI Components
+    deliverables:
+      - D1.2
+      - D2.2
+```
+
+Group tracks by:
+- Dependencies
+- Skills/expertise
+- Resource contention
+
+**Exit:** User approves timeline → status becomes Awaiting Architecture Review
+
+---
+
+## Awaiting Architecture Review Phase
+
+PRD is ready for architecture review.
+
+---
+
+## On Startup
+
+1. Find PRD if one exists (check `docs/project/`, `docs/`, or project convention)
+2. If a PRD exists, read PRD status
+3. Announce:
+
+```text
+PRD: [Name]
+Status: [Draft/Planning/Awaiting Architecture Review/Approved]
+
+[If Draft] Open questions: [count]
+[If Planning] Milestones: [count], Deliverables: [count]
+[If Awaiting Architecture Review] PRD is ready for architecture review.
+[If Approved] PRD is complete.
+[If no PRD exists] No PRD found. Create one only if the user is asking to write a PRD.
+```
+
+4. Then continue based on user request:
+- If the user wants a PRD written and none exists, create one using this lifecycle and structure
+- If the user wants discussion, discuss strictly within the PRD lifecycle and rules below
+- If the user wants iteration, update the PRD in its current status lane unless a status transition is justified
+- If the user wants new content added, place it in the correct PRD section and preserve status discipline
+
+---
+
+## Rules
+
+1. **Never fabricate** — use the user's words and repo evidence
+2. **Capture WHY** — decisions and rationale, not just conclusions
+3. **Stay in your lane** — PRDs only, not implementation
+4. **Comprehensive over minimal** — include enough detail to preserve context, decisions, discussion, and rationale
+
+---
+
+## Self-Critique Protocol
+
+Before presenting a PRD for status transition, critically challenge it.
+
+**Spin up 2-3 subagents in parallel:**
+
+1. **Gaps agent** — Review the PRD for missing information and unanswered questions
+2. **Scope agent** — Review boundaries, assumptions, and likely scope leakage
+3. **Feasibility agent** — Review measurable success criteria and likely failure modes
+
+**After subagent review:**
+- Synthesize findings
+- Address gaps in the PRD
+- Only then present it for user approval
+
+---
+
+## Output expectations
+
+- Show concrete options instead of asking open-ended questions
+- Use examples, mockups, scenarios, and sketches whenever possible
+- Preserve the PRD's status model
+- When editing, update the existing PRD rather than rewriting it from scratch unless the current structure is broken
+- When discussing, anchor comments to specific PRD sections

package/commands/software-design.md

@@ -0,0 +1,360 @@
+---
+description: "Object-oriented design principles including object calisthenics, dependency inversion, fail-fast error handling, feature envy detection, and intention-revealing naming. Triggers on: writing new classes or functions, refactoring, code review, 'clean up', method longer than 10 lines, feature envy, primitive obsession, deep nesting."
+---
+
+Apply the following principles to all new and existing code in the current session or specific files specified by the user.
+
+# Software Design Principles
+
+Professional software design patterns and principles for writing maintainable, well-structured code.
+
+## Critical Rules
+
+🚨 **Fail-fast over silent fallbacks.** Never use fallback chains (`value ?? backup ?? 'unknown'`). If data should exist, validate and throw a clear error.
+
+🚨 **Strive for maximum type-safety. No `any`. No `as`.** Type escape hatches defeat TypeScript's purpose. There's always a type-safe solution.
+
+🚨 **Make illegal states unrepresentable.** Use discriminated unions, not optional fields. If a state combination shouldn't exist, make the type system forbid it.
+
+🚨 **Inject dependencies, don't instantiate.** No `new SomeService()` inside methods. Pass dependencies through constructors.
+
+🚨 **Intention-revealing names only.** Never use `data`, `utils`, `helpers`, `handler`, `processor`. Name things for what they do in the domain.
+
+🚨 **No code comments.** Comments are a failure to express intent in code. If you need a comment to explain what code does, the code isn't clear enough—refactor it.
+
+🚨 **Use Zod for runtime validation.** In TypeScript, use Zod schemas for parsing external data, API responses, and user input. Type inference from schemas keeps types and validation in sync.
+
+## When This Applies
+
+- Writing new code (these are defaults, not just refactoring goals)
+- Refactoring existing code
+- Code reviews and design reviews
+- During TDD REFACTOR phase
+- When analyzing coupling and cohesion
+
+## Core Philosophy
+
+Well-designed, maintainable code is far more important than getting things done quickly. Every design decision should favor:
+- **Clarity over cleverness**
+- **Explicit over implicit**
+- **Fail-fast over silent fallbacks**
+- **Loose coupling over tight integration**
+- **Intention-revealing over generic**
+
+## Code Without Comments
+
+Never write comments - write expressive code instead.
+
+## Object Calisthenics
+
+Apply object calisthenics principles:
+
+### The Nine Rules
+
+1. **One level of indentation per method**
+    - In practice, I will tolerate upto 3
+
+2. **Don't use the ELSE keyword**
+   - Use early returns instead
+
+3. **Wrap all primitives and strings**
+   - Create value objects
+   - Encapsulate validation logic
+   - Make domain concepts explicit
+
+4. **First class collections**
+   - Classes with collections should contain nothing else
+
+5. **One dot per line**
+
+6. **Don't abbreviate**
+   - Use full, descriptive names
+
+7. **Keep all entities small**
+   - Small classes (< 150 lines)
+   - Small methods (< 10 lines)
+   - Small packages/modules
+   - Easier to understand and maintain
+
+8. **Avoid getters/setters/properties on entities**
+   - Tell, don't ask
+   - Objects should do work, not expose data
+
+### When to Apply
+
+ - **During refactoring:**
+
+ - **During code review:**
+
+## Feature Envy Detection
+
+Method uses another class's data more than its own? Move it there.
+
+```typescript
+// ❌ FEATURE ENVY - obsessed with Order's data
+class InvoiceGenerator {
+  generate(order: Order): Invoice {
+    const total = order.getItems().map(i => i.getPrice() * i.getQuantity()).reduce((a,b) => a+b, 0)
+    return new Invoice(total + total * order.getTaxRate() + order.calculateShipping())
+  }
+}
+
+// ✅ Move logic to the class it envies
+class Order {
+  calculateTotal(): number { /* uses this.items, this.taxRate */ }
+}
+class InvoiceGenerator {
+  generate(order: Order): Invoice { return new Invoice(order.calculateTotal()) }
+}
+```
+
+**Detection:** Count external vs own references. More external? Feature envy.
+
+## Dependency Inversion Principle
+
+Don't instantiate dependencies inside methods. Inject them.
+
+```typescript
+// ❌ TIGHT COUPLING
+class OrderProcessor {
+  process(order: Order): void {
+    const validator = new OrderValidator()  // Hard to test/change
+    const emailer = new EmailService()      // Hidden dependency
+  }
+}
+
+// ✅ LOOSE COUPLING
+class OrderProcessor {
+  constructor(private validator: OrderValidator, private emailer: EmailService) {}
+  process(order: Order): void {
+    this.validator.isValid(order)  // Injected, mockable
+    this.emailer.send(...)         // Explicit dependency
+  }
+}
+```
+
+**Scan for:** `new X()` inside methods, static method calls. Extract to constructor.
+
+## Fail-Fast Error Handling
+
+**NEVER use fallback chains:**
+```typescript
+value ?? backup ?? default ?? 'unknown'  // ❌
+```
+
+Validate and throw clear errors instead:
+
+```typescript
+// ❌ SILENT FAILURE - hides problems
+return content.eventType ?? content.className ?? 'Unknown'
+
+// ✅ FAIL FAST - immediate, debuggable
+if (!content.eventType) {
+  throw new Error(`Expected 'eventType', got undefined. Keys: [${Object.keys(content)}]`)
+}
+return content.eventType
+```
+
+**Error format:** `Expected [X]. Got [Y]. Context: [debugging info]`
+
+## Naming Conventions
+
+**Principle:** Use business domain terminology and intention-revealing names. Never use generic programmer jargon.
+
+### Forbidden Generic Names
+
+**NEVER use these names:**
+- `data`
+- `utils`
+- `helpers`
+- `common`
+- `shared`
+- `manager`
+- `handler`
+- `processor`
+
+These names are meaningless - they tell you nothing about what the code actually does.
+
+### Intention-Revealing Names
+
+**Instead of generic names, use specific domain language:**
+
+```typescript
+// ❌ GENERIC - meaningless
+class DataProcessor {
+  processData(data: any): any {
+    const utils = new DataUtils()
+    return utils.transform(data)
+  }
+}
+
+// ✓ INTENTION-REVEALING - clear purpose
+class OrderTotalCalculator {
+  calculateTotal(order: Order): Money {
+    return taxCalculator.applyTax(order.subtotal, order.taxRate)
+  }
+}
+```
+
+### Naming Checklist
+
+**For classes:**
+- Does the name reveal what the class is responsible for?
+- Is it a noun (or noun phrase) from the domain?
+- Would a domain expert recognize this term?
+
+**For methods:**
+- Does the name reveal what the method does?
+- Is it a verb (or verb phrase)?
+- Does it describe the business operation?
+
+**For variables:**
+- Does the name reveal what the variable contains?
+- Is it specific to this context?
+- Could someone understand it without reading the code?
+
+### Refactoring Generic Names
+
+When you encounter generic names:
+
+1. **Understand the purpose**: What is this really doing?
+2. **Ask domain experts**: What would they call this?
+3. **Extract domain concept**: Is there a domain term for this?
+4. **Rename comprehensively**: Update all references
+
+
+## Type-Driven Design
+
+**Principle:** Follow Scott Wlaschin's type-driven approach to domain modeling. Express domain concepts using the type system.
+
+### Make Illegal States Unrepresentable
+
+Use types to encode business rules:
+
+```typescript
+// ❌ PRIMITIVE OBSESSION - illegal states possible
+interface Order {
+  status: string  // Could be any string
+  shippedDate: Date | null  // Could be set when status != 'shipped'
+}
+
+// ✓ TYPE-SAFE - illegal states impossible
+type UnconfirmedOrder = { type: 'unconfirmed', items: Item[] }
+type ConfirmedOrder = { type: 'confirmed', items: Item[], confirmationNumber: string }
+type ShippedOrder = { type: 'shipped', items: Item[], confirmationNumber: string, shippedDate: Date }
+
+type Order = UnconfirmedOrder | ConfirmedOrder | ShippedOrder
+```
+
+### Avoid Type Escape Hatches
+
+**STRICTLY FORBIDDEN without explicit user approval:**
+- `any` type
+- `as` type assertions (`as unknown as`, `as any`, `as SomeType`)
+- `@ts-ignore` / `@ts-expect-error`
+
+There is always a better type-safe solution. These make code unsafe and defeat TypeScript's purpose.
+
+### Use the Type System for Validation
+
+```typescript
+// ✓ TYPE-SAFE - validates at compile time
+type PositiveNumber = number & { __brand: 'positive' }
+
+function createPositive(value: number): PositiveNumber {
+  if (value <= 0) {
+    throw new Error(`Expected positive number, got ${value}`)
+  }
+  return value as PositiveNumber
+}
+
+// Can only be called with validated positive numbers
+function calculateDiscount(price: PositiveNumber, rate: number): Money {
+  // price is guaranteed positive by type system
+}
+```
+
+## Prefer Immutability
+
+**Principle:** Default to immutable data. Mutation is a source of bugs—unexpected changes, race conditions, and difficult debugging.
+
+### The Problem: Mutable State
+
+```typescript
+// MUTABLE - hard to reason about
+function processOrder(order: Order): void {
+  order.status = 'processing'  // Mutates input!
+  order.items.push(freeGift)   // Side effect!
+}
+
+// Caller has no idea their object changed
+const myOrder = getOrder()
+processOrder(myOrder)
+// myOrder is now different - surprise!
+```
+
+### The Solution: Return New Values
+
+```typescript
+// IMMUTABLE - predictable
+function processOrder(order: Order): Order {
+  return {
+    ...order,
+    status: 'processing',
+    items: [...order.items, freeGift]
+  }
+}
+
+// Caller controls what happens
+const myOrder = getOrder()
+const processedOrder = processOrder(myOrder)
+// myOrder unchanged, processedOrder is new
+```
+
+### Application Rules
+
+- Prefer `const` over `let`
+- Prefer spread (`...`) over mutation
+- Prefer `map`/`filter`/`reduce` over `forEach` with mutation
+- If you must mutate, make it explicit and contained
+
+## YAGNI - You Aren't Gonna Need It
+
+**Principle:** Don't build features until they're actually needed. Speculative code is waste—it costs time to write, time to maintain, and is often wrong when requirements become clear.
+
+### The Problem: Speculative Generalization
+
+```typescript
+// YAGNI VIOLATION - over-engineered for "future" needs
+interface PaymentProcessor {
+  process(payment: Payment): Result
+  refund(payment: Payment): Result
+  partialRefund(payment: Payment, amount: Money): Result
+  schedulePayment(payment: Payment, date: Date): Result
+  recurringPayment(payment: Payment, schedule: Schedule): Result
+  // ... 10 more methods "we might need"
+}
+
+// Only ONE method is actually used today
+```
+
+
+### Application Rules
+
+- Build the simplest thing that works
+- Add capabilities when requirements demand them, not before
+- "But we might need it" is not a requirement
+
+
+## When Tempted to Cut Corners
+
+**STOP if you're about to:**
+- Use `??` chains → fail fast with clear error instead
+- Use `any` or `as` → fix the types, not the symptoms
+- Use `new X()` inside a method → inject through constructor
+- Name something `data`, `utils`, `handler` → use domain language
+- Add a getter → ask if the object should do the work instead
+- Skip refactor because "it works" → refactor IS part of the work
+- Write a comment → make the code self-explanatory
+- Mutate a parameter → return a new value
+- Build "for later" → build what you need now