plain-forge 1.0.1 → 1.0.2

package/README.md

@@ -19,73 +19,82 @@ Each phase is **incremental**, not a single long questionnaire. plain-forge walk
 
 ## Getting Started
 
-plain-forge ships as a set of skills that plug into your AI coding tool of choice. Install it once, then invoke `forge-plain` (or `add-feature` to add a feature to an existing ***plain project) from any project.
+plain-forge ships as a set of skills, rules, and docs that plug into your AI coding tool of choice. Install it once, then invoke `forge-plain` (or `add-feature` to add a feature to an existing ***plain project) from any project.
 
-### Install with the `skills` CLI (any runtime)
+### Install with `npx plain-forge install` (recommended)
 
-The fastest way to add plain-forge is the `skills` CLI. The `--all` flag installs **every** plain-forge skill at once:
+The primary install path. Works for every supported runtime and is the only installer that ships **all** plain-forge content (skills, rules, **and** docs) — the other methods below are limited or agent-specific.
 
 ```bash
-npx skills add Codeplain-ai/plain-forge --skill '*'
+npx plain-forge install
 ```
 
-#### Install into a specific runtime
-
-If you only use one runtime, pass `--agent` to target just that one (you can repeat the flag to pick several):
+This prompts you to pick an agent and a scope using an arrow-key menu. You can also pass both flags non-interactively:
 
 ```bash
-# Just Claude Code
-npx skills add Codeplain-ai/plain-forge --skill '*' --agent claude-code
+npx plain-forge install --agent claude --scope project
+```
+
+**Agent options:**
+
+| `--agent` | Installs into | Use when |
+|-----------|---------------|----------|
+| `claude` | `.claude/` | You use Claude Code |
+| `codex` | `.codex/` | You use the OpenAI Codex CLI |
+| `forgecode` | `.forgecode/` | You use ForgeCode |
+| `universal` | `.agents/` | You want a runtime-neutral layout that any agent reading from `.agents/` can pick up |
 
-# Just Codex
-npx skills add Codeplain-ai/plain-forge --skill '*' --agent codex
+**Scope options:**
 
-# Just OpenCode
-npx skills add Codeplain-ai/plain-forge --skill '*' --agent opencode
+| `--scope` | Installs into | Use when |
+|-----------|---------------|----------|
+| `project` | `./<agent-dir>/` in the current working directory | You want plain-forge in just this project |
+| `global` | `~/<agent-dir>/` in your home directory | You want plain-forge available in every project on the machine |
 
-# Any combination, non-interactive
-npx skills add Codeplain-ai/plain-forge --skill '*' --agent opencode --agent codex --agent claude-code
+Each install writes three subfolders under the chosen directory:
+
+```
+<agent-dir>/
+  skills/    # every plain-forge skill
+  rules/     # spec-writing rules (loaded as workspace instructions)
+  docs/      # shared reference docs
 ```
 
-If you'd rather use the native install flow for a specific runtime, the per-tool instructions below still work.
+Re-running `npx plain-forge install` overwrites the destination silently, so it doubles as the upgrade path — `npx plain-forge@latest install` pulls the newest release every time.
 
-### Install in Claude Code
+### Alternative install paths (skills only — no rules or docs)
 
-Requires the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured. Inside any Claude Code session, run the following **three commands**, one after the other (copy and paste each one separately):
+These work but only install the skill files. Rules and docs do **not** travel with them, so use them only if you have a reason not to use `npx plain-forge install`.
 
-**1.** Register this repository as a plugin marketplace:
+#### `npx skills` CLI
 
-```text
-/plugin marketplace add Codeplain-ai/plain-forge
+```bash
+npx skills add Codeplain-ai/plain-forge --skill '*' --agent claude-code
 ```
 
-**2.** Install the `plain-forge` plugin from it:
+Replace `--agent claude-code` with `codex` or `opencode` to target a different runtime, or repeat the flag for several at once.
 
-```text
-/plugin install plain-forge@plain-forge
-```
+#### Claude Code native plugin flow
 
-**3.** Reload plugins so Claude Code picks up the newly installed skills:
+Requires the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). Inside a Claude Code session, run the following **three commands** one after the other:
 
 ```text
