supered 0.1.3

package/lib/manifest.js

@@ -0,0 +1,137 @@
+import { access, readFile, readdir } from "node:fs/promises";
+import { join, relative } 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"
+];
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function parseSkill(path, contents) {
+  const frontmatter = contents.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!frontmatter) {
+    return {
+      path,
+      name: "",
+      description: "",
+      body: contents
+    };
+  }
+
+  const metadata = Object.fromEntries(
+    frontmatter[1]
+      .split("\n")
+      .map((line) => line.match(/^([A-Za-z0-9_-]+):\s*"?([^"]*)"?$/))
+      .filter(Boolean)
+      .map((match) => [match[1], match[2]])
+  );
+
+  return {
+    path,
+    name: metadata.name ?? "",
+    description: metadata.description ?? "",
+    body: frontmatter[2]
+  };
+}
+
+export async function listSkills(root = process.cwd()) {
+  const skillsDir = join(root, "skills");
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const skills = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map(async (entry) => {
+        const path = join(skillsDir, entry.name, "SKILL.md");
+        return parseSkill(path, await readFile(path, "utf8"));
+      })
+  );
+
+  return skills.sort((left, right) => {
+    const leftIndex = SKILL_ORDER.indexOf(left.name);
+    const rightIndex = SKILL_ORDER.indexOf(right.name);
+    return leftIndex - rightIndex;
+  });
+}
+
+export async function collectManifest(root = process.cwd()) {
+  return {
+    package: await readJson(join(root, "package.json")),
+    codexPlugin: await readJson(join(root, ".codex-plugin", "plugin.json")),
+    claudePlugin: await readJson(join(root, ".claude-plugin", "plugin.json")),
+    cursorPlugin: await readJson(join(root, ".cursor-plugin", "plugin.json")),
+    geminiExtension: await readJson(join(root, "gemini-extension.json"))
+  };
+}
+
+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
+  };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "supered",
+  "version": "0.1.3",
+  "description": "A compact agent workflow kit for clarifying, building, verifying, and shipping software changes.",
+  "type": "module",
+  "homepage": "https://fhajjej-ship-it.github.io/Supered/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fhajjej-ship-it/Supered.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fhajjej-ship-it/Supered/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "supered": "bin/supered.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "validate": "node ./bin/supered.mjs validate",
+    "skills": "node ./bin/supered.mjs skills",
+    "smoke-install": "node ./scripts/smoke-install.mjs",
+    "verify-site": "node ./scripts/verify-site.mjs",
+    "verify-package": "node ./scripts/verify-npm-package.mjs",
+    "prepublishOnly": "npm test && npm run validate && npm run smoke-install && npm run verify-package"
+  },
+  "files": [
+    ".claude-plugin/",
+    ".codex-plugin/",
+    ".cursor-plugin/",
+    ".opencode/",
+    "1.svg",
+    "assets/",
+    "bin/",
+    "docs/",
+    "gemini-extension.json",
+    "install.sh",
+    "lib/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent",
+    "coding-agents",
+    "skills",
+    "planning",
+    "verification",
+    "workflow"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "playwright": "^1.60.0"
+  }
+}

package/skills/build-in-slices/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: build-in-slices
+description: Use when implementing features or repository changes that should be built incrementally and verified as they land.
+---
+
+# Build In Slices
+
+Build one meaningful slice at a time. Each slice should make the repo more complete without hiding unfinished work behind broad claims.
+
+## Steps
+
+1. Start with the smallest test or validator that can catch drift.
+2. Run it and observe the failure when practical.
+3. Implement the slice.
+4. Re-run the relevant check.
+5. Continue only after the evidence matches the claim.
+
+## Slice Examples
+
+- Add manifest tests before writing manifest code.
+- Add CLI behavior before expanding documentation.
+- Add one skill file, validate it, then add the next.
+- Update docs only after the product surface is real.
+
+## Evidence
+
+Every slice should leave behind a file diff and a command result that explains what changed.

package/skills/make-a-map/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: make-a-map
+description: Use when an approved task needs a small execution plan with concrete files, checks, and handoff points.
+---
+
+# Make A Map
+
+Turn an approved brief into a short implementation map. Prefer a handful of crisp steps over a sprawling plan.
+
+## Steps
+
+1. Inspect the repo before planning.
+2. Identify the files that must change.
+3. Split work into slices that can be verified independently.
+4. Put the highest-risk slice first.
+5. Name the exact verification commands.
+
+## Plan Rules
+
+- One active step at a time.
+- No ornamental refactors.
+- Keep tasks scoped to the user's request.
+- Update the map as facts change.
+
+## Evidence
+
+A good map names the next command, the next file, and the reason the step matters.

