Scaffold Pack

A scaffold pack bundles skills, prompt surfaces, lint metadata, hooks, and required tools for a repo capability.

Pack Types

• Mandatory default packs cover debugging, docs ingest, misc agent interaction, planning, quality, research, requirements, security, subagents, and verification.
• Language packs come from language-specific package or source-file signals. The TypeScript pack also carries the typegraph-runtime item, which gives Codex TypeScript semantic reads.
• Framework and data packs layer on detected libraries such as Effect, React, Next.js, TanStack Query, Drizzle, or Better Auth.
• Surface packs represent broader work areas: frontend for React or Next.js, backend for Better Auth, Drizzle, Elysia, or tRPC, or for api, backend, server, or service-named workspaces.

hi init detection proposes Packs; the operator confirms them, and settings packs is the only selection. pack-core is always installed. A detected Pack that is not selected is information, never drift.

Mandatory default packs distribute the Harness phase wrappers by default: requirements-phase, delivery-phase, review-phase, debugging-phase, docs-ingest-phase, resolve-debt-phase, and goalify.

Framework packs can own curated opensrc example repository context as maintained pack knowledge.

Invariants

• Repo-aware setup resolves packs, not raw skill choices.
• A Pack selects Registry Items through registry dependencies.
• A skill no Registry Item provides is a Project Skill under .agents/skills/<id>; the installer never removes, compares, or overwrites it.
• When a Registry Item later provides a Project Skill's id, the Baseline skill wins and the Project Skill is renamed [DEPRECATED] <id> and reported; semantic overlap belongs to model-guided hi report.
• Surface packs stay scoped to workspaces where the surface applies: a workspace prompt spec lists frontend or backend only when that workspace shows the surface's signals. hi init proposals use the same signals repository-wide.
• Each Pack publishes its catalog promptSurfaces in Pack meta. A workspace prompt spec lists only the default packs whose surfaces include workspace-prompt-spec (debug, planning, quality, research, requirements, security, subagents); docs, misc, and verification stay in the shared, root, and docs specs. The root spec lists every installed pack.
• The docs prompt spec exists only with the docs pack selected and a docs/ directory that git does not ignore (Recorded Shape docsRoot).
• Drizzle detection provides data-layer guidance and does not imply Effect guidance unless Effect is detected independently.
• Phase wrapper skills are distributed by default but stay global orchestration entrypoints. Scoped AGENTS.md Skill | What / when tables contain selected non-phase scoped skills, not phase wrappers.
• Each generated docs/workspace prompt spec requires every selected non-phase scoped skill exactly once in a Skill | What / when table. The follow-up agent derives each concise, scope-specific row from the complete installed SKILL.md.
• Scoped prompt guidance is structure-first and grounded in current Code Evidence. Conditional detail moves into task-triggered ordinary Markdown references authored with the prompt, not into deeper prompt scopes.
• Every scoped prompt visibly links opensrc/README.md and reads it when work depends on third-party library behavior. Root/shared guidance and existing project-authored nested prompts remain preserved.
• The misc pack contributes wait-what only to shared .agents scope; application workspaces do not inherit it.
• The docs pack contributes writing-for-agents; hi init and hi update handoffs activate it before a follow-up agent authors prompt specs, handoffs, scoped AGENTS.md, or subagent instructions.