@garygentry/feature-forge 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,65 @@
+# @garygentry/feature-forge
+
+Cross-agent installer for the [**feature-forge**](https://github.com/garygentry/feature-forge)
+skill suite — an end-to-end feature-development pipeline that runs on any coding agent
+(Claude, Codex, Copilot, Cursor, or Gemini).
+
+This package installs the canonical forge skills into the agents detected on your machine.
+It is dependency-free and performs sandboxed, manifest-tracked writes.
+
+## Usage
+
+```bash
+# Install into every detected agent:
+npx @garygentry/feature-forge install
+
+# Scope to one agent:
+npx @garygentry/feature-forge install -a codex
+
+# Preview the plan without writing anything:
+npx @garygentry/feature-forge install --dry-run --json
+```
+
+### Commands
+
+| Command            | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `install` (`add`)  | Install feature-forge into the target agent(s).                   |
+| `update`           | Reconcile an existing install to the current adapters.            |
+| `uninstall` (`remove`) | Remove a prior install (manifest-tracked files only).         |
+| `list` (`ls`)      | Report per-agent detected / installed / up-to-date status.        |
+
+### Common flags
+
+| Flag                | Description                                                            |
+| ------------------- | --------------------------------------------------------------------- |
+| `-a, --agent <id>`  | Scope to one agent (`claude`/`codex`/`copilot`/`cursor`/`gemini`).    |
+| `-g, --global`      | Install into the user-level config dir (default: project-local).      |
+| `--symlink`         | Symlink the bundle instead of copying (Windows always copies).        |
+| `--dry-run`         | Print the planned actions without changing anything.                  |
+| `--json`            | Emit the run report as JSON.                                          |
+| `--skip-rauf`       | Skip the rauf resolvability preflight (records `raufPin: null`).      |
+
+## Claude
+
+Claude Code users can alternatively install via the plugin marketplace:
+
+```bash
+/plugin marketplace add garygentry/feature-forge
+/plugin install feature-forge@feature-forge
+```
+
+## Notes
+
+The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
+[`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.7.0`) and records it; pass
+`--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
+`npx @garygentry/rauf` or its
+[binary script](https://github.com/garygentry/rauf#install). See the
+[feature-forge README](https://github.com/garygentry/feature-forge#readme) for the full
+pipeline documentation and per-agent setup guides.
+
+## License
+
+MIT

package/adapters/claude/references/forge-config-schema.json

@@ -147,8 +147,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned rauf@0.6.0 default). Or install/upgrade just the rauf CLI: `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins rauf@0.6.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.7.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/codex/references/forge-config-schema.json

@@ -147,8 +147,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned rauf@0.6.0 default). Or install/upgrade just the rauf CLI: `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins rauf@0.6.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.7.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/copilot/references/forge-config-schema.json

@@ -147,8 +147,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned rauf@0.6.0 default). Or install/upgrade just the rauf CLI: `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins rauf@0.6.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.7.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/cursor/references/forge-config-schema.json

@@ -147,8 +147,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned rauf@0.6.0 default). Or install/upgrade just the rauf CLI: `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins rauf@0.6.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.7.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/gemini/references/forge-config-schema.json

@@ -147,8 +147,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned rauf@0.6.0 default). Or install/upgrade just the rauf CLI: `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins rauf@0.6.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.7.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/dist/manifest.d.ts

