ep-cli: add agent/claude install targets with managed section upsert

Author: PaulJPhilp

packages/ep-cli/README.md

@@ -272,28 +272,32 @@ Subcommands:
 
 `install remove` and `install diff` exist in code but are intentionally not exposed in the public command surface at this time.
 
-### `ep install add --tool text [--skill-level text] [--use-case text] [-i|--interactive]`
+### `ep install add [--tool text] [--skill-level text] [--use-case text] [-i|--interactive]`
 
 Installs rule content into local tool configuration files.
 
 Supported tool values:
 
-- `agents`
+- `agent` (default)
+- `claude`
 - `cursor`
 - `vscode`
 - `windsurf`
 
 Target files:
 
-- `agents` -> rule content is written to `docs/Effect-Patterns-Rules.md`; `AGENTS.md` (in cwd) is updated with a managed block that points to that file.
+- `agent` -> `AGENTS.md` (in cwd), managed Effect section is upserted in place
+- `claude` -> `CLAUDE.md` (in cwd), managed Effect section is upserted in place
 - `cursor` -> `.cursor/rules.md`
 - `vscode` -> `.vscode/rules.md`
 - `windsurf` -> `.windsurf/rules.md`
 
 Examples:
 
 ```bash
-ep install add --tool agents
+ep install add
+ep install add --tool agent
+ep install add --tool claude
 ep install add --tool cursor --skill-level intermediate
 ep install add --tool vscode --use-case building-apis
 ep install add --tool windsurf -i
@@ -304,7 +308,8 @@ Notes:
 - `--interactive` opens multi-select prompt.
 - `--skill-level` maps to pattern difficulty filter.
 - `--use-case` filters results client-side by use case tag.
-- For `agents`, rule content is written to `docs/Effect-Patterns-Rules.md`; `AGENTS.md` is then updated with a managed block (`<!-- EP_RULES_START -->` / `<!-- EP_RULES_END -->`) that references that file. An existing managed block in `AGENTS.md` is replaced in place.
+- `agent` and `claude` use managed sections in `AGENTS.md` / `CLAUDE.md` and update only those sections when rerun.
+- Legacy alias `agents` is accepted and maps to `agent`.
 - State is recorded in installed-rules state JSON file.
 
 Unsupported tool behavior:
@@ -330,7 +335,7 @@ ep install list --installed --json
 JSON shapes:
 
 ```json
-{ "tools": ["agents", "cursor", "vscode", "windsurf"] }
+{ "tools": ["agent", "claude", "cursor", "vscode", "windsurf"] }
 ```
 
 ```json

packages/ep-cli/src/__tests__/cli-contract.test.ts

