clarity-flow — the explicit ClarityKit design flow

An optional, explicitly-activated flow that composes the ClarityKit toolbox into a progressive path: from a rough direction to an implementation-ready design. This skill owns process (ordering, necessity judgment, resume state, the closing ledger); the clarify-* skills own content. It never self-activates and never hijacks a plain design conversation.

Activation — the only way in

Activate when — and only when — the user explicitly asks for the ClarityKit flow (any language, any name for it: "use clarity-flow", "walk the ClarityKit stages"). A governing host workflow whose own instructions call for ClarityKit counts as the explicit ask. Discussing requirements or architecture without that explicit ask is NOT activation — answer in plain conversation; no skill runs and no skip ceremony applies.

On activation, decide three things. These three decisions together cost at most one confirmation round (the defaults usually need none — later steps have their own, separate interaction points):

1. Entry mode.
   • greenfield (default): a new product/project. Start at direction.
   • re-entry: a new feature inside an existing, already-designed system (user says so, or the staging dir holds prior approved artifacts). Do NOT redo direction or requirements — mark them given in flow.yaml, consult existing artifacts read-only as constraints, and enter at behavior (or data when the feature is data-shaped). Changes to existing artifacts are additive deltas; mutating existing behavior is a back-jump, not an edit.
2. Middle order. The two legal orders through the middle are:
   • behavior-first (DEFAULT): scenarios pin what the system must do before technology shapes it. Use unless the user says otherwise.
   • arch-first: the user states it, or hard technology constraints dominate (mandated platform, integration that forces the stack). If the user did not state a preference, proceed with the default and attach one line: "behavior-first chosen by default — say the word if you want architecture first."
3. Scaffold. Run clarity init, then write docs/clarity/flow.yaml (schema below), announce the flow in two lines (steps + order + where you're entering), and enter the first step immediately. No opening ceremony beyond that. In re-entry mode, put the 5-line feature brief (what job, for whom, one non-goal) into the direction step's note so it survives across sessions. (Later clarity init <name> calls for behavior modules: names are lowercase, digits, hyphens.)

Inside a host workflow — sub-flow mode

ClarityKit's natural habitat is the thinking stage before implementation: requirements discussion, design brainstorming, or the moment before an implementation plan is written — frequently inside a host workflow (e.g. superpowers brainstorming, a spec-driven process, a planning phase). When activated there, this flow runs as a SUB-FLOW of the host's thinking stage:

• The host owns the session — when we enter, when we leave, what happens before and after. Never restructure, extend, or shortcut the host's own stages.
• clarity-flow owns the clarification inside — steps, artifacts, flow.yaml, the closing ledger.
• Two output layers. ClarityKit artifacts (diagrams, models, contracts, ADR, commission.md) stay in docs/clarity/ as the design record; the HOST's deliverables (its spec, plan, or ticket documents) receive the conclusions. Write the host's format as the primary output — never force the host to adopt ClarityKit files.
• Exit hands upward. When commission is signed, hand the delegation ledger and risk list to the host so its plan absorbs them; announce the SUB-FLOW complete, never the host workflow itself.

The flow

direction → requirements → { behavior ⇄ architecture } → data → ui → commission

The middle pair (behavior, architecture) runs in the chosen order; data follows both, then ui, then commission. In re-entry mode, architecture usually records skipped with note "stack fixed by the existing system" — or runs as a delta when the feature adds a component.

The step-entry loop (the heart of this skill)

For the next pending step, BEFORE invoking its skill:

1. Judge necessity against the skip condition above + the skill's entry criteria.
2. Necessary → invoke the skill directly. No permission round-trip. The skill's own batched interview already contains the one interaction point where the user weighs in — including which optional diagrams to draw (each with your recommendation and reason; default at most 2 optional diagrams per module, more only if the user asks).
3. Want to skip → one batched question, nothing else in it:

   I propose skipping behavior for this module — it's a one-shot transform with no state. OK to skip? (If we run it, I'd also draw the failure-path view because ___.) The user's single reply decides. On confirmation: record skipped + one-line reason in flow.yaml, move on, never re-litigate.

4. Per-module granularity (behavior only). behavior is evaluated and entered per module — one module may need the YAML tier while another needs a one-diagram light tier; different modules may choose different optional diagrams. data and ui run ONCE each, project-level, after the middle pair.

