Scaffold Setup

Historical (retired in CLI 6.0.0). This page describes the manifest-driven lifecycle (hi scaffold, hi ensure, hi update --check). The Registry Baseline replaced it with hi init, hi update, hi diff, and hi check: see Scaffold Baseline and the CLI scaffolding runbook.

Root hi init establishes project settings and the adoption scaffold. hi scaffold then detects repository shape, resolves scaffold packs, confirms or auto-accepts the pack selection, and writes managed AI operating-context output.

Trigger

An operator runs root hi init in an uninitialized repository, then runs hi scaffold when the repository shape is ready for repo-aware setup. Scaffold accepts --input, --output, and non-interactive --yes.

Actors

• Operator
• hi CLI
• Follow-up agent

Steps

1. hi init asks for backlog, asset, repository-manager, backlog-URL, and wiki choices.
2. Init creates .devpunks/settings.json through the settings authority, seeds the default managed surface and wiki onboarding, and records the first accepted CLI/baseline versions.
3. hi scaffold checks base required tools such as portless and skills.
4. Scaffold scans package manifests and source signals while ignoring generated and non-source trees.
5. It detects repository shape and technologies, resolves the default and detected packs, and asks for confirmation unless --yes accepts them.
6. It checks selected-pack tools, resolves the scaffold baseline, and compiles one desired scaffold state from the final semantic inputs.
7. It applies the desired state, writes .devpunks/scaffold-manifest.json, and records truthful projection evidence.
8. It writes the next-agent prompt, tries to copy it to the clipboard, and hands scoped reconciliation to the follow-up agent.

When that continuation writes or edits prompt specs, handoffs, root/scoped AGENTS.md, or subagent templates/instructions, the generated handoff activates writing-for-agents first and points at the artifact being authored.

The boundary is deliberate: the CLI owns deterministic generation and the handoff text; writing-for-agents governs the follow-up agent's authored instructions.

Generated docs/workspace prompt specs are the detailed authority for scoped prompt authoring. The follow-up agent turns current Code Evidence into structure-first folder, placement, dependency, and boundary rules before applied coding or authoring conventions. It authors each lean prompt and its task-triggered ordinary Markdown references together, adds every selected non-phase skill once as a Skill | What / when row derived from the complete installed SKILL.md, and always links opensrc/README.md; the guide is read when work depends on third-party library behavior.

The Scaffold branch of $hi-cli routes concisely to that contract. The continuation completes each generated docs/workspace target, preserves root/shared guidance and existing nested prompts, creates no deeper prompt scopes, and verifies every relative reference.

Key outputs include .agents/, harness mirrors for Claude/Codex/Cursor/OpenCode, .devpunks/scaffold-manifest.json, prompt specs, lint specs, subagent specs, required-tool metadata, and the next-agent handoff prompt.

Skill Reconciliation

Setup does not inspect or classify skill overlap. It writes generated handoff guidance for the follow-up agent to inspect .agents/skills, .claude/skills, .codex/skills, .cursor/skills, and .opencode/skills.

Exact canonical skill directory id/name intersections with selected pack skills are baseline-owned: the agent keeps the Harness baseline active, archives local evidence under .devpunks/replaced-skills/<skill-id>/..., and removes active local copies or mirrors.

Non-intersecting local skills are repo-owned. The agent preserves them in .agents/skills and exposes them through harness sync so supported harnesses point back to the shared skill source instead of keeping divergent copies. Semantic overlap and baseline integration proposals go through model-guided hi report.

The setup flow writes specifications and managed scaffold assets. Final scoped AGENTS.md prompts remain an intentional post-scaffold reconciliation step so the agent can fit generic scaffold output to the real project shape.

--yes is intentionally narrow. It accepts the default detected pack selection and skips selection prompts, but it does not invent optional packs or resolve post-scaffold policy decisions. Follow-up agents still need to read .devpunks/ artifacts and reconcile generated guidance with the real repository.

Agents should activate $hi-cli before acting on .devpunks artifacts. If hi init seeded a wiki root that does not match the repository layout, reconcile it during this handoff. In monorepos that usually means keeping the routed wiki app and content under apps/wiki; in single-repo layouts it usually means keeping wiki.

Outcome

The repository has explicit settings, a scaffold manifest, and managed AI context that can be checked and refreshed by root hi check and hi update. Pack choices are explicit and recorded before file writes.