reffy-cli 1.0.0 → 1.1.1

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/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.1",
   "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",