reffy-cli 0.7.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 intended as an ideation layer for spec-driven development (SDD) in straightforward, version controlled and agent-friendly markdown files.
+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,19 +17,23 @@ 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 doctor`: diagnoses required Reffy setup and optional tool availability.
+- `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 diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from OpenSpec `spec.md`.
+- `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:
 
@@ -46,34 +50,32 @@ reffy doctor --output text
 reffy doctor --output json
 reffy summarize --output text
 reffy summarize --output json
+reffy plan create --change-id add-login-flow --artifacts login-idea.md
+reffy plan list --output json
+reffy plan archive add-login-flow
+reffy spec show auth --output json
 reffy diagram render --stdin --format svg < diagram.mmd
-reffy diagram render --input openspec/specs/auth/spec.md --format ascii
-reffy diagram render --input openspec/specs/auth/spec.md --format svg --output .reffy/artifacts/auth-spec.svg
+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
 ```
 
-## Using Reffy With SDD Frameworks (OpenSpec Example)
+## Using Reffy With ReffySpec
 
-`reffy` is designed to complement spec-driven development workflows rather than replace them. A common pattern is:
+A practical pattern is:
 
-1. Use Reffy for ideation and context capture in `.reffy/`.
-2. Use an SDD framework (for example [OpenSpec](https://github.com/Fission-AI/OpenSpec)) for formal proposals/specs/tasks.
-3. Keep a clear handoff from exploratory artifacts to formal specs.
+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.
 
 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`: OpenSpec block routes planning/proposal/spec requests to `@/openspec/AGENTS.md`.
-- `.reffy/AGENTS.md`: defines Reffy as the ideation/context layer and documents handoff expectations to OpenSpec.
-- `openspec/AGENTS.md`: defines OpenSpec as the formal planning/specification workflow after ideation is stable.
-- `src/cli.ts`: `reffy init`/`reffy bootstrap` enforce this integration by idempotently writing the managed Reffy guidance into `AGENTS.md` and `.reffy/AGENTS.md`.
-
-Practical connection pattern for any repo:
-
-1. Run `reffy init` to install/refresh the Reffy instruction layer.
-2. Keep your SDD framework instructions (for example OpenSpec) in the same root `AGENTS.md`.
-3. During planning, cite only relevant Reffy artifacts from `.reffy/artifacts/` in your proposal/spec docs.
-4. Continue implementation in your SDD framework's normal review/approval process.
+- `AGENTS.md`: ReffySpec block routes planning/proposal/spec requests to `@/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.
 
 ## Develop
 
@@ -87,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.