skills: add writing-implementation-plans, receiving-code-review, finishing-development-branches

Evaluated obra/superpowers and JuliusBrussee/caveman for gaps in the existing library. These three fill real ones (plan-to-delegate handoff, evidence-based review triage, completion vs. integration authority); adapted for this fleet's Gitea/RLS/multi-delegate conventions. Everything else in both repos duplicated existing skills or didn't fit (see README Provenance note on caveman). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-11 13:21:03 +02:00
parent fa7c367420
commit c7ce105e00
4 changed files with 326 additions and 1 deletions
@@ -92,6 +92,14 @@ than assuming the delegate can fetch it itself.
  rebase conflict by tracing each side's intent; never `--abort`.
 - `tdd` -- red-green-refactor test-driven development, one vertical slice
  at a time, at pre-agreed seams.
+- `writing-implementation-plans` -- turn settled requirements into
+  self-contained, dependency-aware tasks that memoryless delegates can
+  execute and verify without the originating conversation.
+- `receiving-code-review` -- verify incoming review findings against the
+  actual codebase and spec before accepting, rejecting, or implementing them.
+- `finishing-development-branches` -- verify the exact branch tip, confirm
+  its base, and require an explicit integration choice before merge, Gitea
+  push/PR, or cleanup.

 ## Provenance

