@uzysjung/agent-harness 26.102.0 → 26.103.0

package/README.md

@@ -71,6 +71,26 @@ Curation, not a list to browse — pick `csr-supabase` and step 3 pre-checks exa
 
 ---
 
+## Curation philosophy — lean by default
+
+> Maintainer's direction statement (2026-07). The catalog itself is unchanged by this section — it describes how curation decisions are made going forward.
+
+Frontier coding agents (Opus 4.8 / GPT-5.6 class) keep absorbing what skill packs used to teach. Our working position: **a skill has to earn its context cost** — every installed skill occupies the agent's attention even when unused, so the default install stays minimal and "more skills" is treated as a cost, not a feature.
+
+What we believe still earns its place is the **insight layer**, not the knowledge layer:
+
+- **Orchestration know-how** — model/effort role splits (`model-orchestration`), multi-perspective verification (`multi-persona-review`), auditing your own harness (`harness-health-audit`).
+- **Cross-CLI leverage** — use each CLI for what it's best at: natural prose polish via Antigravity (`gemini-consult`), concise structuring + image generation via Codex (`codex-consult`).
+- **Operational facts** — CLI flags, auth flows, deploy steps (`supabase-cli`, `railway-skills`, …) drift with upstream releases no matter how smart models get. Generic pattern guides are the first to become redundant.
+
+Structured workflow bundles (superpowers, BMAD, OpenSpec, …) stay **opt-in and never pre-checked**. Our view: with strong models, an agile direction plus a firm git/PR policy beats enforced ceremony for solo/greenfield work — but multi-dev alignment, junior onboarding, and audit trails are human-side problems that no model upgrade solves, so the choice stays yours ([Workflow curation guide](docs/WORKFLOWS.md)).
+
+What stays fixed is small and deterministic: git/PR policy, verification gates, honest reporting. Within those rails the agent develops flexibly — including running several agents in parallel in one session (safety conventions for that, like worktree isolation, are roadmap items, not shipped features). Since v26.103.0 the installer shows the **session-start context cost** of your selection (bundled skills measured from frontmatter, external assets honestly marked unmeasured), and our test suite holds the bundled-skill descriptors of the default install under a token budget (external assets stay unmeasured).
+
+One honest note: this repository's *own* development harness is deliberately heavier than what it installs — it self-verifies an installer that writes into your project. Shipped defaults ≠ our dev rig.
+
+---
+
 ## Installing into an existing project
 
 `agent-harness` never silently overwrites your config. Before replacing an **editable** file whose contents differ, it writes a timestamped backup next to it — and every backup path is printed in the install summary (`backup` rows). Nothing is deleted.
@@ -200,12 +220,15 @@ External assets are recommended automatically based on your track selection. Ste
 | `asis-tobe-decision` ★ | Present an A-or-B / approval moment as context → recommendation → option table → AS-IS/TO-BE contrast | this project (core) |
 | `compaction-handoff` ★ | Persist durable state + git snapshot + resume anchor before a context `/compact` | this project (core) |
 | `northstar-roadmap` ★ | Measure current state vs the vision doc → ranked feature backlog persisted to docs/plans + memory | this project (core) |
+| `model-orchestration` ★ | Model orchestration policy — role split (orchestrator directs/reviews · strong model authors core/V&V · mid model does repetitive impl/E2E) + effort floors + quota handoff | this project (core) |
+| `harness-health-audit` ★ | Audit your CLAUDE.md/rules/skills/hooks on 4 questions a linter can't answer: TRUE · USED · AFFORDABLE · SAFE | this project (core) |
 