+/plugin marketplace add Codeplain-ai/plain-forge
+/plugin install plain-forge@plain-forge
 /reload-plugins
 ```
 
-Without the reload, the plain-forge skills won't be visible in the current session even though the install succeeded. Once all three commands have run, all plain-forge skills become available.
+Without the reload the skills won't appear in the current session.
 
-### Install in Codex
+#### Codex native plugin flow
 
-Requires the [OpenAI Codex CLI](https://developers.openai.com/codex/cli/reference) installed and signed in. Installation is **two steps**, but only the first one is a shell command:
-
-**1.** From your shell, register this repository as a Codex marketplace:
+Requires the [OpenAI Codex CLI](https://developers.openai.com/codex/cli/reference). From your shell:
 
 ```bash
 codex plugin marketplace add Codeplain-ai/plain-forge
 ```
 
-**2.** Inside Codex, open the plugin directory, pick the `plain-forge` marketplace, and install the plugin from there. (The Codex CLI does not currently expose a `codex plugin install` equivalent — installation has to be triggered from the in-app plugin directory.)
-
-Once the plugin is installed, all plain-forge skills become available in your Codex sessions.
+Then, inside Codex, open the plugin directory, pick the `plain-forge` marketplace, and install the plugin from there. (Codex's CLI does not currently expose a `codex plugin install` equivalent.)
 
 ## Usage
 

package/bin/cli.mjs

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import readline from "node:readline/promises";
+import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -23,49 +23,96 @@ function usage() {
 Options:
   --agent <claude|codex|forgecode|universal>   Target agent layout
   --scope <project|global>                     Install into cwd or $HOME
-  --skill <name>                               Install only the named skill (repeatable; default: all)
   -h, --help                                   Show this help
 
 Examples:
   plain-forge install --agent claude --scope project
   plain-forge install --agent universal --scope global
-  plain-forge install --agent claude --skill add-functional-spec --skill add-concept
 
 Missing flags are prompted interactively.`);
 }
 
 function parseArgs(argv) {
-  const out = { _: [], skills: [] };
+  const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--agent") out.agent = argv[++i];
     else if (a === "--scope") out.scope = argv[++i];
-    else if (a === "--skill") out.skills.push(argv[++i]);
     else if (a === "-h" || a === "--help") out.help = true;
     else out._.push(a);
   }
   return out;
 }
 
