# Harness Forge agent guidance

Use the thin visible bridge surfaces first in installed workspaces:

- `AGENTS.md` for the thin human-readable guidance bridge
- `.hforge/agent-manifest.json` for the machine-readable custom-agent contract
- `.agents/skills/` for auto-discoverable wrappers
- `.specify/` for spec -> plan -> tasks flow state and templates
- `.hforge/library/skills/` for canonical installed skills
- `.hforge/library/rules/` and `.hforge/library/knowledge/` for canonical installed implementation guidance
- `.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-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`, `commands/hforge-recursive-investigate.md`, and `commands/hforge-update.md` for runtimes that support slash-style markdown command entrypoints such as `/hforge-analyze`

## Mode awareness

- when working inside an installed consumer workspace, prefer the hidden canonical AI layer under `.hforge/` plus the thin visible bridges at the repo root
- when working inside the Harness Forge source repository itself, the authored source-of-truth surfaces still live in `skills/`, `rules/`, `knowledge-bases/`, `templates/`, `manifests/`, `targets/`, and `src/`
- do not assume the source repository layout and the installed workspace layout are the same thing
- in installed workspaces, treat `.hforge/` as canonical and the root bridge files as discovery and compatibility surfaces
- in the package source repository, treat `.hforge/` as generated or local runtime state rather than the authored source of truth

## Resolution rule

- treat `AGENTS.md` as the primary human-readable entrypoint
- load `.hforge/agent-manifest.json` first when a machine-readable contract is preferred
- use `.agents/skills/<skill>/SKILL.md` only for discovery
- use `.hforge/library/skills/<skill>/SKILL.md` as the canonical execution contract in installed workspaces
- keep `.agents/skills/*-engineering/` thin and discovery-only so wrappers do
  not become a second authored source of language-pack guidance
- use `.hforge/library/skills/<skill>/references/` for deeper runtime-facing heuristics and templates
- treat `.hforge/library/`, `.hforge/templates/`, `.hforge/runtime/`, `.hforge/state/`, and `.hforge/generated/` as extracted AI-layer surfaces, not product source code
- treat any surface marked `treatAsProductCode: false` in `.hforge/agent-manifest.json` as non-product AI-layer content

## Installed runtime map

- use `.hforge/runtime/repo/repo-map.json` for baseline repo topology and boundary context
- use `.hforge/runtime/repo/recommendations.json` for evidence-backed bundle, profile, and validation recommendations
- use `.hforge/runtime/repo/instruction-plan.json` for target-aware instruction synthesis outputs
- use `.hforge/runtime/findings/validation-gaps.json` and `.hforge/runtime/findings/risk-signals.json` for cautionary runtime signals
- use `.hforge/runtime/tasks/<taskId>/` for task-runtime artifacts such as file-interest, impact-analysis, and task-pack linkage
- use `.hforge/runtime/decisions/` for ASR and ADR records plus machine-readable decision indexes when governance support is installed
- use `.hforge/runtime/recursive/sessions/` for recursive-session state, handles, and promotion traces when recursive mode is enabled
- use `.hforge/runtime/recursive/language-capabilities.json` for the canonical recursive structured-analysis capability map before assuming language support
- use `.hforge/runtime/recursive/runtime-inventory.json` for the canonical host-runtime posture before attempting bounded code cells or reusable helper scripts
- use `.hforge/runtime/recursive/escalation-heuristics.json` as the advisory trigger list for when installed agents should prefer recursive mode
- use `.hforge/observability/` for local-only effectiveness summaries and recommendation or maintenance signals
- use `.hforge/generated/bin/` for workspace-local launchers when bare `hforge` is not already available on `PATH`

## Language discovery

