reffy-cli 1.0.0 → 1.1.2

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/runtime system for agent-friendly development workflows. It keeps ideation artifacts in straightforward version-controlled markdown files and uses `reffyspec/` as the canonical planning/spec layout.
+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/`.
 
 ## Install
 
@@ -17,22 +17,22 @@ npm install -g reffy-cli@latest
 Inside your project:
 
 ```bash
+cd your-project
 reffy init
-reffy bootstrap
 ```
 
 Command summary:
 
-- `reffy init`: idempotently creates/updates root `AGENTS.md` managed block and `.reffy/AGENTS.md`.
-- `reffy bootstrap`: idempotently runs `init`, ensures `.reffy/` structure exists, then reindexes artifacts.
-- `reffy migrate`: migrates a legacy `.references/` workspace into the canonical `.reffy/` layout.
+- `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 bootstrap`: compatibility alias for `reffy init`.
+- `reffy migrate`: migrates a legacy `.references/` workspace into `.reffy/`.
 - `reffy doctor`: diagnoses required Reffy setup and workspace health.
 - `reffy reindex`: reconciles `.reffy/manifest.json` with `.reffy/artifacts` by adding missing files and removing stale entries.
 - `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/tasks/spec scaffolds into the canonical `reffyspec/` layout from indexed Reffy artifacts.
-- `reffy plan validate|list|show|archive`: runs the planning lifecycle natively inside Reffy against `reffyspec/`.
-- `reffy spec list|show`: inspects current spec state natively from `reffyspec/`.
+- `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 diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from compatible `spec.md` files.
 
 Output modes:
@@ -59,22 +59,11 @@ 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
 ```
 
-## Runtime Position
-
-Reffy is the planning/runtime authority in this repository. `reffyspec/` is the native planning/spec surface that matches that runtime ownership.
-
-That means:
-
-1. Reffy owns ideation artifacts, planning scaffolds, inspection, validation, and archive lifecycle behavior.
-2. The vendored fork at `.vendor/ReffySpec` is reference-only.
-3. `reffyspec/` is canonical for active changes, archived changes, and current specs.
-4. No external planning CLI is part of the normal workflow.
-
 ## Using Reffy With ReffySpec
 
 A practical pattern is:
 
-1. Use Reffy for ideation and context capture in `.reffy/`.
+1. Use Reffy for ideation and context capture in `.reffy/artifacts/`.
 2. Use Reffy to scaffold and manage planning files in `reffyspec/`.
 3. Keep a clear traceable path from exploratory artifacts to formal specs.
 4. Use Reffy commands for day-to-day workflow.
@@ -84,36 +73,9 @@ 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`.
-- `.reffy/AGENTS.md`: defines Reffy as the primary runtime and documents compatibility expectations.
+- `.reffy/AGENTS.md`: defines the artifact and ideation workflow.
 - `reffyspec/AGENTS.md`: defines the ReffySpec planning/spec workflow conventions used in this repo.
-- `src/cli.ts`: `reffy init`/`reffy bootstrap` enforce this integration by idempotently writing the managed guidance into `AGENTS.md`, `.reffy/AGENTS.md`, and `reffyspec/AGENTS.md`.
-
-Practical connection pattern for any repo:
-
-1. Run `reffy init` to install/refresh the Reffy instruction layer.
-2. Keep ReffySpec instructions in the same root `AGENTS.md`.
-3. During planning, cite only relevant Reffy artifacts from `.reffy/artifacts/` in your proposal/spec docs.
-4. Prefer Reffy commands for day-to-day workflow.
-
-## Current Boundary
-
-The current project boundary is:
-
-- Native Reffy ownership:
-  - `reffy plan create`
-  - `reffy plan validate`
-  - `reffy plan list`
-  - `reffy plan show`
-  - `reffy plan archive`
-  - `reffy spec list`
-  - `reffy spec show`
-- Native ReffySpec surface:
-  - the on-disk `reffyspec/changes/` and `reffyspec/specs/` layout
-  - `reffyspec/AGENTS.md` as the planning/spec conventions file
-- Unresolved runtime gaps:
-  - none identified for the normal local planning lifecycle in v1
-
-That means the normal workflow is fully Reffy and ReffySpec native.
+- `reffyspec/project.md`: captures durable project context for agents, including purpose, stack, architecture, conventions, and constraints.
 
 ## Develop
 
@@ -127,3 +89,12 @@ npm test
 ```
 
 `npm install` runs this package's `prepare` step, which builds `dist/` automatically.
