@punks/cli 1.0.7 → 2.0.0-beta.1

package/AGENTS.md

@@ -1,10 +1,9 @@
-## CLI Guidance
+## CLI App Guidance
 
 Primary skills here: `effect-authoring`, `simplify`.
 
-This repo owns the `punks` CLI surface, repo detection flow, and scaffold-spec orchestration. Keep prompt/spec resolution logic in this repository; do not leak consumer-repo business logic into the CLI itself.
-If you need Effect details, search:
+This app owns the `punks`/`dp` executable, repo detection flow, local scaffold application, bundled baseline fallback, update/diff ergonomics, and release/baseline publishing scripts. Preserve current CLI behavior during monorepo work.
 
-- `opensrc/repos/github.com/Effect-TS/effect/packages/effect`
+Keep consumer-repo product logic out of the CLI. The future backend owns registry, provenance, auth, telemetry, and artifact access; the CLI remains the local scanner, cache, prompt/skill/hook placer, and filesystem writer.
 
-If work here changes operator workflow, setup, or AI scaffolding behavior, update `docs/README.md` and the relevant runbook in the same task.
+If work here changes operator workflow, setup, or AI scaffolding behavior, update `docs/README.md` and `docs/runbooks/dp-cli-scaffolding.md` in the same task.

package/README.md

