cohesively

name

cohesively

description

Use when the user wants to plan, refactor, design, brainstorm, audit, or review code in a way that should preserve specs, behavior matrices, named invariants, semantic linters, gotchas, architectural seams, tests, and future product direction. The Cohesive router. Triggers on "cohesively", "cohesive design", "design substrate-first", "brainstorm a refactor of X", "review the architecture for cohesion", "review the codebase for cohesion", "audit substrate", "what memory is missing", "review my diff for cohesion", "name an invariant", "encode a behavior matrix", "is this the right place to centralize", "rewrite the specs", "validate the rewrite". Picks the right Cohesive workflow, announces it, and chains the relevant subskills.

Cohesively — the Cohesive router

What this skill does

Classifies a Cohesive-shaped request, picks one workflow, announces it in one sentence, and dispatches. Cohesive distinguishes itself from Superpowers: Superpowers optimizes for disciplined implementation; Cohesive optimizes for durable judgment. Both can run in the same session, and Cohesive composes with Superpowers' using-git-worktrees, code-reviewer, and finishing-a-development-branch skills.

The three gates (flagship workflow)

The user-facing model is three gates, not five subskills. Substrate plumbing is agent-internal.

Gate	What the user gets	What runs underneath
Decide	A recommended direction with main risk + structural mitigation	brainstorm-design (which dispatches discover-substrate internally as Step 0)
Lock	The direction pinned into specs + an architectural reflection on how the system feels after	rewrite-specs + validate-rewrite (repair loop internal)
Build	Code that matches the locked design, with spec-coverage verified	implement-cohesively

The gate vocabulary is the load-bearing chat-surface vocabulary. Subskill IDs stay the dispatch keys; the user sees gates.

The three diagnostics (standalone)

Diagnostic	Use for
cohesive:review-codebase	Whole-architecture cohesion review
cohesive:review-diff	PR / branch / working-changes review
cohesive:audit-substrate	What's missing from the docs and tests

Adoption (one-shot)

Skill	Use for
cohesive:init	First-time adoption on a codebase with no Cohesive substrate. Scans for proto-substrate (rules in comments, scars in test names, branchy code) and produces a draft substrate with side-by-side translations explaining each Cohesive type in plain terms. The user reviews and keeps what fits. Runs once; refuses if substrate already exists.

Change-type gate (forward-looking routes)