When a step's skill reports user approval: set its status done, list its artifacts (relative to the staging dir), and add a one-line note of what was decided. Then repeat the loop. flow.yaml is updated immediately at every status change — it is the resume point for any future session.

Back-jumps — reopen decisions, not stages

When a later step invalidates an earlier conclusion (a scenario no component can own; a contract that doesn't fit its boundary; an error with no recovery scenario):

1. Name the specific decision that flipped, never "redo the stage".
2. Estimate the blast radius ("this invalidates field X and state Y — small touch").
3. Set the CURRENT step back to pending (or done if its other decisions survive), then set the owning step's status to active with a note — never leave two steps active (the validator rejects that). Redo only the invalidated decisions and their artifacts; when the redo is approved, re-enter the step you left.
4. Downgrade valve: the user may refuse the jump and accept the flaw — then it goes on the commission risk list as accepted, and the flow moves on.
5. Thrash rule: any decision that flips twice is being made at the wrong layer or with missing information — either commission a probe against it or escalate one level up (a twice-flipped structure decision is usually a disguised behavior decision). This rule is mandatory; it is the anti-loop governor.

Commission — the terminal step (this skill performs it)

Never skipped, never delegated. Cheap, because it mostly assembles what the flow already surfaced. Write docs/clarity/commission.md:

1. Delegation ledger — two lists:
   • the implementing agent may decide autonomously (library choices within constraints, internal naming, error message wording, standard UI states, anything inside a stated constraint);
   • forces a return to the user (anything touching a contract, a persistent field, an unrecoverable transition, a new dependency, a non-goal boundary).
2. Risk list — top 3–5 risks as "if we're wrong about X, we redo Y", each with an explicit accept or probe decision. A probe is a targeted spike (one risky algorithm, one hostile-input test), never a whole-product prototype.
3. Consistency sweep — scenarios ↔ behavior models ↔ contracts ↔ diagrams agree; clarity check green; every open question is either closed or on the ledger.

Present both lists in the conversation. The user signs off line by line — that signature is the terminal act. Then: mark commission done in flow.yaml and run clarity publish once so the site's progress chips show the finished flow (commission itself produces no diagrams — this closing publish is the only one it needs), and announce the flow complete. Until the signature lands, "implementation-ready" is an assertion, not a fact.

flow.yaml — schema (you maintain it; the CLI validates it)

# TEMPLATE — pick ONE value from each a|b|c union; see examples/flow.yaml for a
# filled-in one. The validator errors on the literal union strings.
flow:
  id: <kebab-case>            # project or module scope
  order: behavior-first | arch-first
steps:
  direction:      { status: pending|active|done|skipped|given, artifacts: [...], note: <one line> }
  requirements:   { ... }
  behavior:       { ... }
  architecture:   { ... }
  data:           { ... }
  ui:             { ... }
  commission:     { status: ..., artifacts: [commission.md] }

• artifacts paths are relative to the staging dir. given means settled elsewhere (re-entry): consulted read-only, not performed.
• Edit the file directly with your file-editing tool. Every clarity command validates it and prints problems as flow.yaml: lines — repair them promptly (they are usually a stale artifact path or a missing note).
• On any session where the flow was previously activated: run clarity status first — one call printing flow progress, the active step with its note, the artifact inventory, preview state, and site freshness. Resume from there; do not re-derive state by listing directories or reading files one by one.

Shared conventions (all ClarityKit capabilities)

• Invocation is explicit everywhere. Each capability runs only when the user names it or a governing flow walks into its step — never self-activated from topic overlap. In plain design conversation, answer plainly.
• Paths are derived, never chosen. Artifacts live in the staging dir <projectRoot>/docs/clarity/ (run clarity root). The ADR is the one handoff artifact (clarity adr → docs/adr/, automatic numbering).
• Presentation contract. Decision-grade content lives in the conversation; files are archives for future agents. Published diagrams carry %% title: (plus %% caption: / %% group: when useful); refer to diagrams by exact browser title.
• Every diagram is verified + published with clarity publish (check-then-build). Never start the preview server yourself — that is the user-invoked clarity-preview skill.
• All tools run through the clarity CLI — never relative tool paths. If clarity is not found: export PATH="$HOME/.local/bin:$PATH" and retry ONCE; still missing → STOP and tell the user to finish the ClarityKit install. Never improvise alternatives (nohup, setsid, hand-rolled servers).