From ffa21e07ced7f0f771a44fd29af9a477e00d2572 Mon Sep 17 00:00:00 2001 From: alex Date: Wed, 11 Mar 2026 11:38:57 +0000 Subject: [PATCH] feat: add plan and review workflow skills --- .../dispatching-parallel-agents/SKILL.md | 50 ++++++++++ .../opencode/skills/executing-plans/SKILL.md | 64 +++++++++++++ .../skills/receiving-code-review/SKILL.md | 53 ++++++++++ .../skills/requesting-code-review/SKILL.md | 61 ++++++++++++ .../skills/requesting-code-review/reviewer.md | 49 ++++++++++ .../subagent-driven-development/SKILL.md | 96 +++++++++++++++++++ .../opencode/skills/writing-plans/SKILL.md | 95 ++++++++++++++++++ 7 files changed, 468 insertions(+) create mode 100644 .config/opencode/skills/dispatching-parallel-agents/SKILL.md create mode 100644 .config/opencode/skills/executing-plans/SKILL.md create mode 100644 .config/opencode/skills/receiving-code-review/SKILL.md create mode 100644 .config/opencode/skills/requesting-code-review/SKILL.md create mode 100644 .config/opencode/skills/requesting-code-review/reviewer.md create mode 100644 .config/opencode/skills/subagent-driven-development/SKILL.md create mode 100644 .config/opencode/skills/writing-plans/SKILL.md diff --git a/.config/opencode/skills/dispatching-parallel-agents/SKILL.md b/.config/opencode/skills/dispatching-parallel-agents/SKILL.md new file mode 100644 index 0000000..a25c5ed --- /dev/null +++ b/.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 " +- `task`: "Investigate and fix failures in " + +## 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. diff --git a/.config/opencode/skills/executing-plans/SKILL.md b/.config/opencode/skills/executing-plans/SKILL.md new file mode 100644 index 0000000..fbf98a6 --- /dev/null +++ b/.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/`). +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 diff --git a/.config/opencode/skills/receiving-code-review/SKILL.md b/.config/opencode/skills/receiving-code-review/SKILL.md new file mode 100644 index 0000000..dfcb08a --- /dev/null +++ b/.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. diff --git a/.config/opencode/skills/requesting-code-review/SKILL.md b/.config/opencode/skills/requesting-code-review/SKILL.md new file mode 100644 index 0000000..9aaaba9 --- /dev/null +++ b/.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/` 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` diff --git a/.config/opencode/skills/requesting-code-review/reviewer.md b/.config/opencode/skills/requesting-code-review/reviewer.md new file mode 100644 index 0000000..db477ec --- /dev/null +++ b/.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 + + + +## Requirements / Plan + +- Plan note: `plans/` +- Requirements summary: + - + - + +## Summary + + + +## Diff Context + +- Base: +- Head: +- Range: `..` +- Key files: + - + - + +```bash +git diff --stat .. +git diff .. +``` + +## 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. diff --git a/.config/opencode/skills/subagent-driven-development/SKILL.md b/.config/opencode/skills/subagent-driven-development/SKILL.md new file mode 100644 index 0000000..aee378d --- /dev/null +++ b/.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/` 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. diff --git a/.config/opencode/skills/writing-plans/SKILL.md b/.config/opencode/skills/writing-plans/SKILL.md new file mode 100644 index 0000000..ec67a35 --- /dev/null +++ b/.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/` +- 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: `` and confirm expected failure +- [ ] Step 3: Implement minimal code for [specific behavior] +- [ ] Step 4: Run: `` and confirm pass +- [ ] Step 5: Run broader verification: `` +```` + +## 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: ` headings for large plans. + +## Completion Handoff + +When done, state where the plan is stored in basic-memory (for example `plans/`) and whether execution should proceed via: +- `subagent-driven-development` (preferred when available), or +- `executing-plans` (single-agent execution).