reffy-cli 1.7.1 → 1.8.0

package/README.md

@@ -33,6 +33,7 @@ Command summary:
 - `reffy plan create`: generates proposal, task, design, and spec scaffolds from indexed Reffy artifacts.
 - `reffy plan validate|list|show|archive`: manages the planning lifecycle under `.reffy/reffyspec/`.
 - `reffy spec list|show`: inspects current spec state under `.reffy/reffyspec/`.
+- `reffy skill list|show|create|validate`: lists, prints, scaffolds, and validates task-oriented skills under `.reffy/skills/`.
 - `reffy remote init|status|push|ls|cat|snapshot`: links, publishes, and inspects a Paseo-backed remote `.reffy/` workspace.
 - `reffy remote workspace create|get` and `reffy remote project register|list`: control-plane operations against the workspace manager actor.
 - `reffy diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from compatible `spec.md` files.
@@ -58,6 +59,10 @@ reffy plan create --change-id add-login-flow --artifacts login-idea.md
 reffy plan list --output json
 reffy plan archive add-login-flow
 reffy spec show auth --output json
+reffy skill list --output json
+reffy skill show create-change
+reffy skill create my-workflow
+reffy skill validate
 reffy remote init --provision
 reffy remote status --output json
 reffy remote push
@@ -97,6 +102,52 @@ reffy spec list
 reffy spec show remote-workspace-manager --output json
 ```
 
+## Skills
+
+Reffy gives *procedures* the same deterministic treatment it gives data. Skills are named, agent-readable task recipes that live as files under `.reffy/skills/`, one directory per skill:
+
+```
+.reffy/skills/
+├── create-change/
+│   └── SKILL.md
+└── <your-skill>/
+    └── SKILL.md
+```
+
+Each `SKILL.md` opens with frontmatter that doubles as a discovery index, followed by a markdown body:
+
+```markdown
+---
+name: create-change
+description: Turn one or more ideation artifacts into a ReffySpec change proposal.
+triggers: ["new change", "plan create", "turn artifact into proposal"]
+commands: ["reffy plan create", "reffy plan validate"]
+managed: true
+---
+
+## When to use this skill
+...
+
+## Steps
+1. ...
+```
+
+- `name`, `description`, and `triggers` are required; `triggers` must have at least one entry so the skill is discoverable.
+- `commands` declares the CLI commands the skill wraps, which `reffy doctor` cross-checks against the installed CLI.
+- `managed: true` marks skills Reffy owns. `reffy init` scaffolds and refreshes managed skills in place and never touches unmanaged ones.
+
+`reffy init` ships six managed skills covering the core workflows: `create-artifact`, `create-change`, `archive-change`, `inspect-specs`, `sync-remote`, and `diagnose`. Author your own with `reffy skill create <name>`.
+
+```bash
+reffy skill list                       # name + description + managed flag
+reffy skill list --output json         # harness-native descriptors for programmatic discovery
+reffy skill show create-change         # print the procedure body
+reffy skill create my-workflow         # scaffold an unmanaged skill from a template
+reffy skill validate                   # check the frontmatter contract for every skill
+```
+
+`reffy skill list`/`show --output json` emit a tool/function-definition style descriptor (`name`, `description`, `triggers`, `commands`, `managed`, `path`; `show` adds `body`) so an agent harness can feed skills into its own discovery machinery without parsing markdown. Skills are discovered from the filesystem and validated by contract — they are not indexed in `manifest.json`. `reffy validate` enforces the skills contract (required fields, unique names, kebab-case directory names matching `name`) alongside the manifest, and `reffy doctor` warns when a skill's declared commands drift from the installed CLI.
+
 ## Remote Sync
 
 Reffy can publish the local `.reffy/` workspace to a Paseo-backed remote workspace and inspect it later with native CLI commands.
@@ -315,6 +366,10 @@ Useful side commands during the arc:
 - `reffy plan show <change-id>` — inspect one change's state without opening every file.
 - `reffy spec list` / `reffy spec show <capability>` — see the canonical specs the deltas will land into.
 
+### Representing pivots
+
+Pivots, deprecations, and wind-downs are not a separate concept in ReffySpec — they are ordinary changes whose delta is mostly REMOVED or MODIFIED requirements instead of ADDED ones. Because every change's `specs/<capability>/spec.md` is already a delta against the canonical spec, a course correction reuses the same machinery as a feature addition: scaffold a change, author a delta that removes or rewrites the relevant requirements, pair it with code-removal tasks, and archive it when shipped. The history of pivots stays legible as a series of deltas under `changes/archive/`, rather than getting buried in code commits.
+
 ### Reference implementation in this repo
 
 - `AGENTS.md`: contains both managed instruction blocks and encodes sequencing.

package/dist/cli.js

