fix: install Grok Skills under .grok and declare hookMatcher metadata

Review feedback: Grok discovers project Skills from .grok/skills, and
platform-specific hook matchers belong on the Platform definition.

Author: mouyase

CHANGELOG.md

@@ -6,7 +6,7 @@ All notable changes to @rpamis/comet will be documented in this file.
 
 ### Added
 
-- **Grok platform support**: `comet init`, `comet update`, `comet doctor`, and `comet uninstall` now treat Grok as a first-class host. Project Skills share the `.agents` root with Codex, while rules and the Hook Router live under `.grok/rules/` and `.grok/hooks/comet.json`. The Router recognizes `--platform grok` and matches Grok's native `write` / `search_replace` tools.
+- **Grok platform support**: `comet init`, `comet update`, `comet doctor`, and `comet uninstall` now treat Grok as a first-class host. Skills, rules, and the Hook Router live under `.grok/skills/`, `.grok/rules/`, and `.grok/hooks/comet.json`. The Router recognizes `--platform grok` and matches Grok's native `write` / `search_replace` tools.
 
 ## What's Changed [0.4.0-beta.19] - 2026-08-15
 

README-zh.md

@@ -463,7 +463,7 @@ comet eval ./my-skill --suite langsmith --html
 | ForgeCode          | `.forge/`     | Trae          | `.trae/`     |
 | Trae CN            | `.trae-cn/`   | ZCode         | `.zcode/`    |
 | MimoCode           | `.mimocode/`  | CoStrict      | `.cospec/`   |
-| Grok               | `.agents/`    |               |              |
+| Grok               | `.grok/`      |               |              |
 
 </details>
 

README.md

@@ -492,7 +492,7 @@ does not expand the backend command list; see the [Skill creation guide](docs/op
 | ForgeCode          | `.forge/`     | Trae          | `.trae/`     |
 | Trae CN            | `.trae-cn/`   | ZCode         | `.zcode/`    |
 | MimoCode           | `.mimocode/`  | CoStrict      | `.cospec/`   |
-| Grok               | `.agents/`    |               |              |
+| Grok               | `.grok/`      |               |              |
 
 </details>
 

app/commands/init.ts

@@ -718,6 +718,7 @@ export async function initCommand(
     ['zcode', 'mimocode'].includes(id),
   );
   const mirrorCodeBuddyPlatformIds = selectedPlatformIdsForOs.filter((id) => id === 'workbuddy');
+  const mirrorCodexPlatformIds = selectedPlatformIdsForOs.filter((id) => id === 'grok');
 
   const selectedNpmDeps = await selectNpmDeps(
     projectPath,
@@ -786,6 +787,7 @@ export async function initCommand(
           osFailureReason = error.message;
         },
         mirrorCodeBuddyPlatformIds,
+        mirrorCodexPlatformIds,
       );
       if (osGlobalStatus === 'installed' && requiresClassicArtifactRoot) {
         await assertClassicProjectMutationAllowed?.();

app/commands/update.ts

@@ -1830,6 +1830,9 @@ async function updateSingleProject(
     const mirrorCodeBuddyPlatformIds = scopeTargets
       .map((target) => target.platform.id)
       .filter((id) => id === 'workbuddy');
+    const mirrorCodexPlatformIds = scopeTargets
+      .map((target) => target.platform.id)
+      .filter((id) => id === 'grok');
     const artifactLayout = scope === 'project' ? classicArtifactLayout : 'legacy';
     try {
       if (scope === 'project') {
@@ -1845,6 +1848,7 @@ async function updateSingleProject(
         scope === 'project' ? assertClassicProjectMutationAllowed : undefined,
         undefined,
         mirrorCodeBuddyPlatformIds,
+        mirrorCodexPlatformIds,
       );
       if (status === 'failed') {
         openSpecStatus = 'failed';

domains/integrations/openspec.ts

@@ -314,6 +314,7 @@ async function mergeGeneratedToolDirectories(
   mirrorOpenCodePlatformIds: readonly string[],
   mirrorCodeBuddyPlatformIds: readonly string[],
   projectMutationGuard?: ProjectMutationGuard,
+  mirrorCodexPlatformIds: readonly string[] = [],
 ): Promise<void> {
   for (const copy of copies) {
     await copyGeneratedToolDirectory(
@@ -364,6 +365,29 @@ async function mergeGeneratedToolDirectories(
       }
     }
   }
+
+  if (toolIds.includes('codex') && mirrorCodexPlatformIds.length > 0) {
+    const codexPlatform = PLATFORMS.find((platform) => platform.id === 'codex');
+    if (codexPlatform) {
+      const source = path.join(
+        stagingProject,
+        codexPlatform.openspecSkillsDir ?? codexPlatform.skillsDir,
+      );
+      if (fs.existsSync(source)) {
+        for (const platformId of new Set(mirrorCodexPlatformIds)) {
+          const platform = PLATFORMS.find((candidate) => candidate.id === platformId);
+          if (!platform || platform.id === 'codex') continue;
+          await copyGeneratedToolDirectory(
+            stagingProject,
+            source,
+            projectPath,
+            path.join(projectPath, getPlatformSkillsDir(platform, 'project')),
+            projectMutationGuard,
+          );
+        }
+      }
+    }
+  }
 }
 
 const ALL_WORKFLOWS_CONFIG =
@@ -708,6 +732,7 @@ async function installOpenSpec(
   projectMutationGuard?: ProjectMutationGuard,
   failureObserver?: OpenSpecFailureObserver,
   mirrorCodeBuddyPlatformIds: string[] = [],
+  mirrorCodexPlatformIds: string[] = [],
 ): Promise<'installed' | 'failed' | 'skipped'> {
   if (scope === 'project') {
     try {
@@ -783,6 +808,7 @@ async function installOpenSpec(
           mirrorOpenCodePlatformIds,
           mirrorCodeBuddyPlatformIds,
           projectMutationGuard,
+          mirrorCodexPlatformIds,
         );
       }
       await assertProjectMutationAllowed(projectMutationGuard, 'after-external', true);
@@ -819,6 +845,15 @@ async function installOpenSpec(
       }
     }
 
+    if (scope === 'global' && mirrorCodexPlatformIds.length > 0 && toolIds.includes('codex')) {
+      mirrorOpenCodeCompatibleOpenSpecPathsFromSource(
+        openspecTargetBase,
+        scope,
+        'codex',
+        mirrorCodexPlatformIds,
+      );
+    }
+
     if (openspecWritesGlobal && toolIds.includes('opencode')) {
       migrateOpenCodeOpenSpecPaths(os.homedir());
     }

domains/integrations/superpowers.ts

@@ -18,8 +18,8 @@ const SKILLS_AGENT_MAP: Record<string, string | null> = {
   continue: 'continue',
   'github-copilot': 'github-copilot',
   gemini: 'gemini-cli',
-  // Grok reads Superpowers from the shared .agents root that Codex owns.
-  grok: 'codex',
+  // Grok has no Skills CLI agent; stage through Claude and copy into .grok/skills.
+  grok: null,
   'amazon-q': 'universal',
   qwen: 'qwen-code',
   kilocode: 'kilo',
@@ -57,6 +57,7 @@ const LINGMA_PLATFORM_ID = 'lingma';
 const ZCODE_PLATFORM_ID = 'zcode';
 const MIMOCODE_PLATFORM_ID = 'mimocode';
 const WORKBUDDY_PLATFORM_ID = 'workbuddy';
+const GROK_PLATFORM_ID = 'grok';
 const STAGE_AGENT = 'claude-code';
 
 function buildSuperpowersInstallCommand(
@@ -117,6 +118,13 @@ function buildWorkBuddySuperpowersStageCommand(): { command: string; args: strin
   };
 }
 
+function buildGrokSuperpowersStageCommand(): { command: string; args: string[] } {
+  return {
+    command: getNpxExecutable(),
+    args: ['skills', 'add', 'obra/superpowers', '-y', '--agent', STAGE_AGENT],
+  };
+}
+
 function getNpxExecutable(platform: NodeJS.Platform = process.platform): string {
   return platform === 'win32' ? 'npx.cmd' : 'npx';
 }
@@ -185,6 +193,19 @@ async function installSuperpowersForWorkBuddy(
   );
 }
 
+async function installSuperpowersForGrok(
+  projectPath: string,
+  scope: InstallScope,
+): Promise<'installed' | 'failed'> {
+  return stageAndCopySuperpowers(
+    GROK_PLATFORM_ID,
+    buildGrokSuperpowersStageCommand(),
+    projectPath,
+    scope,
+    'Grok',
+  );
+}
+
 /**
  * Shared staging flow for platforms whose agent is not supported by the skills CLI
  * (e.g. Lingma, WorkBuddy, ZCode, MimoCode). Superpowers are staged into a temp dir via
@@ -246,6 +267,7 @@ async function installSuperpowersForPlatforms(
   const shouldInstallZCode = platformIds.includes(ZCODE_PLATFORM_ID);
   const shouldInstallMimoCode = platformIds.includes(MIMOCODE_PLATFORM_ID);
   const shouldInstallWorkBuddy = platformIds.includes(WORKBUDDY_PLATFORM_ID);
+  const shouldInstallGrok = platformIds.includes(GROK_PLATFORM_ID);
   let failed = false;
 
   if (skillsCliPlatformIds.length > 0) {
@@ -285,6 +307,11 @@ async function installSuperpowersForPlatforms(
     if (workbuddyStatus === 'failed') failed = true;
   }
 
+  if (shouldInstallGrok) {
+    const grokStatus = await installSuperpowersForGrok(projectPath, scope);
+    if (grokStatus === 'failed') failed = true;
+  }
+
   return failed ? 'failed' : 'installed';
 }
 
@@ -295,5 +322,6 @@ export {
   buildZCodeSuperpowersStageCommand,
   buildMimoCodeSuperpowersStageCommand,
   buildWorkBuddySuperpowersStageCommand,
+  buildGrokSuperpowersStageCommand,
   SKILLS_AGENT_MAP,
 };

domains/skill/platform-inspect.ts

@@ -12,7 +12,7 @@ import {
   computeRuleDestPath,
   isManagedHookCommand,
   readManifest,
-  resolveClaudeCodeHookMatcher,
+  resolveInstalledHookMatcher,
 } from './platform-install.js';
 import { readJsonObjectFile } from './json-object.js';
 import type { InitWorkflowSelection } from '../comet-entry/types.js';
@@ -395,7 +395,7 @@ export async function inspectCometHooksForPlatform(
         (config) => collectGroupedCommands(config, 'PreToolUse'),
         (config, expected) =>
           countGroupedHookMatches(config, 'PreToolUse', expected, (matcher) =>
-            resolveClaudeCodeHookMatcher(platform.id, matcher),
+            resolveInstalledHookMatcher(platform, matcher),
           ),
       );
       for (const legacyFile of platform.legacyHookConfigFiles ?? []) {
@@ -405,7 +405,7 @@ export async function inspectCometHooksForPlatform(
           (config) => collectGroupedCommands(config, 'PreToolUse'),
           (config, expected) =>
             countGroupedHookMatches(config, 'PreToolUse', expected, (matcher) =>
-              resolveClaudeCodeHookMatcher(platform.id, matcher),
+              resolveInstalledHookMatcher(platform, matcher),
             ),
         );
         if (legacy.error) {

domains/skill/platform-install.ts

@@ -71,6 +71,7 @@ const RETIRED_COMET_OWNED_SKILL_PATHS = [
 interface HookCommandContext {
   platformId: string;
   scope: InstallScope;
+  hookMatcher?: string;
 }
 
 type HookInstallStatus = 'installed' | 'skipped' | 'failed';
@@ -1134,7 +1135,7 @@ async function installCometHooksForPlatform(
           hooksConfig,
           platform.hookConfigFile ?? 'settings.local.json',
           platform.name,
-          { platformId: platform.id, scope },
+          { platformId: platform.id, scope, hookMatcher: platform.hookMatcher },
         );
         if (result.status === 'installed') {
           const failedLegacyFiles: string[] = [];
@@ -1168,7 +1169,7 @@ async function installCometHooksForPlatform(
           skillsDir,
           hooksConfig,
           platform.name,
-          { platformId: platform.id, scope },
+          { platformId: platform.id, scope, hookMatcher: platform.hookMatcher },
         );
       case 'gemini':
         return await installGeminiHooks(
@@ -1177,7 +1178,7 @@ async function installCometHooksForPlatform(
           skillsDir,
           hooksConfig,
           platform.name,
-          { platformId: platform.id, scope },
+          { platformId: platform.id, scope, hookMatcher: platform.hookMatcher },
         );
       case 'windsurf':
         return await installWindsurfHooks(
@@ -1186,7 +1187,7 @@ async function installCometHooksForPlatform(
           skillsDir,
           hooksConfig,
           platform.name,
-          { platformId: platform.id, scope },
+          { platformId: platform.id, scope, hookMatcher: platform.hookMatcher },
         );
       case 'copilot':
         return await installCopilotHooks(baseDir, platformBase, skillsDir, hooksConfig, {
@@ -1205,7 +1206,7 @@ async function installCometHooksForPlatform(
           skillsDir,
           hooksConfig,
           platform.name,
-          { platformId: platform.id, scope },
+          { platformId: platform.id, scope, hookMatcher: platform.hookMatcher },
         );
       default:
         return { status: 'failed', reason: `unsupported hook format: ${hookFormat}` };
@@ -1451,12 +1452,11 @@ async function readSettingsJsonObject(
   });
 }
 
-/** Grok aliases Write/Edit to search_replace, but its native write tool is a separate name. */
-function resolveClaudeCodeHookMatcher(platformId: string, matcher: string): string {
-  if (platformId === 'grok' && matcher === 'Write|Edit') {
-    return 'Write|Edit|write|search_replace';
-  }
-  return matcher;
+function resolveInstalledHookMatcher(
+  platform: Pick<Platform, 'hookMatcher'>,
+  matcher: string,
+): string {
+  return platform.hookMatcher ?? matcher;
 }
 
 /**
@@ -1484,7 +1484,7 @@ async function installClaudeCodeHooks(
   const matcherGroups: Record<string, Array<{ type: string; command: string }>> = {};
   for (const [scriptRelPath, config] of Object.entries(hooksConfig)) {
     const command = buildHookCommand(baseDir, skillsDir, scriptRelPath, context);
-    const matcher = resolveClaudeCodeHookMatcher(context.platformId, config.matcher);
+    const matcher = resolveInstalledHookMatcher(context, config.matcher);
     if (!matcherGroups[matcher]) {
       matcherGroups[matcher] = [];
     }
@@ -2143,7 +2143,7 @@ export {
   computeRuleDestPath,
   formatRuleContent,
   isManagedHookCommand,
-  resolveClaudeCodeHookMatcher,
+  resolveInstalledHookMatcher,
   removeManagedCopilotHookEntries,
   buildHookCommand,
   removeManagedHooksFromJsonFile,

platform/install/platforms.ts

@@ -44,6 +44,8 @@ export interface Platform {
   hookConfigFile?: string;
   /** Historical hook config filenames checked during migration and uninstall. */
   legacyHookConfigFiles?: string[];
+  /** Installed PreToolUse matcher when it differs from the portable hook descriptor. */
+  hookMatcher?: string;
 }
 
 const PLATFORM_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -191,22 +193,17 @@ export const PLATFORMS: Platform[] = [
   {
     id: 'grok',
     name: 'Grok',
-    // Project Skills share Codex's .agents root; Grok also scans that directory.
-    // Global Skills and all Grok-owned config live under .grok.
-    skillsDir: '.agents',
+    skillsDir: '.grok',
     globalSkillsDir: '.grok',
-    configDir: '.grok',
-    globalConfigDir: '.grok',
     detectionPaths: ['.grok'],
-    // OpenSpec has no grok tool; reuse Codex so Classic skills land in .agents.
+    // OpenSpec has no grok tool; generate Codex output and mirror it into .grok.
     openspecToolId: 'codex',
-    openspecSkillsDir: '.agents',
-    rulesBaseDir: '.grok',
     rulesDir: 'rules',
     rulesFormat: 'md',
     supportsHooks: true,
     hookFormat: 'claude-code',
     hookConfigFile: 'hooks/comet.json',
+    hookMatcher: 'Write|Edit|write|search_replace',
   },
   {
     id: 'amazon-q',