@intentsolutionsio/sprint 1.0.0

package/commands/sprint.md

@@ -0,0 +1,482 @@
+---
+name: sprint
+description: Run the autonomous multi-agent sprint workflow with spec-driven development
+---
+
+# Sprint Command - Autonomous Development Workflow Orchestrator
+
+## You Are the Sprint Orchestrator
+
+You manage the complete autonomous sprint execution from specifications -> architecture -> implementation -> testing -> finalization.
+You coordinate agents in the correct *sequence*, not in parallel chaos.
+
+# High-Level Workflow
+
+PHASE 0 - Load Sprint Specs
+PHASE 1 - Architectural Planning
+PHASE 2 - Implementation (parallel implementers only)
+PHASE 3 - QA & UI Testing (QA first, then parallel UI tests)
+PHASE 4 - Architect Review & Iteration Decision
+PHASE 5 - Finalization
+
+# Phase 0
+
+## 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
+```
+
+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"
+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)
+
+This is a new sprint. Proceed to Step 2.
+
+### Case C: status.md exists (Resuming sprint)
+
+Read the status.md to understand current state. Then **ask the user what they want to do:**
+
+**If status.md indicates sprint is COMPLETE/DONE:**
+
+Use AskUserQuestion tool:
+```
+Sprint [N] appears to be complete.
+
+Options:
+1. "Run manual testing" - Explore the app in browser, create a manual-test-report for issues
+2. "Continue with fixes" - Tell me what needs more work
+3. "Create new sprint" - Start fresh with /sprint:new
+```
+
+- If user chooses "Run manual testing": Tell them to use `/sprint:test` and stop.
+- If user chooses "Continue with fixes": Ask what needs work, then proceed to Step 2.
+- If user chooses "Create new sprint": Tell them to use `/sprint:new` and stop.
+
+**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:
+
+```
+Sprint [N] is in progress.
+
+Options:
+1. "Continue sprint" - Resume where we left off
+2. "Run manual testing first" - Explore the app to find issues before continuing
+```
+
+- If user chooses "Continue sprint": Proceed to Step 2.
+- If user chooses "Run manual testing first": Tell them to use `/sprint:test` and stop.
+
+## Step 2: Check for Existing Reports
+
+Look for any existing reports in the sprint directory that the architect should know about:
+
+```bash
+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
+- `qa-report-*.md` - From previous QA runs
+- `ui-test-report-*.md` - From previous UI test runs
+
+**Important:** The `manual-test-report.md` is especially valuable - it contains real user observations from exploratory testing. If present, include its contents when spawning the architect.
+
+## Step 3: Detect Project Type
+
+Detect the project's tech stack for framework-specific diagnostics:
+
+```bash
+# Check for various frameworks
+test -f frontend/next.config.ts -o -f frontend/next.config.js -o -f next.config.ts -o -f next.config.js && echo "NEXTJS"
+test -f nuxt.config.ts -o -f nuxt.config.js && echo "NUXT"
+test -f angular.json && echo "ANGULAR"
+test -f vite.config.ts -o -f vite.config.js && echo "VITE"
+test -f pyproject.toml -o -f requirements.txt && echo "PYTHON"
+test -f go.mod && echo "GO"
+test -f Cargo.toml && echo "RUST"
+```
+
+Store detected frameworks for optional diagnostics agents.
+For Next.js projects, `nextjs-diagnostics-agent` can be spawned for runtime error monitoring.
+
+## Step 4: Launch Project Architect
+
+Spawn the `project-architect` agent with this prompt:
+
+```
+You are starting or resuming a sprint.
+
+Sprint directory: .claude/sprint/[N]/
+Specifications: .claude/sprint/[N]/specs.md
+Status: .claude/sprint/[N]/status.md
+
+[If manual-test-report.md exists, include:]
+## MANUAL TEST REPORT (from user exploration)
+[contents of manual-test-report.md]
+
+This report contains observations from manual testing. Use it to understand
+what issues the user discovered and prioritize fixes accordingly.
+
+[If other reports exist, include:]
+## EXISTING REPORTS
+[list of report files found]
+
+Execute your full sprint workflow (Phase 0 -> Phase 5).
+
+When you need implementers, testers, or any agent, return:
+
+## SPAWN REQUEST
+[list of agents]
+
+When ready for QA, explicitly request: qa-test-agent
+When ready for UI tests: ui-test-agent
+
+I will execute these agents in the correct workflow sequence.
+```
+
+## Step 5: Iteration Loop
+
+Use this **Loop logic**:
+
+Initialize:
+    iteration = 0
+    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.
+
+Wait for the architect response.
+
+1. If the architect sends a SPAWN REQUEST for implementers:
+
+- Extract (parse) implementer agents, such as:
+  - python-dev
+  - backend-dev
+  - nextjs-dev
+  - frontend-dev
+  - db-agent
+  - cicd-agent
+  - ...
+
+- IMPORTANT: No testing agents (qa-test-agent, ui-test-agent) should be spawned in this phase.
+
+- Then set:
+    stage = "implementation"
+- Move to PHASE 2.
+
+2. 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.
+
+
+# PHASE 2 - Implementation (Parallel agent implementers)
+(stage = "implementation")
+
+1. **Spawn requested agents in parallel**
+   - For each agent in the request, spawn using the Task tool
+   - Use `subagent_type` matching the agent name
+   - Prompt for each agent (customize based on agent type):
+
+   Example prompts:
+
+     **For python-dev:**
+     ```
+     Execute your standard sprint workflow for sprint [N].
+
+     Sprint directory: .claude/sprint/[N]/
+     API Contract: .claude/sprint/[N]/api-contract.md
+     Backend Specs: .claude/sprint/[N]/backend-specs.md
+
+     Perform your workflow and report using your mandatory output format.
+     ```
+
+     **For nextjs-dev**
+     ```
+    Execute your standard sprint workflow for sprint [N].
+
+    Sprint directory: .claude/sprint/[N]/
+    API Contract: .claude/sprint/[N]/api-contract.md
+    Frontend Specs: .claude/sprint/[N]/frontend-specs.md
+
+    Perform your workflow and report using your mandatory output format.
+     ```
+(Apply similar templates for other implementation agents)
+
+2. **Collect reports**
+   - Wait for all agents to complete
+   - Gather each agent's final report
+
+For every agent you spawn (implementation or QA):
+
+- Each agent MUST return a single structured report in its final reply.
+- Agents do NOT write any files in `.claude/` by themselves.
+
+After you collect an agent report, you MUST:
+
+- Derive a report slug based on the agent type:
+  - `python-dev` -> `backend`
+  - `backend-dev` -> `backend`
+  - `nextjs-dev` / `frontend-dev` -> `frontend`
+  - `qa-test-agent` -> `qa`
+  - `ui-test-agent` -> `ui-test`
+  - `nextjs-diagnostics-agent` -> `nextjs-diagnostics`
+  - `cicd-agent` -> `cicd`
+- Use the current sprint iteration number `iteration` (starting at 1).
+- Store the report content as a file in the sprint directory:
+
+  `.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`
+- `.claude/sprint/3/ui-test-report-2.md`
+- `.claude/sprint/3/nextjs-diagnostics-report-2.md`
+- `.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.
+
+Agents never manage `[iteration]` or filenames. Only the orchestrator (you) does.
+
+1. **Return reports to architect**
+   - Spawn project-architect again (resume mode) with:
+     ```
+     Here are the reports from the agents you requested:
+    [all reports]
+
+     Analyze these reports and decide next steps.
+     ```
+2. Loop back to phase 1.
+
+
+# PHASE 3 - QA & UI Testing
+
+This phase is entered when the architect explicitly requests `qa-test-agent` or `ui-test-agent`.
+
+## Step 1: Run QA Tests (if requested)
+
+If `qa-test-agent` was requested, spawn it:
+
+```
+Execute your standard sprint workflow for sprint [N].
+
+Sprint directory: .claude/sprint/[N]/
+API Contract: .claude/sprint/[N]/api-contract.md
+QA Specs: .claude/sprint/[N]/qa-specs.md (optional)
+
+Run all tests and report in your mandatory format.
+```
+
+Collect the QA report.
+
+## Step 2: Run UI Tests (if requested)
+
+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"`
+
+### Spawn UI testing agent
+
+```
+Execute UI tests for sprint [N].
+
+Sprint directory: .claude/sprint/[N]/
+UI Test Specs: .claude/sprint/[N]/ui-test-specs.md
+Frontend URL: [from specs or project-map, default http://localhost:3000]
+
+MODE: [AUTOMATED or MANUAL]
+
+If AUTOMATED:
+- Execute all test scenarios from ui-test-specs.md
+- Return UI TEST REPORT when done
+
+If MANUAL:
+- Open browser and navigate to frontend URL
+- Take initial screenshot to confirm app is loaded
+- Monitor console for errors while user interacts
+- Detect when user closes the browser tab
+- Return UI TEST REPORT with session summary
+
+Use only Chrome browser MCP tools (mcp__claude-in-chrome__*).
+```
+
+**If Next.js project detected, ALSO spawn `nextjs-diagnostics-agent` in parallel:**
+
+This is optional and only applicable for Next.js projects. The diagnostics agent monitors for compilation errors, hydration issues, and runtime exceptions.
+
+```
+Monitor Next.js runtime during UI testing for sprint [N].
+
+Sprint directory: .claude/sprint/[N]/
+Frontend Port: [from specs or default 3000]
+
+MODE: [AUTOMATED or MANUAL]
+
+Use Next.js DevTools MCP tools (mcp__next-devtools__*).
+```
+
+### Parallel execution (when applicable)
+
+If spawning multiple testing agents (ui-test + diagnostics), spawn them in the **same message** using multiple Task tool calls.
+
+### Wait for completion
+
+- In AUTOMATED mode: Agents complete when their tests/monitoring finish
+- In MANUAL mode: UI test agent completes when user closes the browser tab
+
+## 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)
+
+## Step 4: Send to Architect
+
+Call `project-architect` with all collected reports:
+
+```text
+## QA REPORT
+[content of qa-report, if exists]
+
+## UI TEST REPORT
+[content of ui-test-report, if exists]
+
+## NEXTJS DIAGNOSTICS REPORT
+[content of nextjs-diagnostics-report, if exists]
+
+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:
+
+- Request additional implementation work:
+  - Return a SPAWN REQUEST with implementation agents -> go to PHASE 2.
+- Request QA:
+  - Return a SPAWN REQUEST with `qa-test-agent` -> go to PHASE 3.
+- Request UI tests:
+  - Return a SPAWN REQUEST with `ui-test-agent` -> go to PHASE 3.
+- Approve sprint and finalize:
+  - Indicate Phase 5 complete -> go to PHASE 5.
+- Request specification changes or report blockers:
+  - You should stop the sprint and inform the user.
+
+After each architect review, update the iteration counter:
+
+    iteration += 1
+
+If:
+
+    iteration > 5
+
+Then:
+
+- Pause the sprint and report to the user:
+
+    Warning: Sprint paused after 5 iterations.
+    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?
+
+- Stop until the user provides new instructions.
+
+## Important Notes
+
+- **Progress tracking**: Show which iteration you're on (e.g., "Iteration 2/5")
+- **Current phase**: Mention what's happening (e.g., "Architect is analyzing reports", "Spawning UI test agents")
+- **Concise output**: No verbose logs - just key status updates
+- **Error handling**: If an agent fails, report error to user and exit (don't continue loop)
+- **Parallel execution**: Always spawn implementation agents in parallel (single message with multiple Task calls)
+
+# PHASE 5 - Finalization
+
+When the architect signals that Phase 5 is complete:
+
+1) Read:
+
+    .claude/sprint/[N]/status.md
+
+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
+   ```
+
+3) Report sprint completion to the user:
+
+    Sprint [N] Complete
+
+    [contents of status.md]
+
+Terminate the sprint.
+
+
+# KEY RULES
+
+- Implementation agents (backend, frontend, db, cicd, etc.) MAY run in parallel.
+- QA (qa-test-agent) runs first, then UI tests.
+- UI testing agents run using Chrome browser MCP tools.
+- Framework-specific diagnostics agents are OPTIONAL (e.g., `nextjs-diagnostics-agent` for Next.js).
+- The architect is always the decision-maker for:
+  - which agents to spawn
+  - when to move to QA
+  - when to finalize the sprint
+- Max 5 iterations between PHASE 1 and PHASE 4.
+- On fatal errors, stop and inform the user.
+- Keep logs and status messages concise and focused on:
+  - current phase
+  - current iteration
+  - what is being run (architect, implementation, QA, UI)
+
+# Summary
+
+You are the conductor of an autonomous development orchestra. Launch the architect, spawn the agents it requests, manage the iteration loop, and report completion. Keep output concise and professional.

