Skip to content

xiduzo/wtf / skills/wtf.setup

wtf.setup

Verified

This skill should be used when a user wants to set up WTF in a repository or check that the environment is ready for it — for example "set up wtf", "is wtf ready", "install wtf templates", or "a new dev joined, set them up". Verifies the GitHub CLI and its auth, installs the required gh extensions and the issue and PR templates, configures issue classification, planning, feature scope, and delivery mode, and registers the hooks. Run once per repo when onboarding, or when a contributor joins the project.

shared-references/subagent-protocol.md

View on GitHub
# Sub-Agent Protocol

Rules for any skill that spawns sub-agents via the Agent tool to execute wtf skill steps in parallel or headless. Examples: `wtf.loop`, `wtf.verify-trace` in Full Feature mode, `wtf.refine` during cascade, and `wtf.loop`'s headless `wtf.refine` invocation after each verified Trace.

## Why this matters

Sub-agents do NOT inherit the parent session's loaded skills. A sub-agent spawned from `wtf.loop` cannot see `wtf.implement-trace`'s instructions unless those instructions are embedded in its prompt. Referencing a skill by name from inside a sub-agent prompt will fail. The sub-agent has no way to resolve it.

## Rules

### 1. Embed instructions inline

When a sub-agent needs to execute the steps of another wtf skill, the parent must Read that skill's `SKILL.md` at runtime. Paste the relevant step-range into the sub-agent's prompt. Do not reference the skill by name. Sub-agents cannot load skills.

The practical pattern is:

1. Read the target skill file (for example `skills/wtf.implement-trace/SKILL.md`) at the moment the sub-agent is spawned.
2. Extract the body (skip YAML frontmatter).
3. Paste it into the sub-agent's prompt under a heading like "# Inline instructions — execute the steps below".
4. Prepend an override section that replaces interactive behavior (see rule 2). Pass any already-known context (trace number, branch name, parent feature) so the sub-agent does not re-ask.

Reading at runtime (rather than hard-coding the steps in the orchestrator skill) keeps the sub-agent in sync with the underlying skill without manual mirroring.

### 2. No AskUserQuestion

Sub-agents MUST NOT call `AskUserQuestion`. All interactive prompts are replaced:

- Review/approval questions: skip, proceed automatically with the derived content.
- "What's next?" prompts: skip — the orchestrator controls sequencing.
- Any other interactive choice that would normally pause: record as a pending question (see rule 3).

### 3. NEEDS_INPUT return block

If a genuine blocker or ambiguity requires human input, the sub-agent must return a structured result instead of asking. Examples: test failures, missing contracts, codebase mismatches, approach conflicts.

```
NEEDS_INPUT
trace: #<n>
question: <the question text>
options: <list of options>
context: <relevant details>
```

The orchestrator collects all `NEEDS_INPUT` results after each phase. It groups them by trace. It presents them to the user via a single `AskUserQuestion` call. It re-dispatches the affected sub-agents with the answers embedded in their prompts before continuing.

### 4. Mandatory side effects still run

Lifecycle label updates must always execute in the sub-agent. They cannot be deferred to the orchestrator. If the `gh` command fails, record it in the sub-agent result so the orchestrator can retry.

The mandatory label transitions are:

| After step | Command |
|---|---|
| Implementation TDD cycle complete | `gh issue edit <trace_number> --add-label "implemented"` |
| QA verification passes | `gh issue edit <trace_number> --add-label "verified"` |
| Design handoff written | `gh issue edit <issue_number> --add-label "designed"` |

Headless `wtf.refine` has its own mandatory side effect: the audit-trail comment is always posted, per its skill.

### 5. Isolation and worktree

When multiple sub-agents run in parallel, use `isolation: "worktree"`. Each agent then works on an independent copy of the repo. The worktree is branched from the Trace's base branch (see `./branch-setup.md`) at spawn time. Instruct the sub-agent to run `git pull --rebase origin <base_branch>` before starting work. It should not assume any particular local state.

See `./conflict-graph.md` for how to schedule sub-agents so overlapping files never run in parallel.

## Orchestrator checklist

Before spawning sub-agents, the orchestrator should verify:

1. The target skill file exists and can be read.
2. Each sub-agent prompt is fully self-contained: inline instructions, overrides, pre-known context, conflict-free sub-phase membership.
3. A collection point for `NEEDS_INPUT` results is prepared, with a plan for re-dispatch.
4. Label commands are listed in the sub-agent prompt with explicit "this must run even if other steps fail" framing.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall