opencode-native-team

A multi-agent development team built on pure opencode primitives.

6 markdown files. Zero dependencies. Zero vendor lock-in.

plan → code → test → review → commit

Why

AI coding agents are powerful but unpredictable when requirements live only in chat history. This team adds structure: agree on specs before code, write tests before implementation, review before merge — enforced through role contracts and tool permissions, not framework code.

Won an internal multi-agent bake-off (n=1) against two orchestration frameworks on token economy, zero operator interventions, and deterministic judge score. The current test battery is python3 scripts/validate.py (multiple subprocesses, ~200 checks); see examples/RUN-BRIEF.md for the run-brief template. Full run data available on request.

Quick Start

git clone https://github.com/dsaveliev/opencode-native-team.git
cd opencode-native-team

# Install into your project (agents + /team command + skills + example config)
./install.sh /path/to/your/project

# Or install globally — the team becomes available in every project
./install.sh --global

Prerequisites

• opencode ≥ 1.18
• OpenSpec CLI ≥ 1.14 (npm install -g @fission-ai/openspec)
• python3 (installer config merge + scripts/validate.py)
• An opencode.json with model routing (see examples/opencode.json.example)

Usage

Three ways to run the team (pick one):

1. /team command (recommended) — open opencode in your project and type:

/team add a rate-limited events endpoint to the API

The command runs the orchestrator with your text as the assignment. If a TASK.md exists in the repo root, it takes precedence.

2. CLI one-liner — for scripts and experiments:

opencode run --agent orchestrator 'Read TASK.md and complete the assignment.'

3. TASK.md flow — write the assignment into TASK.md, then use either of the two methods above. The contract / deliverables / process requirements for an example assignment live alongside the change.

The team then runs autonomously: openspec change → planner → coder → tester → reviewer → commit, with a DECISIONS.md entry for every ambiguity it resolved.

Existing openspec project (per-feature workflow)

If your repository already uses OpenSpec, run the team per feature on an already-written change:

/team-change add-user-ratelimit

The orchestrator validates the change, works on branch feat/<change-id> (never main), and implements the existing proposal/design/tasks as-is — corrections are limited to [x]-proofs and observability comments. Merge/PR stays yours.

Adapt the installed config to the project:

• Reviewer/test commands. Extend the reviewer's bash map with the project's verification commands (golangci-lint run, make test, docker compose ...). Keep the map a superset of the contract's frontmatter rules — trimming silently strips protections (see the complete-map rule above).
• Test targets. The tester has a 5-minute budget per task; on a medium backend go test ./... may not fit. Put package-scoped commands into tasks (go test -race ./internal/billing/...) — faster and sharper for coder briefs.
• Budget. From measured runs: ~40–60 min and 1–2M input tokens per feature. First run — pick a low-risk feature and audit DECISIONS.md afterwards: it lists every point where the spec was ambiguous.

Run briefs (long-running runs)

For unattended, long-running runs, drop a RUN-BRIEF.md into the project root (template: examples/RUN-BRIEF.md). Both /team and /team-change detect it before starting and treat it as a read-only execution-policy overlay: scope fences, reading and retry budgets, gates, recovery policy, and the morning handoff.

The brief governs HOW the run proceeds — it may narrow execution, but never grants capabilities, never redefines acceptance criteria, and is never edited mid-run. TASK.md and OpenSpec artifacts keep owning WHAT. No brief — no behavior change. A minimal brief is ~15 lines (envelope, mission reference, decision authority, scope map, termination). Roadmap: recovery semantics (dispositions, dependency propagation) and observability (RUN-SUMMARY) arrive as follow-up changes.

Briefed runs also end with RUN-SUMMARY.md (terminal state, evidence table, branch logs, one human action per blocker) and keep dispositions in BLOCKERS.md; scripts/setup-sandbox.sh <dir> builds a disposable proving ground for drills — see docs/recovery-experiment.md §3. Generate a brief without typing canonical text: python3 scripts/gen-run-brief.py or /team-brief (questions in, verbatim blocks out).

Team

Discipline Layers

Process (OpenSpec)     → "in what order we agree"
Discipline (skills)    → "how to do each type of work"
Team (these agents)    → "who does what"

The orchestrator contract embeds a skill mapping table (which skill at which OpenSpec stage) — deterministic dispatch, no ad-hoc selection.

Security Model

⚠️ Separator patterns are mitigation, not a security boundary. The real boundary is: edit: deny for read-only roles, exact allow-patterns for test commands (no trailing *), and task: deny for all subagents. Coder/tester hold broad bash and are trusted accordingly.

Language Profiles

Contracts are language-agnostic. Language-specific commands (test, vet, build) live in your project's opencode.json:

{
  "agent": {
    "reviewer": {
      "permission": {
        "bash": {
          "go test ./...": "allow",
          "go vet ./...": "allow"
        }
      }
    }
  }
}

An opencode.json.example with Go presets is installed by install.sh.

Complete-map rule (probed): if you override permission.bash for an agent in opencode.json, provide the complete map including its own "*": "deny" catch-all and repeat every allow the agent needs. A partial map is merged behind the contract's frontmatter denies — its allows get defeated (this exact bug shipped once: the reviewer's go test allow was silently overridden until a live run caught it).

Autonomous (headless) runs work out of the box: the example config ships top-level bash/edit allows. They do not weaken subagent contracts — agent frontmatter denies take precedence over top-level allows (probed). Remove them if you prefer interactive ask gating; trim the reviewer map only down to the contract's own rules — validate.py enforces the superset.

Live Dashboard

Every run can carry a live dashboard: agents spawned, task progress, work log, commit timeline, token usage, ETA — served over localhost from the session DB + git + openspec tasks, zero dependencies.

• Served at http://127.0.0.1:<port>/ (fixed port, default 4731; binds 127.0.0.1 only). The page polls /state and repaints itself on data change — no manual reload; if the server dies, the page shows a stopped banner instead of quietly going stale. POST is reserved for the control plane (/control/stop and /control/switch); see docs/dashboard-control-support.md for the supported/unavailable control matrix.
• Observation windows adopt in-flight runs: start monitoring at any moment and the window rolls back to the run's earliest still-active session — the "empty dashboard started too late" failure mode cannot happen.
• Config resolves per key: project .opencode/team-dashboard.json over installation ~/.config/opencode/team-dashboard.json (see examples/team-dashboard.json): mode = ask (default — the team asks once per run via the question tool; headless runs skip silently) | always (starts every run, including --auto) | never, plus refresh seconds, open_browser, port, coverage_ttl, inspect_ttl.
• Launch channels: /team and /team-change start/stop the dashboard automatically per mode (script resolved project-local first, then the global copy). Out-of-band: team-dash (installed onto PATH by install.sh) never asks questions and never touches the session itself, so it is safe mid-run: with a directory argument it points the dashboard there, without arguments it opens the freshest active run. One dashboard per machine on the fixed port — switching projects happens in the dashboard UI (View buttons in the Sessions & instances panel); if a run's pre-flight finds the dashboard already serving another project, it is re-pointed, not conflicted. A port held by a non-dashboard process still fails loudly naming the holder. Manual: .opencode/scripts/team-dashboard.sh serve|stop|once|status <dir>.
• Port already occupied = hard error naming the holding PID (set port per project to run two dashboards side by side). After stop the final HTML stays at tmp/team-dashboard.html. Concurrent serve calls on the same port serialize through a per-port lock; one binds the socket, the rest see the running server and re-point via switch_to.
• Panels: cards (tasks/commits/spawns/errors tiles link to their panels), run-stage stepper, activity swimlanes (lanes ordered by first activity), agents table with spawn counts, collapsible task tree, work log and commit list (click to expand, hover the chart for popups), tool-errors panel beside the work log (tool, agent, time, failing input excerpt). Optional test-coverage card is opt-in via coverage_ttl (seconds; 0/off by default — the tick must not race the tester agent). Observer reads never run project tests; coverage is the explicit --export exception.
• Sessions & instances panel: every running opencode process (pid, project from cwd, CPU time, command) with its recent sessions, a View button per project (re-points the dashboard's observation to it — one dashboard, same port, last switch wins across tabs) and a Stop control per process.
• Operator controls panel: the supported control (process stop, SIGTERM) is marked enforced (h.2.1 grant). Session pause, session cancel, and human takeover are explicitly labelled unavailable with the reason (no runtime API in opencode, or — for takeover — pending a revoke-before-human-write / reconciliation-before-resume implementation in a separate change). The UI never claims a control the runtime cannot enforce.
• Control requests are hardened: localhost Host only, an explicit browser Origin policy (foreign origins are refused before the body is read), JSON content-type required (HTML forms cannot trigger it), and the request body is bounded (64 KiB max) with a 5-second read timeout, strict integer PID, and a JSON-object body. The stop signal is delivered only after the target's resolved executable is verified to live under a trusted install prefix AND match the opencode binary name AND the bound run manifest's start_ms minus a small slack (no recycled PIDs from a previous run) AND the optional target_grant matches the bound manifest's stop_grant field. A renamed or symlinked binary (/bin/sleep as opencode) is refused. A copy of an authentic binary run from /tmp is also refused. The confirmation names the blast radius (all sessions of that process end); there is no automatic SIGKILL escalation.
• The server is a machine-wide singleton tracked by one owner record (~/.local/state/opencode-team/team-dashboard-<port>.json), written atomically (temp + rename) under a per-port flock, so switching A → B → A and stop from any directory work. Operation-specific cleanup: a failing operation only removes the OWNER record it created; a foreign OWNER on a different port is preserved.
• Observation itself stays read-only; the only writer is the one-shot adopt_window state file (a bounded roll-back when a fresh server meets an in-flight run). Model-authored text is escaped for script context (< → \u003c) so it can never break out of the page.
• Read-only inspect (opt-in via inspect_ttl > 0) shows the opencode session list --format json output. It is display-only and never flows into the control plane; it never authorizes a control. Default: off. Effect preview: a table of recent sessions with id, title, updated-ago, and directory.
• Run stage is derived from task progress (plan → code → review → done) and never jumps backward when a new wave starts; the instantaneous activity rides along as a "now: , wave N" label next to the stepper.
• Task timing: completed top-level tasks show their duration; once one has finished, remaining top-level tasks and the run ETA show a ~ projection (median of completed durations — an estimate, clearly marked). The task currently being worked on is highlighted and shows live elapsed.
• Interaction survives refreshes: expanded rows (log, commits, tasks) are remembered per row and re-opened after each automatic repaint; work-log history older than the newest 40 entries is kept in the browser's localStorage (per project + run window, cap 500) so a page reload does not lose it. No dashboard data is ever written into the observed project.

Run Logs and Retro

Every run starts with a durable identity: the pre-flight runs scripts/run-manifest.py init (writes RUN-MANIFEST.json with run_id, git state, mission-source hashes, versions, budgets), and the first delegation runs attach to bind the root and child sessions. The run id is what every artifact and the dashboard label itself with.

Every run ends with a markdown run log exported by the same data path as the dashboard (scripts/gen-team-dashboard.py --export <dir>), so the log and the page can never disagree:

• /team-change writes openspec/changes/<change>/RUN-LOG.md next to its manifest; /team writes tmp/run-logs/<run_id>/RUN-LOG.md (gitignored, run-scoped — same-day runs never collide).
• Contents: run id and window source (declared / adopted / heuristic), run window, per-wave session table with durations, task timings, tool errors, permission denials (command + agent), commits, token totals.
• The orchestrator then appends a ## Recommendations section: friction observed during the run (slow tasks, retries, denials) translated into concrete improvement suggestions for this framework — the feedback loop that tunes prompts, permissions, and wave sizing.

Permissions (toolchain access)

Team agents deny every external directory except the language toolchain surface (Go module/build caches and ~/go/bin, npm, cargo, rustup, pip caches) — go mod tidy, go get, npm install, cargo fetch work inside subagents while foreign project directories stay denied. The orchestrator carries an explicit bash ruleset: allow by default, deny destructive/remote git (push, reset, revert, rebase, stash, am, cherry-pick, checkout --, clean) — so its wave commits run headless under --auto. examples/opencode.json.example mirrors the same allowlist for project-mode installs. For your own (non-team) sessions on this machine, extend ~/.config/opencode/opencode.json: add module managers (go mod*, go get*, npm install*, npm ci*, pip install -r*) to the bash allowlist and the same cache entries to external_directory — then restart opencode.

Stack Skills (per-project extensions)

Add technology-specific skills (golang, sql, k8s…) without touching contracts:

1. Declare them in <project>/.opencode/team-skills.json (see examples/team-skills.json) — each entry names a skill, a source path (local pool) and the OpenSpec stages where it joins the dispatch table.
2. Sync: scripts/sync-skills.sh <project> installs the skills into .opencode/skills/ and pins every file in skills.lock (sha256 — same integrity model as the vendor MANIFEST). Re-run verifies; --update re-copies from sources.
3. The orchestrator picks them up automatically at the declared stages.

Vendored Skills

10 skills (12 files) from agent-skills are vendored; every file — including references/*.md — is pinned with a SHA-256 in vendor/MANIFEST.yaml. install.sh verifies full-length hashes and rejects missing or unlisted files before copying.

Execution plugins (context-mode + Ponytail)

install.sh (project mode) recommends two external OpenCode plugins — context-mode (context/data plane: sandboxed analysis, FTS5 retrieval, session continuity) and Ponytail (implementation discipline: YAGNI, minimal diffs) — by adding them idempotently to the project's opencode.json plugin array. Nothing is vendored; role permissions are untouched by the merge and the agent contracts deny the ctx_* tools a read-only role must not reach (see the permission matrix in docs/integrations.md). Opt out with NATIVE_TEAM_PLUGINS=none ./install.sh ....

Documentation

• SPEC.md — project specification
• docs/design-decisions.md — 13 design decisions
• docs/integrations.md — execution plugins: architecture, permission matrix, precedence
• docs/v4-to-v5.md — evolution and rationale
• docs/timing-analysis.md — time decomposition

Launcher (team-dash)

team-dash (installed onto PATH by install.sh) opens the live dashboard for a project. It is safe mid-run: never asks questions, never touches running sessions.

Resolution rule: team-dash resolves scripts/team-dashboard.sh from the repository that contains the current (or argument-provided) directory via git rev-parse --show-toplevel. The launcher fails loudly with a one-line error if the directory is not inside a git repo, or the script is not in the repo's scripts/. The launcher deliberately does NOT look at ~/.config/opencode/scripts/ — global script copies are a historical artefact of an earlier design and are ignored.

This change (since dashboard-launcher-reliability): install.sh no longer copies the runtime scripts to ~/.config/opencode/scripts/. The launcher is self-evidencing — every script is wherever the repo says it is, and any git mv is immediately effective. Pre-existing files in ~/.config/opencode/scripts/ from a prior install are ignored; to clean them up:

rm -rf ~/.config/opencode/scripts/{,_}*.py \
       ~/.config/opencode/scripts/team-dashboard.sh

Examples:

# inside a project repo, or with a directory argument
team-dash .
team-dash /path/to/project
team-dash          # picks the freshest recently-active run

License

MIT