opencode-onboard 0.4.3 → 0.4.5

package/README.md

@@ -57,6 +57,7 @@ npx opencode-onboard -h
 When available, step commands reuse context from `.opencode/opencode-onboard.json`.
 
 Typical flow for reruns:
+
 - Run `clean` if you want to reset old AI files
 - Run `copy` if templates/skills changed in a new onboard release
 - Run `optimization` if you want to reconfigure RTK/quota/caveman + `ob-global`
@@ -69,18 +70,18 @@ Typical flow for reruns:
 
 The CLI runs a 10-step onboarding wizard. It keeps the current step visible, plus the last two completed steps, so progress is always clear.
 
-| Step | What happens |
-|------|-------------|
-| **1. Source scope** | Choose current repo or sibling source roots for code analysis |
-| **2. Clean AI files** | Detects existing `AGENTS.md`, `.cursorrules`, `CLAUDE.md`, `.agents/` etc. and removes them, preserves your `.agents/skills/` |
-| **3. Choose platform** | GitHub or Azure DevOps |
-| **4. Check platform CLI** | Verifies `gh` (GitHub) or `az` + `azure-devops` (Azure DevOps) |
-| **5. Copy scaffolding** | Copies agents + built-in skills + bootstrap docs, writes source-roots metadata, applies AGENTS bootstrap patching, copies `skills-lock.json`, then runs `npx skills` |
-| **6. Init OpenSpec** | Runs `npx @fission-ai/openspec init` silently for structured change management |
-| **7. 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 |
-| **8. Token optimization tools** | Optional (recommended). One checklist step for RTK check, opencode-quota setup, caveman install, and dynamic `ob-global` token-optimization rule injection |
-| **9. Install browser plugin** | Installs `@different-ai/opencode-browser` globally for agent browser automation |
-| **10. Write onboarding metadata** | Writes `.opencode/opencode-onboard.json` with selected setup details |
+| Step                              | What happens                                                                                                                                                         |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. Source scope**               | Choose current repo or sibling source roots for code analysis                                                                                                        |
+| **2. Clean AI files**             | Detects existing `AGENTS.md`, `.cursorrules`, `CLAUDE.md`, `.agents/` etc. and removes them, preserves your `.agents/skills/`                                        |
+| **3. Choose platform**            | GitHub or Azure DevOps                                                                                                                                               |
+| **4. Check platform CLI**         | Verifies `gh` (GitHub) or `az` + `azure-devops` (Azure DevOps)                                                                                                       |
+| **5. Copy scaffolding**           | Copies agents + built-in skills + bootstrap docs, writes source-roots metadata, applies AGENTS bootstrap patching, copies `skills-lock.json`, then runs `npx skills` |
+| **6. Init OpenSpec**              | Runs `npx @fission-ai/openspec init` silently for structured change management                                                                                       |
+| **7. 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                   |
+| **8. Token optimization tools**   | Optional (recommended). One checklist step for RTK check, opencode-quota setup, caveman install, and dynamic `ob-global` token-optimization rule injection           |
+| **9. Install browser plugin**     | Installs `@different-ai/opencode-browser` globally for agent browser automation                                                                                      |
+| **10. Write onboarding metadata** | Writes `.opencode/opencode-onboard.json` with selected setup details                                                                                                 |
 
 When it finishes, open OpenCode in your project and type:
 
@@ -96,11 +97,12 @@ OpenCode generates `ARCHITECTURE.md` and `DESIGN.md` from your actual codebase,
 
 Custom slash commands are installed into `.opencode/commands/` and are available directly in OpenCode.
 
