opencode-plugin-coding 0.1.2

package/guides/security-reviewer-guide.md

@@ -0,0 +1,184 @@
+# Security Reviewer Guide
+
+Applies to the dedicated security reviewer agent. In v1, this reviewer runs **pre-merge only** — after code-review rounds converge and immediately before the merge decision.
+
+---
+
+## Purpose
+
+The security reviewer provides a focused security analysis of the PR diff. It can **block** the merge if critical security issues are found. This is a specialized role — it does not replace the security aspects of core/normal reviewers but adds a dedicated, thorough security pass that runs after all code-review rounds have converged.
+
+---
+
+## Critical Constraints
+
+- **Repository:** Use the repo name from `.opencode/workflow.json` → `project.repo`
+- **Substitute all placeholders:** `PR_NUMBER`, `BRANCH`, `ROUND`, `MODEL_ID`, `SHA`
+- **Timing:** Pre-merge only (runs after code-review rounds converge, immediately before merge decision)
+- **Allowed bash commands:** `gh api *`, `gh pr view *`, `gh pr diff *`
+
+---
+
+## Comment Format (Required)
+
+Every comment must start with:
+
+```
+**[Security] <your-model-id>:**
+```
+
+Example: `**[Security] github-copilot/claude-sonnet-4.6:**`
+
+---
+
+## Workflow
+
+### Step 1: Read project context
+
+```bash
+gh api repos/<REPO>/contents/AGENTS.md --jq '.content' | base64 -d
+```
+
+Read any security-relevant docs from `workflow.json` → `docsToRead`.
+
+### Step 2: Read the PR diff
+
+```bash
+gh pr view $PR_NUMBER --json title,body,headRefName,headRefOid,files
+gh pr diff $PR_NUMBER
+```
+
+### Step 3: Security analysis
+
+Perform a systematic security review across these categories:
+
+#### Input Validation
+- User input sanitization and validation
+- SQL/NoSQL injection vectors
+- XSS (cross-site scripting) opportunities
+- Command injection via unsanitized shell inputs
+- Path traversal vulnerabilities
+
+#### Authentication & Authorization
+- Auth bypass opportunities
+- Missing or incorrect permission checks
+- Token/session handling issues
+- Privilege escalation paths
+
+#### Data Protection
+- Sensitive data exposure (logs, error messages, API responses)
+- Missing encryption for sensitive data at rest or in transit
+- Hardcoded secrets, API keys, or credentials
+- PII handling compliance
+
+#### Dependency & Supply Chain
+- Known vulnerable dependencies being added
+- Unsafe use of `eval()`, `Function()`, or dynamic code execution
+- Unsafe deserialization
+
+#### API & Network
+- Missing rate limiting on sensitive endpoints
+- CORS misconfiguration
+- Insecure HTTP methods or headers
+- Missing CSRF protection
+
+#### Error Handling
+- Information leakage through error messages
+- Unhandled errors that could cause denial of service
+- Error conditions that bypass security controls
+
+### Step 4: Classify findings
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Exploitable vulnerability, data breach risk, auth bypass | **Blocks** merge — must be fixed first |
+| **High** | Significant security weakness, requires attacker effort | **Blocks** merge |
+| **Medium** | Defense-in-depth issue, hardening opportunity | **Advisory** — reported but does not block |
+| **Low** | Best practice, minor hardening | **Advisory** |
+| **Info** | Observation, no direct risk | **Advisory** |
+
+### Step 5: Post review
+
+```bash
+COMMIT_SHA=$(gh pr view $PR_NUMBER --json headRefOid --jq '.headRefOid')
+```
+
+**If you found security issues**, post findings with inline comments:
+
+```bash
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews \
+  --method POST \
+  --header "Content-Type: application/json" \
+  --input - <<'EOF'
+{
+  "commit_id": "ACTUAL_SHA",
+  "event": "COMMENT",
+  "body": "**[Security] model-id:**\n\n### Overall Risk: MEDIUM / HIGH / CRITICAL\n\n### Findings\n1. [Critical/High/Medium/Low/Info] ...\n\n### Verdict: BLOCK",
+  "comments": [
+    {
+      "path": "src/path/to/file.ts",
+      "line": 42,
+      "side": "RIGHT",
+      "body": "**[Security] model-id:**\n[Severity] <description>"
+    }
+  ]
+}
+EOF
+```
+
+**If you found NO security issues**, you **must still post a review** — post PASS:
+
+```bash
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews \
+  --method POST \
+  --header "Content-Type: application/json" \
+  --input - <<'EOF'
+{
+  "commit_id": "ACTUAL_SHA",
+  "event": "COMMENT",
+  "body": "**[Security] model-id:** PASS — no security issues found"
+}
+EOF
+```
+
+Do **not** summarize what the PR does or describe the changes. The review body contains **only** findings + verdict, or PASS — nothing else.
+
+**Rules:**
+
+- `event`: always `"COMMENT"` — never `"APPROVE"` or `"REQUEST_CHANGES"`
+- `body` (review summary): **must never be empty** — write findings + verdict, or PASS
+- `line`: must be a line number present in the **diff hunk RIGHT side** — see validation step below
+- `side`: `"RIGHT"` always
+- Omit `comments` array entirely when no inline comments
+- Use `<<'EOF'` (single-quoted) so the shell does not expand `$` inside JSON
+
+#### Validate line numbers before posting
+
+For each inline comment, confirm the target line appears in the diff. Run `gh pr diff $PR_NUMBER` and find the file's hunk. Only lines with a `+` prefix (added) or ` ` prefix (context) on the RIGHT side are valid targets. Lines with `-` prefix (removed) are LEFT-side only and will cause a posting error. If the line number is not in any hunk, the GitHub API will reject the comment — **do not guess line numbers from the full file**; use only lines visible in the diff output.
+
+#### Verify posting succeeded
+
+Check that the response contains `"id":`. If absent or errored, retry once using the `--field` form. Report success/failure — **do not silently discard findings**.
+
+---
+
+## Conciseness Rules (Strictly Enforced)
+
+- Each inline comment: **1–3 sentences max**
+- Summary: **findings + verdict only, or PASS** — no PR description, no preambles
+- Do **not** summarize what the PR does — report security findings only
+- No duplicate posts
+
+---
+
+## Output to Orchestrator
+
+Return exactly:
+
+1. **Overall risk level:** LOW / MEDIUM / HIGH / CRITICAL
+2. **Verdict:** PASS or BLOCK
+3. **Critical/High findings** — count + one-line description of each (these block)
+4. **Medium/Low/Info findings** — count + one-line description of each (advisory)
+5. **Posting status** — review ID if succeeded, or failure description
+
+If verdict is **BLOCK**, the orchestrator sends critical/high findings to `core-coder` for fixes, then returns to Phase 3 (code review). After code-review rounds converge again, the security review re-runs.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "opencode-plugin-coding",
+  "version": "0.1.2",
+  "description": "A shared OpenCode plugin for multi-agent software development workflows: brainstorm, plan, orchestrate, review, debug.",
+  "type": "module",
+  "main": ".opencode/plugins/opencode-plugin-coding.js",
+  "license": "MIT",
+  "files": [
+    ".opencode/plugins/",
+    "commands/",
+    "guides/",
+    "skills/",
+    "templates/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:ZooplanktonAI/opencode-plugin-coding.git"
+  }
+}

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: brainstorm
+description: Socratic design interview that refines rough ideas into a validated design document before implementation begins.
+---
+
+# Brainstorm
+
+A Socratic design interview that takes a rough idea and refines it into a clear, validated design document. Use this skill before `plan` to ensure the approach is sound before committing to implementation.
+
+Inspired by Prometheus planning from Oh-My-OpenAgent and the brainstorming skill from Superpowers.
+
+---
+
+## When to Activate
+
+- User has a vague feature idea or request
+- User says "brainstorm", "design", "think through", "explore options"
+- Before a complex task where the approach is not obvious
+- The orchestrator defers to brainstorm before planning
+
+---
+
+## Process
+
+### Phase 1: Understand the Problem
+
+Ask clarifying questions to understand:
+
+1. **What** — What is the user trying to achieve? What problem does this solve?
+2. **Why** — Why is this needed now? What's the motivation?
+3. **Who** — Who is the target user? What's their workflow?
+4. **Constraints** — What are hard constraints (timeline, compatibility, tech stack)?
+
+**Rules:**
+- Ask **at most 3 questions per round** — do not overwhelm
+- If the user's intent is already clear, skip to Phase 2
+- Acknowledge what you understand before asking follow-ups
+
+### Phase 2: Explore the Design Space
+
+Investigate the codebase to understand the current state:
+
+```bash
+# Read project context
+cat AGENTS.md
+# Read relevant source files
+# Search for related existing code
+```
+
+Then present **2–3 concrete approaches**, each with:
+
+- **Approach name** — brief label
+- **How it works** — 2-3 sentences
+- **Pros** — key advantages
+- **Cons** — key disadvantages
+- **Effort estimate** — small / medium / large
+
+Ask the user which direction they prefer, or if they want to explore a different option.
+
+### Phase 3: Deep Dive
+
+Once a direction is chosen:
+
+1. **Architecture** — How does this fit into the existing codebase? What modules are affected?
+2. **Data model** — What data structures or schemas change?
+3. **API surface** — What interfaces change? New endpoints, new props, new methods?
+4. **Edge cases** — What could go wrong? What are the boundary conditions?
+5. **Testing strategy** — How will this be verified?
+
+Present the deep dive and ask for confirmation or adjustments.
+
+### Phase 4: Write Design Document
+
+Produce a design document and **write it to disk** at `.opencode/designs/<feature-name>.md`:
+
+```markdown
+---
+status: draft
+created: <date>
+author: brainstorm
+---
+
+# Design: <Feature Name>
+
+## Problem Statement
+<1-2 sentences>
+
+## Chosen Approach
+<name and brief description>
+
+## Architecture
+<how it fits into the codebase>
+
+## Data Model Changes
+<schema changes, new types, etc.>
+
+## API Surface Changes
+<new/modified interfaces>
+
+## Edge Cases and Risks
+<list>
+
+## Testing Strategy
+<how to verify>
+
+## Estimated Scope
+<small / medium / large>
+
+## Open Questions
+<anything still unresolved>
+```
+
+### Phase 5: Validate
+
+Before finalizing, self-review the design:
+
+- [ ] Does the design address the original problem?
+- [ ] Are there any placeholder or vague sections?
+- [ ] Is the scope realistic?
+- [ ] Are edge cases covered?
+- [ ] Is the testing strategy concrete?
+
+If issues are found, revise and present the updated version.
+
+---
+
+## Output
+
+Return to the user (or orchestrator):
+
+1. **Design document path** — `.opencode/designs/<feature-name>.md`
+2. **Recommended next step** — typically "Run the `plan` skill to decompose this into implementation tasks"
+3. **Open questions** — anything that needs user input before planning
+
+---
+
+## Interaction Style
+
+- Be a thoughtful collaborator, not a yes-machine
+- Challenge assumptions when they seem risky
+- Suggest simpler alternatives when the user is over-engineering
+- Keep each response focused — don't dump everything at once
+- Use concrete code examples when discussing architecture

