opencodekit 0.20.6 → 0.20.8

package/dist/template/.opencode/skill/api-and-interface-design/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: api-and-interface-design
+description: Use when designing REST/GraphQL APIs, SDK interfaces, or public module boundaries — covers contract-first design, versioning, error shapes, and backward compatibility
+version: 1.0.0
+tags: [architecture, code-quality]
+dependencies: []
+---
+
+# API & Interface Design
+
+> **Replaces** ad-hoc API creation where endpoints, error shapes, and versioning are afterthoughts
+
+## When to Use
+
+- Designing a new API endpoint, SDK method, or public module interface
+- Reviewing or extending an existing API for backward compatibility
+- Defining error responses, pagination, or authentication contracts
+
+## When NOT to Use
+
+- Internal-only helper functions that no external code calls
+- Prototyping where the API shape will change frequently (use after stabilization)
+
+## Overview
+
+APIs are contracts. Once published, they're hard to change without breaking consumers. Design the contract first, implement second.
+
+**Core principle:** Define the contract (types, errors, versioning) before writing implementation. Make breaking changes impossible through careful interface design.
+
+## Contract-First Process
+
+```
+1. DEFINE  — Write TypeScript types / OpenAPI schema for request & response
+2. REVIEW  — Check backward compatibility, error coverage, naming consistency
+3. IMPLEMENT — Code against the contract, not the other way around
+4. VERIFY  — Validate implementation matches contract exactly
+```
+
+## API Design Checklist
+
+### Naming
+
+- [ ] Resource-oriented URLs (nouns, not verbs): `/users/{id}` not `/getUser`
+- [ ] Consistent casing (camelCase for JSON fields, kebab-case for URLs)
+- [ ] Plural collection names: `/users` not `/user`
+- [ ] Avoid abbreviations — `configuration` not `config` in public APIs
+
+### Request Design
+
+- [ ] Use appropriate HTTP methods (GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes)
+- [ ] Validate all input with schemas (zod, JSON Schema) at the boundary
+- [ ] Accept only what you need — reject unknown fields
+- [ ] Use query params for filtering/pagination, body for creation/mutation
+
+### Response Design
+
+- [ ] Consistent envelope: `{ data, error, meta }` or flat depending on convention
+- [ ] Include pagination metadata: `{ total, page, pageSize, hasMore }`
+- [ ] Return created/updated resource in mutation responses
+- [ ] Use ISO 8601 for dates, UTC always
+
+### Error Design
+
+```typescript
+// Consistent error shape
+interface ApiError {
+  code: string; // machine-readable: "VALIDATION_ERROR", "NOT_FOUND"
+  message: string; // human-readable description
+  details?: unknown; // field-level errors, context
+  requestId?: string; // correlation ID for debugging
+}
+```
+
+- [ ] Use standard HTTP status codes correctly (400 vs 422 vs 500)
+- [ ] Never expose stack traces or internal errors to clients
+- [ ] Include actionable error messages
+- [ ] Document all possible error codes per endpoint
+
+### Versioning
+
+| Strategy      | When                               | Example                               |
+| ------------- | ---------------------------------- | ------------------------------------- |
+| URL prefix    | Breaking changes to resources      | `/v1/users`, `/v2/users`              |
+| Header        | Breaking changes, same URL desired | `Accept: application/vnd.api.v2+json` |
+| Query param   | Simple, low-ceremony               | `/users?version=2`                    |
+| No versioning | Internal APIs, single consumer     | Direct updates                        |
+
+**Default:** URL prefix versioning for public APIs, no versioning for internal.
+
+### Backward Compatibility Rules
+
+| Safe (Non-Breaking)       | Unsafe (Breaking)        |
+| ------------------------- | ------------------------ |
+| Add optional fields       | Remove or rename fields  |
+| Add new endpoints         | Change field types       |
+| Add new enum values       | Remove enum values       |
+| Widen input validation    | Tighten input validation |
+| Add optional query params | Change URL structure     |
+
+## Common Rationalizations
+
+| Excuse                           | Rebuttal                                                                 |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| "It's just an internal API"      | Internal APIs become external. Design the contract now.                  |
+| "We can change it later"         | Every consumer you add makes changes harder. Get it right early.         |
+| "The frontend team will adapt"   | Consumers shouldn't break because you didn't plan the interface.         |
+| "Error handling is boilerplate"  | Inconsistent errors cause more debugging than any boilerplate saves.     |
+| "Versioning is overkill for now" | Adding versioning later requires migrating all consumers simultaneously. |
+
+## TypeScript Patterns
+
+### Strict Input/Output Types
+
+```typescript
+// ✅ Separate input and output types
+interface CreateUserInput {
+  name: string;
+  email: string;
+}
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string; // ISO 8601
+}
+
+// ✅ Validate at boundary
+const createUserSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+});
+```
+
+### Discriminated Unions for Results
+
+```typescript
+type ApiResult<T> = { success: true; data: T } | { success: false; error: ApiError };
+```
+
+## Red Flags — STOP
+
+- Endpoint returns different shapes depending on internal state
+- Error responses have no consistent structure
+- URL contains verbs (`/createUser`, `/deleteItem`)
+- No input validation at the API boundary
+- Response includes internal database IDs or implementation details
+- Breaking change deployed without version bump
+
+## Verification
+
+- [ ] All endpoints have typed request/response schemas
+- [ ] Error responses follow the consistent error shape
+- [ ] Breaking changes increment the API version
+- [ ] Input validation rejects invalid/extra fields
+- [ ] Response matches documented contract exactly
+
+## See Also
+
+- **defense-in-depth** — Validation at every layer, not just the API boundary
+- **incremental-implementation** — Build API endpoints as thin vertical slices
+- **test-driven-development** — Write API contract tests before implementation

