From cohesive
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cohesive:cohesivelyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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-bra...
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 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.
| 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 |
| 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. |
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:
extend route → chain: rewrite-specs → implement-cohesively (extend mode)design route (forward-looking and brainstorm-shaped) or rewrite-only route (a direction was already named by the user) — unchanged from pre-L2 behaviorcohesive: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).
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.
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: , , ?"
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).
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?"
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".
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.
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?"
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.
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).
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.
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.
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. |
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 extend route is the structural answer for additive changes — it dispatches implement-cohesively 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.
At most one clarifying question per turn. The router's announcement turn asks at most one forced-choice question per route (forms above) before dispatching the subskill. Subskills with multi-turn dialogs (e.g., brainstorm-design conversational mode) carry their own per-turn budget after dispatch. Question form is always a specific forced choice, never a vague "what do you want?" prompt. Render forced-choice questions through AskUserQuestion per references/output-voice.md §"Forced-choice questions".
Do not implement code from the router itself. The router routes; subskills work. Implementation is delegated to the implement route, which dispatches implement-cohesively. That skill in turn composes superpowers:writing-plans and superpowers:executing-plans once per implementation pass — it does not write code itself either. Cohesive's only code-producing surface is superpowers:executing-plans invoked from inside implement-cohesively.
Honor the dispatch prompt contract. When invoking a subskill, include the relevant fragment from the table above. Subskills depend on this; omitting it produces a duplicate clarifying question on top of an already-routed turn.
Compose with Superpowers when present. Specifically:
superpowers:using-git-worktrees (used by rewrite-specs)superpowers:writing-plans and superpowers:executing-plans (used per-pass by implement-cohesively); superpowers:test-driven-development is consumed indirectly via executing-planssuperpowers:finishing-a-development-branch (recommended after implement-cohesively Implemented verdict; user-invoked, never auto-invoked from the router)Track progress with TodoWrite when chaining 3+ subskills. The user should see the gates as they execute (Decide / Lock / Build), not the underlying subskill IDs.
When the request is ambiguous, prefer this resolution order:
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.audit (substrate) for retrospective requests and design for forward-looking ones — these are the two routes most likely to surface what's actually needed.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.
: skill-1 → skill-2 → skill-3) in the announcement. Users see gates and outcomes, not subskill IDs.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub marktoda/cohesive --plugin cohesive