reffy-cli 1.1.2 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@
 [![MIT License](https://img.shields.io/github/license/RoskiDeluge/reffy-ts.svg)](LICENSE)
 [![CI](https://github.com/RoskiDeluge/reffy-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/RoskiDeluge/reffy-ts/actions/workflows/ci.yml)
 
-Reffy is a CLI-first planning system for agent-friendly development workflows. It keeps ideation artifacts in straightforward version-controlled markdown files and manages formal planning files under `reffyspec/`.
+Reffy is a CLI-first planning system for agent-friendly development workflows. It keeps ideation artifacts in straightforward version-controlled markdown files and manages formal planning files under `.reffy/reffyspec/`.
 
 ## Install
 
@@ -23,7 +23,7 @@ reffy init
 
 Command summary:
 
-- `reffy init`: runs the canonical first-run setup flow, creates the `.reffy/` and `reffyspec/` structure, writes managed instructions, reindexes artifacts, and on first-run text output prints a copy/paste instruction for your agent harness.
+- `reffy init`: runs the canonical first-run setup flow, creates the `.reffy/` and `.reffy/reffyspec/` structure, writes managed instructions, reindexes artifacts, and on first-run text output prints a copy/paste instruction for your agent harness.
 - `reffy bootstrap`: compatibility alias for `reffy init`.
 - `reffy migrate`: migrates a legacy `.references/` workspace into `.reffy/`.
 - `reffy doctor`: diagnoses required Reffy setup and workspace health.
@@ -31,8 +31,8 @@ Command summary:
 - `reffy validate`: validates `.reffy/manifest.json` against manifest v1 contract.
 - `reffy summarize`: generates a read-only handoff summary from indexed artifacts.
 - `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 `reffyspec/`.
-- `reffy spec list|show`: inspects current spec state under `reffyspec/`.
+- `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 diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from compatible `spec.md` files.
 
 Output modes:
@@ -55,8 +55,8 @@ reffy plan list --output json
 reffy plan archive add-login-flow
 reffy spec show auth --output json
 reffy diagram render --stdin --format svg < diagram.mmd
-reffy diagram render --input reffyspec/specs/auth/spec.md --format ascii
-reffy diagram render --input reffyspec/specs/auth/spec.md --format svg --output .reffy/artifacts/auth-spec.svg
+reffy diagram render --input .reffy/reffyspec/specs/auth/spec.md --format ascii
+reffy diagram render --input .reffy/reffyspec/specs/auth/spec.md --format svg --output .reffy/artifacts/auth-spec.svg
 ```
 
 ## Using Reffy With ReffySpec
@@ -64,7 +64,7 @@ reffy diagram render --input reffyspec/specs/auth/spec.md --format svg --output
 A practical pattern is:
 
 1. Use Reffy for ideation and context capture in `.reffy/artifacts/`.
-2. Use Reffy to scaffold and manage planning files in `reffyspec/`.
+2. Use Reffy to scaffold and manage planning files in `.reffy/reffyspec/`.
 3. Keep a clear traceable path from exploratory artifacts to formal specs.
 4. Use Reffy commands for day-to-day workflow.
 
@@ -72,10 +72,10 @@ Reference implementation in this repo:
 
 - `AGENTS.md`: contains both managed instruction blocks and encodes sequencing.
 - `AGENTS.md`: Reffy block routes ideation/exploration requests to `@/.reffy/AGENTS.md`.
-- `AGENTS.md`: ReffySpec block routes planning/proposal/spec requests to `@/reffyspec/AGENTS.md`.
+- `AGENTS.md`: ReffySpec block routes planning/proposal/spec requests to `@/.reffy/reffyspec/AGENTS.md`.
 - `.reffy/AGENTS.md`: defines the artifact and ideation workflow.
-- `reffyspec/AGENTS.md`: defines the ReffySpec planning/spec workflow conventions used in this repo.
-- `reffyspec/project.md`: captures durable project context for agents, including purpose, stack, architecture, conventions, and constraints.
+- `.reffy/reffyspec/AGENTS.md`: defines the ReffySpec planning/spec workflow conventions used in this repo.
+- `.reffy/reffyspec/project.md`: captures durable project context for agents, including purpose, stack, architecture, conventions, and constraints.
 
 ## Develop
 

package/dist/cli.js

@@ -6,9 +6,9 @@ import { renderDiagram } from "./diagram.js";
 import { runDoctor } from "./doctor.js";
 import { archivePlanningChange } from "./plan-archive.js";
 import { createPlanScaffold } from "./plan.js";
-import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { DEFAULT_PLANNING_RELATIVE_DIR, looksLikePlanningDir, resolveCanonicalPlanningPath } from "./planning-paths.js";
 import { listPlanningChanges, showPlanningChange, validatePlanningChange } from "./plan-runtime.js";
-import { DEFAULT_REFS_DIRNAME, looksLikeRefsDir } from "./refs-paths.js";
+import { DEFAULT_REFS_DIRNAME, detectWorkspaceState, looksLikeRefsDir } from "./refs-paths.js";
 import { prepareCanonicalPlanningLayout } from "./planning-workspace.js";
 import { ReferencesStore } from "./storage.js";
 import { listSpecs, showSpec } from "./spec-runtime.js";
@@ -25,7 +25,7 @@ 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`',
+    `Please read \`AGENTS.md\` and help me fill out the project context template in \`${DEFAULT_PLANNING_RELATIVE_DIR}/project.md\``,
     "with details about my project, tech stack, architecture, and conventions.",
 ].join(" ");
 function buildReffyBlock(refsDirName) {
@@ -54,12 +54,12 @@ function buildReffySpecBlock() {
 
 These instructions are for AI assistants working in this project.
 
-Always open \`@/${DEFAULT_PLANNING_DIRNAME}/AGENTS.md\` when the request:
+Always open \`@/${DEFAULT_PLANNING_RELATIVE_DIR}/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:
+Use \`@/${DEFAULT_PLANNING_RELATIVE_DIR}/AGENTS.md\` to learn:
 - How to create and apply ReffySpec change proposals
 - ReffySpec format and conventions
 - Project structure and planning guidelines
@@ -109,7 +109,7 @@ You can skip Reffy when the request is:
 - 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.
+- ReffySpec files live under \`${DEFAULT_PLANNING_RELATIVE_DIR}/\` as the canonical planning layout.
 - Do not duplicate full proposal/spec content in Reffy artifacts; generate and link planning outputs from them.
 
 ## ReffySpec Citation Rules
@@ -126,7 +126,7 @@ When a ReffySpec proposal is informed by Reffy artifacts:
 
 ### Reusable Proposal Snippet
 
-Use this in \`${DEFAULT_PLANNING_DIRNAME}/changes/<change-id>/proposal.md\`:
+Use this in \`${DEFAULT_PLANNING_RELATIVE_DIR}/changes/<change-id>/proposal.md\`:
 
 \`\`\`md
 ## Reffy References
@@ -155,17 +155,17 @@ 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.
+- Read the relevant current specs in \`${DEFAULT_PLANNING_RELATIVE_DIR}/specs/\` before changing behavior.
+- Review active changes in \`${DEFAULT_PLANNING_RELATIVE_DIR}/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/\`.
+- Keep current truth in \`${DEFAULT_PLANNING_RELATIVE_DIR}/specs/\` and proposed deltas in \`${DEFAULT_PLANNING_RELATIVE_DIR}/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>/\`.
+1. Read \`${DEFAULT_PLANNING_RELATIVE_DIR}/project.md\` for project conventions.
+2. Inspect current specs in \`${DEFAULT_PLANNING_RELATIVE_DIR}/specs/\`.
+3. Inspect active changes in \`${DEFAULT_PLANNING_RELATIVE_DIR}/changes/\`.
+4. Draft or update proposal/design/tasks/spec files under \`${DEFAULT_PLANNING_RELATIVE_DIR}/changes/<change-id>/\`.
 5. Use native Reffy commands for routine planning workflow:
    - \`reffy plan create\`
    - \`reffy plan validate\`
@@ -177,9 +177,9 @@ These instructions are for AI assistants working in this project.
 
 ## 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.
+- \`${DEFAULT_PLANNING_RELATIVE_DIR}/changes/\` contains active proposed changes.
+- \`${DEFAULT_PLANNING_RELATIVE_DIR}/changes/archive/\` contains historical archived changes.
+- \`${DEFAULT_PLANNING_RELATIVE_DIR}/specs/\` contains current truth for each capability.
 
 ## Proposal Rules
 
@@ -238,7 +238,7 @@ async function initAgents(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");
+    const reffyspecAgentsPath = resolveCanonicalPlanningPath(repoRoot, "AGENTS.md");
     let content = "";
     try {
         content = await fs.readFile(agentsPath, "utf8");
@@ -271,6 +271,11 @@ function discoverRepoRoot(startDir) {
         if (looksLikeRefsDir(current)) {
             return path.dirname(current);
         }
+        if (looksLikePlanningDir(current)) {
+            return path.basename(path.dirname(current)) === DEFAULT_REFS_DIRNAME
+                ? path.dirname(path.dirname(current))
+                : path.dirname(current);
+        }
         if (isDirectory(path.join(current, DEFAULT_REFS_DIRNAME)) || isDirectory(path.join(current, ".references"))) {
             return current;
         }
@@ -466,7 +471,7 @@ function planUsage() {
         "  reffy plan archive <change-id> [--repo PATH] [--output text|json]",
         "",
         "Options:",
-        `  --change-id ID     ${DEFAULT_PLANNING_DIRNAME} change id to create`,
+        `  --change-id ID     ${DEFAULT_PLANNING_RELATIVE_DIR} 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",
@@ -966,7 +971,6 @@ async function main() {
     }
     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 };
@@ -980,7 +984,9 @@ async function main() {
     }
     if (command === "doctor") {
         const repoRoot = parseRepoArg(rest);
-        await prepareCanonicalPlanningLayout(repoRoot);
+        if (detectWorkspaceState(repoRoot).mode !== "legacy") {
+            await prepareCanonicalPlanningLayout(repoRoot);
+        }
         const report = await runDoctor(repoRoot);
         const status = report.summary.required_failed > 0 ? "error" : "ok";
         const payload = { status, command: "doctor", ...report };
@@ -1006,7 +1012,6 @@ 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 };
@@ -1034,7 +1039,6 @@ 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) {

package/dist/plan-archive.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { resolvePlanningPath } from "./planning-paths.js";
 import { validatePlanningChange } from "./plan-runtime.js";
 import { ReferencesStore } from "./storage.js";
 const DELTA_SECTION_PATTERN = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/;
@@ -185,7 +185,7 @@ async function buildSpecUpdates(repoRoot, changeId, changeDir) {
         const deltaContent = await fs.readFile(deltaPath, "utf8");
         const relDeltaPath = path.relative(repoRoot, deltaPath).split(path.sep).join("/");
         const delta = parseArchiveableRequirements(deltaContent, relDeltaPath);
-        const currentSpecPath = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs", capability, "spec.md");
+        const currentSpecPath = resolvePlanningPath(repoRoot, "specs", capability, "spec.md");
         const currentSpecExists = await pathExists(currentSpecPath);
         const nextContent = currentSpecExists
             ? mergeRequirementsIntoCurrentSpec(await fs.readFile(currentSpecPath, "utf8"), delta, path.relative(repoRoot, currentSpecPath).split(path.sep).join("/"))
@@ -204,11 +204,11 @@ export async function archivePlanningChange(repoRoot, changeId) {
     if (!validation.ok) {
         throw new Error(`cannot archive invalid change "${changeId}": ${validation.errors.join("; ")}`);
     }
-    const changeDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", changeId);
+    const changeDir = resolvePlanningPath(repoRoot, "changes", changeId);
     if (!(await pathExists(changeDir))) {
         throw new Error(`change not found: ${changeId}`);
     }
-    const archiveDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", "archive", `${archiveDatePrefix()}-${changeId}`);
+    const archiveDir = resolvePlanningPath(repoRoot, "changes", "archive", `${archiveDatePrefix()}-${changeId}`);
     if (await pathExists(archiveDir)) {
         throw new Error(`archive destination already exists: ${path.relative(repoRoot, archiveDir).split(path.sep).join("/")}`);
     }

package/dist/plan-runtime.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { resolvePlanningPath } from "./planning-paths.js";
 const CHANGE_HEADING_PREFIX = "# Change:";
 const REQUIREMENT_SECTION_PATTERN = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/;
 const REQUIREMENT_HEADING_PATTERN = /^###\s+Requirement:\s+(.+)$/;
@@ -20,7 +20,7 @@ async function listDirectories(dir) {
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
 }
 function getChangePaths(repoRoot, changeId) {
-    const changeDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", changeId);
+    const changeDir = resolvePlanningPath(repoRoot, "changes", changeId);
     return {
         id: changeId,
         changeDir,
@@ -130,7 +130,7 @@ async function buildChangeSummary(repoRoot, changeId) {
     };
 }
 export async function listPlanningChanges(repoRoot) {
-    const changesRoot = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes");
+    const changesRoot = resolvePlanningPath(repoRoot, "changes");
     const changeIds = (await listDirectories(changesRoot)).filter((id) => id !== "archive");
     const summaries = [];
     for (const changeId of changeIds) {

package/dist/plan.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { DEFAULT_PLANNING_RELATIVE_DIR, resolveCanonicalPlanningPath } from "./planning-paths.js";
 function normalizeKebab(value) {
     return value
         .trim()
@@ -259,25 +259,25 @@ export async function createPlanScaffold(store, input) {
     const title = input.title?.trim() || deriveTitle(changeId);
     const capabilityId = normalizeKebab(deriveCapabilityId(changeId));
     const artifactInputs = await loadArtifactPlanningInputs(store, selected);
-    const changeDir = path.join(store.repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", changeId);
+    const changeDir = resolveCanonicalPlanningPath(store.repoRoot, "changes", changeId);
     const specDir = path.join(changeDir, "specs", capabilityId);
     await ensureEmptyChangeDir(changeDir, input.overwrite ?? false);
     await fs.mkdir(specDir, { recursive: true });
     const files = [
         {
-            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "proposal.md"),
+            rel: path.join(DEFAULT_PLANNING_RELATIVE_DIR, "changes", changeId, "proposal.md"),
             content: buildProposal(title, capabilityId, artifactInputs),
         },
         {
-            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "tasks.md"),
+            rel: path.join(DEFAULT_PLANNING_RELATIVE_DIR, "changes", changeId, "tasks.md"),
             content: buildTasks(artifactInputs),
         },
         {
-            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "design.md"),
+            rel: path.join(DEFAULT_PLANNING_RELATIVE_DIR, "changes", changeId, "design.md"),
             content: buildDesign(artifactInputs),
         },
         {
-            rel: path.join(DEFAULT_PLANNING_DIRNAME, "changes", changeId, "specs", capabilityId, "spec.md"),
+            rel: path.join(DEFAULT_PLANNING_RELATIVE_DIR, "changes", changeId, "specs", capabilityId, "spec.md"),
             content: buildSpecDelta(deriveRequirementTitle(title), artifactInputs),
         },
     ];

package/dist/planning-paths.d.ts

@@ -1,17 +1,24 @@
 export declare const DEFAULT_PLANNING_DIRNAME = "reffyspec";
-export declare const LEGACY_PLANNING_DIRNAME = "openspec";
-export type PlanningMode = "canonical" | "legacy" | "dual" | "new";
+export declare const DEFAULT_PLANNING_RELATIVE_DIR = ".reffy/reffyspec";
+export declare const LEGACY_PLANNING_DIRNAME = "reffyspec";
+export declare const COMPAT_PLANNING_DIRNAME = "openspec";
+export type PlanningMode = "canonical" | "legacy" | "compat" | "dual" | "new";
 export interface PlanningState {
     canonicalDir: string;
     legacyDir: string;
+    compatDir: string;
     canonicalExists: boolean;
     legacyExists: boolean;
+    compatExists: boolean;
     mode: PlanningMode;
     activeDirName: string;
     activeDir: string;
 }
 export declare function resolveCanonicalPlanningDir(repoRoot: string): string;
 export declare function resolveLegacyPlanningDir(repoRoot: string): string;
+export declare function resolveCompatPlanningDir(repoRoot: string): string;
+export declare function resolveCanonicalPlanningPath(repoRoot: string, ...parts: string[]): string;
+export declare function resolvePlanningPath(repoRoot: string, ...parts: string[]): string;
 export declare function detectPlanningState(repoRoot: string): PlanningState;
 export declare function resolvePlanningDirName(repoRoot: string): string;
 export declare function resolvePlanningDir(repoRoot: string): string;

package/dist/planning-paths.js

@@ -1,7 +1,10 @@
 import { existsSync, statSync } from "node:fs";
 import path from "node:path";
+import { DEFAULT_REFS_DIRNAME } from "./refs-paths.js";
 export const DEFAULT_PLANNING_DIRNAME = "reffyspec";
-export const LEGACY_PLANNING_DIRNAME = "openspec";
+export const DEFAULT_PLANNING_RELATIVE_DIR = `${DEFAULT_REFS_DIRNAME}/${DEFAULT_PLANNING_DIRNAME}`;
+export const LEGACY_PLANNING_DIRNAME = "reffyspec";
+export const COMPAT_PLANNING_DIRNAME = "openspec";
 function isDirectory(targetPath) {
     try {
         return statSync(targetPath).isDirectory();
@@ -11,18 +14,29 @@ function isDirectory(targetPath) {
     }
 }
 export function resolveCanonicalPlanningDir(repoRoot) {
-    return path.join(repoRoot, DEFAULT_PLANNING_DIRNAME);
+    return path.join(repoRoot, DEFAULT_REFS_DIRNAME, DEFAULT_PLANNING_DIRNAME);
 }
 export function resolveLegacyPlanningDir(repoRoot) {
     return path.join(repoRoot, LEGACY_PLANNING_DIRNAME);
 }
+export function resolveCompatPlanningDir(repoRoot) {
+    return path.join(repoRoot, COMPAT_PLANNING_DIRNAME);
+}
+export function resolveCanonicalPlanningPath(repoRoot, ...parts) {
+    return path.join(resolveCanonicalPlanningDir(repoRoot), ...parts);
+}
+export function resolvePlanningPath(repoRoot, ...parts) {
+    return path.join(resolvePlanningDir(repoRoot), ...parts);
+}
 export function detectPlanningState(repoRoot) {
     const canonicalDir = resolveCanonicalPlanningDir(repoRoot);
     const legacyDir = resolveLegacyPlanningDir(repoRoot);
+    const compatDir = resolveCompatPlanningDir(repoRoot);
     const canonicalExists = isDirectory(canonicalDir);
     const legacyExists = isDirectory(legacyDir);
+    const compatExists = isDirectory(compatDir);
     let mode = "new";
-    if (canonicalExists && legacyExists) {
+    if (canonicalExists && (legacyExists || compatExists)) {
         mode = "dual";
     }
     else if (canonicalExists) {
@@ -31,12 +45,21 @@ export function detectPlanningState(repoRoot) {
     else if (legacyExists) {
         mode = "legacy";
     }
-    const activeDirName = mode === "legacy" ? LEGACY_PLANNING_DIRNAME : DEFAULT_PLANNING_DIRNAME;
+    else if (compatExists) {
+        mode = "compat";
+    }
+    const activeDirName = mode === "legacy"
+        ? LEGACY_PLANNING_DIRNAME
+        : mode === "compat"
+            ? COMPAT_PLANNING_DIRNAME
+            : DEFAULT_PLANNING_RELATIVE_DIR;
     return {
         canonicalDir,
         legacyDir,
+        compatDir,
         canonicalExists,
         legacyExists,
+        compatExists,
         mode,
         activeDirName,
         activeDir: path.join(repoRoot, activeDirName),
@@ -50,7 +73,7 @@ export function resolvePlanningDir(repoRoot) {
 }
 export function looksLikePlanningDir(targetPath) {
     const base = path.basename(targetPath);
-    return ((base === DEFAULT_PLANNING_DIRNAME || base === LEGACY_PLANNING_DIRNAME) &&
+    return ((base === DEFAULT_PLANNING_DIRNAME || base === COMPAT_PLANNING_DIRNAME) &&
         existsSync(path.join(targetPath, "changes")) &&
         existsSync(path.join(targetPath, "specs")));
 }

package/dist/planning-workspace.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { DEFAULT_PLANNING_DIRNAME, LEGACY_PLANNING_DIRNAME, detectPlanningState, resolveCanonicalPlanningDir, } from "./planning-paths.js";
+import { COMPAT_PLANNING_DIRNAME, DEFAULT_PLANNING_DIRNAME, detectPlanningState, resolveCanonicalPlanningDir, } from "./planning-paths.js";
 const DEFAULT_PROJECT_CONTEXT_TEMPLATE = `# Project Context
 
 ## Purpose
@@ -59,12 +59,32 @@ async function ensureCanonicalPlanningStructure(repoRoot) {
 export async function prepareCanonicalPlanningLayout(repoRoot) {
     const current = detectPlanningState(repoRoot);
     if (current.mode === "legacy") {
+        await fs.mkdir(path.dirname(current.canonicalDir), { recursive: true });
         await fs.rename(current.legacyDir, current.canonicalDir);
         return {
             state: detectPlanningState(repoRoot),
             migrated: true,
             created: false,
-            message: `Migrated ${LEGACY_PLANNING_DIRNAME}/ to ${DEFAULT_PLANNING_DIRNAME}/`,
+            message: `Migrated reffyspec/ to ${DEFAULT_PLANNING_DIRNAME}/ within .reffy/`,
+        };
+    }
+    if (current.mode === "compat") {
+        await fs.mkdir(path.dirname(current.canonicalDir), { recursive: true });
+        await fs.rename(current.compatDir, current.canonicalDir);
+        return {
+            state: detectPlanningState(repoRoot),
+            migrated: true,
+            created: false,
+            message: `Migrated ${COMPAT_PLANNING_DIRNAME}/ to .reffy/${DEFAULT_PLANNING_DIRNAME}/`,
+        };
+    }
+    if (current.mode === "dual") {
+        await ensureCanonicalPlanningStructure(repoRoot);
+        return {
+            state: detectPlanningState(repoRoot),
+            migrated: false,
+            created: false,
+            message: `Using canonical .reffy/${DEFAULT_PLANNING_DIRNAME}/; legacy planning directories remain for manual cleanup`,
         };
     }
     const created = await ensureCanonicalPlanningStructure(repoRoot);

package/dist/spec-runtime.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { resolvePlanningPath } from "./planning-paths.js";
 const SPEC_HEADING_SUFFIX = " Specification";
 const PURPOSE_HEADING = "## Purpose";
 const REQUIREMENT_HEADING_PATTERN = /^###\s+Requirement:\s+(.+)$/;
@@ -46,7 +46,7 @@ function extractPurpose(content) {
     return purposeLines.length > 0 ? purposeLines.join(" ") : undefined;
 }
 async function buildSpecSummary(repoRoot, specId) {
-    const specDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs", specId);
+    const specDir = resolvePlanningPath(repoRoot, "specs", specId);
     const specPath = path.join(specDir, "spec.md");
     const designPath = path.join(specDir, "design.md");
     const content = await fs.readFile(specPath, "utf8");
@@ -60,7 +60,7 @@ async function buildSpecSummary(repoRoot, specId) {
     };
 }
 export async function listSpecs(repoRoot) {
-    const specsRoot = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs");
+    const specsRoot = resolvePlanningPath(repoRoot, "specs");
     const specIds = await listDirectories(specsRoot);
     const summaries = [];
     for (const specId of specIds) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "CLI-first, framework-agnostic references workflow for any repo (TypeScript)",
   "keywords": [
     "reffy",