Harness Intelligence CLI

hi scaffolds the AI operating context for each project phase, from requirements and backlog prep to the repo-aware setup pass. This repo carries the executable CLI plus the canonical bundled scaffold baseline under src/data and skills/. At runtime, stable and exact scaffold requests resolve through the verified control-plane authority. Use --baseline bundled explicitly when you intend to use the npm-shipped baseline; stable and exact requests never fall back to it.

Commands

• hi show the command guide
• hi init choose a backlog provider, scaffold requirements/backlog skills, and seed the initial wiki tree
• hi scaffold detect the target repo, confirm or auto-accept pack selection, and write repo-aware scaffold output
• hi tools ensure refresh auto-managed required tools and validate manual platform tools; hint tools ensure is the same command
• hi report submit structured Harness friction for maintainer triage

Usage

hi init
hi scaffold
hi scaffold --yes
hi scaffold -i /path/to/repo
hi scaffold -i /path/to/repo -o /path/to/output
hi tools ensure
hint tools ensure
hi update --yes
hi report --help
hi --version
hi -v
hint --version
hint -v
bun run sync:skills
bun run baseline:build

bun run sync:skills updates a local cache clone of wearedevpunks/skills and then replaces only skills/, overwriting any local changes there.

hi init asks for the backlog provider, defaults to GitHub Projects/Issues, copies .agents/skills/requirements-grill and .agents/skills/write-backlog, seeds an initial Mermaid-enabled wiki tree at apps/wiki for monorepos or wiki for single-repo layouts, writes <wiki-root>/backlog-provider.md, and then prints a fixed post-command prompt. Agents should activate $hi-cli, reconcile generated init output with the real repo layout, keep the pinned backlog provider unless the user changes it, and only start requirements/backlog generation when the user asks for that workflow.

hi scaffold scans the target repo from cwd or -i, resolves the active scaffold baseline, writes scaffold output into the scan root or -o, copies the selected baseline skills, resolves pack-owned lint assets into .devpunks/specs/lint/, and ensures required global tool prerequisites for those skills. Use --yes in non-interactive harnesses to accept the resolved default pack selection without prompts.

Generated docs/workspace prompt specs keep always-loaded guidance compact: they require repository-specific structural invariants, placement and dependency direction, local conventions, and exact-trigger pointers to each selected installed skill. The installed SKILL.md remains authoritative for skill semantics. Source Guide, CLAUDE.md mirror, and narrow validation seams remain explicit.

Before refreshing generated skills, setup/update may take a blind evidence snapshot of repo skill homes under .devpunks/pre-existing-skills. Commands do not classify skill overlaps or keep -local collision copies. After setup, follow-up agents reconcile the skill homes, archive replaced evidence under .devpunks/replaced-skills/<skill-id>/..., preserve non-overlaps through mirrors, and use hi report for baseline-worthy local knowledge. After update, $hi-cli limits reconciliation to skill IDs added, removed, renamed, or reported as locally edited; same-ID content refreshes inspect only affected skills and active mirrors.

hi update --yes applies managed scaffold updates without prompting. It is the non-interactive alias for the apply behavior of --write.

Post-update follow-through starts from the current summary and changed paths, not from existing .devpunks/ artifacts. A clean run stops. Prompt, subagent, lint, hook, tool, source-guide, wiki, and pack work runs only for changed categories. Auto-accepted default/detected packs do not rerun setup. Write modes finish with targeted validation and one hi check --json; a bounded execution worker runs the command without delegating it again.

hi tools ensure / hint tools ensure reads required tool IDs from .devpunks/settings.json, or uses the default Harness toolchain outside a scaffolded repo. It refreshes every auto-managed tool through the selected baseline's explicit trusted latest install target even when the binary is already present. Manual platform tools such as gh, az, and glab are validation-only exclusions: the command never upgrades them and fails with installation guidance when one is missing. Scaffold and update retain their narrower repair policy: install missing auto-managed tools and repair declared minimum-version drift only. In particular, their opensrc target remains ^0.7.2, while hi tools ensure uses opensrc@latest. After refreshing agent-browser, the command preserves browser provisioning and skips its browser download when a configured or supported Chrome, Chromium, or Brave executable already exists. Install contracts come from the selected verified baseline, not repo-owned metadata. Stable and exact authority failures stop the command; pass --baseline bundled only when you intentionally want the npm-shipped baseline.

hi -v / hint -v is equivalent to hi --version / hint --version.

hi report submits reusable Harness docs, workflow, tooling, CLI, skill-pack, or wiki friction to the Harness API. Public CLI submissions are validated, given deterministic metadata, deduped against open harness-report issues, and created as GitHub issues for maintainer triage. Missing server GitHub credentials fail the command instead of silently storing an internal-only report.

Interactive commands check the selected npm dist-tag before running. When a newer CLI is available, hi asks for confirmation, reinstalls through the detected global package manager, and exits so the command can be rerun on the upgraded binary. hi upgrade keeps the same installer path as an explicit manual command. Use --tag next for prerelease channels or --force to reinstall the selected tag even when the current version is fresh.

hi check always refetches stable or exact remote baseline metadata and bytes. Its --refresh-baseline flag remains accepted for backward compatibility. Use --baseline bundled or DP_BASELINE=bundled to force the verified npm-shipped baseline for diagnostics or tests.

Language packs are detected separately from framework packs. TypeScript is selected when scanned manifests depend on typescript or when nested source files include .ts / .tsx; Python is selected from nested .py files. Root-level config files and vendor, virtualenv, generated, scaffold, docs, examples, scripts, opensrc, agent/cache/worktree, and build output directories are ignored.

The generated subagent manifest is repo-shaped from selected packs and prompt specs. Python specialists are generated only when the Python language pack is selected.

