@punks/cli 1.0.1 → 1.0.3

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

@@ -72,7 +72,10 @@ Current scope:
 - 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
-- keep all non-surface agnostic skill packs mandatory (`docs`, `planning`, `quality`, `research`, `requirements`, `subagents`)
+- 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
@@ -81,11 +84,20 @@ Current scope:
 - 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
+- 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.
 
@@ -101,10 +113,10 @@ After confirmation, `punks scaffold setup` writes:
 - `.devpunks/AGENT-HANDOFF.md`
 - `.devpunks/AGENT-SYSTEM-PROMPT.md`
 - `.devpunks/required-tools.json`
-- `.devpunks/specs/lint/assets.json`
-- `.devpunks/specs/lint/selection.json`
-- `.devpunks/specs/lint/README.md`
-- `.devpunks/specs/lint/oxlint-starter.json` when no root Oxlint config already exists
+- `.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`
@@ -120,13 +132,17 @@ It does **not** write final root/docs/workspace `AGENTS.md` files yet. Those rem
 
 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. Generated prompt specs and handoff text tell 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. In linked git worktrees, portless prefixes hostnames with the branch name, so local URLs must be modeled as stable origins that may vary by worktree. When a local frontend proxy targets another portless app, configure the proxy to rewrite the host/origin so the request reaches the intended service instead of looping back to the caller.
+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 so the follow-up agent can fit the final `.oxlintrc.json` shape to the real repo layout.
+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.
 
@@ -146,13 +162,69 @@ Current scope:
 - 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 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 also performs best-effort startup checks on normal command startup. It checks the npm package version for `@punks/cli`, and it checks for the `dp-cli` skill through the global `skills` CLI, installing it when absent and updating it when present. These 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 `npm install -g @punks/cli@latest` 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
 
 To test the built command locally without preparing another repo first, use the committed fixtures:
 
@@ -167,7 +239,7 @@ Those fixtures include minimal `.devpunks/scaffold-manifest.json` files and inte
 
 ## Content Base
 
-The standalone CLI repo is the canonical source of scaffolded content.
+The standalone CLI repo is the canonical source of scaffolded baseline content.
 
 Bundled source-of-truth assets live under:
 
@@ -178,7 +250,7 @@ Bundled source-of-truth assets live under:
 - `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. Refresh it with:
+`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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@punks/cli",
-  "version": "1.0.1",
-  "description": "DevPunks AI scaffolding CLI",
+  "version": "1.0.3",
+  "description": "Devpunks AI scaffolding CLI",
   "type": "module",
   "bin": {
     "devpunks": "dist/index.js",
@@ -15,8 +15,11 @@
   ],
   "scripts": {
     "build": "node ./scripts/build-dist.mjs",
+    "baseline:build": "bun ./scripts/build-baseline.mjs",
+    "baseline:publish": "node ./scripts/publish-baseline.mjs",
     "check-types": "tsc --noEmit",
     "dev": "bun run ./src/index.ts scaffold",
+    "local": "bun run build && bun run ./dist/index.js",
     "release:publish": "node ./scripts/publish-release.mjs",
     "sync:skills": "node ./scripts/sync-skills-repo.mjs",
     "test": "vitest run --config vitest.config.ts"