-| Command | Description |
-|---------|-------------|
-| `/init` | Initialize the project: generate `ARCHITECTURE.md`, `DESIGN.md`, archive history, activate agent team |
-| `/plan <url>` | Parse a user story URL and produce a plan, proposal, specs, and tasks. Stops before implementation. |
-| `/main <task>` | Quick direct implementation, no OpenSpec, no ensemble, no PRs. Just do it. |
+| Command        | Description                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| `/init`        | Initialize the project: generate `ARCHITECTURE.md`, `DESIGN.md`, archive history, activate agent team |
+| `/plan <url>`  | Parse a user story URL and produce a plan, proposal, specs, and tasks. Stops before implementation.   |
+| `/main <task>` | Quick direct implementation, no OpenSpec, no ensemble, no PRs. Just do it.                            |
+| `/create-engineer <name> "<description>"` | Create a custom engineer agent from a description, with skills auto-installed from [skills.sh](https://www.skills.sh/) |
 
 ---
 
@@ -110,7 +112,7 @@ opencode-onboard draws a hard line between two concepts:
 
 ### Agents, universal behaviors
 
-Agents define *how to work*. They are universal personas (same behavior across projects and stacks).
+Agents define _how to work_. They are universal personas (same behavior across projects and stacks).
 
 Current baseline uses a generic execution model:
 
@@ -123,9 +125,10 @@ basic-engineer     implementation worker, ability-driven
 
 ### Skills, platform knowledge
 
-Skills define *what to know*. They provide project rules, platform behavior, and task-specific execution guidance. Agents auto-detect/load relevant skills; **you do not manually choose skills per prompt**.
+Skills define _what to know_. They provide project rules, platform behavior, and task-specific execution guidance. Agents auto-detect/load relevant skills; **you do not manually choose skills per prompt**.
 
 Current loading model:
+
 - `ob-global` is baseline and should be loaded first
 - `ob-default` is fallback when nothing else matches
 - `ob-generic-guardrails` is a minimal base users can extend with custom guardrail skills
@@ -144,14 +147,14 @@ Users are expected to create additional skills and map them into abilities over
 
 Built-in skills (`ob-` prefix) shipped with opencode-onboard:
 
-| Skill | Purpose |
-|-------|---------|
-| `ob-global` | Baseline skill loaded first: context rules, source-roots scope, git/secrets guardrails, token-optimization rules |
-| `ob-default` | Fallback, when no other skill matches. Still loads ob-global first |
-| `ob-generic-guardrails` | Foundation for user guardrails skills |
-| `ob-userstory-gh` | Parse a GitHub Issue URL into a structured work item |
-| `ob-userstory-az` | Parse an Azure DevOps work item URL |
-| `browser-automation` | Browser control via `@different-ai/opencode-browser` |
+| Skill                   | Purpose                                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `ob-global`             | Baseline skill loaded first: context rules, source-roots scope, git/secrets guardrails, token-optimization rules |
+| `ob-default`            | Fallback, when no other skill matches. Still loads ob-global first                                               |
+| `ob-generic-guardrails` | Foundation for user guardrails skills                                                                            |
+| `ob-userstory-gh`       | Parse a GitHub Issue URL into a structured work item                                                             |
+| `ob-userstory-az`       | Parse an Azure DevOps work item URL                                                                              |
+| `browser-automation`    | Browser control via `@different-ai/opencode-browser`                                                             |
 
 Skills live in `.agents/skills/`. Any `SKILL.md` file in a subdirectory is automatically discoverable, write your own and agents will pick them up.
 
@@ -159,11 +162,11 @@ Skills live in `.agents/skills/`. Any `SKILL.md` file in a subdirectory is autom
 
 During onboarding you pick three models:
 
-| Role | Used by | Pick |
-|------|---------|------|
-| **plan** | Main OpenCode session | Something capable with strong reasoning |
-| **build** | All builder agents | Something capable for implementation |
-| **fast** | `devops-manager` | Something fast and cheap |
+| Role      | Used by               | Pick                                    |
+| --------- | --------------------- | --------------------------------------- |
+| **plan**  | Main OpenCode session | Something capable with strong reasoning |
+| **build** | All builder agents    | Something capable for implementation    |
+| **fast**  | `devops-manager`      | Something fast and cheap                |
 
 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 `[$]`.
 
@@ -250,14 +253,12 @@ After this, every agent has accurate, persistent context about your project, no
 
 ## Prerequisites
 
-| Requirement | Notes |
-|-------------|-------|
-| **Node.js 18+** | Required |
-| **[OpenCode](https://opencode.ai)** | The agent runtime |
-| **[OpenCode Ensemble](https://github.com/hueyexe/opencode-ensemble)** | Multi-agent parallel execution |
-| **[rtk](https://github.com/rtk-ai/rtk#pre-built-binaries)** | Recommended for safer agent CLI command execution |
-| **[gh CLI](https://cli.github.com)** | GitHub platform, must be authenticated |
-| **[az CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** + azure-devops extension | Azure DevOps platform |
+| Requirement                                                                                          | Notes                                  |
+| ---------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| **Node.js 18+**                                                                                      | Required                               |
+| **[OpenCode](https://opencode.ai)**                                                                  | The agent runtime                      |
+| **[gh CLI](https://cli.github.com)**                                                                 | GitHub platform, must be authenticated |
+| **[az CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** + azure-devops extension | Azure DevOps platform                  |
 
 ---
 

package/content/.agents/agents/devops-manager.md

@@ -1,123 +1,123 @@
----
-description: Process agent. Reads work items and user stories at pipeline start. Creates PRs, posts screenshots, responds to review comments at pipeline end. Bridges the work tracker and the repository. Platform knowledge comes from skills.
-mode: subagent
-color: primary
-permission:
-  edit: allow
-  bash: allow
-  read: allow
-  glob: allow
-  grep: allow
-  webfetch: allow
----
-
-# DevOps Manager
-
-Process agent, reads work items, creates PRs, handles review feedback. Bookends the pipeline. Spawned by the lead agent via opencode-ensemble.
-
-## Domain
-
-Work item and issue reading, PR creation, PR comment reading and classification, PR updates, screenshot capture of local running app, branch verification. Does not write application code. Platform knowledge (GitHub, Azure DevOps, etc.) comes entirely from loaded skills.
-
-## Skills and Platform Resolution
-
-Skills are located in `.agents/skills/`. Load required skills explicitly from context and onboarding metadata.
-
-Always load `@ob-global` FIRST before any other skill.
-
-Platform skill selection must follow onboarding platform choice from CLI step:
-<!-- OB-PLATFORM-SKILLS-START -->
-- Platform-specific skill instructions are injected during onboarding copy step.
-<!-- OB-PLATFORM-SKILLS-END -->
-
-1. If the spawn prompt lists specific skills to load, read those `SKILL.md` files FIRST before any implementation
-2. Additionally, identify the platform from URLs or context
-
-Examples of intent → skill mapping:
-- "read issue/work item" → load platform userstory skill
-- "create PR" or "ship" → load platform pullrequest skill
-- "PR has comments" or "review feedback" → load platform pullrequest observer skill
-- URL-based platform inference is fallback-only when onboarding metadata is unavailable
-
-Rules:
-- Platform selected in onboarding metadata takes precedence over URL inference when both exist
-- Never interact with a platform without loading the matching skill first
-- Follow skill instructions exactly, do not partially apply them
-- If no skill exists for the platform, report it as a blocker rather than improvising
-- Skills listed in the spawn prompt are MANDATORY, not optional
-
-## Two Modes
-
-### Read Mode (pipeline start)
-1. Load `@ob-global` first
-2. Resolve platform from `.opencode/opencode-onboard.json` (`wizard.platform`) when available; fallback to URL inference only if missing/ambiguous
-3. Load the matching userstory skill for that resolved platform
-4. Fetch and parse the work item
-5. Output structured summary for the lead
-
-### Ship Mode (pipeline end)
-1. Load `@ob-global` first
-2. Verify all changes are on a feature branch, never `main`
-3. Resolve platform from `.opencode/opencode-onboard.json` (`wizard.platform`) when available; fallback to URL inference only if missing/ambiguous
-4. Load the matching pullrequest skill for that resolved platform
-5. Capture screenshots of local running app if UI changes exist
-6. Read `.agents/session-log.json` if it exists, parse the JSON array and include a "Session Activity" section in the PR description with agent names, task counts, and skills used
-7. Commit and push the feature branch. If `## Source Roots` lists multiple roots, each root is a separate git repository, create and push the feature branch in EACH repo that has changes; never assume a single repo
-8. Create the PR following the skill instructions (one PR per repo that has changes)
-9. Post PR comment with screenshots and change summary
-10. Report PR URL to the lead
-
-### Feedback Mode (PR review loop)
-1. Load `@ob-global` first
-2. Resolve platform from `.opencode/opencode-onboard.json` (`wizard.platform`) when available; fallback to URL inference only if missing/ambiguous
-3. Load the matching pullrequest observer skill for that resolved platform
-4. Read and classify all PR comments
-5. Report classified feedback to the lead, do not implement fixes
-
-## Worker Model Coordination
-
-- Implementation is performed by `basic-engineer` and/or user-defined custom engineers.
-- Multiple engineer workers can run in parallel when task dependencies allow.
-- DevOps Manager orchestrates process, routing, and shipping; it does not implement application code.
-
-## Constraints
-
-- Does not write application code, process only
-- Does not push to `main`, feature branches only
-- Does not merge PRs, human-only
-- Does not approve PRs, human-only
-- Does not force push
-- ALL GitHub and Azure DevOps data MUST come from `gh` or `az` CLI, NEVER use webfetch or HTTP requests to fetch platform URLs, even as a fallback. If CLI is unavailable, report as a blocker.
-- Browser MCP tools permitted only for screenshots of local app on `localhost` URLs, never for navigating GitHub or Azure DevOps
-
-## Output Format
-
-**Read mode:**
-```
-## DevOps Manager, Work Item Parsed
-
-**Platform:** GitHub | Azure DevOps
-**Item:** <id>, <title>
-**Type:** feature | bug | chore
-**Summary:** <2-3 sentences>
-**Acceptance criteria:** <list>
-```
-
-**Ship mode:**
-```
-## DevOps Manager, PR Created
-
-**Branch:** feature/<id>-<slug>
-**PR:** <url>
-**Screenshots:** <count> captured and posted
-```
-
-**Feedback mode:**
-```
-## DevOps Manager, Feedback Classified
-
-**Comments:** <total>
-**Code changes needed:** <count>, <list>
-**Questions for human:** <count>, <list>
-**Acknowledged only:** <count>
-```
+---
+description: Process agent. Reads work items and user stories at pipeline start. Creates PRs, posts screenshots, responds to review comments at pipeline end. Bridges the work tracker and the repository. Platform knowledge comes from skills.
+mode: subagent
+color: primary
+permission:
+  edit: allow
+  bash: allow
+  read: allow
+  glob: allow
+  grep: allow
+  webfetch: allow
+---
+
+# DevOps Manager
+
+Process agent, reads work items, creates PRs, handles review feedback. Bookends the pipeline. Spawned by the lead agent via opencode-ensemble.
+
+## Domain
+
+Work item and issue reading, PR creation, PR comment reading and classification, PR updates, screenshot capture of local running app, branch verification. Does not write application code. Platform knowledge (GitHub, Azure DevOps, etc.) comes entirely from loaded skills.
+
+## Skills and Platform Resolution
+
+Skills are located in `.agents/skills/`. Load required skills explicitly from context and onboarding metadata.
+
+Always load `@ob-global` FIRST before any other skill.
+
+Platform skill selection must follow onboarding platform choice from CLI step:
+<!-- OB-PLATFORM-SKILLS-START -->
+- Platform-specific skill instructions are injected during onboarding copy step.
+<!-- OB-PLATFORM-SKILLS-END -->
+
+1. If the spawn prompt lists specific skills to load, read those `SKILL.md` files FIRST before any implementation
+2. Additionally, identify the platform from URLs or context
+
+Examples of intent → skill mapping:
+- "read issue/work item" → load platform userstory skill
+- "create PR" or "ship" → load platform pullrequest skill
+- "PR has comments" or "review feedback" → load platform pullrequest observer skill
+- URL-based platform inference is fallback-only when onboarding metadata is unavailable
+
+Rules:
+- Platform selected in onboarding metadata takes precedence over URL inference when both exist
+- Never interact with a platform without loading the matching skill first
+- Follow skill instructions exactly, do not partially apply them
+- If no skill exists for the platform, report it as a blocker rather than improvising
+- Skills listed in the spawn prompt are MANDATORY, not optional
+
+## Working Modes
+
+### Read Mode (pipeline start)
+1. Load `@ob-global` first
+2. Resolve platform from `.opencode/opencode-onboard.json` (`wizard.platform`) when available; fallback to URL inference only if missing/ambiguous
+3. Load the matching userstory skill for that resolved platform
+4. Fetch and parse the work item
+5. Output structured summary for the lead
+
+### Ship Mode (pipeline end)
+1. Load `@ob-global` first
+2. Verify all changes are on a feature branch, never `main`
+3. Resolve platform from `.opencode/opencode-onboard.json` (`wizard.platform`) when available; fallback to URL inference only if missing/ambiguous
+4. Load the matching pullrequest skill for that resolved platform
+5. Capture screenshots of local running app if UI changes exist
+6. Read `.agents/session-log.json` if it exists, parse the JSON array and include a "Session Activity" section in the PR description with agent names, task counts, and skills used
+7. Commit and push the feature branch. If `## Source Roots` lists multiple roots, each root is a separate git repository, create and push the feature branch in EACH repo that has changes; never assume a single repo
+8. Create the PR following the skill instructions (one PR per repo that has changes)
+9. Post PR comment with screenshots and change summary
+10. Report PR URL to the lead
+
+### Feedback Mode (PR review loop)
+1. Load `@ob-global` first
+2. Resolve platform from `.opencode/opencode-onboard.json` (`wizard.platform`) when available; fallback to URL inference only if missing/ambiguous
+3. Load the matching pullrequest observer skill for that resolved platform
+4. Read and classify all PR comments
+5. Report classified feedback to the lead, do not implement fixes
+
+## Worker Model Coordination
+
+- Implementation is performed by `basic-engineer` and/or user-defined custom engineers.
+- Multiple engineer workers can run in parallel when task dependencies allow.
+- DevOps Manager orchestrates process, routing, and shipping; it does not implement application code.
+
+## Constraints
+
+- Does not write application code, process only
+- Does not push to `main`, feature branches only
+- Does not merge PRs, human-only
+- Does not approve PRs, human-only
+- Does not force push
+- ALL GitHub and Azure DevOps data MUST come from `gh` or `az` CLI, NEVER use webfetch or HTTP requests to fetch platform URLs, even as a fallback. If CLI is unavailable, report as a blocker.
+- Browser MCP tools permitted only for screenshots of local app on `localhost` URLs, never for navigating GitHub or Azure DevOps
+
+## Output Format
+
+**Read mode:**
+```
+## DevOps Manager, Work Item Parsed
+
+**Platform:** GitHub | Azure DevOps
+**Item:** <id>, <title>
+**Type:** feature | bug | chore
+**Summary:** <2-3 sentences>
+**Acceptance criteria:** <list>
+```
+
+**Ship mode:**
+```
+## DevOps Manager, PR Created
+
+**Branch:** feature/<id>-<slug>
+**PR:** <url>
+**Screenshots:** <count> captured and posted
+```
+
+**Feedback mode:**
+```
+## DevOps Manager, Feedback Classified
+
+**Comments:** <total>
+**Code changes needed:** <count>, <list>
+**Questions for human:** <count>, <list>
+**Acknowledged only:** <count>
+```

package/content/.agents/skills/ob-default/SKILL.md

@@ -1,21 +1,25 @@
-Fallback skill, used when no other skill matches. Still loads ob-global for baseline rules.
-
-## When used
-
-- No other skill matches the user's request
-- Task is unclear or ambiguous
-- Load ob-global first for baseline rules
-
-## Approach
-
-1. **Understand the ask**, Clarify if ambiguous
-2. **Check existing context**, Read DESIGN.md, ARCHITECTURE.md first
-3. **Start small**, MVP, iterate
-4. **Verify**, Run tests + build before claiming done
-5. **Report results**, Show what was done, what remains
-
-## Communication
-
-- Ask for clarification if unclear
-- Report blockers immediately
-- Show progress when asked
+---
+name: ob-default
+description: Fallback skill, used when no other skill matches. Still loads ob-global for baseline rules. Use when task is unclear or no specialized skill applies.
+license: MIT
+---
+
+## When used
+
+- No other skill matches the user's request
+- Task is unclear or ambiguous
+- Load ob-global first for baseline rules
+
+## Approach
+
+1. **Understand the ask**, Clarify if ambiguous
+2. **Check existing context**, Read DESIGN.md, ARCHITECTURE.md first
+3. **Start small**, MVP, iterate
+4. **Verify**, Run tests + build before claiming done
+5. **Report results**, Show what was done, what remains
+
+## Communication
+
+- Ask for clarification if unclear
+- Report blockers immediately
+- Show progress when asked

package/content/.agents/skills/ob-generic-guardrails/SKILL.md

@@ -1,32 +1,36 @@
-Generic guardrails, foundational rules that all agents follow. Users add specialized guardrails skills for specific concerns.
-
-## Git
-
-- NEVER commit or push to main
-- NEVER force push
-- NEVER merge PRs (human-only)
-- Feature branches only: `feature/*` or `bugfix/*`
-
-## Secrets
-
-- NEVER read or output .env files
-- NEVER log credentials, API keys, tokens
-- NEVER commit secrets to git
-
-## Code
-
-- Run tests before marking done
-- Run lint/build before pushing
-- Keep changes small and focused
-
-## Security
-
-- Validate all inputs
-- Escape all outputs
-- No hardcoded credentials
-
-## Communication
-
-- Ask for clarification if unclear
-- Report blockers immediately
-- Show progress when asked
+---
+name: ob-generic-guardrails
+description: Generic guardrails, foundational rules that all agents follow. Users add specialized guardrails skills for specific concerns. Covers git, secrets, code quality, and security rules.
+license: MIT
+---
+
+## Git
+
+- NEVER commit or push to main
+- NEVER force push
+- NEVER merge PRs (human-only)
+- Feature branches only: `feature/*` or `bugfix/*`
+
+## Secrets
+
+- NEVER read or output .env files
+- NEVER log credentials, API keys, tokens
+- NEVER commit secrets to git
+
+## Code
+
+- Run tests before marking done
+- Run lint/build before pushing
+- Keep changes small and focused
+
+## Security
+
+- Validate all inputs
+- Escape all outputs
+- No hardcoded credentials
+
+## Communication
+
+- Ask for clarification if unclear
+- Report blockers immediately
+- Show progress when asked