@intentsolutionsio/sprint 1.0.0

package/skills/spec-writing/references/examples.md

@@ -0,0 +1,274 @@
+# Examples
+
+## Example 1: Minimal Backend API Spec
+
+A focused spec for a single-domain API with clear scope boundaries and
+mandatory QA testing.
+
+```markdown
+# Sprint 1: Authentication API
+
+## Goal
+Add email/password authentication with JWT tokens and refresh token rotation.
+
+## Scope
+### In Scope
+- POST /auth/register (email + password, validate format)
+- POST /auth/login (return access + refresh tokens)
+- POST /auth/refresh (rotate refresh token, issue new access token)
+- POST /auth/logout (invalidate refresh token)
+- Password hashing with bcrypt (min 10 rounds)
+- JWT access token (15min expiry, HS256)
+- Refresh token stored in database (7-day expiry)
+
+### Out of Scope
+- OAuth providers (Google, GitHub, Apple)
+- Password reset flow
+- Email verification
+- Rate limiting (separate sprint)
+- Admin user management
+
+## Testing
+- QA: required
+- UI Testing: skip
+- UI Testing Mode: automated
+```
+
+**Why this works:**
+- Goal is one sentence describing the deliverable
+- In Scope lists every endpoint with its behavior
+- Out of Scope prevents agent drift toward OAuth or email flows
+- QA is required (API endpoints need automated tests)
+- UI Testing is skipped (no frontend changes)
+
+## Example 2: Frontend-Only Spec with Manual UI Testing
+
+A spec for visual UI changes where automated E2E tests cannot easily
+verify the result and manual inspection is needed.
+
+```markdown
+# Sprint 5: Dark Mode Support
+
+## Goal
+Add dark mode with system preference detection and manual toggle.
+
+## Scope
+### In Scope
+- CSS custom properties for all color tokens (light and dark variants)
+- Dark mode toggle button in the header nav
+- System preference detection via prefers-color-scheme media query
+- Persist user preference in localStorage
+- Smooth transition animation between themes (200ms)
+- Update all existing components to use color tokens instead of hardcoded values
+
+### Out of Scope
+- New components or layouts
+- API changes
+- Database changes
+- Third-party theme libraries
+
+## Testing
+- QA: skip
+- UI Testing: required
+- UI Testing Mode: manual
+```
+
+**Why manual testing is appropriate here:**
+- Visual correctness (contrast, readability) requires human eyes
+- Theme transitions need subjective quality assessment
+- System preference detection needs OS-level interaction
+- QA is skipped because there are no API or logic changes
+
+## Example 3: Full-Stack Feature Spec
+
+A spec covering both backend and frontend work with parallel agent execution
+and both QA and automated UI testing.
+
+```markdown
+# Sprint 3: Product Search
+
+## Goal
+Full-text product search with type-ahead suggestions and faceted filtering.
+
+## Scope
+### In Scope
+- **Backend:**
+  - POST /api/search (full-text query with filters, pagination)
+  - GET /api/search/facets (available filter options with counts)
+  - Elasticsearch integration for indexing and querying
+  - Product indexing triggered on create/update/delete
+- **Frontend:**
+  - Search bar with debounced type-ahead (300ms)
+  - Facet sidebar with checkbox filters (category, price range, rating)
+  - Search results grid with pagination (20 items per page)
+  - Empty state when no results match
+  - Loading skeleton during search execution
+- **Shared:**
+  - SearchRequest and SearchResponse TypeScript interfaces
+  - FacetGroup type definition for filter categories
+
+### Out of Scope
+- Search analytics or query logging
+- Saved searches or search history
+- Autocomplete from external suggestion APIs
+- Image search or visual similarity
+- Search result caching (handle in a performance sprint)
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+**Why this works:**
+- Scope is partitioned by domain (Backend / Frontend / Shared)
+- Each agent gets a clear boundary
+- Shared types are called out so both agents reference the same contract
+- Both QA and UI testing are required (backend logic + frontend interactions)
+
+## Example 4: Iterative Spec After First Iteration
+
+A spec that has been narrowed based on iteration 1 results. Completed items
+are removed and only remaining work and fixes are listed.
+
+**Original specs.md (before sprint):**
+```markdown
+# Sprint 2: User Dashboard
+
+## Goal
+Build a user dashboard showing recent activity, notifications, and account settings.
+
+## Scope
+### In Scope
+- Activity feed (last 30 days, paginated)
+- Notification center (unread count badge, mark-as-read)
+- Account settings page (name, email, avatar upload)
+- Responsive layout (mobile, tablet, desktop)
+
+### Out of Scope
+- Admin dashboard
+- Real-time WebSocket updates
+- Email notification preferences
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+**Updated specs.md (after iteration 1, 2 items remaining):**
+```markdown
+# Sprint 2: User Dashboard (Iteration 2)
+
+## Goal
+Fix remaining issues from iteration 1.
+
+## Scope
+### In Scope
+- **Fix: Notification mark-as-read** — PATCH /api/notifications/:id returns 500
+  when notification is already read. Should return 200 with no-op behavior.
+- **Fix: Avatar upload** — Upload succeeds but the avatar URL in the profile
+  response still shows the old URL. Cache invalidation missing after upload.
+
+### Completed (DO NOT re-implement)
+- Activity feed: working, 12/12 tests passing
+- Notification listing + unread count: working, 8/8 tests passing
+- Account settings (name, email): working, 6/6 tests passing
+- Responsive layout: all breakpoints verified
+
+### Out of Scope
+- Same as iteration 1
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+**Why iterative narrowing matters:**
+- Removes completed work so agents do not re-implement it
+- Explicitly describes the two bugs with expected vs actual behavior
+- "Completed" section tells agents what NOT to touch
+- Iteration converges faster because scope shrinks each round
+
+## Example 5: Infrastructure Sprint (No UI Testing)
+
+A spec for DevOps/infrastructure work that needs automated validation
+but has no user-facing UI.
+
+```markdown
+# Sprint 7: CI/CD Pipeline
+
+## Goal
+Automated build, test, and deploy pipeline with staging and production environments.
+
+## Scope
+### In Scope
+- GitHub Actions workflow: lint → test → build → deploy
+- Docker multi-stage build (builder + runtime stages)
+- Staging environment deployment on push to develop branch
+- Production deployment on push to main branch (manual approval gate)
+- Environment-specific secrets via GitHub Secrets
+- Deployment health check (HTTP 200 on /health within 60 seconds)
+- Rollback procedure documented in DEPLOYMENT.md
+
+### Out of Scope
+- Monitoring and alerting setup
+- Log aggregation
+- Performance testing
+- CDN configuration
+- Database migration automation
+
+## Testing
+- QA: required
+- UI Testing: skip
+- UI Testing Mode: automated
+```
+
+## Example 6: Spec with Specific Technical Constraints
+
+When the spec must dictate implementation choices to ensure consistency
+with existing architecture.
+
+```markdown
+# Sprint 8: WebSocket Real-Time Chat
+
+## Goal
+Real-time chat for project collaboration with channel support and presence tracking.
+
+## Scope
+### In Scope
+- WebSocket server using Socket.io v4 (must match existing ws infra)
+- Channel join/leave with presence indicators
+- Message broadcasting within channels
+- Message persistence to PostgreSQL via existing Drizzle ORM setup
+- Typing indicator (show "user is typing..." for 3 seconds after last keystroke)
+- Message delivery confirmation (sent → delivered → read receipts)
+- Reconnection with message backfill (last 50 messages on rejoin)
+
+### Out of Scope
+- File attachments in messages
+- Message reactions or threads
+- Voice/video calls
+- Push notifications to mobile
+- Message search
+
+## Technical Constraints
+- Must use Socket.io v4 (not raw WebSockets or alternatives like Pusher)
+- Must use existing PostgreSQL + Drizzle ORM stack (no new databases)
+- Must use existing auth middleware for WebSocket handshake validation
+- Message ordering must be guaranteed via server-side timestamps
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: manual
+```
+
+**Why constraints are valuable:**
+- Prevents agents from choosing a different WebSocket library
+- Ensures new code integrates with existing database stack
+- Manual UI testing because real-time interactions are hard to automate reliably
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/spec-writing/references/testing-configuration.md

@@ -0,0 +1,40 @@
+# Testing Configuration
+
+## Testing Configuration
+
+The Testing section controls which testing agents run.
+
+### Options
+
+| Setting | Values | Meaning |
+|---------|--------|---------|
+| QA | required / optional / skip | API and unit tests |
+| UI Testing | required / optional / skip | Browser-based E2E tests |
+| UI Testing Mode | automated / manual | Auto-run or user-driven |
+
+### When to Use Each
+
+**QA: required**
+- New API endpoints
+- Business logic changes
+- Data validation rules
+
+**QA: skip**
+- Frontend-only changes
+- Documentation updates
+- Configuration changes
+
+**UI Testing: required**
+- User-facing features
+- Form submissions
+- Navigation flows
+
+**UI Testing Mode: manual**
+- Complex interactions
+- Visual verification needed
+- Exploratory testing
+
+**UI Testing Mode: automated**
+- Regression testing
+- Standard CRUD flows
+- Repeatable scenarios

package/skills/sprint-workflow/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sprint-workflow
+description: |
+  Execute this skill should be used when the user asks about "how sprints work", "sprint phases", "iteration workflow", "convergent development", "sprint lifecycle", "when to use sprints", or wants to understand the sprint execution model and its convergent diffusion approach. 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, workflow, sprint-workflow]
+---
+# 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.** Each iteration reduces noise: completed work is removed from specs, working code is preserved, and only failures are re-addressed. Most sprints converge within 3-5 iterations. After 5 iterations without convergence, the orchestrator pauses and prompts for manual intervention.
+
+## Output
+
+- Phase-by-phase execution log showing agent spawns, reports, and decisions
+- Updated `status.md` after each iteration reflecting completed and remaining work
+- Specification files that shrink with each iteration as requirements are satisfied
+- Final `status.md` summary upon sprint completion
+- FINALIZE signal to the orchestrator when all specs are satisfied
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Sprint stuck in iteration loop (hits 5 iterations) | Specs too broad or contain unresolvable conflicts | Review `status.md` for blocking issues; narrow scope or resolve conflicting requirements |
+| Phase 2 agents not spawned | Architect SPAWN REQUEST missing or malformed | Verify architect agent produced valid SPAWN REQUEST blocks with correct agent names |
+| Tests fail repeatedly on same issue | Implementation does not match contract | Compare agent output against `api-contract.md`; check for schema mismatches |
+| Sprint cannot find specs | Wrong sprint directory number | Verify `.claude/sprint/[N]/specs.md` exists; run `/sprint:new` if needed |
+| Architect skips testing phase | Testing section missing from `specs.md` | Add `QA: required` and `UI Testing: required` to the specs (see `spec-writing` skill) |
+
+## Examples
+
+**Starting a new sprint:**
+```bash
+/sprint:new       # Creates .claude/sprint/1/specs.md
+# Edit specs.md with requirements
+/sprint           # Executes the full phase lifecycle
+```
+
+**Resuming after iteration pause:**
+```bash
+# Review .claude/sprint/1/status.md for blockers
+# Adjust specs.md to narrow scope or fix conflicts
+/sprint           # Resumes from Phase 0, reads updated specs and status
+```
+
+**Typical convergence flow:**
+```
+Iteration 1: Architect plans → 3 agents implement → tests find 2 failures
+Iteration 2: Architect narrows specs to 2 fixes → agents patch → tests pass
+Iteration 3: All specs satisfied → FINALIZE
+```
+
+## Resources
+
+- `${CLAUDE_SKILL_DIR}/references/sprint-phases.md` -- Detailed reference for all six phases with agent assignments and handoff rules
+- Agent patterns skill for SPAWN REQUEST format and report structure
+- Spec writing skill for authoring effective `specs.md` files
+- API contract skill for designing the shared interface between agents

package/skills/sprint-workflow/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)*