Agent Patterns

Overview

Agent Patterns defines the coordination protocol for multi-agent sprint execution within the Sprint plugin. It governs how the project architect spawns implementation and testing agents, how agents communicate results via structured reports, and how parallel agents avoid conflicts.

Prerequisites

• Sprint plugin installed and configured (/plugin install sprint)
• Sprint directory initialized at .claude/sprint/[N]/
• specs.md written with clear scope and testing configuration
• Familiarity with the sprint phase lifecycle (see the sprint-workflow skill)

Instructions

1. Structure every agent spawn using the SPAWN REQUEST format. Include the agent name, the specification file it should read, and any scope constraints:

   SPAWN REQUEST
   Agent: python-dev
   Specs: .claude/sprint/1/backend-specs.md
   Contract: .claude/sprint/1/api-contract.md
   Scope: Authentication endpoints only

1. Ensure each spawned agent receives only the files relevant to its scope. Pass the api-contract.md as a shared interface so backend and frontend agents stay synchronized.
2. Collect structured reports from every agent upon completion. Each report must include: work completed, files modified, tests added, and conformity status against the specification.
3. When running agents in parallel, partition work by domain boundary (e.g., backend vs. frontend vs. CI/CD). Never assign overlapping file paths to concurrent agents.
4. Feed agent reports back to the project architect for review. The architect decides whether to iterate (re-spawn with narrowed specs) or advance to the next phase.
5. For testing agents, pass the UI test report format shown in ${CLAUDE_SKILL_DIR}/references/ui-test-report.md so results follow a consistent schema including test counts, coverage, failures, and console errors.

Output

• SPAWN REQUEST blocks consumed by the sprint orchestrator to launch agents
• Structured agent reports containing: summary, files changed, test results, and conformity status
• UI test reports with pass/fail counts, coverage details, failure descriptions, and console error logs
• Updated status.md reflecting completed and remaining work after each iteration

Error Handling

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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/references/typescript-interfaces.md for canonical type patterns.
3. For list endpoints, include pagination parameters and the PaginatedResponse<T> wrapper. Standardize on page, limit, sort, and order query parameters as documented in ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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

E…

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 ${CLAUDE_SKILL_DIR}/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.

Sprint Workflow

Overview

Sprint Workflow describes the convergent diffusion execution model used by the Sprint plugin. A sprint progresses through six distinct phases -- from loading specifications through architectural planning, parallel implementation, testing, review, and finalization.

Prerequisites

• Sprint plugin installed (/plugin install sprint)
• Project onboarded via /sprint:setup (creates .claude/project-goals.md and .claude/project-map.md)
• Sprint created via /sprint:new with a completed specs.md
• Understanding of the agent system (see the agent-patterns skill)

Instructions

1. Phase 0 -- Load Specifications. The orchestrator locates the sprint directory at .claude/sprint/[N]/, reads specs.md for requirements, reads status.md if resuming a prior iteration, and detects the project type for framework-specific agent selection. See ${CLAUDE_SKILL_DIR}/references/sprint-phases.md for the full phase reference.
2. Phase 1 -- Architectural Planning. The project-architect agent reads project-map.md for architecture context and project-goals.md for business objectives. It produces specification files (api-contract.md, backend-specs.md, frontend-specs.md) and returns SPAWN REQUEST blocks for implementation agents.
3. Phase 2 -- Implementation. The orchestrator spawns implementation agents in parallel based on the architect's SPAWN REQUEST blocks. Agents include python-dev, nextjs-dev, cicd-agent, and allpurpose-agent. Each agent reads its assigned spec files and the shared api-contract.md, then returns a structured report.
4. Phase 3 -- Testing. Testing agents execute sequentially: qa-test-agent runs first (API and unit tests), then ui-test-agent runs browser-based E2E tests. Framework-specific diagnostics agents (e.g., nextjs-diagnostics-agent) run in parallel with UI tests. All agents produce test reports.
5. Phase 4 -- Review and Iteration. The architect reviews all agent reports, analyzes conformity against specifications, updates specs (removing completed items, adding fixes for failures), and updates status.md. The architect then decides: spawn more implementation agents, run more tests, or finalize.
6. Phase 5 -- Finalization. The orchestrator writes the final status.md summary, ensures all spec files are in a consistent state, cleans up temporary files like manual-test-report.md, and signals FINALIZE to end the sprint.
7. Convergence model.…