@intentsolutionsio/sprint 1.0.0

package/skills/agent-patterns/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: agent-patterns
+description: |
+  Execute this skill should be used when the user asks about "SPAWN REQUEST format", "agent reports", "agent coordination", "parallel agents", "report format", "agent communication", or needs to understand how agents coordinate within the sprint system. Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.
+allowed-tools: Read
+version: 1.0.0
+author: Damien Laine <damien.laine@gmail.com>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [community, agent-patterns]
+---
+# 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
+   ```
+2. 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.
+3. Collect structured reports from every agent upon completion. Each report must include: work completed, files modified, tests added, and conformity status against the specification.
+4. 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.
+5. 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.
+6. 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
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Agent receives wrong specification file | Incorrect path in SPAWN REQUEST | Verify the sprint directory number and file name before spawning |
+| Overlapping file modifications from parallel agents | Scope boundaries not clearly defined | Partition work by domain; assign distinct directories to each agent |
+| Agent report missing required fields | Agent instructions lack report format | Include the structured report template in the agent prompt |
+| Infinite iteration loop | Specs never fully satisfied | Check `status.md` for blocking issues; the orchestrator pauses after 5 iterations |
+| Agent not found | Misspelled agent name in SPAWN REQUEST | Verify agent markdown files exist in `agents/` directory |
+
+## Examples
+
+**Spawning parallel implementation agents:**
+```
+SPAWN REQUEST
+Agent: python-dev
+Specs: .claude/sprint/1/backend-specs.md
+Contract: .claude/sprint/1/api-contract.md
+
+SPAWN REQUEST
+Agent: nextjs-dev
+Specs: .claude/sprint/1/frontend-specs.md
+Contract: .claude/sprint/1/api-contract.md
+```
+Both agents share the same `api-contract.md` to ensure API compatibility.
+
+**Structured agent report format:**
+```
+AGENT REPORT
+Agent: python-dev
+Status: COMPLETE
+Files Modified: src/auth/routes.py, src/auth/models.py, tests/test_auth.py
+Tests: 12 passed, 0 failed
+Conformity: All backend-specs requirements implemented
+Notes: JWT token expiry set to 24h per spec
+```
+
+**Testing agent coordination:**
+```
+SPAWN REQUEST
+Agent: qa-test-agent
+Specs: .claude/sprint/1/specs.md
+Run After: python-dev, nextjs-dev
+
+SPAWN REQUEST
+Agent: ui-test-agent
+Specs: .claude/sprint/1/specs.md
+Run After: qa-test-agent
+```
+
+## Resources
+
+- `${CLAUDE_SKILL_DIR}/references/ui-test-report.md` -- Structured UI test report format with coverage and failure tracking
+- Sprint workflow skill for phase lifecycle context
+- API contract skill for shared interface design
+- Sprint plugin README for agent architecture overview

package/skills/agent-patterns/references/errors.md

@@ -0,0 +1,8 @@
+# Error Handling Reference
+
+- Invalid input: Prompts for correction
+- Missing dependencies: Lists required components
+- Permission errors: Suggests remediation steps
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/agent-patterns/references/examples.md

@@ -0,0 +1,291 @@
+# Examples
+
+## Example 1: Spawning a Single Implementation Agent
+
+The simplest pattern: one agent implementing one spec file with a shared contract.
+
+**SPAWN REQUEST block:**
+```
+SPAWN REQUEST
+Agent: python-dev
+Specs: .claude/sprint/1/backend-specs.md
+Contract: .claude/sprint/1/api-contract.md
+Scope: All backend endpoints
+```
+
+**Agent reads these files, implements, then returns:**
+```
+AGENT REPORT
+Agent: python-dev
+Status: COMPLETE
+Files Modified:
+  - src/routes/users.py (created)
+  - src/models/user.py (created)
+  - src/middleware/auth.py (created)
+  - tests/test_users.py (created)
+Tests: 15 added, 15 passing
+Conformity: All endpoints match api-contract.md schemas
+Notes: Used bcrypt for password hashing per spec requirement
+```
+
+## Example 2: Parallel Agent Spawns with Domain Partitioning
+
+Multiple agents running concurrently, each assigned to a non-overlapping domain
+boundary to prevent file conflicts.
+
+**Architect produces three SPAWN REQUEST blocks:**
+```
+SPAWN REQUEST
+Agent: python-dev
+Specs: .claude/sprint/2/backend-specs.md
+Contract: .claude/sprint/2/api-contract.md
+Scope: REST API endpoints and database models
+
+SPAWN REQUEST
+Agent: nextjs-dev
+Specs: .claude/sprint/2/frontend-specs.md
+Contract: .claude/sprint/2/api-contract.md
+Scope: React components and page routes
+
+SPAWN REQUEST
+Agent: cicd-agent
+Specs: .claude/sprint/2/infra-specs.md
+Scope: Docker, GitHub Actions, and deployment configs
+```
+
+**Domain boundaries (no file overlap):**
+```
+python-dev  → src/api/*, src/models/*, tests/api/*
+nextjs-dev  → app/*, components/*, tests/ui/*
+cicd-agent  → .github/workflows/*, Dockerfile, docker-compose.yml
+```
+
+**All three agents run simultaneously. Reports collected:**
+```
+AGENT REPORT
+Agent: python-dev
+Status: COMPLETE
+Files Modified: src/api/products.py, src/models/product.py, tests/api/test_products.py
+Tests: 22 added, 22 passing
+Conformity: All 6 backend endpoints match contract
+
+AGENT REPORT
+Agent: nextjs-dev
+Status: COMPLETE
+Files Modified: app/products/page.tsx, components/ProductCard.tsx, components/SearchBar.tsx
+Tests: 8 component tests added
+Conformity: All UI components consume contract-defined response types
+
+AGENT REPORT
+Agent: cicd-agent
+Status: COMPLETE
+Files Modified: .github/workflows/ci.yml, Dockerfile, docker-compose.yml
+Tests: CI pipeline validated locally
+Conformity: Deployment config targets correct service ports
+```
+
+## Example 3: Testing Agent Coordination (Sequential)
+
+Testing agents must run after implementation agents complete. QA runs first,
+then UI testing runs after QA passes.
+
+**Sequential SPAWN REQUEST chain:**
+```
+SPAWN REQUEST
+Agent: qa-test-agent
+Specs: .claude/sprint/3/specs.md
+Run After: python-dev, nextjs-dev
+Contract: .claude/sprint/3/api-contract.md
+Scope: API integration tests and unit test validation
+
+SPAWN REQUEST
+Agent: ui-test-agent
+Specs: .claude/sprint/3/specs.md
+Run After: qa-test-agent
+Scope: Browser-based E2E tests for all user flows
+```
+
+**QA agent report:**
+```
+AGENT REPORT
+Agent: qa-test-agent
+Status: COMPLETE
+Tests:
+  - API tests: 34 passed, 2 failed
+  - Unit tests: 67 passed, 0 failed
+  - Coverage: 89%
+Failures:
+  1. POST /api/orders returns 500 when cart is empty (expected 400)
+  2. GET /api/orders/:id returns stale cache after update
+
+Conformity: 2 endpoints deviate from api-contract.md error codes
+```
+
+**UI test agent report (using structured format):**
+```
+AGENT REPORT
+Agent: ui-test-agent
+Status: COMPLETE
+Tests:
+  - E2E scenarios: 12 passed, 1 failed
+  - Visual regression: 0 changes detected
+Failures:
+  1. Checkout flow: Submit button stays disabled after form validation passes
+     Screenshot: .claude/sprint/3/screenshots/checkout-button-disabled.png
+
+Console Errors:
+  - TypeError: Cannot read property 'validate' of undefined (checkout.tsx:45)
+
+Conformity: Checkout flow blocked by frontend validation bug
+```
+
+## Example 4: Architect Review and Iteration Decision
+
+After collecting all agent reports, the architect decides whether to iterate
+or finalize.
+
+**Architect receives reports from Iteration 1:**
+```
+python-dev: COMPLETE (all endpoints working)
+nextjs-dev: COMPLETE (all components rendered)
+qa-test-agent: 2 failures (empty cart 500, stale cache)
+ui-test-agent: 1 failure (checkout button disabled)
+```
+
+**Architect analysis:**
+```
+Conformity Review:
+  ✓ 4/6 API endpoints fully conformant
+  ✗ POST /api/orders: Missing empty-cart validation (backend fix)
+  ✗ GET /api/orders/:id: Cache invalidation missing (backend fix)
+  ✗ Checkout form: Validation state not propagating (frontend fix)
+
+Decision: ITERATE
+Reason: 3 targeted fixes needed, all within clear scope
+
+Updated backend-specs.md:
+  - REMOVED: All completed endpoint specs
+  - ADDED: Fix empty cart → return 400 with ApiError
+  - ADDED: Invalidate order cache on PATCH/DELETE
+
+Updated frontend-specs.md:
+  - REMOVED: All completed component specs
+  - ADDED: Fix checkout form validation state propagation
+
+Updated status.md:
+  Iteration 1: 3/6 user stories complete. 3 fixes needed.
+```
+
+**Architect spawns narrowed Iteration 2:**
+```
+SPAWN REQUEST
+Agent: python-dev
+Specs: .claude/sprint/3/backend-specs.md
+Contract: .claude/sprint/3/api-contract.md
+Scope: Fix empty-cart validation and cache invalidation only
+
+SPAWN REQUEST
+Agent: nextjs-dev
+Specs: .claude/sprint/3/frontend-specs.md
+Scope: Fix checkout form validation state only
+```
+
+## Example 5: Framework-Specific Agent Selection
+
+The orchestrator detects the project framework and selects appropriate
+specialized agents.
+
+**Project detection:**
+```
+Phase 0 scan:
+  → Found: next.config.js → Framework: Next.js
+  → Found: requirements.txt with fastapi → Backend: FastAPI
+  → Found: docker-compose.yml → Infrastructure: Docker
+
+Agent selection:
+  → nextjs-dev (instead of generic frontend agent)
+  → python-dev (instead of generic backend agent)
+  → cicd-agent (for Docker + CI pipeline)
+```
+
+**For a different project stack:**
+```
+Phase 0 scan:
+  → Found: nuxt.config.ts → Framework: Nuxt 3
+  → Found: package.json with express → Backend: Express.js
+  → Found: serverless.yml → Infrastructure: AWS Lambda
+
+Agent selection:
+  → allpurpose-agent with Nuxt context (no nuxt-specific agent exists)
+  → allpurpose-agent with Express context
+  → cicd-agent with serverless framework context
+```
+
+## Example 6: Handling Agent Failures
+
+When an agent fails to produce a valid report or encounters unrecoverable errors.
+
+**Failed agent report:**
+```
+AGENT REPORT
+Agent: python-dev
+Status: FAILED
+Error: Cannot install dependency 'psycopg2-binary' — compilation fails on arm64
+Files Modified: None
+Tests: None
+Conformity: Unable to assess — implementation did not start
+```
+
+**Architect response:**
+```
+Architect reviews failure:
+  → Root cause: platform-specific dependency issue
+  → Resolution: Switch to 'asyncpg' (pure Python, no compilation)
+  → Updates backend-specs.md: Replace psycopg2-binary with asyncpg
+
+SPAWN REQUEST
+Agent: python-dev
+Specs: .claude/sprint/1/backend-specs.md (updated)
+Contract: .claude/sprint/1/api-contract.md
+Scope: All backend endpoints (retry with asyncpg)
+Notes: Use asyncpg instead of psycopg2-binary for PostgreSQL
+```
+
+## Example 7: Scoped Agent with File Path Constraints
+
+When agents need strict boundaries to prevent overlapping modifications.
+
+**Tightly scoped SPAWN REQUEST:**
+```
+SPAWN REQUEST
+Agent: python-dev
+Specs: .claude/sprint/5/backend-specs.md
+Contract: .claude/sprint/5/api-contract.md
+Scope: Payment processing endpoints only
+Allowed Paths:
+  - src/payments/**
+  - tests/payments/**
+  - src/models/payment.py
+Forbidden Paths:
+  - src/auth/**
+  - src/users/**
+  - src/orders/** (owned by another agent in this iteration)
+```
+
+**Agent respects boundaries in its report:**
+```
+AGENT REPORT
+Agent: python-dev
+Status: COMPLETE
+Files Modified:
+  - src/payments/routes.py (created)
+  - src/payments/stripe_client.py (created)
+  - src/models/payment.py (created)
+  - tests/payments/test_payments.py (created)
+Tests: 9 added, 9 passing
+Conformity: All payment endpoints match contract
+Notes: Did not modify src/orders/ — referenced via import only
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/agent-patterns/references/ui-test-report.md

@@ -0,0 +1,35 @@
+# Ui Test Report
+
+## UI TEST REPORT
+
+### MODE
+AUTOMATED
+
+### SUMMARY
+- Total tests run: 8
+- Passed: 7
+- Failed: 1
+- Session duration: 45s
+
+### COVERAGE
+- Scenarios covered:
+  - Login with valid credentials
+  - Login with invalid password
+  - Registration flow
+  - Password reset request
+- Not covered (yet):
+  - Email verification flow (requires email testing setup)
+
+### FAILURES
+- Scenario: Registration validation
+  - Path/URL: /register
+  - Symptom: Error message not displayed
+  - Expected: "Email already exists" message
+  - Actual: Form submits without feedback
+
+### CONSOLE ERRORS
+None.
+
+### NOTES FOR ARCHITECT
+- Registration error handling needs frontend fix
+```

package/skills/api-contract/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: api-contract
+description: |
+  Configure this skill should be used when the user asks about "API contract", "api-contract.md", "shared interface", "TypeScript interfaces", "request response schemas", "endpoint design", or needs guidance on designing contracts that coordinate backend and frontend agents. Use when building or modifying API endpoints. Trigger with phrases like 'create API', 'design endpoint', or 'API scaffold'.
+allowed-tools: Read
+version: 1.0.0
+author: Damien Laine <damien.laine@gmail.com>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [community, api, typescript]
+---
+# 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
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Backend and frontend schemas diverge | Contract updated without notifying both agents | Always reference a single `api-contract.md`; never duplicate endpoint definitions |
+| Missing error response codes | Contract only documents the happy path | Document all status codes: 400, 401, 403, 404, 409, 422 per endpoint |
+| Ambiguous field types | Using `string` without constraints | Specify format, length, and validation rules (e.g., "string, required, min 8 chars") |
+| Pagination inconsistency | List endpoints use different parameter names | Standardize on the `PaginatedResponse<T>` interface for all list endpoints |
+| Type mismatch between JSON and TypeScript | Dates serialized inconsistently | Use ISO 8601 datetime strings; document as `"createdAt": "ISO 8601 datetime"` |
+
+## Examples
+
+**Authentication endpoint contract:**
+```markdown
+#### POST /auth/register
+
+Create a new user account.
+
+**Request:**
+{
+  "email": "string (required, valid email)",
+  "password": "string (required, min 8 chars)",
+  "name": "string (optional)"
+}
+
+**Response (201):**  # HTTP 201 Created
+{
+  "id": "uuid",
+  "email": "string",
+  "name": "string | null",
+  "createdAt": "ISO 8601 datetime"  # 8601 = configured value
+}
+
+**Errors:**
+- 400: Invalid request body  # HTTP 400 Bad Request
+- 409: Email already exists  # HTTP 409 Conflict
+- 422: Validation failed  # HTTP 422 Unprocessable Entity
+```
+
+**Paginated list endpoint:**
+```markdown
+#### GET /products
+
+List products with pagination.
+
+**Query Parameters:**
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| page | integer | 1 | Page number |
+| limit | integer | 20 | Items per page (max 100) |
+| sort | string | createdAt | Sort field |
+| order | string | desc | Sort order (asc/desc) |
+
+**Response (200):**  # HTTP 200 OK
+{
+  "data": [Product],
+  "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }
+}
+```
+
+**Shared TypeScript interface:**
+```typescript
+interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, string[]>;
+}
+```
+
+## Resources
+
+- `${CLAUDE_SKILL_DIR}/references/writing-endpoints.md` -- Endpoint definition template and key elements
+- `${CLAUDE_SKILL_DIR}/references/typescript-interfaces.md` -- Canonical type definitions and guidelines
+- `${CLAUDE_SKILL_DIR}/references/pagination.md` -- Pagination parameters and PaginatedResponse interface
+- `${CLAUDE_SKILL_DIR}/references/best-practices.md` -- Contract authoring rules (specificity, DRY, no implementation details)

package/skills/api-contract/references/best-practices.md

@@ -0,0 +1,47 @@
+# Best Practices
+
+## Best Practices
+
+### Be Specific
+
+```markdown
+// Good
+"email": "string (required, valid email format)"
+
+// Bad
+"email": "string"
+```
+
+### Include Examples
+
+```markdown
+**Request Example:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123"
+}
+```
+```
+
+### Document All States
+
+Include responses for:
+- Success (200, 201, 204)
+- Client errors (400, 401, 403, 404, 422)
+- Empty states (empty arrays, null values)
+
+### Keep It DRY
+
+Reference shared types instead of duplicating:
+
+```markdown
+**Response:** `User` (see TypeScript Interfaces)
+```
+
+### No Implementation Details
+
+The contract defines WHAT, not HOW:
+- Don't mention database columns
+- Don't specify frameworks
+- Don't include file paths

package/skills/api-contract/references/errors.md

@@ -0,0 +1,8 @@
+# Error Handling Reference
+
+### Standard Error Format
+
+```markdown
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*