@oomerevren/tryforge 0.1.2 → 0.1.3

package/README.md

@@ -1,107 +1,54 @@
-# Forge — The Homebrew for AI Agents
+# Forge — The Universal Package Manager for AI Agent Context, Skills & MCPs
+
+> **Stop manually copying `.cursorrules` and `mcp.json` across 5 different AI editors. One command to rule them all.**
+
+<div align="center">
 
 [![CI](https://github.com/oomerevren-beep/forge/actions/workflows/ci.yml/badge.svg)](https://github.com/oomerevren-beep/forge/actions)
 [![npm version](https://img.shields.io/npm/v/tryforge?label=npm&color=CB3837)](https://www.npmjs.com/package/tryforge)
 [![npm downloads](https://img.shields.io/npm/dw/tryforge?label=downloads)](https://www.npmjs.com/package/tryforge)
 [![license MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![registry](https://img.shields.io/badge/registry-250%20packages-green.svg)](registry/index.json)
+[![registry](https://img.shields.io/badge/registry-21%20verified%20packages-green.svg)](registry/index.json)
 [![GitHub stars](https://img.shields.io/github/stars/oomerevren-beep/forge?style=social)](https://github.com/oomerevren-beep/forge)
 
-> **One CLI to install skills, MCPs, plugins, agents on any harness.**
-
-`brew` is for system packages. `forge` is for AI agent packages. One command, every harness — no more `git clone + cp SKILL.md` four times for four tools.
+<br>
 
 ```bash
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/oomerevren-beep/forge/main/install.sh | sh
-# Windows PowerShell
-irm https://raw.githubusercontent.com/oomerevren-beep/forge/main/install.ps1 | iex
-# or, with Node 22+
-npm i -g tryforge
+npx -y tryforge doctor
+forge add agent-security-auditor
 ```
 
-```bash
-forge doctor                # detect your harnesses
-forge add pdf/extract      # skill → all harnesses at once
-forge add mcp/filesystem    # MCP server → auto mcp.json
-```
-
-**Star to get notified at v1.0** — questions in [Discussions](https://github.com/oomerevren-beep/forge/discussions).
+<br>
 
-<p align="center">
-  <img src="docs/assets/og.png" alt="Forge — The Homebrew for AI Agents" width="640" />
-</p>
-<p align="center">
-  <img src="docs/assets/demo.gif" alt="forge demo — doctor, search, add, list in seconds" width="640" />
-  <br><em>7-second wow: <code>forge doctor → search → add → list</code></em>
-</p>
-
----
+<em>3-second wow: `forge add agent-security-auditor` writes rules to Cursor, Claude, Codex, Windsurf — simultaneously.</em>
 
-## Table of Contents
-
-- [Why Forge?](#why-forge)
-- [Features](#features)
-- [Install](#install)
-- [Quick Start](#quick-start)
-- [Team Sync — `forge install`](#team-sync--forge-install)
-- [Create a Package](#create-a-package)
-- [How it Works](#how-it-works)
-- [Comparison](#comparison)
-- [Registry — 250 Packages](#registry--250-packages)
-- [Architecture](#architecture)
-- [Docs](#docs)
-- [Roadmap](#roadmap)
-- [Contributing](#contributing)
-- [FAQ](#faq)
-- [License](#license)
+</div>
 
 ---
 
 ## Why Forge?
 
-2026: everything is a skill, plugin, or MCP — but installing one is still stone age. Every harness has its own folder, no versioning, no update path.
-
-- `obra/superpowers` — **~280k stars** — install is still manual `git clone + cp`
-- `deepseek-harness` — **~208k stars, ~2 days to 100k** — proved "Everything is a Plugin", but DeepSeek-only
-- `anthropics/skills` — **~173k stars** — Claude-only
-- `mcp-registry` — MCP-only, no skills or agents
-
-Result: a developer using Claude Code + Codex + OpenCode + Cursor installs the **same package 4 times by hand**. No `update`, no `forge.toml`, no team sync.
-
-**Forge fixes it:** 6 package types × 7 harnesses × one CLI. Like `brew` unified system packages, `forge` unifies agent packages. Viral loop: creators promote `forge add me` to distribute their own work.
-
-| Type | Example | What it does |
-|------|---------|--------------|
-| `skill` | `anthropics/plan` | `SKILL.md` capability (Anthropic standard) |
-| `mcp` | `mcp/filesystem` | Model Context Protocol server |
-| `plugin` | `dsh/desktop` | Harness extension |
-| `agent` | `agency/frontend` | Subagent definition |
-| `command` | `cmd/plan` | Slash command `/plan` |
-| `hook` | `hook/pre-tool` | Lifecycle hook |
+You're using Claude Code + Codex + OpenCode + Cursor. You want the same security rules, MCP servers, and skills everywhere. Today you:
 
----
+1. `git clone` a repo
+2. Copy `SKILL.md` to 4 different folders
+3. Manually paste the same rules into `.cursorrules`, `CLAUDE.md`, `.windsurfrules`
+4. Repeat for every new skill, every update
 
-## Features
+**Forge fixes it.** One command → every editor. Deterministic `forge.toml` → your whole team ships the same AI context.
 
-- **Universal — 6 types, one registry.** Skills + MCPs + plugins + agents + commands + hooks in one place.
-- **Multi-harness — 7 adapters today.** One file per harness, so adding Antigravity, Droid, or Copilot is a single PR. Symlink (junction on Windows) preferred, copy fallback.
-- **Team sync — `forge.toml` + `forge.lock`.** Like `package.json` for agents. `forge install` / `forge install --frozen` for CI.
-- **Search in <200ms.** Offline scored `search.json` + typed index, no API key.
-- **Git-native registry.** Every package is a GitHub repo. Forkable, private registry ready. No central DB.
-- **Safe by default.** `sha256`-verified tarballs or hard fail (no silent fallback); mock content only with explicit `--mock`; `forge audit` flags unverified installs; `forge doctor` health check; Windows/Linux/macOS.
+<div align="center">
 
-Supported harnesses (`forge doctor` detects all of them):
+| | Manual Setup | Forge |
+|---|---|---|
+| Multi-editor support | ❌ Copy-paste × 4 | ✅ One command |
+| Version pinning | ❌ None | ✅ `forge.lock` + SHA-256 |
+| Security audit | ❌ Zero | ✅ AST scanner (HIGH = refuse) |
+| Team sync | ❌ Out of sync | ✅ `forge sync` |
+| Updates | ❌ Manual | ✅ `forge update` |
+| Zero-install | ❌ | ✅ `npx -y tryforge` |
 
-| Harness | Status |
-|---------|:------:|
-| Claude Code | ✅ |
-| Codex | ✅ |
-| OpenCode | ✅ |
-| Cursor | ✅ |
-| DeepSeek (dsh) | ⚠️ (community/untested) |
-| Windsurf | ✅ |
-| Generic (any other) | ✅ |
+</div>
 
 ---
 
@@ -114,238 +61,229 @@ curl -fsSL https://raw.githubusercontent.com/oomerevren-beep/forge/main/install.
 # Windows PowerShell
 irm https://raw.githubusercontent.com/oomerevren-beep/forge/main/install.ps1 | iex
 
-# via npm (Node 22+)
+# Or with Node 22+
 npm i -g tryforge
 ```
 
-Requires Node 22+ (TypeScript). Details and troubleshooting: [docs/INSTALL.md](docs/INSTALL.md).
+```bash
+npx -y tryforge doctor   # zero-install — no global install needed
+```
 
 ---
 
-## Quick Start
-
-60 seconds, copy-paste:
+## Quick Start (60 seconds)
 
 ```bash
-npm i -g tryforge          # or: curl -fsSL https://raw.githubusercontent.com/oomerevren-beep/forge/main/install.sh | sh
-forge doctor              # detect your harnesses (7 checked)
-forge add anthropics/plan # install latest → all harnesses at once
-```
+# 1. Initialize your project
+npx forge init
 
-More once you're in:
+# 2. Add the packages you want
+forge add github:my-org/agent-security
+forge add pdf/merge
+forge add mcp/filesystem
 
-```bash
-forge search plan         # find packages (try: pdf, mcp, agent)
-forge list                # installed, with versions
-forge info mcp/github     # detail + versions + engines
-forge outdated            # what can be updated
-forge update              # update all (or: forge update mcp/github)
-forge remove obra/superpowers
+# 3. Sync every editor
+npx forge sync
 ```
 
-```bash
-# version pinning
-forge add anthropics/plan@1.1.0
-forge add anthropics/plan@^1.2.0
+Done. Cursor, Claude Code, Codex, OpenCode, Windsurf, DSH — all share the same context.
 
-# dry run — see what would happen
-forge add anthropics/plan --dry-run
+---
 
-# mock content for packages with no verified tarball yet (explicit opt-in)
-forge add skill/pdf --mock
-forge install --mock       # same opt-in for project installs
-forge update mcp/github --mock
-```
+## Supported Harnesses
 
----
+| Harness | Status | Rule Format |
+|---------|:------:|-------------|
+| Claude Code | ✅ | `CLAUDE.md` merged blocks |
+| Cursor | ✅ | `.cursor/rules/*.mdc` |
+| OpenCode | ✅ | `AGENTS.md` shared blocks |
+| Codex | ✅ | `AGENTS.md` shared blocks |
+| Windsurf | ✅ | `.windsurfrules` merged |
+| DSH | ⚠️ | `AGENTS.md` (community) |
+| Generic | ✅ | `.forge/` fallback |
 
-## Team Sync — `forge install`
+---
 
-Add `forge.toml` to your project, everyone gets the same set with one command.
+## Team Sync — `forge.toml`
 
 ```toml
-# my-project/forge.toml
+# forge.toml — single source of truth for your project's AI context
 [project]
 name = "my-app"
-version = "0.1.0"
+version = "1.0.0"
 
 [dependencies]
-"anthropics/plan" = "^1.2.0"
-"mcp/filesystem" = "^1.0.0"
-"obra/superpowers" = "^3.0.0"
-"skill/pdf" = "^1.0.0"
-```
+"agent-pr-reviewer" = "^1.2.0"
+"mcp-filesystem" = "^1.0.0"
 
-```bash
-forge install          # installs all, writes forge.lock
-forge install --frozen # CI: exact versions from lock (like npm ci)
-forge outdated         # shows 1.1.0 → 1.2.0 etc.
-forge update           # bumps to latest within semver
-```
+[skills.team-rules]
+source = "github:my-org/team-skills"
+ref = "main"
 
-Lockfile `forge.lock` is `[[packages]]` TOML — commit it. `~/.forge/config.toml` holds user defaults (registry URL, default harnesses). Worked example: [examples/team-sync/](examples/team-sync/).
+[agents.developer]
+model = "claude-3-7-sonnet"
+system_prompt = "Senior engineer. TDD. No shortcuts."
 
----
+[mcp.servers.postgres]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/db"]
 
-## Create a Package
+[permissions]
+denied_paths = [".env*", "id_rsa*", "./secrets"]
+allow_network = false
+```
 
 ```bash
-forge init my-skill --type skill --yes   # → SKILL.md + forge.toml
-forge init my-mcp --type mcp --yes       # → MCP template + [mcp] config
-forge init my-agent --type agent --yes   # → agent.md template
-# types: skill | mcp | plugin | agent | command | hook
-
-cat forge.toml
-# [package] name="my-skill" version="0.1.0" type="skill" ...
-
-forge publish   # (v0.2) validates → tarball → GitHub Release → registry PR
+# Everyone on the team runs:
+git pull
+npx forge sync
+# That's it — identical AI context across every editor
 ```
 
-Until `publish` lands, open a PR adding `registry/packages/<slug>.json` (see `schema/forge.schema.json`), then `npm run registry:build`. Minimal working example: [examples/minimal-skill/](examples/minimal-skill/).
-
 ---
 
-## How it Works
+## Security
 
-```
-forge add anthropics/plan
-  → resolve ^1.2.0 → tarball URL + sha256 (from local/bundled registry/index.json; CDN in v0.3)
-  → download to ~/.forge/cache/tarballs/ → verify sha256 (hard fail on mismatch) → extract to ~/.forge/packages/anthropics-plan@1.2.0/
-  → adapter: symlink/copy to all 7 harnesses (Claude/Codex/OpenCode/Cursor/DSH/Windsurf/Generic)
-  → if MCP: backup mcp.json → inject server entry
-```
+Forge is **fail-closed** by default:
 
-Add a harness = one file in `cli/src/adapters/`. See `docs/ADAPTERS.md`.
+- **sha256 verification** — every package is hash-pinned; mismatch = exit 1
+- **Static scanner** — 19 rules (shell-danger, prompt-inject, perm-violation); HIGH blocks install
+- **`forge audit`** — flags mock/unverified installs (exit 1 on high-severity)
+- **`forge.toml` [permissions]** — denied paths enforced per-project
 
-```
-~/.forge/
-  config.toml               # user config
-  packages/<slug>@<ver>/    # extracted content
-  cache/tarballs/           # downloaded .tar.gz
-  links.json                # {pkg, version, adapters[]} source of truth
+```bash
+forge audit                    # scan installed packages
+forge test ./my-package        # pre-publish validation
+forge verify ./my-package      # full schema + security + adapter check
 ```
 
 ---
 
-## Rekabet
-
-|  | **Forge** | `npx skills` (Vercel) | `anthropics/skills` | `DSH` | `mcp-registry` |
-|---|---|---|---|---|---|
-| Türler | **6** (skill/mcp/plugin/agent/command/hook) | 1 (skill) | 1 (skill) | plugin | 1 (mcp) |
-| Harness | **7** (Claude/Codex/OpenCode/Cursor/DSH/Windsurf/Generic) | 75+ ajan | 1 | 1 | ~1 |
-| Versiyonlama | **semver + lock** | skills-lock.json | none | none | partial |
-| Güncelleme | `forge update` | check/update | manual | manual | manual |
-| Takım senkronu | **`forge.toml` + `forge.lock`** | none | none | none | none |
-| Arama | `<200ms` offline | `skills find` | GitHub search | none | web only |
-| Paket doğrulama | **sha256 + fail-closed** | none | none | none | none |
-| Yerel CLI | **evet** (npm i -g) | npx (her seferinde indirir) | manual | manual | — |
+## Available Packages
 
-Fark: Forge, her paketi sha256 ile doğrular (fail-closed), `forge.toml` ile takım senkronu yapar, offline arama yapar ve yerel CLI olarak çalışır. Vercel skills repo-agnostik çalışır ama doğrulama ve takım senkronu yok.
-
----
+**21 verified packages** (sha256-pinned). Registry is git-native and forkable.
 
-## Registry — 21 Verified Packages
-
-Epoch 1d: Sadece sha256 doğrulanmış paketler listeleniyor (fail-closed).
+| Category | Examples |
+|----------|----------|
+| Skills | `cmd/plan`, `cmd/review`, `obra/superpowers` |
+| MCP Servers | `mcp/filesystem`, `mcp/github`, `mcp/postgres`, `mcp/memory`, `mcp/sequential-thinking` |
+| Agents | `agency/frontend`, `agency/backend` |
+| PDF Tools | `pdf/merge`, `pdf/split`, `pdf/forms`, `pdf/ocr`, `pdf/extract`, `pdf/compress`, `pdf/convert`, `pdf/tables` |
 
 ```bash
-forge search mcp        # 5 results
-forge search pdf        # 8 results
-forge search --type skill plan  # filtered
-forge info pdf/compress # versions, engines, sha
+forge search pdf
+forge search mcp
+forge info mcp/github
 ```
 
-Stats: **9 skills, 5 MCPs, 5 agents, 2 commands.** Tümü verified (sha256 pinned).
-
-```bash
-npm run registry:build  # index + search + stats + --check in CI
-```
+---
 
-Düzenli güncelleme: Yeni paketler eklemek için `registry/packages/<slug>.json` oluşturun → `npm run registry:build -- --check`.
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `forge add <pkg>` | Install to all harnesses (registry, GitHub, local) |
+| `forge remove <pkg>` | Uninstall from all harnesses |
+| `forge install` | Install all `[dependencies]` from `forge.toml` |
+| `forge install --frozen` | CI mode: exact from `forge.lock` |
+| `forge sync` | One-command team sync (skills + rules + MCP + roles) |
+| `forge init <name>` | Scaffold a new package |
+| `forge test <pkg>` | Validate against adapter matrix (dry-run) |
+| `forge pack` | Build verified tarball |
+| `forge verify <pkg>` | Schema + security + adapter check |
+| `forge audit` | Scan installed packages (fail-closed) |
+| `forge doctor` | Health check harnesses + store |
+| `forge search <query>` | Fuzzy search (<200ms, offline) |
+| `forge list` | List installed packages |
+| `forge outdated` | Show packages with newer versions |
+| `forge update` | Update all (or one) to latest |
+| `forge tui` | Interactive terminal dashboard |
 
 ---
 
 ## Architecture
 
 ```
-CLI (TypeScript v0.1 → Rust v0.2)
+CLI (TypeScript)
   ├─ registry client (index.json + semver)
-  ├─ store (~/.forge/packages/ + links.json + cache)
-  ├─ adapters (detect/install/list — 1 file per harness)
-  └─ commands (add/remove/list/search/info/doctor/init/install/update/outdated/audit)
+  ├─ store (~/.forge/ + links.json + cache)
+  ├─ adapters (1 file per harness — symlink or copy)
+  ├─ core (merge engine, security scanner, lock, sources)
+  └─ commands (add/remove/sync/audit/test/pack/verify/tui)
 ```
 
-Full diagram and crate layout in `docs/ARCHITECTURE.md`. Tech choices: `commander` + `smol-toml` + `tsx` (no `bun` on Windows), `tsc` emit to `dist/` for `npm pack`.
+**v0.1 → v0.2 → v1.0:**
+- **v0.1** (now): 7 harnesses, 21 verified packages, full CLI
+- **v0.2**: `forge publish`, Rust rewrite for `cargo install`
+- **v1.0**: Team registry, `brew install forge`, `winget`
+
+See [docs/ROADMAP.md](docs/ROADMAP.md).
 
 ---
 
-## Docs
+## Add a Package
 
-- [Install](docs/INSTALL.md) — npm / curl / source, verification
-- [Examples](examples/) — minimal skill + team sync, copy-paste
-- [Vision](docs/VISION.md) — why now, why 100k
-- [PRD](docs/PRD.md) — users, stories, commands, harness matrix
-- [Architecture](docs/ARCHITECTURE.md) — components, security, perf
-- [Package Spec](docs/SPEC.md) — `forge.toml` fields per type
-- [Registry](docs/REGISTRY.md) — index schema, publish, fork
-- [Adapters](docs/ADAPTERS.md) — add a harness in one file
-- [Roadmap](docs/ROADMAP.md) — v0.1 → v1.0
-- [Changelog](CHANGELOG.md) — release history
+```bash
+# 1. Create your package
+forge init my-skill --type skill --yes
+# Edit SKILL.md + forge.toml
+
+# 2. Verify it
+forge verify .
+
+# 3. Publish (v0.2: tarball + GitHub Release + registry PR)
+```
+
+Until `publish` lands, open a PR adding `registry/packages/<slug>.json` + run `npm run registry:build -- --check`.
 
 ---
 
-## Roadmap
+## Add a Harness
 
-**v0.1 — Homebrew moment** (now): 7 harnesses, 21 verified packages, `add/search/list/doctor/install/init`.
-**v0.2 — NPM moment**: `forge publish`, deps, `cargo install`.
-**v0.3 — Store moment**: `forge run`, Rust binary, GUI.
-**v1.0 — Cloud**: team registry, `brew install forge`, `winget`.
+One file: `cli/src/adapters/<name>.ts`. Implement the `Adapter` interface. Register in `adapters/index.ts`. Done.
 
-See `docs/ROADMAP.md`.
+See [docs/ADAPTERS.md](docs/ADAPTERS.md).
 
 ---
 
-## Paket Doğrulama
+## Documentation
 
-Forge, fail-closed paket doğrulama sağlar:
+- [Install Guide](docs/INSTALL.md)
+- [Package Spec](docs/SPEC.md) — `forge.toml` fields per type
+- [Architecture](docs/ARCHITECTURE.md) — components, security, perf
+- [Adapters](docs/ADAPTERS.md) — add a harness in one file
+- [Registry](docs/REGISTRY.md) — index schema, publish, fork
+- [Roadmap](docs/ROADMAP.md)
+- [Examples](examples/)
 
-1. **sha256 pin**: Her paket sürümü SHA-256 hash'i ile imzalanır
-2. **Verify on install**: İndirme sırasında hash kontrol edilir — uyarsa exit 1
-3. **Audit trail**: `forge audit` mock/tamamlanmamış kurulumları listeler
+---
 
-Gelecek (v0.2): Sigstore/cosign ile imzalama, verified publisher programı.
+## Badges
 
-- Add a package: create `registry/packages/<slug>.json` → `npm run registry:build`
-- Add a harness: `cli/src/adapters/<name>.ts` → register in `adapters/index.ts` → `forge doctor`
-- PR checklist: `npm run build && npm test && npm run registry:build -- --check`
-- New? Start with [`good first issue`](https://github.com/oomerevren-beep/forge/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — questions in [Discussions](https://github.com/oomerevren-beep/forge/discussions)
+Add `forge` to your project:
 
-See `CONTRIBUTING.md`, [Code of Conduct](CODE_OF_CONDUCT.md), [Security](SECURITY.md) and `AGENTS.md`.
+```markdown
+[![Managed by Forge](https://img.shields.io/badge/Agent%20Context-Forge-6366f1?style=flat-square&logo=anthropic)](https://github.com/oomerevren-beep/forge)
+```
 
 ---
 
 ## FAQ
 
 **Is this just for Claude Code?**
-No. 7 harnesses today, one file per new harness. The point is *universal* — same reason `brew` beat per-OS managers.
-
-**How is this different from `mcp-registry` or `skills` repos?**
-Those are single-type and single-harness. Forge is `brew` for *all* agent package types, on *every* harness, with versioning/lock/search.
+No. 7 harnesses today, one file per new harness. The point is *universal*.
 
 **Does `install.sh` need `forge.sh` domain?**
-No. `curl -fsSL https://raw.githubusercontent.com/oomerevren-beep/forge/main/install.sh | sh` works today. `forge.sh` is a future vanity alias.
-
-**Are most packages mock content?**
-Honest answer: 245 of 250 registry entries still carry placeholder SHAs (only 5 verified so far). Forge is fail-closed — installing one without `--mock` errors out instead of silently faking it; `forge audit` flags every unverified install. Real tarballs land as maintainers verify them (tracked for Faz 13-full).
+No. Works from GitHub raw today.
 
-**Windows symlinks?**
-Junction (`symlinkSync(..., 'junction')`) on dirs, fallback to `cpSync` on `EPERM`. `doctor` checks `links.json` (source of truth), not just dir scan.
+**Are packages verified?**
+21 are sha256-pinned and pass the static scanner. The rest is tracked for Phase 13.
 
-**Why TypeScript first, not Rust?**
-Speed to market. v0.1 is TypeScript + `tsx`; v0.2 rewrites to Rust for single binary `cargo install`. Adapters stay cheap.
+**Windows support?**
+Full. Junction on dirs, file-by-file copy fallback for non-ASCII paths, PowerShell installer.
 
 **Private registry?**
-Yes. Fork this repo, keep `registry/` private, point `~/.forge/config.toml` `registry = "https://your-r2/index.json"`.
+Yes. Fork this repo, keep `registry/` private, point `~/.forge/config.toml` to your own index.
 
 ---
 
@@ -355,7 +293,9 @@ MIT — see [LICENSE](LICENSE).
 
 ---
 
-<p align="center">
-  <strong>Star this repo to get notified at launch. 21 verified packages are live at <a href="https://github.com/oomerevren-beep/forge/releases/tag/v0.1.1">v0.1.1</a>.</strong><br>
-  <code>forge add</code> → 7 places at once. <code>forge install</code> → team sync. Homebrew simple.
-</p>
+<div align="center">
+
+<strong>Star this repo to get notified at v1.0.</strong><br>
+<code>forge add</code> → 7 places at once. <code>forge sync</code> → team sync. Homebrew simple.
+
+</div>

package/dist/cli/src/adapters/agents-md.js

@@ -0,0 +1,24 @@
+// cli/src/adapters/agents-md.ts — Shared AGENTS.md rule sync (Phase 2).
+//
+// OpenCode, Codex, and DSH all honor the AGENTS.md project convention:
+// standard system-prompt rules in one shared file. Forge merges one marked
+// block per package and never touches surrounding user content.
+import { join } from "path";
+import { pointerBody, syncBlockFile, unsyncBlockFile, shouldSyncRules, } from "./base.js";
+export function agentsMdPath(projectDir) {
+    return join(projectDir, "AGENTS.md");
+}
+export function syncAgentsMd(projectDir, pkgSlug, skillPath, meta) {
+    const file = agentsMdPath(projectDir);
+    if (!shouldSyncRules(projectDir, file))
+        return;
+    syncBlockFile(file, pkgSlug, meta?.version ?? "0.0.0", pointerBody({
+        slug: pkgSlug,
+        version: meta?.version ?? "",
+        description: meta?.description ?? `${pkgSlug} (installed via Forge)`,
+        skillPath,
+    }));
+}
+export function unsyncAgentsMd(projectDir, pkgSlug) {
+    unsyncBlockFile(agentsMdPath(projectDir), pkgSlug);
+}

package/dist/cli/src/adapters/base.js

@@ -0,0 +1,99 @@
+// cli/src/adapters/base.ts — Shared adapter foundation (Phase 2).
+//
+// Eliminates the copy-pasted project-or-home resolution, list/isInstalled
+// loops, and rule-file sync shared by all file-based harness adapters.
+// Adapters keep their own path quirks; everything mechanical lives here.
+//
+// Test hook: set FORGE_TEST_HOME to redirect home-dir resolution into a
+// temp dir so adapter tests never touch the real ~/.cursor, ~/.claude, ...
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { installSkillFiles, uninstallSkillFiles, listDirNames, ensureDir, backupFileIfExists, } from "./types.js";
+import { upsertForgeBlock, removeForgeBlock } from "../core/merge.js";
+export function testHome() {
+    return process.env.FORGE_TEST_HOME ?? homedir();
+}
+/** Build the instruction body for rule files: SKILL.md/agent.md excerpt, capped. */
+export function instructionBody(srcDir, fallback) {
+    for (const f of ["SKILL.md", "agent.md"]) {
+        try {
+            const p = join(srcDir, f);
+            if (existsSync(p)) {
+                const text = readFileSync(p, "utf-8").trim().slice(0, 2000);
+                if (text.length > 0)
+                    return `${text}\n`;
+            }
+        }
+        catch {
+            /* unreadable source — use the fallback line */
+        }
+    }
+    return `${fallback}\n`;
+}
+/** Short pointer body for merged files (CLAUDE.md, AGENTS.md, .windsurfrules). */
+export function pointerBody(pkg) {
+    const at = pkg.version ? `@${pkg.version}` : "";
+    return `- ${pkg.slug}${at}: ${pkg.description}\n  Full instructions: ${pkg.skillPath}\n`;
+}
+export async function sharedList(paths) {
+    for (const b of paths.skillBases()) {
+        if (existsSync(b))
+            return listDirNames(b);
+    }
+    return [];
+}
+export async function sharedIsInstalled(paths, pkgSlug) {
+    return paths.skillBases().some((b) => existsSync(join(b, pkgSlug)));
+}
+export function sharedUninstall(paths, pkgSlug) {
+    for (const b of paths.skillBases())
+        uninstallSkillFiles(pkgSlug, b);
+}
+export function sharedInstall(paths, pkgSlug, srcDir) {
+    installSkillFiles("forge", pkgSlug, srcDir, paths.installBase());
+}
+const PROJECT_MARKERS = [
+    "forge.toml",
+    "package.json",
+    ".git",
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursor",
+    "opencode.json",
+    ".codex",
+    ".windsurf",
+    ".dsh",
+];
+/** True when dir looks like a project (or already holds the rule file). */
+export function isProjectDir(dir) {
+    return PROJECT_MARKERS.some((m) => existsSync(join(dir, m)));
+}
+/** Merge-gate for cwd-root rule files: sync when the file exists or dir is a project. */
+export function shouldSyncRules(dir, filePath) {
+    return existsSync(filePath) || isProjectDir(dir);
+}
+/** Write a fully forge-managed per-package file (e.g. .cursor/rules/<slug>.mdc).
+* An existing file WITHOUT a forge marker is backed up (.bak) first so user
+* content is never silently lost; files already carrying our marker for the
+* same id are overwritten in place.
+*/
+export function writeManagedFile(filePath, id, content) {
+    ensureDir(dirname(filePath));
+    if (existsSync(filePath)) {
+        const raw = readFileSync(filePath, "utf-8");
+        if (!raw.includes(`id="${id}"`))
+            backupFileIfExists(filePath);
+    }
+    writeFileSync(filePath, content);
+}
+/** Merge a forge block into a user-owned file (never touches outside content). */
+export function syncBlockFile(filePath, id, version, body) {
+    ensureDir(dirname(filePath));
+    upsertForgeBlock(filePath, id, version, body);
+}
+/** Remove only our block; delete the file when forge created it and it is now blank. */
+export function unsyncBlockFile(filePath, id) {
+    removeForgeBlock(filePath, id, { deleteIfEmpty: true });
+}
+export { upsertForgeBlock, removeForgeBlock };