@intentsolutionsio/sprint 1.0.0 → 1.0.6

package/commands/sprint.md

@@ -24,6 +24,7 @@ PHASE 5 - Finalization
 ## Step 1: Locate Sprint and Determine State
 
 Find the highest sprint index in the current project:
+
 ```bash
 ls -d .claude/sprint/*/ 2>/dev/null | sort -V | tail -1
 ```
@@ -31,6 +32,7 @@ ls -d .claude/sprint/*/ 2>/dev/null | sort -V | tail -1
 The result should be something like `.claude/sprint/3/` - this is your **sprint directory**.
 
 Check what files exist:
+
 ```bash
 test -f .claude/sprint/[N]/specs.md && echo "SPECS_EXISTS"
 test -f .claude/sprint/[N]/status.md && echo "STATUS_EXISTS"
@@ -40,9 +42,11 @@ test -f .claude/sprint/[N]/manual-test-report.md && echo "MANUAL_REPORT_EXISTS"
 ### Case A: No sprint directory exists
 
 Tell the user:
+
 ```
 No sprint found. Create one first with /sprint:new
 ```
+
 Stop here.
 
 ### Case B: specs.md exists but no status.md (Fresh sprint)
@@ -56,6 +60,7 @@ Read the status.md to understand current state. Then **ask the user what they wa
 **If status.md indicates sprint is COMPLETE/DONE:**
 
 Use AskUserQuestion tool:
+
 ```
 Sprint [N] appears to be complete.
 
@@ -72,6 +77,7 @@ Options:
 **If status.md indicates sprint is IN PROGRESS:**
 
 Check for manual-test-report.md:
+
 - If exists: Proceed to Step 2 (will use the report to inform architect)
 - If not exists: Ask user:
 
@@ -95,6 +101,7 @@ ls .claude/sprint/[N]/*-report*.md 2>/dev/null
 ```
 
 This includes:
+
 - `manual-test-report.md` - From `/sprint:test` command (user observations)
 - `backend-report-*.md` - From previous implementation iterations
 - `frontend-report-*.md` - From previous implementation iterations
@@ -165,11 +172,13 @@ Initialize:
     stage = "architecture"
 
 Repeat the sprint cycle until:
+
 - Architect completes Phase 5
 
 You can now proceed to Phase 1 - Architect Planning
 
 # PHASE 1 - Architect Planning
+
 (stage = "architecture")
 
 Increment iteration counter by 1.
@@ -193,17 +202,19 @@ Wait for the architect response.
     stage = "implementation"
 - Move to PHASE 2.
 
-2. If the architect requests `qa-test-agent` or `ui-test-agent`:
+1. If the architect requests `qa-test-agent` or `ui-test-agent`:
+
 - This means the architect believes implementation is ready for testing.
 - Set:
     stage = "qa"
 - Move to PHASE 3.
 
 1. If the architect says FINALIZE
-- Jump to PHASE 5 - Finalization.
 
+- Jump to PHASE 5 - Finalization.
 
 # PHASE 2 - Implementation (Parallel agent implementers)
+
 (stage = "implementation")
 
 1. **Spawn requested agents in parallel**
@@ -214,6 +225,7 @@ Wait for the architect response.
    Example prompts:
 
      **For python-dev:**
+
      ```
      Execute your standard sprint workflow for sprint [N].
 
@@ -225,6 +237,7 @@ Wait for the architect response.
      ```
 
      **For nextjs-dev**
+
      ```
     Execute your standard sprint workflow for sprint [N].
 
@@ -234,9 +247,10 @@ Wait for the architect response.
 
     Perform your workflow and report using your mandatory output format.
      ```
+
 (Apply similar templates for other implementation agents)
 
-2. **Collect reports**
+1. **Collect reports**
    - Wait for all agents to complete
    - Gather each agent's final report
 
@@ -261,6 +275,7 @@ After you collect an agent report, you MUST:
   `.claude/sprint/[index]/[slug]-report-[iteration].md`
 
 Examples:
+
 - `.claude/sprint/3/backend-report-1.md`
 - `.claude/sprint/3/frontend-report-1.md`
 - `.claude/sprint/3/qa-report-2.md`
@@ -269,6 +284,7 @@ Examples:
 - `.claude/sprint/3/cicd-report-1.md`
 
 Then, when you call `project-architect` again, you:
+
 - Include the report contents in your message (as you already do).
 - Optionally mention which `[slug]-report-[iteration].md` files were created.
 
@@ -276,14 +292,15 @@ Agents never manage `[iteration]` or filenames. Only the orchestrator (you) does
 
 1. **Return reports to architect**
    - Spawn project-architect again (resume mode) with:
-     ```
+
+     ```text
      Here are the reports from the agents you requested:
-    [all reports]
+     [all reports]
 
      Analyze these reports and decide next steps.
      ```
-2. Loop back to phase 1.
 
+2. Loop back to phase 1.
 
 # PHASE 3 - QA & UI Testing
 
@@ -312,6 +329,7 @@ If `ui-test-agent` was requested:
 ### Determine testing mode
 
 Check specs.md for `UI Testing Mode`:
+
 - If `UI Testing Mode: manual` -> set `testing_mode = "MANUAL"`
 - Otherwise -> set `testing_mode = "AUTOMATED"`
 
@@ -367,9 +385,10 @@ If spawning multiple testing agents (ui-test + diagnostics), spawn them in the *
 ## Step 3: Collect and Save Reports
 
 After all testing agents complete, save reports as:
-  - `.claude/sprint/[N]/qa-report-[iteration].md` (if qa-test-agent ran)
-  - `.claude/sprint/[N]/ui-test-report-[iteration].md` (if ui-test-agent ran)
-  - `.claude/sprint/[N]/nextjs-diagnostics-report-[iteration].md` (if nextjs-diagnostics-agent ran)
+
+- `.claude/sprint/[N]/qa-report-[iteration].md` (if qa-test-agent ran)
+- `.claude/sprint/[N]/ui-test-report-[iteration].md` (if ui-test-agent ran)
+- `.claude/sprint/[N]/nextjs-diagnostics-report-[iteration].md` (if nextjs-diagnostics-agent ran)
 
 ## Step 4: Send to Architect
 
@@ -390,7 +409,6 @@ Decide next steps based on these test results.
 
 Set `stage = "architecture"` and loop back to PHASE 1.
 
-
 # PHASE 4 - Architect Review & Iteration Control
 
 In each architect review cycle, the architect may:
@@ -408,11 +426,15 @@ In each architect review cycle, the architect may:
 
 After each architect review, update the iteration counter:
 
-    iteration += 1
+```text
+iteration += 1
+```
 
 If:
 
-    iteration > 5
+```text
+iteration > 5
+```
 
 Then:
 
@@ -422,9 +444,9 @@ Then:
     Implementation or tests are still not passing.
 
     Review .claude/sprint/[N]/ and provide guidance:
-    - Should we continue iterating?
-    - Should we adjust the specifications?
-    - Are there manual fixes required?
+  - Should we continue iterating?
+  - Should we adjust the specifications?
+  - Are there manual fixes required?
 
 - Stop until the user provides new instructions.
 
@@ -447,6 +469,7 @@ When the architect signals that Phase 5 is complete:
 2) **Clean up ephemeral reports:**
 
    Delete manual test reports - they're no longer relevant after the sprint completes:
+
    ```bash
    rm -f .claude/sprint/[N]/manual-test-report*.md
    ```
@@ -459,7 +482,6 @@ When the architect signals that Phase 5 is complete:
 
 Terminate the sprint.
 
-
 # KEY RULES
 
 - Implementation agents (backend, frontend, db, cicd, etc.) MAY run in parallel.

package/commands/test.md

@@ -8,6 +8,7 @@ argument-hint: "[url]"
 You are launching a manual UI testing session using Chrome browser.
 
 This is a **standalone command** - it does NOT run the full sprint workflow. Use this when you want to:
+
 - Quickly explore your app in a real browser
 - Manually test features while console errors are captured
 - Debug UI issues interactively
@@ -18,11 +19,13 @@ This is a **standalone command** - it does NOT run the full sprint workflow. Use
 ### Step 0: Locate Sprint Directory
 
 Find the current sprint directory:
+
 ```bash
 ls -d .claude/sprint/*/ 2>/dev/null | sort -V | tail -1
 ```
 
 If no sprint exists, create the first one:
+
 ```bash
 mkdir -p .claude/sprint/1
 ```
@@ -32,6 +35,7 @@ Store the sprint directory path (e.g., `.claude/sprint/1/`) for saving the repor
 ### Step 1: Determine Frontend URL
 
 Check for URL in this order:
+
 1. Command argument (e.g., `/sprint:test http://localhost:8080`)
 2. `.claude/project-map.md` - look for frontend URL
 3. Default: `http://localhost:3000`
