Workshop

This workspace is a multi-agent development environment powered by opencode. Work is driven by the project-orchestrator agent, which delegates to four specialised subagents in a structured loop.

This is not intended to be replicated 1:1 for your development environment, but may provide an interesting approach which you may want to replicate. It should be noted that this setup uses local LLMs, which are approved for use with private code - while OpenRouter models are only (currently) approved for use in public projects.

Agent loop

clarify → planner → executor → reviewer ──PASS──→ author → done
                       ▲            │
                       └──REVISE────┘
              ▲                      │
              └────────BLOCK─────────┘

Agent	Role	Outputs
`project-orchestrator`	Default primary agent. Clarifies tasks and drives the loop.	Delegates; summarises results.
`planner`	Turns a task into a structured change plan. No code.	Plan doc with `[ ]` checkboxes.
`executor`	Implements the plan exactly and runs tests.	Implementation Summary + Acceptance Criteria Check.
`reviewer`	Critically audits code, security, tests, and UV conventions.	`PASS` / `REVISE` / `BLOCK` verdict.
`author`	Verifies requirements coverage and updates documentation.	Requirements Coverage table + doc edits.

Routing rules

PASS → proceed to author
REVISE → return reviewer's Required Changes to executor; re-review
BLOCK → return reviewer's findings to planner; replan from scratch
UNMET (from author) → return to planner
REVISE × 3 on the same issue → escalate to the user

Conventions

Python only

All application logic must be Python. Shell scripts and other languages are not permitted within project source.

UV for all Python operations

Every dependency, environment, and execution operation goes through UV. Never use pip, python/python3 directly, venv, virtualenv, or hand-edited requirements.txt.

Operation	Command
Run code or a script	`uv run python <script>`
Run tests	`uv run pytest`
Add a runtime dependency	`uv add <pkg>`
Add a dev/test dependency	`uv add --dev <pkg>`
Remove a dependency	`uv remove <pkg>`
Sync environment to lockfile	`uv sync`

Dependencies are declared in pyproject.toml and pinned in uv.lock. Both files are committed.

Subagent handoffs

Each subagent is stateless — every delegation must include the full context (task, prior-agent output, relevant file contents). Agents share no implicit memory.

Configuration

Agent definitions live in .opencode/agents/. The opencode runtime configuration (models, providers, default agent) is in .opencode/opencode.json.

SecondSkoll/workshop-framework

README