---
name: superclarity
description: Entry point and router for a clarify-plan-execute workflow built for long-horizon work tasks. Load this first for any multi-step task, when the user asks for an approach or a plan (规划 / 计划 / 做个方案 / 拆解一下 / 怎么做), or when resuming interrupted work (继续 / 接着做 / 上次做到哪了). Detects which phase applies, loads a domain profile when one fits, owns the .superclarity/ state convention, and reconstructs state after a session ends or context is compacted. Routes to clarifying-intent, surveying-capabilities, drafting-plans, running-plans, and verifying-outcomes, which are phases of this one workflow rather than independent tools. Do NOT use for single-step requests, plain factual questions, or coding-specific methodology.
license: MIT
metadata:
  pack: superclarity
  phase: router
---

# Route the work, own the state

Long tasks do not fail in the middle of a step. They fail at the seams: work starts before anyone agreed what it was, a plan assumes a tool this machine does not have, or the session ends and everything learned evaporates. This skill guards the seams.

Answer the user in whatever language they wrote in. These instructions are English; your replies are not.

## This is the entry point

For any multi-step work task, start here and route from here. The other five skills are phases of one workflow, not five independent tools — entering at `drafting-plans` produces a plan for something nobody agreed to.

If you were loaded mid-workflow anyway, that is fine: read `.superclarity/` first, then continue from the phase the state implies rather than the phase you were called for.

## First move: introspect

Your tools, installed skills, and subagents are usually already in your context. Read that before scanning anything. Probe disk only for what you genuinely cannot see — CLIs on PATH, project scaffolding, config files, or a list your harness does not expose. That is `surveying-capabilities`' job, and it is task-scoped, not exhaustive.

## Which phase applies

| Situation | Go to |
| --- | --- |
| `.superclarity/` holds unfinished work | Resume — see below |
| The ask is vague, broad, or expensive to get wrong | `clarifying-intent` |
| Intent is agreed but you do not know what tooling exists | `surveying-capabilities` |
| Brief approved and capabilities settled, no plan yet | `drafting-plans` |
| An approved plan exists and the user said go | `running-plans` |
| Work looks finished and you are about to report | `verifying-outcomes` |
| One reversible step, seconds of work, no cost | Just do it. Do not ceremonialise a two-minute task. |

## Non-negotiables

1. **No irreversible or costly action without explicit approval.** Reversibility and cost set the gate height — see [risk tiers](references/risk-tiers.md).
2. **Route to the specialist.** If an installed skill covers the domain, the plan goes through it rather than a hand-rolled substitute.
3. **Never invent tooling.** A provider that is not confirmed present does not exist for planning purposes.
4. **Absence of evidence is not evidence of absence.** "We did not observe X" never becomes "X does not exist."

## State lives on disk

Chat history dies at session end and gets compacted mid-task. Files do not. Work of more than a few steps writes to `.superclarity/` in the working directory:

```
.superclarity/
  environment.md          workspace capability inventory (cached, timestamped)
  <task-slug>/
    brief.md              approved intent, scope, non-goals, success criteria
    capabilities.md       capability -> provider resolution, plus gaps
    plan.md               steps with provider, fallback, verification, status
    journal.md            append-only decisions, findings, deviations
    report.md             delivery, coverage, disclosed gaps
    data/                 intermediate artifacts
```

Task lifecycle, what never belongs in these files, and what to do when file writing is unavailable are in [the state model](references/state-model.md).

## Domain profiles

A profile supplies domain knowledge — what must be clarified, a step skeleton, domain acceptance criteria, known pitfalls — without touching the generic workflow. Look in [`profiles/`](profiles/) and in `.superclarity/profiles/` in the user's project. Load it during clarification, not before. If none fits, say so and proceed generically; do not stretch an unrelated profile over the task. To write one, copy [the template](profiles/profile-template.md).

## Resuming

1. Read the state. Never reconstruct it from memory, and never trust memory over the files.
2. Tell the user in three lines: what was agreed, what is done, what is next.
3. Ask whether the brief still holds — stale assumptions are the main risk in resumed work.
4. Continue from where the state actually left off.

Step 4 is where resumed work goes wrong, so its rules — choosing between several unfinished tasks, resuming a brief or plan that was never approved, and reconciling a step that was interrupted mid-flight — are in [the state model](references/state-model.md). Read them before continuing any task you did not start in this session.