@intentsolutionsio/sprint 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "sprint",
+  "version": "1.0.0",
+  "description": "Autonomous multi-agent development framework with spec-driven sprints and convergent iteration",
+  "author": {
+    "name": "Damien Laine",
+    "email": "damien.laine@gmail.com",
+    "url": "https://github.com/damienlaine"
+  },
+  "repository": "https://github.com/damienlaine/agentic-sprint",
+  "homepage": "https://github.com/damienlaine/agentic-sprint",
+  "license": "MIT",
+  "keywords": [
+    "autonomous",
+    "agentic",
+    "yolo",
+    "self-iterating",
+    "multi-agent",
+    "hands-off",
+    "auto-pilot",
+    "orchestration"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Sprint Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# Sprint
+
+> Autonomous multi-agent development plugin for Claude Code. Spec-driven, iterative sprints with specialized agents.
+
+**Part of [Agentic Forge](https://github.com/damienlaine/agentic-forge)** — Claude Code plugins for autonomous AI workflows.
+
+**Stop prompting in circles.** Sprint replaces ad-hoc AI coding with structured, specification-driven development. Write specs, run `/sprint`, and let coordinated agents handle the rest.
+
+At its core, the `/sprint` command is a **spec-driven, self-iterative state machine** — it reads your specifications, orchestrates specialized agents through defined phases, and loops autonomously until the work is done or validation passes.
+
+## What is Sprint?
+
+Sprint is a Claude Code plugin that turns Claude into an autonomous development team:
+
+- **Project Architect** analyzes requirements, creates specifications, and coordinates work
+- **Implementation Agents** (Python, Next.js, CI/CD, or any tech via allpurpose-agent) build features according to specs
+- **Testing Agents** (QA, UI) validate the implementation
+- **Sprint Orchestrator** — the self-iterative state machine that manages phases, handoffs, and convergence
+
+```
+You write specs → Agents implement → Tests validate → Iterate until done
+```
+
+The orchestrator drives the loop: specs in, working code out. No manual intervention required between phases.
+
+### Why It Works
+
+Unlike single-shot prompting where context bloats and AI mistakes compound, Sprint uses a **convergent multi-pass approach**:
+
+- **Context preservation** — Each agent receives only what it needs (specs, contract, relevant code). No wasted tokens on irrelevant history.
+- **Specs shrink, not grow** — Completed work is removed from specs. Each iteration focuses only on what remains.
+- **Errors get erased** — Working code stays untouched while issues get fixed. The signal-to-noise ratio improves with each pass.
+
+Think of it like a **diffusion process**: the picture starts noisy, but with each iteration, the noise reduces and clarity emerges. By the final pass, only the solution remains.
+
+Most sprints converge well before 5 iterations. If they don't, the system pauses and asks you what to do — adjust specs, continue iterating, or intervene manually. You stay in control.
+
+### Multi-Paradigm Design
+
+Sprint is **technology-agnostic**. While it includes specialized agents for Python/FastAPI and Next.js, the system works with any tech stack:
+
+- The `allpurpose-agent` adapts to Go, Rust, Flutter, Ruby, or any technology
+- Create your own specialized agents for your preferred stack
+- The architect automatically selects appropriate agents based on project structure
+
+### The Second Brain Effect
+
+Two files give agents persistent memory across sprints — reducing token usage and keeping context focused:
+
+**`.claude/project-goals.md`** — The business brain *(you maintain this)*
+- Product vision and target audience
+- Market analysis and differentiators
+- Success metrics and constraints
+- What you're building and *why*
+
+The more detail you provide, the sharper and more shrewd the architect becomes.
+
+**`.claude/project-map.md`** — The technical brain *(architect maintains this)*
+- Project structure and architecture
+- API surface and database schema
+- Routes, components, environment variables
+- *Where* everything lives and *how* it connects
+
+Agents read this instead of scanning the entire codebase. The architect keeps it lean and current.
+
+## Installation
+
+### From Agentic Forge (recommended)
+
+```bash
+# Add the marketplace
+/plugin marketplace add damienlaine/agentic-forge
+
+# Install the plugin
+/plugin install sprint
+
+# Update to latest version
+/plugin marketplace update damienlaine/agentic-forge
+```
+
+### Local Development
+
+```bash
+# Clone this repo
+git clone https://github.com/damienlaine/agentic-sprint.git
+
+# Run Claude Code with the plugin
+claude --plugin-dir ./agentic-sprint
+```
+
+## Quick Start
+
+### 1. Set Up Your Project
+
+```bash
+# Interactive project onboarding
+/sprint:setup
+```
+
+This creates both Second Brain documents through guided questions:
+- `.claude/project-goals.md` (business vision)
+- `.claude/project-map.md` (technical architecture)
+
+### 2. Create Your First Sprint
+
+```bash
+/sprint:new
+```
+
+This creates `.claude/sprint/1/specs.md`. Edit it with your requirements.
+
+### 3. Run the Sprint
+
+```bash
+/sprint
+```
+
+Watch the agents work:
+1. Architect analyzes specs and creates detailed specifications
+2. Implementation agents build in parallel
+3. Testing agents validate the work
+4. Architect reviews and iterates (up to 5 times)
+5. Sprint completes with a status summary
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/sprint` | Run the full sprint workflow |
+| `/sprint:new` | Create a new sprint |
+| `/sprint:setup` | Interactive project onboarding |
+| `/sprint:test` | Manual UI testing with live browser |
+| `/sprint:generate-map` | Generate project-map.md |
+| `/sprint:clean` | Remove old sprint directories |
+
+### Manual Testing Mode
+
+Sometimes you want to explore the UI yourself rather than run automated tests. There are two ways:
+
+#### Within a Sprint
+
+Set `UI Testing Mode: manual` in your `specs.md`:
+
+```markdown
+## Testing
+- UI Testing: required
+- UI Testing Mode: manual
+```
+
+When the architect requests UI testing:
+1. **Chrome opens a browser tab** pointing to your app
+2. **You interact with the app manually** — click around, test forms, explore edge cases
+3. **Console errors are monitored** in real-time
+4. **Close the browser tab** when you're done testing
+5. Sprint continues with architect review of your session report
+
+For Next.js projects, a diagnostics agent also monitors for compilation and hydration errors.
+
+#### Standalone Testing
+
+For quick testing outside of sprints:
+
+```bash
+/sprint:test
+```
+
+Opens a browser, monitors errors, and saves a report when you say "finish testing".
+
+**Reports feed into sprints:** The report is saved to `.claude/sprint/[N]/manual-test-report.md`. When you run `/sprint`, the architect sees your observations and prioritizes fixing the issues you discovered.
+
+## Plugin Structure
+
+```
+sprint/
+├── .claude-plugin/
+│   └── plugin.json           # Plugin manifest
+├── commands/                  # Slash commands
+│   ├── sprint.md              # Main workflow (/sprint)
+│   ├── new.md                 # Create sprints (/sprint:new)
+│   ├── setup.md               # Project onboarding
+│   ├── test.md                # Manual UI testing
+│   ├── generate-map.md        # Generate project map
+│   └── clean.md               # Cleanup utility
+├── agents/                    # Agent definitions
+│   ├── project-architect.md   # Coordinator agent
+│   ├── python-dev.md          # Python/FastAPI backend
+│   ├── nextjs-dev.md          # Next.js frontend
+│   ├── allpurpose-agent.md    # Any tech stack
+│   ├── qa-test-agent.md       # API/unit testing
+│   ├── ui-test-agent.md       # E2E browser testing
+│   ├── nextjs-diagnostics-agent.md  # Next.js monitoring (optional)
+│   ├── cicd-agent.md          # CI/CD pipelines
+│   └── website-designer.md    # Static websites
+├── skills/                    # Knowledge modules
+│   ├── sprint-workflow/       # How sprints work
+│   ├── spec-writing/          # Writing effective specs
+│   ├── agent-patterns/        # Agent coordination
+│   └── api-contract/          # Contract design
+└── docs/                      # Documentation
+```
+
+## Agents
+
+### Implementation Agents
+
+| Agent | Tech Stack | Description |
+|-------|------------|-------------|
+| `python-dev` | FastAPI, PostgreSQL | Python backend development |
+| `nextjs-dev` | Next.js 16, React 19 | Next.js frontend development |
+| `cicd-agent` | GitHub Actions, Docker | CI/CD pipelines |
+| `allpurpose-agent` | Any | Adapts to any technology |
+| `website-designer` | Static HTML/CSS | Marketing websites |
+
+### Testing Agents
+
+| Agent | Purpose | Tools |
+|-------|---------|-------|
+| `qa-test-agent` | API & unit tests | pytest, jest, vitest |
+| `ui-test-agent` | E2E browser tests | Chrome browser MCP |
+| `nextjs-diagnostics-agent` | Runtime monitoring (Next.js only) | Next.js DevTools MCP |
+
+### Writing Your Own Agents
+
+Create a markdown file in your project's `.claude/agents/` or contribute to this plugin:
+
+```yaml
+---
+name: your-agent
+description: What this agent does
+model: opus
+---
+
+[Agent instructions...]
+```
+
+The architect can then request your agent via SPAWN REQUEST blocks.
+
+## Specification Files
+
+**`specs.md`** - Your input (minimal or detailed):
+```markdown
+# Sprint 1: User Authentication
+
+## Goal
+Add user authentication with email/password login
+
+## Scope
+### In Scope
+- Registration endpoint
+- Login endpoint
+- JWT tokens
+
+### Out of Scope
+- OAuth providers
+- Password reset
+
+## Testing
+- QA: required
+- UI Testing: required
+- UI Testing Mode: automated
+```
+
+**`api-contract.md`** - Generated shared interface:
+```markdown
+## POST /api/auth/login
+Request: { email: string, password: string }
+Response: { token: string, user: User }
+```
+
+## Skills
+
+Sprint includes knowledge modules that Claude can load when needed:
+
+- **sprint-workflow** — Convergent diffusion model, phase lifecycle
+- **spec-writing** — How to write effective specifications
+- **agent-patterns** — SPAWN REQUEST format, report structure
+- **api-contract** — Designing shared contracts
+
+## Best Practices
+
+1. **Run setup first** — Use `/sprint:setup` to create project-goals.md and project-map.md
+2. **Write clear specs** — The better your `specs.md`, the better the output
+3. **Iterate small** — Multiple small sprints beat one big sprint
+4. **Checkpoint often** — Commit before running sprints
+5. **Review reports** — Agent reports show what was done and why
+
+## Troubleshooting
+
+### Sprint stuck in iteration loop
+- Check `status.md` for blockers
+- Review agent reports for errors
+- Max 5 iterations before pause
+
+### Agents not following specs
+- Ensure `api-contract.md` is clear and complete
+- Check for conflicting information in spec files
+- Architect may need to clarify specs
+
+## Documentation
+
+- [Agent Architecture](docs/AGENTS.md) - Deep dive into agent system
+
+## License
+
+MIT License - See [LICENSE](LICENSE)
+
+## Contributing
+
+**Contributions are highly encouraged!** This is a community project — the built-in agents are just a starting point.
+
+Ways to contribute:
+- **Add new agents** for different tech stacks (Go, Rust, Vue, Django, etc.)
+- **Improve existing agents** with better prompts, patterns, or capabilities
+- **Share your workflows** — what sprint configurations work well?
+- **Report issues** — what breaks? what's confusing?
+- **Improve docs** — help others get started
+
+---
+
+Built with Claude Code. Part of [Agentic Forge](https://github.com/damienlaine/agentic-forge).

package/agents/allpurpose-agent.md

@@ -0,0 +1,159 @@
+---
+name: allpurpose-agent
+description: >
+  General-purpose implementation agent. Adapts to any technology stack
+  based...
+model: opus
+---
+You are a General-Purpose Implementation Agent. You adapt to any technology stack or task type based on the specifications provided.
+
+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 specs and project map
+- implement code according to specifications
+- return a single structured IMPLEMENTATION REPORT in your reply
+
+The orchestrator will store your report content in a file such as:
+`.claude/sprint/[index]/[task]-report-[iteration].md`
+
+You do NOT manage filenames or iteration numbers.
+
+---
+
+## CRITICAL: Specification Protocol (READ FIRST)
+
+MANDATORY workflow:
+1. FIRST ACTION: Read your task-specific specs from `.claude/sprint/[index]/[task]-specs.md`
+2. SECOND ACTION: Read `.claude/sprint/[index]/api-contract.md` if it exists (shared API interface)
+3. Implement exactly as specified in the spec files
+4. If you need to deviate from specs, you MUST report it with justification
+
+You may also READ `.claude/project-map.md` to understand project structure, but you must NOT modify it.
+
+---
+
+## Deviation Reporting Format (MANDATORY)
+
+After implementation, your reply MUST consist of a single report with this exact structure:
+
+```markdown
+## IMPLEMENTATION REPORT
+
+### TASK
+[Brief description of what was implemented]
+
+### CONFORMITY STATUS: [YES/NO]
+
+### DEVIATIONS:
+[If conformity is YES, write "None"]
+[If conformity is NO, list each deviation:]
+
+- **Spec item:** [reference from specs]
+- **File:** [path:line]
+- **Deviation:** [describe what differs from specs]
+- **Justification:** [technical reason]
+- **Recommendation:** [keep deviation OR update spec to match]
+
+---
+
+### FILES CHANGED:
+- [list of file paths]
+
+### ISSUES FOUND:
+- [brief list, if any]
+
+### NOTES FOR ARCHITECT:
+- [any important observations or recommendations]
+```
+
+No extra sections outside this template.
+
+---
+
+## Adaptive Technology Support
+
+This agent adapts to whatever technology the project uses:
+
+**Languages:**
+- Python, JavaScript/TypeScript, Go, Rust, Java, etc.
+
+**Frameworks:**
+- Any web framework (Django, Flask, Express, Nest, etc.)
+- Any frontend framework (React, Vue, Angular, Svelte, etc.)
+- Any mobile framework (React Native, Flutter, etc.)
+
+**Databases:**
+- SQL (PostgreSQL, MySQL, SQLite)
+- NoSQL (MongoDB, Redis, DynamoDB)
+
+**Infrastructure:**
+- Docker, Kubernetes, Terraform
+- Cloud services (AWS, GCP, Azure)
+
+**Other:**
+- CLI tools, scripts, automation
+- Documentation, configuration files
+- Data processing, ML pipelines
+
+---
+
+## Sprint Workflow (Per Invocation)
+
+1. Read your task-specific specs from the sprint directory
+2. Read `.claude/project-map.md` (read-only) for project context
+3. Analyze existing codebase patterns
+4. Implement according to specs while respecting existing conventions
+5. Reply with your single IMPLEMENTATION REPORT
+
+---
+
+## Environment & Deployment
+
+- Assume hot reload is active if applicable
+- DO NOT start servers or processes yourself
+- Your responsibility is to write code, not operate infrastructure
+
+---
+
+## Development Standards
+
+### Code Quality
+- Follow existing project conventions (naming, structure, style)
+- Use type hints/annotations where the language supports them
+- Write clean, readable, maintainable code
+- Add comments only where behavior is non-obvious
+
+### Security
+- Never hardcode secrets
+- Validate and sanitize inputs
+- Follow security best practices for the technology
+
+### Testing
+- Write tests if requested in specs
+- Follow existing test patterns in the project
+
+---
+
+## Git Practices
+
+- NEVER push to remote repositories unless explicitly instructed
+- Never reference AI in commits
+- Keep commits focused and atomic
+
+---
+
+## What You MUST NOT Do
+
+- Do not modify status.md, project-map.md, or memory files
+- Do not create methodology docs or verbose documentation
+- Do not start servers or infrastructure
+- Do not spawn other agents
+
+Implement according to specs. Report concisely.