punks Requirements

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

Goal

punks 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.
• Shared bundled assets come from this repo, not network fetches at runtime.

Command Contract

The current lifecycle uses two root commands:

• hi init docs-onboarding gate; scaffolds docs-onboarding, requirements-grill, write-backlog, create-spec, and seeds the wiki tree
• hi scaffold repo-aware setup; detects technologies, resolves packs, and emits prompts/manifests/hooks

Pre-Boilerplate Contract

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

They should:

• copy only their exact stage-owned skills into .agents/skills/
• overwrite those scaffolded files on rerun for idempotency
• do not inspect or classify pre-existing repo skills before copying stage-owned skills
• print post-command guidance that the follow-up agent owns skill reconciliation across .agents/skills, .claude/skills, .codex/skills, .cursor/skills, and .opencode/skills
• tell the agent exact name/id overlap keeps HI baseline active, local evidence belongs under .devpunks/replaced-skills/<skill-id>/..., non-overlaps stay preserved through harness mirrors, and dp report owns semantic overlap or baseline integration proposals
• let init seed the dedicated Mermaid-enabled wiki tree early so later planning/docs skills have a routed project root
• ask for the backlog provider and default blank input to GitHub Projects/Issues
• pin the selected provider in the seeded wiki so later agents keep using the same backlog target unless the user changes it
• avoid pack detection, stack evaluation, or other side effects beyond the minimal repo-shape sniff needed to choose apps/wiki, app/wiki, or wiki
• print a fixed post-command agent prompt to stdout that tells the next agent to activate $docs-onboarding immediately, inspect code/docs/backlog context, build the Project Map, run the targeted requirements grill, then call create-spec
• 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
• Azure DevOps
• monday.com, mapped as milestones/modules -> groups, epics -> parent items, stories -> subitems

They should not:

• write a root AGENTS.md
• run repo-aware pack detection yet
• create issues, call external services, or mutate anything beyond the bundled scaffold files they own

The dedicated wiki tree is part of that bundled stage output:

• monorepo-shaped target => apps/wiki/
• app-surfaced single-repo target with direct app package surfaces under app/ and no workspace signals, or an already-selected app/wiki root => app/wiki/
• standalone single-repo target => wiki/

That wiki tree is not the same thing as docs/. It owns specs, raw inputs, routed project knowledge, and ingest bookkeeping. It includes Mermaid rendering for fenced mermaid diagrams by default.

Agents must reconcile the seeded wiki root with the actual repository layout before writing durable docs. If an existing repo uses a different app boundary, move or refactor the seeded output into that boundary before continuing.

Repo-Aware Setup Contract

hi scaffold remains the deterministic repo-aware scaffold flow.

It should:

• detect repo facts, not ask the agent to invent them
• resolve those facts to predefined Devpunks 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.

Pre-existing Skill Preservation

hi scaffold must not inspect, classify, or decide pre-existing skill overlap before writing selected pack skills. Its command output and generated handoff guidance must tell the follow-up agent to inspect .agents/skills, .claude/skills, .codex/skills, .cursor/skills, and .opencode/skills.

Exact canonical skill directory id/name overlap with selected baseline skills means HI baseline has precedence. The agent should keep the baseline skill active, archive local evidence under .devpunks/replaced-skills/<skill-id>/..., remove active local copies or mirrors, and suggest dp report when local knowledge should be considered for shared baseline integration.

Non-overlapping local skills remain repo-owned guidance. The agent should preserve them and expose them through harness mirrors or symlinks. Semantic or dynamic overlap is model-guided dp report work, not command runtime behavior.

Repository Model

hi scaffold must support both:

• monorepos
• single-repo package layouts

Repo shape remains an invariant used during scaffold generation 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
• TanStack Start wiki scaffolding is an explicit hi init wiki-framework choice, not inferred from TanStack Query detection.
• 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 resolution happens at pack level only during hi scaffold.

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-great-skills
• 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

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.

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.

hi scaffold must not hardcode all final repo-scoped prompts as static bundled prompt bodies. Instead it should:

• directly scaffold only shared global harness prompts
• emit prompt specs for root/docs/workspace scopes
• instruct the next agent how to turn those specs into final scoped AGENTS.md files

Subagent Manifest Contract

hi scaffold must emit structured guidance for .agents/subagents/manifest.mjs.

That guidance must let the next agent derive:

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

It should also scaffold the neutral harness-sync layer around that manifest:

• shared hooks under .agents/hooks/
• harness sync entrypoint under .agents/scripts/sync-subagents.mjs
• generated harness-native agent/config/mirror surfaces for .claude, .codex, .cursor, and .opencode

Tool Bootstrap Contract

If a bundled skill or scaffold baseline depends on a global external tool, the CLI should model that dependency explicitly and ensure the tool is installed during hi scaffold.

Current examples:

• agent-browser
• opensrc
• portless

The scaffold output should also record the resolved tool requirements in a machine-readable manifest.

hi scaffold should check base required tools before repo detection so missing skills or portless is surfaced immediately. Tools required only by selected packs can be checked after pack confirmation.

hi scaffold --yes must support non-interactive harnesses by accepting the resolved default pack selection without terminal prompts. The flag must not add optional packs or answer post-scaffold policy decisions.

punks update --yes must apply managed scaffold updates without prompting. It is the non-interactive apply flag for harnesses that cannot answer punks update confirmation prompts.

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/. Runtime scaffold behavior must not depend on network fetches.