How to Troubleshoot Stuck Superpowers Multi-Agent Development: 2026 Environment Checks

The skill does not appear, or a sub-agent starts but never returns a result.

This week, check your coding harness for session-start skill injection, file and shell tools, and sub-agent dispatch; then confirm the plugin is enabled and the task is clear. If a required tool is missing, switch to a supported workflow or work manually in sequence. Reinstalling the same plugin will not supply a capability the harness does not have.

This guide is for you if you have installed Superpowers but a skill does not trigger or a multi-agent workflow stops midway. It also helps you compare coding harnesses without assuming they expose the same capabilities. If you maintain remote development sessions, use the checks and incident record to make failures reproducible.

Superpowers multi-agent troubleshooting starts with the failure boundary

Do not treat every stalled workflow as an installation problem. First record the earliest point where the run diverges from what you expected: session startup, skill invocation, tool execution, task handoff, result return, or verification. That boundary narrows the cause before you change settings.

Superpowers documents its skills and harness use through its project README, cross-harness porting guide, and individual skill documents. Use those documents to distinguish the project’s described workflow from a user-built adapter. A community configuration or personal report may be useful evidence for that environment, but it is not an official compatibility guarantee.

Why did Superpowers not trigger a skill? Check whether the current session loaded the skill instructions and whether the harness can discover and invoke them. Installing files on disk is not the same as making them available to the active session. The using-superpowers skill instructions are the reference for the skill’s intended role; compare them with what your harness actually injected.

First observed failure	What to inspect first	What the result tells you
No skill appears after opening a session	Plugin enablement, skill discovery, and startup injection	The issue is likely in registration or session setup, not task dispatch
Skill appears but no tool runs	Available tools, permission rules, and approval state	The skill may be loaded while execution is blocked or unsupported
Task is assigned but no result returns	Dispatch mechanism, task status, and result handoff	The break is likely between the main workflow and the child task
Work appears complete but no test evidence exists	Test command, output, exit status, and review record	Completion has not been verified

Create a minimal reproduction before editing configuration. Use a harmless task that asks the agent to inspect a known file, make a small isolated change only if permitted, run an available check, and report the result. Keep the prompt, active harness, session state, and observed output together. If the failure cannot be reproduced, inspect what differed between the successful and failed sessions before blaming the installation.

A loaded skill is not the same as a working harness

A harness can expose skill instructions but lack the tools needed to carry out the workflow. Check each capability separately: skill discovery and invocation, file reading and writing, shell execution, sub-agent dispatch, and a way to return results to the parent workflow. Do not infer that one capability exists because another does.

The Superpowers guide for porting to a new harness is useful when the same skill behaves differently after a harness change. Compare its integration expectations with the documented features in your current environment. Mark each item as confirmed, unavailable, or unknown. “Unknown” is not proof that a hidden tool exists.

Capability to confirm	Evidence to look for	If it is absent
Startup injection	Session instructions, loaded skill list, or startup log	Fix the integration or load the skill using a documented method
File access	Tool listing and a permitted read operation	Use an available read path or stop the automated workflow
File modification	Tool listing, workspace scope, and approval outcome	Do not ask the agent to edit through an unavailable tool
Shell execution	Tool listing and a harmless command result	Run checks through an approved human-controlled terminal
Task dispatch	Documented dispatch interface and task status	Use sequential work or a supported harness instead
Result handoff	Parent-visible output, task record, or explicit report	Require the child task to write or return a reviewable result

What should you check after changing coding harness? Repeat this capability check in the new harness rather than carrying over assumptions from the old one. Confirm which plugin or adapter is active, how skills enter a fresh session, what tools are available, and whether approvals interrupt execution. The Superpowers README and porting guide describe the project’s own workflow and integration context; they do not make every third-party harness equivalent.

Permissions can look like a broken agent. A tool may be listed but blocked by workspace policy, command restrictions, or an approval step that nobody handled. For Claude Code environments, consult the official CLI usage documentation on tool permissions. For runtimes using approval controls, the official guide to agent guardrails and approvals explains why an approval state can affect whether an action proceeds. Treat a pending or denied action as a permission outcome, not as evidence that the model ignored the task.

When a tool is missing, stop guessing tool names. Record the tools the harness actually exposes, then choose a documented alternative. If file edits and shell commands are available but sub-agent dispatch is not, you can still use Superpowers guidance to plan and complete work in a human-managed sequence. You cannot claim that a multi-agent run happened when no dispatch mechanism was present.

A stalled child task needs a traceable handoff

A sub-agent task can fail because the assignment depends on information that only exists in the parent’s conversation. It can also appear to vanish if the parent never receives a result or if a session is restarted. The Superpowers subagent-driven development skill describes a workflow built around delegating work and reviewing the outcome. Use that as a guide to inspect the handoff, not as proof of what happened inside an opaque runtime.

How do you troubleshoot a Superpowers sub-agent that will not start? Check the harness’s documented dispatch capability first. Then confirm the task was actually issued, inspect any task status or error output, and verify that the parent workflow has a way to receive the result. If the harness has no dispatch tool, stop trying alternate guessed names and use sequential execution or another supported workflow.

For every child task, make the assignment self-contained. Include the goal, relevant files or paths, constraints, expected output, and how the parent should receive the result. Do not rely on context that exists only in a long parent conversation. Ask for a concise report of actions taken, files changed, checks run, and unresolved issues.

