@3lineas/grooveskills 1.0.2 → 1.1.0

package/dist/chunk-5Q6O3BRA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/domains/detector/project-detector.ts","../src/domains/detector/detect-agents.ts","../src/domains/detector/detect-dependencies.ts","../src/domains/registry/skill-catalog.ts","../src/domains/ui/ui-orchestrator.ts","../src/domains/ui/banners.ts","../src/domains/ui/prompt-skills.ts","../src/domains/ui/prompt-agents.ts","../src/domains/ui/prompt-harness.ts","../src/domains/ui/prompt-confirm-overwrite.ts","../src/domains/installer/verify-skill-exists.ts","../src/domains/installer/install-orchestrator.ts","../src/domains/adapters/antigravity.adapter.ts","../src/domains/project-store/project-paths.ts","../src/domains/adapters/link-helper.ts","../src/domains/adapters/claude.adapter.ts","../src/domains/adapters/cursor.adapter.ts","../src/domains/adapters/gemini.adapter.ts","../src/domains/project-store/sync-project-store.ts","../src/domains/installer/resolve-skills-source.ts","../src/domains/harness/install-harness.ts","../src/domains/harness/harness-templates.ts","../src/domains/harness/upsert-agent-instructions.ts","../src/domains/harness/write-project-config.ts","../src/main.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { detectAgents } from \"@/domains/detector/detect-agents\";\nimport { detectDependencies } from \"@/domains/detector/detect-dependencies\";\nimport { SKILL_CATALOG } from \"@/domains/registry/skill-catalog\";\nimport type { ProjectContext } from \"@/types/context.types\";\n\nexport function detectProjectContext(targetPath: string): ProjectContext {\n  const detectedAgents = detectAgents(targetPath);\n  const { dependencies, exists } = detectDependencies(targetPath);\n\n  const suggestedSkillIds: string[] = [\"best-practices\"];\n\n  for (const skill of SKILL_CATALOG) {\n    if (skill.dependencies.length === 0) {\n      continue;\n    }\n    const hasMatch = skill.dependencies.some((dep) => dependencies.includes(dep));\n    if (hasMatch && !suggestedSkillIds.includes(skill.id)) {\n      suggestedSkillIds.push(skill.id);\n    }\n  }\n\n  const harnessExists = existsSync(join(targetPath, \".grooveskills\", \"memory\", \"context.md\"));\n\n  return {\n    targetPath,\n    detectedDependencies: dependencies,\n    suggestedSkillIds,\n    detectedAgents,\n    packageJsonExists: exists,\n    harnessExists,\n  };\n}\n","import { readdirSync } from \"node:fs\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nexport function detectAgents(targetPath: string): AgentId[] {\n  const detected: AgentId[] = [];\n\n  try {\n    const entries = new Set(readdirSync(targetPath));\n\n    if (entries.has(\".agents\")) {\n      detected.push(\"antigravity\");\n    }\n    if (entries.has(\".claude\")) {\n      detected.push(\"claude\");\n    }\n    if (entries.has(\".cursor\")) {\n      detected.push(\"cursor\");\n    }\n    if (entries.has(\".gemini\")) {\n      detected.push(\"gemini\");\n    }\n  } catch {\n    // If directory cannot be read, return empty list gracefully\n  }\n\n  return detected;\n}\n","import { readFileSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nexport interface PackageJsonDetection {\n  dependencies: string[];\n  exists: boolean;\n}\n\nexport function detectDependencies(targetPath: string): PackageJsonDetection {\n  const packageJsonPath = join(targetPath, \"package.json\");\n\n  if (!existsSync(packageJsonPath)) {\n    return { dependencies: [], exists: false };\n  }\n\n  try {\n    const raw = readFileSync(packageJsonPath, \"utf-8\");\n    const parsed = JSON.parse(raw) as {\n      dependencies?: Record<string, string>;\n      devDependencies?: Record<string, string>;\n    };\n\n    const direct = Object.keys(parsed.dependencies ?? {});\n    const dev = Object.keys(parsed.devDependencies ?? {});\n    const all = Array.from(new Set([...direct, ...dev]));\n\n    return { dependencies: all, exists: true };\n  } catch {\n    return { dependencies: [], exists: true };\n  }\n}\n","import type { SkillMetadata } from \"@/types/skill.types\";\n\nexport const SKILL_CATALOG: SkillMetadata[] = [\n  {\n    id: \"groove-harness\",\n    name: \"GrooveSkills Harness\",\n    description: \"Lightweight project harness, context memory, and 3-lane task execution (Answer, Task, Spec) for AI coding agents\",\n    dependencies: [],\n    directoryName: \"groove-harness\",\n  },\n  {\n    id: \"best-practices\",\n    name: \"Universal Best Practices\",\n    description: \"Multi-language clean code standards, early returns, no barrel files, strict typing, <200 lines\",\n    dependencies: [],\n    directoryName: \"best-practices\",\n  },\n  {\n    id: \"hono\",\n    name: \"Hono Architecture (Valibot)\",\n    description: \"Enterprise Hono API standard with Valibot validation, isolated Actions layer, and RPC bindings\",\n    dependencies: [\"hono\", \"@hono/valibot-validator\", \"@hono/standard-validator\"],\n    directoryName: \"hono\",\n  },\n  {\n    id: \"react-core\",\n    name: \"React Core Fundamentals\",\n    description: \"Opinionated React fundamentals: function components, JSX, immutable state, core hooks, lists, and controlled inputs\",\n    dependencies: [\"react\", \"react-dom\"],\n    directoryName: \"react-core\",\n  },\n  {\n    id: \"react-advanced\",\n    name: \"React 19 Advanced & Compiler Architecture\",\n    description: \"Modern React 19 platform features: React Compiler auto-memoization, concurrent rendering, use(), Actions, virtualization, and RSC boundaries\",\n    dependencies: [\"react\", \"react-dom\"],\n    directoryName: \"react-advanced\",\n  },\n  {\n    id: \"react-create-page\",\n    name: \"React Page & View Architecture\",\n    description: \"Clean architecture for React pages: declarative page coordinators, domain hooks, isolated API actions, Valibot + Formisch forms, and atomic co-location\",\n    dependencies: [\"react\", \"react-dom\"],\n    directoryName: \"react-create-page\",\n  },\n];\n","import * as p from \"@clack/prompts\";\nimport pc from \"picocolors\";\nimport { renderBanner } from \"@/domains/ui/banners\";\nimport { promptSkills } from \"@/domains/ui/prompt-skills\";\nimport { promptAgents } from \"@/domains/ui/prompt-agents\";\nimport { promptHarness } from \"@/domains/ui/prompt-harness\";\nimport { promptConfirmOverwrite } from \"@/domains/ui/prompt-confirm-overwrite\";\nimport { verifySkillExists } from \"@/domains/installer/verify-skill-exists\";\nimport { installSkills } from \"@/domains/installer/install-orchestrator\";\nimport { SKILL_CATALOG } from \"@/domains/registry/skill-catalog\";\nimport type { ProjectContext } from \"@/types/context.types\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nexport async function runInteractiveUi(context: ProjectContext): Promise<void> {\n  console.log(renderBanner());\n  p.intro(pc.magenta(\"Welcome to GrooveSkills! Let's tailor your AI agents with clean architectural standards.\"));\n\n  if (context.detectedDependencies.length > 0) {\n    p.note(\n      `Detected dependencies: ${context.detectedDependencies.map((d) => pc.bold(d)).join(\", \")}\\n` +\n      `Active AI folders: ${context.detectedAgents.map((a) => pc.green(a)).join(\", \") || \"None (will be created)\"}`,\n      \"Project Environment\"\n    );\n  }\n\n  const selectedSkills = await promptSkills(context.suggestedSkillIds);\n  if (p.isCancel(selectedSkills)) {\n    p.cancel(\"Installation cancelled. Have a wonderful day!\");\n    process.exit(0);\n  }\n\n  const selectedAgents = await promptAgents(context.detectedAgents);\n  if (p.isCancel(selectedAgents)) {\n    p.cancel(\"Installation cancelled. Have a wonderful day!\");\n    process.exit(0);\n  }\n\n  const harnessChoice = await promptHarness(context.harnessExists);\n  if (p.isCancel(harnessChoice)) {\n    p.cancel(\"Installation cancelled. Have a wonderful day!\");\n    process.exit(0);\n  }\n\n  let forceOverwrite = true;\n  const anyExists = (selectedSkills as string[]).some((skillId) => {\n    const meta = SKILL_CATALOG.find((s) => s.id === skillId);\n    return meta ? verifySkillExists(context.targetPath, meta.directoryName, selectedAgents as AgentId[]) : false;\n  });\n\n  if (anyExists) {\n    const confirm = await promptConfirmOverwrite();\n    if (p.isCancel(confirm) || !confirm) {\n      p.cancel(\"Installation stopped to protect existing skills.\");\n      process.exit(0);\n    }\n    forceOverwrite = Boolean(confirm);\n  }\n\n  const s = p.spinner();\n  s.start(\"Installing and adapting skills across your configured AI agents...\");\n\n  const result = await installSkills({\n    targetPath: context.targetPath,\n    selectedSkillIds: selectedSkills as string[],\n    selectedAgents: selectedAgents as AgentId[],\n    forceOverwrite,\n    enableHarness: Boolean(harnessChoice),\n    detectedDependencies: context.detectedDependencies,\n  });\n\n  s.stop(pc.green(\"All skills and harness have been successfully configured!\"));\n\n  const harnessStatus = result.harnessInitialized\n    ? pc.green(\"Initialized in .grooveskills/\")\n    : pc.dim(\"Skipped\");\n\n  p.note(\n    `Configured skills: ${result.installedSkills.map((s) => pc.bold(s)).join(\", \")}\\n` +\n    `Target agents: ${result.configuredAgents.map((a) => pc.cyan(a)).join(\", \")}\\n` +\n    `GrooveSkills Harness: ${harnessStatus}`,\n    \"Installation Summary\"\n  );\n\n  p.outro(pc.green(\"Your AI programming pair is now empowered with your team's architectural habits! 🚀\"));\n}\n","import pc from \"picocolors\";\n\nexport function renderBanner(): string {\n  const title = pc.bold(pc.white(\" GROOVE SKILLS \"));\n  const badge = pc.bgMagenta(pc.black(title));\n  const subtitle = pc.dim(\"Multi-Agent AI Skills & Architectural Standards\");\n\n  return `${badge}  ${subtitle}\\n`;\n}\n","import * as p from \"@clack/prompts\";\nimport { SKILL_CATALOG } from \"@/domains/registry/skill-catalog\";\n\nexport async function promptSkills(suggestedSkillIds: string[]): Promise<string[] | symbol> {\n  const options = SKILL_CATALOG.map((skill) => {\n    const isSuggested = suggestedSkillIds.includes(skill.id);\n    return {\n      value: skill.id,\n      label: skill.name,\n      hint: isSuggested ? \"Suggested based on your project stack\" : skill.description,\n    };\n  });\n\n  const selected = await p.multiselect({\n    message: \"Which skills would you like to install in this project?\",\n    options,\n    initialValues: suggestedSkillIds,\n    required: true,\n  });\n\n  return selected;\n}\n","import * as p from \"@clack/prompts\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nexport async function promptAgents(detectedAgents: AgentId[]): Promise<AgentId[] | symbol> {\n  const options: Array<{ value: AgentId; label: string; hint: string }> = [\n    { value: \"antigravity\", label: \"Antigravity\", hint: \".agents/skills (Google Agentic IDE)\" },\n    { value: \"claude\", label: \"Claude Code\", hint: \".claude/skills (Anthropic Claude Code)\" },\n    { value: \"cursor\", label: \"Cursor\", hint: \".cursor/rules/*.mdc (Cursor IDE Rules)\" },\n    { value: \"gemini\", label: \"Gemini Code Assist\", hint: \".gemini/skills (Google Gemini)\" },\n  ];\n\n  const initialValues: AgentId[] = detectedAgents.length > 0 ? detectedAgents : [\"antigravity\"];\n\n  const selected = await p.multiselect({\n    message: \"Which AI agents should be configured?\",\n    options,\n    initialValues,\n    required: true,\n  });\n\n  return selected as AgentId[] | symbol;\n}\n","import * as p from \"@clack/prompts\";\n\nexport async function promptHarness(harnessExists: boolean): Promise<boolean | symbol> {\n  const message = harnessExists\n    ? \"GrooveSkills Harness is already initialized. Would you like to update agent rules and memory templates?\"\n    : \"Would you like to initialize the GrooveSkills Harness in .grooveskills/ (project memory, ADR, and 3-lane task execution)?\";\n\n  const confirm = await p.confirm({\n    message,\n    initialValue: true,\n  });\n\n  return confirm;\n}\n","import * as p from \"@clack/prompts\";\n\nexport async function promptConfirmOverwrite(): Promise<boolean | symbol> {\n  return await p.confirm({\n    message: \"Some skills already exist in this project. Would you like to overwrite them with the latest version?\",\n    initialValue: true,\n  });\n}\n","import { lstatSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nconst AGENT_DESTINATION_MAP: Record<AgentId, (dir: string) => string> = {\n  antigravity: (dir) => join(\".agents\", \"skills\", dir),\n  claude: (dir) => join(\".claude\", \"skills\", dir),\n  cursor: (dir) => join(\".cursor\", \"rules\", `${dir}.mdc`),\n  gemini: (dir) => join(\".gemini\", \"skills\", dir),\n};\n\nexport function verifySkillExists(\n  targetPath: string,\n  skillDirectoryName: string,\n  agents: AgentId[]\n): boolean {\n  for (const agent of agents) {\n    const relativePathResolver = AGENT_DESTINATION_MAP[agent];\n    const destination = join(targetPath, relativePathResolver(skillDirectoryName));\n\n    try {\n      lstatSync(destination);\n      return true;\n    } catch {\n      // Path does not exist\n    }\n  }\n\n  return false;\n}\n","import { join } from \"node:path\";\nimport { AntigravityAdapter } from \"@/domains/adapters/antigravity.adapter\";\nimport { ClaudeAdapter } from \"@/domains/adapters/claude.adapter\";\nimport { CursorAdapter } from \"@/domains/adapters/cursor.adapter\";\nimport { GeminiAdapter } from \"@/domains/adapters/gemini.adapter\";\nimport { syncProjectStore } from \"@/domains/project-store/sync-project-store\";\nimport { getProjectSkillsDir } from \"@/domains/project-store/project-paths\";\nimport { installHarness } from \"@/domains/harness/install-harness\";\nimport { writeProjectConfig } from \"@/domains/harness/write-project-config\";\nimport { SKILL_CATALOG } from \"@/domains/registry/skill-catalog\";\nimport type { AgentAdapter } from \"@/domains/adapters/adapter.interface\";\nimport type { InstallOptions, InstallResult } from \"@/types/installer.types\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nconst ADAPTER_REGISTRY: Record<AgentId, AgentAdapter> = {\n  antigravity: new AntigravityAdapter(),\n  claude: new ClaudeAdapter(),\n  cursor: new CursorAdapter(),\n  gemini: new GeminiAdapter(),\n};\n\nexport async function installSkills(options: InstallOptions): Promise<InstallResult> {\n  const skillsToInstall = [...options.selectedSkillIds];\n\n  if (options.enableHarness && !skillsToInstall.includes(\"groove-harness\")) {\n    skillsToInstall.push(\"groove-harness\");\n  }\n\n  syncProjectStore(options.targetPath, skillsToInstall, options.selectedAgents);\n\n  const projectSkillsDir = getProjectSkillsDir(options.targetPath);\n  const createdFiles: string[] = [];\n\n  for (const skillId of skillsToInstall) {\n    const skill = SKILL_CATALOG.find((item) => item.id === skillId);\n    if (!skill) {\n      continue;\n    }\n\n    const skillSourceDir = join(projectSkillsDir, skill.directoryName);\n\n    for (const agentId of options.selectedAgents) {\n      const adapter = ADAPTER_REGISTRY[agentId];\n      if (!adapter) {\n        continue;\n      }\n\n      const files = await adapter.installSkill(options.targetPath, skill, skillSourceDir);\n      createdFiles.push(...files);\n    }\n  }\n\n  let harnessInitialized = false;\n  if (options.enableHarness) {\n    const harnessFiles = installHarness({\n      targetPath: options.targetPath,\n      selectedAgents: options.selectedAgents,\n      selectedSkillIds: skillsToInstall,\n      detectedDependencies: options.detectedDependencies || [],\n    });\n    createdFiles.push(...harnessFiles);\n    harnessInitialized = true;\n  }\n\n  const configPath = writeProjectConfig(\n    options.targetPath,\n    skillsToInstall,\n    options.selectedAgents,\n    Boolean(options.enableHarness)\n  );\n  createdFiles.push(configPath);\n\n  return {\n    installedSkills: skillsToInstall,\n    configuredAgents: options.selectedAgents,\n    createdFiles,\n    harnessInitialized,\n  };\n}\n","import { mkdirSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { getProjectSkillsDir } from \"@/domains/project-store/project-paths\";\nimport { createOrReplaceSymlink } from \"@/domains/adapters/link-helper\";\nimport type { AgentAdapter } from \"@/domains/adapters/adapter.interface\";\nimport type { SkillMetadata } from \"@/types/skill.types\";\n\nexport class AntigravityAdapter implements AgentAdapter {\n  readonly id = \"antigravity\" as const;\n  readonly name = \"Antigravity\";\n  readonly targetRelativeDir = \".agents/skills\";\n\n  async installSkill(\n    targetPath: string,\n    skill: SkillMetadata,\n    _skillSourceDir: string\n  ): Promise<string[]> {\n    const parentDir = join(targetPath, this.targetRelativeDir);\n    if (!existsSync(parentDir)) {\n      mkdirSync(parentDir, { recursive: true });\n    }\n\n    const destination = join(parentDir, skill.directoryName);\n    const projectSkillDir = join(getProjectSkillsDir(targetPath), skill.directoryName);\n\n    createOrReplaceSymlink(projectSkillDir, destination, \"dir\");\n\n    return [destination];\n  }\n}\n","import { join } from \"node:path\";\n\nexport function getProjectStoreDir(targetPath: string): string {\n  return join(targetPath, \".grooveskills\");\n}\n\nexport function getProjectSkillsDir(targetPath: string): string {\n  return join(getProjectStoreDir(targetPath), \"skills\");\n}\n\nexport function getProjectCursorRulesDir(targetPath: string): string {\n  return join(getProjectStoreDir(targetPath), \"cursor-rules\");\n}\n\nexport function getProjectMemoryDir(targetPath: string): string {\n  return join(getProjectStoreDir(targetPath), \"memory\");\n}\n\nexport function getProjectTasksDir(targetPath: string): string {\n  return join(getProjectMemoryDir(targetPath), \"tasks\");\n}\n\nexport function getProjectConfigPath(targetPath: string): string {\n  return join(getProjectStoreDir(targetPath), \"config.json\");\n}\n","import { lstatSync, unlinkSync, rmSync, symlinkSync } from \"node:fs\";\nimport { dirname, relative } from \"node:path\";\n\nfunction removeExistingLinkPath(path: string): void {\n  try {\n    const lstat = lstatSync(path);\n\n    if (lstat.isDirectory() && !lstat.isSymbolicLink()) {\n      rmSync(path, { recursive: true, force: true });\n      return;\n    }\n\n    unlinkSync(path);\n  } catch {\n    // If path does not exist, exit early\n  }\n}\n\nexport function createOrReplaceSymlink(\n  target: string,\n  linkPath: string,\n  type: \"dir\" | \"file\"\n): void {\n  removeExistingLinkPath(linkPath);\n\n  const linkDir = dirname(linkPath);\n  const relativeTarget = relative(linkDir, target);\n\n  symlinkSync(relativeTarget, linkPath, type);\n}\n","import { mkdirSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { getProjectSkillsDir } from \"@/domains/project-store/project-paths\";\nimport { createOrReplaceSymlink } from \"@/domains/adapters/link-helper\";\nimport type { AgentAdapter } from \"@/domains/adapters/adapter.interface\";\nimport type { SkillMetadata } from \"@/types/skill.types\";\n\nexport class ClaudeAdapter implements AgentAdapter {\n  readonly id = \"claude\" as const;\n  readonly name = \"Claude Code\";\n  readonly targetRelativeDir = \".claude/skills\";\n\n  async installSkill(\n    targetPath: string,\n    skill: SkillMetadata,\n    _skillSourceDir: string\n  ): Promise<string[]> {\n    const parentDir = join(targetPath, this.targetRelativeDir);\n    if (!existsSync(parentDir)) {\n      mkdirSync(parentDir, { recursive: true });\n    }\n\n    const destination = join(parentDir, skill.directoryName);\n    const projectSkillDir = join(getProjectSkillsDir(targetPath), skill.directoryName);\n\n    createOrReplaceSymlink(projectSkillDir, destination, \"dir\");\n\n    return [destination];\n  }\n}\n","import { mkdirSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { getProjectCursorRulesDir } from \"@/domains/project-store/project-paths\";\nimport { createOrReplaceSymlink } from \"@/domains/adapters/link-helper\";\nimport type { AgentAdapter } from \"@/domains/adapters/adapter.interface\";\nimport type { SkillMetadata } from \"@/types/skill.types\";\n\nexport class CursorAdapter implements AgentAdapter {\n  readonly id = \"cursor\" as const;\n  readonly name = \"Cursor\";\n  readonly targetRelativeDir = \".cursor/rules\";\n\n  async installSkill(\n    targetPath: string,\n    skill: SkillMetadata,\n    _skillSourceDir: string\n  ): Promise<string[]> {\n    const rulesDir = join(targetPath, this.targetRelativeDir);\n    if (!existsSync(rulesDir)) {\n      mkdirSync(rulesDir, { recursive: true });\n    }\n\n    const filename = `${skill.id}.mdc`;\n    const destination = join(rulesDir, filename);\n    const projectRuleFile = join(getProjectCursorRulesDir(targetPath), filename);\n\n    createOrReplaceSymlink(projectRuleFile, destination, \"file\");\n\n    return [destination];\n  }\n}\n","import { mkdirSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { getProjectSkillsDir } from \"@/domains/project-store/project-paths\";\nimport { createOrReplaceSymlink } from \"@/domains/adapters/link-helper\";\nimport type { AgentAdapter } from \"@/domains/adapters/adapter.interface\";\nimport type { SkillMetadata } from \"@/types/skill.types\";\n\nexport class GeminiAdapter implements AgentAdapter {\n  readonly id = \"gemini\" as const;\n  readonly name = \"Gemini Code Assist\";\n  readonly targetRelativeDir = \".gemini/skills\";\n\n  async installSkill(\n    targetPath: string,\n    skill: SkillMetadata,\n    _skillSourceDir: string\n  ): Promise<string[]> {\n    const parentDir = join(targetPath, this.targetRelativeDir);\n    if (!existsSync(parentDir)) {\n      mkdirSync(parentDir, { recursive: true });\n    }\n\n    const destination = join(parentDir, skill.directoryName);\n    const projectSkillDir = join(getProjectSkillsDir(targetPath), skill.directoryName);\n\n    createOrReplaceSymlink(projectSkillDir, destination, \"dir\");\n\n    return [destination];\n  }\n}\n","import { cpSync, mkdirSync, existsSync, writeFileSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport {\n  getProjectSkillsDir,\n  getProjectCursorRulesDir,\n} from \"@/domains/project-store/project-paths\";\nimport { resolveSkillsSourceRoot } from \"@/domains/installer/resolve-skills-source\";\nimport { SKILL_CATALOG } from \"@/domains/registry/skill-catalog\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nexport function syncProjectStore(\n  targetPath: string,\n  selectedSkillIds: string[],\n  selectedAgents: AgentId[]\n): void {\n  const bundledSkillsDir = resolveSkillsSourceRoot();\n  const projectSkillsDir = getProjectSkillsDir(targetPath);\n  const projectCursorRulesDir = getProjectCursorRulesDir(targetPath);\n\n  if (!existsSync(projectSkillsDir)) {\n    mkdirSync(projectSkillsDir, { recursive: true });\n  }\n\n  const needsCursorRules = selectedAgents.includes(\"cursor\");\n  if (needsCursorRules && !existsSync(projectCursorRulesDir)) {\n    mkdirSync(projectCursorRulesDir, { recursive: true });\n  }\n\n  for (const skillId of selectedSkillIds) {\n    const skill = SKILL_CATALOG.find((item) => item.id === skillId);\n    if (!skill) {\n      continue;\n    }\n\n    const sourceSkillDir = join(bundledSkillsDir, skill.directoryName);\n    const destSkillDir = join(projectSkillsDir, skill.directoryName);\n\n    if (existsSync(sourceSkillDir)) {\n      cpSync(sourceSkillDir, destSkillDir, { recursive: true });\n    }\n\n    if (!needsCursorRules) {\n      continue;\n    }\n\n    const skillMdPath = join(destSkillDir, \"SKILL.md\");\n    if (!existsSync(skillMdPath)) {\n      continue;\n    }\n\n    const content = readFileSync(skillMdPath, \"utf-8\");\n    const mdcHeader = `---\ndescription: ${skill.description}\nglobs: [\"**/*\"]\nalwaysApply: false\n---\n\n`;\n    const cleanedBody = content.replace(/^---[\\s\\S]*?---\\s*/, \"\");\n    const targetMdc = join(projectCursorRulesDir, `${skill.id}.mdc`);\n    writeFileSync(targetMdc, `${mdcHeader}${cleanedBody}`, \"utf-8\");\n  }\n}\n","import { fileURLToPath } from \"node:url\";\nimport { dirname, resolve, join } from \"node:path\";\nimport { existsSync } from \"node:fs\";\n\nexport function resolveSkillsSourceRoot(): string {\n  const currentFilePath = fileURLToPath(import.meta.url);\n  const currentDir = dirname(currentFilePath);\n\n  // 1. From dist/ in published npm package or local build: dist/../skills\n  const candidateFromDist = resolve(currentDir, \"../skills\");\n  if (existsSync(candidateFromDist)) {\n    return candidateFromDist;\n  }\n\n  // 2. From src/domains/installer/ during development: ../../../skills\n  const candidateFromSrc = resolve(currentDir, \"../../../skills\");\n  if (existsSync(candidateFromSrc)) {\n    return candidateFromSrc;\n  }\n\n  // 3. Search upward for the package root containing a skills directory\n  let searchDir = currentDir;\n  for (let i = 0; i < 5; i++) {\n    const candidate = join(searchDir, \"skills\");\n    if (existsSync(candidate)) {\n      return candidate;\n    }\n    const parent = dirname(searchDir);\n    if (parent === searchDir) {\n      break;\n    }\n    searchDir = parent;\n  }\n\n  throw new Error(\n    `GrooveSkills internal error: Unable to locate bundled skills directory from ${currentDir}`\n  );\n}\n","import { existsSync, mkdirSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport {\n  getProjectMemoryDir,\n  getProjectTasksDir,\n} from \"@/domains/project-store/project-paths\";\nimport {\n  buildContextTemplate,\n  buildDecisionsTemplate,\n  buildTaskTemplate,\n} from \"@/domains/harness/harness-templates\";\nimport { upsertAgentInstructions } from \"@/domains/harness/upsert-agent-instructions\";\nimport type { HarnessInstallOptions } from \"@/types/harness.types\";\n\nexport function installHarness(options: HarnessInstallOptions): string[] {\n  const memoryDir = getProjectMemoryDir(options.targetPath);\n  const tasksDir = getProjectTasksDir(options.targetPath);\n\n  if (!existsSync(tasksDir)) {\n    mkdirSync(tasksDir, { recursive: true });\n  }\n\n  const createdFiles: string[] = [];\n\n  const contextPath = join(memoryDir, \"context.md\");\n  if (!existsSync(contextPath)) {\n    writeFileSync(contextPath, buildContextTemplate(options.detectedDependencies), \"utf-8\");\n    createdFiles.push(contextPath);\n  }\n\n  const decisionsPath = join(memoryDir, \"decisions.md\");\n  if (!existsSync(decisionsPath)) {\n    writeFileSync(decisionsPath, buildDecisionsTemplate(), \"utf-8\");\n    createdFiles.push(decisionsPath);\n  }\n\n  const templateTaskPath = join(tasksDir, \"_template.md\");\n  if (!existsSync(templateTaskPath)) {\n    writeFileSync(templateTaskPath, buildTaskTemplate(), \"utf-8\");\n    createdFiles.push(templateTaskPath);\n  }\n\n  const instructions = upsertAgentInstructions(options.targetPath, options.selectedAgents);\n  createdFiles.push(...instructions);\n\n  return createdFiles;\n}\n","export function buildContextTemplate(detectedDependencies: string[]): string {\n  const depsFormatted = detectedDependencies.length > 0\n    ? detectedDependencies.map((d) => `- \\`${d}\\``).join(\"\\n\")\n    : \"- (No external dependencies detected)\";\n\n  return `# Project Context & Architecture\n\nThis file provides AI agents with instant architectural orientation for this project.\n\n## 1. Stack & Dependencies\n${depsFormatted}\n\n## 2. Directory Structure Conventions\n- Follow single-responsibility per file (<200 lines).\n- Maintain direct imports with path aliases; avoid barrel files.\n- Keep domain boundaries explicit and clean.\n\n## 3. Essential Commands\n- Build: Refer to \\`package.json\\` scripts.\n- Typecheck: Refer to TypeScript configuration.\n- Tests: Refer to test runner configuration.\n`;\n}\n\nexport function buildDecisionsTemplate(): string {\n  const now = new Date().toISOString().split(\"T\")[0];\n  return `# Architecture Decision Records (ADR)\n\nAn append-only log of significant technical and architectural choices.\n\n| Date | Title | Decision | Reason & Consequences |\n| :--- | :--- | :--- | :--- |\n| ${now} | Adopt GrooveSkills Harness | Initialized \\`.grooveskills/\\` control plane | Clean, encapsulated agent memory and 3-lane execution flow |\n`;\n}\n\nexport function buildTaskTemplate(): string {\n  return `---\nstatus: in-progress\ncreatedAt: \\${CURRENT_DATE}\n---\n\n# Feature / Task Title\n\n## Intent\nDescribe what changes are being made and why they are necessary.\n\n## Scope\n- In scope:\n- Out of scope:\n\n## Checklist\n- [ ] Task 1: (Define expected observed proof)\n- [ ] Task 2: (Define expected observed proof)\n\n## Evidence\n- Observed test/typecheck/build commands or runtime outputs proving completion.\n\n## Next\n- Next concrete step if interrupted.\n`;\n}\n\nexport function buildAgentHarnessBlock(): string {\n  return `<!-- grooveskills:harness:start -->\n# GrooveSkills Harness — Agent Rules & Memory\n\nThis project uses the **GrooveSkills Harness** located in \\`.grooveskills/\\`.\n\n## 1. Three-Lane Rule\n- **Answer**: Explanations, audits, or questions. Read-only; write zero code.\n- **Task**: Direct implementation. Record intent, scope, and checklist in \\`.grooveskills/memory/tasks/<slug>.md\\`. Only check off tasks with observed evidence under \\`Evidence\\`.\n- **Spec**: Ambiguous or high-impact architecture. Clarify and validate the spec in \\`.grooveskills/memory/tasks/<slug>.md\\` before writing code.\n\n## 2. Memory Locations\n- Architecture context: \\`.grooveskills/memory/context.md\\`\n- Technical decisions (ADR): \\`.grooveskills/memory/decisions.md\\`\n- Active tasks & evidence: \\`.grooveskills/memory/tasks/\\`\n<!-- grooveskills:harness:end -->`;\n}\n","import { existsSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { buildAgentHarnessBlock } from \"@/domains/harness/harness-templates\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nconst START_MARKER = \"<!-- grooveskills:harness:start -->\";\nconst END_MARKER = \"<!-- grooveskills:harness:end -->\";\n\nfunction applyHarnessBlock(filePath: string): void {\n  const block = buildAgentHarnessBlock();\n\n  if (!existsSync(filePath)) {\n    writeFileSync(filePath, `${block}\\n`, \"utf-8\");\n    return;\n  }\n\n  const existingContent = readFileSync(filePath, \"utf-8\");\n\n  if (existingContent.includes(START_MARKER) && existingContent.includes(END_MARKER)) {\n    const regex = new RegExp(`${START_MARKER}[\\\\s\\\\S]*?${END_MARKER}`, \"g\");\n    const updated = existingContent.replace(regex, block);\n    writeFileSync(filePath, updated, \"utf-8\");\n    return;\n  }\n\n  const separator = existingContent.endsWith(\"\\n\") ? \"\\n\" : \"\\n\\n\";\n  writeFileSync(filePath, `${existingContent}${separator}${block}\\n`, \"utf-8\");\n}\n\nexport function upsertAgentInstructions(targetPath: string, selectedAgents: AgentId[]): string[] {\n  const updatedFiles: string[] = [];\n\n  const agentsMdPath = join(targetPath, \"AGENTS.md\");\n  applyHarnessBlock(agentsMdPath);\n  updatedFiles.push(agentsMdPath);\n\n  if (selectedAgents.includes(\"claude\")) {\n    const claudeMdPath = join(targetPath, \"CLAUDE.md\");\n    applyHarnessBlock(claudeMdPath);\n    updatedFiles.push(claudeMdPath);\n  }\n\n  return updatedFiles;\n}\n","import { existsSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { getProjectConfigPath } from \"@/domains/project-store/project-paths\";\nimport type { GrooveSkillsConfig } from \"@/types/harness.types\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nexport function writeProjectConfig(\n  targetPath: string,\n  newSkills: string[],\n  newAgents: AgentId[],\n  harnessEnabled: boolean\n): string {\n  const configPath = getProjectConfigPath(targetPath);\n\n  let existingSkills: string[] = [];\n  let existingAgents: AgentId[] = [];\n  let existingHarness = false;\n\n  if (existsSync(configPath)) {\n    try {\n      const parsed = JSON.parse(readFileSync(configPath, \"utf-8\")) as Partial<GrooveSkillsConfig>;\n      if (Array.isArray(parsed.skills)) {\n        existingSkills = parsed.skills;\n      }\n      if (Array.isArray(parsed.agents)) {\n        existingAgents = parsed.agents;\n      }\n      if (typeof parsed.harness === \"boolean\") {\n        existingHarness = parsed.harness;\n      }\n    } catch {\n      // If parsing fails, fall back to initial state\n    }\n  }\n\n  const mergedSkills = Array.from(new Set([...existingSkills, ...newSkills]));\n  const mergedAgents = Array.from(new Set([...existingAgents, ...newAgents]));\n\n  const config: GrooveSkillsConfig = {\n    version: 1,\n    harness: existingHarness || harnessEnabled,\n    agents: mergedAgents,\n    skills: mergedSkills,\n    updatedAt: new Date().toISOString(),\n  };\n\n  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\\n`, \"utf-8\");\n\n  return configPath;\n}\n","import { detectProjectContext } from \"@/domains/detector/project-detector\";\nimport { runInteractiveUi } from \"@/domains/ui/ui-orchestrator\";\nimport { installSkills } from \"@/domains/installer/install-orchestrator\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nexport interface CliOptions {\n  skills?: string[];\n  agents?: AgentId[];\n  yes?: boolean;\n  harness?: boolean;\n}\n\nexport async function runGrooveSkills(options: CliOptions = {}): Promise<void> {\n  const targetPath = process.cwd();\n  const context = detectProjectContext(targetPath);\n\n  const hasSkills = options.skills && options.skills.length > 0;\n  const hasAgents = options.agents && options.agents.length > 0;\n  const isDirectHarness = Boolean(options.harness) && hasAgents;\n\n  if ((hasSkills && hasAgents) || isDirectHarness) {\n    await installSkills({\n      targetPath,\n      selectedSkillIds: options.skills || [],\n      selectedAgents: options.agents || [],\n      forceOverwrite: Boolean(options.yes),\n      enableHarness: options.harness,\n      detectedDependencies: context.detectedDependencies,\n    });\n    return;\n  }\n\n  await runInteractiveUi(context);\n}\n"],"mappings":"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","names":["existsSync","join","existsSync","join","p","pc","p","p","confirm","p","join","join","existsSync","join","join","lstatSync","join","existsSync","mkdirSync","existsSync","join","join","existsSync","mkdirSync","mkdirSync","existsSync","join","join","existsSync","mkdirSync","mkdirSync","existsSync","join","join","existsSync","mkdirSync","mkdirSync","existsSync","readFileSync","join","dirname","join","existsSync","existsSync","mkdirSync","join","readFileSync","existsSync","mkdirSync","writeFileSync","join","existsSync","readFileSync","writeFileSync","join","existsSync","writeFileSync","readFileSync","join","existsSync","mkdirSync","join","writeFileSync","existsSync","readFileSync","writeFileSync","existsSync","readFileSync","writeFileSync","join","pc","s","confirm"]}

