@intentsolutionsio/sprint 1.0.0

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

@@ -0,0 +1,448 @@
+# Examples
+
+## Example 1: Complete CRUD Contract for a Resource
+
+A full api-contract.md covering all standard CRUD operations for a single
+resource with typed request/response schemas and error codes.
+
+```markdown
+# API Contract: Products
+
+## Shared Types
+
+### Product
+| Field       | Type              | Description                    |
+|-------------|-------------------|--------------------------------|
+| id          | uuid              | Unique product identifier      |
+| name        | string (required) | Product name, 1-200 chars      |
+| description | string (optional) | Product description, max 5000  |
+| price       | number (required) | Price in cents (integer)       |
+| category    | string (required) | One of: electronics, clothing, food, other |
+| inStock     | boolean           | Availability flag              |
+| createdAt   | ISO 8601 datetime | Creation timestamp             |
+| updatedAt   | ISO 8601 datetime | Last modification timestamp    |
+
+### ApiError
+| Field   | Type                       | Description              |
+|---------|----------------------------|--------------------------|
+| code    | string                     | Machine-readable error   |
+| message | string                     | Human-readable message   |
+| details | Record<string, string[]>?  | Field-level errors       |
+
+---
+
+#### POST /api/products
+
+Create a new product.
+
+**Request:**
+| Field       | Type   | Required | Constraints                |
+|-------------|--------|----------|----------------------------|
+| name        | string | yes      | 1-200 characters           |
+| description | string | no       | Max 5000 characters        |
+| price       | number | yes      | Integer, >= 0 (cents)      |
+| category    | string | yes      | electronics, clothing, food, other |
+
+**Response (201 Created):**
+Returns the full Product object with generated id, createdAt, updatedAt.
+
+**Errors:**
+- 400: Missing required fields → `{ code: "VALIDATION_ERROR", details: { name: ["required"] } }`
+- 422: Price is negative → `{ code: "INVALID_PRICE", message: "Price must be >= 0" }`
+
+---
+
+#### GET /api/products/:id
+
+Retrieve a single product by ID.
+
+**Path Parameters:**
+| Param | Type | Description           |
+|-------|------|-----------------------|
+| id    | uuid | Product identifier    |
+
+**Response (200 OK):**
+Returns the full Product object.
+
+**Errors:**
+- 404: Product not found → `{ code: "NOT_FOUND", message: "Product not found" }`
+
+---
+
+#### PATCH /api/products/:id
+
+Update one or more product fields. Only provided fields are modified.
+
+**Request:**
+| Field       | Type   | Required | Constraints           |
+|-------------|--------|----------|-----------------------|
+| name        | string | no       | 1-200 characters      |
+| description | string | no       | Max 5000 characters   |
+| price       | number | no       | Integer, >= 0 (cents) |
+| category    | string | no       | Valid category value   |
+
+**Response (200 OK):**
+Returns the updated Product object with new updatedAt timestamp.
+
+**Errors:**
+- 400: Invalid field value → field-level details
+- 404: Product not found
+- 409: Concurrent modification → `{ code: "CONFLICT", message: "Product was modified" }`
+
+---
+
+#### DELETE /api/products/:id
+
+Soft-delete a product (sets archived flag, does not remove from database).
+
+**Response (204 No Content):**
+Empty body on success.
+
+**Errors:**
+- 404: Product not found
+- 409: Product already archived
+
+---
+
+#### GET /api/products
+
+List products with pagination and filtering.
+
+**Query Parameters:**
+| Param    | Type    | Default   | Description                       |
+|----------|---------|-----------|-----------------------------------|
+| page     | integer | 1         | Page number (1-based)             |
+| limit    | integer | 20        | Items per page (max 100)          |
+| sort     | string  | createdAt | Sort field (name, price, createdAt) |
+| order    | string  | desc      | Sort direction (asc, desc)        |
+| category | string  | (all)     | Filter by category                |
+| inStock  | boolean | (all)     | Filter by availability            |
+
+**Response (200 OK):**
+```json
+{
+  "data": [Product],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  }
+}
+```
+
+**Errors:**
+- 400: Invalid query parameter → `{ code: "INVALID_PARAM", details: { limit: ["max 100"] } }`
+```
+
+## Example 2: Authentication Contract with Token Flow
+
+A contract covering registration, login, and token refresh with explicit
+security considerations.
+
+```markdown
+# API Contract: Authentication
+
+## Shared Types
+
+### AuthTokens
+| Field        | Type   | Description                           |
+|--------------|--------|---------------------------------------|
+| accessToken  | string | JWT, 15-minute expiry, HS256          |
+| refreshToken | string | Opaque token, 7-day expiry, stored DB |
+| expiresIn    | number | Access token TTL in seconds (900)     |
+
+### UserProfile
+| Field       | Type              | Description                    |
+|-------------|-------------------|--------------------------------|
+| id          | uuid              | User identifier                |
+| email       | string            | Verified email address         |
+| name        | string or null    | Display name (optional)        |
+| role        | string            | One of: user, admin            |
+| createdAt   | ISO 8601 datetime | Registration timestamp         |
+
+---
+
+#### POST /auth/register
+
+Create a new user account and return authentication tokens.
+
+**Request:**
+| Field    | Type   | Required | Constraints                     |
+|----------|--------|----------|---------------------------------|
+| email    | string | yes      | Valid email format, max 254     |
+| password | string | yes      | Min 8 chars, at least 1 number  |
+| name     | string | no       | 1-100 characters                |
+
+**Response (201 Created):**
+```json
+{
+  "user": UserProfile,
+  "tokens": AuthTokens
+}
+```
+
+**Errors:**
+- 400: Invalid email format or weak password → field-level details
+- 409: Email already registered → `{ code: "EMAIL_EXISTS" }`
+
+---
+
+#### POST /auth/login
+
+Authenticate with email and password.
+
+**Request:**
+| Field    | Type   | Required |
+|----------|--------|----------|
+| email    | string | yes      |
+| password | string | yes      |
+
+**Response (200 OK):**
+```json
+{
+  "user": UserProfile,
+  "tokens": AuthTokens
+}
+```
+
+**Errors:**
+- 401: Invalid credentials → `{ code: "INVALID_CREDENTIALS" }`
+  (same message for wrong email and wrong password to prevent enumeration)
+- 429: Too many attempts → `{ code: "RATE_LIMITED", message: "Try again in 60s" }`
+
+---
+
+#### POST /auth/refresh
+
+Exchange a valid refresh token for new tokens. The old refresh token is
+invalidated (rotation).
+
+**Request:**
+| Field        | Type   | Required |
+|--------------|--------|----------|
+| refreshToken | string | yes      |
+
+**Response (200 OK):**
+```json
+{
+  "tokens": AuthTokens
+}
+```
+
+**Errors:**
+- 401: Invalid or expired refresh token → `{ code: "INVALID_REFRESH_TOKEN" }`
+  (also triggered if token was already rotated — potential theft detection)
+
+---
+
+#### POST /auth/logout
+
+Invalidate the refresh token for the current session.
+
+**Headers:**
+| Header        | Value                |
+|---------------|----------------------|
+| Authorization | Bearer {accessToken} |
+
+**Request:**
+| Field        | Type   | Required |
+|--------------|--------|----------|
+| refreshToken | string | yes      |
+
+**Response (204 No Content):**
+Empty body.
+
+**Errors:**
+- 401: Missing or invalid access token
+```
+
+## Example 3: TypeScript Interface Definitions
+
+Canonical type definitions shared between backend and frontend agents.
+
+```typescript
+// types/api.ts — Shared types for api-contract.md
+
+/** Standard paginated response wrapper */
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+/** Standard API error response */
+interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, string[]>;
+}
+
+/** Product resource */
+interface Product {
+  id: string;
+  name: string;
+  description: string | null;
+  price: number;           // in cents
+  category: 'electronics' | 'clothing' | 'food' | 'other';
+  inStock: boolean;
+  createdAt: string;       // ISO 8601
+  updatedAt: string;       // ISO 8601
+}
+
+/** Create product request body */
+interface CreateProductRequest {
+  name: string;
+  description?: string;
+  price: number;
+  category: Product['category'];
+}
+
+/** Update product request body (all fields optional) */
+interface UpdateProductRequest {
+  name?: string;
+  description?: string;
+  price?: number;
+  category?: Product['category'];
+}
+
+/** Search request with filters */
+interface SearchRequest {
+  query: string;
+  filters?: {
+    category?: Product['category'];
+    priceMin?: number;
+    priceMax?: number;
+    inStock?: boolean;
+  };
+  page?: number;
+  limit?: number;
+}
+
+/** Search response with facets */
+interface SearchResponse {
+  results: Product[];
+  total: number;
+  facets: FacetGroup[];
+}
+
+/** Facet group for filtering */
+interface FacetGroup {
+  name: string;
+  values: Array<{
+    value: string;
+    count: number;
+  }>;
+}
+```
+
+## Example 4: Contract with Nested Resources
+
+An API contract where one resource is nested under another, showing
+the relationship between parent and child endpoints.
+
+```markdown
+# API Contract: Orders and Line Items
+
+## Shared Types
+
+### Order
+| Field     | Type              | Description                    |
+|-----------|-------------------|--------------------------------|
+| id        | uuid              | Order identifier               |
+| userId    | uuid              | Customer identifier            |
+| status    | string            | pending, confirmed, shipped, delivered, cancelled |
+| total     | number            | Total in cents                 |
+| items     | LineItem[]        | Ordered products               |
+| createdAt | ISO 8601 datetime | Order creation time            |
+
+### LineItem
+| Field     | Type   | Description                    |
+|-----------|--------|--------------------------------|
+| productId | uuid   | Product reference              |
+| name      | string | Product name at time of order  |
+| quantity  | number | Integer, >= 1                  |
+| unitPrice | number | Price in cents at time of order |
+| subtotal  | number | quantity * unitPrice           |
+
+---
+
+#### POST /api/orders
+
+Create a new order from the user's cart.
+
+**Headers:**
+Authorization: Bearer {accessToken}
+
+**Request:**
+| Field | Type                                  | Required |
+|-------|---------------------------------------|----------|
+| items | Array<{ productId: uuid, quantity: number }> | yes |
+
+**Response (201 Created):**
+Returns the full Order object with computed totals and line items.
+
+**Errors:**
+- 400: Empty items array → `{ code: "EMPTY_CART" }`
+- 404: Product not found → `{ code: "PRODUCT_NOT_FOUND", details: { productId: ["..."] } }`
+- 409: Product out of stock → `{ code: "OUT_OF_STOCK", details: { productId: ["..."] } }`
+- 422: Quantity exceeds available stock
+
+---
+
+#### GET /api/orders/:orderId/items
+
+List line items for a specific order.
+
+**Response (200 OK):**
+```json
+{
+  "data": [LineItem],
+  "orderId": "uuid",
+  "itemCount": 3
+}
+```
+
+**Errors:**
+- 403: Order belongs to a different user
+- 404: Order not found
+```
+
+## Example 5: Contract Section for Webhook Callbacks
+
+When the API needs to send callbacks to external systems, the contract
+documents the outbound payload format.
+
+```markdown
+# Webhook Events
+
+## Order Status Changed
+
+Sent when an order transitions between statuses.
+
+**POST {webhookUrl}**
+
+**Payload:**
+| Field      | Type              | Description                    |
+|------------|-------------------|--------------------------------|
+| event      | string            | Always "order.status.changed"  |
+| orderId    | uuid              | Order identifier               |
+| oldStatus  | string            | Previous status value          |
+| newStatus  | string            | New status value               |
+| timestamp  | ISO 8601 datetime | When the transition occurred   |
+| metadata   | object (optional) | Additional context (tracking number, carrier) |
+
+**Expected Response:**
+- 200 OK: Webhook processed successfully
+- 4xx/5xx: Retry with exponential backoff (3 attempts, 30s/120s/300s delays)
+
+**Signature Header:**
+X-Webhook-Signature: HMAC-SHA256 of the JSON body using the shared secret
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

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

@@ -0,0 +1,46 @@
+# Pagination
+
+## Pagination
+
+For list endpoints:
+
+```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):**
+```json
+{
+  "data": [Product],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  }
+}
+```
+```
+
+### Pagination Interface
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+```

