pn-slice-contracts

Slice contracts

When used as a standalone skill, begin every response with [pn-skill] 🔺

When to use

Use this skill at feature_program step 1 to define and lock interface contracts between slices, and to generate .cursor/worktrees.json. Also use at step 4 (verifier gate) to author contract-conformance tests and interpret verifier reports.

Purpose

Contracts are the seams between slices. They must be locked before fan-out so every slice works against the same interface. Without locked contracts, parallel agents invent incompatible field names (userId vs user_id vs uid) and the merge phase becomes a semantic debugging session.

Contract types and when to use each

Type	When	Example
TypeScript interfaces	Shared data models, request/response shapes in a TS monorepo	interface CreateOrderRequest { userId: string; items: OrderItem[] }
JSON Schema	Language-agnostic APIs, config files, event envelopes	{ "type": "object", "properties": { "userId": { "type": "string" } } }
OpenAPI stubs	REST endpoints consumed across slices	paths: /orders: post: requestBody: ...
GraphQL schema fragment	Shared types in a GraphQL API	type Order { id: ID! userId: ID! items: [OrderItem!]! }

Use the simplest format that covers the consuming slice's needs. TypeScript interfaces for all-TS repos; OpenAPI stubs when contracts cross language boundaries.

Where contracts live

docs/refs/contracts/<programSlug>/
├── shared-types.ts         ← TypeScript shared interfaces
├── api-stubs.yaml          ← OpenAPI stubs (paths only, no implementation)
├── events.schema.json      ← JSON Schema for event envelopes
└── README.md               ← Contract index (auto-generated at step 1)

Rules:

• All contract files live in docs/refs/contracts/<programSlug>/.
• Contract files are read-only to slice worktrees — slices consume but do not edit them.
• Any edit to contracts re-triggers step 1 review (major patch path).