hi Requirements

This document captures the durable requirements agreed for the hi CLI so the implementation can evolve without losing the product contract.

Goal

hi is an AI-first scaffolding CLI for agent-ready projects.

It should:

• scaffold the right AI operating context for the current project phase
• keep pre-boilerplate flows lightweight and language-agnostic
• keep repo-aware setup deterministic once a repo and stack exist
• emit operator prompts that guide the next agent through the current gate

Core Principles

• The lifecycle is explicit.
• Pre-boilerplate scaffolding is stage-driven.
• Repo-aware setup is pack-driven.
• Skill selection is curated by the CLI, not exposed as a raw chooser.
• Harness content is built from this repo and distributed only through the public Registry; the CLI ships no bundled Baseline and fetches the Baseline at runtime.

Command Contract

The lifecycle uses four commands (CLI 6.0.0):

• hi init detects the repository once, proposes Packs and Software Scopes, writes Project settings from the confirmed selection, then runs hi update
• hi update installs the latest Baseline from the Registry and writes the Installed Record last
• hi diff reports the Drift Check per managed path and writes nothing
• hi check compares the installed Baseline with the Registry latest and reports status

hi scaffold is retired into hi init.

Pre-Boilerplate Contract

hi init assumes the operator is already inside the target workspace or repository folder.

Since CLI 6.0.0, hi init also detects the repository, fetches the Baseline from the Registry, writes Authored starters such as root AGENTS.md when absent, and never creates or aligns a wiki. Where an item below conflicts with that, the Registry Baseline spec supersedes it.

They should:

• install Registry skills into .agents/skills/ as Copied Artifacts
• keep every Project Skill (a skill no Registry Item provides) in .agents/skills/ and never remove, compare, or overwrite it; move real skill directories from .claude/skills, .codex/skills, .cursor/skills, and .opencode/skills into .agents/skills/
• on an id collision with a Registry skill, rename the Project Skill to .agents/skills/[DEPRECATED] <id> and report it; hi report owns proposals to move project knowledge into shared skills
• leave wiki creation, root selection, framework, and content under project ownership
• ask for the backlog provider and default blank input to GitHub Projects/Issues
• pin selected providers and the backlog project URL in .devpunks/settings.json so later agents keep using the same targets unless the user changes them
• avoid repo-aware pack detection and stack evaluation during init; the CLI does not choose a wiki root
• print a fixed post-command agent prompt to stdout that routes through $hi-cli to check the existing project-owned wiki structure; start $docs-onboarding only after that check passes, then inspect code/docs/backlog context, build the Project Map, and follow the requirements handoff
• make docs-onboarding the canonical existing-project adoption gate before setup when a repo needs initial wiki/spec context reconstructed
• make the requirements grill the canonical gate inside docs onboarding before spec reconstruction and before backlog creation, with write-backlog available after the grill handoff closes
• make write-backlog format accepted requirements as EPICS and subchildren stories: each EPIC is a parent capability and each subchild story is an independently observable product slice beneath that EPIC

Supported init backlog providers:

• GitHub Projects/Issues, the default
• Linear

They should not:

• write a root AGENTS.md
• run repo-aware pack detection yet
• create issues, call external services, or mutate anything beyond the Managed Artifacts and Project settings they own

Since CLI 6.0.0 the Registry installs no wiki; wiki setup belongs to the owning project (user decision 2026-09-28). Detection records an existing wiki root (apps/wiki/, app/wiki/, then wiki/) in the Recorded Shape.

The wiki owns specs, raw inputs, routed project knowledge, and ingest bookkeeping. Operational documentation remains in docs/; the wiki may project those canonical pages. The project owns Mermaid support and other rendering choices.

Before writing durable knowledge or starting $docs-onboarding, the hi-cli post-command handoff checks the existing wiki against the project's routing, frontmatter, navigation, link, and ingest standards and runs its content checks. If no wiki exists, report the check as not-applicable and keep onboarding pending until the user authorizes project-owned wiki creation or selects an existing wiki. Preserve existing routes and authored content.

Repo-Aware Setup Contract

