super-opencode 1.1.2 → 1.2.0

package/.opencode/skills/decision-log/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: decision-log
+description: Architecture Decision Record (ADR) creation, tracking, and management for informed technical choices.
+---
+
+# Decision Log Skill
+
+## Purpose
+
+To transform **implicit decisions** into **explicit records**. This skill ensures every significant technical choice is documented with context, alternatives, and consequences—preventing "tribal knowledge" loss and enabling future maintainers to understand the "why" behind the "what."
+
+**ROI Metric**: Spending 10 minutes documenting a decision saves hours of debate and prevents costly reversals months later.
+
+## When to Use
+
+- **Trigger**: When `architect` recommends a technology, pattern, or structural change.
+- **Trigger**: When a decision has >1 viable alternative.
+- **Trigger**: When a decision is hard to reverse (high consequence).
+- **Trigger**: When `pm-agent` flags a decision as "architecturally significant."
+
+## The ADR Protocol (The 5-Step Process)
+
+### 1. Recognition (Is This Significant?)
+
+**Ask**: Does this decision impact any of the following?
+- Technology stack (language, framework, database)
+- Architecture style (microservices vs monolith, REST vs GraphQL)
+- Infrastructure (cloud provider, containerization, serverless)
+- Security model (auth strategy, encryption approach)
+- Data strategy (storage, caching, messaging)
+- Team workflow (CI/CD, branching strategy, code review)
+
+**If YES** → Create an ADR  
+**If NO** → Document briefly in code comments
+
+### 2. Context (Why Are We Doing This?)
+
+Document the forces at play:
+- Business requirements (scale, compliance, time-to-market)
+- Technical constraints (legacy systems, team expertise)
+- Quality attributes (performance, security, maintainability)
+
+### 3. Decision (What Did We Choose?)
+
+State the decision clearly:
+- Chosen option with version/variant
+- Configuration details
+- Scope (what's in, what's out)
+
+### 4. Alternatives (What Else Did We Consider?)
+
+Document at least 2-3 alternatives:
+- Option name and brief description
+- Pros and cons
+- Why it was rejected (be honest: "team familiarity," "cost," "risk")
+
+### 5. Consequences (What Happens Now?)
+
+List the implications:
+- **Positive**: Benefits we gain
+- **Negative**: Trade-offs we accept
+- **Neutral**: Changes to workflows or expectations
+- **Risks**: What could go wrong
+- **Migration**: Path from current state to new state
+
+## ADR Template
+
+```markdown
+# ADR-[NUMBER]: [Short Title]
+
+## Status
+- Proposed
+- Accepted
+- Deprecated (replaced by ADR-XXX)
+- Superseded by ADR-XXX
+
+## Context
+
+[The problem statement. What is the issue we're addressing? What forces are at play?]
+
+[Example: We need to choose a database for our user service. The service must handle 10k writes/second with ACID compliance. Team has Postgres expertise but limited NoSQL experience.]
+
+## Decision
+
+**We will use [TECHNOLOGY/Approach] version [X.Y]**
+
+[Clear, concise statement of the decision.]
+
+### Configuration
+- Setting A: Value
+- Setting B: Value
+
+### Scope
+- **In Scope**: User data, session storage
+- **Out of Scope**: Analytics data (see ADR-015)
+
+## Alternatives Considered
+
+### Option 1: [Name]
+[Description]
+
+**Pros:**
+- Benefit A
+- Benefit B
+
+**Cons:**
+- Drawback A
+- Drawback B
+
+**Decision**: Rejected because [specific reason].
+
+### Option 2: [Name]
+[Description]
+
+**Pros:**
+- Benefit A
+- Benefit B
+
+**Cons:**
+- Drawback A
+- Drawback B
+
+**Decision**: Rejected because [specific reason].
+
+### Option 3: Status Quo (Do Nothing)
+**Decision**: Rejected because [specific reason].
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative / Trade-offs
+- [Trade-off 1]
+- [Trade-off 2]
+
+### Neutral
+- [Change 1]
+
+### Risks
+- [Risk 1] → Mitigation: [strategy]
+- [Risk 2] → Mitigation: [strategy]
+
+### Migration Path
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Related Decisions
+- Relates to ADR-XXX
+- Depends on ADR-YYY
+- Supersedes ADR-ZZZ
+
+## Notes
+- **Decision Date**: YYYY-MM-DD
+- **Decision Makers**: [Name], [Name]
+- **Stakeholders Consulted**: [Team/Individual]
+```
+
+## Execution Template
+
+*Use this when documenting a decision.*
+
+```markdown
+## 📝 Decision Documentation
+
+### 1. Decision Summary
+- **Topic**: [What are we deciding?]
+- **Significance**: High/Medium/Low
+- **Reversibility**: Easy/Moderate/Difficult
+
+### 2. Context & Forces
+- Business driver: [What business need drives this?]
+- Technical driver: [What technical need drives this?]
+- Constraints: [Time, budget, expertise, legacy]
+
+### 3. Options Analysis
+
+| Option | Pros | Cons | Score (1-10) |
+|:-------|:-----|:-----|:------------:|
+| Option A | Fast, proven | Expensive | 7 |
+| Option B | Cheap, flexible | Unproven | 6 |
+| Option C | [Status Quo] | Technical debt | 4 |
+
+### 4. Recommendation
+**Chosen**: Option A  
+**Rationale**: Best balance of speed and reliability given Q2 deadline. Cost acceptable.
+
+### 5. ADR Status
+- [ ] Draft created
+- [ ] Reviewed by architect
+- [ ] Reviewed by team
+- [ ] Accepted
+- [ ] Documented in `docs/adr/`
+```
+
+## ADR Index Maintenance
+
+Maintain an index file for discoverability:
+
+```markdown
+# Architecture Decision Records
+
+## Active Decisions
+| ADR | Title | Date | Status |
+|:----|:------|:-----|:------:|
+| 001 | Use PostgreSQL for Core Data | 2026-01-15 | Accepted |
+| 002 | Adopt Next.js App Router | 2026-01-20 | Accepted |
+| 003 | Implement JWT Authentication | 2026-01-25 | Accepted |
+
+## Deprecated/Superseded
+| ADR | Title | Date | Status |
+|:----|:------|:-----|:------:|
+| 000 | Use MongoDB (pilot) | 2026-01-10 | Superseded by ADR-001 |
+```
+
+## Integration with Agents
+
+- **`architect`**: Primary user—creates ADRs for all architectural decisions.
+- **`pm-agent`**: Reviews ADRs for impact on timelines and resources.
+- **`backend` / `frontend`**: Reference ADRs when implementing to understand constraints.
+- **`writer`**: Updates ADRs with implementation details and outcomes.
+
+## Storage Location
+
+```
+docs/
+└── adr/
+    ├── README.md           # Index of all ADRs
+    ├── 001-use-postgres.md
+    ├── 002-nextjs-app-router.md
+    └── 003-jwt-auth.md
+```
+
+Or in `.opencode/memory/adr/` for agent-centric projects.