+
+## Release Security
+
+Reffy publishes from GitHub Actions using npm trusted publishing with provenance enabled.
+
+To verify an installed package:
+
+- Check the package provenance details on npm.
+- Run `npm audit signatures` after install to verify registry signatures and available provenance attestations.

package/dist/cli.js

@@ -24,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
@@ -355,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]",
@@ -363,8 +417,8 @@ 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.",
@@ -873,74 +927,11 @@ async function main() {
     if (command === "init") {
         printBanner(output);
         const repoRoot = parseRepoArg(rest);
-        const workspace = await prepareCanonicalWorkspace(repoRoot);
-        const planning = await prepareCanonicalPlanningLayout(repoRoot);
-        const agents = await initAgents(repoRoot);
-        const payload = {
-            status: "ok",
-            command: "init",
-            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,
-        };
-        if (output === "json") {
-            printResult(output, payload);
-        }
-        else {
-            if (workspace.message) {
-                console.log(workspace.message);
-            }
-            if (planning.message) {
-                console.log(planning.message);
-            }
-            console.log(`Updated ${agents.root_agents_path}`);
-            console.log(`Updated ${agents.reffy_agents_path}`);
-            console.log(`Updated ${agents.reffyspec_agents_path}`);
-        }
-        return 0;
+        return await runSetupCommand("init", output, repoRoot);
     }
     if (command === "bootstrap") {
         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",
-            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);
-        }
-        else {
-            if (workspace.message) {
-                console.log(workspace.message);
-            }
-            if (planning.message) {
-                console.log(planning.message);
-            }
-            console.log(`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)}`);
-        }
-        return 0;
+        return await runSetupCommand("bootstrap", output, repoRoot);
     }
     if (command === "migrate") {
         const repoRoot = parseRepoArg(rest);

package/dist/plan-archive.js

@@ -33,20 +33,27 @@ async function listFilesRecursive(dir) {
     }
     return files.sort();
 }
