mcp-subagents-opencode 1.0.0

package/build/templates/overlays/coder-triggerdev.mdx

@@ -0,0 +1,296 @@
+## TRIGGER.DEV CODING GUIDELINES
+
+You are working in a codebase that uses **Trigger.dev v4** for background tasks. Follow these patterns.
+
+---
+
+### TASK DEFINITION
+
+```typescript
+import { task, schemaTask, logger, metadata } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+// Basic task
+export const myTask = task({
+  id: "my-task",  // globally unique, lowercase, hyphens OK
+  run: async (payload, { ctx }) => {
+    // ctx.run.id, ctx.task.id, ctx.attempt.number, ctx.environment.type
+    return result;
+  },
+});
+
+// Schema-validated task (preferred)
+export const validatedTask = schemaTask({
+  id: "validated-task",
+  schema: z.object({
+    userId: z.string().uuid(),
+    amount: z.number().positive(),
+  }),
+  run: async (payload) => {
+    // payload is validated and typed
+  },
+});
+```
+
+**Critical rules:**
+- Tasks MUST be exported and imported by the entry point (`trigger/index.ts`) to register
+- Task IDs must be globally unique within the project
+- Payloads must be JSON-serializable — no Dates (use ISO strings), no class instances, no circular refs
+- Payload size limits: Free 64KB, Pro 3MB
+
+---
+
+### TRIGGERING PATTERNS
+
+```typescript
+// Fire-and-forget
+const handle = await myTask.trigger({ userId: "123" }, {
+  idempotencyKey: "user-123-action",  // prevent duplicate runs
+  tags: ["user-123"],
+  delay: "30s",
+});
+
+// Trigger and wait for result
+const result = await myTask.triggerAndWait({ userId: "123" });
+if (result.ok) { /* result.output */ } else { /* result.error */ }
+
+// Subtask orchestration
+export const orchestrator = task({
+  id: "orchestrator",
+  run: async (payload) => {
+    const step1 = await subtaskA.triggerAndWait({ ... });
+    if (!step1.ok) throw new Error("Step 1 failed");
+    return await subtaskB.triggerAndWait({ input: step1.output });
+  },
+});
+
+// Parallel subtasks
+const result = await batch.triggerByTaskAndWait([
+  { task: taskA, payload: { ... } },
+  { task: taskB, payload: { ... } },
+]);
+
+// Batch (up to 500 per call, chunk larger sets)
+const handles = await myTask.batchTrigger(
+  items.map(item => ({ payload: { item }, options: { idempotencyKey: `item-${item.id}` } }))
+);
+```
+
+---
+
+### SCHEDULED TASKS
+
+```typescript
+import { schedules } from "@trigger.dev/sdk";
+
+export const dailyReport = schedules.task({
+  id: "daily-report",
+  cron: { pattern: "0 9 * * *", timezone: "America/New_York" },
+  run: async (payload) => {
+    // payload.timestamp, payload.lastTimestamp, payload.timezone
+  },
+});
+
+// Dynamic schedules (from backend)
+await schedules.create({
+  task: "user-report",
+  cron: "0 9 * * 1",
+  externalId: "user-123",
+  deduplicationKey: "user-123-weekly",
+});
+```
+
+- Prevent overlapping: `queue: { concurrencyLimit: 1 }`
+
+---
+
+### LOGGING CONVENTIONS
+
+```typescript
+// Format: {operation}_{phase} in snake_case — ALWAYS
+logger.info("document_process_started", {
+  correlation_id: `doc-${payload.id.slice(0, 8)}`,
+  request_id: payload.requestId,
+  run_id: ctx.run.id,
+});
+
+logger.info("document_process_completed", {
+  correlation_id: correlationId,
+  processing_time_ms: Date.now() - startTime,
+});
+
+logger.error("document_process_failed", {
+  correlation_id: correlationId,
+  error_type: error.name,
+  error_message: error.message,
+});
+```
+
+- Message format: `{operation}_{phase}` (e.g., `order_process_started`, `payment_charge_failed`)
+- Always snake_case for both message and data keys — never camelCase
+- Lifecycle phases: `_started`, `_validating`, `_calling_{service}`, `_completed`, `_failed`
+- Always include: `correlation_id`, `request_id`, `run_id`
+
+---
+
+### IDEMPOTENCY
+
+```typescript
+import { idempotencyKeys } from "@trigger.dev/sdk";
+
+// Trigger-level (prevent duplicate runs)
+await myTask.trigger({ orderId: "123" }, { idempotencyKey: "process-order-123" });
+
+// Inside task — run-scoped (safe for retries)
+const runKey = await idempotencyKeys.create(`charge-${orderId}`);
+
+// Inside task — global (unique across different runs)
+const globalKey = await idempotencyKeys.create(`order-${orderId}`, { scope: "global" });
+
+// For long-term dedup (beyond 30-day TTL), use database-level checks
+```
+
+Key patterns: `order-${orderId}`, `stripe-event-${event.id}`, `daily-report-${date}`
+
+---
+
+### RETRIES & ERROR HANDLING
+
+```typescript
+import { AbortTaskRunError } from "@trigger.dev/sdk";
+
+export const apiTask = task({
+  id: "api-task",
+  retry: {
+    maxAttempts: 5,
+    factor: 2,
+    minTimeoutInMs: 2000,
+    maxTimeoutInMs: 30000,
+    randomize: true,
+  },
+  run: async (payload, { ctx }) => {
+    try {
+      return await apiCall(payload);
+    } catch (error) {
+      // Don't retry validation/auth errors
+      if (error.status === 400 || error.status === 401 || error.status === 403) {
+        throw new AbortTaskRunError(`Unrecoverable: ${error.status}`);
+      }
+      throw error;  // Retry on transient errors
+    }
+  },
+});
+```
+
+| Use Case | Config |
+|----------|--------|
+| Network/transient | factor: 2, min: 1s, max: 30s, attempts: 5 |
+| Rate limits | factor: 3, min: 5s, max: 120s, attempts: 3 |
+| Database | factor: 1.5, min: 500ms, max: 5s, attempts: 3 |
+| No retry | maxAttempts: 1 |
+
+---
+
+### CONCURRENCY
+
+```typescript
+import { queue } from "@trigger.dev/sdk";
+
+// Per-task limit
+export const limitedTask = task({
+  id: "limited-task",
+  queue: { concurrencyLimit: 10 },
+  run: async (payload) => { /* ... */ },
+});
+
+// Shared queue (multiple tasks share concurrency pool)
+const apiQueue = queue({ name: "api-queue", concurrencyLimit: 10 });
+
+export const taskA = task({ id: "task-a", queue: apiQueue, run: async () => {} });
+export const taskB = task({ id: "task-b", queue: apiQueue, run: async () => {} });
+```
+
+Limits: External API 5-20, Database 10-50, File processing 5-10, Singleton 1.
+
+---
+
+### HOOKS & MIDDLEWARE
+
+```typescript
+export const taskWithHooks = task({
+  id: "task-with-hooks",
+  onSuccess: async ({ output, ctx }) => { await notifySuccess(ctx.run.id, output); },
+  onFailure: async ({ error, ctx }) => { await notifyFailure(ctx.run.id, error); },  // after ALL retries
+  onWait: async () => { await db.disconnect(); },
+  onResume: async () => { await db.connect(); },
+  run: async (payload) => { /* ... */ },
+});
+
+// Global middleware (src/trigger/init.ts)
+import { locals, tasks } from "@trigger.dev/sdk";
+
+const DbLocal = locals.create<Database>("db");
+export function getDb() { return locals.getOrThrow(DbLocal); }
+
+tasks.middleware("db", async ({ next }) => {
+  const db = await Database.connect();
+  locals.set(DbLocal, db);
+  await next();
+  await db.disconnect();
+});
+```
+
+---
+
+### METADATA & STREAMING
+
+```typescript
+// Progress updates (metadata limit: 256KB)
+metadata.set({ status: "processing", progress: 0 });
+metadata.set({ progress: Math.round(((i + 1) / total) * 100) });
+
+// AI streaming
+import { streamText } from "ai";
+const result = streamText({ model: openai("gpt-4o"), prompt });
+const fullStream = await metadata.stream("llm", result.fullStream);
+```
+
+For large data, store externally and put the URL in metadata.
+
+---
+
+### CONFIGURATION (trigger.config.ts)
+
+```typescript
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project-ref>",
+  dirs: ["./src/trigger"],
+  runtime: "node",  // "node" | "node-22" | "bun"
+  logLevel: "info",
+  maxDuration: 300,  // seconds
+  retries: {
+    enabledInDev: true,
+    default: { maxAttempts: 3, factor: 2, minTimeoutInMs: 1000, maxTimeoutInMs: 60000, randomize: true },
+  },
+  build: { external: ["sharp", "sqlite3"], autoDetectExternal: true },
+});
+```
+
+---
+
+### ANTI-PATTERNS
+
+| Anti-Pattern | Solution |
+|---|---|
+| Large payloads (data blobs) | Pass IDs/URLs, not data |
+| Unexported tasks | Export + import in entry point |
+| Non-serializable payloads (Dates, classes) | Use ISO strings, plain objects |
+| Class instances across awaits | Rehydrate after every await (checkpoints) |
+| No idempotency keys | Always use for important operations |
+| Retrying non-transient errors | Use `AbortTaskRunError` for 400/401/403 |
+| Overlapping scheduled tasks | Set `queue: { concurrencyLimit: 1 }` |
+| camelCase log keys | Always snake_case |
+| PII in logs | Log UUIDs, never emails/names |
+| No run_id persistence | Always save `ctx.run.id` back to DB |

