@qlucent/fishi-core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -441,10 +441,18 @@ declare function getAgentFactoryTemplate(): string;
  */
 declare function getCoordinatorFactoryTemplate(): string;
 
+type ConflictResolution = 'skip' | 'merge' | 'replace';
+interface FileResolutionMap {
+    categories: Record<string, ConflictResolution>;
+    files: Record<string, ConflictResolution>;
+}
 interface ScaffoldOptions extends InitOptions {
     projectName: string;
     projectType: ProjectType;
     brownfieldAnalysis?: BrownfieldAnalysisData;
+    resolutions?: FileResolutionMap;
+    docsReadmeExists?: boolean;
+    rootClaudeMdExists?: boolean;
 }
 interface ScaffoldResult {
     agentCount: number;
@@ -455,4 +463,64 @@ interface ScaffoldResult {
 }
 declare function generateScaffold(targetDir: string, options: ScaffoldOptions): Promise<ScaffoldResult>;
 
-export { type AgentDefinition, type AgentRole, type AgentTemplate, type BrownfieldAnalysisData, type ClaudeMdOptions, type CommandTemplate, type CostMode, type DetectionCheck, type DetectionResult, type DynamicAgentConfig, type ExecutionConfig, type FishiConfig, type FishiYamlOptions, type GateConfig, type GateStatus, type GitConfig, type HookTemplate, type InitOptions, type McpConfig, type McpServerConfig, type ModelRoutingConfig, type ModelTier, type ProjectConfig, type ProjectType, type ProjectYamlOptions, type ScaffoldOptions, type ScaffoldResult, type SkillTemplate, type StateConfig, type TaskStatus, type TaskboardConfig, type TemplateContext, architectAgentTemplate, backendAgentTemplate, devLeadTemplate, devopsAgentTemplate, docsAgentTemplate, frontendAgentTemplate, fullstackAgentTemplate, generateScaffold, getAdaptiveTaskGraphSkill, getAgentCompleteHook, getAgentFactoryTemplate, getAgentRegistryTemplate, getApiDesignSkill, getAutoCheckpointHook, getBoardCommand, getBrainstormingSkill, getBrownfieldAnalysisSkill, getBrownfieldDiscoverySkill, getClaudeMdTemplate, getCodeGenSkill, getCoordinatorFactoryTemplate, getDebuggingSkill, getDeploymentSkill, getDocCheckerScript, getDocumentationSkill, getFishiYamlTemplate, getGateCommand, getGateManagerScript, getGitignoreAdditions, getInitCommand, getLearningsManagerScript, getMasterOrchestratorTemplate, getMcpJsonTemplate, getMemoryManagerScript, getModelRoutingReference, getPhaseRunnerScript, getPostEditHook, getPrdCommand, getPrdSkill, getProjectYamlTemplate, getResetCommand, getResumeCommand, getSafetyCheckHook, getSessionStartHook, getSettingsJsonTemplate, getSprintCommand, getStatusCommand, getTaskboardOpsSkill, getTaskboardUpdateHook, getTestingSkill, getTodoManagerScript, getValidateScaffoldScript, getWorktreeManagerScript, getWorktreeSetupHook, marketingAgentTemplate, opsLeadTemplate, planningAgentTemplate, planningLeadTemplate, qualityLeadTemplate, researchAgentTemplate, securityAgentTemplate, testingAgentTemplate, uiuxAgentTemplate, writingAgentTemplate };
+interface FileConflict {
+    path: string;
+    size: number;
+}
+interface ConflictCategory {
+    name: string;
+    label: string;
+    conflicts: FileConflict[];
+}
+interface ConflictMap {
+    categories: ConflictCategory[];
+    hasConflicts: boolean;
+    totalConflicts: number;
+    docsReadmeExists: boolean;
+    rootClaudeMdExists: boolean;
+}
+declare function detectConflicts(targetDir: string): ConflictMap;
+
+interface BackupManifest {
+    timestamp: string;
+    fishi_version: string;
+    files: {
+        path: string;
+        size: number;
+    }[];
+}
+declare function createBackup(targetDir: string, conflictingFiles: string[]): Promise<string>;
+
+/**
+ * Prepend FISHI content to the TOP of an existing CLAUDE.md (for root CLAUDE.md).
+ * FISHI rules go first so they have higher priority in Claude Code.
+ */
+declare function mergeClaudeMdTop(existing: string, fishiContent: string): string;
+/**
+ * Append FISHI content to the BOTTOM of an existing CLAUDE.md (for .claude/CLAUDE.md).
+ */
+declare function mergeClaudeMd(existing: string, fishiContent: string): string;
+interface HookEntry {
+    matcher: string;
+    command: string;
+    [key: string]: unknown;
+}
+interface SettingsJson {
+    hooks?: Record<string, HookEntry[]>;
+    permissions?: {
+        allow?: string[];
+        deny?: string[];
+    };
+    env?: Record<string, string>;
+    enabledPlugins?: string[];
+    [key: string]: unknown;
+}
+declare function mergeSettingsJson(existing: SettingsJson, fishi: SettingsJson): SettingsJson;
+interface McpJson {
+    mcpServers: Record<string, Record<string, unknown>>;
+    [key: string]: unknown;
+}
+declare function mergeMcpJson(existing: McpJson, fishi: McpJson): McpJson;
+declare function mergeGitignore(existing: string, fishiAdditions: string): string;
+
+export { type AgentDefinition, type AgentRole, type AgentTemplate, type BackupManifest, type BrownfieldAnalysisData, type ClaudeMdOptions, type CommandTemplate, type ConflictCategory, type ConflictMap, type ConflictResolution, type CostMode, type DetectionCheck, type DetectionResult, type DynamicAgentConfig, type ExecutionConfig, type FileConflict, type FileResolutionMap, type FishiConfig, type FishiYamlOptions, type GateConfig, type GateStatus, type GitConfig, type HookTemplate, type InitOptions, type McpConfig, type McpServerConfig, type ModelRoutingConfig, type ModelTier, type ProjectConfig, type ProjectType, type ProjectYamlOptions, type ScaffoldOptions, type ScaffoldResult, type SkillTemplate, type StateConfig, type TaskStatus, type TaskboardConfig, type TemplateContext, architectAgentTemplate, backendAgentTemplate, createBackup, detectConflicts, devLeadTemplate, devopsAgentTemplate, docsAgentTemplate, frontendAgentTemplate, fullstackAgentTemplate, generateScaffold, getAdaptiveTaskGraphSkill, getAgentCompleteHook, getAgentFactoryTemplate, getAgentRegistryTemplate, getApiDesignSkill, getAutoCheckpointHook, getBoardCommand, getBrainstormingSkill, getBrownfieldAnalysisSkill, getBrownfieldDiscoverySkill, getClaudeMdTemplate, getCodeGenSkill, getCoordinatorFactoryTemplate, getDebuggingSkill, getDeploymentSkill, getDocCheckerScript, getDocumentationSkill, getFishiYamlTemplate, getGateCommand, getGateManagerScript, getGitignoreAdditions, getInitCommand, getLearningsManagerScript, getMasterOrchestratorTemplate, getMcpJsonTemplate, getMemoryManagerScript, getModelRoutingReference, getPhaseRunnerScript, getPostEditHook, getPrdCommand, getPrdSkill, getProjectYamlTemplate, getResetCommand, getResumeCommand, getSafetyCheckHook, getSessionStartHook, getSettingsJsonTemplate, getSprintCommand, getStatusCommand, getTaskboardOpsSkill, getTaskboardUpdateHook, getTestingSkill, getTodoManagerScript, getValidateScaffoldScript, getWorktreeManagerScript, getWorktreeSetupHook, marketingAgentTemplate, mergeClaudeMd, mergeClaudeMdTop, mergeGitignore, mergeMcpJson, mergeSettingsJson, opsLeadTemplate, planningAgentTemplate, planningLeadTemplate, qualityLeadTemplate, researchAgentTemplate, securityAgentTemplate, testingAgentTemplate, uiuxAgentTemplate, writingAgentTemplate };

package/dist/index.js

@@ -10375,12 +10375,117 @@ RECOMMENDATION: suggested next step
 }
 
 // src/generators/scaffold.ts