@@ -12,6 +12,7 @@ import { DEFAULT_PLANNING_RELATIVE_DIR, looksLikePlanningDir, resolveCanonicalPl
 import { listPlanningChanges, showPlanningChange, validatePlanningChange } from "./plan-runtime.js";
 import { assertWorkspaceSummaryIdentity, collectWorkspaceDocuments, describeRemoteLinkage, ensureManagerInit, ensureWorkspaceTarget, extractWorkspaceSummaryIdentity, PaseoManagerClient, PaseoWorkspaceBackendClient, readRemoteConfig, RemoteHttpError, removeWorkspaceTarget, requireWorkspaceIdentity, resolveRemoteConfigPath, resolveRemoteTarget, resolveSelectedWorkspaceId, updateRemoteConfigMetadata, validateImportResult, } from "./remote.js";
 import { DEFAULT_REFS_DIRNAME, detectWorkspaceState, looksLikeRefsDir } from "./refs-paths.js";
+import { createSkill, discoverSkills, findSkill, scaffoldManagedSkills, validateSkills, } from "./skills.js";
 import { prepareCanonicalPlanningLayout } from "./planning-workspace.js";
 import { ReferencesStore } from "./storage.js";
 import { listSpecs, showSpec } from "./spec-runtime.js";
@@ -47,6 +48,8 @@ Use \`@/${refsDirName}/AGENTS.md\` to learn:
 - How Reffy owns the runtime while preserving ReffySpec planning files
 - How to store and consume ideation context in \`${refsDirName}/\`
 
+Before performing a Reffy workflow, check \`${refsDirName}/skills/\` (or run \`reffy skill list\`) and follow the matching skill.
+
 Keep this managed block so \`reffy init\` can refresh the instructions.
 
 <!-- REFFY:END -->`;
@@ -83,6 +86,7 @@ These instructions are for AI assistants working in this project.
 - Add/update exploratory artifacts and keep them concise.
 - Run \`reffy reindex\` and \`reffy validate\` after artifact changes.
 - Use \`reffy summarize --output json\` and \`reffy plan create\` to turn artifact context into planning scaffolds.
+- Before performing a Reffy workflow, check \`${refsDirName}/skills/\` (or run \`reffy skill list\`) and follow the matching skill.
 
 ## When To Use Reffy
 
@@ -381,6 +385,7 @@ async function runSetupCommand(commandName, output, repoRoot) {
     const workspace = await prepareCanonicalWorkspace(repoRoot);
     const planning = await prepareCanonicalPlanningLayout(repoRoot);
     const agents = await initAgents(repoRoot);
+    const skills = await scaffoldManagedSkills(repoRoot);
     const store = new ReferencesStore(repoRoot);
     const reindex = await store.reindexArtifacts();
     const payload = {
@@ -393,6 +398,7 @@ async function runSetupCommand(commandName, output, repoRoot) {
         migrated_planning_layout: planning.migrated,
         created_planning_layout: planning.created,
         ...agents,
+        skills,
         refs_dir: store.refsDir,
         manifest_path: store.manifestPath,
         reindex,
@@ -411,6 +417,7 @@ async function runSetupCommand(commandName, output, repoRoot) {
     console.log(`Updated ${agents.root_agents_path}`);
     console.log(`Updated ${agents.reffy_agents_path}`);
     console.log(`Updated ${agents.reffyspec_agents_path}`);
+    console.log(`Skills: ${String(skills.written_skills.length)} managed (${skills.preserved_unmanaged.length} unmanaged preserved)`);
     console.log(`Reindex: added=${String(reindex.added)} removed=${String(reindex.removed)} total=${String(reindex.total)}`);
     if (shouldPrintBootstrapOnboarding(workspace.created, workspace.migrated, planning.created, planning.migrated)) {
         printBootstrapOnboarding();
@@ -434,6 +441,7 @@ function usage() {
         "  summarize  Generate a read-only summary of indexed Reffy artifacts.",
         "  plan       Generate and manage ReffySpec planning scaffolds from indexed Reffy artifacts.",
         "  spec       Inspect current specs from the ReffySpec layout.",
+        "  skill      List, show, create, and validate Reffy skills under .reffy/skills.",
         "  remote     Link, publish, and inspect a Paseo-backed remote Reffy workspace.",
         "  diagram    Render Mermaid diagrams (supports SVG and ASCII).",
     ].join("\n");
@@ -465,6 +473,15 @@ function specUsage() {
         "  reffy spec show <spec-id> [--repo PATH] [--output text|json]",
     ].join("\n");
 }
+function skillUsage() {
+    return [
+        "Usage:",
+        "  reffy skill list [--repo PATH] [--output text|json]",
+        "  reffy skill show <name> [--repo PATH] [--output text|json]",
+        "  reffy skill create <name> [--repo PATH] [--output text|json]",
+        "  reffy skill validate [<name>] [--repo PATH] [--output text|json]",
+    ].join("\n");
+}
 function planUsage() {
     return [
         "Usage:",
@@ -1744,6 +1761,129 @@ async function main() {
         console.error(specUsage());
         return 1;
     }
+    if (command === "skill") {
+        const [subcommand, ...skillArgs] = rest;
+        if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+            console.error(skillUsage());
+            return 1;
+        }
+        const output = parseOutputMode(skillArgs);
+        const repoRoot = parseRepoArg(skillArgs);
+        await prepareCanonicalWorkspace(repoRoot);
+        const positionals = getPlanPositionalArgs(skillArgs);
+        if (subcommand === "list") {
+            const skills = await discoverSkills(repoRoot);
+            const descriptors = skills.map(({ name, description, triggers, commands, managed, path: relPath }) => ({
+                name,
+                description,
+                triggers,
+                commands,
+                managed,
+                path: relPath,
+            }));
+            if (output === "json") {
+                printResult(output, { status: "ok", command: "skill", subcommand: "list", skills: descriptors });
+            }
+            else if (descriptors.length === 0) {
+                console.log("Skills:");
+                console.log("- (none)");
+            }
+            else {
+                console.log("Skills:");
+                for (const skill of descriptors) {
+                    console.log(`- ${skill.name}${skill.managed ? " [managed]" : ""} - ${skill.description}`);
+                }
+            }
+            return 0;
+        }
+        if (subcommand === "show") {
+            const name = positionals[0];
+            if (!name) {
+                console.error("reffy skill show requires a skill name");
+                console.error(skillUsage());
+                return 1;
+            }
+            const skill = await findSkill(repoRoot, name);
+            if (!skill) {
+                if (output === "json") {
+                    printResult(output, { status: "error", command: "skill", subcommand: "show", error: `skill "${name}" not found` });
+                }
+                else {
+                    console.error(`Skill "${name}" not found`);
+                }
+                return 1;
+            }
+            if (output === "json") {
+                printResult(output, {
+                    status: "ok",
+                    command: "skill",
+                    subcommand: "show",
+                    skill: {
+                        name: skill.name,
+                        description: skill.description,
+                        triggers: skill.triggers,
+                        commands: skill.commands,
+                        managed: skill.managed,
+                        path: skill.path,
+                        body: skill.body,
+                    },
+                });
+            }
+            else {
+                console.log(skill.body.trim());
+            }
+            return 0;
+        }
+        if (subcommand === "create") {
+            const name = positionals[0];
+            if (!name) {
+                console.error("reffy skill create requires a skill name");
+                console.error(skillUsage());
+                return 1;
+            }
+            try {
+                const result = await createSkill(repoRoot, name);
+                if (output === "json") {
+                    printResult(output, { status: "ok", command: "skill", subcommand: "create", ...result });
+                }
+                else {
+                    console.log(`Created skill "${result.name}" at ${result.entry_path}`);
+                }
+                return 0;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (output === "json") {
+                    printResult(output, { status: "error", command: "skill", subcommand: "create", error: message });
+                }
+                else {
+                    console.error(message);
+                }
+                return 1;
+            }
+        }
+        if (subcommand === "validate") {
+            const name = positionals[0];
+            const result = await validateSkills(repoRoot, name);
+            const payload = { status: result.ok ? "ok" : "error", command: "skill", subcommand: "validate", ...result };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else if (result.ok) {
+                console.log(`Skills valid: skills=${String(result.skill_count)}`);
+            }
+            else {
+                console.error(`Skills invalid: ${String(result.issues.length)} issue(s)`);
+                for (const issue of result.issues) {
+                    console.error(`error: ${issue.skill}${issue.field ? ` (${issue.field})` : ""}: ${issue.message}`);
+                }
+            }
+            return result.ok ? 0 : 1;
+        }
+        console.error(`Unknown skill subcommand: ${subcommand}`);
+        console.error(skillUsage());
+        return 1;
+    }
     const output = parseOutputMode(rest);
     if (command === "init") {
         printBanner(output);
@@ -1759,6 +1899,7 @@ async function main() {
         const workspace = await prepareCanonicalWorkspace(repoRoot);
         const planning = await prepareCanonicalPlanningLayout(repoRoot);
         const agents = await initAgents(repoRoot);
+        const skills = await scaffoldManagedSkills(repoRoot);
         const payload = {
             status: "ok",
             command: "migrate",
@@ -1770,6 +1911,7 @@ async function main() {
             created_planning_layout: planning.created,
             refs_dir: workspace.state.canonicalDir,
             ...agents,
+            skills,
         };
         if (output === "json") {
             printResult(output, payload);
@@ -1782,6 +1924,7 @@ async function main() {
             console.log(`Updated ${agents.root_agents_path}`);
             console.log(`Updated ${agents.reffy_agents_path}`);
             console.log(`Updated ${agents.reffyspec_agents_path}`);
+            console.log(`Skills: ${String(skills.written_skills.length)} managed (${skills.preserved_unmanaged.length} unmanaged preserved)`);
         }
         return 0;
     }
@@ -1830,12 +1973,20 @@ async function main() {
         const repoRoot = parseRepoArg(rest);
         const store = new ReferencesStore(repoRoot);
         const result = await store.validateManifest();
-        const payload = { status: result.ok ? "ok" : "error", command: "validate", ...result };
+        const skills = await validateSkills(repoRoot);
+        const ok = result.ok && skills.ok;
+        const payload = {
+            status: ok ? "ok" : "error",
+            command: "validate",
+            ...result,
+            skills: { ok: skills.ok, issues: skills.issues, skill_count: skills.skill_count },
+        };
         if (output === "json") {
             printResult(output, payload);
         }
-        else if (result.ok) {
+        else if (ok) {
             console.log(`Manifest valid: artifacts=${String(result.artifact_count)}`);
+            console.log(`Skills valid: skills=${String(skills.skill_count)}`);
             if (result.warnings.length > 0) {
                 for (const warning of result.warnings) {
                     console.log(`warn: ${warning}`);
@@ -1843,15 +1994,23 @@ async function main() {
             }
         }
         else {
-            console.error(`Manifest invalid: ${String(result.errors.length)} error(s)`);
-            for (const error of result.errors) {
-                console.error(`error: ${error}`);
+            if (!result.ok) {
+                console.error(`Manifest invalid: ${String(result.errors.length)} error(s)`);
+                for (const error of result.errors) {
+                    console.error(`error: ${error}`);
+                }
+                for (const warning of result.warnings) {
+                    console.error(`warn: ${warning}`);
+                }
             }
-            for (const warning of result.warnings) {
-                console.error(`warn: ${warning}`);
+            if (!skills.ok) {
+                console.error(`Skills invalid: ${String(skills.issues.length)} issue(s)`);
+                for (const issue of skills.issues) {
+                    console.error(`error: ${issue.skill}${issue.field ? ` (${issue.field})` : ""}: ${issue.message}`);
+                }
             }
         }
-        return result.ok ? 0 : 1;
+        return ok ? 0 : 1;
     }
     if (command === "summarize") {
         const repoRoot = parseRepoArg(rest);

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { validateManifest } from "./manifest.js";
 import { detectWorkspaceState, resolveRefsDirName } from "./refs-paths.js";
+import { findCommandDrift } from "./skills.js";
 async function pathExists(targetPath) {
     try {
         await fs.access(targetPath);
@@ -88,5 +89,16 @@ export async function runDoctor(repoRoot) {
             ? "legacy .references workspace detected; run `reffy migrate` to adopt .reffy/"
             : ".reffy/ is the active workspace",
     });
+    const commandDrift = await findCommandDrift(repoRoot);
+    checks.push({
+        id: "skills_commands_current",
+        level: "optional",
+        ok: commandDrift.length === 0,
+        message: commandDrift.length === 0
+            ? "skill command references match the installed CLI"
+            : `stale skill command references: ${commandDrift
+                .map((drift) => `${drift.skill} -> "${drift.command}"`)
+                .join("; ")}`,
+    });
     return { checks, summary: summarizeChecks(checks) };
 }

package/dist/skills.d.ts

@@ -0,0 +1,96 @@
+export declare const SKILLS_DIRNAME = "skills";
+export declare const SKILL_ENTRY_FILENAME = "SKILL.md";
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    triggers: string[];
+    commands: string[];
+    managed: boolean;
+}
+export interface SkillDescriptor {
+    name: string;
+    description: string;
+    triggers: string[];
+    commands: string[];
+    managed: boolean;
+    path: string;
+}
+export interface SkillRecord extends SkillDescriptor {
+    dir: string;
+    entryPath: string;
+    body: string;
+}
+export interface SkillValidationIssue {
+    skill: string;
+    field?: string;
+    message: string;
+}
+export interface SkillValidationResult {
+    ok: boolean;
+    issues: SkillValidationIssue[];
+    skill_count: number;
+}
+export declare function resolveSkillsDir(repoRoot: string): string;
+export declare function isKebabCase(value: string): boolean;
+/**
+ * Parse the `SKILL.md` frontmatter contract. Supports a leading `---` fenced
+ * block with scalar fields (`name`, `description`, `managed`) and list fields
+ * (`triggers`, `commands`) in either inline (`[a, b]`) or block (`- a`) form.
+ * Returns the parsed frontmatter and the remaining markdown body.
+ */
+export declare function parseSkillFile(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+};
+/**
+ * Discover skills by scanning `.reffy/skills/` for directories containing a
+ * `SKILL.md` entry file. Skills are filesystem-discovered and never indexed in
+ * `manifest.json`.
+ */
+export declare function discoverSkills(repoRoot: string): Promise<SkillRecord[]>;
+export declare function findSkill(repoRoot: string, name: string): Promise<SkillRecord | null>;
+/**
+ * Validate every skill (or one named skill) against the frontmatter contract:
+ * required fields, non-empty triggers, unique names, and kebab-case directory
+ * names matching `name`.
+ */
+export declare function validateSkills(repoRoot: string, name?: string): Promise<SkillValidationResult>;
+/**
+ * The canonical command table of the installed CLI. `reffy doctor` cross-checks
+ * each skill's declared `commands` against this table and warns on drift.
+ */
+export declare const KNOWN_COMMANDS: readonly string[];
+export declare function isKnownCommand(command: string): boolean;
+export interface SkillCommandDrift {
+    skill: string;
+    command: string;
+}
+export declare function findCommandDrift(repoRoot: string): Promise<SkillCommandDrift[]>;
+interface ManagedSkillDefinition {
+    name: string;
+    description: string;
+    triggers: string[];
+    commands: string[];
+    body: string;
+}
+export declare const MANAGED_SKILLS: readonly ManagedSkillDefinition[];
+export declare function isManagedSkillName(name: string): boolean;
+export interface SkillScaffoldResult {
+    created_dir: boolean;
+    written_skills: string[];
+    preserved_unmanaged: string[];
+}
+/**
+ * Create `.reffy/skills/` and write the built-in managed skills. Managed skill
+ * bodies are (re)written in place on every call; unmanaged skills are never
+ * touched.
+ */
+export declare function scaffoldManagedSkills(repoRoot: string): Promise<SkillScaffoldResult>;
+export interface SkillCreateResult {
+    name: string;
+    entry_path: string;
+    created: boolean;
+}
+/** Scaffold a new unmanaged skill from a template. */
+export declare function createSkill(repoRoot: string, name: string): Promise<SkillCreateResult>;
+export {};

package/dist/skills.js

@@ -0,0 +1,471 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveRefsDir } from "./refs-paths.js";
+export const SKILLS_DIRNAME = "skills";
+export const SKILL_ENTRY_FILENAME = "SKILL.md";
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function resolveSkillsDir(repoRoot) {
+    return path.join(resolveRefsDir(repoRoot), SKILLS_DIRNAME);
+}
+export function isKebabCase(value) {
+    return KEBAB_CASE.test(value);
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseScalar(raw) {
+    const trimmed = raw.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function parseInlineList(raw) {
+    const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+    if (inner.trim() === "") {
+        return [];
+    }
+    return inner
+        .split(",")
+        .map((item) => parseScalar(item))
+        .filter((item) => item.length > 0);
+}
+/**
+ * Parse the `SKILL.md` frontmatter contract. Supports a leading `---` fenced
+ * block with scalar fields (`name`, `description`, `managed`) and list fields
+ * (`triggers`, `commands`) in either inline (`[a, b]`) or block (`- a`) form.
+ * Returns the parsed frontmatter and the remaining markdown body.
+ */
+export function parseSkillFile(content) {
+    const normalized = content.replace(/^/, "");
+    const frontmatter = { triggers: [], commands: [], managed: false };
+    const lines = normalized.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        return { frontmatter, body: normalized };
+    }
+    let end = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1) {
+        return { frontmatter, body: normalized };
+    }
+    let currentListKey = null;
+    for (let i = 1; i < end; i += 1) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            continue;
+        }
+        const blockItem = /^\s*-\s+(.*)$/.exec(line);
+        if (blockItem && currentListKey) {
+            const value = parseScalar(blockItem[1]);
+            if (value.length > 0) {
+                frontmatter[currentListKey].push(value);
+            }
+            continue;
+        }
+        const keyMatch = /^([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(line);
+        if (!keyMatch) {
+            continue;
+        }
+        const key = keyMatch[1].trim();
+        const rawValue = keyMatch[2].trim();
+        currentListKey = null;
+        if (key === "name") {
+            frontmatter.name = parseScalar(rawValue);
+        }
+        else if (key === "description") {
+            frontmatter.description = parseScalar(rawValue);
+        }
+        else if (key === "managed") {
+            frontmatter.managed = parseScalar(rawValue).toLowerCase() === "true";
+        }
+        else if (key === "triggers" || key === "commands") {
+            if (rawValue.startsWith("[")) {
+                frontmatter[key] = parseInlineList(rawValue);
+            }
+            else if (rawValue === "") {
+                currentListKey = key;
+            }
+            else {
+                frontmatter[key] = [parseScalar(rawValue)];
+            }
+        }
+    }
+    const body = lines.slice(end + 1).join("\n").replace(/^\n+/, "");
+    return { frontmatter, body };
+}
+function toDescriptor(record) {
+    const { frontmatter, dirName, relPath } = record;
+    return {
+        name: frontmatter.name ?? dirName,
+        description: frontmatter.description ?? "",
+        triggers: frontmatter.triggers,
+        commands: frontmatter.commands,
+        managed: frontmatter.managed,
+        path: relPath,
+    };
+}
+/**
+ * Discover skills by scanning `.reffy/skills/` for directories containing a
+ * `SKILL.md` entry file. Skills are filesystem-discovered and never indexed in
+ * `manifest.json`.
+ */
+export async function discoverSkills(repoRoot) {
+    const skillsDir = resolveSkillsDir(repoRoot);
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => []);
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    const records = [];
+    for (const dirName of dirs) {
+        const dir = path.join(skillsDir, dirName);
+        const entryPath = path.join(dir, SKILL_ENTRY_FILENAME);
+        if (!(await pathExists(entryPath))) {
+            continue;
+        }
+        const content = await fs.readFile(entryPath, "utf8");
+        const { frontmatter, body } = parseSkillFile(content);
+        const relPath = path.relative(repoRoot, entryPath);
+        const descriptor = toDescriptor({ frontmatter, dirName, relPath });
+        records.push({ ...descriptor, dir, entryPath, body });
+    }
+    return records;
+}
+export async function findSkill(repoRoot, name) {
+    const skills = await discoverSkills(repoRoot);
+    return skills.find((skill) => skill.name === name) ?? null;
+}
+/**
+ * Validate every skill (or one named skill) against the frontmatter contract:
+ * required fields, non-empty triggers, unique names, and kebab-case directory
+ * names matching `name`.
+ */
+export async function validateSkills(repoRoot, name) {
+    const skillsDir = resolveSkillsDir(repoRoot);
+    const issues = [];
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => []);
+    const dirs = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((dirName) => name === undefined || dirName === name)
+        .sort();
+    const seenNames = new Map();
+    for (const dirName of dirs) {
+        const label = dirName;
+        const entryPath = path.join(skillsDir, dirName, SKILL_ENTRY_FILENAME);
+        if (!(await pathExists(entryPath))) {
+            issues.push({ skill: label, message: `${SKILL_ENTRY_FILENAME} is missing` });
+            continue;
+        }
+        const content = await fs.readFile(entryPath, "utf8");
+        const { frontmatter } = parseSkillFile(content);
+        if (!frontmatter.name || frontmatter.name.trim() === "") {
+            issues.push({ skill: label, field: "name", message: "frontmatter is missing required field: name" });
+        }
+        else {
+            if (frontmatter.name !== dirName) {
+                issues.push({
+                    skill: label,
+                    field: "name",
+                    message: `name "${frontmatter.name}" does not match directory name "${dirName}"`,
+                });
+            }
+            const prior = seenNames.get(frontmatter.name);
+            if (prior) {
+                issues.push({
+                    skill: label,
+                    field: "name",
+                    message: `duplicate skill name "${frontmatter.name}" (also defined in "${prior}")`,
+                });
+            }
+            else {
+                seenNames.set(frontmatter.name, dirName);
+            }
+        }
+        if (!isKebabCase(dirName)) {
+            issues.push({ skill: label, message: `directory name "${dirName}" is not kebab-case` });
+        }
+        if (!frontmatter.description || frontmatter.description.trim() === "") {
+            issues.push({ skill: label, field: "description", message: "frontmatter is missing required field: description" });
+        }
+        if (frontmatter.triggers.length === 0) {
+            issues.push({ skill: label, field: "triggers", message: "frontmatter field triggers must contain at least one entry" });
+        }
+    }
+    if (name !== undefined && dirs.length === 0) {
+        issues.push({ skill: name, message: `skill "${name}" was not found` });
+    }
+    return { ok: issues.length === 0, issues, skill_count: dirs.length };
+}
+// --- Command-reference staleness -------------------------------------------
+/**
+ * The canonical command table of the installed CLI. `reffy doctor` cross-checks
+ * each skill's declared `commands` against this table and warns on drift.
+ */
+export const KNOWN_COMMANDS = [
+    "reffy init",
+    "reffy bootstrap",
+    "reffy migrate",
+    "reffy doctor",
+    "reffy reindex",
+    "reffy validate",
+    "reffy summarize",
+    "reffy plan create",
+    "reffy plan validate",
+    "reffy plan list",
+    "reffy plan show",
+    "reffy plan archive",
+    "reffy spec list",
+    "reffy spec show",
+    "reffy remote init",
+    "reffy remote status",
+    "reffy remote push",
+    "reffy remote ls",
+    "reffy remote cat",
+    "reffy remote snapshot",
+    "reffy remote workspace create",
+    "reffy remote workspace get",
+    "reffy remote workspace delete",
+    "reffy remote project register",
+    "reffy remote project list",
+    "reffy diagram render",
+    "reffy skill list",
+    "reffy skill show",
+    "reffy skill create",
+    "reffy skill validate",
+];
+/** Reduce a declared command string to its leading non-flag tokens. */
+function commandHead(command) {
+    const tokens = command.trim().split(/\s+/);
+    const head = [];
+    for (const token of tokens) {
+        if (token.startsWith("-")) {
+            break;
+        }
+        head.push(token);
+    }
+    return head.join(" ");
+}
+export function isKnownCommand(command) {
+    const head = commandHead(command);
+    if (head === "") {
+        return false;
+    }
+    return KNOWN_COMMANDS.some((known) => head === known || head.startsWith(`${known} `));
+}
+export async function findCommandDrift(repoRoot) {
+    const skills = await discoverSkills(repoRoot);
+    const drift = [];
+    for (const skill of skills) {
+        for (const command of skill.commands) {
+            if (!isKnownCommand(command)) {
+                drift.push({ skill: skill.name, command });
+            }
+        }
+    }
+    return drift;
+}
+function renderSkillFile(def) {
+    const lines = ["---"];
+    lines.push(`name: ${def.name}`);
+    lines.push(`description: ${def.description}`);
+    lines.push(`triggers: [${def.triggers.map((t) => JSON.stringify(t)).join(", ")}]`);
+    lines.push(`commands: [${def.commands.map((c) => JSON.stringify(c)).join(", ")}]`);
+    lines.push(`managed: ${def.managed ? "true" : "false"}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(def.body.trim());
+    lines.push("");
+    return lines.join("\n");
+}
+export const MANAGED_SKILLS = [
+    {
+        name: "create-artifact",
+        description: "Capture ideation context as a Reffy artifact and register it in the manifest.",
+        triggers: ["new artifact", "capture idea", "add note", "reindex"],
+        commands: ["reffy reindex", "reffy validate"],
+        body: `## When to use this skill
+Use this when you have raw ideation, exploration, or research context to capture before any formal planning.
+
+## Steps
+1. Write the context as a markdown file under \`.reffy/artifacts/\` with a clear, stable, kebab-case filename.
+2. Run \`reffy reindex\` to add the new file to \`.reffy/manifest.json\`.
+3. Run \`reffy validate\` to confirm the manifest still satisfies the v1 contract.
+4. Confirm the artifact appears in the manifest with the expected name and id.
+
+## Failure modes
+- If \`reffy validate\` reports an invalid manifest, fix the reported entry before continuing — do not hand-edit ids.
+- Keep artifacts exploratory; do not duplicate full proposal or spec content here.`,
+    },
+    {
+        name: "create-change",
+        description: "Turn one or more ideation artifacts into a ReffySpec change proposal.",
+        triggers: ["new change", "plan create", "turn artifact into proposal"],
+        commands: ["reffy plan create", "reffy plan validate"],
+        body: `## When to use this skill
+Use this when ideation has converged and you are ready to scaffold a formal ReffySpec change from one or more artifacts.
+
+## Steps
+1. Pick the source artifacts in \`.reffy/artifacts/\` that inform the change.
+2. Run \`reffy plan create --change-id <kebab-id> --artifacts <files> --title "<title>"\`.
+3. Fill in the scaffolded \`proposal.md\`, \`design.md\`, \`tasks.md\`, and \`specs/<capability>/spec.md\` deltas.
+   Each delta requirement needs at least one \`#### Scenario:\`.
+4. Run \`reffy plan validate <change-id>\` and resolve every error before implementing.
+
+## Failure modes
+- If validation reports a missing scenario block, add at least one scenario to each requirement.
+- Use a unique verb-led, kebab-case \`change-id\`.`,
+    },
+    {
+        name: "archive-change",
+        description: "Complete and archive a shipped ReffySpec change, merging its delta into canonical specs.",
+        triggers: ["archive change", "ship change", "plan archive", "merge spec"],
+        commands: ["reffy plan validate", "reffy plan archive", "reffy spec show"],
+        body: `## When to use this skill
+Use this once a change is implemented and verified and you want to fold its spec delta into canonical truth.
+
+## Steps
+1. Confirm every task in \`tasks.md\` is checked off.
+2. Run \`reffy plan validate <change-id>\` one last time.
+3. Run \`reffy plan archive <change-id>\` to move the change under \`changes/archive/<date>-<change-id>/\` and merge its delta specs.
+4. Verify the merge with \`reffy spec show <capability>\`.
+
+## Failure modes
+- If archive reports unmerged or conflicting requirements, inspect the delta against the canonical spec before retrying.`,
+    },
+    {
+        name: "inspect-specs",
+        description: "Ground work in current truth by inspecting canonical specs before changing behavior.",
+        triggers: ["inspect specs", "current truth", "spec list", "spec show"],
+        commands: ["reffy spec list", "reffy spec show"],
+        body: `## When to use this skill
+Use this before drafting a change or implementing behavior, to confirm what the specs already say.
+
+## Steps
+1. Run \`reffy spec list\` to enumerate capabilities and their requirement counts.
+2. Run \`reffy spec show <capability>\` to read the requirements and scenarios for a capability.
+3. Reference the relevant spec from your proposal or skill rather than restating its requirements.
+
+## Failure modes
+- If a capability is missing, it likely needs a new \`ADDED\` delta in a change rather than an edit to canonical specs.`,
+    },
+    {
+        name: "sync-remote",
+        description: "Publish and inspect the local .reffy/ workspace on a Paseo-backed remote.",
+        triggers: ["remote sync", "push workspace", "paseo", "remote status"],
+        commands: ["reffy remote init", "reffy remote status", "reffy remote push", "reffy remote snapshot"],
+        body: `## When to use this skill
+Use this to link, publish, or inspect the shared remote workspace projection.
+
+## Required environment
+- \`PASEO_ENDPOINT\` — the Paseo endpoint URL (never persisted).
+- \`PASEO_TOKEN\` — the bearer token (never persisted by the CLI).
+
+Provide them either by exporting them in your shell or by placing them in a
+\`.env\` file at the repo root — every \`reffy remote\` command auto-loads \`.env\`
+(use \`--env-file PATH\` to point at a different file). Exported shell vars take
+precedence over \`.env\`.
+
+## Steps
+1. Ensure both values are available via the shell or \`.env\`; the CLI fails fast and names a missing one.
+2. First time: \`reffy remote init --provision\` to create the workspace and mint a token. Save the token immediately.
+3. \`reffy remote status\` to confirm linkage and identity.
+4. \`reffy remote push\` to import the full local \`.reffy/\` tree.
+5. \`reffy remote snapshot\` / \`ls\` / \`cat\` to inspect the remote projection.
+
+## Failure modes
+- A missing token makes the stored identifiers in \`.reffy/state/remote.json\` inert — set \`PASEO_TOKEN\`.`,
+    },
+    {
+        name: "diagnose",
+        description: "Diagnose Reffy workspace health and resolve common failure classes.",
+        triggers: ["diagnose", "doctor", "validate", "workspace health"],
+        commands: ["reffy doctor", "reffy validate"],
+        body: `## When to use this skill
+Use this first when a Reffy command misbehaves in an unfamiliar repo.
+
+## Steps
+1. Run \`reffy doctor\` for the required/optional check list.
+2. Run \`reffy validate\` to confirm the manifest contract.
+3. Resolve each failure by class:
+   - Missing \`.reffy/\` or \`AGENTS.md\`: run \`reffy init\`.
+   - Legacy \`.references/\` workspace: run \`reffy migrate\`.
+   - Invalid manifest: fix the reported entry, then re-run \`reffy validate\`.
+   - Skill command drift: update the stale skill's \`commands\` list.
+
+## Failure modes
+- A non-zero exit from \`reffy doctor\` means a required check failed; address required failures before optional warnings.`,
+    },
+];
+export function isManagedSkillName(name) {
+    return MANAGED_SKILLS.some((skill) => skill.name === name);
+}
+/**
+ * Create `.reffy/skills/` and write the built-in managed skills. Managed skill
+ * bodies are (re)written in place on every call; unmanaged skills are never
+ * touched.
+ */
+export async function scaffoldManagedSkills(repoRoot) {
+    const skillsDir = resolveSkillsDir(repoRoot);
+    const created_dir = !(await pathExists(skillsDir));
+    await fs.mkdir(skillsDir, { recursive: true });
+    const written = [];
+    for (const def of MANAGED_SKILLS) {
+        const dir = path.join(skillsDir, def.name);
+        await fs.mkdir(dir, { recursive: true });
+        const entryPath = path.join(dir, SKILL_ENTRY_FILENAME);
+        const content = renderSkillFile({ ...def, managed: true });
+        await fs.writeFile(entryPath, content, "utf8");
+        written.push(def.name);
+    }
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true }).catch(() => []);
+    const preserved_unmanaged = entries
+        .filter((entry) => entry.isDirectory() && !isManagedSkillName(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    return { created_dir, written_skills: written, preserved_unmanaged };
+}
+const UNMANAGED_TEMPLATE_BODY = `## When to use this skill
+Describe the situation in which an agent should follow this skill.
+
+## Steps
+1. First step, naming the exact \`reffy\` command to run.
+2. Next step.
+
+## Failure modes
+- Describe a likely failure and how to recover from it.`;
+/** Scaffold a new unmanaged skill from a template. */
+export async function createSkill(repoRoot, name) {
+    if (!isKebabCase(name)) {
+        throw new Error(`Skill name must be kebab-case: "${name}"`);
+    }
+    if (isManagedSkillName(name)) {
+        throw new Error(`"${name}" is a managed skill name and is reserved by reffy init`);
+    }
+    const skillsDir = resolveSkillsDir(repoRoot);
+    const dir = path.join(skillsDir, name);
+    const entryPath = path.join(dir, SKILL_ENTRY_FILENAME);
+    if (await pathExists(entryPath)) {
+        throw new Error(`Skill "${name}" already exists at ${path.relative(repoRoot, entryPath)}`);
+    }
+    await fs.mkdir(dir, { recursive: true });
+    const content = renderSkillFile({
+        name,
+        description: "One-line summary of what this skill does.",
+        triggers: ["describe", "when", "to", "use"],
+        commands: [],
+        managed: false,
+        body: UNMANAGED_TEMPLATE_BODY,
+    });
+    await fs.writeFile(entryPath, content, "utf8");
+    return { name, entry_path: path.relative(repoRoot, entryPath), created: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Planning system for AI assisted development.",
   "keywords": [
     "reffy",