package/build/templates/overlays/coder-typescript.mdx

@@ -0,0 +1,45 @@
+## TYPESCRIPT-SPECIFIC GUIDELINES
+
+You are working in a **TypeScript** codebase. Apply these principles with zero exceptions.
+
+### Type Safety — NON-NEGOTIABLE
+- ALWAYS use strict TypeScript (`strict: true` in tsconfig) — if the project has it disabled, note it but write strict code anyway
+- **NEVER use `any`** — use `unknown` + type guards, or proper generic constraints
+- Prefer `interface` over `type` for object shapes — interfaces are extendable and produce better error messages
+- Use **discriminated unions** for state machines and variant types
+- Use `as const` for literal types and enum-like objects
+- **Explicit return types** on all exported functions — don't rely on inference for public API
+- Use `readonly` arrays and objects where mutation is not needed
+- Template literal types for string patterns (e.g., `type EventName = \`on${string}\``)
+
+### Error Handling
+- Use **typed error classes** that extend `Error` — never throw raw strings
+- Use Result/Either pattern for expected failures (function returns success or typed error)
+- Never `catch` and swallow — always handle, rethrow, or log with context
+- Use `unknown` in catch blocks: `catch (err: unknown)`
+
+### Imports & Module Structure
+- **Named exports** over default exports (better refactoring, tree-shaking)
+- Barrel exports (`index.ts`) for public APIs of modules
+- Import grouping: `external packages` → `internal modules` → `type imports`
+- Use `import type { ... }` for type-only imports (prevents runtime import)
+- Never use `require()` in TypeScript
+
+### Code Patterns
+- Prefer **composition over inheritance** — use interfaces + factory functions
+- Use `Map`/`Set` over plain objects for dynamic keys
+- Prefer `for...of` over `forEach` for readability and `break`/`continue` support
+- Use optional chaining (`?.`) and nullish coalescing (`??`) — avoid `&&` chains for null checks
+- Use `satisfies` operator for type checking without widening
+
+### Naming Conventions
+- `PascalCase` for types, interfaces, classes, enums
+- `camelCase` for variables, functions, methods
+- `UPPER_SNAKE_CASE` for constants
+- Prefix interfaces with context, not `I` — `UserService` not `IUserService`
+- Boolean variables: `is*`, `has*`, `can*`, `should*`
+
+### Testing Considerations
+- Write code that is **easily testable** — pure functions, dependency injection, no hidden globals
+- Export internal functions for testing only via `/** @internal */` JSDoc tag
+- Prefer deterministic code — avoid `Date.now()` directly, accept timestamps as params

