.opencode/gsd-core/references/planner-interface-context.md

Interface Context for Executors

Key insight: "The difference between handing a contractor blueprints versus telling them 'build me a house.'"

When creating plans that depend on existing code or create new interfaces consumed by other plans:

For plans that USE existing code:

After determining files_modified, extract the key interfaces/types/exports from the codebase that executors will need:

# Extract type definitions, interfaces, and exports from relevant files
grep -n "export\\|interface\\|type\\|class\\|function" {relevant_source_files} 2>/dev/null | head -50

Embed these in the plan's <context> section as an <interfaces> block:

<interfaces>
<!-- Key types and contracts the executor needs. Extracted from codebase. -->
<!-- Executor should use these directly — no codebase exploration needed. -->

From src/types/user.ts:
```typescript
export interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

From src/api/auth.ts:

export function validateToken(token: string): Promise<User | null>;
export function createSession(user: User): Promise<SessionToken>;

```

For plans that CREATE new interfaces:

If this plan creates types/interfaces that later plans depend on, include a "Wave 0" skeleton step:

<task type="auto">
  <name>Task 0: Write interface contracts</name>
  <files>src/types/newFeature.ts</files>
  <action>Create type definitions that downstream plans will implement against. These are the contracts — implementation comes in later tasks.</action>
  <verify>File exists with exported types, no implementation</verify>
  <done>Interface file committed, types exported</done>
</task>

When to include interfaces:

• Plan touches files that import from other modules → extract those module's exports
• Plan creates a new API endpoint → extract the request/response types
• Plan modifies a component → extract its props interface
• Plan depends on a previous plan's output → extract the types from that plan's files_modified

When to skip:

• Plan is self-contained (creates everything from scratch, no imports)
• Plan is pure configuration (no code interfaces involved)
• Level 0 discovery (all patterns already established)