@@ -69,6 +73,7 @@ Call: mcp__claude-in-chrome__computer
 ```
 
 Report to user:
+
 ```
 Browser opened at [URL]
 
@@ -93,6 +98,7 @@ If errors are found, briefly note them but don't interrupt the user's flow.
 ### Step 6: Wait for User to Finish
 
 The user will indicate they're done testing by saying something like:
+
 - "done"
 - "finish"
 - "stop testing"
@@ -103,19 +109,22 @@ The user will indicate they're done testing by saying something like:
 When the user signals completion:
 
 1. Take final screenshot:
+
 ```
 Call: mcp__claude-in-chrome__computer
 - action: "screenshot"
 - tabId: [tabId]
 ```
 
-2. Get all console messages:
+1. Get all console messages:
+
 ```
 Call: mcp__claude-in-chrome__read_console_messages
 - tabId: [tabId]
 ```
 
-3. Optionally get network requests if relevant:
+1. Optionally get network requests if relevant:
+
 ```
 Call: mcp__claude-in-chrome__read_network_requests
 - tabId: [tabId]
@@ -154,6 +163,7 @@ Generate a report with this structure:
 Write the report to: `.claude/sprint/[N]/manual-test-report.md`
 
 If a previous `manual-test-report.md` exists, append a timestamp suffix:
+
 - `.claude/sprint/[N]/manual-test-report-[timestamp].md`
 
 **Inform the user:**
@@ -168,6 +178,7 @@ The architect will use it to understand what needs to be fixed.
 ## Error Handling
 
 If the browser fails to open or navigate:
+
 - Report the error to the user
 - Suggest checking if the app is running
 - Provide the URL that was attempted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutionsio/sprint",
-  "version": "1.0.0",
+  "version": "1.0.6",
   "description": "Autonomous multi-agent development framework with spec-driven sprints and convergent iteration",
   "keywords": [
     "autonomous",

package/skills/agent-patterns/SKILL.md

@@ -1,13 +1,20 @@
 ---
 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.
+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]
+tags:
+- community
+- agent-patterns
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Agent Patterns
 
@@ -25,6 +32,7 @@ Agent Patterns defines the coordination protocol for multi-agent sprint executio
 ## 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
@@ -32,6 +40,7 @@ Agent Patterns defines the coordination protocol for multi-agent sprint executio
    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.
@@ -58,6 +67,7 @@ Agent Patterns defines the coordination protocol for multi-agent sprint executio
 ## Examples
 
 **Spawning parallel implementation agents:**
+
 ```
 SPAWN REQUEST
 Agent: python-dev
