plan-interface-contracts

name	plan-interface-contracts
description	Public function/method signatures per WP
argument-hint	Invoked by Planner Coordinator - do not call directly

plan-interface-contracts

Phase: 2 (Contract Generation) Common contract: .github/skills/PLAN-SKILL-CONTRACT.md Spec refs: FR-037, FR-038, FR-039

This skill is dispatched by the Planner Coordinator during Phase 2. It reads the plan accumulator (WP files from Phase 1) and generates language-specific interface contract files scoped per work package.

---

Input Contract (FR-023)

#	Input	Description
1	skill_path	Path to this SKILL.md file
2	plan_dir	Path to .sdd/plans/ directory
3	contracts_dir	Path to .sdd/plans/contracts/ directory
4	spec_path	Path to the source spec file
5	spec_artifacts_dir	Path to spec companion artifacts
6	research_summary	Key findings from the research phase
7	target_language	Programming language for contract generation
8	patterns	Active plan-domain patterns to avoid
9	phase	Phase indicator (always 2 for this skill)

---

Execution Sequence (FR-024)

1. Read SKILL.md - Load this file for contract generation instructions
2. Read plan state - Read README and all WP files to identify which WPs need interface contracts
3. Read spec + artifacts - Read the spec and the companion artifact interfaces.<ext> from spec_artifacts_dir. Read spec and artifact files in parallel.
4. Write contract files - Write interfaces.<ext> to contracts_dir/<WP-slug>/ per applicable WP

---

Step 1 - Analyze Plan Accumulator

Read the plan README and all WP files. For each WP, determine if it introduces or modifies:

1. Public functions or methods
2. Class or module interfaces (abstract classes, protocols, traits)
3. Module exports

Skip WPs that:

• Only modify configuration or documentation
• Only create test files
• Do not introduce any public API surface

Build a WP-to-interface mapping:

WP01 -> [UserService.create(), UserService.getById(), AuthMiddleware.verify()]
WP02 -> [OrderService.place(), OrderService.cancel(), PaymentGateway.charge()]
...

---

Step 2 - Read Spec Companion Artifact (FR-038)

Check if spec_artifacts_dir contains an interfaces.<ext> file. If it exists:

1. Parse the spec-level interface definitions
2. These are the canonical signatures -- WP-level contracts MUST match them
3. Extend (not modify) the spec artifact with WP-specific internal helpers

If the spec artifact does NOT exist:

• Generate interfaces from the spec prose (FR descriptions, API contracts, data model)
• Note in a comment that these were derived from spec prose, not from a companion artifact

---

Step 3 - Generate Interface Contract Files (FR-037)

For each applicable WP, generate <contracts_dir>/<WP-slug>/interfaces.<ext>:

3a. Manifest Header (FR-039)

Every contract file MUST start with the manifest header:

// Generated by: plan-interface-contracts skill
// Source spec: <spec_path>
// Work package: WP<NN>-<slug>
// Target language: <target_language>
// DO NOT EDIT MANUALLY -- regenerated on plan revision

Adjust comment syntax for the target language:

• TypeScript/JavaScript: //
• Python: #
• Go: //
• Java: //
• Rust: //

3b. Public Function/Method Signatures (FR-037.1)

For each public function or method the WP introduces:

// TypeScript example
export interface UserService {
  create(input: CreateUserInput): Promise<User>;
  getById(id: string): Promise<User | null>;
  update(id: string, input: UpdateUserInput): Promise<User>;
  delete(id: string): Promise<void>;
}

# Python example
from abc import ABC, abstractmethod

class UserService(ABC):
    @abstractmethod
    async def create(self, input: CreateUserInput) -> User: ...
    @abstractmethod
    async def get_by_id(self, id: str) -> User | None: ...

Requirements:

• All parameters MUST be typed
• All return types MUST be specified
• Async/sync MUST match the spec's design
• No implementation bodies -- type signatures only

3c. Class/Module Interface Definitions (FR-037.2)

For abstract classes, protocols, traits, or interface types:

• Define the full interface contract
• Include property types for class-level attributes
• Include method signatures for all public methods

3d. Module Export Definitions (FR-037.3)

For module-level exports:

• List all public exports from the module
• Include re-exports from sub-modules if applicable

---

Step 4 - Scope Contracts to WP and Write Shared Contracts (FR-037, FR-038)

Each WP's interface file MUST contain ONLY the interfaces that WP introduces or modifies:

• Do NOT duplicate interfaces from other WPs
• If a WP extends an interface from a prior WP, import the base interface and re-export the extended version

Shared interface contracts

For interfaces that will be consumed by subsequent WPs:

1. Write the interface definition to BOTH <contracts_dir>/<WP-slug>/interfaces.<ext> AND <contracts_dir>/shared/interfaces.<ext>.
2. The shared file accumulates interface definitions across WPs -- append new interfaces to it; do NOT overwrite existing content.
3. Subsequent WPs' contract files SHALL import shared interfaces from ../shared/interfaces rather than from the owning WP's directory.
4. If <contracts_dir>/shared/interfaces.<ext> does not exist, create it with the standard manifest header.

Import syntax by language:

• TypeScript: import { UserService } from '../shared/interfaces';
• Python: from ..shared.interfaces import UserService

---

Step 5 - 800-Line Block Compliance (FR-013)

If a WP's interface file exceeds 800 lines:

1. Split the generation into multiple write operations
2. Read the prior output before writing the next block
3. Ensure the final file is valid syntax

For most WPs, interface files will be well under 800 lines.

---

Constraints

• Output MUST be valid syntax in the target language -- the file must parse without errors
• Do NOT include implementation bodies, business logic, or test code in contract files
• Do NOT modify WP markdown files -- read only
• Do NOT modify spec artifacts -- read only
• Only write to <contracts_dir>/<WP-slug>/interfaces.<ext>
• Use plain ASCII hyphens and straight quotes only -- no em dashes, smart quotes, or curly apostrophes