@punks/cli 1.0.2 → 1.0.4

package/dist/index.js

@@ -41912,37 +41912,29 @@ var hookCatalog = [
 // src/data/catalog/lint.ts
 var sharedReactPlacement = {
   recommendedConfigFile: ".oxlintrc.json",
-  recommendedFiles: [
-    "apps/web/**/*.{js,jsx,ts,tsx}",
-    "packages/ui/**/*.{js,jsx,ts,tsx}"
-  ],
-  recommendedWorkspaces: ["apps/web", "packages/ui"],
-  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."
+  recommendedFiles: ["<detected-react-workspace>/**/*.{js,jsx,ts,tsx}"],
+  recommendedWorkspaces: ["detected React workspaces"],
+  placementNotes: "Add as an override for detected React-rendered code. Keep backend packages outside this override unless they render React."
 };
 var 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."
 };
 var 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."
 };
 var 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."
 };
 var lintCatalog = [
@@ -42193,11 +42185,11 @@ var validateLintCatalog = (catalog) => {
 
 // src/data/catalog/packs.ts
 var 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"] },
@@ -42220,6 +42212,7 @@ var 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: [] },
@@ -42292,7 +42285,7 @@ var toolCatalog = [
 
 // src/version.ts
 var cliPackageName = "@punks/cli";
-var cliVersion = "1.0.2";
+var cliVersion = "1.0.4";
 
 // src/baseline/bundled.ts
 var bundledBaseline = {
@@ -43135,7 +43128,6 @@ var section = (title, lines3) => [
   ...lines3
 ];
 var maybeSection = (title, lines3) => lines3.length === 1 && lines3[0] === "  \u2205" ? [] : section(title, lines3);
-var collectOpensrcReferences = (result) => [...new Set(result.promptSpecs.flatMap((spec) => spec.opensrcReferences))].toSorted();
 var formatDetectionSummary = (detection) => [
   "Scaffold detection summary",
   `cwd: ${detection.cwd}`,
@@ -43176,58 +43168,50 @@ var formatConfirmationSummary = (result, baseline = bundledBaseline) => [
   ...section("scaffold manifest:", formatList([result.scaffoldManifestFile]))
 ].join(`
 `);
-var formatAgentHandoffSummary = (result) => (() => {
-  const opensrcReferences = collectOpensrcReferences(result);
-  return [
-    "Give this to the next agent",
-    "",
-    "You are continuing a `punks scaffold` run.",
-    "",
-    "Read first:",
-    `  \u2022 \`${result.scaffoldManifestFile}\``,
-    `  \u2022 \`${result.agentHandoffFile}\``,
-    `  \u2022 \`${result.requiredToolsFile}\``,
-    "",
-    ...result.toolBootstrapStatuses.length === 0 ? [] : [
-      "Tool bootstrap status:",
-      ...result.toolBootstrapStatuses.map((entry) => `  \u2022 \`${entry.toolId}\`: ${entry.status === "already-present" ? "already present" : "installed during scaffold"}`),
-      ""
-    ],
-    "What was scaffolded:",
-    "  \u2022 final scoped/root prompt files were not written yet",
-    ...formatList([
-      ...result.promptOutputs,
-      ...result.lintSpecFiles,
-      ...result.skillFiles,
-      ...result.promptSpecFiles,
-      ...result.subagentFiles,
-      ...result.scriptFiles,
-      ...result.hookFiles,
-      ...result.harnessFiles
-    ]),
-    "",
-    "What you must do:",
-    "  1. Treat the prompt spec markdown files as instructions, not final prompt bodies.",
-    result.monorepo ? "  2. Repo is in monorepo mode. Generate final prompt files for root, docs, and each relevant app/package scope." : "  2. Repo is in single-repo mode. Stitch scoped guidance into one root prompt, plus docs guidance when present.",
-    "  3. Read `.devpunks/required-tools.json` and verify `skills`, `portless`, `opensrc`, and `agent-browser` are actually available when listed. If any are missing, install/fix that first.",
-    "  4. Keep the final prompt house style tight: `## ... Guidance`, `Primary skills here`, one short scope-boundary paragraph, optional `opensrc` guidance only when needed, then the docs-update rule.",
-    "  5. Treat every authored root/docs/workspace `AGENTS.md` file as the neutral scoped prompt source and create a sibling `CLAUDE.md` symlink mirror beside each one.",
-    "  6. Keep `.agents/AGENTS.md` as the shared global prompt source behind the scoped prompt tree; `.claude/CLAUDE.md` should mirror that neutral file.",
-    "  7. Keep `.agents/hooks/` as the neutral hook source, `.agents/skills/` as the main skill directory, and `.agents/scripts/sync-subagents.mjs` as the harness sync entrypoint. Only `.claude/skills` should mirror `.agents/skills`.",
-    "  8. Reconcile `.agents/subagents/manifest.mjs` with both `.agents/subagents/manifest.prompt.md` and `.devpunks/specs/subagents/manifest-spec.json`.",
-    "  9. Update owned paths / guidance file references in the subagent manifest to match the real repo shape.",
-    "  10. Use `portless` as the local-dev URL baseline. Prefer stable subdomains over raw `localhost:<port>` values in env examples, endpoint defaults, callback URLs, allowed origins, CORS, and app-to-app proxies.",
-    "  11. When you need source context from installed libraries, run `opensrc path <package>` or `opensrc path owner/repo`, then inspect the returned checkout path.",
-    ...opensrcReferences.length === 0 ? [
-      "  12. Use `opensrc path <package>` or `opensrc path owner/repo` to ensure local source checkouts exist only for the core framework/library sources that materially affect implementation decisions in this repo. Decide autonomously which dependencies are core enough; do not clone everything mechanically."
-    ] : [
-      "  12. Immediately use `opensrc path <package>` or `opensrc path owner/repo` to ensure local source checkouts exist for these core libraries before authoring final prompts or implementation plans. Then inspect the returned checkout paths, especially:",
-      ...opensrcReferences.map((reference) => `      \u2022 \`${reference}\``),
-      "  13. Use `opensrc path <package>` or `opensrc path owner/repo` again when you need source context from other installed libraries beyond that core set."
-    ]
-  ].join(`
+var formatAgentHandoffSummary = (result) => [
+  "Give this to the next agent",
+  "",
+  "You are continuing a `punks scaffold` run.",
+  "",
+  "Read first:",
+  `  \u2022 \`${result.scaffoldManifestFile}\``,
+  `  \u2022 \`${result.agentHandoffFile}\``,
+  `  \u2022 \`${result.requiredToolsFile}\``,
+  "",
+  ...result.toolBootstrapStatuses.length === 0 ? [] : [
+    "Tool bootstrap status:",
+    ...result.toolBootstrapStatuses.map((entry) => `  \u2022 \`${entry.toolId}\`: ${entry.status === "already-present" ? "already present" : "installed during scaffold"}`),
+    ""
+  ],
+  "What was scaffolded:",
+  "  \u2022 final scoped/root prompt files were not written yet",
+  ...formatList([
+    ...result.promptOutputs,
+    ...result.lintSpecFiles,
+    ...result.skillFiles,
+    ...result.promptSpecFiles,
+    ...result.subagentFiles,
+    ...result.scriptFiles,
+    ...result.hookFiles,
+    ...result.harnessFiles
+  ]),
+  "",
+  "What you must do:",
+  "  1. Treat the prompt spec markdown files as instructions, not final prompt bodies.",
+  result.monorepo ? "  2. Repo is in monorepo mode. Generate final prompt files for root, docs, and each relevant app/package scope." : "  2. Repo is in single-repo mode. Stitch scoped guidance into one root prompt, plus docs guidance when present.",
+  "  3. Read `.devpunks/required-tools.json` and verify `skills`, `portless`, `opensrc`, and `agent-browser` are actually available when listed. If any are missing, install/fix that first.",
+  "  4. Keep the final prompt house style tight: `## ... Guidance`, `Primary skills here`, one short scope-boundary paragraph, optional `opensrc` guidance only when needed, then the docs-update rule.",
+  "  5. Treat every authored root/docs/workspace `AGENTS.md` file as the neutral scoped prompt source and create a sibling `CLAUDE.md` symlink mirror beside each one.",
+  "  6. Keep `.agents/AGENTS.md` as the shared global prompt source behind the scoped prompt tree; `.claude/CLAUDE.md` should mirror that neutral file.",
+  "  7. Keep `.agents/hooks/` as the neutral hook source, `.agents/skills/` as the main skill directory, and `.agents/scripts/sync-subagents.mjs` as the harness sync entrypoint. Only `.claude/skills` should mirror `.agents/skills`.",
+  "  8. Reconcile `.agents/subagents/manifest.mjs` with both `.agents/subagents/manifest.prompt.md` and `.devpunks/specs/subagents/manifest-spec.json`.",
+  "  9. Update owned paths / guidance file references in the subagent manifest to match the real repo shape.",
+  "  10. Use `portless` as the local-dev URL baseline. Prefer stable subdomains over raw `localhost:<port>` values in env examples, endpoint defaults, callback URLs, allowed origins, CORS, and app-to-app proxies.",
+  "  11. If adopting Oxlint or Oxfmt, replace existing lint/format setup deliberately: package scripts, task pipelines, CI, editor/docs references, and hooks should agree on the new tools.",
+  "  12. Before authoring final prompts or implementation plans, identify the core detected libraries whose source behavior matters.",
+  "  13. Run `opensrc path <package>` or `opensrc path owner/repo` for those core libraries, then inspect the returned checkout paths. Clone the major framework/runtime libraries you will reason about; do not clone every dependency mechanically."
+].join(`
 `);
-})();
 var formatSelectionPreview = (options3) => [
   "Review scaffold selection before continuing",
   ...section("prefilled packs:", formatPackList(options3.preselectedPacks, options3.baseline)),
@@ -43636,9 +43620,11 @@ When a nested \`AGENTS.md\` lists "Primary skills here", treat those skill names
 
 Do not rely only on the root instructions when a scoped \`AGENTS.md\` exists.
 
+For code review requests, take a review stance: findings first, severity ordered, with precise file/line references. Use \`simplify\` to inspect changed code for clarity, naming, duplication, derivable state, and unnecessary abstraction. Use \`improve-codebase-architecture\` when review uncovers cross-module coupling, shallow-module sprawl, testability friction, or AI-navigation problems; surface grounded candidates and ask before turning them into broader refactor work.
+
 When inspecting external library internals, prefer official docs first. If source context is needed, resolve cached read-only sources with \`opensrc path <package>\` for packages or \`opensrc path owner/repo\` for repositories, then inspect the returned absolute path. This applies broadly to third-party dependencies used here.
 
-Use \`portless\` for local development URLs instead of baking raw \`localhost:<port>\` values into docs, env examples, endpoint defaults, callback URLs, allowed origins, CORS lists, or app-to-app proxy targets. Portless assigns stable \`*.localhost\` subdomains, injects \`PORT\` and \`PORTLESS_URL\` into child processes, and prefixes linked git worktrees with the branch name so parallel worktrees do not collide. When a local dev proxy calls another portless app, rewrite the host/origin (for example Vite \`changeOrigin: true\`) so the proxy reaches the intended app.
+Use \`portless\` for local development URLs instead of baking raw \`localhost:<port>\` values into docs, env examples, endpoint defaults, callback URLs, allowed origins, CORS lists, or app-to-app proxy targets.
 
 If work here changes setup, workflow, AI scaffold surfaces, or other non-obvious behavior, update \`docs/README.md\` and the relevant runbook in \`docs/runbooks/\` in the same task.`;
 var docsPromptTemplate = `## Docs Guidance
@@ -43671,8 +43657,7 @@ var resolveSeededWorkspacePrompt = ({
       "",
       `Primary skills here: ${renderPrimarySkills(primarySkills)}.`,
       "",
-      "This app is the frontend surface. Keep backend logic out of `apps/web`; use `packages/api` for API contracts and `packages/ui` for shared UI primitives.",
-      "Prefer portless URLs and `PORTLESS_URL`-aware env handling for local origins, API endpoints, OAuth/callback URLs, and browser test targets instead of hardcoded ports.",
+      `This app is the frontend surface for \`${relativeWorkspacePath}\`. Keep backend logic out of this workspace; route API contracts and shared UI primitives to their owning workspaces.`,
       ...extraLines,
       "If work here changes non-obvious frontend behavior, integration constraints, or setup expectations, update `docs/README.md` and the relevant domain doc/runbook in the same task."
     ].join(`
@@ -43684,15 +43669,10 @@ var resolveSeededWorkspacePrompt = ({
       "",
       `Primary skills here: ${renderPrimarySkills(primarySkills)}.`,
       "",
-      "This app is the HTTP transport boundary. Keep business logic and Effect layers in `packages/api`; keep `apps/server` focused on Elysia routes, tRPC mounting, and request/response adaptation.",
-      "Treat portless hostnames as the local-dev origin contract. Keep CORS, callback origins, API base URLs, and service-to-service dev targets aligned with stable `*.localhost` names and worktree-prefixed subdomains.",
+      `This app is the HTTP transport boundary for \`${relativeWorkspacePath}\`. Keep business logic in its owning backend/domain workspace; keep this scope focused on routes, mounting, middleware, and request/response adaptation.`,
       "If transport work touches Effect request/response schemas, adapters, or other Effect code, use `effect-authoring` before editing.",
       "",
-      "If you need Effect details, read `packages/api/AGENTS.md` and search:",
-      "",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/effect`",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/sql`",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/sql-drizzle`",
+      "If this workspace uses Effect and source behavior matters, run `opensrc path effect` or the relevant upstream repo lookup before relying on internals.",
       "",
       "If work here changes transport behavior, env/setup, or integration boundaries, update `docs/README.md` and the relevant domain doc/runbook in the same task."
     ].join(`
@@ -43705,10 +43685,8 @@ var resolveSeededWorkspacePrompt = ({
       `Primary skills here: ${renderPrimarySkills(primarySkills)}.`,
       "",
       "This app owns the `punks` CLI surface, repo detection flow, and scaffold-spec orchestration. Keep prompt/spec resolution logic in `apps/cli`; do not leak repo-specific business logic into this app.",
-      "When scaffold guidance touches local development URLs, include portless guidance for stable subdomains, worktree isolation, and env/origin/proxy alignment.",
-      "If you need Effect details, search:",
-      "",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/effect`",
+      "When scaffold guidance touches local development URLs, keep portless guidance concise and repo-wide unless a scoped prompt owns URL/proxy configuration.",
+      "If Effect source behavior matters, run `opensrc path effect` before relying on internals.",
       "",
       "If work here changes operator workflow, setup, or AI scaffolding behavior, update `docs/README.md` and the relevant runbook in the same task."
     ].join(`
@@ -43720,14 +43698,11 @@ var resolveSeededWorkspacePrompt = ({
       "",
       `Primary skills here: ${renderPrimarySkills(primarySkills)}.`,
       "",
-      "`packages/api` is the home for Effect application logic and tRPC procedures. Keep HTTP transport concerns in `apps/server`.",
-      "Use `effect-authoring` before writing or refactoring Effect code. Use `effect-backend-structure` for repo-specific backend layout, and `effect-recoverable-actions` for multi-step mutation flows that need an explicit rollback/repair strategy.",
-      "",
-      "If you need Effect details, search:",
+      `\`${relativeWorkspacePath}\` is the backend/domain workspace. Keep HTTP transport concerns in the transport app when the repo has one.`,
+      "Use Effect skills only when this workspace actually uses Effect. For non-Effect Drizzle/backend code, follow the local backend prompt and nearest package conventions.",
+      "Use `logging-best-practices` when adding or changing backend logging, request context, audit events, telemetry-adjacent diagnostics, or production debugging signals.",
       "",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/effect`",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/sql`",
-      "- `opensrc/repos/github.com/Effect-TS/effect/packages/sql-drizzle`",
+      "If Effect source behavior matters, run `opensrc path effect` or the relevant upstream repo lookup before relying on internals.",
       "",
       "If work here changes procedures, domain boundaries, layer contracts, or required setup, update `docs/README.md` and the relevant domain doc/runbook in the same task."
     ].join(`
@@ -43758,7 +43733,7 @@ var resolveSeededWorkspacePrompt = ({
       "",
       `Primary skills here: ${renderPrimarySkills(primarySkills)}.`,
       "",
-      "This package owns shared frontend/UI primitives used by `apps/web`. Keep package APIs reusable and presentation-focused.",
+      `\`${relativeWorkspacePath}\` owns shared frontend/UI primitives. Keep package APIs reusable and presentation-focused.`,
       ...extraLines,
       "If work here changes shared primitives, design tokens, or usage expectations, update `docs/README.md` and the relevant domain doc/runbook in the same task."
     ].join(`
@@ -43796,9 +43771,9 @@ var renderPromptSpecMarkdown = (spec) => [
   "- Follow with one short paragraph defining the scope boundary: what belongs here vs elsewhere.",
   "- Treat every authored `AGENTS.md` file as the neutral source of truth and create a sibling `CLAUDE.md` symlink mirror that points to it.",
   "- Add `opensrc` / source-inspection guidance only when this scope actually needs it.",
-  "- Add portless guidance anywhere local dev URLs, origins, callbacks, endpoint env vars, CORS, or app-to-app proxies are configured.",
+  "- Add portless guidance only to the root/handoff, or to a scoped prompt that directly owns local URL, origin, callback, CORS, or proxy configuration.",
   "- End with the docs-update rule when work in this scope changes setup, workflow, contracts, or non-obvious behavior.",
-  "- Add extra focused sections only when the scope truly needs them, like the `packages/api` recoverable-action guidance.",
+  "- Add extra focused sections only when the detected scope truly needs them.",
   "",
   "## Selected packs",
   "",
@@ -43808,18 +43783,17 @@ var renderPromptSpecMarkdown = (spec) => [
   "",
   ...bulletList(spec.primarySkills, "- `simplify`"),
   "",
-  "## Opensrc references",
+  "## Source inspection",
   "",
-  ...bulletList(spec.opensrcReferences, "- `(none required for this scope)`"),
+  "- No concrete `opensrc` repositories are preselected by scaffold.",
+  "- During post-scaffold setup, decide which detected core libraries materially affect prompt or lint authoring, then run `opensrc path <package>` or `opensrc path owner/repo` for those libraries before relying on source behavior.",
   "",
   "## Authoring guidance",
   "",
   "- Keep the final prompt concise, imperative, and scope-first.",
-  "- Match the existing repo house style used by prompts like `apps/server/AGENTS.md`, `apps/web/AGENTS.md`, and `packages/api/AGENTS.md`.",
+  "- Match the existing repo house style used by the detected workspace prompt files.",
   "- Preserve this order: heading, `Primary skills here`, scope boundary, optional `opensrc`, docs update rule.",
   "- Route broader monorepo concerns back to the root prompt instead of repeating them in every scope.",
-  "- Prefer portless stable URLs like `https://web.project.localhost` and `https://api.project.localhost` over hardcoded `localhost:<port>` values in docs, env examples, callback URLs, allowed origins, and local proxy targets.",
-  "- When one local app proxies to another through portless, configure the proxy to rewrite the host/origin (for example Vite `changeOrigin: true`) so requests route to the intended app instead of looping back.",
   "- If a seed prompt exists in the source repo, preserve repo-specific constraints while reconciling them with the detected pack set.",
   "- Keep docs-maintenance workflow in prompt files, not in generated docs pages."
 ].join(`
@@ -43840,8 +43814,7 @@ var renderAgentHandoffMarkdown = ({
   harnessFiles,
   scaffoldManifestFile,
   requiredToolsFile,
-  toolBootstrapStatuses,
-  opensrcReferences
+  toolBootstrapStatuses
 }) => [
   "# Agent Handoff",
   "",
@@ -43874,20 +43847,13 @@ var renderAgentHandoffMarkdown = ({
   monorepo ? "4. Because this repo is in monorepo mode, create scoped prompt files for the root, docs scope when present, and each relevant app/package scope." : "4. Because this repo is in single-repo mode, stitch scope guidance into a single root prompt plus docs guidance when present.",
   "5. Author every root/docs/workspace `AGENTS.md` file as the neutral prompt source of truth and create a sibling `CLAUDE.md` symlink mirror beside each one instead of maintaining duplicated prompt bodies.",
   "6. Keep `.agents/AGENTS.md` as the shared global guidance source behind the scoped prompt tree; `.claude/CLAUDE.md` should stay a symlink mirror of that neutral file.",
-  "7. Prefer portless stable local URLs over raw localhost ports in env examples, endpoint constants, callback URLs, allowed origins, CORS, and app-to-app proxy targets. Account for worktree-prefixed subdomains.",
+  "7. Keep portless as the repo-wide local URL baseline: prefer stable local subdomains over raw localhost ports where env examples, endpoint constants, callback URLs, allowed origins, CORS, or app-to-app proxy targets are configured.",
   "8. Use the lint asset specs to reconcile repo Oxlint config. If the repo has no Oxlint config yet, start from the generated starter config instead of inventing a baseline.",
   "9. Keep `.agents/hooks/` as the neutral hook source of truth; harness hook mirrors should point back to it.",
   "10. Use `.agents/scripts/sync-subagents.mjs` to regenerate harness-native agents, hook mirrors, shared prompt mirrors, and the `.claude/skills` compatibility mirror when the neutral manifest changes.",
   "11. Populate or reconcile `.agents/subagents/manifest.mjs` using both the manifest spec JSON and the manifest prompt markdown.",
   "12. Adjust owned paths and guidance file references in the subagent manifest to match the real repo layout. Monorepo vs single-repo shape affects these paths.",
-  "13. When inspecting installed libraries or packages in this repo, run `opensrc path <package>` or `opensrc path owner/repo`, then inspect the returned checkout path for source context instead of mutating vendored code.",
-  ...opensrcReferences.length === 0 ? [
-    "14. Use `opensrc path <package>` or `opensrc path owner/repo` to ensure local source checkouts exist only for the core framework/library sources that materially affect implementation decisions in this repo. Decide autonomously which dependencies are core enough; do not clone everything mechanically."
-  ] : [
-    "14. Immediately use `opensrc path <package>` or `opensrc path owner/repo` to ensure local source checkouts exist for these core libraries before authoring final prompts or implementation plans. Then inspect the returned checkout paths, especially:",
-    ...opensrcReferences.map((reference) => `- \`${reference}\``),
-    "15. Use `opensrc path <package>` or `opensrc path owner/repo` again when you need source context from other installed libraries beyond that core set."
-  ],
+  "13. Before authoring final prompts or implementation plans, identify the core detected libraries whose source behavior matters, run `opensrc path <package>` or `opensrc path owner/repo` for those libraries, then inspect the returned checkout paths. Clone the major framework/runtime libraries you will reason about; do not clone every dependency mechanically.",
   "",
   "## Shared core files",
   "",
@@ -43933,6 +43899,8 @@ var renderLintSpecMarkdown = ({
   "",
   "Use these selected Oxlint assets to fit the target repo's real lint topology.",
   "Treat each asset as an atomic override payload plus placement guidance, not as a pre-merged final `.oxlintrc.json` block.",
+  "If you adopt Oxlint or Oxfmt, replace the repo's existing lint/format entrypoints deliberately: update package scripts, task pipelines, editor/docs references, and agent hooks together so old ESLint/Prettier commands do not remain as stale defaults.",
+  "If the repo already has lint/format tooling, preserve project-specific ignores, generated-file exclusions, and CI behavior while migrating; do not overwrite working config wholesale.",
   "",
   "## Baseline",
   "",
@@ -44062,7 +44030,8 @@ var specPathForPromptTarget = (relativePath) => {
   return path8.join(".devpunks/specs/prompts", path8.dirname(relativePath), "prompt.md");
 };
 var uniqueSorted = (values3) => [...new Set(values3)].toSorted();
-var collectOpensrcReferences2 = (promptSpecs) => uniqueSorted(promptSpecs.flatMap((spec) => spec.opensrcReferences));
+var collectOpensrcReferences = (promptSpecs) => uniqueSorted(promptSpecs.flatMap((spec) => spec.opensrcReferences));
+var detectionHasPackage = (detection, packageName) => detection.manifests.some((manifest) => manifest.dependencies.includes(packageName));
 var selectedSkills = (finalPacks, baseline) => uniqueSorted(finalPacks.flatMap((packId) => skillsForPack(packId, baseline)));
 var selectedHookIds = (finalPacks, baseline) => uniqueSorted(finalPacks.flatMap((packId) => hooksForPack(packId, baseline)));
 var oxlintConfigCandidates = [
@@ -44109,7 +44078,11 @@ var packsForWorkspace = ({
   const hasDependency = (name) => dependencies.has(name);
   const hasDependencyPrefix = (prefix) => dependencyNames.some((name) => name.startsWith(prefix));
   const hasBackendDependency = () => hasDependency("better-auth") || hasDependency("drizzle-orm") || hasDependency("drizzle-kit") || hasDependency("elysia") || hasDependencyPrefix("@trpc/");
+  const hasFrontendDependency = () => hasDependency("next") || hasDependency("react") || hasDependency("react-dom") || hasDependency("@tanstack/react-query");
+  const hasFrontendWorkspaceName = () => relativeWorkspacePath.split(path8.sep).some((segment) => segment === "frontend" || segment === "ui" || segment === "web") || (manifest?.packageName?.replace(/^@[^/]+\//u, "").split(/[^a-zA-Z0-9]+/u).filter((segment) => segment.length > 0).map((segment) => segment.toLowerCase()).some((segment) => segment === "frontend" || segment === "ui" || segment === "web") ?? false);
   const hasBackendWorkspaceName2 = () => relativeWorkspacePath.split(path8.sep).some((segment) => segment === "api" || segment === "backend" || segment === "server" || segment === "services") || (manifest?.packageName?.replace(/^@[^/]+\//u, "").split(/[^a-zA-Z0-9]+/u).filter((segment) => segment.length > 0).map((segment) => segment.toLowerCase()).some((segment) => segment === "api" || segment === "backend" || segment === "server" || segment === "service") ?? false);
+  const isFrontendWorkspace = hasFrontendDependency() || hasFrontendWorkspaceName();
+  const isBackendWorkspace = hasBackendDependency() || hasBackendWorkspaceName2();
   const packs = [];
   if (selectedPacks.has("quality")) {
     packs.push("quality");
@@ -44147,7 +44120,7 @@ var packsForWorkspace = ({
     }
     return uniqueSorted(packs);
   }
-  if (relativeWorkspacePath === "apps/web" || relativeWorkspacePath === "packages/ui") {
+  if (isFrontendWorkspace) {
     if (selectedPacks.has("frontend")) {
       packs.push("frontend");
     }
@@ -44161,7 +44134,7 @@ var packsForWorkspace = ({
       packs.push("tanstack-query");
     }
   }
-  if (relativeWorkspacePath === "apps/server") {
+  if (isBackendWorkspace && !isFrontendWorkspace) {
     if (selectedPacks.has("backend")) {
       packs.push("backend");
     }
@@ -44183,20 +44156,6 @@ var packsForWorkspace = ({
       packs.push("turborepo");
     }
   }
-  if (relativeWorkspacePath === "packages/api") {
-    if (selectedPacks.has("backend")) {
-      packs.push("backend");
-    }
-    if (selectedPacks.has("effect")) {
-      packs.push("effect");
-    }
-    if (selectedPacks.has("drizzle")) {
-      packs.push("drizzle");
-    }
-    if (selectedPacks.has("trpc")) {
-      packs.push("trpc");
-    }
-  }
   if (relativeWorkspacePath === "packages/auth" && selectedPacks.has("better-auth")) {
     packs.push("better-auth");
   }
@@ -44234,7 +44193,7 @@ var packsForWorkspace = ({
     if (packId === "frontend" && (hasDependency("react") || hasDependency("next"))) {
       packs.push(packId);
     }
-    if (packId === "backend" && (hasBackendDependency() || hasBackendWorkspaceName2())) {
+    if (packId === "backend" && isBackendWorkspace && !isFrontendWorkspace) {
       packs.push(packId);
     }
   }
@@ -44255,16 +44214,6 @@ var primarySkillsForWorkspace = ({
   const skills = workspacePacks.flatMap((packId) => skillsForPack(packId, baseline));
   return uniqueSorted(skills);
 };
-var opensrcReferencesForWorkspace = (relativeWorkspacePath, packs) => {
-  if (relativeWorkspacePath === "apps/server" || relativeWorkspacePath === "packages/api" || packs.includes("effect") || packs.includes("drizzle")) {
-    return [
-      "opensrc/repos/github.com/Effect-TS/effect/packages/effect",
-      "opensrc/repos/github.com/Effect-TS/effect/packages/sql",
-      "opensrc/repos/github.com/Effect-TS/effect/packages/sql-drizzle"
-    ];
-  }
-  return [];
-};
 var buildPromptSpec = ({
   scanDirectory,
   relativePath,
@@ -44294,7 +44243,7 @@ var buildPromptSpec = ({
       baseline
     }),
     packs,
-    opensrcReferences: opensrcReferencesForWorkspace(workspacePath, packs)
+    opensrcReferences: []
   };
 };
 var buildSubagentManifestSpec = ({
@@ -44525,8 +44474,10 @@ var writeScaffoldOutput = ({
   const hookFiles = [];
   const harnessFiles = [];
   const finalSkills = selectedSkills(finalPacks, baseline);
-  const finalHookIds = selectedHookIds(finalPacks, baseline);
-  const lintAssets = resolveLintAssetsForPacks(finalPacks, baseline);
+  const hasOxlint = detectionHasPackage(detection, "oxlint");
+  const hasOxfmt = detectionHasPackage(detection, "oxfmt");
+  const finalHookIds = selectedHookIds(finalPacks, baseline).filter((hookId) => hookId !== "format-edited-file" || hasOxfmt);
+  const lintAssets = hasOxlint ? resolveLintAssetsForPacks(finalPacks, baseline) : [];
   const lintAssetIdsByPack = Object.fromEntries(finalPacks.map((packId) => [packId, lintAssets.filter((asset) => asset.sourcePacks.includes(packId)).map((asset) => asset.id)]).filter(([, assetIds]) => assetIds.length > 0));
   const rootOxlintConfigFiles = existingOxlintConfigFiles(scanDirectory);
   const hasExistingRootOxlintConfig = rootOxlintConfigFiles.length > 0;
@@ -44539,7 +44490,7 @@ var writeScaffoldOutput = ({
     finalPacks,
     baseline
   }));
-  const opensrcReferences = collectOpensrcReferences2(promptSpecs);
+  const opensrcReferences = collectOpensrcReferences(promptSpecs);
   generatedFiles.push(writeArtifact({
     outputDirectory,
     relativePath: ".agents/AGENTS.md",
@@ -44923,12 +44874,26 @@ var runScaffold = ({
   ensureTools = true,
   baseline = bundledBaseline
 }) => exports_Effect.gen(function* () {
-  const detection = applyRepoShapeMode(yield* detectRepository(scanDirectory), repoShapeMode);
-  const resolved = resolvePackSelection(detection, baseline);
+  const baseRequiredTools = requiredToolsForSkills([], baseline);
+  let toolBootstrapStatuses = [];
   const resolvedOutputDirectory = path9.resolve(outputDirectory ?? scanDirectory);
   yield* prompt4.writeLine(renderScaffoldTitle());
   yield* prompt4.writeLine("");
   yield* prompt4.writeLine(renderSetupIntro());
+  if (ensureTools && baseRequiredTools.length > 0) {
+    yield* prompt4.writeLine("");
+    yield* prompt4.writeLine(renderHint(`Checking base scaffold tools: ${baseRequiredTools.join(", ")}`));
+    toolBootstrapStatuses = yield* exports_Effect.try({
+      try: () => ensureToolsInstalled(baseRequiredTools, baseline),
+      catch: (cause3) => new CliValidationError({
+        message: cause3 instanceof Error ? cause3.message : "Failed to install required base scaffold tools."
+      })
+    });
+    yield* prompt4.writeLine(renderCommandSection("Base tool check", toolBootstrapStatuses.map((entry) => `\u2022 ${entry.toolId}: ${entry.status === "already-present" ? "already present" : "installed during scaffold"}`).join(`
+`)));
+  }
+  const detection = applyRepoShapeMode(yield* detectRepository(scanDirectory), repoShapeMode);
+  const resolved = resolvePackSelection(detection, baseline);
   yield* prompt4.writeLine("");
   yield* prompt4.writeLine(renderCommandSection("Detection", formatDetectionSummary(detection)));
   yield* prompt4.writeLine("");
@@ -44984,17 +44949,22 @@ var runScaffold = ({
   }
   const skillIds = selectedSkills2(finalPacks, baseline);
   const requiredTools = requiredToolsForSkills(skillIds, baseline);
-  let toolBootstrapStatuses = [];
-  if (ensureTools && requiredTools.length > 0) {
+  const checkedToolIds = new Set(toolBootstrapStatuses.map((entry) => entry.toolId));
+  const remainingRequiredTools = requiredTools.filter((toolId) => !checkedToolIds.has(toolId));
+  if (ensureTools && remainingRequiredTools.length > 0) {
     yield* prompt4.writeLine("");
-    yield* prompt4.writeLine(renderHint(`Ensuring required tools: ${requiredTools.join(", ")}`));
-    toolBootstrapStatuses = yield* exports_Effect.try({
-      try: () => ensureToolsInstalled(requiredTools, baseline),
+    yield* prompt4.writeLine(renderHint(`Ensuring selected-pack tools: ${remainingRequiredTools.join(", ")}`));
+    const remainingToolBootstrapStatuses = yield* exports_Effect.try({
+      try: () => ensureToolsInstalled(remainingRequiredTools, baseline),
       catch: (cause3) => new CliValidationError({
         message: cause3 instanceof Error ? cause3.message : "Failed to install required scaffold tools."
       })
     });
-    yield* prompt4.writeLine(renderCommandSection("Tool bootstrap", toolBootstrapStatuses.map((entry) => `\u2022 ${entry.toolId}: ${entry.status === "already-present" ? "already present" : "installed during scaffold"}`).join(`
+    toolBootstrapStatuses = [
+      ...toolBootstrapStatuses,
+      ...remainingToolBootstrapStatuses
+    ].toSorted((left3, right3) => left3.toolId.localeCompare(right3.toolId));
+    yield* prompt4.writeLine(renderCommandSection("Tool bootstrap", remainingToolBootstrapStatuses.map((entry) => `\u2022 ${entry.toolId}: ${entry.status === "already-present" ? "already present" : "installed during scaffold"}`).join(`
 `)));
   }
   const scaffoldOutput = yield* writeScaffoldOutput({
@@ -46832,7 +46802,7 @@ var readTaggedVersion = async ({
   try {
     const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/${encodeURIComponent(tag4)}`, {
       headers: {
-        accept: "application/vnd.npm.install-v1+json"
+        accept: "application/json"
       },
       signal: controller.signal
     });
@@ -46998,29 +46968,51 @@ var updateDpCliSkill = (scope5) => {
   });
   return result.status === 0;
 };
-var updateDpCliSkillIfPresent = () => {
+var installDpCliSkillGlobal = () => {
+  const result = spawnSync("skills", [
+    "add",
+    "wearedevpunks/skills",
+    "--global",
+    "--skill",
+    "dp-cli",
+    "--yes"
+  ], {
+    stdio: "ignore",
+    shell: false,
+    timeout: 30000
+  });
+  return result.status === 0;
+};
+var ensureDpCliSkillPresent = () => {
   if (!commandExists2("skills")) {
     return {
+      skillsCliAvailable: false,
       detected: false,
       project: false,
       global: false,
+      installedGlobal: false,
       updatedProject: false,
       updatedGlobal: false
     };
   }
-  const project3 = listSkills("project").some((skill) => skill.name === "dp-cli");
-  const global = listSkills("global").some((skill) => skill.name === "dp-cli");
+  const projectBeforeInstall = listSkills("project").some((skill) => skill.name === "dp-cli");
+  const globalBeforeInstall = listSkills("global").some((skill) => skill.name === "dp-cli");
+  const installedGlobal = projectBeforeInstall || globalBeforeInstall ? false : installDpCliSkillGlobal();
+  const project3 = projectBeforeInstall;
+  const global = globalBeforeInstall || installedGlobal || listSkills("global").some((skill) => skill.name === "dp-cli");
   return {
+    skillsCliAvailable: true,
     detected: project3 || global,
     project: project3,
     global,
+    installedGlobal,
     updatedProject: project3 ? updateDpCliSkill("project") : false,
     updatedGlobal: global ? updateDpCliSkill("global") : false
   };
 };
 
 // src/index.ts
-var app = exports_Command.make("punks", {}, () => exports_Effect.sync(() => console.log(renderCommandGuide()))).pipe(exports_Command.withDescription("DevPunks AI scaffolding CLI."), exports_Command.withSubcommands([scaffoldCommand, updateCommand]));
+var app = exports_Command.make("punks", {}, () => exports_Effect.sync(() => console.log(renderCommandGuide()))).pipe(exports_Command.withDescription("Devpunks AI scaffolding CLI."), exports_Command.withSubcommands([scaffoldCommand, updateCommand]));
 var cli = exports_Command.run(app, {
   name: "punks",
   version: cliVersion
@@ -47048,6 +47040,6 @@ var dpCliSkillUpdate = exports_Effect.sync(() => {
   if (!shouldCheckDpCliSkillUpdate()) {
     return;
   }
-  updateDpCliSkillIfPresent();
+  ensureDpCliSkillPresent();
 });
 exports_Effect.zipRight(exports_Effect.zipRight(selfUpdateNotice, dpCliSkillUpdate), cli(process.argv)).pipe(exports_Effect.provide(exports_Layer.mergeAll(exports_BunContext.layer)), exports_BunRuntime.runMain);