@eric0117/agentforge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric0117
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# agentforge
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/68277906-3c7f-442e-a68d-2ab2631698ab" width="720" alt="agentforge" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@eric0117/agentforge"><img src="https://img.shields.io/npm/v/@eric0117/agentforge.svg?style=flat-square" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@eric0117/agentforge"><img src="https://img.shields.io/npm/dm/@eric0117/agentforge.svg?style=flat-square" alt="npm downloads" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@eric0117/agentforge.svg?style=flat-square" alt="license" /></a>
+  <img src="https://img.shields.io/node/v/@eric0117/agentforge.svg?style=flat-square" alt="node" />
+</p>
+
+> Multi-repo workspace bootstrapper for **Claude Code**, **Cursor**, and **OpenAI Codex CLI**.
+
+**You're a developer. You don't work on one thing at a time. And when you do, it never lives in one repo.**
+
+A bug fix touches the API and the admin panel. A feature ships PRs across three services. Tomorrow you're back on yesterday's work — and a teammate just edited the same files.
+
+`agentforge` makes that the default workflow — not the chaos. One feature = one slug = a git worktree per repo, side by side on disk. Multiple features in flight, each with its own AI session. Skills triggered by natural language — no commands to memorize. Finished work archived with enough context that next month's "how did we handle X?" returns a real answer.
+
+It does **not** ship its own AI runtime — bring your own Claude Code / Cursor / Codex CLI.
+
+---
+
+## Why
+
+Working across several repos at once is painful with a single AI agent:
+
+- Your session is rooted in one repo, but the change touches three.
+- You lose context when you switch terminals to a different repo.
+- Parallel features step on each other's branches.
+- "How did we solve this last time?" disappears the moment a PR is merged.
+
+agentforge gives you a flat directory layout where every feature has its own per-repo git worktrees, every AI agent gets the same set of skills (in the same language), and finished work is archived with enough metadata to be queried later.
+
+---
+
+## Quick start
+
+```bash
+# Install (scoped package — command on PATH is still `agentforge`)
+npm install -g @eric0117/agentforge
+
+# Bootstrap a workspace — interactive prompts walk you through
+# language (en / ko / ja) and which agents to install (Claude / Cursor / Codex)
+mkdir my-workspace && cd my-workspace
+agentforge init
+```
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/0eb690b2-afaf-475e-85f2-5ef33a99b118" width="720" alt="agentforge init — interactive prompts" />
+</p>
+
+```bash
+# Clone your repos into repos/
+git clone https://github.com/your-org/backend-api.git repos/backend-api
+git clone https://github.com/your-org/admin-web.git repos/admin-web
+
+# Start working — open the AI CLI of your choice from the workspace root
+claude        # or: cursor . / codex
+```
+
+> Prefer non-interactive? `agentforge init . --agent all --lang en --yes` skips every prompt.
+
+From inside the session, describe what you want in natural language. agentforge skills pick the right action — no command memorization needed:
+
+> "Let's start a new feature: tighten the rate limit"
+
+→ `agentforge-feature-start` proposes a slug, asks which repos are in scope, creates worktrees under `anvil/<slug>/<repo>/`, and (in Claude Code) dispatches a background session you can switch to with `←`.
+
+---
+
+## Directory layout
+
+```
+my-workspace/
+├── repos/                       # main branch of each repo (read-only / explore)
+│   ├── backend-api/
+│   └── admin-web/
+├── anvil/                       # IN-PROGRESS features only
+│   └── <slug>/                  # e.g. 260524-feat-rate-limit
+│       ├── backend-api/         # git worktree on a feature branch
+│       ├── admin-web/           # git worktree on a feature branch
+│       └── CLAUDE.md            # feature description + context + repo list
+├── artifacts/                   # closed features, by completion date
+│   └── 20260524/
+│       └── <slug>/
+│           ├── CLAUDE.md        # moved here at retro time
+│           ├── RETRO.md         # retrospective
+│           ├── refs.json        # per-repo branch / HEAD / PR pointers
+│           ├── plans/           # plan files
+│           └── sessions/        # AI session transcripts
+├── agentforge/                  # workspace metadata
+│   ├── config.json              # which agents, which language
+│   ├── skills/                  # master skill files (single source of truth)
+│   └── log.jsonl                # append-only activity log
+└── .claude/skills/              # per-agent skill copies (auto-generated)
+    .cursor/rules/
+    .agents/skills/              # codex
+```
+
+The filesystem is the source of truth — there is no separate metadata file to drift. `ls anvil/` shows what's in flight; `ls artifacts/` shows what's done.
+
+---
+
+## How a feature flows
+
+| Step | What you say | Skill that fires |
+|---|---|---|
+| 1. Question / explore | "Where is the auth handler in the backend API?" | `agentforge-project-router` |
+| 2. Discover something to change | "Let's fix this — start a feature" | `agentforge-feature-start` |
+| 3. (Optional) plan the work | "How should we split this?" | (any agent — plan it together) |
+| 4. Implement | (regular coding in the dispatched session) | — |
+| 5. Check blast radius before merging | "Where else is `X` used?" | `agentforge-cross-repo-impact` |
+| 6. Pre-merge ops sanity check | "Anything ops needs before I ship?" | `agentforge-pre-deploy-check` |
+| 7. Open PRs for the feature | "Open PRs for this feature" | `agentforge-pr-create` |
+| 8. Plan the merge / deploy order | "Which PR first?" | `agentforge-release-coordinate` |
+| 9. Audit review comments | "What do we need to fix from the review?" | `agentforge-pr-review-analyze` |
+| 10. Hand off mid-flight (optional) | "I'm going on vacation — package this up" | `agentforge-context-handoff` |
+| 11. Close the feature | "We're done — write a retro" | `agentforge-feature-retro` |
+
+You don't have to remember the skill names — they're triggered by natural language, in English / 한국어 / 日本語.
+
+---
+
+## Skills
+
+All skills live in `agentforge/skills/` (master) and are auto-propagated to every installed agent (`.claude/skills/`, `.cursor/rules/`, `.agents/skills/`) by `agentforge sync-skills`.
+
+| Skill | What it does |
+|---|---|
+| `agentforge-project-router` | Routes a natural-language question to the right `repos/<name>/`. |
+| `agentforge-feature-start` | Creates per-repo git worktrees for a new feature; re-runnable to add repos to an existing one. Detects per-repo branch-naming conventions from history. |
+| `agentforge-cross-repo-impact` | Traces the blast radius of a change across every repo in the workspace. |
+| `agentforge-pre-deploy-check` | Surfaces non-code changes (migrations, env vars, cache keys, queue contracts, infra files) that ops needs to handle before merge. Read-only. |
+| `agentforge-pr-create` | Opens one PR per repo for a feature; cross-links the PRs. Never force-pushes, never merges. |
+| `agentforge-pr-review-analyze` | Pulls every review thread, verifies each against the live code, returns a prioritized action list. |
+| `agentforge-release-coordinate` | Plans the multi-repo merge / deploy order with preconditions, wait conditions, and a reverse-order rollback playbook. Read-only. |
+| `agentforge-context-handoff` | Packages a feature's current state into `HANDOFF.md` so another developer (or future-you) can pick up without context loss. |
+| `agentforge-feature-retro` | Closes a feature: writes the retrospective, archives session logs and PR refs into `artifacts/`, removes worktrees, cleans up. |
+| `agentforge-incident-context` | First-responder context for a production page: searches every repo for the alert clue, names recent committers, traces the call path. Read-only. |
+| `agentforge-history` | Queries past features — "how did we handle X last time?", "which feature added Y?", with grounded file / commit / PR references. Read-only. |
+
+Every skill that modifies state asks before destructive operations and writes activity to `agentforge/log.jsonl`.
+
+You can also add **your own** skills (`agentforge add-skill`) — they get propagated to every agent the same way.
+
+---
+
+## CLI reference
+
+```
+agentforge init [path]                       # bootstrap a workspace
+agentforge add-agent [agents] [path]         # add Claude / Cursor / Codex to an existing workspace
+agentforge remove-agent <agent> [path]
+agentforge list-skills [path]                # show all installed skills
+agentforge add-skill [path]                  # author a new skill
+agentforge remove-skill <name> [path]
+agentforge sync-skills [path]                # propagate master skill edits to every agent
+agentforge enter [slug]                      # cd into a feature worktree + launch claude
+agentforge rename <old-slug> <new-slug>      # rename a feature (worktrees, branch, CLAUDE.md)
+agentforge doctor [path]                     # diagnose a workspace
+agentforge help
+```
+
+Flags:
+- `--force` — overwrite per-agent files (always backs up to `.bak` first).
+- `--yes` — non-interactive; assume yes on confirmation prompts.
+- `--lang en|ko|ja` — language for skill bodies.
+- `--agent claude,cursor,codex` or `--agent all` — which agents to scaffold for.
+
+---
+
+## Multi-agent support
+
+agentforge writes the same skill set into the file layout each AI CLI expects:
+
+| Agent | Skill location | Workspace guide |
+|---|---|---|
+| **Claude Code** | `.claude/skills/<id>/SKILL.md` | `CLAUDE.md` |
+| **Cursor** | `.cursor/rules/<id>.mdc` | `.cursor/rules/CLAUDE.mdc` |
+| **OpenAI Codex CLI** | `.agents/skills/<id>.md` | `AGENTS.md` |
+
+Edit a file in `agentforge/skills/` and run `agentforge sync-skills` — every agent picks up the change with the previous version backed up to `.bak`.
+
+### How skills flow
+
+```
+   User runs:                         Source of truth:
+   ─────────────                      ─────────────────
+   agentforge add-skill    ─────→     agentforge/skills/<id>.md
+                                              │
+   agentforge sync-skills  ─────→             │  (renders the template into
+                                              │   each agent's expected layout)
+                                              ▼
+                            ┌─────────────────┼─────────────────┐
+                            ▼                 ▼                 ▼
+                     .claude/skills/    .cursor/rules/    .agents/skills/
+                      (Claude Code)        (Cursor)        (Codex CLI)
+```
+
+The master copy in `agentforge/skills/` is the **single source of truth**. The per-agent
+files are regenerated from it — never edit them directly; your changes will be
+overwritten on the next `sync-skills`.
+
+---
+
+## Internationalization
+
+Skills are stored as templates with a `{{OUTPUT_LANGUAGE_INSTRUCTION}}` placeholder. The workspace's `agentforge/config.json` `lang` field decides which language is baked in at install time (`en` / `ko` / `ja`). Switch languages by re-running `agentforge init --force-skills --lang <code>` — your master files in `agentforge/skills/` are preserved.
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- `git` ≥ 2.20 (for `git worktree`)
+- `gh` (GitHub CLI) — only for PR-related skills (`pr-create`, `pr-review-analyze`, `release-coordinate`)
+- The AI CLI of your choice (Claude Code, Cursor, or Codex CLI) — for skill invocation
+- Optional: `jq` — speeds up the activity log writer; the skills fall back to hand-built JSON if missing
+
+---
+
+## Conventions
+
+- `repos/<name>/` is **read-only** — no code edits there. Use `agentforge-feature-start` to spawn a worktree.
+- One feature = one slug = one directory under `anvil/` (and later `artifacts/<date>/`).
+- Slug format: `<YYMMDD>-<kind>-<core>` where `<kind>` is `feat` / `fix` / `refactor` / `chore`.
+- Branch names per repo follow each repo's own convention, detected from recent branches at feature-start time. They may differ from the slug.
+- `anvil/` only contains in-progress work. Completed features move to `artifacts/<YYYYMMDD>/<slug>/`.
+
+---
+
+## FAQ
+
+**Do I need Claude Code?**
+No. agentforge ships skills for Claude Code, Cursor, and OpenAI Codex CLI — pick one or install all three with `--agent all`. Skills are plain markdown rendered into each agent's expected layout.
+
+**I edited a skill, but my AI session doesn't seem to use the new version.**
+Skill files load at AI session startup. After `agentforge sync-skills` (or any edit to a master file), restart your AI CLI session — the in-memory copy in the running session won't pick up file changes.
+
+**My `.claude/skills/<id>/` is filling up with `SKILL.md.bak.N` files. Is that normal?**
+Yes — `sync-skills` always backs up the previous version before overwriting. Safe to clean up periodically:
+```bash
+find .claude/skills .cursor/rules .agents/skills -name "*.bak*" -delete
+```
+
+**Can I use this alongside Nx / Turborepo / Lerna / Bazel?**
+Yes — they're orthogonal. agentforge structures the **dev workflow** (per-feature worktrees, skill triggers, archives). Monorepo build tools structure the **build graph**. Use both.
+
+**Why git worktrees instead of just branches?**
+With worktrees, every feature is a separate working directory on disk. You can have one AI session open per feature, working in parallel without `git stash` / branch-switching dances. Each worktree has its own `node_modules` / build output if needed.
+
+**Branch name per repo isn't the slug — why?**
+Each repo can follow its own convention (`feature/<TICKET>-<topic>`, `feat/<slug>`, `<user>/<topic>`). `agentforge-feature-start` samples recent branches per repo to detect the pattern, then proposes a branch name that fits — the slug just names the worktree directory.
+
+**How do I write my own skill?**
+Run `agentforge add-skill` from inside the workspace — it scaffolds a master file under `agentforge/skills/<id>.md`, optionally seeded from `--from <file>`. Edit the markdown, then `agentforge sync-skills`. Existing skills in `agentforge/skills/` are good references for structure (frontmatter + body + `## Output language` block).
+
+**Windows support?**
+agentforge itself is plain Node.js and works on Windows. `git worktree` works on Windows too, but long path edge cases and shell-script-style command examples in some skills may surface issues — file an issue if you hit one.
+
+---
+
+## Contributing
+
+Architecture, build flow, and skill-author conventions live in [`CLAUDE.md`](./CLAUDE.md) — read that before opening a PR. Issues and pull requests welcome.
+
+---
+
+## License
+
+MIT.
+