-function parseAddedRequirements(content, relPath) {
+function parseArchiveableRequirements(content, relPath) {
     const lines = content.split(/\r?\n/);
     const sectionTypes = new Set();
-    const blocks = [];
-    let inAddedSection = false;
+    const added = [];
+    const modified = [];
+    let currentSectionType = null;
     let currentTitle = null;
     let currentLines = [];
     const flush = () => {
         if (!currentTitle)
             return;
-        blocks.push({
+        const block = {
             title: currentTitle,
             content: currentLines.join("\n").trimEnd(),
-        });
+        };
+        if (currentSectionType === "ADDED") {
+            added.push(block);
+        }
+        else if (currentSectionType === "MODIFIED") {
+            modified.push(block);
+        }
         currentTitle = null;
         currentLines = [];
     };
@@ -56,7 +63,7 @@ function parseAddedRequirements(content, relPath) {
             flush();
             const sectionType = sectionMatch[1] ?? "";
             sectionTypes.add(sectionType);
-            inAddedSection = sectionType === "ADDED";
+            currentSectionType = sectionType === "ADDED" || sectionType === "MODIFIED" ? sectionType : null;
             continue;
         }
         const requirementMatch = line.match(REQUIREMENT_PATTERN);
@@ -71,17 +78,17 @@ function parseAddedRequirements(content, relPath) {
         }
     }
     flush();
-    const unsupported = Array.from(sectionTypes).filter((sectionType) => sectionType !== "ADDED");
+    const unsupported = Array.from(sectionTypes).filter((sectionType) => sectionType !== "ADDED" && sectionType !== "MODIFIED");
     if (unsupported.length > 0) {
         throw new Error(`${relPath}: unsupported delta sections for archive: ${unsupported.join(", ")}`);
     }
-    if (!inAddedSection && sectionTypes.size === 0) {
+    if (sectionTypes.size === 0) {
         throw new Error(`${relPath}: no supported archiveable requirements found`);
     }
-    if (blocks.length === 0) {
-        throw new Error(`${relPath}: no ADDED requirements found to archive`);
+    if (added.length === 0 && modified.length === 0) {
+        throw new Error(`${relPath}: no archiveable requirements found`);
     }
-    return blocks;
+    return { added, modified };
 }
 function buildNewCurrentSpec(capability, changeId, blocks) {
     return [
@@ -95,18 +102,74 @@ function buildNewCurrentSpec(capability, changeId, blocks) {
         "",
     ].join("\n");
 }
-function appendRequirementsToCurrentSpec(existing, blocks, relPath) {
+function parseCurrentSpecRequirementBlocks(existing, relPath) {
     if (!existing.includes(REQUIREMENTS_HEADING)) {
         throw new Error(`${relPath}: current spec is missing a "## Requirements" section`);
     }
-    for (const block of blocks) {
-        const escaped = block.title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const duplicatePattern = new RegExp(`^###\\s+Requirement:\\s+${escaped}\\s*$`, "m");
-        if (duplicatePattern.test(existing)) {
+    const lines = existing.split(/\r?\n/);
+    const blocks = [];
+    let inRequirements = false;
+    let currentTitle = null;
+    let currentLines = [];
+    const flush = () => {
+        if (!currentTitle)
+            return;
+        blocks.push({
+            title: currentTitle,
+            content: currentLines.join("\n").trimEnd(),
+        });
+        currentTitle = null;
+        currentLines = [];
+    };
+    for (const line of lines) {
+        if (line.trim() === REQUIREMENTS_HEADING) {
+            inRequirements = true;
+            continue;
+        }
+        if (!inRequirements) {
+            continue;
+        }
+        if (/^##\s+/.test(line) && line.trim() !== REQUIREMENTS_HEADING) {
+            flush();
+            break;
+        }
+        const requirementMatch = line.match(REQUIREMENT_PATTERN);
+        if (requirementMatch) {
+            flush();
+            currentTitle = requirementMatch[1]?.trim() ?? "unknown";
+            currentLines = [line];
+            continue;
+        }
+        if (currentTitle) {
+            currentLines.push(line);
+        }
+    }
+    flush();
+    return blocks;
+}
+function mergeRequirementsIntoCurrentSpec(existing, delta, relPath) {
+    const currentBlocks = parseCurrentSpecRequirementBlocks(existing, relPath);
+    const currentTitles = new Set(currentBlocks.map((block) => block.title));
+    for (const block of delta.added) {
+        if (currentTitles.has(block.title)) {
             throw new Error(`${relPath}: current spec already contains requirement "${block.title}"`);
         }
+        currentBlocks.push(block);
+        currentTitles.add(block.title);
+    }
+    for (const block of delta.modified) {
+        const index = currentBlocks.findIndex((currentBlock) => currentBlock.title === block.title);
+        if (index < 0) {
+            throw new Error(`${relPath}: current spec is missing requirement "${block.title}" required for MODIFIED archive`);
+        }
+        currentBlocks[index] = block;
+    }
+    const requirementsHeadingIndex = existing.indexOf(REQUIREMENTS_HEADING);
+    if (requirementsHeadingIndex < 0) {
+        throw new Error(`${relPath}: current spec is missing a "## Requirements" section`);
     }
-    return `${existing.trimEnd()}\n\n${blocks.map((block) => block.content).join("\n\n")}\n`;
+    const prefix = existing.slice(0, requirementsHeadingIndex + REQUIREMENTS_HEADING.length);
+    return `${prefix}\n${currentBlocks.map((block) => `\n${block.content}`).join("")}\n`;
 }
 async function buildSpecUpdates(repoRoot, changeId, changeDir) {
     const specsRoot = path.join(changeDir, "specs");
@@ -121,11 +184,17 @@ async function buildSpecUpdates(repoRoot, changeId, changeDir) {
             continue;
         const deltaContent = await fs.readFile(deltaPath, "utf8");
         const relDeltaPath = path.relative(repoRoot, deltaPath).split(path.sep).join("/");
-        const blocks = parseAddedRequirements(deltaContent, relDeltaPath);
+        const delta = parseArchiveableRequirements(deltaContent, relDeltaPath);
         const currentSpecPath = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs", capability, "spec.md");
-        const nextContent = (await pathExists(currentSpecPath))
-            ? appendRequirementsToCurrentSpec(await fs.readFile(currentSpecPath, "utf8"), blocks, path.relative(repoRoot, currentSpecPath).split(path.sep).join("/"))
-            : buildNewCurrentSpec(capability, changeId, blocks);
+        const currentSpecExists = await pathExists(currentSpecPath);
+        const nextContent = currentSpecExists
+            ? mergeRequirementsIntoCurrentSpec(await fs.readFile(currentSpecPath, "utf8"), delta, path.relative(repoRoot, currentSpecPath).split(path.sep).join("/"))
+            : (() => {
+                if (delta.modified.length > 0) {
+                    throw new Error(`${relDeltaPath}: cannot archive MODIFIED requirements without an existing current spec`);
+                }
+                return buildNewCurrentSpec(capability, changeId, delta.added);
+            })();
         updates.set(currentSpecPath, nextContent);
     }
     return updates;

package/dist/planning-workspace.js

@@ -1,6 +1,38 @@
 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";
+const DEFAULT_PROJECT_CONTEXT_TEMPLATE = `# Project Context
+
+## Purpose
+[Describe your project's purpose and goals]
+
+## Tech Stack
+- [List your primary technologies]
+- [e.g., TypeScript, React, Node.js]
+
+## Project Conventions
+
+### Code Style
+[Describe your code style preferences, formatting rules, and naming conventions]
+
+### Architecture Patterns
+[Document your architectural decisions and patterns]
+
+### Testing Strategy
+[Explain your testing approach and requirements]
+
+### Git Workflow
+[Describe your branching strategy and commit conventions]
+
+## Domain Context
+[Add domain-specific knowledge that AI assistants need to understand]
+
+## Important Constraints
+[List any technical, business, or regulatory constraints]
+
+## External Dependencies
+[Document key external services, APIs, or systems]
+`;
 async function pathExists(targetPath) {
     try {
         await fs.access(targetPath);
@@ -12,12 +44,16 @@ async function pathExists(targetPath) {
 }
 async function ensureCanonicalPlanningStructure(repoRoot) {
     const planningDir = resolveCanonicalPlanningDir(repoRoot);
+    const projectContextPath = path.join(planningDir, "project.md");
     let created = false;
     if (!(await pathExists(planningDir))) {
         created = true;
     }
     await fs.mkdir(path.join(planningDir, "changes", "archive"), { recursive: true });
     await fs.mkdir(path.join(planningDir, "specs"), { recursive: true });
+    if (!(await pathExists(projectContextPath))) {
+        await fs.writeFile(projectContextPath, DEFAULT_PROJECT_CONTEXT_TEMPLATE, "utf8");
+    }
     return created;
 }
 export async function prepareCanonicalPlanningLayout(repoRoot) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "CLI-first, framework-agnostic references workflow for any repo (TypeScript)",
   "keywords": [
     "reffy",
@@ -12,6 +12,14 @@
     "sdd"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RoskiDeluge/reffy.git"
+  },
+  "homepage": "https://github.com/RoskiDeluge/reffy",
+  "bugs": {
+    "url": "https://github.com/RoskiDeluge/reffy/issues"
+  },
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -33,6 +41,10 @@
   "engines": {
     "node": ">=20"
   },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
   "dependencies": {
     "beautiful-mermaid": "^0.1.3",
     "mime-types": "^2.1.35",