Design and generate a project-specific OpenCode agent team with specialized agents, tools, plugins, commands, and skills tailored to the project type and stack. Use after the base scaffold exists to customize the generic agent templates into project-aware specialists.
Use this skill to design the agent team for the project. This is creative work — you analyze the project and customize the agents, tools, and plugins to match.
scaffold-kickoff after a fresh scaffold render, use the design path for a new project-specific team..opencode/ operating layer, use the retrofit path.The repo-scaffold-factory script generates a base set of generic agent templates. project-skill-bootstrap then creates the repo-local skill pack those agents are allowed to use. In retrofit mode, this skill restores .opencode/ first so project-skill-bootstrap has a concrete local skill layer to rewrite. Your job is to read the canonical brief, use the already-generated local skills when they exist, and customize the agents to be project-specific.
Read docs/spec/CANONICAL-BRIEF.md to understand:
Decide which agents this project needs. Start from the baseline and add/modify based on project type.
Baseline agents (always present):
team-leader — the single visible coordinator, delegates to specialistslane-executor — hidden write-capable worker for lease-bound parallel workplanner — turns tickets into implementation plansplan-review — approves/rejects plans before implementationimplementer — implements the approved plan (at least one, may have multiple)reviewer-code — code review for correctness and regressionsreviewer-security — security review for trust boundaries and secretstester-qa — QA validation and closeout readinessdocs-handoff — closeout artifact synchronizationbacklog-verifier — re-checks completed tickets after a workflow or process upgradeticket-creator — creates guarded follow-up tickets only from verifier proofProject-specific agents (add based on project type):
For UI/frontend projects:
implementer-ui)For API projects:
For MCP server projects:
For database-heavy projects:
For CLI/library projects:
You may create multiple implementer-type agents for different domains within a single project, but keep the total agent count conservative unless the canonical brief proves genuinely disjoint domains.
Default to one visible team leader with a shallow hidden specialist topology. Keep lane-executor as the default hidden worker for bounded parallel implementation. Only introduce a manager or section-leader hierarchy when the canonical brief shows strong non-overlapping domains that justify the extra coordination layer. Treat that hierarchy as advanced project-specific customization, not as a first-class scaffold profile.
Utility agents (include based on need):
utility-explore — repo evidence gatheringutility-github-research — GitHub-focused researchutility-shell-inspect — read-only shell commandsutility-summarize — evidence compressionutility-ticket-audit — ticket/state consistencyutility-web-research — external technical researchOmit utility agents that aren't useful for the project.
For EVERY agent, rewrite the generic prompt to be project-specific:
What to customize:
cargo test* for Rust, flutter test* for Flutter)Inject stack-specific implementation notes:
Stack-specific notes block so it no longer contains scaffold placeholder text.docs/spec/CANONICAL-BRIEF.md, the actual repo layout, and the selected stack rather than pasting generic catalog text.docs/AGENT-DELEGATION.md aligned with the detected stack adapters and their canonical verification commands.What NOT to change:
__PLANNER_MODEL__, etc. are already substituted by the script)planning -> plan_review -> implementation -> review -> qa -> smoke-test -> closeout)Example customization for a React web app:
The generic planner says: "You produce decision-complete plans for a single ticket."
Customize to: "You produce decision-complete plans for a single ticket in the Example App React frontend. Plans must specify which components are affected, what state management changes are needed, and what test scenarios to cover. Reference the component tree in docs/spec/CANONICAL-BRIEF.md."
Write each agent to .opencode/agents/<prefix>-<role>.md with proper YAML frontmatter.
Verify:
description, model, mode, hidden, temperature, top_p.opencode/skills/.opencode/agents/write: false, edit: falsewrite: true, edit: trueticket_lookup.transition_guidance before changing lifecycle stateenvironment_bootstrap before normal lifecycle workAlso generate docs/AGENT-DELEGATION.md as a derived project-specific document.
It must document:
START-HERE.md, run ticket_lookup, identify the active ticket, then resume from canonical stateTreat docs/AGENT-DELEGATION.md as derived from the actual agent set you created in .opencode/agents/, not as a generic boilerplate file.
The base scaffold generates these standard tools (keep them all):
artifact_write.ts — write canonical artifactsartifact_register.ts — register artifact metadatacontext_snapshot.ts — generate context snapshotsenvironment_bootstrap.ts — install and verify project/toolchain/test prerequisiteshandoff_publish.ts — publish START-HERE handoffissue_intake.ts — route post-completion defects through reopen or follow-up flowskill_ping.ts — record skill invocationsticket_claim.ts — claim a lease for lane-bound write workticket_create.ts — guarded follow-up or remediation ticket creationticket_lookup.ts — resolve tickets from manifestticket_release.ts — release a lease after write work completesticket_reopen.ts — reopen a ticket when original accepted scope is no longer trueticket_reverify.ts — restore trust on historical completion after new evidenceticket_update.ts — update ticket state with stage gates.opencode/lib/workflow.ts — shared types and utilitiesConsider whether the project needs additional tools:
If additional tools are warranted, create them following the patterns in .opencode/lib/workflow.ts.
The base scaffold generates these standard plugins (keep them all):
invocation-tracker.ts — audit loggingsession-compactor.ts — context preservation on compactionstage-gate-enforcer.ts — blocks unsafe operations before plan approvalticket-sync.ts — records ticket state changestool-guard.ts — blocks dangerous operationsThese are generic and work for any project. Only add project-specific plugins if genuinely needed.
The base scaffold generates:
kickoff.md — start the autonomous planning cycleresume.md — resume from the latest statebootstrap-check.md — verify environment bootstrap readinessissue-triage.md — route defects found after prior completionreverify-ticket.md — restore trust on historical completionplan-wave.md — choose safe parallel candidates for the next waverun-lane.md — run one bounded lane through lease-based executionjoin-lanes.md — reconcile completed parallel lanes into one foreground pathCustomize these to reference project-specific agents and skills. If the generated repo includes stack-specific bootstrap or verification entrypoints, make those references match the detected adapter family instead of a generic default.
Before leaving this skill, confirm all of these are true:
.opencode/agents/ contains only the intended project-specific agent set for this repodocs/AGENT-DELEGATION.md matches the actual generated agent set and restart flow for this repoWhen this skill runs as a scafforge-repair follow-on regeneration pass, read .opencode/meta/repair-follow-on-state.json and, after the agent team, commands, and related prompt surfaces are actually refreshed for the current repair cycle, write:
.opencode/state/artifacts/history/repair/opencode-team-bootstrap-completion.mdUse this minimal shape so the public repair runner can auto-recognize opencode-team-bootstrap completion for the current repair cycle on the next run:
# Repair Follow-On Completion
- completed_stage: opencode-team-bootstrap
- cycle_id: <cycle_id from .opencode/meta/repair-follow-on-state.json>
- completed_by: opencode-team-bootstrap
## Summary
- Regenerated the project-specific OpenCode agent team and related command/tool routing for the current repair cycle.
Do not emit this artifact speculatively. Only write it once the agent-team regeneration work is actually complete for the current repair cycle.
lane-executor as the default bounded parallel write workerask permissions — agents don't prompt the userpermission.task allowlists — agents can only delegate to named agents/kickoff, /resume, or other .opencode/commands/ files as internal workflow workaroundsContinue to ../agent-prompt-engineering/SKILL.md as directed by ../scaffold-kickoff/SKILL.md.
references/agent-system.md for the team structurereferences/tools-plugins-mcp.md for the tool/plugin/command layer../repo-scaffold-factory/assets/project-template/ for the base templates../agent-prompt-engineering/SKILL.md for prompt hardening rules