creating-spec

What this skill does

# Creating Spec

Systematic workflow for creating comprehensive technical specifications that centralize scattered functionality, fill SDK gaps, or plan new feature modules. This skill encodes the proven process used to produce high-quality specs like session-management and tool-registry-bridge specs.

<critical_rules>

## MANDATORY WORKFLOW

You MUST follow these phases in order. Skipping phases or combining them will produce incomplete specs.

### Phase 1: DEEP EXPLORATION (output only, no writes)

**Goal**: Map the full landscape of existing code across ALL relevant codebases before proposing anything.

1. **Launch parallel exploration agents** (4-5 simultaneous) covering:
   - The target package where the spec will be implemented (e.g., `providers/sdk`)
   - The reference implementation that has the most complete version (e.g., `providers/runtime`)
   - Consumer codebases that have their own versions (e.g., `packages/electron/src/agents/`, `packages/electron/src/looper/`)
   - Any shared packages that contain related types or utilities (e.g., `packages/types`)

2. **Each explorer must report**:
   - File paths with key types/interfaces
   - How components connect and interact
   - What patterns are used (Effect services, Context.Tag, factories, etc.)
   - Duplication and fragmentation across codebases

3. **MANDATORY**: Read the key files directly after exploration to verify findings. Do NOT rely solely on explorer summaries for type signatures or API shapes.

4. **Present findings FIRST** — show the user:
   - A cross-codebase comparison table (what exists where)
   - A duplication map (what's doing the same thing in multiple places)
   - What should be centralized vs. what should stay where it is
   - Clear identification of gaps

**FORBIDDEN**: Writing any files during Phase 1. Output analysis to chat only.

### Phase 2: CLARIFICATION (ask questions before writing)

**Goal**: Resolve design decisions that affect the spec's architecture.

1. **Use the AskUserQuestion tool** to ask 2-4 focused questions about:
   - Scope decisions (full replacement vs. building blocks vs. thin wrapper)
   - Automation level (fully automatic vs. manual vs. hybrid)
   - Backward compatibility concerns (native support vs. consumer handles)
   - What to include vs. exclude from the centralized module

2. **Question format**:
   - Each question should have 2-3 concrete options with descriptions
   - Mark the recommended option with "(Recommended)"
   - Options should represent genuinely different architectural choices, not trivial preferences

3. **MANDATORY**: Wait for user answers before proceeding. Do NOT assume defaults.

**FORBIDDEN**: Asking more than 4 questions at once. Keep it focused on decisions that materially affect the spec.

### Phase 3: SPEC WRITING

**Goal**: Write a comprehensive specification at the right level of abstraction — behavioral contracts and architectural decisions, not implementation code.

1. **Check existing spec format** — Read any previous specs in the same directory (e.g., `tasks/prd-sdk/1_*.md`, `tasks/prd-sdk/2_*.md`) to match the established style and structure.

2. **Write the spec** following the template structure below.

3. **MANDATORY sections** (all must be present):
   - Problem Statement (what's broken/duplicated, what it costs today)
   - Design overview (architecture diagram in ASCII, high-level flow)
   - New files (directory structure)
   - Detailed API specifications (interfaces, types, service tags)
   - What this replaces (file-by-file mapping of what changes where)
   - Interaction with existing systems (how it coexists with what's already there)
   - Public API surface (explicit exports list)
   - High-Level Implementation Overview (consumer-facing code examples)
   - Testing strategy (unit + integration test plans)
   - Implementation order (numbered steps with dependencies and parallelization)
   - Migration path (phased rollout for existing consumers)
   - What does NOT move (explicit exclusion list with reasons)

### Phase 3b: EFFECT-TS COMPLIANCE CHECK

**Goal**: Verify all code snippets in the spec follow Effect-TS patterns before presenting to the user.

**MANDATORY**: After writing the spec, audit every code snippet against the `effect-ts` and `effect-ts` skills. Check:

1. **Import patterns**: Must use `import * as Module from "effect/Module"`, never `import { X } from "effect"`
2. **Branded types**: All domain primitives (IDs, keys, names) must be branded via `Schema.String.pipe(Schema.brand("X"))`. Check existing `protocol/branded.ts` for established patterns.
3. **Schema class patterns**: `Schema.Class` for records, `Schema.TaggedClass` for discriminated variants (events, status types). Check how existing events in `protocol/events.ts` are defined and match exactly.
4. **No `Schema.Unknown`**: Use `JsonValue`, `JsonObject` (from `protocol/shared.ts`), or `Schema.Defect` (for wrapping external errors). Never `Schema.Unknown` or bare `unknown` in types.
5. **No `Schema.Enums`**: Use `Schema.Literal("a", "b", "c")` for string literal unions. `Schema.Enums` is only for TypeScript `enum` types.
6. **No `Schema.suspend`**: Only for recursive types. Not needed for referencing other schemas.
7. **Service pattern**: Services must use `Context.Tag` with static factory methods and static `layer`. Never module-scoped functions for service logic or layer factories.
8. **Static helpers**: Helper/utility functions must be static methods on a helper class (e.g., `MyHelpers.resolve()`), not module-scoped `export const` functions.
9. **`Effect.fn` tracing**: All service method implementations must specify `Effect.fn("ServiceName.methodName")` for observability. Note this requirement explicitly in the spec.
10. **Error handling**: Domain errors use `Schema.TaggedError`. Unknown external errors wrapped with `Schema.Defect`. No `unknown` in error channels.
11. **Secrets**: API keys and sensitive values use `Redacted.Redacted`, not plain `string`.
12. **Testability**: Use `Clock.currentTimeMillis` instead of `Date.now()` or raw `clock` callbacks. Effect's `TestClock` handles test time control.
13. **Immutable state**: Service state must be held in `Ref` or `SynchronizedRef`, not mutable `Map`/`Set`. Prefer `HashMap.HashMap` from Effect.
14. **Schema.Class construction**: When returning instances of `Schema.Class` types, always use `new ClassName({...})` constructors, not plain object literals.

### Phase 3c: CROSS-SPEC CONSISTENCY CHECK

**Goal**: Ensure the new spec doesn't contradict or duplicate definitions from other specs.

**MANDATORY**: Before finalizing, check against all existing specs in the same directory:

1. **No duplicate definitions**: If a type, constant, or function is already defined in another spec, import it — don't redefine. Common sources of duplication:
   - Provider family resolution functions
   - Provider metadata key fallback maps
   - Type definitions that span multiple concerns
2. **Consistent naming**: Same concept must have the same name across all specs. If Spec N defines `ProviderFamilyId`, Spec N+1 must not call it `OpenResponsesProviderFamily`.
3. **Compatible types**: If two specs extend the same interface (e.g., `CompozyCallProviderOptions`), list ALL fields from all specs, not just yours.
4. **Implementation ordering**: If your spec depends on a type expansion from another spec (e.g., `ProviderId` growing from 3 to 11 values), document this dependency explicitly in the Implementation Order section.
5. **Canonical ownership**: Each type/function/constant must have ONE canonical source file. The spec that defines it is the owner. All other specs that need it must say "Import from `src/path/file.ts` (defined in Spec N)".

### Phase 4: HIGH-LEVEL IMPLEMENTATION (iterate if asked)

**Goal**: Show concrete consumer-facing API examples that demonstrate how the final result works.

1. **Include in the spec** a "High-Level Implementation Overview" section with:
   - Setup / configuration co