package/dist/add-agent.js

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pickAgents } from "./agent-prompt.js";
+import { readMasterDir } from "./agents/io.js";
+import { AGENTS, getAgent } from "./agents/index.js";
+import { masterDir, readConfig, upsertConfig, } from "./agentforge-config.js";
+import { pickLanguage } from "./lang-prompt.js";
+import { SKILLS } from "./skills-data.js";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+export async function runAddAgent(opts) {
+    const root = resolve(opts.pathArg ?? process.cwd());
+    if (!isAgentforgeWorkspace(root)) {
+        process.stderr.write(`\n${YELLOW}⚠${RESET} Not an agentforge workspace yet.\n` +
+            `  ${DIM}${root}${RESET}\n\n` +
+            `  Run ${CYAN}agentforge init${RESET} here first to set one up.\n\n`);
+        process.exit(1);
+    }
+    // master must exist before we can install adapters from it
+    if (!existsSync(masterDir(root))) {
+        process.stderr.write(`\n${YELLOW}⚠${RESET} No master skills directory at ${DIM}${masterDir(root)}${RESET}\n\n` +
+            `  Run ${CYAN}agentforge init${RESET} here first to set up the workspace.\n\n`);
+        process.exit(1);
+    }
+    const cfg = readConfig(root);
+    // If user passed --lang and it conflicts with what's already written into
+    // master files, we'd silently produce a mixed-lang workspace (new agent's
+    // CLAUDE.md/.cursorrules/AGENTS.md in --lang, but the actual skill files
+    // copied from master in the original lang). Refuse and point at the
+    // re-init path.
+    if (opts.lang && cfg?.lang && opts.lang !== cfg.lang) {
+        process.stderr.write(`\n${YELLOW}⚠${RESET} workspace was initialized with ${BOLD}lang=${cfg.lang}${RESET}, ` +
+            `you passed ${BOLD}--lang ${opts.lang}${RESET}.\n\n` +
+            `  Master skills are already in ${cfg.lang} — mixing langs would produce inconsistent output.\n` +
+            `  To switch the whole workspace to ${opts.lang}: ${CYAN}agentforge init ${root} --lang ${opts.lang} --force-skills${RESET}\n` +
+            `  To keep ${cfg.lang}: drop the ${CYAN}--lang${RESET} flag.\n\n`);
+        process.exit(1);
+    }
+    const installed = new Set(cfg?.agents ?? Array.from(detectInstalledAgentsFallback(root)));
+    const lang = await resolveLanguage(opts, cfg?.lang);
+    const agentsToAdd = await resolveAgentList(opts, installed, lang, root);
+    if (agentsToAdd.length === 0) {
+        console.log(`${YELLOW}no agents selected — nothing to do.${RESET}`);
+        return;
+    }
+    const { skills: masterSkills, skipped } = readMasterDir(masterDir(root));
+    if (skipped.length > 0) {
+        for (const sk of skipped) {
+            console.log(`  ${DIM}skipped master file ${sk.file} — ${sk.reason}${RESET}`);
+        }
+    }
+    console.log("");
+    console.log(`${BOLD}${GREEN}+${RESET} adding agents to ${CYAN}${root}${RESET}`);
+    console.log("");
+    for (const id of agentsToAdd) {
+        const adapter = getAgent(id);
+        console.log(`${BOLD}${CYAN}▸ ${adapter.label}${RESET}`);
+        adapter.install({
+            root,
+            masterSkills,
+            skillCatalog: SKILLS.slice(),
+            lang,
+            forceSkills: opts.forceSkills,
+            forceClaude: opts.forceClaude,
+        });
+        console.log("");
+    }
+    // update config.agents (union)
+    upsertConfig(root, { agents: [...installed, ...agentsToAdd] });
+    printNextSteps(root, agentsToAdd);
+}
+async function resolveLanguage(opts, configLang) {
+    if (opts.lang)
+        return opts.lang;
+    if (configLang)
+        return configLang; // honor what's already in config
+    if (opts.yes)
+        return "en";
+    return pickLanguage();
+}
+async function resolveAgentList(opts, installed, lang, root) {
+    if (opts.agents && opts.agents.length > 0) {
+        const dup = opts.agents.filter((id) => installed.has(id));
+        if (dup.length > 0) {
+            console.log(`${DIM}  note: already installed → skipping: ${dup.join(", ")}${RESET}`);
+        }
+        return opts.agents.filter((id) => !installed.has(id));
+    }
+    if (opts.yes) {
+        const remaining = AGENTS.map((a) => a.id).filter((id) => !installed.has(id));
+        if (remaining.length === 0) {
+            console.log(`${YELLOW}all known agents are already installed in ${root}.${RESET}`);
+        }
+        return remaining;
+    }
+    if (installed.size === AGENTS.length) {
+        console.log(`${YELLOW}all known agents are already installed in ${root}.${RESET}`);
+        return [];
+    }
+    return pickAgents(lang, {
+        disabled: installed,
+        headerLabel: "Agents to add",
+    });
+}
+/** fallback when config.json doesn't exist yet — same logic as before */
+function detectInstalledAgentsFallback(root) {
+    const installed = new Set();
+    if (existsSync(join(root, ".claude/skills")) ||
+        existsSync(join(root, "CLAUDE.md")))
+        installed.add("claude");
+    if (existsSync(join(root, ".cursor/rules")) ||
+        existsSync(join(root, ".cursorrules")))
+        installed.add("cursor");
+    if (existsSync(join(root, ".agents/skills")) ||
+        existsSync(join(root, "AGENTS.md")))
+        installed.add("codex");
+    return installed;
+}
+function isAgentforgeWorkspace(root) {
+    const markers = [
+        "agentforge",
+        "repos",
+        "anvil",
+        "artifacts",
+        ".claude",
+        ".cursor",
+        ".agents",
+        "CLAUDE.md",
+        "AGENTS.md",
+        ".cursorrules",
+    ];
+    return markers.some((m) => existsSync(join(root, m)));
+}
+function printNextSteps(root, agentIds) {
+    const labels = agentIds
+        .map((id) => AGENTS.find((a) => a.id === id)?.label ?? id)
+        .join(", ");
+    console.log(`${BOLD}${GREEN}✓${RESET} added: ${labels}  ${DIM}(in ${root})${RESET}`);
+    console.log("");
+}

