Scaffold Setup

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
• punks 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.

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.