@punks/cli 0.1.15 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,10 @@
+## CLI Guidance
+
+Primary skills here: `effect-authoring`, `simplify`.
+
+This repo owns the `punks` CLI surface, repo detection flow, and scaffold-spec orchestration. Keep prompt/spec resolution logic in this repository; do not leak consumer-repo business logic into the CLI itself.
+If you need Effect details, search:
+
+- `opensrc/repos/github.com/Effect-TS/effect/packages/effect`
+
+If work here changes operator workflow, setup, or AI scaffolding behavior, update `docs/README.md` and the relevant runbook in the same task.

package/README.md

@@ -0,0 +1,64 @@
+# 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.
+
+## Commands
+
+- `punks`
+  show the command guide
+- `punks scaffold`
+  show the scaffold lifecycle index
+- `punks scaffold init`
+  scaffold the requirements-stage discovery skill and seed the wiki tree
+- `punks scaffold backlog`
+  print the backlog-stage operator prompt; no backlog-stage packs are scaffolded today
+- `punks scaffold setup`
+  detect the target repo, confirm pack selection, and write repo-aware scaffold output
+
+## Usage
+
+```bash
+punks scaffold
+punks scaffold init
+punks scaffold backlog
+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 sync:skills` updates a local cache clone of `wearedevpunks/skills` and then replaces only `skills/`, overwriting any local changes there.
+
+`punks scaffold init` copies `.agents/skills/grill-me`, seeds a dedicated wiki tree at `apps/wiki` for monorepos or `wiki` for single-repo layouts, and then prints the fixed operator prompt for the requirements gate.
+
+`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.
+
+The lint scaffold is intentionally agent-facing rather than repo-mutating:
+
+- selected lint assets are emitted under `.devpunks/specs/lint/`
+- each asset carries Oxlint rule payload plus placement guidance
+- if the target repo has no root Oxlint config yet, scaffold also emits a starter `.devpunks/specs/lint/oxlint-starter.json`
+- the follow-up agent fits those assets into the repo's real lint topology instead of `punks` editing `.oxlintrc.json` directly
+
+Current scaffold-managed global tools:
+
+- `agent-browser`
+- `opensrc`
+
+## Development
+
+```bash
+bun install
+bun run build
+bun run test
+bun run check-types
+```
+
+## Docs
+
+- [Scaffolding runbook](./docs/runbooks/punks-cli-scaffolding.md)
+- [Example: cicilca-doc-portal](./examples/cicilca-doc-portal/README.md)

package/dist/data/AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## Philosophy
+
+This codebase will outlive you. Every shortcut becomes someone else's burden. Every hack compounds into technical debt that slows the team down.
+
+You are not writing code, you are shaping the future of the project. The patterns established will be copied, the corners cut will be cut again.
+
+Fight entropy, leave the codebase better than when you found it.
+
+## Writing style
+
+- When generating tokens be extremely concise. Sacrifice grammar for the sake of concision.
+- Be detailed about concepts, reasoning, assumptions, tradeoffs, and questions; keep wording terse.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them. Don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting by default.
+- Don't refactor things that aren't broken by default.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it. Don't delete it by default.
+- If adjacent code materially affects correctness, clarity, maintainability, or the requested change, changing it is allowed. Fight entropy, do not preserve harmful local minima.
+
+When your changes create orphans:
+
+- Remove imports, variables, functions, and code paths that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request or to necessary entropy-reducing support for that request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" -> "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
+- "Refactor X" -> "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```text
+1. [Step] -> verify: [check]
+2. [Step] -> verify: [check]
+3. [Step] -> verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## Plan mode
+
+- Plans must be self-contained. Embed all gathered knowledge and context directly in the plan file: relevant code paths, existing patterns, constraints, assumptions, and design reasoning. The executor should be able to implement from the plan alone, doing only optional supplementary research.
+- Be very detailed and explain deeply concepts and reasoning behind design choices.
+- Always emphasize the initial situation, issue, and solution.
+- For complex tasks, break plans into phases with built-in validation gates. Define expected outcomes, assertions, or checks per phase so the executor can self-verify correctness before moving on with no human checkpoint needed.
+- At the end of the plan list unresolved questions if any.
+
+## Dependency source inspection
+
+- Prefer web search and official docs first when inspecting external libraries or packages.
+- If web results are unsuccessful, stale, or not detailed enough for implementation, fetch source locally.
+- For npm packages, use `opensrc path <package>` to get the absolute path to cached source code, fetching on cache miss.
+- For non-npm packages, clone the upstream `owner/repo` git source directly with `opensrc path <owner>/<repo>`.
+
+## Subagents
+
+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.
+
+**On session start:** Read `.agents/notes/index.md` (create if missing).
+**Write notes for:**
+
+- Non-obvious behaviors, gotchas, edge cases
+- Hard-won insights that took investigation
+- Project conventions and architectural decisions
+- Setup and config quirks
+  **Don't note:** File locations, basic structure, session summaries, trivial facts.
+  **Guidelines:** Store in `.agents/notes/`, keep `index.md` lean with one line per note, update existing notes before creating new ones, include why not just what, prune aggressively.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, clarifying questions come before implementation rather than after mistakes, and the codebase trends toward lower entropy over time.