@@ -67,6 +67,8 @@ describe("ep-cli stream and machine-mode contracts", () => {
     const parsed = JSON.parse(result.stdout);
     expect(Array.isArray(parsed.tools)).toBe(true);
     expect(parsed.tools).toContain("cursor");
+    expect(parsed.tools).toContain("agent");
+    expect(parsed.tools).toContain("claude");
   });
 
   it("keeps unsupported-tool diagnostics on stderr", () => {

packages/ep-cli/src/commands/__tests__/install-commands.test.ts

@@ -34,7 +34,8 @@ describe("install commands", () => {
 			const exit = await run(["install", "list"]);
 			expect(Exit.isSuccess(exit)).toBe(true);
 			const output = capture.logs.join("\n");
-			expect(output).toContain("agents");
+			expect(output).toContain("agent");
+			expect(output).toContain("claude");
 			expect(output).toContain("cursor");
 			expect(output).toContain("vscode");
 			expect(output).toContain("windsurf");
@@ -47,7 +48,8 @@ describe("install commands", () => {
 			const parsed = JSON.parse(jsonLines);
 			expect(Array.isArray(parsed.tools)).toBe(true);
 			expect(parsed.tools).toContain("cursor");
-			expect(parsed.tools).toContain("agents");
+			expect(parsed.tools).toContain("agent");
+			expect(parsed.tools).toContain("claude");
 		});
 
 		it("outputs JSON for --installed --json with no rules", async () => {

packages/ep-cli/src/commands/install-commands.ts

@@ -11,13 +11,109 @@ import { Install, InstalledRule } from "../services/install/index.js";
 import { colorize } from "../utils.js";
 import { UnsupportedToolError } from "../errors.js";
 
+type InstallTool = "agent" | "claude" | "cursor" | "vscode" | "windsurf";
+
+const EFFECT_AGENT_START = "<!-- EFFECT_SKILLS_AGENT_START -->";
+const EFFECT_AGENT_END = "<!-- EFFECT_SKILLS_AGENT_END -->";
+const EFFECT_CLAUDE_START = "<!-- EFFECT_SKILLS_CLAUDE_START -->";
+const EFFECT_CLAUDE_END = "<!-- EFFECT_SKILLS_CLAUDE_END -->";
+
+const normalizeTool = (tool: string): InstallTool | null => {
+  if (tool === "agents") return "agent";
+  if (tool === "agent" || tool === "claude" || tool === "cursor" || tool === "vscode" || tool === "windsurf") {
+    return tool;
+  }
+  return null;
+};
+
+const installTargetByTool: Record<InstallTool, string> = {
+  agent: "AGENTS.md",
+  claude: "CLAUDE.md",
+  cursor: ".cursor/rules.md",
+  vscode: ".vscode/rules.md",
+  windsurf: ".windsurf/rules.md",
+};
+
+const markerByTool: Partial<Record<InstallTool, { start: string; end: string }>> = {
+  agent: { start: EFFECT_AGENT_START, end: EFFECT_AGENT_END },
+  claude: { start: EFFECT_CLAUDE_START, end: EFFECT_CLAUDE_END },
+};
+
+const escapeRegex = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const upsertManagedSection = (
+  current: string,
+  startMarker: string,
+  endMarker: string,
+  sectionBody: string
+): string => {
+  const managedSection = `${startMarker}\n${sectionBody}\n${endMarker}\n`;
+  const replacePattern = new RegExp(
+    `${escapeRegex(startMarker)}[\\s\\S]*?${escapeRegex(endMarker)}\\n?`,
+    "m"
+  );
+
+  if (current.includes(startMarker) && current.includes(endMarker)) {
+    return current.replace(replacePattern, managedSection);
+  }
+
+  if (current.trim().length === 0) {
+    return managedSection;
+  }
+
+  const separator = current.endsWith("\n") ? "\n" : "\n\n";
+  return `${current}${separator}${managedSection}`;
+};
+
+const buildAgentSection = (
+  rules: ReadonlyArray<Pick<InstalledRule, "id" | "title" | "skillLevel" | "useCase" | "description">>,
+  generatedAtIso: string
+): string =>
+  [
+    "## Effect Skills",
+    "",
+    `Generated by ep on ${generatedAtIso}.`,
+    "",
+    ...rules.flatMap((rule) => [
+      `### ${rule.title}`,
+      `- ID: ${rule.id}`,
+      `- Skill Level: ${rule.skillLevel ?? "general"}`,
+      `- Use Cases: ${(rule.useCase ?? []).join(", ") || "none"}`,
+      "",
+      rule.description,
+      "",
+    ]),
+  ].join("\n");
+
+const buildClaudeSection = (
+  rules: ReadonlyArray<Pick<InstalledRule, "title" | "skillLevel" | "useCase" | "description">>,
+  generatedAtIso: string
+): string =>
+  [
+    "## Coding Standards (Effect Patterns)",
+    "",
+    `Updated: ${generatedAtIso}`,
+    "",
+    "### Guiding Principles",
+    "",
+    ...rules.map((rule) => {
+      const level = rule.skillLevel ?? "general";
+      const useCases = (rule.useCase ?? []).slice(0, 3).join(", ");
+      const useCaseSuffix = useCases.length > 0 ? ` [${useCases}]` : "";
+      return `- **${rule.title}** (${level})${useCaseSuffix}: ${rule.description}`;
+    }),
+    "",
+    "Use these as defaults when making implementation decisions in this repository.",
+  ].join("\n");
+
 /**
  * install:add - Add rules to AI tool configuration
  */
 export const installAddCommand = Command.make("add", {
   options: {
     tool: Options.text("tool").pipe(
-      Options.withDescription("The AI tool to install rules for (cursor, agents, vscode, windsurf)")
+      Options.withDescription("Target tool format (agent, claude, cursor, vscode, windsurf)"),
+      Options.withDefault("agent")
     ),
     skillLevel: Options.optional(
       Options.text("skill-level").pipe(
@@ -42,25 +138,20 @@ export const installAddCommand = Command.make("add", {
       const { loadInstalledRules, saveInstalledRules, searchRules } = yield* Install;
       const fs = yield* FileSystem.FileSystem;
 
-      const installTargetByTool: Record<string, string> = {
-        agents: "AGENTS.md",
-        cursor: ".cursor/rules.md",
-        vscode: ".vscode/rules.md",
-        windsurf: ".windsurf/rules.md",
-      };
-
-      const targetPath = installTargetByTool[options.tool];
-      if (!targetPath) {
+      const normalizedTool = normalizeTool(options.tool);
+      if (!normalizedTool) {
+        const supportedTools = ["agent", "claude", "cursor", "vscode", "windsurf"];
         yield* Display.showError(
-          `Tool '${options.tool}' is not supported by local file injection yet. Supported: ${Object.keys(installTargetByTool).join(", ")}`
+          `Tool '${options.tool}' is not supported by local file injection yet. Supported: ${supportedTools.join(", ")}`
         );
         return yield* Effect.fail(new UnsupportedToolError({
           tool: options.tool,
-          supported: Object.keys(installTargetByTool),
+          supported: supportedTools,
         }));
       }
+      const targetPath = installTargetByTool[normalizedTool];
 
-      yield* Console.log(colorize("\nInstalling rules for " + options.tool + "...\n", "CYAN"));
+      yield* Console.log(colorize("\nInstalling rules for " + normalizedTool + "...\n", "CYAN"));
 
       let rulesToInstall = yield* searchRules({
         skillLevel: Option.getOrUndefined(options.skillLevel),
@@ -85,10 +176,11 @@ export const installAddCommand = Command.make("add", {
         return;
       }
 
+      const generatedAt = new Date().toISOString();
       const rulesMarkdown = [
         "# Effect Patterns Rules",
         "",
-        `Generated by ep on ${new Date().toISOString()}.`,
+        `Generated by ep on ${generatedAt}.`,
         "Source: Effect Patterns Database",
         "",
         ...rulesToInstall.flatMap((rule) => [
@@ -105,27 +197,24 @@ export const installAddCommand = Command.make("add", {
         ]),
       ].join("\n");
 
-      if (options.tool === "agents") {
-        const startMarker = "<!-- EP_RULES_START -->";
-        const endMarker = "<!-- EP_RULES_END -->";
-        const canonicalPath = path.join(process.cwd(), "docs", "Effect-Patterns-Rules.md");
-        const docsDir = path.dirname(canonicalPath);
-
-        yield* fs.makeDirectory(docsDir, { recursive: true });
-        yield* fs.writeFileString(canonicalPath, rulesMarkdown);
-
-        const pointerLine = "For Effect Patterns rules, see [docs/Effect-Patterns-Rules.md](docs/Effect-Patterns-Rules.md).";
-        const managedSection = `${startMarker}\n\n${pointerLine}\n\n${endMarker}\n`;
+      if (normalizedTool === "agent" || normalizedTool === "claude") {
+        const markers = markerByTool[normalizedTool];
+        if (!markers) {
+          return yield* Effect.fail(new Error(`Missing marker configuration for tool: ${normalizedTool}`));
+        }
 
+        const managedBody =
+          normalizedTool === "agent"
+            ? buildAgentSection(rulesToInstall, generatedAt)
+            : buildClaudeSection(rulesToInstall, generatedAt);
         const exists = yield* fs.exists(targetPath);
         const current = exists ? yield* fs.readFileString(targetPath) : "";
-        const nextContent =
-          current.includes(startMarker) && current.includes(endMarker)
-            ? current.replace(
-                /<!-- EP_RULES_START -->[\s\S]*<!-- EP_RULES_END -->\n?/m,
-                managedSection
-              )
-            : `${current}${current.endsWith("\n") ? "" : "\n"}\n${managedSection}`;
+        const nextContent = upsertManagedSection(
+          current,
+          markers.start,
+          markers.end,
+          managedBody
+        );
 
         yield* fs.writeFileString(targetPath, nextContent);
       } else {
@@ -138,7 +227,7 @@ export const installAddCommand = Command.make("add", {
       const newRules: InstalledRule[] = rulesToInstall.map((r) => ({
         ...r,
         installedAt: new Date().toISOString(),
-        tool: options.tool,
+        tool: normalizedTool,
         version: "1.0.0",
       }));
       const merged = [
@@ -147,10 +236,8 @@ export const installAddCommand = Command.make("add", {
       ];
       yield* saveInstalledRules(merged);
 
-      if (options.tool === "agents") {
-        yield* Display.showSuccess(
-          `Installed ${rulesToInstall.length} rule(s) to docs/Effect-Patterns-Rules.md and updated ${targetPath}`
-        );
+      if (normalizedTool === "agent" || normalizedTool === "claude") {
+        yield* Console.log(`✅ Installed Effect Skills to ${targetPath}`);
       } else {
         yield* Display.showSuccess(`Installed ${rulesToInstall.length} rule(s) to ${targetPath}`);
       }
@@ -186,7 +273,8 @@ const displayInstalledRules = (
 const displaySupportedTools = (): Effect.Effect<void, unknown> =>
   Effect.gen(function* () {
     yield* Console.log(colorize("\n📋 Supported AI Tools\n", "BRIGHT"));
-    yield* Console.log("  • agents");
+    yield* Console.log("  • agent");
+    yield* Console.log("  • claude");
     yield* Console.log("  • cursor");
     yield* Console.log("  • vscode");
     yield* Console.log("  • windsurf");
@@ -211,7 +299,7 @@ export const installListCommand = Command.make("list", {
   Command.withHandler(({ options }) =>
     Effect.gen(function* () {
       const { loadInstalledRules } = yield* Install;
-      const supportedTools = ["agents", "cursor", "vscode", "windsurf"] as const;
+      const supportedTools = ["agent", "claude", "cursor", "vscode", "windsurf"] as const;
 
       if (options.json) {
         if (options.installed) {