- prefer `.hforge/library/knowledge/seeded/typescript/` with `.hforge/library/rules/common/` and `.hforge/library/rules/typescript/` when the repo is TypeScript-heavy or JavaScript-heavy with strong typing needs
- prefer `.hforge/library/skills/javascript-engineering/` when the repo is JavaScript-first and the task is not primarily about TypeScript typing
- prefer `.hforge/library/knowledge/seeded/java/` with `.hforge/library/rules/common/` and `.hforge/library/rules/java/` for Java services and libraries
- prefer `.hforge/library/knowledge/seeded/dotnet/` with `.hforge/library/rules/common/` and `.hforge/library/rules/dotnet/` for .NET repos
- prefer `.hforge/library/knowledge/seeded/lua/` with `.hforge/library/rules/common/` and `.hforge/library/rules/lua/` for Lua work
- prefer `.hforge/library/knowledge/seeded/powershell/` with `.hforge/library/rules/common/` and `.hforge/library/rules/powershell/` for PowerShell and Windows automation
- use the structured packs under `.hforge/library/knowledge/structured/` with the matching `.hforge/library/rules/<language>/` directory for Python, Go, Kotlin, Rust, C++, PHP, Perl, Swift, and Shell
- use `.hforge/library/manifests/catalog/language-assets.json` when the installed language surface is not obvious from the repo layout alone
- when a seeded language pack is present, load `docs/examples-guide.md` before choosing an example and then load the single closest scenario file from `examples/`
- treat seeded language docs under `knowledge-bases/seeded/<language>/docs/` as execution guidance, not as descriptive catalog copy
- after implementation, require a pass through `docs/review-checklist.md` for the active language pack
- prefer the language-specific workflow under `templates/workflows/implement-<language>-change.md` over improvised plans when the task is implementation-heavy

## Specialized skills

- 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
- prefer `.hforge/library/skills/complex-task-protocol/` when a task has at least two complexity signals, one high-signal condition, or explicit user interest in subagents, learning capture, recovery, orchestration, or complex-task handling
- prefer `.agents/skills/hforge-recursive-investigate/SKILL.md` or `commands/hforge-recursive-investigate.md` when the task is ambiguous, cross-module, or investigation-heavy enough to justify recursive mode and Typed RLM-first execution
- prefer recursive mode when the task is ambiguous, cross-module, long-context, policy-sensitive, or worth preserving as durable evidence, but treat that as an agent decision rather than an always-on background policy
- 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

- 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

## Target support posture

- treat Codex and Claude Code as first-class targets
- treat Cursor and OpenCode as partial targets unless the capability matrix says otherwise
- prefer `hforge target inspect <target> --json` or `.hforge/library/manifests/catalog/harness-capability-matrix.json` before claiming a target supports a runtime-native behavior
- do not imply hook-native, workflow-native, or recursive-native parity where support is only translated, bridged, or documentation-driven
- use `.codex/` and `.claude/` as target-facing bridges, not as replacements for the shared `.hforge/` runtime

## Runtime notes

- Claude Code installs map target runtime files into `.claude/`
- Codex installs map target runtime files into `.codex/`
- installed workspaces compile the shared intelligence runtime into `.hforge/runtime/`
- target-facing files such as `AGENTS.md`, `.agents/skills/`, `.codex/`, and `.claude/` are thin bridges back to the hidden canonical AI layer rather than separate knowledge systems
- recursive runtime state, when present, lives under `.hforge/runtime/recursive/sessions/` and should be treated as hidden operational state rather than product code
- recursive structured analysis is the promoted execution surface for recursive repository investigation; treat the REPL as optional and non-authoritative

## 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, 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
- prefer `hforge bootstrap --root . --yes` when the repository needs target autodiscovery and one-pass Harness Forge setup
- prefer `hforge task list --root . --json`, `hforge task inspect <taskId> --root . --json`, and `hforge pack inspect <taskId> --root . --json` when task-runtime artifacts are relevant
- prefer `hforge recursive capabilities --root . --json` before claiming recursive structured-analysis support for a language
- prefer `hforge recursive runtimes --root . --json` before assuming Python or PowerShell code-cell availability
- prefer `hforge recursive provision-runtime <python|powershell> --root . --json` when a healthy host runtime exists but you want a workspace-managed recursive alias
- prefer `hforge recursive run <sessionId> --file <snippet> --root . --json`, `hforge recursive run <sessionId> --stdin --root . --json`, `hforge recursive runs <sessionId> --root . --json`, and `hforge recursive inspect-run <sessionId> <runId> --root . --json` for promoted recursive structured-analysis flows
- prefer `hforge flow status --root . --json` when flow recovery state matters
- prefer `hforge review --root . --json`, `hforge export --root . --json`, `hforge doctor --root . --json`, and `hforge audit --root . --json` for runtime health and handoff checks
- prefer `hforge update --root . --dry-run --yes` before a managed package refresh and `hforge update --root . --yes` when you want to reapply the latest published Harness Forge surfaces without discarding gathered runtime state
- when bare `hforge` is unavailable, use the workspace-local launcher under `.hforge/generated/bin/` instead of reaching for package-source entrypoints such as `node dist/cli/index.js`
- `hforge shell setup --yes` is the preferred way to make bare `hforge` available without forcing a global npm mutation
- `npm install -g @harness-forge/cli` is optional convenience, not the default requirement
- use `.hforge/runtime/repo/repo-map.json`, `.hforge/runtime/repo/instruction-plan.json`, `.hforge/runtime/repo/recommendations.json`, and `.hforge/runtime/findings/risk-signals.json` as the extracted runtime intelligence surfaces
- treat framework matches, recommendation evidence, and validation gaps as first-class signals, not as optional decoration
- use the complex-task protocol automatically for qualifying work rather than waiting for a slash command; keep simple tasks light, bound sidecar agents to independent work, verify before completion, and capture only durable non-duplicative learning

