From 9dd2c318fbe71d5658df0360fbd2ac270d06133d Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 4 Jul 2026 12:33:34 -0400 Subject: [PATCH] feat(directives): scavenge superpowers plugin (subagent-driven-development, using-git-worktrees): 4 directives --- .../meta.md | 8 ++++ .../v1.md | 40 +++++++++++++++++++ .../meta.md | 8 ++++ .../v1.md | 32 +++++++++++++++ .../directives/presets/current_baseline.md | 11 ++++- .../spec_review_before_quality_review/meta.md | 8 ++++ .../spec_review_before_quality_review/v1.md | 33 +++++++++++++++ .../meta.md | 8 ++++ .../v1.md | 40 +++++++++++++++++++ 9 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 conductor/directives/detect_existing_isolation_before_creating/meta.md create mode 100644 conductor/directives/detect_existing_isolation_before_creating/v1.md create mode 100644 conductor/directives/never_inherit_session_history_to_subagent/meta.md create mode 100644 conductor/directives/never_inherit_session_history_to_subagent/v1.md create mode 100644 conductor/directives/spec_review_before_quality_review/meta.md create mode 100644 conductor/directives/spec_review_before_quality_review/v1.md create mode 100644 conductor/directives/verify_clean_baseline_before_starting/meta.md create mode 100644 conductor/directives/verify_clean_baseline_before_starting/v1.md diff --git a/conductor/directives/detect_existing_isolation_before_creating/meta.md b/conductor/directives/detect_existing_isolation_before_creating/meta.md new file mode 100644 index 00000000..1905ada3 --- /dev/null +++ b/conductor/directives/detect_existing_isolation_before_creating/meta.md @@ -0,0 +1,8 @@ +# detect_existing_isolation_before_creating + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/using-git-worktrees/SKILL.md`. The directive encodes Step 0 (lines 18-37): detect GIT_DIR != GIT_COMMON (real worktree) vs submodule vs normal checkout BEFORE creating a new worktree. Counterweight to the LLM default of "I'll just create a worktree" without checking the current workspace state, which produces nested worktrees the harness cannot see or clean up. +**Source:** superpowers plugin `skills/using-git-worktrees/SKILL.md:18-37` (Step 0: Detect Existing Isolation) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/detect_existing_isolation_before_creating/v1.md b/conductor/directives/detect_existing_isolation_before_creating/v1.md new file mode 100644 index 00000000..b65b25a8 --- /dev/null +++ b/conductor/directives/detect_existing_isolation_before_creating/v1.md @@ -0,0 +1,40 @@ +# Detect existing worktree/submodule isolation BEFORE creating a new worktree — nesting creates phantom state + +## The rule + +Before creating a new isolated workspace (worktree, branch, clone), the agent runs Step 0 detection: it checks whether it is already in a worktree or a submodule. If yes (and it's a real worktree, not a submodule), the agent SKIPS the create step and uses the existing workspace. Creating a nested worktree inside an existing worktree produces phantom state the parent harness cannot see or clean up. + +Per `skills/using-git-worktrees/SKILL.md:18-37` (Step 0: Detect Existing Isolation): + +> ```bash +> GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) +> GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) +> BRANCH=$(git branch --show-current) +> ``` +> +> **Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule: +> +> ```bash +> git rev-parse --show-superproject-working-tree 2>/dev/null +> ``` +> +> **If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree. +> +> Report with branch state: +> - On a branch: "Already in isolated workspace at `` on branch ``." +> - Detached HEAD: "Already in isolated workspace at `` (detached HEAD, externally managed). Branch creation needed at finish time." + +## Why + +A nested worktree produces three problems: (1) the parent harness cannot find or clean it up on session exit (phantom state); (2) the user's main checkout now has a checked-out-by-someone-else branch in its `.git/worktrees/` registry; (3) the agent spends the session editing in the wrong worktree. Detection is cheap (two `git rev-parse` calls) and prevents all three. + +The submodule guard is the specific reason this exists: a submodule's git directory is in `.git/modules//`, not the parent repo's `.git/`, so the simple `GIT_DIR != GIT_COMMON` check matches inside submodules too. Without the guard, the agent believes it is in a worktree when it is actually in a submodule, and creates a parallel worktree in the wrong context. + +## What this means in practice + +- The first action of any new feature work in a project is the Step 0 detection. +- If `GIT_DIR != GIT_COMMON` and `git rev-parse --show-superproject-working-tree` returns empty, the agent is in a real worktree — SKIP the create step. +- If `GIT_DIR != GIT_COMMON` but the superproject query returns a path, the agent is in a submodule — treat as a normal repo checkout (the isolation is the submodule, not a worktree). +- If `GIT_DIR == GIT_COMMON`, the agent is in a normal checkout — proceed to Step 1 (create or work in place). +- The detection script and the report template are copypaste-stable: the agent always pastes the same two-line answer in the response. +- Skipping detection to "save time" is the canonical mistake per `skills/using-git-worktrees/SKILL.md:179-180` (Common Mistakes: "Creating a nested worktree inside an existing one"). diff --git a/conductor/directives/never_inherit_session_history_to_subagent/meta.md b/conductor/directives/never_inherit_session_history_to_subagent/meta.md new file mode 100644 index 00000000..e9eb50be --- /dev/null +++ b/conductor/directives/never_inherit_session_history_to_subagent/meta.md @@ -0,0 +1,8 @@ +# never_inherit_session_history_to_subagent + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/dispatching-parallel-agents/SKILL.md` + `skills/subagent-driven-development/SKILL.md`. The directive encodes "They should never inherit your session's context or history — you construct exactly what they need" at dispatching-parallel-agents:9-10 + subagent-driven-development:9-14. Counterweight to the LLM default of pasting parent context into child prompts "to save time," which breaks the sub-agent's focus and burns both child tokens on irrelevant parent history. +**Source:** superpowers plugin `skills/dispatching-parallel-agents/SKILL.md:9-10` + `skills/subagent-driven-development/SKILL.md:9-14` + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/never_inherit_session_history_to_subagent/v1.md b/conductor/directives/never_inherit_session_history_to_subagent/v1.md new file mode 100644 index 00000000..aa351376 --- /dev/null +++ b/conductor/directives/never_inherit_session_history_to_subagent/v1.md @@ -0,0 +1,32 @@ +# Sub-agents MUST receive explicit context only — they never inherit the orchestrator's session history + +## The rule + +When dispatching a sub-agent (Tier 3 worker, Tier 4 QA, or any external-task invocation), the agent's prompt includes exactly the context the sub-agent needs to do the job. The sub-agent does NOT inherit the parent's conversation history, error logs, prior reasoning, scratch notes, or system reminders. Each sub-agent starts with a clean context window and is filled with the orchestrator-curated subset. + +Per `skills/dispatching-parallel-agents/SKILL.md:9-10`: + +> You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work. + +And `skills/subagent-driven-development/SKILL.md:9-14`: + +> **Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work. + +## Why + +Two reasons: + +1. **Sub-agent performance.** A sub-agent with a focused, structured prompt succeeds at the specific task; a sub-agent that inherits megabytes of orchestrator history gets distracted, form-shifts (changes style to match the inherited context), and burns tokens re-reading irrelevant context. The LLM's context window is not "free" — filling it with what the sub-agent doesn't need directly competes with what it does need. + +2. **Orchestrator context preservation.** If every sub-agent's full conversation streamed back into the orchestrator's context (rather than only the artifact), the orchestrator's context window would explode after 2-3 sub-agent calls. This is the inverse direction of the rule and is enforced by `subagent_returns_artifact_not_transcript`. Together, both directions form the "sub-agent context firewall." + +This directive governs the orchestrator → sub-agent direction (sub-agent does not see parent history); `subagent_returns_artifact_not_transcript` governs the sub-agent → orchestrator direction (orchestrator does not see sub-agent history). Both must hold for the firewall to be intact. + +## What this means in practice + +- The sub-agent's prompt is written as if the sub-agent has never seen this conversation, this codebase, or this user. +- The prompt pastes the relevant context: relevant file:line refs, error messages, the spec the task implements, the tests to write, the constraints to obey. +- The prompt does NOT reference "as we discussed earlier" / "the previous error" / "your prior research" — there is no prior for the sub-agent. +- The prompt's role is "you are a Tier 3 worker; here is the spec; here is the file; write the code" — not "you are continuing our conversation." +- Context isolation is what makes sub-agents parallelizable: two sub-agents dispatched simultaneously have identical prompts and identical behavior (modulo LLM nondeterminism). If history leaked, the parallelization invariant would break. +- If a sub-agent needs context from another sub-agent's work, the orchestrator mediates — it pastes the relevant excerpt from agent A's artifact into agent B's prompt. The sub-agents do not call each other directly. diff --git a/conductor/directives/presets/current_baseline.md b/conductor/directives/presets/current_baseline.md index 65d48290..4b44290b 100644 --- a/conductor/directives/presets/current_baseline.md +++ b/conductor/directives/presets/current_baseline.md @@ -30,6 +30,7 @@ Read each file below before any action. - boundary_layer_exception: conductor/directives/boundary_layer_exception/v1.md - cache_stable_to_volatile: conductor/directives/cache_stable_to_volatile/v1.md - cheap_fix_first_investigation_phases: conductor/directives/cheap_fix_first_investigation_phases/v1.md +- detect_existing_isolation_before_creating: conductor/directives/detect_existing_isolation_before_creating/v1.md - chroma_cache_path: conductor/directives/chroma_cache_path/v1.md - chronology_must_regenerate_after_every_track_ship: conductor/directives/chronology_must_regenerate_after_every_track_ship/v1.md - classifier_must_emit_per_row_evidence: conductor/directives/classifier_must_emit_per_row_evidence/v1.md @@ -80,6 +81,7 @@ Read each file below before any action. - modal_explicit_opened_list_for_lifecycle: conductor/directives/modal_explicit_opened_list_for_lifecycle/v1.md - modular_controller_pattern: conductor/directives/modular_controller_pattern/v1.md - neutral_language_for_doc_drift: conductor/directives/neutral_language_for_doc_drift/v1.md +- never_inherit_session_history_to_subagent: conductor/directives/never_inherit_session_history_to_subagent/v1.md - nil_sentinel_pattern: conductor/directives/nil_sentinel_pattern/v1.md - no_comments_in_body: conductor/directives/no_comments_in_body/v1.md - no_conductor_yaml_for_artifacts: conductor/directives/no_conductor_yaml_for_artifacts/v1.md @@ -102,6 +104,7 @@ Read each file below before any action. - review_plan_critically_before_executing: conductor/directives/review_plan_critically_before_executing/v1.md - skill_check_before_clarifying: conductor/directives/skill_check_before_clarifying/v1.md - spec_self_review_four_checks: conductor/directives/spec_self_review_four_checks/v1.md +- spec_review_before_quality_review: conductor/directives/spec_review_before_quality_review/v1.md - spec_template_required_6_sections: conductor/directives/spec_template_required_6_sections/v1.md - system_reminder_redact_don_act: conductor/directives/system_reminder_redact_don_act/v1.md - per_aggregate_dataclass_promotion: conductor/directives/per_aggregate_dataclass_promotion/v1.md @@ -164,6 +167,7 @@ Read each file below before any action. - use_git_history_as_classification_source_of_truth: conductor/directives/use_git_history_as_classification_source_of_truth/v1.md - user_corrections_log_in_state_toml: conductor/directives/user_corrections_log_in_state_toml/v1.md - use_batched_test_runner: conductor/directives/use_batched_test_runner/v1.md +- verify_clean_baseline_before_starting: conductor/directives/verify_clean_baseline_before_starting/v1.md - verbatim_lift_not_rewrite: conductor/directives/verbatim_lift_not_rewrite/v1.md - view_composes_does_not_leak_into_theme_get_color: conductor/directives/view_composes_does_not_leak_into_theme_get_color/v1.md - verify_before_editing: conductor/directives/verify_before_editing/v1.md @@ -213,7 +217,12 @@ total of 148, and the 2026-07-04 superpowers scavenge (batch 3 of 5: review cluster) added 4 more (3 from receiving-code-review — no-performative-agreement + verify-critique-before-implementing + clarify-unclear-before-partial-impl; 1 from requesting-code-review — review-after-each-task-not-end) for a total of -152 — see HARVEST_SUMMARY.md for what was lifted in each pass). +152, and the 2026-07-04 superpowers scavenge (batch 4 of 5: subagent / workflow) +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). No alternative encodings tested yet. This preset is the control group for future experiments. diff --git a/conductor/directives/spec_review_before_quality_review/meta.md b/conductor/directives/spec_review_before_quality_review/meta.md new file mode 100644 index 00000000..3c6856a3 --- /dev/null +++ b/conductor/directives/spec_review_before_quality_review/meta.md @@ -0,0 +1,8 @@ +# spec_review_before_quality_review + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/subagent-driven-development/SKILL.md`. The directive encodes the Red Flag "Start code quality review before spec compliance is ✅ (wrong order)" at lines 246-261 plus the process flow at lines 76-79. Counterweight to the LLM default of running only a single "review" per task (which conflates the two review goals and allows missing-feature bugs to slip past as minor style issues). +**Source:** superpowers plugin `skills/subagent-driven-development/SKILL.md:76-79` (process flow) + `:246-261` (Red Flags) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/spec_review_before_quality_review/v1.md b/conductor/directives/spec_review_before_quality_review/v1.md new file mode 100644 index 00000000..f1de0b28 --- /dev/null +++ b/conductor/directives/spec_review_before_quality_review/v1.md @@ -0,0 +1,33 @@ +# Spec compliance review comes BEFORE code quality review — wrong order means both reviews are skipped + +## The rule + +In subagent-driven development, when an implementer subagent returns "DONE," the orchestrator dispatches the spec-compliance reviewer FIRST. Only after the spec-compliance reviewer approves does the orchestrator dispatch the code-quality reviewer. The order is non-negotiable; reversing them skips both reviews. + +Per `skills/subagent-driven-development/SKILL.md:246-261` (Red Flags): + +> **Never:** +> - Start code quality review before spec compliance is ✅ (wrong order) +> - Move to next task while either review has open issues + +And the process flow at lines 76-79: + +> "Spec reviewer subagent confirms code matches spec?" [yes] → +> "Dispatch code quality reviewer subagent" + +## Why + +The two reviews catch different things. Spec compliance asks: "does the code do what the spec required (and only what the spec required)?" Code quality asks: "is the code well-written (clean, tested, maintainable)?" A "well-written" code that does the wrong thing is still wrong; a "correct" code that is spaghetti still needs cleanup. The reviews are complementary. + +But the order matters: spec-compliance issues are usually larger (missing or extra features) than code-quality issues (naming, structure). If code quality runs first, the reviewer can spend the entire review budget on minor style issues and never flag the missing feature. Conversely, if code quality runs second, the spec-compliance findings may already have caused structural rewrites that the code-quality reviewer now has to re-evaluate. Spec-first is cheaper. + +There is also a confirmation-bias fix: reviewers who see the code first form an opinion about its style; running the spec reviewer first anchors them on what the code should be, not what it looks like. + +## What this means in practice + +- Implementer says "DONE" → dispatch spec-compliance reviewer FIRST. +- If spec reviewer says "❌ Issues" → implementer fixes → spec reviewer re-reviews → repeat until ✅. +- Only when spec reviewer says "✅ Spec compliant" → THEN dispatch code-quality reviewer. +- If both reviewers have open issues, neither review is done. Both must be ✅ before the next task starts. +- The orchestrator does NOT aggregate ("looks fine overall") when either reviewer has open issues. Aggregating is the failure mode the red flag exists to prevent. +- The two-stage review is per task, not per track. A 5-task plan has 10 reviews (5 spec + 5 quality), not 2 reviews at the end. diff --git a/conductor/directives/verify_clean_baseline_before_starting/meta.md b/conductor/directives/verify_clean_baseline_before_starting/meta.md new file mode 100644 index 00000000..ad545351 --- /dev/null +++ b/conductor/directives/verify_clean_baseline_before_starting/meta.md @@ -0,0 +1,8 @@ +# verify_clean_baseline_before_starting + +## v1 + +**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/using-git-worktrees/SKILL.md`. The directive encodes Step 4 (lines 134-145): run the test suite to confirm a clean baseline BEFORE any implementation; if tests fail, report and ask permission to proceed. Counterweight to the LLM default of "I'll trust the tests pass and start writing code," which produces ambiguous post-implementation failure attribution. +**Source:** superpowers plugin `skills/using-git-worktrees/SKILL.md:134-145` (Step 4: Verify Clean Baseline) + +**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives) diff --git a/conductor/directives/verify_clean_baseline_before_starting/v1.md b/conductor/directives/verify_clean_baseline_before_starting/v1.md new file mode 100644 index 00000000..19bf123c --- /dev/null +++ b/conductor/directives/verify_clean_baseline_before_starting/v1.md @@ -0,0 +1,40 @@ +# Verify a clean test baseline BEFORE starting implementation — pre-existing failures must be flagged before, not blamed on the new work + +## The rule + +Before writing any implementation code in a new worktree, branch, or workspace, the agent runs the test suite to confirm the BASELINE passes. Pre-existing failures must be captured and reported BEFORE the new work starts; otherwise the agent cannot distinguish "test was already broken" from "my change broke the test" later. + +Per `skills/using-git-worktrees/SKILL.md:134-145` (Step 4: Verify Clean Baseline): + +> Run tests to ensure workspace starts clean: +> +> ```bash +> # Use project-appropriate command +> npm test / cargo test / pytest / go test ./... +> ``` +> +> **If tests fail:** Report failures, ask whether to proceed or investigate. +> **If tests pass:** Report ready. +> +> ### Report +> +> ``` +> Worktree ready at +> Tests passing ( tests, 0 failures) +> Ready to implement +> ``` + +## Why + +A test that fails after a change is ambiguous if the baseline is also failing: the change may have introduced the failure, or the failure may have been there before. The agent cannot bisect; the agent cannot confidently claim "my fix works." The user is also asked to evaluate a mixed signal ("tests pass" + "tests fail") that is impossible to act on. + +A clean baseline is also a permission check: the user agrees the workspace was passing before this work, so the failure attribution later is unambiguous. Without the baseline, the user has no signal of what "broken" means. + +## What this means in practice + +- The first command after creating the worktree (or branching) is `pytest` / `npm test` / the project-appropriate test command. +- The output is captured in full (never filtered — see `no_output_filtering`) and committed either to the working log or `tests/artifacts/`. +- A failing baseline is reported to the user before any implementation begins: "Baseline is failing: tests X, Y, Z fail with errors A, B, C. Should I (a) proceed and attribute these to baseline, (b) investigate first, or (c) abandon this work?" — three options, no hidden fourth. +- A passing baseline is reported tersely: "Worktree ready at ``. Tests passing (N tests, 0 failures). Ready to implement ``." +- The baseline report is the first line of evidence in any post-implementation test report. If you cannot produce this line, the test signal is unreliable. +- "I'll just trust the tests pass" is forbidden; the run happens, the output is read, the count is recorded.