package/dist/data/catalog/lint.ts

@@ -0,0 +1,349 @@
+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 interface LintJsPluginDefinition {
+  readonly name: string;
+  readonly specifier: string;
+}
+
+export interface LintPlacementDefinition {
+  readonly recommendedConfigFile: string;
+  readonly recommendedFiles: ReadonlyArray<string>;
+  readonly recommendedWorkspaces: ReadonlyArray<string>;
+  readonly placementNotes: string;
+}
+
+export interface LintAssetDefinition {
+  readonly id: LintAssetId;
+  readonly description: string;
+  readonly plugins: ReadonlyArray<string>;
+  readonly jsPlugins: ReadonlyArray<LintJsPluginDefinition>;
+  readonly settings: Record<string, unknown>;
+  readonly rules: Record<string, unknown>;
+  readonly requiredDevDependencies: ReadonlyArray<string>;
+  readonly placement: LintPlacementDefinition;
+}
+
+const 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.",
+} as const satisfies LintPlacementDefinition;
+
+const webOnlyPlacement = {
+  recommendedConfigFile: ".oxlintrc.json",
+  recommendedFiles: ["apps/web/**/*.{js,jsx,ts,tsx}"],
+  recommendedWorkspaces: ["apps/web"],
+  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"],
+  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;
+
+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}",
+  ],
+  recommendedWorkspaces: ["apps/web", "packages/api"],
+  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;
+
+export const lintCatalog = [
+  {
+    id: "react-core",
+    description: "Core React rules for rendered app and shared UI code.",
+    plugins: ["unicorn", "typescript", "oxc", "react"],
+    jsPlugins: [],
+    settings: {},
+    rules: {
+      "react/rules-of-hooks": "error",
+      "react/exhaustive-deps": "error",
+      "react/forward-ref-uses-ref": "error",
+      "react/jsx-key": "error",
+      "react/jsx-no-comment-textnodes": "error",
+      "react/jsx-no-duplicate-props": "error",
+      "react/jsx-no-target-blank": "error",
+      "react/jsx-no-undef": "error",
+      "react/jsx-no-useless-fragment": "error",
+      "react/no-children-prop": "error",
+      "react/no-danger-with-children": "error",
+      "react/no-direct-mutation-state": "error",
+      "react/no-find-dom-node": "error",
+      "react/no-render-return-value": "error",
+      "react/no-string-refs": "error",
+      "react/no-this-in-sfc": "error",
+      "react/no-unknown-property": "error",
+      "react/no-unescaped-entities": "error",
+      "react/no-unsafe": "error",
+      "react/void-dom-elements-no-children": "error",
+    },
+    requiredDevDependencies: [],
+    placement: sharedReactPlacement,
+  },
+  {
+    id: "react-hooks",
+    description: "React Hooks lint rules via the JS plugin bridge for Oxlint.",
+    plugins: [],
+    jsPlugins: [
+      {
+        name: "react-hooks-js",
+        specifier: "eslint-plugin-react-hooks",
+      },
+    ],
+    settings: {},
+    rules: {
+      "react-hooks-js/component-hook-factories": "error",
+      "react-hooks-js/config": "error",
+      "react-hooks-js/error-boundaries": "error",
+      "react-hooks-js/gating": "error",
+      "react-hooks-js/globals": "error",
+      "react-hooks-js/immutability": "error",
+      "react-hooks-js/incompatible-library": "error",
+      "react-hooks-js/preserve-manual-memoization": "error",
+      "react-hooks-js/purity": "error",
+      "react-hooks-js/refs": "error",
+      "react-hooks-js/set-state-in-effect": "error",
+      "react-hooks-js/set-state-in-render": "error",
+      "react-hooks-js/static-components": "error",
+      "react-hooks-js/unsupported-syntax": "error",
+      "react-hooks-js/use-memo": "error",
+    },
+    requiredDevDependencies: ["eslint-plugin-react-hooks"],
+    placement: sharedReactPlacement,
+  },
+  {
+    id: "react-you-might-not-need-an-effect",
+    description: "Guidance rules that push React code away from unnecessary effects.",
+    plugins: [],
+    jsPlugins: [
+      {
+        name: "react-you-might-not-need-an-effect-js",
+        specifier: "eslint-plugin-react-you-might-not-need-an-effect",
+      },
+    ],
+    settings: {},
+    rules: {
+      "react-you-might-not-need-an-effect-js/no-adjust-state-on-prop-change":
+        "error",
+      "react-you-might-not-need-an-effect-js/no-chain-state-updates": "error",
+      "react-you-might-not-need-an-effect-js/no-derived-state": "error",
+      "react-you-might-not-need-an-effect-js/no-empty-effect": "error",
+      "react-you-might-not-need-an-effect-js/no-event-handler": "error",
+      "react-you-might-not-need-an-effect-js/no-initialize-state": "error",
+      "react-you-might-not-need-an-effect-js/no-pass-data-to-parent": "error",
+      "react-you-might-not-need-an-effect-js/no-pass-live-state-to-parent":
+        "error",
+      "react-you-might-not-need-an-effect-js/no-reset-all-state-on-prop-change":
+        "error",
+    },
+    requiredDevDependencies: [
+      "eslint-plugin-react-you-might-not-need-an-effect",
+    ],
+    placement: sharedReactPlacement,
+  },
+  {
+    id: "next-core",
+    description: "Next.js correctness rules for the main web application.",
+    plugins: ["nextjs"],
+    jsPlugins: [],
+    settings: {},
+    rules: {
+      "nextjs/inline-script-id": "error",
+      "nextjs/next-script-for-ga": "error",
+      "nextjs/no-assign-module-variable": "error",
+      "nextjs/no-async-client-component": "error",
+      "nextjs/no-before-interactive-script-outside-document": "error",
+      "nextjs/no-css-tags": "error",
+      "nextjs/no-document-import-in-page": "error",
+      "nextjs/no-duplicate-head": "error",
+      "nextjs/no-head-element": "error",
+      "nextjs/no-head-import-in-document": "error",
+      "nextjs/no-html-link-for-pages": "error",
+      "nextjs/no-img-element": "error",
+      "nextjs/no-page-custom-font": "error",
+      "nextjs/no-script-component-in-head": "error",
+      "nextjs/no-styled-jsx-in-document": "error",
+      "nextjs/no-sync-scripts": "error",
+      "nextjs/no-title-in-document-head": "error",
+      "nextjs/no-typos": "error",
+      "nextjs/no-unwanted-polyfillio": "error",
+    },
+    requiredDevDependencies: [],
+    placement: {
+      ...webOnlyPlacement,
+      placementNotes:
+        "Place this beside the React app override and set `settings.next.rootDir` to the repo's actual Next workspace roots if the final config needs that plugin setting.",
+    },
+  },
+  {
+    id: "tanstack-query-core",
+    description: "TanStack Query rules via the Oxlint JS plugin bridge.",
+    plugins: [],
+    jsPlugins: [
+      {
+        name: "tanstack-query-js",
+        specifier: "@tanstack/eslint-plugin-query",
+      },
+    ],
+    settings: {},
+    rules: {
+      "tanstack-query-js/exhaustive-deps": "error",
+      "tanstack-query-js/infinite-query-property-order": "error",
+      "tanstack-query-js/mutation-property-order": "error",
+      "tanstack-query-js/no-rest-destructuring": "warn",
+      "tanstack-query-js/no-unstable-deps": "error",
+      "tanstack-query-js/no-void-query-fn": "error",
+      "tanstack-query-js/stable-query-client": "error",
+    },
+    requiredDevDependencies: ["@tanstack/eslint-plugin-query"],
+    placement: {
+      ...webOnlyPlacement,
+      placementNotes:
+        "Scope this to client code that owns TanStack Query usage. Keep it out of server-only or shared non-query packages unless those paths actually create queries or mutations.",
+    },
+  },
+  {
+    id: "effect-no-barrel-imports",
+    description: "Effect architectural rule that blocks barrel-package imports.",
+    plugins: [],
+    jsPlugins: [
+      {
+        name: "effect-js",
+        specifier: "@effect/eslint-plugin",
+      },
+    ],
+    settings: {},
+    rules: {
+      "effect-js/no-import-from-barrel-package": [
+        "error",
+        {
+          packageNames: ["effect"],
+        },
+      ],
+    },
+    requiredDevDependencies: ["@effect/eslint-plugin"],
+    placement: effectPlacement,
+  },
+  {
+    id: "vitest-core",
+    description: "Vitest-focused test rules for repo-owned test globs.",
+    plugins: ["vitest"],
+    jsPlugins: [],
+    settings: {
+      vitest: {
+        typecheck: false,
+      },
+    },
+    rules: {
+      "vitest/consistent-each-for": "warn",
+      "vitest/no-conditional-tests": "error",
+      "vitest/no-import-node-test": "error",
+      "vitest/warn-todo": "warn",
+    },
+    requiredDevDependencies: [],
+    placement: vitestPlacement,
+  },
+] as const satisfies ReadonlyArray<LintAssetDefinition>;
+
+const stableJson = (value: unknown): string => JSON.stringify(value);
+
+const placementKeyOf = (placement: LintPlacementDefinition): string =>
+  [
+    placement.recommendedConfigFile,
+    ...placement.recommendedFiles,
+  ].join("::");
+
+export const validateLintCatalog = (
+  catalog: ReadonlyArray<LintAssetDefinition>,
+): ReadonlyArray<LintAssetDefinition> => {
+  const seenIds = new Set<string>();
+  const seenRules = new Map<string, { readonly assetId: string; readonly value: string }>();
+  const seenSettings = new Map<
+    string,
+    { readonly assetId: string; readonly value: string }
+  >();
+  const seenJsPlugins = new Map<
+    string,
+    { readonly assetId: string; readonly specifier: string }
+  >();
+
+  for (const asset of catalog) {
+    if (seenIds.has(asset.id)) {
+      throw new Error(`Duplicate lint asset id: ${asset.id}`);
+    }
+    seenIds.add(asset.id);
+
+    const placementKey = placementKeyOf(asset.placement);
+
+    for (const [ruleName, ruleValue] of Object.entries(asset.rules)) {
+      const key = `${placementKey}::rule::${ruleName}`;
+      const value = stableJson(ruleValue);
+      const previous = seenRules.get(key);
+      if (previous !== undefined && previous.value !== value) {
+        throw new Error(
+          `Conflicting lint rule \`${ruleName}\` for placement \`${placementKey}\`: ${previous.assetId} vs ${asset.id}`,
+        );
+      }
+      if (previous === undefined) {
+        seenRules.set(key, { assetId: asset.id, value });
+      }
+    }
+
+    for (const [settingName, settingValue] of Object.entries(asset.settings)) {
+      const key = `${placementKey}::setting::${settingName}`;
+      const value = stableJson(settingValue);
+      const previous = seenSettings.get(key);
+      if (previous !== undefined && previous.value !== value) {
+        throw new Error(
+          `Conflicting lint setting \`${settingName}\` for placement \`${placementKey}\`: ${previous.assetId} vs ${asset.id}`,
+        );
+      }
+      if (previous === undefined) {
+        seenSettings.set(key, { assetId: asset.id, value });
+      }
+    }
+
+    for (const plugin of asset.jsPlugins) {
+      const key = `${placementKey}::js-plugin::${plugin.name}`;
+      const previous = seenJsPlugins.get(key);
+      if (previous !== undefined && previous.specifier !== plugin.specifier) {
+        throw new Error(
+          `Conflicting JS plugin alias \`${plugin.name}\` for placement \`${placementKey}\`: ${previous.assetId} vs ${asset.id}`,
+        );
+      }
+      if (previous === undefined) {
+        seenJsPlugins.set(key, {
+          assetId: asset.id,
+          specifier: plugin.specifier,
+        });
+      }
+    }
+  }
+
+  return catalog;
+};

