@harness-forge/cli 1.2.3 → 1.2.4

package/.agents/skills/token-budget-optimizer/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: token-budget-optimizer
+description: Auto-discoverable wrapper for `.hforge/library/skills/token-budget-optimizer/SKILL.md`.
+---
+
+# Token Budget Optimizer
+
+## Activation
+
+- trigger when context is getting large, repetitive, or expensive to keep in active prompt history
+- trigger when the repo already has runtime summaries, task artifacts, decisions, or specs that can be reused instead of re-read
+- trigger before broad repo rescans when the next safe answer may already exist in `.hforge/` or other authoritative guidance surfaces
+
+## Use These Surfaces
+
+- `.hforge/library/skills/token-budget-optimizer/SKILL.md`
+- `.hforge/library/skills/token-budget-optimizer/references/`
+- `.hforge/library/skills/token-budget-optimizer/scripts/inspect_token_surfaces.py`
+- `.hforge/library/docs/authoring/token-budget-optimizer-port.md`
+
+## Operating Rule
+
+Use the canonical skill under `.hforge/library/skills/` for execution. Treat
+this wrapper as a discovery entrypoint only, prefer the smallest authoritative
+runtime surfaces first, and use the maintainer-facing port note only when the
+import rationale or promotion intent matters.

package/AGENTS.md

@@ -60,6 +60,7 @@ Use the thin visible bridge surfaces first in installed workspaces:
 
 - prefer `.hforge/library/skills/cloud-architect/` when the task is about deployment topology, distributed systems, reliability, observability, or cloud trade-offs across services
 - prefer `.hforge/library/skills/engineering-assistant/` when the task needs architecture plus implementation orchestration, option framing, or explicit project-memory and change-discipline guidance in one surface
+- prefer `.hforge/library/skills/token-budget-optimizer/` when prompt history is growing, repo context is being repeated, or existing runtime artifacts should be reused before broader rescans
 - use `.hforge/library/manifests/catalog/framework-assets.json` and `.hforge/runtime/repo/recommendations.json` when framework or bundle matching is more reliable than guessing from file extensions
 
 ## Imported skill governance
@@ -67,8 +68,10 @@ Use the thin visible bridge surfaces first in installed workspaces:
 - treat `.hforge/library/manifests/catalog/engineering-assistant-import-inventory.json` as the review ledger for the single-skill engineering-assistant port
 - keep maintainer-facing provenance for that port in `.hforge/library/docs/authoring/engineering-assistant-port.md`
 - treat `.hforge/library/manifests/catalog/enhanced-skill-import-inventory.json` as the review ledger for embedded skill packs and use it before changing imported skill surfaces
+- treat `.hforge/library/manifests/catalog/token-budget-optimizer-import-inventory.json` as the review ledger for the token-budget-optimizer port and promotion rationale
 - treat `.agents/skills/` as the discovery layer and `.hforge/library/skills/` as the canonical installed execution layer
 - keep maintainer-facing provenance in `.hforge/library/docs/authoring/enhanced-skill-import.md`
+- keep maintainer-facing provenance for token-budget optimization in `.hforge/library/docs/authoring/token-budget-optimizer-port.md`
 - use `RESEARCH-SOURCES.md` and `VALIDATION.md` only as additional provenance, not as replacements for the canonical installed skill surfaces
 - prefer the project-owned canonical `.hforge/library/skills/` surfaces over any raw imported archive layout
 
@@ -123,4 +126,4 @@ Use the thin visible bridge surfaces first in installed workspaces:
 ## Usage promotion
 
 - if an operator wants stronger Harness Forge usage in day-to-day agent work, use `docs/agent-usage-playbook.md`
-- prefer the playbook prompts when you want the agent to prove it is reading the installed guidance layer, use the command catalog, create task artifacts, write decision records, or escalate into recursive mode
+- prefer the playbook prompts when you want the agent to prove it is reading the installed guidance layer, use the command catalog, compact context efficiently, create task artifacts, write decision records, or escalate into recursive mode

package/README.md

@@ -101,7 +101,7 @@ Instead of relying on one-off prompts or tribal setup knowledge, it gives you a
 | 🎯 Runtime targets | 4 target surfaces: Codex, Claude Code, Cursor, OpenCode |
 | 🧠 Knowledge system | 14 language packs total: 5 seeded + 9 structured |
 | 🧩 Framework coverage | 12 framework packs including React, Next.js, Vite, Express, FastAPI, Django, ASP.NET Core, Spring Boot, Laravel, Symfony, Gin, and Ktor |