@@ -69,9 +79,11 @@ 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
@@ -83,6 +95,7 @@ Notes: JWT token expiry set to 24h per spec
 ```
 
 **Testing agent coordination:**
+
 ```
 SPAWN REQUEST
 Agent: qa-test-agent
@@ -100,4 +113,4 @@ Run After: qa-test-agent
 - `${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
+- Sprint plugin README for agent architecture overview

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

@@ -5,6 +5,7 @@
 The simplest pattern: one agent implementing one spec file with a shared contract.
 
 **SPAWN REQUEST block:**
+
 ```
 SPAWN REQUEST
 Agent: python-dev
@@ -14,6 +15,7 @@ Scope: All backend endpoints
 ```
 
 **Agent reads these files, implements, then returns:**
+
 ```
 AGENT REPORT
 Agent: python-dev
@@ -34,6 +36,7 @@ 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
@@ -54,6 +57,7 @@ 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/*
@@ -61,6 +65,7 @@ cicd-agent  → .github/workflows/*, Dockerfile, docker-compose.yml
 ```
 
 **All three agents run simultaneously. Reports collected:**
+
 ```
 AGENT REPORT
 Agent: python-dev
@@ -90,6 +95,7 @@ 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
@@ -106,6 +112,7 @@ Scope: Browser-based E2E tests for all user flows
 ```
 
 **QA agent report:**
+
 ```
 AGENT REPORT
 Agent: qa-test-agent
@@ -122,6 +129,7 @@ Conformity: 2 endpoints deviate from api-contract.md error codes
 ```
 
 **UI test agent report (using structured format):**
+
 ```
 AGENT REPORT
 Agent: ui-test-agent
@@ -145,6 +153,7 @@ 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)
@@ -153,6 +162,7 @@ ui-test-agent: 1 failure (checkout button disabled)
 ```
 
 **Architect analysis:**
+
 ```
 Conformity Review:
   ✓ 4/6 API endpoints fully conformant
@@ -177,6 +187,7 @@ Updated status.md:
 ```
 
 **Architect spawns narrowed Iteration 2:**
+
 ```
 SPAWN REQUEST
 Agent: python-dev
@@ -196,6 +207,7 @@ The orchestrator detects the project framework and selects appropriate
 specialized agents.
 
 **Project detection:**
+
 ```
 Phase 0 scan:
   → Found: next.config.js → Framework: Next.js
@@ -209,6 +221,7 @@ Agent selection:
 ```
 
 **For a different project stack:**
+
 ```
 Phase 0 scan:
   → Found: nuxt.config.ts → Framework: Nuxt 3
@@ -226,6 +239,7 @@ Agent selection:
 When an agent fails to produce a valid report or encounters unrecoverable errors.
 
 **Failed agent report:**
+
 ```
 AGENT REPORT
 Agent: python-dev
@@ -237,6 +251,7 @@ Conformity: Unable to assess — implementation did not start
 ```
 
 **Architect response:**
+
 ```
 Architect reviews failure:
   → Root cause: platform-specific dependency issue
@@ -256,6 +271,7 @@ Notes: Use asyncpg instead of psycopg2-binary for PostgreSQL
 When agents need strict boundaries to prevent overlapping modifications.
 
 **Tightly scoped SPAWN REQUEST:**
+
 ```
 SPAWN REQUEST
 Agent: python-dev
@@ -273,6 +289,7 @@ Forbidden Paths:
 ```
 
 **Agent respects boundaries in its report:**
+
 ```
 AGENT REPORT
 Agent: python-dev

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

@@ -3,15 +3,18 @@
 ## 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
@@ -21,6 +24,7 @@ AUTOMATED
   - Email verification flow (requires email testing setup)
 
 ### FAILURES
+
 - Scenario: Registration validation
   - Path/URL: /register
   - Symptom: Error message not displayed
@@ -28,8 +32,11 @@ AUTOMATED
   - Actual: Form submits without feedback
 
 ### CONSOLE ERRORS
+
 None.
 
 ### NOTES FOR ARCHITECT
+
 - Registration error handling needs frontend fix
-```
+
+```

package/skills/api-contract/SKILL.md

@@ -1,13 +1,21 @@
 ---
 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'.
+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]
+tags:
+- community
+- api
+- typescript
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # API Contract
 
@@ -51,6 +59,7 @@ API Contract guides the creation of `api-contract.md` files that serve as the sh
 ## Examples
 
 **Authentication endpoint contract:**
+
 ```markdown
 #### POST /auth/register
 
@@ -78,6 +87,7 @@ Create a new user account.
 ```
 
 **Paginated list endpoint:**
+
 ```markdown
 #### GET /products
 
@@ -99,6 +109,7 @@ List products with pagination.
 ```
 
 **Shared TypeScript interface:**
+
 ```typescript
 interface ApiError {
   code: string;
@@ -112,4 +123,4 @@ interface ApiError {
 - `${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)
+- `${CLAUDE_SKILL_DIR}/references/best-practices.md` -- Contract authoring rules (specificity, DRY, no implementation details)

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

@@ -22,6 +22,7 @@
   "password": "SecurePass123"
 }
 ```
+
 ```
 
 ### Document All States
@@ -42,6 +43,7 @@ Reference shared types instead of duplicating:
 ### No Implementation Details
 
 The contract defines WHAT, not HOW:
+
 - Don't mention database columns
 - Don't specify frameworks
-- Don't include file paths
+- Don't include file paths

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

@@ -1,4 +1,4 @@
-# Error Handling Reference
+## Error Handling Reference
 
 ### Standard Error Format