-**First-party advisor** (`official`, **opt-in** — `--with gemini-consult`; repo-bundled, installs across all 4 CLIs; needs the external Antigravity [`agy`](https://antigravity.google/cli) CLI at runtime):
+**First-party advisors** (`official`, **opt-in** — `--with gemini-consult` / `--with codex-consult`; repo-bundled, install across all 4 CLIs; each needs its external CLI at runtime — Antigravity [`agy`](https://antigravity.google/cli) or OpenAI `codex`):
 
 | Asset | What | Source |
 |---|---|---|
-| `gemini-consult` | Consult Gemini (via `agy`) for natural **Korean** phrasing + **multi-persona** second-opinion review — an idiomatic, independent second model | this project |
+| `gemini-consult` | Consult Gemini (via `agy`) for natural **Korean** phrasing + **multi-persona** second-opinion review + image generation — an idiomatic, independent second model | this project |
+| `codex-consult` | Consult OpenAI Codex (`codex exec`) for **concise / structured** rewriting + **image generation** (real PNG on disk) — division of labor: nuance/persona → gemini, concision/structure/images → codex | this project |
 
 ### Security & ECC (opt-in)
 

package/dist/index.js

@@ -709,7 +709,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "@uzysjung/agent-harness",
-  version: "26.102.0",
+  version: "26.103.0",
   description: "Curate vetted AI-coding skills & plugins by your tech stack \u2014 install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
   type: "module",
   publishConfig: {
@@ -763,7 +763,8 @@ var package_default = {
 
 // src/commands/install.ts
 init_esm_shims();
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/cli-targets.ts
 init_esm_shims();
@@ -2719,6 +2720,54 @@ function listHookFiles(hookDir) {
 // src/commands/install-render.ts
 init_esm_shims();
 
+// src/context-cost.ts
+init_esm_shims();
+import { existsSync as existsSync12, readFileSync as readFileSync12 } from "fs";
+import { join as join11, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(chars) {
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+function resolveBundleRoot() {
+  return resolve2(fileURLToPath(new URL(".", import.meta.url)), "..");
+}
+function extractFrontmatter(content) {
+  const m = content.match(/^?---\r?\n([\s\S]*?)\r?\n---/);
+  return m?.[1] ?? null;
+}
+function assetDescriptorTokens(assetId, root = resolveBundleRoot()) {
+  const asset = EXTERNAL_ASSETS.find((a) => a.id === assetId);
+  if (!asset || asset.method.kind !== "internal") return null;
+  const skillMd = join11(root, "templates", "skills", asset.method.key, "SKILL.md");
+  if (!existsSync12(skillMd)) return null;
+  const fm = extractFrontmatter(readFileSync12(skillMd, "utf8"));
+  return fm === null ? null : estimateTokens(fm.length);
+}
+function summarizeContextCost(assetIds, root = resolveBundleRoot()) {
+  let measuredTokens = 0;
+  let measuredCount = 0;
+  let unmeasuredCount = 0;
+  for (const id of assetIds) {
+    const tokens = assetDescriptorTokens(id, root);
+    if (tokens === null) unmeasuredCount += 1;
+    else {
+      measuredTokens += tokens;
+      measuredCount += 1;
+    }
+  }
+  return { measuredTokens, measuredCount, unmeasuredCount };
+}
+function formatContextCostLine(s) {
+  if (s.measuredCount === 0 && s.unmeasuredCount === 0) return null;
+  if (s.measuredCount === 0) {
+    return `session-start context cost: unmeasured (${s.unmeasuredCount} external asset${s.unmeasuredCount === 1 ? "" : "s"})`;
+  }
+  const skills = `${s.measuredCount} bundled skill${s.measuredCount === 1 ? "" : "s"} measured`;
+  const external = s.unmeasuredCount > 0 ? ` \xB7 ${s.unmeasuredCount} external unmeasured` : "";
+  return `session-start context cost: ~${s.measuredTokens} tokens (${skills}${external})`;
+}
+
 // src/preset-recommend.ts
 init_esm_shims();
 function recommendedExternalAssets(presets) {
@@ -2783,6 +2832,8 @@ function renderInstallHeader(log, spec, mode) {
     for (const [cat, ids] of groupAssetsByCategory(finalAssets)) {
       log(`              ${c.dim(`\xB7 ${cat}:`)} ${ids.join(", ")}`);
     }
+    const cost = formatContextCostLine(summarizeContextCost(finalAssets));
+    if (cost) log(`              ${c.dim(`\xB7 ${cost}`)}`);
   }
   log("");
 }
@@ -3248,7 +3299,7 @@ function installAction(options, deps = {}) {
       withKarpathyHook: options.withKarpathyHook === true
     },
     cli: validated.cli,
-    projectDir: resolve2(options.projectDir ?? process.cwd()),
+    projectDir: resolve3(options.projectDir ?? process.cwd()),
     scope: resolveScopeOption(options.scope, err)
   };
   executeSpec(spec, {
@@ -3317,7 +3368,7 @@ function defaultRunPipeline(spec, harnessRoot, mode, callbacks) {
   return runInstall(ctx);
 }
 function defaultHarnessRoot() {
-  return resolve2(new URL(".", import.meta.url).pathname, "..");
+  return resolve3(fileURLToPath2(new URL(".", import.meta.url)), "..");
 }
 function registerInstallCommand(cli2) {
   cli2.command("install", "Install harness assets into a project").option("--track <name>", "[Track] Track to install (repeatable)", { type: [String] }).option(
@@ -3352,15 +3403,15 @@ function registerInstallCommand(cli2) {
 // src/commands/uninstall.ts
 init_esm_shims();
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync12, readFileSync as readFileSync12, rmSync } from "fs";
-import { join as join11, resolve as resolve3 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync13, rmSync } from "fs";
+import { join as join12, resolve as resolve4 } from "path";
 function uninstallAction(options, deps = {}) {
   const log = deps.log ?? console.log;
   const err = deps.err ?? console.error;
   const exit = deps.exit ?? ((code) => process.exit(code));
   const spawn = deps.spawn ?? defaultSpawn2;
   const rm = deps.rm ?? defaultRm;
-  const projectDir = resolve3(options.projectDir ?? process.cwd());
+  const projectDir = resolve4(options.projectDir ?? process.cwd());
   const installLog = readInstallLog(projectDir);
   if (!installLog) {
     err(status.failure(c.red(`ERROR: install log not found at ${installLogPath(projectDir)}`)));
@@ -3525,22 +3576,22 @@ function buildGlobalAdvisoryCmd(asset) {
   }
 }
 function removeTemplates(log, projectDir, rm) {
-  rm(join11(projectDir, log.templates.claudeDir));
-  if (log.templates.codexDir) rm(join11(projectDir, log.templates.codexDir));
-  if (log.templates.opencodeDir) rm(join11(projectDir, log.templates.opencodeDir));
+  rm(join12(projectDir, log.templates.claudeDir));
+  if (log.templates.codexDir) rm(join12(projectDir, log.templates.codexDir));
+  if (log.templates.opencodeDir) rm(join12(projectDir, log.templates.opencodeDir));
   const rootMd = log.templates.rootClaudeMd;
   if (rootMd) {
     if (rootClaudeMdModified(log, projectDir)) return { rootClaudeMdKept: true };
-    rm(join11(projectDir, rootMd.path));
+    rm(join12(projectDir, rootMd.path));
   }
   return { rootClaudeMdKept: false };
 }
 function rootClaudeMdModified(log, projectDir) {
   const rootMd = log.templates.rootClaudeMd;
   if (!rootMd) return false;
-  const path = join11(projectDir, rootMd.path);
-  if (!existsSync12(path)) return false;
-  return hashContent(readFileSync12(path, "utf8")) !== rootMd.sha256;
+  const path = join12(projectDir, rootMd.path);
+  if (!existsSync13(path)) return false;
+  return hashContent(readFileSync13(path, "utf8")) !== rootMd.sha256;
 }
 function formatTemplateList(log) {
   const items = [log.templates.claudeDir];
@@ -3552,7 +3603,7 @@ function defaultSpawn2(cmd, args) {
   return spawnSync2(cmd, [...args], { encoding: "utf8", stdio: "pipe", timeout: 12e4 });
 }
 function defaultRm(path) {
-  if (existsSync12(path)) {
+  if (existsSync13(path)) {
     rmSync(path, { recursive: true, force: true });
   }
 }
@@ -4846,8 +4897,8 @@ Proceed?`,
 
 // src/state.ts
 init_esm_shims();
-import { existsSync as existsSync13, readFileSync as readFileSync13 } from "fs";
-import { join as join12 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync14 } from "fs";
+import { join as join13 } from "path";
 var META_FILE = ".claude/.installed-tracks";
 var LEGACY_SIGNATURES = [
   { rule: "htmx.md", track: "ssr-htmx" },
@@ -4857,13 +4908,13 @@ var LEGACY_SIGNATURES = [
   { rule: "cli-development.md", track: "tooling" }
 ];
 function detectInstallState(projectDir) {
-  const claudeDir = join12(projectDir, ".claude");
-  const hasClaudeDir = existsSync13(claudeDir);
+  const claudeDir = join13(projectDir, ".claude");
+  const hasClaudeDir = existsSync14(claudeDir);
   if (!hasClaudeDir) {
     return { state: "new", tracks: [], source: "none", hasClaudeDir: false };
   }
-  const metaPath = join12(projectDir, META_FILE);
-  if (existsSync13(metaPath)) {
+  const metaPath = join13(projectDir, META_FILE);
+  if (existsSync14(metaPath)) {
     const tracks2 = readMetafile(metaPath);
     return { state: "existing", tracks: tracks2, source: "metafile", hasClaudeDir: true };
   }
@@ -4871,7 +4922,7 @@ function detectInstallState(projectDir) {
   return { state: "existing", tracks, source: "legacy", hasClaudeDir: true };
 }
 function readMetafile(path) {
-  const raw = readFileSync13(path, "utf8");
+  const raw = readFileSync14(path, "utf8");
   const seen = /* @__PURE__ */ new Set();
   for (const line of raw.split(/\s+/)) {
     const trimmed = line.trim();
@@ -4882,13 +4933,13 @@ function readMetafile(path) {
   return [...seen].sort();
 }
 function inferFromLegacySignatures(projectDir) {
-  const rulesDir = join12(projectDir, ".claude/rules");
-  if (!existsSync13(rulesDir)) {
+  const rulesDir = join13(projectDir, ".claude/rules");
+  if (!existsSync14(rulesDir)) {
     return [];
   }
   const found = /* @__PURE__ */ new Set();
   for (const sig of LEGACY_SIGNATURES) {
-    if (existsSync13(join12(rulesDir, sig.rule))) {
+    if (existsSync14(join13(rulesDir, sig.rule))) {
       found.add(sig.track);
     }
   }
@@ -5101,6 +5152,8 @@ function formatSummary(spec) {
     for (const [cat, ids] of groupAssetsByCategory(finalAssets)) {
       lines.push(`  \xB7 ${cat}: ${ids.join(", ")}`);
     }
+    const cost = formatContextCostLine(summarizeContextCost(finalAssets));
+    if (cost) lines.push(`  \xB7 ${cost}`);
   }
   if (spec.userOverride) {
     if (spec.userOverride.forceInclude.length > 0) {