@punks/cli 1.0.6 → 2.0.0-beta.0

package/dist/data/catalog/skills.ts

@@ -12,44 +12,358 @@ export interface SkillCatalogEntry {
 }
 
 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"] },
-  { 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-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: [] },
-  { 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: [] },
+  {
+    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: "delivery-phase",
+    sourceDirectory: "skills/agnostic/planning/delivery-phase",
+    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: "debugging-phase",
+    sourceDirectory: "skills/agnostic/debug/debugging-phase",
+    tier: "agnostic",
+    language: null,
+    framework: null,
+    requiresTools: ["debug-agent"],
+  },
+  {
+    id: "docs-ingest-phase",
+    sourceDirectory: "skills/agnostic/docs/docs-ingest-phase",
+    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: "goalify",
+    sourceDirectory: "skills/agnostic/planning/goalify",
+    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-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: "requirements-phase",
+    sourceDirectory: "skills/agnostic/requirements/requirements-phase",
+    tier: "agnostic",
+    language: null,
+    framework: null,
+    requiresTools: [],
+  },
+  {
+    id: "resolve-debt-phase",
+    sourceDirectory: "skills/agnostic/planning/resolve-debt-phase",
+    tier: "agnostic",
+    language: null,
+    framework: null,
+    requiresTools: [],
+  },
+  {
+    id: "review-phase",
+    sourceDirectory: "skills/agnostic/research/review-phase",
+    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 = string;

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

@@ -109,7 +109,8 @@ function buildClaudeSettingsConfig({ hasFormatHook, hasTestHook }) {
                 hooks: [
                   {
                     type: "command",
-                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
+                    command:
+                      'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
                     timeout: 600,
                   },
                 ],
@@ -119,7 +120,8 @@ function buildClaudeSettingsConfig({ hasFormatHook, hasTestHook }) {
                 hooks: [
                   {
                     type: "command",
-                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
+                    command:
+                      'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
                     timeout: 600,
                   },
                 ],
@@ -135,7 +137,8 @@ function buildClaudeSettingsConfig({ hasFormatHook, hasTestHook }) {
                 hooks: [
                   {
                     type: "command",
-                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/format-edited-file.mjs claude',
+                    command:
+                      'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/format-edited-file.mjs claude',
                     timeout: 30,
                   },
                 ],
@@ -449,7 +452,11 @@ async function main() {
   };
   await writeFile(codexConfigPath, buildCodexAgentConfig(availableHooks), "utf8");
   await rm(path.join(codexDir, "hooks.json"), { force: true });
-  await writeFile(claudeSettingsPath, encodeJson(buildClaudeSettingsConfig(availableHooks)), "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);

package/dist/data/subagents/manifest.mjs

@@ -1,7 +1,6 @@
 const capabilityPacks = {
   "frontend-core": {
-    description:
-      "Core Next.js and React app structure guidance for product-facing frontend work.",
+    description: "Core Next.js and React app structure guidance for product-facing frontend work.",
     skills: [
       "next-best-practices",
       "async-react-patterns",
@@ -10,13 +9,11 @@ const capabilityPacks = {
     ],
   },
   simplify: {
-    description:
-      "Simplify and refine recently modified code for clarity and consistency.",
+    description: "Simplify and refine recently modified code for clarity and consistency.",
     skills: ["simplify"],
   },
   "frontend-ui": {
-    description:
-      "UI implementation, browser testing, visual quality, and composition patterns.",
+    description: "UI implementation, browser testing, visual quality, and composition patterns.",
     skills: [
       "agent-browser",
       "frontend-design",
@@ -30,8 +27,7 @@ const capabilityPacks = {
     skills: ["tanstack-query"],
   },
   "frontend-cache": {
-    description:
-      "Next.js cache components, PPR, cache tags, and related rendering/cache behavior.",
+    description: "Next.js cache components, PPR, cache tags, and related rendering/cache behavior.",
     skills: ["next-cache-components"],
   },
   "server-core": {
@@ -42,25 +38,16 @@ const capabilityPacks = {
   "api-core": {
     description:
       "Effect application logic, pre-write authoring guidance, service/layer patterns, and test-first backend domain work.",
-    skills: [
-      "effect-authoring",
-      "effect-best-practices",
-      "effect-recoverable-actions",
-      "tdd",
-    ],
+    skills: ["effect-authoring", "effect-best-practices", "effect-recoverable-actions", "tdd"],
   },
   "auth-core": {
-    description:
-      "Better Auth conventions and security-sensitive authentication behavior.",
-    skills: [
-      "better-auth-best-practices",
-      "better-auth-security-best-practices",
-    ],
+    description: "Better Auth conventions and security-sensitive authentication behavior.",
+    skills: ["better-auth-best-practices", "better-auth-security-best-practices"],
   },
   "docs-core": {
     description:
       "Repo documentation maintenance, routing, and human-facing durable knowledge capture.",
-    skills: ["docs-maintenance"],
+    skills: ["docs-ingest-phase"],
   },
   "review-core": {
     description:
@@ -78,8 +65,7 @@ const capabilityPacks = {
     ],
   },
   "python-async": {
-    description:
-      "Python asyncio, concurrent I/O, async API boundaries, and async test strategy.",
+    description: "Python asyncio, concurrent I/O, async API boundaries, and async test strategy.",
     skills: [
       "async-python-patterns",
       "python-project-structure",
@@ -90,11 +76,7 @@ const capabilityPacks = {
   "python-quality": {
     description:
       "Python pytest coverage, fixture design, style checks, and refactor-safe quality work.",
-    skills: [
-      "python-testing-patterns",
-      "python-code-style",
-      "python-design-patterns",
-    ],
+    skills: ["python-testing-patterns", "python-code-style", "python-design-patterns"],
   },
 };
 
@@ -133,14 +115,14 @@ const agents = [
     ],
   },
   {
-    name: "docs-maintenance",
+    name: "docs-ingest-phase",
     description:
       "Use for repo documentation work centered on docs updates, index maintenance, ADR routing, and keeping docs grounded in implemented reality.",
     ownedPaths: ["docs/**"],
     guidanceFiles: ["docs/AGENTS.md"],
     activationInstructions: skillActivationInstructions,
     packs: ["docs-core", "simplify"],
-    skills: ["docs-maintenance", "simplify"],
+    skills: ["docs-ingest-phase", "simplify"],
     boundaries: [
       "Own documentation updates in docs/ and keep them human-facing and implementation-grounded.",
       "If the task is mainly code implementation, tell the parent to use the relevant code specialist and only return for the docs follow-up.",
@@ -295,11 +277,7 @@ const agents = [
     guidanceFiles: ["packages/auth/AGENTS.md"],
     activationInstructions: skillActivationInstructions,
     packs: ["auth-core", "simplify"],
-    skills: [
-      "better-auth-best-practices",
-      "better-auth-security-best-practices",
-      "simplify",
-    ],
+    skills: ["better-auth-best-practices", "better-auth-security-best-practices", "simplify"],
     boundaries: [
       "Treat auth work as security-sensitive and stay inside packages/auth unless explicitly coordinating with another specialist.",
       "If the task is mainly Effect application logic, tell the parent to use api-domain instead.",
@@ -342,14 +320,7 @@ const agents = [
     name: "python-async",
     description:
       "Use for Python async work centered on asyncio, concurrent I/O, async APIs, background tasks, and async test coverage.",
-    ownedPaths: [
-      "src/**",
-      "packages/**",
-      "services/**",
-      "apps/**",
-      "tests/**",
-      "pyproject.toml",
-    ],
+    ownedPaths: ["src/**", "packages/**", "services/**", "apps/**", "tests/**", "pyproject.toml"],
     guidanceFiles: ["AGENTS.md"],
     activationInstructions: skillActivationInstructions,
     packs: ["python-async", "python-quality", "simplify"],
@@ -383,12 +354,7 @@ const agents = [
     guidanceFiles: ["AGENTS.md"],
     activationInstructions: skillActivationInstructions,
     packs: ["python-quality", "simplify"],
-    skills: [
-      "python-testing-patterns",
-      "python-code-style",
-      "python-design-patterns",
-      "simplify",
-    ],
+    skills: ["python-testing-patterns", "python-code-style", "python-design-patterns", "simplify"],
     boundaries: [
       "Own pytest structure, fixtures, parameterization, integration-test shape, and test readability.",
       "Prefer tests that exercise real behavior over brittle mocks unless the boundary is genuinely external.",