OpenCode Dev Studio Plugin — Planner-Driven Agent Team Generator

An OpenCode plugin that ships a planner agent which analyzes your existing project using built-in agents (explore, general), then designs and scaffolds a tailored 3-tier agent team — the planner builds the builders.

1. Core Flow: Planner-First Architecture

The plugin ships one agent (studio) and custom tools. The studio agent is an intelligent planner that:

1. Scans — uses explore subagent to analyze the codebase (deps, file structure, imports, patterns)
2. Reasons — maps findings to known tech stacks from its knowledge base
3. Proposes — presents you with a team design: "I found Next.js + Convex + BAML. Here's the team I'd create..."
4. Confirms — you approve, modify, or add stacks
5. Scaffolds — uses custom tools to generate the full .opencode/ directory
6. Self-replaces — after generation, the studio agent is no longer needed; the new team takes over

YOU: "Set up agents for this project"
         │
         ▼
  ┌──────────────┐    ┌─────────┐
  │ studio agent │───▶│ explore │──▶ scans codebase
  │  (planner)   │    └─────────┘   package.json, imports,
  │              │                   file structure, configs
  │              │    ┌─────────┐
  │              │───▶│ general │──▶ researches unknowns
  │              │    └─────────┘   (optional)
  │              │
  │  "I found Next.js 15, Convex, BAML, Tailwind."
  │  "Proposing 4 departments, 12 specialists."
  │  "Want me to proceed?"
  │              │
  │     YOU: "yes, also add ADK"
  │              │
  │              │───▶ studio_scaffold tool
  │              │     generates .opencode/*
  └──────────────┘
         │
         ▼
  .opencode/
  ├── agents/      ← architect, build, review + dept leads + specialists
  ├── prompts/     ← tailored to YOUR project's actual patterns
  ├── commands/    ← /design, /implement, /review, /standup
  ├── plugins/     ← decision-journal, standards-guard
  └── opencode.json

Key insight: The planner doesn't just match stack names — it reads your actual code to understand patterns, conventions, and project structure, then bakes that context into the generated prompts.

2. Project Structure

Repo: D:\Projects\opencode-dev-studio

opencode-dev-studio/
├── package.json                 ← npm-publishable
├── tsconfig.json
├── README.md
│
├── src/
│   ├── index.ts                 ← Plugin entry: registers studio agent + tools
│   │
│   ├── tools/                   ← Custom tools the studio agent calls
│   │   ├── scaffold.ts          ← studio_scaffold: generates full .opencode/
│   │   ├── add-department.ts    ← studio_add_dept: adds one dept to existing
│   │   ├── refresh.ts           ← studio_refresh: re-generates prompts for a dept
│   │   └── list-stacks.ts       ← studio_list_stacks: shows available stacks
│   │
│   ├── generators/              ← Pure functions that produce file contents
│   │   ├── config.ts            ← opencode.json agent/command/permission entries
│   │   ├── agents.ts            ← .opencode/agents/*.md files
│   │   ├── prompts.ts           ← .opencode/prompts/*.txt files
│   │   ├── commands.ts          ← .opencode/commands/*.md files
│   │   └── plugins.ts           ← .opencode/plugins/*.ts files
│   │
│   ├── templates/               ← Template functions per artifact type
│   │   ├── primary-agent.ts     ← architect / build / review
│   │   ├── lead-agent.ts        ← department lead
│   │   ├── specialist-agent.ts  ← hidden specialist
│   │   ├── prompt.ts            ← system prompt with project context injection
│   │   └── command.ts           ← ceremony commands
│   │
│   └── registry/                ← Knowledge base the planner consults
│       ├── index.ts             ← lookup/list + types
│       └── stacks/
│           ├── google-adk.ts
│           ├── baml.ts
│           ├── convex.ts
│           ├── nextjs.ts
│           └── tailwind-shadcn.ts
│
├── agents/
│   └── studio.md                ← The planner agent definition (shipped with plugin)
│
└── test/
    └── generators.test.ts

3. The Studio Planner Agent

The plugin ships a single agent defined in agents/studio.md:

---
description: >
  Dev Studio planner. Analyzes your project, designs a tailored agent team,
  and scaffolds all configuration. Use this to set up or modify your dev studio.
mode: primary
temperature: 0.2
color: "#8b5cf6"
permission:
  edit: allow
  bash:
    "*": ask
    "cat *": allow
    "type *": allow
    "dir *": allow
    "ls *": allow
    "find *": allow
  task:
    "*": deny
    "explore": allow
    "general": allow
---

You are the Dev Studio Planner — an intelligent architect that designs
agent teams for software projects.

## Your workflow

1. **Analyze the project** — use the `explore` subagent to scan:
   - Dependency files: package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod
   - Config files: tsconfig.json, next.config.*, convex.config.*, .bamlrc
   - Directory structure: src/, app/, convex/, baml_src/, etc.
   - Import patterns: what frameworks/libraries are actually used

2. **Map to departments** — match findings against your known stack registry.
   Use `studio_list_stacks` to see available stacks.
   For technologies NOT in the registry, design a custom department on the fly.

3. **Propose the team** — present the user with:
   - Which departments you'd create and why
   - How many specialists per department
   - The task permission hierarchy
   - Ask if they want to add/remove/modify anything

4. **Scaffold** — after user confirms, call `studio_scaffold` with the
   finalized team design.

5. **Project-aware prompts** — when generating, include project-specific
   context you discovered:
   - Actual directory structure conventions
   - Package versions in use
   - Naming patterns you observed
   - Architecture patterns (monorepo, app router, etc.)

## Rules
- Always scan before proposing. Never assume the stack.
- Always confirm with the user before scaffolding.
- If you find a technology with no registry entry, design a reasonable
  department structure yourself based on your knowledge.
- Include Context7 MCP in the generated config so agents can pull live docs.

How it uses built-in agents:

| Built-in | What studio uses it for | |---|---| | explore | Scans file tree, reads package.json, greps imports, finds config files. Read-only, fast. | | general | Researches unknown frameworks if the planner encounters something it doesn't recognize. |

The planner can run explore multiple times to dig deeper:

• First pass: dependency files + top-level structure
• Second pass: specific imports in key files
• Third pass: config patterns (e.g., reading next.config.js for app router vs pages router)

4. Stack Registry — Planner's Knowledge Base

The registry is the planner's knowledge base. It helps match findings to stacks, but the planner can also design departments for unknown stacks on the fly.

// src/registry/index.ts
export interface StackDefinition {
  id: string
  name: string
  color: string
  description: string
  detection: {
    packages?: string[]       // npm/pip/cargo package names
    files?: string[]          // config files that indicate this stack
    directories?: string[]    // directory patterns
    imports?: string[]        // import patterns to grep for
  }
  lead: {
    name: string
    description: string
    expertise: string[]
    escalation: Record<string, string>
  }
  specialists: Array<{
    name: string
    focus: string
    knowledgeTopics: string[]
  }>
  knowledgeSources: string[]
}

5. What Gets Generated

Tier 1 — Primary Agents (always):

• architect — CTO, plans, read-only
• build — VP Eng, full tools
• review — VP Quality, read-only

Tier 2 — Department Leads (per detected/requested stack):

• @-mentionable subagents, one per technology
• Prompts include project-specific context the planner discovered

Tier 3 — Hidden Specialists (per department):

• Only invokable by their parent lead
• Focused on specific sub-domains of the technology

Project-Aware Prompt Enhancement:

The planner injects discovered context into generated prompts:

## Project Context (auto-detected)
- Framework: Next.js 15 with App Router
- Directory: app/(dashboard)/ for authenticated routes
- Backend: Convex with 4-folder structure (agent/, bridge/, orchestrator/, data/)
- Styling: Tailwind CSS + shadcn/ui
- State: React Query + Convex real-time subscriptions
- Package manager: bun
- TypeScript: strict mode

When writing code, follow these conventions.

6. Custom Tools

studio_scaffold

Generates the complete .opencode/ directory based on a team design.

studio_add_dept

Adds one department to an existing setup.

studio_refresh

Re-scans project and updates prompts with fresh context.

studio_list_stacks

Returns the registry of known stacks with detection hints.

7. Install

{
  "plugin": ["opencode-dev-studio"]
}

After installing, switch to the studio agent and say:

Set up a dev studio for this project

8. Development

npm install
npm run build
npm run test

License

MIT