supered 0.2.0 → 0.3.0

package/docs/roadmap.md

@@ -19,6 +19,7 @@
 
 ## v0.3
 
+- Install Health checks through `supered doctor`.
 - Skill authoring guide with contribution tests.
 - Release automation for tags, notes, and metadata checks.
 - Optional templates for repo launch checklists.

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.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A compact workflow kit for agentic coding sessions.",
   "mcpServers": {},
   "contextFileName": "GEMINI.md"

package/install.sh

@@ -6,6 +6,13 @@ SUPERED_REF="${SUPERED_REF:-main}"
 SUPERED_TARGET="${SUPERED_TARGET:-codex}"
 SUPERED_SOURCE_DIR="${SUPERED_SOURCE_DIR:-}"
 SUPERED_DEST="${SUPERED_DEST:-}"
+SUPERED_SKILLS='using-supered
+shape-the-task
+make-a-map
+build-in-slices
+trace-the-fault
+prove-the-change
+ship-the-work'
 
 usage() {
   cat <<'EOF'
@@ -71,6 +78,23 @@ default_dest() {
   esac
 }
 
+reject_symlink() {
+  [ ! -L "$1" ] || die "Refusing to install symlink: $1"
+}
+
+reject_source_symlinks() {
+  reject_symlink "$1"
+  linked="$(find "$1" -type l -print -quit)"
+  [ -z "$linked" ] || die "Refusing to install symlink: $linked"
+}
+
+reject_destination_symlinks() {
+  [ ! -L "$dest" ] || die "Refusing to install into symlinked destination: $dest"
+  for skill in $SUPERED_SKILLS; do
+    [ ! -L "$dest/$skill" ] || die "Refusing to install into symlinked destination: $dest/$skill"
+  done
+}
+
 download_source() {
   tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/supered.XXXXXX")"
   archive="$tmp_dir/supered.tar.gz"
@@ -100,7 +124,19 @@ if [ -z "$dest" ]; then
   dest="$(default_dest)"
 fi
 
+for skill in $SUPERED_SKILLS; do
+  skill_dir="$source_dir/skills/$skill"
+  [ -d "$skill_dir" ] || die "Missing skill directory: $skill_dir"
+  reject_source_symlinks "$skill_dir"
+  [ -f "$skill_dir/SKILL.md" ] || die "Missing skill file: $skill_dir/SKILL.md"
+done
+
+reject_destination_symlinks
 mkdir -p "$dest"
-cp -R "$source_dir/skills/." "$dest/"
+reject_destination_symlinks
+
+for skill in $SUPERED_SKILLS; do
+  cp -R "$source_dir/skills/$skill" "$dest/"
+done
 
 printf 'Installed Supered for %s at %s\n' "$SUPERED_TARGET" "$dest"

package/lib/eval-pack.js

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { SKILL_ORDER } from "./supered-policy.js";
+
+export const EVAL_CATALOG_VERSION = "0.1";
+export const SCORING_DIMENSIONS = [
+  "clarity",
+  "actionability",
+  "guardrails",
+  "evidence",
+  "outcome"
+];
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function add(errorList, condition, message) {
+  if (!condition) {
+    errorList.push(message);
+  }
+}
+
+export async function readEvalPack(root = process.cwd()) {
+  return {
+    catalog: await readJson(join(root, "docs", "evals", "scenarios.json")),
+    report: await readJson(join(root, "docs", "evals", "baseline-results.json"))
+  };
+}
+
+export async function validateEvalPack(root = process.cwd()) {
+  const errors = [];
+  const { catalog, report } = await readEvalPack(root);
+  const scenarioIds = new Set();
+  const coveredSkills = new Set();
+
+  add(errors, catalog.product === "Supered", "Eval Pack catalog product must be Supered");
+  add(errors, catalog.version === EVAL_CATALOG_VERSION, `Eval Pack catalog version must be ${EVAL_CATALOG_VERSION}`);
+  add(errors, catalog.scoring?.maxScore === 5, "Eval Pack scoring maxScore must be 5");
+  add(
+    errors,
+    JSON.stringify(catalog.scoring?.dimensions ?? []) === JSON.stringify(SCORING_DIMENSIONS),
+    "Eval Pack scoring dimensions are not aligned"
+  );
+  add(errors, catalog.scenarios?.length === 10, "Eval Pack must include 10 scenarios");
+
+  for (const scenario of catalog.scenarios ?? []) {
+    add(errors, /^S\d{2}$/.test(scenario.id), `${scenario.id} must use an S00-style id`);
+    add(errors, !scenarioIds.has(scenario.id), `${scenario.id} must be unique`);
+    scenarioIds.add(scenario.id);
+
+    add(errors, scenario.title?.length >= 12, `${scenario.id} needs a specific title`);
+    add(errors, scenario.prompt?.length >= 80, `${scenario.id} prompt is too thin`);
+    add(errors, scenario.context?.length >= 80, `${scenario.id} context is too thin`);
+    add(errors, scenario.successCriteria?.length >= 3, `${scenario.id} needs success criteria`);
+    add(errors, scenario.expectedEvidence?.length >= 2, `${scenario.id} needs evidence expectations`);
+    add(errors, scenario.primarySkills?.length >= 1, `${scenario.id} needs a primary skill`);
+
+    for (const skill of scenario.primarySkills ?? []) {
+      coveredSkills.add(skill);
+      add(errors, SKILL_ORDER.includes(skill), `${scenario.id} references unknown skill ${skill}`);
+    }
+  }
+
+  for (const skill of SKILL_ORDER) {
+    add(errors, coveredSkills.has(skill), `Eval Pack does not exercise ${skill}`);
+  }
+
+  add(errors, report.product === "Supered", "Eval Pack report product must be Supered");
+  add(errors, report.catalogVersion === EVAL_CATALOG_VERSION, "Eval Pack report catalogVersion is not aligned");
+  add(errors, report.results?.length === 10, "Eval Pack report must include 10 results");
+  add(errors, report.summary?.averageScore >= 4.2, "Eval Pack baseline average should show useful outcomes");
+
+  for (const result of report.results ?? []) {
+    add(errors, scenarioIds.has(result.scenarioId), `${result.scenarioId} does not match a known scenario`);
+    add(
+      errors,
+      JSON.stringify(Object.keys(result.scores ?? {}).sort()) === JSON.stringify([...SCORING_DIMENSIONS].sort()),
+      `${result.scenarioId} scores must cover every scoring dimension`
+    );
+    for (const score of Object.values(result.scores ?? {})) {
+      add(errors, Number.isInteger(score), "Eval Pack scores must be integers");
+      add(errors, score >= 1 && score <= 5, "Eval Pack scores must be between 1 and 5");
+    }
+    add(errors, result.notes?.length >= 80, `${result.scenarioId} needs explanatory scoring notes`);
+    add(errors, result.recommendedSkill?.length > 0, `${result.scenarioId} needs a recommended skill`);
+  }
+
+  return {
+    errors,
+    catalog,
+    report,
+    summary: {
+      scenarioCount: catalog.scenarios?.length ?? 0,
+      resultCount: report.results?.length ?? 0,
+      averageScore: report.summary?.averageScore ?? 0,
+      coveredSkills: SKILL_ORDER.filter((skill) => coveredSkills.has(skill))
+    }
+  };
+}

package/lib/host-install.js

@@ -0,0 +1,88 @@
+import { cp, lstat, mkdir, readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { defaultInstallDest, SKILL_ORDER } from "./supered-policy.js";
+
+async function assertNoSymlinks(path) {
+  const entry = await lstat(path);
+  if (entry.isSymbolicLink()) {
+    throw new Error(`Refusing to install symlink: ${path}`);
+  }
+
+  if (!entry.isDirectory()) {
+    return;
+  }
+
+  const children = await readdir(path);
+  await Promise.all(children.map((child) => assertNoSymlinks(join(path, child))));
+}
+
+async function assertSkillIsInstallable(skillsDir, skill) {
+  const skillDir = join(skillsDir, skill);
+  await assertNoSymlinks(skillDir);
+
+  const skillFile = join(skillDir, "SKILL.md");
+  try {
+    await stat(skillFile);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Missing skill file: ${skillFile}`);
+    }
+    throw error;
+  }
+}
+
+async function assertDestinationPathIsSafe(dest) {
+  try {
+    const destination = await lstat(dest);
+    if (destination.isSymbolicLink()) {
+      throw new Error(`Refusing to install into symlinked destination: ${dest}`);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+async function assertManagedDestinationsAreSafe(dest) {
+  for (const skill of SKILL_ORDER) {
+    const skillDest = join(dest, skill);
+    try {
+      const destination = await lstat(skillDest);
+      if (destination.isSymbolicLink()) {
+        throw new Error(`Refusing to install into symlinked destination: ${skillDest}`);
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+}
+
+export async function installSuperedSkills({ root = process.cwd(), target, dest, home = process.env.HOME } = {}) {
+  if (!target) {
+    throw new Error("Install requires --target.");
+  }
+
+  const installDest = dest ?? defaultInstallDest(target, home);
+  const skillsDir = resolve(root, "skills");
+
+  await assertDestinationPathIsSafe(installDest);
+  await assertManagedDestinationsAreSafe(installDest);
+  for (const skill of SKILL_ORDER) {
+    await assertSkillIsInstallable(skillsDir, skill);
+  }
+
+  await mkdir(installDest, { recursive: true });
+  for (const skill of SKILL_ORDER) {
+    await cp(join(skillsDir, skill), join(installDest, skill), { recursive: true });
+  }
+
+  return {
+    target,
+    dest: installDest,
+    installedSkills: [...SKILL_ORDER]
+  };
+}

package/lib/install-doctor.js

@@ -0,0 +1,181 @@
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { defaultInstallDest, SKILL_ORDER } from "./supered-policy.js";
+
+function shellQuote(value) {
+  if (!/[\s'"\\]/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function fixCommand(target, dest) {
+  return `npx supered@latest install --target ${target} --dest ${shellQuote(dest)}`;
+}
+
+function issue(code, message, extra = {}) {
+  return {
+    code,
+    message,
+    ...extra
+  };
+}
+
+async function lstatOrNull(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function findSymlink(path) {
+  const entry = await lstatOrNull(path);
+  if (!entry) {
+    return null;
+  }
+  if (entry.isSymbolicLink()) {
+    return path;
+  }
+  if (!entry.isDirectory()) {
+    return null;
+  }
+
+  const children = await readdir(path);
+  for (const child of children) {
+    const linked = await findSymlink(join(path, child));
+    if (linked) {
+      return linked;
+    }
+  }
+  return null;
+}
+
+async function readInstalledSkill(dest, skill) {
+  const skillDir = join(dest, skill);
+  const linked = await findSymlink(skillDir);
+  if (linked) {
+    return {
+      linked
+    };
+  }
+
+  const skillFile = join(skillDir, "SKILL.md");
+  const fileStat = await lstatOrNull(skillFile);
+  if (!fileStat) {
+    return {
+      missing: true
+    };
+  }
+  if (fileStat.isSymbolicLink()) {
+    return {
+      linked: skillFile
+    };
+  }
+
+  return {
+    contents: await readFile(skillFile, "utf8")
+  };
+}
+
+export async function inspectSuperedInstall({ root = process.cwd(), target, dest, home = process.env.HOME } = {}) {
+  if (!target) {
+    throw new Error("Doctor requires --target.");
+  }
+
+  const installDest = dest ?? defaultInstallDest(target, home);
+  const sourceSkillsDir = resolve(root, "skills");
+  const issues = [];
+  const missingSkills = [];
+  const changedSkills = [];
+  const installedSkills = [];
+  const command = fixCommand(target, installDest);
+  const destStat = await lstatOrNull(installDest);
+
+  if (!destStat) {
+    return {
+      target,
+      dest: installDest,
+      status: "issues",
+      issues: [
+        issue("missing-destination", `Install destination does not exist: ${installDest}`, {
+          path: installDest
+        })
+      ],
+      installedSkills,
+      missingSkills: [...SKILL_ORDER],
+      changedSkills,
+      fixCommand: command
+    };
+  }
+
+  if (destStat.isSymbolicLink()) {
+    return {
+      target,
+      dest: installDest,
+      status: "issues",
+      issues: [
+        issue("symlinked-destination", `Install destination is a symlink: ${installDest}`, {
+          path: installDest
+        })
+      ],
+      installedSkills,
+      missingSkills,
+      changedSkills,
+      fixCommand: command
+    };
+  }
+
+  for (const skill of SKILL_ORDER) {
+    const expectedPath = join(sourceSkillsDir, skill, "SKILL.md");
+    const expected = await readFile(expectedPath, "utf8");
+    const installed = await readInstalledSkill(installDest, skill);
+
+    if (installed.linked) {
+      issues.push(
+        issue("unsafe-symlink", `Managed skill contains a symlink: ${installed.linked}`, {
+          skill,
+          path: installed.linked
+        })
+      );
+      continue;
+    }
+
+    if (installed.missing) {
+      missingSkills.push(skill);
+      issues.push(
+        issue("missing-skill", `Missing installed skill file: ${join(installDest, skill, "SKILL.md")}`, {
+          skill,
+          path: join(installDest, skill, "SKILL.md")
+        })
+      );
+      continue;
+    }
+
+    installedSkills.push(skill);
+    if (installed.contents !== expected) {
+      changedSkills.push(skill);
+      issues.push(
+        issue("changed-skill", `Installed skill differs from this Supered bundle: ${skill}`, {
+          skill,
+          path: join(installDest, skill, "SKILL.md")
+        })
+      );
+    }
+  }
+
+  return {
+    target,
+    dest: installDest,
+    status: issues.length === 0 ? "ok" : "issues",
+    issues,
+    installedSkills,
+    missingSkills,
+    changedSkills,
+    fixCommand: command
+  };
+}

package/lib/manifest.js

@@ -1,15 +1,9 @@
-import { access, readFile, readdir } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
 
-export const SKILL_ORDER = [
-  "using-supered",
-  "shape-the-task",
-  "make-a-map",
-  "build-in-slices",
-  "trace-the-fault",
-  "prove-the-change",
-  "ship-the-work"
-];
+import { SKILL_ORDER } from "./supered-policy.js";
+
+export { SKILL_ORDER } from "./supered-policy.js";
 
 async function readJson(path) {
   return JSON.parse(await readFile(path, "utf8"));
@@ -72,66 +66,6 @@ export async function collectManifest(root = process.cwd()) {
 }
 
 export async function validateProject(root = process.cwd()) {
-  const errors = [];
-  const checked = ["package.json"];
-  const manifest = await collectManifest(root);
-  checked.push(".codex-plugin/plugin.json");
-  checked.push(".claude-plugin/plugin.json");
-  checked.push(".cursor-plugin/plugin.json");
-  checked.push("gemini-extension.json");
-
-  if (manifest.package.name !== "supered") {
-    errors.push("package.json name must be supered");
-  }
-
-  if (manifest.codexPlugin.name !== "supered") {
-    errors.push(".codex-plugin/plugin.json name must be supered");
-  }
-
-  if (manifest.codexPlugin.interface?.displayName !== "Supered") {
-    errors.push("Codex plugin displayName must be Supered");
-  }
-
-  if (manifest.codexPlugin.skills !== "./skills/") {
-    errors.push("Codex plugin skills path must be ./skills/");
-  }
-
-  const logoPath = manifest.codexPlugin.interface?.logo?.replace(/^\.\//, "");
-  if (logoPath) {
-    checked.push(logoPath);
-    try {
-      await access(join(root, logoPath));
-    } catch {
-      errors.push(`Missing logo file: ${logoPath}`);
-    }
-  } else {
-    errors.push("Codex plugin interface.logo is required");
-  }
-
-  const skills = await listSkills(root);
-  for (const skill of skills) {
-    checked.push(relative(root, skill.path));
-    if (!skill.name) {
-      errors.push(`${relative(root, skill.path)} is missing a name`);
-    }
-    if (!skill.description) {
-      errors.push(`${relative(root, skill.path)} is missing a description`);
-    }
-    if (!/^# /m.test(skill.body)) {
-      errors.push(`${relative(root, skill.path)} is missing an H1`);
-    }
-  }
-
-  const skillNames = skills.map((skill) => skill.name);
-  for (const expected of SKILL_ORDER) {
-    if (!skillNames.includes(expected)) {
-      errors.push(`Missing skill: ${expected}`);
-    }
-  }
-
-  return {
-    errors,
-    checked,
-    skills
-  };
+  const { validateReleaseBundle } = await import("./release-bundle.js");
+  return validateReleaseBundle(root);
 }