agency-rules 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffold.
+- Conversion engine driven by `tools.json`.
+- Renderers for **Google Antigravity**, **pi-agent**, **oh-my-pi (omp)**,
+  and **OpenCode** (via `opencode-rules`).
+- `mise.toml` with toolchain (`node@22`), tasks (`validate`, `convert`,
+  `install`, `test`, `ci`), and post-install hook.
+- Test suites for frontmatter parsing and every renderer.
+- Documentation: architecture, rule spec, harness extension guide.
+
+### Changed
+
+- N/A
+
+### Fixed
+
+- N/A
+
+---
+
+## [0.1.0] — TBD
+
+First tagged release. Reserved for the v0.1.0 cut once the harness set is
+stable.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deuri Vasquez
+
+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

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# agency-rules
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Write rules once. Run them everywhere.**
+
+`agency-rules` compiles a single set of generic Markdown rules into the
+native formats expected by **Google Antigravity**, **pi-agent**,
+**oh-my-pi (omp)**, and **OpenCode** (via the `opencode-rules` plugin).
+
+The whole pipeline — toolchain, environment, and tasks — is managed by
+[mise](https://mise.jdx.dev), so every collaborator and CI runner uses the
+exact same Node version and the exact same commands.
+
+---
+
+## Why
+
+Every coding agent has its own rule format:
+
+| Harness | Format | Location |
+| --- | --- | --- |
+| Google Antigravity | YAML frontmatter with `trigger` | `.agents/rules/*.md` |
+| pi-agent | Per-rule directory with `RULES.md` | `.pi/rules/<slug>/RULES.md` |
+| oh-my-pi (omp) | Markdown with frontmatter | `.omp/rules/*.{md,mdc}` |
+| OpenCode | Markdown via `opencode-rules` plugin | `.opencode/rules/*.md` |
+
+Writing the same rule four times is a maintenance nightmare. `agency-rules`
+lets you write it **once** in a neutral format and compile it to all four
+with a single command, driven by a declarative contract (`tools.json`).
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install toolchain + dependencies (one time)
+git clone https://github.com/<your-org>/agency-rules.git
+cd agency-rules
+mise install
+
+# 2. Compile rules to every harness
+mise run convert
+
+# 3. Install into harnesses detected on your machine
+mise run install --scope project
+```
+
+That's it. Your rules are now live in `.agents/`, `.pi/`, `.omp/`, and
+`.opencode/` (and the `opencode-rules` plugin is registered in
+`opencode.json` automatically).
+
+---
+
+## Repository layout
+
+```
+agency-rules/
+├── rules/              ← source of truth (Markdown + YAML frontmatter)
+├── integrations/       ← compiled output (generated, gitignored)
+├── scripts/            ← convert, install, validate + renderers
+├── tests/              ← node:test suites for renderers and parsing
+├── docs/               ← architecture, spec, extension guide
+├── tools.json          ← the conversion contract
+└── mise.toml           ← toolchain + tasks
+```
+
+---
+
+1. **Validate**: `mise run validate`.
+2. **Convert**: `mise run convert` and inspect `integrations/`.
+3. **Test**: `mise run test`.
+
+## Commands
+
+All commands go through mise:
+
+| Command | What it does |
+| --- | --- |
+| `mise run setup` | Install Node dependencies (`npm ci`) |
+| `mise run validate` | Validate every rule's frontmatter against `rules/_schema.json` |
+| `mise run check` | Format + lint + organize imports with Biome (write mode) |
+| `mise run convert` | Compile `rules/` → `integrations/<harness>/` |
+| `mise run convert:dry-run` | Preview which files `convert` would write (no writes) |
+| `mise run install` | Copy compiled output into harness directories |
+| `mise run install:dry-run` | Preview which files `install` would copy (no writes) |
+| `mise run test` | Run the Node test suite |
+| `mise run ci` | Full pipeline (`validate` → `check` → `convert` → `test`) |
+
+See `mise tasks` for the up-to-date list.
+
+### Dry-run workflow
+
+The typical inner loop uses dry-runs first to inspect what will change
+before anything hits disk:
+
+```bash
+mise run convert:dry-run            # see generated file paths + sizes
+mise run convert                    # actually write to integrations/
+mise run install:dry-run -- --all   # see copy destinations
+mise run install -- --all           # actually copy into harness dirs
+```
+
+---
+
+## Adding a rule
+
+1. Create `rules/<category>/<slug>.md` following
+   [`docs/RULE-SPEC.md`](docs/RULE-SPEC.md).
+2. Run `mise run validate` — it must pass.
+3. Run `mise run convert` — inspect `integrations/` to sanity-check output.
+4. Open a PR.
+
+---
+
+## Adding a harness
+
+See [`docs/ADDING-A-HARNESS.md`](docs/ADDING-A-HARNESS.md). It's roughly:
+
+1. Add an entry in `tools.json`.
+2. Add a renderer in `scripts/lib/renderers/`.
+3. Register the renderer in `scripts/lib/renderers/index.mjs`.
+4. Add tests in `tests/convert.test.mjs`.
+
+The conversion engine itself never changes.
+
+---
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) — data flow, contracts, caching.
+- [Rule spec](docs/RULE-SPEC.md) — the neutral frontmatter format.
+- [Adding a harness](docs/ADDING-A-HARNESS.md) — extension guide.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests welcome.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for responsible disclosure.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/docs/ADDING-A-HARNESS.md

@@ -0,0 +1,170 @@
+# Adding a Harness
+
+This guide walks through adding support for a new coding agent. The example
+uses a hypothetical harness called **`example-agent`**.
+
+---
+
+## Prerequisites
+
+Read [`ARCHITECTURE.md`](ARCHITECTURE.md) first. You need to understand:
+
+- Why `tools.json` is a contract (not a list).
+- What renderers do (pure functions, no I/O).
+- What the installer does (copies per manifest).
+
+---
+
+## Step 1 — Add an entry to `tools.json`
+
+Add a new key under `harnesses`. Every field matters:
+
+```json
+"example-agent": {
+  "id": "example-agent",
+  "label": "Example Agent",
+  "format": "md-example",
+  "installKind": "per-rule",
+  "integrationPath": "{{slug}}.md",
+  "detect": { "dirs": [".example", "~/.example"] },
+  "dest": {
+    "project": ".example/rules/{{slug}}.md",
+    "user": "~/.example/rules/{{slug}}.md"
+  },
+  "frontmatter": {
+    "required": ["description"],
+    "map": {
+      "description": "string",
+      "globs": "array<string>|string"
+    }
+  }
+}
+```
+
+Field checklist:
+
+- [ ] `id` — matches the key, kebab-case.
+- [ ] `label` — human-readable name.
+- [ ] `format` — you will use this string as a key in `renderers/index.mjs`.
+- [ ] `installKind` — currently only `per-rule` is implemented.
+- [ ] `integrationPath` — path under `integrations/<id>/`. Use `{{slug}}`.
+- [ ] `detect.dirs` / `detect.files` — where the harness lives.
+- [ ] `dest.project` / `dest.user` — install destinations.
+- [ ] `frontmatter.required` — fields the harness cannot run without.
+- [ ] `frontmatter.map` — documentation of supported fields.
+- [ ] `plugin` — only if the harness needs a plugin registered.
+
+---
+
+## Step 2 — Create the renderer
+
+Create `scripts/lib/renderers/example-agent.mjs`:
+
+```js
+import { wrap } from './_util.mjs';
+
+export function renderExampleAgent(rule, _harness) {
+  const d = rule.data;
+  const fm = { description: d.description };
+  if (d.globs !== undefined) fm.globs = d.globs;
+  return wrap(fm, rule.body);
+}
+```
+
+Rules for renderers:
+
+- Pure. No `fs`, no `process`, no globals.
+- Signature is `(rule, harness) => string`.
+- Read only the fields your harness understands. Drop the rest silently —
+  other harnesses may need them.
+- Use `wrap()` from `_util.mjs` for consistent frontmatter formatting.
+
+---
+
+## Step 3 — Register the renderer
+
+Edit `scripts/lib/renderers/index.mjs`:
+
+```js
+import { renderExampleAgent } from './example-agent.mjs';
+
+export const renderers = {
+  // ...
+  'md-example': renderExampleAgent,
+};
+```
+
+The key must be the exact string from `tools.json`'s `format` field.
+
+---
+
+## Step 4 — Add tests
+
+Edit `tests/convert.test.mjs` and add a block:
+
+```js
+import { renderExampleAgent } from '../scripts/lib/renderers/example-agent.mjs';
+
+test('example-agent: emits description', () => {
+  const fm = matter(renderExampleAgent(baseRule)).data;
+  assert.equal(fm.description, 'Rules for TS.');
+});
+
+test('example-agent: preserves globs as-is', () => {
+  const fm = matter(renderExampleAgent(baseRule)).data;
+  assert.deepEqual(fm.globs, ['**/*.ts', '**/*.tsx']);
+});
+```
+
+Cover:
+
+- A rule with only the required fields.
+- A rule with every optional field your harness supports.
+- The "body preserved verbatim" test in the shared block.
+
+---
+
+## Step 5 — Verify end-to-end
+
+```bash
+mise run validate        # schema must still pass
+mise run convert         # your harness should appear in the summary
+ls integrations/example-agent/
+mise run test            # all renderer tests, including yours
+mise run install --harness example-agent --scope project
+```
+
+Inspect `integrations/example-agent/<slug>.md` and confirm the output matches
+your harness's expected format.
+
+---
+
+## Step 6 — Update docs
+
+- Add a row to the compatibility matrix in `docs/RULE-SPEC.md`.
+- Add a row to the harness table in `README.md`.
+- Update the "Adding a rule — checklist" in `CONTRIBUTING.md` if the new
+  harness changes requirements.
+
+---
+
+## Step 7 — Open a PR
+
+Title: `feat(harness): support example-agent`
+
+Include in the description:
+
+- Link to the harness's documentation.
+- A sample compiled output.
+- Screenshot or log from `mise run install` (optional but helpful).
+
+---
+
+## Supported harnesses (current)
+
+| Harness | `format` | `installKind` | Path |
+| --- | --- | --- | --- |
+| Google Antigravity | `md-yaml-trigger` | `per-rule` | `.agents/rules/*.md` |
+| pi-agent | `md-rules-dir` | `per-rule` | `.pi/rules/<slug>/RULES.md` |
+| oh-my-pi (omp) | `md-or-mdc` | `per-rule` | `.omp/rules/*.md` |
+| OpenCode | `md-plugin` | `per-rule` | `.opencode/rules/*.md` |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,130 @@
+# Architecture
+
+This document explains how `agency-rules` turns one set of generic rules into
+four native harness formats, and why the pipeline is shaped the way it is.
+
+---
+
+## Data flow
+
+```
+         rules/*.md                     tools.json
+         (source of truth)              (contract)
+              │                              │
+              │                              │
+              ▼                              ▼
+    ┌────────────────────────────────────────────┐
+    │  scripts/validate.mjs  (schema + uniqueness)│
+    └────────────────────────────────────────────┘
+                        │
+                        ▼
+    ┌────────────────────────────────────────────┐
+    │  scripts/convert.mjs                        │
+    │    for each harness:                        │
+    │      render = renderers[harness.format]     │
+    │      for each rule:                         │
+    │        write render(rule, harness)          │
+    │      write _manifest.json                   │
+    └────────────────────────────────────────────┘
+                        │
+                        ▼
+              integrations/<harness>/...
+              (compiled, gitignored)
+                        │
+                        ▼
+    ┌────────────────────────────────────────────┐
+    │  scripts/install.mjs                        │
+    │    detect harnesses                         │
+    │    copy files to harness.dest[scope]        │
+    │    register plugins (opencode)              │
+    └────────────────────────────────────────────┘
+                        │
+                        ▼
+                  user's harness dirs
+```
+
+---
+
+## Layers
+
+| Layer | File(s) | Responsibility |
+| --- | --- | --- |
+| **Source** | `rules/**/*.md` | Generic Markdown + YAML frontmatter. |
+| **Schema** | `rules/_schema.json` | JSON Schema enforcing the neutral format. |
+| **Contract** | `tools.json` | Declares each harness: format, integration path, install destinations, frontmatter mapping, plugin metadata. |
+| **Engine** | `scripts/convert.mjs` | Iterates over rules × harnesses, calls the right renderer, writes output + manifest. |
+| **Renderers** | `scripts/lib/renderers/*.mjs` | Pure functions: `(rule, harness) → markdown string`. No I/O. |
+| **Installer** | `scripts/install.mjs` | Detects harnesses, copies compiled files to real destinations, registers plugins. |
+| **Validator** | `scripts/validate.mjs` | Runs the schema and checks slug uniqueness before anything else runs. |
+| **Orchestration** | `mise.toml` | Pins Node version, defines tasks, composes `ci`, wires the `postinstall` hook. |
+
+Each layer has exactly one job. Renderers never touch the filesystem; the
+engine never hardcodes a harness; the installer never renders.
+
+---
+
+## Why `tools.json` is the single source of truth
+
+Every harness-specific decision lives there:
+
+- **Which renderer** to use (`format`).
+- **What path** the output takes inside `integrations/<harness>/` (`integrationPath`).
+- **Where** the file ultimately lands for `project` and `user` scopes (`dest`).
+- **Which frontmatter fields** are required and how they map (`frontmatter`).
+- **Whether** plugin registration is needed (`plugin`).
+
+Adding a harness is additive: one `tools.json` entry + one renderer +
+one test. The engine, installer, and validator never change.
+
+---
+
+## Determinism guarantees
+
+- **Pure renderers.** Same input → same output byte for byte. No timestamps,
+  no random ordering. Manifests are sorted by slug.
+- **Full reset on convert.** `integrations/<harness>/` is deleted before
+  being rewritten. No stale files survive a rename.
+- **Manifest as index.** `integrations/<harness>/_manifest.json` records
+  every file the installer should copy. The installer trusts the manifest,
+  not a directory walk.
+- **Locked toolchain.** `mise.lock` pins exact versions of Node and any
+  installed CLIs. CI uses `mise install --locked` to fail on drift.
+
+---
+
+## Caching
+
+`mise run convert` declares:
+
+```toml
+sources = ["rules/**/*.md", "tools.json", "scripts/lib/**/*.mjs"]
+outputs = ["integrations/**/*"]
+```
+
+If no source has changed since the last run, mise skips the task entirely.
+This keeps the inner loop fast as the rules tree grows.
+
+---
+
+## OpenCode plugin registration
+
+OpenCode needs `opencode-rules` registered in `opencode.json`. The installer:
+
+1. Reads (or creates) `opencode.json`.
+2. Ensures `config.plugin` is an array.
+3. Appends `"opencode-rules@latest"` if it isn't already present.
+4. Writes the config back with 2-space indentation.
+
+If the file exists but is invalid JSON, the installer warns and skips rather
+than overwriting — a corrupted config is never silently clobbered.
+
+---
+
+## Security considerations
+
+- Rule slugs are validated against `^[a-z][a-z0-9-]*$` before they reach the
+  filesystem, preventing path traversal via `{{slug}}` substitution.
+- `install.mjs` only reads from `integrations/` and writes to paths derived
+  from `tools.json` — it never reads arbitrary user input paths.
+- Renderers do not execute rule content; they only stringify it. No `eval`,
+  no shell, no dynamic imports.

package/docs/RULE-SPEC.md

@@ -0,0 +1,135 @@
+# Rule Specification
+
+The neutral format for a rule: **Markdown with YAML frontmatter**.
+Every rule compiles to every harness, so the frontmatter must carry enough
+information to derive each harness's expectations.
+
+---
+
+## File layout
+
+```
+rules/
+├── _schema.json
+├── <category>/
+│   └── <slug>.md
+```
+
+- `_schema.json` is the JSON Schema. It is not a rule and is skipped.
+- Any file starting with `_` is skipped.
+- `<slug>` should equal the frontmatter `name`.
+
+---
+
+## Frontmatter fields
+
+| Field | Required | Type | Description |
+| --- | --- | --- | --- |
+| `name` | ✅ | string, `^[a-z][a-z0-9-]*$`, ≤64 | Unique identifier. Used as the slug. |
+| `description` | ✅ | string, 1–1024 | **When** the rule applies (not what it says). Harnesses use this for matching. |
+| `globs` | ❌ | string \| string[] | File patterns that trigger the rule. |
+| `alwaysApply` | ❌ | boolean | If `true`, ignore `globs` and always apply. |
+| `trigger` | ❌ | `always_on` \| `glob` \| `model_decision` \| `manual` | Explicit trigger for Antigravity. Overrides auto-derivation. |
+| `match` | ❌ | `any` \| `all` | OpenCode: match any glob or all globs. |
+| `tags` | ❌ | string[] | Freeform metadata. Ignored by all harnesses. |
+| `tools` | ❌ | string[] | pi-agent: tools the rule provides. Preserved verbatim. |
+
+---
+
+## Body
+
+The body is Markdown. It is copied verbatim into every compiled output.
+Don't put harness-specific syntax here — anything that must differ goes in
+the frontmatter and is handled by the renderer.
+
+---
+
+## Compatibility matrix
+
+| Field | Antigravity | pi-agent | oh-my-pi | OpenCode |
+| --- | --- | --- | --- | --- |
+| `name` | (derived) | ✅ used | ✅ used | — |
+| `description` | ✅ emitted | ✅ emitted | ✅ emitted | ✅ used for matching |
+| `globs` | ✅ joined as string under `trigger: glob` | ✗ dropped | ✅ preserved | ✅ preserved |
+| `alwaysApply` | ✅ → `trigger: always_on` | ✗ dropped | ✅ preserved | ✗ dropped |
+| `trigger` | ✅ emitted | ✗ dropped | ✗ dropped | ✗ dropped |
+| `match` | ✗ dropped | ✗ dropped | ✗ dropped | ✅ preserved |
+| `tags` | ✗ dropped | ✗ dropped | ✗ dropped | ✗ dropped |
+| `tools` | ✗ dropped | ✅ preserved | ✗ dropped | ✗ dropped |
+
+"✗ dropped" means the field is not emitted in that harness's output. It does
+not mean it's an error to set it — other harnesses may need it. The renderer
+picks what its harness understands.
+
+---
+
+## Antigravity trigger precedence
+
+Antigravity requires a `trigger` field. The renderer resolves it in this
+order:
+
+1. Explicit `trigger` in the rule.
+2. `alwaysApply: true` → `always_on`.
+3. `globs` present → `glob`.
+4. Only `description` → `model_decision`.
+5. Nothing → `manual`.
+
+When `trigger: glob`, the renderer joins the `globs` array with commas into a
+single string, which is the format Antigravity's YAML parser expects.
+
+---
+
+## Examples
+
+### Always-on baseline
+
+```markdown
+---
+name: coding-standards
+description: Baseline rules applied to every edit regardless of file type.
+alwaysApply: true
+tags: [base]
+---
+
+# Coding Standards
+...
+```
+
+Compiles to Antigravity `trigger: always_on`, oh-my-pi `alwaysApply: true`,
+and pi-agent / OpenCode with just `name` + `description`.
+
+### Scoped to file globs
+
+```markdown
+---
+name: typescript
+description: Mandatory rules for editing TypeScript and TSX files.
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+tags: [language, typescript]
+---
+
+# TypeScript Rules
+...
+```
+
+Compiles to Antigravity `trigger: glob` + `globs: "**/*.ts,**/*.tsx"`,
+oh-my-pi and OpenCode with the original array, pi-agent without `globs`.
+
+### Description-only (model decision)
+
+```markdown
+---
+name: api-review
+description: Use this rule when reviewing REST API endpoint definitions.
+---
+
+# API Review
+...
+```
+
+Compiles to Antigravity `trigger: model_decision`. Other harnesses get just
+`name` + `description`.
+
+```

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "agency-rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Write rules once. Run them in every harness.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Deuri Vasquez <deuriib@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deuriib/agency-rules.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deuriib/agency-rules/issues"
+  },
+  "homepage": "https://github.com/deuriib/agency-rules#readme",
+  "keywords": ["ai", "agents", "rules", "antigravity", "pi-agent", "opencode", "oh-my-pi"],
+  "engines": { "node": ">=20.12" },
+  "files": [
+    "scripts/",
+    "tools.json",
+    "rules/_schema.json",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.5.0"
+  }
+}