-| 🛠 Skills | 44 packaged skills across language engineering, workflow orchestration, operational helpers, and workload-specialized flows |
+| 🛠 Skills | 45 packaged skills across language engineering, workflow orchestration, operational helpers, and workload-specialized flows |
 | 🔁 Flow support | `.specify/` spec → plan → tasks → implement flow plus flow-state recovery |
 | 🔬 Intelligence | `scan`, `recommend`, `cartograph`, `classify-boundaries`, and `synthesize-instructions` |
 | 📊 Local observability | Effectiveness summaries, recommendation acceptance, hook runs, maintenance traces, and runtime summaries |
@@ -267,6 +267,7 @@ Harness Forge can lower token burn because it gives the agent:
 - focused runtime summaries
 - machine-readable manifests
 - curated skills
+- a promoted token-budget-optimizer skill for context compaction and reuse-first work
 - reusable task/state artifacts
 - repo-aware recommendations
 - structured entrypoints instead of blind exploration
@@ -418,7 +419,7 @@ Harness Forge is strongest with **Codex** and **Claude Code** today.
 - structured language engineering skills
 - Speckit workflow orchestration skills
 - operational helper skills
-- workload-specialized skills such as incident triage, dependency upgrade safety, profiling, API contract review, database migration review, release readiness, repo modernization, observability setup, and cloud architecture
+- workload-specialized skills such as incident triage, dependency upgrade safety, profiling, API contract review, database migration review, release readiness, repo modernization, observability setup, cloud architecture, and token-budget optimization
 
 ---
 
@@ -724,7 +725,7 @@ That playbook includes:
 
 - launcher-aware command resolution when `hforge` is not on `PATH`
 - concrete operator prompts that tell agents to read the installed runtime
-- examples for task artifacts, decision records, recursive mode, and support verification
+- examples for task artifacts, decision records, recursive mode, support verification, and token-budget compaction
 
 In runtimes that expose packaged markdown commands, Harness Forge can also ship
 triggerable command docs such as `/hforge-init`, `/hforge-analyze`,

package/docs/agent-usage-playbook.md

@@ -50,6 +50,8 @@ following:
 - uses `status`, `commands`, `recommend`, `review`, `task`, or `recursive` instead of inventing unsupported commands
 - reads `.hforge/runtime/repo/repo-map.json` or `.hforge/runtime/repo/recommendations.json` before making support claims
 - writes durable artifacts only when the workflow actually calls for them
+- compacts context by reusing runtime summaries, task artifacts, and decision
+  records instead of rereading wide repo surfaces
 
 ## Important limitation
 
@@ -92,6 +94,15 @@ hforge recursive plan "investigate the issue" --task-id TASK-001 --root . --json
 hforge recursive capabilities --root . --json
 ```
 
+If the task is large or the prompt is getting expensive:
+
+```text
+Load .agents/skills/token-budget-optimizer/SKILL.md and use the installed
+token-budget-optimizer skill before broad repo scanning. Reuse existing
+runtime summaries, task artifacts, and decision records first, then tell me
+which surfaces you will keep loaded and which ones you can compact away.
+```
+
 ## Prompt patterns
 
 ### 1. Prove that the agent is using Harness Forge
@@ -165,6 +176,17 @@ output, before claiming that Claude Code, Codex, Cursor, or OpenCode supports a
 behavior.
 ```
 