Before dispatching design, rewrite-only, or extend, the router asks one forced-choice question via AskUserQuestion — the change-type gate. The gate does not fire for review (codebase), review (diff), audit (substrate), init, implement, or artifact (those don't introduce substrate or are past the decision point).

The question is verdict-led: the agent reads signals in the user's request and pre-fills a (Recommended) option; the user can override.

Field	Value
Header	Change type
Question	"Are you extending an existing concept, or introducing a new one?"
Option 1	Extending an existing concept — adds a leaf to an enum, a row to a behavior matrix, a sibling case to an existing pattern, or tightens an existing invariant.
Option 2	Introducing a new concept — new named-invariant family, new behavior matrix, new seam, new admission layer, concept merge/split.

Pre-fill heuristic. The agent recommends Option 1 when the request reads as adding to an existing thing — phrases like "add X to Y," "support a new value for E," "extend Y with Z," "add another like the others." It recommends Option 2 when the request reads as introducing a new thing — phrases like "introduce a new family of X," "add a new admission layer," "create a new matrix for Y," "refactor X into two concepts," "move the seam between A and B." When signals are mixed or absent, default to Option 2 (the safer default — heavier flow handles ambiguity through brainstorm-design's pressure-testing).

Routing from the gate answer:

• Option 1 → extend route → chain: rewrite-specs → implement-cohesively (extend mode)
• Option 2 → design route (forward-looking and brainstorm-shaped) or rewrite-only route (a direction was already named by the user) — unchanged from pre-L2 behavior
• User cancels the form, picks neither, or types free-form ("neither — I'm just exploring") → halt the dispatch and ask one prose follow-up: "Would you like to think through this without committing to a route yet — would cohesive:discover-substrate or cohesive:audit-substrate be more useful?" Do NOT silently fall back to the Option-2 pre-fill; the cancel is a deliberate signal the user wants to step back.

The gate is asked once per session per substrate-shaped request. If the user re-asks for the same change later, do not re-ask (the choice is sticky for the request shape).

Routes

Read the user's request and map to one of the routes below. Trigger phrases are primary; topic and verb tense are secondary. For the three forward-looking routes (design, rewrite-only, extend), the §"Change-type gate" above runs first and picks between them.

Route: design (Decide gate)

When: Forward-looking change that the §"Change-type gate" classified as introducing a new concept (Option 2) — a brainstorm or refactor where there's a real design space to explore. Phrases like "introduce a new family of X," "add a new admission layer," "refactor X into two concepts," "move the seam between A and B."

Stops at: A recommended direction with main risk + structural mitigation. The user approves before the Lock gate runs; design conversations often end here.

Clarifying question (optional, max one): "Which future pressure should this design optimize for most: , , ?"

Route: extend (light path)

When: Forward-looking change that the §"Change-type gate" classified as extending an existing concept (Option 1) — adding a leaf to an enum, a row to a behavior matrix, a sibling case to an existing pattern, or tightening an existing invariant. The substrate already names the concept; the change adds one more member.

Stops at: Code on the branch + a verdict from cross-mirror-reviewer (Covered / Sites Missing / Bigger than extension). The light path skips brainstorm-design (no design space) and validate-rewrite (no novel design to fresh-eyes); it runs rewrite-specs to land the doc change and then implement-cohesively in extend mode for the code change + cross-mirror sweep at end-of-run.

Clarifying question: None at the router level — the gate already classified. The downstream skills (rewrite-specs, implement-cohesively extend mode) ask their canonical questions if their inputs are missing.

Backstop: If cross-mirror-reviewer returns Bigger than extension, the user has mis-classified — the diff went beyond extension shape. The reviewer surfaces the verdict; the user decides to revert or accept retroactively (re-routing through rewrite-specs + validate-rewrite to get fresh-eyes on the now-larger rewrite).

Route: rewrite-only (Lock gate)

When: Forward-looking change that the §"Change-type gate" classified as introducing a new concept (Option 2), AND a direction has been chosen (from a prior brainstorm, a review, or named by the user). The user wants the design pinned into specs. "Rewrite the specs for X", "lock in the design for Y", "update the design docs to reflect Z".

Stops at: Approved verdict + an Architectural reflection — synthesizing how the architecture feels after the lock and what it makes harder downstream. The user approves before the Build gate runs.

Clarifying question (required if no direction is named): "Has a direction been chosen, or should we run brainstorm-design first?"

Route: implement (Build gate)

When: A spec rewrite has been validated (Approved verdict from validate-rewrite) and the user wants code that matches it. "Implement the approved rewrite", "build it", "land docs with implementation", "ship the rewrite".

Stops at: Code on the branch + a spec-coverage verdict (✓ code matches locked design / ✗ drift in N places).

Clarifying question (required if the validation review path is not in the user's request): "Has validate-rewrite returned Approved for a spec rewrite, or should I run the design route first?"

The user can decline the Build gate in favor of superpowers:writing-plans directly — this skips Cohesive's end-of-run reviewer verification of the rewrite, with the user accepting that implementation may drift. Surfaced as the Lock gate's Implement with Superpowers directly alternative — conditionally rendered when the rewrite is small enough that the implement-cohesively flow would be ceremony, per ${CLAUDE_PLUGIN_ROOT}/skills/validate-rewrite/SKILL.md §"Conditional alternatives".

Route: review (codebase)

When: Whole codebase or subsystem architecture review. "Review the architecture", "review the codebase", "is this codebase healthy".

Stops at: A verdict with thesis + top findings + recommended next step.

Route: review (diff)

When: PR / branch / working-changes review. "Review my PR", "review this diff", "review the change".

Clarifying question (only if needed): "Which PR / branch / set of changes? I see uncommitted changes; should I review those, or do you have a PR number?"

Route: audit (substrate)

When: "What memory is missing", "audit substrate", "what specs/invariants/gotchas should we have but don't".

Stops at: A ranked list of artifacts to add (specs, invariants, matrices, gotchas) with file:line evidence and a sketch of what each artifact would say.

Route: init

When: First-time adoption on a codebase with no Cohesive substrate. "Initialize cohesive", "set up substrate", "bootstrap cohesive", "we're new to cohesive", "first time using cohesive on this codebase", "init".

Stops at: A draft substrate directory at docs/cohesive/init-draft/ containing proposed artifacts with side-by-side translations explaining each Cohesive type in plain terms. The user reviews each draft, edits or deletes, and git mvs kept drafts to canonical locations.

The init route is one-shot — init's Hard constraint #1 refuses if substrate already exists. For codebases with existing substrate, the right route is audit (substrate).

Route: artifact (V1 — deferred)

When: "Name an invariant", "encode a behavior matrix", "create a gotcha doc".

Current behavior (until V1): Return the relevant template path and offer to fill it out inline. Dedicated artifact skills (create-invariant, create-matrix) ship in V1.

Cohesive v0.1 doesn't yet have a dedicated `<artifact>` skill. The template is at
${CLAUDE_PLUGIN_ROOT}/references/templates/<template>.md. I can fill it out with you now if you like.

Dispatch prompt contract

The router-driven case requires explicit prereq-state passing — without it, subskills ask the canonical clarifying question on top of an already-routed turn. Most routes need no prereq state because their subskill dispatches cohesive:discover-substrate internally; only the four routes that consume prior-stage artifacts need explicit state:

Route	State the router must pass in the dispatch prompt
design	n/a at dispatch; once rewrite-specs is reached as step 4, pass approved direction: <option + summary> and the branch name
extend	Change surface: <one or two sentences naming what to extend, e.g., 'add HOME to SurfaceRole'>; pass the branch name to step 2 once rewrite-specs has produced it
rewrite-only	Approved direction: <option name + summary> (or route to design first); pass the branch name to step 2 once rewrite-specs has produced it
implement	Validate-rewrite returned **Approved**; review at <path>. plus Branch: design/<slug>. The validation review file carries the **Rewrite-tip:** SHA (captured at Approved time); implement-cohesively parses it from there. Both required.

All other routes (review (codebase), review (diff), audit (substrate), init, artifact) take no router-passed state — their subskills handle discovery and prereqs internally.

Internal-discovery consumers. These skills dispatch cohesive:discover-substrate themselves as Step 0 / Phase 1.0 of their Process: brainstorm-design, audit-substrate, review-codebase, review-diff, and implement-cohesively (extend mode only, scoped to the change surface). The router passes no discovery prereq; each consumer owns the dispatch. An Optional override clause in each consumer's Hard constraint #1 lets the dispatch prompt name a pre-existing discovery report path to skip re-running.

Direct (non-router) invocation. The subskill asks its canonical question (about change surface or scope, not about discovery state — discovery is always internal). The state contract above is router-side only.

Required behavior

1. Announce the route in one sentence. The form is just the outcome — no chain rendering, no methodology framing:

   "."

   The outcome leads with what the user receives. The internal route name (one of: design, extend, review (codebase), review (diff), audit (substrate), rewrite-only, implement, init, artifact) is the dispatch key the router uses to pick its chain — it is agent-internal and does not appear in the announcement string. The chain (which subskills run underneath) is internal too; users see gates and outcomes, not subskill IDs. Per-route outcome sentences:

   Internal route	Announcement outcome sentence
   design	I'll explore design tradeoffs and recommend a direction.
   extend	I'll extend the existing concept and verify all sibling sites are updated.
   review (codebase)	I'll review the architecture for cohesion.
   review (diff)	I'll review the change against the docs.
   audit (substrate)	I'll find what's missing from the docs and tests.
   rewrite-only	I'll lock the chosen direction into specs and pressure-test the architecture.
   implement	I'll build the locked design and verify the code matches it.
   init	I'll scan your codebase for proto-substrate and produce drafts you can review.
   artifact	I'll draft the artifact you asked for.

2. Process before implementation. If behavior or architecture is changing, route through either the Decide gate (for shape-changes) or the §"Change-type gate" extend path (for additions) before any code. The implement route is the structural answer to "implement now" for the standard path — it dispatches implement-cohesively standard mode, which drives code against the spec diff (anchored at the rewrite-tip SHA persisted in the Approved validation review) via single-pass writing-plans + executing-plans + end-of-run dual reviewer dispatch. The route is the structural answer for additive changes — it dispatches extend mode, which drives code via writing-plans + executing-plans + end-of-run cross-mirror reviewer. Freeform code-writing from this skill body is forbidden.

Routing decision logic

When the request is ambiguous, prefer this resolution order:

1. Explicit user instruction ("review the codebase" → review/codebase; "init" / "set up substrate" → init). Always wins.
2. Adoption signal. "First time using cohesive", "we have no substrate", or running against a codebase where discover-substrate would return Empty-substrate verdict → init. The init route is one-shot at adoption time; do not route a returning user with existing substrate to init.
3. Verb tense and implementation cue. Imperative implementation verbs against an existing approved rewrite ("implement", "land", "ship", "build it") → implement. Other forward-looking verbs ("add", "refactor", "build", "design") → ask the §"Change-type gate" question first; Option 1 → extend, Option 2 → design (or rewrite-only if a direction was already named). Retrospective ("review", "audit", "what's wrong with") → review.
4. Scope hints. Whole-repo / subsystem / "the codebase" → review (codebase). Diff / PR / branch / changes → review (diff). Missing / gaps / what's-not-there → audit (substrate).
5. Default. When truly stuck, default to audit (substrate) for retrospective requests and design for forward-looking ones — these are the two routes most likely to surface what's actually needed.

Output

The router produces a single-sentence announcement before the first subskill is invoked. Per ${CLAUDE_PLUGIN_ROOT}/references/output-voice.md §"Density budgets," the router's render budget is 1 sentence — it has no # title and is exempt from the voice-citation grep that applies to longer-rendered skills. The announcement leads with what the user gets — not the methodology framing, not the subskill chain.

The canonical announcement template:

<one-sentence outcome from the per-route table in §"Required behavior" #1>

Then the router invokes the first subskill. Each subskill produces its own output and recommends the next. The user can stop at any gate boundary.

Acceptance criteria

• The router classifies every Cohesive-relevant request to exactly one route.
• The route is announced before any subskill runs, in one sentence, with no chain rendering or methodology framing.
• At most one clarifying question is asked per turn, and each is precise (not vague). Subskills with multi-turn conversational modes carry the per-turn budget through the dispatched dialog.
• Code is not produced from the router.
• The user-facing chat-surface vocabulary is the gate vocabulary (Decide / Lock / Build); subskill IDs are agent-internal.
• Long chains (3+ subskills) are tracked with TodoWrite using gate names.
• The dispatch prompt contract is honored — subskills receive prereq/direction state explicitly.

Red flags

• Rendering the subskill chain (: skill-1 → skill-2 → skill-3) in the announcement. Users see gates and outcomes, not subskill IDs.
• Asking "what do you want?" or "can you tell me more?" — both are too vague. If a question is needed, it must be a specific forced choice.
• Routing to multiple workflows in parallel ("I'll do both a design and a review"). Pick one. If the user really wants both, they can ask twice.
• Producing implementation suggestions or code in the router itself. The router routes; subskills do work.
• Dispatching subskills without the announcement. Users need to know which gate they're in.
• Dispatching subskills without the prereq/direction context the dispatch contract requires. Subskills will then ask their canonical question on top of an already-routed turn.
• Using "substrate" as a user-facing chat-surface term in announcements or trailers. Substrate is agent-internal vocabulary; the user-facing surface is the gate vocabulary.

What this skill is not

• Not the workflow itself. The router picks; the subskills work.
• Not a general-purpose AI coding assistant. Cohesive is opinionated about what kinds of work it does.
• Not a replacement for Superpowers. Cohesive handles substrate; Superpowers handles implementation discipline. Use both.