package/skills/git-worktree/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: git-worktree
+description: Create and manage isolated git worktrees for parallel development. Set up before orchestrate, clean up after merge.
+---
+
+# Git Worktree
+
+Manage isolated git worktrees for the multi-agent workflow. Each agent works in its own worktree to avoid conflicts. Read agent names from `workflow.json` → `agents` (each entry is a `{ name, model }` object — use `.name` for paths).
+
+---
+
+## When to Activate
+
+- Before `orchestrate` — ensure worktrees exist
+- After merge — clean up worktree state
+- User asks to set up or reset worktrees
+
+---
+
+## Worktree Layout
+
+| Agent | Path | Purpose |
+|-------|------|---------|
+| `coreCoder` | `.worktrees/<coreCoder.name>` | Implementation workspace |
+| Each entry in `coreReviewers` | `.worktrees/<entry.name>` | Code review with full verification |
+
+Normal reviewers do **not** need worktrees — they use `gh pr diff` (read-only).
+
+---
+
+## Setup
+
+### Create worktrees (idempotent)
+
+Read `agents.coreCoder.name` and each `agents.coreReviewers[i].name` from `workflow.json`. For each, create a worktree if it doesn't exist:
+
+```bash
+# For coreCoder.name:
+ls .worktrees/<coreCoder.name> 2>/dev/null || git worktree add --detach .worktrees/<coreCoder.name>
+
+# For each entry in coreReviewers:
+ls .worktrees/<entry.name> 2>/dev/null || git worktree add --detach .worktrees/<entry.name>
+```
+
+### Ensure .gitignore entry
+
+`.worktrees/` must be in `.gitignore`. The `/zooplankton-coding-init` command handles this automatically.
+
+### Install dependencies (if needed)
+
+After creating a new worktree, install dependencies:
+
+```bash
+cd .worktrees/<agent-name> && <packageManager> install
+```
+
+Core reviewer worktrees also need dependencies for running verification commands.
+
+---
+
+## Before Each Task
+
+Clean and sync each worktree before use:
+
+```bash
+cd .worktrees/<agent-name>
+
+# Abort any in-progress operations
+git merge --abort 2>/dev/null
+git rebase --abort 2>/dev/null
+git cherry-pick --abort 2>/dev/null
+
+# Discard uncommitted changes
+git checkout -- . 2>/dev/null
+git clean -fd
+
+# Fetch latest
+git fetch origin
+```
+
+For **core-coder**, create a feature branch:
+
+```bash
+git checkout -B <username>--<branch-name> origin/<defaultBranch>
+```
+
+For **core-reviewers**, check out the PR branch:
+
+```bash
+git checkout --detach origin/<pr-branch>
+```
+
+---
+
+## After Merge
+
+Detach all worktrees so the feature branch can be deleted:
+
+```bash
+# For coreCoder.name:
+git -C .worktrees/<coreCoder.name> checkout --detach HEAD
+
+# For each entry in coreReviewers:
+git -C .worktrees/<entry.name> checkout --detach HEAD
+```
+
+Then delete the branch locally and remotely (handled by the `orchestrate` skill).
+
+---
+
+## Troubleshooting
+
+### Worktree locked
+
+```bash
+git worktree unlock .worktrees/<name>
+```
+
+### Worktree directory exists but is not a valid worktree
+
+```bash
+git worktree remove .worktrees/<name> --force
+git worktree add --detach .worktrees/<name>
+```
+
+### Cannot delete branch because it's checked out in a worktree
+
+Detach the worktree first (see "After Merge" above).
+
+---
+
+## Rules
+
+- **Never work on the default branch** in any worktree — always create or checkout a feature/PR branch
+- **Always clean before use** — stale state from a previous task can cause subtle bugs
+- **Worktrees are persistent** — don't recreate them between tasks, just clean and re-checkout
+- **`.worktrees/` is always gitignored** — never commit worktree directories