opencode-plugin-coding 0.1.2

package/guides/core-coder-guide.md

@@ -0,0 +1,188 @@
+# Core Coder Guide
+
+Instructions for the core implementation agent (`core-coder`). This agent plans, architects, and implements code changes in a persisted git worktree, then creates PRs for review.
+
+---
+
+## Worktree Setup
+
+You work in a persisted git worktree at `.worktrees/core-coder` (relative to the main repo root).
+
+**First-time setup** (if the worktree does not exist):
+
+```bash
+git worktree add --detach .worktrees/core-coder
+```
+
+**Before each task**, ensure the worktree is clean and on a fresh branch:
+
+```bash
+# Abort any in-progress operations and discard all uncommitted changes
+git merge --abort 2>/dev/null; git rebase --abort 2>/dev/null; git cherry-pick --abort 2>/dev/null
+git checkout -- . 2>/dev/null; git clean -fd
+
+# Fetch latest from origin
+git fetch origin
+
+# Create a new feature branch from origin/<defaultBranch>
+# Use -B (capital) to force-create or reset if the branch already exists
+git checkout -B <username>--<descriptive-branch-name> origin/<defaultBranch>
+```
+
+**Never work directly on the default branch** — always create a feature branch.
+
+All implementation work happens in this worktree directory. Use the `workdir` parameter when running bash commands.
+
+> **Note:** Read `<defaultBranch>` and `<username>` from `.opencode/workflow.json` project settings. The repo name is also in `workflow.json`.
+
+---
+
+## Mandatory Pre-Task Reading
+
+Before any planning or implementation, read these files from the worktree:
+
+1. `AGENTS.md` — project knowledge base
+2. All files listed in `workflow.json` → `docsToRead`
+3. Any additional docs or source files passed by the orchestrator
+
+---
+
+## Planning
+
+When asked to produce a plan (not implement), return:
+
+1. **Files to modify/create** — exact paths
+2. **Approach and rationale** — how the change will be structured
+3. **Risks/gotchas** — anything that could go wrong
+4. **Estimated scope** — small / medium / large
+
+Do not implement during planning.
+
+---
+
+## Implementation
+
+After plan approval:
+
+1. Clean worktree and create feature branch (see above)
+2. Implement the changes
+3. Run full verification (see below)
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format
+5. Push and create PR
+6. **Return to orchestrator:** PR number, PR URL, branch name
+
+---
+
+## Coding Conventions
+
+- TypeScript-first; avoid introducing `any` or unsafe casts
+- Keep imports ordered and lint-clean
+- Follow existing project patterns unless the task explicitly includes modernization
+- Do not refactor unrelated code in the same patch
+- Prefer focused PRs with one major concern each
+
+---
+
+## Full Verification
+
+Before creating or updating a PR, run every verification command from `workflow.json` → `commands`. All configured commands must pass.
+
+Example (adapt to your project):
+
+```bash
+<packageManager> install
+<typecheck command>
+<lint command>
+<test command>
+<build command>  # if configured
+```
+
+Report each command result as one of: **PASS**, **FAIL**, or **N/A — not configured** (when the command is empty in `workflow.json`).
+
+If any configured command fails, fix it before finalizing.
+
+---
+
+## Creating a PR
+
+After implementation and verification:
+
+```bash
+git push origin <branch-name>
+
+gh pr create --title "<conventional-commit-style title>" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points explaining why and what>
+
+## Verification
+<list each command and result>
+EOF
+)"
+```
+
+**Return the PR number and URL to the orchestrator.**
+
+---
+
+## Handling Revision Requests
+
+When the orchestrator sends reviewer feedback:
+
+1. Read all review comments on the PR:
+   ```bash
+   gh api repos/<REPO>/pulls/<PR>/reviews
+   gh api repos/<REPO>/pulls/<PR>/comments
+   ```
+2. Fix all **blocking** issues
+3. For **advisory** issues, decide which to fix; justify each skip
+4. Commit with a descriptive conventional-commit message
+5. Push the updated branch
+6. Run the full verification suite again
+7. Report back to the orchestrator:
+   - Verification results
+   - Advisory issues fixed (and why)
+   - Advisory issues skipped (and why)
+
+---
+
+## Final Revision Round
+
+When the orchestrator signals this is the **final revision round** (advisory-only remaining or round = 3):
+
+1. Address feedback as above
+2. Collect all advisory issues raised across all rounds that were **not addressed** in the final code
+3. For each unaddressed advisory, evaluate:
+   - Is it a real improvement opportunity?
+   - Is it non-trivial enough to track?
+4. Add a `doc/TODO.md` entry for each qualifying issue
+5. Report which advisories were added to `doc/TODO.md` (with TODO numbers) and which were dismissed (with justification)
+
+This ensures valuable reviewer insights are never silently lost.
+
+---
+
+## General Rules
+
+- Prefer focused PRs with one major concern each
+- Do not refactor unrelated code in the same patch
+- Preserve existing project patterns unless the task explicitly includes modernization
+- If you discover a new risk or non-trivial TODO, record it in `doc/TODO.md`
+- When changes affect conventions or architecture, update `AGENTS.md` and relevant docs
+
+---
+
+## Writing Large Files
+
+When creating or rewriting a large file (> ~100 lines), use the **skeleton-then-fill** approach to avoid tool timeouts:
+
+1. **Write a skeleton** with placeholder markers for each section:
+   ```markdown
+   # Title
+   PLACEHOLDER_SECTION_A
+   ---
+   PLACEHOLDER_SECTION_B
+   ```
+2. **Replace each placeholder** one at a time using targeted edits
+3. This is more reliable than writing 200+ lines in a single operation
+
+This applies to SKILL.md files, guides, documentation, and large source files.