package/rules/_schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "name",
+    "description"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "maxLength": 64
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "globs": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        }
+      ]
+    },
+    "alwaysApply": {
+      "type": "boolean"
+    },
+    "trigger": {
+      "enum": [
+        "always_on",
+        "glob",
+        "model_decision",
+        "manual"
+      ]
+    },
+    "match": {
+      "enum": [
+        "any",
+        "all"
+      ]
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/scripts/convert.mjs

@@ -0,0 +1,106 @@
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readRules } from './lib/frontmatter.mjs';
+import { renderers } from './lib/renderers/index.mjs';
+
+const { values: args } = parseArgs({
+    options: {
+        'dry-run': { type: 'boolean', default: false },
+        harness: { type: 'string' },
+    },
+});
+
+const dryRun = args['dry-run'];
+const prefix = dryRun ? '  [dry-run]' : ' ';
+
+const RULES_DIR = process.env.RULES_DIR || 'rules';
+const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
+
+const tools = JSON.parse(await readFile('tools.json', 'utf8'));
+const rules = await readRules(RULES_DIR);
+
+if (rules.length === 0) {
+    console.error(`❌ No rules found in ${RULES_DIR}`);
+    process.exit(1);
+}
+
+console.log(
+    `📚 Found ${rules.length} rule(s) in ${RULES_DIR}${dryRun ? ' (dry-run — nothing will be written)' : ''}\n`,
+);
+
+const harnessIds = args.harness ? [args.harness] : Object.keys(tools.harnesses);
+
+for (const id of harnessIds) {
+    if (!tools.harnesses[id]) {
+        console.error(`❌ Unknown harness: ${id}`);
+        process.exit(1);
+    }
+}
+
+let totalFiles = 0;
+
+for (const id of harnessIds) {
+    const harness = tools.harnesses[id];
+    const render = renderers[harness.format];
+    if (!render) {
+        console.error(`❌ No renderer for format "${harness.format}" (harness: ${id})`);
+        process.exit(1);
+    }
+
+    if (!harness.integrationPath) {
+        console.error(`❌ Missing "integrationPath" for harness "${id}" in tools.json`);
+        process.exit(1);
+    }
+
+    const harnessDir = join(INTEGRATIONS_DIR, id);
+    const manifest = [];
+
+    for (const rule of rules) {
+        let output;
+        try {
+            output = render(rule, harness);
+        } catch (err) {
+            console.error(`❌ ${id}: failed to render "${rule.slug}": ${err.message}`);
+            process.exit(1);
+        }
+
+        const relPath = harness.integrationPath.replace('{{slug}}', rule.slug);
+        const outPath = join(harnessDir, relPath);
+        manifest.push({ slug: rule.slug, path: relPath, size: output.length });
+        totalFiles++;
+
+        if (!dryRun) {
+            await mkdir(dirname(outPath), { recursive: true });
+            await writeFile(outPath, output);
+        }
+    }
+
+    if (!dryRun) {
+        await writeFile(
+            join(harnessDir, '_manifest.json'),
+            JSON.stringify(
+                {
+                    harness: id,
+                    format: harness.format,
+                    files: manifest.map(({ slug, path }) => ({ slug, path })),
+                },
+                null,
+                2,
+            ),
+        );
+    }
+
+    console.log(`✅ ${id.padEnd(12)} → ${manifest.length} file(s)`);
+    if (dryRun) {
+        for (const f of manifest) {
+            console.log(`${prefix} would write ${join(harnessDir, f.path)} (${f.size} bytes)`);
+        }
+    }
+}
+
+const summary = dryRun
+    ? `\n🔎 Dry-run: would write ${totalFiles} file(s) across ${harnessIds.length} harness(es). Nothing was written.`
+    : `\n🎉 Wrote ${totalFiles} file(s) across ${harnessIds.length} harness(es).`;
+
+console.log(summary);

