supered 0.1.3 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Small, evidence-first workflows for coding agents.",
   "author": {
     "name": "Farouk Hajjej",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "A compact agent workflow kit for clarifying, building, verifying, and shipping software changes.",
   "author": {
     "name": "Farouk Hajjej",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Small, evidence-first workflows for coding agents.",
   "homepage": "https://fhajjej-ship-it.github.io/Supered/",
   "license": "MIT",

package/README.md

@@ -63,6 +63,25 @@ Host-specific notes:
 
 Marketplace readiness lives in [docs/marketplace-checklist.md](docs/marketplace-checklist.md).
 
+## Which Skill Should I Use?
+
+Use [docs/which-skill.md](docs/which-skill.md) as the quick router:
+
+- unclear task: `shape-the-task`
+- clear but large task: `make-a-map`
+- planned implementation: `build-in-slices`
+- broken or flaky behavior: `trace-the-fault`
+- completion claim: `prove-the-change`
+- commit, publish, or handoff: `ship-the-work`
+
+## Eval Pack
+
+Supered includes a public eval pack so the skills can be judged against realistic work instead of vibes.
+
+- [Scenario catalog](docs/evals/scenarios.json): 10 realistic coding-agent scenarios.
+- [Baseline results](docs/evals/baseline-results.json): scores across clarity, actionability, guardrails, evidence, and outcome.
+- [Eval report](docs/evals/README.md): how to use the scenarios to improve the skills.
+
 ## CLI
 
 ```bash

package/bin/supered.mjs

@@ -1,19 +1,13 @@
 #!/usr/bin/env node
-import { cp, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { listSkills, validateProject } from "../lib/manifest.js";
+import { installSuperedSkills } from "../lib/host-install.js";
+import { listSkills } from "../lib/manifest.js";
+import { validateReleaseBundle } from "../lib/release-bundle.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const [command, ...args] = process.argv.slice(2);
-const installTargets = {
-  codex: ".codex/skills",
-  claude: ".claude/skills",
-  cursor: ".cursor/skills",
-  gemini: ".gemini/skills",
-  opencode: ".opencode/skills"
-};
 
 function printHelp() {
   console.log(`Supered
@@ -42,7 +36,7 @@ async function skillsCommand() {
 }
 
 async function validateCommand() {
-  const result = await validateProject(root);
+  const result = await validateReleaseBundle(root);
   if (result.errors.length > 0) {
     for (const error of result.errors) {
       console.error(`- ${error}`);
@@ -54,29 +48,18 @@ async function validateCommand() {
   console.log(`Supered bundle is valid: ${result.skills.length} skills, ${result.checked.length} files checked.`);
 }
 
-function defaultInstallDest(target) {
-  const home = process.env.HOME;
-  if (!home) {
-    throw new Error("HOME is not set; pass --dest explicitly.");
-  }
-
-  if (installTargets[target]) return `${home}/${installTargets[target]}`;
-  throw new Error(`Unsupported target: ${target}`);
-}
-
 async function installCommand() {
   const targetIndex = args.indexOf("--target");
   const destIndex = args.indexOf("--dest");
   const target = targetIndex === -1 ? "" : args[targetIndex + 1];
-  const dest = destIndex === -1 ? defaultInstallDest(target) : args[destIndex + 1];
+  const dest = destIndex === -1 ? undefined : args[destIndex + 1];
 
-  if (!target || !dest) {
+  if (!target || (destIndex !== -1 && !dest)) {
     throw new Error("Install requires --target <codex|claude|cursor|gemini|opencode>.");
   }
 
-  await mkdir(dest, { recursive: true });
-  await cp(resolve(root, "skills"), dest, { recursive: true });
-  console.log(`Installed Supered skills for ${target} at ${dest}.`);
+  const result = await installSuperedSkills({ root, target, dest });
+  console.log(`Installed Supered skills for ${result.target} at ${result.dest}.`);
 }
 
 try {

package/docs/evals/README.md

@@ -0,0 +1,34 @@
+# Supered Eval Pack
+
+This pack gives Supered a visible usefulness standard: 10 realistic coding-agent scenarios, a simple scoring rubric, and baseline results for the current skill set.
+
+The goal is not to claim scientific benchmark status. The goal is to make the product falsifiable: a reader can see what the skills are supposed to help with, how outcomes are judged, and where the current library is strong or still dependent on project context.
+
+## Files
+
+- [scenarios.json](scenarios.json): 10 realistic coding-agent scenarios with prompts, context, primary skills, success criteria, and expected evidence.
+- [baseline-results.json](baseline-results.json): maintainer-scored baseline results for Supered v0.2.0.
+
+## Scoring
+
+Each scenario is scored from 1 to 5 across five dimensions:
+
+- `clarity`: the skill helps the agent understand what kind of work this is.
+- `actionability`: the skill tells the agent what to do next, not just how to think.
+- `guardrails`: the skill prevents common bad moves such as scope creep, guessing, or premature claims.
+- `evidence`: the skill asks for proof before completion or handoff.
+- `outcome`: the skill increases the chance of a useful user-facing result.
+
+## Baseline Summary
+
+The current baseline average is `4.58 / 5` across the catalog. Strongest areas are release handoff, verification, and fault tracing. The scenarios with lower scores are intentionally product-heavy or environment-dependent, where a skill can guide the agent but cannot replace user priorities, browser access, database access, or security review.
+
+## How To Use It
+
+1. Pick a scenario close to your real task.
+2. Ask an agent to use the recommended Supered skill.
+3. Score the result against the five dimensions.
+4. Add notes when the skill was vague, too strict, or missing a useful recovery path.
+5. Propose a skill improvement or a new scenario when the score exposes a real gap.
+
+This gives contributors a practical way to improve Supered without turning the project into a pile of opinions.

package/docs/evals/baseline-results.json

@@ -0,0 +1,132 @@
+{
+  "product": "Supered",
+  "catalogVersion": "0.1",
+  "summary": {
+    "averageScore": 4.58,
+    "scenarioCount": 10,
+    "scoreScale": "1-5",
+    "method": "Maintainer review of the v0.2.0 Supered skill bodies against the scenario catalog. Scores are intentionally conservative until external user studies exist."
+  },
+  "results": [
+    {
+      "scenarioId": "S01",
+      "recommendedSkill": "shape-the-task",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 4,
+        "evidence": 4,
+        "outcome": 5
+      },
+      "notes": "The skill asks for users, constraints, assumptions, and acceptance signals before implementation, which directly prevents dashboard overreach. Evidence is strong but still depends on user confirmation."
+    },
+    {
+      "scenarioId": "S02",
+      "recommendedSkill": "make-a-map",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 4,
+        "outcome": 5
+      },
+      "notes": "The mapping playbook fits multi-file auth work well because it forces affected areas, checkpoints, and verification commands before edits. External security review may still be needed."
+    },
+    {
+      "scenarioId": "S03",
+      "recommendedSkill": "build-in-slices",
+      "scores": {
+        "clarity": 4,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 4,
+        "outcome": 4
+      },
+      "notes": "The slice discipline prevents a settings redesign from swallowing the small save-confirmation task. The score is slightly lower because visual quality still needs domain judgment."
+    },
+    {
+      "scenarioId": "S04",
+      "recommendedSkill": "trace-the-fault",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "The fault-tracing skill is strongest on this scenario: it demands symptom capture, hypotheses, probes, and proof before patches. The remaining risk is platform access to mobile Safari."
+    },
+    {
+      "scenarioId": "S05",
+      "recommendedSkill": "prove-the-change",
+      "scores": {
+        "clarity": 5,
+        "actionability": 4,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 5
+      },
+      "notes": "The verification skill explicitly blocks premature completion claims and requires fresh proof. Actionability is high, though the exact export check depends on the app's local tooling."
+    },
+    {
+      "scenarioId": "S06",
+      "recommendedSkill": "ship-the-work",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 5
+      },
+      "notes": "The shipping skill aligns directly with public release work: clean status, intended staging, verification, push, release, and public read-back. It is the best fit in the catalog."
+    },
+    {
+      "scenarioId": "S07",
+      "recommendedSkill": "using-supered",
+      "scores": {
+        "clarity": 4,
+        "actionability": 5,
+        "guardrails": 4,
+        "evidence": 4,
+        "outcome": 4
+      },
+      "notes": "The entrypoint helps route a messy request into a first useful workflow instead of trying everything. The score is lower because the request still requires product prioritization."
+    },
+    {
+      "scenarioId": "S08",
+      "recommendedSkill": "trace-the-fault",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "CI recovery benefits from the same diagnosis discipline: start from logs, reproduce, isolate, then patch. Outcome depends on whether the CI failure can be reproduced locally."
+    },
+    {
+      "scenarioId": "S09",
+      "recommendedSkill": "make-a-map",
+      "scores": {
+        "clarity": 4,
+        "actionability": 5,
+        "guardrails": 4,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "The map-and-slice combination handles migration risk well by separating schema, data, and route compatibility. Database-specific rollback details remain project dependent."
+    },
+    {
+      "scenarioId": "S10",
+      "recommendedSkill": "ship-the-work",
+      "scores": {
+        "clarity": 5,
+        "actionability": 4,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "The handoff scenario is well covered because the skill values honest status over false completion. It needs local judgment about whether to commit partial work or leave notes only."
+    }
+  ]
+}

package/docs/evals/scenarios.json

@@ -0,0 +1,212 @@
+{
+  "product": "Supered",
+  "version": "0.1",
+  "description": "A compact public catalog of realistic coding-agent scenarios for checking whether Supered skills are useful in practice.",
+  "scoring": {
+    "maxScore": 5,
+    "dimensions": [
+      "clarity",
+      "actionability",
+      "guardrails",
+      "evidence",
+      "outcome"
+    ],
+    "rubric": {
+      "1": "Absent or actively misleading.",
+      "2": "Present but too vague to guide reliable work.",
+      "3": "Usable with noticeable gaps or extra human correction.",
+      "4": "Strong enough for normal work with minor judgment required.",
+      "5": "Excellent: specific, safe, evidence-driven, and ready to apply."
+    }
+  },
+  "scenarios": [
+    {
+      "id": "S01",
+      "title": "Turn a vague feature request into a buildable slice",
+      "prompt": "Add dashboards for customers so they can understand account health, but keep it simple and do not overbuild it.",
+      "context": "The repo has a React admin app, no product requirements document, three possible user roles, and no obvious owner for metric definitions. The agent must avoid inventing a large analytics system.",
+      "primarySkills": [
+        "using-supered",
+        "shape-the-task"
+      ],
+      "successCriteria": [
+        "Clarifies the target user, first workflow, and non-goals.",
+        "Produces a short brief that can be accepted or corrected.",
+        "Identifies the smallest useful dashboard slice before implementation."
+      ],
+      "expectedEvidence": [
+        "A concise task brief with assumptions called out.",
+        "A list of decisions that need user confirmation before code changes."
+      ]
+    },
+    {
+      "id": "S02",
+      "title": "Map a multi-file authentication change",
+      "prompt": "Add magic-link login to the existing app and make sure the old password login still works.",
+      "context": "The app has API routes, an email sender, session middleware, and browser tests. The request touches security-sensitive paths and must be broken into reviewable changes.",
+      "primarySkills": [
+        "make-a-map",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Lists affected files and ownership boundaries before editing.",
+        "Sequences backend, email, session, and UI work into small checkpoints.",
+        "Names verification commands for old and new login paths."
+      ],
+      "expectedEvidence": [
+        "A short execution map with ordered slices.",
+        "Verification notes covering both magic-link and password login."
+      ]
+    },
+    {
+      "id": "S03",
+      "title": "Implement a narrow UI improvement without scope creep",
+      "prompt": "Make the settings page easier to scan and add a save confirmation when preferences change.",
+      "context": "The settings page is already used by customers, has mixed form components, and has a brittle screenshot test. The agent should improve the workflow without redesigning the app.",
+      "primarySkills": [
+        "build-in-slices"
+      ],
+      "successCriteria": [
+        "Starts with one visible behavior and one verification path.",
+        "Keeps layout and interaction edits separable.",
+        "Avoids unrelated visual redesign or component churn."
+      ],
+      "expectedEvidence": [
+        "A small diff grouped around the settings workflow.",
+        "Passing component or browser verification for the save confirmation."
+      ]
+    },
+    {
+      "id": "S04",
+      "title": "Diagnose an intermittent checkout failure",
+      "prompt": "Checkout sometimes fails with a generic payment error, mostly on mobile Safari. Fix it.",
+      "context": "Logs show several possible causes: token refresh, double-submit, gateway declines, and a recent UI refactor. The agent must investigate before changing code.",
+      "primarySkills": [
+        "trace-the-fault"
+      ],
+      "successCriteria": [
+        "Separates symptom, reproduction attempts, and hypotheses.",
+        "Finds evidence for one root cause before patching.",
+        "Adds or updates a regression check for the observed failure."
+      ],
+      "expectedEvidence": [
+        "A fault trace showing ruled-out hypotheses.",
+        "A failing-then-passing check or a documented reproduction result."
+      ]
+    },
+    {
+      "id": "S05",
+      "title": "Prove a production bug fix before claiming completion",
+      "prompt": "The export button is fixed now, right? Tell the customer we are done and include the exact proof that the filtered CSV download works.",
+      "context": "A prior agent changed CSV generation but did not run the browser workflow. The customer issue involves filters, permissions, and a downloaded file.",
+      "primarySkills": [
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Refuses to claim completion from code changes alone.",
+        "Runs the relevant automated or manual export verification.",
+        "Reports the actual evidence and any untested risk."
+      ],
+      "expectedEvidence": [
+        "Fresh command output or browser verification notes.",
+        "A final status that distinguishes verified behavior from assumptions."
+      ]
+    },
+    {
+      "id": "S06",
+      "title": "Prepare a small public release",
+      "prompt": "Commit this library update, push it, tag a release, and make sure the public install instructions still work.",
+      "context": "The repo is public, has CI, a package manifest, generated screenshots, and possible uncommitted user files. The agent must not overwrite unrelated work.",
+      "primarySkills": [
+        "ship-the-work",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Checks the worktree and stages only intended files.",
+        "Runs release-relevant validation before tagging or publishing.",
+        "Reads back the public release or install path after shipping."
+      ],
+      "expectedEvidence": [
+        "Git status, commit, push, and release URLs.",
+        "Public install or package registry verification."
+      ]
+    },
+    {
+      "id": "S07",
+      "title": "Choose the right workflow for a mixed request",
+      "prompt": "The app is slow, the nav is confusing, and we should probably add AI summaries. Can you just improve it?",
+      "context": "The request mixes performance, design, and new AI features. The agent needs to route the session instead of starting a broad refactor.",
+      "primarySkills": [
+        "using-supered",
+        "shape-the-task"
+      ],
+      "successCriteria": [
+        "Identifies separate work types and risks.",
+        "Chooses a first skill based on the highest uncertainty.",
+        "Offers a narrow next action instead of starting all tasks at once."
+      ],
+      "expectedEvidence": [
+        "A routing decision with the chosen Supered skill.",
+        "A short set of questions or assumptions that unblock the first slice."
+      ]
+    },
+    {
+      "id": "S08",
+      "title": "Recover from a failing CI run",
+      "prompt": "CI is red after the last push. Please inspect the failed job, fix the real cause, and keep the intended feature intact.",
+      "context": "The failure could come from tests, packaging, linting, or browser setup. The agent must inspect the failed job and avoid local-only guesses.",
+      "primarySkills": [
+        "trace-the-fault",
+        "build-in-slices"
+      ],
+      "successCriteria": [
+        "Starts from the failing CI evidence.",
+        "Reproduces or narrows the failure locally before editing.",
+        "Makes the smallest fix that preserves the intended feature."
+      ],
+      "expectedEvidence": [
+        "CI log excerpt or command that identifies the failure point.",
+        "A passing local check and, when possible, a green rerun."
+      ]
+    },
+    {
+      "id": "S09",
+      "title": "Add tests around a risky data migration",
+      "prompt": "Add a migration that backfills missing organization slugs without breaking existing URLs.",
+      "context": "The database has legacy rows, duplicate display names, and routing code that assumes slugs are stable. The migration needs a reversible plan and proof.",
+      "primarySkills": [
+        "make-a-map",
+        "build-in-slices",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Maps schema, data, and route changes before implementation.",
+        "Builds the migration and app compatibility in separate slices.",
+        "Verifies duplicate and legacy-row cases explicitly."
+      ],
+      "expectedEvidence": [
+        "Migration test cases or dry-run output for edge cases.",
+        "Application route checks for old and new organization URLs."
+      ]
+    },
+    {
+      "id": "S10",
+      "title": "Hand off unfinished work honestly",
+      "prompt": "I need to stop here. Leave the branch in a state another engineer can continue from.",
+      "context": "The agent has partial implementation, one failing test, and two unverified assumptions. The handoff must be useful without pretending the work is done.",
+      "primarySkills": [
+        "ship-the-work",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Separates completed, partial, and unstarted work.",
+        "Lists failing or skipped checks clearly.",
+        "Leaves next steps and evidence paths for the next engineer."
+      ],
+      "expectedEvidence": [
+        "A handoff note with known status and blockers.",
+        "Command output showing the current failing or passing checks."
+      ]
+    }
+  ]
+}

package/docs/index.html

@@ -15,6 +15,7 @@
       </a>
       <nav>
         <a href="#skills">Skills</a>
+        <a href="#proof">Proof</a>
         <a href="#install">Install</a>
         <a href="https://github.com/fhajjej-ship-it/Supered">GitHub</a>
       </nav>
@@ -65,6 +66,28 @@
         </div>
       </section>
 
+      <section id="proof" class="proof" aria-labelledby="proof-title">
+        <div class="section-head">
+          <p class="eyebrow">Proof</p>
+          <h2 id="proof-title">Eval pack, not vibes.</h2>
+          <p>Supered ships with 10 realistic coding-agent scenarios and a baseline scoring pass across clarity, actionability, guardrails, evidence, and outcome.</p>
+        </div>
+        <div class="proof-grid">
+          <a href="https://github.com/fhajjej-ship-it/Supered/blob/main/docs/which-skill.md">
+            <span>Guide</span>
+            <strong>Which skill should I use?</strong>
+          </a>
+          <a href="https://github.com/fhajjej-ship-it/Supered/blob/main/docs/evals/scenarios.json">
+            <span>Catalog</span>
+            <strong>10 realistic coding-agent scenarios</strong>
+          </a>
+          <a href="https://github.com/fhajjej-ship-it/Supered/blob/main/docs/evals/README.md">
+            <span>Eval pack</span>
+            <strong>How usefulness is scored</strong>
+          </a>
+        </div>
+      </section>
+
       <section id="install" class="install" aria-labelledby="install-title">
         <div>
           <p class="eyebrow">Install</p>

package/docs/skill-design-principles.md

@@ -0,0 +1,25 @@
+# Skill Design Principles
+
+Supered skills are written as operating playbooks, not inspirational prompts. The description is only a trigger. The body carries the useful work: required inputs, a procedure, evidence expectations, guardrails, failure handling, and quality gates.
+
+## Source Guidance
+
+- OpenAI's skill guidance emphasizes concise, reusable task instructions that can be invoked when the model needs a specific capability: https://openai.com/academy/skills/
+- OpenAI's practical agent guide frames agents as systems that need clear task boundaries, reliable handoffs, tool use, and verification loops: https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/
+- Anthropic's Agent Skills guidance describes skills as modular capability folders with instructions and optional resources, loaded only when relevant: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
+- Anthropic's agent-building guidance favors simple, composable workflows, clear routing, explicit evaluator patterns, and measured autonomy: https://www.anthropic.com/engineering/building-effective-agents
+- OpenAI's prompt engineering best practices reinforce direct instructions, concrete examples, explicit constraints, and clear desired outputs: https://help.openai.com/en/articles/6654000-playground-and-prompt-engineering
+
+## Supered Standards
+
+Every bundled skill should meet these standards:
+
+- Trigger-only metadata: the frontmatter description starts with `Use when`, stays short, and does not summarize the procedure.
+- Progressive disclosure: the first page gives the operating path; deeper examples and resources are only included when they help the agent act.
+- Evidence-first completion: each workflow names what proof must exist before the agent claims progress.
+- Guardrails over vibes: each skill states hard stop conditions and behaviors that must not happen.
+- Failure-mode literacy: common breakdowns are named with recovery moves.
+- Concrete examples: scenarios show what good use looks like in real development work.
+- Testable quality: repository tests enforce the structural minimum so the skills cannot drift back into thin paragraphs.
+
+The goal is not more text for its own sake. The goal is a compact professional standard: when an agent opens a Supered skill, it should know when to use it, how to proceed, when to stop, what to show, and how to prove the result.

package/docs/styles.css

@@ -176,6 +176,7 @@ h3 {
 }
 
 .workflow,
+.proof,
 .install {
   border-top: 1px solid var(--line);
   padding: 68px clamp(24px, 6vw, 84px);
@@ -209,12 +210,47 @@ h3 {
 }
 
 .steps p,
+.proof p,
 .install p {
   color: var(--muted);
   font-size: 18px;
   line-height: 1.45;
 }
 
+.proof-grid {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  margin-top: 30px;
+}
+
+.proof-grid a {
+  background: white;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  display: grid;
+  gap: 14px;
+  min-height: 150px;
+  padding: 22px;
+}
+
+.proof-grid a:hover {
+  border-color: var(--teal);
+}
+
+.proof-grid span {
+  color: var(--orange);
+  font-size: 13px;
+  font-weight: 850;
+  text-transform: uppercase;
+}
+
+.proof-grid strong {
+  color: var(--navy);
+  font-size: 22px;
+  line-height: 1.15;
+}
+
 .install {
   align-items: start;
   display: grid;
@@ -269,6 +305,10 @@ code {
     grid-template-columns: 1fr;
   }
 
+  .proof-grid {
+    grid-template-columns: 1fr;
+  }
+
   .hero-media {
     justify-items: start;
   }

package/docs/which-skill.md

@@ -0,0 +1,33 @@
+# Which Skill Should I Use?
+
+Start with the shape of the work, not the name of the tool.
+
+| Situation | Use this skill | Why |
+| --- | --- | --- |
+| The request is broad, mixed, or risky and you are not sure where to begin. | `using-supered` | Routes the session to the right next workflow. |
+| The user asks for something vague, underspecified, or easy to overbuild. | `shape-the-task` | Produces a short brief, assumptions, non-goals, and acceptance signals. |
+| The direction is approved but the files, order, or checks are unclear. | `make-a-map` | Turns intent into an execution map with checkpoints and verification. |
+| You are implementing code, docs, packaging, or site changes. | `build-in-slices` | Keeps work small, reviewable, and easier to recover from. |
+| Something is broken, flaky, confusing, or explained only by guesses. | `trace-the-fault` | Forces symptom capture, hypotheses, probes, and evidence before patches. |
+| You are about to say work is done, fixed, published, or ready. | `prove-the-change` | Requires fresh proof before any completion claim. |
+| The work needs commit, push, release, deploy, publish, or public handoff. | `ship-the-work` | Makes shipping part of the work and preserves evidence for readers. |
+
+## Fast Routing
+
+- If the task is unclear: start with `shape-the-task`.
+- If the task is clear but large: start with `make-a-map`.
+- If the task is already planned: start with `build-in-slices`.
+- If behavior is broken: start with `trace-the-fault`.
+- If you are making a claim: start with `prove-the-change`.
+- If the work leaves your machine: start with `ship-the-work`.
+
+## Combining Skills
+
+Good sessions often use two or three skills in order:
+
+- New feature: `shape-the-task` -> `make-a-map` -> `build-in-slices` -> `prove-the-change`.
+- Bug fix: `trace-the-fault` -> `build-in-slices` -> `prove-the-change`.
+- Public release: `prove-the-change` -> `ship-the-work`.
+- Messy request: `using-supered` -> whichever skill the routing decision selects.
+
+Do not load every skill just because they exist. Use the smallest workflow that changes the outcome.