-import { mkdir, writeFile, readFile, appendFile } from "fs/promises";
+import { mkdir, writeFile, readFile } from "fs/promises";
+import { readFile as fsReadFile } from "fs/promises";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
+
+// src/generators/merge-strategies.ts
+var FISHI_START = "<!-- FISHI:START \u2014 Auto-generated by FISHI. Do not edit between markers. -->";
+var FISHI_END = "<!-- FISHI:END -->";
+function mergeClaudeMdTop(existing, fishiContent) {
+  const section = `${FISHI_START}
+### FISHI Framework
+${fishiContent}
+${FISHI_END}
+---
+`;
+  const startIdx = existing.indexOf(FISHI_START);
+  const endIdx = existing.indexOf(FISHI_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    const sectionEnd = endIdx + FISHI_END.length;
+    let afterEnd = sectionEnd;
+    const afterContent = existing.slice(afterEnd);
+    const separatorMatch = afterContent.match(/^\n?---\n/);
+    if (separatorMatch) {
+      afterEnd += separatorMatch[0].length;
+    }
+    return section + existing.slice(afterEnd);
+  }
+  return section + "\n" + existing;
+}
+function mergeClaudeMd(existing, fishiContent) {
+  const section = `
+---
+### FISHI Framework
+${FISHI_START}
+${fishiContent}
+${FISHI_END}`;
+  const startIdx = existing.indexOf(FISHI_START);
+  const endIdx = existing.indexOf(FISHI_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    let sectionStart = existing.lastIndexOf("\n---\n### FISHI Framework", startIdx);
+    if (sectionStart === -1) sectionStart = startIdx;
+    const sectionEnd = endIdx + FISHI_END.length;
+    return existing.slice(0, sectionStart) + section + existing.slice(sectionEnd);
+  }
+  return existing + section;
+}
+function mergeSettingsJson(existing, fishi) {
+  const result = { ...existing };
+  const mergedHooks = { ...existing.hooks };
+  if (fishi.hooks) {
+    for (const [event, entries] of Object.entries(fishi.hooks)) {
+      if (!mergedHooks[event]) {
+        mergedHooks[event] = [...entries];
+      } else {
+        for (const entry of entries) {
+          const isDuplicate = mergedHooks[event].some(
+            (e) => e.matcher === entry.matcher && e.command === entry.command
+          );
+          if (!isDuplicate) {
+            mergedHooks[event] = [...mergedHooks[event], entry];
+          }
+        }
+      }
+    }
+  }
+  result.hooks = mergedHooks;
+  const existingAllow = existing.permissions?.allow || [];
+  const fishiAllow = fishi.permissions?.allow || [];
+  const existingDeny = existing.permissions?.deny || [];
+  const fishiDeny = fishi.permissions?.deny || [];
+  result.permissions = {
+    allow: [.../* @__PURE__ */ new Set([...existingAllow, ...fishiAllow])],
+    deny: [.../* @__PURE__ */ new Set([...existingDeny, ...fishiDeny])]
+  };
+  if (fishi.env) {
+    result.env = { ...fishi.env, ...existing.env };
+  }
+  if (fishi.enabledPlugins) {
+    result.enabledPlugins = [
+      .../* @__PURE__ */ new Set([...existing.enabledPlugins || [], ...fishi.enabledPlugins])
+    ];
+  }
+  return result;
+}
+function mergeMcpJson(existing, fishi) {
+  const merged = { ...existing, mcpServers: { ...existing.mcpServers } };
+  for (const [name, config] of Object.entries(fishi.mcpServers)) {
+    if (!(name in merged.mcpServers)) {
+      merged.mcpServers[name] = config;
+    }
+  }
+  return merged;
+}
+function mergeGitignore(existing, fishiAdditions) {
+  if (existing.includes(".trees/")) {
+    return existing;
+  }
+  return existing + fishiAdditions;
+}
+
+// src/generators/scaffold.ts
 async function generateScaffold(targetDir, options) {
   let filesCreated = 0;
-  async function write(relativePath, content) {
+  const resolutions = options.resolutions;
+  async function write(relativePath, content, category) {
+    if (resolutions) {
+      const fileRes = resolutions.files[relativePath];
+      const catRes = category ? resolutions.categories[category] : void 0;
+      const resolution = fileRes || catRes;
+      if (resolution === "skip") return;
+    }
     const fullPath = join(targetDir, relativePath);
     await mkdir(dirname(fullPath), { recursive: true });
     await writeFile(fullPath, content, "utf-8");
@@ -10431,39 +10536,39 @@ async function generateScaffold(targetDir, options) {
   for (const dir of dirs) {
     await mkdir(join(targetDir, dir), { recursive: true });
   }
-  await write(".claude/agents/master-orchestrator.md", getMasterOrchestratorTemplate());
-  await write(".claude/agents/coordinators/planning-lead.md", planningLeadTemplate(ctx));
-  await write(".claude/agents/coordinators/dev-lead.md", devLeadTemplate(ctx));
-  await write(".claude/agents/coordinators/quality-lead.md", qualityLeadTemplate(ctx));
-  await write(".claude/agents/coordinators/ops-lead.md", opsLeadTemplate(ctx));
-  await write(".claude/agents/research-agent.md", researchAgentTemplate(ctx));
-  await write(".claude/agents/planning-agent.md", planningAgentTemplate(ctx));
-  await write(".claude/agents/architect-agent.md", architectAgentTemplate(ctx));
-  await write(".claude/agents/backend-agent.md", backendAgentTemplate(ctx));
-  await write(".claude/agents/frontend-agent.md", frontendAgentTemplate(ctx));
-  await write(".claude/agents/uiux-agent.md", uiuxAgentTemplate(ctx));
-  await write(".claude/agents/fullstack-agent.md", fullstackAgentTemplate(ctx));
-  await write(".claude/agents/devops-agent.md", devopsAgentTemplate(ctx));
-  await write(".claude/agents/testing-agent.md", testingAgentTemplate(ctx));
-  await write(".claude/agents/security-agent.md", securityAgentTemplate(ctx));
-  await write(".claude/agents/docs-agent.md", docsAgentTemplate(ctx));
-  await write(".claude/agents/writing-agent.md", writingAgentTemplate(ctx));
-  await write(".claude/agents/marketing-agent.md", marketingAgentTemplate(ctx));
+  await write(".claude/agents/master-orchestrator.md", getMasterOrchestratorTemplate(), "agents");
+  await write(".claude/agents/coordinators/planning-lead.md", planningLeadTemplate(ctx), "agents");
+  await write(".claude/agents/coordinators/dev-lead.md", devLeadTemplate(ctx), "agents");
+  await write(".claude/agents/coordinators/quality-lead.md", qualityLeadTemplate(ctx), "agents");
+  await write(".claude/agents/coordinators/ops-lead.md", opsLeadTemplate(ctx), "agents");
+  await write(".claude/agents/research-agent.md", researchAgentTemplate(ctx), "agents");
+  await write(".claude/agents/planning-agent.md", planningAgentTemplate(ctx), "agents");
+  await write(".claude/agents/architect-agent.md", architectAgentTemplate(ctx), "agents");
+  await write(".claude/agents/backend-agent.md", backendAgentTemplate(ctx), "agents");
+  await write(".claude/agents/frontend-agent.md", frontendAgentTemplate(ctx), "agents");
+  await write(".claude/agents/uiux-agent.md", uiuxAgentTemplate(ctx), "agents");
+  await write(".claude/agents/fullstack-agent.md", fullstackAgentTemplate(ctx), "agents");
+  await write(".claude/agents/devops-agent.md", devopsAgentTemplate(ctx), "agents");
+  await write(".claude/agents/testing-agent.md", testingAgentTemplate(ctx), "agents");
+  await write(".claude/agents/security-agent.md", securityAgentTemplate(ctx), "agents");
+  await write(".claude/agents/docs-agent.md", docsAgentTemplate(ctx), "agents");
+  await write(".claude/agents/writing-agent.md", writingAgentTemplate(ctx), "agents");
+  await write(".claude/agents/marketing-agent.md", marketingAgentTemplate(ctx), "agents");
   const agentCount = 18;
   await write(".fishi/agent-factory/agent-template.md", getAgentFactoryTemplate());
   await write(".fishi/agent-factory/coordinator-template.md", getCoordinatorFactoryTemplate());
-  await write(".claude/skills/brainstorming/SKILL.md", getBrainstormingSkill());
-  await write(".claude/skills/brownfield-analysis/SKILL.md", getBrownfieldAnalysisSkill());
-  await write(".claude/skills/taskboard-ops/SKILL.md", getTaskboardOpsSkill());
-  await write(".claude/skills/code-gen/SKILL.md", getCodeGenSkill());
-  await write(".claude/skills/debugging/SKILL.md", getDebuggingSkill());
-  await write(".claude/skills/api-design/SKILL.md", getApiDesignSkill());
-  await write(".claude/skills/testing/SKILL.md", getTestingSkill());
-  await write(".claude/skills/deployment/SKILL.md", getDeploymentSkill());
-  await write(".claude/skills/prd/SKILL.md", getPrdSkill());
-  await write(".claude/skills/brownfield-discovery/SKILL.md", getBrownfieldDiscoverySkill());
-  await write(".claude/skills/adaptive-taskgraph/SKILL.md", getAdaptiveTaskGraphSkill());
-  await write(".claude/skills/documentation/SKILL.md", getDocumentationSkill());
+  await write(".claude/skills/brainstorming/SKILL.md", getBrainstormingSkill(), "skills");
+  await write(".claude/skills/brownfield-analysis/SKILL.md", getBrownfieldAnalysisSkill(), "skills");
+  await write(".claude/skills/taskboard-ops/SKILL.md", getTaskboardOpsSkill(), "skills");
+  await write(".claude/skills/code-gen/SKILL.md", getCodeGenSkill(), "skills");
+  await write(".claude/skills/debugging/SKILL.md", getDebuggingSkill(), "skills");
+  await write(".claude/skills/api-design/SKILL.md", getApiDesignSkill(), "skills");
+  await write(".claude/skills/testing/SKILL.md", getTestingSkill(), "skills");
+  await write(".claude/skills/deployment/SKILL.md", getDeploymentSkill(), "skills");
+  await write(".claude/skills/prd/SKILL.md", getPrdSkill(), "skills");
+  await write(".claude/skills/brownfield-discovery/SKILL.md", getBrownfieldDiscoverySkill(), "skills");
+  await write(".claude/skills/adaptive-taskgraph/SKILL.md", getAdaptiveTaskGraphSkill(), "skills");
+  await write(".claude/skills/documentation/SKILL.md", getDocumentationSkill(), "skills");
   const skillCount = 12;
   await write(".fishi/scripts/session-start.mjs", getSessionStartHook());
   await write(".fishi/scripts/auto-checkpoint.mjs", getAutoCheckpointHook());
@@ -10496,14 +10601,14 @@ async function generateScaffold(targetDir, options) {
   await write(".fishi/todos/agents/frontend-agent.md", todoTemplate("frontend-agent"));
   await write(".fishi/todos/agents/testing-agent.md", todoTemplate("testing-agent"));
   await write(".fishi/todos/agents/devops-agent.md", todoTemplate("devops-agent"));
-  await write(".claude/commands/fishi-init.md", getInitCommand());
-  await write(".claude/commands/fishi-status.md", getStatusCommand());
-  await write(".claude/commands/fishi-resume.md", getResumeCommand());
-  await write(".claude/commands/fishi-gate.md", getGateCommand());
-  await write(".claude/commands/fishi-board.md", getBoardCommand());
-  await write(".claude/commands/fishi-sprint.md", getSprintCommand());
-  await write(".claude/commands/fishi-reset.md", getResetCommand());
-  await write(".claude/commands/fishi-prd.md", getPrdCommand());
+  await write(".claude/commands/fishi-init.md", getInitCommand(), "commands");
+  await write(".claude/commands/fishi-status.md", getStatusCommand(), "commands");
+  await write(".claude/commands/fishi-resume.md", getResumeCommand(), "commands");
+  await write(".claude/commands/fishi-gate.md", getGateCommand(), "commands");
+  await write(".claude/commands/fishi-board.md", getBoardCommand(), "commands");
+  await write(".claude/commands/fishi-sprint.md", getSprintCommand(), "commands");
+  await write(".claude/commands/fishi-reset.md", getResetCommand(), "commands");
+  await write(".claude/commands/fishi-prd.md", getPrdCommand(), "commands");
   const commandCount = 8;
   await write(".fishi/fishi.yaml", getFishiYamlTemplate({
     projectName: options.projectName,
@@ -10513,16 +10618,50 @@ async function generateScaffold(targetDir, options) {
     language: options.language,
     framework: options.framework
   }));
-  await write(".claude/settings.json", getSettingsJsonTemplate());
-  await write(".claude/CLAUDE.md", getClaudeMdTemplate({
+  const settingsContent = getSettingsJsonTemplate();
+  if (resolutions?.categories["settings-json"] === "merge") {
+    const existingRaw = await fsReadFile(join(targetDir, ".claude", "settings.json"), "utf-8");
+    const merged = mergeSettingsJson(JSON.parse(existingRaw), JSON.parse(settingsContent));
+    await write(".claude/settings.json", JSON.stringify(merged, null, 2) + "\n", "settings-json");
+  } else {
+    await write(".claude/settings.json", settingsContent, "settings-json");
+  }
+  const claudeMdContent = getClaudeMdTemplate({
     projectName: options.projectName,
     projectDescription: ctx.projectDescription,
     projectType: options.projectType,
     language: options.language,
     framework: options.framework,
     brownfieldAnalysis: options.brownfieldAnalysis
-  }));
-  await write(".mcp.json", getMcpJsonTemplate());
+  });
+  if (options.rootClaudeMdExists) {
+    const rootResolution = resolutions?.categories["root-claude-md"];
+    if (rootResolution === "merge") {
+      const existingMd = await fsReadFile(join(targetDir, "CLAUDE.md"), "utf-8");
+      const merged = mergeClaudeMdTop(existingMd, claudeMdContent);
+      const fullPath = join(targetDir, "CLAUDE.md");
+      await writeFile(fullPath, merged, "utf-8");
+      filesCreated++;
+    } else if (rootResolution === "replace") {
+      const fullPath = join(targetDir, "CLAUDE.md");
+      await writeFile(fullPath, claudeMdContent, "utf-8");
+      filesCreated++;
+    }
+  } else if (resolutions?.categories["claude-md"] === "merge") {
+    const existingMd = await fsReadFile(join(targetDir, ".claude", "CLAUDE.md"), "utf-8");
+    const merged = mergeClaudeMd(existingMd, claudeMdContent);
+    await write(".claude/CLAUDE.md", merged, "claude-md");
+  } else {
+    await write(".claude/CLAUDE.md", claudeMdContent, "claude-md");
+  }
+  const mcpContent = getMcpJsonTemplate();
+  if (resolutions?.categories["mcp-json"] === "merge") {
+    const existingRaw = await fsReadFile(join(targetDir, ".mcp.json"), "utf-8");
+    const merged = mergeMcpJson(JSON.parse(existingRaw), JSON.parse(mcpContent));
+    await write(".mcp.json", JSON.stringify(merged, null, 2) + "\n", "mcp-json");
+  } else {
+    await write(".mcp.json", mcpContent, "mcp-json");
+  }
   await write(".fishi/state/project.yaml", getProjectYamlTemplate({
     projectName: options.projectName,
     projectDescription: ctx.projectDescription,
@@ -10537,18 +10676,24 @@ async function generateScaffold(targetDir, options) {
   await write(".fishi/memory/decisions.md", "# Architecture Decision Log\n\n_No decisions recorded yet._\n");
   await write(".fishi/memory/agents/master-orchestrator.md", getMasterOrchestratorMemory(ctx));
   await write(".fishi/learnings/shared.md", "# Learnings \u2014 shared\n\n## Mistakes & Fixes\n\n## Best Practices\n");
-  await write("docs/README.md", `# ${options.projectName}
+  if (!options.docsReadmeExists) {
+    await write("docs/README.md", `# ${options.projectName}
 
 Documentation will be generated as the project progresses.
 `);
+  }
   await write(".fishi/taskboard/board.md", getEmptyBoard());
   await write(".fishi/taskboard/backlog.md", getEmptyBacklog());
   const gitignorePath = join(targetDir, ".gitignore");
   const additions = getGitignoreAdditions();
   if (existsSync(gitignorePath)) {
-    const existing = await readFile(gitignorePath, "utf-8");
-    if (!existing.includes(".trees/")) {
-      await appendFile(gitignorePath, "\n" + additions, "utf-8");
+    if (resolutions?.categories["gitignore"] === "skip") {
+    } else {
+      const existing = await readFile(gitignorePath, "utf-8");
+      const merged = mergeGitignore(existing, "\n" + additions);
+      if (merged !== existing) {
+        await writeFile(join(targetDir, ".gitignore"), merged, "utf-8");
+      }
     }
   } else {
     await writeFile(gitignorePath, additions, "utf-8");
@@ -10648,9 +10793,157 @@ Prioritized list of all upcoming work items.
 _Backlog is empty. Use /fishi-init to start the planning process._
 `;
 }
+
+// src/generators/conflict-detector.ts
+import { existsSync as existsSync2, statSync } from "fs";
+import { join as join2 } from "path";
+var FISHI_FILES = {
+  "claude-md": {
+    label: ".claude/CLAUDE.md",
+    files: [".claude/CLAUDE.md"]
+  },
+  "settings-json": {
+    label: ".claude/settings.json",
+    files: [".claude/settings.json"]
+  },
+  "mcp-json": {
+    label: ".mcp.json",
+    files: [".mcp.json"]
+  },
+  "agents": {
+    label: "Agents",
+    files: [
+      ".claude/agents/master-orchestrator.md",
+      ".claude/agents/coordinators/planning-lead.md",
+      ".claude/agents/coordinators/dev-lead.md",
+      ".claude/agents/coordinators/quality-lead.md",
+      ".claude/agents/coordinators/ops-lead.md",
+      ".claude/agents/research-agent.md",
+      ".claude/agents/planning-agent.md",
+      ".claude/agents/architect-agent.md",
+      ".claude/agents/backend-agent.md",
+      ".claude/agents/frontend-agent.md",
+      ".claude/agents/uiux-agent.md",
+      ".claude/agents/fullstack-agent.md",
+      ".claude/agents/devops-agent.md",
+      ".claude/agents/testing-agent.md",
+      ".claude/agents/security-agent.md",
+      ".claude/agents/docs-agent.md",
+      ".claude/agents/writing-agent.md",
+      ".claude/agents/marketing-agent.md"
+    ]
+  },
+  "skills": {
+    label: "Skills",
+    files: [
+      ".claude/skills/brainstorming/SKILL.md",
+      ".claude/skills/brownfield-analysis/SKILL.md",
+      ".claude/skills/taskboard-ops/SKILL.md",
+      ".claude/skills/code-gen/SKILL.md",
+      ".claude/skills/debugging/SKILL.md",
+      ".claude/skills/api-design/SKILL.md",
+      ".claude/skills/testing/SKILL.md",
+      ".claude/skills/deployment/SKILL.md",
+      ".claude/skills/prd/SKILL.md",
+      ".claude/skills/brownfield-discovery/SKILL.md",
+      ".claude/skills/adaptive-taskgraph/SKILL.md",
+      ".claude/skills/documentation/SKILL.md"
+    ]
+  },
+  "commands": {
+    label: "Commands",
+    files: [
+      ".claude/commands/fishi-init.md",
+      ".claude/commands/fishi-status.md",
+      ".claude/commands/fishi-resume.md",
+      ".claude/commands/fishi-gate.md",
+      ".claude/commands/fishi-board.md",
+      ".claude/commands/fishi-sprint.md",
+      ".claude/commands/fishi-reset.md",
+      ".claude/commands/fishi-prd.md"
+    ]
+  },
+  "gitignore": {
+    label: ".gitignore",
+    files: [".gitignore"]
+  }
+};
+function detectConflicts(targetDir) {
+  const categories = [];
+  let totalConflicts = 0;
+  const rootClaudeMdExists = existsSync2(join2(targetDir, "CLAUDE.md"));
+  for (const [name, def] of Object.entries(FISHI_FILES)) {
+    if (name === "claude-md" && rootClaudeMdExists) {
+      categories.push({ name, label: def.label, conflicts: [] });
+      continue;
+    }
+    const conflicts = [];
+    for (const relPath of def.files) {
+      const fullPath = join2(targetDir, relPath);
+      if (existsSync2(fullPath)) {
+        const stat = statSync(fullPath);
+        conflicts.push({ path: relPath, size: stat.size });
+      }
+    }
+    categories.push({ name, label: def.label, conflicts });
+    totalConflicts += conflicts.length;
+  }
+  if (rootClaudeMdExists) {
+    const stat = statSync(join2(targetDir, "CLAUDE.md"));
+    categories.unshift({
+      name: "root-claude-md",
+      label: "CLAUDE.md (root)",
+      conflicts: [{ path: "CLAUDE.md", size: stat.size }]
+    });
+    totalConflicts += 1;
+  }
+  const docsReadmeExists = existsSync2(join2(targetDir, "docs", "README.md"));
+  return {
+    categories,
+    hasConflicts: totalConflicts > 0,
+    totalConflicts,
+    docsReadmeExists,
+    rootClaudeMdExists
+  };
+}
+
+// src/generators/backup-manager.ts
+import { mkdir as mkdir2, copyFile, writeFile as writeFile2, rename } from "fs/promises";
+import { existsSync as existsSync3, statSync as statSync2 } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
+async function createBackup(targetDir, conflictingFiles) {
+  const now = /* @__PURE__ */ new Date();
+  const timestamp = now.toISOString().replace(/:/g, "-").replace(/\.\d+Z$/, "");
+  const backupDir = join3(targetDir, ".fishi", "backup", timestamp);
+  await mkdir2(backupDir, { recursive: true });
+  const manifestFiles = [];
+  for (const relPath of conflictingFiles) {
+    const srcPath = join3(targetDir, relPath);
+    const destPath = join3(backupDir, relPath);
+    if (existsSync3(srcPath)) {
+      await mkdir2(dirname2(destPath), { recursive: true });
+      await copyFile(srcPath, destPath);
+      const stat = statSync2(srcPath);
+      manifestFiles.push({ path: relPath, size: stat.size });
+    }
+  }
+  const fishiVersion = "0.3.0";
+  const manifest = {
+    timestamp: now.toISOString(),
+    fishi_version: fishiVersion,
+    files: manifestFiles
+  };
+  const manifestPath = join3(backupDir, "manifest.json");
+  const tmpPath = manifestPath + ".tmp";
+  await writeFile2(tmpPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+  await rename(tmpPath, manifestPath);
+  return backupDir;
+}
 export {
   architectAgentTemplate,
   backendAgentTemplate,
+  createBackup,
+  detectConflicts,
   devLeadTemplate,
   devopsAgentTemplate,
   docsAgentTemplate,
@@ -10704,6 +10997,11 @@ export {
   getWorktreeManagerScript,
   getWorktreeSetupHook,
   marketingAgentTemplate,
+  mergeClaudeMd,
+  mergeClaudeMdTop,
+  mergeGitignore,
+  mergeMcpJson,
+  mergeSettingsJson,
   opsLeadTemplate,
   planningAgentTemplate,
   planningLeadTemplate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlucent/fishi-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared templates, types, and generators for the FISHI framework",
   "license": "MIT",
   "type": "module",