@harness-forge/cli 1.2.1 → 1.2.2

package/AGENTS.md

@@ -11,6 +11,8 @@ Use the thin visible bridge surfaces first in installed workspaces:
 - `.hforge/templates/` for canonical installed task and workflow templates
 - `.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`
 
 ## Mode awareness
 
@@ -117,3 +119,8 @@ Use the thin visible bridge surfaces first in installed workspaces:
 ## Release gate
 
 - run `npm run validate:release` before publish, handoff, or release-signoff work
+
+## 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

package/README.md

@@ -714,6 +714,22 @@ When integrating a custom agent, start here:
 5. `.agents/skills/<skill>/SKILL.md`
 6. `.hforge/library/skills/<skill>/SKILL.md`
 
+## 🧠 Agent Usage Playbook
+
+If you want Claude Code, Codex, or another custom agent to use Harness Forge
+more explicitly instead of merely coexisting with it, use
+`docs/agent-usage-playbook.md`.
+
+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
+
+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`.
+
 ---
 
 ## 🙌 Acknowledgements

package/commands/hforge-analyze.md

@@ -0,0 +1,55 @@
+---
+id: command-hforge-analyze
+kind: command
+title: Harness Analyze Command
+summary: Use when an agent should inspect the installed Harness Forge runtime before planning, coding, or making support claims.
+status: stable
+owner: core
+applies_to:
+  - codex
+  - claude-code
+  - cursor
+  - opencode
+languages:
+  - all
+generated: false
+---
+# Harness Analyze Command
+
+## Syntax
+
+Invoke this command in runtimes that support markdown-backed command entrypoints,
+for example `/hforge-analyze` followed by the active task, goal, or repo
+question.
+
+## Arguments and options
+
+- include the current task, feature, bug, or investigation objective
+- include the workspace root when the runtime is not already scoped to the repo
+- prefer installed runtime inspection before implementation or support claims
+
+## Expected workflow
+
+1. inspect `AGENTS.md`, `.hforge/agent-manifest.json`, and `.hforge/generated/agent-command-catalog.json`
+2. resolve command execution through `.hforge/generated/bin/hforge(.cmd|.ps1)` first, bare `hforge` second, and `npx @harness-forge/cli` last
+3. run the most relevant repo-intelligence and health commands, typically `status`, `commands`, `recommend`, and `review`
+4. read `.hforge/runtime/repo/repo-map.json`, `.hforge/runtime/repo/recommendations.json`, and any task or recursive runtime surfaces that apply
+5. summarize what the installed Harness Forge runtime says before editing files
+
+## Output contract
+
+- active Harness Forge surfaces called out explicitly
+- command resolution path stated explicitly
+- relevant runtime artifacts and recommendation evidence summarized
+- clear next step suggested: implement, create task artifacts, write a decision record, or escalate into recursive mode
+
+## Side effects
+
+- may run read-oriented CLI commands such as `status`, `commands`, `recommend`, `review`, `task`, or `recursive capabilities`
+- should remain diagnostic-first unless the operator explicitly asks for task artifacts, decisions, or recursive runs
+
+## Failure behavior
+
+- if the workspace is not initialized, say so and recommend `npx @harness-forge/cli` or `hforge init`
+- if bare `hforge` is unavailable, fall back to the workspace launcher or `npx @harness-forge/cli`
+- do not claim support or runtime state that is not present in the installed surfaces

package/docs/agent-usage-playbook.md

@@ -0,0 +1,198 @@
+# Agent Usage Playbook
+
+Harness Forge is most useful when the agent treats it as an explicit operating
+layer rather than passive repo decoration.
+
+This playbook shows how to promote actual usage in installed workspaces, how to
+run commands even when bare `hforge` is not on `PATH`, and what prompts to give
+Claude Code or Codex so they use the installed runtime instead of falling back
+to ad-hoc repo exploration.
+
+## Command resolution rule
+
+Inside an installed workspace, agents should resolve Harness Forge commands in
+this order:
+
+1. `.hforge/generated/bin/hforge.cmd` or `.ps1` on Windows, or `./.hforge/generated/bin/hforge` on POSIX
+2. bare `hforge`
+3. `npx @harness-forge/cli`
+
+That means a global install is optional. Agents can still run the package
+reliably through the workspace-local launcher.
+
+## Slash-style command trigger
+
+In runtimes that support markdown command entrypoints, Harness Forge can also
+be promoted through `/hforge-analyze`.
+
+That command is backed by `commands/hforge-analyze.md` and is intended to make
+the agent:
+
+- inspect the installed Harness Forge runtime first
+- choose a safe command execution path
+- summarize active guidance, targets, repo intelligence, and next steps before coding
+
+## What usage looks like
+
+An agent is usually using Harness Forge well when it does at least some of the
+following:
+
+- reads `AGENTS.md`, `CLAUDE.md`, or target bridge files before acting
+- checks `.hforge/agent-manifest.json` or `.hforge/generated/agent-command-catalog.json`
+- 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
+
+## Important limitation
+
+Normal agent work does not automatically populate every Harness Forge runtime
+folder.
+
+For example:
+
+- `.hforge/runtime/tasks/` only fills when task-runtime flows are used
+- `.hforge/runtime/decisions/` only fills when ASR or ADR style decision records are written
+- `.hforge/runtime/recursive/sessions/` only fills when recursive mode is explicitly used
+
+So an empty task or decision folder does not automatically mean the agent is
+ignoring Harness Forge. It often means the agent is using the guidance layer
+but has not yet been asked to persist structured runtime artifacts.
+
+## Recommended first commands
+
+These are the best low-friction commands to promote actual package usage:
+
+```bash
+hforge status --root . --json
+hforge commands --json
+hforge recommend . --json
+hforge review --root . --json
+```
+
+If the repo already has meaningful complexity:
+
+```bash
+hforge cartograph . --json
+hforge classify-boundaries . --json
+hforge synthesize-instructions . --target claude-code --json
+```
+
+If the task is hard or multi-hop:
+
+```bash
+hforge recursive plan "investigate the issue" --task-id TASK-001 --root . --json
+hforge recursive capabilities --root . --json
+```
+
+## Prompt patterns
+
+### 1. Prove that the agent is using Harness Forge
+
+Use this when you want the agent to confirm it is reading the installed layer:
+
+```text
+Before making changes, inspect CLAUDE.md, AGENTS.md, and .hforge/agent-manifest.json.
+Tell me which Harness Forge surfaces are active in this repo, which command form
+you will use, and which hidden runtime files you consider authoritative.
+```
+
+### 2. Force command-aware behavior
+
+Use this when the agent tends to improvise commands:
+
+```text
+Use the installed Harness Forge command catalog before inventing commands.
+Resolve execution through .hforge/generated/bin/hforge first, then bare hforge,
+then npx @harness-forge/cli. Show me the command you chose before running it.
+```
+
+### 3. Force repo-aware guidance before coding
+
+Use this when you want the agent to inspect the workspace before implementation:
+
+```text
+Use Harness Forge to inspect this repo before coding. Run status, commands, and
+recommend, then summarize what the installed runtime says about targets, risks,
+and recommended operating surfaces before you edit files.
+```
+
+### 4. Create durable task artifacts
+
+Use this when you want visible runtime evidence for a feature or bug:
+
+```text
+Treat this work as a tracked Harness Forge task. Create a task id, inspect the
+repo using the installed runtime, and persist task-runtime artifacts for file
+interest, impact analysis, and task pack output before implementation.
+```
+
+### 5. Create decision records
+
+Use this when the work changes architecture, workflow, or support posture:
+
+```text
+If this task changes architecture, release posture, workflow contracts, or AI
+runtime behavior, write a Harness Forge decision record under
+.hforge/runtime/decisions and summarize the rationale in the response.
+```
+
+### 6. Escalate into recursive mode
+
+Use this when the work is ambiguous or investigation-heavy:
+
+```text
+This is a hard investigation task. Use Harness Forge recursive mode instead of
+chat-only reasoning. Plan a recursive session, inspect recursive capabilities,
+run one bounded structured analysis step, and return the durable run result.
+```
+
+### 7. Keep the agent honest about support claims
+
+Use this when the task touches target support or language behavior:
+
+```text
+Do not guess target or language support. Use Harness Forge capability surfaces,
+including .hforge/runtime/recursive/language-capabilities.json and target inspect
+output, before claiming that Claude Code, Codex, Cursor, or OpenCode supports a
+behavior.
+```
+
+## Claude-specific examples
+
+```text
+Use CLAUDE.md as the Claude-native bridge, but keep AGENTS.md as the shared
+cross-agent contract. Before implementing, inspect the installed Harness Forge
+runtime and tell me which launcher or command form you will use.
+```
+
+```text
+Use Harness Forge as your repo operating layer for this task. Read CLAUDE.md,
+AGENTS.md, and .hforge/generated/agent-command-catalog.json, then use status,
+recommend, and review before you write code.
+```
+
+## Codex-specific examples
+
+```text
+Use AGENTS.md and the installed Harness Forge command catalog before editing.
+If hforge is not on PATH, use the workspace launcher under .hforge/generated/bin.
+Prefer Harness Forge repo-intelligence commands over blind repo scanning.
+```
+
+```text
+Use Harness Forge to bootstrap your understanding of this repo: inspect command
+availability, review installed targets, run recommendation and repo-map flows,
+and base your plan on the installed runtime outputs instead of assumptions.
+```
+
+## Best operator habit
+
+If you want agents to use Harness Forge more consistently, make that an explicit
+instruction at the start of important tasks:
+
+```text
+Use the installed Harness Forge runtime for this task, not just the repo files.
+Inspect the active guidance surfaces first, resolve the safest command form, and
+persist structured artifacts when the task crosses into tracked work,
+architecture decisions, or recursive investigation.
+```

package/docs/agents.md

@@ -17,6 +17,8 @@ AI content into the hidden `.hforge/` layer.
 - `.hforge/runtime/recursive/language-capabilities.json` for the canonical
   recursive structured-analysis capability map before deeper recursive
   investigation begins
+- `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
 - `RESEARCH-SOURCES.md` and `VALIDATION.md` for optional pack-level provenance detail
 

