opencode-mad 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +238 -235
  2. package/agents/mad-fixer.md +44 -31
  3. package/agents/mad-merger.md +45 -18
  4. package/agents/mad-tester.md +187 -224
  5. package/agents/orchestrator.md +510 -430
  6. package/install.js +85 -66
  7. package/package.json +36 -36
  8. package/plugins/mad-plugin.ts +627 -546
  9. package/skills/mad-workflow/SKILL.md +27 -0
package/README.md CHANGED
@@ -1,235 +1,238 @@
1
- # opencode-mad
2
-
3
- **Multi-Agent Dev (MAD)** - Parallel development orchestration plugin for [OpenCode](https://opencode.ai).
4
-
5
- Decompose complex tasks into parallelizable subtasks, each running in isolated git worktrees with dedicated AI subagents.
6
-
7
- ## Features
8
-
9
- - **Smart Planning** - Orchestrator asks clarifying questions before coding
10
- - **File Ownership** - Each agent has exclusive files, preventing merge conflicts
11
- - **Parallel Execution** - Multiple developers work simultaneously in git worktrees
12
- - **Automated Testing** - Tester agent validates code before merge
13
- - **Conflict Resolution** - Dedicated merger agent handles git conflicts
14
- - **Integration Fixes** - Fixer agent ensures everything works together
15
-
16
- ## Installation
17
-
18
- ### Option 1: npx (Recommended)
19
-
20
- ```bash
21
- # Install to current project
22
- npx opencode-mad install
23
-
24
- # Or install globally (all projects)
25
- npx opencode-mad install -g
26
- ```
27
-
28
- ### Option 2: Manual copy
29
-
30
- ```bash
31
- # Clone the repo
32
- git clone https://github.com/Nistro-dev/opencode-mad.git
33
-
34
- # Copy to your project
35
- cp -r opencode-mad/agents your-project/.opencode/
36
- cp -r opencode-mad/commands your-project/.opencode/
37
- cp -r opencode-mad/plugins your-project/.opencode/
38
- cp -r opencode-mad/skills your-project/.opencode/
39
-
40
- # Or copy globally
41
- cp -r opencode-mad/agents ~/.config/opencode/agents/
42
- cp -r opencode-mad/commands ~/.config/opencode/commands/
43
- cp -r opencode-mad/plugins ~/.config/opencode/plugins/
44
- cp -r opencode-mad/skills ~/.config/opencode/skills/
45
- ```
46
-
47
- ### Project structure after installation
48
-
49
- ```
50
- your-project/
51
- ├── .opencode/
52
- │ ├── agents/
53
- │ │ ├── orchestrator.md # Main coordinator
54
- │ │ ├── mad-developer.md # Implements features
55
- │ │ ├── mad-tester.md # Tests before merge
56
- │ │ ├── mad-merger.md # Resolves conflicts
57
- │ │ └── mad-fixer.md # Fixes integration
58
- │ ├── commands/
59
- │ ├── plugins/
60
- │ │ └── mad-plugin.ts
61
- │ └── skills/
62
- └── ... your code
63
- ```
64
-
65
- ## Usage
66
-
67
- Once installed, just talk to the orchestrator naturally:
68
-
69
- ```
70
- You: Create a Task Timer app with Express backend and React frontend
71
-
72
- Orchestrator: Before I create the development plan, I need to clarify:
73
- 1. Database: SQLite, PostgreSQL, or in-memory?
74
- 2. Authentication needed?
75
- 3. Dark mode or light mode?
76
- ...
77
-
78
- You: SQLite, no auth, dark mode
79
-
80
- Orchestrator: Here's the development plan:
81
- [Shows plan with file ownership]
82
-
83
- Ready to proceed? Reply "GO"
84
-
85
- You: GO
86
-
87
- Orchestrator: [Creates worktrees, spawns developers in parallel...]
88
- ```
89
-
90
- ### Commands (Optional)
91
-
92
- | Command | Description |
93
- |---------|-------------|
94
- | `/mad <task>` | Start parallel orchestration |
95
- | `/mad-status` | Show worktree status |
96
- | `/mad-visualize` | ASCII dashboard |
97
- | `/mad-fix <worktree>` | Fix errors in a worktree |
98
- | `/mad-merge-all` | Merge all completed worktrees |
99
-
100
- ### Reporting Bugs
101
-
102
- Just tell the orchestrator about the bug - it will delegate to a fixer:
103
-
104
- ```
105
- You: There's a CORS error, the frontend can't reach the backend
106
-
107
- Orchestrator: I'll spawn a fixer to resolve this.
108
- [Delegates to mad-fixer]
109
- ```
110
-
111
- ## How It Works
112
-
113
- ```
114
- ┌─────────────────────────────────────────────────────────────┐
115
- │ You: "Create a full-stack app..." │
116
- └─────────────────────────────────────────────────────────────┘
117
- │
118
- ▼
119
- ┌─────────────────────────────────────────────────────────────┐
120
- │ ORCHESTRATOR (primary agent) │
121
- │ - Asks clarifying questions │
122
- │ - Creates plan with file ownership │
123
- │ - Waits for "GO" │
124
- └─────────────────────────────────────────────────────────────┘
125
- │ "GO"
126
- ▼
127
- ┌─────────────────────────────────────────────────────────────┐
128
- │ DEVELOPERS (parallel in git worktrees) │
129
- │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
130
- │ │ Backend │ │ Frontend │ │ Config │ │
131
- │ │ /backend │ │ /frontend│ │ /root │ │
132
- │ └──────────┘ └──────────┘ └──────────┘ │
133
- │ Each owns exclusive files - no conflicts! │
134
- └─────────────────────────────────────────────────────────────┘
135
- │
136
- ▼
137
- ┌─────────────────────────────────────────────────────────────┐
138
- │ TESTERS (parallel) │
139
- │ - Test APIs with curl │
140
- │ - Check frontend for errors │
141
- │ - Verify integration │
142
- │ - Fix simple bugs or block if major issues │
143
- └─────────────────────────────────────────────────────────────┘
144
- │
145
- ▼
146
- ┌─────────────────────────────────────────────────────────────┐
147
- │ MERGER (if conflicts) │
148
- │ - Understands both branches' intent │
149
- │ - Combines functionality intelligently │
150
- └─────────────────────────────────────────────────────────────┘
151
- │
152
- ▼
153
- ┌─────────────────────────────────────────────────────────────┐
154
- │ FIXER (if integration issues) │
155
- │ - Fixes cross-component bugs │
156
- │ - Ensures frontend + backend work together │
157
- └─────────────────────────────────────────────────────────────┘
158
- │
159
- ▼
160
- DONE!
161
- ```
162
-
163
- ## Agents
164
-
165
- | Agent | Mode | Description |
166
- |-------|------|-------------|
167
- | `orchestrator` | primary | Coordinates workflow, asks questions, creates plans. **Never codes directly.** |
168
- | `mad-developer` | subagent | Implements tasks in isolated worktrees |
169
- | `mad-tester` | subagent | Tests code before merge |
170
- | `mad-merger` | subagent | Resolves git merge conflicts |
171
- | `mad-fixer` | subagent | Fixes integration issues |
172
-
173
- ## Custom Tools
174
-
175
- The plugin provides these tools:
176
-
177
- | Tool | Description |
178
- |------|-------------|
179
- | `mad_worktree_create` | Create isolated git worktree |
180
- | `mad_status` | Get status of all worktrees |
181
- | `mad_visualize` | ASCII art dashboard |
182
- | `mad_test` | Run tests on a worktree |
183
- | `mad_merge` | Merge completed worktree |
184
- | `mad_cleanup` | Remove finished worktree |
185
- | `mad_done` | Mark task as completed |
186
- | `mad_blocked` | Mark task as blocked |
187
- | `mad_read_task` | Read task description |
188
- | `mad_log` | Log orchestration events |
189
-
190
- ## File Ownership System
191
-
192
- The key to avoiding merge conflicts is **explicit file ownership**:
193
-
194
- ```
195
- Task 1 (backend):
196
- OWNS: /backend/**
197
- CANNOT TOUCH: /frontend/**, /package.json
198
-
199
- Task 2 (frontend):
200
- OWNS: /frontend/**
201
- CANNOT TOUCH: /backend/**, /package.json
202
-
203
- Task 3 (config):
204
- OWNS: /package.json, /README.md, /.gitignore
205
- CANNOT TOUCH: /backend/**, /frontend/**
206
- ```
207
-
208
- ## Requirements
209
-
210
- - [OpenCode](https://opencode.ai) 1.0+
211
- - Git (for worktrees)
212
- - Node.js 18+
213
-
214
- ## Configuration
215
-
216
- The orchestrator uses these defaults:
217
- - Model: `anthropic/claude-opus-4-5`
218
- - Never pushes automatically (only commits)
219
- - Always asks questions before planning
220
-
221
- To change the model, edit `.opencode/agents/orchestrator.md`:
222
-
223
- ```yaml
224
- ---
225
- model: anthropic/claude-sonnet-4-20250514
226
- ---
227
- ```
228
-
229
- ## License
230
-
231
- MIT
232
-
233
- ## Contributing
234
-
235
- Issues and PRs welcome at [github.com/Nistro-dev/opencode-mad](https://github.com/Nistro-dev/opencode-mad)
1
+ # opencode-mad
2
+
3
+ **Multi-Agent Dev (MAD)** - Parallel development orchestration plugin for [OpenCode](https://opencode.ai).
4
+
5
+ Decompose complex tasks into parallelizable subtasks, each running in isolated git worktrees with dedicated AI subagents.
6
+
7
+ ## Features
8
+
9
+ - **Smart Planning** - Orchestrator asks clarifying questions before coding
10
+ - **File Ownership** - Each agent has exclusive files, preventing merge conflicts
11
+ - **Parallel Execution** - Multiple developers work simultaneously in git worktrees
12
+ - **Automated Testing** - Tester agent validates code before merge
13
+ - **Conflict Resolution** - Dedicated merger agent handles git conflicts
14
+ - **Integration Fixes** - Fixer agent ensures everything works together
15
+
16
+ ## Installation
17
+
18
+ ### Option 1: npx (Recommended)
19
+
20
+ ```bash
21
+ # Install to current project
22
+ npx opencode-mad install
23
+
24
+ # Or install globally (all projects)
25
+ npx opencode-mad install -g
26
+
27
+ # Update existing installation
28
+ npx opencode-mad update -g
29
+
30
+ # Check version
31
+ npx opencode-mad version
32
+ ```
33
+
34
+ ### Option 2: Manual copy
35
+
36
+ ```bash
37
+ # Clone the repo
38
+ git clone https://github.com/Nistro-dev/opencode-mad.git
39
+
40
+ # Copy to your project
41
+ cp -r opencode-mad/agents your-project/.opencode/
42
+ cp -r opencode-mad/commands your-project/.opencode/
43
+ cp -r opencode-mad/plugins your-project/.opencode/
44
+ cp -r opencode-mad/skills your-project/.opencode/
45
+
46
+ # Or copy globally
47
+ cp -r opencode-mad/agents ~/.config/opencode/agents/
48
+ cp -r opencode-mad/commands ~/.config/opencode/commands/
49
+ cp -r opencode-mad/plugins ~/.config/opencode/plugins/
50
+ cp -r opencode-mad/skills ~/.config/opencode/skills/
51
+ ```
52
+
53
+ ### Project structure after installation
54
+
55
+ ```
56
+ your-project/
57
+ ├── .opencode/
58
+ │ ├── agents/
59
+ │ │ ├── orchestrator.md # Main coordinator
60
+ │ │ ├── mad-developer.md # Implements features
61
+ │ │ ├── mad-tester.md # Tests before merge
62
+ │ │ ├── mad-merger.md # Resolves conflicts
63
+ │ │ └── mad-fixer.md # Fixes integration
64
+ │ ├── commands/
65
+ │ ├── plugins/
66
+ │ │ └── mad-plugin.ts
67
+ │ └── skills/
68
+ └── ... your code
69
+ ```
70
+
71
+ ## Usage
72
+
73
+ Once installed, just talk to the orchestrator naturally:
74
+
75
+ ```
76
+ You: Create a Task Timer app with Express backend and React frontend
77
+
78
+ Orchestrator: Before I create the development plan, I need to clarify:
79
+ 1. Database: SQLite, PostgreSQL, or in-memory?
80
+ 2. Authentication needed?
81
+ 3. Dark mode or light mode?
82
+ ...
83
+
84
+ You: SQLite, no auth, dark mode
85
+
86
+ Orchestrator: Here's the development plan:
87
+ [Shows plan with file ownership]
88
+
89
+ Ready to proceed? Reply "GO"
90
+
91
+ You: GO
92
+
93
+ Orchestrator: [Creates worktrees, spawns developers in parallel...]
94
+ ```
95
+
96
+ ### Commands (Optional)
97
+
98
+ | Command | Description |
99
+ |---------|-------------|
100
+ | `/mad <task>` | Start parallel orchestration |
101
+ | `/mad-status` | Show worktree status |
102
+ | `/mad-visualize` | ASCII dashboard |
103
+ | `/mad-fix <worktree>` | Fix errors in a worktree |
104
+ | `/mad-merge-all` | Merge all completed worktrees |
105
+
106
+ ### Reporting Bugs
107
+
108
+ Just tell the orchestrator about the bug - it will delegate to a fixer:
109
+
110
+ ```
111
+ You: There's a CORS error, the frontend can't reach the backend
112
+
113
+ Orchestrator: I'll spawn a fixer to resolve this.
114
+ [Delegates to mad-fixer]
115
+ ```
116
+
117
+ ## How It Works
118
+
119
+ ```
120
+ ┌─────────────────────────────────────────────────────────────┐
121
+ │ You: "Create a full-stack app..." │
122
+ └─────────────────────────────────────────────────────────────┘
123
+ │
124
+ ▼
125
+ ┌─────────────────────────────────────────────────────────────┐
126
+ │ ORCHESTRATOR (primary agent) │
127
+ │ - Asks clarifying questions │
128
+ │ - Creates plan with file ownership │
129
+ │ - Waits for "GO" │
130
+ └─────────────────────────────────────────────────────────────┘
131
+ │ "GO"
132
+ ▼
133
+ ┌─────────────────────────────────────────────────────────────┐
134
+ │ DEVELOPERS (parallel in git worktrees) │
135
+ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
136
+ │ │ Backend │ │ Frontend │ │ Config │ │
137
+ │ │ /backend │ │ /frontend│ │ /root │ │
138
+ │ └──────────┘ └──────────┘ └──────────┘ │
139
+ │ Each owns exclusive files - no conflicts! │
140
+ └─────────────────────────────────────────────────────────────┘
141
+ │
142
+ ▼
143
+ ┌─────────────────────────────────────────────────────────────┐
144
+ │ TESTERS (parallel) │
145
+ │ - Test APIs with curl │
146
+ │ - Check frontend for errors │
147
+ │ - Verify integration │
148
+ │ - Fix simple bugs or block if major issues │
149
+ └─────────────────────────────────────────────────────────────┘
150
+ │
151
+ ▼
152
+ ┌─────────────────────────────────────────────────────────────┐
153
+ │ MERGER (if conflicts) │
154
+ │ - Understands both branches' intent │
155
+ │ - Combines functionality intelligently │
156
+ └─────────────────────────────────────────────────────────────┘
157
+ │
158
+ ▼
159
+ ┌─────────────────────────────────────────────────────────────┐
160
+ │ FIXER (if integration issues) │
161
+ │ - Fixes cross-component bugs │
162
+ │ - Ensures frontend + backend work together │
163
+ └─────────────────────────────────────────────────────────────┘
164
+ │
165
+ ▼
166
+ DONE!
167
+ ```
168
+
169
+ ## Agents
170
+
171
+ | Agent | Mode | Description |
172
+ |-------|------|-------------|
173
+ | `orchestrator` | primary | Coordinates workflow, asks questions, creates plans. **Never codes directly.** |
174
+ | `mad-developer` | subagent | Implements tasks in isolated worktrees |
175
+ | `mad-tester` | subagent | Tests code before merge |
176
+ | `mad-merger` | subagent | Resolves git merge conflicts |
177
+ | `mad-fixer` | subagent | Fixes integration issues |
178
+
179
+ ## Custom Tools
180
+
181
+ The plugin provides these tools:
182
+
183
+ | Tool | Description |
184
+ |------|-------------|
185
+ | `mad_worktree_create` | Create isolated git worktree |
186
+ | `mad_status` | Get status of all worktrees |
187
+ | `mad_visualize` | ASCII art dashboard |
188
+ | `mad_test` | Run tests on a worktree |
189
+ | `mad_merge` | Merge completed worktree |
190
+ | `mad_cleanup` | Remove finished worktree |
191
+ | `mad_done` | Mark task as completed |
192
+ | `mad_blocked` | Mark task as blocked |
193
+ | `mad_read_task` | Read task description |
194
+ | `mad_log` | Log orchestration events |
195
+ | `mad_check_update` | Check for plugin updates |
196
+
197
+ ## Updates
198
+
199
+ opencode-mad checks for updates automatically and notifies you when a new version is available.
200
+
201
+ To update manually:
202
+ ```bash
203
+ npx opencode-mad update -g
204
+ ```
205
+
206
+ To check for updates:
207
+ ```bash
208
+ npx opencode-mad version
209
+ ```
210
+
211
+ ## Requirements
212
+
213
+ - [OpenCode](https://opencode.ai) 1.0+
214
+ - Git (for worktrees)
215
+ - Node.js 18+
216
+
217
+ ## Configuration
218
+
219
+ The orchestrator uses these defaults:
220
+ - Model: `anthropic/claude-opus-4-5`
221
+ - Never pushes automatically (only commits)
222
+ - Always asks questions before planning
223
+
224
+ To change the model, edit `.opencode/agents/orchestrator.md`:
225
+
226
+ ```yaml
227
+ ---
228
+ model: anthropic/claude-sonnet-4-20250514
229
+ ---
230
+ ```
231
+
232
+ ## License
233
+
234
+ MIT
235
+
236
+ ## Contributing
237
+
238
+ Issues and PRs welcome at [github.com/Nistro-dev/opencode-mad](https://github.com/Nistro-dev/opencode-mad)
package/agents/mad-fixer.md CHANGED
@@ -1,21 +1,21 @@
1
- ---
2
- description: MAD Fixer - Resolves build errors, test failures, and integration issues after merges
3
- mode: subagent
4
- model: anthropic/claude-opus-4-5
5
- temperature: 0.1
6
- color: "#ef4444"
1
+ ---
2
+ description: MAD Fixer - Resolves build errors, test failures, and integration issues in worktrees
3
+ mode: subagent
4
+ model: anthropic/claude-opus-4-5
5
+ temperature: 0.1
6
+ color: "#ef4444"
7
7
  tools:
8
8
  mad_read_task: true
9
9
  mad_done: true
10
10
  mad_blocked: true
11
- write: true
12
- edit: true
13
- patch: true
11
+ mad_worktree_create: true
12
+ mad_test: true
14
13
  bash: true
15
14
  glob: true
16
15
  grep: true
17
- view: true
18
- ls: true
16
+ read: true
17
+ write: true
18
+ edit: true
19
19
  permission:
20
20
  bash:
21
21
  "*": allow
@@ -24,33 +24,36 @@ permission:
24
24
 
25
25
  # MAD Fixer
26
26
 
27
- You are a **MAD Fixer subagent**. Your role is to fix build errors, test failures, and integration issues **after all branches have been merged**.
27
+ You are a **MAD Fixer subagent**. Your role is to fix build errors, test failures, and integration issues **in an isolated worktree**.
28
28
 
29
- ## When You're Called
29
+ ## CRITICAL: NEVER Work on Main Directly
30
30
 
31
- The orchestrator spawns you after:
32
- 1. All developer branches have been merged
33
- 2. The merger agent has resolved any conflicts
34
- 3. But the final `mad_test` fails
31
+ **ALL fixes MUST be done in a worktree.** You NEVER modify code on main directly.
32
+
33
+ ## When You're Called
35
34
 
35
+ The orchestrator spawns you with a worktree already created for your fix.
36
36
  You receive context about:
37
37
  - What errors occurred (build, lint, test)
38
38
  - What the original tasks were trying to accomplish
39
- - The current state of the codebase
39
+ - Which worktree to work in
40
40
 
41
41
  ## Your Workflow
42
42
 
43
- ### 1. Understand the Problem
44
- When spawned by the orchestrator:
45
- - Check for `.agent-error` file which contains error details
46
- - The orchestrator may describe the specific issue
47
- - You're working on the MAIN branch, not a worktree
43
+ ### 1. Read Your Task
44
+ ```
45
+ mad_read_task(worktree: "fix-<issue-name>")
46
+ ```
48
47
 
49
- ### 2. Navigate to the Project
48
+ Understand what needs to be fixed and which worktree you're working in.
49
+
50
+ ### 2. Navigate to Your Worktree
50
51
  ```bash
51
- cd $(git rev-parse --show-toplevel)
52
+ cd $(git rev-parse --show-toplevel)/worktrees/<worktree-name>
52
53
  ```
53
54
 
55
+ **IMPORTANT: You work in a WORKTREE, not on main!**
56
+
54
57
  ### 3. Diagnose the Issue
55
58
  ```bash
56
59
  # Read error file if exists
@@ -123,21 +126,23 @@ kill %1
123
126
  ### 6. Commit and Signal Completion
124
127
  ```bash
125
128
  git add -A
126
- git commit -m "fix: resolve integration issues after merge
129
+ git commit -m "fix: resolve integration issues
127
130
 
128
131
  - Fixed API endpoint mismatch between frontend and backend
129
132
  - Added missing CORS configuration
130
133
  - Updated import paths"
131
134
  ```
132
135
 
133
- Then:
136
+ Then signal completion so the orchestrator can merge your fix:
134
137
  ```
135
138
  mad_done(
136
- worktree: "main",
139
+ worktree: "fix-<issue-name>",
137
140
  summary: "Fixed integration issues: API endpoints aligned, CORS enabled, all tests passing"
138
141
  )
139
142
  ```
140
143
 
144
+ **The orchestrator will then merge your worktree into main.**
145
+
141
146
  ## Important Rules
142
147
 
143
148
  1. **Understand the big picture** - You're fixing how pieces fit together
@@ -189,14 +194,22 @@ app.use(cors());
189
194
 
190
195
  ```
191
196
  mad_blocked(
192
- worktree: "main",
197
+ worktree: "fix-<issue-name>",
193
198
  reason: "Backend expects PostgreSQL but no database is configured. Need to know: should we use SQLite instead or set up PostgreSQL?"
194
199
  )
195
200
  ```
196
201
 
202
+ ## Important Rules
203
+
204
+ 1. **NEVER work on main directly** - Always work in your assigned worktree
205
+ 2. **Commit your changes** - Make atomic commits with clear messages
206
+ 3. **Call mad_done when finished** - The orchestrator handles merging
207
+ 4. **Use mad_blocked if stuck** - Don't guess, ask for clarification
208
+
197
209
  ## Remember
198
210
 
199
- - You're the final quality gate before the feature is complete
200
- - Your fixes make parallel work actually work together
211
+ - You're fixing issues in an isolated worktree
212
+ - Your fixes will be merged by the orchestrator after you're done
201
213
  - Take time to understand how all pieces should connect
202
214
  - A working but imperfect solution beats a broken perfect one
215
+ - **NEVER modify code on main - ALWAYS use your worktree!**