@harness-forge/cli 1.2.1 → 1.2.3

package/skills/hforge-decide/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: hforge-decide
+description: create or update durable asr or adr records for harness forge workspaces. use when an analysis or implementation choice changes runtime behavior, package boundaries, support posture, migration strategy, or any other architecture-significant concern that should remain reviewable after the current session.
+---
+
+# HForge Decide
+
+## Trigger Signals
+
+- an analysis or implementation choice has architecture-significant consequences
+- the repo already has decision records and the new work should link to them
+- multiple credible options exist and the rationale should stay durable
+- a task pack, impact analysis, or review surfaced a decision candidate that should not stay implicit
+
+## Inspect First
+
+- `.hforge/runtime/decisions/index.json`
+- `.hforge/runtime/tasks/`
+- `.hforge/runtime/findings/`
+- `.hforge/runtime/repo/recommendations.json`
+- the most relevant existing ASR or ADR if one already exists
+
+## Workflow
+
+1. frame the decision clearly before writing anything
+2. inspect related task packs, impact analysis, risk signals, and existing decision records
+3. create an ASR when the direction is still being evaluated and an ADR when the decision is accepted enough to guide future work
+4. write the record under `.hforge/runtime/decisions/` with context, decision, consequences, constraints, risks, and follow-up actions
+5. update supersession or related-record links when the new decision changes an earlier one
+
+## Output Contract
+
+- a concise ASR or ADR with explicit status and rationale
+- links to related tasks, impacts, and superseded records
+- follow-up actions or open questions when the work is not fully settled
+
+## Validation Path
+
+- `.hforge/runtime/decisions/index.json`
+- `schemas/runtime/decision-record.schema.json`
+- `schemas/runtime/architecture-significance.schema.json`
+
+## Failure Modes
+
+- the real decision is still too vague to record
+- there is not enough evidence to justify a durable record yet
+- the new record conflicts with an existing one and the supersession path is unclear
+
+## Escalation
+
+- escalate when the decision changes public support or target guarantees
+- escalate when migration or rollback cost is materially different across options
+- escalate when a new record would contradict an existing accepted ADR
+
+## References
+
+- `skills/hforge-decide/references/decision-rubric.md`
+- `skills/hforge-decide/references/output-contract.md`

package/skills/hforge-decide/references/decision-rubric.md

@@ -0,0 +1,18 @@
+# Decision rubric
+
+Create or update a record when the choice affects one or more of these:
+- runtime behavior
+- package or bundle boundaries
+- target support posture
+- migration or rollback strategy
+- validation, release, or maintenance guarantees
+
+Prefer ASR when:
+- exploration is still active
+- the trade-offs are being narrowed
+- the work needs a reviewable candidate before acceptance
+
+Prefer ADR when:
+- the direction is stable enough to guide future work
+- the team needs a durable accepted rationale
+- the decision supersedes an earlier record

package/skills/hforge-decide/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-decide` result should include:
+- the record type and why it was chosen
+- the decision statement in one or two lines
+- constraints, risks, and consequences
+- task refs or runtime evidence that justify the record

package/skills/hforge-init/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: hforge-init
+description: initialize harness forge in the current repository, bootstrap the target-aware runtime, and establish the managed surfaces needed for later review, analysis, and decision tracking. use when the repo is not initialized, when runtime files are missing, or when the user asks to set up hforge in a project.
+---
+
+# HForge Init
+
+## Trigger Signals
+
+- the repository is not yet initialized for Harness Forge
+- `.hforge/agent-manifest.json` or `.hforge/runtime/index.json` is missing
+- target runtime files such as `.codex/` or `.claude/` are missing or incomplete
+- the user asks to initialize, bootstrap, or wire Harness Forge into a repo
+
+## Inspect First
+
+- repository root files such as `README.md`, `package.json`, and CI or target config files
+- `AGENTS.md` and `.agents/skills/` when present
+- `.hforge/agent-manifest.json` and `.hforge/runtime/index.json` when present
+- `.codex/` and `.claude/` bridge surfaces when present
+
+## Workflow
+
+1. inspect the current workspace state with `hforge status --root . --json`
+2. if the repo is not initialized or target runtime files are absent, run `hforge bootstrap --root . --yes`
+3. run `hforge refresh --root . --json` after bootstrap so shared runtime summaries are current
+4. inspect `hforge catalog --json` when bundle or profile visibility matters
+5. summarize detected targets, installed surfaces, runtime artifacts, and the recommended next command
+
+## Output Contract
+
+- initialization status and whether bootstrap was needed
+- detected targets and managed runtime surfaces now present
+- runtime artifacts now available under `.hforge/runtime/`
+- the best next command to run, such as `/hforge-analyze` or `/hforge-review`
+
+## Validation Path
+
+- `hforge status --root . --json`
+- `hforge bootstrap --root . --yes`
+- `hforge refresh --root . --json`
+
+## Failure Modes
+
+- the repo is not writable
+- the `hforge` launcher is not available
+- target detection is incomplete or no supported target is installed yet
+
+## Escalation
+
+- escalate when bootstrap cannot write the project-owned runtime
+- escalate when targets are ambiguous and the repo needs explicit operator intent
+- escalate when package installation or shell setup is missing
+
+## References
+
+- `skills/hforge-init/references/bootstrap-order.md`
+- `skills/hforge-init/references/output-contract.md`

package/skills/hforge-init/references/bootstrap-order.md

@@ -0,0 +1,7 @@
+# Bootstrap order
+
+1. Run `hforge status --root . --json` first to avoid bootstrapping blindly.
+2. Prefer `hforge bootstrap --root . --yes` when the repo needs one-pass setup.
+3. Run `hforge refresh --root . --json` immediately after bootstrap so the runtime summary, repo intelligence, and generated indexes are current.
+4. Only inspect `hforge catalog --json` after the workspace exists and targets are known.
+5. If bare `hforge` is unavailable, use the workspace-local launcher under `.hforge/generated/bin/` once the repo is initialized.

package/skills/hforge-init/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-init` result should include:
+- whether the repo was already initialized or required bootstrap
+- detected target runtimes
+- the highest-value managed surfaces now available
+- the next recommended command and why it should be run next

