API Contract

Overview

API Contract guides the creation of api-contract.md files that serve as the shared interface between backend and frontend agents during sprint execution. The contract defines request/response schemas, endpoint routes, TypeScript interfaces, and error formats so that implementation agents build to an agreed specification without direct coordination.

Prerequisites

• Sprint directory initialized at .claude/sprint/[N]/
• specs.md with defined feature scope and endpoint requirements
• Familiarity with RESTful API conventions (HTTP methods, status codes, JSON schemas)
• TypeScript knowledge for interface definitions (recommended)

Instructions

1. Create api-contract.md in the sprint directory (.claude/sprint/[N]/api-contract.md). Define each endpoint using the standard format: HTTP method, route path, description, request body, response body with status code, and error codes. See ${CLAUDESKILLDIR}/references/writing-endpoints.md for the full template.
2. Define TypeScript interfaces for all request and response types. Use explicit types instead of any, mark optional fields with ?, and use string | null for nullable values. Reference ${CLAUDESKILLDIR}/references/typescript-interfaces.md for canonical type patterns.
3. For list endpoints, include pagination parameters and the PaginatedResponse wrapper. Standardize on page, limit, sort, and order query parameters as documented in ${CLAUDESKILLDIR}/references/pagination.md.
4. Document all response states: success (200, 201, 204), client errors (400, 401, 403, 404, 422), and empty states. Use a consistent error response format with code, message, and optional details fields.
5. Follow best practices from ${CLAUDESKILLDIR}/references/best-practices.md: be specific about field constraints (e.g., "string, required, valid email format"), include request/response examples, reference shared types instead of duplicating, and omit implementation details (no database columns, framework names, or file paths).
6. Share the contract file path in SPAWN REQUEST blocks so both backend and frontend agents read the same interface definition.

Output

• api-contract.md containing all endpoint definitions with typed request/response schemas
• TypeScript interface declarations for User, CreateUserRequest, LoginRequest, AuthResponse, ApiError, and domain-specific types
• Paginated response wrappers for list endpoints
• Standardized error format across all endpoints

Spec Writing

Overview

Spec Writing provides guidance on authoring effective specs.md files that drive the Sprint plugin's autonomous development workflow. A well-written specification determines the quality of agent output by clearly defining goals, scope boundaries, and testing requirements.

Prerequisites

• Sprint plugin installed (/plugin install sprint)
• Project onboarding completed via /sprint:setup (creates project-goals.md and project-map.md)
• Sprint directory created via /sprint:new (generates .claude/sprint/[N]/specs.md)
• Understanding of the sprint phase lifecycle (see the sprint-workflow skill)

Instructions

1. Open the generated specs.md file at .claude/sprint/[N]/specs.md and define a concise goal statement at the top. State what the sprint delivers in one sentence (e.g., "Add user authentication with email/password login").
2. Define explicit scope boundaries using In Scope and Out of Scope sections. List specific features, endpoints, or components in each. Agents only implement what appears in scope; ambiguity leads to drift.
3. Add the Testing section to control which testing agents run and how. Configure three settings as documented in ${CLAUDESKILLDIR}/references/testing-configuration.md:

• QA: required | optional | skip -- Controls API and unit test execution
• UI Testing: required | optional | skip -- Controls browser-based E2E tests
• UI Testing Mode: automated | manual -- Auto-run or user-driven testing

1. Set QA to required for new API endpoints, business logic changes, and data validation rules. Set QA to skip for frontend-only changes, documentation updates, or configuration changes.
2. Set UI Testing to required for user-facing features, form submissions, and navigation flows. Choose automated mode for regression testing and standard CRUD flows; choose manual mode for complex interactions, visual verification, or exploratory testing.
3. Keep specifications minimal but precise. The architect expands high-level specs into detailed implementation files (backend-specs.md, frontend-specs.md, api-contract.md). Over-specifying implementation details in specs.md constrains the architect unnecessarily.
4. For iterative sprints, review status.md from the previous iteration. Remove completed items from specs and add any new requirements or bug fixes discovered during testing.

Output