@punks/cli 1.0.1 → 1.0.3

package/README.md

@@ -1,8 +1,8 @@
-# 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 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,13 +62,41 @@ 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.
+
+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
 bun install
 bun run build
+bun run baseline:build
 bun run test
 bun run check-types
 ```

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;
@@ -32,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;
@@ -64,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,10 +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"] },
@@ -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

@@ -15,9 +15,11 @@ 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: [] },
+  { 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 +34,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 +52,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/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);