package/dist/add-skill.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import * as readline from "node:readline/promises";
+import { splitFrontmatter } from "./agents/io.js";
+import { confirm } from "./confirm.js";
+import { masterDir, requireWorkspace } from "./agentforge-config.js";
+import { LANG_INSTRUCTIONS } from "./skills-data.js";
+import { runSyncSkills } from "./sync-skills.js";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+export async function runAddSkill(opts) {
+    const root = resolve(opts.pathArg ?? process.cwd());
+    const cfg = requireWorkspace(root);
+    if (opts.fromFile) {
+        await addFromFile(root, opts.fromFile);
+    }
+    else {
+        await addInteractive(root, cfg.lang, opts.noEdit, opts.yes);
+    }
+    if (!opts.noEdit) {
+        console.log("");
+        console.log(`${BOLD}${CYAN}↻${RESET} propagating to agents...`);
+        // adding a skill changes root-level skill indexes (e.g. AGENTS.md Skills
+        // section), so we ask for a root-guide refresh as well.
+        await runSyncSkills({
+            pathArg: root,
+            forceSkills: false,
+            forceClaude: true,
+        });
+    }
+    else {
+        console.log("");
+        console.log(`${DIM}master file ready. Edit it, then run \`agentforge sync-skills\` to propagate.${RESET}`);
+    }
+}
+async function addFromFile(root, fromFile) {
+    const src = resolve(fromFile);
+    if (!existsSync(src)) {
+        process.stderr.write(`\n${RED}✗${RESET} Source file not found.\n  ${DIM}${src}${RESET}\n\n`);
+        process.exit(1);
+    }
+    if (!statSync(src).isFile()) {
+        process.stderr.write(`\n${RED}✗${RESET} ${DIM}${src}${RESET} is not a regular file.\n  ${DIM}--from expects a .md file path${RESET}\n\n`);
+        process.exit(1);
+    }
+    const content = readFileSync(src, "utf8");
+    const { frontmatter } = splitFrontmatter(content);
+    const name = frontmatter["name"];
+    if (!name || !frontmatter["description"]) {
+        process.stderr.write(`\n${RED}✗${RESET} Missing required frontmatter in ${DIM}${src}${RESET}\n\n` +
+            `  The file needs a frontmatter block at the top:\n` +
+            `    ${DIM}---${RESET}\n` +
+            `    ${CYAN}name:${RESET} my-skill\n` +
+            `    ${CYAN}description:${RESET} One-line summary of what this skill does.\n` +
+            `    ${DIM}---${RESET}\n\n`);
+        process.exit(1);
+    }
+    if (!isValidSkillName(name)) {
+        process.stderr.write(`\n${RED}✗${RESET} Invalid skill name: "${name}"\n\n` +
+            `  Use kebab-case: letters, digits, hyphens. Must start with a letter.\n` +
+            `  ${DIM}Example: my-debug-helper${RESET}\n\n`);
+        process.exit(1);
+    }
+    const dst = join(masterDir(root), `${name}.md`);
+    if (existsSync(dst)) {
+        process.stderr.write(`\n${RED}✗${RESET} Skill "${name}" already exists.\n  ${DIM}${dst}${RESET}\n\n` +
+            `  Run ${CYAN}agentforge remove-skill ${name}${RESET} to remove it, or choose a different name.\n\n`);
+        process.exit(1);
+    }
+    mkdirSync(masterDir(root), { recursive: true });
+    copyFileSync(src, dst);
+    console.log(`${GREEN}+${RESET} added master skill: ${name}  ${DIM}(from ${src})${RESET}`);
+}
+async function addInteractive(root, lang, noEdit, yes) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    let name = "";
+    while (true) {
+        name = (await rl.question(`${CYAN}?${RESET} ${BOLD}Skill name${RESET} ${DIM}(kebab-case, e.g. my-debug-helper)${RESET} `)).trim();
+        if (!isValidSkillName(name)) {
+            console.log(`  ${RED}invalid name.${RESET} ${DIM}letters/digits/hyphens, must start with a letter.${RESET}`);
+            continue;
+        }
+        if (existsSync(join(masterDir(root), `${name}.md`))) {
+            console.log(`  ${RED}already exists:${RESET} ${name}`);
+            continue;
+        }
+        break;
+    }
+    const description = (await rl.question(`${CYAN}?${RESET} ${BOLD}Description${RESET} ${DIM}(one line — what this skill does)${RESET}\n${DIM}›${RESET} `)).trim();
+    if (description === "") {
+        rl.close();
+        process.stderr.write(`\n${RED}✗${RESET} Description is required — it's how agents decide when to use this skill.\n\n`);
+        process.exit(1);
+    }
+    rl.close();
+    // build placeholder body
+    const body = buildPlaceholderBody(name, description, lang);
+    const dst = join(masterDir(root), `${name}.md`);
+    mkdirSync(dirname(dst), { recursive: true });
+    writeFileSync(dst, body);
+    console.log(`${GREEN}+${RESET} wrote master file: agentforge/skills/${name}.md`);
+    if (noEdit)
+        return;
+    const openEditor = yes || (await confirm("Open this skill in $EDITOR now?", true));
+    if (!openEditor)
+        return;
+    await openInEditor(dst);
+}
+function isValidSkillName(name) {
+    return /^[a-z][a-z0-9-]*$/.test(name);
+}
+function buildPlaceholderBody(name, description, lang) {
+    return `---
+name: ${name}
+description: ${description}
+---
+
+# ${name}
+
+<!-- Write your skill instructions here. -->
+<!-- When the user's request matches the description above, this content -->
+<!-- becomes the agent's playbook for the response. -->
+
+## When to apply
+
+<!-- describe trigger conditions -->
+
+## How to do it
+
+<!-- step-by-step procedure -->
+
+## Rules
+
+<!-- constraints, safety, do/don't -->
+
+## Output language
+
+${LANG_INSTRUCTIONS[lang]}
+`;
+}
+async function openInEditor(path) {
+    const editor = process.env.VISUAL ||
+        process.env.EDITOR ||
+        (await firstAvailable(["nano", "vim", "vi"]));
+    if (!editor) {
+        console.log(`${YELLOW}no $VISUAL/$EDITOR set and no fallback editor (nano/vim/vi) found.${RESET}`);
+        console.log(`  ${DIM}Edit the file manually: ${path}${RESET}`);
+        return;
+    }
+    // split editor string in case it has args (e.g. "code -w")
+    const parts = editor.split(/\s+/).filter(Boolean);
+    const cmd = parts[0];
+    const args = [...parts.slice(1), path];
+    await new Promise((resolveProm, rejectProm) => {
+        const child = spawn(cmd, args, { stdio: "inherit" });
+        child.on("error", rejectProm);
+        child.on("exit", (code) => {
+            if (code === 0 || code === null)
+                resolveProm();
+            else
+                rejectProm(new Error(`editor exited with code ${code}`));
+        });
+    });
+}
+async function firstAvailable(cmds) {
+    for (const c of cmds) {
+        const ok = await new Promise((res) => {
+            const child = spawn("which", [c], { stdio: "ignore" });
+            child.on("exit", (code) => res(code === 0));
+            child.on("error", () => res(false));
+        });
+        if (ok)
+            return c;
+    }
+    return null;
+}