What problem does this solve?
Agents often fail by assuming the shape of their operating environment before acting.
The most obvious version is shell/platform confusion: using bash/Linux commands in a Windows or PowerShell environment, assuming Unix paths, assuming grep, sed, which, or python3 exist, or giving command blocks that are not runnable in the actual setup.
I think the same failure pattern shows up outside shell commands too.
For example, an agent can inspect the first visible connector or tool surface, decide it does not expose the operation needed for the task, and report that the task is blocked, even though a richer connector or tool surface is available next to it.
Other versions I have seen:
- assuming the current working directory is the target repo;
- assuming the current branch or worktree is safe to mutate;
- assuming auth exists;
- assuming a write action is appropriate when the task is still research/planning;
- assuming a generated or protected surface is the thing to edit.
These look like separate bugs, but the shared failure is that the agent starts acting from an assumed environment model.
Related prior work exists around worktrees, Windows/PowerShell failures, current-directory handling, and tool availability. I did not find an existing proposal that treats this as one general environment-orientation problem.
Proposed solution
Add some form of environment-orientation behavior before environment-sensitive action.
The behavior would be:
- Identify which environment facts could change the next safe step.
- Inspect only those facts.
- Make a short decision.
- Proceed.
This should not be a broad preflight checklist. It should be selective.
If shell syntax matters, check shell/OS. If connector capability matters, inspect available connector/tool surfaces before declaring the task blocked. If mutation is about to happen, check repo/worktree/write authority. If none of that matters, do not add ceremony.
Examples of useful decisions:
- This is read-only GitHub research. Use search/read operations only; do not use mutation operations.
- The first connector does not expose the needed operation. Check adjacent available connectors before declaring this blocked.
- This task requires runnable commands, but shell/OS is unknown. Check or ask before giving shell-specific commands.
- This task mutates a repository. Check target repo, branch, worktree, and working tree state before editing.
The behavior I’m proposing is not “inspect everything.” It is “do not assume the operating surface when that assumption could change the next action.”
What alternatives did you consider?
One alternative is to handle this only in specific skills: worktree guidance for worktree problems, shell guidance for shell problems, connector guidance for connector problems, and so on.
That helps with each local case, but I think it misses the common failure mode. The same agent habit shows up across shells, repos, connectors, auth, cwd, worktrees, and mutation boundaries.
Another alternative is to add more Windows/PowerShell examples. That would help with the most visible version of the problem, but not with agents falsely reporting that a task is blocked because they inspected the wrong tool surface, or mutating before confirming they are in the right phase of work.
Another alternative is to leave this to user correction. That works eventually, but only after the agent has already taken the wrong path or declared a false blocker.
My preference would be a small general behavior that can be reused wherever environment assumptions matter.
Is this appropriate for core Superpowers?
I think so.
This is not specific to one project, one domain, or one third-party integration. It applies to anyone using agents across different shells, operating systems, harnesses, connectors, repositories, and worktrees.
The exact integration point may not be a new standalone skill. It might belong in workflow selection/bootstrap, or it might be split across existing shell, worktree, connector, and mutation-safety guidance.
The core behavior seems general: before environment-sensitive action, inspect the minimum environment facts that could change the next safe step.
Environment (required)
| Field |
Value |
| Superpowers version |
6.0.3 latest at time of writing |
| Harness (Claude Code, Cursor, etc.) |
Observed primarily in Codex Desktop and Devin Desktop |
| Harness version |
Codex Desktop v26.616.51431 & Devin Desktop v3.2.23 |
| Your model + version |
Observed across OpenAI models in Codex Desktop; in Devin Desktop, observed across OpenAI models, Claude models, SWE-1.6, and GLM-5.2 |
| All plugins installed |
Varies by session; superpowers is the main plugin that I have in every harness and environment. The relevant pattern was not tied to one specific plugin set. |
Context
Prior art I found while searching:
Those all seem related, but narrower. This proposal is to name the broader failure pattern: agents acting from an assumed operating environment before checking the environment facts that would change the next safe step.
Possible eval scenarios:
- Windows/PowerShell context where bash commands are tempting.
- Agent starts outside the target repo.
- Current checkout is not the intended worktree.
- Limited connector/tool surface appears before a richer one.
- Task is read-only, but mutation tools are available.
- Common CLI is unavailable, but another available tool can complete the task.
- Generated/protected output exists next to the editable source.
Passing behavior would mean the agent checks the relevant environment fact, avoids irrelevant preflight, avoids false “blocked” claims, and proceeds with the safer next step.
What problem does this solve?
Agents often fail by assuming the shape of their operating environment before acting.
The most obvious version is shell/platform confusion: using bash/Linux commands in a Windows or PowerShell environment, assuming Unix paths, assuming
grep,sed,which, orpython3exist, or giving command blocks that are not runnable in the actual setup.I think the same failure pattern shows up outside shell commands too.
For example, an agent can inspect the first visible connector or tool surface, decide it does not expose the operation needed for the task, and report that the task is blocked, even though a richer connector or tool surface is available next to it.
Other versions I have seen:
These look like separate bugs, but the shared failure is that the agent starts acting from an assumed environment model.
Related prior work exists around worktrees, Windows/PowerShell failures, current-directory handling, and tool availability. I did not find an existing proposal that treats this as one general environment-orientation problem.
Proposed solution
Add some form of environment-orientation behavior before environment-sensitive action.
The behavior would be:
This should not be a broad preflight checklist. It should be selective.
If shell syntax matters, check shell/OS. If connector capability matters, inspect available connector/tool surfaces before declaring the task blocked. If mutation is about to happen, check repo/worktree/write authority. If none of that matters, do not add ceremony.
Examples of useful decisions:
The behavior I’m proposing is not “inspect everything.” It is “do not assume the operating surface when that assumption could change the next action.”
What alternatives did you consider?
One alternative is to handle this only in specific skills: worktree guidance for worktree problems, shell guidance for shell problems, connector guidance for connector problems, and so on.
That helps with each local case, but I think it misses the common failure mode. The same agent habit shows up across shells, repos, connectors, auth, cwd, worktrees, and mutation boundaries.
Another alternative is to add more Windows/PowerShell examples. That would help with the most visible version of the problem, but not with agents falsely reporting that a task is blocked because they inspected the wrong tool surface, or mutating before confirming they are in the right phase of work.
Another alternative is to leave this to user correction. That works eventually, but only after the agent has already taken the wrong path or declared a false blocker.
My preference would be a small general behavior that can be reused wherever environment assumptions matter.
Is this appropriate for core Superpowers?
I think so.
This is not specific to one project, one domain, or one third-party integration. It applies to anyone using agents across different shells, operating systems, harnesses, connectors, repositories, and worktrees.
The exact integration point may not be a new standalone skill. It might belong in workflow selection/bootstrap, or it might be split across existing shell, worktree, connector, and mutation-safety guidance.
The core behavior seems general: before environment-sensitive action, inspect the minimum environment facts that could change the next safe step.
Environment (required)
Context
Prior art I found while searching:
render-graphs.jschecked for Graphviz by shelling out towhich dot, which assumes Unix-like shell behavior.review-packagerunning git commands against$PWD, which forced callers into fragilecd /path/to/worktree ; review-package BASE HEADcommand shapes before adding a-C DIRoption.git add/git commit, causing subagents in.worktrees/to see nothing or drift back to the main branch.Those all seem related, but narrower. This proposal is to name the broader failure pattern: agents acting from an assumed operating environment before checking the environment facts that would change the next safe step.
Possible eval scenarios:
Passing behavior would mean the agent checks the relevant environment fact, avoids irrelevant preflight, avoids false “blocked” claims, and proceeds with the safer next step.