Basic Usage

Basic usage has two macro commands.

cd /path/to/repo
hi scaffold init
hi scaffold setup

hi scaffold init prepares the requirements and backlog surface when the project still needs pinned context. hi scaffold setup installs Harness operating context after the repository is ready for setup.

After setup, the important state is the generated handoff. The next agent reads .devpunks output, reconciles generated guidance with the real repository, and then uses the supported Harness flows for requirements, delivery, debugging, review, ClawPatch, and docs closeout.

Agents should activate $hi-cli before following command output or generated .devpunks handoffs.

Workflow

The operator decides when to initialize requirements, answers open requirements questions, confirms selected packs, and reviews the generated handoff. The CLI handles repo scanning, pack resolution, managed-file writes, manifest recording, and update checks. The agent runs skill flows and uses external tools inside those flows when evidence or provider sync requires them.

Backlog providers are interchangeable at this level. Linear and GitHub have different mechanics, but the Harness model is the same: project context becomes an EPIC, and the accepted breakdown becomes child stories or sub-issues under that EPIC.

Capability Map

Capability	Type	Who drives it	What it produces
`hi scaffold init`	Command	Operator + CLI	Docs onboarding and wiki seed, plus the next prompt for context discovery.
`$requirements-phase`	Skill flow	Agent + operator	Project knowledge and context persisted into EPIC and child stories or sub-issues.
`hi scaffold setup`	Command	Operator + CLI	Repo scan, selected packs, managed files, scaffold manifest, and post-setup handoff.
`$delivery-phase`	Skill flow	Agent	Spec, plan, implementation, review, validation, and docs closeout for a scoped goal.
`$debugging-phase`	Skill flow	Agent	Evidence-backed cause, bounded fix, rerun proof, or a concrete blocker.
`$review-phase`	Skill flow	Agent	Findings, risks, missing validation, and simplification or refactor guidance.
ClawPatch lifecycle	Hybrid	Agent + ClawPatch	Discovered findings, selected finding resolution, revalidation, or triage.
`$docs-ingest-phase`	Skill flow	Agent	Routed wiki/project docs and repo-docs alignment after proven changes.
`dp check`	Command	Operator + CLI	Read-only pre-work CLI and scaffold/baseline drift report.
`dp update`	Command	Operator + CLI	Scaffold drift report or accepted managed update.
`hi report`	Command	Operator + CLI	Harness, tooling, or docs friction issue for maintainer triage.

Requirements Gate

Use scaffold init first when the repository needs project context, requirements discovery, backlog shape, or an initial wiki surface.

hi scaffold init

This command seeds docs-onboarding, requirements-grill, write-backlog, create-spec, and the initial wiki structure, then prints the next operator prompt. The next agent should activate $docs-onboarding immediately, inspect code, existing docs, and backlog context, build the Project Map, run the targeted requirements grill, and call create-spec to reconstruct evidence-backed specs. Stop here if the repository needs docs onboarding or requirements shaping before setup.

If the generated wiki root does not match the repository shape, reconcile it before writing durable docs. Monorepos usually keep this content in apps/wiki; single-repo layouts usually keep it in wiki.

Repo-Aware Setup

Use scaffold setup when the repository is ready for Harness installation.

hi scaffold setup

The CLI scans the repo, proposes packs, asks for confirmation, writes managed Harness assets, and records .devpunks/scaffold-manifest.json. Review the proposed packs before accepting them; they decide which skills, prompt specs, tools, and managed files the repo receives.

To scan or write outside the current directory:

hi scaffold setup -i /path/to/repo
hi scaffold setup -i /path/to/repo -o /path/to/output

For the full command contract, see Scaffold Setup.

Updating A Harnessed Repo

Use update after the repository already has .devpunks/scaffold-manifest.json.

dp check
dp update --check
dp update --write

dp check reports CLI executable and scaffold/baseline drift without writing and summarizes changelog entries when available. dp update --check is the lower-level managed scaffold preview. --write applies accepted managed updates. If the manifest is missing, run hi scaffold setup; do not create a legacy root manifest by hand. Accepted dp upgrade or dp update remediation should run in a subagent before project work continues.

Reporting Harness Friction

Use report when a local run exposes reusable Harness friction that maintainers should triage.

hi report --title "Skill guidance stale" --body "The generated guidance references an old command." --type docs

Reports open GitHub issues in wearedevpunks/harness-intelligence for backoffice triage. They are for Harness/tooling/docs feedback, not project product backlog by default.

Success Check

After setup, verify:

.devpunks/scaffold-manifest.json exists
generated prompt specs exist under .devpunks
generated skill and agent surfaces match the selected packs
the generated handoff prompt is present
the next agent can activate $hi-cli and follow the generated handoff

That is the first successful setup. From there, the next agent follows the generated handoff prompt and reconciles scoped guidance with the real repository boundaries.

For command internals, baseline behavior, and manifest semantics, continue to the CLI Domain. For methodology and supported skill flows, continue to Harness Foundations and Supported Flows.