opencode-onboard 0.4.2 → 0.4.4

package/content/.opencode/commands/create-engineer.md

@@ -0,0 +1,109 @@
+---
+description: Create a custom engineer agent from a description, with skills from skills.sh
+---
+
+Create a new custom engineer agent based on the `basic-engineer.md` template.
+
+**Usage**: `/create-engineer <name> "<description>"`
+
+Example: `/create-engineer frontend-engineer "A frontend engineer specialized in React, Next.js, and CSS"`
+
+**Steps**
+
+1. **Parse input**
+
+   Extract `<name>` and `<description>` from the arguments after `/create-engineer`.
+   - Name should be kebab-case (e.g., `frontend-engineer`)
+   - Description is the quoted string explaining the agent's specialty
+   - If no input provided, use the AskUserQuestion tool to ask for both.
+
+2. **Search for relevant skills from skills.sh**
+
+   Based on the description and the project context (read ARCHITECTURE.md, DESIGN.md), search for relevant skills:
+
+   ```bash
+   npx skills search "<relevant keywords from description>"
+   ```
+
+   If the search doesn't work or returns nothing, browse https://www.skills.sh/ for relevant skills based on the agent's specialty.
+
+   Select 2-5 skills that are most relevant to the agent's role. Prefer official/popular skills.
+
+3. **Install selected skills**
+
+   For each selected skill:
+   ```bash
+   npx skills add <owner/repo>
+   ```
+
+   This installs the skill files into the project.
+
+4. **Create the agent file**
+
+   Create `.agents/agents/<name>.md` with this structure:
+
+   ```markdown
+   ---
+   description: <description>
+   mode: subagent
+   color: <pick a unique hex color>
+   temperature: 0.2
+   permission:
+     edit: allow
+     bash: allow
+     read: allow
+     glob: allow
+     grep: allow
+   ---
+
+   ## Abilities
+   - Guardrails: @ob-generic-guardrails
+   - Development: <@installed-skill-1>, <@installed-skill-2>, ...
+   - Testing: <@installed-skill-for-testing>, ...
+   - Infrastructure: <@installed-skill-for-devops-cicd>, ...
+
+   ## Workflow
+
+   When spawned by the lead:
+   1. Call `team_tasks_list` and verify your assigned task IDs and status before starting.
+   2. For each assigned task: before calling `team_claim task_id:<id>`, check `team_tasks_list` to confirm every dependency of that task has status `done`. If any dependency is not done, skip to the next assigned task that IS unblocked. Only claim tasks whose dependencies are fully complete.
+   3. Load `@ob-global` first, then load mandatory ability `Guardrails`.
+   4. Load additional abilities from the `## Abilities` section as needed for the claimed task domain (for example: development, testing, infrastructure). Each ability can include one or more skills; load all relevant skills listed under each selected ability.
+   5. Send a short `team_message` to lead confirming claimed task ID and loaded skills.
+   6. Implement the task following all loaded skill rules.
+   7. Call `team_tasks_complete task_id:<id>` after finishing that task.
+   8. Repeat until all currently assigned tasks are completed or blocked.
+   9. Message lead with results via `team_message`. Lead may assign more tasks, do NOT stop working or shut down until lead confirms no more tasks for you.
+   10. If lead sends new task IDs via `team_message`, treat them as new assignments and go back to step 2.
+   ```
+
+   Place the installed skills under the most relevant ability category:
+   - **Development** — language frameworks, UI libraries, application code skills
+   - **Testing** — test frameworks, linting, type checking, validation skills
+   - **Infrastructure** — DevOps, CI/CD, cloud, deployment, containerization skills
+
+   Distribute skills across ALL categories that apply. Only include categories that have at least one real skill assigned (besides Guardrails which is always present).
+
+5. **Update AGENTS.md**
+
+   Add the new agent to the agents table in AGENTS.md:
+   ```
+   | `<name>` | .agents/agents/<name>.md | <short role description> |
+   ```
+
+6. **Show summary**
+
+   Report:
+   - Agent file created at `.agents/agents/custom-engineer-<name>.md`
+   - Skills installed (list each with source)
+   - How to use: "This agent will be spawned by the lead during `/opsx-apply` for tasks matching its specialty."
+
+**Guidelines**
+- Always keep `@ob-generic-guardrails` in the Guardrails ability
+- NEVER use `@ob-default` in any ability category - all abilities must reference real installed skills
+- **Development** = language/framework/UI skills. **Testing** = test/lint/typecheck skills. **Infrastructure** = DevOps, CI/CD, cloud, deployment skills. Never put UI/CSS skills under Infrastructure.
+- Distribute installed skills across the appropriate categories — not just Development
+- Only include ability categories that have at least one real skill assigned
+- Pick a color that doesn't conflict with existing agents (basic-engineer uses #68A063)
+- Skills should match both the agent description AND the project's tech stack
+- If `npx skills` CLI is not available, manually reference skills by their `owner/repo` name in the abilities section and tell the user to install them

package/content/.opencode/commands/init.md

@@ -1,5 +1,5 @@
 ---
-description: Initialize the project — runs the bootstrap sequence defined in AGENTS.md if not yet initialized.
+description: Initialize the project, runs the bootstrap sequence defined in AGENTS.md if not yet initialized.
 ---
 
 Check if `AGENTS.md` is in bootstrap mode (contains `<!-- AGENTS-TEMPLATE-START -->`).

package/content/.opencode/commands/main.md

@@ -1,5 +1,5 @@
 ---
-description: Quick direct implementation — no OpenSpec, no ensemble, no PRs. Just do it.
+description: Quick direct implementation, no OpenSpec, no ensemble, no PRs. Just do it.
 ---
 
 Implement the task described after `/main` directly and immediately.

package/content/.opencode/commands/opsx-apply.md

@@ -86,79 +86,134 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
       DO NOT call team_claim yourself, only agents claim tasks.
       DO NOT proceed to 6d until team_tasks_add succeeds.
 
-   **Step 6d.** Discover available agents, assign tasks by best fit, then spawn workers.
-
-      Agent discovery and assignment rule:
-      - Read `.agents/agents/*.md` and use each agent's `description` and `## Abilities` to understand specialization.
-      - For each task ID, choose the best-fit agent based on task domain (backend, frontend, infra, testing, etc.).
-      - Prefer specialized agents when available; use `basic-engineer` as fallback only.
-      - Only spawn agents that have assigned task IDs.
-
-      REQUIRED assignment algorithm (do not skip):
-      1. Build candidate list from `.agents/agents/*.md` excluding `devops-manager`.
-      2. Classify each task by domain using task text (api/backend, ui/frontend, infra/devops, testing/qa).
-      3. For each task, score every candidate agent:
-         - +3 if agent description explicitly matches domain
-         - +2 if agent `## Abilities` include domain-relevant skills
-         - +1 if prior tasks of same domain already assigned to that agent (cohesion)
-      4. Assign task to highest-score agent.
-      5. Use `basic-engineer` ONLY when no specialized agent has positive score.
-      6. If all tasks go to `basic-engineer`, you MUST explain why no specialist matched.
-
-      HARD RULES:
-      - NEVER assign a task to `basic-engineer` if a specialized agent has higher score.
-      - NEVER skip agent discovery from `.agents/agents/*.md`.
-      - ALWAYS include assignment rationale in spawn prompt: "Selected because <domain match>".
-
-      Skill loading is worker-driven:
-      - The spawned agent MUST load `@ob-global` first.
-      - Then it MUST load skills from its own `## Abilities` for the claimed task domain.
-
-      Each team_spawn MUST include the agent field (required, causes NOT NULL error if omitted).
-
-      The spawn prompt must contain exactly:
-      1. Their name and role on this team
-      2. Which tasks are theirs, list the task IDs and content from the board
-      2.1 Why they were selected for those tasks (domain/abilities match)
-      3. Key context they need (summarized from context files, do NOT tell them to read files themselves)
-      4. The 6 OpenCode tools they have available (these are OpenCode tools, NOT shell commands, call them directly as tools, never via bash):
-         team_claim, team_tasks_complete, team_tasks_list, team_tasks_add, team_message, team_broadcast
-      5. How to proceed: call team_claim tool with the task_id to claim a task before starting it, call team_tasks_complete tool after finishing it, repeat until all their tasks are done, then call team_message tool to notify lead with results or blockers
-      6. Which skills to load: list the skill names and paths they MUST read before implementing. Example: "Before starting, read `.agents/skills/next-best-practices/SKILL.md` and follow its rules for all Next.js code."
-
-      Keep spawn prompts under 600 tokens. Do not describe team internals or how ensemble works.
-      Only spawn agents whose tasks are actually needed by this change. Skip agents with no tasks.
-
-      Spawn one or more best-fit workers (parallel when dependencies allow):
-      ```
-      team_spawn name:"eng-1" agent:"backend-engineer" prompt:"..."
-      team_spawn name:"eng-2" agent:"frontend-engineer" prompt:"..."
-      team_spawn name:"eng-3" agent:"basic-engineer" prompt:"..."
-      ```
-
-      Then immediately send each spawned worker a start message with exact task IDs:
-      ```
-      team_message to:"eng-1" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id1>] ... Claim each task ID before starting."
-      team_message to:"eng-2" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id2>] ... Claim each task ID before starting."
-      team_message to:"eng-3" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id3>] ... Claim each task ID before starting."
-      ```
+   **Step 6d.** Discover available agents, assign an INITIAL BATCH of tasks, then spawn workers.
+
+       **CONCURRENCY LIMIT: Maximum {{MAX_CONCURRENT_AGENTS}} truly concurrent agents at a time.**
+       All agents in a wave MUST be spawned and running simultaneously, not one-at-a-time sequentially.
+
+       **ROLLING BATCH MODEL:**
+       Agents do NOT receive all their tasks upfront. Instead:
+       - Assign each agent an initial batch of up to 3 tasks (respecting dependencies).
+       - When an agent completes its batch and messages back, the lead assigns the next batch of up to 3 unassigned tasks from the board that match the agent's domain.
+       - Repeat until no pending tasks remain on the board.
+       - Only shut down an agent when the board has no more tasks for its domain.
+
+       This prevents agents from idling after one task, avoids overloading spawn prompts, and lets the lead adapt assignments based on progress.
+
+       **FILE DOMAIN SEPARATION (mandatory):**
+       Each agent MUST own a non-overlapping set of files/directories. Examples:
+       - Agent A owns `src/backend/Application/Commands/`, Agent B owns `src/backend/Application/Queries/`
+       - Agent A owns `src/frontend/app/(auth)/events/`, Agent B owns `src/frontend/app/(auth)/admin/`
+       Never assign two agents tasks that touch the same file or controller.
+
+       Agent discovery and assignment rule:
+       - Read `.agents/agents/*.md` and use each agent's `description` and `## Abilities` to understand specialization.
+       - For each task ID, choose the best-fit agent based on task domain (backend, frontend, infra, testing, etc.).
+       - Prefer specialized agents when available; use `basic-engineer` as fallback only.
+       - Only spawn agents that have assigned task IDs.
+
+       REQUIRED assignment algorithm (do not skip):
+       1. Build candidate list from `.agents/agents/*.md` excluding `devops-manager`.
+       2. Classify each task by domain using task text (api/backend, ui/frontend, infra/devops, testing/qa).
+       3. For each task, score every candidate agent:
+          - +3 if agent description explicitly matches domain
+          - +2 if agent `## Abilities` include domain-relevant skills
+          - +1 if prior tasks of same domain already assigned to that agent (cohesion)
+       4. Assign task to highest-score agent.
+       5. Use `basic-engineer` ONLY when no specialized agent has positive score.
+       6. If all tasks go to `basic-engineer`, you MUST explain why no specialist matched.
+
+       HARD RULES:
+       - NEVER assign a task to `basic-engineer` if a specialized agent has higher score.
+       - NEVER skip agent discovery from `.agents/agents/*.md`.
+       - ALWAYS include assignment rationale in spawn prompt: "Selected because <domain match>".
+
+       Skill loading is worker-driven:
+       - The spawned agent MUST load `@ob-global` first.
+       - Then it MUST load skills from its own `## Abilities` for the claimed task domain.
+
+       Each team_spawn MUST include the agent field (required, causes NOT NULL error if omitted).
+
+       **Spawn prompt format (strict, max 400 tokens):**
+
+       ```
+       You are {name}, {role}. Your file domain: {list of directories you own exclusively}.
+
+       Initial tasks (claim each with team_claim before starting, team_tasks_complete after commit):
+       - {task_id_1}: {one-line description}
+       - {task_id_2}: {one-line description}
+       - {task_id_3}: {one-line description}
+
+       Context: {2-3 sentences of essential context from the specs, NOT full file contents}
+
+       Build command: {e.g., "dotnet build TechEvents.slnx" or "pnpm build"}
+       After each task: git add -A && git commit -m "feat: <description>"
+
+       IMPORTANT: After completing all tasks above, message lead with results.
+       Lead may assign you more tasks. Do NOT shut down until lead confirms no more tasks.
+       Start with team_claim on your first task NOW. Do not read files or plan first.
+       ```
+
+       DO NOT include:
+       - Full file contents or code snippets in the prompt
+       - Descriptions of how ensemble works
+       - Lists of available tools (the agent already knows from its agent.md)
+       - Instructions to "message lead when planning", agents should only message when DONE or BLOCKED
+
+       Spawn workers:
+       ```
+       team_spawn name:"eng-1" agent:"backend-engineer" prompt:"..."
+       team_spawn name:"eng-2" agent:"frontend-engineer" prompt:"..."
+       ```
+
+       Then immediately send each spawned worker a start message:
+       ```
+       team_message to:"eng-1" text:"Start now. First action: team_claim {first_task_id}. Go."
+       team_message to:"eng-2" text:"Start now. First action: team_claim {first_task_id}. Go."
+       ```
 
    **Step 6e.** After sending start messages, tell the user what is running, then STOP and wait.
-      Do NOT call team_results, team_status, or team_broadcast in a loop.
-      Teammates will message you when done or blocked. Wait for those messages.
-
-   **Step 6f.** When a teammate messages back, you receive a ping only, the full content is NOT in the notification.
-      Call team_results to read the full message and mark it read. Then for each teammate: team_shutdown → team_merge.
-      If team_merge blocks ("overlapping local changes"), commit or stash your local changes first, then retry.
-      Fix any other blockers reported.
+       Do NOT call team_results, team_status, or team_broadcast in a loop.
+       Teammates will message you when done or blocked. Wait for those messages.
+
+       Tell the user: "Agents spawned. Check dashboard at http://localhost:4747/. I'll report when they finish."
+
+   **Step 6f.** When a teammate messages back (rolling re-assignment loop):
+       1. Call `team_results from:"<name>"` to read full message.
+       2. Call `team_tasks_list` to check remaining pending/unassigned tasks on the board.
+       3. **If there are more unassigned tasks matching this agent's domain:**
+          - Pick up to 3 unassigned, unblocked tasks for this agent's domain.
+          - Send them via `team_message to:"<name>" text:"Next tasks: [task-<id1>] <desc>, [task-<id2>] <desc>, [task-<id3>] <desc>. Claim each with team_claim before starting."`
+          - Do NOT shut down the agent. Go back to waiting (step 6e).
+       4. **If no more tasks for this agent:**
+          - `team_shutdown member:"<name>"`
+          - `team_merge member:"<name>"`
+          - If team_merge blocks on local changes: `git stash`, retry merge, `git stash pop`
+       5. **If ALL agents are shut down and tasks remain unassigned** (new domain, dependencies unblocked):
+          - Spawn new agents for the remaining tasks (back to step 6d).
+       6. **If ALL tasks are done:** proceed to step 7.
+
+       **IMMEDIATE SHUTDOWN RULE:** Never leave a finished agent running when there are no more tasks for it. But DO keep agents alive if more tasks in their domain are pending.
+
+       **ZERO PENDING TASKS GUARANTEE:** Before proceeding to step 7, call `team_tasks_list` and verify EVERY task is either `done` or `blocked`. If any task is `pending` and unassigned, assign it to an agent or spawn a new one. Never leave pending tasks orphaned.
+
+   **Step 6g. Stall detection (if agent has no commits after 5 minutes):**
+      1. `team_message to:"<name>" text:"Status? If stuck, report blocker. If not started, run team_claim {task_id} now."`
+      2. Wait 2 more minutes
+      3. If still no response: `team_shutdown member:"<name>" force:true`
+      4. Respawn with same tasks, fresh prompt
+      5. Log stall in session-log for post-mortem
 
 7. **Verification check**
 
-   Run verification tasks (tests/build/lint) using a worker suited for verification scope:
-   - either same engineer workers
-   - or a dedicated verifier worker if your project defines one
-
-   Wait for results → fix blockers.
+   After ALL agents are merged, run verification on the lead branch directly:
+   ```bash
+   # Backend
+   dotnet build <solution>
+   # Frontend
+   pnpm build
+   ```
+   Fix any errors yourself (small fixes only). If large fixes needed, spawn one more agent.
 
 8. **Mark tasks complete in openspec**
 
@@ -183,12 +238,18 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
 - NEVER call team_spawn before team_tasks_add, tasks must exist before agents are spawned
 - NEVER poll team_results or team_status in a loop, wait for teammates to message you
 - NEVER call team_claim or team_tasks_complete as lead, only agents call these tools
-- ALWAYS pass the task IDs returned by team_tasks_add to each agent's spawn prompt
 - NEVER edit files between team_spawn and team_merge, team_merge blocks on overlapping local changes
+- NEVER leave pending tasks orphaned, always verify board is empty before proceeding to step 7
 - ALWAYS add every task to the board with team_tasks_add before spawning
+- ALWAYS assign initial batch of up to 3 tasks per agent in spawn prompt
+- ALWAYS re-assign next batch (up to 3) via team_message when agent reports done, if more tasks exist for its domain
+- ALWAYS call team_tasks_list after each agent reports done to check for remaining unassigned tasks
 - ALWAYS spawn workers based on dependencies: parallel when safe, sequential when required
 - ALWAYS instruct agents to call team_claim before each task and team_tasks_complete after
-- If teammates are stuck, use team_message to resend tasks, then wait, never implement directly
+- ALWAYS enforce max {{MAX_CONCURRENT_AGENTS}} truly concurrent agents (all running simultaneously, not sequentially)
+- ALWAYS enforce non-overlapping file domains per agent
+- ALWAYS shut down + merge agents only when no more tasks remain for their domain
+- If teammates are stuck, use team_message to nudge, then stall detection (step 6g)
 - Mark tasks complete in openspec AFTER worker implementation and verification finish, not before
 - Pause on errors, blockers, or unclear requirements. Do not guess
 - Use contextFiles from CLI output, do not assume specific file paths

package/content/.opencode/commands/plan.md

@@ -1,5 +1,5 @@
 ---
-description: Parse a user story URL and produce a plan — proposal, specs, and tasks. Stops before implementation.
+description: Parse a user story URL and produce a plan, proposal, specs, and tasks. Stops before implementation.
 ---
 
 Parse the work item at the URL provided after `/plan` and produce a full implementation plan.