@punks/cli 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,8 @@
 # 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 now carries the canonical scaffold content base under `src/data` plus a local `skills/` copy sourced from the public [wearedevpunks/skills](https://github.com/wearedevpunks/skills) repo.
-The CLI runtime stays private; `skills/` is the public, shareable skill surface refreshed through a local shallow-clone cache.
+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](https://github.com/wearedevpunks/skills) repo remains only the Vercel skills CLI interface.
 
 ## Commands
 
@@ -27,6 +27,7 @@ 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.
@@ -35,7 +36,21 @@ bun run sync:skills
 
 `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`, writes scaffold output into the scan root or `-o`, copies the selected skills from the bundled `skills/` catalog, resolves pack-owned lint assets into `.devpunks/specs/lint/`, and ensures required global tool prerequisites for those skills.
+`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:
+
+```bash
+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:
 
@@ -47,18 +62,37 @@ The lint scaffold is intentionally agent-facing rather than repo-mutating:
 Current scaffold-managed global tools:
 
 - `agent-browser`
+- `debug-agent`
 - `opensrc`
+- `portless`
+- `skills`
+
+On startup, `punks` checks npm for a newer CLI version. When it can infer whether the installed binary came from Bun, pnpm, or npm, it updates itself with the same global package manager; otherwise it prints a manual update hint. If the `dp-cli` operator skill is installed in the current project or globally, startup also asks the `skills` CLI to update that skill. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks.
+
+## Publishing
+
+Use one command per release type:
+
+```bash
+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.
 
 ## Development
 
 ```bash
 bun install
 bun run build
+bun run baseline:build
 bun run test
 bun run check-types
 ```
 
 ## Docs
 
-- [Scaffolding runbook](./docs/runbooks/punks-cli-scaffolding.md)
+- [Scaffolding runbook](./docs/runbooks/dp-cli-scaffolding.md)
 - [Example: cicilca-doc-portal](./examples/cicilca-doc-portal/README.md)

package/dist/data/AGENTS.md

@@ -98,12 +98,6 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 In readonly scenarios ONLY spawn subagents aggressively for parallelization opportunities outside code writing. Examples: research, auditing, docs updating, investigating multiple hypotheses, exploring unrelated areas. Fan out whenever possible, synthesize findings before acting.
 
-## Harness Skill Layout
-
-- Keep `.agents/skills/` as the main project-local skill directory.
-- Keep `.claude/skills` as a symlink to `.agents/skills` for Claude compatibility.
-- Do not create `.codex/skills`, `.cursor/skills`, or `.opencode/skills`; Codex, Cursor, and OpenCode should read from `.agents/skills`.
-
 ## Notes — Cross-session Memory
 
 Notebook at `.agents/notes/`. Shared memory across sessions. Never ask permission.

package/dist/data/catalog/hooks.ts

@@ -0,0 +1,26 @@
+export interface HookDefinition {
+  readonly id: string;
+  readonly harness: "shared";
+  readonly outputPath: string;
+  readonly description: string;
+  readonly sourcePath: string;
+}
+
+export const hookCatalog = [
+  {
+    id: "format-edited-file",
+    harness: "shared",
+    outputPath: ".agents/hooks/format-edited-file.mjs",
+    description:
+      "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

@@ -1,11 +1,4 @@
-export type LintAssetId =
-  | "effect-no-barrel-imports"
-  | "next-core"
-  | "react-core"
-  | "react-hooks"
-  | "react-you-might-not-need-an-effect"
-  | "tanstack-query-core"
-  | "vitest-core";
+export type LintAssetId = string;
 
 export interface LintJsPluginDefinition {
   readonly name: string;

package/dist/data/catalog/packs.ts

@@ -25,6 +25,7 @@ export interface PackCatalogEntry {
 export const packCatalog = [
   { id: "backend", category: "surface", triggerPackages: [], description: "Backend pack: domain structure and recoverable actions.", skills: ["backend-domain-structure", "backend-recoverable-actions"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared backend domain baseline", "workspace backend action/recovery 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: ["effect-backend-structure", "effect-recoverable-actions"], 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"] },
@@ -40,5 +41,6 @@ export const packCatalog = [
   { 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: "typescript", category: "language", triggerPackages: ["typescript"], description: "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.", skills: [], lintAssets: [], hooks: ["format-edited-file", "require-tests-for-pr"], promptSurfaces: [], promptDetails: [] },
+  { 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>;

package/dist/data/catalog/skills.ts

@@ -18,6 +18,7 @@ export const skillCatalog = [
   { id: "better-auth-best-practices", sourceDirectory: "skills/frameworks/better-auth/better-auth-best-practices", tier: "framework", language: "typescript", framework: "better-auth", requiresTools: [] },
   { id: "create-plan", sourceDirectory: "skills/agnostic/planning/create-plan", tier: "agnostic", language: null, framework: null, requiresTools: [] },
   { id: "create-spec", sourceDirectory: "skills/agnostic/planning/create-spec", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "debug-agent", sourceDirectory: "skills/agnostic/debug/debug-agent", tier: "agnostic", language: null, framework: null, requiresTools: ["debug-agent"] },
   { id: "docs-maintenance", sourceDirectory: "skills/agnostic/docs/docs-maintenance", tier: "agnostic", language: null, framework: null, requiresTools: [] },
   { id: "effect-authoring", sourceDirectory: "skills/frameworks/effect/effect-authoring", tier: "framework", language: "typescript", framework: "effect", requiresTools: ["opensrc"] },
   { id: "effect-backend-structure", sourceDirectory: "skills/frameworks/effect/effect-backend-structure", tier: "framework", language: "typescript", framework: "effect", requiresTools: ["opensrc"] },
@@ -32,6 +33,12 @@ export const skillCatalog = [
   { id: "next-best-practices", sourceDirectory: "skills/frameworks/nextjs/next-best-practices", tier: "framework", language: "typescript", framework: "nextjs", requiresTools: [] },
   { id: "next-cache-components", sourceDirectory: "skills/frameworks/nextjs/next-cache-components", tier: "framework", language: "typescript", framework: "nextjs", requiresTools: [] },
   { id: "parallel-research", sourceDirectory: "skills/agnostic/research/parallel-research", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "async-python-patterns", sourceDirectory: "skills/languages/python/async-python-patterns", tier: "language", language: "python", framework: null, requiresTools: [] },
+  { id: "python-code-style", sourceDirectory: "skills/languages/python/python-code-style", tier: "language", language: "python", framework: null, requiresTools: [] },
+  { id: "python-design-patterns", sourceDirectory: "skills/languages/python/python-design-patterns", tier: "language", language: "python", framework: null, requiresTools: [] },
+  { id: "python-project-structure", sourceDirectory: "skills/languages/python/python-project-structure", tier: "language", language: "python", framework: null, requiresTools: [] },
+  { id: "python-testing-patterns", sourceDirectory: "skills/languages/python/python-testing-patterns", tier: "language", language: "python", framework: null, requiresTools: [] },
+  { id: "quality-types", sourceDirectory: "skills/languages/typescript/quality-types", tier: "language", language: "typescript", framework: null, requiresTools: [] },
   { id: "async-react-patterns", sourceDirectory: "skills/frameworks/react/async-react-patterns", tier: "framework", language: "typescript", framework: "react", requiresTools: [] },
   { id: "requirements-grill", sourceDirectory: "skills/agnostic/requirements/requirements-grill", tier: "agnostic", language: null, framework: null, requiresTools: [] },
   { id: "simplify", sourceDirectory: "skills/agnostic/quality/simplify", tier: "agnostic", language: null, framework: null, requiresTools: [] },
@@ -44,4 +51,4 @@ export const skillCatalog = [
   { id: "write-backlog", sourceDirectory: "skills/agnostic/requirements/write-backlog", tier: "agnostic", language: null, framework: null, requiresTools: [] },
 ] as const satisfies ReadonlyArray<SkillCatalogEntry>;
 
-export type SkillId = (typeof skillCatalog)[number]["id"];
+export type SkillId = string;

package/dist/data/catalog/tools.ts

@@ -5,6 +5,12 @@ export const toolCatalog = [
     requiredBins: ["node"],
     ensureCommands: [["agent-browser", "install"]],
   },
+  {
+    id: "debug-agent",
+    packageName: "debug-agent",
+    requiredBins: ["node"],
+    ensureCommands: [],
+  },
   {
     id: "opensrc",
     packageName: "opensrc",
@@ -17,6 +23,12 @@ export const toolCatalog = [
     requiredBins: ["node"],
     ensureCommands: [],
   },
+  {
+    id: "skills",
+    packageName: "skills",
+    requiredBins: ["node"],
+    ensureCommands: [],
+  },
 ] as const;
 
-export type ToolId = (typeof toolCatalog)[number]["id"];
+export type ToolId = string;

package/dist/data/subagents/manifest.mjs

@@ -62,6 +62,35 @@ const capabilityPacks = {
       "Repo documentation maintenance, routing, and human-facing durable knowledge capture.",
     skills: ["docs-maintenance"],
   },
+  "python-core": {
+    description:
+      "Python project structure, code style, design boundaries, and everyday implementation guidance.",
+    skills: [
+      "python-project-structure",
+      "python-design-patterns",
+      "python-code-style",
+      "python-testing-patterns",
+    ],
+  },
+  "python-async": {
+    description:
+      "Python asyncio, concurrent I/O, async API boundaries, and async test strategy.",
+    skills: [
+      "async-python-patterns",
+      "python-project-structure",
+      "python-code-style",
+      "python-testing-patterns",
+    ],
+  },
+  "python-quality": {
+    description:
+      "Python pytest coverage, fixture design, style checks, and refactor-safe quality work.",
+    skills: [
+      "python-testing-patterns",
+      "python-code-style",
+      "python-design-patterns",
+    ],
+  },
 };
 
 const skillActivationInstructions = [
@@ -248,6 +277,96 @@ const agents = [
       "If the task is mainly HTTP transport or route mounting, tell the parent to use server-transport instead.",
     ],
   },
+  {
+    name: "python-app",
+    description:
+      "Use for Python application work centered on module structure, implementation, code style, maintainability, and tests.",
+    ownedPaths: [
+      "src/**",
+      "packages/**",
+      "services/**",
+      "apps/**",
+      "tests/**",
+      "pyproject.toml",
+      "requirements*.txt",
+      "uv.lock",
+      "poetry.lock",
+    ],
+    guidanceFiles: ["AGENTS.md"],
+    activationInstructions: skillActivationInstructions,
+    packs: ["python-core", "python-quality", "simplify"],
+    skills: [
+      "python-project-structure",
+      "python-design-patterns",
+      "python-code-style",
+      "python-testing-patterns",
+      "simplify",
+    ],
+    boundaries: [
+      "Own ordinary Python implementation, project layout, module boundaries, and nearby tests.",
+      "If the task is mainly asyncio, concurrent I/O, WebSockets, or async API behavior, tell the parent to use python-async instead.",
+      "If the task is mainly test suite design, fixture cleanup, or pytest behavior without feature work, tell the parent to use python-testing instead.",
+      "If the task is mainly TypeScript, frontend, Effect, or auth-specific work, tell the parent to use the matching non-Python specialist.",
+    ],
+  },
+  {
+    name: "python-async",
+    description:
+      "Use for Python async work centered on asyncio, concurrent I/O, async APIs, background tasks, and async test coverage.",
+    ownedPaths: [
+      "src/**",
+      "packages/**",
+      "services/**",
+      "apps/**",
+      "tests/**",
+      "pyproject.toml",
+    ],
+    guidanceFiles: ["AGENTS.md"],
+    activationInstructions: skillActivationInstructions,
+    packs: ["python-async", "python-quality", "simplify"],
+    skills: [
+      "async-python-patterns",
+      "python-project-structure",
+      "python-code-style",
+      "python-testing-patterns",
+      "simplify",
+    ],
+    boundaries: [
+      "Own async Python flows, cancellation, task lifetime, backpressure, concurrent I/O, and async test coverage.",
+      "Keep structural refactors limited to what the async change needs; broader project layout belongs to python-app.",
+      "If the task is synchronous business logic or package structure, tell the parent to use python-app instead.",
+      "If the task is only pytest fixture or assertion work, tell the parent to use python-testing instead.",
+    ],
+  },
+  {
+    name: "python-testing",
+    description:
+      "Use for Python test work centered on pytest, fixtures, integration boundaries, mocks, coverage, and refactor-safe assertions.",
+    ownedPaths: [
+      "tests/**",
+      "**/tests/**",
+      "src/**",
+      "packages/**",
+      "services/**",
+      "apps/**",
+      "pyproject.toml",
+    ],
+    guidanceFiles: ["AGENTS.md"],
+    activationInstructions: skillActivationInstructions,
+    packs: ["python-quality", "simplify"],
+    skills: [
+      "python-testing-patterns",
+      "python-code-style",
+      "python-design-patterns",
+      "simplify",
+    ],
+    boundaries: [
+      "Own pytest structure, fixtures, parameterization, integration-test shape, and test readability.",
+      "Prefer tests that exercise real behavior over brittle mocks unless the boundary is genuinely external.",
+      "If fixing production Python code becomes the main task, tell the parent to use python-app or python-async depending on the failure.",
+      "If test work crosses into TypeScript, frontend, or Effect-specific systems, tell the parent to split that work to the matching specialist.",
+    ],
+  },
 ];
 
 export { agents, capabilityPacks };