@clue-ai/cli 0.0.6 → 0.0.8

package/src/setup-check.mjs

@@ -1,5 +1,6 @@
 import { access, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { validateSemanticCiRequest } from "./contracts.mjs";
 import {
   findLifecycleCallApiNames,
   findLifecycleGuardViolations,
@@ -14,7 +15,7 @@ const disallowedWorkflowMetadataPattern =
 const SETUP_SKILLS = [
   "clue-setup-orchestrator",
   "clue-route-semantic-snapshot",
-  "clue-semantic-ci",
+  "clue-semantic-gen",
   "clue-sdk-instrumentation",
   "clue-setup-audit",
   "clue-local-verification",
@@ -31,6 +32,24 @@ const REQUIRED_LIFECYCLE_APIS = [
   "ClueSetAccount",
   "ClueLogout",
 ];
+
+const semanticRequestFromWorkflow = (workflow) => {
+  const match = workflow.match(
+    /CLUE_SEMANTIC_REQUEST_JSON: \|\n([\s\S]*?)\n\s*run: \|/,
+  );
+  if (!match) {
+    return null;
+  }
+  const requestJson = match[1]
+    .split("\n")
+    .map((line) => line.replace(/^ {12}/, ""))
+    .join("\n");
+  try {
+    return validateSemanticCiRequest(JSON.parse(requestJson));
+  } catch {
+    return null;
+  }
+};
 const BACKEND_SDK_MARKERS = [
   "clue-fastapi-sdk",
   "clue-django-sdk",
@@ -300,18 +319,25 @@ export const runSetupCheck = async ({
   const absoluteWorkflowPath = join(resolvedRepoRoot, workflowPath);
   if (await exists(absoluteWorkflowPath)) {
     const workflow = await readFile(absoluteWorkflowPath, "utf8");
+    const semanticRequest = semanticRequestFromWorkflow(workflow);
     addCheck(
       checks,
       "semantic_workflow",
       workflow.includes(
-        "npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+        "npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
       ) &&
+        semanticRequest !== null &&
         workflow.includes("CLUE_SEMANTIC_REQUEST_JSON: |") &&
         workflow.includes("CLUE_API_KEY: ${{ secrets.CLUE_API_KEY }}") &&
         workflow.includes(
           "CLUE_AI_PROVIDER_API_KEY: ${{ secrets.CLUE_AI_PROVIDER_API_KEY }}",
         ) &&
         workflow.includes("CLUE_AI_PROVIDER: ${{ vars.CLUE_AI_PROVIDER }}") &&
+        workflow.includes("CLUE_AI_MODEL: ${{ vars.CLUE_AI_MODEL }}") &&
+        !workflow.includes('"ai_provider": "${{ vars.CLUE_AI_PROVIDER }}"') &&
+        !workflow.includes('"ai_provider_base_url"') &&
+        !workflow.includes('"ai_model": "${{ vars.CLUE_AI_MODEL }}"') &&
+        !workflow.includes('"root_path"') &&
         workflow.includes("permissions:\n  contents: read") &&
         workflow.includes("persist-credentials: false") &&
         !disallowedWorkflowMetadataPattern.test(workflow),

package/src/setup-prepare.mjs

@@ -7,8 +7,65 @@ import {
 import { runSetupDetect } from "./setup-detect.mjs";
 
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
 const BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
 const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
+const AI_PROVIDER_GUIDES = {
+  codex: {
+    provider: "openai",
+    apiKeyValue: "<openai-api-key>",
+    model: "gpt-5.4-mini",
+    secretComments: [
+      "Codexを選んだ場合はOpenAIのAPI keyを使います。",
+      "https://platform.openai.com/api-keys で作成して、GitHub Secretに保存してください。",
+      "ここにはClue API keyではなく、OpenAI API keyを入れてください。",
+    ],
+    providerComments: [
+      "setup targetがcodexのため、providerはopenaiで自動設定しています。",
+    ],
+    modelComments: [
+      "まず迷ったら gpt-5.4-mini を使ってください。",
+      "精度を優先する場合の例: gpt-5.5",
+      "コストを優先する場合の例: gpt-5.4-nano",
+    ],
+  },
+  claude_code: {
+    provider: "anthropic",
+    apiKeyValue: "<anthropic-api-key>",
+    model: "claude-sonnet-4-6",
+    secretComments: [
+      "Claude Codeを選んだ場合はAnthropicのAPI keyを使います。",
+      "https://console.anthropic.com/settings/keys で作成して、GitHub Secretに保存してください。",
+      "ここにはClue API keyではなく、Anthropic API keyを入れてください。",
+    ],
+    providerComments: [
+      "setup targetがclaude_codeのため、providerはanthropicで自動設定しています。",
+    ],
+    modelComments: [
+      "まず迷ったら claude-sonnet-4-6 を使ってください。",
+      "精度を優先する場合の例: claude-opus-4-7",
+      "コストを優先する場合の例: claude-haiku-4-5-20251001",
+    ],
+  },
+};
+const GENERIC_AI_PROVIDER_GUIDE = {
+  provider: "<openai-or-anthropic>",
+  apiKeyValue: "<provider-api-key>",
+  model: "<provider-model>",
+  secretComments: [
+    "OpenAIまたはAnthropicのAPI keyを作成し、GitHub Secretに保存してください。",
+    "OpenAI: https://platform.openai.com/api-keys",
+    "Anthropic: https://console.anthropic.com/settings/keys",
+    "ここにはClue API keyではなく、選択したAI providerのAPI keyを入れてください。",
+  ],
+  providerComments: [
+    "codexを使う場合はopenai、claude_codeを使う場合はanthropicを指定してください。",
+  ],
+  modelComments: [
+    "OpenAIの例: gpt-5.4-mini / gpt-5.5 / gpt-5.4-nano",
+    "Anthropicの例: claude-sonnet-4-6 / claude-opus-4-7 / claude-haiku-4-5-20251001",
+  ],
+};
 
 const writeJson = async ({ repoRoot, path, value }) => {
   const absolutePath = join(resolve(repoRoot), path);
@@ -16,6 +73,12 @@ const writeJson = async ({ repoRoot, path, value }) => {
   await writeFile(absolutePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 };
 
+const writeText = async ({ repoRoot, path, value }) => {
+  const absolutePath = join(resolve(repoRoot), path);
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, value, "utf8");
+};
+
 const firstCandidateOrBlocker = (detection) => {
   if (!detection.detected || detection.candidates.length === 0) {
     return {
@@ -81,6 +144,9 @@ const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
 
 const buildEndpoint = (baseUrl, path) => `${trimTrailingSlash(baseUrl)}${path}`;
 
+const aiProviderGuideForTarget = (target) =>
+  AI_PROVIDER_GUIDES[target] ?? GENERIC_AI_PROVIDER_GUIDE;
+
 const setupContextFromInput = (input = {}) => ({
   clue_api_key: optionalString(input.clueApiKey),
   clue_api_base_url: optionalString(input.clueApiBaseUrl),
@@ -133,8 +199,10 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
   }
 
   const watchTargets = manifest.lifecycle_verification.watch_targets;
+  const aiProviderGuide = aiProviderGuideForTarget(manifest.target);
   return {
     status: "ready",
+    env_file_path: DEFAULT_ENV_GUIDE_PATH,
     message: "各サービスの env ファイルに以下を設定してください。",
     service_env_blocks: watchTargets.map((target) => ({
       kind: target.kind,
@@ -149,17 +217,94 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
         { name: "CLUE_API_KEY", value: setupContext.clue_api_key },
         {
           name: "CLUE_AI_PROVIDER_API_KEY",
-          value: "<openai-or-anthropic-api-key>",
+          value: aiProviderGuide.apiKeyValue,
+          comments: aiProviderGuide.secretComments,
         },
       ],
       variables: [
-        { name: "CLUE_AI_PROVIDER", value: "<openai-or-anthropic>" },
-        { name: "CLUE_AI_MODEL", value: "<selected-provider-model>" },
+        {
+          name: "CLUE_AI_PROVIDER",
+          value: aiProviderGuide.provider,
+          comments: aiProviderGuide.providerComments,
+        },
+        {
+          name: "CLUE_AI_MODEL",
+          value: aiProviderGuide.model,
+          comments: aiProviderGuide.modelComments,
+        },
       ],
     },
   };
 };
 
+const renderEnvironmentEntry = (entry) => [
+  ...(Array.isArray(entry.comments)
+    ? entry.comments.map((comment) => `# ${comment}`)
+    : []),
+  `${entry.name}=${entry.value}`,
+];
+
+const buildEnvironmentGuideText = (instructions) => {
+  if (!instructions || instructions.status !== "ready") return null;
+  const lines = [
+    "# Clue setup environment values",
+    "# This file contains setup secrets. Do not commit it.",
+    "",
+    instructions.message,
+    "",
+  ];
+  for (const block of instructions.service_env_blocks) {
+    lines.push(
+      `[${block.kind}] ${block.root_path} (${block.env_file_candidates.join(" or ")})`,
+      block.env_block,
+      "",
+    );
+  }
+  lines.push(
+    "GitHub Secrets",
+    ...instructions.ci_github.secrets.flatMap(renderEnvironmentEntry),
+    "",
+  );
+  if (instructions.ci_github.variables.length > 0) {
+    lines.push(
+      "GitHub Variables",
+      ...instructions.ci_github.variables.flatMap(renderEnvironmentEntry),
+      "",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+};
+
+const summarizeEnvironmentInstructions = (instructions) => {
+  if (!instructions || instructions.status !== "ready") {
+    return instructions;
+  }
+  return {
+    status: "ready",
+    env_file_path: instructions.env_file_path,
+    message:
+      `${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets に反映してください。`,
+    service_env_block_count: instructions.service_env_blocks.length,
+    github_secret_names: instructions.ci_github.secrets.map(
+      (entry) => entry.name,
+    ),
+    github_variable_names: instructions.ci_github.variables.map(
+      (entry) => entry.name,
+    ),
+  };
+};
+
+const writeEnvironmentGuideIfReady = async ({ repoRoot, instructions }) => {
+  const content = buildEnvironmentGuideText(instructions);
+  if (!content) return null;
+  await writeText({
+    repoRoot,
+    path: instructions.env_file_path,
+    value: content,
+  });
+  return instructions.env_file_path;
+};
+
 export const runSetupPrepare = async ({
   repoRoot,
   target,
@@ -189,12 +334,14 @@ export const runSetupPrepare = async ({
       path: setupManifestPath,
       value: manifest,
     });
+    const environmentInstructions = buildEnvironmentInstructions({
+      manifest,
+      setupContext,
+    });
     return {
       ...manifest,
-      environment_instructions: buildEnvironmentInstructions({
-        manifest,
-        setupContext,
-      }),
+      environment_instructions:
+        summarizeEnvironmentInstructions(environmentInstructions),
     };
   }
 
@@ -267,23 +414,43 @@ export const runSetupPrepare = async ({
       "CLUE_API_KEY",
       "CLUE_AI_PROVIDER",
       "CLUE_AI_PROVIDER_API_KEY",
+      "CLUE_AI_MODEL",
       "CLUE_PROJECT_KEY",
       "CLUE_ENVIRONMENT",
       "CLUE_INGEST_ENDPOINT",
       "CLUE_API_BASE_URL",
-      "CLUE_AI_MODEL",
     ],
   };
+  const environmentInstructions = buildEnvironmentInstructions({
+    manifest,
+    setupContext,
+  });
+  const manifestWithEnvironmentArtifact = {
+    ...manifest,
+    artifacts: {
+      ...manifest.artifacts,
+      environment_file_path:
+        environmentInstructions.status === "ready"
+          ? environmentInstructions.env_file_path
+          : null,
+    },
+  };
   await writeJson({
     repoRoot: resolvedRepoRoot,
     path: setupManifestPath,
-    value: manifest,
+    value: manifestWithEnvironmentArtifact,
+  });
+  const environmentFilePath = await writeEnvironmentGuideIfReady({
+    repoRoot: resolvedRepoRoot,
+    instructions: environmentInstructions,
   });
   return {
-    ...manifest,
-    environment_instructions: buildEnvironmentInstructions({
-      manifest,
-      setupContext,
-    }),
+    ...manifestWithEnvironmentArtifact,
+    artifacts: {
+      ...manifestWithEnvironmentArtifact.artifacts,
+      environment_file_path: environmentFilePath,
+    },
+    environment_instructions:
+      summarizeEnvironmentInstructions(environmentInstructions),
   };
 };

package/src/setup-tool.mjs

@@ -5,7 +5,7 @@ import readline from "node:readline/promises";
 const SKILL_NAMES = [
   "clue-setup-orchestrator",
   "clue-route-semantic-snapshot",
-  "clue-semantic-ci",
+  "clue-semantic-gen",
   "clue-sdk-instrumentation",
   "clue-setup-audit",
   "clue-local-verification",
@@ -36,7 +36,7 @@ const skillBody = (name) => {
       "Use first when running the full Clue setup so one execution agent per implementation workstream and multiple monitoring agents coordinate separate setup phases.",
     "clue-route-semantic-snapshot":
       "Use when checking backend route coverage and semantic snapshot readiness without hand-authoring generated snapshot files.",
-    "clue-semantic-ci":
+    "clue-semantic-gen":
       "Use when adding or updating Clue semantic snapshot CI for this repository.",
     "clue-sdk-instrumentation":
       "Use when adding ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout lifecycle calls to a customer repository.",
@@ -48,6 +48,137 @@ const skillBody = (name) => {
       "Use when producing the final Clue setup report with changed files, blockers, env names, and next steps.",
   };
 
+  const agentRoles = {
+    "clue-setup-orchestrator":
+      "Coordinator agent. Owns sequencing, agent assignment, gates, and blocker handling. It must not edit product code directly.",
+    "clue-route-semantic-snapshot":
+      "Semantic route readiness agent. Owns backend route inventory/readiness validation only. It must not author generated snapshot content or SDK code.",
+    "clue-semantic-gen":
+      "Semantic generation CI agent. Owns machine-owned CI workflow verification/refresh only. It must not hand-write snapshot content or SDK lifecycle code.",
+    "clue-sdk-instrumentation":
+      "SDK lifecycle implementation agent. Owns Clue SDK dependency, initialization, and lifecycle call implementation only.",
+    "clue-setup-audit":
+      "Read-only monitoring agent. Owns P0/P1 review for one completed workstream at a time. It must not edit files.",
+    "clue-local-verification":
+      "Read-only verification agent. Owns setup-check/setup-watch evidence and local verification readiness. It must not edit files.",
+    "clue-setup-report":
+      "Final reporting agent. Owns concise completion evidence only after execution and monitoring gates pass.",
+  };
+
+  const owns = {
+    "clue-setup-orchestrator": [
+      "read `.clue/setup-manifest.json` first",
+      "assign exactly one execution agent per implementation workstream",
+      "assign multiple read-only monitoring agents",
+      "stop on manifest blockers or P0/P1 findings",
+    ],
+    "clue-route-semantic-snapshot": [
+      "backend route discovery readiness",
+      "route coverage gaps and unsupported-framework blockers",
+      "privacy-safe evidence needed by semantic generation",
+    ],
+    "clue-semantic-gen": [
+      "`.github/workflows/clue-semantic-snapshot.yml` generated workflow shape",
+      "`semantic-gen` command wiring",
+      "GitHub secrets/variables referenced by name only",
+      "privacy boundary between customer repo CI and Clue API",
+    ],
+    "clue-sdk-instrumentation": [
+      "real Clue SDK imports/dependencies",
+      "ClueInit bootstrap placement",
+      "ClueIdentify login-success coverage",
+      "ClueSetAccount account/workspace/tenant coverage",
+      "ClueLogout logout/session-reset coverage",
+      "failure isolation so host behavior never depends on Clue success",
+    ],
+    "clue-setup-audit": [
+      "line-by-line diff review",
+      "responsibility boundary checks",
+      "P0/P1 findings before the next workstream continues",
+    ],
+    "clue-local-verification": [
+      "`setup-check` evidence",
+      "`setup-watch --local` readiness",
+      "local URL confirmation without assuming ports",
+    ],
+    "clue-setup-report": [
+      "changed files",
+      "commands run",
+      "skills and agents used",
+      "remaining blockers and required env names",
+    ],
+  };
+
+  const mustNot = {
+    "clue-setup-orchestrator": [
+      "do product-code implementation itself",
+      "merge workstreams into one broad task",
+      "continue after a blocker without reporting it",
+    ],
+    "clue-route-semantic-snapshot": [
+      "create SDK lifecycle calls",
+      "create or edit the CI workflow",
+      "hand-author generated semantic snapshot content",
+    ],
+    "clue-semantic-gen": [
+      "inspect `.env` or secret files",
+      "send raw source files, prompts, completions, or secret values to Clue",
+      "hand-edit generated snapshot content",
+    ],
+    "clue-sdk-instrumentation": [
+      "create no-op wrappers or placeholder lifecycle functions",
+      "place ClueInit on repeated UI/request paths",
+      "block login/logout/account/request flows on Clue success",
+      "guess service keys or ports",
+    ],
+    "clue-setup-audit": [
+      "make edits",
+      "approve unclear lifecycle points",
+      "approve secret values in code, diff, or report",
+    ],
+    "clue-local-verification": [
+      "make edits",
+      "assume localhost ports",
+      "treat setup-watch as complete before every expected implemented lifecycle check passes or is reported blocked",
+    ],
+    "clue-setup-report": [
+      "claim complete with unverified workstreams",
+      "include secret values",
+      "hide blockers or skipped checks",
+    ],
+  };
+
+  const outputs = {
+    "clue-setup-orchestrator": [
+      "agent plan with execution agents, monitoring agents, file ownership, and gate order",
+      "blocker list if setup cannot proceed",
+    ],
+    "clue-route-semantic-snapshot": [
+      "route readiness result: ready or blocked",
+      "route coverage evidence and blocker details",
+    ],
+    "clue-semantic-gen": [
+      "CI workflow verification result",
+      "whether regeneration was required and which command was used",
+    ],
+    "clue-sdk-instrumentation": [
+      "implemented lifecycle locations",
+      "dependency/import changes",
+      "tests or verification commands",
+    ],
+    "clue-setup-audit": [
+      "P0/P1 findings with file references",
+      "approval or blocked status for the reviewed workstream",
+    ],
+    "clue-local-verification": [
+      "setup-check/setup-watch command evidence",
+      "passed, blocked, or cannot-run status with reasons",
+    ],
+    "clue-setup-report": [
+      "final report with changed files, commands, skills, agents, verification, blockers, and env names",
+    ],
+  };
+
   const steps = {
     "clue-setup-orchestrator": [
       "Use one execution agent per implementation workstream.",
@@ -55,7 +186,7 @@ const skillBody = (name) => {
       "Required execution agents: SDK Lifecycle Execution Agent, Semantic Snapshot Readiness Execution Agent, and Semantic Snapshot CI Execution Agent.",
       "Run execution agents in parallel only when file ownership does not conflict; otherwise run them sequentially with monitor gates between workstreams.",
       "Use multiple monitoring agents for read-only checks, or named review passes if subagents are unavailable.",
-      "The initial `clue-ai setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment <environment>` command already performs repository discovery, semantic CI workflow generation, setup manifest generation, and service-specific environment guidance when backend routes can be detected.",
+      "The initial `clue-ai setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment <environment>` command already performs repository discovery, semantic CI workflow generation, setup manifest generation, and writes service-specific environment guidance to `.env.clue` when backend routes can be detected.",
       "Before implementation, read `.clue/setup-manifest.json` and treat it as the mechanical setup source of truth.",
       "Use the service keys and watch targets from `.clue/setup-manifest.json`; do not invent service keys.",
       "If `.clue/setup-manifest.json` has status `blocked`, stop and report its blockers instead of guessing.",
@@ -72,7 +203,7 @@ const skillBody = (name) => {
       "Do not create or commit `.clue/semantic-request.runtime.json`; the semantic CI request must be passed through the generated workflow environment instead of a repository file.",
       "Keep route coverage/readiness checks separate from CI workflow creation and SDK lifecycle implementation.",
       "Do not create CI workflow files or SDK lifecycle calls from this skill.",
-      "Do not create or commit `.clue/semantic-routes.json`; route inventory is dynamic and must be recomputed mechanically by `clue-ai semantic-inventory`, `clue-ai setup-check`, or `clue-ai semantic-ci`.",
+      "Do not create or commit `.clue/semantic-routes.json`; route inventory is dynamic and must be recomputed mechanically by `clue-ai semantic-inventory`, `clue-ai setup-check`, or `clue-ai semantic-gen`.",
       "If route inventory must be inspected locally, run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` and review stdout instead of writing a repo file.",
       "Inspect only allowed source paths.",
       "Identify the backend framework, backend root path, route files, controllers, handlers, and route declaration patterns from privacy-safe evidence.",
@@ -87,21 +218,22 @@ const skillBody = (name) => {
       "The expected generated snapshot structure preserves unresolved_operation_effects with missing_context instead of fabricating unknown operation effects.",
       "Report route coverage gaps, unsupported backend frameworks, and unclear backend roots as blockers instead of guessing.",
     ],
-    "clue-semantic-ci": [
+    "clue-semantic-gen": [
       "Use this skill as the source of truth for semantic snapshot CI workflow format.",
       "Keep CI workflow creation separate from route coverage/readiness checks and SDK lifecycle implementation.",
       "Do not author semantic snapshot content, runtime request files, or SDK lifecycle calls from this skill.",
       "Treat `.github/workflows/clue-semantic-snapshot.yml` as a machine-owned artifact generated by `clue-ai setup`; do not hand-edit it.",
       "Create or update `.github/workflows/clue-semantic-snapshot.yml` only by running `npx @clue-ai/cli semantic-workflow --framework <framework> --backend-root-path <path> --repo .` when it must be refreshed.",
       "If `npx` cannot be used in the current environment, use the local `clue-ai semantic-workflow` command equivalent instead of hand-writing the workflow.",
-      "The workflow must pass `CLUE_SEMANTIC_REQUEST_JSON` through the workflow environment and then call `npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .`.",
+      "The workflow must pass `CLUE_SEMANTIC_REQUEST_JSON` through the workflow environment and then call `npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .`.",
       "Do not create, commit, or stage `.clue/semantic-request.runtime.json` in the customer repository.",
       "The workflow must not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
-      "The workflow should send only repository id, commit sha, workflow run id, project key variable, service key, framework, source path allowlist, source path denylist, Clue API base URL variable, and AI model variable.",
+      "The workflow should send only repository id, commit sha, workflow run id, project key variable, service key, framework, source path allowlist, source path denylist, and Clue API base URL variable.",
       "Use minimal GitHub permissions and checkout without persisted credentials when generating the workflow.",
       "Reference GitHub Secrets and Variables by name only.",
       "Required GitHub secrets are `CLUE_API_KEY` and `CLUE_AI_PROVIDER_API_KEY`.",
       "Required GitHub variables are `CLUE_AI_PROVIDER` and `CLUE_AI_MODEL`.",
+      "Semantic generation runs inside the customer repository CI with the customer AI provider key; do not send raw source code, prompts, or completions to Clue.",
       "Do not print or commit secret values.",
     ],
     "clue-sdk-instrumentation": [
@@ -117,7 +249,7 @@ const skillBody = (name) => {
       "If `npx` cannot be used in the current environment, use the local `clue-ai lifecycle-apply` command equivalent instead of manually applying the exact replacements.",
       "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
       "Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
-      "For local env files, use the service-specific env blocks printed by `clue-ai setup`; do not ask the user to guess `CLUE_SERVICE_KEY`.",
+      "For local env files, use the service-specific env blocks written to `.env.clue` by `clue-ai setup`; do not ask the user to guess `CLUE_SERVICE_KEY`.",
       "For browser code, use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, and `CLUE_INGEST_ENDPOINT`. Let the target framework expose or inject those values safely without hard-coding a Next.js-only prefix.",
       "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT`.",
       "Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
@@ -157,11 +289,11 @@ const skillBody = (name) => {
       "Confirm generated skill files exist.",
       "Confirm workflow files and SDK lifecycle imports/calls exist when those phases have run.",
       "Confirm backend routes have a backend Clue SDK dependency/import/init when a backend exists.",
-      "Confirm `.github/workflows/clue-semantic-snapshot.yml` calls `npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON`.",
+      "Confirm `.github/workflows/clue-semantic-snapshot.yml` calls `npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON`.",
       "Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
       "Run `npx @clue-ai/cli setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle` when possible.",
-      "For interactive local verification, run `npx @clue-ai/cli setup-watch --project-key <project-key> --environment <environment> --clue-api-base-url <clue-api-base-url> --watch-targets frontend:<service-key>[init,identify,set-account,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>` and operate every local frontend/backend service until all expected checks pass.",
+      "For interactive local verification, run `npx @clue-ai/cli setup-watch --local` and operate every local frontend/backend service until all expected checks pass.",
       "Only include lifecycle checks that the implementation ownership plan expects for that service. If a service emits an undeclared lifecycle event, treat it as a possible duplicate instrumentation issue.",
       "Never assume localhost ports. Ask the repository scripts, env examples, or the running service output for the actual frontend/backend URLs.",
       "If `npx` cannot be used in the current environment, use the local `clue-ai setup-check` command equivalent.",
@@ -187,7 +319,23 @@ const skillBody = (name) => {
     `description: ${descriptions[name]}`,
     "---",
     "",
-    "# Rules",
+    "# Agent Role",
+    "",
+    agentRoles[name],
+    "",
+    "# Owns",
+    "",
+    ...owns[name].map((item) => `- ${item}`),
+    "",
+    "# Must Not",
+    "",
+    ...mustNot[name].map((item) => `- ${item}`),
+    "",
+    "# Output Contract",
+    "",
+    ...outputs[name].map((item) => `- ${item}`),
+    "",
+    "# Shared Rules",
     "",
     "- For full Clue setup, use one execution agent per implementation workstream and multiple monitoring agents for read-only checks.",
     "- The full setup must start with `clue-setup-orchestrator`.",