agent-economy 0.2.0 → 0.2.2

package/README.md

@@ -12,6 +12,14 @@ ae doctor                     # detect rtk / billion-context / goal plugin
 ae packs                      # curated third-party rule/skill packs
 ```
 
+### Install with your agent (no terminal needed)
+
+Paste this into opencode / Claude Code / Codex / Cursor — the agent does the rest:
+
+> Install agent-economy: run `npx -y agent-economy@latest init --level standard --yes`, then `npx -y agent-economy@latest skill`, then `npx -y agent-economy@latest doctor`, and report the results. Don't ask clarifying questions; project scope.
+
+After that, every future session discovers the `agent-economy-setup` skill and knows how to verify, re-configure, or extend the setup on its own.
+
 ## Why requests, not tokens
 
 Token-compression tools (billion-context, RTK, headroom) are plentiful. **Request-economy tooling does not exist** — yet per-request metering is what actually caps free-tier sessions (measured baseline: ~7 model requests per user message in a real opencode session). Batching 3 independent calls into 1 round saves 2 requests *and* 2 round-trips of latency, every time. No plugin can force batching — call count is decided at generation time — so the prompt is the only injection point. This project owns that injection point.
@@ -40,9 +48,19 @@ You can't police teammates' machines — you can police the repo:
 - run: npx agent-economy verify --min-level strict
 ```
 
-## Packs (v0.2 roadmap)
+## Development
+
+```bash
+npm test                              # hermetic node:test suite
+git config core.hooksPath .githooks   # pre-commit verify (one-time per clone)
+node src/cli.js packs --check         # curated specs vs upstream HEAD (weekly in CI)
+```
 
-Curated, attributed, pinned fetch-on-demand integrations — never vendored:
+Releases: push a tag (`git tag vX.Y.Z && git push --tags`) — the `release` workflow runs the tests, then publishes to npm via **OIDC trusted publishing** (no token secret). One-time setup on npmjs.com: package → Settings → Trusted Publisher → `markymakes-dev/agent-economy` · workflow `release.yml`.
+
+## Packs
+
+Curated, attributed, pinned fetch-on-demand integrations - never vendored:
 
 | Pack | Source | Kind |
 |---|---|---|
@@ -51,6 +69,12 @@ Curated, attributed, pinned fetch-on-demand integrations — never vendored:
 | `ecc-harness` | affaan-m/ECC | harness performance patterns |
 | `anthropic-skills` | anthropics/skills | official skills |
 
+```bash
+ae packs --install ecc-harness   # → ~/.claude/skills (override with --dir)
+```
+
+RTK and billion-context are **runtime tools**, not packs — `ae packs` prints their setup commands, `ae inventory` shows whether they're alive. `ae` never installs them for you.
+
 ## Positioning
 
 Token compressors optimize **bytes**; this optimizes **round-trips**. Different unit, different layer, complementary stack. The dedicated AGENTS.md-template niche is empty (existing repos: 6–41★) while the adjacent skills ecosystem measures in six figures — the lane is open.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "agent-economy",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "files": [
     "src",
     "packs",
+    "skills",
     "AGENTS.md",
     "README.md",
     "LICENSE"
@@ -14,6 +15,9 @@
     "ae": "src/cli.js",
     "economy": "src/cli.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "engines": {
     "node": ">=18"
   },

package/packs/registry.json

@@ -16,24 +16,59 @@
       "source": "mattpocock/skills",
       "ref": "main",
       "kind": "skills",