package/.opencode/skills/doc-sync/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: doc-sync
+description: Documentation synchronization with code to prevent drift and ensure accuracy.
+---
+
+# Doc Sync Skill
+
+## Purpose
+
+To prevent **documentation drift**—the silent killer of maintainability. This skill ensures documentation stays synchronized with code changes, catching discrepancies before they become "source of truth" conflicts.
+
+**ROI Metric**: Accurate docs reduce onboarding time by 50% and prevent costly misimplementations.
+
+## When to Use
+
+- **Trigger**: After any significant code change (new feature, API change, refactor).
+- **Trigger**: When `self-check` flags documentation in implementation reports.
+- **Trigger**: Before releases (ensures public docs are accurate).
+- **Trigger**: When onboarding new team members (docs are tested).
+- **Trigger**: When `pm-agent` schedules a "documentation audit."
+
+## The Doc Sync Protocol (The 4-Step Process)
+
+### 1. Discovery (What Docs Exist?)
+
+**Scan for documentation:**
+```
+docs/
+├── README.md              # Project overview
+├── api/                   # API documentation
+├── architecture/          # System design docs
+├── setup.md              # Developer onboarding
+├── deployment.md         # Deployment guide
+└── adr/                  # Architecture decisions
+
+README.md
+CONTRIBUTING.md
+AGENTS.md
+CHANGELOG.md
+```
+
+**Identify doc types:**
+- **API Docs**: OpenAPI/Swagger, README endpoints
+- **Architecture Docs**: Diagrams, system descriptions
+- **Setup Docs**: Installation, configuration
+- **ADR Docs**: Decision records
+- **Code Comments**: JSDoc, docstrings
+
+### 2. Extraction (What Does Code Say?)
+
+**Extract current state from code:**
+
+**API Contracts:**
+```typescript
+// From backend code
+@Post('/users')
+async createUser(@Body() dto: CreateUserDto) {
+  // Extract: POST /users accepts CreateUserDto
+}
+
+// From Zod schemas
+export const CreateUserSchema = z.object({
+  email: z.string().email(),  // Extract: email required, must be valid
+  name: z.string().min(2),     // Extract: name required, min 2 chars
+});
+```
+
+**Configuration:**
+```typescript
+// From config files
+export const config = {
+  database: {
+    host: process.env.DB_HOST,     // Extract: DB_HOST env var required
+    port: parseInt(process.env.DB_PORT || '5432'),  // Extract: DB_PORT optional, default 5432
+  }
+};
+```
+
+**Dependencies:**
+```json
+// From package.json
+{
+  "dependencies": {
+    "react": "^18.2.0",  // Extract: React 18 required
+    "next": "14.0.0"     // Extract: Next.js 14 required
+  }
+}
+```
+
+### 3. Comparison (Do They Match?)
+
+**Compare extracted code state with documented state:**
+
+| Source | Documented | Actual | Status |
+|:-------|:-----------|:-------|:-------|
+| API: POST /users | Accepts `name`, `email` | Accepts `name`, `email`, `role` | ⚠️ MISMATCH |
+| DB: Host | Required env var | Has default `localhost` | ⚠️ MISMATCH |
+| Node version | v16 required | v18 in Dockerfile | ⚠️ MISMATCH |
+| Dependency: React | v17 | v18 | ❌ OUTDATED |
+
+### 4. Synchronization (Update Docs)
+
+**Update strategies:**
+
+**A. Immediate Update**
+- Update docs as part of the same PR that changes code.
+- Include in Definition of Done: "Documentation updated."
+
+**B. Scheduled Sync**
+- Weekly/bi-weekly doc review sessions.
+- Batch update accumulated drift.
+
+**C. Release Gate**
+- Block releases if doc sync check fails.
+- Enforce accuracy before going public.
+
+## Doc Sync Checklist Template
+
+```markdown
+# Doc Sync Report: [Feature/Release]
+
+## Summary
+**Scope**: [What changed?]  
+**Date**: YYYY-MM-DD  
+**Sync Status**: ✅ In Sync | ⚠️ Minor Drift | ❌ Major Drift
+
+## Files Changed
+| File | Change Type | Docs Updated? |
+|:-----|:------------|:-------------:|
+| src/api/users.ts | New endpoint | ⬜ |
+| src/config/db.ts | New env var | ⬜ |
+| package.json | Dependency bump | ⬜ |
+
+## API Documentation Sync
+
+| Endpoint | Doc Location | Doc Status | Code Status | Match? |
+|:---------|:-------------|:-----------|:------------|:------:|
+| POST /users | docs/api/users.md | v1.0 | v1.1 (added role) | ❌ |
+| GET /users/:id | docs/api/users.md | v1.0 | v1.0 | ✅ |
+
+### Required Updates
+- [ ] Add `role` parameter to POST /users documentation
+- [ ] Update example request/response
+- [ ] Add validation rules for role field
+
+## Environment Variables Sync
+
+| Variable | Doc Location | Doc Status | Code Status | Match? |
+|:---------|:-------------|:-----------|:------------|:------:|
+| DB_HOST | README.md | Required | Required | ✅ |
+| DB_PORT | README.md | Not documented | Optional (5432) | ⚠️ |
+| REDIS_URL | README.md | Required | Optional | ❌ |
+
+### Required Updates
+- [ ] Document DB_PORT as optional with default
+- [ ] Update REDIS_URL from required to optional
+
+## Dependencies Sync
+
+| Dependency | Doc Location | Doc Version | Actual Version | Match? |
+|:-----------|:-------------|:------------|:---------------|:------:|
+| Node.js | README.md | v16.x | v18.x | ❌ |
+| React | README.md | v17.x | v18.2.x | ❌ |
+| PostgreSQL | README.md | v13 | v15 | ⚠️ |
+
+### Required Updates
+- [ ] Update Node.js requirement to v18
+- [ ] Update React requirement to v18
+- [ ] Verify PostgreSQL compatibility doc
+
+## Architecture Docs Sync
+
+| Component | Doc Location | Doc Status | Code Status | Match? |
+|:----------|:-------------|:-----------|:------------|:------:|
+| Auth Service | docs/arch/auth.md | JWT | JWT + OAuth | ⚠️ |
+| Database Schema | docs/arch/db.md | v1 | v2 (added orders) | ❌ |
+
+### Required Updates
+- [ ] Add OAuth flow to auth documentation
+- [ ] Update database schema diagram
+- [ ] Document orders table
+
+## Action Items
+
+### Immediate (Block Release)
+- [ ] Update POST /users API docs
+- [ ] Correct Node.js version requirement
+
+### This Week
+- [ ] Document missing env vars
+- [ ] Update architecture diagram
+
+### Next Sprint
+- [ ] Full dependency audit
+- [ ] Review all code comments
+
+## Verification
+- [ ] All API examples tested and working
+- [ ] Setup instructions verified on clean machine
+- [ ] Architecture diagrams match current system
+- [ ] Code comments are accurate
+```
+
+## Execution Template
+
+*Use this during code review or before release.*
+
+```markdown
+## 🔄 Doc Sync Check: [PR/Release Name]
+
+### 1. Code Changes
+| File | Lines Changed | Doc Impact |
+|:-----|:-------------:|:-----------|
+| api/auth.ts | +45, -12 | Authentication flow |
+| config/app.ts | +8, -2 | New env var |
+| types/user.ts | +23, -0 | User fields |
+
+### 2. Extracted Code State
+**API Changes:**
+- New endpoint: `POST /auth/refresh` (added in auth.ts:67)
+- New field: `User.lastLoginAt` (added in types/user.ts:12)
+
+**Config Changes:**
+- New env: `JWT_REFRESH_SECRET` (added in config/app.ts:23)
+
+### 3. Documentation Audit
+
+| Doc File | Section | Needs Update? | Action |
+|:---------|:--------|:-------------:|:-------|
+| docs/api/auth.md | Endpoints | ✅ Yes | Add refresh endpoint |
+| docs/api/auth.md | Examples | ✅ Yes | Add refresh example |
+| README.md | Env Vars | ✅ Yes | Add JWT_REFRESH_SECRET |
+| docs/models/user.md | Schema | ✅ Yes | Add lastLoginAt field |
+
+### 4. Sync Plan
+**This PR:**
+- [ ] Update docs/api/auth.md
+- [ ] Update README.md
+- [ ] Update docs/models/user.md
+
+**Estimated Time**: 30 minutes
+
+### 5. Definition of Done
+- [ ] All code changes reflected in docs
+- [ ] Examples tested and working
+- [ ] Doc review completed
+```
+
+## Automation Strategies
+
+### A. CI/CD Integration
+```yaml
+# .github/workflows/doc-sync.yml
+name: Documentation Sync Check
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'docs/**'
+
+jobs:
+  doc-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Check API Docs
+        run: |
+          # Extract API routes from code
+          npm run extract-api > api-current.json
+          # Compare with documented API
+          npm run verify-docs api-current.json docs/api/
+          
+      - name: Check Type Definitions
+        run: |
+          # Verify TypeScript types match documented types
+          npm run verify-types
+```
+
+### B. Pre-Commit Hooks
+```bash
+# .husky/pre-commit
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+# If API files changed, remind to update docs
+if git diff --cached --name-only | grep -q "src/api/"; then
+  echo "⚠️  API files changed. Did you update the documentation?"
+fi
+```
+
+### C. Living Documentation
+Generate docs from code automatically:
+```typescript
+// Use tools like:
+// - TypeDoc for TypeScript
+// - JSDoc for JavaScript
+// - Swagger/OpenAPI from code annotations
+// - MkDocs with code extraction plugins
+```
+
+## Integration with Agents
+
+- **`backend`**: Updates API docs when endpoints change.
+- **`frontend`**: Updates component docs when props change.
+- **`architect`**: Updates architecture docs when system changes.
+- **`writer`**: Reviews and polishes documentation.
+- **`pm-agent`**: Schedules doc sync audits, tracks completion.
+
+## Common Doc Drift Scenarios
+
+### Scenario 1: API Evolution
+```
+Week 1: API accepts { name, email }
+Week 4: Code adds optional `role` field
+Week 8: Client tries to use `role` from outdated docs → Error
+```
+**Fix**: Update API docs same week role is added.
+
+### Scenario 2: Environment Changes
+```
+Original: DB_HOST required, DB_PORT defaults to 5432
+Docs say: Both DB_HOST and DB_PORT are required
+Result: Developer confusion, wasted time
+```
+**Fix**: Sync env var docs with actual config.
+
+### Scenario 3: Dependency Updates
+```
+Docs say: Requires Node.js 16
+Dockerfile: Uses Node.js 18
+CI/CD: Uses Node.js 18
+New dev: Installs Node 16, gets deprecation warnings
+```
+**Fix**: Update all version references together.
+
+## Success Metrics
+
+- **Doc Accuracy Score**: % of documented items that match code
+- **Time to Onboard**: How long for new dev to get running
+- **Support Tickets**: % related to doc confusion
+- **API Error Rate**: % due to clients following outdated docs
+
+Target: 95%+ doc accuracy, <1 day onboarding time.