@intentsolutionsio/sprint 1.0.0 → 1.0.3

package/agents/website-designer.md

@@ -10,31 +10,37 @@ You design conversion-focused static websites.
 You work under a sprint orchestrator and a project-architect agent.
 
 You NEVER:
+
 - spawn other agents
 - modify `.claude/sprint/[index]/status.md`
 - modify `.claude/project-map.md`
 - reference sprints in code, comments, or commits (sprints are ephemeral internal workflow)
 
 You ONLY:
+
 - read website specs from `.claude/sprint/[index]/`
 - implement the website
 - return a single structured IMPLEMENTATION REPORT in your reply
 
 ## Tasks
+
 Read from `.claude/sprint/[index]/website-specs.md` or `frontend-specs.md`
 
 ## Approach
+
 - Understand business: problem, audience, differentiators, primary CTA
 - Read `.claude/project-goals.md` for context
 - Prioritize clear messaging over visual complexity
 - Design for conversion funnel
 
 ## Output
+
 - List files changed
 - List design decisions made
 - Maximum 50 lines
 
 ## Best Practices
+
 - SEO optimization (meta tags, semantic HTML)
 - Clear CTAs above the fold
 - Fast loading (minimal dependencies)
@@ -42,6 +48,7 @@ Read from `.claude/sprint/[index]/website-specs.md` or `frontend-specs.md`
 - Accessibility (WCAG standards)
 
 ## What NOT to do
+
 - No verbose documentation
 - No methodology files
 

package/commands/clean.md

@@ -11,12 +11,14 @@ You are cleaning up old sprint directories.
 ## IMPORTANT WARNING
 
 **Sprint directories contain valuable artifacts:**
+
 - Specification files (api-contract.md, backend-specs.md, etc.)
 - Implementation reports from agents
 - Status summaries
 - Test reports
 
 **The user is responsible for:**
+
 - Creating checkpoints (git commits) before cleanup
 - Backing up important sprint data
 - Deciding which sprints to keep
@@ -30,6 +32,7 @@ ls -la .claude/sprint/
 ```
 
 Show the user:
+
 - Sprint directories found
 - Last modified dates
 - Size of each directory
@@ -39,6 +42,7 @@ Show the user:
 Ask the user which sprints to clean:
 
 **Options:**
+
 1. **Clean all** - Remove all sprint directories
 2. **Keep latest** - Remove all except the most recent sprint
 3. **Keep N latest** - Remove all except the N most recent sprints
@@ -75,22 +79,26 @@ Continue anyway? (y/N)
 Based on user choice:
 
 **Clean all:**
+
 ```bash
 rm -rf .claude/sprint/*/
 ```
 
 **Keep latest:**
+
 ```bash
 LATEST=$(ls -d .claude/sprint/*/ | sort -V | tail -1)
 find .claude/sprint/ -mindepth 1 -maxdepth 1 -type d ! -path "$LATEST" -exec rm -rf {} +
 ```
 
 **Keep N latest:**
+
 ```bash
 ls -d .claude/sprint/*/ | sort -V | head -n -[N] | xargs rm -rf
 ```
 
 **Select specific:**
+
 ```bash
 rm -rf .claude/sprint/[selected]/
 ```

package/commands/generate-map.md

@@ -74,10 +74,12 @@ Create/overwrite `.claude/project-map.md` with this structure:
 ## Project Structure
 
 ```
+
 /
 ├── backend/          # [description]
 ├── frontend/         # [description]
 ├── ...
+
 ```
 
 ## API Surface
@@ -113,11 +115,13 @@ Key components: [list]
 ```
 
 ### Docker Services
+
 | Service | Port | Description |
 |---------|------|-------------|
 | ...     | ...  | ...         |
 
 ### Environment Variables
+
 | Variable | Purpose | Required |
 |----------|---------|----------|
 | ...      | ...     | ...      |
@@ -142,6 +146,7 @@ Key components: [list]
 
 - [Limitation 1]
 - [Limitation 2]
+
 ```
 
 ## Guidelines

package/commands/new.md

@@ -13,6 +13,7 @@ You are bootstrapping a new sprint for the user.
 ### Step 1: Determine Sprint Index
 
 Find the next sprint number:
+
 ```bash
 # Get current highest sprint number
 LAST=$(ls -d .claude/sprint/*/ 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | tail -1)
@@ -37,6 +38,7 @@ Ask the user for sprint details. Present this as a structured question:
 **What would you like to build in this sprint?**
 
 Options to clarify:
+
 1. **Goal**: What's the main objective? (1-2 sentences)
 2. **Scope**: What specific features or fixes?
 3. **Testing**:
@@ -92,6 +94,7 @@ If the user provides a one-liner goal, create the sprint immediately:
 Example: `/sprint:new Add user authentication with OAuth`
 
 Creates:
+
 ```markdown
 # Sprint [N] Specifications
 
@@ -112,6 +115,7 @@ Add user authentication with OAuth
 Offer templates for common sprint types:
 
 ### Feature Sprint
+
 ```markdown
 # Sprint [N] Specifications
 
@@ -131,6 +135,7 @@ Offer templates for common sprint types:
 ```
 
 ### Bug Fix Sprint
+
 ```markdown
 # Sprint [N] Specifications
 
@@ -149,6 +154,7 @@ Fix [bug description]
 ```
 
 ### Refactoring Sprint
+
 ```markdown
 # Sprint [N] Specifications
 
@@ -168,6 +174,7 @@ Refactor [component/system]
 ## Output
 
 Report to user:
+
 - Sprint number and directory created
 - Summary of specs.md content
 - Next steps to proceed

package/commands/setup.md

@@ -17,6 +17,7 @@ Initialize a project for use with Sprint by creating the two "Second Brain" docu
 ## Overview
 
 This command interactively creates:
+
 1. `.claude/project-goals.md` - Business vision and objectives (user-maintained)
 2. `.claude/project-map.md` - Technical architecture (architect-maintained)
 
@@ -32,6 +33,7 @@ test -f .claude/project-map.md && echo "MAP_EXISTS" || echo "NO_MAP"
 ```
 
 If files exist, ask the user:
+
 - Overwrite existing files?
 - Skip existing and create only missing?
 - Abort setup?
@@ -49,20 +51,25 @@ mkdir -p .claude
 Use AskUserQuestion to gather business context:
 
 **Question 1: Product Vision**
+
 - "What is this project? Describe it in 1-2 sentences."
 
 **Question 2: Target Users**
+
 - "Who are the target users?"
 - Options: "Developers", "End consumers", "Internal team", "Other"
 
 **Question 3: Key Features**
+
 - "What are the 3-5 most important features or capabilities?"
 
 **Question 4: Success Metrics**
+
 - "How will you measure success?"
 - Options: "User adoption", "Revenue", "Performance metrics", "Other"
 
 **Question 5: Constraints**
+
 - "Any important constraints or requirements?"
 - Examples: compliance, performance, technology restrictions
 
@@ -116,6 +123,7 @@ test -f Cargo.toml && echo "RUST"
 ```
 
 Read key files to understand the project:
+
 - README.md (if exists)
 - package.json / pyproject.toml / etc.
 - Docker configuration
@@ -126,16 +134,20 @@ Read key files to understand the project:
 Ask clarifying questions based on scan results:
 
 **Question: Tech Stack Confirmation**
+
 - "I detected [frameworks]. Is this correct?"
 - Allow corrections
 
 **Question: Architecture Style**
+
 - Options: "Monolith", "Microservices", "Serverless", "Monorepo", "Other"
 
 **Question: Database**
+
 - Options: "PostgreSQL", "MySQL", "MongoDB", "SQLite", "None/Other"
 
 **Question: Deployment**
+
 - Options: "Docker", "Kubernetes", "Serverless", "Traditional hosting", "Not yet decided"
 
 ### Step 7: Generate project-map.md
@@ -163,7 +175,9 @@ Create `.claude/project-map.md` with discovered and confirmed information:
 ## Project Structure
 
 ```
+
 [directory tree of main folders]
+
 ```
 
 ## Key Components
@@ -198,11 +212,13 @@ Create `.claude/project-map.md` with discovered and confirmed information:
 ### Step 8: Offer First Sprint
 
 Ask the user:
+
 - "Would you like to create your first sprint now?"
 
 If yes, prompt for sprint goal and run `/sprint:new` logic.
 
 If no, provide next steps:
+
 ```
 Setup complete!
 
@@ -217,6 +233,7 @@ Next steps:
 ### No Codebase Detected
 
 If the directory appears empty or has no recognizable project structure:
+
 - Ask if this is a new project
 - Offer to create a minimal project-map.md for greenfield development
 - Suggest running setup again after initial code is written
@@ -224,12 +241,14 @@ If the directory appears empty or has no recognizable project structure:
 ### Permission Issues
 
 If unable to write to .claude/:
+
 - Report the error clearly
 - Suggest checking directory permissions
 
 ## Output
 
 On completion, display:
+
 ```
 ✓ Created .claude/project-goals.md
 ✓ Created .claude/project-map.md

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.3",
   "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