package/build/templates/overlays/coder-vue.mdx

@@ -0,0 +1,62 @@
+## VUE-SPECIFIC GUIDELINES
+
+You are working in a **Vue** codebase. Apply these principles with zero exceptions.
+
+### Composition API — The Default
+- Use **Composition API** with `<script setup>` — not Options API, unless the project explicitly uses it
+- `<script setup>` is the recommended syntax — all top-level bindings are automatically exposed to the template
+- Keep `<script setup>` organized: imports → props/emits → reactive state → computed → watchers → functions → lifecycle
+
+### Reactivity — ref/reactive
+- Use `ref()` for primitives and values you might reassign: `const count = ref(0)`
+- Use `reactive()` for objects/collections that you mutate: `const form = reactive({ name: '', email: '' })`
+- Access `ref` values with `.value` in script, automatic unwrapping in templates
+- **Never destructure reactive objects** — it breaks reactivity. Use `toRefs()` if needed
+- Use `shallowRef()` / `shallowReactive()` for large objects where deep reactivity is wasteful
+
+### Computed & Watch
+- Use `computed()` for derived state — automatically cached and dependency-tracked
+- Use `watch()` for side effects when reactive data changes — API calls, logging
+- Use `watchEffect()` when you want automatic dependency tracking (no explicit source)
+- Avoid watchers when computed will do — computed is simpler and more performant
+- Use `{ immediate: true }` when the watcher should run on initialization
+
+### Composables — Reusable Logic
+- Extract reusable stateful logic into composables: `useAuth()`, `useFetch()`, `useLocalStorage()`
+- Composable naming: always start with `use`
+- Composables go in `composables/` directory
+- Composables can use all Composition API features: ref, computed, watch, lifecycle hooks
+- Return reactive state and methods from composables — let the consumer decide how to use them
+
+### Pinia — State Management
+- Use **Pinia** for global state — not Vuex (Pinia is the official recommendation)
+- Use `defineStore()` with Setup Store syntax (Composition API style) — matches component patterns
+- Keep stores focused — one store per domain concern
+- Use `storeToRefs()` when destructuring store state in components — preserves reactivity
+- Actions can be async — use them for API calls and complex mutations
+
+### Single-File Component Conventions
+- Order: `<script setup>` → `<template>` → `<style scoped>`
+- Use `scoped` styles by default — prevents CSS leaking
+- Use CSS `v-bind()` for dynamic styles based on reactive data
+- Keep templates readable — extract complex logic into computed properties or composables
+- Use `<component :is="...">` for dynamic components
+
+### Props & Events
+- Define props with `defineProps<{ name: string; count?: number }>()` — TypeScript-typed
+- Define emits with `defineEmits<{ (e: 'update', value: string): void }>()` — typed events
+- Use `v-model` with `defineModel()` (Vue 3.4+) for two-way binding
+- Props are readonly — never mutate props directly. Emit an event to request parent changes
+
+### Naming Conventions
+- `PascalCase` for components in script: `import UserCard from './UserCard.vue'`
+- `PascalCase` or `kebab-case` for components in templates (follow project convention)
+- `camelCase` for composables, functions, variables
+- Props: `camelCase` in script, `kebab-case` in templates: `prop: userName` → `<Comp :user-name="...">`
+- Events: `camelCase` with `defineEmits`: `update:modelValue`, `itemClicked`
+
+### Testing Considerations
+- Write composables as pure functions when possible — testable without component mounting
+- Use `@vue/test-utils` `mount()` / `shallowMount()` for component tests
+- Use Pinia test helpers: `createTestingPinia()` with `initialState`
+- Prefer testing behavior over implementation — test what the user sees, not internal state

