my-opencode 1.2.1 → 1.3.0
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.
- package/LICENSE +21 -21
- package/README.md +259 -180
- package/agents/architect.md +30 -30
- package/agents/code-reviewer.md +29 -29
- package/agents/executor.md +30 -30
- package/agents/fullstack-dev.md +57 -57
- package/agents/spec-writer.md +37 -37
- package/agents/team-lead.md +60 -60
- package/agents/tech-writer.md +30 -30
- package/agents/test-engineer.md +30 -30
- package/agents/verifier.md +33 -33
- package/bin/cli.js +341 -311
- package/bin/moc +199 -0
- package/opencode.json +170 -167
- package/package.json +50 -48
- package/plugins/README.md +64 -0
- package/plugins/provider-profile.mjs +139 -0
- package/scripts/postinstall.js +202 -182
- package/skills/adr/SKILL.md +91 -91
- package/skills/adr/references/templates.md +100 -100
- package/skills/adr/scripts/README.md +5 -5
- package/skills/dev-flow/SKILL.md +188 -188
- package/skills/dev-flow/references/code-phase.md +72 -72
- package/skills/dev-flow/references/contract-phase.md +81 -81
- package/skills/dev-flow/references/verify-phase.md +129 -129
- package/skills/dev-flow/scripts/README.md +3 -3
- package/skills/docs-gen/SKILL.md +162 -162
- package/skills/docs-gen/references/doc-styles.md +216 -216
- package/skills/docs-gen/scripts/README.md +5 -5
- package/skills/orchestrate/SKILL.md +112 -112
- package/skills/orchestrate/references/orchestration-patterns.md +56 -56
- package/skills/pr-review/SKILL.md +110 -110
- package/skills/pr-review/references/review-dimensions.md +117 -117
- package/skills/pr-review/references/security-checklist.md +122 -122
- package/skills/pr-review/scripts/README.md +5 -5
- package/skills/test-gen/SKILL.md +143 -143
- package/skills/test-gen/references/framework-detection.md +105 -105
- package/skills/test-gen/references/test-patterns.md +260 -260
- package/skills/test-gen/scripts/README.md +5 -5
|
@@ -1,216 +1,216 @@
|
|
|
1
|
-
# Doc Style Reference — Language-Specific Conventions
|
|
2
|
-
|
|
3
|
-
## TypeScript / JavaScript — JSDoc
|
|
4
|
-
|
|
5
|
-
```typescript
|
|
6
|
-
/**
|
|
7
|
-
* Creates a new user in the system.
|
|
8
|
-
*
|
|
9
|
-
* @param name - The user's display name (2-50 chars)
|
|
10
|
-
* @param email - The user's email address (must be unique)
|
|
11
|
-
* @returns The created user object with generated ID
|
|
12
|
-
* @throws {ValidationError} If name or email are invalid
|
|
13
|
-
* @throws {ConflictError} If email already exists
|
|
14
|
-
*/
|
|
15
|
-
async function createUser(name: string, email: string): Promise<User> {
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
### JSDoc Tags
|
|
19
|
-
| Tag | When to Use |
|
|
20
|
-
|-----|-------------|
|
|
21
|
-
| `@param name - desc` | Every function parameter |
|
|
22
|
-
| `@returns` | Non-void functions |
|
|
23
|
-
| `@throws` | Documented exceptions |
|
|
24
|
-
| `@template T` | Generic type parameters |
|
|
25
|
-
| `@deprecated reason` | Deprecated APIs, with migration path |
|
|
26
|
-
| `@example` | Usage example (preferred over prose) |
|
|
27
|
-
| `@see` | Cross-reference to related code |
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## TypeScript / JavaScript — TSDoc
|
|
32
|
-
|
|
33
|
-
```typescript
|
|
34
|
-
/**
|
|
35
|
-
* Creates a new user in the system.
|
|
36
|
-
*
|
|
37
|
-
* @param name - The user's display name (2-50 chars)
|
|
38
|
-
* @param email - The user's email address (must be unique)
|
|
39
|
-
* @returns The created user
|
|
40
|
-
*
|
|
41
|
-
* @example
|
|
42
|
-
* ```ts
|
|
43
|
-
* const user = await createUser('Alice', 'alice@test.com')
|
|
44
|
-
* ```
|
|
45
|
-
*/
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
TSDoc is a superset of JSDoc with better TypeScript integration. Prefer TSDoc in TypeScript projects.
|
|
49
|
-
|
|
50
|
-
---
|
|
51
|
-
|
|
52
|
-
## Python — Google Style Docstrings
|
|
53
|
-
|
|
54
|
-
```python
|
|
55
|
-
def create_user(name: str, email: str) -> User:
|
|
56
|
-
"""Create a new user in the system.
|
|
57
|
-
|
|
58
|
-
Args:
|
|
59
|
-
name: The user's display name (2-50 chars).
|
|
60
|
-
email: The user's email address (must be unique).
|
|
61
|
-
|
|
62
|
-
Returns:
|
|
63
|
-
The created user object with generated ID.
|
|
64
|
-
|
|
65
|
-
Raises:
|
|
66
|
-
ValidationError: If name or email are invalid.
|
|
67
|
-
ConflictError: If email already exists.
|
|
68
|
-
"""
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
## Python — NumPy Style Docstrings
|
|
74
|
-
|
|
75
|
-
```python
|
|
76
|
-
def create_user(name: str, email: str) -> User:
|
|
77
|
-
"""Create a new user in the system.
|
|
78
|
-
|
|
79
|
-
Parameters
|
|
80
|
-
----------
|
|
81
|
-
name : str
|
|
82
|
-
The user's display name (2-50 chars).
|
|
83
|
-
email : str
|
|
84
|
-
The user's email address (must be unique).
|
|
85
|
-
|
|
86
|
-
Returns
|
|
87
|
-
-------
|
|
88
|
-
User
|
|
89
|
-
The created user object with generated ID.
|
|
90
|
-
|
|
91
|
-
Raises
|
|
92
|
-
------
|
|
93
|
-
ValidationError
|
|
94
|
-
If name or email are invalid.
|
|
95
|
-
"""
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
---
|
|
99
|
-
|
|
100
|
-
## Python — reST Style (Sphinx)
|
|
101
|
-
|
|
102
|
-
```python
|
|
103
|
-
def create_user(name: str, email: str) -> User:
|
|
104
|
-
"""Create a new user in the system.
|
|
105
|
-
|
|
106
|
-
:param name: The user's display name (2-50 chars).
|
|
107
|
-
:param email: The user's email address (must be unique).
|
|
108
|
-
:returns: The created user object with generated ID.
|
|
109
|
-
:raises ValidationError: If name or email are invalid.
|
|
110
|
-
:raises ConflictError: If email already exists.
|
|
111
|
-
"""
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## Rust — rustdoc
|
|
117
|
-
|
|
118
|
-
```rust
|
|
119
|
-
/// Creates a new user in the system.
|
|
120
|
-
///
|
|
121
|
-
/// # Arguments
|
|
122
|
-
/// * `name` - The user's display name (2-50 chars)
|
|
123
|
-
/// * `email` - The user's email address (must be unique)
|
|
124
|
-
///
|
|
125
|
-
/// # Returns
|
|
126
|
-
/// The created `User` object
|
|
127
|
-
///
|
|
128
|
-
/// # Errors
|
|
129
|
-
/// Returns `ValidationError` if name or email are invalid.
|
|
130
|
-
/// Returns `ConflictError` if email already exists.
|
|
131
|
-
///
|
|
132
|
-
/// # Example
|
|
133
|
-
/// ```rust
|
|
134
|
-
/// let user = create_user("Alice", "alice@test.com")?;
|
|
135
|
-
/// ```
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
---
|
|
139
|
-
|
|
140
|
-
## Go — Godoc
|
|
141
|
-
|
|
142
|
-
```go
|
|
143
|
-
// CreateUser creates a new user in the system.
|
|
144
|
-
// It validates the input and checks for duplicate emails.
|
|
145
|
-
//
|
|
146
|
-
// Parameters:
|
|
147
|
-
// - name: the user's display name (2-50 chars)
|
|
148
|
-
// - email: the user's email address (must be unique)
|
|
149
|
-
//
|
|
150
|
-
// Returns the created user, or an error if validation fails
|
|
151
|
-
// or the email already exists.
|
|
152
|
-
func CreateUser(name string, email string) (*User, error) {
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
### Godoc Conventions
|
|
156
|
-
- First sentence is the summary (used in `go doc` listing)
|
|
157
|
-
- Use full sentences with proper punctuation
|
|
158
|
-
- Document function behavior, not implementation
|
|
159
|
-
- `//` only, no `/* */`
|
|
160
|
-
|
|
161
|
-
---
|
|
162
|
-
|
|
163
|
-
## ADR Template
|
|
164
|
-
|
|
165
|
-
```markdown
|
|
166
|
-
# ADR-001: Use PostgreSQL for Primary Database
|
|
167
|
-
|
|
168
|
-
**Date:** 2026-05-25
|
|
169
|
-
**Status:** Accepted
|
|
170
|
-
|
|
171
|
-
## Context
|
|
172
|
-
We need a primary database for storing user data.
|
|
173
|
-
The system needs strong consistency and complex queries.
|
|
174
|
-
|
|
175
|
-
## Decision
|
|
176
|
-
Use PostgreSQL 16 as the primary database.
|
|
177
|
-
|
|
178
|
-
## Consequences
|
|
179
|
-
- ✅ Strong consistency with ACID transactions
|
|
180
|
-
- ✅ Rich query capabilities (JSON, full-text search)
|
|
181
|
-
- ⚠️ Requires managed database service (increased cost)
|
|
182
|
-
- ⚠️ Schema migrations need careful planning
|
|
183
|
-
|
|
184
|
-
## Alternatives Considered
|
|
185
|
-
- MySQL: Similar capabilities but weaker JSON support
|
|
186
|
-
- MongoDB: Better horizontal scaling but eventual consistency
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
ADR numbering: sequential (`ADR-001`, `ADR-002`). Location: `docs/adr/`.
|
|
190
|
-
|
|
191
|
-
---
|
|
192
|
-
|
|
193
|
-
## CHANGELOG Template
|
|
194
|
-
|
|
195
|
-
```markdown
|
|
196
|
-
# Changelog
|
|
197
|
-
|
|
198
|
-
## [1.2.0] - 2026-05-25
|
|
199
|
-
|
|
200
|
-
### Added
|
|
201
|
-
- User creation API endpoint (POST /api/users)
|
|
202
|
-
- Email validation utility
|
|
203
|
-
|
|
204
|
-
### Changed
|
|
205
|
-
- Upgraded Express from 4.18 to 4.21
|
|
206
|
-
- Rate limiting now applied to all endpoints
|
|
207
|
-
|
|
208
|
-
### Fixed
|
|
209
|
-
- Memory leak in WebSocket connections
|
|
210
|
-
- Edge case in date parsing for timezone offsets
|
|
211
|
-
|
|
212
|
-
### Security
|
|
213
|
-
- Updated bcrypt dependency to patch CVE-2026-XXXX
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
Follow [Keep a Changelog](https://keepachangelog.com) convention unless project uses custom format.
|
|
1
|
+
# Doc Style Reference — Language-Specific Conventions
|
|
2
|
+
|
|
3
|
+
## TypeScript / JavaScript — JSDoc
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
/**
|
|
7
|
+
* Creates a new user in the system.
|
|
8
|
+
*
|
|
9
|
+
* @param name - The user's display name (2-50 chars)
|
|
10
|
+
* @param email - The user's email address (must be unique)
|
|
11
|
+
* @returns The created user object with generated ID
|
|
12
|
+
* @throws {ValidationError} If name or email are invalid
|
|
13
|
+
* @throws {ConflictError} If email already exists
|
|
14
|
+
*/
|
|
15
|
+
async function createUser(name: string, email: string): Promise<User> {
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### JSDoc Tags
|
|
19
|
+
| Tag | When to Use |
|
|
20
|
+
|-----|-------------|
|
|
21
|
+
| `@param name - desc` | Every function parameter |
|
|
22
|
+
| `@returns` | Non-void functions |
|
|
23
|
+
| `@throws` | Documented exceptions |
|
|
24
|
+
| `@template T` | Generic type parameters |
|
|
25
|
+
| `@deprecated reason` | Deprecated APIs, with migration path |
|
|
26
|
+
| `@example` | Usage example (preferred over prose) |
|
|
27
|
+
| `@see` | Cross-reference to related code |
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## TypeScript / JavaScript — TSDoc
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
/**
|
|
35
|
+
* Creates a new user in the system.
|
|
36
|
+
*
|
|
37
|
+
* @param name - The user's display name (2-50 chars)
|
|
38
|
+
* @param email - The user's email address (must be unique)
|
|
39
|
+
* @returns The created user
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* ```ts
|
|
43
|
+
* const user = await createUser('Alice', 'alice@test.com')
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
TSDoc is a superset of JSDoc with better TypeScript integration. Prefer TSDoc in TypeScript projects.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Python — Google Style Docstrings
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
def create_user(name: str, email: str) -> User:
|
|
56
|
+
"""Create a new user in the system.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
name: The user's display name (2-50 chars).
|
|
60
|
+
email: The user's email address (must be unique).
|
|
61
|
+
|
|
62
|
+
Returns:
|
|
63
|
+
The created user object with generated ID.
|
|
64
|
+
|
|
65
|
+
Raises:
|
|
66
|
+
ValidationError: If name or email are invalid.
|
|
67
|
+
ConflictError: If email already exists.
|
|
68
|
+
"""
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Python — NumPy Style Docstrings
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
def create_user(name: str, email: str) -> User:
|
|
77
|
+
"""Create a new user in the system.
|
|
78
|
+
|
|
79
|
+
Parameters
|
|
80
|
+
----------
|
|
81
|
+
name : str
|
|
82
|
+
The user's display name (2-50 chars).
|
|
83
|
+
email : str
|
|
84
|
+
The user's email address (must be unique).
|
|
85
|
+
|
|
86
|
+
Returns
|
|
87
|
+
-------
|
|
88
|
+
User
|
|
89
|
+
The created user object with generated ID.
|
|
90
|
+
|
|
91
|
+
Raises
|
|
92
|
+
------
|
|
93
|
+
ValidationError
|
|
94
|
+
If name or email are invalid.
|
|
95
|
+
"""
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Python — reST Style (Sphinx)
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
def create_user(name: str, email: str) -> User:
|
|
104
|
+
"""Create a new user in the system.
|
|
105
|
+
|
|
106
|
+
:param name: The user's display name (2-50 chars).
|
|
107
|
+
:param email: The user's email address (must be unique).
|
|
108
|
+
:returns: The created user object with generated ID.
|
|
109
|
+
:raises ValidationError: If name or email are invalid.
|
|
110
|
+
:raises ConflictError: If email already exists.
|
|
111
|
+
"""
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Rust — rustdoc
|
|
117
|
+
|
|
118
|
+
```rust
|
|
119
|
+
/// Creates a new user in the system.
|
|
120
|
+
///
|
|
121
|
+
/// # Arguments
|
|
122
|
+
/// * `name` - The user's display name (2-50 chars)
|
|
123
|
+
/// * `email` - The user's email address (must be unique)
|
|
124
|
+
///
|
|
125
|
+
/// # Returns
|
|
126
|
+
/// The created `User` object
|
|
127
|
+
///
|
|
128
|
+
/// # Errors
|
|
129
|
+
/// Returns `ValidationError` if name or email are invalid.
|
|
130
|
+
/// Returns `ConflictError` if email already exists.
|
|
131
|
+
///
|
|
132
|
+
/// # Example
|
|
133
|
+
/// ```rust
|
|
134
|
+
/// let user = create_user("Alice", "alice@test.com")?;
|
|
135
|
+
/// ```
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Go — Godoc
|
|
141
|
+
|
|
142
|
+
```go
|
|
143
|
+
// CreateUser creates a new user in the system.
|
|
144
|
+
// It validates the input and checks for duplicate emails.
|
|
145
|
+
//
|
|
146
|
+
// Parameters:
|
|
147
|
+
// - name: the user's display name (2-50 chars)
|
|
148
|
+
// - email: the user's email address (must be unique)
|
|
149
|
+
//
|
|
150
|
+
// Returns the created user, or an error if validation fails
|
|
151
|
+
// or the email already exists.
|
|
152
|
+
func CreateUser(name string, email string) (*User, error) {
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Godoc Conventions
|
|
156
|
+
- First sentence is the summary (used in `go doc` listing)
|
|
157
|
+
- Use full sentences with proper punctuation
|
|
158
|
+
- Document function behavior, not implementation
|
|
159
|
+
- `//` only, no `/* */`
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## ADR Template
|
|
164
|
+
|
|
165
|
+
```markdown
|
|
166
|
+
# ADR-001: Use PostgreSQL for Primary Database
|
|
167
|
+
|
|
168
|
+
**Date:** 2026-05-25
|
|
169
|
+
**Status:** Accepted
|
|
170
|
+
|
|
171
|
+
## Context
|
|
172
|
+
We need a primary database for storing user data.
|
|
173
|
+
The system needs strong consistency and complex queries.
|
|
174
|
+
|
|
175
|
+
## Decision
|
|
176
|
+
Use PostgreSQL 16 as the primary database.
|
|
177
|
+
|
|
178
|
+
## Consequences
|
|
179
|
+
- ✅ Strong consistency with ACID transactions
|
|
180
|
+
- ✅ Rich query capabilities (JSON, full-text search)
|
|
181
|
+
- ⚠️ Requires managed database service (increased cost)
|
|
182
|
+
- ⚠️ Schema migrations need careful planning
|
|
183
|
+
|
|
184
|
+
## Alternatives Considered
|
|
185
|
+
- MySQL: Similar capabilities but weaker JSON support
|
|
186
|
+
- MongoDB: Better horizontal scaling but eventual consistency
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
ADR numbering: sequential (`ADR-001`, `ADR-002`). Location: `docs/adr/`.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## CHANGELOG Template
|
|
194
|
+
|
|
195
|
+
```markdown
|
|
196
|
+
# Changelog
|
|
197
|
+
|
|
198
|
+
## [1.2.0] - 2026-05-25
|
|
199
|
+
|
|
200
|
+
### Added
|
|
201
|
+
- User creation API endpoint (POST /api/users)
|
|
202
|
+
- Email validation utility
|
|
203
|
+
|
|
204
|
+
### Changed
|
|
205
|
+
- Upgraded Express from 4.18 to 4.21
|
|
206
|
+
- Rate limiting now applied to all endpoints
|
|
207
|
+
|
|
208
|
+
### Fixed
|
|
209
|
+
- Memory leak in WebSocket connections
|
|
210
|
+
- Edge case in date parsing for timezone offsets
|
|
211
|
+
|
|
212
|
+
### Security
|
|
213
|
+
- Updated bcrypt dependency to patch CVE-2026-XXXX
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Follow [Keep a Changelog](https://keepachangelog.com) convention unless project uses custom format.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
# docs-gen Scripts
|
|
2
|
-
|
|
3
|
-
Placeholder for documentation utility scripts. Future candidates:
|
|
4
|
-
- `api-docs-from-routes.py` — Parse Express/FastAPI routes and generate API doc stubs
|
|
5
|
-
- `changelog-bump.py` — Generate changelog entry from conventional commits
|
|
1
|
+
# docs-gen Scripts
|
|
2
|
+
|
|
3
|
+
Placeholder for documentation utility scripts. Future candidates:
|
|
4
|
+
- `api-docs-from-routes.py` — Parse Express/FastAPI routes and generate API doc stubs
|
|
5
|
+
- `changelog-bump.py` — Generate changelog entry from conventional commits
|
|
@@ -1,112 +1,112 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: orchestrate
|
|
3
|
-
description: |
|
|
4
|
-
Multi-agent orchestration for complex development tasks. Breaks down large work, delegates to specialized agents, manages contracts, and drives the fix loop.
|
|
5
|
-
Use when tasks span multiple domains, require parallel execution, or need full lifecycle management.
|
|
6
|
-
Triggers on: "orchestrate", "coordinate", "manage", "run the full pipeline", "team", "complex task"
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# Orchestrate
|
|
10
|
-
|
|
11
|
-
Multi-agent orchestration workflow for complex development tasks.
|
|
12
|
-
|
|
13
|
-
## When to Use
|
|
14
|
-
|
|
15
|
-
- Task is too large for a single agent
|
|
16
|
-
- Task spans multiple domains (frontend + backend + infra)
|
|
17
|
-
- Need parallel execution of independent subtasks
|
|
18
|
-
- Full lifecycle management from architecture to merge
|
|
19
|
-
|
|
20
|
-
## Comparison with fullstack-dev
|
|
21
|
-
|
|
22
|
-
| Aspect | fullstack-dev | team-lead |
|
|
23
|
-
|--------|---------------|-----------|
|
|
24
|
-
| Scope | Single feature | Multi-domain, complex tasks |
|
|
25
|
-
| Parallelism | Sequential phases | Parallel subtask execution |
|
|
26
|
-
| Delegation | One agent per phase | Multiple agents concurrently |
|
|
27
|
-
| State | Single contract chain | Parallel + merge contracts |
|
|
28
|
-
| Best for | Well-defined changes | Large features, refactors, cross-cutting work |
|
|
29
|
-
|
|
30
|
-
## Workflow
|
|
31
|
-
|
|
32
|
-
```
|
|
33
|
-
Task Intake → Decomposition → Parallel Dispatch → Collection → Synthesis → Review → Done
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
### Step 1: Task Intake
|
|
37
|
-
|
|
38
|
-
Analyze the user's request and determine scope:
|
|
39
|
-
- **Simple** (≤3 files, single domain) → delegate to fullstack-dev
|
|
40
|
-
- **Complex** (multi-domain, large scope) → orchestrate here
|
|
41
|
-
|
|
42
|
-
Ask clarifying questions if needed (one at a time with rationale).
|
|
43
|
-
|
|
44
|
-
### Step 2: Decomposition
|
|
45
|
-
|
|
46
|
-
Break the task into manageable subtasks, each with:
|
|
47
|
-
- Clear input/output
|
|
48
|
-
- Assigned agent type
|
|
49
|
-
- Dependencies between subtasks
|
|
50
|
-
- Whether an ADR or contract is needed first
|
|
51
|
-
|
|
52
|
-
### Step 3: Parallel Dispatch
|
|
53
|
-
|
|
54
|
-
Launch independent subtasks concurrently using the Task tool with appropriate `subagent_type`:
|
|
55
|
-
|
|
56
|
-
```markdown
|
|
57
|
-
Task 1: architect (ADR for infrastructure choice)
|
|
58
|
-
Task 2: spec-writer (contract for API design)
|
|
59
|
-
(These are independent — launch in parallel)
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Dependent subtasks run sequentially:
|
|
63
|
-
```
|
|
64
|
-
Task 1: architect (ADR) → Task 2: spec-writer (contract) → Task 3: executor (implement)
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### Step 4: Collection
|
|
68
|
-
|
|
69
|
-
Read contract outputs from `docs/adr/` and `docs/specs/` for each subtask.
|
|
70
|
-
Resolve conflicts between parallel streams.
|
|
71
|
-
|
|
72
|
-
### Step 5: Synthesis
|
|
73
|
-
|
|
74
|
-
Combine parallel results into a coherent whole. Write `.handoffs/orchestrate/synthesis.md` with:
|
|
75
|
-
- What each subtask produced
|
|
76
|
-
- Integration notes
|
|
77
|
-
- Remaining work
|
|
78
|
-
- Risks discovered
|
|
79
|
-
|
|
80
|
-
### Step 6: Review
|
|
81
|
-
|
|
82
|
-
Run pr-review on the synthesized result:
|
|
83
|
-
- Delegate to code-reviewer agent
|
|
84
|
-
- Apply fixes if issues found
|
|
85
|
-
- Check that all architectural decisions have ADRs
|
|
86
|
-
|
|
87
|
-
### Step 7: Verification
|
|
88
|
-
|
|
89
|
-
Run tests:
|
|
90
|
-
- Delegate to test-engineer for new test generation
|
|
91
|
-
- Delegate to verifier for full test suite run
|
|
92
|
-
|
|
93
|
-
## Artifact Summary
|
|
94
|
-
|
|
95
|
-
| Artifact | Location | Persistent | Purpose |
|
|
96
|
-
|----------|----------|------------|---------|
|
|
97
|
-
| ADR | `docs/adr/NNNN-title.md` | ✅ Committed | Architecture decisions |
|
|
98
|
-
| Contract | `docs/specs/<feature>/` | ✅ Committed | Requirements, ACs, API |
|
|
99
|
-
| Synthesis | `.handoffs/orchestrate/synthesis.md` | ❌ Temporary | Merge notes |
|
|
100
|
-
|
|
101
|
-
## Handoff Directory
|
|
102
|
-
|
|
103
|
-
All orchestration state: `.handoffs/orchestrate/`
|
|
104
|
-
|
|
105
|
-
## Error Recovery
|
|
106
|
-
|
|
107
|
-
| Failure | Action |
|
|
108
|
-
|---------|--------|
|
|
109
|
-
| Subtask fails | Retry once, then report to user |
|
|
110
|
-
| Parallel conflicts | Reconcile in synthesis phase |
|
|
111
|
-
| Verification fails | Enter fix loop (max 3 retries) |
|
|
112
|
-
| User changes mind | Accept new direction, re-plan affected subtasks |
|
|
1
|
+
---
|
|
2
|
+
name: orchestrate
|
|
3
|
+
description: |
|
|
4
|
+
Multi-agent orchestration for complex development tasks. Breaks down large work, delegates to specialized agents, manages contracts, and drives the fix loop.
|
|
5
|
+
Use when tasks span multiple domains, require parallel execution, or need full lifecycle management.
|
|
6
|
+
Triggers on: "orchestrate", "coordinate", "manage", "run the full pipeline", "team", "complex task"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Orchestrate
|
|
10
|
+
|
|
11
|
+
Multi-agent orchestration workflow for complex development tasks.
|
|
12
|
+
|
|
13
|
+
## When to Use
|
|
14
|
+
|
|
15
|
+
- Task is too large for a single agent
|
|
16
|
+
- Task spans multiple domains (frontend + backend + infra)
|
|
17
|
+
- Need parallel execution of independent subtasks
|
|
18
|
+
- Full lifecycle management from architecture to merge
|
|
19
|
+
|
|
20
|
+
## Comparison with fullstack-dev
|
|
21
|
+
|
|
22
|
+
| Aspect | fullstack-dev | team-lead |
|
|
23
|
+
|--------|---------------|-----------|
|
|
24
|
+
| Scope | Single feature | Multi-domain, complex tasks |
|
|
25
|
+
| Parallelism | Sequential phases | Parallel subtask execution |
|
|
26
|
+
| Delegation | One agent per phase | Multiple agents concurrently |
|
|
27
|
+
| State | Single contract chain | Parallel + merge contracts |
|
|
28
|
+
| Best for | Well-defined changes | Large features, refactors, cross-cutting work |
|
|
29
|
+
|
|
30
|
+
## Workflow
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
Task Intake → Decomposition → Parallel Dispatch → Collection → Synthesis → Review → Done
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Step 1: Task Intake
|
|
37
|
+
|
|
38
|
+
Analyze the user's request and determine scope:
|
|
39
|
+
- **Simple** (≤3 files, single domain) → delegate to fullstack-dev
|
|
40
|
+
- **Complex** (multi-domain, large scope) → orchestrate here
|
|
41
|
+
|
|
42
|
+
Ask clarifying questions if needed (one at a time with rationale).
|
|
43
|
+
|
|
44
|
+
### Step 2: Decomposition
|
|
45
|
+
|
|
46
|
+
Break the task into manageable subtasks, each with:
|
|
47
|
+
- Clear input/output
|
|
48
|
+
- Assigned agent type
|
|
49
|
+
- Dependencies between subtasks
|
|
50
|
+
- Whether an ADR or contract is needed first
|
|
51
|
+
|
|
52
|
+
### Step 3: Parallel Dispatch
|
|
53
|
+
|
|
54
|
+
Launch independent subtasks concurrently using the Task tool with appropriate `subagent_type`:
|
|
55
|
+
|
|
56
|
+
```markdown
|
|
57
|
+
Task 1: architect (ADR for infrastructure choice)
|
|
58
|
+
Task 2: spec-writer (contract for API design)
|
|
59
|
+
(These are independent — launch in parallel)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Dependent subtasks run sequentially:
|
|
63
|
+
```
|
|
64
|
+
Task 1: architect (ADR) → Task 2: spec-writer (contract) → Task 3: executor (implement)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Step 4: Collection
|
|
68
|
+
|
|
69
|
+
Read contract outputs from `docs/adr/` and `docs/specs/` for each subtask.
|
|
70
|
+
Resolve conflicts between parallel streams.
|
|
71
|
+
|
|
72
|
+
### Step 5: Synthesis
|
|
73
|
+
|
|
74
|
+
Combine parallel results into a coherent whole. Write `.handoffs/orchestrate/synthesis.md` with:
|
|
75
|
+
- What each subtask produced
|
|
76
|
+
- Integration notes
|
|
77
|
+
- Remaining work
|
|
78
|
+
- Risks discovered
|
|
79
|
+
|
|
80
|
+
### Step 6: Review
|
|
81
|
+
|
|
82
|
+
Run pr-review on the synthesized result:
|
|
83
|
+
- Delegate to code-reviewer agent
|
|
84
|
+
- Apply fixes if issues found
|
|
85
|
+
- Check that all architectural decisions have ADRs
|
|
86
|
+
|
|
87
|
+
### Step 7: Verification
|
|
88
|
+
|
|
89
|
+
Run tests:
|
|
90
|
+
- Delegate to test-engineer for new test generation
|
|
91
|
+
- Delegate to verifier for full test suite run
|
|
92
|
+
|
|
93
|
+
## Artifact Summary
|
|
94
|
+
|
|
95
|
+
| Artifact | Location | Persistent | Purpose |
|
|
96
|
+
|----------|----------|------------|---------|
|
|
97
|
+
| ADR | `docs/adr/NNNN-title.md` | ✅ Committed | Architecture decisions |
|
|
98
|
+
| Contract | `docs/specs/<feature>/` | ✅ Committed | Requirements, ACs, API |
|
|
99
|
+
| Synthesis | `.handoffs/orchestrate/synthesis.md` | ❌ Temporary | Merge notes |
|
|
100
|
+
|
|
101
|
+
## Handoff Directory
|
|
102
|
+
|
|
103
|
+
All orchestration state: `.handoffs/orchestrate/`
|
|
104
|
+
|
|
105
|
+
## Error Recovery
|
|
106
|
+
|
|
107
|
+
| Failure | Action |
|
|
108
|
+
|---------|--------|
|
|
109
|
+
| Subtask fails | Retry once, then report to user |
|
|
110
|
+
| Parallel conflicts | Reconcile in synthesis phase |
|
|
111
|
+
| Verification fails | Enter fix loop (max 3 retries) |
|
|
112
|
+
| User changes mind | Accept new direction, re-plan affected subtasks |
|