opencode-onboard 0.1.1 → 0.1.3
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/README.md +213 -214
- package/content/AGENTS.md +236 -1
- package/package.json +1 -1
- package/src/index.js +2 -3
- package/content/.agents/agents/.bootstrap/AGENTS.template.md +0 -234
package/README.md
CHANGED
|
@@ -1,214 +1,213 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
<img src="https://raw.githubusercontent.com/CKGrafico/opencode-onboard/refs/heads/main/logo.png" alt="opencode-onboard" width="160" />
|
|
4
|
-
|
|
5
|
-
# 🧰 opencode-onboard
|
|
6
|
-
|
|
7
|
-
**One command to prepare any codebase for AI agent workflows.**
|
|
8
|
-
|
|
9
|
-
Works with [OpenCode](https://opencode.ai), [OpenCode Ensemble](https://github.com/hueyexe/opencode-ensemble), [OpenSpec](https://github.com/fission-ai/openspec), GitHub and Azure DevOps.
|
|
10
|
-
|
|
11
|
-
[](https://www.npmjs.com/package/opencode-onboard)
|
|
12
|
-
[](https://www.npmjs.com/package/opencode-onboard)
|
|
13
|
-
[](./LICENSE)
|
|
14
|
-
[](https://nodejs.org)
|
|
15
|
-
|
|
16
|
-
</div>
|
|
17
|
-
|
|
18
|
-
## What is this?
|
|
19
|
-
|
|
20
|
-
Most codebases have no `AGENTS.md`, no architecture docs agents can read, and no defined workflow for picking up tasks. Agents end up improvising, and that produces inconsistent, brittle results.
|
|
21
|
-
|
|
22
|
-
**opencode-onboard** fixes that in a single interactive run. It installs a universal agent team,
|
|
23
|
-
|
|
24
|
-
<div align="center">
|
|
25
|
-
<img src="https://raw.githubusercontent.com/CKGrafico/opencode-onboard/refs/heads/main/demo.gif" alt="opencode-onboard demo" width="700" />
|
|
26
|
-
</div>
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
| **
|
|
46
|
-
| **
|
|
47
|
-
| **
|
|
48
|
-
| **
|
|
49
|
-
| **
|
|
50
|
-
| **
|
|
51
|
-
| **
|
|
52
|
-
| **
|
|
53
|
-
| **
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
| `ob-userstory-
|
|
94
|
-
| `
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| **
|
|
106
|
-
| **
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
├──
|
|
145
|
-
├──
|
|
146
|
-
├──
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
├──
|
|
151
|
-
│ ├──
|
|
152
|
-
│ ├──
|
|
153
|
-
│ ├──
|
|
154
|
-
│ ├──
|
|
155
|
-
│
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
├──
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
| **
|
|
183
|
-
| **[OpenCode](https://opencode
|
|
184
|
-
| **[
|
|
185
|
-
| **[
|
|
186
|
-
| **[
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
MIT © [ckgrafico](https://github.com/ckgrafico)
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="https://raw.githubusercontent.com/CKGrafico/opencode-onboard/refs/heads/main/logo.png" alt="opencode-onboard" width="160" />
|
|
4
|
+
|
|
5
|
+
# 🧰 opencode-onboard
|
|
6
|
+
|
|
7
|
+
**One command to prepare any codebase for AI agent workflows in OpenCode.**
|
|
8
|
+
|
|
9
|
+
Works with [OpenCode](https://opencode.ai), [OpenCode Ensemble](https://github.com/hueyexe/opencode-ensemble), [OpenSpec](https://github.com/fission-ai/openspec), GitHub and Azure DevOps.
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/opencode-onboard)
|
|
12
|
+
[](https://www.npmjs.com/package/opencode-onboard)
|
|
13
|
+
[](./LICENSE)
|
|
14
|
+
[](https://nodejs.org)
|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
## What is this?
|
|
19
|
+
|
|
20
|
+
Most codebases have no `AGENTS.md`, no architecture docs agents can read, and no defined workflow for picking up tasks. Agents end up improvising, and that produces inconsistent, brittle results.
|
|
21
|
+
|
|
22
|
+
**opencode-onboard** fixes that in a single interactive run. It installs a universal and agnostic agent team,but let you choose your own skills, preconfigured your AI models, and initd OpenCode with Openspec and Ensemble.
|
|
23
|
+
|
|
24
|
+
<div align="center">
|
|
25
|
+
<img src="https://raw.githubusercontent.com/CKGrafico/opencode-onboard/refs/heads/main/demo.gif" alt="opencode-onboard demo" width="700" />
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
## Quick start
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx opencode-onboard@latest
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Requires **Node.js 18+**.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## How it works
|
|
39
|
+
|
|
40
|
+
The CLI clears the screen, shows a welcome banner, and walks you through 10 steps. The screen always shows the last 2 completed steps + the current one so you always know where you are.
|
|
41
|
+
|
|
42
|
+
| Step | What happens |
|
|
43
|
+
|------|-------------|
|
|
44
|
+
| **1. Environment check** | Verifies Node.js ≥ 18 and pnpm are available |
|
|
45
|
+
| **2. Clean AI files** | Detects existing `AGENTS.md`, `.cursorrules`, `CLAUDE.md`, `.agents/` etc. and removes them, preserves your `.agents/skills/` |
|
|
46
|
+
| **3. Choose platform** | GitHub or Azure DevOps |
|
|
47
|
+
| **4. Check platform CLI** | Verifies `gh` (GitHub) or `az` + `azure-devops` (Azure DevOps) |
|
|
48
|
+
| **5. Copy scaffolding** | Drops agents, skills, and bootstrap docs into your project |
|
|
49
|
+
| **6. Init OpenSpec** | Runs `npx @fission-ai/openspec init` silently for structured change management |
|
|
50
|
+
| **7. Install skills** | Installs built-in `ob-` skills + optional additional skills provider |
|
|
51
|
+
| **8. Choose models** | Fetches live model list from [models.dev](https://models.dev), lets you pick plan / build / fast models with cost indicators and canonical pricing |
|
|
52
|
+
| **9. Check RTK** | Verifies `rtk` is on PATH |
|
|
53
|
+
| **10. Install browser plugin** | Installs `@different-ai/opencode-browser` globally for agent browser automation |
|
|
54
|
+
|
|
55
|
+
When it finishes, open OpenCode in your project and type:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
init
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
OpenCode generates `ARCHITECTURE.md` and `DESIGN.md` from your actual codebase, then activates the full agent team.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Agents and Skills
|
|
66
|
+
|
|
67
|
+
opencode-onboard draws a hard line between two concepts:
|
|
68
|
+
|
|
69
|
+
### Agents, universal behaviors
|
|
70
|
+
|
|
71
|
+
Agents define *how to work*. They are behavioral personas, the same for every project, every tech stack, every team. You never configure them or choose between them. All six are always installed.
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
devops-manager reads work items, creates PRs, handles review feedback
|
|
75
|
+
front-engineer web, mobile, UI, anything visual
|
|
76
|
+
back-engineer APIs, services, data, AI, anything not UI
|
|
77
|
+
infra-engineer Terraform, pipelines, cloud infrastructure
|
|
78
|
+
quality-engineer unit, integration, e2e tests across all layers
|
|
79
|
+
security-auditor vulnerability audit, secrets, auth gaps
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Each agent has a color in the OpenCode UI. Builder agents (`front-engineer`, `back-engineer`, `infra-engineer`) run at `temperature: 0.2` for deterministic output. `security-auditor` is read-only, edit is denied.
|
|
83
|
+
|
|
84
|
+
### Skills, platform knowledge
|
|
85
|
+
|
|
86
|
+
Skills define *what to know*. They provide the tech and platform-specific knowledge agents need. Agents detect and load relevant skills automatically, **you never tell an agent which skill to use**.
|
|
87
|
+
|
|
88
|
+
Built-in skills (`ob-` prefix) shipped with opencode-onboard:
|
|
89
|
+
|
|
90
|
+
| Skill | Purpose |
|
|
91
|
+
|-------|---------|
|
|
92
|
+
| `ob-userstory-gh` | Parse a GitHub Issue URL into a structured work item |
|
|
93
|
+
| `ob-userstory-az` | Parse an Azure DevOps work item URL |
|
|
94
|
+
| `browser-automation` | Browser control via `@different-ai/opencode-browser` |
|
|
95
|
+
|
|
96
|
+
Skills live in `.agents/skills/`. Any `SKILL.md` file in a subdirectory is automatically discoverable, write your own and agents will pick them up.
|
|
97
|
+
|
|
98
|
+
### Models, plan / build / fast
|
|
99
|
+
|
|
100
|
+
During onboarding you pick three models:
|
|
101
|
+
|
|
102
|
+
| Role | Used by | Pick |
|
|
103
|
+
|------|---------|------|
|
|
104
|
+
| **plan** | Main OpenCode session | Something capable with strong reasoning |
|
|
105
|
+
| **build** | All builder agents | Something capable for implementation |
|
|
106
|
+
| **fast** | `devops-manager` | Something fast and cheap |
|
|
107
|
+
|
|
108
|
+
Models are fetched live from [models.dev](https://models.dev) (3000+ models, cached weekly). Cost tiers `[$]` `[$$]` `[$$$]` always reflect the canonical provider price, so `github-copilot/claude-opus-4.7` shows `[$$]` not `[$]`.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## The pipeline
|
|
113
|
+
|
|
114
|
+
When you give the lead agent a work item URL, it runs the full pipeline automatically:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
devops-manager → parse work item via skill → structured summary
|
|
118
|
+
↓
|
|
119
|
+
openspec-propose
|
|
120
|
+
proposal + specs + tasks
|
|
121
|
+
↓
|
|
122
|
+
[confirm with user]
|
|
123
|
+
↓
|
|
124
|
+
front-engineer + back-engineer + infra-engineer (parallel)
|
|
125
|
+
↓
|
|
126
|
+
quality-engineer
|
|
127
|
+
tests, build, lint, acceptance
|
|
128
|
+
↓
|
|
129
|
+
security-auditor
|
|
130
|
+
vulnerabilities, secrets
|
|
131
|
+
↓
|
|
132
|
+
devops-manager → screenshots → commit → push → PR → comment
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Each agent runs in its own isolated git worktree via [OpenCode Ensemble](https://github.com/hueyexe/opencode-ensemble), with a live dashboard at `http://localhost:4747`.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## What gets installed
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
your-project/
|
|
143
|
+
├── AGENTS.md ← bootstrap mode, replaced after first "init"
|
|
144
|
+
├── ARCHITECTURE.md ← prompt for agents to fill in from your codebase
|
|
145
|
+
├── DESIGN.md ← prompt for agents to fill in from your codebase
|
|
146
|
+
├── .opencode/
|
|
147
|
+
│ └── opencode.json ← plan model + plugins configured
|
|
148
|
+
└── .agents/
|
|
149
|
+
├── agents/
|
|
150
|
+
│ ├── devops-manager.md
|
|
151
|
+
│ ├── front-engineer.md
|
|
152
|
+
│ ├── back-engineer.md
|
|
153
|
+
│ ├── infra-engineer.md
|
|
154
|
+
│ ├── quality-engineer.md
|
|
155
|
+
│ └── security-auditor.md
|
|
156
|
+
└── skills/
|
|
157
|
+
├── browser-automation/
|
|
158
|
+
├── ob-userstory-gh/ ← or -az, depending on platform
|
|
159
|
+
└── ob-userstory-az/
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## The bootstrap sequence
|
|
165
|
+
|
|
166
|
+
The first time you type `init` in OpenCode after onboarding:
|
|
167
|
+
|
|
168
|
+
1. OpenCode reads your codebase and writes a real `ARCHITECTURE.md`
|
|
169
|
+
2. OpenCode reads your design patterns and writes a real `DESIGN.md`
|
|
170
|
+
3. `AGENTS.md` is replaced by the production version
|
|
171
|
+
4. Your agent team is live
|
|
172
|
+
|
|
173
|
+
After this, every agent has accurate, persistent context about your project, no manual documentation required.
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Prerequisites
|
|
178
|
+
|
|
179
|
+
| Requirement | Notes |
|
|
180
|
+
|-------------|-------|
|
|
181
|
+
| **Node.js 18+** | Required |
|
|
182
|
+
| **[OpenCode](https://opencode.ai)** | The agent runtime |
|
|
183
|
+
| **[OpenCode Ensemble](https://github.com/hueyexe/opencode-ensemble)** | Multi-agent parallel execution |
|
|
184
|
+
| **[rtk](https://github.com/rtk-ai/rtk#pre-built-binaries)** | Required for agents to run CLI commands safely |
|
|
185
|
+
| **[gh CLI](https://cli.github.com)** | GitHub platform, must be authenticated |
|
|
186
|
+
| **[az CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** + azure-devops extension | Azure DevOps platform |
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Development
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
git clone https://github.com/ckgrafico/opencode-onboard.git
|
|
194
|
+
cd opencode-onboard
|
|
195
|
+
pnpm install
|
|
196
|
+
|
|
197
|
+
# Run the CLI locally
|
|
198
|
+
node src/index.js
|
|
199
|
+
|
|
200
|
+
# Run tests
|
|
201
|
+
pnpm test
|
|
202
|
+
|
|
203
|
+
# Watch mode
|
|
204
|
+
pnpm test:watch
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Tests are written with [Vitest](https://vitest.dev).
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## License
|
|
212
|
+
|
|
213
|
+
MIT © [ckgrafico](https://github.com/ckgrafico)
|
package/content/AGENTS.md
CHANGED
|
@@ -61,7 +61,7 @@ The output must be a real, populated `ARCHITECTURE.md` covering all sections the
|
|
|
61
61
|
|
|
62
62
|
### Step 4, Rewrite this file
|
|
63
63
|
|
|
64
|
-
Replace the entire contents of `AGENTS.md` with the
|
|
64
|
+
Replace the entire contents of this file (`AGENTS.md`) with everything below the line `<!-- AGENTS-TEMPLATE-START -->` in this same file. Delete the bootstrap section and the template marker — the file should contain only the template content when done.
|
|
65
65
|
|
|
66
66
|
---
|
|
67
67
|
|
|
@@ -88,3 +88,238 @@ You're ready to work.
|
|
|
88
88
|
- Do NOT create branches or PRs
|
|
89
89
|
- Do NOT modify any project source files
|
|
90
90
|
- Only read source files for analysis, write only to ARCHITECTURE.md, DESIGN.md, AGENTS.md, and openspec/
|
|
91
|
+
|
|
92
|
+
<!-- AGENTS-TEMPLATE-START -->
|
|
93
|
+
# AGENTS.md
|
|
94
|
+
|
|
95
|
+
This file provides guidance to AI agents when working in this repository.
|
|
96
|
+
|
|
97
|
+
*Agent-agnostic, works with OpenCode, Claude Code, Codex, Gemini, etc.*
|
|
98
|
+
|
|
99
|
+
## Project Overview
|
|
100
|
+
|
|
101
|
+
This is the agent orchestration layer for your project. It provides:
|
|
102
|
+
- Universal agent team for development workflow
|
|
103
|
+
- OpenSpec change management
|
|
104
|
+
- Skills for platform-specific knowledge
|
|
105
|
+
|
|
106
|
+
## I Am the Lead, Full Workflow Ownership
|
|
107
|
+
|
|
108
|
+
When the user provides a work item URL, says "implement the plan", or "I've added comments to the PR", **I own the full lifecycle**. I load the appropriate skill and use ensemble tools (`team_create`, `team_spawn`, etc.) to coordinate the agent team.
|
|
109
|
+
|
|
110
|
+
Trigger patterns:
|
|
111
|
+
- `work on this <azure-devops-url>` → spawn `devops-manager` in read mode → propose OpenSpec → implement → ship
|
|
112
|
+
- `work on this <github-url>` → spawn `devops-manager` in read mode → propose OpenSpec → implement → ship
|
|
113
|
+
- `implement the plan` → load skill `openspec-apply-change` → implement → ship
|
|
114
|
+
- `I've added comments to the PR` → spawn `devops-manager` in feedback mode → fix → update PR
|
|
115
|
+
|
|
116
|
+
**Never delegate without a plan. Never write implementation code directly, always spawn specialists.**
|
|
117
|
+
|
|
118
|
+
## Multi-Agent Execution, opencode-ensemble
|
|
119
|
+
|
|
120
|
+
Parallel execution uses the `opencode-ensemble` plugin (`team_create`, `team_spawn`, etc.).
|
|
121
|
+
Works on **all platforms** (Windows, macOS, Linux) via OpenCode's built-in worktree support.
|
|
122
|
+
|
|
123
|
+
| Tool | What it does |
|
|
124
|
+
|------|-------------|
|
|
125
|
+
| `team_create` | Create a team (caller becomes lead) |
|
|
126
|
+
| `team_spawn` | Start a teammate asynchronously |
|
|
127
|
+
| `team_shutdown` | Stop a teammate, preserve their branch |
|
|
128
|
+
| `team_merge` | Merge a teammate's branch into working dir |
|
|
129
|
+
| `team_cleanup` | Tear down the team |
|
|
130
|
+
| `team_results` | Retrieve full message from a teammate |
|
|
131
|
+
| `team_message` | Send a direct message to a teammate |
|
|
132
|
+
| `team_broadcast` | Message all teammates |
|
|
133
|
+
| `team_tasks_add` | Add tasks to shared board |
|
|
134
|
+
| `team_tasks_complete` | Mark task done |
|
|
135
|
+
|
|
136
|
+
**Dashboard**: Monitor running agents at **http://localhost:4747/**
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Pipeline
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
devops-manager (read mode)
|
|
144
|
+
→ parse work item via skill → structured summary
|
|
145
|
+
↓
|
|
146
|
+
openspec-propose
|
|
147
|
+
→ proposal.md + specs + tasks
|
|
148
|
+
↓
|
|
149
|
+
[confirm with user]
|
|
150
|
+
↓
|
|
151
|
+
front-engineer + back-engineer + infra-engineer ← parallel, only spawn what the task needs
|
|
152
|
+
↓
|
|
153
|
+
quality-engineer
|
|
154
|
+
→ tests, build, lint, acceptance criteria
|
|
155
|
+
↓
|
|
156
|
+
security-auditor
|
|
157
|
+
→ vulnerability audit, secrets, auth gaps
|
|
158
|
+
↓
|
|
159
|
+
devops-manager (ship mode)
|
|
160
|
+
→ screenshots → commit → push → PR → post comment
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Phase 1, Parse & Propose
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
1. team_spawn devops-manager (read mode) → fetch work item via skill, output summary
|
|
167
|
+
2. Load skill: openspec-propose → generate proposal.md, specs/, tasks.md
|
|
168
|
+
- team_create → spawn design + specs in parallel → merge → write tasks.md
|
|
169
|
+
3. Show summary, confirm with user before implementing
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### Phase 2, Implement
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
1. Load skill: openspec-apply-change → get apply instructions
|
|
176
|
+
2. Create feature branch: feature/{id}-{slug}
|
|
177
|
+
3. team_create "<change-name>"
|
|
178
|
+
4. Announce: "Team running. Monitor at http://localhost:4747/"
|
|
179
|
+
5. Spawn only what the task needs (in parallel):
|
|
180
|
+
team_spawn name:front agent:front-engineer → UI tasks
|
|
181
|
+
team_spawn name:back agent:back-engineer → backend tasks
|
|
182
|
+
team_spawn name:infra agent:infra-engineer → infra tasks
|
|
183
|
+
6. Wait for all → team_results → team_shutdown + team_merge
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Phase 3, Quality
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
7. team_spawn name:quality agent:quality-engineer → tests, build, lint
|
|
190
|
+
8. Wait → team_results → fix any blockers → team_shutdown
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Phase 4, Security
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
9. team_spawn name:security agent:security-auditor → audit full change
|
|
197
|
+
10. Wait → team_results → fix Critical findings → team_shutdown
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Phase 5, Ship
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
11. team_spawn name:devops agent:devops-manager (ship mode)
|
|
204
|
+
→ screenshots → commit & push → create PR → post comment
|
|
205
|
+
12. Wait → team_results → report PR URL to user
|
|
206
|
+
13. team_cleanup
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Phase 6, PR Feedback Loop
|
|
210
|
+
|
|
211
|
+
```
|
|
212
|
+
When user says "I've added comments to the PR":
|
|
213
|
+
1. team_spawn devops-manager (feedback mode) → read & classify comments
|
|
214
|
+
2. Wait → team_results → spawn front/back/infra for code-change items (parallel)
|
|
215
|
+
3. Wait → team_results → spawn quality-engineer → verify fixes
|
|
216
|
+
4. Wait → team_results → spawn devops-manager (ship mode) → push & update PR
|
|
217
|
+
5. team_cleanup
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## Agents
|
|
223
|
+
|
|
224
|
+
All agents are universal, no project-specific knowledge. Platform and tech knowledge comes from skills.
|
|
225
|
+
|
|
226
|
+
| Agent | File | Role |
|
|
227
|
+
|-------|------|------|
|
|
228
|
+
| `devops-manager` | .agents/agents/devops-manager.md | Reads work items, creates PRs, handles review feedback |
|
|
229
|
+
| `front-engineer` | .agents/agents/front-engineer.md | Web, mobile, UI implementation |
|
|
230
|
+
| `back-engineer` | .agents/agents/back-engineer.md | APIs, services, data, AI implementation |
|
|
231
|
+
| `infra-engineer` | .agents/agents/infra-engineer.md | Terraform, pipelines, cloud infrastructure |
|
|
232
|
+
| `quality-engineer` | .agents/agents/quality-engineer.md | Unit, integration, e2e tests across all layers |
|
|
233
|
+
| `security-auditor` | .agents/agents/security-auditor.md | Vulnerability audit, secrets, auth gaps |
|
|
234
|
+
|
|
235
|
+
## Skills
|
|
236
|
+
|
|
237
|
+
Skills provide platform and tech-specific knowledge. Agents detect and load them automatically, the user never specifies which skill to use.
|
|
238
|
+
|
|
239
|
+
Skills are located in `.agents/skills/`. Each skill has a `SKILL.md` with a description the agent reads to determine relevance.
|
|
240
|
+
|
|
241
|
+
| Skill | Purpose |
|
|
242
|
+
|-------|---------|
|
|
243
|
+
| `ob-userstory-az` | Parse Azure DevOps work item URL |
|
|
244
|
+
| `ob-userstory-gh` | Parse GitHub Issue URL |
|
|
245
|
+
| `ob-pullrequest-az` | Create PR on Azure DevOps |
|
|
246
|
+
| `ob-pullrequest-gh` | Create PR on GitHub |
|
|
247
|
+
| `openspec-propose` | Propose change artifacts (proposal, specs, tasks) |
|
|
248
|
+
| `openspec-apply-change` | Implement change with agent team |
|
|
249
|
+
| `openspec-archive-change` | Archive completed change |
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Branch Naming
|
|
254
|
+
|
|
255
|
+
Format: `feature/{issue-id}-{slug}`
|
|
256
|
+
Example: `feature/42-add-user-auth`
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## Project Structure
|
|
261
|
+
|
|
262
|
+
```
|
|
263
|
+
[project-root]/
|
|
264
|
+
├── .agents/
|
|
265
|
+
│ ├── agents/ # Agent definitions (universal, no project knowledge)
|
|
266
|
+
│ └── skills/ # Skills (platform/tech specific knowledge)
|
|
267
|
+
├── openspec/
|
|
268
|
+
│ ├── specs/
|
|
269
|
+
│ └── changes/
|
|
270
|
+
│ └── {change}/
|
|
271
|
+
│ └── images/
|
|
272
|
+
├── AGENTS.md
|
|
273
|
+
├── ARCHITECTURE.md
|
|
274
|
+
└── DESIGN.md
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Guardrails
|
|
280
|
+
|
|
281
|
+
### Git Operations
|
|
282
|
+
|
|
283
|
+
Agents CAN:
|
|
284
|
+
- ✅ Commit to feature branches
|
|
285
|
+
- ✅ Push to feature branches
|
|
286
|
+
|
|
287
|
+
Agents CANNOT:
|
|
288
|
+
- ❌ Commit or push to `main`, FORBIDDEN
|
|
289
|
+
- ❌ Force push, FORBIDDEN
|
|
290
|
+
- ❌ Merge PRs, human-only
|
|
291
|
+
- ❌ Create or delete branches other than `feature/*`
|
|
292
|
+
|
|
293
|
+
### Platform CLI
|
|
294
|
+
|
|
295
|
+
ALL platform interactions via CLI only. Browser MCP FORBIDDEN for any DevOps or GitHub operation.
|
|
296
|
+
|
|
297
|
+
| Operation | Azure DevOps | GitHub |
|
|
298
|
+
|-----------|-------------|--------|
|
|
299
|
+
| Read issue | `az boards work-item show --id <id>` | `gh issue view <number>` |
|
|
300
|
+
| Read PR threads | `az devops invoke ...` | `gh pr view <number> --comments` |
|
|
301
|
+
| Create PR | `az repos pr create ...` | `gh pr create ...` |
|
|
302
|
+
|
|
303
|
+
Browser MCP tools permitted only for screenshots of **local running app** on `localhost` URLs.
|
|
304
|
+
|
|
305
|
+
### Security
|
|
306
|
+
|
|
307
|
+
Agents CANNOT:
|
|
308
|
+
- ❌ Access `.env` or config files with secrets
|
|
309
|
+
- ❌ Log or output credentials, API keys, or tokens
|
|
310
|
+
- ❌ Commit secrets to git
|
|
311
|
+
|
|
312
|
+
### Scope
|
|
313
|
+
|
|
314
|
+
- Max 10 files per change
|
|
315
|
+
- No architecture changes without human approval
|
|
316
|
+
- No pipeline modifications without human approval
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## Communication Style
|
|
321
|
+
|
|
322
|
+
Terse. Technical substance exact. Only fluff die.
|
|
323
|
+
Drop: articles, filler, pleasantries, hedging.
|
|
324
|
+
Fragments OK. Short synonyms. Code unchanged.
|
|
325
|
+
Pattern: [thing] [action] [reason]. [next step].
|
package/package.json
CHANGED
package/src/index.js
CHANGED
|
@@ -1,234 +0,0 @@
|
|
|
1
|
-
# AGENTS.md
|
|
2
|
-
|
|
3
|
-
This file provides guidance to AI agents when working in this repository.
|
|
4
|
-
|
|
5
|
-
*Agent-agnostic, works with OpenCode, Claude Code, Codex, Gemini, etc.*
|
|
6
|
-
|
|
7
|
-
## Project Overview
|
|
8
|
-
|
|
9
|
-
This is the agent orchestration layer for your project. It provides:
|
|
10
|
-
- Universal agent team for development workflow
|
|
11
|
-
- OpenSpec change management
|
|
12
|
-
- Skills for platform-specific knowledge
|
|
13
|
-
|
|
14
|
-
## I Am the Lead, Full Workflow Ownership
|
|
15
|
-
|
|
16
|
-
When the user provides a work item URL, says "implement the plan", or "I've added comments to the PR", **I own the full lifecycle**. I load the appropriate skill and use ensemble tools (`team_create`, `team_spawn`, etc.) to coordinate the agent team.
|
|
17
|
-
|
|
18
|
-
Trigger patterns:
|
|
19
|
-
- `work on this <azure-devops-url>` → spawn `devops-manager` in read mode → propose OpenSpec → implement → ship
|
|
20
|
-
- `work on this <github-url>` → spawn `devops-manager` in read mode → propose OpenSpec → implement → ship
|
|
21
|
-
- `implement the plan` → load skill `openspec-apply-change` → implement → ship
|
|
22
|
-
- `I've added comments to the PR` → spawn `devops-manager` in feedback mode → fix → update PR
|
|
23
|
-
|
|
24
|
-
**Never delegate without a plan. Never write implementation code directly, always spawn specialists.**
|
|
25
|
-
|
|
26
|
-
## Multi-Agent Execution, opencode-ensemble
|
|
27
|
-
|
|
28
|
-
Parallel execution uses the `opencode-ensemble` plugin (`team_create`, `team_spawn`, etc.).
|
|
29
|
-
Works on **all platforms** (Windows, macOS, Linux) via OpenCode's built-in worktree support.
|
|
30
|
-
|
|
31
|
-
| Tool | What it does |
|
|
32
|
-
|------|-------------|
|
|
33
|
-
| `team_create` | Create a team (caller becomes lead) |
|
|
34
|
-
| `team_spawn` | Start a teammate asynchronously |
|
|
35
|
-
| `team_shutdown` | Stop a teammate, preserve their branch |
|
|
36
|
-
| `team_merge` | Merge a teammate's branch into working dir |
|
|
37
|
-
| `team_cleanup` | Tear down the team |
|
|
38
|
-
| `team_results` | Retrieve full message from a teammate |
|
|
39
|
-
| `team_message` | Send a direct message to a teammate |
|
|
40
|
-
| `team_broadcast` | Message all teammates |
|
|
41
|
-
| `team_tasks_add` | Add tasks to shared board |
|
|
42
|
-
| `team_tasks_complete` | Mark task done |
|
|
43
|
-
|
|
44
|
-
**Dashboard**: Monitor running agents at **http://localhost:4747/**
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## Pipeline
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
devops-manager (read mode)
|
|
52
|
-
→ parse work item via skill → structured summary
|
|
53
|
-
↓
|
|
54
|
-
openspec-propose
|
|
55
|
-
→ proposal.md + specs + tasks
|
|
56
|
-
↓
|
|
57
|
-
[confirm with user]
|
|
58
|
-
↓
|
|
59
|
-
front-engineer + back-engineer + infra-engineer ← parallel, only spawn what the task needs
|
|
60
|
-
↓
|
|
61
|
-
quality-engineer
|
|
62
|
-
→ tests, build, lint, acceptance criteria
|
|
63
|
-
↓
|
|
64
|
-
security-auditor
|
|
65
|
-
→ vulnerability audit, secrets, auth gaps
|
|
66
|
-
↓
|
|
67
|
-
devops-manager (ship mode)
|
|
68
|
-
→ screenshots → commit → push → PR → post comment
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
### Phase 1, Parse & Propose
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
1. team_spawn devops-manager (read mode) → fetch work item via skill, output summary
|
|
75
|
-
2. Load skill: openspec-propose → generate proposal.md, specs/, tasks.md
|
|
76
|
-
- team_create → spawn design + specs in parallel → merge → write tasks.md
|
|
77
|
-
3. Show summary, confirm with user before implementing
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### Phase 2, Implement
|
|
81
|
-
|
|
82
|
-
```
|
|
83
|
-
1. Load skill: openspec-apply-change → get apply instructions
|
|
84
|
-
2. Create feature branch: feature/{id}-{slug}
|
|
85
|
-
3. team_create "<change-name>"
|
|
86
|
-
4. Announce: "Team running. Monitor at http://localhost:4747/"
|
|
87
|
-
5. Spawn only what the task needs (in parallel):
|
|
88
|
-
team_spawn name:front agent:front-engineer → UI tasks
|
|
89
|
-
team_spawn name:back agent:back-engineer → backend tasks
|
|
90
|
-
team_spawn name:infra agent:infra-engineer → infra tasks
|
|
91
|
-
6. Wait for all → team_results → team_shutdown + team_merge
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
### Phase 3, Quality
|
|
95
|
-
|
|
96
|
-
```
|
|
97
|
-
7. team_spawn name:quality agent:quality-engineer → tests, build, lint
|
|
98
|
-
8. Wait → team_results → fix any blockers → team_shutdown
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
### Phase 4, Security
|
|
102
|
-
|
|
103
|
-
```
|
|
104
|
-
9. team_spawn name:security agent:security-auditor → audit full change
|
|
105
|
-
10. Wait → team_results → fix Critical findings → team_shutdown
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
### Phase 5, Ship
|
|
109
|
-
|
|
110
|
-
```
|
|
111
|
-
11. team_spawn name:devops agent:devops-manager (ship mode)
|
|
112
|
-
→ screenshots → commit & push → create PR → post comment
|
|
113
|
-
12. Wait → team_results → report PR URL to user
|
|
114
|
-
13. team_cleanup
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
### Phase 6, PR Feedback Loop
|
|
118
|
-
|
|
119
|
-
```
|
|
120
|
-
When user says "I've added comments to the PR":
|
|
121
|
-
1. team_spawn devops-manager (feedback mode) → read & classify comments
|
|
122
|
-
2. Wait → team_results → spawn front/back/infra for code-change items (parallel)
|
|
123
|
-
3. Wait → team_results → spawn quality-engineer → verify fixes
|
|
124
|
-
4. Wait → team_results → spawn devops-manager (ship mode) → push & update PR
|
|
125
|
-
5. team_cleanup
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
## Agents
|
|
131
|
-
|
|
132
|
-
All agents are universal, no project-specific knowledge. Platform and tech knowledge comes from skills.
|
|
133
|
-
|
|
134
|
-
| Agent | File | Role |
|
|
135
|
-
|-------|------|------|
|
|
136
|
-
| `devops-manager` | .agents/agents/devops-manager.md | Reads work items, creates PRs, handles review feedback |
|
|
137
|
-
| `front-engineer` | .agents/agents/front-engineer.md | Web, mobile, UI implementation |
|
|
138
|
-
| `back-engineer` | .agents/agents/back-engineer.md | APIs, services, data, AI implementation |
|
|
139
|
-
| `infra-engineer` | .agents/agents/infra-engineer.md | Terraform, pipelines, cloud infrastructure |
|
|
140
|
-
| `quality-engineer` | .agents/agents/quality-engineer.md | Unit, integration, e2e tests across all layers |
|
|
141
|
-
| `security-auditor` | .agents/agents/security-auditor.md | Vulnerability audit, secrets, auth gaps |
|
|
142
|
-
|
|
143
|
-
## Skills
|
|
144
|
-
|
|
145
|
-
Skills provide platform and tech-specific knowledge. Agents detect and load them automatically, the user never specifies which skill to use.
|
|
146
|
-
|
|
147
|
-
Skills are located in `.agents/skills/`. Each skill has a `SKILL.md` with a description the agent reads to determine relevance.
|
|
148
|
-
|
|
149
|
-
| Skill | Purpose |
|
|
150
|
-
|-------|---------|
|
|
151
|
-
| `ob-userstory-az` | Parse Azure DevOps work item URL |
|
|
152
|
-
| `ob-userstory-gh` | Parse GitHub Issue URL |
|
|
153
|
-
| `ob-pullrequest-az` | Create PR on Azure DevOps |
|
|
154
|
-
| `ob-pullrequest-gh` | Create PR on GitHub |
|
|
155
|
-
| `openspec-propose` | Propose change artifacts (proposal, specs, tasks) |
|
|
156
|
-
| `openspec-apply-change` | Implement change with agent team |
|
|
157
|
-
| `openspec-archive-change` | Archive completed change |
|
|
158
|
-
|
|
159
|
-
---
|
|
160
|
-
|
|
161
|
-
## Branch Naming
|
|
162
|
-
|
|
163
|
-
Format: `feature/{issue-id}-{slug}`
|
|
164
|
-
Example: `feature/42-add-user-auth`
|
|
165
|
-
|
|
166
|
-
---
|
|
167
|
-
|
|
168
|
-
## Project Structure
|
|
169
|
-
|
|
170
|
-
```
|
|
171
|
-
[project-root]/
|
|
172
|
-
└── Copilots/ ← THIS FOLDER (agent orchestration)
|
|
173
|
-
├── .opencode/
|
|
174
|
-
│ ├── agents/ # Agent definitions (universal, no project knowledge)
|
|
175
|
-
│ └── skills/ # Skills (platform/tech specific knowledge)
|
|
176
|
-
├── openspec/
|
|
177
|
-
│ ├── specs/
|
|
178
|
-
│ └── changes/
|
|
179
|
-
│ └── {change}/
|
|
180
|
-
│ └── images/
|
|
181
|
-
├── AGENTS.md
|
|
182
|
-
├── ARCHITECTURE.md
|
|
183
|
-
└── DESIGN.md
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## Guardrails
|
|
189
|
-
|
|
190
|
-
### Git Operations
|
|
191
|
-
|
|
192
|
-
Agents CAN:
|
|
193
|
-
- ✅ Commit to feature branches
|
|
194
|
-
- ✅ Push to feature branches
|
|
195
|
-
|
|
196
|
-
Agents CANNOT:
|
|
197
|
-
- ❌ Commit or push to `main`, FORBIDDEN
|
|
198
|
-
- ❌ Force push, FORBIDDEN
|
|
199
|
-
- ❌ Merge PRs, human-only
|
|
200
|
-
- ❌ Create or delete branches other than `feature/*`
|
|
201
|
-
|
|
202
|
-
### Platform CLI
|
|
203
|
-
|
|
204
|
-
ALL platform interactions via CLI only. Browser MCP FORBIDDEN for any DevOps or GitHub operation.
|
|
205
|
-
|
|
206
|
-
| Operation | Azure DevOps | GitHub |
|
|
207
|
-
|-----------|-------------|--------|
|
|
208
|
-
| Read issue | `az boards work-item show --id <id>` | `gh issue view <number>` |
|
|
209
|
-
| Read PR threads | `az devops invoke ...` | `gh pr view <number> --comments` |
|
|
210
|
-
| Create PR | `az repos pr create ...` | `gh pr create ...` |
|
|
211
|
-
|
|
212
|
-
Browser MCP tools permitted only for screenshots of **local running app** on `localhost` URLs.
|
|
213
|
-
|
|
214
|
-
### Security
|
|
215
|
-
|
|
216
|
-
Agents CANNOT:
|
|
217
|
-
- ❌ Access `.env` or config files with secrets
|
|
218
|
-
- ❌ Log or output credentials, API keys, or tokens
|
|
219
|
-
- ❌ Commit secrets to git
|
|
220
|
-
|
|
221
|
-
### Scope
|
|
222
|
-
|
|
223
|
-
- Max 10 files per change
|
|
224
|
-
- No architecture changes without human approval
|
|
225
|
-
- No pipeline modifications without human approval
|
|
226
|
-
|
|
227
|
-
---
|
|
228
|
-
|
|
229
|
-
## Communication Style
|
|
230
|
-
|
|
231
|
-
Terse. Technical substance exact. Only fluff die.
|
|
232
|
-
Drop: articles, filler, pleasantries, hedging.
|
|
233
|
-
Fragments OK. Short synonyms. Code unchanged.
|
|
234
|
-
Pattern: [thing] [action] [reason]. [next step].
|