reffy-cli 0.7.0 → 1.1.1

package/dist/cli.js

@@ -4,9 +4,16 @@ import { existsSync, promises as fs, statSync } from "node:fs";
 import path from "node:path";
 import { renderDiagram } from "./diagram.js";
 import { runDoctor } from "./doctor.js";
-import { DEFAULT_REFS_DIRNAME, looksLikeRefsDir, resolveRefsDirName } from "./refs-paths.js";
+import { archivePlanningChange } from "./plan-archive.js";
+import { createPlanScaffold } from "./plan.js";
+import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { listPlanningChanges, showPlanningChange, validatePlanningChange } from "./plan-runtime.js";
+import { DEFAULT_REFS_DIRNAME, looksLikeRefsDir } from "./refs-paths.js";
+import { prepareCanonicalPlanningLayout } from "./planning-workspace.js";
 import { ReferencesStore } from "./storage.js";
+import { listSpecs, showSpec } from "./spec-runtime.js";
 import { summarizeArtifacts } from "./summarize.js";
+import { prepareCanonicalWorkspace } from "./workspace.js";
 const require = createRequire(import.meta.url);
 const { version: packageVersion } = require("../package.json");
 const REFFY_ASCII = [
@@ -17,6 +24,10 @@ const REFFY_ASCII = [
     "|_|  \\___||_| |_|  \\__, |",
     "                   |___/ ",
 ].join("\n");
+const BOOTSTRAP_AGENT_INSTRUCTION = [
+    'Please read `AGENTS.md` and help me fill out the project context template in `reffyspec/project.md`',
+    "with details about my project, tech stack, architecture, and conventions.",
+].join(" ");
 function buildReffyBlock(refsDirName) {
     return `<!-- REFFY:START -->
 # Reffy Instructions
@@ -29,14 +40,34 @@ Always open \`@/${refsDirName}/AGENTS.md\` when the request:
 - Refers to "reffy", "references", "explore", or "context layer"
 
 Use \`@/${refsDirName}/AGENTS.md\` to learn:
-- Reffy workflow and artifact conventions
-- How Reffy and OpenSpec should be sequenced
+- Reffy workflow for ideation, artifact indexing, and planning scaffolds
+- How Reffy owns the runtime while preserving ReffySpec planning files
 - How to store and consume ideation context in \`${refsDirName}/\`
 
 Keep this managed block so \`reffy init\` can refresh the instructions.
 
 <!-- REFFY:END -->`;
 }
+function buildReffySpecBlock() {
+    return `<!-- REFFYSPEC:START -->
+# ReffySpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open \`@/${DEFAULT_PLANNING_DIRNAME}/AGENTS.md\` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Needs the authoritative planning/spec workflow for this repo
+
+Use \`@/${DEFAULT_PLANNING_DIRNAME}/AGENTS.md\` to learn:
+- How to create and apply ReffySpec change proposals
+- ReffySpec format and conventions
+- Project structure and planning guidelines
+
+Keep this managed block so \`reffy init\` can refresh the instructions.
+
+<!-- REFFYSPEC:END -->`;
+}
 function buildReffyAgentsContent(refsDirName) {
     return `# Reffy Instructions
 
@@ -48,7 +79,7 @@ These instructions are for AI assistants working in this project.
 - If needed, read existing context in \`${refsDirName}/artifacts/\`.
 - Add/update exploratory artifacts and keep them concise.
 - Run \`reffy reindex\` and \`reffy validate\` after artifact changes.
-- After ideation approval, run \`reffy summarize --output json\` and pick only directly relevant artifacts for proposal citations.
+- Use \`reffy summarize --output json\` and \`reffy plan create\` to turn artifact context into planning scaffolds.
 
 ## When To Use Reffy
 
@@ -70,17 +101,20 @@ You can skip Reffy when the request is:
 2. Add or update artifacts to capture exploratory context.
 3. Run \`reffy reindex\` to index newly added files into \`${refsDirName}/manifest.json\`.
 4. Run \`reffy validate\` to verify manifest contract compliance.
+5. Run \`reffy plan create\` to generate proposal/tasks/spec scaffolds from selected artifacts when planning is ready.
 
-## Relationship To OpenSpec
+## Relationship To ReffySpec
 
-- Reffy is the ideation/context layer.
-- OpenSpec is the formal planning/spec layer.
-- After ideation stabilizes, hand off to OpenSpec by following \`@/openspec/AGENTS.md\`.
-- Do not duplicate full proposal/spec content in Reffy artifacts; summarize and link to OpenSpec outputs.
+- Reffy owns ideation artifacts, manifest metadata, and native planning scaffolds.
+- ReffySpec is the planning subsystem inside Reffy.
+- The vendored fork at \`/.vendor/ReffySpec\` is reference-only for v1; first-party behavior lives in this repo.
+- Reffy is the primary runtime authority for this project.
+- ReffySpec files live under \`${DEFAULT_PLANNING_DIRNAME}/\` as the canonical planning layout.
+- Do not duplicate full proposal/spec content in Reffy artifacts; generate and link planning outputs from them.
 
-## OpenSpec Citation Rules
+## ReffySpec Citation Rules
 
-When an OpenSpec proposal is informed by Reffy artifacts:
+When a ReffySpec proposal is informed by Reffy artifacts:
 - After ideation approval, run \`reffy summarize --output json\` to shortlist candidate artifacts.
 - Include a short "Reffy References" subsection in \`proposal.md\` (or design notes if more appropriate).
 - Cite only artifact filenames that directly informed the proposal's problem, scope, decisions, or constraints.
@@ -92,7 +126,7 @@ When an OpenSpec proposal is informed by Reffy artifacts:
 
 ### Reusable Proposal Snippet
 
-Use this in \`openspec/changes/<change-id>/proposal.md\`:
+Use this in \`${DEFAULT_PLANNING_DIRNAME}/changes/<change-id>/proposal.md\`:
 
 \`\`\`md
 ## Reffy References
@@ -114,9 +148,59 @@ No Reffy references used.
 - Keep manifests machine-readable and schema-compliant (version 1).
 `;
 }
+function buildReffySpecAgentsContent() {
+    return `# ReffySpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+## TL;DR Checklist
+
+- Read the relevant current specs in \`${DEFAULT_PLANNING_DIRNAME}/specs/\` before changing behavior.
+- Review active changes in \`${DEFAULT_PLANNING_DIRNAME}/changes/\` before drafting or implementing new work.
+- Use ReffySpec change proposals for new capabilities, breaking changes, or architecture shifts.
+- Keep current truth in \`${DEFAULT_PLANNING_DIRNAME}/specs/\` and proposed deltas in \`${DEFAULT_PLANNING_DIRNAME}/changes/\`.
+
+## ReffySpec Workflow
+
+1. Read \`${DEFAULT_PLANNING_DIRNAME}/project.md\` for project conventions.
+2. Inspect current specs in \`${DEFAULT_PLANNING_DIRNAME}/specs/\`.
+3. Inspect active changes in \`${DEFAULT_PLANNING_DIRNAME}/changes/\`.
+4. Draft or update proposal/design/tasks/spec files under \`${DEFAULT_PLANNING_DIRNAME}/changes/<change-id>/\`.
+5. Use native Reffy commands for routine planning workflow:
+   - \`reffy plan create\`
+   - \`reffy plan validate\`
+   - \`reffy plan list\`
+   - \`reffy plan show\`
+   - \`reffy plan archive\`
+   - \`reffy spec list\`
+   - \`reffy spec show\`
+
+## Directory Model
+
+- \`${DEFAULT_PLANNING_DIRNAME}/changes/\` contains active proposed changes.
+- \`${DEFAULT_PLANNING_DIRNAME}/changes/archive/\` contains historical archived changes.
+- \`${DEFAULT_PLANNING_DIRNAME}/specs/\` contains current truth for each capability.
+
+## Proposal Rules
+
+- Use a unique verb-led \`change-id\` in kebab-case.
+- Include \`proposal.md\`, \`tasks.md\`, optional \`design.md\`, and delta specs per affected capability.
+- Delta specs must use \`## ADDED|MODIFIED|REMOVED|RENAMED Requirements\`.
+- Each requirement must include at least one \`#### Scenario:\`.
+
+## Reffy Relationship
+
+- Reffy owns the runtime and artifact workflow.
+- ReffySpec is the canonical planning/spec surface.
+- Reffy artifacts in \`.reffy/\` should inform proposal/design content without duplicating the full planning files.
+`;
+}
 const REFFY_START = "<!-- REFFY:START -->";
 const REFFY_END = "<!-- REFFY:END -->";
+const REFFYSPEC_START = "<!-- REFFYSPEC:START -->";
+const REFFYSPEC_END = "<!-- REFFYSPEC:END -->";
 const OPENSPEC_START = "<!-- OPENSPEC:START -->";
+const OPENSPEC_END = "<!-- OPENSPEC:END -->";
 function upsertReffyBlock(content) {
     return upsertReffyBlockForDir(content, DEFAULT_REFS_DIRNAME);
 }
@@ -134,10 +218,27 @@ function upsertReffyBlockForDir(content, refsDirName) {
     }
     return content.trim().length > 0 ? `${reffyBlock}\n\n${content.trimStart()}` : `${reffyBlock}\n`;
 }
