@mrciphersmith/keryx 0.3.2 → 0.3.3

package/dist/core.js

@@ -8191,6 +8191,12 @@ var init_catalog = __esm(() => {
       "Ask Jev one choice question per open comment; keryx writes every word of the finding.",
       "Never post a reply or resolve a thread \u2014 the label is advisory only."
     ]),
+    skill("review-jev-contract", "review", ["recommended", "full"], "Check a PR description's own claims, and a linked flow's frozen acceptance criteria, against the diff, scored by Jev.", [
+      "Split the PR description into claims deterministically \u2014 bullets, and sentences carrying a verb cue.",
+      "Compute deterministic facts per claim first: named files/symbols/flags in the diff, tests touched, exported-symbol changes.",
+      'Ask Jev one noul per claim; a claim the facts CONTRADICT (e.g. "no API change" with an exported symbol touched) is major regardless of the answer.',
+      "Reuse flow 328's check-ac.ts (via runCheckAc) for the linked flow's frozen acceptance criteria \u2014 never reimplemented here."
+    ]),
     skill("review-logic", "review", ["recommended", "full"], "Review logic correctness, contracts, edge cases, nullability, and async behavior.", [
       "Trace behavior through call sites and affected context.",
       "Look for incorrect assumptions, missing branches, race conditions, and error paths.",
@@ -8655,6 +8661,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-frontend-conventions": 213,
     "review/review-highload": 550,
     "review/review-jev-comments": 184,
+    "review/review-jev-contract": 193,
     "review/review-jev-docs": 189,
     "review/review-jev-risk": 190,
     "review/review-jev-rules": 267,
@@ -9849,16 +9856,17 @@ function stripMutationToolsForPolicy(tools, policyProfile) {
 function mdSentinelLine(definition) {
   return `<!-- ${agentManagedSentinelText(definition)} -->`;
 }
-function renderClaudeExport(definition, header) {
+function renderClaudeExport(definition, header, options = {}) {
   const { allowed, strippedForPolicy } = stripMutationToolsForPolicy(definition.tools, definition.policy_profile);
   const { mappedTools, droppedTools } = mapToolsForTarget(allowed, "claude");
   const claudeTools = mappedTools.length > 0 ? mappedTools : CLAUDE_READ_BASELINE;
+  const modelLine = options.claudeSubagentAliases === false ? "model: inherit" : `model: ${CLAUDE_MODEL_ALIAS[definition.model_tier]}`;
   const frontmatter = [
     "---",
     `name: ${yamlDoubleQuoted(definition.name)}`,
     `description: ${yamlDoubleQuoted(definition.description)}`,
     `tools: ${yamlDoubleQuoted(claudeTools.join(", "))}`,
-    "model: inherit",
+    modelLine,
     "---"
   ].join(`
 `);
@@ -9979,9 +9987,9 @@ ${header}
     }
   };
 }
-function renderHostExport(definition, target, header) {
+function renderHostExport(definition, target, header, options = {}) {
   if (target === "claude") {
-    return { ok: true, result: renderClaudeExport(definition, header) };
+    return { ok: true, result: renderClaudeExport(definition, header, options) };
   }
   if (target === "codex") {
     return renderCodexExport(definition, header);
@@ -10023,7 +10031,7 @@ function compileAgentHeader(definition) {
   }
   return { ok: true, header: renderHeader(definition) };
 }
-function compileAgentDefinition(definition, target) {
+function compileAgentDefinition(definition, target, options = {}) {
   const headerResult = compileAgentHeader(definition);
   if (!headerResult.ok) {
     return { ok: false, error: headerResult.error };
@@ -10032,9 +10040,9 @@ function compileAgentDefinition(definition, target) {
   if (target === "keryx-shell") {
     return compileKeryxShell(definition, header);
   }
-  return renderHostExport(definition, target, header);
+  return renderHostExport(definition, target, header, options);
 }
-var KERYX_SHELL_ENFORCEMENT, BASELINE_NGRAM_WORDS = 10, BASELINE_WORDS, BASELINE_NGRAMS, AGENT_CONTENT_HASH_PLACEHOLDER, CONTENT_HASH_MARKER = "content-sha256:", MUTATION_TOOL_NAMES, CLAUDE_READ_BASELINE, KIRO_READ_BASELINE;
+var KERYX_SHELL_ENFORCEMENT, BASELINE_NGRAM_WORDS = 10, BASELINE_WORDS, BASELINE_NGRAMS, AGENT_CONTENT_HASH_PLACEHOLDER, CONTENT_HASH_MARKER = "content-sha256:", MUTATION_TOOL_NAMES, CLAUDE_READ_BASELINE, KIRO_READ_BASELINE, CLAUDE_MODEL_ALIAS;
 var init_compile = __esm(() => {
   init_baseline();
   init_schema();
@@ -10052,6 +10060,11 @@ var init_compile = __esm(() => {
   MUTATION_TOOL_NAMES = new Set(["apply_patch", "shell_exec"]);
   CLAUDE_READ_BASELINE = ["Read", "Grep", "Glob"];
   KIRO_READ_BASELINE = ["read"];
+  CLAUDE_MODEL_ALIAS = {
+    deep: "opus",
+    standard: "sonnet",
+    light: "haiku"
+  };
 });
 
 // src/agents/export.ts
@@ -10128,6 +10141,28 @@ function decideAction(existing, generated, format, expectedName) {
   }
   return { action: "update" };
 }
+async function readClaudeSubagentAliasesConfig(projectRoot) {
+  const file = path36.join(projectRoot, CLAUDE_SUBAGENT_ALIASES_CONFIG_PATH);
+  if (!await pathExists(file)) {
+    return { enabled: true };
+  }
+  const read = await readJsonObjectFile(file);
+  if (read.state !== "object") {
+    return { enabled: true, note: `${CLAUDE_SUBAGENT_ALIASES_CONFIG_PATH} could not be read as a JSON object; claude subagent aliases stayed enabled` };
+  }
+  const modelGuidance = read.value["modelGuidance"];
+  if (typeof modelGuidance !== "object" || modelGuidance === null || Array.isArray(modelGuidance)) {
+    return { enabled: true };
+  }
+  const value = modelGuidance["claudeSubagentAliases"];
+  if (value === false) {
+    return { enabled: false };
+  }
+  if (value !== undefined && value !== true) {
+    return { enabled: true, note: `${CLAUDE_SUBAGENT_ALIASES_CONFIG_PATH}: modelGuidance.claudeSubagentAliases is not a boolean; aliases stayed enabled` };
+  }
+  return { enabled: true };
+}
 async function planAgentExport(projectRoot, definition, runtime, opts = {}) {
   const supportLevel = agentExportSupport(runtime, opts.lookup);
   if (runtime === "keryx-shell") {
@@ -10194,7 +10229,8 @@ ${headerResult.header}
       ...decided.reason !== undefined ? { reason: decided.reason } : {}
     };
   }
-  const compiled = compileAgentDefinition(definition, runtime);
+  const compileOptions = runtime === "claude" ? { claudeSubagentAliases: (await readClaudeSubagentAliasesConfig(projectRoot)).enabled } : {};
+  const compiled = compileAgentDefinition(definition, runtime, compileOptions);
   if (!compiled.ok) {
     return {
       runtime,
@@ -10323,9 +10359,10 @@ var defaultAgentSupportLookup = (runtime) => {
   if (!surface)
     return;
   return matrixStateToExportLevel(classifySurfaceState(adapter, surface));
-}, PROSE_EXPORT_ROOT = ".metaproject/agents-export", HOST_AGENTS_DIR;
+}, PROSE_EXPORT_ROOT = ".metaproject/agents-export", CLAUDE_SUBAGENT_ALIASES_CONFIG_PATH = ".metaproject/tasks.config.json", HOST_AGENTS_DIR;
 var init_export2 = __esm(() => {
   init_fs();
+  init_json();
   init_contained_write();
   init_registry();
   init_matrix();
@@ -23346,6 +23383,7 @@ __export(exports_service3, {
   confirmPreconditionError: () => confirmPreconditionError,
   createFlowService: () => createFlowService,
   evaluatedVerdict: () => evaluatedVerdict,
+  extractCriterionTokens: () => extractCriterionTokens,
   factsOnlyVerdict: () => factsOnlyVerdict,
   hashDiff: () => hashDiff,
   isFrozen: () => isFrozen,
@@ -36986,7 +37024,7 @@ var HELP_GROUPS = [
     kind: "cli",
     name: "routing",
     group: "Connect a model provider",
-    summary: "Category -> model routing table (list, set, unset, trust) and the model-profile catalogue (profile list, profile set)."
+    summary: "Category -> model routing table (list, set, unset, trust), the model-profile catalogue (profile list, profile set), and real measured task cost (stats)."
   },
   { kind: "slash", name: "/connect", group: "Connect a model provider", summary: "Switch provider; row buttons test/disconnect it." },
   {
@@ -37183,12 +37221,30 @@ var HELP_GROUPS = [
     group: "Managed work",
     summary: "List open PR review comments with a Jev resolved/still-open/escalation label \u2014 /opencomments <owner/repo> <pr>."
   },
+  {
+    kind: "slash",
+    name: "/contract",
+    group: "Managed work",
+    summary: "Check PR-description claims and a linked flow's frozen acceptance criteria against the working diff, with Jev."
+  },
+  {
+    kind: "slash",
+    name: "/triage",
+    group: "Managed work",
+    summary: "Advisory annotations \u2014 severity calibration, duplicate-merge candidates, verifier queue order \u2014 over the latest review package, with Jev."
+  },
   {
     kind: "slash",
     name: "/guard",
     group: "Managed work",
     summary: "Opt-in turn guard: after a turn, checks whether the request was done and catches a reply that contradicts the tools \u2014 /guard [on|off]."
   },
+  {
+    kind: "slash",
+    name: "/route",
+    group: "Managed work",
+    summary: "Opt-in routing classifier: each request runs on its routing category's model \u2014 /route [on|off]."
+  },
   { kind: "slash", name: "/plan", group: "Managed work", summary: "Toggle read-only mode \u2014 /plan [on|off]." },
   {
     kind: "slash",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/install-manifest.json

@@ -116,6 +116,28 @@
       ],
       "stackDetectionAware": true
     },
+    "docker-k8s-terraform": {
+      "description": "Common rules plus the Docker/Kubernetes/Terraform tool pack component, installed when `keryx stack detect` finds a matching tag (docker, docker-compose, or terraform). Experimental: has not cleared the honest behavioral eval gate yet.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "tool:docker-k8s-terraform"
+      ],
+      "stackDetectionAware": true
+    },
+    "ci-github-gitlab": {
+      "description": "Common rules plus the CI (GitHub Actions & GitLab CI) tool pack component, installed when `keryx stack detect` finds a matching tag (github-actions or gitlab-ci). Experimental: has not cleared the honest behavioral eval gate yet.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "tool:ci-github-gitlab"
+      ],
+      "stackDetectionAware": true
+    },
     "full": {
       "description": "Every registered module and component, unconditionally.",
       "modules": [
@@ -146,7 +168,19 @@
         "angular-rules",
         "angular-skills",
         "nextjs-nuxt-rules",
-        "nextjs-nuxt-skills"
+        "nextjs-nuxt-skills",
+        "docker-k8s-terraform-rules",
+        "docker-k8s-terraform-skills",
+        "ci-github-gitlab-rules",
+        "ci-github-gitlab-skills",
+        "php-laravel-rules",
+        "php-laravel-skills",
+        "ruby-rails-rules",
+        "ruby-rails-skills",
+        "c-cpp-rules",
+        "c-cpp-skills",
+        "sql-db-rules",
+        "sql-db-skills"
       ],
       "components": [
         "lang:ts-js-node",
@@ -157,8 +191,58 @@
         "lang:go",
         "framework:vue",
         "framework:angular",
-        "framework:nextjs-nuxt"
+        "framework:nextjs-nuxt",
+        "tool:docker-k8s-terraform",
+        "tool:ci-github-gitlab",
+        "framework:php-laravel",
+        "framework:ruby-rails",
+        "lang:c-cpp",
+        "capability:sql-db"
       ]
+    },
+    "php-laravel": {
+      "description": "Common rules plus the PHP/Laravel stack pack component (`php-laravel-rules` + `php-laravel-skills`, from src/gdskills/bundled/stacks/php-laravel/), installed when `keryx stack detect` finds a matching tag.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "framework:php-laravel"
+      ],
+      "stackDetectionAware": true
+    },
+    "ruby-rails": {
+      "description": "Common rules plus the Ruby on Rails stack pack component (`ruby-rails-rules` + `ruby-rails-skills`, from src/gdskills/bundled/stacks/ruby-rails/), installed when `keryx stack detect` finds a matching tag.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "framework:ruby-rails"
+      ],
+      "stackDetectionAware": true
+    },
+    "c-cpp": {
+      "description": "Common rules plus the C/C++ stack pack component (`c-cpp-rules` + `c-cpp-skills`, from src/gdskills/bundled/stacks/c-cpp/), installed when `keryx stack detect` finds a matching tag.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "lang:c-cpp"
+      ],
+      "stackDetectionAware": true
+    },
+    "sql-db": {
+      "description": "Common rules plus the SQL/database stack pack component (`sql-db-rules` + `sql-db-skills`, from src/gdskills/bundled/stacks/sql-db/), installed when `keryx stack detect` finds a matching tag.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "capability:sql-db"
+      ],
+      "stackDetectionAware": true
     }
   },
   "modules": {
@@ -664,6 +748,186 @@
       "defaultInstall": true,
       "cost": "medium",
       "stability": "experimental"
+    },
+    "docker-k8s-terraform-rules": {
+      "kind": "rule",
+      "description": "Docker/Kubernetes/Terraform stack pack rules (coding-style, patterns, security, testing; scoped to Dockerfiles, compose YAML, k8s/Helm YAML, *.tf/*.tfvars) from src/gdskills/bundled/stacks/docker-k8s-terraform/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/docker-k8s-terraform/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "docker-k8s-terraform-skills": {
+      "kind": "skill",
+      "description": "Docker/Kubernetes/Terraform stack pack skills (no implement skill per W1-stack-catalog.md -- config authoring lives in the deploy quality skill; review, build-fix) from src/gdskills/bundled/stacks/docker-k8s-terraform/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/docker-k8s-terraform/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "ci-github-gitlab-rules": {
+      "kind": "rule",
+      "description": "CI (GitHub Actions & GitLab CI) stack pack rules (patterns, security; scoped to .github/workflows/*.yml and .gitlab-ci.yml only) from src/gdskills/bundled/stacks/ci-github-gitlab/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/ci-github-gitlab/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "ci-github-gitlab-skills": {
+      "kind": "skill",
+      "description": "CI (GitHub Actions & GitLab CI) stack pack skills (implementation, code review, build-fix) from src/gdskills/bundled/stacks/ci-github-gitlab/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/ci-github-gitlab/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "php-laravel-rules": {
+      "kind": "rule",
+      "description": "PHP/Laravel stack pack rules (coding-style, patterns, security, testing) from src/gdskills/bundled/stacks/php-laravel/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/php-laravel/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "php-laravel-skills": {
+      "kind": "skill",
+      "description": "PHP/Laravel stack pack skills (implementation, testing, code review, build-fix) from src/gdskills/bundled/stacks/php-laravel/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/php-laravel/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "ruby-rails-rules": {
+      "kind": "rule",
+      "description": "Ruby on Rails stack pack rules (coding-style, patterns, security, testing) from src/gdskills/bundled/stacks/ruby-rails/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/ruby-rails/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "ruby-rails-skills": {
+      "kind": "skill",
+      "description": "Ruby on Rails stack pack skills (implementation, testing, code review, build-fix) from src/gdskills/bundled/stacks/ruby-rails/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/ruby-rails/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "c-cpp-rules": {
+      "kind": "rule",
+      "description": "C/C++ stack pack rules (coding-style, patterns, security, testing) from src/gdskills/bundled/stacks/c-cpp/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/c-cpp/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "c-cpp-skills": {
+      "kind": "skill",
+      "description": "C/C++ stack pack skills (implementation, testing, code review, build-fix) from src/gdskills/bundled/stacks/c-cpp/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/c-cpp/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "sql-db-rules": {
+      "kind": "rule",
+      "description": "SQL/database stack pack rules (coding-style, patterns, security, testing) from src/gdskills/bundled/stacks/sql-db/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/sql-db/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "sql-db-skills": {
+      "kind": "skill",
+      "description": "SQL/database stack pack skills (implementation, testing, code review, build-fix) from src/gdskills/bundled/stacks/sql-db/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/sql-db/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
     }
   },
   "components": {
@@ -792,6 +1056,89 @@
       "provenance": {
         "origin": "authored"
       }
+    },
+    "tool:docker-k8s-terraform": {
+      "family": "tool",
+      "modules": [
+        "docker-k8s-terraform-rules",
+        "docker-k8s-terraform-skills"
+      ],
+      "detectionMarkers": [
+        "docker",
+        "docker-compose",
+        "terraform"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "tool:ci-github-gitlab": {
+      "family": "tool",
+      "modules": [
+        "ci-github-gitlab-rules",
+        "ci-github-gitlab-skills"
+      ],
+      "detectionMarkers": [
+        "github-actions",
+        "gitlab-ci"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "framework:php-laravel": {
+      "family": "framework",
+      "modules": [
+        "php-laravel-rules",
+        "php-laravel-skills"
+      ],
+      "detectionMarkers": [
+        "php",
+        "laravel"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "framework:ruby-rails": {
+      "family": "framework",
+      "modules": [
+        "ruby-rails-rules",
+        "ruby-rails-skills"
+      ],
+      "detectionMarkers": [
+        "ruby",
+        "rails"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "lang:c-cpp": {
+      "family": "language",
+      "modules": [
+        "c-cpp-rules",
+        "c-cpp-skills"
+      ],
+      "detectionMarkers": [
+        "c-cpp"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "capability:sql-db": {
+      "family": "capability",
+      "modules": [
+        "sql-db-rules",
+        "sql-db-skills"
+      ],
+      "detectionMarkers": [
+        "sql"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
     }
   }
 }

package/src/gdskills/bundled/rules/core/model-selection.mdc

@@ -177,6 +177,24 @@ entry point; `decideDispatchModel` is what it calls.
 Nothing reads a recorded resolution back and checks it. These fields explain a
 finished run; they do not gate one.
 
+## A third place: compiling a Claude Code subagent file
+
+`keryx agents export --runtime claude` (`src/agents/compile.ts`'s
+`renderClaudeExport`) is neither of the two shapes above — it never asks
+`spawn_subagent` or `keryx review tier` anything, and it runs at EXPORT time,
+once, against a file written to disk, not at dispatch time. Claude Code's own
+subagent frontmatter has no tier concept and no candidate discovery at all; it
+accepts exactly four fixed, version-free words for `model` — `opus`, `sonnet`,
+`haiku`, `inherit` — and nothing else. The compiler maps a definition's
+declared `model_tier` onto that fixed vocabulary directly: `deep` to `opus`,
+`standard` to `sonnet`, `light` to `haiku` (an undeclared tier defaults to
+`standard`, so it lands on `sonnet`). This is not the discover/rank/fall-back
+resolution described above, and it is not a model id — it is a static lookup
+into the one enum a host's own docs define, so it can never go stale the way a
+literal id would. A project that wants the pre-existing behavior sets
+`.metaproject/tasks.config.json`'s `modelGuidance.claudeSubagentAliases:
+false`, which restores `model: inherit` for every tier.
+
 ## Choosing the tier
 
 The tier is **computed, not judged**. Run:

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: job-orchestrator
-description: "Use when a GitHub issue or complex intent needs to be analyzed, planned, and implemented end-to-end with sub-agents. NOT for: the same pipeline under Task Manager flow state (use flow-orchestrator)."
+description: "Use when a GitHub issue or complex intent needs to be analyzed, planned, and implemented end-to-end with sub-agents — this skill orchestrates the whole task from issue to PR. NOT for: the same pipeline under Task Manager flow state (use flow-orchestrator)."
 triggers:
   - "implement issue"
   - "full workflow"

package/src/gdskills/bundled/skills/planning/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem that benefits from multiple perspectives. NOT for: writing the chosen option up as a formal requirements document (use prd-creator)."
+description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem with several options that benefits from multiple perspectives. NOT for: writing the chosen option up as a formal requirements document (use prd-creator)."
 triggers:
   - "brainstorm"
   - "explore options"

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. NOT for: clarifying implementation specifics AFTER context is already collected — use `interview` instead."
+description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that clarifies the real requirements and turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. NOT for: clarifying implementation specifics AFTER context is already collected — use `interview` instead."
 triggers:
   - "ask questions"
   - "clarify requirements"

package/src/gdskills/bundled/skills/quality/deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deploy
-description: "Use when deploying to any environment (staging, production) or when a deployment pipeline needs to run. NOT for the database schema changes a release depends on (use `db-migrate`)."
+description: "Use when deploying a release to any environment (staging, production) or when a deployment pipeline needs to run. NOT for the database schema changes a release depends on (use `db-migrate`)."
 triggers:
   - "deploy"
   - "deployment"