feat: add plan and review workflow skills

.config/opencode/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: dispatching-parallel-agents
+description: Dispatch focused subagents in parallel for genuinely independent problem domains
+permalink: opencode-config/skills/dispatching-parallel-agents/skill
+---
+
+# Dispatching Parallel Agents
+
+## Core Value
+
+When there are 2+ genuinely independent failures/problem domains, dispatch one focused agent per domain concurrently instead of serial investigation.
+
+## When to Use
+
+Use when all are true:
+- You have multiple failures across separate domains.
+- Each domain can be investigated without shared context/state.
+- Agents can work without touching the same files or interfering.
+
+Do **not** parallelize when:
+- Failures may share a root cause.
+- You still need a single root-cause investigation first.
+- Agents would edit the same area and conflict.
+
+## Dispatch Pattern
+
+1. Split failures into independent domains.
+2. Write one prompt per domain.
+3. Dispatch subagents concurrently with the `task` tool.
+4. Review results, integrate non-conflicting fixes, then run full verification.
+
+Example dispatch intent (tool-level wording):
+- `task`: "Investigate and fix failures in <domain A only>"
+- `task`: "Investigate and fix failures in <domain B only>"
+
+## Prompt Quality Requirements
+
+Each subagent prompt must include:
+1. **One clear problem domain** (single file/subsystem/failure cluster).
+2. **Self-contained context** (errors, failing tests, relevant constraints).
+3. **Explicit constraints** (what not to change; scope boundaries).
+4. **Explicit expected output** (root cause + files changed + validation run).
+
+## Verification and Quality Pipeline
+
+After subagents return:
+1. Check for overlapping edits or assumption conflicts.
+2. Run required verification for the integrated result (not partial checks).
+3. Send the feature through reviewer, then tester when behavior is user-facing.
+4. Do not claim completion without fresh verification evidence.

.config/opencode/skills/executing-plans/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: executing-plans
+description: Execute an approved implementation plan from basic-memory with task tracking,
+  verification, and blocker handling
+permalink: opencode-config/skills/executing-plans/skill
+---
+
+# Executing Plans
+
+## Overview
+
+Use this skill when a plan already exists in local basic-memory `plans/` notes and the goal is to execute it safely and completely.
+
+Core workflow:
+- Read the plan
+- Critically review before starting
+- Create or update the plan note checklist in basic-memory
+- Execute tasks one by one
+- Run the verifications specified by the plan
+- Stop on blockers instead of guessing
+
+## Step 1: Load and Review the Plan
+
+1. Read the target note from basic-memory project `plans/` (for example, `plans/<feature-name>`).
+2. Review the plan critically before coding.
+3. Identify gaps, contradictions, unclear steps, or missing prerequisites.
+4. If concerns exist, raise them before implementation.
+5. If the plan is sound, create/update the plan note checklist in basic-memory to mirror executable tasks.
+
+## Step 2: Execute Tasks Sequentially
+
+For each task in order:
+1. Mark one task as `in_progress`.
+2. Follow the plan steps exactly for that task.
+3. Run the verifications specified for that task (tests/checks/manual verification).
+4. If verification passes, mark task `completed` and continue.
+5. Keep only one active task at a time unless the plan explicitly allows parallel work.
+
+## Step 3: Complete the Branch Workflow
+
+After all tasks are completed and verified:
+- Use `git-workflow` for branch finish options (merge, PR, keep for later, or discard with confirmation).
+- Record implementation outcomes back to the relevant basic-memory `plans/` note when requested.
+
+## Blocker Rules (Stop Conditions)
+
+Stop execution immediately and ask for clarification when:
+- A blocker prevents progress (missing dependency, failing prerequisite, unavailable environment)
+- A plan instruction is unclear or conflicts with other instructions
+- Plan gaps prevent safe implementation
+- Required verification repeatedly fails
+
+Do not guess through blockers.
+
+## Worktree and Branch Safety
+
+- Follow worktree-first conventions: execute implementation from the feature worktree, not the primary tree on a base branch.
+- Never start implementation directly on `main`/`master` (or the repository's active base branch) without explicit user consent.
+
+## Related Skills
+
+- `subagent-driven-development` — use when the work should be split across specialized agents
+- `writing-plans` — use when the plan must be created or rewritten before execution
+- `git-workflow` — use to complete branch/PR flow after implementation

.config/opencode/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: receiving-code-review
+description: Evaluate review feedback technically before acting; fix correct items and push back on incorrect ones with codebase evidence
+permalink: opencode-config/skills/receiving-code-review/skill
+---
+
+# Receiving Code Review Feedback
+
+## Core Workflow
+
+When feedback arrives, follow this order:
+
+1. **Read fully** before reacting.
+2. **Understand the actual requirement** (restate it or ask a clarifying question).
+3. **Verify against codebase reality** (current behavior, constraints, tests, compatibility).
+4. **Decide whether feedback is correct for this codebase**.
+5. **Then act**: implement the fix, or push back with technical reasoning.
+
+## Guardrails
+
+- Do not use performative praise or agreement.
+- Do not promise fixes before verification.
+- If any feedback is unclear, clarify first instead of partially implementing items you do understand.
+
+## Processing Multi-Item Feedback
+
+Apply items in this order:
+
+1. Clarifications first.
+2. Blocking/security issues.
+3. Simpler items.
+4. Complex items.
+
+Test each change as you go.
+
+## When to Push Back
+
+Push back when a suggestion is incorrect for this codebase, breaks existing behavior, or ignores known constraints.
+
+Push back style:
+- Keep it technical and specific.
+- Reference concrete code/tests/constraints.
+- Propose a safer alternative when possible.
+
+## When Feedback Is Correct
+
+Implement the fix and report the concrete change.
+
+Keep acknowledgments factual and concise; let verified code changes demonstrate agreement.
+
+## Bottom Line
+
+Technical correctness comes first: verify, decide, then fix or push back.

.config/opencode/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: requesting-code-review
+description: Request a reviewer pass after each task or feature and before merge to catch issues early
+permalink: opencode-config/skills/requesting-code-review/skill
+---
+
+# Requesting Code Review
+
+Request a `reviewer` agent pass before changes move forward or merge.
+
+## Core Workflow
+
+Request review:
+- After a completed task in a multi-task implementation
+- After finishing a feature slice
+- Before opening or merging a PR
+
+Include all required context in the request:
+- What was implemented
+- Requirements or plan source (for example, `plans/<note-name>` in basic-memory)
+- Brief summary of behavior and design choices
+- Actual diff context (commit range and/or key changed files)
+
+## How to Run It
+
+1. Gather concrete diff context for the exact review scope:
+
+```bash
+BASE_SHA=$(git merge-base HEAD origin/$(git rev-parse --abbrev-ref @{upstream} | cut -d/ -f2 2>/dev/null || echo main))
+HEAD_SHA=$(git rev-parse HEAD)
+
+git diff --stat "$BASE_SHA..$HEAD_SHA"
+git diff "$BASE_SHA..$HEAD_SHA"
+```
+
+2. Dispatch `reviewer` with a focused request using:
+- exact implemented scope
+- the relevant `plans/` note or requirement text
+- a concise summary
+- the concrete diff range (`BASE_SHA..HEAD_SHA`) and any key files
+
+Use `reviewer.md` as a request template.
+
+3. Triage feedback before continuing:
+- Fix critical issues immediately
+- Address important issues before merge
+- Track minor issues intentionally
+- If feedback appears incorrect, reply with code/test evidence and request clarification
+
+## Red Flags
+
+Never:
+- Skip review because a change seems small
+- Continue with unresolved critical issues
+- Request review without plan/requirement context
+- Request review without concrete diff scope
+
+## Related Skills
+
+- `verification-before-completion`
+- `git-workflow`

.config/opencode/skills/requesting-code-review/reviewer.md

@@ -0,0 +1,49 @@
+---
+title: reviewer-request-template
+type: note
+permalink: opencode-config/skills/requesting-code-review/reviewer-template
+---
+
+# Reviewer Request Template
+
+Use this when dispatching the `reviewer` agent.
+
+## What Was Implemented
+
+<what-was-implemented>
+
+## Requirements / Plan
+
+- Plan note: `plans/<note-name>`
+- Requirements summary:
+  - <requirement-1>
+  - <requirement-2>
+
+## Summary
+
+<brief summary of behavior/design choices>
+
+## Diff Context
+
+- Base: <base-sha>
+- Head: <head-sha>
+- Range: `<base-sha>..<head-sha>`
+- Key files:
+  - <path-1>
+  - <path-2>
+
+```bash
+git diff --stat <base-sha>..<head-sha>
+git diff <base-sha>..<head-sha>
+```
+
+## Reviewer Output Requested
+
+1. Strengths
+2. Issues by severity:
+   - Critical (must fix)
+   - Important (should fix before merge)
+   - Minor (nice to have)
+3. Merge readiness verdict with short reasoning
+
+For each issue include file:line, why it matters, and suggested fix.

.config/opencode/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: subagent-driven-development
+description: Execute a plan by dispatching one coder task at a time with ordered spec and quality gates
+permalink: opencode-config/skills/subagent-driven-development/skill
+---
+
+# Subagent-Driven Development
+
+Use this skill to execute an existing plan from `plans/*` by delegating **one implementation task at a time** to a fresh `coder`, then running ordered quality gates before moving to the next task.
+
+## Core Workflow Value
+
+1. Dispatch a fresh `coder` for exactly one task.
+2. Run **spec-compliance review first**.
+3. Run **code-quality review second**.
+4. Run `tester` functional validation for user-visible behavior.
+5. Only then mark the task done and continue.
+
+Do not run multiple coder implementations in parallel for the same branch/worktree.
+
+## When to Use
+
+Use when you already have a concrete plan note (usually under `plans/`) and want controlled, high-signal execution with clear review loops.
+
+Prefer this over ad-hoc execution when tasks are independent enough to complete sequentially and verify individually.
+
+## Execution Loop (Per Task)
+
+1. **Load task from plan**
+   - Read `plans/<plan-note>` once.
+   - Extract the exact task text and acceptance criteria.
+   - Prepare any architectural/context notes the coder needs.
+
+2. **Dispatch coder with full context (no rediscovery)**
+   - Paste the **full task text** directly into the coder delegation.
+   - Paste relevant context (paths, constraints, discovered values, dependencies).
+   - Do not ask coder to rediscover the plan.
+
+3. **Handle coder status explicitly**
+   - `DONE`: proceed to spec-compliance review.
+   - `PARTIAL`: resolve stated gaps, then re-dispatch remaining scope.
+   - `BLOCKED`: unblock (context/scope/approach) before retrying.
+
+4. **Reviewer pass 1 — spec compliance (required first)**
+   - `reviewer` checks implementation against task requirements only:
+     - missing requirements
+     - extra/unrequested scope
+     - requirement misinterpretations
+   - If issues exist, send fixes back to `coder`, then re-run this pass.
+
+5. **Reviewer pass 2 — code quality (only after spec pass)**
+   - `reviewer` checks maintainability and correctness quality:
+     - clarity of structure/responsibilities
+     - consistency with local conventions
+     - risk hotspots and change quality
+   - If issues exist, send fixes to `coder`, then re-run this pass.
+
+6. **Tester pass — functional verification**
+   - `tester` validates behavior through real execution paths per local quality pipeline.
+   - If tester fails, return to `coder`, then re-run reviewer/tester as needed.
+
+7. **Record and continue**
+   - Update the relevant `plans/*` checklist/note with concise implementation outcomes.
+   - Move to the next task only when all gates for the current task pass.
+
+## Dispatch Guidance
+
+When delegating to `coder`, include:
+
+- Task name and goal
+- Full task text from the plan
+- Exact constraints ("only this feature", target files, forbidden scope)
+- Discovered values that must be used verbatim
+- Required output format/status expectations
+
+Keep delegations narrow. One coder dispatch should correspond to one task outcome.
+
+## Red Flags
+
+Never:
+
+- skip spec-compliance review
+- run code-quality review before spec-compliance passes
+- mark a task done with open reviewer/tester findings
+- make the coder re-read the entire plan for context already available
+- batch multiple independent tasks into one coder implementation dispatch
+
+## Local Integration
+
+- Plan source of truth: basic-memory notes under `plans/`
+- Implementation agent: `coder`
+- Review agent: `reviewer` (spec pass, then quality pass)
+- Functional validation agent: `tester`
+- Overall gate order: `coder` → `reviewer(spec)` → `reviewer(quality)` → `tester`
+
+This skill complements the repository's mandatory review/test pipeline by enforcing per-task execution discipline and ordered review loops.

.config/opencode/skills/writing-plans/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: writing-plans
+description: Create implementation plans detailed enough for an executor with little project context
+permalink: opencode-config/skills/writing-plans/skill
+---
+
+# Writing Plans
+
+## When to Use
+
+Use this skill when you have requirements for a non-trivial implementation and need a clear plan before editing code.
+
+## Core Goal
+
+Write a comprehensive implementation plan that assumes the executor lacks prior context. The plan must include exact tasks, file paths, expected code shape, and verification commands.
+
+## Scope Check
+
+If requirements contain multiple independent features/subsystems, split into separate plans so each can be implemented and verified independently.
+
+## Plan Storage (basic-memory)
+
+Store plans as basic-memory notes in the repo project under `plans/`.
+
+- Project: `opencode-config` (or current repo project)
+- Note path: `plans/<feature-or-workstream-name>`
+- Use only basic-memory `plans/` notes for plan storage.
+
+## Plan Header Template
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> For implementation: use `subagent-driven-development` when subagents are available; otherwise use `executing-plans`.
+
+**Goal:** [one sentence]
+
+**Architecture:** [2-3 concise sentences]
+
+**Tech Stack:** [languages, frameworks, tools]
+```
+
+## Build the Plan in This Order
+
+1. **Map file structure first**
+   - List files to create/modify/test using exact paths.
+   - State each file's responsibility.
+   - Prefer small, focused files and clear interfaces.
+
+2. **Decompose into small actionable tasks**
+   - Tasks should be independently understandable and testable.
+   - Use checkbox syntax for steps: `- [ ]`.
+   - Keep each step concrete (write test, run command, implement minimal code, re-run checks).
+
+3. **Include code shape guidance**
+   - Show function/class signatures, data flow, and key logic constraints.
+   - Avoid vague instructions like "add validation" without describing expected behavior.
+
+4. **Include exact verification commands (when known)**
+   - Provide commands with scope and expected result.
+   - Example: `pytest tests/path/test_file.py::test_case -v` → expected FAIL before implementation, PASS after.
+   - If exact commands are unknown, state how to discover them from repo scripts/docs.
+
+## Task Template
+
+````markdown
+### Task N: [Name]
+
+**Files:**
+- Create: `path/to/new_file.ts`
+- Modify: `path/to/existing_file.ts`
+- Test: `path/to/test_file.ts`
+
+- [ ] Step 1: Write/extend failing test for [specific behavior]
+- [ ] Step 2: Run: `<exact command>` and confirm expected failure
+- [ ] Step 3: Implement minimal code for [specific behavior]
+- [ ] Step 4: Run: `<exact command>` and confirm pass
+- [ ] Step 5: Run broader verification: `<exact command>`
+````
+
+## Plan Review Loop (required)
+
+After each plan chunk:
+
+1. Review for completeness, scope alignment, actionable decomposition, and verification quality.
+2. Fix identified issues in the same chunk.
+3. Re-review until the chunk is implementation-ready.
+
+Suggested chunking: use `## Chunk N: <name>` headings for large plans.
+
+## Completion Handoff
+
+When done, state where the plan is stored in basic-memory (for example `plans/<name>`) and whether execution should proceed via:
+- `subagent-driven-development` (preferred when available), or
+- `executing-plans` (single-agent execution).