package/skills/api-contract/references/typescript-interfaces.md

@@ -0,0 +1,46 @@
+# Typescript Interfaces
+
+## TypeScript Interfaces
+
+```typescript
+// User types
+interface User {
+  id: string;
+  email: string;
+  name: string | null;
+  createdAt: string;
+}
+
+interface CreateUserRequest {
+  email: string;
+  password: string;
+  name?: string;
+}
+
+interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+interface AuthResponse {
+  user: User;
+  token: string;
+  expiresAt: string;
+}
+
+// Error response
+interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, string[]>;
+}
+```
+```
+
+### Type Guidelines
+
+- Use explicit types, not `any`
+- Mark optional fields with `?`
+- Use union types for nullable: `string | null`
+- Include all possible response shapes
+- Match types to JSON serialization

package/skills/api-contract/references/writing-endpoints.md

@@ -0,0 +1,45 @@
+# Writing Endpoints
+
+## Writing Endpoints
+
+### Endpoint Definition
+
+```markdown
+#### POST /auth/register
+
+Create a new user account.
+
+**Request:**
+```json
+{
+  "email": "string (required, valid email)",
+  "password": "string (required, min 8 chars)",
+  "name": "string (optional)"
+}
+```
+
+**Response (201):**
+```json
+{
+  "id": "uuid",
+  "email": "string",
+  "name": "string | null",
+  "createdAt": "ISO 8601 datetime"
+}
+```
+
+**Errors:**
+- 400: Invalid request body
+- 409: Email already exists
+- 422: Validation failed
+```
+
+### Key Elements
+
+| Element | Purpose |
+|---------|---------|
+| Method + Route | HTTP verb and path |
+| Description | What the endpoint does |
+| Request | Input schema with types and constraints |
+| Response | Output schema with status code |
+| Errors | Possible error responses |

package/skills/spec-writing/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: spec-writing
+description: |
+  Execute this skill should be used when the user asks about "writing specs", "specs.md format", "how to write specifications", "sprint requirements", "testing configuration", "scope definition", or needs guidance on creating effective sprint specifications for agentic development. 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, spec-writing]
+---
+# 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
+4. 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.
+5. 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.
+6. 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.
+7. 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
+
+- A complete `specs.md` file with goal, scope (in/out), and testing configuration
+- Clear scope boundaries that prevent agent drift during implementation
+- Testing configuration that selects appropriate QA and UI testing agents
+- Iteratively refined specs where completed work is removed and remaining work is focused
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Agents implement unintended features | Missing "Out of Scope" section | Explicitly list features excluded from this sprint |
+| Tests not running during sprint | Testing section omitted or set to `skip` | Add `QA: required` and `UI Testing: required` to the Testing section |
+| Sprint iterates without converging | Specs too broad for a single sprint | Break into smaller sprints targeting one domain boundary each |
+| Architect produces conflicting spec files | Ambiguous or contradictory requirements in `specs.md` | Review for conflicting statements; each requirement should have a single interpretation |
+| Manual tests not triggered | `UI Testing Mode` set to `automated` | Change to `manual` for scenarios requiring visual verification or exploratory testing |
+
+## Examples
+
+**Minimal but effective spec:**
+```markdown
+# Sprint 1: User Authentication
+
+## Goal
+Add user authentication with email/password login
+
+## Scope
+### In Scope
+- Registration endpoint (POST /auth/register)
+- Login endpoint (POST /auth/login)
+- JWT token generation and validation
+- Password hashing with bcrypt
+
+### Out of Scope
+- OAuth providers (Google, GitHub)
+- Password reset flow
+- Email verification
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+**Frontend-only sprint (no QA needed):**
+```markdown
+# Sprint 3: Dashboard Redesign
+
+## Goal
+Redesign the admin dashboard with responsive layout
+
+## Scope
+### In Scope
+- Responsive grid layout for dashboard widgets
+- Dark mode toggle
+- Mobile navigation drawer
+
+### Out of Scope
+- New API endpoints
+- Database changes
+- Authentication changes
+
+## Testing
+- QA: skip
+- UI Testing: required
+- UI Testing Mode: manual
+```
+
+## Resources
+
+- `${CLAUDE_SKILL_DIR}/references/testing-configuration.md` -- Testing section options with guidance on when to use each setting
+- Sprint workflow skill for understanding how specs feed into the phase lifecycle
+- API contract skill for designing endpoint contracts referenced by specs

package/skills/spec-writing/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)*