oh-my-workflow 0.1.0 → 0.2.1

package/README.md

@@ -94,6 +94,23 @@ and fix your script. stdout is one result JSON; the `--pretty` tree and a
 (fan-out / verify-vote / pipeline / loop-until-dry), the debug loop, and the
 conventions. That skill is the primary product; this README is the human intro.
 
+## Install the skill (the primary product)
+
+omw's primary product is an **agent-authoring skill** (`skill/SKILL.md`) — it
+teaches a coding agent to write, run, and repair omw workflows. After the package
+is installed, wire the skill into your agent in one step:
+
+```sh
+omw skill install            # → ~/.claude/skills/oh-my-workflow  (Claude Code auto-discovers it)
+omw skill install --project  # → ./.claude/skills/oh-my-workflow  (this repo only)
+omw skill path               # print the bundled SKILL.md path (cat / pipe / point an agent at it)
+```
+
+Then ask your coding agent: *"use oh-my-workflow to <task>"* — it authors a
+`workflow.ts` and runs it with `omw run`. (The skill is Claude-Code-flavored;
+for other hosts use `omw skill path` and feed the file in however that host loads
+context.)
+
 ## Adapters
 
 A node is a coding agent driven through its headless prompt→result CLI.
@@ -101,8 +118,8 @@ A node is a coding agent driven through its headless prompt→result CLI.
 | adapter | status | notes |
 |---|---|---|
 | **fake** | built-in, free, deterministic | the no-key demo engine and test double |
