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, scaffold content resolves from the latest stable GitHub release baseline with bundled fallback; the public wearedevpunks/skills repo remains only the Vercel skills CLI interface.

Commands

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

Usage

hi scaffold
hi scaffold init
hi scaffold setup
hi scaffold setup --yes
hi scaffold setup -i /path/to/repo
hi scaffold setup -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 scaffold 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 setup 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.

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 checks required external tools and repairs missing installable tools. In a scaffolded repo it reads tool IDs from .devpunks/settings.json; outside a scaffolded repo it validates the default Harness toolchain. Install contracts come from the trusted stable baseline, with bundled fallback, not from repo-owned metadata. This command is not read-only. It may install or repair missing tools. When agent-browser is present and a supported Chrome, Chromium, or Brave executable already exists, validation, setup, and update should not force a Chrome download.

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.

Use --baseline bundled to force the npm-shipped baseline, or --refresh-baseline to refetch the stable remote baseline.

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.

To install the global hi-cli operator skill from the public skills repo:

skills add https://github.com/wearedevpunks/skills/tree/main/skills/agnostic/cli/hi-cli --skill hi-cli --global --yes

If skills is not installed as a global command yet:

npx skills add https://github.com/wearedevpunks/skills/tree/main/skills/agnostic/cli/hi-cli --skill hi-cli --global --yes

Use hi operator status, install, update, or migrate to manage this independently installed operator skill. 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.

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 DP_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 DP_NO_SKILL_UPDATE_CHECK=1 to skip that check or DP_STARTUP_CHECK_INTERVAL_MS=0 to force the worker during local testing.

Publishing

Use one command per release type:

bun run baseline:publish
bun run release:publish

bun run baseline:publish builds the current scaffold baseline, creates or updates the baseline/stable/<date>-<sha> GitHub release, and uploads the baseline manifest plus tarball. Use it when scaffold data changes but the npm executable does not need a new version.

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

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

Docs

• Scaffolding runbook
• Example: cicilca-doc-portal