Devpunks CLI

punks scaffolds the AI operating context for each project phase, from requirements and backlog prep to the repo-aware setup pass. This repo carries the executable CLI plus the canonical bundled scaffold baseline under src/data and skills/. At runtime, scaffold content resolves from the latest stable GitHub release baseline with bundled fallback; the public wearedevpunks/skills repo remains only the Vercel skills CLI interface.

Commands

• punks show the command guide
• punks scaffold show the scaffold lifecycle index
• punks scaffold init scaffold the requirements-stage discovery skill and seed the wiki tree
• punks scaffold backlog print the backlog-stage operator prompt; no backlog-stage packs are scaffolded today
• punks scaffold setup detect the target repo, confirm pack selection, and write repo-aware scaffold output

Usage

punks scaffold
punks scaffold init
punks scaffold backlog
punks scaffold setup
punks scaffold setup -i /path/to/repo
punks scaffold setup -i /path/to/repo -o /path/to/output
bun run sync:skills
bun run baseline:build

bun run sync:skills updates a local cache clone of wearedevpunks/skills and then replaces only skills/, overwriting any local changes there.

punks scaffold init copies .agents/skills/grill-me, seeds a dedicated wiki tree at apps/wiki for monorepos or wiki for single-repo layouts, and then prints the fixed operator prompt for the requirements gate.

punks scaffold backlog does not currently copy any stage-specific packs. It prints the fixed operator prompt for the backlog gate so the lifecycle stays explicit.

punks scaffold setup scans the target repo from cwd or -i, resolves the active scaffold baseline, writes scaffold output into the scan root or -o, copies the selected baseline skills, resolves pack-owned lint assets into .devpunks/specs/lint/, and ensures required global tool prerequisites for those skills.

Use --baseline bundled to force the npm-shipped baseline, or --refresh-baseline to refetch the stable remote baseline.

Language packs are detected separately from framework packs. TypeScript is selected when scanned manifests depend on typescript or when nested source files include .ts / .tsx; Python is selected from nested .py files. Root-level config files and vendor, virtualenv, generated, scaffold, docs, examples, scripts, opensrc, cache, and build output directories are ignored.

The default subagent manifest includes Python templates that combine the language skills into python-app, python-async, and python-testing specialists.

To install only the local dp-cli operator skill from the public skills repo checkout:

npx skills add /Users/stefan/Desktop/repos/wearedevpunks-skills --skill dp-cli --full-depth

The skill source lives at /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/cli/dp-cli.

The lint scaffold is intentionally agent-facing rather than repo-mutating:

• selected lint assets are emitted under .devpunks/specs/lint/
• each asset carries Oxlint rule payload plus placement guidance
• if the target repo has no root Oxlint config yet, scaffold also emits a starter .devpunks/specs/lint/oxlint-starter.json
• the follow-up agent fits those assets into the repo's real lint topology instead of punks editing .oxlintrc.json directly

Current scaffold-managed global tools:

• agent-browser
• debug-agent
• opensrc
• portless
• skills

On startup, punks may start a detached best-effort worker for a newer CLI version and the presence of the dp-cli operator skill. The requested command renders immediately; startup checks are advisory, run at most once per 12 hours by default, and never install/update packages or skills while another CLI command is starting. Set DP_NO_UPDATE_CHECK=1 or DP_NO_SKILL_UPDATE_CHECK=1 to skip those checks, or DP_STARTUP_CHECK_INTERVAL_MS=0 to force the worker during local testing.

Publishing

Use one command per release type:

bun run baseline:publish
bun run release:publish

bun run baseline:publish builds the current scaffold baseline, creates or updates the baseline/stable/<date>-<sha> GitHub release, and uploads the baseline manifest plus tarball. Use it when scaffold data changes but the npm executable does not need a new version.

bun run release:publish publishes the current package.json version to npm, updates the latest and next dist-tags, and pushes the matching v<version> git tag. Commit and push the version bump before running it; the script refuses dirty worktrees and existing tags that point at another commit.

Before npm releases, authenticate against the public npm registry:

npm login --registry=https://registry.npmjs.org/
npm whoami

The logged-in account must have publish access to @punks/cli.

Development

bun install
bun run build
bun run baseline:build
bun run test
bun run check-types

Docs

• Scaffolding runbook
• Example: cicilca-doc-portal