package/dist/data/catalog/packs.ts

@@ -0,0 +1,44 @@
+import type { PackCategory, PackId } from "../../core/models";
+import type { LintAssetId } from "./lint";
+import type { SkillId } from "./skills";
+
+export type PackHookId = "format-edited-file" | "require-tests-for-pr";
+export type PackPromptSurfaceId =
+  | "shared-agents"
+  | "root-prompt-spec"
+  | "docs-prompt-spec"
+  | "workspace-prompt-spec"
+  | "subagent-manifest";
+
+export interface PackCatalogEntry {
+  readonly id: PackId;
+  readonly category: Exclude<PackCategory, "optional">;
+  readonly triggerPackages: ReadonlyArray<string>;
+  readonly description: string;
+  readonly skills: ReadonlyArray<SkillId>;
+  readonly lintAssets: ReadonlyArray<LintAssetId>;
+  readonly hooks: ReadonlyArray<PackHookId>;
+  readonly promptSurfaces: ReadonlyArray<PackPromptSurfaceId>;
+  readonly promptDetails: ReadonlyArray<string>;
+}
+
+export const packCatalog = [
+  { id: "backend", category: "surface", triggerPackages: [], description: "Backend pack: domain structure and recoverable actions.", skills: ["backend-domain-structure", "backend-recoverable-actions"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared backend domain baseline", "workspace backend action/recovery guidance"] },
+  { id: "better-auth", category: "detected", triggerPackages: ["better-auth"], description: "Better Auth guidance pack.", skills: ["better-auth-best-practices"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared auth guardrails", "workspace auth boundaries"] },
+  { id: "docs", category: "default", triggerPackages: [], description: "Default docs pack: docs-maintenance.", skills: ["docs-maintenance"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "docs-prompt-spec"], promptDetails: ["shared docs baseline", "docs scope spec"] },
+  { id: "drizzle", category: "detected", triggerPackages: ["drizzle-kit", "drizzle-orm"], description: "Drizzle guidance pack.", skills: ["effect-backend-structure", "effect-recoverable-actions"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared data-layer baseline", "workspace db flow rules"] },
+  { id: "effect", category: "detected", triggerPackages: ["effect", "@effect/"], description: "Effect guidance pack family.", skills: ["effect-authoring", "effect-best-practices", "effect-backend-structure", "effect-recoverable-actions"], lintAssets: ["effect-no-barrel-imports"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared effect authoring baseline", "workspace service/layer rules"] },
+  { id: "elysia", category: "detected", triggerPackages: ["elysia"], description: "Elysia guidance pack.", skills: ["elysiajs"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared api-server baseline", "workspace route/plugin rules"] },
+  { id: "frontend", category: "surface", triggerPackages: [], description: "Frontend pack: agent-browser, design taste, and frontend domain structure.", skills: ["agent-browser", "design-taste-frontend", "frontend-domain-structure"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared product-ui baseline", "workspace UX/browser guidance", "workspace frontend domain boundaries"] },
+  { id: "nextjs", category: "detected", triggerPackages: ["next"], description: "Next.js guidance pack.", skills: ["next-best-practices", "next-cache-components"], lintAssets: ["next-core"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared app-router baseline", "workspace next rendering rules"] },
+  { id: "planning", category: "default", triggerPackages: [], description: "Default planning pack: grill-me, create-spec, create-plan, implement-spec.", skills: ["grill-me", "create-spec", "create-plan", "implement-spec"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared planning baseline", "workspace plan/spec execution rules"] },
+  { id: "quality", category: "default", triggerPackages: [], description: "Default quality pack: tdd, simplify.", skills: ["tdd", "simplify"], lintAssets: ["vitest-core"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared change-quality baseline", "workspace test/refactor expectations"] },
+  { id: "react", category: "detected", triggerPackages: ["react", "react-dom"], description: "React guidance pack.", skills: ["async-react-patterns", "vercel-composition-patterns", "vercel-react-best-practices"], lintAssets: ["react-core", "react-hooks", "react-you-might-not-need-an-effect"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared react structure baseline", "workspace react composition rules"] },
+  { id: "research", category: "default", triggerPackages: [], description: "Default research pack: parallel-research.", skills: ["parallel-research"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared investigation baseline", "workspace research handoff rules"] },
+  { id: "requirements", category: "default", triggerPackages: [], description: "Default requirements pack: requirements-grill, write-backlog.", skills: ["requirements-grill", "write-backlog"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared requirements baseline", "workspace backlog shaping rules"] },
+  { id: "subagents", category: "default", triggerPackages: [], description: "Default subagents pack: swarm-planner.", skills: ["swarm-planner"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec", "subagent-manifest"], promptDetails: ["shared delegation baseline", "workspace ownership handoffs", "subagent manifest scaffold"] },
+  { id: "tanstack-query", category: "detected", triggerPackages: ["@tanstack/react-query"], description: "TanStack Query guidance pack.", skills: ["tanstack-query"], lintAssets: ["tanstack-query-core"], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared tanstack query baseline", "workspace server-state rules"] },
+  { id: "trpc", category: "detected", triggerPackages: ["@trpc/"], description: "tRPC guidance pack.", skills: [], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared contract-first baseline", "workspace client/server boundaries"] },
+  { id: "turborepo", category: "detected", triggerPackages: ["turbo"], description: "Turborepo guidance pack.", skills: ["turborepo"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared monorepo baseline", "workspace task boundary rules"] },
+  { id: "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: [] },
+] as const satisfies ReadonlyArray<PackCatalogEntry>;

package/dist/data/catalog/skills.ts

@@ -0,0 +1,47 @@
+import type { ToolId } from "./tools";
+
+export type SkillTier = "agnostic" | "language" | "framework";
+
+export interface SkillCatalogEntry {
+  readonly id: string;
+  readonly sourceDirectory: string;
+  readonly tier: SkillTier;
+  readonly language: string | null;
+  readonly framework: string | null;
+  readonly requiresTools: ReadonlyArray<ToolId>;
+}
+
+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: "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: "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"] },
+  { id: "effect-best-practices", sourceDirectory: "skills/frameworks/effect/effect-best-practices", tier: "framework", language: "typescript", framework: "effect", requiresTools: [] },
+  { id: "effect-recoverable-actions", sourceDirectory: "skills/frameworks/effect/effect-recoverable-actions", tier: "framework", language: "typescript", framework: "effect", requiresTools: ["opensrc"] },
+  { id: "elysiajs", sourceDirectory: "skills/frameworks/elysia/elysiajs", tier: "framework", language: "typescript", framework: "elysiajs", requiresTools: [] },
+  { id: "design-taste-frontend", sourceDirectory: "skills/agnostic/frontend/design-taste-frontend", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "frontend-domain-structure", sourceDirectory: "skills/agnostic/frontend/frontend-domain-structure", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "grill-me", sourceDirectory: "skills/agnostic/planning/grill-me", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "improve-codebase-architecture", sourceDirectory: "skills/agnostic/research/improve-codebase-architecture", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "implement-spec", sourceDirectory: "skills/agnostic/planning/implement-spec", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { 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-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: [] },
+  { id: "swarm-planner", sourceDirectory: "skills/agnostic/subagents/swarm-planner", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "tanstack-query", sourceDirectory: "skills/frameworks/tanstack-query/tanstack-query", tier: "framework", language: "typescript", framework: "tanstack-query", requiresTools: ["opensrc"] },
+  { id: "tdd", sourceDirectory: "skills/agnostic/quality/tdd", tier: "agnostic", language: null, framework: null, requiresTools: [] },
+  { id: "turborepo", sourceDirectory: "skills/frameworks/turborepo/turborepo", tier: "framework", language: null, framework: "turborepo", requiresTools: [] },
+  { id: "vercel-composition-patterns", sourceDirectory: "skills/frameworks/react/vercel-composition-patterns", tier: "framework", language: "typescript", framework: "react", requiresTools: [] },
+  { id: "vercel-react-best-practices", sourceDirectory: "skills/frameworks/react/vercel-react-best-practices", tier: "framework", language: "typescript", framework: "react", requiresTools: [] },
+  { 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"];