package/docs/commands.md

@@ -62,6 +62,19 @@ For agents inside an installed workspace, the safest execution order is:
 2. bare `hforge`
 3. `npx @harness-forge/cli`
 
+## Markdown command entrypoints
+
+Some agent runtimes support markdown-backed command triggers in addition to the
+CLI. Harness Forge ships command docs for those environments under `commands/`.
+
+Examples:
+
+- `/hforge-analyze` to force installed-runtime inspection before coding
+- `commands/hforge-analyze.md` as the canonical packaged command surface
+- `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.
+
 ```bash
 npx @harness-forge/cli
 npx @harness-forge/cli shell setup --yes
@@ -116,6 +129,9 @@ under `.hforge/state/`, and intentionally preserve gathered runtime state such
 as task artifacts, decision records, recursive sessions, and observability
 signals.
 
+For agent-facing examples and prompt patterns that encourage actual runtime
+usage instead of passive installation, see `docs/agent-usage-playbook.md`.
+
 ## Maintainer source-checkout examples
 
 When developing Harness Forge itself from a source checkout, the equivalent

package/manifests/bundles/core.json

@@ -37,6 +37,7 @@
       "version": 1,
       "description": "Core command guidance and usage patterns.",
       "paths": [
+        "commands/hforge-analyze.md",
         "commands/plan.md",
         "commands/test.md",
         "contexts/dev.md",
@@ -59,7 +60,7 @@
       ],
       "owner": "core",
       "usageCues": [
-        "Use when starting, testing, or validating work."
+        "Use when starting, testing, validating, or analyzing work."
       ]
     },
     {

package/manifests/catalog/compatibility-matrix.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-03-28T21:42:25.027Z",
+  "generatedAt": "2026-03-28T22:25:09.358Z",
   "entries": [
     {
       "subjectType": "language",

package/manifests/catalog/package-surface.json

@@ -64,6 +64,9 @@
     "docs/observability.md",
     "docs/benchmark-scenarios.md",
     "docs/release-process.md",
+    "commands/hforge-analyze.md",
+    "commands/plan.md",
+    "commands/test.md",
     "knowledge-bases/seeded/README.md",
     "rules/common/README.md",
     "skills/README.md",
@@ -222,6 +225,9 @@
         "docs/benchmark-scenarios.md",
         "docs/troubleshooting.md",
         "docs/versioning-and-migration.md",
+        "commands/hforge-analyze.md",
+        "commands/plan.md",
+        "commands/test.md",
         "hooks",
         "mcp",
         "profiles"

package/package.json

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

package/scripts/intelligence/shared.mjs

@@ -4,6 +4,9 @@ import { fileURLToPath } from "node:url";
 
 const IGNORED_DIRS = new Set([
   ".git",
+  ".claude",
+  ".codex",
+  ".cursor",
   ".hforge",
   ".next",
   ".nuxt",
@@ -19,9 +22,47 @@ const IGNORED_DIRS = new Set([
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
-function bump(map, key, evidence) {
+function languageWeightForPath(file) {
+  const normalized = file.replaceAll("\\", "/");
+
+  if (
+    normalized.startsWith(".claude/") ||
+    normalized.startsWith(".codex/") ||
+    normalized.startsWith(".cursor/") ||
+    normalized.startsWith(".agents/") ||
+    normalized.startsWith(".github/")
+  ) {
+    return 0;
+  }
+
+  if (
+    normalized.startsWith("src/") ||
+    normalized.startsWith("app/") ||
+    normalized.startsWith("lib/") ||
+    normalized.startsWith("seed/") ||
+    normalized.startsWith("data/")
+  ) {
+    return 2;
+  }
+
+  if (
+    normalized.startsWith("scripts/") ||
+    normalized.startsWith("tools/") ||
+    normalized.startsWith("bin/")
+  ) {
+    return 0.35;
+  }
+
+  if (normalized.startsWith("tests/") || normalized.includes("/tests/")) {
+    return 0.5;
+  }
+
+  return 1;
+}
+
+function bump(map, key, evidence, amount = 1) {
   const current = map.get(key) ?? { count: 0, evidence: [] };
-  current.count += 1;
+  current.count += amount;
   if (evidence && current.evidence.length < 5 && !current.evidence.includes(evidence)) {
     current.evidence.push(evidence);
   }
@@ -105,41 +146,49 @@ function detectLanguages(files) {
   const languageCounts = new Map();
 
   for (const file of files) {
+    const weight = languageWeightForPath(file);
+    if (weight <= 0) {
+      continue;
+    }
+
     if (/\.(ts|tsx|js|jsx)$/i.test(file)) {
-      bump(languageCounts, "typescript", file);
+      bump(languageCounts, "typescript", file, weight);
     }
     if (/\.py$/i.test(file)) {
-      bump(languageCounts, "python", file);
+      bump(languageCounts, "python", file, weight);
     }
     if (/\.go$/i.test(file)) {
-      bump(languageCounts, "go", file);
+      bump(languageCounts, "go", file, weight);
     }
     if (/\.java$/i.test(file)) {
-      bump(languageCounts, "java", file);
+      bump(languageCounts, "java", file, weight);
     }
     if (/\.(kt|kts)$/i.test(file)) {
-      bump(languageCounts, "kotlin", file);
+      bump(languageCounts, "kotlin", file, weight);
     }
     if (/\.rs$/i.test(file)) {
-      bump(languageCounts, "rust", file);
+      bump(languageCounts, "rust", file, weight);
     }
     if (/\.(cpp|cxx|cc|hpp|hh|h)$/i.test(file)) {
-      bump(languageCounts, "cpp", file);
+      bump(languageCounts, "cpp", file, weight);
     }
     if (/\.php$/i.test(file)) {
-      bump(languageCounts, "php", file);
+      bump(languageCounts, "php", file, weight);
     }
     if (/\.(pl|pm)$/i.test(file)) {
-      bump(languageCounts, "perl", file);
+      bump(languageCounts, "perl", file, weight);
     }
     if (/\.swift$/i.test(file)) {
-      bump(languageCounts, "swift", file);
+      bump(languageCounts, "swift", file, weight);
+    }
+    if (/\.lua$/i.test(file)) {
+      bump(languageCounts, "lua", file, weight);
     }
     if (/\.(sh|bash|zsh)$/i.test(file)) {
-      bump(languageCounts, "shell", file);
+      bump(languageCounts, "shell", file, weight);
     }
     if (/\.(cs|csproj|sln)$/i.test(file)) {
-      bump(languageCounts, "dotnet", file);
+      bump(languageCounts, "dotnet", file, weight);
     }
   }