@@ -28,7 +28,7 @@ export interface BuildManifestArgs {
     readonly skills: readonly string[];
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (spec 03). */
     readonly sourceHash: string;
-    /** Recorded pinned rauf coordinate (e.g. "rauf@0.6.0"); `null` when `--skip-rauf` (spec 06). */
+    /** Recorded pinned rauf coordinate (e.g. "@garygentry/rauf@0.7.0"); `null` when `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** Symlink mode only: the source bundle the namespace dir links to (REQ-SAFE-02). */
     readonly link?: {

package/dist/rauf.d.ts

@@ -17,26 +17,27 @@ import { type Result } from "./types.js";
  * downstream `forge-rauf-loop-default` read the same value, and recorded into each manifest
  * as `InstallManifest.raufPin` (05-manifest-and-uninstall.md).
  *
- * Shape: `<name>@<version>` — UNSCOPED `rauf`. Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.6.0.
+ * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
+ * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.7.0.
  *
- * Correctable config (OQ-C): the FINAL published coordinate is confirmed by `packaging-docs-ci`
- * when rauf's publish path is stood up. Until then this resolves to a package that does not yet
- * exist on npm (IR-2), so the preflight WILL fail — the known, designed failure mode, not a bug.
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.7.0` resolves from the npm registry, so the
+ * preflight below passes by default. (Historically this pin pointed at an unpublished package and
+ * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export declare const RAUF_PIN = "rauf@0.6.0";
+export declare const RAUF_PIN = "@garygentry/rauf@0.7.0";
 /**
  * An injectable, READ-ONLY registry query (D1). Given a coordinate `name@version`, returns the
  * resolved version string on success, or an `InstallerError` if it is not resolvable.
  *
  * Injectable so tests mock the registry with NO real network: the default implementation
  * (`defaultRegistryQuery`) shells `npm view <coordinate> version`; a test passes a stub
- * returning `ok("0.6.0")` or `err({ code: "RAUF_UNRESOLVABLE", ... })`.
+ * returning `ok("0.7.0")` or `err({ code: "RAUF_UNRESOLVABLE", ... })`.
  *
  * Contract: the query MUST be read-only — it MUST NOT install, MUST NOT mutate global npm
  * state, and MUST NOT execute rauf. `npm view` satisfies this (it only reads registry metadata).
  *
- * @param coordinate - the `name@version` to resolve, e.g. "rauf@0.6.0"
+ * @param coordinate - the `name@version` to resolve, e.g. "@garygentry/rauf@0.7.0"
  * @returns Result<string> — the resolved version on success; RAUF_UNRESOLVABLE on failure.
  */
 export type RegistryQuery = (coordinate: string) => Result<string>;
@@ -44,12 +45,12 @@ export type RegistryQuery = (coordinate: string) => Result<string>;
 export interface PreflightRaufOpts {
     /**
      * When true (the `--skip-rauf` flag), skip the preflight entirely: perform NO network call
-     * and return `{ raufPin: null }`. For environments that knowingly defer rauf (e.g. CI
-     * dry-runs while rauf is unpublished — IR-2).
+     * and return `{ raufPin: null }`. For environments that knowingly defer rauf (e.g. offline
+     * installs or CI dry-runs that won't use the default loop).
      */
     readonly skip?: boolean;
     /**
-     * The registry query to use. Default: `defaultRegistryQuery` (`npm view rauf@<pin> version`
+     * The registry query to use. Default: `defaultRegistryQuery` (`npm view <RAUF_PIN> version`
      * via node:child_process). Tests inject a stub so no real network call is made.
      */
     readonly query?: RegistryQuery;
@@ -61,7 +62,7 @@ export interface PreflightRaufOpts {
  *  - `opts.skip` (the `--skip-rauf` flag) ⇒ return `ok({ raufPin: null })` immediately, with NO
  *    network call.
  *  - otherwise ⇒ run a READ-ONLY registry resolvability check on `RAUF_PIN` (default query:
- *    `npm view rauf@<pin> version`). No install, no global-npm mutation, no execution of rauf.
+ *    `npm view <RAUF_PIN> version`). No install, no global-npm mutation, no execution of rauf.
  *      · resolvable  ⇒ return `ok({ raufPin: RAUF_PIN })` — the value the manifest records.
  *      · unresolvable ⇒ return `err(<RAUF_UNRESOLVABLE>)` carrying the FIXED message (§6).
  *

package/dist/rauf.js

@@ -18,14 +18,15 @@ import { err, ok } from "./types.js";
  * downstream `forge-rauf-loop-default` read the same value, and recorded into each manifest
  * as `InstallManifest.raufPin` (05-manifest-and-uninstall.md).
  *
- * Shape: `<name>@<version>` — UNSCOPED `rauf`. Advanced on each feature-forge release to a new
- * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.6.0.
+ * Shape: `<name>@<version>` — the SCOPED package `@garygentry/rauf` (the unscoped `rauf` name is
+ * blocked by npm's similarity filter). Advanced on each feature-forge release to a new
+ * known-compatible rauf (REQ-RAUF-03). The current rauf version is 0.7.0.
  *
- * Correctable config (OQ-C): the FINAL published coordinate is confirmed by `packaging-docs-ci`
- * when rauf's publish path is stood up. Until then this resolves to a package that does not yet
- * exist on npm (IR-2), so the preflight WILL fail — the known, designed failure mode, not a bug.
+ * rauf is now PUBLISHED (rauf#28): `@garygentry/rauf@0.7.0` resolves from the npm registry, so the
+ * preflight below passes by default. (Historically this pin pointed at an unpublished package and
+ * the preflight was a designed-to-fail check — see the `--skip-rauf` escape hatch.)
  */
-export const RAUF_PIN = "rauf@0.6.0";
+export const RAUF_PIN = "@garygentry/rauf@0.7.0";
 /**
  * Resolvability preflight for the pinned default loop runner (D1; REQ-RAUF-01/02/03, OQ-1).
  *
@@ -33,7 +34,7 @@ export const RAUF_PIN = "rauf@0.6.0";
  *  - `opts.skip` (the `--skip-rauf` flag) ⇒ return `ok({ raufPin: null })` immediately, with NO
  *    network call.
  *  - otherwise ⇒ run a READ-ONLY registry resolvability check on `RAUF_PIN` (default query:
- *    `npm view rauf@<pin> version`). No install, no global-npm mutation, no execution of rauf.
+ *    `npm view <RAUF_PIN> version`). No install, no global-npm mutation, no execution of rauf.
  *      · resolvable  ⇒ return `ok({ raufPin: RAUF_PIN })` — the value the manifest records.
  *      · unresolvable ⇒ return `err(<RAUF_UNRESOLVABLE>)` carrying the FIXED message (§6).
  *
@@ -108,11 +109,13 @@ function raufUnresolvableError() {
         message: "pinned default loop runner `" +
             RAUF_PIN +
             "` is not resolvable from the npm registry. Network is required at " +
-            "install; if rauf is not yet published this is the known cross-repo " +
-            "prerequisite (see packaging-docs-ci). Skills were still installed; " +
-            "the default loop will be unavailable until rauf publishes.",
+            "install; this usually means no network access or a registry that cannot " +
+            "see the pin. Skills were still installed; the default loop will be " +
+            "unavailable until the pin resolves.",
         remedy: "Ensure network access and that `" +
             RAUF_PIN +
-            "` is published, or re-run with `--skip-rauf` to defer the default loop.",
+            "` is resolvable (`npm view " +
+            RAUF_PIN +
+            " version`), or re-run with `--skip-rauf` to defer the default loop.",
     };
 }

package/dist/types.d.ts

@@ -124,7 +124,7 @@ export interface InstallManifest {
     readonly featureForgeVersion: string | null;
     /** SHA-256 over the source bundle's canonical (sorted-path) file set — drift anchor (OQ-4, spec 03). */
     readonly sourceHash: string;
-    /** Pinned rauf coordinate recorded at install, e.g. "rauf@0.6.0"; `null` if `--skip-rauf` (spec 06). */
+    /** Pinned rauf coordinate recorded at install, e.g. "@garygentry/rauf@0.7.0"; `null` if `--skip-rauf` (spec 06). */
     readonly raufPin: string | null;
     /** ISO-8601 timestamps. */
     readonly installedAt: string;

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "@garygentry/feature-forge",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cross-agent installer for the feature-forge skill suite — installs the canonical forge pipeline into Claude, Codex, Copilot, Cursor, or Gemini.",
   "license": "MIT",
   "type": "module",
-  "bin": { "feature-forge": "dist/cli.js" },
+  "bin": {
+    "feature-forge": "dist/cli.js"
+  },
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "adapters"
+  ],
+  "engines": {
+    "node": ">=18"
   },
-  "files": ["dist", "adapters"],
-  "engines": { "node": ">=18" },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/garygentry/feature-forge.git",
     "directory": "installer"
   },
   "homepage": "https://github.com/garygentry/feature-forge#readme",
-  "bugs": { "url": "https://github.com/garygentry/feature-forge/issues" },
+  "bugs": {
+    "url": "https://github.com/garygentry/feature-forge/issues"
+  },
   "keywords": [
     "feature-forge",
     "cli",
@@ -28,7 +40,9 @@
     "cursor",
     "gemini"
   ],
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "node --test",