@rhize/skill-forge 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,19 @@ promote/hold/reject decision**, before it is allowed anywhere near your working
 
 ## Quickstart
 
+```bash
+npx @rhize/skill-forge init
+```
+
+Optional, but recommended first: `init` detects which coding agents you have installed (Claude
+Code, Codex CLI, Cursor, Windsurf, OpenCode, Gemini CLI, and more), lets you pick which of their
+skill directories should be gated, a default promotion target, and an optional agent to hand
+follow-up prompts off to (see [`--ingest`](#ingestion-handoff---ingest)). No configuration is
+required for a first run either way — skip `init` and skill-forge defaults to `<cwd>/.claude/skills`
+as its promotion target and `~/.skill-forge/quarantine` as its sandbox (and offers to run `init` for
+you the first time `add`/`scan`/`list`/`status` runs with no config present, in an interactive
+terminal). See [docs/configuration.md](docs/configuration.md) for the full field reference.
+
 ```bash
 npx @rhize/skill-forge add <owner>/<skill-name>
 ```
@@ -35,10 +48,6 @@ One command runs the whole gate:
 4. Runs overlap analysis against your configured skill set, if one is configured.
 5. Prints a report and asks you to **promote**, **hold**, or **reject** the candidate.
 
-No configuration is required for a first run: skill-forge defaults to `<cwd>/.claude/skills` as
-its promotion target and `~/.skill-forge/quarantine` as its sandbox. See
-[docs/configuration.md](docs/configuration.md) to change either.
-
 To gate a skill without installing it (always cleans up afterward):
 
 ```bash
@@ -51,12 +60,29 @@ anything ending in `.git`), or a local filesystem path.
 ## Commands
 
 ```
+skill-forge init [options]             Detect installed agents and set gate targets / handoff agent
 skill-forge add <source> [options]     Quarantine-install a skill and run it through the gate
-skill-forge scan <source>              Gate a skill without installing it (always cleans up)
+skill-forge scan <source> [options]    Gate a skill without installing it (always cleans up)
 skill-forge list                       List skills currently held in quarantine
 skill-forge status                     Show configuration and quarantine summary
 ```
 
+### `init`
+
+```bash
+skill-forge init              # interactive: pick targets, default target, handoff agent
+skill-forge init --defaults   # non-interactive: all detected agents, first as default (CI)
+skill-forge init --list       # print detected agent skill roots and exit — no writes
+```
+
+Probes the known agent matrix (`src/agents.ts`) for both project-relative (`.claude/skills`, ...)
+and global (`~/.codex/skills`, ...) skill directories that already exist on disk, then writes
+`skillsRoots`, `agents`, `defaultTarget`, and (if you pick a handoff agent) `handoffCommand` to
+`config.json`. Safe to re-run any time — it always starts from your existing config and only
+overwrites the fields it's responsible for. If no `config.json` exists yet, `add`/`scan`/`list`/
+`status` offer to run this for you on first use (skipped entirely for `--json`/`--yes`/non-TTY
+invocations, so scripted runs never block on a prompt).
+
 ### `add`
 
 ```bash
@@ -75,26 +101,28 @@ target skills root until you decide.
 |---|---|
 | *(none)* | Prompts you to **promote**, **hold**, or **reject** the candidate. |
 | `-y, --yes` | Skips the prompt and honors the gate verdict: a `block` safety verdict is rejected (process exits nonzero); anything else (`pass`/`warn`) is promoted. |
-| `-t, --target <dir>` | Skills root to promote into. Defaults to the config's `skillsRoots[0]`. |
-| `--json` | Prints the gate result (profile, safety findings, overlap) as JSON instead of the terminal report box. |
-| `--ingest` | Pro. After a successful promote, hands off to Claude — see [Claude handoff](#claude-handoff---ingest). |
+| `-t, --target <dir>` | Skills root to promote into. Defaults to the config's `defaultTarget`, then `skillsRoots[0]`. |
+| `--json` | Prints the gate result (profile, safety findings, overlap) as JSON instead of the terminal report box. Implies non-interactive: the decision is made the same way `--yes` makes it (verdict decides promote/hold/reject), never an interactive prompt. |
+| `--ingest` | Pro (free during the 0.x beta). After a successful promote, hands off to a coding agent — see [Ingestion handoff](#ingestion-handoff---ingest). |
 
-With a valid Pro license, a promoted skill gets a provenance entry appended to
-`<target>/SOURCES.md`, and every promote or hold decision is recorded to
-`~/.skill-forge/queue.json` (or `$SKILL_FORGE_HOME/queue.json`) — see
+A promoted skill gets a provenance entry appended to `<target>/SOURCES.md`, and every promote or
+hold decision is recorded to `~/.skill-forge/queue.json` (or `$SKILL_FORGE_HOME/queue.json`) — see
 [`docs/queue-schema.md`](docs/queue-schema.md) for the entry schema. A reject writes neither —
-nothing is left behind to record. Without a license, `add` prints a short upgrade notice in place
-of the ledger entry and queue write instead, and otherwise completes normally.
+nothing is left behind to record. These are Pro features that run free during the 0.x beta (see
+[docs/pro.md](docs/pro.md#beta-pricing-0x)): with no valid license, `add` still writes them, and
+prints a one-line notice above the report instead of skipping them.
 
 ### `scan`
 
 ```bash
 skill-forge scan owner/name
+skill-forge scan owner/name --json
 ```
 
 Runs the same gate pipeline as `add` (profile → safety → overlap → report) but never promotes
 anything — the quarantine sandbox is always cleaned up afterward, on success or failure. Exits
-nonzero when the safety verdict is `block`.
+nonzero when the safety verdict is `block`. `--json` prints the same gate-result payload shape as
+`add`'s.
 
 ### `list` / `status`
 
@@ -111,9 +139,10 @@ strictness) plus a count of held entries.
 | Safety gate — built-in ruleset + SkillSpector shell-out | ✓ | ✓ |
 | Terminal report + `--json` | ✓ | ✓ |
 | Promote / hold / reject decision | ✓ | ✓ |
+| `init` setup wizard (agent detection, gate targets, handoff agent) | ✓ | ✓ |
 | Overlap analysis against your configured skill set | | ✓ |
 | Provenance ledger (`SOURCES.md` audit trail) | | ✓ |
-| Pending-ingestion queue + `--ingest` Claude handoff | | ✓ |
+| Pending-ingestion queue + `--ingest` handoff | | ✓ |
 | Set-level organizer (capability registry, redundancy, dependency graph) | | ✓ |
 
 Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit
@@ -121,13 +150,16 @@ promote/reject decision, with nothing held back. Pro is the curation layer on to
 candidate duplicates something you already have, and an ongoing provenance record across your
 whole skill set rather than a single install-time decision.
 
-**Current build status:** this is a pre-release build. Overlap analysis, the provenance ledger,
-and the pending-ingestion queue / `--ingest` handoff are gated on a valid license
-(`SKILL_FORGE_LICENSE` env var or `config.json`'s `licenseKey`, verified offline — see
-[docs/pro.md](docs/pro.md)); without one, `add` prints a short upgrade notice in place of each and
-otherwise completes normally. The set-level organizer and the skills.sh partner-audit enrichment
-are not yet exposed by any CLI command, licensed or not. See [docs/pro.md](docs/pro.md) for the
-per-feature implementation status.
+**Everything free until 1.0.** This is a 0.x beta build, and the Pro tier's runtime license check
+is intentionally asleep for the whole 0.x line: overlap analysis, the provenance ledger, and the
+pending-ingestion queue / `--ingest` handoff all run for everyone, licensed or not. Without a valid
+license (`SKILL_FORGE_LICENSE` env var or `config.json`'s `licenseKey`, verified offline), `add`
+prints a one-line notice — `Pro feature (...) — free during the 0.x beta; will require a license at
+1.0.` — above the report (or in the `--json` payload's `notices` array) and otherwise runs exactly
+as a licensed run would. At 1.0 the lock re-arms and these features go back to requiring a valid
+key. The set-level organizer and the skills.sh partner-audit enrichment are not yet exposed by any
+CLI command, licensed or not, beta or not. See [docs/pro.md](docs/pro.md) for the per-feature
+implementation status.
 
 ## Security model
 
@@ -152,37 +184,51 @@ per-feature implementation status.
   `VERCEL_OIDC_TOKEN`. The client exists (`src/gate/skillsSh.ts`) but `add`/`scan` do not call it
   yet in this build — see [docs/gate-policy.md](docs/gate-policy.md) for current status.
 
-## Claude handoff (`--ingest`)
+## Ingestion handoff (`--ingest`)
 
 `skill-forge` deliberately doesn't try to decide *what to extract* from a skill worth adopting —
 that deeper judgment (which patterns to keep, whether to absorb into an existing skill vs. fork a
-new one, verifying the result beats baseline) belongs to the companion Claude Code skill
-`rhize-skill-forge`, invoked via its `/rhize-meta:forge-ingest` slash command.
+new one, verifying the result beats baseline) is a job for a coding agent, not the gate. `--ingest`
+hands a promoted skill off to one, running the bundled, agent-neutral prompt at
+`assets/ingest-prompt.md` (Claude Code users get a deeper experience via the companion
+`rhize-skill-forge` plugin skill, but the bundled prompt works with any agent).
 
 ```bash
 skill-forge add owner/name --yes --ingest
 ```
 
-- If a `claude` binary is on `PATH`, skill-forge spawns it (inheriting your terminal) running
-  `claude -p "/rhize-meta:forge-ingest <installedPath>"`.
-- If not, skill-forge prints that exact command for you to run yourself.
-- Every promote or hold is recorded to the pending queue (`~/.skill-forge/queue.json`) regardless
-  of `--ingest` — nothing is lost if you skip the handoff. A later
-  `/rhize-meta:forge-ingest` run with no argument drains the whole pending queue.
+The command that gets run, in order:
+
+1. `config.handoffCommand` — an argv-style template (`["claude", "-p", "{prompt}"]`-shaped) set by
+   `skill-forge init`'s "handoff agent" prompt, with `{path}` (the installed skill) and `{prompt}`
+   (the bundled prompt file) substituted in. Never shell-parsed, so it's safe even if a substituted
+   path contains shell metacharacters.
+2. Otherwise, the first known agent binary found on `PATH` (`claude`, `codex`, `cursor-agent`,
+   `windsurf`, `opencode`, `gemini`), invoked generically with the prompt.
+3. Otherwise, skill-forge prints the prompt path and skill path for you to hand off yourself.
+
+Every promote or hold is recorded to the pending queue (`~/.skill-forge/queue.json`) regardless of
+`--ingest` — nothing is lost if you skip the handoff. See [`docs/queue-schema.md`](docs/queue-schema.md)
+for the entry schema.
 
 ## Configuration
 
-Config lives at `~/.skill-forge/config.json` (or `$SKILL_FORGE_HOME/config.json`):
+Config lives at `~/.skill-forge/config.json` (or `$SKILL_FORGE_HOME/config.json`). Run
+`skill-forge init` to generate it interactively, or write it by hand:
 
 ```json
 {
   "skillsRoots": ["/path/to/.claude/skills"],
   "quarantineDir": "/path/to/quarantine",
-  "strictness": "block-high"
+  "strictness": "block-high",
+  "defaultTarget": "/path/to/.claude/skills",
+  "agents": [{ "id": "claude-code", "skillsRoot": "/path/to/.claude/skills" }],
+  "handoffCommand": ["claude", "-p", "Read {prompt} and follow its instructions for the skill installed at {path}"]
 }
 ```
 
-Missing keys fall back to defaults (`skillsRoots: ["<cwd>/.claude/skills"]`). Full field reference,
+Missing keys fall back to defaults (`skillsRoots: ["<cwd>/.claude/skills"]`); `defaultTarget`,
+`agents`, and `handoffCommand` are optional and only written by `init`. Full field reference,
 including current caveats, in [docs/configuration.md](docs/configuration.md).
 
 ## FAQ
@@ -210,8 +256,10 @@ See [docs/gate-policy.md](docs/gate-policy.md).
 **Is there a license key or activation step?**
 An offline-verified license key exists (`SKILL_FORGE_LICENSE` env var or `config.json`'s
 `licenseKey`), but there's no `license`/`activate` CLI command — you set the key via config or
-environment, not a command. It gates overlap analysis, the provenance ledger, and the
-pending-ingestion queue / `--ingest` handoff. See [docs/pro.md](docs/pro.md) for details.
+environment, not a command. Through the 0.x beta the key doesn't gate anything: overlap analysis,
+the provenance ledger, and the pending-ingestion queue / `--ingest` handoff all run for everyone,
+with a one-line "free during the beta" notice if no valid key is set. See
+[docs/pro.md](docs/pro.md) for details.
 
 ## License