package/skills/prove-the-change/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: prove-the-change
+description: Use before claiming work is complete, tests pass, a bug is fixed, or a public handoff is ready.
+---
+
+# Prove The Change
+
+Claims need evidence. Run fresh verification close to the final answer.
+
+## Steps
+
+1. List the claims you are about to make.
+2. Pick the command or inspection that proves each claim.
+3. Run the checks.
+4. Read the output and note failures honestly.
+5. Report only what the evidence supports.
+
+## Common Proof
+
+- `npm test` for JavaScript packages.
+- `npm run validate` for Supered bundle integrity.
+- `git status --short` for clean or expected working tree state.
+- A browser or screenshot check for visible UI work.
+
+## Evidence
+
+The final response should include the checks run and the result.

package/skills/shape-the-task/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: shape-the-task
+description: Use when the user has a rough idea and the agent needs to turn it into a short, buildable brief before implementation.
+---
+
+# Shape The Task
+
+Shape the work before building. The goal is a brief that is small enough to act on and concrete enough to test.
+
+## Steps
+
+1. Name the product or change.
+2. Write the target user and the job they need done.
+3. List the smallest useful feature set.
+4. Note constraints, exclusions, and risk.
+5. Confirm the implementation surface: files, package, repo, app, or deployment.
+
+## Brief Format
+
+Use this shape when helpful:
+
+```text
+Outcome:
+Audience:
+Must include:
+Can skip:
+Evidence:
+```
+
+## Evidence
+
+Before moving to implementation, the agent should be able to explain what will be built, what will not be built, and how success will be checked.

package/skills/ship-the-work/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ship-the-work
+description: Use when preparing local work for GitHub: staging, committing, pushing, creating a repository, or handing off a public link.
+---
+
+# Ship The Work
+
+Shipping is the last implementation slice. Treat it with the same care as code.
+
+## Steps
+
+1. Inspect `git status --short`.
+2. Review the changed files for accidental scope.
+3. Run the relevant verification commands.
+4. Stage only intended files.
+5. Commit with a short, specific message.
+6. Push to the intended public repository.
+7. Report the branch, commit, repository URL, and checks.
+
+## Guardrails
+
+- Do not stage unrelated user changes silently.
+- Do not push secrets, local credentials, or generated noise.
+- Do not call a repo public until GitHub confirms visibility.
+
+## Evidence
+
+The handoff should include a GitHub URL and the exact validation that ran before the push.

package/skills/trace-the-fault/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: trace-the-fault
+description: Use when debugging broken behavior, failing tests, confusing output, or deployment failures with an unknown cause.
+---
+
+# Trace The Fault
+
+Debug from symptom to cause. Do not patch randomly.
+
+## Steps
+
+1. Reproduce the symptom.
+2. State what changed, what stayed the same, and what is unknown.
+3. Add the smallest observation that distinguishes likely causes.
+4. Follow the evidence to the responsible boundary.
+5. Fix the cause and keep the reproduction as a check when possible.
+
+## Guardrails
+
+- Do not make multiple unrelated fixes at once.
+- Do not explain a failure before reproducing it.
+- Do not delete evidence until the fix is verified.
+
+## Evidence
+
+Completion requires the original symptom to be checked again after the fix.

package/skills/using-supered/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: using-supered
+description: Use when starting a Supered-guided coding session or when choosing which Supered workflow fits the user's request.
+---
+
+# Using Supered
+
+Supered keeps agent work small, explicit, and verifiable. Start here when a request could benefit from a workflow instead of immediate code.
+
+## When To Use
+
+Use this skill for new features, bug fixes, code cleanup, public repo preparation, or any request where the agent needs to decide how much process is helpful.
+
+## Steps
+
+1. Identify the user's desired outcome in one sentence.
+2. Pick the narrowest matching Supered skill.
+3. State the skill choice briefly before doing the work.
+4. Keep progress visible with short updates.
+5. Finish with evidence, not vibes.
+
+## Skill Map
+
+- `shape-the-task`: rough idea, unclear scope, or multiple possible products.
+- `make-a-map`: approved direction that needs an execution plan.
+- `build-in-slices`: implementation work that should stay incremental.
+- `trace-the-fault`: broken behavior with an unknown cause.
+- `prove-the-change`: completion, test, or deployment claims.
+- `ship-the-work`: commit, push, release, or public GitHub handoff.