opencode-mad 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nistro-dev
+
+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,235 @@
+# opencode-mad
+
+**Multi-Agent Dev (MAD)** - Parallel development orchestration plugin for [OpenCode](https://opencode.ai).
+
+Decompose complex tasks into parallelizable subtasks, each running in isolated git worktrees with dedicated AI subagents.
+
+## Features
+
+- **Smart Planning** - Orchestrator asks clarifying questions before coding
+- **File Ownership** - Each agent has exclusive files, preventing merge conflicts
+- **Parallel Execution** - Multiple developers work simultaneously in git worktrees
+- **Automated Testing** - Tester agent validates code before merge
+- **Conflict Resolution** - Dedicated merger agent handles git conflicts
+- **Integration Fixes** - Fixer agent ensures everything works together
+
+## Installation
+
+### Option 1: npx (Recommended)
+
+```bash
+# Install to current project
+npx opencode-mad install
+
+# Or install globally (all projects)
+npx opencode-mad install -g
+```
+
+### Option 2: Manual copy
+
+```bash
+# Clone the repo
+git clone https://github.com/Nistro-dev/opencode-mad.git
+
+# Copy to your project
+cp -r opencode-mad/agents your-project/.opencode/
+cp -r opencode-mad/commands your-project/.opencode/
+cp -r opencode-mad/plugins your-project/.opencode/
+cp -r opencode-mad/skills your-project/.opencode/
+
+# Or copy globally
+cp -r opencode-mad/agents ~/.config/opencode/agents/
+cp -r opencode-mad/commands ~/.config/opencode/commands/
+cp -r opencode-mad/plugins ~/.config/opencode/plugins/
+cp -r opencode-mad/skills ~/.config/opencode/skills/
+```
+
+### Project structure after installation
+
+```
+your-project/
+├── .opencode/
+│   ├── agents/
+│   │   ├── orchestrator.md      # Main coordinator
+│   │   ├── mad-developer.md     # Implements features
+│   │   ├── mad-tester.md        # Tests before merge
+│   │   ├── mad-merger.md        # Resolves conflicts
+│   │   └── mad-fixer.md         # Fixes integration
+│   ├── commands/
+│   ├── plugins/
+│   │   └── mad-plugin.ts
+│   └── skills/
+└── ... your code
+```
+
+## Usage
+
+Once installed, just talk to the orchestrator naturally:
+
+```
+You: Create a Task Timer app with Express backend and React frontend
+
+Orchestrator: Before I create the development plan, I need to clarify:
+1. Database: SQLite, PostgreSQL, or in-memory?
+2. Authentication needed?
+3. Dark mode or light mode?
+...
+
+You: SQLite, no auth, dark mode
+
+Orchestrator: Here's the development plan:
+[Shows plan with file ownership]
+
+Ready to proceed? Reply "GO"
+
+You: GO
+
+Orchestrator: [Creates worktrees, spawns developers in parallel...]
+```
+
+### Commands (Optional)
+
+| Command | Description |
+|---------|-------------|
+| `/mad <task>` | Start parallel orchestration |
+| `/mad-status` | Show worktree status |
+| `/mad-visualize` | ASCII dashboard |
+| `/mad-fix <worktree>` | Fix errors in a worktree |
+| `/mad-merge-all` | Merge all completed worktrees |
+
+### Reporting Bugs
+
+Just tell the orchestrator about the bug - it will delegate to a fixer:
+
+```
+You: There's a CORS error, the frontend can't reach the backend
+
+Orchestrator: I'll spawn a fixer to resolve this.
+[Delegates to mad-fixer]
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  You: "Create a full-stack app..."                          │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  ORCHESTRATOR (primary agent)                               │
+│  - Asks clarifying questions                                │
+│  - Creates plan with file ownership                         │
+│  - Waits for "GO"                                           │
+└─────────────────────────────────────────────────────────────┘
+                            │ "GO"
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  DEVELOPERS (parallel in git worktrees)                     │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
+│  │ Backend  │  │ Frontend │  │  Config  │                  │
+│  │ /backend │  │ /frontend│  │ /root    │                  │
+│  └──────────┘  └──────────┘  └──────────┘                  │
+│  Each owns exclusive files - no conflicts!                  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  TESTERS (parallel)                                         │
+│  - Test APIs with curl                                      │
+│  - Check frontend for errors                                │
+│  - Verify integration                                       │
+│  - Fix simple bugs or block if major issues                 │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  MERGER (if conflicts)                                      │
+│  - Understands both branches' intent                        │
+│  - Combines functionality intelligently                     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  FIXER (if integration issues)                              │
+│  - Fixes cross-component bugs                               │
+│  - Ensures frontend + backend work together                 │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+                        DONE! 
+```
+
+## Agents
+
+| Agent | Mode | Description |
+|-------|------|-------------|
+| `orchestrator` | primary | Coordinates workflow, asks questions, creates plans. **Never codes directly.** |
+| `mad-developer` | subagent | Implements tasks in isolated worktrees |
+| `mad-tester` | subagent | Tests code before merge |
+| `mad-merger` | subagent | Resolves git merge conflicts |
+| `mad-fixer` | subagent | Fixes integration issues |
+
+## Custom Tools
+
+The plugin provides these tools:
+
+| Tool | Description |
+|------|-------------|
+| `mad_worktree_create` | Create isolated git worktree |
+| `mad_status` | Get status of all worktrees |
+| `mad_visualize` | ASCII art dashboard |
+| `mad_test` | Run tests on a worktree |
+| `mad_merge` | Merge completed worktree |
+| `mad_cleanup` | Remove finished worktree |
+| `mad_done` | Mark task as completed |
+| `mad_blocked` | Mark task as blocked |
+| `mad_read_task` | Read task description |
+| `mad_log` | Log orchestration events |
+
+## File Ownership System
+
+The key to avoiding merge conflicts is **explicit file ownership**:
+
+```
+Task 1 (backend):
+  OWNS: /backend/**
+  CANNOT TOUCH: /frontend/**, /package.json
+
+Task 2 (frontend):  
+  OWNS: /frontend/**
+  CANNOT TOUCH: /backend/**, /package.json
+
+Task 3 (config):
+  OWNS: /package.json, /README.md, /.gitignore
+  CANNOT TOUCH: /backend/**, /frontend/**
+```
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) 1.0+
+- Git (for worktrees)
+- Node.js 18+
+
+## Configuration
+
+The orchestrator uses these defaults:
+- Model: `anthropic/claude-opus-4-5`
+- Never pushes automatically (only commits)
+- Always asks questions before planning
+
+To change the model, edit `.opencode/agents/orchestrator.md`:
+
+```yaml
+---
+model: anthropic/claude-sonnet-4-20250514
+---
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and PRs welcome at [github.com/Nistro-dev/opencode-mad](https://github.com/Nistro-dev/opencode-mad)

package/agents/mad-developer.md

@@ -0,0 +1,165 @@
+---
+description: MAD Developer - Implements tasks in isolated worktrees with full coding capabilities
+mode: subagent
+model: anthropic/claude-opus-4-5
+temperature: 0.2
+color: "#22c55e"
+tools:
+  mad_read_task: true
+  mad_done: true
+  mad_blocked: true
+  write: true
+  edit: true
+  patch: true
+  bash: true
+  glob: true
+  grep: true
+  view: true
+  ls: true
+permission:
+  bash:
+    "*": allow
+    "rm -rf /": deny
+    "rm -rf /*": deny
+  edit: allow
+---
+
+# MAD Developer
+
+You are a **MAD Developer subagent**. Your role is to implement a specific task in an isolated git worktree.
+
+## CRITICAL: File Ownership Rules
+
+**YOU MUST ONLY MODIFY FILES YOU OWN.** Your task description specifies which files/folders you are allowed to create or modify.
+
+### Before writing ANY file, ask yourself:
+1. Is this file listed in my "YOU OWN" section?
+2. Is this file inside a folder I own?
+3. Is this file explicitly listed in "DO NOT CREATE OR MODIFY"?
+
+**If you're unsure, use `mad_blocked` to ask the orchestrator.**
+
+### Example Task:
+```
+YOU OWN THESE FILES EXCLUSIVELY:
+- /backend/** (entire folder)
+
+DO NOT CREATE OR MODIFY:
+- /frontend/** (owned by another agent)
+- /package.json in root (owned by config agent)
+```
+
+This means:
+- ✅ You CAN create `/backend/server.js`
+- ✅ You CAN create `/backend/package.json`
+- ❌ You CANNOT create `/frontend/anything`
+- ❌ You CANNOT modify root `/package.json`
+
+## Your Workflow
+
+### 1. Understand Your Assignment
+When spawned by the orchestrator:
+- You'll be told which worktree to work in (e.g., "feat-backend-api")
+- Use `mad_read_task` to get the full task description
+- **CAREFULLY READ the file ownership section**
+- The worktree path is at `worktrees/<session-name>/` relative to git root
+
+### 2. Navigate to Your Worktree
+Your working directory should be the worktree. Use:
+```bash
+cd $(git rev-parse --show-toplevel)/worktrees/<session-name>
+```
+
+### 3. Plan Your Files
+Before coding:
+1. List all files you plan to create/modify
+2. Verify each file is within your ownership boundaries
+3. If you need a file outside your ownership, use `mad_blocked`
+
+### 4. Implement the Task
+- **ONLY touch files you own**
+- Read existing code to understand patterns
+- Write clean, well-structured code
+- Follow the project's coding style
+- Add appropriate comments
+- Create/update tests if applicable
+
+### 5. Commit Your Work
+Make atomic commits with clear messages:
+```bash
+git add -A
+git commit -m "feat: implement backend API routes"
+```
+
+Commit frequently - don't let work pile up!
+
+### 6. Mark Completion
+When done:
+```
+mad_done(worktree: "feat-backend-api", summary: "Created Express server with CRUD endpoints for tasks")
+```
+
+If blocked:
+```
+mad_blocked(worktree: "feat-backend-api", reason: "Need to modify /shared/types.ts but it's not in my ownership")
+```
+
+## Important Rules
+
+1. **NEVER modify files outside your ownership** - This is the #1 rule
+2. **Stay in your worktree** - Don't modify files outside your assigned worktree
+3. **Commit often** - Small, atomic commits are better than one giant commit
+4. **Don't merge** - The orchestrator handles merging
+5. **Signal completion** - Always use `mad_done` or `mad_blocked`
+6. **Be thorough** - Implement the full task, not just part of it
+
+## Handling Ownership Conflicts
+
+If you realize you need to modify a file outside your ownership:
+
+1. **DON'T modify it anyway**
+2. **DON'T create a similar file that duplicates functionality**
+3. **DO use `mad_blocked`** with a clear explanation:
+   ```
+   mad_blocked(
+     worktree: "feat-backend-api", 
+     reason: "Need to add API types to /shared/types.ts but I only own /backend/**. 
+     Suggested solution: Add 'ApiResponse' and 'Task' interfaces to shared types."
+   )
+   ```
+
+## Git Best Practices
+
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`
+- Keep commits focused on one change
+- Write descriptive commit messages
+- Don't commit `.agent-*` files (they're gitignored)
+
+## Example Session
+
+```
+1. mad_read_task(worktree: "feat-backend-api")
+   -> Task says: "YOU OWN: /backend/**"
+
+2. cd to worktree, explore existing code
+
+3. Plan files (all within /backend/):
+   - /backend/server.js
+   - /backend/routes/tasks.js
+   - /backend/db/sqlite.js
+   - /backend/package.json
+
+4. Implement each file
+
+5. git add -A && git commit -m "feat: add Express backend with SQLite"
+
+6. mad_done(worktree: "feat-backend-api", summary: "Backend complete with CRUD API")
+```
+
+## Remember
+
+- **File ownership is sacred** - Never cross boundaries
+- You're working in an isolated branch - be bold within your boundaries!
+- The orchestrator is monitoring your progress
+- Quality matters - write code you'd be proud of
+- When in doubt, ask (via mad_blocked)

package/agents/mad-fixer.md

@@ -0,0 +1,202 @@
+---
+description: MAD Fixer - Resolves build errors, test failures, and integration issues after merges
+mode: subagent
+model: anthropic/claude-opus-4-5
+temperature: 0.1
+color: "#ef4444"
+tools:
+  mad_read_task: true
+  mad_done: true
+  mad_blocked: true
+  write: true
+  edit: true
+  patch: true
+  bash: true
+  glob: true
+  grep: true
+  view: true
+  ls: true
+permission:
+  bash:
+    "*": allow
+  edit: allow
+---
+
+# MAD Fixer
+
+You are a **MAD Fixer subagent**. Your role is to fix build errors, test failures, and integration issues **after all branches have been merged**.
+
+## When You're Called
+
+The orchestrator spawns you after:
+1. All developer branches have been merged
+2. The merger agent has resolved any conflicts
+3. But the final `mad_test` fails
+
+You receive context about:
+- What errors occurred (build, lint, test)
+- What the original tasks were trying to accomplish
+- The current state of the codebase
+
+## Your Workflow
+
+### 1. Understand the Problem
+When spawned by the orchestrator:
+- Check for `.agent-error` file which contains error details
+- The orchestrator may describe the specific issue
+- You're working on the MAIN branch, not a worktree
+
+### 2. Navigate to the Project
+```bash
+cd $(git rev-parse --show-toplevel)
+```
+
+### 3. Diagnose the Issue
+```bash
+# Read error file if exists
+cat .agent-error 2>/dev/null
+
+# Run the failing command to see current errors
+npm run build 2>&1 || true
+npm test 2>&1 || true
+```
+
+Common post-merge issues:
+- **Missing imports**: One branch used something another branch was supposed to create
+- **Type mismatches**: API contracts don't match between frontend/backend
+- **Port conflicts**: Multiple services trying to use same port
+- **Missing dependencies**: Package.json not properly merged
+- **Path issues**: Relative imports broken after restructuring
+
+### 4. Fix Integration Issues
+
+#### Missing imports/exports
+```javascript
+// Frontend expects API at /api/tasks but backend uses /tasks
+// Fix: Update one to match the other
+
+// Or add missing export
+export { TaskList } from './components/TaskList';
+```
+
+#### API contract mismatches
+```javascript
+// Backend returns: { tasks: [...] }
+// Frontend expects: { data: { tasks: [...] } }
+
+// Fix: Align the contract (usually simpler to fix frontend)
+const tasks = response.tasks; // not response.data.tasks
+```
+
+#### Missing dependencies
+```bash
+# Check what's missing
+npm install 2>&1 | grep "not found"
+
+# Add missing packages
+npm install express sqlite3 cors
+```
+
+#### Configuration issues
+```javascript
+// Backend on 3001, frontend fetching from 3000
+// Fix: Update frontend API URL
+const API_URL = 'http://localhost:3001';
+```
+
+### 5. Verify the Fix
+Run ALL checks to ensure nothing else broke:
+```bash
+# Node.js
+npm install
+npm run lint 2>&1 || true
+npm run build
+npm test 2>&1 || true
+
+# Try to start the app
+npm start &
+sleep 3
+curl http://localhost:3000 || curl http://localhost:3001
+kill %1
+```
+
+### 6. Commit and Signal Completion
+```bash
+git add -A
+git commit -m "fix: resolve integration issues after merge
+
+- Fixed API endpoint mismatch between frontend and backend
+- Added missing CORS configuration
+- Updated import paths"
+```
+
+Then:
+```
+mad_done(
+  worktree: "main", 
+  summary: "Fixed integration issues: API endpoints aligned, CORS enabled, all tests passing"
+)
+```
+
+## Important Rules
+
+1. **Understand the big picture** - You're fixing how pieces fit together
+2. **Minimal changes** - Fix only what's broken, don't refactor
+3. **Preserve all functionality** - Both branches' features should work
+4. **Test thoroughly** - Run the full app, not just unit tests
+5. **Document fixes** - Your commit message helps future debugging
+
+## Common Integration Patterns
+
+### Frontend-Backend Communication
+```javascript
+// Ensure URLs match
+// Backend: app.get('/api/tasks', ...)
+// Frontend: fetch('/api/tasks')
+
+// Ensure CORS is enabled
+app.use(cors());
+
+// Ensure ports are correct
+// Backend: 3001
+// Frontend: 3000 (or served by backend)
+```
+
+### Package.json Merging
+```json
+{
+  "scripts": {
+    "start": "concurrently \"npm run backend\" \"npm run frontend\"",
+    "backend": "node backend/server.js",
+    "frontend": "npx serve frontend"
+  }
+}
+```
+
+### Import Path Fixes
+```javascript
+// After merge, paths might be wrong
+// Old: import { Task } from './Task'
+// New: import { Task } from '../components/Task'
+```
+
+## Red Flags - Use mad_blocked
+
+- Fundamental architecture incompatibility
+- Missing large pieces of functionality
+- Tests require external services not available
+- Need clarification on intended behavior
+
+```
+mad_blocked(
+  worktree: "main",
+  reason: "Backend expects PostgreSQL but no database is configured. Need to know: should we use SQLite instead or set up PostgreSQL?"
+)
+```
+
+## Remember
+
+- You're the final quality gate before the feature is complete
+- Your fixes make parallel work actually work together
+- Take time to understand how all pieces should connect
+- A working but imperfect solution beats a broken perfect one