-      "status": "planned",
-      "note": "Matt Pocock's .agents directory — engineering skills for real codebases (install spec TBD)"
+      "status": "curated",
+      "install": [
+        { "from": "skills/engineering/tdd", "to": "tdd" },
+        { "from": "skills/engineering/code-review", "to": "code-review" },
+        { "from": "skills/engineering/diagnosing-bugs", "to": "diagnosing-bugs" },
+        { "from": "skills/engineering/codebase-design", "to": "codebase-design" },
+        { "from": "skills/engineering/pr", "to": "pr" },
+        { "from": "skills/productivity/writing-for-agents", "to": "writing-for-agents" }
+      ],
+      "note": "Curated subset of Matt Pocock's engineering skills (the full 66-skill collection is worth browsing; these are the evergreen ones)"
     },
     {
       "id": "ecc-harness",
       "source": "affaan-m/ECC",
       "ref": "main",
       "kind": "harness",
-      "status": "planned",
-      "note": "Agent-harness performance patterns: skills, instincts, memory, security (install spec TBD)"
+      "status": "curated",
+      "install": [
+        { "from": ".agents/skills/verification-loop", "to": "verification-loop" },
+        { "from": ".agents/skills/change-impact", "to": "change-impact" },
+        { "from": ".agents/skills/coding-standards", "to": "coding-standards" },
+        { "from": ".agents/skills/security-review", "to": "security-review" }
+      ],
+      "note": "Request-economy-relevant subset of ECC's harness skills. strategic-compact excluded: it pushes manual /compact at token thresholds, which conflicts with proxy-based compaction (billion-context) that owns the compaction lane. ECC-specific skills like ecc-conventions deliberately excluded"
     },
     {
       "id": "anthropic-skills",
       "source": "anthropics/skills",
       "ref": "main",
       "kind": "skills",
-      "status": "planned",
-      "note": "Official Anthropic agent skills (install spec TBD)"
+      "status": "curated",
+      "install": [
+        { "from": "skills/skill-creator", "to": "skill-creator" },
+        { "from": "skills/mcp-builder", "to": "mcp-builder" },
+        { "from": "skills/webapp-testing", "to": "webapp-testing" }
+      ],
+      "note": "Official Anthropic skills, agent-tooling subset (document skills docx/pdf/pptx/xlsx live in the same repo if you want them manually)"
+    },
+    {
+      "id": "rtk",
+      "source": "rtk-ai/rtk",
+      "kind": "tool",
+      "status": "stack",
+      "setup": "winget install rtk-ai.rtk · then: rtk init -g --opencode --hook-only --no-patch",
+      "note": "Command rewriter — cuts agent tool output at the source (100+ per-command filters, fail-open)"
+    },
+    {
+      "id": "billion-context",
+      "source": "ranxianglei/billion-context",
+      "kind": "tool",
+      "status": "stack",
+      "setup": "npm i -g billion-context · then: bili plugin install opencode",
+      "note": "Context-compression proxy for agent sessions — folds stale context out of every request"
     }
   ]
 }

package/skills/agent-economy-setup/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: agent-economy-setup
+description: Install, verify, or configure agent-economy request-economy rules. Use when the user asks to install/set up agent-economy, wants the agent to save requests/quota/credits, mentions ae commands, or a CI check on agent-economy fails.
+license: MIT
+---
+
+# agent-economy setup
+
+Free and metered agent tiers bill **per request** — every model round-trip costs one. agent-economy manages a battle-tested rule set as an idempotent, marker-bounded block in `AGENTS.md`, so agents batch, dedupe, and finish in fewer round-trips.
+
+## Commands
+
+- `ae init [--level off|standard|strict] [--scope project|global|both] [--yes]` — install/update the rules block (interactive unless `--yes`)
+- `ae verify [file] [--min-level standard|strict]` — check the block; exit 0 ok, 1 missing, 2 below level (this is the CI gate)
+- `ae doctor` — detect companion tooling (rtk, billion-context, goal plugin)
+- `ae inventory` — list the token-economy stack (with live health) + all loaded plugins/skills/MCP
+- `ae packs` / `ae packs --install <id>` — curated third-party rule/skill packs (fetch-on-demand, attributed)
+- `ae skill` — (re)install this skill
+
+## Installing for a user
+
+1. Run `npx -y agent-economy@latest init --level standard --yes` (project scope). Use `--level strict` when the user wants maximum savings; `--scope global` writes `~/.config/opencode/AGENTS.md`.
+2. Run `npx -y agent-economy@latest skill` so future sessions can manage the setup themselves.
+3. Run `npx -y agent-economy@latest doctor` and report the results.
+4. Optional: `npx -y agent-economy@latest packs --install karpathy-rules` (behavior rules). NEVER install stack tools (`rtk`, `billion-context`) without asking — they change runtime behavior, not content.
+
+## Guardrails
+
+- The block between `<!-- agent-economy:start level=… -->` and `<!-- agent-economy:end -->` is MANAGED — never hand-edit it; change the level with `ae init --level <lvl>`.
+- `ae init` is idempotent and backs up to `AGENTS.md.bak-<timestamp>` first.
+- If a repo contains the block, run `ae verify --min-level strict` before committing.
+- Levels: `standard` = batch + dedupe + filter output at source; `strict` = + assume-and-proceed, same-turn completion, no subagents for small lookups.

package/src/cli.js

@@ -38,6 +38,16 @@ const startMarker = (lvl) => `<!-- agent-economy:start level=${lvl} -->`;
 const blockFor = (lvl) => [startMarker(lvl), "", HEADER, "", ...RULES[lvl], "", MARKER_END].join("\n");
 const globalFile = () => path.join(os.homedir(), ".config", "opencode", "AGENTS.md");
 
