@harness-forge/cli 1.2.2 → 1.2.4

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/docs/commands.md

@@ -69,8 +69,19 @@ CLI. Harness Forge ships command docs for those environments under `commands/`.
 
 Examples:
 
+- `/hforge-init` to bootstrap or refresh the project-owned Harness Forge runtime
 - `/hforge-analyze` to force installed-runtime inspection before coding
-- `commands/hforge-analyze.md` as the canonical packaged command surface
+- `/hforge-review` to inspect drift, decision coverage, and stale runtime artifacts
+- `/hforge-refresh` to regenerate runtime summaries after install or repo changes
+- `/hforge-decide` to capture durable ASR or ADR records
+- `/hforge-status` to inspect current workspace state before acting
+- `/hforge-commands` to inspect the shipped command catalog before inventing commands
+- `/hforge-recommend` to run repo-intelligence and recommendation flows
+- `/hforge-cartograph` to inspect repo topology, boundaries, and hotspots
+- `/hforge-task` to inspect task-runtime folders and task packs
+- `/hforge-recursive` to escalate difficult work into recursive structured analysis
+- `/hforge-update` to preview or apply a non-destructive package refresh
+- `commands/hforge-init.md`, `commands/hforge-analyze.md`, `commands/hforge-review.md`, `commands/hforge-refresh.md`, `commands/hforge-decide.md`, `commands/hforge-status.md`, `commands/hforge-commands.md`, `commands/hforge-recommend.md`, `commands/hforge-cartograph.md`, `commands/hforge-task.md`, `commands/hforge-recursive.md`, and `commands/hforge-update.md` as the canonical packaged command surfaces
 - `commands/plan.md` and `commands/test.md` for broader planning and validation guidance
 
 Treat these as agent-facing prompt entrypoints, not replacements for the CLI.

package/manifests/bundles/core.json

@@ -38,6 +38,17 @@
       "description": "Core command guidance and usage patterns.",
       "paths": [
         "commands/hforge-analyze.md",
+        "commands/hforge-cartograph.md",
+        "commands/hforge-commands.md",
+        "commands/hforge-decide.md",
+        "commands/hforge-init.md",
+        "commands/hforge-recommend.md",
+        "commands/hforge-recursive.md",
+        "commands/hforge-refresh.md",
+        "commands/hforge-review.md",
+        "commands/hforge-status.md",
+        "commands/hforge-task.md",
+        "commands/hforge-update.md",
         "commands/plan.md",
         "commands/test.md",
         "contexts/dev.md",

package/manifests/catalog/compatibility-matrix.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-03-28T22:25:09.358Z",
+  "generatedAt": "2026-03-29T00:26:01.295Z",
   "entries": [
     {
       "subjectType": "language",
@@ -960,6 +960,46 @@
       "relatedId": "go-engineering",
       "supportLevel": "full"
     },
+    {
+      "subjectType": "target",
+      "subjectId": "claude-code",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-analyze",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "claude-code",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-decide",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "claude-code",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-init",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "claude-code",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-refresh",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "claude-code",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-review",
+      "supportLevel": "full"
+    },
     {
       "subjectType": "target",
       "subjectId": "claude-code",
@@ -1224,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",
@@ -1755,6 +1803,46 @@
       "relatedId": "go-engineering",
       "supportLevel": "full"
     },
+    {
+      "subjectType": "target",
+      "subjectId": "codex",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-analyze",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "codex",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-decide",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "codex",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-init",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "codex",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-refresh",
+      "supportLevel": "full"
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "codex",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-review",
+      "supportLevel": "full"
+    },
     {
       "subjectType": "target",
       "subjectId": "codex",
@@ -2019,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",
@@ -2597,6 +2693,51 @@
       "supportLevel": "partial",
       "notes": "Cursor only provides partial skill support for go-engineering."
     },
+    {
+      "subjectType": "target",
+      "subjectId": "cursor",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-analyze",
+      "supportLevel": "partial",
+      "notes": "Cursor only provides partial skill support for hforge-analyze."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "cursor",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-decide",
+      "supportLevel": "partial",
+      "notes": "Cursor only provides partial skill support for hforge-decide."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "cursor",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-init",
+      "supportLevel": "partial",
+      "notes": "Cursor only provides partial skill support for hforge-init."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "cursor",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-refresh",
+      "supportLevel": "partial",
+      "notes": "Cursor only provides partial skill support for hforge-refresh."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "cursor",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-review",
+      "supportLevel": "partial",
+      "notes": "Cursor only provides partial skill support for hforge-review."
+    },
     {
       "subjectType": "target",
       "subjectId": "cursor",
@@ -2894,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",
@@ -3473,6 +3623,51 @@
       "supportLevel": "partial",
       "notes": "OpenCode only provides partial skill support for go-engineering."
     },
+    {
+      "subjectType": "target",
+      "subjectId": "opencode",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-analyze",
+      "supportLevel": "partial",
+      "notes": "OpenCode only provides partial skill support for hforge-analyze."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "opencode",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-decide",
+      "supportLevel": "partial",
+      "notes": "OpenCode only provides partial skill support for hforge-decide."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "opencode",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-init",
+      "supportLevel": "partial",
+      "notes": "OpenCode only provides partial skill support for hforge-init."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "opencode",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-refresh",
+      "supportLevel": "partial",
+      "notes": "OpenCode only provides partial skill support for hforge-refresh."
+    },
+    {
+      "subjectType": "target",
+      "subjectId": "opencode",
+      "relationType": "supports",
+      "relatedType": "skill",
+      "relatedId": "hforge-review",
+      "supportLevel": "partial",
+      "notes": "OpenCode only provides partial skill support for hforge-review."
+    },
     {
       "subjectType": "target",
       "subjectId": "opencode",
@@ -3770,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",
@@ -65,12 +67,33 @@
     "docs/benchmark-scenarios.md",
     "docs/release-process.md",
     "commands/hforge-analyze.md",
+    "commands/hforge-cartograph.md",
+    "commands/hforge-commands.md",
+    "commands/hforge-decide.md",
+    "commands/hforge-init.md",
+    "commands/hforge-recommend.md",
+    "commands/hforge-recursive.md",
+    "commands/hforge-refresh.md",
+    "commands/hforge-review.md",
+    "commands/hforge-status.md",
+    "commands/hforge-task.md",
+    "commands/hforge-update.md",
     "commands/plan.md",
     "commands/test.md",
+    ".agents/skills/hforge-analyze/SKILL.md",
+    ".agents/skills/hforge-decide/SKILL.md",
+    ".agents/skills/hforge-init/SKILL.md",
+    ".agents/skills/hforge-refresh/SKILL.md",
+    ".agents/skills/hforge-review/SKILL.md",
     "knowledge-bases/seeded/README.md",
     "rules/common/README.md",
     "skills/README.md",
     "skills/engineering-assistant/SKILL.md",
+    "skills/hforge-analyze/SKILL.md",
+    "skills/hforge-decide/SKILL.md",
+    "skills/hforge-init/SKILL.md",
+    "skills/hforge-refresh/SKILL.md",
+    "skills/hforge-review/SKILL.md",
     "skills/typescript-engineering/SKILL.md",
     "skills/java-engineering/SKILL.md",
     "skills/dotnet-engineering/SKILL.md",
@@ -79,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",
@@ -155,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",
@@ -221,11 +251,23 @@
         "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",
         "docs/versioning-and-migration.md",
         "commands/hforge-analyze.md",
+        "commands/hforge-cartograph.md",
+        "commands/hforge-commands.md",
+        "commands/hforge-decide.md",
+        "commands/hforge-init.md",
+        "commands/hforge-recommend.md",
+        "commands/hforge-recursive.md",
+        "commands/hforge-refresh.md",
+        "commands/hforge-review.md",
+        "commands/hforge-status.md",
+        "commands/hforge-task.md",
+        "commands/hforge-update.md",
         "commands/plan.md",
         "commands/test.md",
         "hooks",
@@ -339,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",
@@ -376,6 +421,11 @@
         ".specify",
         ".agents/skills",
         ".agents/skills/repo-onboarding/SKILL.md",
+        ".agents/skills/hforge-analyze/SKILL.md",
+        ".agents/skills/hforge-decide/SKILL.md",
+        ".agents/skills/hforge-init/SKILL.md",
+        ".agents/skills/hforge-refresh/SKILL.md",
+        ".agents/skills/hforge-review/SKILL.md",
         ".agents/skills/architecture-decision-records/SKILL.md",
         ".agents/skills/api-contract-review/SKILL.md",
         ".agents/skills/db-migration-review/SKILL.md",
@@ -389,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",
@@ -402,6 +453,11 @@
         ".specify",
         ".agents/skills",
         ".agents/skills/repo-onboarding/SKILL.md",
+        ".agents/skills/hforge-analyze/SKILL.md",
+        ".agents/skills/hforge-decide/SKILL.md",
+        ".agents/skills/hforge-init/SKILL.md",
+        ".agents/skills/hforge-refresh/SKILL.md",
+        ".agents/skills/hforge-review/SKILL.md",
         ".agents/skills/architecture-decision-records/SKILL.md",
         ".agents/skills/api-contract-review/SKILL.md",
         ".agents/skills/db-migration-review/SKILL.md",
@@ -415,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"