Use the CLI-owned operator commands for the global hi-cli skill:

hi operator status
hi operator install
hi operator update
hi operator migrate

hi skills rename remains a deprecated alias for hi operator migrate. Operator mutations require the agent to reload or reactivate $hi-cli; their post-command flow does not inspect .devpunks artifacts or run scaffold follow-through. hi upgrade updates only the CLI executable.

Operator commands do not select or forward a Harness agent. Interactive mutations let Skills CLI present its supported target picker. Plain and structured-output mutations use Skills CLI automatic detection. Harness verifies the canonical copy identity returned by Skills CLI and treats its aggregated agents list as provider evidence. Migration removes legacy copies only when the provider-reported replacement bindings cover every provider-reported legacy binding in that scope.

Operator writes require Skills CLI 1.5.20 or newer. The CLI fetches the frozen shared-skills revision into a scoped temporary Git checkout, verifies the fetched commit exactly, and passes the checked-out hi-cli directory to skills add --copy. It removes the checkout on every exit and reinspects the installed manifest before migration removes any legacy dp-cli copy.

If Skills CLI lists a hi-cli copy whose content differs from the immutable target, hi operator status reports it as outdated inventory and recommends hi operator update. Project-local outdated inventory still shadows a verified global copy for the current project. Install, update, and migration replace outdated copies, then require exact post-write verification; migration keeps dp-cli when the replacement remains mismatched.

The lint scaffold is intentionally agent-facing rather than repo-mutating:

• selected lint assets are emitted under .devpunks/specs/lint/
• each asset carries Oxlint rule payload plus placement guidance
• if the target repo has no root Oxlint config yet, scaffold also emits a starter .devpunks/specs/lint/oxlint-starter.json
• the follow-up agent fits those assets into the repo's real lint topology instead of hi editing .oxlintrc.json directly

Current scaffold-managed global tools:

• agent-browser
• debug-agent
• opensrc
• portless
• skills

On startup, hi checks interactive TTY commands for a newer CLI and asks before installing. --help, --version, CI, non-interactive commands, and HI_NO_UPDATE_CHECK=1 skip the prompt. The hi-cli operator skill check stays detached and advisory, runs at most once per 12 hours by default, and never updates skills while another CLI command is starting. Set HI_NO_SKILL_UPDATE_CHECK=1 to skip that check or HI_STARTUP_CHECK_INTERVAL_MS=0 to force the worker during local testing.

Publishing

Use one command per release type:

BASELINE_VERSION=YYYY.MM.DD-short-slug BASELINE_CLI_VERSION_RANGE='>=2.6.0 <3' bun run baseline:publish
bun run release:publish

bun run baseline:publish requires an explicit nonblank BASELINE_CLI_VERSION_RANGE, DP_CONTROL_PLANE_URL, and publisher-only DP_BASELINE_PUBLISH_TOKEN. It builds the current scaffold baseline, creates the baseline/stable/<version> GitHub release and uploads the baseline manifest plus tarball once, verifies their GitHub release identity and digests, and sends one authenticated promotion request to the control plane. A retry reuses matching assets and uploads only missing assets without editing or replacing present ones; it refuses mismatched, malformed, or duplicate present assets. The token is sent only as the request bearer credential and is never written to output or the promotion payload.

The durable promotion commit is production publication; baseline publishing does not change deployment configuration or deploy the API. The publisher confirms stable metadata plus manifest and archive identity through the control plane after the commit. A failed or mismatched post-commit confirmation exits nonzero as indeterminate. Retry the same release: its stable publication identity reconciles to the already-committed revision instead of creating a second promotion.

bun run release:publish builds the CLI as a portable Node script with bundled scaffold assets, publishes a sanitized npm package from the built dist/ output, updates the latest dist-tag, also updates next for latest releases, pushes the matching v<version> git tag, and creates or updates the GitHub release title and notes from the categorized CHANGELOG.md content. GitHub notes use compact category labels such as changed: and fixed: without changelog publish metadata. Commit the version bump and changelog entry before running it; the script refuses dirty worktrees, missing changelog entries, uncategorized release notes, and existing tags that point at another commit. Set NPM_TAG=beta for beta prereleases without moving latest.

The published hi / hint commands do not require Bun at runtime. Bun is needed to build and publish from this repo; the npm package contains the compiled Node entrypoint plus bundled scaffold assets.

Before npm releases, authenticate against the public npm registry:

npm login --registry=https://registry.npmjs.org/
npm whoami

The logged-in account must have publish access to @punks/cli.

Development

From the repository root, run the current TypeScript source instead of the globally installed package:

bun run cli -- --help
bun run cli -- check --baseline bundled --input .
bun run cli:entrypoints
bun run cli:ui

bun run cli -- <path> disables the CLI and operator-skill startup update checks for that source process. bun run cli:entrypoints derives every root and nested command path from the executable registry and prints ready-to-copy help commands plus the native global actions. bun run cli:ui renders the developer-only terminal/HTML catalog, retains it in a fresh temporary preview directory, and prints the file:// URL. Use bun run --cwd apps/cli ui:catalog -- --check for a self-cleaning catalog validation or pass --output <run-owned-directory> to choose the retained destination. The catalog script and fixtures are excluded from the npm package.

Interactive output uses open terminal rails: ◇ section headings, │ rows, and a final └ row. The large gradient title appears on the interactive root guide reached through bare hi, hi --help, hi -h, or hi --wizard. Redirected plain output keeps its stable ANSI-free contract. NO_COLOR always disables color; FORCE_COLOR=0 also disables it, while other FORCE_COLOR values enable the configured HI_THEME/COLORFGBG palette.

bun install
bun run build
bun run baseline:build
bun run test
bun run check-types

Docs

• Scaffolding runbook
• Example: cicilca-doc-portal