-| **claude** | **full** (live-verified, 2.1.177) | `claude -p --output-format json`; `--resume` powers in-session schema self-repair |
-| **codex** | **experimental** (live-verified, 0.137.0) | `codex exec --json`; **no cost field**; tolerates malformed JSONL ([openai/codex#15451](https://github.com/openai/codex/issues/15451)) and fails *actionably* |
+| **claude** | **full** (live-verified, 2.1.x) | `claude -p --output-format json`; `--resume` powers in-session schema self-repair |
+| **codex** | **experimental** (live-verified, 0.137.x) | `codex exec --json`; **no cost field**; tolerates malformed JSONL ([openai/codex#15451](https://github.com/openai/codex/issues/15451)) and fails *actionably* |
 | **pi** | planned | not wired yet (`--agent pi` → exit 3 + install hint) |
 | **kiro** | not a fit | its CLI is an IDE launcher (open files/diffs), no headless prompt→result interface |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-workflow",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Run coding-agent CLIs (claude -p / codex exec) as nodes in a plain-JS workflow. The thin deterministic glue.",
   "type": "module",
   "author": "Dongwook Kim (https://github.com/domuk-k)",

package/skill/SKILL.md

@@ -34,22 +34,35 @@ bad node never crashes the run.
 single raw LLM API call (that's LangGraph/Mastra territory; an omw node is a
 *whole coding agent*).
 
-## The 30-second free demo (no API key)
+## The 30-second free demo (no API key, nothing to clone)
+
+omw is on npm, so you can run the whole thing in one line — no install step, no
+key, no cost:
+
+```sh
+bunx oh-my-workflow@latest run examples/deep-research --agent fake
+# → {"confirmed":[…],"summary":{…}}    exit 0 · no key · no cost · deterministic
+```
+
+> Tip: use `@latest`. A bare `bunx oh-my-workflow` can serve a stale cached copy.
+
+That single command runs the **whole spine** for you — a fan-out search, a
+pipeline, a scripted schema-fail→self-repair, and a scripted timeout→drop — and
+prints one result JSON. Want to watch it happen? Add `--pretty` for the
+phase/fan-out tree on stderr:
 
 ```sh
-git clone <repo-url> && cd oh-my-workflow   # repo not yet public; fill in the URL
-bun install
-bun src/cli/omw.ts run examples/deep-research --agent fake
-# → {"confirmed":[…],"summary":{…}}     exit 0 · no key · no cost · `--agent fake` is deterministic
+bunx oh-my-workflow@latest run examples/deep-research --agent fake --pretty
 ```
 
-`--agent fake` is a built-in deterministic adapter: it runs the full spine
-(fan-out + pipeline + a scripted schema-fail→self-repair + a scripted
-timeout→drop) and prints one result JSON. Add `--pretty` to see the phase/fan-out
-tree on stderr. Swap `--agent claude` once you've run `claude login`.
+`--agent fake` is a built-in, deterministic adapter — it's the no-key demo engine
+and the test double. When you're ready for real work, run `claude login` once and
+swap `--agent fake` → `--agent claude`. Same script, real nodes.
 
-> Once published this is `bunx oh-my-workflow run …`; today run the bin directly
-> from a clone as shown above.
+> **Reading this as a skill?** You already have it. To install/update it for a
+> coding agent: `bunx oh-my-workflow@latest skill install` (→ `~/.claude/skills/`,
+> or `--project` for one repo); `omw skill path` prints the bundled copy for other
+> hosts. Re-run `skill install` anytime to refresh.
 
 ---
 
@@ -389,8 +402,8 @@ agents that expose such a CLI can be nodes.
 | adapter | status | invoke | structured out | in-session follow-up |
 |---|---|---|---|---|
 | **fake** | built-in, free, deterministic | in-process fixtures | as scripted | yes (fixture) |
-| **claude** | **full** (live-verified, claude 2.1.177) | `claude -p <p> --output-format json` | parse `.result` | `--resume` |
-| **codex** | **experimental** (live-verified, codex 0.137.0) | `codex exec --json -s workspace-write` | last `agent_message` from JSONL | `exec resume` |
+| **claude** | **full** (live-verified, claude 2.1.x) | `claude -p <p> --output-format json` | parse `.result` | `--resume` |
+| **codex** | **experimental** (live-verified, codex 0.137.x) | `codex exec --json -s workspace-write` | last `agent_message` from JSONL | `exec resume` |
 | **pi** | planned | `pi --print` | stdout | — |
 | **kiro** | **not a fit** | — | — | — |
 

package/src/cli/omw.ts

@@ -6,6 +6,7 @@
 import { runCommand } from "./run";
 import { replayCommand } from "./replay";
 import { validateCommand } from "./validate";
+import { skillCommand } from "./skill";
 
 const io = {
   stdout: (s: string) => process.stdout.write(s),
@@ -21,13 +22,16 @@ async function main(argv: string[]): Promise<number> {
       return replayCommand(rest, io);
     case "validate":
       return validateCommand(rest, io);
+    case "skill":
+      return skillCommand(rest, io);
     default:
       io.stderr(
         "usage: omw <command>\n\n" +
           "commands:\n" +
           "  run <workflow> --agent <fake|claude|codex|pi> [--args JSON] [--concurrency N] [--resume <journal.jsonl>] [--pretty]\n" +
           "  replay <journal.jsonl> [--json]\n" +
-          "  validate <workflow> [--json]\n\n" +
+          "  validate <workflow> [--json]\n" +
+          "  skill install [--project]   install the omw authoring skill for your coding agent\n\n" +
           "free demo (no API key):  omw run examples/deep-research --agent fake\n",
       );
       return cmd === undefined ? 2 : 2;

package/src/cli/skill.ts

@@ -0,0 +1,104 @@
+// `omw skill <install|path>` — make "installed npm package" → "active authoring
+// skill" one ergonomic step. The bundled skill/SKILL.md is the primary product:
+// it teaches a coding agent to author, run, and repair omw workflows. `install`
+// copies it into a coding agent's skills dir (auto-discovered by Claude Code);
+// `path` prints the bundled copy's location for piping / pointing an agent at it.
+//
+// fs is reachable directly (this is the IO wiring command, like run.ts); the arg
+// parse is a pure function so the contract is testable without touching disk.
+
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Package root, so the bundled skill resolves whether omw runs from a clone or
+ *  an npm install invoked from any cwd. (Same technique as run.ts's PKG_ROOT.) */
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SKILL_NAME = "oh-my-workflow";
+
+export type SkillIo = {
+  stdout: (s: string) => void;
+  stderr: (s: string) => void;
+  /** Overridable for tests; default to the real environment. */
+  homeDir?: string;
+  cwd?: string;
+  /** Directory holding the bundled SKILL.md; defaults to <pkg>/skill. */
+  skillDir?: string;
+};
+
+export type SkillParse =
+  | { ok: true; sub: "install"; project: boolean }
+  | { ok: true; sub: "path" }
+  | { ok: true; sub: "help" }
+  | { ok: false; error: string };
+
+const USAGE =
+  "usage: omw skill <command>\n\n" +
+  "commands:\n" +
+  "  install [--project]   copy the skill into a skills dir so a coding agent picks it up\n" +
+  "                        (default: ~/.claude/skills/oh-my-workflow; --project: ./.claude/skills/…)\n" +
+  "  path                  print the bundled SKILL.md path (for cat / piping / pointing an agent at it)\n";
+
+export function parseSkillArgs(argv: string[]): SkillParse {
+  const [sub, ...rest] = argv;
+  if (sub === undefined || sub === "help" || sub === "--help" || sub === "-h") {
+    return { ok: true, sub: "help" };
+  }
+  if (sub === "path") {
+    if (rest.length > 0) return { ok: false, error: `unexpected argument: ${rest[0]}` };
+    return { ok: true, sub: "path" };
+  }
+  if (sub === "install") {
+    let project = false;
+    for (const tok of rest) {
+      if (tok === "--project") project = true;
+      else return { ok: false, error: `unexpected argument: ${tok}` };
+    }
+    return { ok: true, sub: "install", project };
+  }
+  return { ok: false, error: `unknown skill subcommand: ${sub}` };
+}
+
+export async function skillCommand(argv: string[], io: SkillIo): Promise<number> {
+  const parsed = parseSkillArgs(argv);
+  if (!parsed.ok) {
+    io.stderr(`${parsed.error}\n\n${USAGE}`);
+    return 2;
+  }
+  if (parsed.sub === "help") {
+    io.stdout(USAGE);
+    return 0;
+  }
+
+  const srcDir = io.skillDir ?? join(PKG_ROOT, "skill");
+  const srcFile = join(srcDir, "SKILL.md");
+  if (!existsSync(srcFile)) {
+    io.stderr(`bundled skill not found at ${srcFile} — reinstall oh-my-workflow?\n`);
+    return 1;
+  }
+
+  if (parsed.sub === "path") {
+    io.stdout(`${srcFile}\n`);
+    return 0;
+  }
+
+  // install — idempotent: copy the whole skill dir (SKILL.md + any bundled
+  // resources) in place, and report installed vs updated.
+  const base = parsed.project ? join(io.cwd ?? process.cwd(), ".claude") : join(io.homeDir ?? homedir(), ".claude");
+  const destDir = join(base, "skills", SKILL_NAME);
+  const dest = join(destDir, "SKILL.md");
+  const updating = existsSync(dest);
+  // Clean replace, not an additive copy: drop a prior install first so a file
+  // that was removed from the bundle doesn't linger as stale content.
+  rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  cpSync(srcDir, destDir, { recursive: true });
+
+  io.stdout(
+    `${updating ? "updated" : "installed"} ${SKILL_NAME} skill → ${dest}\n` +
+      `${parsed.project ? "This project's" : "Claude Code"} agent auto-discovers skills here.\n` +
+      `Next: ask your coding agent to "use oh-my-workflow to <your task>".\n`,
+  );
+  return 0;
+}