-async function promptChoice(question, choices) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    while (true) {
-      const ans = (await rl.question(`${question} [${choices.join("/")}]: `)).trim().toLowerCase();
-      if (choices.includes(ans)) return ans;
-      console.log(`  please answer one of: ${choices.join(", ")}`);
-    }
-  } finally {
-    rl.close();
+function promptChoice(question, choices) {
+  const input = process.stdin;
+  const output = process.stdout;
+  if (!input.isTTY) {
+    return Promise.reject(
+      new Error(
+        `cannot prompt for "${question}" — stdin is not a TTY. Pass the value as a flag instead.`,
+      ),
+    );
   }
+
+  return new Promise((resolve, reject) => {
+    let index = 0;
+    let rendered = 0;
+
+    const render = () => {
+      if (rendered > 0) {
+        readline.moveCursor(output, 0, -rendered);
+        readline.clearScreenDown(output);
+      }
+      output.write(`? ${question} (use arrow keys, enter to select)\n`);
+      for (let i = 0; i < choices.length; i++) {
+        const pointer = i === index ? "\x1b[36m>\x1b[0m" : " ";
+        const label = i === index ? `\x1b[36m${choices[i]}\x1b[0m` : choices[i];
+        output.write(`  ${pointer} ${label}\n`);
+      }
+      rendered = choices.length + 1;
+    };
+
+    const cleanup = () => {
+      input.removeListener("keypress", onKey);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\x1b[?25h"); // show cursor
+    };
+
+    const onKey = (_str, key) => {
+      if (!key) return;
+      if (key.name === "up" || (key.ctrl && key.name === "p")) {
+        index = (index - 1 + choices.length) % choices.length;
+        render();
+      } else if (key.name === "down" || (key.ctrl && key.name === "n")) {
+        index = (index + 1) % choices.length;
+        render();
+      } else if (key.name === "return") {
+        cleanup();
+        output.write(`  \x1b[32m${choices[index]}\x1b[0m\n`);
+        resolve(choices[index]);
+      } else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+        cleanup();
+        output.write("\n");
+        reject(new Error("cancelled"));
+      }
+    };
+
+    readline.emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    output.write("\x1b[?25l"); // hide cursor
+    input.on("keypress", onKey);
+    render();
+  });
 }
 
-function copyTree(srcDir, destDir, filterNames) {
+function copyTree(srcDir, destDir) {
   if (!fs.existsSync(srcDir)) return 0;
   fs.mkdirSync(destDir, { recursive: true });
   let count = 0;
   for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    if (filterNames && !filterNames.has(entry.name)) continue;
     const src = path.join(srcDir, entry.name);
     const dest = path.join(destDir, entry.name);
     if (entry.isDirectory()) {
@@ -82,7 +129,9 @@ async function cmdInstall(args) {
   let agent = args.agent;
   if (!agent) agent = await promptChoice("Which agent?", Object.keys(AGENTS));
   if (!Object.hasOwn(AGENTS, agent)) {
-    console.error(`unknown agent "${agent}". valid: ${Object.keys(AGENTS).join(", ")}`);
+    console.error(
+      `unknown agent "${agent}". valid: ${Object.keys(AGENTS).join(", ")}`,
+    );
     process.exit(2);
   }
 
@@ -96,22 +145,18 @@ async function cmdInstall(args) {
   const root = scope === "global" ? os.homedir() : process.cwd();
   const baseDir = path.join(root, AGENTS[agent]);
 
-  const explicit = args.skills.filter((s) => s !== "*");
-  const skillFilter = explicit.length ? new Set(explicit) : null;
-
-  const skillsSrc = path.join(forgeDir, "skills");
-  if (skillFilter) {
-    for (const name of skillFilter) {
-      if (!fs.existsSync(path.join(skillsSrc, name))) {
-        console.error(`skill "${name}" not found under ${skillsSrc}`);
-        process.exit(2);
-      }
-    }
-  }
-
-  const skillsCount = copyTree(skillsSrc, path.join(baseDir, "skills"), skillFilter);
-  const rulesCount = copyTree(path.join(forgeDir, "rules"), path.join(baseDir, "rules"), null);
-  const docsCount = copyTree(path.join(forgeDir, "docs"), path.join(baseDir, "docs"), null);
+  const skillsCount = copyTree(
+    path.join(forgeDir, "skills"),
+    path.join(baseDir, "skills"),
+  );
+  const rulesCount = copyTree(
+    path.join(forgeDir, "rules"),
+    path.join(baseDir, "rules"),
+  );
+  const docsCount = copyTree(
+    path.join(forgeDir, "docs"),
+    path.join(baseDir, "docs"),
+  );
 
   console.log(`installed into ${baseDir}`);
   console.log(`  skills: ${skillsCount}`);
@@ -138,6 +183,9 @@ async function main() {
 }
 
 main().catch((err) => {
-  console.error(err instanceof Error ? err.stack ?? err.message : err);
+  if (err instanceof Error && err.message === "cancelled") {
+    process.exit(130);
+  }
+  console.error(err instanceof Error ? (err.stack ?? err.message) : err);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {