@harness-forge/cli 1.2.2 → 1.2.4

package/.agents/skills/hforge-analyze/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: "hforge-analyze"
+description: "Analyze the current repository using Harness Forge runtime surfaces, refresh stale findings when needed, summarize repo shape and risks, and promote architecture-significant findings into durable notes or decision candidates."
+compatibility: "Works best in repositories already initialized with Harness Forge, but may bootstrap first if needed."
+metadata:
+  author: "harness-forge"
+  source: "skills/hforge-analyze/SKILL.md"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You must consider the user input before proceeding.
+
+## Goal
+
+Use Harness Forge as the primary repo-analysis system instead of re-deriving the repository state from scratch.
+
+## Execution
+
+1. Treat the text after `/hforge-analyze` as the focus area or analysis lens.
+2. Inspect `.hforge/agent-manifest.json`, `.hforge/runtime/index.json`, and `.hforge/runtime/repo/` first when present.
+3. Run `hforge status --root . --json`.
+4. If runtime artifacts are missing or stale, run `hforge refresh --root . --json`.
+5. Run `hforge review --root . --json` when health, decision coverage, or stale task state matters.
+6. Summarize:
+   - repo shape
+   - dominant languages and frameworks
+   - risks and validation gaps
+   - recommended next actions
+7. When the analysis reveals architecture-significant changes, promote them into an ASR or ADR under `.hforge/runtime/decisions/`.
+8. Keep product code unchanged unless the user explicitly asks for edits.

package/.agents/skills/hforge-decide/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "hforge-decide"
+description: "Create or update a durable ASR or ADR for architecture-significant repository findings so the reasoning survives the current session."
+compatibility: "Works best in Harness Forge workspaces with runtime decision surfaces."
+metadata:
+  author: "harness-forge"
+  source: "skills/hforge-decide/SKILL.md"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You must consider the user input before proceeding.
+
+## Goal
+
+Turn a meaningful technical choice into a durable decision artifact under `.hforge/runtime/decisions/`.
+
+## Execution
+
+1. Treat the text after `/hforge-decide` as the decision topic or scope.
+2. Inspect `.hforge/runtime/decisions/index.json` first when present.
+3. Inspect the most relevant task pack, impact analysis, repo findings, and existing related decisions.
+4. Use an ASR when the direction is still being evaluated and an ADR when the decision is accepted enough to guide future work.
+5. Write a concise, reviewable record with context, decision, consequences, and follow-up items.
+6. Explicitly link superseded or related decisions when applicable.

package/.agents/skills/hforge-init/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: "hforge-init"
+description: "Bootstrap Harness Forge in the current repository, install or refresh the project-owned runtime, and summarize the managed surfaces that are now available."
+compatibility: "Requires a repository where Harness Forge can write project-owned runtime files."
+metadata:
+  author: "harness-forge"
+  source: "skills/hforge-init/SKILL.md"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You must consider the user input before proceeding.
+
+## Goal
+
+Initialize the current repository for Harness Forge usage and make the installed runtime easy to inspect and use.
+
+## Execution
+
+1. Treat the text after `/hforge-init` as optional setup hints such as target preference or setup intent.
+2. Check whether `.hforge/agent-manifest.json` or `.hforge/runtime/index.json` already exists.
+3. Run `hforge status --root . --json` first.
+4. If the repository is not initialized or required target runtime surfaces are missing, run `hforge bootstrap --root . --yes`.
+5. Run `hforge refresh --root . --json` after bootstrap or whenever runtime summaries look incomplete.
+6. Summarize:
+   - detected targets
+   - installed managed surfaces
+   - runtime artifacts now available
+   - the best next command to run
+7. If bootstrap cannot run safely, explain the blocker and list the minimum next manual step.

package/.agents/skills/hforge-refresh/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: "hforge-refresh"
+description: "Refresh Harness Forge runtime summaries and generated state after install changes, content updates, or stale repo-intelligence artifacts."
+compatibility: "Requires a repository where Harness Forge runtime artifacts already exist or can be bootstrapped."
+metadata:
+  author: "harness-forge"
+  source: "skills/hforge-refresh/SKILL.md"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You must consider the user input before proceeding.
+
+## Goal
+
+Regenerate the shared runtime summaries and report what changed.
+
+## Execution
+
+1. Treat the text after `/hforge-refresh` as optional focus notes.
+2. Run `hforge refresh --root . --json`.
+3. Run `hforge status --root . --json` after refresh when install-state confirmation matters.
+4. Summarize refreshed runtime artifacts, any missing prerequisites, and the best next command.
+5. If refresh fails because the repo is not initialized, recommend `/hforge-init` as the next step.

package/.agents/skills/hforge-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "hforge-review"
+description: "Review Harness Forge runtime health, decision coverage, drift, stale task artifacts, and managed-surface integrity for the current repository."
+compatibility: "Requires an initialized Harness Forge workspace for full value."
+metadata:
+  author: "harness-forge"
+  source: "skills/hforge-review/SKILL.md"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You must consider the user input before proceeding.
+
+## Goal
+
+Produce a runtime-health review instead of a generic repo summary.
+
+## Execution
+
+1. Treat the text after `/hforge-review` as optional review emphasis.
+2. Run `hforge review --root . --json` first.
+3. If the review suggests installation drift or missing managed surfaces, run `hforge doctor --root . --json`.
+4. If package-surface integrity is in doubt, run `hforge audit --root . --json`.
+5. Summarize blockers, warnings, stale artifacts, decision gaps, and the highest-value cleanup steps.
+6. Do not mutate runtime state unless the user asks for a follow-up fix.

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

@@ -12,7 +12,7 @@ Use the thin visible bridge surfaces first in installed workspaces:
 - `.hforge/runtime/index.json` and `.hforge/runtime/README.md` for shared runtime state and bridge resolution
 - `.hforge/generated/agent-command-catalog.json` for safe command discovery
 - `docs/agent-usage-playbook.md` for concrete command-resolution guidance, operator prompts, and examples that promote actual Harness Forge usage
-- `commands/hforge-analyze.md` for runtimes that support slash-style markdown command entrypoints such as `/hforge-analyze`
+- `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` for runtimes that support slash-style markdown command entrypoints such as `/hforge-analyze`
 
 ## Mode awareness
 
@@ -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
 
@@ -92,7 +95,7 @@ Use the thin visible bridge surfaces first in installed workspaces:
 ## Command discovery and execution
 
 - for first use in a repo, prefer `npx @harness-forge/cli`
-- prefer `hforge commands --json` or `.hforge/generated/agent-command-catalog.json` to discover shipped CLI commands and npm scripts before inventing a command path
+- prefer `hforge commands --json` or `.hforge/generated/agent-command-catalog.json` to discover shipped CLI commands, markdown-backed agent commands, and npm scripts before inventing a command path
 - resolve CLI execution in this order inside an installed workspace: `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
 - prefer `hforge status --root . --json` to inspect the installed workspace state
 - prefer `hforge catalog --json` to review installed bundles, packs, and profiles
@@ -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,11 +725,14 @@ 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-analyze`, alongside supporting
-command surfaces like `commands/plan.md` and `commands/test.md`.
+triggerable command docs such as `/hforge-init`, `/hforge-analyze`,
+`/hforge-review`, `/hforge-refresh`, `/hforge-decide`, `/hforge-status`,
+`/hforge-commands`, `/hforge-recommend`, `/hforge-cartograph`,
+`/hforge-task`, `/hforge-recursive`, and `/hforge-update`, alongside
+supporting command surfaces like `commands/plan.md` and `commands/test.md`.
 
 ---
 

package/commands/hforge-cartograph.md

@@ -0,0 +1,35 @@
+---
+id: command-hforge-cartograph
+kind: command
+title: Harness Cartograph Command
+summary: Use when an agent should build or inspect repo maps, service boundaries, hotspots, and validation gaps before planning or implementation.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Cartograph Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-cartograph` followed by the repo area, risk, or architecture
+question that needs deeper investigation.
+
+## Expected workflow
+
+1. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+2. run `hforge cartograph . --json`
+3. when boundary or recommendation context is needed, run `hforge classify-boundaries . --json` and `hforge recommend . --json`
+4. summarize dominant languages, likely service boundaries, risk hotspots, validation gaps, and the next best command or skill to use
+
+## Failure behavior
+
+- if the workspace is not initialized, the command may still run through `npx @harness-forge/cli`
+- keep repo topology and support claims tied to the generated evidence, not inference alone

package/commands/hforge-commands.md

@@ -0,0 +1,34 @@
+---
+id: command-hforge-commands
+kind: command
+title: Harness Commands Command
+summary: Use when an agent should inspect the shipped Harness Forge command catalog before inventing an execution path.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Commands Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-commands`.
+
+## Expected workflow
+
+1. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+2. run `hforge commands --json`
+3. prefer the agent-safe variants and the markdown command entrypoints from the generated catalog before inventing commands
+4. summarize the best command or trigger for the task at hand
+
+## Failure behavior
+
+- if the command catalog is missing, recommend `hforge refresh --root . --json`
+- if the workspace is not initialized, recommend `/hforge-init`

package/commands/hforge-decide.md

@@ -0,0 +1,35 @@
+---
+id: command-hforge-decide
+kind: command
+title: Harness Decide Command
+summary: Use when an agent should capture an architecture-significant choice as a durable ASR or ADR inside the Harness Forge runtime.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Decide Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-decide` followed by the decision topic or scope.
+
+## Expected workflow
+
+1. inspect `.hforge/runtime/decisions/index.json`, relevant task-runtime artifacts, and runtime findings first
+2. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+3. choose ASR when the direction is still being evaluated and ADR when the decision is stable enough to guide later work
+4. write or update the durable record under `.hforge/runtime/decisions/`
+5. summarize the decision statement, rationale, constraints, consequences, and related runtime evidence
+
+## Failure behavior
+
+- if the decision is still too vague, say so and list the missing evidence
+- if the new record would contradict an accepted ADR, call that out explicitly before writing

package/commands/hforge-init.md

@@ -0,0 +1,37 @@
+---
+id: command-hforge-init
+kind: command
+title: Harness Init Command
+summary: Use when an agent should initialize or bootstrap Harness Forge in the current repository before deeper analysis or implementation.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Init Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-init` followed by optional target or setup hints.
+
+## Expected workflow
+
+1. inspect `AGENTS.md`, `.hforge/agent-manifest.json`, and `.hforge/runtime/index.json` when present
+2. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+3. run `hforge status --root . --json` before bootstrapping blindly
+4. run `hforge bootstrap --root . --yes` when the repo is not initialized or required target surfaces are missing
+5. follow with `hforge refresh --root . --json` so runtime summaries and indexes are current
+6. summarize detected targets, installed surfaces, and the best next command
+
+## Failure behavior
+
+- if the repo is not writable, explain the blocker instead of retrying blindly
+- if the launcher is unavailable, fall back to `npx @harness-forge/cli`
+- do not claim initialization succeeded unless the managed runtime surfaces now exist

package/commands/hforge-recommend.md

@@ -0,0 +1,34 @@
+---
+id: command-hforge-recommend
+kind: command
+title: Harness Recommend Command
+summary: Use when an agent should run repo-intelligence and recommendation flows before setup, architecture, or implementation work.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Recommend Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-recommend` followed by the active repo question or focus area.
+
+## Expected workflow
+
+1. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+2. run `hforge recommend . --json`
+3. when the task needs deeper shape analysis, run `hforge cartograph . --json` and `hforge classify-boundaries . --json`
+4. summarize dominant languages, frameworks, risks, validation gaps, and the most relevant recommended bundles, skills, or profiles
+
+## Failure behavior
+
+- if the workspace is not initialized, the command may still run from `npx @harness-forge/cli`
+- keep support claims tied to recommendation evidence, not assumptions

package/commands/hforge-recursive.md

@@ -0,0 +1,34 @@
+---
+id: command-hforge-recursive
+kind: command
+title: Harness Recursive Command
+summary: Use when an agent should escalate difficult work into recursive structured-analysis with durable session and run artifacts.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+languages:
+  - all
+generated: false
+---
+# Harness Recursive Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-recursive` followed by the investigation goal, task id, or
+the specific recursive structured-analysis step you want to run.
+
+## Expected workflow
+
+1. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+2. run `hforge recursive capabilities --root . --json` before claiming language support
+3. create or inspect a session with `hforge recursive plan ... --root . --json` or `hforge recursive inspect <sessionId> --root . --json`
+4. submit structured analysis with `hforge recursive run <sessionId> --file <snippet>` or `--stdin`
+5. inspect durable results with `hforge recursive runs <sessionId> --root . --json` and `hforge recursive inspect-run <sessionId> <runId> --root . --json`
+
+## Failure behavior
+
+- if the current language is not supported, say so explicitly and fall back to non-recursive investigation
+- do not imply recursive-native parity on partial targets; keep support claims aligned with the capability map

package/commands/hforge-refresh.md

@@ -0,0 +1,35 @@
+---
+id: command-hforge-refresh
+kind: command
+title: Harness Refresh Command
+summary: Use when an agent should regenerate Harness Forge runtime summaries and repo-intelligence artifacts after install or content changes.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Refresh Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-refresh` with optional notes about what changed.
+
+## Expected workflow
+
+1. inspect `.hforge/runtime/index.json`, `.hforge/runtime/repo/`, and `.hforge/generated/agent-command-catalog.json` first when present
+2. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+3. run `hforge refresh --root . --json`
+4. run `hforge status --root . --json` when install-state confirmation matters
+5. summarize which runtime artifacts were regenerated and what to inspect next
+
+## Failure behavior
+
+- if the repo is not initialized, recommend `/hforge-init`
+- do not pretend refresh repaired drift that still needs `doctor`, `audit`, or a maintainer fix

package/commands/hforge-review.md

@@ -0,0 +1,36 @@
+---
+id: command-hforge-review
+kind: command
+title: Harness Review Command
+summary: Use when an agent should review runtime health, drift, decision coverage, and stale task artifacts in an installed Harness Forge workspace.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Review Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-review` followed by optional review focus notes.
+
+## Expected workflow
+
+1. inspect `.hforge/runtime/index.json`, `.hforge/runtime/decisions/`, and `.hforge/runtime/tasks/` first when present
+2. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+3. run `hforge review --root . --json`
+4. run `hforge doctor --root . --json` when managed surfaces look incomplete or drifted
+5. run `hforge audit --root . --json` when packaged-surface integrity is in doubt
+6. summarize blockers, warnings, stale runtime artifacts, and the single best next remediation step
+
+## Failure behavior
+
+- if the workspace is not initialized, say so explicitly and recommend `/hforge-init`
+- do not mutate runtime state unless the operator asks for a fix

package/commands/hforge-status.md

@@ -0,0 +1,34 @@
+---
+id: command-hforge-status
+kind: command
+title: Harness Status Command
+summary: Use when an agent should inspect the current Harness Forge workspace state before acting.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Status Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-status` followed by optional focus notes.
+
+## Expected workflow
+
+1. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+2. run `hforge status --root . --json`
+3. inspect `.hforge/runtime/index.json`, `.hforge/agent-manifest.json`, and installed target bridges when they exist
+4. summarize installed targets, visibility mode, important runtime surfaces, and the best next command
+
+## Failure behavior
+
+- if the workspace is not initialized, recommend `/hforge-init`
+- if the launcher is unavailable, fall back to `npx @harness-forge/cli`

package/commands/hforge-task.md

@@ -0,0 +1,35 @@
+---
+id: command-hforge-task
+kind: command
+title: Harness Task Command
+summary: Use when an agent should inspect Harness Forge task-runtime folders, task packs, and linked artifacts for the current work item.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Task Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-task` followed by a task id or the current task description.
+
+## Expected workflow
+
+1. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+2. run `hforge task list --root . --json`
+3. if a task id is known, run `hforge task inspect <taskId> --root . --json`
+4. when task-pack detail matters, run `hforge pack inspect <taskId> --root . --json`
+5. summarize the most relevant task-runtime artifacts and the next recommended action
+
+## Failure behavior
+
+- if no task folders exist, say so explicitly instead of implying the runtime is broken
+- if the workspace is not initialized, recommend `/hforge-init`