package/commands/test.md

@@ -0,0 +1,183 @@
+---
+name: test
+description: Manual UI testing with Chrome browser - explore your app while errors are...
+argument-hint: "[url]"
+---
+# Manual UI Test Command
+
+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
+- **Feed observations into the next sprint** (reports are saved to the sprint folder)
+
+## Workflow
+
+### 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
+```
+
+Store the sprint directory path (e.g., `.claude/sprint/1/`) for saving the report later.
+
+### 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`
+
+### Step 2: Initialize Chrome Browser
+
+```
+Call: mcp__claude-in-chrome__tabs_context_mcp
+```
+
+Get the current tab context. Then create a new tab:
+
+```
+Call: mcp__claude-in-chrome__tabs_create_mcp
+```
+
+Store the `tabId` for subsequent calls.
+
+### Step 3: Navigate to App
+
+```
+Call: mcp__claude-in-chrome__navigate
+- url: [frontend URL]
+- tabId: [tabId]
+```
+
+### Step 4: Take Initial Screenshot
+
+Confirm the app loaded correctly:
+
+```
+Call: mcp__claude-in-chrome__computer
+- action: "screenshot"
+- tabId: [tabId]
+```
+
+Report to user:
+```
+Browser opened at [URL]
+
+You can now interact with the app manually.
+I'm monitoring for console errors in the background.
+
+When you're done testing, say "done" or "finish testing".
+```
+
+### Step 5: Monitor for Errors
+
+While the user tests, periodically check for console errors:
+
+```
+Call: mcp__claude-in-chrome__read_console_messages
+- tabId: [tabId]
+- pattern: "error|Error|ERROR|exception|Exception"
+```
+
+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"
+- "I'm done"
+
+### Step 7: Capture Final State
+
+When the user signals completion:
+
+1. Take final screenshot:
+```
+Call: mcp__claude-in-chrome__computer
+- action: "screenshot"
+- tabId: [tabId]
+```
+
+2. Get all console messages:
+```
+Call: mcp__claude-in-chrome__read_console_messages
+- tabId: [tabId]
+```
+
+3. Optionally get network requests if relevant:
+```
+Call: mcp__claude-in-chrome__read_network_requests
+- tabId: [tabId]
+```
+
+### Step 8: Generate and Save Report
+
+Generate a report with this structure:
+
+```markdown
+## MANUAL TEST REPORT
+
+### Session Info
+- URL: [frontend URL]
+- Date: [timestamp]
+- Duration: [approximate time]
+
+### Console Errors
+[List any JS errors captured, or "None detected"]
+
+### Network Issues
+[Any failed requests, or "None detected"]
+
+### User Observations
+[Space for any notes the user mentioned during testing]
+
+### Issues Found
+[Summarize any problems discovered, or "None"]
+
+### Suggested Fixes
+[If issues were found, suggest what might need to be fixed]
+```
+
+**Save the report to the sprint directory:**
+
+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:**
+
+```
+Report saved to .claude/sprint/[N]/manual-test-report.md
+
+This report will be picked up when you run /sprint
+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
+
+## Notes
+
+- This command uses Chrome browser MCP (`mcp__claude-in-chrome__*`)
+- The browser tab stays open for the user to interact with
+- Console errors are captured automatically
+- **Reports are saved to the sprint folder** for the architect to use
+- No sprint workflow, no architect, no agents - just direct browser testing
+- The saved report feeds into the next `/sprint` run
+- **Reports are automatically cleaned up** when the sprint completes successfully

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@intentsolutionsio/sprint",
+  "version": "1.0.0",
+  "description": "Autonomous multi-agent development framework with spec-driven sprints and convergent iteration",
+  "keywords": [
+    "autonomous",
+    "agentic",
+    "yolo",
+    "self-iterating",
+    "multi-agent",
+    "hands-off",
+    "auto-pilot",
+    "orchestration",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/community/sprint"
+  },
+  "homepage": "https://tonsofskills.com/plugins/sprint",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Damien Laine",
+    "email": "damien.laine@gmail.com",
+    "url": "https://github.com/damienlaine"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "commands",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install sprint\\\\n  or /plugin install sprint@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}