+### 8. Force context compaction and reuse
+
+Use this when the task is long-running or the agent is repeating repo scans:
+
+```text
+Use the installed Harness Forge token-budget-optimizer skill before you expand
+context further. Reuse existing runtime summaries, task artifacts, and decision
+records first. Tell me what you will keep loaded, what you will compact, and
+what new evidence still requires a focused read.
+```
+
 ## Claude-specific examples
 
 ```text

package/docs/agents.md

@@ -20,6 +20,7 @@ AI content into the hidden `.hforge/` layer.
 - `docs/agent-usage-playbook.md` for copy-ready prompts and examples that make
   agents use the installed Harness Forge runtime more explicitly
 - `docs/authoring/enhanced-skill-import.md` for curated research and validation provenance behind imported skill upgrades
+- `docs/authoring/token-budget-optimizer-port.md` for maintainer-facing provenance behind the promoted context-compaction skill
 - `RESEARCH-SOURCES.md` and `VALIDATION.md` for optional pack-level provenance detail
 
 ## When agents should use Harness Forge
@@ -36,6 +37,8 @@ AI content into the hidden `.hforge/` layer.
   an explicit recursive session instead of growing the prompt
 - when a recursive session needs one bounded structured analysis step with a
   durable run record instead of chat-only reasoning
+- when prompt history is growing and the next safe answer may already exist in
+  `.hforge/runtime/`, task artifacts, or decision records
 
 ## Discovery rule
 
@@ -58,3 +61,5 @@ AI content into the hidden `.hforge/` layer.
   `.hforge/agent-manifest.json` first and treat every surface it marks
   `treatAsProductCode: false` as AI-layer content rather than application code
 - use `docs/authoring/enhanced-skill-import.md`, `RESEARCH-SOURCES.md`, and `VALIDATION.md` only when provenance or import rationale matters
+- use `.agents/skills/token-budget-optimizer/SKILL.md` when the next safe step
+  depends on compacting context and reusing authoritative runtime surfaces

package/docs/authoring/token-budget-optimizer-port.md

@@ -0,0 +1,78 @@
+# Token Budget Optimizer Port Governance
+
+This document records how the March 2026 `hforge-token-budget-optimizer`
+archive was ported into Harness Forge.
+
+## Source pack
+
+- Pack name: `Harness Forge Token Budget Optimizer Skill Pack`
+- Inventory record: `manifests/catalog/token-budget-optimizer-import-inventory.json`
+- Imported scope:
+  - context compaction and reuse-first operating guidance
+  - token-surface audit heuristics
+  - a promotion ladder for choosing what belongs in active context
+  - a deterministic helper script for identifying high-value low-cost surfaces
+  - OpenAI-oriented runtime metadata in `agents/openai.yaml`
+
+## Canonical outcome
+
+Harness Forge now owns one canonical token-budget optimization surface at
+`skills/token-budget-optimizer/SKILL.md`.
+
+The port preserves the imported pack's distinctive value:
+
+- compact first, scan later
+- prefer authoritative runtime summaries over repeated broad repo reads
+- keep context costs explicit instead of relying on intuition alone
+- reuse task artifacts, decision records, repo maps, and command catalogs before
+  re-deriving them in chat
+
+## Artifact decisions
+
+| Imported artifact | Outcome | Project-owned destination | Why |
+| --- | --- | --- | --- |
+| `hforge-token-budget-optimizer/SKILL.md` | embed | `skills/token-budget-optimizer/SKILL.md` | the responsibility is distinct and should be first-class in the skill library |
+| `hforge-token-budget-optimizer/references/*.md` | embed | `skills/token-budget-optimizer/references/` | the audit dimensions, promotion ladder, scoring model, and report template are direct runtime guidance |
+| `hforge-token-budget-optimizer/scripts/inspect_token_surfaces.py` | embed | `skills/token-budget-optimizer/scripts/inspect_token_surfaces.py` | the helper is deterministic and useful across supported runtimes |
+| `hforge-token-budget-optimizer/agents/openai.yaml` | translate | this document plus the canonical wrapper | runtime-specific metadata becomes maintainer provenance instead of a universal contract |
+
+## Imported metadata summary
+
+The source pack carried one OpenAI-oriented descriptor under
+`agents/openai.yaml`. Harness Forge treats that file as provenance only and
+keeps cross-agent discovery in the project-owned wrapper under
+`.agents/skills/token-budget-optimizer/SKILL.md`.
+
+## Promotion intent
+
+This skill is intentionally promoted because it improves one of Harness Forge's
+core product promises: lower token burn through better reuse of installed
+runtime knowledge.
+
+The intended workflow is:
+
+1. consult existing runtime and task artifacts first
+2. keep only the smallest authoritative set of surfaces in active context
+3. expand into focused code reads only when the compact context is not enough
+
+## Runtime compatibility baseline
+
+- Codex: translated support through canonical skill, wrapper, and packaged helper
+  script
+- Claude Code: translated support through canonical skill, wrapper, and packaged
+  helper script
+- Cursor: guidance-first support
+- OpenCode: guidance-first support
+
+This keeps support claims honest while still making the skill broadly usable.
+
+## Acceptance rules for future updates
+
+- keep `manifests/catalog/token-budget-optimizer-import-inventory.json` aligned
+  with every imported artifact and follow-up translation
+- preserve one canonical `skills/token-budget-optimizer/` surface instead of
+  creating variants with overlapping responsibility
+- do not promote compaction in ways that hide release gates, support posture,
+  migration steps, or other safety-critical details
+- keep runtime-specific metadata maintainer-facing unless project-owned
+  cross-agent surfaces are explicitly added

package/manifests/catalog/compatibility-matrix.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-03-28T23:56:45.619Z",
+  "generatedAt": "2026-03-29T00:26:01.295Z",
   "entries": [
     {
       "subjectType": "language",
@@ -1264,6 +1264,14 @@
       "relatedId": "test-strategy-and-coverage",
       "supportLevel": "full"
     },
+    {
+      "subjectType": "target",
+      "subjectId": "claude-code",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "token-budget-optimizer",
+      "supportLevel": "full"
+    },
     {
       "subjectType": "target",
       "subjectId": "claude-code",
@@ -2099,6 +2107,14 @@
       "relatedId": "test-strategy-and-coverage",
       "supportLevel": "full"
     },
+    {
+      "subjectType": "target",
+      "subjectId": "codex",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "token-budget-optimizer",
+      "supportLevel": "full"
+    },
     {
       "subjectType": "target",
       "subjectId": "codex",
@@ -3019,6 +3035,15 @@
       "supportLevel": "partial",
       "notes": "Cursor only provides partial skill support for test-strategy-and-coverage."
     },
+    {
+      "subjectType": "target",
+      "subjectId": "cursor",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "token-budget-optimizer",
+      "supportLevel": "partial",
+      "notes": "Cursor only provides partial skill support for token-budget-optimizer."
+    },
     {
       "subjectType": "target",
       "subjectId": "cursor",
@@ -3940,6 +3965,15 @@
       "supportLevel": "partial",
       "notes": "OpenCode only provides partial skill support for test-strategy-and-coverage."
     },
+    {
+      "subjectType": "target",
+      "subjectId": "opencode",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "token-budget-optimizer",
+      "supportLevel": "partial",
+      "notes": "OpenCode only provides partial skill support for token-budget-optimizer."
+    },
     {
       "subjectType": "target",
       "subjectId": "opencode",

package/manifests/catalog/index.json

@@ -29,6 +29,7 @@
     "manifests/catalog/flow-artifacts.json",
     "manifests/catalog/engineering-assistant-import-inventory.json",
     "manifests/catalog/enhanced-skill-import-inventory.json",
+    "manifests/catalog/token-budget-optimizer-import-inventory.json",
     "manifests/catalog/package-surface.json",
     "manifests/catalog/seeded-knowledge-files.json"
   ],

package/manifests/catalog/package-surface.json

@@ -49,12 +49,14 @@
     ".agents/skills/javascript-engineering/SKILL.md",
     ".agents/skills/cloud-architect/SKILL.md",
     ".agents/skills/recursive-structured-analysis/SKILL.md",
+    ".agents/skills/token-budget-optimizer/SKILL.md",
     "docs/catalog/language-packs.md",
     "docs/catalog/framework-packs.md",
     "docs/templates/authoring.md",
     "docs/authoring/skills.md",
     "docs/authoring/engineering-assistant-port.md",
     "docs/authoring/enhanced-skill-import.md",
+    "docs/authoring/token-budget-optimizer-port.md",
     "docs/flow-orchestration.md",
     "docs/generated-artifacts.md",
     "docs/hooks/catalog.md",
@@ -100,6 +102,12 @@
     "skills/javascript-engineering",
     "skills/cloud-architect",
     "skills/recursive-structured-analysis/SKILL.md",
+    "skills/token-budget-optimizer/SKILL.md",
+    "skills/token-budget-optimizer/references/audit-dimensions.md",
+    "skills/token-budget-optimizer/references/promotion-ladder.md",
+    "skills/token-budget-optimizer/references/scoring-model.md",
+    "skills/token-budget-optimizer/references/report-template.md",
+    "skills/token-budget-optimizer/scripts/inspect_token_surfaces.py",
     "skills/repo-onboarding/SKILL.md",
     "skills/documentation-lookup/SKILL.md",
     "skills/security-scan/SKILL.md",
@@ -176,6 +184,7 @@
     "manifests/catalog/flow-artifacts.json",
     "manifests/catalog/engineering-assistant-import-inventory.json",
     "manifests/catalog/enhanced-skill-import-inventory.json",
+    "manifests/catalog/token-budget-optimizer-import-inventory.json",
     "manifests/catalog/seeded-knowledge-files.json",
     "manifests/catalog/package-surface.json",
     "manifests/hooks/index.json",
@@ -242,6 +251,7 @@
         "docs/maintenance-lifecycle.md",
         "docs/release-process.md",
         "docs/authoring/engineering-assistant-port.md",
+        "docs/authoring/token-budget-optimizer-port.md",
         "docs/observability.md",
         "docs/benchmark-scenarios.md",
         "docs/troubleshooting.md",
@@ -371,11 +381,14 @@
       "paths": [
         "manifests/catalog/engineering-assistant-import-inventory.json",
         "docs/authoring/engineering-assistant-port.md",
+        "docs/authoring/token-budget-optimizer-port.md",
         "skills/engineering-assistant/references/architecture.md",
         "skills/engineering-assistant/references/project-notes.md",
         "skills/engineering-assistant/references/change-discipline.md",
         "manifests/catalog/enhanced-skill-import-inventory.json",
+        "manifests/catalog/token-budget-optimizer-import-inventory.json",
         "docs/authoring/enhanced-skill-import.md",
+        "docs/authoring/token-budget-optimizer-port.md",
         "skills/repo-onboarding/references/discovery-checklist.md",
         "skills/architecture-decision-records/references/decision-rubric.md",
         "skills/api-contract-review/references/review-template.md",
@@ -426,6 +439,7 @@
         ".agents/skills/javascript-engineering/SKILL.md",
         ".agents/skills/cloud-architect/SKILL.md",
         ".agents/skills/recursive-structured-analysis/SKILL.md",
+        ".agents/skills/token-budget-optimizer/SKILL.md",
         "targets/codex/adapter.json",
         "targets/codex/runtime/.codex",
         "scripts/codex/apply-home-config.mjs",
@@ -457,6 +471,7 @@
         ".agents/skills/javascript-engineering/SKILL.md",
         ".agents/skills/cloud-architect/SKILL.md",
         ".agents/skills/recursive-structured-analysis/SKILL.md",
+        ".agents/skills/token-budget-optimizer/SKILL.md",
         "targets/claude-code/adapter.json",
         "targets/claude-code/runtime/.claude",
         "hooks"

package/manifests/catalog/token-budget-optimizer-import-inventory.json

@@ -0,0 +1,146 @@
+{
+  "packId": "token-budget-optimizer-2026-03",
+  "sourceName": "Harness Forge Token Budget Optimizer Skill Pack",
+  "sourceVersion": "2026-03-29-import",
+  "resourceRoots": [
+    "hforge-token-budget-optimizer/"
+  ],
+  "summary": "Governed port record for the imported token-budget-optimizer skill, preserving its context-compaction and reuse-first intent while translating the pack into project-owned canonical skill, wrapper, references, and helper surfaces.",
+  "validationScope": "The port validates canonical skill ownership, wrapper discovery coverage, package-surface registration, and front-door promotion for token-efficient agent operation. Runtime-native slash commands are intentionally not required for this skill.",
+  "researchScope": "The imported pack contributes context-compaction guidance, reuse-first operating rules, token-surface audit dimensions, a scoring model, a promotion ladder, and a deterministic helper script for identifying high-value low-cost runtime surfaces.",
+  "entries": [
+    {
+      "artifactPath": "hforge-token-budget-optimizer/SKILL.md",
+      "artifactType": "skill",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The imported pack owns a distinct runtime responsibility around context compaction and reuse-first navigation, so it should ship as one canonical skill rather than being folded into a broader helper.",
+      "destinationPath": "skills/token-budget-optimizer/SKILL.md",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/references/audit-dimensions.md",
+      "artifactType": "reference",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The audit dimensions are direct supporting guidance for deciding which surfaces deserve active prompt space.",
+      "destinationPath": "skills/token-budget-optimizer/references/audit-dimensions.md",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/references/promotion-ladder.md",
+      "artifactType": "reference",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The promotion ladder turns the imported context-reuse idea into a reusable operating model for agents in installed workspaces.",
+      "destinationPath": "skills/token-budget-optimizer/references/promotion-ladder.md",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/references/scoring-model.md",
+      "artifactType": "reference",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The scoring model is a direct supporting heuristic for choosing low-cost high-authority context surfaces.",
+      "destinationPath": "skills/token-budget-optimizer/references/scoring-model.md",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/references/report-template.md",
+      "artifactType": "reference",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The report template preserves the imported pack's goal of making compaction decisions explicit and reviewable.",
+      "destinationPath": "skills/token-budget-optimizer/references/report-template.md",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/scripts/inspect_token_surfaces.py",
+      "artifactType": "script",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The helper script is deterministic, package-owned, and directly useful for ranking reusable context surfaces before an agent expands prompt history.",
+      "destinationPath": "skills/token-budget-optimizer/scripts/inspect_token_surfaces.py",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/agents/openai.yaml",
+      "artifactType": "metadata",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "translate",
+      "decisionReason": "The source runtime metadata is treated as pack provenance while the project expresses cross-agent discovery through the canonical wrapper and maintainer-facing port note.",
+      "destinationPath": "docs/authoring/token-budget-optimizer-port.md",
+      "reviewStatus": "accepted"
+    },
+    {
+      "artifactPath": "hforge-token-budget-optimizer/.agents-wrapper",
+      "artifactType": "wrapper",
+      "skillId": "token-budget-optimizer",
+      "existingProjectSurface": null,
+      "decision": "embed",
+      "decisionReason": "The imported skill needs a visible discovery wrapper so Codex and Claude Code can find the canonical token-optimization workflow quickly.",
+      "destinationPath": ".agents/skills/token-budget-optimizer/SKILL.md",
+      "reviewStatus": "accepted"
+    }
+  ],
+  "compatibilityProfiles": [
+    {
+      "targetId": "codex",
+      "supportLevel": "translated",
+      "metadataMode": "translated",
+      "helperMode": "packaged-script",
+      "notes": "Codex consumes the canonical skill and wrapper directly, and can optionally run the helper script when a deterministic token-surface audit is useful."
+    },
+    {
+      "targetId": "claude-code",
+      "supportLevel": "translated",
+      "metadataMode": "translated",
+      "helperMode": "packaged-script",
+      "notes": "Claude Code consumes the same canonical skill and wrapper, with the helper script available when the operator wants explicit compaction evidence."
+    },
+    {
+      "targetId": "cursor",
+      "supportLevel": "guidance-only",
+      "metadataMode": "unsupported",
+      "helperMode": "documentation-first",
+      "notes": "Cursor can follow the guidance surfaces, but the primary promotion path is still the canonical skill and maintainer note."
+    },
+    {
+      "targetId": "opencode",
+      "supportLevel": "guidance-only",
+      "metadataMode": "unsupported",
+      "helperMode": "documentation-first",
+      "notes": "OpenCode receives the canonical guidance without overstating runtime-native metadata parity."
+    }
+  ],
+  "portingRules": [
+    {
+      "ruleId": "promote-reuse-first-runtime-skills",
+      "matchCriteria": "An imported skill owns a distinct responsibility for context compaction, reuse-first reasoning, or token-cost discipline.",
+      "preferredOutcome": "embed",
+      "requiredFollowUps": [
+        "create the canonical skill under skills/",
+        "ship supporting references and helper surfaces under the same skill directory",
+        "add a discovery wrapper under .agents/skills/",
+        "register the skill in package-surface and front-door docs"
+      ]
+    },
+    {
+      "ruleId": "translate-runtime-specific-metadata",
+      "matchCriteria": "The imported artifact is runtime-specific metadata rather than canonical cross-agent guidance.",
+      "preferredOutcome": "translate",
+      "requiredFollowUps": [
+        "summarize the metadata in maintainer-facing provenance",
+        "avoid claiming universal runtime-native parity",
+        "keep the canonical wrapper and skill as the active discovery path"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-forge/cli",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Harness Forge: modular agentic AI workspace installer, catalog, and workflow runtime.",
   "type": "module",
   "bin": {

package/skills/README.md

@@ -57,6 +57,7 @@ and modernization guidance sourced into project-owned `references/` directories.
 - `skills/security-scan/`
 - `skills/release-readiness/`
 - `skills/architecture-decision-records/`
+- `skills/token-budget-optimizer/`
 
 ## Workload-specialized skills
 
@@ -92,3 +93,8 @@ maintainer-facing provenance instead of shipping duplicate skill identities.
 Single-skill ports such as `engineering-assistant` should preserve the same
 discipline through `manifests/catalog/engineering-assistant-import-inventory.json`
 and `docs/authoring/engineering-assistant-port.md`.
+
+Context-compaction ports such as `token-budget-optimizer` should preserve the
+same discipline through
+`manifests/catalog/token-budget-optimizer-import-inventory.json` and
+`docs/authoring/token-budget-optimizer-port.md`.

package/skills/token-budget-optimizer/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: token-budget-optimizer
+description: compact context, reuse existing runtime artifacts, and choose the smallest authoritative surface before expanding prompt history. use when the task is growing large, when earlier repo intelligence already exists, or when repeated rescans would waste tokens without adding new evidence.
+---
+
+# Token Budget Optimizer
+
+## Trigger Signals
+
+- the prompt is getting long and earlier repo context is being repeated
+- the repo already has `AGENTS.md`, `.hforge/runtime/`, specs, plans, or review artifacts that can answer the next question
+- the task is investigative or iterative enough that careless re-reading will waste tokens
+- the agent is about to scan broad directory trees before checking existing runtime summaries
+
+## Inspect First
+
+- `.hforge/agent-manifest.json` and `.hforge/generated/agent-command-catalog.json`
+- `.hforge/runtime/index.json`, `.hforge/runtime/repo/repo-map.json`, and `.hforge/runtime/repo/recommendations.json`
+- active guidance bridges such as `AGENTS.md`, `CLAUDE.md`, and `.agents/skills/<skill>/SKILL.md`
+- any existing `spec.md`, `plan.md`, `tasks.md`, review output, or decision record relevant to the current task
+- `skills/token-budget-optimizer/scripts/inspect_token_surfaces.py` when a deterministic token-surface audit would help
+
+## Workflow
+
+1. identify the concrete question the agent must answer next and avoid reading more than that question requires
+2. rank existing surfaces by authority, freshness, and cost, preferring hidden runtime summaries and durable artifacts before broad source scans
+3. reuse prior findings, repo maps, decision records, and task artifacts instead of re-deriving them from scratch
+4. compact the active context into a short working set: current goal, authoritative surfaces, open questions, and the next small evidence step
+5. escalate to deeper reads only when the compacted working set cannot answer the task safely
+
+## Output Contract
+
+- a short context budget summary with the current goal and the smallest authoritative surfaces to keep loaded
+- a reuse plan listing which runtime artifacts, docs, or task artifacts should be trusted instead of reread
+- compaction candidates describing what can be summarized once and then dropped from active context
+- unresolved gaps that still require new evidence or deeper file reads
+
+## Failure Modes
+
+- runtime artifacts are stale, missing, or do not cover the active question
+- the task is genuinely novel and prior summaries are no longer trustworthy
+- the agent mistakes low-cost summaries for high-authority truth and skips required verification
+
+## Escalation
+
+- escalate when the repo has conflicting guidance across `AGENTS.md`, runtime summaries, and product code
+- escalate when token saving would hide a risky detail such as a release gate, migration step, or support constraint
+- escalate when there is no reliable compact surface and the agent must build a new authoritative summary first
+
+## References
+
+- `skills/token-budget-optimizer/references/audit-dimensions.md`
+- `skills/token-budget-optimizer/references/promotion-ladder.md`
+- `skills/token-budget-optimizer/references/scoring-model.md`
+- `skills/token-budget-optimizer/references/report-template.md`
+- `skills/token-budget-optimizer/scripts/inspect_token_surfaces.py`

package/skills/token-budget-optimizer/references/audit-dimensions.md

@@ -0,0 +1,37 @@
+# Token Surface Audit Dimensions
+
+Use these dimensions when deciding whether a surface deserves active context.
+
+## Authority
+
+- highest: generated or maintained runtime truth such as `.hforge/agent-manifest.json`, `.hforge/generated/agent-command-catalog.json`, and current runtime indexes
+- medium: maintained docs and active skill contracts
+- lower: old notes, ad-hoc chat summaries, or broad source scans without task focus
+
+## Freshness
+
+- prefer artifacts regenerated after the latest repo changes
+- downgrade summaries that predate major install, refresh, or architecture changes
+- if freshness is unclear, verify with `status`, `refresh`, or a targeted file read
+
+## Reuse value
+
+- high when the surface already answers the current question directly
+- medium when the surface narrows the search space meaningfully
+- low when the surface only restates generic repo facts or marketing prose
+
+## Token cost
+
+- very low: compact JSON summaries, short skill wrappers, direct command catalogs
+- medium: short markdown guides and specific reference docs
+- high: large source trees, broad recursive scans, or entire repo reviews with no focus
+
+## Risk of omission
+
+- high risk means the surface guards support claims, release gates, migrations, security rules, or architecture decisions
+- low risk means the surface is descriptive but not safety-critical
+
+## Recommended decision rule
+
+Keep in active context only the smallest set of high-authority, sufficiently
+fresh surfaces that answer the current question without hiding a known risk.

package/skills/token-budget-optimizer/references/promotion-ladder.md

@@ -0,0 +1,44 @@
+# Context Promotion Ladder
+
+Use this ladder to decide what belongs in active prompt context.
+
+## Level 1: Discovery only
+
+- wrappers in `.agents/skills/`
+- short command docs
+- repo root guidance bridges
+
+Use these to choose the next canonical surface quickly.
+
+## Level 2: Canonical operating surfaces
+
+- `.hforge/agent-manifest.json`
+- `.hforge/generated/agent-command-catalog.json`
+- canonical skill contracts under `.hforge/library/skills/`
+- runtime indexes and repo summaries
+
+Prefer these before reading broad product code.
+
+## Level 3: Task-bound artifacts
+
+- spec, plan, and task documents
+- task-runtime artifacts
+- decision records
+- review summaries and validation outputs
+
+Promote these when the work is already scoped and historical context matters.
+
+## Level 4: Focused code evidence
+
+- only the files needed to resolve an active question
+- only the specific function, module, schema, or config block that matters
+
+Do not jump here until the earlier levels stop being enough.
+
+## Level 5: Broad exploratory scans
+
+- full repo walks
+- many-file comparisons
+- recursive investigation sessions
+
+Use these only when lower-cost surfaces cannot answer the question safely.

package/skills/token-budget-optimizer/references/report-template.md

@@ -0,0 +1,25 @@
+# Token Budget Report Template
+
+## Current goal
+
+- What question must be answered next?
+
+## Keep loaded
+
+- Which 3-6 surfaces are authoritative enough to stay in active context?
+
+## Reuse instead of reread
+
+- Which runtime artifacts, prior summaries, or task docs already cover the needed context?
+
+## Compact and drop
+
+- Which broad notes, repeated chat summaries, or low-authority reads can be collapsed into one sentence and removed from active context?
+
+## New evidence still required
+
+- Which focused files or commands still need to be read or run?
+
+## Risk notes
+
+- What important detail would be dangerous to over-compress?

package/skills/token-budget-optimizer/references/scoring-model.md

@@ -0,0 +1,43 @@
+# Token Budget Scoring Model
+
+Use a simple score to compare candidate context surfaces.
+
+## Formula
+
+`score = authority + freshness + reuseValue - tokenCost - ambiguityPenalty`
+
+Each dimension can be scored from `0` to `3`.
+
+## Guidance
+
+- authority:
+  - `3` canonical machine-readable runtime truth
+  - `2` maintained human-readable canonical docs
+  - `1` narrow ad-hoc notes or inferred summaries
+  - `0` stale or untrusted context
+- freshness:
+  - `3` generated or edited after the relevant change
+  - `2` likely current but not recently verified
+  - `1` possibly stale
+  - `0` known stale
+- reuseValue:
+  - `3` directly answers the next question
+  - `2` sharply narrows what must be read next
+  - `1` weakly helpful
+  - `0` mostly decorative
+- tokenCost:
+  - `3` large or diffuse
+  - `2` moderate
+  - `1` small
+  - `0` tiny
+- ambiguityPenalty:
+  - `3` likely to mislead without verification
+  - `2` needs careful cross-checking
+  - `1` low ambiguity
+  - `0` explicit and stable
+
+## Usage rule
+
+Prefer the smallest set of surfaces with the highest positive score, then
+validate any high-risk claim with one focused evidence read instead of a broad
+context expansion.

package/skills/token-budget-optimizer/scripts/inspect_token_surfaces.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Inspect likely high-value context surfaces for token-efficient agent work."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+SURFACES = [
+    ("AGENTS.md", "guidance", 3, 3, 3, 1),
+    ("CLAUDE.md", "guidance", 3, 3, 2, 1),
+    (".hforge/agent-manifest.json", "runtime", 3, 3, 3, 1),
+    (".hforge/generated/agent-command-catalog.json", "runtime", 3, 3, 3, 1),
+    (".hforge/runtime/index.json", "runtime", 3, 3, 2, 1),
+    (".hforge/runtime/repo/repo-map.json", "runtime", 3, 2, 3, 1),
+    (".hforge/runtime/repo/recommendations.json", "runtime", 3, 2, 3, 1),
+    (".hforge/runtime/repo/instruction-plan.json", "runtime", 3, 2, 2, 1),
+    ("README.md", "docs", 2, 2, 1, 2),
+    (".specify/spec.md", "workflow", 2, 2, 3, 2),
+    (".specify/plan.md", "workflow", 2, 2, 3, 2),
+    (".specify/tasks.md", "workflow", 2, 2, 3, 2),
+]
+
+
+def score(authority: int, freshness: int, reuse_value: int, token_cost: int) -> int:
+    return authority + freshness + reuse_value - token_cost
+
+
+def main() -> int:
+    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd().resolve()
+    found = []
+    missing = []
+
+    for relative_path, category, authority, freshness, reuse_value, token_cost in SURFACES:
+        absolute_path = root / relative_path
+        entry = {
+            "path": relative_path,
+            "category": category,
+            "score": score(authority, freshness, reuse_value, token_cost),
+            "authority": authority,
+            "freshness": freshness,
+            "reuseValue": reuse_value,
+            "tokenCost": token_cost,
+        }
+        if absolute_path.exists():
+            entry["sizeBytes"] = absolute_path.stat().st_size
+            found.append(entry)
+        else:
+            missing.append(entry)
+
+    found.sort(key=lambda item: (-item["score"], item["path"]))
+    missing.sort(key=lambda item: (-item["score"], item["path"]))
+
+    result = {
+        "workspaceRoot": str(root),
+        "recommendedKeepLoaded": found[:6],
+        "recommendedFallbackReads": found[6:10],
+        "missingButUseful": missing[:6],
+    }
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())