package/scripts/install.mjs

@@ -0,0 +1,142 @@
+import { access, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { detectHarnesses, expandHome, pathExists } from './lib/detect.mjs';
+
+const { values: args } = parseArgs({
+    options: {
+        scope: { type: 'string', default: 'project' },
+        harness: { type: 'string' },
+        all: { type: 'boolean', default: false },
+        'dry-run': { type: 'boolean', default: false },
+    },
+});
+
+if (!['project', 'user'].includes(args.scope)) {
+    console.error(`❌ Invalid --scope: ${args.scope} (use "project" or "user")`);
+    process.exit(1);
+}
+
+const dryRun = args['dry-run'];
+const tag = dryRun ? '[dry-run]' : '     ';
+const log = (msg) => console.log(`  ${tag} ${msg}`);
+
+const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
+const tools = JSON.parse(await readFile('tools.json', 'utf8'));
+
+let targets;
+if (args.harness) {
+    if (!tools.harnesses[args.harness]) {
+        console.error(`❌ Unknown harness: ${args.harness}`);
+        process.exit(1);
+    }
+    targets = [args.harness];
+} else if (args.all) {
+    targets = Object.keys(tools.harnesses);
+} else {
+    targets = await detectHarnesses(tools);
+    if (targets.length === 0) {
+        console.warn(
+            `⚠️  No harness detected. Pass --harness <id> or --all to force.${dryRun ? '' : ''}`,
+        );
+        process.exit(0);
+    }
+}
+
+console.log(
+    `🔍 Targets: ${targets.join(', ')} (scope: ${args.scope})${dryRun ? ' — dry-run, no changes will be made' : ''}\n`,
+);
+
+let copied = 0;
+let skippedHarnesses = 0;
+let pluginChanges = 0;
+
+for (const id of targets) {
+    const harness = tools.harnesses[id];
+    const srcDir = join(INTEGRATIONS_DIR, id);
+
+    if (!(await pathExists(srcDir))) {
+        console.warn(
+            `⚠️  ${id}: no compiled output at ${srcDir}, skipping. Run "mise run convert" first.`,
+        );
+        skippedHarnesses++;
+        continue;
+    }
+
+    const manifest = JSON.parse(await readFile(join(srcDir, '_manifest.json'), 'utf8'));
+    const destTemplate = harness.dest[args.scope];
+    if (!destTemplate) {
+        console.warn(`⚠️  ${id}: no dest for scope "${args.scope}"`);
+        skippedHarnesses++;
+        continue;
+    }
+
+    for (const { slug, path: relPath } of manifest.files) {
+        const destPath = expandHome(destTemplate.replace('{{slug}}', slug));
+        if (dryRun) {
+            log(`${id}: would copy ${relPath} → ${destPath}`);
+        } else {
+            await mkdir(dirname(destPath), { recursive: true });
+            await copyFile(join(srcDir, relPath), destPath);
+            log(`${id}: ${destPath}`);
+        }
+        copied++;
+    }
+
+    if (harness.plugin) {
+        const changed = await handlePlugin(id, harness.plugin, args.scope, dryRun, log);
+        if (changed) pluginChanges++;
+    }
+}
+
+console.log(
+    dryRun
+        ? `\n🔎 Dry-run: would copy ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
+              (pluginChanges ? ` Would update ${pluginChanges} plugin config(s).` : '') +
+              ` Nothing was written.`
+        : `\n🎉 Installed ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
+              (pluginChanges ? ` Updated ${pluginChanges} plugin config(s).` : ''),
+);
+
+if (dryRun && skippedHarnesses > 0) {
+    console.log(
+        `\n⚠️  ${skippedHarnesses} harness(es) skipped due to missing integrations. Run "mise run convert" first.`,
+    );
+}
+
+// ── Plugin registration ────────────────────────────────────────────────
+async function handlePlugin(id, plugin, scope, dry, logFn) {
+    const configPath =
+        scope === 'user'
+            ? expandHome('~/.config/opencode/opencode.json')
+            : join(process.cwd(), 'opencode.json');
+
+    let config = {};
+    let existed = false;
+    if (await pathExists(configPath)) {
+        existed = true;
+        try {
+            config = JSON.parse(await readFile(configPath, 'utf8'));
+        } catch {
+            console.warn(`⚠️  ${id}: ${configPath} is not valid JSON, skipping plugin registration`);
+            return false;
+        }
+    }
+
+    config.plugin = config.plugin || [];
+    if (config.plugin.includes(plugin.entry)) {
+        logFn(`${id}: plugin "${plugin.entry}" already registered in ${configPath}`);
+        return false;
+    }
+
+    const action = existed ? 'would add' : 'would create and add';
+    logFn(`${id}: ${action} "${plugin.entry}" to ${configPath}`);
+
+    if (!dry) {
+        config.plugin.push(plugin.entry);
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+    }
+
+    return true;
+}

package/scripts/lib/detect.mjs

@@ -0,0 +1,32 @@
+import { access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function expandHome(p) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+export async function pathExists(p) {
+  try {
+    await access(expandHome(p));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function detectHarnesses(tools) {
+  const detected = [];
+  for (const [id, harness] of Object.entries(tools.harnesses)) {
+    const dirs = harness.detect?.dirs ?? [];
+    const files = harness.detect?.files ?? [];
+    let found = false;
+    for (const p of [...dirs, ...files]) {
+      if (await pathExists(p)) { found = true; break; }
+    }
+    if (found) detected.push(id);
+  }
+  return detected;
+}

package/scripts/lib/frontmatter.mjs

@@ -0,0 +1,37 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, basename } from 'node:path';
+import matter from 'gray-matter';
+
+/**
+ * Reads every *.md file under `dir` (recursive), parses YAML frontmatter,
+ * and returns an array of { slug, source, data, body }.
+ *
+ * `slug` is derived from the frontmatter `name` (authoritative), with the
+ * filename as fallback. Files starting with `_` are skipped.
+ */
+export async function readRules(dir) {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  const rules = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name.startsWith('_')) continue;
+
+    const parent = entry.parentPath ?? entry.path;
+    const filePath = join(parent, entry.name);
+    const raw = await readFile(filePath, 'utf8');
+    const parsed = matter(raw);
+    const filename = basename(filePath, '.md');
+    const slug = typeof parsed.data?.name === 'string' ? parsed.data.name : filename;
+
+    rules.push({
+      slug,
+      source: relative(dir, filePath),
+      data: parsed.data ?? {},
+      body: (parsed.content ?? '').trim(),
+    });
+  }
+
+  return rules.sort((a, b) => a.slug.localeCompare(b.slug));
+}

package/scripts/lib/renderers/_util.mjs

@@ -0,0 +1,8 @@
+import { stringify as yamlStringify } from 'yaml';
+
+/** Wraps YAML frontmatter + body in a Markdown document. */
+export function wrap(data, body) {
+  const fm = yamlStringify(data).trimEnd();
+  const content = (body ?? '').trim();
+  return `---\n${fm}\n---\n\n${content}\n`;
+}

package/scripts/lib/renderers/antigravity.mjs

@@ -0,0 +1,30 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * Antigravity expects a YAML frontmatter with a mandatory `trigger` field.
+ * Precedence:
+ *   1. explicit `trigger` in the rule
+ *   2. `alwaysApply: true`           → always_on
+ *   3. `globs` present               → glob
+ *   4. only `description`            → model_decision
+ *   5. nothing                       → manual
+ */
+export function renderAntigravity(rule, _harness) {
+  const d = rule.data;
+  let trigger = d.trigger;
+
+  if (!trigger) {
+    if (d.alwaysApply === true) trigger = 'always_on';
+    else if (d.globs) trigger = 'glob';
+    else if (d.description) trigger = 'model_decision';
+    else trigger = 'manual';
+  }
+
+  const fm = { trigger };
+  if (trigger === 'glob' && d.globs) {
+    fm.globs = Array.isArray(d.globs) ? d.globs.join(',') : d.globs;
+  }
+  if (d.description) fm.description = d.description;
+
+  return wrap(fm, rule.body);
+}

package/scripts/lib/renderers/index.mjs

@@ -0,0 +1,12 @@
+import { renderAntigravity } from './antigravity.mjs';
+import { renderPiAgent } from './pi-agent.mjs';
+import { renderOhMyPi } from './oh-my-pi.mjs';
+import { renderOpencode } from './opencode.mjs';
+
+/** Maps `format` from tools.json → renderer function. */
+export const renderers = {
+  'md-yaml-trigger': renderAntigravity,
+  'md-rules-dir': renderPiAgent,
+  'md-or-mdc': renderOhMyPi,
+  'md-plugin': renderOpencode,
+};

package/scripts/lib/renderers/oh-my-pi.mjs

@@ -0,0 +1,16 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * oh-my-pi preserves `name`, `description`, optional `globs` and
+ * `alwaysApply` in the frontmatter. Accepts .md or .mdc; we emit .md.
+ */
+export function renderOhMyPi(rule, _harness) {
+  const d = rule.data;
+  const fm = {
+    name: d.name,
+    description: d.description,
+  };
+  if (d.globs !== undefined) fm.globs = d.globs;
+  if (d.alwaysApply !== undefined) fm.alwaysApply = d.alwaysApply;
+  return wrap(fm, rule.body);
+}

package/scripts/lib/renderers/opencode.mjs

@@ -0,0 +1,13 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * OpenCode's `opencode-rules` plugin discovers .md files with a `description`
+ * (used for matching) and optional `globs`/`match` controls.
+ */
+export function renderOpencode(rule, _harness) {
+  const d = rule.data;
+  const fm = { description: d.description };
+  if (d.globs !== undefined) fm.globs = d.globs;
+  if (d.match !== undefined) fm.match = d.match;
+  return wrap(fm, rule.body);
+}

package/scripts/lib/renderers/pi-agent.mjs

@@ -0,0 +1,17 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * pi-agent expects each rule in its own directory as RULES.md with a
+ * frontmatter carrying `name`, `description`, and optionally `tools`.
+ */
+export function renderPiAgent(rule, _harness) {
+  const d = rule.data;
+  const fm = {
+    name: d.name,
+    description: d.description,
+  };
+  if (Array.isArray(d.tools) && d.tools.length > 0) {
+    fm.tools = d.tools;
+  }
+  return wrap(fm, rule.body);
+}

package/scripts/validate.mjs

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import Ajv from 'ajv';
+import { readRules } from './lib/frontmatter.mjs';
+
+const RULES_DIR = process.env.RULES_DIR || 'rules';
+
+const schema = JSON.parse(await readFile(join(RULES_DIR, '_schema.json'), 'utf8'));
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validate = ajv.compile(schema);
+
+const rules = await readRules(RULES_DIR);
+
+if (rules.length === 0) {
+  console.error(`❌ No rules found in ${RULES_DIR}`);
+  process.exit(1);
+}
+
+const seen = new Set();
+let failures = 0;
+
+for (const rule of rules) {
+  const errors = [];
+
+  if (seen.has(rule.slug)) {
+    errors.push({ instancePath: '/name', message: `duplicate rule name "${rule.slug}"` });
+  }
+  seen.add(rule.slug);
+
+  if (!validate(rule.data)) {
+    for (const e of validate.errors ?? []) {
+      errors.push(e);
+    }
+  }
+
+  if (errors.length > 0) {
+    failures++;
+    console.error(`❌ ${rule.source}`);
+    for (const e of errors) {
+      console.error(`   ${e.instancePath || '/'} ${e.message}`);
+    }
+  } else {
+    console.log(`✅ ${rule.source}`);
+  }
+}
+
+if (failures > 0) {
+  console.error(`\n💥 ${failures}/${rules.length} rule(s) failed validation.`);
+  process.exit(1);
+}
+
+console.log(`\n🎉 ${rules.length} rule(s) validated successfully.`);

package/tools.json

@@ -0,0 +1,91 @@
+{
+  "version": 1,
+  "harnesses": {
+    "antigravity": {
+      "id": "antigravity",
+      "label": "Google Antigravity",
+      "format": "md-yaml-trigger",
+      "installKind": "per-rule",
+      "integrationPath": "{{slug}}.md",
+      "detect": { "dirs": [".agents", "~/.gemini"], "files": ["GEMINI.md", "AGENTS.md"] },
+      "dest": {
+        "project": ".agents/rules/{{slug}}.md",
+        "user": "~/.gemini/config/rules/{{slug}}.md"
+      },
+      "frontmatter": {
+        "required": ["trigger"],
+        "map": {
+          "trigger": "always_on|glob|model_decision|manual",
+          "globs": "string",
+          "description": "string"
+        }
+      }
+    },
+    "pi-agent": {
+      "id": "pi-agent",
+      "label": "Pi Coding Agent",
+      "format": "md-rules-dir",
+      "installKind": "per-rule",
+      "integrationPath": "{{slug}}/RULES.md",
+      "detect": { "dirs": [".pi", "~/.pi"] },
+      "dest": {
+        "project": ".pi/rules/{{slug}}/RULES.md",
+        "user": "~/.pi/agent/rules/{{slug}}/RULES.md"
+      },
+      "frontmatter": {
+        "required": ["name", "description"],
+        "map": {
+          "name": "string",
+          "description": "string",
+          "tools": "array<string>"
+        }
+      }
+    },
+    "oh-my-pi": {
+      "id": "oh-my-pi",
+      "label": "oh-my-pi (omp)",
+      "format": "md-or-mdc",
+      "installKind": "per-rule",
+      "integrationPath": "{{slug}}.md",
+      "detect": { "dirs": [".omp", "~/.omp"] },
+      "dest": {
+        "project": ".omp/rules/{{slug}}.md",
+        "user": "~/.omp/agent/rules/{{slug}}.md"
+      },
+      "frontmatter": {
+        "required": ["name", "description"],
+        "map": {
+          "name": "string",
+          "description": "string",
+          "globs": "array<string>|string",
+          "alwaysApply": "boolean"
+        }
+      },
+      "extensions": [".md", ".mdc"]
+    },
+    "opencode": {
+      "id": "opencode",
+      "label": "OpenCode (via opencode-rules)",
+      "format": "md-plugin",
+      "installKind": "per-rule",
+      "integrationPath": "{{slug}}.md",
+      "detect": { "dirs": [".opencode", "~/.config/opencode"] },
+      "dest": {
+        "project": ".opencode/rules/{{slug}}.md",
+        "user": "~/.config/opencode/rules/{{slug}}.md"
+      },
+      "frontmatter": {
+        "required": ["description"],
+        "map": {
+          "description": "string",
+          "globs": "array<string>|string",
+          "match": "\"any\"|\"all\""
+        }
+      },
+      "plugin": {
+        "package": "opencode-rules",
+        "entry": "opencode-rules@latest"
+      }
+    }
+  }
+}