From 57f577980e07f7851dff9be4d9e1c2e5a3b6963b Mon Sep 17 00:00:00 2001 From: alex Date: Wed, 11 Mar 2026 11:27:40 +0000 Subject: [PATCH 1/3] feat: strengthen git workflow skill guidance --- .config/opencode/skills/git-workflow/SKILL.md | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/.config/opencode/skills/git-workflow/SKILL.md b/.config/opencode/skills/git-workflow/SKILL.md index e064125..b7404e5 100644 --- a/.config/opencode/skills/git-workflow/SKILL.md +++ b/.config/opencode/skills/git-workflow/SKILL.md @@ -33,9 +33,17 @@ permalink: opencode-config/skills/git-workflow/skill ### Creating a worktree for a new feature: ```bash # From project root +mkdir -p .worktrees +git check-ignore -q .worktrees || { printf "Add .worktrees/ to .gitignore before continuing.\n"; exit 1; } git worktree add .worktrees/ -b ``` +Before starting feature implementation in the new worktree: +- Verify `.worktrees/` is the project-local location and ignored by git before creating or reusing worktrees. +- Run project-declared setup/config scripts if the worktree needs dependencies or generated files. +- Run a baseline verification (project-declared check/test/lint scripts) to confirm the branch is clean before making changes. +- If baseline verification fails, stop and diagnose the environment or branch state before coding. + ### Creating multiple worktrees for independent workstreams: ```bash # From project root — create all worktrees upfront @@ -48,13 +56,29 @@ git worktree add .worktrees/ -b feat/ - Example: `workdir="/path/to/project/.worktrees/my-feature"` for all bash commands. - **Each coder invocation must target a specific worktree** — never mix worktrees in one coder dispatch. -### Completing a worktree: +### After implementation and tests pass: choose one finish path + +1. **Merge locally** + - Merge `` into your tracked/current base branch, then remove the feature worktree. + - If the branch is fully integrated and no longer needed, delete it. +2. **Push and open PR** + - Push `` and create a PR to the base branch using the GitHub PR procedure below. + - Keep the worktree until review/merge is complete, then remove the worktree and delete the merged branch. +3. **Keep branch/worktree for later** + - Leave branch and worktree in place when work is paused or awaiting input. + - Record the next step and expected resume point so cleanup is not forgotten. +4. **Discard work (destructive)** + - Only for work you explicitly want to throw away. + - Require typed confirmation before running destructive commands: `Type exactly: DISCARD `. + - After confirmation, remove the worktree and force-delete the unmerged branch with `git branch -D `; this cannot be undone from git alone once commits are unreachable. + +### Example local-merge cleanup flow: ```bash -# From main working tree -git checkout main +# From the primary working tree +git checkout git merge git worktree remove .worktrees/ -git branch -d # optional cleanup +git branch -d # optional cleanup when fully merged ``` ### Completing multiple worktrees (independent PRs): From e03234a0df20c61c277c07467a99db818a28c0bc Mon Sep 17 00:00:00 2001 From: alex Date: Wed, 11 Mar 2026 11:27:40 +0000 Subject: [PATCH 2/3] feat: add verification and debugging workflow skills --- .../skills/systematic-debugging/SKILL.md | 92 +++++++++++++++++++ .../condition-based-waiting.md | 68 ++++++++++++++ .../systematic-debugging/defense-in-depth.md | 64 +++++++++++++ .../root-cause-tracing.md | 66 +++++++++++++ .../skills/test-driven-development/SKILL.md | 77 ++++++++++++++++ .../testing-anti-patterns.md | 83 +++++++++++++++++ .../verification-before-completion/SKILL.md | 47 ++++++++++ 7 files changed, 497 insertions(+) create mode 100644 .config/opencode/skills/systematic-debugging/SKILL.md create mode 100644 .config/opencode/skills/systematic-debugging/condition-based-waiting.md create mode 100644 .config/opencode/skills/systematic-debugging/defense-in-depth.md create mode 100644 .config/opencode/skills/systematic-debugging/root-cause-tracing.md create mode 100644 .config/opencode/skills/test-driven-development/SKILL.md create mode 100644 .config/opencode/skills/test-driven-development/testing-anti-patterns.md create mode 100644 .config/opencode/skills/verification-before-completion/SKILL.md diff --git a/.config/opencode/skills/systematic-debugging/SKILL.md b/.config/opencode/skills/systematic-debugging/SKILL.md new file mode 100644 index 0000000..6ef2731 --- /dev/null +++ b/.config/opencode/skills/systematic-debugging/SKILL.md @@ -0,0 +1,92 @@ +--- +name: systematic-debugging +description: Use when encountering bugs, test failures, or unexpected behavior before proposing fixes +permalink: opencode-config/skills/systematic-debugging/skill +--- + +# Systematic Debugging + +## Overview + +Random fix attempts create churn and often introduce new issues. + +**Core principle:** always identify root cause before attempting fixes. + +## The Iron Law + +``` +NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST +``` + +If Phase 1 is incomplete, do not propose or implement fixes. + +## When to Use + +Use for any technical issue: +- Test failures +- Unexpected runtime behavior +- Build or CI failures +- Integration breakages +- Performance regressions + +Use this especially when: +- You are under time pressure +- A "quick patch" seems obvious +- Previous fix attempts did not work +- You do not yet understand why the issue occurs + +## Four-Phase Process + +Complete each phase in order. + +### Phase 1: Root-Cause Investigation + +1. Read error messages and stack traces fully. +2. Reproduce the issue reliably with exact steps. +3. Check recent changes (code, config, dependency, environment). +4. Gather evidence at component boundaries (inputs, outputs, config propagation). +5. Trace data flow backward to the original trigger. + +For deeper tracing techniques, see `root-cause-tracing.md`. + +### Phase 2: Pattern Analysis + +1. Find similar working code in the same repository. +2. Compare broken and working paths line by line. +3. List all differences, including small ones. +4. Identify required dependencies and assumptions. + +### Phase 3: Hypothesis and Minimal Testing + +1. State one concrete hypothesis: "X is failing because Y". +2. Make the smallest possible change to test only that hypothesis. +3. Verify result before making any additional changes. +4. If the test fails, form a new hypothesis from new evidence. + +### Phase 4: Fix and Verify + +1. Create a minimal failing reproduction (automated test when possible). +2. Implement one fix targeting the identified root cause. +3. Verify the issue is resolved and no regressions were introduced. +4. If fix attempts keep failing, stop and reassess design assumptions. + +## Red Flags (Stop and Restart at Phase 1) + +- "Let me try this quick fix first" +- "I’ll batch several changes and see what works" +- "It probably is X" +- Proposing solutions before tracing the data flow +- Continuing repeated fix attempts without new evidence + +## Supporting Techniques + +Use these companion references while executing this process: + +- `root-cause-tracing.md` — trace failures backward through the call chain +- `condition-based-waiting.md` — replace arbitrary sleeps with condition polling +- `defense-in-depth.md` — add layered validation so recurrence is harder + +## Related Skills + +- `test-driven-development` — build minimal failing tests and iterate safely +- `verification-before-completion` — confirm behavior end-to-end before claiming done diff --git a/.config/opencode/skills/systematic-debugging/condition-based-waiting.md b/.config/opencode/skills/systematic-debugging/condition-based-waiting.md new file mode 100644 index 0000000..8318296 --- /dev/null +++ b/.config/opencode/skills/systematic-debugging/condition-based-waiting.md @@ -0,0 +1,68 @@ +--- +title: condition-based-waiting +type: note +permalink: opencode-config/skills/systematic-debugging/condition-based-waiting +--- + +# Condition-Based Waiting + +## Overview + +Arbitrary sleep durations create flaky tests and race conditions. + +**Core principle:** wait for the condition that proves readiness, not a guessed delay. + +## When to Use + +Use this when: +- Tests rely on `sleep` or fixed `setTimeout` delays +- Asynchronous operations complete at variable speeds +- Tests pass locally but fail in CI or under load + +Avoid arbitrary waits except when explicitly validating timing behavior (for example, debounce intervals), and document why timing-based waiting is necessary. + +## Core Pattern + +```ts +// ❌ Timing guess +await new Promise((r) => setTimeout(r, 100)); + +// ✅ Condition wait +await waitFor(() => getState() === 'ready', 'state ready'); +``` + +## Generic Helper + +```ts +async function waitFor( + condition: () => T | false | undefined | null, + description: string, + timeoutMs = 5000, + pollMs = 10 +): Promise { + const started = Date.now(); + + while (true) { + const result = condition(); + if (result) return result; + + if (Date.now() - started > timeoutMs) { + throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`); + } + + await new Promise((r) => setTimeout(r, pollMs)); + } +} +``` + +## Practical Guidance + +- Keep polling intervals modest (for example, 10ms) to avoid hot loops. +- Always include a timeout and actionable error message. +- Query fresh state inside the loop; do not cache stale values outside it. + +## Common Mistakes + +- Polling too aggressively (high CPU, little benefit) +- Waiting forever without timeout +- Mixing arbitrary delays and condition checks without rationale diff --git a/.config/opencode/skills/systematic-debugging/defense-in-depth.md b/.config/opencode/skills/systematic-debugging/defense-in-depth.md new file mode 100644 index 0000000..3fd4727 --- /dev/null +++ b/.config/opencode/skills/systematic-debugging/defense-in-depth.md @@ -0,0 +1,64 @@ +--- +title: defense-in-depth +type: note +permalink: opencode-config/skills/systematic-debugging/defense-in-depth +--- + +# Defense in Depth + +## Overview + +A single validation check can be bypassed by alternate paths, refactors, or test setup differences. + +**Core principle:** add validation at multiple layers so one missed check does not recreate the same failure. + +## Layered Validation Model + +### Layer 1: Entry Validation +Reject obviously invalid input at boundaries (CLI/API/public methods). + +### Layer 2: Business-Logic Validation +Re-validate assumptions where operations are performed. + +### Layer 3: Environment Guards +Block dangerous operations in sensitive contexts (for example, test/runtime safety guards). + +### Layer 4: Diagnostic Context +Emit enough structured debug information to support future root-cause analysis. + +## Applying the Pattern + +1. Trace real data flow from entry to failure. +2. Mark all checkpoints where invalid state could be detected. +3. Add targeted validation at each relevant layer. +4. Verify each layer can catch invalid input independently. + +## Example Shape + +```ts +function createWorkspace(path: string) { + // Layer 1: entry + if (!path || path.trim() === '') { + throw new Error('path is required'); + } + + // Layer 2: operation-specific + if (!isPathAllowed(path)) { + throw new Error(`path not allowed: ${path}`); + } +} + +async function dangerousOperation(path: string) { + // Layer 3: environment guard + if (process.env.NODE_ENV === 'test' && !isSafeTestPath(path)) { + throw new Error(`refusing unsafe path in test mode: ${path}`); + } + + // Layer 4: diagnostic context + console.error('operation context', { path, cwd: process.cwd(), stack: new Error().stack }); +} +``` + +## Key Outcome + +Root-cause fixes prevent recurrence at the origin. Layered validation reduces the chance that adjacent paths can reintroduce the same class of bug. diff --git a/.config/opencode/skills/systematic-debugging/root-cause-tracing.md b/.config/opencode/skills/systematic-debugging/root-cause-tracing.md new file mode 100644 index 0000000..d1f052b --- /dev/null +++ b/.config/opencode/skills/systematic-debugging/root-cause-tracing.md @@ -0,0 +1,66 @@ +--- +title: root-cause-tracing +type: note +permalink: opencode-config/skills/systematic-debugging/root-cause-tracing +--- + +# Root-Cause Tracing + +## Overview + +Many bugs appear deep in a stack trace, but the origin is often earlier in the call chain. + +**Core principle:** trace backward to the original trigger, then fix at the source. + +## When to Use + +Use this when: +- The symptom appears far from where bad input was introduced +- The call chain spans multiple layers or components +- You can see failure but cannot yet explain origin + +## Tracing Process + +1. **Capture the symptom clearly** + - Exact error text, stack frame, and context. + +2. **Find immediate failure point** + - Identify the exact operation that throws or misbehaves. + +3. **Walk one frame up** + - Determine who called it and with which values. + +4. **Repeat until source** + - Continue tracing callers and values backward until you find where invalid state/data originated. + +5. **Fix at source** + - Correct the earliest trigger rather than patching downstream symptoms. + +## Instrumentation Tips + +When manual tracing is hard, add targeted instrumentation before the risky operation: + +```ts +const stack = new Error().stack; +console.error('debug context', { + input, + cwd: process.cwd(), + envMode: process.env.NODE_ENV, + stack, +}); +``` + +Guidelines: +- Log before failure-prone operations, not after. +- Include values that influence behavior. +- Capture stack traces for call-path evidence. + +## Common Mistake + +**Mistake:** fixing where the error appears because it is visible. + +**Better:** trace backward and fix where incorrect state is first introduced. + +## Pair with Layered Defenses + +After fixing the source, apply layered validation from `defense-in-depth.md` so similar failures are blocked earlier in the future. diff --git a/.config/opencode/skills/test-driven-development/SKILL.md b/.config/opencode/skills/test-driven-development/SKILL.md new file mode 100644 index 0000000..f4b0506 --- /dev/null +++ b/.config/opencode/skills/test-driven-development/SKILL.md @@ -0,0 +1,77 @@ +--- +name: test-driven-development +description: Enforce test-first development for features and bug fixes — no production + code before a failing test +permalink: opencode-config/skills/test-driven-development/skill +--- + +# Test-Driven Development (TDD) + +## When to Use + +Use this skill when implementing behavior changes: +- New features +- Bug fixes +- Refactors that alter behavior + +If the work introduces or changes production behavior, TDD applies. + +## Core Rule + +``` +NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST +``` + +If production code was written first, delete or revert it and restart from a failing test. + +## Red → Green → Refactor Loop + +### 1) RED: Write one failing test +- Write one small test that expresses the next expected behavior. +- Prefer clear test names describing observable behavior. +- Use real behavior paths where practical; mock only when isolation is required. + +### 2) Verify RED (mandatory) +Run the new test and confirm: +- It fails (not just errors) +- It fails for the expected reason +- It fails because behavior is missing, not because the test is broken + +If it passes immediately, the test is not proving the new behavior. Fix the test first. + +### 3) GREEN: Add minimal production code +- Implement only enough code to make the failing test pass. +- Do not add extra features, abstractions, or speculative options. + +### 4) Verify GREEN (mandatory) +Run the test suite scope needed for confidence: +- New test passes +- Related tests still pass + +If failures appear, fix production code first unless requirements changed. + +### 5) REFACTOR +- Improve names, remove duplication, and simplify structure. +- Keep behavior unchanged. +- Keep tests green throughout. + +Repeat for the next behavior. + +## Quality Checks Before Completion + +- [ ] Each behavior change has a test that failed before implementation +- [ ] New tests failed for the expected reason first +- [ ] Production code was added only after RED was observed +- [ ] Tests now pass cleanly +- [ ] Edge cases for changed behavior are covered + +## Practical Guardrails + +- "I'll write tests after" is not TDD. +- Manual verification does not replace automated failing-then-passing tests. +- If a test is hard to write, treat it as design feedback and simplify interfaces. +- Keep test intent focused on behavior, not internals. + +## Related Reference + +For common mistakes around mocks and test design, see [testing-anti-patterns](./testing-anti-patterns.md). diff --git a/.config/opencode/skills/test-driven-development/testing-anti-patterns.md b/.config/opencode/skills/test-driven-development/testing-anti-patterns.md new file mode 100644 index 0000000..1e0c5fc --- /dev/null +++ b/.config/opencode/skills/test-driven-development/testing-anti-patterns.md @@ -0,0 +1,83 @@ +--- +title: testing-anti-patterns +type: note +permalink: opencode-config/skills/test-driven-development/testing-anti-patterns +--- + +# Testing Anti-Patterns + +Use this reference when writing/changing tests, introducing mocks, or considering test-only production APIs. + +## Core Principle + +Test real behavior, not mock behavior. + +Mocks are isolation tools, not the subject under test. + +## Anti-Pattern 1: Testing mock existence instead of behavior + +**Problem:** Assertions only prove a mock rendered or was called, not that business behavior is correct. + +**Fix:** Assert observable behavior of the unit/system under test. If possible, avoid mocking the component being validated. + +Gate check before assertions on mocked elements: +- Am I validating system behavior or only that a mock exists? +- If only mock existence, rewrite the test. + +## Anti-Pattern 2: Adding test-only methods to production code + +**Problem:** Production classes gain methods used only by tests (cleanup hooks, debug helpers), polluting real APIs. + +**Fix:** Move test-only setup/cleanup into test utilities or fixtures. + +Gate check before adding a production method: +- Is this method needed in production behavior? +- Is this resource lifecycle actually owned by this class? +- If not, keep it out of production code. + +## Anti-Pattern 3: Mocking without understanding dependencies + +**Problem:** High-level mocks remove side effects the test depends on, causing false positives/negatives. + +**Fix:** Understand dependency flow first, then mock the lowest-cost external boundary while preserving needed behavior. + +Gate check before adding a mock: +1. What side effects does the real method perform? +2. Which side effects does this test rely on? +3. Can I mock a lower-level boundary instead? + +If unsure, run against real implementation first, then add minimal mocking. + +## Anti-Pattern 4: Incomplete mock structures + +**Problem:** Mocks include only fields used immediately, omitting fields consumed downstream. + +**Fix:** Mirror complete response/object shapes used in real flows. + +Gate check for mocked data: +- Does this mock match the real schema/shape fully enough for downstream consumers? +- If uncertain, include the full documented structure. + +## Anti-Pattern 5: Treating tests as a follow-up phase + +**Problem:** "Implementation complete, tests later" breaks TDD and reduces confidence. + +**Fix:** Keep tests inside the implementation loop: +1. Write failing test +2. Implement minimum code +3. Re-run tests +4. Refactor safely + +## Quick Red Flags + +- Assertions target `*-mock` markers rather than behavior outcomes +- Methods exist only for tests in production classes +- Mock setup dominates test logic +- You cannot explain why each mock is necessary +- Tests are written only after code "already works" + +## Bottom Line + +If a test does not fail first for the intended reason, it is not validating the behavior change reliably. + +Keep TDD strict: failing test first, then minimal code. diff --git a/.config/opencode/skills/verification-before-completion/SKILL.md b/.config/opencode/skills/verification-before-completion/SKILL.md new file mode 100644 index 0000000..77fe80c --- /dev/null +++ b/.config/opencode/skills/verification-before-completion/SKILL.md @@ -0,0 +1,47 @@ +--- +name: verification-before-completion +description: Require fresh verification evidence before any completion or success claim +permalink: opencode-config/skills/verification-before-completion/skill +--- + +## When to Load + +Load this skill immediately before claiming work is complete, fixed, or passing. + +## Core Rule + +``` +NO COMPLETION OR SUCCESS CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE +``` + +If you did not run the relevant verification command for this change, do not claim success. + +## Verification Gate + +Before any completion statement: + +1. **Identify** the exact command that proves the claim. +2. **Run** the full command now (no cached or earlier output). +3. **Check** exit code and output details (failure count, errors, warnings as relevant). +4. **Report** the result with concrete evidence. + - If verification fails, report failure status and next fix step. + - If verification passes, state success and include proof. + +## Common Proof Examples + +- **Tests pass** → fresh test run shows expected suite and zero failures. +- **Lint is clean** → fresh lint run shows zero errors. +- **Build succeeds** → fresh build run exits 0. +- **Bug is fixed** → reproduction scenario now passes after the fix. +- **Requirements are met** → checklist is re-verified against the implemented result. + +## Anti-patterns + +- "Should pass" / "probably fixed" / "looks good" +- claiming completion from partial checks +- relying on old command output +- trusting status reports without independent verification + +## Bottom Line + +Run the right command, inspect the output, then make the claim. From ffa21e07ced7f0f771a44fd29af9a477e00d2572 Mon Sep 17 00:00:00 2001 From: alex Date: Wed, 11 Mar 2026 11:38:57 +0000 Subject: [PATCH 3/3] 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).