@@ -105,6 +113,8 @@ each skill's frontmatter:
 - [Mte90/linus-torvalds-skill](https://github.com/Mte90/linus-torvalds-skill) (CC0-1.0)
 - [mattpocock/skills](https://github.com/mattpocock/skills) (MIT)
 - [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) (MIT)
+- [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) (MIT;
+  evaluated, no skill retained)

 ## Vetting external skills

@@ -125,4 +135,4 @@ When a real, non-obvious pattern or gotcha comes up more than once,
 write it down here rather than re-discovering it next time. Keep each
 skill focused on one concern, include the *why* (not just the *what*) so
 future edge cases can be judged sensibly, and prefer concrete confirmed
-incidents over generic advice.
+incidents over generic advice.
@@ -0,0 +1,113 @@
+---
+name: finishing-development-branches
+description: Use after implementation is complete and before merging, pushing, opening a Gitea pull request, or cleaning up a feature branch or worktree.
+license: MIT
+source: https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md
+---
+
+# Finishing Development Branches
+
+Completion and integration are different decisions. A green feature branch
+does not authorise merging, pushing, deleting branches, or removing worktrees.
+Verify the exact tree, identify its provenance, then let the user choose the
+integration action.
+
+## 1. Establish the state
+
+From the feature workspace, record:
+
+```bash
+git status --short
+git branch --show-current
+git rev-parse HEAD
+git rev-parse --show-toplevel
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git remote -v
+```
+
+Determine the intended base branch from the brief, branch upstream, merge
+base, or conversation. If it is not confirmed, ask. Do not assume `main`.
+
+Stop if the tree contains unexplained changes. They may belong to the user or
+another delegate; do not stage, discard, or fold them into the integration.
+
+## 2. Verify the branch tip
+
+Run the project’s required targeted and full regression checks on the current
+`HEAD`. Read their actual output. For higher-risk changes, run the relevant
+end-to-end path as required by `verification-before-completion`.
+
+Also inspect what will integrate:
+
+```bash
+git log --oneline <base>..HEAD
+git diff --check <base>...HEAD
+git diff --stat <base>...HEAD
+```
+
+If a check fails, report the failure and stop. Do not offer integration of a
+known-red branch.
+
+## 3. Present the integration choices
+
+Report the confirmed base, branch/commit, test evidence, and whether this is a
+linked worktree. Then offer only applicable choices:
+
+1. Merge locally into the confirmed base.
+2. Push the feature branch and open a Gitea pull request.
+3. Keep the branch and workspace unchanged for later review.
+
+Wait for the user’s choice. Do not infer permission to push or merge from a
+request to implement or commit. Never offer deletion as routine cleanup.
+
+## 4. Execute only the chosen action
+
+### Merge locally
+
+Before pulling or contacting a remote, confirm that updating the base from the
+remote is wanted. From the primary checkout:
+
+```bash
+git switch <base>
+git merge <feature-branch>
+```
+
+Do not use a strategy flag merely to avoid conflicts. If conflicts occur,
+follow `resolving-merge-conflicts`; never abort the merge/rebase. Re-run the
+full verification suite on the merged tree because the result is a different
+tree from the tested feature tip.
+
+### Push and create a Gitea pull request
+
+Confirm the remote and branch names before pushing. Never force-push to solve
+a rejection; inspect the remote divergence and ask if rewriting remote history
+would be required. Follow repository/Gitea templates and report the pull
+request URL. Keep the feature workspace for review fixes.
+
+### Keep as-is
+
+Report the branch name, commit, and full workspace path. Make no cleanup
+changes.
+
+## 5. Cleanup is separately authorised
+
+Remove a linked worktree or delete a branch only after its work is safely
+integrated, or after the user explicitly asks to discard it. Before a discard,
+show the exact branch, worktree path, and commits that would become
+unreferenced; require an explicit confirmation naming those targets.
+
+Never clean unrelated or merely “stale-looking” worktrees. Never use
+force-deletion for normal cleanup. After any authorised cleanup, verify with
+`git worktree list` and `git branch --list` and report what was removed.
+
+## Stop conditions
+
+Stop and preserve all state when:
+
+- tests or merged-result verification fail;
+- the base branch is uncertain;
+- the remote has diverged;
+- conflicts are unresolved;
+- the tree contains unexplained changes;
+- the requested action would delete or rewrite work without explicit consent.
@@ -0,0 +1,89 @@
+---
+name: receiving-code-review
+description: Use when acting on code-review findings from a human or delegate, especially when feedback is ambiguous, technically questionable, or may conflict with the specification or existing behavior.
+license: MIT
+source: https://github.com/obra/superpowers/blob/main/skills/receiving-code-review/SKILL.md
+---
+
+# Receiving Code Review
+
+Review feedback is a claim to investigate, not a patch queue to apply blindly.
+The reviewer may have missed codebase context; the implementer may be biased
+toward defending their own work. Resolve both risks with evidence.
+
+## Triage the complete review first
+
+For every finding, record:
+
+- exact file/line and the claimed failure;
+- severity and whether it blocks the stated requirements;
+- the reviewer’s proposed fix, if any;
+- whether the finding is clear, verified, disputed, or needs a decision.
+
+Read all findings before editing. Items can depend on each other, and fixing a
+clear symptom before understanding a related architectural concern can create
+rework.
+
+## Verify against this codebase
+
+For each material finding:
+
+1. Restate the falsifiable claim: what input or state should produce what bad
+   result?
+2. Inspect the cited code plus its callers, tests, compatibility constraints,
+   and relevant specification.
+3. Reproduce the problem or add the cheapest check that distinguishes a real
+   defect from a false positive.
+4. Decide whether the proposed fix addresses the root cause without breaking
+   existing behavior, tenant isolation, platform support, or scope.
+
+For multi-tenant changes, explicitly test a cross-tenant negative case; a
+query that returns the expected row for one tenant does not prove RLS safety.
+For WordPress or infrastructure changes, verify the actual runtime convention
+instead of substituting a generic framework preference.
+
+If a finding cannot be verified with available access or artifacts, say
+exactly what evidence is missing. Do not silently convert uncertainty into an
+implementation decision.
+
+## Resolve conflicts before editing
+
+- If the finding is unclear, ask one concrete question and do not guess at the
+  requested behavior.
+- If it conflicts with the approved spec or a prior user decision, present the
+  conflicting texts and ask which governs.
+- If it requests unused “professional” machinery, search for actual callers
+  and requirements first; reject scope growth that has no consumer.
+- If it is technically wrong, push back with code, tests, or runtime evidence.
+  Do not comply merely because the reviewer sounds confident.
+- If it is correct, fix it without performative agreement. State the verified
+  problem and the change.
+
+## Implement and close findings one at a time
+
+Order work by security/data-loss defects, other blocking correctness defects,
+then non-blocking improvements. For each accepted finding:
+
+1. Create or identify a check that fails for the reported problem.
+2. Apply the smallest in-scope fix.
+3. Re-run the targeted check and relevant regression tests.
+4. Record the evidence and mark only that finding resolved.
+
+Do not let the implementer’s self-review close the loop. A fresh reviewer (or
+the lead model) must inspect the fix diff, and `verification-before-completion`
+still applies before reporting the review resolved.
+
+## Response format
+
+Keep the response technical:
+
+```text
+Finding: <location and claim>
+Verdict: accepted | rejected | needs decision | unverified
+Evidence: <test, code path, or missing access>
+Action: <fix made, reason no change was made, or exact question>
+Verification: <command and result, if changed>
+```
+
+Avoid gratitude, defensiveness, or automatic agreement. The useful output is
+a traceable decision backed by evidence.
@@ -0,0 +1,113 @@
+---
+name: writing-implementation-plans
+description: Use when requirements are settled and a multi-step change needs an implementation plan that memoryless delegates can execute without access to the originating conversation.
+license: MIT
+source: https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md
+---
+
+# Writing Implementation Plans
+
+A plan is an executable handoff, not a summary of intent. The worker may be a
+fresh CLI delegate with no conversation history, and individual tasks may be
+assigned out of order. If the plan leaves a choice implicit, the worker will
+have to invent it.
+
+## Before writing tasks
+
+1. Read the settled spec or requirements and inspect the actual code paths,
+   tests, project instructions, and established patterns involved.
+2. Resolve contradictions and material unknowns before planning. Marking them
+   `TBD` only moves the design decision to a less-informed delegate.
+3. Map every file to create or modify and give each one a clear
+   responsibility. Avoid unrelated restructuring.
+4. Split work into independently testable vertical slices. Fold setup,
+   migrations, wiring, and documentation into the slice that needs them;
+   don't create standalone tasks that leave the system unusable.
+5. Identify shared files and state. Tasks that edit the same bootstrap file,
+   schema, migration sequence, or live environment are sequential unless the
+   design removes that collision. See `parallel-delegate-shared-files`.
+
+## Plan header
+
+Start with:
+
+```markdown
+# <Feature> Implementation Plan
+
+**Goal:** <one sentence>
+
+**Architecture:** <two or three sentences describing the approach and boundaries>
+
+**Stack and environment:** <relevant runtimes, services, jail/container, database>
+
+## Global constraints
+
+- <exact version, naming, compatibility, security, tenant-isolation, and scope rules>
+
+## Verification
+
+- <commands for targeted tests, full regression tests, and any real end-to-end check>
+```
+
+Copy exact values from the requirements. For multi-tenant work, state the
+tenant/RLS invariants explicitly; never let a worker infer them from nearby
+code. For remote or production-adjacent work, state the exact host/jail,
+whether mutation is authorised, and how secrets must be read without being
+printed.
+
+## Task contract
+
+Each task must stand alone:
+
+```markdown
+### Task N: <independently testable outcome>
+
+**Depends on:** <prior task outputs, or "none">
+
+**Files:**
+- Create: `exact/path`
+- Modify: `exact/path` — <symbol or section>
+- Test: `exact/path`
+
+**Interfaces:**
+- Consumes: <exact names, signatures, schemas, or artifacts>
+- Produces: <exact names, signatures, schemas, or artifacts>
+
+**Requirements:**
+- <observable behavior and edge cases>
+
+**Steps:**
+- [ ] Write the failing test for <behavior>.
+- [ ] Run `<targeted command>`; expect <specific failure proving the test is red-capable>.
+- [ ] Implement the smallest change that passes it.
+- [ ] Run `<targeted command>`; expect <specific success>.
+- [ ] Run `<broader command>`; expect no regressions.
+- [ ] Commit only this task's files with `<message or project convention>`.
+
+**Report:** <facts and evidence the delegate must return>
+```
+
+Write exact commands and concrete expected signals. Include code or
+pseudocode only where it removes a real ambiguity; don't turn the plan into a
+second implementation. When a task brief will be extracted from the plan,
+repeat its binding constraints instead of saying “same as above.”
+
+## Self-review before delegation
+
+- Trace every requirement to a task and every task to the goal. Remove gaps
+  and scope creep.
+- Search for placeholders and vague steps: `TBD`, `TODO`, “handle errors,”
+  “add validation,” “write tests,” “similar to Task N.” Replace each with an
+  explicit decision or action.
+- Check that interface names and types match across tasks.
+- Check ordering: a task must not consume an artifact that does not exist yet.
+- Check concurrency: no parallel tasks may edit the same file or mutate the
+  same shared environment.
+- Check verification: every claimed outcome has a command or observation that
+  could prove it false.
+- Have the user approve material architectural or scope decisions before
+  implementation begins.
+
+When dispatching tasks, still apply `delegate-brief-writing`: the extracted
+task plus relevant global constraints, confirmed facts, credentials handling,
+verification, and report contract form the self-contained brief.