+function upsertPlanningBlock(content) {
+    const reffyspecBlock = buildReffySpecBlock();
+    if (content.includes(REFFYSPEC_START) && content.includes(REFFYSPEC_END)) {
+        const prefix = content.split(REFFYSPEC_START)[0] ?? "";
+        const suffix = content.split(REFFYSPEC_END, 2)[1] ?? "";
+        const trimmedSuffix = suffix.trimStart();
+        return trimmedSuffix.length > 0 ? `${prefix}${reffyspecBlock}\n\n${trimmedSuffix}` : `${prefix}${reffyspecBlock}\n`;
+    }
+    if (content.includes(OPENSPEC_START) && content.includes(OPENSPEC_END)) {
+        const prefix = content.split(OPENSPEC_START)[0] ?? "";
+        const suffix = content.split(OPENSPEC_END, 2)[1] ?? "";
+        const trimmedSuffix = suffix.trimStart();
+        return trimmedSuffix.length > 0 ? `${prefix}${reffyspecBlock}\n\n${trimmedSuffix}` : `${prefix}${reffyspecBlock}\n`;
+    }
+    return content.trim().length > 0 ? `${content.trimEnd()}\n\n${reffyspecBlock}\n` : `${reffyspecBlock}\n`;
+}
 async function initAgents(repoRoot) {
-    const refsDirName = resolveRefsDirName(repoRoot);
+    const refsDirName = DEFAULT_REFS_DIRNAME;
     const agentsPath = path.join(repoRoot, "AGENTS.md");
     const reffyAgentsPath = path.join(repoRoot, refsDirName, "AGENTS.md");
+    const reffyspecAgentsPath = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "AGENTS.md");
     let content = "";
     try {
         content = await fs.readFile(agentsPath, "utf8");
@@ -145,11 +246,13 @@ async function initAgents(repoRoot) {
     catch {
         content = "";
     }
-    const updated = upsertReffyBlockForDir(content, refsDirName);
+    const updated = upsertPlanningBlock(upsertReffyBlockForDir(content, refsDirName));
     await fs.mkdir(path.dirname(reffyAgentsPath), { recursive: true });
+    await fs.mkdir(path.dirname(reffyspecAgentsPath), { recursive: true });
     await fs.writeFile(agentsPath, updated, "utf8");
     await fs.writeFile(reffyAgentsPath, buildReffyAgentsContent(refsDirName), "utf8");
-    return { root_agents_path: agentsPath, reffy_agents_path: reffyAgentsPath };
+    await fs.writeFile(reffyspecAgentsPath, buildReffySpecAgentsContent(), "utf8");
+    return { root_agents_path: agentsPath, reffy_agents_path: reffyAgentsPath, reffyspec_agents_path: reffyspecAgentsPath };
 }
 function pathExists(targetPath) {
     return existsSync(targetPath);
@@ -199,6 +302,30 @@ function parseRepoArg(argv) {
     }
     return discoverRepoRoot(process.cwd());
 }
+function getPlanPositionalArgs(argv) {
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo" || arg === "--output" || arg === "--change-id" || arg === "--title" || arg === "--artifacts") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--repo=") ||
+            arg.startsWith("--output=") ||
+            arg.startsWith("--change-id=") ||
+            arg.startsWith("--title=") ||
+            arg.startsWith("--artifacts=") ||
+            arg === "--json" ||
+            arg === "--all" ||
+            arg === "--force") {
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        positionals.push(arg);
+    }
+    return positionals;
+}
 function parseOutputMode(argv) {
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -232,6 +359,56 @@ function printBanner(mode) {
         console.log("");
     }
 }
