@skillsmith/core 0.12.1 → 0.12.3

package/dist/src/services/SubagentGenerator.client-profiles.js

@@ -0,0 +1,260 @@
+/**
+ * SMI-6276 (Wave 6 Step 1): per-client generation profile for companion
+ * subagent files (`SubagentGenerator.ts`).
+ *
+ * `SubagentGenerator.generateSubagentContent()` predates multi-client support
+ * entirely — it always emitted Claude-native tool names (`Read, Write, Bash,
+ * WebFetch, Grep, Glob, WebSearch`) plus a `model: <haiku|sonnet|opus>`
+ * frontmatter field, for every client `COMPANION_AGENT_TARGETS`
+ * (`../install/paths.ts`) writes a companion-agent file for — including
+ * clients whose own agent-definition format doesn't have a `tools:` or
+ * `model:` concept, has one with entirely different value semantics, or (a
+ * real, spec-documented failure mode for AntiGravity specifically — see
+ * below) can HANG the subagent process on an unmapped tool name.
+ *
+ * This module is the exhaustive per-client answer, keyed on `ClientId`
+ * (matching `COMPANION_AGENT_TARGETS`'s own key set, not the narrower
+ * `HarnessId` — every `ClientId` gets a companion-agent file written
+ * somewhere per `COMPANION_AGENT_TARGETS`, so every one needs a content
+ * decision here too). For each client:
+ *
+ * 1. Which frontmatter fields it accepts (`includeSkillsField`,
+ *    `toolsPolicy`, `modelPolicy`, `extraFrontmatterLines`).
+ * 2. Its tool-identifier vocabulary and value SHAPE — `'claude-native'`
+ *    (Skillsmith's internal tool names ARE that client's own names, emitted
+ *    as a comma-separated scalar, no translation needed), `'mapped-array'`
+ *    (the client has its OWN, confirmed-different tool vocabulary AND
+ *    expects a YAML array rather than a scalar — translate through
+ *    `toolNameMap`, silently drop any internal name with no confirmed
+ *    mapping, and omit the field entirely if nothing maps), or `'omit'`
+ *    (vocabulary not independently verified at all — never emit the field
+ *    rather than guess a wrong value).
+ * 3. Its model-selection policy — `'claude-enum'` (accepts Claude's
+ *    `haiku|sonnet|opus` values directly) or `'omit'` (either no `model:`
+ *    concept at all, or one with value semantics that don't line up with
+ *    Skillsmith's internal enum — including a DIFFERENT PROVIDER's own
+ *    model-tier vocabulary, which is a family swap, not just a renaming).
+ *
+ * Confidence levels (style follows `../install/agent-harness-targets.ts`'s
+ * own header — HIGH/MEDIUM/LOW per client, dated citation, never asserted
+ * past what the citation actually supports):
+ *
+ * - **claude-code** — HIGH. Claude Code's own native subagent format
+ *   (`.claude/agents/*.md`): `name`, `description`, `tools` (comma-separated
+ *   Claude tool names), `model`. This is this repo's pre-existing behavior
+ *   (unchanged by this wave) and matches `renderClaudeShim()`
+ *   (`agent-pack/shims.ts`), which uses the identical `name`/`description`/
+ *   `tools` frontmatter shape for the fixed named-agent shim.
+ * - **cursor** — HIGH, verified live against cursor.com/docs/subagents
+ *   (fetched 2026-08-30): "Cursor recognizes subagent files across multiple
+ *   directory formats: `.cursor/agents/` (Cursor format), `.claude/agents/`
+ *   (Claude compatibility), `.codex/agents/` (Codex compatibility)."
+ *   `COMPANION_AGENT_TARGETS.cursor` resolves to the SAME path as
+ *   `claude-code` (`~/.claude/agents/<name>-specialist.md` — see that
+ *   table's own comment: "Cursor 2.4+ reads `.claude/agents/` natively — no
+ *   separate shim file"), so the file this generator actually writes for
+ *   `--client cursor` is read by Cursor through that Claude-compatibility
+ *   path and must carry genuine Claude-format frontmatter — this profile
+ *   mirrors `claude-code`'s exactly (same object, not a coincidental
+ *   duplicate). Cursor's OWN native `.cursor/agents/*.md` format is verified
+ *   DIFFERENT (fields: `name`, `description`, `model` — values `inherit`,
+ *   `fast`, or a hardcoded model ID, NOT Claude's `haiku|sonnet|opus` enum —
+ *   `readonly`, `is_background`; explicitly NO `tools` field: "Subagents
+ *   inherit all tools from the parent, including MCP tools from configured
+ *   servers") but Skillsmith never writes to that native directory (no
+ *   `.cursor/agents/` entry exists in `COMPANION_AGENT_TARGETS`), so that
+ *   narrower native schema does not govern the file this generator produces.
+ * - **antigravity** — HIGH for the schema itself, verified live against
+ *   `antigravity.google/docs/subagents/` (fetched 2026-08-30, cross-checked
+ *   by an independent WebSearch and by Wayback snapshots bracketing
+ *   2026-08-06 through 2026-08-16 — see
+ *   `docs/internal/implementation/smi-6276-subagent-true-antigravity-repro.md`
+ *   for the full investigation, filed for the separate `subagent: true`
+ *   question but covering this same schema). **Correction of SMI-5982's
+ *   original sourcing**: that wave cited
+ *   `antigravity.google/docs/cli/commands/agents` (the CLI `/agents` TUI
+ *   command reference, whose example happens to show only `name`+
+ *   `description`) as if it were the full schema. The real, richer schema
+ *   lives at `/docs/subagents`: `name`, `description` (both required),
+ *   `tools` (`string[]`, default `[]` — a YAML ARRAY, not a scalar, of
+ *   AntiGravity's OWN tool names, e.g. `view_file`, `replace_file_content`,
+ *   `grep_search`, `run_command` — confirmed DIFFERENT from Skillsmith's
+ *   Claude-style names), `mainAgent`/`subagent` (booleans, both default
+ *   `true` — the `subagent: true` question is Step 2's separate scope, not
+ *   touched here), `model` (`inherit|flash|pro`, default `inherit` — NOT
+ *   Claude's `haiku|sonnet|opus`), `commandExecutionPolicy`, `mcpServers`,
+ *   `skills`/`plugins` (skill PATHS like `skills/my-helper-skill` — a
+ *   DIFFERENT concept from Skillsmith's own `skills: <bare-name>` extension
+ *   field below, not reused here for that reason).
+ *
+ *   MEDIUM for the specific tool-name MAPPING used here: the docs page only
+ *   gives 4 example tool names (not a complete enumeration), so
+ *   `toolNameMap` below covers only those 4, mapped by clear name
+ *   correspondence (`view_file`→Read, `replace_file_content`→Write/Edit,
+ *   `grep_search`→Grep, `run_command`→Bash); Skillsmith's `Glob`, `WebFetch`,
+ *   and `WebSearch` have no confirmed AntiGravity equivalent and are
+ *   silently dropped, never guessed. This is deliberately a `'mapped-array'`
+ *   policy rather than `'omit'`, unlike every other unverified-vocabulary
+ *   client in this table: AntiGravity's own schema documents `tools`
+ *   defaulting to `[]` (empty) when omitted — the OPPOSITE of Cursor's
+ *   "inherits from parent" or Copilot's "all tools available" defaults — so
+ *   omitting the field here would ship a companion subagent with literally
+ *   ZERO tool access, not a harmlessly-permissive default. A confidently-cited
+ *   partial mapping is more correct than that, and strictly safer than
+ *   guessing at unconfirmed names: the same docs page's own "Known Issue
+ *   (Tool Validation)" warns that "specifying an unmapped or misspelled tool
+ *   name in the `tools` list may cause the subagent process to hang during
+ *   execution" — every name emitted here is a name AntiGravity's own docs
+ *   use as a worked example, never an invented one.
+ *
+ *   `model:` is OMITTED for AntiGravity, not mapped — deliberately, not for
+ *   lack of trying. AntiGravity's `flash`/`pro` are Gemini model tiers;
+ *   Skillsmith's `haiku`/`sonnet`/`opus` are Claude model tiers. These are
+ *   two DIFFERENT model families from two different vendors, not two
+ *   spellings of the same capability scale — `haiku→flash` and `opus→pro`
+ *   are plausible analogies, but `sonnet` (Skillsmith's own default "for
+ *   balanced workloads", `determineModel()`) has no principled third rung to
+ *   land on in a 2-tier scale, and no official source equates any Claude
+ *   tier to any Gemini tier. Omitting the field uses AntiGravity's own
+ *   documented default (`inherit` — defer to whatever tier the invoking
+ *   session already uses), which is a real, working, spec-sanctioned value,
+ *   not an absence of a decision.
+ * - **copilot** — MEDIUM, verified live against GitHub's own docs
+ *   (docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents,
+ *   fetched 2026-08-30): `.agent.md` frontmatter DOES support a `tools` list
+ *   (documented examples: `"read"`, `"edit"`, `"search"`) and a `model`
+ *   field. NOT verified: a full mapping from Skillsmith's own 8-tool
+ *   vocabulary (`Read`/`Write`/`Edit`/`Bash`/`Grep`/`Glob`/`WebFetch`/
+ *   `WebSearch`) onto Copilot's identifier set — only 2-3 of the 8 have a
+ *   plausible lowercase counterpart in the documented examples, with no
+ *   confirmed equivalents for `Bash`/`Grep`/`Glob`/`WebFetch` specifically.
+ *   Unlike AntiGravity, Copilot's own docs confirm omission is SAFE here —
+ *   "Omitting tools grants access to all available tools — the default is
+ *   permissive" — so, per this wave's fallback rule, omit `tools:` rather
+ *   than emit a guessed-wrong partial mapping; the omission doesn't cripple
+ *   the subagent the way it would for AntiGravity. `model:` is likewise
+ *   omitted — its value format (Copilot's own model catalog IDs) has no
+ *   confirmed correspondence to Skillsmith's internal `haiku|sonnet|opus`
+ *   abstraction.
+ * - **opencode** — MEDIUM, verified live against opencode.ai/v2/docs/agents/
+ *   (fetched 2026-08-30): confirmed frontmatter fields `description`, `mode`
+ *   (`primary|subagent|all`), `model` (`provider/model#variant` format — NOT
+ *   Claude's `haiku|sonnet|opus` enum), `color`, `steps`, `permissions`. This
+ *   repo's own `renderOpenCodeShim()` (`agent-pack/shims.ts`) already
+ *   documents the load-bearing fact this profile reuses: "OpenCode's
+ *   frontmatter `tools` field is a permission map, not a plain list; setting
+ *   it wrong would restrict tools rather than reference them" — same
+ *   precedent applied here, omitting `tools:` rather than writing a
+ *   Claude-shaped value into a boolean-permission-map field (a different,
+ *   harder mapping problem than AntiGravity's plain array — not attempted in
+ *   this wave). `mode: subagent` IS included (HIGH confidence for this one
+ *   line specifically — mirrors the already-shipped `renderOpenCodeShim()`
+ *   verbatim). `model:` omitted — no confirmed mapping from Skillsmith's
+ *   internal enum to OpenCode's `provider/model` format.
+ * - **windsurf** — LOW. No independently confirmed per-subagent-file
+ *   frontmatter schema for tool/model restriction was found; Windsurf's
+ *   Cascade agent runtime is additionally documented as being retired (EOL
+ *   2026-07-01, superseded by Devin Local). Omit `tools:` and `model:`,
+ *   matching this table's existing conservative default for windsurf
+ *   (`COMPANION_AGENT_TARGETS.windsurf`'s own comment: "No
+ *   `AGENT_SHIM_TARGETS` entry exists for windsurf ... defaults to today's
+ *   actual behavior" — that comment covers the file PATH only; this module
+ *   makes the equivalent conservative call for the file's CONTENT).
+ * - **agents** — LOW. This `ClientId` is the generic cross-agent /
+ *   `AGENTS.md` convention (also Codex's install target — "Codex: reads
+ *   ONLY `~/.agents/skills`", `../install/paths.ts`'s own header comment).
+ *   The `AGENTS.md` standard itself has no required fields and no YAML
+ *   frontmatter for its single project-instructions file (openai/codex's own
+ *   `AGENTS.md`; agents.md spec) — there is no confirmed per-agent-definition
+ *   file schema with tool/model fields for this identifier at all. Omit
+ *   `tools:` and `model:`.
+ * - **hermes** — LOW. Hermes's own documented frontmatter
+ *   (hermes-agent.nousresearch.com/docs/) is for SKILL files (`name`,
+ *   `description`, `version`, `author`, `platforms`), not a separate
+ *   subagent-definition schema with tool/model restriction fields. Omit
+ *   `tools:` and `model:`.
+ * - **grok** — LOW. Grok Build (docs.x.ai/build/overview,
+ *   github.com/xai-org/grok-build) confirms agent frontmatter EXISTS
+ *   ("Subagents can declare their own `mcpServers` in agent frontmatter") but
+ *   no built-in tool-identifier vocabulary or Claude-comparable model enum is
+ *   documented. Omit `tools:` and `model:`.
+ *
+ * @see docs/internal/implementation/cursor-antigravity-tier-parity-plan.md (Wave 6 Step 1)
+ * @see docs/internal/implementation/smi-6276-subagent-true-antigravity-repro.md (AntiGravity schema source-of-truth)
+ */
+import { CANONICAL_CLIENT } from '../install/paths.js';
+/** claude-code's own native format — this generator's pre-existing (unchanged) behavior. */
+const CLAUDE_FORMAT_PROFILE = {
+    confidence: 'HIGH',
+    citation: "Claude Code's native `.claude/agents/*.md` subagent format (name/description/tools/model) — this repo's pre-existing behavior; matches renderClaudeShim() (agent-pack/shims.ts).",
+    includeSkillsField: true,
+    toolsPolicy: 'claude-native',
+    modelPolicy: 'claude-enum',
+    extraFrontmatterLines: [],
+};
+/** Minimal name+description-only shape shared by every unverified-vocabulary client. */
+function minimalProfile(confidence, citation, extraFrontmatterLines = []) {
+    return {
+        confidence,
+        citation,
+        includeSkillsField: false,
+        toolsPolicy: 'omit',
+        modelPolicy: 'omit',
+        extraFrontmatterLines,
+    };
+}
+/**
+ * AntiGravity's own tool vocabulary (antigravity.google/docs/subagents/,
+ * fetched 2026-08-30) — only the 4 names the docs page itself uses as
+ * worked examples. See module header for why this is `'mapped-array'`
+ * rather than `'omit'` (AntiGravity's own `tools` default is `[]`, not
+ * permissive) and why `Glob`/`WebFetch`/`WebSearch` have no entry.
+ */
+const ANTIGRAVITY_TOOL_NAME_MAP = {
+    Read: 'view_file',
+    Write: 'replace_file_content',
+    Edit: 'replace_file_content',
+    Bash: 'run_command',
+    Grep: 'grep_search',
+};
+export const SUBAGENT_CLIENT_PROFILES = {
+    'claude-code': CLAUDE_FORMAT_PROFILE,
+    // Mirrors claude-code exactly: COMPANION_AGENT_TARGETS.cursor writes into
+    // the SAME `~/.claude/agents/<name>-specialist.md` path, and Cursor reads
+    // that directory as a documented Claude-compatibility surface (see module
+    // header). This is a deliberate object reuse, not accidental sharing.
+    cursor: CLAUDE_FORMAT_PROFILE,
+    antigravity: {
+        confidence: 'HIGH',
+        citation: 'antigravity.google/docs/subagents/ (fetched 2026-08-30, cross-checked via independent WebSearch + Wayback bracketing 2026-08-06..2026-08-16; see smi-6276-subagent-true-antigravity-repro.md): tools is a YAML array of AntiGravity-own names defaulting to [] when omitted; model is inherit|flash|pro (a different vendor/model family from Claude — omitted rather than force-mapped).',
+        includeSkillsField: false,
+        toolsPolicy: 'mapped-array',
+        toolNameMap: ANTIGRAVITY_TOOL_NAME_MAP,
+        modelPolicy: 'omit',
+        extraFrontmatterLines: [],
+    },
+    copilot: minimalProfile('MEDIUM', "docs.github.com custom-agents docs (fetched 2026-08-30): tools/model fields exist and omitting tools is documented as permissive ('all tools available') — safe to omit rather than guess the full Skillsmith-tool-name mapping."),
+    opencode: minimalProfile('MEDIUM', "opencode.ai/v2/docs/agents/ (fetched 2026-08-30) + this repo's own renderOpenCodeShim(): tools is a boolean permission map, not a list — omit rather than mis-shape it. mode: subagent is HIGH-confidence and included.", ['mode: subagent']),
+    windsurf: minimalProfile('LOW', 'No confirmed per-subagent-file tools/model schema found; Cascade is documented as being retired (EOL 2026-07-01).'),
+    agents: minimalProfile('LOW', 'The generic AGENTS.md convention has no required fields and no confirmed per-agent-definition-file schema at all.'),
+    hermes: minimalProfile('LOW', 'hermes-agent.nousresearch.com/docs/: documented frontmatter is for SKILL files (name/description/version/author/platforms), not a subagent tools/model schema.'),
+    grok: minimalProfile('LOW', 'docs.x.ai/build/overview + xai-org/grok-build: agent frontmatter exists but no built-in tool-identifier vocabulary or Claude-comparable model enum is documented.'),
+};
+/** Resolve the per-client generation profile for `client` (default: canonical / claude-code). */
+export function getSubagentGenerationProfile(client = CANONICAL_CLIENT) {
+    return SUBAGENT_CLIENT_PROFILES[client];
+}
+/**
+ * Translate Skillsmith-internal tool names through `profile.toolNameMap`,
+ * dropping any name with no confirmed entry and de-duplicating the result
+ * (two internal names can map to the same client tool, e.g. AntiGravity's
+ * `Write`/`Edit` -> `replace_file_content`). Returns `[]` when nothing maps
+ * — callers must omit the `tools:` field entirely in that case, not emit an
+ * empty array, per this module's own fallback philosophy.
+ */
+export function mapToolNames(tools, profile) {
+    const map = profile.toolNameMap ?? {};
+    const mapped = tools.map((tool) => map[tool]).filter((tool) => tool !== undefined);
+    return Array.from(new Set(mapped));
+}
+//# sourceMappingURL=SubagentGenerator.client-profiles.js.map

