opencodekit 0.20.6 → 0.20.8

package/dist/template/.opencode/skill/deprecation-and-migration/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: deprecation-and-migration
+description: Use when deprecating APIs, migrating between library versions, removing legacy code, or planning breaking changes — covers deprecation notices, migration guides, codemods, and staged rollout
+version: 1.0.0
+tags: [architecture, workflow]
+dependencies: []
+---
+
+# Deprecation & Migration
+
+> **Replaces** sudden breaking changes with structured, communicable transitions that give consumers time to adapt
+
+## When to Use
+
+- Deprecating an API endpoint, function, or module
+- Migrating between major library/framework versions
+- Removing legacy code paths or feature flags
+- Planning breaking changes across multiple consumers
+
+## When NOT to Use
+
+- Internal refactors that don't affect any public API or consumer
+- Bug fixes that change behavior (that's a fix, not a migration)
+- Adding new features alongside existing ones (no deprecation needed)
+
+## Overview
+
+Deprecation is a communication protocol. Migration is the execution plan. Both must be explicit, gradual, and reversible until the cutover point.
+
+**Core principle:** Never remove without warning. Never warn without a replacement. Never migrate without a rollback plan.
+
+## Deprecation Process
+
+```
+1. ANNOUNCE  — Mark as deprecated with notice + replacement + timeline
+2. PROVIDE   — Ship the replacement alongside the deprecated code
+3. MIGRATE   — Help consumers move (codemods, guides, examples)
+4. MONITOR   — Track usage of deprecated paths
+5. REMOVE    — Remove only after usage drops to zero (or deadline passes)
+```
+
+## Deprecation Notices
+
+### In Code
+
+```typescript
+/**
+ * @deprecated Use `createUser()` instead. Will be removed in v3.0.
+ * Migration guide: https://docs.example.com/migrate-v3
+ */
+export function addUser(name: string): User {
+  console.warn(
+    "addUser() is deprecated. Use createUser() instead. See: https://docs.example.com/migrate-v3",
+  );
+  return createUser({ name });
+}
+```
+
+### Checklist
+
+- [ ] `@deprecated` JSDoc tag with replacement name
+- [ ] Runtime warning on first call (not every call — use a flag)
+- [ ] Migration guide URL in the deprecation message
+- [ ] Removal version/date specified
+- [ ] TypeScript: mark with `@deprecated` for IDE strikethrough
+
+## Migration Guide Template
+
+```markdown
+# Migration: v2 → v3
+
+## Breaking Changes
+
+| Change                   | Before          | After                  | Effort |
+| ------------------------ | --------------- | ---------------------- | ------ |
+| `addUser` → `createUser` | `addUser(name)` | `createUser({ name })` | S      |
+| Config format changed    | `config.key`    | `config.settings.key`  | M      |
+
+## Step-by-Step
+
+1. Update dependency: `npm install pkg@3.0.0`
+2. Run codemod: `npx pkg-migrate v2-to-v3`
+3. Manual fixes: [list of manual changes]
+4. Verify: `npm test && npm run typecheck`
+
+## Rollback
+
+If issues arise: `npm install pkg@2.x.x` — v2 APIs still work until v4.
+
+## Timeline
+
+- v2.5.0: Deprecation warnings added
+- v3.0.0: New API shipped, old API still works with warnings
+- v3.5.0: Old API removed (6 months after v3.0.0)
+```
+
+## Codemod Patterns
+
+### Simple Find & Replace
+
+```typescript
+// jscodeshift transform
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  return j(file.source)
+    .find(j.CallExpression, { callee: { name: "addUser" } })
+    .forEach((path) => {
+      path.node.callee.name = "createUser";
+      // Wrap string arg in object: addUser("name") → createUser({ name: "name" })
+      const arg = path.node.arguments[0];
+      path.node.arguments = [j.objectExpression([j.property("init", j.identifier("name"), arg)])];
+    })
+    .toSource();
+}
+```
+
+### When to Write a Codemod
+
+| Consumers       | Change Complexity   | Write Codemod?                             |
+| --------------- | ------------------- | ------------------------------------------ |
+| 1-5 call sites  | Simple rename       | No — manual is faster                      |
+| 5-20 call sites | Simple rename       | Maybe — saves time and ensures consistency |
+| 20+ call sites  | Any change          | Yes — manual migration is error-prone      |
+| Any count       | Complex restructure | Yes — reduce human error                   |
+
+## Staged Rollout
+
+```
+Phase 1: Ship new API alongside old (backward compatible)
+  └── Duration: 1-2 release cycles
+  └── Verify: New API works, old API still works
+
+Phase 2: Add deprecation warnings to old API
+  └── Duration: 2-4 release cycles
+  └── Monitor: Track warning frequency, identify stragglers
+
+Phase 3: Remove old API
+  └── Only when: Usage is zero OR deadline passed
+  └── Verify: No references remain in codebase
+  └── Rollback: Revert removal if unexpected breakage
+```
+
+## Common Rationalizations
+
+| Excuse                                 | Rebuttal                                                                           |
+| -------------------------------------- | ---------------------------------------------------------------------------------- |
+| "Nobody uses the old API"              | Prove it with usage data. Assumption ≠ evidence.                                   |
+| "It's an internal API, just change it" | Internal consumers break too. Deprecate or coordinate.                             |
+| "Deprecation warnings are noisy"       | That's the point — they surface migration debt before it becomes an emergency.     |
+| "We'll document later"                 | Undocumented breaking changes cause support load that dwarfs documentation effort. |
+| "The codemod is too much work"         | One codemod saves N manual migrations. Calculate the actual ROI.                   |
+| "Just bump the major version"          | A version bump without a migration path is abandonment, not deprecation.           |
+
+## Feature Flag Cleanup
+
+Feature flags are a form of deprecation — they accumulate if not cleaned up.
+
+```
+1. Deploy feature behind flag (OFF)
+2. Enable for team → canary → percentage → 100%
+3. Once stable at 100%: REMOVE the flag
+4. Delete: flag definition, branching code, old code path
+5. Verify: tests pass without the flag
+```
+
+**Flag lifecycle max:** 30 days at 100% before cleanup is mandatory.
+
+## Red Flags — STOP
+
+- Breaking change shipped without deprecation period
+- Deprecated code removed before usage reaches zero
+- No migration guide or codemod for complex changes
+- Feature flags older than 90 days without cleanup plan
+- Runtime deprecation warnings suppressed instead of addressed
+
+## Verification
+
+- [ ] Deprecated APIs have `@deprecated` tags with replacement
+- [ ] Runtime warnings fire on deprecated API usage
+- [ ] Migration guide exists with step-by-step + rollback
+- [ ] Usage of deprecated paths is tracked/monitored
+- [ ] Feature flags have documented cleanup dates
+- [ ] Codemod written for changes affecting 20+ call sites
+
+## See Also
+
+- **api-and-interface-design** — Designing APIs that minimize future deprecation
+- **incremental-implementation** — Migrating in thin vertical slices
+- **documentation-and-adrs** — Recording the decision to deprecate/migrate

package/dist/template/.opencode/skill/development-lifecycle/SKILL.md

@@ -3,7 +3,16 @@ name: development-lifecycle
 description: Orchestrates the full feature development lifecycle from ideation through verification. Guides through phases (brainstorm → design → specify → plan → implement → verify) and loads appropriate sub-skills at each stage.
 version: 1.0.0
 tags: [workflow, planning]
-dependencies: [brainstorming, prd, writing-plans, executing-plans, verification-before-completion, requesting-code-review, finishing-a-development-branch]
+dependencies:
+  [
+    brainstorming,
+    prd,
+    writing-plans,
+    executing-plans,
+    verification-before-completion,
+    requesting-code-review,
+    finishing-a-development-branch,
+  ]
 ---
 
 ---
@@ -24,6 +33,8 @@ dependencies: [brainstorming, prd, writing-plans, executing-plans, verification-
 
 This skill orchestrates the complete feature development workflow, guiding you through each phase and loading the appropriate sub-skills automatically.
 
+**Note:** For quick skill routing by intent, see the Intent → Skill Mapping table in `AGENTS.md`. This skill is for full end-to-end orchestration when you need phase-by-phase guidance.
+
 **Use when:** Starting any new feature, migration, refactor, or significant change.
 
 **Announce at start:** "I'm using development-lifecycle to guide this work through all phases."
@@ -58,12 +69,6 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 **When:** You have a rough idea but need to explore and refine it.
 
-**Load skill:**
-
-```typescript
-skill({ name: "brainstorming" });
-```
-
 **Entry criteria:** User has an idea or problem to solve.
 
 **Process:**
@@ -92,12 +97,6 @@ skill({ name: "brainstorming" });
 
 **When:** Design is validated, need formal requirements and task breakdown.
 
-**Load skill:**
-
-```typescript
-skill({ name: "prd" });
-```
-
 **Entry criteria:** Design document exists and is validated.
 
 **Process:**
@@ -126,12 +125,6 @@ skill({ name: "prd" });
 
 **When:** PRD is complete, need executable task list.
 
-**Load skill:**
-
-```typescript
-skill({ name: "prd-task" });
-```
-
 **Entry criteria:** PRD exists at `.beads/artifacts/<bead-id>/prd.md`.
 
 **Process:**
@@ -158,12 +151,6 @@ skill({ name: "prd-task" });
 
 **When:** Tasks defined, need detailed implementation instructions.
 
-**Load skill:**
-
-```typescript
-skill({ name: "writing-plans" });
-```
-
 **Entry criteria:** Task list exists (prd.json or tasks.md).
 
 **Process:**
@@ -192,12 +179,6 @@ skill({ name: "writing-plans" });
 
 **When:** Plan is ready, time to build.
 
-**Load skill:**
-
-```typescript
-skill({ name: "executing-plans" });
-```
-
 **Entry criteria:** Plan exists at `.beads/artifacts/<bead-id>/plan.md`.
 
 **Process:**
@@ -225,12 +206,6 @@ skill({ name: "executing-plans" });
 
 **When:** Implementation complete, before claiming done.
 
-**Load skill:**
-
-```typescript
-skill({ name: "verification-before-completion" });
-```
-
 **Entry criteria:** All implementation tasks marked complete.
 
 **Process:**
@@ -250,17 +225,6 @@ skill({ name: "verification-before-completion" });
 
 ## Phase Transitions
 
-### Quick Start (Skip to appropriate phase)
-
-| Starting Point                    | Begin At | Command                                             |
-| --------------------------------- | -------- | --------------------------------------------------- |
-| Rough idea                        | Phase 1  | `skill({ name: "brainstorming" })`                  |
-| Design done, need requirements    | Phase 2  | `skill({ name: "prd" })`                            |
-| PRD done, need task JSON          | Phase 3  | `skill({ name: "prd-task" })`                       |
-| Tasks defined, need detailed plan | Phase 4  | `skill({ name: "writing-plans" })`                  |
-| Plan ready, time to build         | Phase 5  | `skill({ name: "executing-plans" })`                |
-| Done coding, need verification    | Phase 6  | `skill({ name: "verification-before-completion" })` |
-
 ### Skipping Phases
 
 For small changes, you can skip early phases:

package/dist/template/.opencode/skill/documentation-and-adrs/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: documentation-and-adrs
+description: Use when writing technical documentation, Architecture Decision Records (ADRs), API docs, or project READMEs — covers documentation structure, ADR format, and keeping docs in sync with code
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
+---
+
+# Documentation & ADRs
+
+> **Replaces** undocumented architectural decisions and stale wiki pages with living documentation that stays close to code
+
+## When to Use
+
+- Making a significant architectural decision that should be recorded
+- Writing or updating project documentation (README, guides, API docs)
+- Onboarding documentation needs updating
+- Code has complex behavior that isn't obvious from reading it
+
+## When NOT to Use
+
+- Code is self-documenting (clear naming, simple logic, typed interfaces)
+- Writing comments that restate what the code does (comment the why, not the what)
+- Documentation for throwaway prototypes
+
+## Overview
+
+Documentation has two purposes: **decisions** (why things are the way they are) and **usage** (how to use them). ADRs handle the first. Guides, READMEs, and API docs handle the second.
+
+**Core principle:** Document decisions when they're made, not months later when context is lost. Keep docs next to the code they describe.
+
+## Architecture Decision Records (ADRs)
+
+### When to Write an ADR
+
+- Choosing between technologies, frameworks, or approaches
+- Establishing a pattern that the team should follow
+- Deviating from an existing convention (and why)
+- Any decision you'd want to explain to a new team member in 6 months
+
+### ADR Template
+
+```markdown
+# ADR-NNN: [Decision Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+
+What is the issue we're facing? What constraints exist?
+[2-5 sentences describing the problem and constraints]
+
+## Decision
+
+What did we decide to do?
+[1-3 sentences stating the decision clearly]
+
+## Alternatives Considered
+
+| Option   | Pros | Cons | Verdict            |
+| -------- | ---- | ---- | ------------------ |
+| Option A | ...  | ...  | Chosen             |
+| Option B | ...  | ...  | Rejected: [reason] |
+| Option C | ...  | ...  | Rejected: [reason] |
+
+## Consequences
+
+### Positive
+
+- [Good outcomes]
+
+### Negative
+
+- [Trade-offs accepted]
+
+### Risks
+
+- [Things that could go wrong]
+```
+
+### ADR File Location
+
+```
+docs/adr/
+├── 001-use-typescript.md
+├── 002-choose-react-over-vue.md
+├── 003-api-versioning-strategy.md
+└── template.md
+```
+
+**Naming:** `NNN-kebab-case-title.md` — numbered for ordering, kebab-case for readability.
+
+## README Structure
+
+### Minimum Viable README
+
+```markdown
+# Project Name
+
+One-line description of what this does.
+
+## Quick Start
+
+[3-5 commands to get running]
+
+## Development
+
+[How to build, test, lint]
+
+## Architecture
+
+[Brief overview or link to docs/]
+
+## Contributing
+
+[Link to CONTRIBUTING.md or inline guide]
+```
+
+### README Anti-Patterns
+
+| Anti-Pattern                        | Fix                             |
+| ----------------------------------- | ------------------------------- |
+| "See wiki for docs" (wiki is stale) | Keep docs in repo, next to code |
+| Huge README (>500 lines)            | Split into docs/ directory      |
+| No Quick Start section              | First thing a new dev needs     |
+| Setup instructions that don't work  | CI should verify setup steps    |
+
+## API Documentation
+
+### In-Code Documentation
+
+````typescript
+/**
+ * Create a new project workspace.
+ *
+ * @param name - Project name (1-100 chars, alphanumeric + hyphens)
+ * @param options - Configuration options
+ * @returns The created project with generated ID
+ * @throws {ValidationError} If name is invalid
+ * @throws {ConflictError} If project name already exists
+ *
+ * @example
+ * ```typescript
+ * const project = await createProject('my-app', { template: 'react' });
+ * console.log(project.id); // "proj_abc123"
+ * ```
+ */
+export async function createProject(
+  name: string,
+  options?: CreateProjectOptions,
+): Promise<Project> {
+````
+
+### Documentation Comments Rules
+
+| Do                                               | Don't                                |
+| ------------------------------------------------ | ------------------------------------ |
+| Document the **why**                             | Restate the code as prose            |
+| Document **contracts** (inputs, outputs, errors) | Document obvious getters/setters     |
+| Document **non-obvious behavior**                | Document every function              |
+| Include **examples** for complex APIs            | Write examples for self-evident APIs |
+
+## Keeping Docs in Sync
+
+### Documentation Debt Signals
+
+- README references files that don't exist
+- Setup instructions fail on clean checkout
+- API docs describe removed/renamed endpoints
+- ADRs reference superseded decisions without linking forward
+
+### Automation
+
+```yaml
+# CI check: verify docs are not stale
+- name: Check links
+  run: npx markdown-link-check README.md docs/**/*.md
+
+- name: Verify setup instructions
+  run: |
+    # Run the Quick Start commands from README
+    npm install
+    npm run build
+    npm test
+```
+
+## Common Rationalizations
+
+| Excuse                         | Rebuttal                                                                |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| "The code is self-documenting" | Code shows what, not why. Decisions need context.                       |
+| "Nobody reads the docs"        | Because the docs are stale. Fresh docs get read.                        |
+| "I'll document it later"       | You won't. Context decays faster than you think.                        |
+| "ADRs are overhead"            | An ADR takes 10 minutes. Re-debating the decision takes hours.          |
+| "We use Notion/Confluence"     | Docs in external tools drift from code. Keep docs in repo.              |
+| "Comments get stale"           | So delete stale comments. But contracts and decisions need documenting. |
+
+## Red Flags — STOP
+
+- Architecture changed but no ADR recorded
+- README setup instructions haven't been tested in >30 days
+- API docs describe behavior that doesn't match implementation
+- Decision was made in Slack/meeting with no written record
+- New team member can't set up the project from docs alone
+
+## Verification
+
+- [ ] Significant decisions have ADRs with status, context, and alternatives
+- [ ] README Quick Start works on a clean checkout
+- [ ] API functions with complex behavior have JSDoc with examples
+- [ ] No dead links in documentation
+- [ ] Docs live in the repo (not external wiki only)
+
+## See Also
+
+- **api-and-interface-design** — API docs are part of the interface contract
+- **deprecation-and-migration** — Deprecation decisions warrant ADRs
+- **prd** — Product requirements docs (higher-level than ADRs)