Handoff point	Record	Failure interpretation
Before dispatch	Exact task text and relevant workspace context	The assignment may be incomplete or dependent on unstated context
At dispatch	Tool or interface used and returned status	A missing interface or rejected request is not a child-task result
During execution	Visible logs, approvals, and session changes	A pause may be waiting for permission or a live session
At return	Output location and parent-visible response	Work may exist without a usable handoff
After return	Changed files and review notes	A report still needs independent verification

Long sessions add another source of uncertainty: context may be summarized, a session may restart, or the parent may no longer have the original task state in view. Do not infer that a particular internal model event occurred unless the harness provides evidence. Instead, compare session identifiers or logs where available, check whether the task remains active, and determine whether the result was written to the workspace or returned to the parent.

Separate failed tests from missing evidence

A tool error, a failed test, and a test that never ran are different outcomes. Label them separately. If verification was not executed because shell access was unavailable, the accurate status is “not run,” not “passed.” If a command ran and returned a failure, preserve the command and its output. If the tool was blocked pending approval, record that state and who or what needs to approve it.

A practical verification record has distinct fields: intended test, exact command, observed output, exit status if exposed, approval state, review result, and final conclusion. These are diagnostic parameters, not a substitute for the harness’s own logs. Keep the raw output where your environment permits it, and avoid replacing it with a summary such as “tests look good.”

When the verification result is incomplete, compare the using-superpowers skill and the sub-agent development guidance with the actual run. Ask whether the required step was requested, whether a tool executed it, and whether the evidence reached the final report. That separates a missing workflow instruction from a blocked tool or a broken return path.

Use this decision path before changing the setup

Follow the branch that matches the evidence. Do not reinstall, switch harnesses, or widen permissions until the check points to that change.

If the skill is absent from the fresh session, confirm plugin enablement and startup injection. If either is missing, fix the documented integration and start a clean session; if both are confirmed, inspect skill discovery next.
If the skill is present but file or shell actions fail, inspect the tool list and permission or approval state. If a tool is unavailable, use an approved manual action; if it is available but blocked, resolve the specific policy or approval.
If local tools work but child tasks do not start, confirm that the harness exposes dispatch and that the request is accepted. If dispatch is absent, choose sequential execution or a harness with a documented dispatch path.
If the child task runs but the parent sees no result, inspect task status, logs, workspace outputs, and the return mechanism. If the session has restarted, recover the task from persisted records rather than assuming the work completed.
If a change is reported but verification is missing, run the appropriate check through an available, approved path. If you cannot run it, report the limitation instead of marking the task successful.

This decision path answers a common practical question: Can you use Superpowers without a sub-agent tool? Yes, where the harness can load and apply the relevant skills and you can perform the work through available tools or a human-controlled sequence. No, if you specifically require automated child-task dispatch: that workflow needs an actual dispatch capability. Keep the plan, implementation, and review steps explicit when you fall back to manual execution.

Keep an environment record you can repeat

A useful incident record should let another maintainer reproduce the check without exposing project secrets. Capture the harness name and version, the Superpowers installation or adapter state, the active skill list, available tools, permission or approval outcome, session continuity, minimal task text, logs or output, verification status, and the change that resolved the issue. Redact credentials, private source code, and user data.

Record field	Example of useful evidence	Avoid recording
Environment	Harness name, version, operating system, and workspace mode	Access tokens or private keys
Skill state	Plugin enabled state and whether the skill appeared in a fresh session	Unredacted personal prompts
Tool state	Available file, shell, and dispatch capabilities	Secret values in command output
Reproduction	Minimal task and the first unexpected result	Unrelated project files
Resolution	Setting changed, workflow substituted, and repeat-test outcome	Claims of success without test evidence

After an upgrade or harness change, run the same minimal task under the new environment. Compare the recorded capability state and output with the previous run. If the behavior changes, you have a useful before-and-after observation. If it does not, revert to the next cause in the decision path rather than making several untracked changes at once.

For environment-specific access or service questions, use the Hashvps help center or contact Hashvps. Keep those support details separate from the Superpowers compatibility question: remote access does not by itself add a missing harness tool or guarantee that a particular plugin integration is available.

Choose the runtime that matches the actual bottleneck

Your current setup may be local or remote, and each can be the right choice. Local execution gives you direct control of your files and tools, but you must maintain the environment and preserve session state yourself. A remote development machine can provide a separate workspace for repeatable tests, but you still need to confirm the harness, permissions, and dispatch mechanism inside that workspace. A different harness may solve a missing capability; a new machine alone may not.

If your current environment repeatedly loses session state, mixes project dependencies, or makes remote access difficult, renting a Mac from Hashvps can be a useful way to test a separate Mac development environment without first committing to a purchase. Review the available Hashvps package details and verify that the access method and environment fit your actual workflow before moving a project. For long-running, stable workloads or work that requires specific physical interfaces, owning and managing suitable hardware may be a better fit. And if your failure is simply that the selected harness has no sub-agent dispatch, fix or replace that workflow first; a Mac rental will not create a missing tool automatically.

Your next action is simple: reproduce the failure once, record the first broken boundary, and check the corresponding capability before changing the installation. If the environment cannot provide a required tool, switch to a workflow it supports and keep the verification record honest.