@@ -42,7 +42,7 @@ Use `--baseline bundled` to force the npm-shipped baseline, or `--refresh-baseli
 
 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.
+The generated subagent manifest is repo-shaped from selected packs and prompt specs. Python specialists are generated only when the Python language pack is selected.
 
 To install only the local `dp-cli` operator skill from the public skills repo checkout:
 
@@ -80,7 +80,7 @@ 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.
+`bun run release:publish` publishes the current `package.json` version to npm, updates the `latest` dist-tag, also updates `next` for latest releases, 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. Set `NPM_TAG=beta` for beta prereleases without moving `latest`.
 
 Before npm releases, authenticate against the public npm registry:
 

package/dist/data/catalog/hooks.ts

@@ -15,4 +15,11 @@ export const hookCatalog = [
       "Shared hook that auto-formats edited JS/TS/JSON files and lint-checks product files after tool use.",
     sourcePath: "hooks/format-edited-file.mjs",
   },
+  {
+    id: "require-tests-for-pr",
+    harness: "shared",
+    outputPath: ".agents/hooks/require-tests-for-pr.mjs",
+    description: "Shared hook that blocks PR creation while tests are failing.",
+    sourcePath: "hooks/require-tests-for-pr.mjs",
+  },
 ] as const satisfies ReadonlyArray<HookDefinition>;

package/dist/data/catalog/lint.ts

@@ -133,22 +133,17 @@ export const lintCatalog = [
     ],
     settings: {},
     rules: {
-      "react-you-might-not-need-an-effect-js/no-adjust-state-on-prop-change":
-        "error",
+      "react-you-might-not-need-an-effect-js/no-adjust-state-on-prop-change": "error",
       "react-you-might-not-need-an-effect-js/no-chain-state-updates": "error",
       "react-you-might-not-need-an-effect-js/no-derived-state": "error",
       "react-you-might-not-need-an-effect-js/no-empty-effect": "error",
       "react-you-might-not-need-an-effect-js/no-event-handler": "error",
       "react-you-might-not-need-an-effect-js/no-initialize-state": "error",
       "react-you-might-not-need-an-effect-js/no-pass-data-to-parent": "error",
-      "react-you-might-not-need-an-effect-js/no-pass-live-state-to-parent":
-        "error",
-      "react-you-might-not-need-an-effect-js/no-reset-all-state-on-prop-change":
-        "error",
+      "react-you-might-not-need-an-effect-js/no-pass-live-state-to-parent": "error",
+      "react-you-might-not-need-an-effect-js/no-reset-all-state-on-prop-change": "error",
     },
-    requiredDevDependencies: [
-      "eslint-plugin-react-you-might-not-need-an-effect",
-    ],
+    requiredDevDependencies: ["eslint-plugin-react-you-might-not-need-an-effect"],
     placement: sharedReactPlacement,
   },
   {
@@ -258,24 +253,15 @@ export const lintCatalog = [
 const stableJson = (value: unknown): string => JSON.stringify(value);
 
 const placementKeyOf = (placement: LintPlacementDefinition): string =>
-  [
-    placement.recommendedConfigFile,
-    ...placement.recommendedFiles,
-  ].join("::");
+  [placement.recommendedConfigFile, ...placement.recommendedFiles].join("::");
 
 export const validateLintCatalog = (
   catalog: ReadonlyArray<LintAssetDefinition>,
 ): ReadonlyArray<LintAssetDefinition> => {
   const seenIds = new Set<string>();
   const seenRules = new Map<string, { readonly assetId: string; readonly value: string }>();
-  const seenSettings = new Map<
-    string,
-    { readonly assetId: string; readonly value: string }
-  >();
-  const seenJsPlugins = new Map<
-    string,
-    { readonly assetId: string; readonly specifier: string }
-  >();
+  const seenSettings = new Map<string, { readonly assetId: string; readonly value: string }>();
+  const seenJsPlugins = new Map<string, { readonly assetId: string; readonly specifier: string }>();
 
   for (const asset of catalog) {
     if (seenIds.has(asset.id)) {

package/dist/data/catalog/packs.ts

@@ -2,7 +2,7 @@ import type { PackCategory, PackId } from "../../core/models";
 import type { LintAssetId } from "./lint";
 import type { SkillId } from "./skills";
 
-export type PackHookId = "format-edited-file";
+export type PackHookId = "format-edited-file" | "require-tests-for-pr";
 export type PackPromptSurfaceId =
   | "shared-agents"
   | "root-prompt-spec"
@@ -23,24 +23,266 @@ export interface PackCatalogEntry {
 }
 
 export const packCatalog = [
-  { id: "backend", category: "surface", triggerPackages: [], description: "Backend pack: domain structure, recoverable actions, and logging.", skills: ["backend-domain-structure", "backend-recoverable-actions", "logging-best-practices"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared backend domain baseline", "workspace backend action/recovery guidance", "workspace logging/observability guidance"] },
-  { id: "better-auth", category: "detected", triggerPackages: ["better-auth"], description: "Better Auth guidance pack.", skills: ["better-auth-best-practices"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared auth guardrails", "workspace auth boundaries"] },
-  { id: "debug", category: "default", triggerPackages: [], description: "Default debug pack: debug-agent runtime-evidence workflow.", skills: ["debug-agent"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared runtime debugging baseline", "workspace evidence-first debugging workflow"] },
-  { id: "docs", category: "default", triggerPackages: [], description: "Default docs pack: docs-maintenance.", skills: ["docs-maintenance"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "docs-prompt-spec"], promptDetails: ["shared docs baseline", "docs scope spec"] },
-  { id: "drizzle", category: "detected", triggerPackages: ["drizzle-kit", "drizzle-orm"], description: "Drizzle guidance pack.", skills: [], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared data-layer baseline", "workspace db flow rules"] },
-  { id: "effect", category: "detected", triggerPackages: ["effect", "@effect/"], description: "Effect guidance pack family.", skills: ["effect-authoring", "effect-best-practices", "effect-backend-structure", "effect-recoverable-actions"], lintAssets: ["effect-no-barrel-imports"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared effect authoring baseline", "workspace service/layer rules"] },
-  { id: "elysia", category: "detected", triggerPackages: ["elysia"], description: "Elysia guidance pack.", skills: ["elysiajs"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared api-server baseline", "workspace route/plugin rules"] },
-  { id: "frontend", category: "surface", triggerPackages: [], description: "Frontend pack: agent-browser, design taste, and frontend domain structure.", skills: ["agent-browser", "design-taste-frontend", "frontend-domain-structure"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared product-ui baseline", "workspace UX/browser guidance", "workspace frontend domain boundaries"] },
-  { id: "nextjs", category: "detected", triggerPackages: ["next"], description: "Next.js guidance pack.", skills: ["next-best-practices", "next-cache-components"], lintAssets: ["next-core"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared app-router baseline", "workspace next rendering rules"] },
-  { id: "planning", category: "default", triggerPackages: [], description: "Default planning pack: grill-me, create-spec, create-plan, implement-spec.", skills: ["grill-me", "create-spec", "create-plan", "implement-spec"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared planning baseline", "workspace plan/spec execution rules"] },
-  { id: "quality", category: "default", triggerPackages: [], description: "Default quality pack: tdd, simplify.", skills: ["tdd", "simplify"], lintAssets: ["vitest-core"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared change-quality baseline", "workspace test/refactor expectations"] },
-  { id: "react", category: "detected", triggerPackages: ["react", "react-dom"], description: "React guidance pack.", skills: ["async-react-patterns", "vercel-composition-patterns", "vercel-react-best-practices"], lintAssets: ["react-core", "react-hooks", "react-you-might-not-need-an-effect"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared react structure baseline", "workspace react composition rules"] },
-  { id: "research", category: "default", triggerPackages: [], description: "Default research pack: parallel-research.", skills: ["parallel-research"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared investigation baseline", "workspace research handoff rules"] },
-  { id: "requirements", category: "default", triggerPackages: [], description: "Default requirements pack: requirements-grill, write-backlog.", skills: ["requirements-grill", "write-backlog"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared requirements baseline", "workspace backlog shaping rules"] },
-  { id: "subagents", category: "default", triggerPackages: [], description: "Default subagents pack: swarm-planner.", skills: ["swarm-planner"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec", "subagent-manifest"], promptDetails: ["shared delegation baseline", "workspace ownership handoffs", "subagent manifest scaffold"] },
-  { id: "tanstack-query", category: "detected", triggerPackages: ["@tanstack/react-query"], description: "TanStack Query guidance pack.", skills: ["tanstack-query"], lintAssets: ["tanstack-query-core"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared tanstack query baseline", "workspace server-state rules"] },
-  { id: "trpc", category: "detected", triggerPackages: ["@trpc/"], description: "tRPC guidance pack.", skills: [], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared contract-first baseline", "workspace client/server boundaries"] },
-  { id: "turborepo", category: "detected", triggerPackages: ["turbo"], description: "Turborepo guidance pack.", skills: ["turborepo"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared monorepo baseline", "workspace task boundary rules"] },
-  { id: "python", category: "language", triggerPackages: [], description: "Shared Python language pack for async, style, structure, testing, and design guidance.", skills: ["async-python-patterns", "python-code-style", "python-design-patterns", "python-project-structure", "python-testing-patterns"], lintAssets: [], hooks: [], promptSurfaces: [], promptDetails: [] },
-  { id: "typescript", category: "language", triggerPackages: ["typescript"], description: "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.", skills: ["quality-types"], lintAssets: [], hooks: ["format-edited-file"], promptSurfaces: [], promptDetails: [] },
+  {
+    id: "backend",
+    category: "surface",
+    triggerPackages: [],
+    description: "Backend pack: domain structure, recoverable actions, and logging.",
+    skills: ["backend-domain-structure", "backend-recoverable-actions", "logging-best-practices"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: [
+      "shared backend domain baseline",
+      "workspace backend action/recovery guidance",
+      "workspace logging/observability guidance",
+    ],
+  },
+  {
+    id: "better-auth",
+    category: "detected",
+    triggerPackages: ["better-auth"],
+    description: "Better Auth guidance pack.",
+    skills: ["better-auth-best-practices"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared auth guardrails", "workspace auth boundaries"],
+  },
+  {
+    id: "debug",
+    category: "default",
+    triggerPackages: [],
+    description: "Default debug pack: debugging phase and debug-agent runtime-evidence workflow.",
+    skills: ["debugging-phase", "debug-agent"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: [
+      "shared runtime debugging baseline",
+      "workspace evidence-first debugging workflow",
+    ],
+  },
+  {
+    id: "docs",
+    category: "default",
+    triggerPackages: [],
+    description: "Default docs pack: docs-ingest-phase.",
+    skills: ["docs-ingest-phase"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "docs-prompt-spec"],
+    promptDetails: ["shared docs baseline", "docs scope spec"],
+  },
+  {
+    id: "drizzle",
+    category: "detected",
+    triggerPackages: ["drizzle-kit", "drizzle-orm"],
+    description: "Drizzle guidance pack.",
+    skills: [],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared data-layer baseline", "workspace db flow rules"],
+  },
+  {
+    id: "effect",
+    category: "detected",
+    triggerPackages: ["effect", "@effect/"],
+    description: "Effect guidance pack family.",
+    skills: [
+      "effect-authoring",
+      "effect-best-practices",
+      "effect-backend-structure",
+      "effect-recoverable-actions",
+    ],
+    lintAssets: ["effect-no-barrel-imports"],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared effect authoring baseline", "workspace service/layer rules"],
+  },
+  {
+    id: "elysia",
+    category: "detected",
+    triggerPackages: ["elysia"],
+    description: "Elysia guidance pack.",
+    skills: ["elysiajs"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared api-server baseline", "workspace route/plugin rules"],
+  },
+  {
+    id: "frontend",
+    category: "surface",
+    triggerPackages: [],
+    description: "Frontend pack: agent-browser, design taste, and frontend domain structure.",
+    skills: ["agent-browser", "design-taste-frontend", "frontend-domain-structure"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: [
+      "shared product-ui baseline",
+      "workspace UX/browser guidance",
+      "workspace frontend domain boundaries",
+    ],
+  },
+  {
+    id: "nextjs",
+    category: "detected",
+    triggerPackages: ["next"],
+    description: "Next.js guidance pack.",
+    skills: ["next-best-practices", "next-cache-components"],
+    lintAssets: ["next-core"],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared app-router baseline", "workspace next rendering rules"],
+  },
+  {
+    id: "planning",
+    category: "default",
+    triggerPackages: [],
+    description:
+      "Default planning pack: delivery phase, specs, plans, implementation, and debt resolution.",
+    skills: [
+      "delivery-phase",
+      "goalify",
+      "grill-me",
+      "create-spec",
+      "create-plan",
+      "implement-spec",
+      "resolve-debt-phase",
+    ],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared planning baseline", "workspace plan/spec execution rules"],
+  },
+  {
+    id: "quality",
+    category: "default",
+    triggerPackages: [],
+    description: "Default quality pack: tdd, simplify.",
+    skills: ["tdd", "simplify"],
+    lintAssets: ["vitest-core"],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared change-quality baseline", "workspace test/refactor expectations"],
+  },
+  {
+    id: "react",
+    category: "detected",
+    triggerPackages: ["react", "react-dom"],
+    description: "React guidance pack.",
+    skills: ["async-react-patterns", "vercel-composition-patterns", "vercel-react-best-practices"],
+    lintAssets: ["react-core", "react-hooks", "react-you-might-not-need-an-effect"],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared react structure baseline", "workspace react composition rules"],
+  },
+  {
+    id: "research",
+    category: "default",
+    triggerPackages: [],
+    description: "Default research pack: parallel research, review, and architecture inspection.",
+    skills: ["parallel-research", "review-phase", "improve-codebase-architecture"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared investigation baseline", "workspace research handoff rules"],
+  },
+  {
+    id: "requirements",
+    category: "default",
+    triggerPackages: [],
+    description: "Default requirements pack: requirements phase, grill, and backlog authoring.",
+    skills: ["requirements-phase", "requirements-grill", "write-backlog"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared requirements baseline", "workspace backlog shaping rules"],
+  },
+  {
+    id: "subagents",
+    category: "default",
+    triggerPackages: [],
+    description: "Default subagents pack: swarm-planner.",
+    skills: ["swarm-planner"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: [
+      "shared-agents",
+      "root-prompt-spec",
+      "workspace-prompt-spec",
+      "subagent-manifest",
+    ],
+    promptDetails: [
+      "shared delegation baseline",
+      "workspace ownership handoffs",
+      "subagent manifest scaffold",
+    ],
+  },
+  {
+    id: "tanstack-query",
+    category: "detected",
+    triggerPackages: ["@tanstack/react-query"],
+    description: "TanStack Query guidance pack.",
+    skills: ["tanstack-query"],
+    lintAssets: ["tanstack-query-core"],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared tanstack query baseline", "workspace server-state rules"],
+  },
+  {
+    id: "trpc",
+    category: "detected",
+    triggerPackages: ["@trpc/"],
+    description: "tRPC guidance pack.",
+    skills: [],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared contract-first baseline", "workspace client/server boundaries"],
+  },
+  {
+    id: "turborepo",
+    category: "detected",
+    triggerPackages: ["turbo"],
+    description: "Turborepo guidance pack.",
+    skills: ["turborepo"],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"],
+    promptDetails: ["shared monorepo baseline", "workspace task boundary rules"],
+  },
+  {
+    id: "python",
+    category: "language",
+    triggerPackages: [],
+    description:
+      "Shared Python language pack for async, style, structure, testing, and design guidance.",
+    skills: [
+      "async-python-patterns",
+      "python-code-style",
+      "python-design-patterns",
+      "python-project-structure",
+      "python-testing-patterns",
+    ],
+    lintAssets: [],
+    hooks: [],
+    promptSurfaces: [],
+    promptDetails: [],
+  },
+  {
+    id: "typescript",
+    category: "language",
+    triggerPackages: ["typescript"],
+    description:
+      "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.",
+    skills: ["quality-types"],
+    lintAssets: [],
+    hooks: ["format-edited-file", "require-tests-for-pr"],
+    promptSurfaces: [],
+    promptDetails: [],
+  },
 ] as const satisfies ReadonlyArray<PackCatalogEntry>;