package/dist/template/.opencode/skill/beads/SKILL.md

@@ -13,6 +13,7 @@ dependencies: []
 # Beads Workflow - Multi-Agent Task Coordination
 
 > **Replaces** ad-hoc task tracking with sticky notes, TODO comments, or mental checklists that lose state between sessions
+
 ## When to Use
 
 - Coordinating multi-session work with dependencies, blockers, or file locking needs
@@ -98,7 +99,7 @@ See: `references/EXAMPLES.md` for complete usage examples.
 
 ## Multi-Agent Coordination (Summary)
 
-For parallel execution with multiple subagents, use the **beads-bridge** skill.
+For parallel execution with multiple subagents, use the **swarm-coordination** skill.
 
 See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
 
@@ -113,13 +114,13 @@ See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
 
 ## Anti-Patterns
 
-| Anti-Pattern | Why It Fails | Instead |
-| --- | --- | --- |
-| Claiming a bead without reading its current state first (`br show`) | Misses dependencies, blockers, and prior context | Run `br show <id>` before `br update <id> --status in_progress` |
-| Closing a bead without verification evidence | Marks incomplete or broken work as done | Run verification commands and capture output before `br close` |
-| Working on blocked beads (dependencies not met) | Wastes time and causes out-of-order delivery | Use `br ready` and confirm dependencies in `br show <id>` |
-| Modifying bead state without user confirmation | Violates workflow expectations and can surprise collaborators | Ask before changing bead status, especially close/sync actions |
-| Using `br sync` without `--flush-only` (can cause conflicts) | May write unexpected state and increase sync conflict risk | Always use `br sync --flush-only` then commit `.beads/` manually |
+| Anti-Pattern                                                        | Why It Fails                                                  | Instead                                                          |
+| ------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Claiming a bead without reading its current state first (`br show`) | Misses dependencies, blockers, and prior context              | Run `br show <id>` before `br update <id> --status in_progress`  |
+| Closing a bead without verification evidence                        | Marks incomplete or broken work as done                       | Run verification commands and capture output before `br close`   |
+| Working on blocked beads (dependencies not met)                     | Wastes time and causes out-of-order delivery                  | Use `br ready` and confirm dependencies in `br show <id>`        |
+| Modifying bead state without user confirmation                      | Violates workflow expectations and can surprise collaborators | Ask before changing bead status, especially close/sync actions   |
+| Using `br sync` without `--flush-only` (can cause conflicts)        | May write unexpected state and increase sync conflict risk    | Always use `br sync --flush-only` then commit `.beads/` manually |
 
 ## Verification
 
@@ -178,4 +179,4 @@ MAINTENANCE:
 ## See Also
 
 - `verification-before-completion`
-- `beads-bridge`
+- `swarm-coordination`

package/dist/template/.opencode/skill/beads/references/MULTI_AGENT.md

@@ -1,26 +1,26 @@
 # Multi-Agent Coordination (Swarm Mode)
 
-For parallel execution with multiple subagents, use the **beads-bridge** skill:
+For parallel execution with multiple subagents, use the **swarm-coordination** skill:
 
 ```typescript
-skill({ name: "beads-bridge" });
+skill({ name: "swarm-coordination" });
 ```
 
-**beads-bridge** provides (via unified `swarm` tool):
+**swarm-coordination** provides (via unified `swarm` tool):
 
 - `swarm({ operation: "sync" })` - Sync Beads tasks to OpenCode todos for subagent visibility
 - `swarm({ operation: "monitor" })` - Real-time progress tracking and visualization
 - `swarm({ operation: "plan" })` - Task classification and dependency analysis
 - `swarm({ operation: "delegate" })` - Create delegation packets for workers
 
-**When to use beads vs beads-bridge:**
+**When to use beads vs swarm-coordination:**
 
-| Scenario                       | Use                              |
-| ------------------------------ | -------------------------------- |
-| Single agent, linear work      | `beads` skill only               |
-| Multiple agents in parallel    | `beads-bridge` + `beads`         |
-| Need subagents to see tasks    | `beads-bridge` (swarm sync push) |
-| Track worker progress visually | `beads-bridge` (swarm monitor)   |
+| Scenario                       | Use                                    |
+| ------------------------------ | -------------------------------------- |
+| Single agent, linear work      | `beads` skill only                     |
+| Multiple agents in parallel    | `swarm-coordination` + `beads`         |
+| Need subagents to see tasks    | `swarm-coordination` (swarm sync push) |
+| Track worker progress visually | `swarm-coordination` (swarm monitor)   |
 
 **Example swarm workflow:**
 