package/dist/src/services/SubagentGenerator.client-profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubagentGenerator.client-profiles.js","sourceRoot":"","sources":["../../../src/services/SubagentGenerator.client-profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuLG;AAEH,OAAO,EAAE,gBAAgB,EAAiB,MAAM,qBAAqB,CAAA;AAiErE,4FAA4F;AAC5F,MAAM,qBAAqB,GAA8B;IACvD,UAAU,EAAE,MAAM;IAClB,QAAQ,EACN,kLAAkL;IACpL,kBAAkB,EAAE,IAAI;IACxB,WAAW,EAAE,eAAe;IAC5B,WAAW,EAAE,aAAa;IAC1B,qBAAqB,EAAE,EAAE;CAC1B,CAAA;AAED,wFAAwF;AACxF,SAAS,cAAc,CACrB,UAAmD,EACnD,QAAgB,EAChB,wBAA2C,EAAE;IAE7C,OAAO;QACL,UAAU;QACV,QAAQ;QACR,kBAAkB,EAAE,KAAK;QACzB,WAAW,EAAE,MAAM;QACnB,WAAW,EAAE,MAAM;QACnB,qBAAqB;KACtB,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,yBAAyB,GAAqC;IAClE,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,sBAAsB;IAC7B,IAAI,EAAE,sBAAsB;IAC5B,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,aAAa;CACpB,CAAA;AAED,MAAM,CAAC,MAAM,wBAAwB,GAA0D;IAC7F,aAAa,EAAE,qBAAqB;IACpC,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,EAAE,qBAAqB;IAC7B,WAAW,EAAE;QACX,UAAU,EAAE,MAAM;QAClB,QAAQ,EACN,2XAA2X;QAC7X,kBAAkB,EAAE,KAAK;QACzB,WAAW,EAAE,cAAc;QAC3B,WAAW,EAAE,yBAAyB;QACtC,WAAW,EAAE,MAAM;QACnB,qBAAqB,EAAE,EAAE;KAC1B;IACD,OAAO,EAAE,cAAc,CACrB,QAAQ,EACR,kOAAkO,CACnO;IACD,QAAQ,EAAE,cAAc,CACtB,QAAQ,EACR,yNAAyN,EACzN,CAAC,gBAAgB,CAAC,CACnB;IACD,QAAQ,EAAE,cAAc,CACtB,KAAK,EACL,mHAAmH,CACpH;IACD,MAAM,EAAE,cAAc,CACpB,KAAK,EACL,mHAAmH,CACpH;IACD,MAAM,EAAE,cAAc,CACpB,KAAK,EACL,gKAAgK,CACjK;IACD,IAAI,EAAE,cAAc,CAClB,KAAK,EACL,mKAAmK,CACpK;CACF,CAAA;AAED,iGAAiG;AACjG,MAAM,UAAU,4BAA4B,CAC1C,SAAmB,gBAAgB;IAEnC,OAAO,wBAAwB,CAAC,MAAM,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAwB,EACxB,OAAkC;IAElC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAA;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAA;IAClG,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;AACpC,CAAC"}

package/dist/src/services/SubagentGenerator.d.ts

@@ -9,47 +9,19 @@
  *
  * Part of the Skillsmith Optimization Layer for transforming
  * community skills into more performant versions.
+ *
+ * SMI-6276 (Wave 6 Step 1): companion-agent frontmatter is now generated
+ * per TARGET CLIENT via `SubagentGenerator.client-profiles.ts` — this file
+ * no longer emits Claude-native tool names / a Claude `model:` value
+ * unconditionally for every client `COMPANION_AGENT_TARGETS` writes a
+ * companion file for. Types split to `.types.ts`, pure helpers split to
+ * `.helpers.ts` (500-line standard).
  */
+export type { ClaudeModel, SubagentDefinition, SubagentGenerationResult, } from './SubagentGenerator.types.js';
+export { CLAUDE_MODELS } from './SubagentGenerator.types.js';
 import type { SkillAnalysis } from './SkillAnalyzer.js';
-/**
- * SMI-1795: Claude model constants for type safety and consistency
- */
-export declare const CLAUDE_MODELS: {
-    readonly HAIKU: "haiku";
-    readonly SONNET: "sonnet";
-    readonly OPUS: "opus";
-};
-export type ClaudeModel = (typeof CLAUDE_MODELS)[keyof typeof CLAUDE_MODELS];
-/**
- * Generated subagent definition
- */
-export interface SubagentDefinition {
-    /** Subagent name (e.g., "jest-helper-specialist") */
-    name: string;
-    /** Description for the Task tool */
-    description: string;
-    /** Trigger phrases that should invoke this subagent */
-    triggerPhrases: string[];
-    /** Tools the subagent needs access to */
-    tools: string[];
-    /** Recommended model */
-    model: ClaudeModel;
-    /** The full markdown content for ~/.claude/agents/ */
-    content: string;
-}
-/**
- * Result of subagent generation
- */
-export interface SubagentGenerationResult {
-    /** Whether a subagent was generated */
-    generated: boolean;
-    /** The subagent definition (if generated) */
-    subagent?: SubagentDefinition;
-    /** Reason if not generated */
-    reason?: string;
-    /** CLAUDE.md integration snippet */
-    claudeMdSnippet?: string;
-}
+import { type ClientId } from '../install/paths.js';
+import { type SubagentGenerationResult } from './SubagentGenerator.types.js';
 /**
  * Generate a companion subagent for a skill
  *
@@ -57,18 +29,24 @@ export interface SubagentGenerationResult {
  * @param description - The skill's description
  * @param content - The full SKILL.md content
  * @param analysis - Analysis from SkillAnalyzer
+ * @param client - SMI-6276: target client for the generated companion-agent
+ *   frontmatter shape (default: canonical / `claude-code`, preserving prior
+ *   behavior for every existing caller). See `SubagentGenerator.client-profiles.ts`.
  * @returns Subagent generation result
  */
-export declare function generateSubagent(skillName: string, description: string, content: string, analysis: SkillAnalysis): SubagentGenerationResult;
+export declare function generateSubagent(skillName: string, description: string, content: string, analysis: SkillAnalysis, client?: ClientId): SubagentGenerationResult;
 /**
  * Generate a minimal subagent for skills that don't need full analysis
  *
  * @param skillName - The name of the skill
  * @param description - The skill's description
  * @param content - The full SKILL.md content
+ * @param client - SMI-6276: target client for the generated companion-agent
+ *   frontmatter shape (default: canonical / `claude-code`, preserving prior
+ *   behavior for every existing caller). See `SubagentGenerator.client-profiles.ts`.
  * @returns Subagent generation result
  */
-export declare function generateMinimalSubagent(skillName: string, description: string, content: string): SubagentGenerationResult;
+export declare function generateMinimalSubagent(skillName: string, description: string, content: string, client?: ClientId): SubagentGenerationResult;
 declare const _default: {
     generateSubagent: typeof generateSubagent;
     generateMinimalSubagent: typeof generateMinimalSubagent;

package/dist/src/services/SubagentGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SubagentGenerator.d.ts","sourceRoot":"","sources":["../../../src/services/SubagentGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,oBAAoB,CAAA;AAE1E;;GAEG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAA;AAE5E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IAEZ,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAA;IAEnB,uDAAuD;IACvD,cAAc,EAAE,MAAM,EAAE,CAAA;IAExB,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAA;IAEf,wBAAwB;IACxB,KAAK,EAAE,WAAW,CAAA;IAElB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,SAAS,EAAE,OAAO,CAAA;IAElB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAE7B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAoRD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,GACtB,wBAAwB,CAmE1B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,wBAAwB,CAkD1B;;;;;AAED,wBAA4D"}
+{"version":3,"file":"SubagentGenerator.d.ts","sourceRoot":"","sources":["../../../src/services/SubagentGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAErE,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,8BAA8B,CAAA;AA0GrC;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,MAAM,GAAE,QAA2B,GAClC,wBAAwB,CAoE1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,QAA2B,GAClC,wBAAwB,CAmD1B;;;;;AAED,wBAA4D"}

package/dist/src/services/SubagentGenerator.helpers.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SMI-1788: Pure helper functions for SubagentGenerator — tool detection,
+ * trigger-phrase extraction, model selection, and Claude-tool-named
+ * guidance text. Split out under the 500-line standard (SMI-6276) following
+ * this directory's existing `.helpers.ts` convention (see
+ * SkillAnalyzer.helpers.ts / SkillDecomposer.helpers.ts).
+ */
+import type { ToolUsageAnalysis } from './SkillAnalyzer.js';
+import { type ClaudeModel } from './SubagentGenerator.types.js';
+/**
+ * Tool detection patterns for analyzing skill content
+ */
+export declare const TOOL_PATTERNS: Record<string, {
+    patterns: string[];
+    priority: number;
+}>;
+/**
+ * Minimum tools that most subagents need
+ */
+export declare const BASE_TOOLS: string[];
+/**
+ * SMI-1819: Maximum length for subagent names to prevent overly long identifiers
+ */
+export declare const MAX_SUBAGENT_NAME_LENGTH = 100;
+/**
+ * Generate tool usage guidelines for a subagent (Claude-named tools).
+ * Only used for clients whose `toolsPolicy` is `'claude-native'` — see
+ * `SubagentGenerator.client-profiles.ts` and `OMITTED_TOOLS_GUIDANCE`.
+ */
+export declare function generateToolGuidelines(tools: string[]): string;
+/**
+ * SMI-6276: fallback tool-usage guidance for any client whose companion
+ * subagent file does not carry Claude-named tools in its `tools:`
+ * frontmatter — either because the field is omitted entirely, or because it
+ * was translated into that client's OWN vocabulary (`mapped-array`, e.g.
+ * AntiGravity's `view_file`/`run_command`). Naming Claude-specific tool
+ * identifiers in this prose body would be misleading either way, so this
+ * stays generic. See `SubagentGenerator.client-profiles.ts`.
+ */
+export declare const OMITTED_TOOLS_GUIDANCE = "- Use the tools available on this platform minimally and efficiently";
+/**
+ * Generate CLAUDE.md integration snippet
+ *
+ * NOTE (SMI-6276): deliberately NOT client-parameterized — CLAUDE.md is
+ * inherently a Claude Code artifact regardless of which client the
+ * companion-agent FILE itself targets, so this always describes the
+ * Claude-side delegation recommendation. Out of this wave's scope; see
+ * `SubagentGenerator.client-profiles.ts`'s header for what IS in scope.
+ */
+export declare function generateClaudeMdSnippet(skillName: string, description: string, triggerPhrases: string[], tools: string[], model: ClaudeModel): string;
+/**
+ * Extract trigger phrases from skill description and content
+ */
+export declare function extractTriggerPhrases(description: string, content: string): string[];
+/**
+ * Determine optimal model for subagent
+ * SMI-1795: Uses CLAUDE_MODELS constants for type safety
+ */
+export declare function determineModel(toolUsage: ToolUsageAnalysis, lineCount: number): ClaudeModel;
+/**
+ * Detect tools needed from skill content
+ */
+export declare function detectTools(content: string): string[];
+//# sourceMappingURL=SubagentGenerator.helpers.d.ts.map

package/dist/src/services/SubagentGenerator.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubagentGenerator.helpers.d.ts","sourceRoot":"","sources":["../../../src/services/SubagentGenerator.helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAE9E;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAoDlF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,UAAW,CAAA;AAElC;;GAEG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CA6B9D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,yEACqC,CAAA;AAExE;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,WAAW,GACjB,MAAM,CA0BR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAwDpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAgB3F;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAcrD"}

package/dist/src/services/SubagentGenerator.helpers.js

@@ -0,0 +1,228 @@
+/**
+ * SMI-1788: Pure helper functions for SubagentGenerator — tool detection,
+ * trigger-phrase extraction, model selection, and Claude-tool-named
+ * guidance text. Split out under the 500-line standard (SMI-6276) following
+ * this directory's existing `.helpers.ts` convention (see
+ * SkillAnalyzer.helpers.ts / SkillDecomposer.helpers.ts).
+ */
+import { CLAUDE_MODELS } from './SubagentGenerator.types.js';
+/**
+ * Tool detection patterns for analyzing skill content
+ */
+export const TOOL_PATTERNS = {
+    Read: {
+        patterns: ['read file', 'read the', 'examine', 'view file', 'Read tool', 'check file'],
+        priority: 1,
+    },
+    Write: {
+        patterns: ['write file', 'create file', 'save to', 'output to', 'Write tool', 'generate file'],
+        priority: 2,
+    },
+    Edit: {
+        patterns: [
+            'edit file',
+            'modify',
+            'update file',
+            'patch',
+            'Edit tool',
+            'change file',
+            'refactor',
+        ],
+        priority: 2,
+    },
+    Bash: {
+        patterns: [
+            'bash',
+            'npm',
+            'npx',
+            'git',
+            'docker',
+            'yarn',
+            'pnpm',
+            'terminal',
+            'shell',
+            'command',
+        ],
+        priority: 3,
+    },
+    Grep: {
+        patterns: ['grep', 'search for', 'find text', 'pattern match', 'Grep tool', 'search in'],
+        priority: 1,
+    },
+    Glob: {
+        patterns: ['glob', 'find file', 'file pattern', 'list files', 'Glob tool', 'locate'],
+        priority: 1,
+    },
+    WebFetch: {
+        patterns: ['fetch', 'http', 'api call', 'url', 'WebFetch', 'download', 'request'],
+        priority: 2,
+    },
+    WebSearch: {
+        patterns: ['web search', 'search online', 'lookup online', 'WebSearch', 'search the web'],
+        priority: 2,
+    },
+};
+/**
+ * Minimum tools that most subagents need
+ */
+export const BASE_TOOLS = ['Read'];
+/**
+ * SMI-1819: Maximum length for subagent names to prevent overly long identifiers
+ */
+export const MAX_SUBAGENT_NAME_LENGTH = 100;
+/**
+ * Generate tool usage guidelines for a subagent (Claude-named tools).
+ * Only used for clients whose `toolsPolicy` is `'claude-native'` — see
+ * `SubagentGenerator.client-profiles.ts` and `OMITTED_TOOLS_GUIDANCE`.
+ */
+export function generateToolGuidelines(tools) {
+    const guidelines = [];
+    if (tools.includes('Read')) {
+        guidelines.push('- **Read**: Use to examine files before modifications');
+    }
+    if (tools.includes('Write')) {
+        guidelines.push('- **Write**: Use for creating new files only');
+    }
+    if (tools.includes('Edit')) {
+        guidelines.push('- **Edit**: Use for modifying existing files');
+    }
+    if (tools.includes('Bash')) {
+        guidelines.push('- **Bash**: Use for command execution, prefer non-destructive commands');
+    }
+    if (tools.includes('Grep')) {
+        guidelines.push('- **Grep**: Use for searching file contents');
+    }
+    if (tools.includes('Glob')) {
+        guidelines.push('- **Glob**: Use for finding files by pattern');
+    }
+    if (tools.includes('WebFetch')) {
+        guidelines.push('- **WebFetch**: Use for fetching web content');
+    }
+    if (tools.includes('WebSearch')) {
+        guidelines.push('- **WebSearch**: Use for searching the web');
+    }
+    return guidelines.length > 0 ? guidelines.join('\n') : '- Use tools minimally and efficiently';
+}
+/**
+ * SMI-6276: fallback tool-usage guidance for any client whose companion
+ * subagent file does not carry Claude-named tools in its `tools:`
+ * frontmatter — either because the field is omitted entirely, or because it
+ * was translated into that client's OWN vocabulary (`mapped-array`, e.g.
+ * AntiGravity's `view_file`/`run_command`). Naming Claude-specific tool
+ * identifiers in this prose body would be misleading either way, so this
+ * stays generic. See `SubagentGenerator.client-profiles.ts`.
+ */
+export const OMITTED_TOOLS_GUIDANCE = '- Use the tools available on this platform minimally and efficiently';
+/**
+ * Generate CLAUDE.md integration snippet
+ *
+ * NOTE (SMI-6276): deliberately NOT client-parameterized — CLAUDE.md is
+ * inherently a Claude Code artifact regardless of which client the
+ * companion-agent FILE itself targets, so this always describes the
+ * Claude-side delegation recommendation. Out of this wave's scope; see
+ * `SubagentGenerator.client-profiles.ts`'s header for what IS in scope.
+ */
+export function generateClaudeMdSnippet(skillName, description, triggerPhrases, tools, model) {
+    const triggerPatterns = triggerPhrases.length > 0
+        ? triggerPhrases.map((p) => `- "${p}"`).join('\n')
+        : '- [add trigger patterns]';
+    const exampleTask = triggerPhrases.length > 0 ? triggerPhrases[0] : `execute ${skillName} task`;
+    return `
+### Subagent Delegation: ${skillName}
+
+When tasks match ${skillName} triggers, delegate to the ${skillName}-specialist
+subagent instead of executing directly. This provides context isolation and
+~37-97% token savings.
+
+**Trigger Patterns:**
+${triggerPatterns}
+
+**Delegation Example:**
+\`\`\`
+Task("${skillName}-specialist", "${exampleTask}", "${skillName}-specialist")
+\`\`\`
+
+**Model:** ${model}
+**Tools:** ${tools.join(', ')}
+`;
+}
+/**
+ * Extract trigger phrases from skill description and content
+ */
+export function extractTriggerPhrases(description, content) {
+    const phrases = [];
+    // Common trigger phrase patterns. CodeQL finding (SMI-6276, polynomial
+    // regex / ReDoS): the original patterns paired an optional word group
+    // (e.g. `(?:you\s+)?`) directly against a lazy wildcard capture
+    // (`(.+?)`) — since `.` also matches the letters/spaces the optional
+    // group matches, the engine has exponentially many ways to split
+    // ambiguous input (long runs of repeated words/spaces) between "the
+    // optional group matched" and "the wildcard consumed it instead".
+    // `textToSearch` includes up to 2000 chars of externally-authored
+    // SKILL.md content (a real untrusted-input path in a skill registry).
+    // Fix: bound each capture group to a small fixed max length instead of
+    // an unbounded lazy wildcard — extracted phrases are truncated to <=50
+    // chars a few lines below regardless, so this changes no real-world
+    // behavior, but caps worst-case backtracking work to a small constant
+    // instead of growing with input length.
+    const MAX_CANDIDATE_PHRASE_LENGTH = 60;
+    const patterns = [
+        new RegExp(`when\\s+(?:you\\s+)?(?:need\\s+to\\s+)?([^.,]{1,${MAX_CANDIDATE_PHRASE_LENGTH}})(?:[.,]|$)`, 'gi'),
+        new RegExp(`use\\s+(?:this\\s+)?(?:when|for)\\s+([^.,]{1,${MAX_CANDIDATE_PHRASE_LENGTH}})(?:[.,]|$)`, 'gi'),
+        new RegExp(`(?:helps?\\s+(?:you\\s+)?(?:to\\s+)?)?([^\\n]{1,${MAX_CANDIDATE_PHRASE_LENGTH}}?)(?:\\s+tasks?|\\s+operations?)`, 'gi'),
+    ];
+    const textToSearch = description + ' ' + content.slice(0, 2000); // Search first 2000 chars
+    for (const pattern of patterns) {
+        for (const match of textToSearch.matchAll(pattern)) {
+            const phrase = match[1].trim().toLowerCase();
+            if (phrase.length >= 5 && phrase.length <= 50 && !phrases.includes(phrase)) {
+                phrases.push(phrase);
+            }
+        }
+    }
+    // Extract from "trigger" or "invoke" mentions
+    const triggerMatch = content.match(/trigger[s]?\s*[:=]\s*["`']([^"`']+)["`']/gi);
+    if (triggerMatch) {
+        for (const match of triggerMatch) {
+            const phrase = match.replace(/trigger[s]?\s*[:=]\s*["`']/i, '').replace(/["`']$/, '');
+            if (!phrases.includes(phrase.toLowerCase())) {
+                phrases.push(phrase.toLowerCase());
+            }
+        }
+    }
+    return phrases.slice(0, 5); // Limit to 5 phrases
+}
+/**
+ * Determine optimal model for subagent
+ * SMI-1795: Uses CLAUDE_MODELS constants for type safety
+ */
+export function determineModel(toolUsage, lineCount) {
+    // Haiku for simple, fast operations
+    if (toolUsage.detectedTools.length <= 2 && lineCount < 200) {
+        return CLAUDE_MODELS.HAIKU;
+    }
+    // Opus for complex, reasoning-heavy tasks
+    if (toolUsage.bashCommandCount > 5 ||
+        (toolUsage.fileReadCount > 3 && toolUsage.fileWriteCount > 3)) {
+        return CLAUDE_MODELS.OPUS;
+    }
+    // Sonnet for balanced workloads (default)
+    return CLAUDE_MODELS.SONNET;
+}
+/**
+ * Detect tools needed from skill content
+ */
+export function detectTools(content) {
+    const lowerContent = content.toLowerCase();
+    const detectedTools = new Set(BASE_TOOLS);
+    for (const [tool, config] of Object.entries(TOOL_PATTERNS)) {
+        for (const pattern of config.patterns) {
+            if (lowerContent.includes(pattern.toLowerCase())) {
+                detectedTools.add(tool);
+                break;
+            }
+        }
+    }
+    return Array.from(detectedTools);
+}
+//# sourceMappingURL=SubagentGenerator.helpers.js.map