+function shouldPrintBootstrapOnboarding(workspaceCreated, workspaceMigrated, planningCreated, planningMigrated) {
+    return workspaceCreated || workspaceMigrated || planningCreated || planningMigrated;
+}
+function printBootstrapOnboarding() {
+    console.log("");
+    console.log("Next step for your agent harness:");
+    console.log("Copy and paste this into your conversation with your chosen agent:");
+    console.log("");
+    console.log(BOOTSTRAP_AGENT_INSTRUCTION);
+}
+async function runSetupCommand(commandName, output, repoRoot) {
+    const workspace = await prepareCanonicalWorkspace(repoRoot);
+    const planning = await prepareCanonicalPlanningLayout(repoRoot);
+    const agents = await initAgents(repoRoot);
+    const store = new ReferencesStore(repoRoot);
+    const reindex = await store.reindexArtifacts();
+    const payload = {
+        status: "ok",
+        command: commandName,
+        workspace_mode: workspace.state.mode,
+        migrated_workspace: workspace.migrated,
+        created_workspace: workspace.created,
+        planning_mode: planning.state.mode,
+        migrated_planning_layout: planning.migrated,
+        created_planning_layout: planning.created,
+        ...agents,
+        refs_dir: store.refsDir,
+        manifest_path: store.manifestPath,
+        reindex,
+    };
+    if (output === "json") {
+        printResult(output, payload);
+        return 0;
+    }
+    if (workspace.message) {
+        console.log(workspace.message);
+    }
+    if (planning.message) {
+        console.log(planning.message);
+    }
+    console.log(`${commandName === "init" ? "Initialized" : "Bootstrapped"} ${store.refsDir}`);
+    console.log(`Updated ${agents.root_agents_path}`);
+    console.log(`Updated ${agents.reffy_agents_path}`);
+    console.log(`Updated ${agents.reffyspec_agents_path}`);
+    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();
+    }
+    return 0;
+}
 function usage() {
     return [
         "Usage: reffy <command> [--repo PATH] [--output text|json]",
@@ -240,12 +417,15 @@ function usage() {
         "  --version  Print the installed reffy package version.",
         "",
         "Commands:",
-        "  init       Ensure root AGENTS.md block and .reffy/AGENTS.md are up to date.",
-        "  bootstrap  Run init, ensure .reffy structure exists, then reindex artifacts.",
+        "  init       Run the canonical first-run setup flow and refresh managed instructions.",
+        "  bootstrap  Compatibility alias for init.",
+        "  migrate    Migrate a legacy .references workspace to the canonical .reffy layout.",
         "  doctor     Diagnose required Reffy setup and optional tool availability.",
         "  reindex    Scan .reffy/artifacts and add missing files to manifest.",
         "  validate   Validate .reffy/manifest.json against manifest v1 contract.",
         "  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.",
         "  diagram    Render Mermaid diagrams (supports SVG and ASCII).",
     ].join("\n");
 }
@@ -254,7 +434,7 @@ function diagramUsage() {
         "Usage: reffy diagram render [--repo PATH] [--input PATH|--stdin] [--format svg|ascii] [--output PATH]",
         "",
         "Options:",
-        "  --input PATH      Read Mermaid (or OpenSpec spec.md) from file",
+        "  --input PATH      Read Mermaid (or ReffySpec spec.md) from file",
         "  --stdin           Read Mermaid text from stdin",
         "  --format VALUE    Output format: svg (default) or ascii",
         "  --output PATH     Write rendered result to file instead of stdout",
@@ -269,6 +449,30 @@ function diagramUsage() {
         "  --font NAME       SVG font family override",
     ].join("\n");
 }
+function specUsage() {
+    return [
+        "Usage:",
+        "  reffy spec list [--repo PATH] [--output text|json]",
+        "  reffy spec show <spec-id> [--repo PATH] [--output text|json]",
+    ].join("\n");
+}
+function planUsage() {
+    return [
+        "Usage:",
+        "  reffy plan create --change-id ID [--repo PATH] [--artifacts file1.md,file2.md|--all] [--title TEXT]",
+        "  reffy plan validate <change-id> [--repo PATH] [--output text|json]",
+        "  reffy plan list [--repo PATH] [--output text|json]",
+        "  reffy plan show <change-id> [--repo PATH] [--output text|json]",
+        "  reffy plan archive <change-id> [--repo PATH] [--output text|json]",
+        "",
+        "Options:",
+        `  --change-id ID     ${DEFAULT_PLANNING_DIRNAME} change id to create`,
+        "  --title TEXT       Human-readable proposal title",
+        "  --artifacts LIST   Comma-separated artifact filenames or ids to link",
+        "  --all              Use all indexed artifacts as planning inputs",
+        "  --force            Overwrite an existing non-empty change directory",
+    ].join("\n");
+}
 function parseDiagramArgs(argv) {
     const repoRoot = parseRepoArg(argv);
     const args = {
@@ -368,6 +572,83 @@ function parseDiagramArgs(argv) {
     }
     return args;
 }
+function parsePlanArgs(argv) {
+    const repoRoot = parseRepoArg(argv);
+    const args = {
+        repoRoot,
+        changeId: "",
+        artifactFilters: [],
+        includeAllArtifacts: false,
+        overwrite: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--repo="))
+            continue;
+        if (arg === "--json")
+            continue;
+        if (arg === "--output") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--output="))
+            continue;
+        if (arg === "--change-id") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--change-id requires a value");
+            args.changeId = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--change-id=")) {
+            args.changeId = arg.split("=", 2)[1] ?? "";
+            continue;
+        }
+        if (arg === "--title") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--title requires a value");
+            args.title = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--title=")) {
+            args.title = arg.split("=", 2)[1];
+            continue;
+        }
+        if (arg === "--artifacts") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--artifacts requires a comma-separated value");
+            args.artifactFilters = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--artifacts=")) {
+            const value = arg.split("=", 2)[1] ?? "";
+            args.artifactFilters = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+            continue;
+        }
+        if (arg === "--all") {
+            args.includeAllArtifacts = true;
+            continue;
+        }
+        if (arg === "--force") {
+            args.overwrite = true;
+            continue;
+        }
+        throw new Error(`Unknown plan option: ${arg}`);
+    }
+    if (!args.changeId) {
+        throw new Error("--change-id is required");
+    }
+    return args;
+}
 function printSection(title, values) {
     console.log(`${title}:`);
     if (values.length === 0) {
@@ -400,6 +681,7 @@ async function main() {
             return 1;
         }
         const parsed = parseDiagramArgs(diagramArgs);
+        await prepareCanonicalPlanningLayout(parsed.repoRoot);
         const rendered = await renderDiagram({
             repoRoot: parsed.repoRoot,
             inputPath: parsed.inputPath,
@@ -426,47 +708,265 @@ async function main() {
         }
         return 0;
     }
+    if (command === "plan") {
+        const [subcommand, ...planArgs] = rest;
+        if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+            console.error(planUsage());
+            return 1;
+        }
+        if (subcommand === "create") {
+            const output = parseOutputMode(planArgs);
+            const parsed = parsePlanArgs(planArgs);
+            await prepareCanonicalPlanningLayout(parsed.repoRoot);
+            const store = new ReferencesStore(parsed.repoRoot);
+            const validation = await store.validateManifest();
+            if (!validation.ok) {
+                const payload = { status: "error", command: "plan", subcommand: "create", ...validation };
+                if (output === "json") {
+                    printResult(output, payload);
+                }
+                else {
+                    console.error(`Cannot create plan: manifest invalid (${String(validation.errors.length)} error(s))`);
+                }
+                return 1;
+            }
+            const result = await createPlanScaffold(store, {
+                changeId: parsed.changeId,
+                title: parsed.title,
+                artifactFilters: parsed.artifactFilters,
+                includeAllArtifacts: parsed.includeAllArtifacts,
+                overwrite: parsed.overwrite,
+            });
+            const payload = { status: "ok", command: "plan", subcommand: "create", ...result };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else {
+                console.log(`Created ${result.change_dir}`);
+                console.log(`Artifacts linked: ${String(result.linked_artifacts)}`);
+                for (const file of result.written_files) {
+                    console.log(`- ${file}`);
+                }
+            }
+            return 0;
+        }
+        const output = parseOutputMode(planArgs);
+        const repoRoot = parseRepoArg(planArgs);
+        await prepareCanonicalPlanningLayout(repoRoot);
+        const positionals = getPlanPositionalArgs(planArgs);
+        if (subcommand === "validate") {
+            const changeId = positionals[0];
+            if (!changeId) {
+                console.error("reffy plan validate requires a change id");
+                console.error(planUsage());
+                return 1;
+            }
+            const result = await validatePlanningChange(repoRoot, changeId);
+            const payload = { status: result.ok ? "ok" : "error", command: "plan", subcommand: "validate", ...result };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else if (result.ok) {
+                console.log(`Change "${changeId}" is valid`);
+                console.log(`Tasks: ${String(result.task_status.completed)}/${String(result.task_status.total)}`);
+                console.log(`Delta specs: ${String(result.delta_count)}`);
+                for (const warning of result.warnings) {
+                    console.log(`warn: ${warning}`);
+                }
+            }
+            else {
+                console.error(`Change "${changeId}" has issues`);
+                for (const error of result.errors) {
+                    console.error(`error: ${error}`);
+                }
+                for (const warning of result.warnings) {
+                    console.error(`warn: ${warning}`);
+                }
+            }
+            return result.ok ? 0 : 1;
+        }
+        if (subcommand === "list") {
+            const changes = await listPlanningChanges(repoRoot);
+            const payload = { status: "ok", command: "plan", subcommand: "list", changes };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else if (changes.length === 0) {
+                console.log("Changes:");
+                console.log("- (none)");
+            }
+            else {
+                console.log("Changes:");
+                for (const change of changes) {
+                    console.log(`- ${change.id} - ${change.title} [deltas ${String(change.delta_count)}] [tasks ${String(change.task_status.completed)}/${String(change.task_status.total)}]`);
+                }
+            }
+            return 0;
+        }
+        if (subcommand === "show") {
+            const changeId = positionals[0];
+            if (!changeId) {
+                console.error("reffy plan show requires a change id");
+                console.error(planUsage());
+                return 1;
+            }
+            const result = await showPlanningChange(repoRoot, changeId);
+            const payload = { status: "ok", command: "plan", subcommand: "show", change: result };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else {
+                console.log(`# ${result.title}`);
+                console.log("");
+                console.log(result.proposal.trim());
+                console.log("");
+                console.log("## Tasks");
+                console.log(result.tasks.trim());
+                if (result.design) {
+                    console.log("");
+                    console.log("## Design");
+                    console.log(result.design.trim());
+                }
+                if (result.specs.length > 0) {
+                    console.log("");
+                    console.log("## Specs");
+                    for (const spec of result.specs) {
+                        console.log(`### ${spec.capability}`);
+                        console.log(spec.content.trim());
+                    }
+                }
+            }
+            return 0;
+        }
+        if (subcommand === "archive") {
+            const changeId = positionals[0];
+            if (!changeId) {
+                console.error("reffy plan archive requires a change id");
+                console.error(planUsage());
+                return 1;
+            }
+            const result = await archivePlanningChange(repoRoot, changeId);
+            const payload = { status: "ok", command: "plan", subcommand: "archive", ...result };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else {
+                console.log(`Archived ${changeId} to ${result.archive_dir}`);
+                console.log(`Updated specs: ${String(result.updated_specs.length)}`);
+                console.log(`Linked artifacts updated: ${String(result.linked_artifacts)}`);
+            }
+            return 0;
+        }
+        {
+            console.error(`Unknown plan subcommand: ${subcommand}`);
+            console.error(planUsage());
+            return 1;
+        }
+    }
+    if (command === "spec") {
+        const [subcommand, ...specArgs] = rest;
+        if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+            console.error(specUsage());
+            return 1;
+        }
+        const output = parseOutputMode(specArgs);
+        const repoRoot = parseRepoArg(specArgs);
+        await prepareCanonicalPlanningLayout(repoRoot);
+        const positionals = getPlanPositionalArgs(specArgs);
+        if (subcommand === "list") {
+            const specs = await listSpecs(repoRoot);
+            const payload = { status: "ok", command: "spec", subcommand: "list", specs };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else if (specs.length === 0) {
+                console.log("Specs:");
+                console.log("- (none)");
+            }
+            else {
+                console.log("Specs:");
+                for (const spec of specs) {
+                    console.log(`- ${spec.id} - ${spec.title} [requirements ${String(spec.requirement_count)}]`);
+                }
+            }
+            return 0;
+        }
+        if (subcommand === "show") {
+            const specId = positionals[0];
+            if (!specId) {
+                console.error("reffy spec show requires a spec id");
+                console.error(specUsage());
+                return 1;
+            }
+            const result = await showSpec(repoRoot, specId);
+            const payload = { status: "ok", command: "spec", subcommand: "show", spec: result };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else {
+                console.log(`# ${result.title}`);
+                if (result.purpose) {
+                    console.log("");
+                    console.log(`Purpose: ${result.purpose}`);
+                }
+                console.log("");
+                console.log(result.spec.trim());
+                if (result.design) {
+                    console.log("");
+                    console.log("## Design");
+                    console.log(result.design.trim());
+                }
+            }
+            return 0;
+        }
+        console.error(`Unknown spec subcommand: ${subcommand}`);
+        console.error(specUsage());
+        return 1;
+    }
     const output = parseOutputMode(rest);
     if (command === "init") {
         printBanner(output);
         const repoRoot = parseRepoArg(rest);
-        const agents = await initAgents(repoRoot);
-        const payload = { status: "ok", command: "init", ...agents };
-        if (output === "json") {
-            printResult(output, payload);
-        }
-        else {
-            console.log(`Updated ${agents.root_agents_path}`);
-            console.log(`Updated ${agents.reffy_agents_path}`);
-        }
-        return 0;
+        return await runSetupCommand("init", output, repoRoot);
     }
     if (command === "bootstrap") {
         const repoRoot = parseRepoArg(rest);
+        return await runSetupCommand("bootstrap", output, repoRoot);
+    }
+    if (command === "migrate") {
+        const repoRoot = parseRepoArg(rest);
+        const workspace = await prepareCanonicalWorkspace(repoRoot);
+        const planning = await prepareCanonicalPlanningLayout(repoRoot);
         const agents = await initAgents(repoRoot);
-        const store = new ReferencesStore(repoRoot);
-        const reindex = await store.reindexArtifacts();
         const payload = {
             status: "ok",
-            command: "bootstrap",
+            command: "migrate",
+            workspace_mode: workspace.state.mode,
+            migrated_workspace: workspace.migrated,
+            created_workspace: workspace.created,
+            planning_mode: planning.state.mode,
+            migrated_planning_layout: planning.migrated,
+            created_planning_layout: planning.created,
+            refs_dir: workspace.state.canonicalDir,
             ...agents,
-            refs_dir: store.refsDir,
-            manifest_path: store.manifestPath,
-            reindex,
         };
         if (output === "json") {
             printResult(output, payload);
         }
         else {
-            console.log(`Bootstrapped ${store.refsDir}`);
+            console.log(workspace.message ?? `Workspace ready at ${workspace.state.canonicalDir}`);
+            if (planning.message) {
+                console.log(planning.message);
+            }
             console.log(`Updated ${agents.root_agents_path}`);
             console.log(`Updated ${agents.reffy_agents_path}`);
-            console.log(`Reindex: added=${String(reindex.added)} removed=${String(reindex.removed)} total=${String(reindex.total)}`);
+            console.log(`Updated ${agents.reffyspec_agents_path}`);
         }
         return 0;
     }
     if (command === "reindex") {
         const repoRoot = parseRepoArg(rest);
+        await prepareCanonicalPlanningLayout(repoRoot);
         const store = new ReferencesStore(repoRoot);
         const reindex = await store.reindexArtifacts();
         const payload = { status: "ok", command: "reindex", ...reindex };
@@ -480,6 +980,7 @@ async function main() {
     }
     if (command === "doctor") {
         const repoRoot = parseRepoArg(rest);
+        await prepareCanonicalPlanningLayout(repoRoot);
         const report = await runDoctor(repoRoot);
         const status = report.summary.required_failed > 0 ? "error" : "ok";
         const payload = { status, command: "doctor", ...report };
@@ -505,6 +1006,7 @@ async function main() {
     }
     if (command === "validate") {
         const repoRoot = parseRepoArg(rest);
+        await prepareCanonicalPlanningLayout(repoRoot);
         const store = new ReferencesStore(repoRoot);
         const result = await store.validateManifest();
         const payload = { status: result.ok ? "ok" : "error", command: "validate", ...result };
@@ -532,6 +1034,7 @@ async function main() {
     }
     if (command === "summarize") {
         const repoRoot = parseRepoArg(rest);
+        await prepareCanonicalPlanningLayout(repoRoot);
         const store = new ReferencesStore(repoRoot);
         const validation = await store.validateManifest();
         if (!validation.ok) {