package/dist/template/.opencode/skill/ci-cd-and-automation/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: ci-cd-and-automation
+description: Use when setting up CI/CD pipelines, GitHub Actions workflows, automated testing in CI, or deployment automation — covers pipeline design, caching, secrets management, and release workflows
+version: 1.0.0
+tags: [devops, workflow]
+dependencies: []
+---
+
+# CI/CD & Automation
+
+> **Replaces** manual deployment checklists and ad-hoc scripts with repeatable, auditable automation pipelines
+
+## When to Use
+
+- Setting up or modifying CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
+- Adding automated testing, linting, or type-checking to a repository
+- Configuring deployment automation or release workflows
+- Optimizing CI performance (caching, parallelism, conditional runs)
+
+## When NOT to Use
+
+- Local development scripts (use Makefile or package.json scripts)
+- One-time migration scripts that don't repeat
+- Infrastructure provisioning (use infrastructure-as-code tools directly)
+
+## Overview
+
+CI/CD pipelines are the quality gates between code and production. A well-designed pipeline catches problems early, runs fast, and deploys safely.
+
+**Core principle:** Every step that a human does manually before merging or deploying should be automated in the pipeline. If it can be automated, it must be.
+
+## Pipeline Design
+
+### Verification Pipeline (PR/Push)
+
+```yaml
+# Ordered by speed: fastest gates first
+steps:
+  1. Lint          # seconds — catches formatting/style issues
+  2. Typecheck     # seconds — catches type errors
+  3. Unit tests    # seconds-minutes — catches logic bugs
+  4. Build         # minutes — catches compilation issues
+  5. Integration   # minutes — catches integration bugs
+  6. E2E tests     # minutes — catches user-facing bugs (optional per-PR)
+```
+
+**Fail-fast rule:** Run cheapest checks first. Don't waste 10 minutes on E2E tests if linting fails in 5 seconds.
+
+### Deployment Pipeline (Main/Release)
+
+```
+1. All verification steps pass
+2. Build production artifacts
+3. Deploy to staging
+4. Run smoke tests against staging
+5. Deploy to production (manual gate or auto)
+6. Run smoke tests against production
+7. Monitor error rates for rollback window
+```
+
+## GitHub Actions Patterns
+
+### Basic PR Verification
+
+```yaml
+name: verify
+on: [pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: ".node-version"
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build
+```
+
+### Caching Strategy
+
+| What         | Cache Key         | Restore Key | Impact       |
+| ------------ | ----------------- | ----------- | ------------ |
+| Dependencies | `lockfile hash`   | `os-deps-`  | 30-60s saved |
+| Build output | `source hash`     | `os-build-` | 1-5min saved |
+| Test cache   | `test files hash` | `os-test-`  | Variable     |
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.pnpm-store
+    key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+    restore-keys: ${{ runner.os }}-pnpm-
+```
+
+### Parallel Jobs
+
+```yaml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps: [checkout, setup, "pnpm lint"]
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps: [checkout, setup, "pnpm typecheck"]
+
+  test:
+    runs-on: ubuntu-latest
+    steps: [checkout, setup, "pnpm test"]
+
+  build:
+    needs: [lint, typecheck, test] # Only build after all checks pass
+    runs-on: ubuntu-latest
+    steps: [checkout, setup, "pnpm build"]
+```
+
+## Secrets Management
+
+| Rule                                       | Reason                                        |
+| ------------------------------------------ | --------------------------------------------- |
+| Never echo secrets in CI logs              | Logs are often accessible to all contributors |
+| Use GitHub Secrets / environment variables | Encrypted at rest, masked in logs             |
+| Rotate secrets on exposure                 | Assume compromised if ever logged             |
+| Separate secrets per environment           | Staging keys ≠ production keys                |
+| Use OIDC for cloud providers               | No long-lived credentials needed              |
+
+## Release Automation
+
+### Semantic Versioning
+
+```
+MAJOR.MINOR.PATCH
+  │      │     └── Bug fixes (backward compatible)
+  │      └──────── New features (backward compatible)
+  └─────────────── Breaking changes
+```
+
+### Tag-Based Release
+
+```yaml
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  release:
+    steps:
+      - uses: actions/checkout@v4
+      - run: pnpm build
+      - run: pnpm publish # or deploy
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+```
+
+## Common Rationalizations
+
+| Excuse                              | Rebuttal                                                                          |
+| ----------------------------------- | --------------------------------------------------------------------------------- |
+| "CI is slow, I'll test locally"     | Local tests miss environment-specific issues. Optimize CI instead of skipping it. |
+| "We can add CI later"               | Every merged PR without CI is a potential regression. Set up day one.             |
+| "The pipeline is too complex"       | Complexity means you're catching real issues. Simplify steps, not coverage.       |
+| "Manual deploy is faster"           | Until someone deploys the wrong branch. Automation prevents human error.          |
+| "Caching is premature optimization" | 5 minutes saved per PR × 20 PRs/week = 100 minutes/week. Cache from day one.      |
+
+## CI Performance Optimization
+
+| Technique              | Savings                   | Effort                 |
+| ---------------------- | ------------------------- | ---------------------- |
+| Dependency caching     | 30-60s per run            | Low — add cache action |
+| Parallel jobs          | 50-70% of sequential time | Low — split into jobs  |
+| Conditional runs       | Skip unchanged paths      | Medium — path filters  |
+| Build artifact caching | 1-5min per run            | Medium — cache config  |
+| Self-hosted runners    | Faster hardware           | High — infrastructure  |
+
+## Red Flags — STOP
+
+- CI pipeline takes >15 minutes for a PR check
+- Secrets hardcoded in workflow files
+- No caching configured despite slow builds
+- Tests skipped in CI "to save time"
+- Manual deployment steps in the release process
+- No rollback mechanism for failed deployments
+
+## Verification
+
+- [ ] All verification steps run on every PR
+- [ ] Pipeline fails fast (cheapest checks first)
+- [ ] Dependencies are cached
+- [ ] Secrets are never printed in logs
+- [ ] Release process is tag-triggered and automated
+- [ ] Rollback procedure is documented and tested
+
+## See Also
+
+- **verification-gates** — Detecting project type and running appropriate checks
+- **git-workflow-and-versioning** — Branch strategy and commit conventions
+- **security-and-hardening** — Secrets management and supply chain security