do

Files (1)

• SKILL.md

SKILL.md (first lines)

# Do — the front door

Single entry point for coding work. Figures out what the user wants, applies the principles, routes to the right workflow, and keeps the full toolkit visible so nothing gets forgotten.

## Phase -1 — load the 1%-rule enforcement (non-negotiable)

`Skill(skill: "using-superpowers")` — installed from `obra/superpowers@using-superpowers` via skills.sh, always-on. Establishes the rule: *if there is even a 1% chance a skill might apply, you MUST invoke it*. No inlined copy here — the upstream skill owns the enforcement text and auto-updates.

### Parallel 1%-rule — team-vs-agent tool choice (non-negotiable)

The skill-level 1%-rule doesn't cover the **tool** choice between `Agent()` fan-out and `team-do`. That decision is made INSIDE `/do` and `/do` sub-skills. The rule here is the same shape:

**If there is even a 1% chance the work benefits from multi-turn coordination, parallel review, staged handoffs, iteration, or a verify-fix loop — route to team-do.** You do not get to decide "this is simple enough for solo Agent()" — the Phase 1b burden-of-proof test decides.

Red flags that mean you're about to pick Agent when team is correct:
- *"This is just a small change."* → run the four-question test (single concern / ≤2 files / no iteration / <15 min). ANY answer "no" → team.
- *"The user is in a hurry."* → team-do is 3–5× faster wallclock on ≥3 parcels. Solo serial is slower.
- *"team-do is overkill here."* → the Phase 1b test decides that, not your intuition.
- *"I'll just spawn a quick Agent() for research."* → if you're about to run ≥3 Agent() calls in parallel, that IS what team-do is for. Use team-do.
- *"team-do has too much ceremony."* → Phase 2 now preloads the team primitives. Entry cost is zero.

## Phase 0 — INVOKE the three base skills as tool calls (non-negotiable)

Before Phase 1 classification, before any `Read`/`Grep`/`Glob`/`Bash`/`Edit`/`Write`/`WebSearch`/`WebFetch`/MCP call, **invoke these three skills via the `Skill` tool**:

```
Skill(skill: "karpathy-guidelines")
Skill(skill: "coding-style")
Skill(skill: "research-first")
```

Make all three calls in one message (parallel). Do not paraphrase or interpret their bodies inline — the Skill tool is what loads their full content into the turn and activates their rules. Reading the skill markdown yourself is a lint failure: it skips activation and wastes tokens.

The three skills are complementary:

- **`karpathy-guidelines`** — behavioral (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution)
- **`coding-style`** — surface style (No comments / Clean + optimized / Self-documenting names / Smallest surface / No dead defense)
- **`research-first`** — research discipline (MCP-first for library claims, date-pin or version-pin, cite inline, never silently assert, delegate heavy research to a subagent)

If you notice partway through a turn that you didn't invoke them at Phase 0, invoke them now, then continue. Don't "catch up by reading" — the tool call is the activation.

The `pre-research-check.sh` hook (PreToolUse on WebSearch / WebFetch / mcp__docfork__* / mcp__deepwiki__* / mcp__github__*) emits an advisory to stderr if a research tool fires before `Skill("research-first")` has been invoked this turn. Treat the advisory as a correction prompt — invoke the skill, then retry.

### Subagents inherit nothing — instruct them to self-load

Subagents spawned via `Agent(...)` start with a **fresh context**. They do NOT inherit main's loaded skills. Main's `Skill("research-first")` invocation only applies to main.

So when main delegates work to a subagent, the `Agent(prompt: ...)` call MUST include a Phase-0 preamble for the subagent:

```
Before any tool call, invoke these in parallel:
  Skill(skill: "karpathy-guidelines")
  Skill(skill: "research-first")       ← include when the subagent does research
  Skill(skill: "coding-style")         ← include when the subagent writes/edits code
Then proceed with the task below.
---
<actual task>
```

Rule of thumb: whichever of the three base skills applies to the subagent's work, name it in the preamble. The subagent invokes them itself at its own Phase 0; main doesn't forward skill content, just the instruction to load.

## Phase 1 — Classify the task (fast)

Read the user's request and decide which bucket fits best:

