opencode-plugin-zooplankton

The unified global OpenCode plugin for ZooplanktonAI.

This repo is self-hosted: it uses the plugin it ships for its own development workflow.

What it provides

1. Coding-standards injection

Pushes instructions/coding-standards.md into every LLM call's system prompt array — including subagents — via the experimental.chat.system.transform hook. This ensures standards stay salient even in long multi-agent conversations where trailing instructions may be deprioritized.

Current rules:

1. Skeleton-then-replace for large files — write a stub structure first, then fill in implementations chunk by chunk.
2. Prefer Edit over Write for existing files — use targeted find-and-replace instead of full file rewrites.
3. Prefer master over main — use master as the default branch name for new repos.
4. Context handoff via temp files — for large sub-agent payloads (>2000 tokens), write to /tmp/ and pass the path instead of inlining.
5. Web research tools — use Context7 (use context7) for library docs, gh_grep for cross-repo examples; prefer these over open-ended web search.

2. Skills

Multi-agent software development skills auto-discovered by OpenCode via config.skills.paths:

• plan — Optional design phase + decompose a feature into bite-sized implementation tasks with acceptance criteria, written to disk.
• orchestrate — Full multi-agent workflow (plan → implement → review → revise → retro → merge) with parallel reviewers, pr-commentator subagent for consolidated posting, and adaptive scoring. Dispatches to a GitHub or local-git path based on project config.
• test-driven-development — Enforce RED-GREEN-REFACTOR cycle (opt-in per project).
• systematic-debugging — 4-phase debugging (reproduce, hypothesize, isolate, fix).
• git-worktree — Manage isolated git worktrees for parallel agent work.
• playwright — Browser automation / e2e testing via the Playwright MCP server.

3. Commands

Registered on startup via the config hook into config.command:

• /zooplankton-init — Scaffold zooplankton.json, agent MD files, and plan/retro templates for a project.
• /zooplankton-update — Refresh agent MD files from the latest guides (after plugin upgrade).
• /zooplankton-add-agent — Add a new agent MD file to the project.
• /zooplankton-plan — Run the plan skill standalone (design + decompose).
• /zooplankton-orchestrate — Run the full orchestrate workflow on a given task.
• /zooplankton-orchestrate-auto — Run orchestrate in autonomous mode (auto-approves all steps).
• /zooplankton-orchestrate-resume — Resume an interrupted orchestrate run.
• /zooplankton-pr-review — Run review-only on an existing PR (no implementation).

4. Guides

Per-role agent instructions under guides/, with unified files containing inline mode callouts:

• Coders: core-coder, junior-coder, frontend-coder
• Reviewers: core-reviewer, reviewer (normal), security-reviewer, frontend-reviewer
• Explorers: explorer
• Strategic: sage
• GitHub posting: pr-commentator

Each role has a single unified guide (e.g. core-coder-guide.md) with inline > **GitHub mode:** / > **Local mode:** callouts. /zooplankton-init generates agent MD files that reference the unified guide; the agent reads project.platform from zooplankton.json at invocation time.

5. Autonomous-mode permission hook

When autonomousMode: true in a project's zooplankton.json, the permission.asked hook auto-allows every permission request — intended for CI / trusted automation scenarios. Exception: doom_loop requests are always denied regardless of autonomousMode — infinite-loop protection is never bypassed.

6. Sensitive file guard

The tool.execute.before hook blocks reads and writes to ~/.ssh/*, ~/.npmrc, and ~/.netrc. (.env is already blocked natively by OpenCode.) Project-level .npmrc files outside the home directory are permitted.

Installation

Install globally so it applies to every project:

# In ~/.config/opencode/
npm install opencode-plugin-zooplankton

Add to ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-plugin-zooplankton"]
}

That's it. Skills, commands, guides, and coding-standards injection all activate automatically. No per-project install or file copying needed.

Migrating from the old split: If your opencode.json also listed "opencode-plugin-coding", remove it — that package is deprecated and its contents live here now.

How it works

The plugin registers six OpenCode hooks:

1. experimental.chat.system.transform — Appends instructions/coding-standards.md content to the system[] array for every LLM call (including subagents). Deduplicated via LF-normalized substring check so repeated calls don't pile up.

2. config — Pushes skills/ into config.skills.paths and merges every .md file under commands/ into config.command. Pre-existing user commands take precedence.

3. permission.asked — Reads zooplankton.json from the working directory; sets output.action = "allow" when autonomousMode === true. Always sets output.action = "deny" for doom_loop requests (infinite-loop protection is never bypassed).

4. tool.execute.before — Blocks reads and writes to ~/.ssh/*, ~/.npmrc, and ~/.netrc. Project-level .npmrc files (outside the home directory) are permitted.

5. experimental.session.compacting — Injects zooplankton.json project config (platform, repo, autonomousMode) into the session compaction context so these settings persist across summary boundaries.

6. event — When notifications: true in zooplankton.json, shows a TUI toast when a session goes idle. Opt-in; silently no-ops when the TUI client is unavailable (e.g., headless/CI).

Note: experimental.chat.system.transform is an experimental OpenCode API (available since OpenCode ≥0.1) and may change in future versions.

Adding rules

Edit instructions/coding-standards.md, bump the version in package.json, then republish.

Recommended MCP Servers

These are not bundled but are referenced in Coding Standard Rule 5. Install them globally for the best experience.

Context7

Fetches current, version-specific library documentation directly from source. Invoke by appending use context7 to any prompt about a library's API.

npx ctx7 setup --opencode

gh_grep

Cross-repo code search across public GitHub. Zero-auth, no install needed — just add to opencode.json:

{
  "mcp": {
    "gh_grep": {
      "type": "sse",
      "url": "https://mcp.grep.app/sse"
    }
  }
}

Development

Requires Node.js >= 20.

git clone [email protected]:ZooplanktonAI/opencode-plugin-zooplankton.git
cd opencode-plugin-zooplankton
npm install
npm test

See AGENTS.md for the full project knowledge base, repository layout, conventions, and release checklist.