## Cartographer+ project-intelligence workflow

Cartographer+ answers what exists, what is connected, what context a task needs,
and which commands should run. Prefer one broker call over memorizing the
individual commands.

- before starting a code task: `hforge agent hook --event task.started --goal "<goal>" --json`
- before editing files: `hforge agent hook --event files.pre_edit --files "<paths>" --json`
- after editing files: `hforge agent hook --event files.changed --files "<paths>" --json`
- before a PR or finishing: `hforge agent hook --event pr.prep --json` then `--event task.completed --json`
- the broker is triage-only by default: it returns `recommendedCommands` and a `nextAction`; read them and act
- pass `--execute` to let the broker run the auto-executable diagnostic commands in-process (graph build, context compile, impact). It never spawns a shell and is gated by `.hforge/agent-triggers.yaml` `autonomyLevel` (default `diagnostic`; `manual` disables execution)
- repeated identical hooks within the cooldown return the cached run; do not loop on the broker
- the underlying commands are also callable directly: `hforge graph build|status|inspect`, `hforge context compile|show|list`, `hforge impact <file>|--files|--changed|--goal`
- read the compiled context bundle (`.hforge/cartographer/context-bundles/`) before opening unrelated files; treat its `graphFreshness`/`contextTruncated` markers as authoritative about staleness
- treat impact `risk` as `low|medium|high|architectural`; a `--goal` impact is predicted, not observed, and is capped below architectural
- Cartographer+ links the existing decision/ADR system through a provider; never create a competing ADR store
- inspect broker history with `hforge agent hooks status|list`; runs are audited in `.hforge/cartographer/agent-hooks/runs.jsonl`
- cross-platform fallbacks `scripts/cartographer/hforge-agent-hook.{py,sh,ps1,mjs}` only print a plan (dry-run); they never execute — execution goes through `hforge agent hook --execute`

## Trust and scope rules

- do not treat `.hforge/` runtime state, task state, recursive state, or generated manifests as product application code unless the task is explicitly about Harness Forge itself
- prefer the machine-readable command catalog and capability matrix over guessing or prose-only interpretation
- treat stale or missing runtime artifacts as signals to run `status`, `refresh`, `doctor`, or `audit` rather than inventing a recovery path
- keep support claims honest: if a target or surface is partial, translated, or non-authoritative, say so explicitly

## 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, compact context efficiently, create task artifacts, write decision records, or escalate into recursive mode

## Feature and bug workflow defaults

- for meaningful feature work, use the `double-diamond-feature` skill (or `/hforge-double-diamond`) before coding: Discover evidence, Define problem/non-goals/acceptance, Develop at least two options for non-trivial work, Deliver with validation and rollback notes
- for defects, regressions, outages, or flaky tests, use `bug-investigation` (or `/hforge-bug-diamond`) instead: triage and contain, reproduce, hypothesize, test, fix the confirmed cause, verify, prevent recurrence
- keep small low-risk tasks in Lite mode; label facts as user-provided, repository-derived, runtime-derived, external, or assumption; never claim certainty without evidence
- these workflows are command/skill driven and host-agnostic; pause for human confirmation before high-risk auth, secrets, payments, data-migration, or production changes

<!-- SPECKIT START -->
For additional context about technologies to be used, project structure,
shell commands, and other important information, read the current plan:
`specs/016-complex-task-protocol/plan.md`
<!-- SPECKIT END -->