From 73116199b7787ea70f383a16ae44d298048b234b Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 4 Jul 2026 12:36:06 -0400 Subject: [PATCH] feat(directives): scavenge superpowers plugin (finishing-a-development-branch, verification-before-completion, writing-plans): 5 directives --- .../evidence_before_completion_claims/meta.md | 8 +++ .../evidence_before_completion_claims/v1.md | 44 +++++++++++++++ .../exactly_four_completion_options/meta.md | 8 +++ .../exactly_four_completion_options/v1.md | 53 +++++++++++++++++++ .../plan_steps_2_to_5_minutes_each/meta.md | 8 +++ .../plan_steps_2_to_5_minutes_each/v1.md | 28 ++++++++++ .../plans_no_placeholders_or_tbds/meta.md | 8 +++ .../plans_no_placeholders_or_tbds/v1.md | 30 +++++++++++ .../directives/presets/current_baseline.md | 14 ++++- .../meta.md | 8 +++ .../v1.md | 41 ++++++++++++++ 11 files changed, 248 insertions(+), 2 deletions(-) create mode 100644 conductor/directives/evidence_before_completion_claims/meta.md create mode 100644 conductor/directives/evidence_before_completion_claims/v1.md create mode 100644 conductor/directives/exactly_four_completion_options/meta.md create mode 100644 conductor/directives/exactly_four_completion_options/v1.md create mode 100644 conductor/directives/plan_steps_2_to_5_minutes_each/meta.md create mode 100644 conductor/directives/plan_steps_2_to_5_minutes_each/v1.md create mode 100644 conductor/directives/plans_no_placeholders_or_tbds/meta.md create mode 100644 conductor/directives/plans_no_placeholders_or_tbds/v1.md create mode 100644 conductor/directives/verify_tests_before_offering_completion_options/meta.md create mode 100644 conductor/directives/verify_tests_before_offering_completion_options/v1.md diff --git a/conductor/directives/evidence_before_completion_claims/meta.md b/conductor/directives/evidence_before_completion_claims/meta.md new file mode 100644 index 00000000..44800697 --- /dev/null +++ b/conductor/directives/evidence_before_completion_claims/meta.md @@ -0,0 +1,8 @@ +# evidence_before_completion_claims + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/verification-before-completion/SKILL.md`. The directive encodes the Iron Law (lines 17-21 "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE") plus the Gate Function (lines 24-37) and the Red Flags list. Counterweight to the LLM's training-data bias toward "should pass now" / "looks good" / "I think it's done" — premature satisfaction expressions that ship broken work to user debugging. +**Source:** superpowers plugin `skills/verification-before-completion/SKILL.md:17-37` (Iron Law + Gate Function) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/evidence_before_completion_claims/v1.md b/conductor/directives/evidence_before_completion_claims/v1.md new file mode 100644 index 00000000..6806450d --- /dev/null +++ b/conductor/directives/evidence_before_completion_claims/v1.md @@ -0,0 +1,44 @@ +# No completion claims without fresh verification evidence — "should work" / "looks good" / "probably fine" are lies, not hedges + +## The iron law + +The agent NEVER claims a test passes, a build succeeds, a bug is fixed, or a task is complete without having run the verification command in the SAME message and observed the output. "Should work now" / "Looks correct" / "Probably fine" / "I think it works" all count as making claims without evidence. The agent does not get to hedge its way past verification. + +Per `skills/verification-before-completion/SKILL.md:17-37` (The Iron Law + Gate Function): + +> ``` +> NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE +> ``` +> +> If you haven't run the verification command in this message, you cannot claim it passes. +> +> The Gate Function: +> +> ``` +> BEFORE claiming any status or expressing satisfaction: +> +> 1. IDENTIFY: What command proves this claim? +> 2. RUN: Execute the FULL command (fresh, complete) +> 3. READ: Full output, check exit code, count failures +> 4. VERIFY: Does output confirm the claim? +> - If NO: State actual status with evidence +> - If YES: State claim WITH evidence +> 5. ONLY THEN: Make the claim +> +> Skip any step = lying, not verifying +> ``` + +## Why + +The agent's training data biases toward agreement: if the user asks "is it done?", the agent says "yes" because the conversation feels complete and the tests "should" pass. This is dishonest. The user trusts the agent's word; the agent's word is built on a guess; the guess is wrong N% of the time; the user discovers the failure at the worst moment. + +The verification requirement is also a forcing function against premature "Great!", "Perfect!", "Done!" — satisfaction expressions before evidence. Per `skills/verification-before-completion/SKILL.md:55-56` (Red Flags): "Expressing satisfaction before verification ('Great!', 'Perfect!', 'Done!', etc.)" is a STOP signal. + +## What this means in practice + +- Every test claim is preceded by a test run in the same message. The user can see the `[34/34 pass]` output immediately before the claim. +- Every build claim is preceded by the build command's exit code. The exit code is the evidence, not the agent's belief. +- Every "fixed" claim is preceded by running the original symptom (not just the new code's own tests). The symptom may be a test or a manual repro. +- The agent does NOT aggregate ("all looks good") when the verification command output is ambiguous. Ambiguous = verify again, or run a more specific check. +- "I think it's done" is NEVER a valid answer. Either the verification output is in the message (and the claim follows) or the message says "I have not yet verified; running the check now" and the next message contains the evidence. +- This directive applies to ALL completion claims: agent → user, agent → another agent, agent → commit message ("fixed: closes #123" requires the test run, not just the code change). diff --git a/conductor/directives/exactly_four_completion_options/meta.md b/conductor/directives/exactly_four_completion_options/meta.md new file mode 100644 index 00000000..a43fe436 --- /dev/null +++ b/conductor/directives/exactly_four_completion_options/meta.md @@ -0,0 +1,8 @@ +# exactly_four_completion_options + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/finishing-a-development-branch/SKILL.md`. The directive encodes Step 4 (lines 66-93): present exactly 4 structured options (or 3 for detached HEAD); never an open-ended "what next?". Counterweight to the LLM default of "Implementation complete. What now?" which forces the user to enumerate options the agent could have listed. +**Source:** superpowers plugin `skills/finishing-a-development-branch/SKILL.md:66-93` (Step 4: Present Options) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/exactly_four_completion_options/v1.md b/conductor/directives/exactly_four_completion_options/v1.md new file mode 100644 index 00000000..ca545181 --- /dev/null +++ b/conductor/directives/exactly_four_completion_options/v1.md @@ -0,0 +1,53 @@ +# Present exactly 4 (or 3 for detached HEAD) structured completion options — never an open-ended "what next?" + +## The rule + +When implementation is complete and the tests pass, the agent presents a fixed menu of options: + +- Normal repo / named branch: **4 options** — (1) Merge to base, (2) Push and create PR, (3) Keep the branch as-is, (4) Discard this work. +- Detached HEAD: **3 options** — (1) Push as new branch and create PR, (2) Keep as-is, (3) Discard. + +The agent does NOT add a fifth "what next?", does NOT ask open-ended questions, does NOT propose custom alternatives in the same message. The user picks from the menu, or declines explicitly. Options 1-4 (or 1-3 for detached) are the entire menu, no explanation beyond the option text. + +Per `skills/finishing-a-development-branch/SKILL.md:66-93` (Step 4: Present Options): + +> **Normal repo and named-branch worktree — present exactly these 4 options:** +> +> ``` +> Implementation complete. What would you like to do? +> +> 1. Merge back to locally +> 2. Push and create a Pull Request +> 3. Keep the branch as-is (I'll handle it later) +> 4. Discard this work +> +> Which option? +> ``` +> +> **Detached HEAD — present exactly these 3 options:** +> +> ``` +> Implementation complete. You're on a detached HEAD (externally managed workspace). +> +> 1. Push as new branch and create a Pull Request +> 2. Keep as-is (I'll handle it later) +> 3. Discard this work +> +> Which option? +> ``` +> +> **Don't add explanation** - keep options concise. + +## Why + +An open-ended "what next?" puts the decision-decomposition on the user. The user has to enumerate options the agent could have listed. A structured 4-option menu enumerates the standard outcomes; the user picks the standard they want. The agent stays in the role of enumerator, the user stays in the role of chooser. + +The fixed-number rule (4 or 3) also preempts the agent adding an "explain your custom option" fifth option that becomes a long negotiation. If the user's need is custom, the user says so; the standard menu still serves as the default. + +## What this means in practice + +- After tests pass, the agent PASTES the exact menu (substituting `` and ``). +- The menu has no extra prose. No "I think you might want to..." — that goes before the menu if needed. +- The detached-head 3-option menu replaces the 4-option menu when Step 2 detects detached HEAD; the agent does not present both. +- The user's answer is parsed as option number (1-4) or option text ("merge", "push", "keep", "discard"). A custom answer is treated as "I want something not in the menu — what would that be?" and the user then describes their custom flow. +- The agent does NOT pre-fill the recommendation. The menu is unranked; the user picks. diff --git a/conductor/directives/plan_steps_2_to_5_minutes_each/meta.md b/conductor/directives/plan_steps_2_to_5_minutes_each/meta.md new file mode 100644 index 00000000..35edd7d0 --- /dev/null +++ b/conductor/directives/plan_steps_2_to_5_minutes_each/meta.md @@ -0,0 +1,8 @@ +# plan_steps_2_to_5_minutes_each + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/writing-plans/SKILL.md`. The directive encodes the Bite-Sized Task Granularity block (lines 37-44): each step is one action, 2-5 minutes, with verifiable completion. Counterweight to the LLM default of writing multi-action plan steps ("set up X, write Y, run Z, commit") that produce unauditable half-done work. +**Source:** superpowers plugin `skills/writing-plans/SKILL.md:37-44` (Bite-Sized Task Granularity) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/plan_steps_2_to_5_minutes_each/v1.md b/conductor/directives/plan_steps_2_to_5_minutes_each/v1.md new file mode 100644 index 00000000..6f3da423 --- /dev/null +++ b/conductor/directives/plan_steps_2_to_5_minutes_each/v1.md @@ -0,0 +1,28 @@ +# Implementation plans MUST have bite-sized steps — one action per step, 2-5 minutes per step + +## The rule + +Each step in an implementation plan is ONE action that one engineer can do in 2-5 minutes. "Write the failing test" is a step. "Run it to verify it fails" is the next step. "Implement the minimal code to pass" is the next. "Run the tests and verify they pass" is the next. "Commit" is the next. Each step has a single, atomic action. + +Per `skills/writing-plans/SKILL.md:37-44` (Bite-Sized Task Granularity): + +> **Each step is one action (2-5 minutes):** +> - "Write the failing test" - step +> - "Run it to make sure it fails" - step +> - "Implement the minimal code to make the test pass" - step +> - "Run the tests and make sure they pass" - step +> - "Commit" - step + +## Why + +A plan with multi-action steps ("set up the test infrastructure, write three tests, run the suite, fix the obvious bugs, commit") is unauditable. The engineer finishes step N but cannot tell what counts as "step N done." Half-done steps compound into half-done plans; half-done plans produce incomplete features. + +2-5 minutes per step also matches the engineer's actual context: a single action, a single edit, a single verification. The engineer finishes step N, marks the checkbox, starts step N+1. The rhythm is sustainable; the plan is auditable; the engineer never has to re-read step N's description to know what "done" means. + +## What this means in practice + +- Every step fits on one screen (typically 5-15 lines of prose or 5-30 lines of code). +- Every step has a verifiable completion: a test result, a file created, a command output, a commit. +- The plan is structured so that the engineer never has to read more than the current step to know what to do. Forward references ("as described above") are forbidden — each step self-contains. +- Plan self-review checks the granularity: any step that takes >5 minutes for a competent engineer to execute is split into smaller steps. +- The 2-5 minute rule is not aspirational; it is a constraint the plan author must satisfy. If a step needs >5 minutes, the step is doing too much. diff --git a/conductor/directives/plans_no_placeholders_or_tbds/meta.md b/conductor/directives/plans_no_placeholders_or_tbds/meta.md new file mode 100644 index 00000000..885b12ad --- /dev/null +++ b/conductor/directives/plans_no_placeholders_or_tbds/meta.md @@ -0,0 +1,8 @@ +# plans_no_placeholders_or_tbds + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/writing-plans/SKILL.md`. The directive encodes the "No Placeholders" block at lines 106-114 (TBD/TODO/implement-later/similar-to-Task-N/add-appropriate-validation are plan failures). Counterweight to the LLM default of writing vague steps that mask the author's incomplete design and force the executing engineer to re-design on the fly. +**Source:** superpowers plugin `skills/writing-plans/SKILL.md:106-114` (No Placeholders) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/plans_no_placeholders_or_tbds/v1.md b/conductor/directives/plans_no_placeholders_or_tbds/v1.md new file mode 100644 index 00000000..0d31a223 --- /dev/null +++ b/conductor/directives/plans_no_placeholders_or_tbds/v1.md @@ -0,0 +1,30 @@ +# Plans show all code in the step — no "implement later", no "similar to Task N", no "TBD" — every step is independently executable + +## The rule + +Every step in an implementation plan contains the actual code the engineer writes (in a code block), the actual command they run (with exact arguments), and the actual expected output. The engineer reading step N has zero need to read other steps to know what to do. Forward references ("see Task 3"), placeholders ("implement later"), or vague steps ("add appropriate validation") are forbidden; they are plan failures, not "filled in later." + +Per `skills/writing-plans/SKILL.md:106-114` (No Placeholders): + +> Every step must contain the actual content an engineer needs. These are **plan failures** — never write them: +> - "TBD", "TODO", "implement later", "fill in details" +> - "Add appropriate error handling" / "add validation" / "handle edge cases" +> - "Write tests for the above" (without actual test code) +> - "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order) +> - Steps that describe what to do without showing how (code blocks required for code steps) +> - References to types, functions, or methods not defined in any task + +## Why + +Plan authors write vague steps when they themselves don't know the answer yet. "Add appropriate validation" is the plan author's confession that they haven't designed the validation yet. The engineer reading the step then has to design it themselves — which is implementation, not execution. + +Placeholders also break the engineer reading out of order. If step 7 says "use the Foo class added in Task 3," the engineer reading step 7 must scroll back to Task 3 to know what Foo is. Repeating the code (or at minimum the interface) in step 7's context is the cure. + +## What this means in practice + +- Every step's code is shown verbatim in a code block. No "..." for "fill in the rest." +- Every step's command is shown verbatim with expected output. The engineer knows what success looks like. +- Every step that references an earlier task's artifact re-states the relevant excerpt inline. The engineer never has to flip back. +- "TBD" / "TODO" / "implement later" / "fill in details" / "add appropriate X" are not allowed in plan steps. The plan author rewrites them as concrete steps or removes them. +- Plan self-review checks for each forbidden phrase; the check is mandatory per `skills/writing-plans/SKILL.md:128-129` (Placeholder scan). +- The plan's quality is proportional to the explicitness of each step. A plan with 50 lines of code per step is a plan that survives context-switch. diff --git a/conductor/directives/presets/current_baseline.md b/conductor/directives/presets/current_baseline.md index 4b44290b..b1525a5f 100644 --- a/conductor/directives/presets/current_baseline.md +++ b/conductor/directives/presets/current_baseline.md @@ -43,6 +43,8 @@ Read each file below before any action. - decompose_or_isolate_never_offload: conductor/directives/decompose_or_isolate_never_offload/v1.md - decorator_orphan_pitfall: conductor/directives/decorator_orphan_pitfall/v1.md - delete_means_delete_no_reference: conductor/directives/delete_means_delete_no_reference/v1.md +- evidence_before_completion_claims: conductor/directives/evidence_before_completion_claims/v1.md +- exactly_four_completion_options: conductor/directives/exactly_four_completion_options/v1.md - defer_heavy_sdk_imports_to_subprocess: conductor/directives/defer_heavy_sdk_imports_to_subprocess/v1.md - no_performative_agreement_in_review: conductor/directives/no_performative_agreement_in_review/v1.md - defer_not_catch_for_native_crashes: conductor/directives/defer_not_catch_for_native_crashes/v1.md @@ -110,6 +112,8 @@ Read each file below before any action. - per_aggregate_dataclass_promotion: conductor/directives/per_aggregate_dataclass_promotion/v1.md - per_conversation_scratch_dir: conductor/directives/per_conversation_scratch_dir/v1.md - per_dimension_pick_dim_not_tool: conductor/directives/per_dimension_pick_dim_not_tool/v1.md +- plan_steps_2_to_5_minutes_each: conductor/directives/plan_steps_2_to_5_minutes_each/v1.md +- plans_no_placeholders_or_tbds: conductor/directives/plans_no_placeholders_or_tbds/v1.md - per_phase_metric_regression_fix: conductor/directives/per_phase_metric_regression_fix/v1.md - pathlib_read_write_no_newline_kwarg: conductor/directives/pathlib_read_write_no_newline_kwarg/v1.md - pipeline_immediate_mode_no_object: conductor/directives/pipeline_immediate_mode_no_object/v1.md @@ -173,6 +177,7 @@ Read each file below before any action. - verify_before_editing: conductor/directives/verify_before_editing/v1.md - verbose_commit_message_ban: conductor/directives/verbose_commit_message_ban/v1.md - verify_critique_before_implementing: conductor/directives/verify_critique_before_implementing/v1.md +- verify_tests_before_offering_completion_options: conductor/directives/verify_tests_before_offering_completion_options/v1.md - warm_md_duplicates_not_in_place: conductor/directives/warm_md_duplicates_not_in_place/v1.md - workspace_paths: conductor/directives/workspace_paths/v1.md @@ -221,8 +226,13 @@ cluster) added 4 more (3 from receiving-code-review — no-performative-agreemen added 4 more (2 from subagent-driven-development — spec-review-before-quality- review + never-inherit-session-history-to-subagent; 2 from using-git-worktrees — detect-existing-isolation-before-creating + verify-clean-baseline-before- -starting) for a total of 156 — see HARVEST_SUMMARY.md for what was lifted in -each pass). +starting) for a total of 156, and the 2026-07-04 superpowers scavenge (batch +5 of 5: finishing / verification) added 5 more (2 from finishing-a-development- +branch — verify-tests-before-offering-completion-options + exactly-four- +completion-options; 1 from verification-before-completion evidence-before- +completion-claims; 2 from writing-plans — plan-steps-2-to-5-minutes-each + +plans-no-placeholders-or-TBDs) for a total of 161 — see HARVEST_SUMMARY.md +for what was lifted in each pass). No alternative encodings tested yet. This preset is the control group for future experiments. diff --git a/conductor/directives/verify_tests_before_offering_completion_options/meta.md b/conductor/directives/verify_tests_before_offering_completion_options/meta.md new file mode 100644 index 00000000..adc9f453 --- /dev/null +++ b/conductor/directives/verify_tests_before_offering_completion_options/meta.md @@ -0,0 +1,8 @@ +# verify_tests_before_offering_completion_options + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/finishing-a-development-branch/SKILL.md`. The directive encodes Step 1 (lines 18-38): verify tests pass BEFORE presenting merge/PR/discard options; if tests fail, STOP and report failures. Counterweight to the LLM default of presenting completion options on agent confidence rather than verification evidence, which ships broken merges to user debugging queues. +**Source:** superpowers plugin `skills/finishing-a-development-branch/SKILL.md:18-38` (Step 1: Verify Tests) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/verify_tests_before_offering_completion_options/v1.md b/conductor/directives/verify_tests_before_offering_completion_options/v1.md new file mode 100644 index 00000000..c5fcc167 --- /dev/null +++ b/conductor/directives/verify_tests_before_offering_completion_options/v1.md @@ -0,0 +1,41 @@ +# Tests MUST be verified passing BEFORE offering merge/PR/discard options — never offer completion on broken code + +## The rule + +When implementation is "complete" and the agent is preparing to surface merge / PR / keep / discard options to the user, the agent MUST first run the full test suite and confirm it passes. The options menu is only shown after verification; it is NEVER shown on the agent's belief that "it should work now." + +Per `skills/finishing-a-development-branch/SKILL.md:18-38` (Step 1: Verify Tests): + +> **Before presenting options, verify tests pass:** +> +> ```bash +> # Run project's test suite +> npm test / cargo test / pytest / go test ./... +> ``` +> +> **If tests fail:** +> ``` +> Tests failing ( failures). Must fix before completing: +> +> [Show failures] +> +> Cannot proceed with merge/PR until tests pass. +> ``` +> +> Stop. Don't proceed to Step 2. +> +> **If tests pass:** Continue to Step 2. + +## Why + +A merge or PR with failing tests is a worse outcome than not merging. The user has to debug the failures (often in a high-pressure moment because the merge was assumed ready), the failure attribution is harder in the merged state than the branch state, and the user can no longer revert cleanly. The cost of merging broken code is higher than the cost of running the tests first. + +The Step 1 gate is also a forcing function against "I'm confident it works." Confidence is not evidence; the test run is. + +## What this means in practice + +- The agent runs the full suite (not just the tests touched by the change) and confirms `0 failures`. +- If ANY test fails, the agent reports the failure count, the failing tests, and the user's three options: (a) fix now, (b) fix later (handle the failure with a TODO), (c) investigate root cause. The agent does NOT proceed to Step 2. +- The verification output is captured in full (per `no_output_filtering`). +- "Just this once — tests probably pass, the change is trivial" is forbidden; the run happens, the evidence is recorded. +- After merge, the user is told "Tests verified passing on merge result" — not "I ran tests before merging." The verification is reproducible.