+function skill(dir) {
+  const src = path.join(ROOT, "skills", "agent-economy-setup");
+  const target = path.resolve(dir || path.join(os.homedir(), ".claude", "skills", "agent-economy-setup"));
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.cpSync(src, target, { recursive: true });
+  console.log(`  ✔ agent-economy-setup skill → ${target}`);
+  console.log("  = agents discover it automatically (opencode picks it up without restart)");
+}
+
 function upsert(file, level) {
   const exists = fs.existsSync(file);
   const prev = exists ? fs.readFileSync(file, "utf8") : "";
@@ -98,14 +108,25 @@ function doctor() {
 
 function packs() {
   const reg = JSON.parse(fs.readFileSync(path.join(ROOT, "packs", "registry.json"), "utf8"));
-  console.log("  Curated packs (fetch-on-demand in v0.2; attribution + pinned refs):\n");
-  for (const p of reg.packs) console.log(`  ${p.id.padEnd(18)} ${p.source.padEnd(38)} [${p.status}] ${p.note}`);
+  console.log("  Curated packs (fetch-on-demand; attribution + pinned refs):\n");
+  for (const p of reg.packs.filter((p) => p.status !== "stack"))
+    console.log(`  ${p.id.padEnd(18)} ${p.source.padEnd(38)} [${p.status}] ${p.note}`);
+  const tools = reg.packs.filter((p) => p.status === "stack");
+  if (tools.length) {
+    console.log("\n  Stack tools (runtime — detected by `ae inventory`; ae never installs these):\n");
+    for (const p of tools) console.log(`  ${p.id.padEnd(18)} ${p.source.padEnd(38)} setup: ${p.setup}`);
+  }
 }
 
 async function installPack(id, dir) {
   const reg = JSON.parse(fs.readFileSync(path.join(ROOT, "packs", "registry.json"), "utf8"));
   const p = reg.packs.find((x) => x.id === id);
   if (!p) { console.error(`  ✘ unknown pack "${id}"`); process.exit(2); }
+  if (p.status === "stack") {
+    console.error(`  ✘ "${id}" is a runtime tool, not a fetchable pack — ae never installs those.`);
+    console.error(`    set it up directly: ${p.setup}`);
+    process.exit(2);
+  }
   if (!Array.isArray(p.install) || !p.install.length) {
     console.error(`  ✘ pack "${id}" has no curated install spec yet (status: ${p.status})`);
     process.exit(2);
@@ -141,6 +162,34 @@ async function installPack(id, dir) {
   }
 }
 
+async function checkPack(id) {
+  const reg = JSON.parse(fs.readFileSync(path.join(ROOT, "packs", "registry.json"), "utf8"));
+  const list = id ? reg.packs.filter((p) => p.id === id) : reg.packs.filter((p) => Array.isArray(p.install) && p.install.length);
+  if (!list.length) { console.error(id ? `  ✘ unknown pack "${id}"` : "  = no installable packs"); process.exit(id ? 2 : 0); }
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "ae-check-"));
+  let bad = 0;
+  try {
+    for (const p of list) {
+      const url = `https://codeload.github.com/${p.source}/tar.gz/refs/heads/${p.ref || "main"}`;
+      console.log(`  … ${p.id} (${p.source}@${p.ref || "main"})`);
+      const res = await fetch(url);
+      if (!res.ok) { console.log(`    ✘ download failed: HTTP ${res.status}`); bad++; continue; }
+      const tgz = path.join(work, `${p.id}.tgz`);
+      fs.writeFileSync(tgz, Buffer.from(await res.arrayBuffer()));
+      const r = spawnSync("tar", ["-tzf", tgz], { encoding: "utf8", maxBuffer: 128 * 1024 * 1024 });
+      if (r.status !== 0) { console.log("    ✘ tar listing failed"); bad++; continue; }
+      const files = new Set(r.stdout.split(/\r?\n/).map((f) => f.replace(/^[^/]+\//, "")));
+      const missing = p.install.filter((s) => !files.has(`${s.from}/SKILL.md`));
+      if (missing.length) { for (const s of missing) console.log(`    ✘ drift: ${s.from}/SKILL.md gone from upstream`); bad++; }
+      else console.log(`    ✔ ${p.install.length}/${p.install.length} specs present`);
+    }
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+  console.log(bad ? `  ✘ ${bad} pack(s) drifted — update packs/registry.json` : "  = all curated install specs match upstream HEAD");
+  process.exit(bad ? 1 : 0);
+}
+
 function listDir(p, filter) {
   try { return fs.readdirSync(p, { withFileTypes: true }).filter((d) => filter(d, p)).map((d) => d.name); }
   catch { return []; }
@@ -234,6 +283,8 @@ const HELP = `
     packs     List curated third-party rule/skill packs
               --install <id> [--dir <target>]   fetch + install a curated pack
                                                 (default target: ~/.claude/skills)
+              --check [id]                      validate install specs against upstream HEAD
+    skill     Install the agent-economy-setup skill (teaches any agent to run ae)
     help      This text
 
   Every model round-trip bills one request. Batch the independent ones.
@@ -281,8 +332,11 @@ async function main() {
   }
 
   if (cmd === "doctor") return doctor();
+  if (cmd === "skill") return skill(get("--dir"));
   if (cmd === "inventory") return inventory();
   if (cmd === "packs") {
+    const cid = get("--check");
+    if (hasFlag("--check")) return checkPack(cid && !cid.startsWith("--") ? cid : undefined);
     if (get("--install")) return installPack(get("--install"), get("--dir"));
     return packs();
   }