hi init and hi update are the deterministic repo-aware setup flow.

It should:

• detect repo facts, not ask the agent to invent them
• resolve those facts to predefined Harness packs
• scaffold the shared AI setup
• emit instructions/specs the next agent can use to generate repo-scoped prompts and subagent config

The CLI must stay deterministic at the detection/mapping layer and flexible at the final repo-reconciliation layer.

Project Skill Preservation

Skills present before Harness, and skills no Registry Item provides, are Project Skills under .agents/skills/<id>, reachable through the harness links. The installer never removes, compares, or overwrites them. When a Registry Item later provides a Project Skill's id, the Baseline skill wins: the Project Skill directory is renamed [DEPRECATED] <id>, the Registry skill installs under the original id, and the command reports the rename. Semantic overlap is model-guided hi report work, not command runtime behavior.

Repository Model

hi init and hi update must support both:

• monorepos
• single-repo package layouts

Repo shape is part of the Recorded Shape and must stay overrideable with:

• auto
• monorepo
• single

Detection Contract

Initial setup detection is JS/TS manifest based.

Primary sources:

• repo package.json files discovered recursively, with ignore rules for generated/non-source trees

Initial technology mapping:

• next -> nextjs, react
• react, react-dom -> react
• @tanstack/react-query and related query packages -> tanstack-query
• Wiki framework and package choices are project-owned; TanStack Query detection does not select a wiki framework.
• elysia -> elysia
• @trpc/* -> trpc
• drizzle-orm, drizzle-kit -> drizzle
• better-auth -> better-auth
• turbo -> turborepo
• effect, @effect/* -> effect
• @pulumi/pulumi, @pulumi/* -> pulumi

drizzle is data-layer detection only. It must not imply Effect skills or Effect source references unless the effect pack is selected independently.

Pack Contract

Pack selection happens at Pack level only: hi init detection proposes Packs, and settings packs selects them.

The CLI must never ask the user or agent to choose raw skills in the repo-aware setup flow.

Default packs

Default packs are always preselected and visually distinguished. They are not removable.

Current default packs:

• debug debugging-phase, debug-agent
• docs docs-ingest-phase, writing-for-agents
• misc wait-what
• planning delivery-phase, goalify, grilling, create-spec, create-plan, implement-spec, resolve-debt-phase
• subagents swarm-planner
• quality tdd, codebase-design, simplify
• research parallel-research, review-phase, autoreview, improve-codebase-architecture
• requirements requirements-phase, requirements-grill, write-backlog
• security audit-cicd-security, security-best-practices

create-spec, create-plan, implement-spec, and delivery-phase must target EPICS and their subchildren stories when backlog context exists. create-spec anchors on the EPIC and harvests all subchild-story requirements. create-plan maps tasks back to the EPIC and covered subchildren stories. implement-spec preserves those story requirements during execution. delivery-phase must carry that same EPIC -> subchildren stories contract through the whole lifecycle.

The security pack applies two mandatory constraints:

• audit-cicd-security stays read-only by default; remediation actions for critical or high severity require explicit user approval.
• security-best-practices is only introduced for explicit Python, JavaScript, TypeScript, or Go security requests.

Surface packs

Frontend-oriented skills should be grouped into a single detected frontend surface pack:

• frontend agent-browser, design-taste-frontend, frontend-domain-structure

Framework/data packs may layer on top of that surface:

• react async-react-patterns, vercel-composition-patterns, vercel-react-best-practices
• nextjs next-best-practices, next-cache-components
• tanstack-query tanstack-query

Backend-oriented agnostic skills should be grouped into a single detected backend surface pack:

• backend backend-domain-structure, backend-recoverable-actions, logging-best-practices

Prompt Contract

Pre-boilerplate commands use fixed stdout operator prompts.

The Registry must not ship final repo-scoped prompts as static prompt bodies. Instead:

• the shared global harness prompt is a Copied Artifact
• prompt specs for root/docs/workspace scopes are Built Artifacts under .devpunks/specs/prompts/
• instruct the next agent how to turn those specs into final scoped AGENTS.md files

Subagent Manifest Contract

The Registry installs .agents/subagents/manifest.mjs as an Authored Artifact with structured guidance for tailoring it.

That guidance must let the next agent derive:

• which specialists should exist
• owned paths
• guidance files
• packs
• explicit skills
• scope boundaries

Around that manifest:

• shared hooks under .agents/hooks/
• Harness Adapters in the CLI build harness-native agent files for .claude, .codex, .cursor, and .opencode during hi update; no sync script is distributed

Tool Bootstrap Contract

If a Registry skill or Baseline depends on a global external tool, the Baseline declares it as a required tool; hi check reports missing tools and hi tools ensure installs them.

Current examples:

• agent-browser
• opensrc
• portless

Project settings record the required tools.

hi init --yes must support non-interactive harnesses by accepting the proposed Pack selection without terminal prompts. The flag must not add optional packs or answer post-command policy decisions.

hi update --yes must apply the Baseline without prompting. It overwrites a Copied Artifact that has a local edit and an upstream change and reports it; git keeps the local version. Authored Artifacts are never overwritten.

Scaffold setup must not invent or auto-select arbitrary concrete opensrc repositories. The generated post-scaffold instructions should require the next agent to identify the core detected libraries whose source behavior matters, ask the user when that set is ambiguous, and run opensrc path <package> or opensrc path owner/repo for only that focused set.

Framework packs may also declare curated example repositories as maintained pack knowledge. These example repositories are separate from direct package source context: agents inspect them with opensrc path owner/repo to gather real-world patterns and code architectures aligned with the skills included by the selected pack. Concrete curated example lists belong in generated scoped/workspace prompt guidance for the selected packs, while root shared guidance stays generic.

Phase skills are default-distributed but must remain global orchestration entrypoints. Generated prompt specs, handoffs, and update output must instruct follow-up agents to keep requirements-phase, delivery-phase, debugging-phase, review-phase, resolve-debt-phase, and docs-ingest-phase out of scoped AGENTS.md Primary skills here lines.

Lint Scaffold Contract

The shipped starter/root lint baseline should exclude generated and non-source surfaces by default, including:

• all lock files
• all dot-directories
• generated agent/harness folders unless a target repo explicitly opts them back into lint scope

When scaffold guidance leads an agent to adopt Oxlint or Oxfmt, it must tell the agent to replace existing lint/format entrypoints deliberately: package scripts, task pipelines, CI, editor/docs references, and agent hooks should agree on the new tools.

Repo-aware setup should apply selected pack-owned Oxlint assets to the closest owning package or app. If that workspace has no oxlint.config.ts, setup writes a complete package/app config extending Ultracite core plus selected framework presets. Existing JSON/JSONC local rules should be carried forward into the generated config where possible, and selected asset overlays should add only missing JS plugin aliases, settings, and rules while preserving unrelated local policy.

When setup applies Oxlint assets, it should also add missing lint dev dependencies to the nearest owning package.json, including oxlint, ultracite, and any JS plugin packages required by selected overlays. Existing dependency versions must be preserved.

The scaffolded Oxfmt/Oxlint hook should not force a root Oxlint config. It should invoke Oxlint in a way that lets the tool resolve the nearest config for the edited file. Emit the format hook only when oxfmt is declared or Python is detected, because JS/TS formatting still depends on Oxfmt while Python uses Ruff routing.

Ruff lint assets should use the same closest-config and nearest-package model when Python pack-owned rules are added later.

Dedicated CLI Repo Contract

The standalone private wearedevpunks/harness-intelligence repo remains the source of truth for:

• pack registry
• stage-owned scaffold prompts
• subagent templates
• hook base files
• root/shared prompt assets
• examples

The local /Users/stefan/Desktop/repos/wearedevpunks-skills checkout is the authoring source for shareable skill changes in this environment. Edit that source first, push it to wearedevpunks/skills, then run bun run sync:skills here so the CLI cache pulls the committed public tree into local skills/. hi init and hi update fetch the Baseline from the public Registry at runtime, without credentials.