package/build/templates/overlays/planner-architecture.mdx

@@ -0,0 +1,78 @@
+## ARCHITECTURE PLANNING GUIDELINES
+
+You are planning an **architectural change**. This affects system boundaries, component relationships, and data flow. Get it right — architecture mistakes are expensive to fix.
+
+### Discovery Phase — MANDATORY
+- **Map current component boundaries:** What modules/services exist? What are their responsibilities?
+- **Identify integration points:** How do components communicate? (function calls, HTTP, events, shared DB, message queue)
+- **Trace data flow:** Follow data from entry point to storage and back — document the full path
+- **Find coupling:** Where do components know too much about each other's internals?
+- **Identify the pain point:** What specific architectural problem are you solving? (scaling bottleneck, tangled dependencies, deployment coupling, etc.)
+
+### Design Principles
+- **Separation of concerns:** Each component has ONE reason to change
+- **Dependency direction:** Dependencies point inward (domain doesn't depend on infrastructure)
+- **Interface boundaries:** Define explicit contracts between components — not implicit coupling
+- **Minimize shared state:** Shared mutable state is the root of most architecture problems
+- **Design for the failure case:** What happens when a component is slow, down, or returns errors?
+
+### Task Structure — The Architecture Sequence
+
+```
+1. DEFINE INTERFACES / CONTRACTS
+   └─ Create the new interfaces, types, protocols that define component boundaries
+   └─ These are the contracts that consumers and implementors agree on
+   └─ No behavior change yet — just contracts
+
+2. IMPLEMENT CORE DOMAIN LOGIC
+   └─ Build the core business logic behind the new interfaces
+   └─ Pure functions and domain types — no infrastructure concerns
+   └─ Testable in isolation
+
+3. BUILD ADAPTERS
+   └─ Create adapters that connect domain logic to infrastructure (DB, HTTP, file system)
+   └─ Each adapter implements one interface
+   └─ Adapters are independently replaceable
+
+4. WIRE ORCHESTRATION
+   └─ Connect components through the defined interfaces
+   └─ Dependency injection or factory pattern for assembly
+   └─ Configuration and startup sequence
+
+5. INTEGRATION VERIFICATION
+   └─ End-to-end verification that all components work together
+   └─ Performance baseline to compare with previous architecture
+   └─ Migration plan for any data or state that needs to move
+```
+
+### Decision Documentation
+For each significant architectural decision, document using ADR (Architecture Decision Record) format:
+
+```markdown
+## ADR-[N]: [Title]
+
+**Status:** Proposed
+**Context:** [What problem are we facing?]
+**Decision:** [What we decided]
+**Consequences:**
+- [Positive consequence]
+- [Negative consequence / trade-off]
+**Reversibility:** [Easy / Hard / Irreversible] — [explanation]
+```
+
+**Classify decisions:**
+- **Reversible (two-way door):** Decide quickly, adjust later. Example: choosing a serialization format
+- **Irreversible (one-way door):** Think deeply, get input. Example: splitting a monolith, choosing a message broker
+
+### Risk Assessment — CRITICAL
+- **Migration complexity:** Can old and new architecture coexist during transition? (Strangler fig pattern)
+- **Data migration:** Does data need to move between systems/schemas? Plan this separately
+- **Performance regression:** Will the new architecture introduce latency (extra network hops, serialization)?
+- **Operational complexity:** More components = more things to deploy, monitor, debug
+- **Team impact:** Does the team understand the new architecture? Training needed?
+
+### Task Design
+- Each task: **one component or one boundary change**, independently deployable
+- Success criteria include: "Component X communicates with Y only through interface Z"
+- Never combine infrastructure changes with domain logic changes in one task
+- Include rollback strategy for each architectural change

package/build/templates/overlays/planner-bugfix.mdx

@@ -0,0 +1,36 @@
+## BUG FIX PLANNING GUIDELINES
+
+You are planning a **bug fix**. Root cause analysis is paramount — never plan a fix for symptoms.
+
+### Root Cause Analysis — DO THIS FIRST
+- **Reproduce the bug path:** Trace from user input → code execution path → failure point
+- **Identify the ROOT cause**, not just where the error appears — the error location and the bug location are often different
+- **Check:** Is this a single bug or a pattern? Search the codebase for similar code that might have the same issue
+- **Timeline:** When was this introduced? Was there a recent change that caused it? (`git log` the affected files)
+- **Scope:** Who is affected? All users? Specific conditions? Specific environments?
+
+### Fix Strategy — Minimal and Upstream
+- **Prefer minimal upstream fix** over downstream workaround — fix where the data goes wrong, not where the error surfaces
+- **Single-line fix if sufficient** — don't refactor adjacent code just because you're in the file
+- **Consider regressions:** Will this fix break anything else? Check all callers of the affected function
+- **Verify the fix concept** before planning implementation — does the logic actually solve the root cause?
+
+### Mandatory Task Structure
+Every bug fix plan MUST include these tasks:
+
+1. **Root cause documentation** — Write a clear explanation of what went wrong and why
+2. **The fix itself** — Minimal code change that addresses the root cause
+3. **Regression test** — A test that fails before the fix and passes after
+4. **Pattern check** — Search for the same bug pattern elsewhere in the codebase and fix if found
+
+### Task Design
+- Each task: **one file change**, clear before/after behavior
+- Success criteria: "Before fix: [behavior]. After fix: [behavior]"
+- Include the **exact error message, stack trace, or reproduction steps** in the Builder brief
+- Reference the **specific line numbers** where the bug occurs
+
+### Risk Assessment
+- **Regression risk:** What could this fix break? List explicitly
+- **Data impact:** Has bad data been written? Is cleanup needed?
+- **Deployment urgency:** Is this blocking production? Hotfix or normal release?
+- **Rollback plan:** If the fix causes new issues, what's the rollback?

package/build/templates/overlays/planner-feature.mdx

@@ -0,0 +1,38 @@
+## FEATURE PLANNING GUIDELINES
+
+You are planning a **new feature**. This requires comprehensive discovery and careful task design.
+
+### Discovery Phase — MANDATORY
+- **Map ALL touchpoints:** UI components, API endpoints, database tables, background services, third-party integrations
+- **Identify affected user flows** end-to-end — trace from user action to database and back
+- **Find existing patterns** for similar features in the codebase — the new feature should follow established conventions
+- **Audit dependencies:** What libraries/services does this feature need? Are they already available?
+- **Check for feature flags:** Does the project use feature flags? Should this be behind one?
+
+### Task Design — Sequence Matters
+1. **Data model first** — database migrations, schema changes, type definitions
+2. **Service/business logic layer** — core functionality without UI
+3. **API layer** — endpoints, request/response schemas, validation
+4. **UI integration** — components, state management, routing
+5. **Integration tests** — end-to-end verification
+
+Each task MUST have:
+- **Single deliverable** — one file or one behavior change
+- **Clear success criteria** — objective, testable conditions
+- **File paths** — exact paths the Builder needs to create/modify
+- **Patterns to follow** — reference existing code that does something similar
+
+### Risk Assessment
+- **New dependencies:** Do we need new packages? Version compatibility?
+- **Database migrations:** Reversible? Data backfill needed? Downtime?
+- **Backwards compatibility:** Does this break existing API consumers?
+- **Performance:** How does this scale? N+1 queries? Large payloads?
+- **Security:** New attack surface? Auth/authz implications?
+
+### Handoff Quality Checklist
+Before marking planning complete, verify:
+- [ ] Builder brief has EXACT file paths for every task
+- [ ] Every task references existing code patterns to follow
+- [ ] Success criteria are testable (not "works well" but "returns 200 with valid JWT")
+- [ ] Tester checklist covers: happy path, error cases, edge cases, visual checks
+- [ ] Dependencies between tasks are explicit and wave-grouped

package/build/templates/overlays/planner-migration.mdx

@@ -0,0 +1,50 @@
+## MIGRATION PLANNING GUIDELINES
+
+You are planning a **migration** (API version, database schema, library upgrade, framework change). Safety and reversibility are paramount.
+
+### Assessment Phase — MANDATORY
+- **Current state:** Document exactly what exists today — versions, schemas, dependencies, consumers
+- **Target state:** Document exactly what "done" looks like — new versions, new schemas, new APIs
+- **Scope:** List ALL affected files, services, database tables, API consumers, configuration files
+- **Breaking changes:** Explicitly list every breaking change between current and target state
+
+### Migration Strategy
+- **Incremental migration (strangler fig) PREFERRED** — replace piece by piece, not big-bang
+- **Coexistence period:** Can old and new run simultaneously during transition? Design for this
+- **Rollback plan is MANDATORY** — every migration task must be individually reversible
+- **Feature flags:** Use feature flags to control rollout if available in the project
+- **Data migration:** If database changes are involved, plan the data migration separately from schema migration
+
+### Phase Structure — Every Migration Plan Must Have These
+
+**Phase 1: Preparation (no behavior change)**
+- Add compatibility layers, adapters, new schemas alongside old
+- Add deprecation warnings to old code paths
+- Create migration utilities/scripts
+- All existing tests must still pass
+
+**Phase 2: Migration (gradual switchover)**
+- Switch consumers one at a time to new code paths
+- Run old and new in parallel where possible
+- Monitor for errors/regressions at each step
+- Each task independently deployable and rollback-able
+
+**Phase 3: Cleanup (remove old code)**
+- Remove deprecated code paths
+- Remove compatibility layers
+- Remove old schemas/migrations
+- Update documentation
+- This phase should be a SEPARATE plan — don't mix cleanup with migration
+
+### Risk Assessment — CRITICAL
+- **Data loss scenarios:** Can any migration step lose data? How is this prevented?
+- **Downtime requirements:** Does any step require downtime? How long? Can it be zero-downtime?
+- **Consumer impact:** Who depends on the old API/schema? Have they been notified?
+- **Performance regression:** Does the new version perform the same or better? Benchmark
+- **Rollback testing:** Has the rollback procedure been verified?
+
+### Task Design
+- Each task: **one migration step**, independently deployable, independently reversible
+- Success criteria include: "Rollback: [exact steps to undo this task]"
+- Never combine schema migration with data migration in one task
+- Never combine behavior changes with cleanup in one task

package/build/templates/overlays/planner-refactor.mdx

@@ -0,0 +1,57 @@
+## REFACTORING PLANNING GUIDELINES
+
+You are planning a **refactoring**. The codebase must work correctly at every step — never break it in the middle.
+
+### Assessment Phase — MANDATORY
+- **Identify the code smell or structural problem** — name it precisely (duplication, God class, feature envy, shotgun surgery, etc.)
+- **Map ALL usages** of the code you want to change — use `warpgrep_codebase_search` exhaustively
+- **Quantify blast radius:** How many files, functions, and callers are affected?
+- **Check for existing tests** — if tests cover the code, they're your safety net. If not, characterization tests come first
+- **Understand the current behavior completely** before planning any changes — refactoring changes structure, not behavior
+
+### Strategy — Strangler Fig Pattern
+- **Each task must leave the codebase in a working state** — never a "break it then fix it" sequence
+- **New code alongside old:** Introduce the new pattern/structure first, THEN migrate consumers, THEN remove old code
+- **Tests pass after every task** — if a task breaks tests, the task is too big or the approach is wrong
+- **Incremental over big-bang** — 5 small safe steps beat 1 large risky step
+
+### Task Structure — The Refactoring Sequence
+
+Every refactoring plan MUST follow this sequence:
+
+```
+1. ADD CHARACTERIZATION TESTS (if missing)
+   └─ Write tests that document current behavior
+   └─ These tests MUST pass before AND after every subsequent task
+
+2. INTRODUCE NEW PATTERN ALONGSIDE OLD
+   └─ Create the new abstraction/structure/function
+   └─ Old code still works unchanged
+   └─ Tests still pass
+
+3. MIGRATE CONSUMERS ONE-BY-ONE
+   └─ Each task migrates ONE consumer from old → new
+   └─ Tests pass after each migration
+   └─ Old and new coexist during this phase
+
+4. REMOVE OLD CODE
+   └─ Only after ALL consumers migrated
+   └─ Verify no remaining references
+   └─ Tests still pass
+
+5. VERIFY ALL TESTS PASS
+   └─ Full test suite run
+   └─ Manual verification of key flows if applicable
+```
+
+### Risk Assessment
+- **Behavioral change risk:** Refactoring should NOT change behavior. If it does, that's a feature change disguised as refactoring — split it
+- **Merge conflict risk:** Is anyone else working on these files? Coordinate or plan for conflict resolution
+- **Rollback plan per task:** Each task should be individually revertable with `git revert`
+- **Integration risk:** Does this refactoring affect API contracts, database queries, or external service calls?
+
+### Task Design
+- Each task: **one file or one logical change**, tests pass after
+- Success criteria: "Before: [code structure]. After: [code structure]. Behavior: unchanged"
+- Include the **exact code pattern** being replaced and the new pattern — Builder should not have to figure out the transformation
+- Reference the **specific functions/classes** being refactored with file paths and line ranges