| Signal in user's message | Route to |
|---|---|
| Any multi-file / multi-part / multi-concern task — "build several", "fix across", "refactor + review", "audit + fix", "plan and implement", "work on N things", or ANY request that fails the four-question solo-qualification test | **team-do** (default for non-trivial work — primary bucket, not a Phase 1b override) |
| any non-trivial feature request ("build X", "add Y", "implement Z") that lacks an existing `tasks/specs/<date>-<topic>.md` spec file, OR fuzzy-scope language ("rough idea", "I'm thinking", "maybe we should", "not sure yet", "figure out") | **brainstorming** (produces a short spec at `tasks/specs/<date>-<topic>.md`, then re-enters Phase 1 with the spec) |
| "help me clarify the spec", "pin down the requirements", "what am I missing", OR a spec at `tasks/specs/*.md` has ≥3 `[NEEDS CLARIFICATION]` markers | **speckit-clarify** (from `dceoy/speckit-agent-skills@speckit-clarify`, installed via skills.sh — faithful port of spec-kit's `/speckit.clarify` max-5-Q bounded loop) |
| "build", "implement", "add", "ship", "create a new …" | **ship-feature** |
| "broken", "error", "crash", "failing test", "bug", "doesn't work" | **fix-bug** |
| "refactor", "clean up", "simplify", "extract", "dedupe", "reorganize" | **refactor-safely** |
| "security review", "audit", "vuln", "is this safe" | **security-audit** |
| "how does this work", "explain", "what is this repo", "onboarding" | **onboard-codebase** |
| "review our stack", "is this the best", "compare alternatives", "what should we swap" | **Phase 3 + `Skill(audit-rigor)`** (audit/review task — load the rigor discipline, then execute with parallel `Agent()` fan-out) |
| "write a skill", "add a skill", "modify the routing", "this skill isn't firing" | **writing-skills** (from `obra/superpowers@writing-skills`, installed via skills.sh — upstream canonical skill-authoring guide with anthropic-best-practices, persuasion-principles, worked examples) |
| "write an eval", "regression test for a prompt", "how do I know this skill still works" | **evals-first** |
| "is this ready to commit", "/commit", "self-review before PR", "about to push" | **pre-review-checklist** (chain BEFORE `pr-review-toolkit:review-pr`) |
| None match, or just a question/small tweak | **Phase 3 (fall-through)** |

When ambiguous, pick based on whether existing behavior changes:
- Behavior changes → ship-feature or fix-bug
- Behavior preserved → refactor-safely
- No code change, just understanding → onboard-codebase

### Done-gate (non-negotiable)

Before you emit "done", "complete", "shipped", "passes", or any claim that your work is finished — AFTER any `Write` / `Edit` / `MultiEdit` tool call in the turn — you MUST invoke `Skill(skill: "verification-before-completion")`. The upstream skill runs the iron-law self-challenge (red → green verification, full test suite re-run, evidence capture) before you're allowed to claim done. The `stop-verification-check.sh` hook emits a post-hoc advisory if you skip it — treat that advisory as a correction prompt and re-invoke on the next turn.

This is the parallel of `research-first` + `stop-research-check.sh`: post-hoc audit + explicit skill-call instruction + never-silent-assert.

### Phase 1b — Team vs Subagent decision

Pick based on **what the work needs to get done correctly**. Not based on cost — cost is not your concern.

| What the work needs | Use |
|---|---|
| Independent parallel reads that all return once (explore + lint + test + scan) | **Subagents** — N parallel `Agent()` calls in one message |
| One-shot specialist reviews that don't argue with each other | **Subagents** |
| Multi-turn coordination — an agent's output at turn 2 depends on another's at turn 1 | **Team** |
| Debate / competing hypotheses — agents must send messages to each other | **Team** |
| Verify → fix loop where reviewers keep prior findings across iterations | **Team** |
| Staged pipeline with handoff docs between phases (plan → exec → verify → fix) | **Team** |

**Default route: team-do. Solo `Agent()` fan-out must justify itself.**

Per Anthropic's official TeamCreate schema: *"When in doubt about whether a task warrants a team, prefer spawning a team."* — `code.claude.com/docs/en/agent-teams`

### The burden-of-proof inversion

To pick **solo `Agent()` fan-out**, ALL FOUR of these must hold (not some — all):

1. Single concern — one logical change, not a set of related changes
2. Touches ≤2 files — counted before you start, not "it should only need 2"
3. No iteration — no verify-fix loop, no "run tests + adjust" cycle expected
4. Total ETA <15 min — a small, bounded operation

If ANY of those four is false → **team-do**. No discretion. "This feels simple enough for solo" is a lint failure — the same rationalizations that `using-superpowers` forbids for skill invocation apply here for the team-vs-agent decision.

From youssefKadaouiAbbassi/yka-code, MIT.

More from youssefKadaouiAbbassi/yka-code