opencode-onboard 0.1.2 → 0.1.4
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 -213
- package/content/.agents/skills/browser-automation/SKILL.md +26 -10
- package/content/.agents/skills/ob-pullrequest-az/SKILL.md +170 -0
- package/content/.agents/skills/ob-pullrequest-gh/SKILL.md +140 -0
- package/content/.agents/skills/ob-userstory-az/SKILL.md +172 -206
- package/content/.agents/skills/ob-userstory-gh/SKILL.md +21 -57
- package/content/AGENTS.md +237 -1
- package/package.json +1 -1
- package/content/.agents/agents/.bootstrap/AGENTS.template.md +0 -234
package/README.md
CHANGED
|
@@ -1,213 +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
|
-
## 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)
|
|
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)
|
|
@@ -1,19 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: browser-automation
|
|
3
|
-
description: Reliable, composable browser automation using
|
|
3
|
+
description: Reliable, composable browser automation using OpenCode Browser primitives. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
|
|
4
4
|
license: MIT
|
|
5
|
-
compatibility: opencode
|
|
5
|
+
compatibility: Requires opencode-browser extension installed and running.
|
|
6
6
|
metadata:
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
author: copilots
|
|
8
|
+
version: "1.0"
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Browser MCP tools are permitted ONLY for interactions with the LOCAL running app on `localhost` URLs.
|
|
12
|
+
**Navigating to external services (github.com, dev.azure.com, etc.) via browser MCP is FORBIDDEN.**
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
- Use `browser_query` list and index selection to click reliably
|
|
15
|
-
- Confirm state changes after each action
|
|
16
|
-
- Support CLI-first debugging with `opencode-browser tool` commands
|
|
14
|
+
---
|
|
17
15
|
|
|
18
16
|
## Best-practice workflow
|
|
19
17
|
|
|
@@ -25,6 +23,8 @@ metadata:
|
|
|
25
23
|
6. Click, type, or select using `index`
|
|
26
24
|
7. Confirm using `browser_query` or `browser_snapshot`
|
|
27
25
|
|
|
26
|
+
---
|
|
27
|
+
|
|
28
28
|
## CLI-first debugging
|
|
29
29
|
|
|
30
30
|
- List all available tools: `npx @different-ai/opencode-browser tools`
|
|
@@ -33,7 +33,7 @@ metadata:
|
|
|
33
33
|
- Run smoke test: `npx @different-ai/opencode-browser self-test`
|
|
34
34
|
- After `update`, reload the unpacked extension in `chrome://extensions`
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
---
|
|
37
37
|
|
|
38
38
|
## Selecting options
|
|
39
39
|
|
|
@@ -41,6 +41,8 @@ This path is useful for reproducing selector/scroll issues quickly before runnin
|
|
|
41
41
|
- Prefer `value` or `label`; use `optionIndex` when needed
|
|
42
42
|
- Example: `browser_select({ selector: "select", value: "plugin" })`
|
|
43
43
|
|
|
44
|
+
---
|
|
45
|
+
|
|
44
46
|
## Query modes
|
|
45
47
|
|
|
46
48
|
- `text`: read visible text from a matched element
|
|
@@ -49,11 +51,15 @@ This path is useful for reproducing selector/scroll issues quickly before runnin
|
|
|
49
51
|
- `exists`: check presence and count
|
|
50
52
|
- `page_text`: extract visible page text
|
|
51
53
|
|
|
54
|
+
---
|
|
55
|
+
|
|
52
56
|
## Opening tabs
|
|
53
57
|
|
|
54
58
|
- Use `browser_open_tab` to create a new tab, optionally with `url` and `active`
|
|
55
59
|
- Example: `browser_open_tab({ url: "https://example.com", active: false })`
|
|
56
60
|
|
|
61
|
+
---
|
|
62
|
+
|
|
57
63
|
## Troubleshooting
|
|
58
64
|
|
|
59
65
|
- If a selector fails, run `browser_query` with `mode=page_text` to confirm the content exists
|
|
@@ -61,3 +67,13 @@ This path is useful for reproducing selector/scroll issues quickly before runnin
|
|
|
61
67
|
- For inbox/chat panes, try text selectors first (`text:Subject line`) then verify selection with `browser_query`
|
|
62
68
|
- For scrollable containers, pass both `selector` and `x`/`y` to `browser_scroll` and then verify `scrollTop`
|
|
63
69
|
- Confirm results after each action
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Guardrails
|
|
74
|
+
|
|
75
|
+
- ✅ Screenshots of locally running app on `localhost` URLs
|
|
76
|
+
- ✅ Click, type, scroll, query on `localhost` pages
|
|
77
|
+
- ❌ Navigate to external services (github.com, dev.azure.com, npmjs.com, etc.) — FORBIDDEN
|
|
78
|
+
- ❌ Use browser tools for any DevOps or GitHub operations — FORBIDDEN
|
|
79
|
+
- ❌ Use browser tools to read or modify production systems — FORBIDDEN
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ob-pullrequest-az
|
|
3
|
+
description: Create Azure DevOps PRs with screenshots, or read and triage PR review feedback. Use when shipping a feature branch or when user says "I've added comments to the PR".
|
|
4
|
+
license: MIT
|
|
5
|
+
compatibility: Requires az CLI, az devops extension, openspec CLI, and opencode-browser for screenshots.
|
|
6
|
+
metadata:
|
|
7
|
+
author: copilots
|
|
8
|
+
version: "1.0"
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
**RTK - MANDATORY**
|
|
12
|
+
|
|
13
|
+
Use `rtk` wrapper for ALL CLI commands:
|
|
14
|
+
- `rtk git add` NOT `git add`
|
|
15
|
+
- `rtk git commit` NOT `git commit`
|
|
16
|
+
- `rtk git push` NOT `git push`
|
|
17
|
+
- `rtk az repos pr create` NOT `az repos pr create`
|
|
18
|
+
- `rtk az repos pr work-item add` NOT `az repos pr work-item add`
|
|
19
|
+
- `rtk az devops invoke` NOT `az devops invoke`
|
|
20
|
+
|
|
21
|
+
**Browser MCP tools are FORBIDDEN for all Azure DevOps operations.**
|
|
22
|
+
Browser tools are ONLY permitted for screenshots of the LOCAL running app on `localhost` URLs.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Mode A: Create PR (ship mode)
|
|
27
|
+
|
|
28
|
+
Triggered when devops-manager is in ship mode after implementation is complete.
|
|
29
|
+
|
|
30
|
+
### Step 1: Verify feature branch
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
rtk git branch --show-current
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Branch must be `feature/{id}-{slug}`. NEVER push to `main`.
|
|
37
|
+
|
|
38
|
+
### Step 2: Capture screenshots (if UI changes exist)
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
browser_navigate url="http://localhost:{port}/{route}"
|
|
42
|
+
browser_wait ms=2000
|
|
43
|
+
browser_screenshot
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Save to: `openspec/changes/{change-name}/images/{feature}.png`
|
|
47
|
+
|
|
48
|
+
### Step 3: Commit and push
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
rtk git add .
|
|
52
|
+
rtk git commit -m "feat(#{id}): {description}"
|
|
53
|
+
rtk git push origin feature/{id}-{slug}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Step 4: Create PR
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
rtk az repos pr create \
|
|
60
|
+
--repository {repo} \
|
|
61
|
+
--source-branch feature/{id}-{slug} \
|
|
62
|
+
--target-branch main \
|
|
63
|
+
--title "feat(#{id}): {title}" \
|
|
64
|
+
--description "{description}"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Step 5: Link work item (MANDATORY, run sequentially — not in parallel)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
rtk az repos pr work-item add --id {pr-id} --work-items {workitem-id}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Step 6: Post screenshot comment
|
|
74
|
+
|
|
75
|
+
Build raw URL for each image:
|
|
76
|
+
```
|
|
77
|
+
https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path=openspec/changes/{change}/images/{file}.png&versionType=branch&version={branch}&api-version=7.1
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Post via:
|
|
81
|
+
```bash
|
|
82
|
+
rtk az devops invoke \
|
|
83
|
+
--area git --resource pullRequestThreads \
|
|
84
|
+
--route-parameters project={project} repositoryId={repo} pullRequestId={pr-id} \
|
|
85
|
+
--http-method POST --api-version 7.1 --in-file body.json
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`body.json`:
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"comments": [{
|
|
92
|
+
"parentCommentId": 0,
|
|
93
|
+
"content": "## Screenshots\n\n",
|
|
94
|
+
"commentType": 1
|
|
95
|
+
}],
|
|
96
|
+
"status": "active"
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Mode B: Read PR Feedback (feedback mode)
|
|
103
|
+
|
|
104
|
+
Triggered when user says "I've added comments to the PR" or "check PR feedback".
|
|
105
|
+
|
|
106
|
+
### Step 1: Find PRs
|
|
107
|
+
|
|
108
|
+
If PR link provided, extract ID from URL. Otherwise:
|
|
109
|
+
```bash
|
|
110
|
+
rtk az repos pr list --repository {repo} --status active --top 1
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Step 2: Read comment threads
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
rtk az devops invoke \
|
|
117
|
+
--area git --resource pullRequestThreads \
|
|
118
|
+
--route-parameters project={project} repositoryId={repo} pullRequestId={id} \
|
|
119
|
+
--http-method GET --api-version 7.1
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Step 3: Categorize feedback
|
|
123
|
+
|
|
124
|
+
| Category | Description | Action |
|
|
125
|
+
|----------|-------------|--------|
|
|
126
|
+
| `code-change` | Reviewer requests code modification | Return to lead to spawn specialists |
|
|
127
|
+
| `spec-update` | Affects proposal, design, or tasks | Update openspec artifacts |
|
|
128
|
+
| `question` | Reviewer asks a question | Reply with answer |
|
|
129
|
+
| `resolved` | Thread already resolved | Skip |
|
|
130
|
+
|
|
131
|
+
### Step 4: Update openspec (if spec-update)
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
rtk git branch --show-current
|
|
135
|
+
# feature/193208-roles-crud → change: us-193208-roles-crud
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Update: `openspec/changes/{change}/proposal.md`, `design.md`, or `tasks.md` as appropriate.
|
|
139
|
+
|
|
140
|
+
### Step 5: Reply to each thread
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
rtk az devops invoke \
|
|
144
|
+
--area git --resource pullRequestThreadComments \
|
|
145
|
+
--route-parameters project={project} repositoryId={repo} pullRequestId={id} threadId={tid} \
|
|
146
|
+
--http-method POST --api-version 7.1 --in-file reply.json
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`reply.json`:
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"comments": [{
|
|
153
|
+
"parentCommentId": 1,
|
|
154
|
+
"content": "Acknowledged — applying this change now.",
|
|
155
|
+
"commentType": 1
|
|
156
|
+
}]
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Guardrails
|
|
163
|
+
|
|
164
|
+
- ✅ Commit and push to feature branches only
|
|
165
|
+
- ✅ Create and comment on PRs via az CLI
|
|
166
|
+
- ✅ Screenshots of localhost only via browser_screenshot
|
|
167
|
+
- ❌ Commit or push to `main` — FORBIDDEN
|
|
168
|
+
- ❌ Force push — FORBIDDEN
|
|
169
|
+
- ❌ Merge or approve PRs — human-only
|
|
170
|
+
- ❌ Navigate browser to dev.azure.com — FORBIDDEN
|