@punks/cli 1.0.2 → 1.0.3

package/README.md

@@ -1,4 +1,4 @@
-# DevPunks CLI
+# 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/`.
@@ -82,6 +82,15 @@ bun run release:publish
 
 `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:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm whoami
+```
+
+The logged-in account must have publish access to `@punks/cli`.
+
 ## Development
 
 ```bash

package/dist/data/catalog/lint.ts

@@ -25,31 +25,24 @@ export interface LintAssetDefinition {
 
 const sharedReactPlacement = {
   recommendedConfigFile: ".oxlintrc.json",
-  recommendedFiles: [
-    "apps/web/**/*.{js,jsx,ts,tsx}",
-    "packages/ui/**/*.{js,jsx,ts,tsx}",
-  ],
-  recommendedWorkspaces: ["apps/web", "packages/ui"],
+  recommendedFiles: ["<detected-react-workspace>/**/*.{js,jsx,ts,tsx}"],
+  recommendedWorkspaces: ["detected React workspaces"],
   placementNotes:
-    "Add as an override for React-rendered code. Keep the same scope for shared UI packages unless the target repo clearly splits product UI into other workspaces.",
+    "Add as an override for detected React-rendered code. Keep backend packages outside this override unless they render React.",
 } as const satisfies LintPlacementDefinition;
 
 const webOnlyPlacement = {
   recommendedConfigFile: ".oxlintrc.json",
-  recommendedFiles: ["apps/web/**/*.{js,jsx,ts,tsx}"],
-  recommendedWorkspaces: ["apps/web"],
+  recommendedFiles: ["<detected-nextjs-workspace>/**/*.{js,jsx,ts,tsx}"],
+  recommendedWorkspaces: ["detected Next.js workspaces"],
   placementNotes:
     "Place this in the Next.js app override. If the repo uses a different frontend app path, retarget the file globs to that workspace before composing the final Oxlint config.",
 } as const satisfies LintPlacementDefinition;
 
 const effectPlacement = {
   recommendedConfigFile: ".oxlintrc.json",
-  recommendedFiles: [
-    "apps/server/**/*.{js,jsx,ts,tsx}",
-    "packages/api/**/*.{js,jsx,ts,tsx}",
-    "packages/db/**/*.{js,jsx,ts,tsx}",
-  ],
-  recommendedWorkspaces: ["apps/server", "packages/api", "packages/db"],
+  recommendedFiles: ["<detected-effect-workspace>/**/*.{js,jsx,ts,tsx}"],
+  recommendedWorkspaces: ["detected Effect workspaces"],
   placementNotes:
     "Apply this only where Effect code lives. If the target repo renames or splits backend workspaces, move the override with those code paths instead of broadening it repo-wide.",
 } as const satisfies LintPlacementDefinition;
@@ -57,11 +50,10 @@ const effectPlacement = {
 const vitestPlacement = {
   recommendedConfigFile: ".oxlintrc.json",
   recommendedFiles: [
-    "apps/web/**/*.{test,spec}.{js,jsx,ts,tsx}",
-    "apps/web/src/test/**/*.{js,jsx,ts,tsx}",
-    "packages/api/**/*.{test,spec}.{js,jsx,ts,tsx}",
+    "<detected-test-workspace>/**/*.{test,spec}.{js,jsx,ts,tsx}",
+    "<detected-test-workspace>/src/test/**/*.{js,jsx,ts,tsx}",
   ],
-  recommendedWorkspaces: ["apps/web", "packages/api"],
+  recommendedWorkspaces: ["detected JavaScript/TypeScript test workspaces"],
   placementNotes:
     "Attach this to test-only globs. Expand or narrow the file patterns to match the repo's actual Vitest test layout instead of treating it as a global default.",
 } as const satisfies LintPlacementDefinition;

package/dist/data/catalog/packs.ts

@@ -23,11 +23,11 @@ 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: "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: ["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: "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"] },

package/dist/data/catalog/skills.ts

@@ -15,6 +15,7 @@ export const skillCatalog = [
   { id: "agent-browser", sourceDirectory: "skills/agnostic/frontend/agent-browser", tier: "framework", language: null, framework: "browser-automation", requiresTools: ["agent-browser"] },
   { id: "backend-domain-structure", sourceDirectory: "skills/agnostic/backend/backend-domain-structure", tier: "agnostic", language: null, framework: null, requiresTools: [] },
   { id: "backend-recoverable-actions", sourceDirectory: "skills/agnostic/backend/backend-recoverable-actions", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "logging-best-practices", sourceDirectory: "skills/agnostic/backend/logging-best-practices", tier: "agnostic", language: null, framework: null, requiresTools: [] },
   { 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: [] },

package/dist/data/scripts/sync-subagents.mjs

@@ -52,92 +52,131 @@ const cursorManagedComment =
 const opencodeManagedComment =
   "<!-- Generated by scripts/sync-subagents.mjs. Edit .agents/subagents/manifest.mjs instead. -->";
 
-const codexAgentConfig = [
-  "[agents]",
-  "max_threads = 6",
-  "max_depth = 1",
-  "",
-  "[features]",
-  "codex_hooks = true",
-  "",
-  "[hooks]",
-  "SessionStart = [",
-  '  { matcher = "startup|resume", hooks = [',
-  '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/format-edited-file.mjs\\" session-start", statusMessage = "Capturing edited-file baseline", timeout = 30 },',
-  "  ] },",
-  "]",
-  "PreToolUse = [",
-  '  { matcher = "Bash|.*[Pp]ull.?[Rr]equest.*|.*[Pp][Rr].?[Cc]reate.*|.*create[_-]?pull[_-]?request.*", hooks = [',
-  '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/require-tests-for-pr.mjs\\" codex", statusMessage = "Checking tests before PR creation", timeout = 600 },',
-  "  ] },",
-  "]",
-  "PostToolUse = [",
-  '  { matcher = "Bash|apply_patch|.*apply.?patch.*|edit|write|multiedit", hooks = [',
-  '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/format-edited-file.mjs\\" post", statusMessage = "Auto-formatting edited files", timeout = 30 },',
-  "  ] },",
-  "]",
-  "",
-].join("\n");
+function buildCodexAgentConfig({ hasFormatHook, hasTestHook }) {
+  const lines = [
+    "[agents]",
+    "max_threads = 6",
+    "max_depth = 1",
+    "",
+    "[features]",
+    "codex_hooks = true",
+    "",
+    "[hooks]",
+  ];
+
+  if (hasFormatHook) {
+    lines.push(
+      "SessionStart = [",
+      '  { matcher = "startup|resume", hooks = [',
+      '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/format-edited-file.mjs\\" session-start", statusMessage = "Capturing edited-file baseline", timeout = 30 },',
+      "  ] },",
+      "]",
+    );
+  }
+
+  if (hasTestHook) {
+    lines.push(
+      "PreToolUse = [",
+      '  { matcher = "Bash|.*[Pp]ull.?[Rr]equest.*|.*[Pp][Rr].?[Cc]reate.*|.*create[_-]?pull[_-]?request.*", hooks = [',
+      '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/require-tests-for-pr.mjs\\" codex", statusMessage = "Checking tests before PR creation", timeout = 600 },',
+      "  ] },",
+      "]",
+    );
+  }
 
-const claudeSettingsConfig = {
-  hooks: {
-    PreToolUse: [
-      {
-        matcher: "mcp__github__create_pull_request",
-        hooks: [
-          {
-            type: "command",
-            command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
-            timeout: 600,
-          },
-        ],
-      },
-      {
-        matcher: "Bash",
-        hooks: [
-          {
-            type: "command",
-            command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
-            timeout: 600,
-          },
-        ],
-      },
-    ],
-    PostToolUse: [
-      {
-        matcher: "Edit|Write|MultiEdit",
-        hooks: [
-          {
-            type: "command",
-            command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/format-edited-file.mjs claude',
-            timeout: 30,
-          },
-        ],
-      },
-    ],
-  },
-};
-
-const cursorHooksConfig = {
-  version: 1,
-  hooks: {
-    beforeMCPExecution: [
-      {
-        command: "node .cursor/hooks/require-tests-for-pr.mjs cursor",
-      },
-    ],
-    beforeShellExecution: [
-      {
-        command: "node .cursor/hooks/require-tests-for-pr.mjs cursor",
-      },
-    ],
-    afterFileEdit: [
-      {
-        command: "node .cursor/hooks/format-edited-file.mjs cursor",
-      },
-    ],
-  },
-};
+  if (hasFormatHook) {
+    lines.push(
+      "PostToolUse = [",
+      '  { matcher = "Bash|apply_patch|.*apply.?patch.*|edit|write|multiedit", hooks = [',
+      '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/format-edited-file.mjs\\" post", statusMessage = "Auto-formatting edited files", timeout = 30 },',
+      "  ] },",
+      "]",
+    );
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+function buildClaudeSettingsConfig({ hasFormatHook, hasTestHook }) {
+  return {
+    hooks: {
+      ...(hasTestHook
+        ? {
+            PreToolUse: [
+              {
+                matcher: "mcp__github__create_pull_request",
+                hooks: [
+                  {
+                    type: "command",
+                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
+                    timeout: 600,
+                  },
+                ],
+              },
+              {
+                matcher: "Bash",
+                hooks: [
+                  {
+                    type: "command",
+                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
+                    timeout: 600,
+                  },
+                ],
+              },
+            ],
+          }
+        : {}),
+      ...(hasFormatHook
+        ? {
+            PostToolUse: [
+              {
+                matcher: "Edit|Write|MultiEdit",
+                hooks: [
+                  {
+                    type: "command",
+                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/format-edited-file.mjs claude',
+                    timeout: 30,
+                  },
+                ],
+              },
+            ],
+          }
+        : {}),
+    },
+  };
+}
+
+function buildCursorHooksConfig({ hasFormatHook, hasTestHook }) {
+  return {
+    version: 1,
+    hooks: {
+      ...(hasTestHook
+        ? {
+            beforeMCPExecution: [
+              {
+                command: "node .cursor/hooks/require-tests-for-pr.mjs cursor",
+              },
+            ],
+            beforeShellExecution: [
+              {
+                command: "node .cursor/hooks/require-tests-for-pr.mjs cursor",
+              },
+            ],
+          }
+        : {}),
+      ...(hasFormatHook
+        ? {
+            afterFileEdit: [
+              {
+                command: "node .cursor/hooks/format-edited-file.mjs cursor",
+              },
+            ],
+          }
+        : {}),
+    },
+  };
+}
 
 function getSkillNames(agent) {
   if (Array.isArray(agent.skills)) {
@@ -306,6 +345,18 @@ async function ensureSymlink(linkPath, targetPath) {
   await symlink(relativeTarget, linkPath);
 }
 
+async function pathExists(filePath) {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
 async function writeManagedFiles(directory, extension, renderedByName) {
   await mkdir(directory, { recursive: true });
 
@@ -340,38 +391,26 @@ async function syncHookSurface() {
   await mkdir(cursorHooksDir, { recursive: true });
   await mkdir(opencodePluginsDir, { recursive: true });
 
-  await ensureSymlink(
-    path.join(codexHooksDir, "format-edited-file.mjs"),
-    path.join(sharedHooksPath, "format-edited-file.mjs"),
-  );
-  await ensureSymlink(
-    path.join(codexHooksDir, "require-tests-for-pr.mjs"),
-    path.join(sharedHooksPath, "require-tests-for-pr.mjs"),
-  );
-  await ensureSymlink(
-    path.join(claudeHooksDir, "format-edited-file.mjs"),
-    path.join(sharedHooksPath, "format-edited-file.mjs"),
-  );
-  await ensureSymlink(
-    path.join(claudeHooksDir, "require-tests-for-pr.mjs"),
-    path.join(sharedHooksPath, "require-tests-for-pr.mjs"),
-  );
-  await ensureSymlink(
-    path.join(cursorHooksDir, "format-edited-file.mjs"),
-    path.join(sharedHooksPath, "format-edited-file.mjs"),
-  );
-  await ensureSymlink(
-    path.join(cursorHooksDir, "require-tests-for-pr.mjs"),
-    path.join(sharedHooksPath, "require-tests-for-pr.mjs"),
-  );
-  await ensureSymlink(
-    path.join(opencodePluginsDir, "format-edited-file.mjs"),
-    path.join(sharedHooksPath, "format-edited-file.mjs"),
-  );
-  await ensureSymlink(
-    path.join(opencodePluginsDir, "require-tests-for-pr.mjs"),
-    path.join(sharedHooksPath, "require-tests-for-pr.mjs"),
-  );
+  for (const hookName of ["format-edited-file.mjs", "require-tests-for-pr.mjs"]) {
+    const sourcePath = path.join(sharedHooksPath, hookName);
+    const targetPaths = [
+      path.join(codexHooksDir, hookName),
+      path.join(claudeHooksDir, hookName),
+      path.join(cursorHooksDir, hookName),
+      path.join(opencodePluginsDir, hookName),
+    ];
+
+    if (await pathExists(sourcePath)) {
+      for (const targetPath of targetPaths) {
+        await ensureSymlink(targetPath, sourcePath);
+      }
+      continue;
+    }
+
+    for (const targetPath of targetPaths) {
+      await rm(targetPath, { force: true, recursive: true });
+    }
+  }
 }
 
 async function syncSkillMirrors() {
@@ -404,10 +443,14 @@ async function main() {
   await mkdir(path.dirname(codexConfigPath), { recursive: true });
   await mkdir(path.dirname(claudeSettingsPath), { recursive: true });
   await mkdir(path.dirname(cursorHooksJsonPath), { recursive: true });
-  await writeFile(codexConfigPath, codexAgentConfig, "utf8");
+  const availableHooks = {
+    hasFormatHook: await pathExists(path.join(sharedHooksPath, "format-edited-file.mjs")),
+    hasTestHook: await pathExists(path.join(sharedHooksPath, "require-tests-for-pr.mjs")),
+  };
+  await writeFile(codexConfigPath, buildCodexAgentConfig(availableHooks), "utf8");
   await rm(path.join(codexDir, "hooks.json"), { force: true });
-  await writeFile(claudeSettingsPath, encodeJson(claudeSettingsConfig), "utf8");
-  await writeFile(cursorHooksJsonPath, encodeJson(cursorHooksConfig), "utf8");
+  await writeFile(claudeSettingsPath, encodeJson(buildClaudeSettingsConfig(availableHooks)), "utf8");
+  await writeFile(cursorHooksJsonPath, encodeJson(buildCursorHooksConfig(availableHooks)), "utf8");
   await writeManagedFiles(claudeAgentsDir, "md", claudeFiles);
   await writeManagedFiles(codexAgentsDir, "toml", codexFiles);
   await writeManagedFiles(cursorAgentsDir, "md", cursorFiles);

package/dist/data/subagents/manifest.mjs

@@ -62,6 +62,11 @@ const capabilityPacks = {
       "Repo documentation maintenance, routing, and human-facing durable knowledge capture.",
     skills: ["docs-maintenance"],
   },
+  "review-core": {
+    description:
+      "Cross-cutting review, simplification, and architecture-friction analysis for changed code.",
+    skills: ["simplify", "improve-codebase-architecture"],
+  },
   "python-core": {
     description:
       "Python project structure, code style, design boundaries, and everyday implementation guidance.",
@@ -102,7 +107,31 @@ const skillActivationInstructions = [
   "Do not rely on role name or inherited context alone; scoped AGENTS.md skill routing is part of the task contract.",
 ];
 
+const reviewActivationInstructions = [
+  ...skillActivationInstructions,
+  "Stay read-only unless the parent explicitly asks for fixes.",
+  "Lead with findings, sorted by severity, with precise file/line references.",
+  "Use `simplify` to evaluate whether recently changed code can be clearer, smaller, or less stateful.",
+  "Use `improve-codebase-architecture` only when the review reveals cross-module coupling, shallow-module sprawl, testability friction, or AI-navigation problems worth surfacing.",
+];
+
 const agents = [
+  {
+    name: "code-review",
+    description:
+      "Use for cross-cutting code review centered on bugs, regressions, simplification opportunities, architecture friction, and review-ready findings across changed code.",
+    ownedPaths: ["**/*"],
+    guidanceFiles: ["AGENTS.md"],
+    activationInstructions: reviewActivationInstructions,
+    packs: ["review-core"],
+    skills: ["simplify", "improve-codebase-architecture"],
+    boundaries: [
+      "Review first: identify concrete defects, behavioral risks, missing tests, and simplification opportunities before summarizing.",
+      "Do not edit files unless the parent explicitly assigns implementation after the review.",
+      "Keep architecture notes grounded in observed code friction; return candidate refactors or follow-up RFC recommendations instead of speculative rewrites.",
+      "If the task asks for feature work rather than review, tell the parent to use the relevant implementation specialist.",
+    ],
+  },
   {
     name: "docs-maintenance",
     description: