feat(directives): scavenge superpowers plugin (using-superpowers, brainstorming, dispatching-parallel-agents, executing-plans): 6 directives
This commit is contained in:
@@ -0,0 +1,8 @@
|
||||
# agent_prompt_one_independent_domain
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/dispatching-parallel-agents/SKILL.md`. The directive encodes the four Common Mistakes (broad scope, no context, no constraints, vague output) and the four required axes of a good agent prompt (focused, self-contained, specific output, constrained). Counterweight to the LLM default of "Fix all the tests in the suite" prompts that lose the sub-agent in scope.
|
||||
**Source:** superpowers plugin `skills/dispatching-parallel-agents/SKILL.md:86-90` (Good agent prompts) + `:113-122` (Common Mistakes table)
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,42 @@
|
||||
# Sub-agent prompts scope exactly ONE independent problem domain — "fix all the tests" is the canonical anti-pattern
|
||||
|
||||
## The rule
|
||||
|
||||
When dispatching a sub-agent for parallel or focused work, the agent prompt's scope is exactly one test file, one subsystem, or one independent problem. "Fix all the tests in the suite" or "investigate the bug across the codebase" is too broad; the agent gets lost in scope and the answer is shallow.
|
||||
|
||||
Per `skills/dispatching-parallel-agents/SKILL.md:113-122` (Common Mistakes):
|
||||
|
||||
> **❌ Too broad:** "Fix all the tests" - agent gets lost
|
||||
> **✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
|
||||
>
|
||||
> **❌ No context:** "Fix the race condition" - agent doesn't know where
|
||||
> **✅ Context:** Paste the error messages and test names
|
||||
>
|
||||
> **❌ No constraints:** Agent might refactor everything
|
||||
> **✅ Constraints:** "Do NOT change production code" or "Fix tests only"
|
||||
>
|
||||
> **❌ Vague output:** "Fix it" - you don't know what changed
|
||||
> **✅ Specific:** "Return summary of root cause and changes"
|
||||
|
||||
## The four axes of a good prompt
|
||||
|
||||
Every good agent prompt has all four (per `skills/dispatching-parallel-agents/SKILL.md:86-90` "Good agent prompts"):
|
||||
|
||||
1. **Focused** — one clear problem domain (one test file, one subsystem, one error)
|
||||
2. **Self-contained** — all context the agent needs to understand the problem is pasted in (error messages, file paths, test names, expected vs actual)
|
||||
3. **Specific about output** — what does the agent return? (a verdict, a diff summary, a root cause, an artifact)
|
||||
4. **Constrained** — what may the agent NOT touch? ("do not change production code"; "fix tests only")
|
||||
|
||||
## Why
|
||||
|
||||
A broad scope forces the sub-agent to triage on the orchestrator's behalf. The orchestrator already triaged — that is why this work is a single dispatch and not a brainstorming session. The sub-agent's job is execution, not scoping. Forcing it to scope blurs the boundary between orchestrator and worker, and the worker either makes bad scope decisions or returns a half-scoped answer.
|
||||
|
||||
Per the canonical anti-pattern from `skills/dispatching-parallel-agents/SKILL.md:113`: "**❌ Too broad:** 'Fix all the tests' - agent gets lost." The agent prompt's first sentence should name the file, the subsystem, or the failure domain.
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- A sub-agent prompt always begins with "Fix [specific file]" / "Investigate [specific subsystem]" / "Resolve [specific error]."
|
||||
- The prompt body pastes the relevant error messages, test names, and exact lines; the agent does not have to re-derive context.
|
||||
- The prompt explicitly enumerates what the agent must NOT change ("Do not modify production code in this dispatch; fix tests only").
|
||||
- The prompt's output section names the artifact shape ("Return: a 1-paragraph summary of root cause + the list of files changed"). The agent does not have to guess.
|
||||
- If the work needs to touch more than one independent domain, dispatch separate agents for each; do not bundle them.
|
||||
@@ -0,0 +1,8 @@
|
||||
# brainstorm_even_for_simple_projects
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/brainstorming/SKILL.md`. The directive encodes the HARD-GATE at lines 12-14 ("Do NOT invoke any implementation skill... until you have presented a design and the user has approved it") plus the Anti-Pattern at lines 16-18. Counterweight to the LLM default of skipping design for "simple" tasks where unexamined assumptions cause the most wasted work.
|
||||
**Source:** superpowers plugin `skills/brainstorming/SKILL.md:12-14` (HARD-GATE) + `:16-18` (Anti-Pattern "This Is Too Simple To Need A Design")
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,27 @@
|
||||
# Every project must be brainstormed — even "simple" projects — and the design must be approved before any implementation
|
||||
|
||||
## The iron gate
|
||||
|
||||
No implementation may begin without a brainstormed design and explicit user approval. "Simple" projects are not exempt; the design may be short (a few sentences for a config change or single-function utility), but the user-approval gate is non-negotiable.
|
||||
|
||||
Per `skills/brainstorming/SKILL.md:12-14` (HARD-GATE):
|
||||
|
||||
> Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
|
||||
|
||||
Per `skills/brainstorming/SKILL.md:16-18` (Anti-Pattern):
|
||||
|
||||
> Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
|
||||
|
||||
## Why
|
||||
|
||||
"Simple" projects are exactly where unexamined assumptions cost the most. The agent picks a default library, a default storage layer, a default module layout, then the user requests a different one and the work is rebuilt. The 60 seconds the design gate takes is cheaper than the half-day of redoing the wrong default.
|
||||
|
||||
The gate also creates an audit trail: the user sees the design before any irreversible tool call, and the user can correct course from a sketch rather than a half-built house.
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- A 1-line fix request is brainstormed too. The design may be: "Change line N from `x` to `y` because [reason]; expected result: [test outcome]."
|
||||
- A config change is brainstormed too. The design may be: "Add `[section].key = value` because [reason]; expected effect: [behavior]."
|
||||
- A TODO list is brainstormed too. The design may be: "Items ordered by [rationale]; expected completion criterion: [definition of done]."
|
||||
- The user is shown the design, the user agrees, the agent implements. No silent fallback to "this is obvious, let me just do it."
|
||||
- An agent that begins implementation without approval has violated the gate, not "saved time."
|
||||
@@ -0,0 +1,8 @@
|
||||
# design_leads_with_recommendation
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/brainstorming/SKILL.md`. The directive encodes the "lead with your recommended option and explain why" rule from the Exploring Approaches section. Counterweight to the LLM default of presenting neutral option-lists that abdicate the decision.
|
||||
**Source:** superpowers plugin `skills/brainstorming/SKILL.md:82-84` (Exploring approaches, "Lead with your recommended option and explain why")
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,27 @@
|
||||
# Brainstorming designs must lead with a recommended approach plus the reasoning — never present 2-3 unranked options and ask the user to pick
|
||||
|
||||
## The rule
|
||||
|
||||
When proposing brainstorming approaches, the agent presents 2-3 alternatives with trade-offs, BUT leads the presentation with the recommended option and an explicit "why this is best" rationale. The user can override, but the agent's first sentence is the recommendation, not a list of choices.
|
||||
|
||||
Per `skills/brainstorming/SKILL.md:82-84`:
|
||||
|
||||
> **Exploring approaches:**
|
||||
>
|
||||
> - Propose 2-3 different approaches with trade-offs
|
||||
> - Present options conversationally with your recommendation and reasoning
|
||||
> - **Lead with your recommended option and explain why**
|
||||
|
||||
## Why
|
||||
|
||||
A neutral "here are three options" presentation puts the decision weight on the user, who has less context than the agent. The agent's job is to make the call and explain the reasoning. The user can reject the recommendation, but starting from a list of unranked options forces them to reconstruct the trade-off analysis the agent already did.
|
||||
|
||||
An unranked list also reads as indecisive — the agent appears unsure, which the user reads as "this is risky." A clear recommendation with reasoning reads as "here is what I would do and why you might disagree."
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- First sentence of any approach comparison: "I recommend X, because Y."
|
||||
- The 2-3 alternatives come AFTER the recommendation, not before.
|
||||
- "What would you like to do?" with no recommendation is forbidden.
|
||||
- The agent states its confidence and the residual risks in the recommendation, not just the upside.
|
||||
- If new context invalidates the recommendation, the agent RE-states the recommendation with the new information; it does not silently switch to a hedge.
|
||||
@@ -88,10 +88,16 @@ Read each file below before any action.
|
||||
- one_space_indent: conductor/directives/one_space_indent/v1.md
|
||||
- opt_in_integration_test_via_env_var_marker: conductor/directives/opt_in_integration_test_via_env_var_marker/v1.md
|
||||
- parse_failure_visible_to_conversation: conductor/directives/parse_failure_visible_to_conversation/v1.md
|
||||
- agent_prompt_one_independent_domain: conductor/directives/agent_prompt_one_independent_domain/v1.md
|
||||
- anti_entropy_state_audit_before_adding: conductor/directives/anti_entropy_state_audit_before_adding/v1.md
|
||||
- audit_before_claiming_current_state: conductor/directives/audit_before_claiming_current_state/v1.md
|
||||
- brainstorm_even_for_simple_projects: conductor/directives/brainstorm_even_for_simple_projects/v1.md
|
||||
- design_leads_with_recommendation: conductor/directives/design_leads_with_recommendation/v1.md
|
||||
- manual_compaction_only_no_auto_summarize: conductor/directives/manual_compaction_only_no_auto_summarize/v1.md
|
||||
- meta_tooling_app_boundary_check: conductor/directives/meta_tooling_app_boundary_check/v1.md
|
||||
- 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_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
|
||||
@@ -182,8 +188,13 @@ property delegation, 1 from live-gui-fragility-fixes imscope tuple-return,
|
||||
1 from regression-fixes LogPruner backoff + theme-adapt tests, 1 from
|
||||
undo-redo-lifecycle-fix cheapest-fix-first phases, 1 from theme-syntax-
|
||||
modularization TOML global-then-project merge, 1 from various plan
|
||||
constraints merged into opt-in integration env-var marker) for a total of 136
|
||||
— see HARVEST_SUMMARY.md for what was lifted in each pass).
|
||||
constraints merged into opt-in integration env-var marker) for a total of 136,
|
||||
and the 2026-07-04 superpowers scavenge (batch 1 of 5: process / orchestration)
|
||||
added 6 more (1 from using-superpowers Skill-Check-Iron-Rule, 3 from
|
||||
brainstorming — lead-with-recommendation + even-simple-projects-get-designed +
|
||||
spec-self-review-4-checks, 1 from dispatching-parallel-agents agent-prompt-
|
||||
focused-on-one-domain, 1 from executing-plans review-plan-critically-first) for
|
||||
a total of 142 — 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.
|
||||
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
# review_plan_critically_before_executing
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/executing-plans/SKILL.md`. The directive encodes Step 1's "Review critically - identify any questions or concerns about the plan ... If concerns: Raise them with your human partner before starting." Counterweight to the LLM default of executing plans verbatim while privately noting concerns that only surface when the implementation breaks.
|
||||
**Source:** superpowers plugin `skills/executing-plans/SKILL.md:18-22` (Step 1: Load and Review Plan)
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,27 @@
|
||||
# Plans must be reviewed critically BEFORE execution begins — concerns are raised to the user first, not discovered during implementation
|
||||
|
||||
## The rule
|
||||
|
||||
When handed a plan (or writing one for self-execution), the agent reads the plan ONCE critically before starting any task. Any question, concern, missing precondition, or suspected error in the plan is raised to the user (or the plan owner) BEFORE the first code change. The agent does not "discover" the issue three tasks in and backtrack silently.
|
||||
|
||||
Per `skills/executing-plans/SKILL.md:18-22` (Step 1: Load and Review Plan):
|
||||
|
||||
> 1. Read plan file
|
||||
> 2. Review critically - identify any questions or concerns about the plan
|
||||
> 3. If concerns: Raise them with your human partner before starting
|
||||
> 4. If no concerns: Create TodoWrite and proceed
|
||||
|
||||
## Why
|
||||
|
||||
A plan is a contract. Starting execution binds the agent to the plan's order, scope, and approach. If the plan is wrong, every subsequent task compounds the error. The cost of raising concerns BEFORE starting is a few minutes of conversation; the cost of discovering the issue AT task 3 is a partial-undo of tasks 1-2 plus the rebuild.
|
||||
|
||||
This is also the inverse of "implementation-by-stealth": silently executing a plan while privately disagreeing with it. The user assumes the plan is being executed as approved; the agent is sandbagging one task at a time. Critical review surfaces the disagreement early.
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- The first action on receiving a plan is "Read the whole plan ONCE, list concerns."
|
||||
- Concerns include: missing preconditions, wrong dependency order, ambiguous acceptance criteria, capability the agent lacks, library/version mismatch, missing test infrastructure.
|
||||
- Concerns are listed BEFORE the first task starts; not as an aside while starting task 1.
|
||||
- If no concerns, the agent announces "Plan reviewed, no concerns, beginning Task 1" — explicit, not silent.
|
||||
- Concerns are specific: "Task 4 assumes Foo is installed; please confirm" not "I have some concerns about the plan."
|
||||
- The agent does NOT soften concerns to be polite. The user can ignore a concern; they cannot act on an unvoiced one.
|
||||
@@ -0,0 +1,8 @@
|
||||
# skill_check_before_clarifying
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/using-superpowers/SKILL.md`. The directive encodes the iron rule "Skill check precedes any response or action, even at 1% relevance" — including clarifying questions, file exploration, and shell calls. The Red Flags table (lines 79-95) is the canonical list of rationalizations the agent uses to skip this check.
|
||||
**Source:** superpowers plugin `skills/using-superpowers/SKILL.md:45-46` (Iron Rule) + `:79-95` (Red Flags table)
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,31 @@
|
||||
# Skill check must precede any clarifying question, exploration, or action — even at 1% relevance
|
||||
|
||||
## The rule
|
||||
|
||||
Before any response (including clarifying questions, file reads, or shell calls), the agent MUST check whether any superpowers skill applies. If a skill applies, the agent invokes it first; only after the skill body has been read does the agent produce the response.
|
||||
|
||||
A 1% chance a skill applies is enough to justify the check. The skill check is non-optional, non-deferrable, and not subject to "I'll do it after I get more context."
|
||||
|
||||
Per `skills/using-superpowers/SKILL.md:45-46`: "**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it."
|
||||
|
||||
## Why
|
||||
|
||||
Skills encode workflows the agent has been trained to skip. The agent's training data biases toward "let me explore the codebase first" / "let me check git/files quickly" / "let me gather more context." All three patterns bypass the skill check; all three then run unguided. Producing the response without reading the skill produces output that the skill would have shaped differently.
|
||||
|
||||
Per `skills/using-superpowers/SKILL.md:79-95` (Red Flags table), the rationalizations are exact:
|
||||
|
||||
| Thought | Reality |
|
||||
|---------|---------|
|
||||
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
|
||||
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
|
||||
| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
|
||||
| "Let me gather information first" | Skills tell you HOW to gather information. |
|
||||
| "The skill is overkill" | Simple things become complex. Use it. |
|
||||
| "I remember that skill" | Skills evolve. Read current version. |
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- Before writing any clarifying question, run a Skill-tool-equivalent check.
|
||||
- Before reading any file, run a Skill-tool-equivalent check.
|
||||
- Before running any shell command, run a Skill-tool-equivalent check.
|
||||
- Announce the skill invocation explicitly ("Using [skill] to [purpose]") per `skills/using-superpowers/SKILL.md:65-66` so the user / future-self can audit which skill was followed.
|
||||
@@ -0,0 +1,8 @@
|
||||
# spec_self_review_four_checks
|
||||
|
||||
## v1
|
||||
|
||||
**Why this iteration:** Lifted from the global OpenCode superpowers plugin (obra/superpowers) — `skills/brainstorming/SKILL.md`. The directive encodes the Spec Self-Review block at lines 117-124 (placeholder scan + internal consistency + scope check + ambiguity check). Counterweight to the LLM default of shipping specs with TBDs and contradictions and asking the user to spot them.
|
||||
**Source:** superpowers plugin `skills/brainstorming/SKILL.md:117-124` (Spec Self-Review block)
|
||||
|
||||
**Lifted:** 2026-07-04 (scavenge sweep: superpowers plugin directives)
|
||||
@@ -0,0 +1,28 @@
|
||||
# Every spec must self-review against four checks — placeholders, internal consistency, scope, ambiguity — before user review
|
||||
|
||||
## The four checks
|
||||
|
||||
After writing the design spec, the agent runs an inline self-review before handing the spec to the user. The four checks are mandatory and in this order. Any failure is fixed inline; no re-review loop, no waiting for the user to flag the issue.
|
||||
|
||||
Per `skills/brainstorming/SKILL.md:117-124` (Spec Self-Review):
|
||||
|
||||
> 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
|
||||
> 2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
|
||||
> 3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
|
||||
> 4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
|
||||
>
|
||||
> Fix any issues inline. No need to re-review — just fix and move on.
|
||||
|
||||
## Why
|
||||
|
||||
Self-review is faster than user-review-loop. The agent catches its own placeholder text or scope overshoot in seconds; the user catches them in minutes-to-hours of round-trip. The user's review time is the expensive resource; the agent's review is cheap. Run the cheap review first.
|
||||
|
||||
The four checks are also the four classes of failures that derail implementation. Placeholders produce unfinished code. Inconsistency produces code that contradicts itself. Over-scope produces code that half-implements a feature. Ambiguity produces code that implements the wrong interpretation. Pre-empt all four.
|
||||
|
||||
## What this means in practice
|
||||
|
||||
- The agent reads its own freshly-written spec ONCE before showing it to the user.
|
||||
- For each of the four checks, the agent scans the spec for the corresponding failure mode.
|
||||
- Any failure is fixed by editing the spec file in place; no commit yet (the fix is part of the write).
|
||||
- The spec the user sees is the spec the agent would write if asked to "write the cleanest possible spec for the same requirement."
|
||||
- If the agent catches itself wanting to defer a fix ("the user can decide"), the agent fixes it inline per the original protocol.
|
||||
Reference in New Issue
Block a user