@punks/cli 1.0.7 → 2.0.0-beta.0

package/docs/runbooks/dp-cli-scaffolding.md

@@ -1,261 +0,0 @@
-# `punks` CLI Scaffolding
-
-This repository owns the `punks` command used to scaffold AI operating context across the project lifecycle.
-
-For the durable product contract, see [requirements](../reference/dp-requirements.md). This runbook focuses on how the implementation behaves today.
-
-## Current Command Surface
-
-- `punks scaffold`
-  lifecycle index; prints the available scaffold phases
-- `punks scaffold init`
-  scaffolds the requirements grill and backlog authoring skills, seeds the wiki tree, and prints the operator prompt
-- `punks scaffold backlog`
-  prints the backlog-stage operator prompt; no backlog-stage packs are scaffolded today
-- `punks scaffold setup`
-  runs the repo-aware scaffold flow: detect repo facts, resolve packs, confirm selection, and emit prompts/manifests/hooks
-- `punks update`
-  refreshes scaffold-managed assets from the recorded `.devpunks/scaffold-manifest.json`
-
-## `init` Behavior
-
-`punks scaffold init`:
-
-- writes into the current working directory by default
-- supports `-o, --output <path>` to target a different output directory
-- copies only:
-  - `.agents/skills/requirements-grill`
-  - `.agents/skills/write-backlog`
-- seeds a dedicated wiki tree:
-  - monorepo-shaped target => `apps/wiki/`
-  - single-repo target => `wiki/`
-- creates:
-  - `<wiki-root>/AGENTS.md`
-  - `<wiki-root>/CLAUDE.md` as a symlink mirror of `AGENTS.md`
-  - `<wiki-root>/domains/.gitkeep`
-  - `<wiki-root>/specs/.gitkeep`
-  - `<wiki-root>/raw/assets/.gitkeep`
-  - `<wiki-root>/raw/external/.gitkeep`
-  - `<wiki-root>/raw/meetings/.gitkeep`
-  - `<wiki-root>/index.md`
-  - `<wiki-root>/log.md`
-- overwrites those scaffolded files on rerun
-- prints a fixed operator prompt that tells the next agent to run `requirements-grill`, then `write-backlog` after the grill handoff closes, and treat the scaffolded wiki root as distinct from `docs/`
-
-It does not:
-
-- write a root `AGENTS.md`
-- do full pack or technology detection
-- inspect existing repo shape only enough to choose `apps/wiki` vs `wiki`
-- inspect the PRD location
-- create external side effects
-
-## `backlog` Behavior
-
-`punks scaffold backlog`:
-
-- writes into the current working directory by default
-- supports `-o, --output <path>` to target a different output directory
-- copies no stage-specific packs right now
-- prints a fixed operator prompt that makes the empty backlog stage explicit
-
-It does not scan for the PRD yet and does not scaffold planning skills.
-
-## `setup` Behavior
-
-`punks scaffold setup` is the existing repo-aware scaffold flow.
-
-Current scope:
-
-- scan `package.json` manifests recursively across the target repo, with ignore rules for non-source trees
-- detect normalized technologies from dependency names
-- treat React, Next.js, and TanStack Query as separate frontend capability layers; React is the plain framework pack triggered by `react` / `react-dom` or implied by `next`, and pulls in `async-react-patterns` to prevent outdated manual async state modeling
-- include the `frontend` agnostic surface pack only when React or Next.js is detected; it carries product UI, browser validation, and frontend domain-structure guidance
-- include the `backend` agnostic surface pack when backend framework/data/auth packages are detected (`elysia`, `@trpc/*`, `drizzle-orm`, `drizzle-kit`, `better-auth`) or when package names/manifest paths clearly mark an API/backend/server/service workspace
-- assign backend packs only to backend-looking workspace prompt specs; do not add backend skills to frontend-looking workspaces just because backend/data/auth packs exist elsewhere in the repo
-- include backend logging guidance through `logging-best-practices` anywhere the backend surface pack applies, so backend prompts cover wide events, request context, and production debugging signals alongside structure and recoverability
-- keep Drizzle as data-layer guidance only; do not scaffold Effect skills or Effect opensrc references from Drizzle unless `effect` / `@effect/*` is also detected
-- keep all non-surface agnostic skill packs mandatory (`debug`, `docs`, `planning`, `quality`, `research`, `requirements`, `subagents`)
-- detect monorepo signals from `pnpm-workspace.yaml`, `turbo.json`, root workspaces, and workspace package count
-- resolve predefined packs from those facts
-- run a branded interactive confirmation flow
-- print a human summary plus optional JSON confirmation result to stdout
-- support `-i, --input <path>` to scan a different repository root
-- support `-o, --output <path>` to target a different output location
-- support `--json` to print the full machine-readable scaffold payload on demand
-- support `--repo-shape auto|monorepo|single` to override repo-shape detection when needed
-- support `--baseline stable|bundled` to choose the scaffold content baseline
-- support `--refresh-baseline` to refetch the stable remote baseline instead of reusing the cache
-- copy shared prompt/manifest assets, selected skill directories, shared hook files, harness sync scripts, and subagent templates
-- generate harness-native agent/config/mirror surfaces for `.claude`, `.codex`, `.cursor`, and `.opencode`
-- emit prompt specs, selected lint asset specs, subagent manifest specs, a required-tools manifest, and an agent handoff file
-- write a paste-ready next-agent prompt file and try to copy it to the clipboard automatically
-- include `portless` in the required tools manifest so follow-up agents can standardize local dev URLs across worktrees and avoid raw port collisions
-- include `skills` in the required tools manifest so follow-up agents can install/update public skill entrypoints such as `dp-cli`
-- check the base required tools (`portless`, `skills`) at the start of setup before repo detection, then check selected-pack tools after pack confirmation
-- include `debug-agent` through the default debug pack and install/verify the `debug-agent` CLI without running `debug-agent init`, because the CLI already scaffolds the project-local skill
-- scaffold Oxlint specs/starter config only when scanned package manifests declare `oxlint`, and scaffold the `format-edited-file` Oxfmt/Oxlint hook only when manifests declare `oxfmt`; repos without those tools keep their existing lint/format setup untouched
-- scaffolded hooks infer the target repo package manager from `packageManager` first, then lockfiles, so Oxfmt/Oxlint execution does not hardcode the CLI repo's package manager
-- select language packs separately from framework packs; TypeScript is selected from a `typescript` package dependency or nested `.ts` / `.tsx` files, and Python is selected from nested `.py` files, while ignoring root config files plus vendor, virtualenv, scaffold, docs, examples, scripts, `opensrc`, cache, and build output
-- seed Python subagent templates that combine the Python language skills into `python-app`, `python-async`, and `python-testing` specialists
-- seed a read-only `code-review` subagent template that uses `simplify` for changed-code cleanup review and `improve-codebase-architecture` for grounded architecture-friction findings
-
-If `-o, --output` points at a path that does not exist yet, `punks scaffold setup` creates it before writing the generated files.
-
-## `setup` Output Contract
-
-After confirmation, `punks scaffold setup` writes:
-
-- `.agents/AGENTS.md`
-- `.agents/hooks/*`
-- `.agents/scripts/sync-subagents.mjs`
-- `.agents/skills/*`
-- `.claude/skills` as a symlink to `.agents/skills`
-- `.devpunks/AGENT-HANDOFF.md`
-- `.devpunks/AGENT-SYSTEM-PROMPT.md`
-- `.devpunks/required-tools.json`
-- `.devpunks/specs/lint/assets.json` when `oxlint` is declared
-- `.devpunks/specs/lint/selection.json` when `oxlint` is declared
-- `.devpunks/specs/lint/README.md` when `oxlint` is declared
-- `.devpunks/specs/lint/oxlint-starter.json` when `oxlint` is declared and no root Oxlint config already exists
-- `.devpunks/specs/prompts/shared-agents.md`
-- `.devpunks/specs/prompts/root.md`
-- `.devpunks/specs/prompts/docs.md`
-- `.devpunks/specs/prompts/apps/*/prompt.md`
-- `.devpunks/specs/prompts/packages/*/prompt.md`
-- `.devpunks/specs/subagents/manifest-spec.json`
-- `.agents/subagents/manifest.prompt.md`
-- `.agents/subagents/manifest.mjs`
-- generated harness surfaces under `.claude/`, `.codex/`, `.cursor/`, `.opencode/`
-- `.devpunks/scaffold-manifest.json`
-
-It does **not** write final root/docs/workspace `AGENTS.md` files yet. Those remain authored by the next agent from the generated prompt specs.
-
-After scaffold completes, the CLI writes `.devpunks/AGENT-SYSTEM-PROMPT.md`, tries to copy that prompt to the clipboard, and ends with a short terminal section telling the operator to paste that generated prompt into the next agent.
-
-Scaffolded guidance treats `portless` as the local-development URL baseline. Root/handoff guidance tells follow-up agents to prefer stable `*.localhost` subdomains over raw `localhost:<port>` values in env examples, endpoint defaults, callback URLs, allowed origins, CORS, and app-to-app proxy targets. Scoped prompts should repeat portless guidance only when that workspace directly owns URL, origin, callback, CORS, or proxy configuration.
-
-Scaffolded guidance does not emit concrete opensrc repository refs. The post-scaffold agent must identify the detected core libraries whose source behavior matters for prompt, plan, lint, or implementation decisions, ask the user when the priority is ambiguous, then run `opensrc path <package>` or `opensrc path owner/repo` for that focused set.
-
-Root prompt guidance routes code review requests to findings-first review with precise file/line references. It tells review agents to use `simplify` for clarity, naming, duplication, derivable state, and unnecessary abstraction, and to use `improve-codebase-architecture` only when observed review friction justifies candidate refactors or follow-up RFCs.
-
-When the next agent authors those final prompt files, each root/docs/workspace `AGENTS.md` should be treated as the neutral source of truth and mirrored by a sibling `CLAUDE.md` symlink. `.agents/AGENTS.md` remains the shared global neutral source, and `.claude/CLAUDE.md` should mirror it.
-
-Keep `.agents/skills/` as the main skill directory. Only `.claude/skills` is generated as a compatibility symlink; Codex, Cursor, and OpenCode should read skills from `.agents/skills` instead of maintaining `.codex/skills`, `.cursor/skills`, or `.opencode/skills` mirrors.
-
-It also does **not** mutate the repo's final Oxlint config. Lint is scaffolded as selected pack-owned assets plus placement guidance only when `oxlint` is already present in scanned package manifests, so the follow-up agent can fit the final `.oxlintrc.json` shape to the real repo layout. If the agent adopts Oxlint or Oxfmt, it must replace existing lint/format setup deliberately by updating package scripts, task pipelines, editor/docs references, CI, and agent hooks together instead of leaving stale ESLint/Prettier/Biome entrypoints behind.
-
-The scaffolded starter baseline excludes lock files and dot-directories by default so generated/vendor surfaces do not get linted as product code.
-
-## `update` Behavior
-
-`punks update` is the maintenance path after `punks scaffold setup`.
-
-Current scope:
-
-- reads only `.devpunks/scaffold-manifest.json`
-- uses the recorded `finalPacks` as the update source of truth
-- re-scans package manifests to refresh repo facts and detect pack drift
-- renders the expected scaffold output into a temporary directory before touching the repo
-- diffs managed files with `diff`/jsdiff unified patches
-- asks before writing by default
-- supports `-i, --input <path>` to target a scaffolded repo root
-- supports `--check` to write nothing and exit nonzero when managed updates are available
-- supports `--write` to apply without prompting
-- supports `--json` to print the machine-readable update result
-- supports `--baseline stable|bundled` and `--refresh-baseline`, matching setup behavior
-- restores missing managed files that still belong to the current scaffold output
-- reports stale managed files from the old manifest but does not delete them
-- installs/ensures required tools when applying updates, matching setup behavior
-
-`punks update` updates scaffold-managed assets such as `.agents/AGENTS.md`, selected skills, prompt/lint/subagent specs, hook/script files, harness surfaces, required-tools metadata, handoff prompts, and `.devpunks/scaffold-manifest.json`.
-
-It does **not** silently accept a newly resolved pack set. When current package manifests resolve to different packs than the recorded manifest, update reports pack drift and prints an operator prompt for an agent to rerun `punks scaffold setup` intentionally. It also reports baseline drift when the active baseline version differs from the version recorded in `.devpunks/scaffold-manifest.json`.
-
-## Dynamic Baselines
-
-The npm package is the executable engine. Scaffoldable content resolves through a baseline:
-
-- default: latest remote stable baseline from `wearedevpunks/cli` GitHub releases
-- fallback: bundled baseline shipped in npm when offline, invalid, or unavailable
-- forced fallback: `--baseline bundled` or `DP_BASELINE=bundled`
-- forced refresh: `--refresh-baseline` or `DP_BASELINE_REFRESH=1`
-- local testing: `DP_BASELINE_URL=file:///absolute/path/to/scaffold-baseline`
-
-Baseline artifacts include dynamic scaffoldable data:
-
-- `data/catalog/packs.json`
-- `data/catalog/skills.json`
-- `data/catalog/tools.json`
-- `data/catalog/hooks.json`
-- `data/catalog/lint-assets.json`
-- `data/hooks/`
-- `data/scripts/`
-- `data/subagents/`
-- `skills/`
-
-New packs in a baseline release appear in CLI pack resolution/output without an npm publish when they use the existing pack fields: `id`, `category`, `triggerPackages`, `skills`, `hooks`, `lintAssets`, `promptSurfaces`, and `promptDetails`. Brand-new detection algorithms still require an npm CLI release.
-
-Baseline release tags must never reuse npm semver tags. Use the `baseline/stable/*` namespace for baseline content releases and keep npm executable releases on `v*` tags.
-
-Build and publish the stable baseline release assets with:
-
-```bash
-bun run baseline:build
-bun run baseline:publish
-```
-
-`baseline:build` creates `dist/baseline/scaffold-baseline.json` and `dist/baseline/scaffold-baseline.tgz`. `baseline:publish` creates a GitHub release tag under `baseline/stable/*` and uploads both assets.
-
-Publish npm executable releases with `bun run release:publish` from a clean worktree after authenticating with npm:
-
-```bash
-npm login --registry=https://registry.npmjs.org/
-npm whoami
-```
-
-The npm account must have publish access to `@punks/cli`; otherwise npm may report a confusing scoped-package 404 during `npm publish`.
-
-## CLI Self-Update Detection
-
-The CLI may start best-effort startup checks on normal command startup. The requested command must render immediately; checks run in a detached worker and are rate-limited by a local cache marker to at most once per 12 hours by default. The worker checks the npm package version for `@punks/cli`, and it checks the `dp-cli` skill through the `skills` CLI. It only prints advisory install/update commands. Startup must never install or update packages/skills while another CLI command is starting, and it must never run or suggest plain root `skills update`. These checks are separate from `punks update`, which updates scaffold-managed repo assets.
-
-- checks `https://registry.npmjs.org/%40punks%2Fcli/latest`
-- compares that dist-tag version with the bundled CLI version
-- prints the inferred package-manager update command only when the registry version is newer
-- silently skips the notice when npm is unreachable, the registry response is invalid, or the command is `--help` / `--version`
-- skips in CI and when `DP_NO_UPDATE_CHECK=1`
-- supports `DP_UPDATE_TAG=next` for canary/operator testing against another dist-tag
-- supports `DP_STARTUP_CHECK_INTERVAL_MS=0` to force the detached worker during local testing
-
-To test the built command locally without preparing another repo first, use the committed fixtures:
-
-```bash
-bun run build
-bun ./dist/index.js update -i test-fixtures/single-package --check
-bun ./dist/index.js update -i test-fixtures/monorepo-root --check
-bun ./dist/index.js update -i test-fixtures/root-with-src-monorepo/src --check
-```
-
-Those fixtures include minimal `.devpunks/scaffold-manifest.json` files and intentionally omit the generated managed assets, so `--check` should report missing managed files and exit nonzero.
-
-## Content Base
-
-The standalone CLI repo is the canonical source of scaffolded baseline content.
-
-Bundled source-of-truth assets live under:
-
-- `skills/`
-- `src/data/subagents/`
-- `src/data/hooks/`
-- `src/data/scripts/`
-- `src/data/catalog/`
-- `src/content/stage-scaffold.ts`
-
-`skills/` is refreshed from the public [wearedevpunks/skills](https://github.com/wearedevpunks/skills) repo through a shallow local cache clone. That public repo remains the Vercel skills CLI interface, not the full scaffold baseline source. Refresh local skills with:
-
-```bash
-bun run sync:skills
-```
-
-The sync command replaces only `skills/` and overwrites any local changes there.