package/skills/hforge-refresh/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: hforge-refresh
+description: refresh shared runtime summaries and generated harness forge artifacts after install changes, repo changes, or stale analysis state. use when the runtime is present but outdated, incomplete, or no longer trustworthy.
+---
+
+# HForge Refresh
+
+## Trigger Signals
+
+- runtime summaries are stale after installs or content changes
+- repo-intelligence artifacts no longer match the current repository state
+- the user explicitly asks to refresh the project-owned runtime
+- a later review or analysis should not rely on outdated runtime state
+
+## Inspect First
+
+- `.hforge/runtime/index.json`
+- `.hforge/generated/agent-command-catalog.json`
+- `.hforge/runtime/repo/`
+
+## Workflow
+
+1. run `hforge refresh --root . --json`
+2. follow with `hforge status --root . --json` when install-state confirmation matters
+3. summarize regenerated artifacts, remaining gaps, and the best next action
+
+## Output Contract
+
+- confirmation that refresh ran or why it could not
+- refreshed runtime artifacts and any remaining missing prerequisites
+- the next command to run, usually `/hforge-analyze` or `/hforge-review`
+
+## Validation Path
+
+- `hforge refresh --root . --json`
+- `hforge status --root . --json`
+
+## Failure Modes
+
+- the repo is not initialized
+- required runtime files or launchers are missing
+- refresh cannot reconcile the current install state
+
+## Escalation
+
+- escalate when refresh cannot complete without a fresh bootstrap
+- escalate when runtime summaries regenerate but still disagree with the repo
+
+## References
+
+- `skills/hforge-refresh/references/refresh-order.md`
+- `skills/hforge-refresh/references/output-contract.md`

package/skills/hforge-refresh/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-refresh` result should include:
+- whether refresh succeeded
+- which runtime surfaces were regenerated
+- what still looks stale or blocked
+- the next command that should be run now that the runtime is current

package/skills/hforge-refresh/references/refresh-order.md

@@ -0,0 +1,5 @@
+# Refresh order
+
+1. `hforge refresh --root . --json`
+2. `hforge status --root . --json`
+3. inspect `.hforge/runtime/repo/` and `.hforge/generated/agent-command-catalog.json` if follow-up verification is needed

package/skills/hforge-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: hforge-review
+description: runtime health review for harness forge workspaces. use when the user wants drift checks, decision coverage, stale task review, managed-surface integrity, or a clear pass-fail summary of the current runtime state.
+---
+
+# HForge Review
+
+## Trigger Signals
+
+- the user asks whether the current Harness Forge setup is healthy
+- runtime drift, stale task artifacts, or missing managed surfaces are suspected
+- a handoff, release, or package refresh needs a concise review first
+- decision coverage and runtime governance need to be checked before moving on
+
+## Inspect First
+
+- `.hforge/runtime/index.json`
+- `.hforge/runtime/decisions/index.json`
+- `.hforge/runtime/tasks/`
+- `.hforge/generated/agent-command-catalog.json`
+- `.hforge/agent-manifest.json`
+
+## Workflow
+
+1. run `hforge review --root . --json`
+2. if installation drift is suspected, run `hforge doctor --root . --json`
+3. if package-surface integrity is suspected, run `hforge audit --root . --json`
+4. summarize blockers, warnings, stale runtime artifacts, decision gaps, and the best cleanup order
+
+## Output Contract
+
+- runtime health summary with blocker, warning, and cleanup sections
+- decision-coverage and stale-task callouts when relevant
+- the next remediation command to run
+
+## Validation Path
+
+- `hforge review --root . --json`
+- `hforge doctor --root . --json`
+- `hforge audit --root . --json`
+
+## Failure Modes
+
+- the workspace is not initialized
+- review signals are incomplete because runtime summaries are stale
+- doctor or audit cannot read the current install state
+
+## Escalation
+
+- escalate when install drift risks losing managed state
+- escalate when audit shows package-surface mismatches that need a maintainer fix
+- escalate when runtime findings and source-of-truth manifests disagree
+
+## References
+
+- `skills/hforge-review/references/review-order.md`
+- `skills/hforge-review/references/output-contract.md`

package/skills/hforge-review/references/output-contract.md

@@ -0,0 +1,7 @@
+# Output contract
+
+A good `/hforge-review` result should include:
+- whether the runtime is healthy enough to trust
+- what is stale, drifted, or missing
+- what can be fixed by refresh versus what needs a maintainer change
+- the single best next remediation step

package/skills/hforge-review/references/review-order.md

@@ -0,0 +1,7 @@
+# Review order
+
+1. `hforge review --root . --json`
+2. `.hforge/runtime/decisions/index.json`
+3. `.hforge/runtime/tasks/`
+4. `hforge doctor --root . --json` when managed surfaces look incomplete
+5. `hforge audit --root . --json` when package-surface integrity matters