package/dist/cli.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 import {
   runGrooveSkills
-} from "./chunk-TYA2EELM.js";
+} from "./chunk-5Q6O3BRA.js";
 
 // bin/cli.ts
 import { Command } from "commander";
 var program = new Command();
-program.name("grooveskills").description("Multi-agent AI skills and architecture standards installer").version("1.0.0").option("-s, --skills <skills...>", "Specific skill IDs to install (e.g. best-practices hono)").option("-a, --agents <agents...>", "Target AI agents (antigravity claude cursor gemini)").option("-y, --yes", "Automatically confirm overwrite of existing skills", false).action(async (options) => {
+program.name("grooveskills").description("Multi-agent AI skills and architecture standards installer").version("1.1.0").option("-s, --skills <skills...>", "Specific skill IDs to install (e.g. best-practices hono groove-harness)").option("-a, --agents <agents...>", "Target AI agents (antigravity claude cursor gemini)").option("-y, --yes", "Automatically confirm overwrite of existing skills", false).option("--harness", "Initialize or update GrooveSkills project harness in .grooveskills/").option("--no-harness", "Skip harness initialization").action(async (options) => {
   try {
     await runGrooveSkills({
       skills: options.skills,
       agents: options.agents,
-      yes: options.yes
+      yes: options.yes,
+      harness: options.harness
     });
   } catch (error) {
     console.error("An unexpected error occurred while running GrooveSkills:", error);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../bin/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Command } from \"commander\";\nimport { runGrooveSkills } from \"@/main\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nconst program = new Command();\n\nprogram\n  .name(\"grooveskills\")\n  .description(\"Multi-agent AI skills and architecture standards installer\")\n  .version(\"1.0.0\")\n  .option(\"-s, --skills <skills...>\", \"Specific skill IDs to install (e.g. best-practices hono)\")\n  .option(\"-a, --agents <agents...>\", \"Target AI agents (antigravity claude cursor gemini)\")\n  .option(\"-y, --yes\", \"Automatically confirm overwrite of existing skills\", false)\n  .action(async (options: { skills?: string[]; agents?: string[]; yes?: boolean }) => {\n    try {\n      await runGrooveSkills({\n        skills: options.skills,\n        agents: options.agents as AgentId[] | undefined,\n        yes: options.yes,\n      });\n    } catch (error) {\n      console.error(\"An unexpected error occurred while running GrooveSkills:\", error);\n      process.exit(1);\n    }\n  });\n\nprogram.parse();\n"],"mappings":";;;;;;AACA,SAAS,eAAe;AAIxB,IAAM,UAAU,IAAI,QAAQ;AAE5B,QACG,KAAK,cAAc,EACnB,YAAY,4DAA4D,EACxE,QAAQ,OAAO,EACf,OAAO,4BAA4B,0DAA0D,EAC7F,OAAO,4BAA4B,qDAAqD,EACxF,OAAO,aAAa,sDAAsD,KAAK,EAC/E,OAAO,OAAO,YAAqE;AAClF,MAAI;AACF,UAAM,gBAAgB;AAAA,MACpB,QAAQ,QAAQ;AAAA,MAChB,QAAQ,QAAQ;AAAA,MAChB,KAAK,QAAQ;AAAA,IACf,CAAC;AAAA,EACH,SAAS,OAAO;AACd,YAAQ,MAAM,4DAA4D,KAAK;AAC/E,YAAQ,KAAK,CAAC;AAAA,EAChB;AACF,CAAC;AAEH,QAAQ,MAAM;","names":[]}
+{"version":3,"sources":["../bin/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Command } from \"commander\";\nimport { runGrooveSkills } from \"@/main\";\nimport type { AgentId } from \"@/types/agent.types\";\n\nconst program = new Command();\n\nprogram\n  .name(\"grooveskills\")\n  .description(\"Multi-agent AI skills and architecture standards installer\")\n  .version(\"1.1.0\")\n  .option(\"-s, --skills <skills...>\", \"Specific skill IDs to install (e.g. best-practices hono groove-harness)\")\n  .option(\"-a, --agents <agents...>\", \"Target AI agents (antigravity claude cursor gemini)\")\n  .option(\"-y, --yes\", \"Automatically confirm overwrite of existing skills\", false)\n  .option(\"--harness\", \"Initialize or update GrooveSkills project harness in .grooveskills/\")\n  .option(\"--no-harness\", \"Skip harness initialization\")\n  .action(async (options: { skills?: string[]; agents?: string[]; yes?: boolean; harness?: boolean }) => {\n    try {\n      await runGrooveSkills({\n        skills: options.skills,\n        agents: options.agents as AgentId[] | undefined,\n        yes: options.yes,\n        harness: options.harness,\n      });\n    } catch (error) {\n      console.error(\"An unexpected error occurred while running GrooveSkills:\", error);\n      process.exit(1);\n    }\n  });\n\nprogram.parse();\n"],"mappings":";;;;;;AACA,SAAS,eAAe;AAIxB,IAAM,UAAU,IAAI,QAAQ;AAE5B,QACG,KAAK,cAAc,EACnB,YAAY,4DAA4D,EACxE,QAAQ,OAAO,EACf,OAAO,4BAA4B,yEAAyE,EAC5G,OAAO,4BAA4B,qDAAqD,EACxF,OAAO,aAAa,sDAAsD,KAAK,EAC/E,OAAO,aAAa,qEAAqE,EACzF,OAAO,gBAAgB,6BAA6B,EACpD,OAAO,OAAO,YAAwF;AACrG,MAAI;AACF,UAAM,gBAAgB;AAAA,MACpB,QAAQ,QAAQ;AAAA,MAChB,QAAQ,QAAQ;AAAA,MAChB,KAAK,QAAQ;AAAA,MACb,SAAS,QAAQ;AAAA,IACnB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,YAAQ,MAAM,4DAA4D,KAAK;AAC/E,YAAQ,KAAK,CAAC;AAAA,EAChB;AACF,CAAC;AAEH,QAAQ,MAAM;","names":[]}

package/dist/main.d.ts

@@ -4,6 +4,7 @@ interface CliOptions {
     skills?: string[];
     agents?: AgentId[];
     yes?: boolean;
+    harness?: boolean;
 }
 declare function runGrooveSkills(options?: CliOptions): Promise<void>;
 

package/dist/main.js

@@ -1,6 +1,6 @@
 import {
   runGrooveSkills
-} from "./chunk-TYA2EELM.js";
+} from "./chunk-5Q6O3BRA.js";
 export {
   runGrooveSkills
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3lineas/grooveskills",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Multi-agent CLI to install opinionated AI coding skills and architectural standards (Hono, React, Next.js, and more)",
   "type": "module",
   "bin": {

package/skills/groove-harness/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: groove-harness
+description: Lightweight project harness, context memory, and 3-lane task execution (Answer, Task, Spec) for AI coding agents.
+---
+
+# GrooveSkills Harness — Project Control Plane
+
+A lightweight, non-intrusive harness living entirely within `.grooveskills/`. It gives agents persistent project memory, clear architectural boundaries, and a disciplined 3-lane execution flow.
+
+---
+
+## 1. The Three Execution Lanes
+
+Classify each user request into one of three lanes before taking action:
+
+### Lane 1: Answer (Read-Only)
+- **Trigger**: The user asks for explanations, audits, code reviews, comparisons, or architectural questions.
+- **Rule**: Read-only. Write zero code, create zero artifacts, modify no files.
+
+### Lane 2: Task (Direct Feature or Bugfix)
+- **Trigger**: Concrete change, standard feature, refactor, or bugfix with clear requirements.
+- **Protocol**:
+  1. Locate or create `.grooveskills/memory/tasks/<slug>.md` using the format in `.grooveskills/memory/tasks/_template.md`.
+  2. Declare `Intent`, `Scope`, and an itemized `Checklist`.
+  3. Execute code changes incrementally according to project standards.
+  4. Only check off items once **observed evidence** is verified (e.g. `check-types`, test runs, or command outputs under `Evidence`).
+  5. Keep `Next` updated so any interruption costs nothing.
+
+### Lane 3: Spec (Complex or Ambiguous Architecture)
+- **Trigger**: Multi-component restructuring, ambiguous requirements, or high-risk domain changes.
+- **Protocol**:
+  1. Draft the architectural proposal, interfaces, trade-offs, and open questions inside `.grooveskills/memory/tasks/<slug>.md`.
+  2. Present the spec to the user and request explicit confirmation.
+  3. Once approved, switch to Lane 2 (Task) for disciplined implementation.
+
+---
+
+## 2. Project Memory Maintenance
+
+- **`.grooveskills/memory/context.md`**: Stores project stack, architectural patterns, conventions, and key commands. Read this when starting work on a domain; update it when new dependencies or architectural standards are introduced.
+- **`.grooveskills/memory/decisions.md`**: An append-only Architecture Decision Record (ADR). Log significant technical decisions (`Date`, `Context`, `Decision`, `Consequences`).
+- **`.grooveskills/memory/tasks/`**: Individual feature records holding intent and observed proof.
+
+---
+
+## 3. Core Principles
+
+1. **No Silent Changes**: Every non-trivial change is backed by an observed verification step.
+2. **Strict Encapsulation**: Keep harness and state confined to `.grooveskills/`. Do not pollute the root repository.
+3. **Respect Best Practices**: All code must follow strict typing, guard clauses, SRP, direct imports (no barrels), and file limits (<200 lines).

package/skills/react-advanced/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: react-advanced
+description: Use when building with React 19 platform features and rendering architecture: React Compiler (auto-memoization), concurrent rendering (useTransition, useDeferredValue, Suspense), the use() hook, Actions (useActionState, useOptimistic, useFormStatus), ref-as-prop, <Context value>, compound components, context splitting, error boundaries, portals, virtualization (@tanstack/react-virtual), code-splitting, and RSC / 'use client' boundaries. TRIGGER when optimizing React performance, adopting React 19 APIs, working with forms/mutations, or architecting complex React component trees. Always adhere to 'best-practices' and 'react-core'.
+---
+
+# React Advanced: React 19 Platform & Rendering Architecture
+
+Opinionated reference for **React 19** and **React Compiler 1.0** capabilities, concurrent rendering primitives, async Actions, advanced component composition, performance engineering, and React Server Component (RSC) boundaries.
+
+---
+
+## 1. Golden Rules (Non-negotiable)
+
+1. **React Compiler First — Stop Reflexive Manual Memoization**:
+   - Do not wrap every derived value or handler in `useMemo`, `useCallback`, or `React.memo` by reflex in new code.
+   - Reserve manual `useMemo`/`useCallback` strictly for **effect dependency stability** (`useEffect` identity contracts) or code skipped by the compiler.
+   - Never strip existing manual memoization blindly; respect `preserve-manual-memoization` lint warnings.
+2. **React 19 Idioms Only (No Legacy Wrappers)**:
+   - Receive `ref` as a plain prop on function components (`ComponentProps<"input">`)—never use `forwardRef` in new code.
+   - Render `<MyContext value={val}>` directly—never use legacy `<MyContext.Provider>`.
+   - Render native `<title>`, `<meta>`, and `<link>` tags directly in components—never add `react-helmet`.
+3. **Actions for Async Mutations & Forms**:
+   - Use `useActionState`, `useOptimistic`, `useFormStatus`, and `<form action={fn}>` for form submissions and async mutations instead of manual `isLoading`/`error` `useState` boilerplate.
+4. **Concurrent Responsiveness & Post-`await` Transitions**:
+   - Use `useTransition` for non-urgent state updates and `useDeferredValue` instead of fixed `setTimeout` debouncing for expensive derived renders.
+   - Inside `startTransition(async () => { ... })`, always re-wrap state updates that happen **after an `await`** in a nested `startTransition(() => setState(...))`.
+5. **Safe `use()` Hook Usage**:
+   - `use(promiseOrContext)` may be called conditionally after early returns, but **never inside `try / catch`**. Handle rejected promises with an **Error Boundary**.
+   - Never create a new promise inline during client render (`use(fetchData())`); pass a stable promise created on the server, in a parent, or in an event/transition.
+6. **Context Architecture by Change Frequency**:
+   - Native Context has no selector and bypasses `React.memo`. Never combine high-frequency state (e.g. cursor/scroll) and low-frequency state (e.g. theme/auth) in a single Context. Split contexts by update rate and memoize provider values.
+7. **Virtualize Large Lists & Split by Route**:
+   - Virtualize lists exceeding ~100 items using `@tanstack/react-virtual`.
+   - Code-split with `React.lazy` + `Suspense` at **route or heavy-feature boundaries**, avoiding micro-chunks (<10KB).
+8. **Strict RSC & `'use server'` Security Boundary**:
+   - Treat `'use client'` as a **module dependency graph** boundary: props crossing into client modules must be serializable.
+   - Treat every `'use server'` function as a public HTTP endpoint: validate inputs with **Valibot** (`* as v from "valibot"`) and verify authorization inside the function before executing mutations.
+9. **GrooveSkills Architecture Compliance**:
+   - Enforce `< 200` lines per file, mandatory `@/...` path aliases, zero barrel files (`index.ts`), and early returns across all components and hooks.
+
+---
+
+## 2. Compiler, Concurrency & React 19 Actions
+
+```tsx
+import { startTransition, useActionState, useDeferredValue, useState } from "react";
+import { updateFilterPreferenceAction } from "@/actions/catalog/update-filter-preference.action";
+import type { Product } from "@/types/product.types";
+
+export function ProductExplorer({ catalog }: { catalog: Product[] }) {
+  const [query, setQuery] = useState<string>("");
+  const deferredQuery = useDeferredValue(query, "");
+
+  const [state, saveAction, isPending] = useActionState(
+    async (_prev: { error?: string }, formData: FormData) => {
+      const savedQuery = String(formData.get("query") ?? "");
+      return await updateFilterPreferenceAction({ query: savedQuery });
+    },
+    {}
+  );
+
+  function handleAsyncRefresh(fetchNext: () => Promise<string>): void {
+    startTransition(async () => {
+      const nextQuery = await fetchNext();
+      // Always re-wrap state updates after await in startTransition:
+      startTransition(() => setQuery(nextQuery));
+    });
+  }
+
+  const matches = catalog.filter((item) =>
+    item.name.toLowerCase().includes(deferredQuery.toLowerCase())
+  );
+
+  return (
+    <section>
+      <form action={saveAction}>
+        <input name="query" value={query} onChange={(e) => setQuery(e.target.value)} />
+        <button type="submit" disabled={isPending}>Save Filter</button>
+        {state.error && <p role="alert">{state.error}</p>}
+      </form>
+      <ul style={{ opacity: query !== deferredQuery ? 0.6 : 1 }}>
+        {matches.map((p) => <li key={p.id}>{p.name}</li>)}
+      </ul>
+    </section>
+  );
+}
+```
+
+---
+
+## 3. RSC & `'use server'` Boundary with Valibot
+
+Server Functions (`'use server'`) are public-facing boundaries. Always validate inputs with **Valibot** and authorize the caller before executing business logic.
+
+```tsx
+"use server";
+
+import * as v from "valibot";
+import { requireAuthenticatedUser } from "@/actions/auth/require-authenticated-user.action";
+
+const commentSchema = v.object({
+  articleId: v.pipe(v.string(), v.nonEmpty("Article ID is required.")),
+  body: v.pipe(
+    v.string(),
+    v.trim(),
+    v.minLength(3, "Please write at least 3 characters before posting.")
+  ),
+});
+
+export async function publishCommentServerAction(formData: FormData) {
+  const parsed = v.safeParse(commentSchema, {
+    articleId: formData.get("articleId"),
+    body: formData.get("body"),
+  });
+
+  if (!parsed.success) {
+    return { success: false, error: parsed.issues[0].message };
+  }
+
+  const user = await requireAuthenticatedUser();
+  return { success: true, userId: user.id, message: "Thank you! Your comment has been published." };
+}
+```
+
+---
+
+## 4. Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It Fails | Fix |
+| :--- | :--- | :--- |
+| Hand-memoizing everything with React Compiler active | Adds visual noise and redundant cache overhead | Write plain code; use `useMemo` only as an effect-dependency escape hatch |
+| Stripping existing `useMemo` blindly | Can break effect dependency stability contracts | Respect `preserve-manual-memoization` lint warnings |
+| Updating state after `await` in `startTransition` without re-wrapping | Post-`await` update escapes the transition; `isPending` ends prematurely | Wrap post-`await` state updates in `startTransition(() => ...)` |
+| Calling `use(promise)` inside `try / catch` or creating promises in client render | Suspense throws internal signals; inline promises recreate every render | Use Error Boundaries for rejections; create promises above the component |
+| Using `forwardRef`, `<Context.Provider>`, or `react-helmet` | Deprecated/superseded in React 19 | Pass `ref` as prop, render `<Context value>`, use native `<title>`/`<meta>` |
+| Unvalidated `'use server'` arguments | `'use server'` endpoints are public and untrusted | Validate with Valibot (`* as v from "valibot"`) and check auth first |
+
+---
+
+## 5. Reference Navigation
+
+- **[react-compiler.md](references/react-compiler.md)**: Compiler adoption, ESLint v6+, escape hatches, and detection checklist.
+- **[concurrent-rendering.md](references/concurrent-rendering.md)**: `useTransition`, post-`await` rule, `useDeferredValue`, `Suspense`, and streaming SSR.
+- **[react19-actions-and-apis.md](references/react19-actions-and-apis.md)**: `use()`, `useActionState`, `useOptimistic`, `useFormStatus`, `ref` prop, `<Context value>`, and native metadata.
+- **[component-patterns.md](references/component-patterns.md)**: Compound components, context splitting, `use-context-selector`, error boundaries, and portals.
+- **[performance.md](references/performance.md)**: `@tanstack/react-virtual`, route-first `React.lazy`, Profiler workflow, and anti-pattern table.
+- **[rsc-boundary.md](references/rsc-boundary.md)**: Module-graph `'use client'` rules, serializable props, `'use server'` Valibot security, and React version pinning.

package/skills/react-advanced/references/component-patterns.md

@@ -0,0 +1,117 @@
+# Advanced Component Patterns
+
+> Source of truth: [useContext](https://react.dev/reference/react/useContext), [createPortal](https://react.dev/reference/react-dom/createPortal), and [Component (error boundaries)](https://react.dev/reference/react/Component).
+
+## Compound Components
+
+Compound components let a parent and its sub-components coordinate through implicit shared state via Context so consumers compose pieces declaratively without prop drilling. In GrooveSkills projects, keep each sub-component under 200 lines or extract sub-components into dedicated files under the same domain folder.
+
+```tsx
+import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
+
+interface TabsContextValue {
+  activeTab: string;
+  setActiveTab: (id: string) => void;
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+export function useTabsContext(): TabsContextValue {
+  const ctx = useContext(TabsContext);
+  if (!ctx) {
+    throw new Error("Tab components must be rendered inside <TabsRoot>.");
+  }
+  return ctx;
+}
+
+export function TabsRoot({
+  defaultTab,
+  children,
+}: {
+  defaultTab: string;
+  children: ReactNode;
+}) {
+  const [activeTab, setActiveTab] = useState<string>(defaultTab);
+  const value = useMemo(() => ({ activeTab, setActiveTab }), [activeTab]);
+
+  return <TabsContext value={value}>{children}</TabsContext>;
+}
+```
+
+## Context Optimization
+
+Native context has **no selector**. When a provider value changes, **every** consumer of that context re-renders, regardless of which slice each consumer reads:
+
+- `React.memo` does **not** block context-driven re-renders.
+- `use(Context)` adds *conditional reading* but **not** *selective subscription*.
+- The React Compiler does **not** solve large-context over-rendering.
+
+### Native fix 1 — Memoize the provider value
+
+A provider value object created inline is a new reference every render. Memoize it when passing an object literal:
+
+```tsx
+const authValue = useMemo(() => ({ user, signOut }), [user, signOut]);
+return <AuthContext value={authValue}>{children}</AuthContext>;
+```
+
+### Native fix 2 — Split contexts by change frequency
+
+Separate slow-changing state from fast-changing state so frequent updates never re-render consumers of stable data:
+
+```tsx
+// ❌ BAD: theme (rare) and pointer (frequent) share one context.
+const UIContext = createContext<{ theme: ThemeMode; pointer: Point } | null>(null);
+
+// ✅ GOOD: independent contexts; pointer churn never re-renders theme consumers.
+export const ThemeContext = createContext<ThemeMode>("light");
+export const PointerContext = createContext<Point>({ x: 0, y: 0 });
+```
+
+### Userland fix — `use-context-selector` or External Stores
+
+When a single store holds many slices and consumers must subscribe to a single slice, use `use-context-selector` or a dedicated external store (`useSyncExternalStore` / Zustand / Nanostores).
+
+## Custom Hooks vs Render Props
+
+- **Custom Hooks (`use-*.ts`)**: Default choice for sharing stateful logic cleanly across components.
+- **Render Props**: Useful for headless UI wrappers that own behavior/DOM measurement and delegate markup rendering to the caller.
+
+## Error Boundaries
+
+Error boundaries catch errors thrown during render, lifecycle methods, and constructors of the tree below them. For async and event-handler errors, pair `react-error-boundary` (`useErrorBoundary().showBoundary(error)`) with React 19's root `onCaughtError` / `onUncaughtError` hooks.
+
+```tsx
+import { useErrorBoundary } from "react-error-boundary";
+import { saveRecordAction } from "@/actions/records/save-record.action";
+
+export function SaveRecordButton({ payload }: { payload: string }) {
+  const { showBoundary } = useErrorBoundary();
+
+  async function handleSave(): Promise<void> {
+    try {
+      await saveRecordAction(payload);
+    } catch (error) {
+      showBoundary(error);
+    }
+  }
+
+  return (
+    <button type="button" onClick={handleSave}>
+      Save Changes
+    </button>
+  );
+}
+```
+
+## Portals
+
+`createPortal` renders children into a different DOM node (`document.body`) while keeping them in the same place in the **React tree** (preserving Context and React event bubbling). Use portals for modals, dialogs, tooltips, and toasts that must escape parent `overflow: hidden` or `z-index` stacking contexts.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it is wrong | Detection |
+|---|---|---|
+| One large context for high-frequency state | Every consumer re-renders on any change; `memo` cannot block it | Profiler shows unrelated consumers re-rendering |
+| Expecting `React.memo` to stop context re-renders | Context bypasses prop comparison | Memoized child still re-renders on context change |
+| Expecting native boundaries to catch async/event errors | Native boundaries catch only render-phase errors | Unhandled promise rejections in click handlers |

package/skills/react-advanced/references/concurrent-rendering.md

@@ -0,0 +1,130 @@
+# Concurrent Rendering
+
+> Source of truth: [useTransition](https://react.dev/reference/react/useTransition), [useDeferredValue](https://react.dev/reference/react/useDeferredValue), [Suspense](https://react.dev/reference/react/Suspense), and [renderToPipeableStream](https://react.dev/reference/react-dom/server/renderToPipeableStream).
+
+Concurrent rendering lets React prepare a new UI in the background and interrupt it for more urgent work. Urgent updates (typing, clicking) stay responsive while expensive updates (filtering thousands of rows, navigating) render without blocking input.
+
+## `useTransition`
+
+`useTransition` marks a state update as a non-urgent **transition**. React renders the transition in the background, keeps the current UI interactive, and exposes `isPending` so the UI can show a subtle pending indicator without a hard fallback.
+
+```tsx
+import { useState, useTransition } from "react";
+import { ExpensiveReports } from "@/components/reports/expensive-reports";
+import { HomeOverview } from "@/components/home/home-overview";
+import { TabBar } from "@/components/navigation/tab-bar";
+
+export function TabbedView() {
+  const [tab, setTab] = useState<"home" | "reports">("home");
+  const [isPending, startTransition] = useTransition();
+
+  function selectTab(next: "home" | "reports"): void {
+    startTransition(() => setTab(next));
+  }
+
+  return (
+    <>
+      <TabBar active={tab} onSelect={selectTab} busy={isPending} />
+      {tab === "reports" ? <ExpensiveReports /> : <HomeOverview />}
+    </>
+  );
+}
+```
+
+### React 19 async transitions and the post-`await` gotcha
+
+React 19 allows `startTransition` to receive an async function (an "Action"). Only updates issued **synchronously within the transition scope** belong to the transition. Updates after an `await` run in a fresh task and escape it unless re-wrapped.
+
+```tsx
+// ❌ BAD: setResult runs after await, outside the transition; isPending ends early.
+startTransition(async () => {
+  const data = await fetchData();
+  setResult(data);
+});
+
+// ✅ GOOD: re-wrap the post-await update so it stays part of the transition.
+startTransition(async () => {
+  const data = await fetchData();
+  startTransition(() => setResult(data));
+});
+```
+
+## `startTransition` vs `useDeferredValue`
+
+`startTransition` marks an update non-urgent at the **call site** (event handlers). `useDeferredValue` marks a **value** as allowed to lag when an expensive subtree trails a fast-changing input.
+
+Prefer `useDeferredValue` over a fixed `setTimeout` debounce for expensive *derived renders*: it is interruptible and device-adaptive.
+
+```tsx
+import { useDeferredValue, useState } from "react";
+
+export interface RowItem {
+  id: string;
+  label: string;
+}
+
+export function FilterList({ rows }: { rows: RowItem[] }) {
+  const [text, setText] = useState<string>("");
+  const deferredText = useDeferredValue(text, "");
+
+  const filtered = rows.filter((r) => r.label.includes(deferredText));
+  const isStale = text !== deferredText;
+
+  return (
+    <>
+      <input value={text} onChange={(e) => setText(e.target.value)} />
+      <ul style={{ opacity: isStale ? 0.6 : 1 }}>
+        {filtered.map((r) => (
+          <li key={r.id}>{r.label}</li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
+## Suspense for Data
+
+A component suspends when it reads a not-yet-resolved promise via `use()`. The nearest `<Suspense fallback>` shows until the promise resolves.
+
+```tsx
+import { Suspense, use } from "react";
+import type { User } from "@/types/user.types";
+import { ProfileSkeleton } from "@/components/profile/profile-skeleton";
+
+export function ProfileSection({ userPromise }: { userPromise: Promise<User> }) {
+  return (
+    <Suspense fallback={<ProfileSkeleton />}>
+      <ProfileHeader userPromise={userPromise} />
+    </Suspense>
+  );
+}
+
+function ProfileHeader({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise);
+  return <h1>{user.name}</h1>;
+}
+```
+
+### Resetting a boundary with `key`
+
+Changing the `key` on a Suspense boundary (or a component inside it) discards the previous tree and re-suspends when switching the displayed resource:
+
+```tsx
+<Suspense fallback={<ProfileSkeleton />}>
+  <ProfileLoader key={userId} userId={userId} />
+</Suspense>
+```
+
+## Streaming SSR (React Level)
+
+For Node servers, `renderToPipeableStream` streams HTML as Suspense boundaries resolve (`renderToReadableStream` for Web Streams / Edge / Cloudflare Workers). Design a meaningful **shell** (header, navigation, layout) that flushes immediately, and let slower data stream behind Suspense.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it is wrong | Detection |
+|---|---|---|
+| State update after `await` in an async transition | Escapes the transition; `isPending` ends early | UI flips to non-pending mid-operation |
+| Fixed debounce/throttle for expensive derived renders | `useDeferredValue` is interruptible and adaptive | Janky typing on slow devices; hard-coded timers |
+| One root spinner instead of a streamed shell | Blocks first paint on the slowest data | Long blank time-to-first-byte |
+| Suspense fallback that mismatches final layout | Causes layout shift on reveal | Visible jump when content arrives |