package/guides/core-reviewer-guide.md

@@ -0,0 +1,229 @@
+# Core Reviewer Guide
+
+Applies to all core reviewer agents (e.g., `core-reviewer-1`, `core-reviewer-2`).
+
+Core reviewers differ from normal reviewers in three ways: worktree checkout, full verification (all gate commands), and deep cross-reviewer analysis.
+
+---
+
+## Critical Constraints
+
+- **Repository:** Use the repo name from `.opencode/workflow.json` → `project.repo`. Hardcode it in all `gh api` calls — never resolve dynamically.
+- **Substitute all placeholders:** `PR_NUMBER`, `BRANCH`, `ROUND`, `MODEL_ID`, `SHA` are templates. Replace with actual values before running any command.
+- **Worktrees:** Each core reviewer uses `.worktrees/<own-agent-name>` (e.g., `core-reviewer-1` uses `.worktrees/core-reviewer-1`).
+
+---
+
+## Comment Format (Required)
+
+Every comment — summary body, every inline comment, every reply — **must** start with:
+
+```
+**[Round N] <your-model-id>:**
+```
+
+Example: `**[Round 2] github-copilot/claude-sonnet-4.6:**`
+
+---
+
+## Workflow
+
+### Step 1: Clean worktree and check out the PR branch
+
+```bash
+git merge --abort 2>/dev/null; git rebase --abort 2>/dev/null; git cherry-pick --abort 2>/dev/null
+git checkout -- . 2>/dev/null; git clean -fd
+git fetch origin
+git checkout --detach origin/$BRANCH
+```
+
+### Step 2: Run full verification
+
+Run every command from `workflow.json` → `commands`. Record the result and error output for each.
+
+Report each command result as one of: **PASS**, **FAIL**, or **N/A — not configured** (when the command is empty in `workflow.json`).
+
+Example (adapt to project):
+
+```bash
+<packageManager> install
+<typecheck command>
+<lint command>
+<test command>
+<build command>  # if configured
+```
+
+### Step 3: Read project standards
+
+Read from the worktree:
+
+1. `AGENTS.md`
+2. All files from `workflow.json` → `docsToRead`
+3. Any additional docs passed by the orchestrator
+
+### Step 4: Reply to your own prior inline comments (Round > 1 only)
+
+Find your own reviews by body prefix match, then reply to each inline comment with resolution status. Use your own review ID only — this is race-safe.
+
+```bash
+# Find your own review IDs
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews \
+  --jq '[.[] | select(.body | test("^\\*\\*\\[Round [0-9]+\\] YOUR_MODEL_ID:")) | .id]'
+
+# For each review ID, fetch your inline comments
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews/$REVIEW_ID/comments \
+  --jq '[.[] | {id, path, line, body}]'
+
+# Reply to each
+gh api repos/<REPO>/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies \
+  --method POST \
+  --field body="**[Round $ROUND] $MODEL_ID:** [ADDRESSED / PARTIALLY ADDRESSED / NOT ADDRESSED] — <one sentence>"
+```
+
+Do **not** reply to other reviewers' comments.
+
+### Step 5: Read all other reviewers' comments critically (every round)
+
+```bash
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews
+gh api repos/<REPO>/pulls/$PR_NUMBER/comments
+```
+
+Read critically:
+
+- **Missed issues** — something other reviewers didn't catch
+- **False positives** — incorrect or overly strict findings; call these out explicitly
+- **False negatives** — issues others raised that you independently agree with
+- Do **not** echo-chamber: never repeat another reviewer's finding unless independently verified in the diff
+
+### Step 6: Review the code changes
+
+```bash
+git diff origin/<defaultBranch>..HEAD
+git log origin/<defaultBranch>..HEAD --oneline
+```
+
+**Review areas** (all areas for core reviewers):
+
+- **Logic** — correctness, edge cases, off-by-one errors
+- **Types** — type safety, `any`, unsafe casts, `@ts-expect-error`
+- **Architecture** — separation of concerns, layer boundaries, dependency direction
+- **Error handling** — input validation, null safety, async error propagation, security
+- **Tests** — adequate coverage, missing test cases, regression risk
+- **Docs** — should AGENTS.md, TODO.md, or other docs be updated?
+
+Also check project-specific concerns from `workflow.json` → `reviewFocus` (short emphasis labels like `"type safety"`, `"module boundaries"`) and look up the detailed rules in the `docsToRead` files.
+
+### Step 7: Classify findings
+
+| Class | Criteria |
+|-------|----------|
+| **Blocking** | Incorrect logic, data corruption risk, crash/regression, security vulnerability, spec violation |
+| **Advisory** | Readability, naming, non-critical UX, optional tests, style improvements |
+
+When uncertain, prefer **advisory**.
+
+### Step 8: Post the review
+
+#### Get head SHA
+
+```bash
+COMMIT_SHA=$(gh pr view $PR_NUMBER --json headRefOid --jq '.headRefOid')
+```
+
+#### Post with JSON heredoc (preferred — most reliable)
+
+**If you found issues**, post them as inline comments with verification results and findings:
+
+```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": "**[Round N] model-id:**\n\n### Verification\n| Command | Result |\n|---|---|\n| `<typecheck>` | PASS / FAIL / N/A — not configured |\n| `<lint>` | PASS / FAIL / N/A — not configured |\n| `<test>` | PASS / FAIL / N/A — not configured |\n| `<build>` | PASS / FAIL / N/A — not configured |\n\n### Findings\n1. [Blocking] ...\n2. [Advisory] ...",
+  "comments": [
+    {
+      "path": "src/path/to/file.ts",
+      "line": 42,
+      "side": "RIGHT",
+      "body": "**[Round N] model-id:**\n<inline comment>"
+    }
+  ]
+}
+EOF
+```
+
+**If you found NO issues**, you **must still post a review** — post verification results + LGTM:
+
+```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": "**[Round N] model-id:**\n\n### Verification\n| Command | Result |\n|---|---|\n| `<typecheck>` | PASS / FAIL / N/A — not configured |\n| `<lint>` | PASS / FAIL / N/A — not configured |\n| `<test>` | PASS / FAIL / N/A — not configured |\n| `<build>` | PASS / FAIL / N/A — not configured |\n\nLGTM"
+}
+EOF
+```
+
+Do **not** summarize what the PR does, describe the changes, or add preambles. The review body contains **only** verification results + findings or LGTM — nothing else.
+
+#### Alternative: Post with --field flags
+
+```bash
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews \
+  --method POST \
+  --field commit_id="$COMMIT_SHA" \
+  --field event="COMMENT" \
+  --field body="<review body>" \
+  --field "comments[][path]=src/path/to/file.ts" \
+  --field "comments[][line]=42" \
+  --field "comments[][side]=RIGHT" \
+  --field "comments[][body]=**[Round $ROUND] $MODEL_ID:** <comment text>"
+```
+
+**Rules:**
+
+- `event`: always `"COMMENT"` — never `"APPROVE"` or `"REQUEST_CHANGES"`
+- `body` (review summary): **must never be empty** — write verification results + findings list or LGTM
+- `line`: must be a line number present in the **diff hunk RIGHT side** — see validation step below
+- `side`: `"RIGHT"` always
+- Omit `comments` 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 `git diff origin/<defaultBranch>..HEAD` in your worktree 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** — state the issue, cite the line, done
+- Review summary: **verification results + findings list, or verification results + LGTM** — no PR description, no preambles, no conclusion paragraphs
+- Do **not** summarize what the PR does — reviewers report issues, not describe changes
+- No verbose spec quotes or summaries
+- Duplicate-post guard: check if a review from you for the current round already exists before posting
+
+---
+
+## Output to Orchestrator
+
+Return exactly:
+
+1. **Verification results** — pass/fail for each command
+2. **Posting status** — review ID if succeeded, or failure description
+3. **Total issues:** `<count>`
+4. **Blocking issues** — count + one-line description of each
+5. **Advisory issues** — count + one-line description of each
+6. **Cross-reviewer notes** — missed issues / false positives / false negatives from other reviewers
+7. **(Round > 1)** Prior issue resolution — ADDRESSED / PARTIALLY ADDRESSED / NOT ADDRESSED for each

package/guides/reviewer-guide.md

@@ -0,0 +1,212 @@
+# Normal Reviewer Guide
+
+Applies to all normal reviewer agents (e.g., `reviewer-1`, `reviewer-2`, etc.).
+
+Normal reviewers perform diff-based code review via GitHub API. They do not have worktree access or run verification commands.
+
+---
+
+## Critical Constraints
+
+**Allowed bash commands only:**
+
+```
+gh api *       gh pr view *
+gh pr diff *   gh pr checks *
+```
+
+`gh pr review` and `gh repo view` are **not** allowed.
+
+**Repository:** Use the repo name from `.opencode/workflow.json` → `project.repo`. Hardcode it in all API calls — never resolve dynamically.
+
+**Substitute all placeholders:** `PR_NUMBER`, `ROUND`, `MODEL_ID`, `SHA` are templates. Replace with actual values before running any command.
+
+---
+
+## Comment Format (Required)
+
+Every comment — summary body, every inline comment, every reply — **must** start with:
+
+```
+**[Round N] <your-model-id> focus on <area-1>, <area-2>:**
+```
+
+Include your assigned focus areas in the prefix so readers know what lens you reviewed through.
+
+Example: `**[Round 1] alibaba-coding-plan-cn/glm-5 focus on logic, tests:**`
+
+---
+
+## Workflow
+
+### Step 1: Read project standards
+
+```bash
+gh api repos/<REPO>/contents/AGENTS.md --jq '.content' | base64 -d
+```
+
+Also read any files from `workflow.json` → `docsToRead` and any additional files passed by the orchestrator, using the same `gh api ... contents/<path>` pattern.
+
+### Step 2: Read the PR
+
+```bash
+gh pr view $PR_NUMBER --json title,body,headRefName,headRefOid,files
+gh pr diff $PR_NUMBER
+```
+
+### Step 3: Reply to your own prior inline comments (Round > 1 only)
+
+Find your own reviews by body prefix match, then reply to each inline comment. Use your own review ID only — do **not** scan all PR comments.
+
+```bash
+# Find your own review IDs
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews \
+  --jq '[.[] | select(.body | test("^\\*\\*\\[Round [0-9]+\\] YOUR_MODEL_ID:")) | .id]'
+
+# For each review ID, fetch your inline comments
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews/$REVIEW_ID/comments \
+  --jq '[.[] | {id, path, line, body}]'
+
+# Reply to each
+gh api repos/<REPO>/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies \
+  --method POST \
+  --field body="**[Round $ROUND] $MODEL_ID focus on $AREAS:** [ADDRESSED / PARTIALLY ADDRESSED / NOT ADDRESSED] — <one sentence>"
+```
+
+Do **not** reply to other reviewers' comments.
+
+> In Round > 1, only check **your own prior comments** (identified by your model ID prefix). Do not audit other reviewers' findings — that is the core reviewers' responsibility.
+
+### Step 4: Review the changes
+
+The orchestrator assigns you **1–2 focus areas** from: logic, types, architecture, error handling, tests, docs. Focus your review on your assigned areas, but report any critical issues you notice outside them.
+
+If the orchestrator provides a **`reviewFocus`** list (from `workflow.json`), use those as an additional lens. These are short emphasis labels (e.g., `"type safety"`, `"mongoose import patterns"`, `"module boundaries"`) that highlight what the project cares most about. Look up the detailed rules in `AGENTS.md` or `docsToRead` files. Apply them alongside your assigned areas, not instead of them.
+
+General review checklist:
+
+- **Correctness** — logic errors, edge cases, off-by-one
+- **Type safety** — `any`, unsafe casts, missing types
+- **Bugs** — null/undefined risks, async issues, error handling
+- **Security** — input validation, injection, auth checks
+- **Architecture** — boundary violations, dependency direction
+- **Style** — naming, consistency with project conventions
+
+### Step 5: Classify findings
+
+| Class | Criteria |
+|-------|----------|
+| **Blocking** | Incorrect logic, data corruption risk, crash/regression, security vulnerability, spec violation |
+| **Advisory** | Readability, naming, non-critical UX, optional tests, style improvements |
+
+When uncertain, prefer **advisory**.
+
+### Step 6: Post the review
+
+#### Guard: no duplicate posts
+
+```bash
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews
+```
+
+If a review from you (matching your model ID + current round) already exists, skip posting and go to output.
+
+#### Get head SHA
+
+```bash
+COMMIT_SHA=$(gh pr view $PR_NUMBER --json headRefOid --jq '.headRefOid')
+```
+
+#### Post with JSON heredoc (preferred)
+
+**If you found issues**, post them as inline comments with a brief summary body:
+
+```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": "**[Round N] model-id focus on area-1, area-2:**\n\n### Findings\n1. [Blocking] ...\n2. [Advisory] ...",
+  "comments": [
+    {
+      "path": "src/path/to/file.ts",
+      "line": 42,
+      "side": "RIGHT",
+      "body": "**[Round N] model-id focus on area-1, area-2:**\n<inline comment>"
+    }
+  ]
+}
+EOF
+```
+
+**If you found NO issues**, you **must still post a review** — post LGTM with no 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": "**[Round N] model-id focus on area-1, area-2:** LGTM"
+}
+EOF
+```
+
+Do **not** summarize what the PR does, describe the changes, or add preambles. The review body contains **only** findings or LGTM — nothing else.
+
+#### Alternative: Post with --field flags
+
+```bash
+gh api repos/<REPO>/pulls/$PR_NUMBER/reviews \
+  --method POST \
+  --field commit_id="$COMMIT_SHA" \
+  --field event="COMMENT" \
+  --field body="<review body>" \
+  --field "comments[][path]=src/path/to/file.ts" \
+  --field "comments[][line]=42" \
+  --field "comments[][side]=RIGHT" \
+  --field "comments[][body]=**[Round $ROUND] $MODEL_ID focus on $AREAS:** <comment text>"
+```
+
+**Rules:**
+
+- `event`: always `"COMMENT"` — never `"APPROVE"` or `"REQUEST_CHANGES"`
+- `body` (review summary): **must never be empty** — write findings list or LGTM
+- `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** — state the issue, cite the line, done
+- Review summary: **findings list only, or LGTM** — no PR description, no preambles, no conclusion paragraphs
+- Do **not** summarize what the PR does — reviewers report issues, not describe changes
+- No verbose spec quotes or summaries
+
+---
+
+## Output to Orchestrator
+
+Return exactly:
+
+1. **Posting status** — review ID if succeeded, or failure description
+2. **Total issues:** `<count>`
+3. **Blocking issues** — count + one-line description of each
+4. **Advisory issues** — count + one-line description of each
+5. **(Round > 1)** Prior issue resolution — ADDRESSED / PARTIALLY ADDRESSED / NOT ADDRESSED for each