@clubmatto/ai-kit 0.0.7 → 0.0.9

package/README.md

@@ -83,11 +83,12 @@ ai-kit sync
 
 ```bash
 # Bump version in package.json first
-git add package.json && git commit -m "release: bump version to <version>"
+git add ai-kit/package.json
+git commit -m "release: bump version to <version>"
 
-# Create git tag with prefix (triggers automated release)
-git tag ai-kit/v<version>
-git push origin ai-kit/v<version>
+# Create git tag and push both (tag triggers automated release)
+git tag -a ai-kit/v<version> -m "v<version>"
+git push origin main --follow-tags
 ```
 
 ## License

package/dist/src/cmd/sync.js

@@ -9,6 +9,7 @@ const template_1 = require("../template");
 const output_1 = require("../output");
 const detect_1 = require("../detection/detect");
 const language_detectors_1 = require("../detection/language-detectors");
+const plan_1 = require("../plan");
 const rootDir = (0, path_1.join)(__dirname, "..", "..", "..");
 const defaultSourceDirs = {
     rules: (0, path_1.join)(rootDir, "src", "rules"),
@@ -17,41 +18,31 @@ const defaultSourceDirs = {
     commands: (0, path_1.join)(rootDir, "src", "commands"),
 };
 async function sync(cwd, version, options, logger = output_1.log, sourceDirs = defaultSourceDirs) {
-    const manifest = (0, manifest_1.readManifest)(cwd);
     logger.logo(version);
-    if (manifest && manifest.version === version) {
-        logger.success(`Already at latest version (${version})`);
-        return;
-    }
     logger.welcome();
-    const counts = await doSync(cwd, version, options, logger, sourceDirs);
-    logger.summary(counts);
-}
-function writeItem(aiDir, file) {
-    const targetDir = (0, path_1.join)(aiDir, file.type);
-    if (!(0, fs_1.existsSync)(targetDir)) {
-        (0, fs_1.mkdirSync)(targetDir, { recursive: true });
-    }
-    const targetPath = (0, path_1.join)(targetDir, file.name);
-    const parentDir = (0, path_1.dirname)(targetPath);
-    if (!(0, fs_1.existsSync)(parentDir)) {
-        (0, fs_1.mkdirSync)(parentDir, { recursive: true });
-    }
-    (0, fs_1.writeFileSync)(targetPath, (0, template_1.processTemplate)(file.content));
-}
-async function doSync(cwd, version, options, logger, sourceDirs) {
     const aiDir = (0, path_1.join)(cwd, ".agents");
     if (!(0, fs_1.existsSync)(aiDir)) {
         (0, fs_1.mkdirSync)(aiDir, { recursive: true });
     }
+    const manifest = (0, manifest_1.readManifest)(cwd);
+    const desired = buildDesiredFiles(sourceDirs, cwd, options);
+    const actions = (0, plan_1.diffDesired)(desired, manifest, cwd);
+    const changes = executeActions(actions, cwd, logger);
+    const newFiles = {};
+    for (const [relPath, df] of desired) {
+        newFiles[relPath] = { sourceHash: df.identity };
+    }
+    (0, manifest_1.writeManifest)(cwd, { version, files: newFiles });
+    logger.summary(changes);
+}
+function buildDesiredFiles(sourceDirs, cwd, options) {
+    const desired = new Map();
     const contentFiles = (0, reader_1.readContent)(sourceDirs.rules, sourceDirs.skills);
     const rootFiles = (0, reader_1.readConfigs)(sourceDirs.agents);
-    // Detect languages and determine project type
     const detectionResult = (0, detect_1.detectLanguages)(cwd);
     let languages = detectionResult.languages;
     let isMonorepo = detectionResult.isMonorepo;
     const primaryLanguage = detectionResult.primaryLanguage;
-    // Apply overrides from options
     if (options.allRules) {
         languages = language_detectors_1.detectors.map((d) => d.name);
         isMonorepo = true;
@@ -66,84 +57,127 @@ async function doSync(cwd, version, options, logger, sourceDirs) {
         languages = options.languages;
         isMonorepo = languages.length > 1;
     }
-    // If no languages detected and no overrides, fall back to all rules (monorepo)
     if (languages.length === 0) {
-        languages = language_detectors_1.detectors.map((d) => d.name);
         isMonorepo = true;
     }
     const agentsFile = (0, reader_1.readAgents)(sourceDirs.agents, isMonorepo, primaryLanguage);
-    // Filter rules based on detected languages
     const ruleFilesToInclude = options.allRules
         ? (0, detect_1.getAllRuleFiles)()
         : (0, detect_1.getRuleFilesForLanguages)(languages);
     const rules = contentFiles.filter((f) => {
         if (f.type !== "rules")
             return false;
-        // Always include non-language-specific rules (plan-mode.md, unsure.md, etc.)
-        if (!(0, detect_1.isLanguageSpecificRule)(f.name)) {
+        if (!(0, detect_1.isLanguageSpecificRule)(f.name))
             return true;
-        }
-        // For language-specific rules, check if they're in the include list
         return ruleFilesToInclude.includes(f.name);
     });
-    const stats = { rules: 0, skills: 0, commands: 0 };
-    const installedRootFiles = [];
     if (!options.skipOpencode) {
         const commandConfig = (0, reader_1.getCommandConfig)(sourceDirs.commands);
-        stats.commands = Object.keys(commandConfig).length;
-        if (Object.keys(commandConfig).length > 0) {
-            logger.section("commands");
-            for (const name of Object.keys(commandConfig)) {
-                logger.success(`${name}.md`);
-            }
-        }
-        if (rootFiles.length > 0) {
-            logger.section("configs");
-            for (const file of rootFiles) {
-                let content = file.content;
-                if (file.name === "opencode.json" &&
-                    Object.keys(commandConfig).length > 0) {
-                    const config = JSON.parse(content);
-                    config.command = commandConfig;
-                    content = JSON.stringify(config, null, 2) + "\n";
-                }
-                const targetPath = (0, path_1.join)(cwd, file.name);
-                (0, fs_1.writeFileSync)(targetPath, content);
-                logger.success(`${file.name}`);
-                installedRootFiles.push(file.name);
+        for (const file of rootFiles) {
+            let content = file.content;
+            if (file.name === "opencode.json" &&
+                Object.keys(commandConfig).length > 0) {
+                const config = JSON.parse(content);
+                config.command = commandConfig;
+                content = JSON.stringify(config, null, 2) + "\n";
             }
+            desired.set(file.name, {
+                path: file.name,
+                identity: (0, manifest_1.hashContent)(content),
+                content,
+                category: file.name === "opencode.json"
+                    ? "opencode-json"
+                    : "static",
+            });
         }
     }
     if (agentsFile) {
-        const targetPath = (0, path_1.join)(cwd, agentsFile.name);
-        (0, fs_1.writeFileSync)(targetPath, (0, template_1.processTemplate)(agentsFile.content));
-        logger.success(`${agentsFile.name}`);
+        desired.set(agentsFile.name, {
+            path: agentsFile.name,
+            identity: (0, manifest_1.hashContent)(agentsFile.content),
+            content: (0, template_1.processTemplate)(agentsFile.content),
+            category: "agents-md",
+        });
     }
-    if (rules.length > 0) {
-        logger.section("rules");
-        for (const file of rules) {
-            writeItem(aiDir, file);
-            logger.success(`${file.name}`);
-            stats.rules++;
-        }
+    for (const file of rules) {
+        const relPath = (0, path_1.join)(".agents", file.type, file.name);
+        desired.set(relPath, {
+            path: relPath,
+            identity: (0, manifest_1.hashContent)(file.content),
+            content: (0, template_1.processTemplate)(file.content),
+            category: "static",
+        });
     }
     const skills = contentFiles.filter((f) => f.type === "skills");
-    if (skills.length > 0) {
-        logger.section("skills");
-        const skillDirs = [...new Set(skills.map((f) => f.name.split("/")[0]))];
-        stats.skills = skillDirs.length;
-        for (const dir of skillDirs) {
-            const dirFiles = skills.filter((f) => f.name.startsWith(dir + "/"));
-            logger.success(`${dir} (${dirFiles.length} files)`);
-            for (const file of dirFiles) {
-                writeItem(aiDir, file);
+    for (const file of skills) {
+        const relPath = (0, path_1.join)(".agents", file.type, file.name);
+        desired.set(relPath, {
+            path: relPath,
+            identity: (0, manifest_1.hashContent)(file.content),
+            content: (0, template_1.processTemplate)(file.content),
+            category: "static",
+        });
+    }
+    return desired;
+}
+function executeActions(actions, cwd, logger) {
+    const changes = (0, plan_1.emptySyncChanges)();
+    for (const action of actions) {
+        const targetPath = (0, path_1.join)(cwd, action.relPath);
+        switch (action.action) {
+            case "add": {
+                const dir = (0, path_1.dirname)(targetPath);
+                if (!(0, fs_1.existsSync)(dir))
+                    (0, fs_1.mkdirSync)(dir, { recursive: true });
+                (0, fs_1.writeFileSync)(targetPath, action.content);
+                changes.added++;
+                logger.success(`+ ${action.relPath}`);
+                break;
+            }
+            case "update": {
+                const dir = (0, path_1.dirname)(targetPath);
+                if (!(0, fs_1.existsSync)(dir))
+                    (0, fs_1.mkdirSync)(dir, { recursive: true });
+                (0, fs_1.writeFileSync)(targetPath, action.content);
+                changes.updated++;
+                logger.success(`~ ${action.relPath}`);
+                break;
+            }
+            case "skip":
+                changes.skipped++;
+                break;
+            case "merge": {
+                const currentContent = (0, fs_1.readFileSync)(targetPath, "utf-8");
+                const merged = (0, plan_1.mergeOpencodeJson)(action.content, currentContent);
+                (0, fs_1.writeFileSync)(targetPath, merged);
+                changes.merged++;
+                logger.success(`M ${action.relPath}`);
+                break;
+            }
+            case "backup": {
+                const currentContent = (0, fs_1.readFileSync)(targetPath, "utf-8");
+                const backupDir = (0, path_1.join)(cwd, ".agents");
+                if (!(0, fs_1.existsSync)(backupDir))
+                    (0, fs_1.mkdirSync)(backupDir, { recursive: true });
+                const backupPath = (0, path_1.join)(backupDir, `${action.relPath}.bak.${Date.now()}`);
+                (0, fs_1.writeFileSync)(backupPath, currentContent);
+                (0, fs_1.writeFileSync)(targetPath, action.content);
+                changes.backedUp++;
+                logger.success(`! ${action.relPath}`);
+                break;
+            }
+            case "remove": {
+                (0, fs_1.rmSync)(targetPath, { force: true });
+                changes.removed++;
+                logger.success(`- ${action.relPath}`);
+                break;
+            }
+            case "warn": {
+                changes.warned++;
+                logger.warn(`${action.relPath} (modified — skipped)`);
+                break;
             }
         }
     }
-    (0, manifest_1.writeManifest)(cwd, {
-        version,
-        installedAt: new Date().toISOString(),
-        rootFiles: installedRootFiles,
-    });
-    return stats;
+    return changes;
 }

package/dist/src/detection/detect.js

@@ -6,20 +6,23 @@ exports.getAllRuleFiles = getAllRuleFiles;
 exports.isLanguageSpecificRule = isLanguageSpecificRule;
 const language_detectors_1 = require("./language-detectors");
 const scanner_1 = require("./scanner");
+function hasMatchingFile(files, names) {
+    return names.some((name) => files.some((f) => f === name || f.endsWith("/" + name)));
+}
+function hasMatchingExtension(files, extensions) {
+    return extensions.some((ext) => files.some((f) => f.endsWith(ext)));
+}
 function detectLanguages(cwd) {
+    const { allFiles, rootFiles } = (0, scanner_1.scanTree)(cwd);
     const detected = new Set();
     for (const detector of language_detectors_1.detectors) {
-        if ((0, scanner_1.hasAnyConfigFile)(cwd, detector.configFiles)) {
+        const hasConfigAtRoot = hasMatchingFile(rootFiles, detector.configFiles);
+        const hasConfigInTree = hasMatchingFile(allFiles, detector.configFiles);
+        const hasSource = hasMatchingExtension(allFiles, detector.extensions);
+        if (hasConfigAtRoot || hasConfigInTree || hasSource) {
             detected.add(detector.name);
         }
     }
-    if (detected.size === 0) {
-        for (const detector of language_detectors_1.detectors) {
-            if ((0, scanner_1.hasAnySourceFile)(cwd, detector.extensions, 2)) {
-                detected.add(detector.name);
-            }
-        }
-    }
     const languages = Array.from(detected);
     const isMonorepo = languages.length > 1;
     const primaryLanguage = languages.length > 0 ? languages[0] : undefined;

package/dist/src/detection/language-detectors.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectors = void 0;
-//TODO this is a good first implementation
-//but we clearly want each detector to come with a detect function
 exports.detectors = [
     {
         name: "typescript",

package/dist/src/detection/scanner.js

@@ -1,9 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasAnyConfigFile = hasAnyConfigFile;
-exports.hasAnySourceFile = hasAnySourceFile;
-const fs_1 = require("fs");
-const path_1 = require("path");
+exports.scanTree = scanTree;
+const fdir_1 = require("fdir");
 const IGNORE_DIRS = [
     "node_modules",
     ".git",
@@ -13,41 +11,13 @@ const IGNORE_DIRS = [
     ".next",
     ".nuxt",
 ];
-function hasAnyConfigFile(cwd, configFiles) {
-    for (const configFile of configFiles) {
-        if ((0, fs_1.existsSync)((0, path_1.join)(cwd, configFile))) {
-            return true;
-        }
-    }
-    return false;
-}
-function hasAnySourceFile(cwd, extensions, maxDepth = 2) {
-    return scanForExtensions(cwd, extensions, maxDepth, 0);
-}
-function scanForExtensions(dir, extensions, maxDepth, currentDepth) {
-    if (currentDepth > maxDepth) {
-        return false;
-    }
-    try {
-        const entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            const fullPath = (0, path_1.join)(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (!IGNORE_DIRS.includes(entry.name) && !entry.name.startsWith(".")) {
-                    if (scanForExtensions(fullPath, extensions, maxDepth, currentDepth + 1)) {
-                        return true;
-                    }
-                }
-            }
-            else if (entry.isFile()) {
-                if (extensions.some((ext) => entry.name.endsWith(ext))) {
-                    return true;
-                }
-            }
-        }
-    }
-    catch {
-        // If we can't read the directory, skip it
-    }
-    return false;
+function scanTree(cwd, maxDepth = 4) {
+    const allFiles = new fdir_1.fdir()
+        .withRelativePaths()
+        .withMaxDepth(maxDepth)
+        .exclude((name) => IGNORE_DIRS.includes(name) || name.startsWith("."))
+        .crawl(cwd)
+        .sync();
+    const rootFiles = allFiles.filter((f) => !f.includes("/"));
+    return { allFiles, rootFiles };
 }

package/dist/src/manifest.js

@@ -1,24 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashContent = hashContent;
 exports.readManifest = readManifest;
 exports.writeManifest = writeManifest;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const crypto_1 = require("crypto");
 const AI_DIR = ".agents";
 const MANIFEST_FILE = ".ai-kit";
 function getManifestPath(cwd) {
     return (0, path_1.join)(cwd, AI_DIR, MANIFEST_FILE);
 }
+function hashContent(content) {
+    return (0, crypto_1.createHash)("sha256").update(content, "utf-8").digest("hex");
+}
 function readManifest(cwd) {
     const path = getManifestPath(cwd);
     if (!(0, fs_1.existsSync)(path))
         return null;
-    return JSON.parse((0, fs_1.readFileSync)(path, "utf-8"));
+    try {
+        const data = JSON.parse((0, fs_1.readFileSync)(path, "utf-8"));
+        if (!data.files) {
+            return { version: data.version || "0.0.0", files: {} };
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
 }
 function writeManifest(cwd, manifest) {
     const dir = (0, path_1.join)(cwd, AI_DIR);
     if (!(0, fs_1.existsSync)(dir)) {
         (0, fs_1.mkdirSync)(dir, { recursive: true });
     }
-    (0, fs_1.writeFileSync)(getManifestPath(cwd), JSON.stringify(manifest, null, 2));
+    (0, fs_1.writeFileSync)(getManifestPath(cwd), JSON.stringify(manifest, null, 2) + "\n");
 }

package/dist/src/output.js

@@ -30,17 +30,28 @@ exports.log = {
     },
     section: (msg) => console.log(colorize(`  → ${msg}`, "cyan")),
     success: (msg) => console.log(colorize(`    ✓ ${msg}`, "green")),
+    warn: (msg) => console.log(colorize(`    ! ${msg}`, "yellow")),
     final: (msg) => console.log(colorize(`  ✓ ${msg}`, "green")),
     summary: (counts) => {
-        console.log(colorize("\n  ✓ Done!", "green"));
-        console.log(colorize(`  → `, "dim") +
-            colorize(counts.commands.toString(), "white") +
-            colorize(` commands`, "dim") +
-            colorize(`, `, "dim") +
-            colorize(counts.rules.toString(), "white") +
-            colorize(` rules`, "dim") +
-            colorize(`, `, "dim") +
-            colorize(counts.skills.toString(), "white") +
-            colorize(` skills`, "dim"));
+        const parts = [];
+        if (counts.added > 0)
+            parts.push(colorize(`+${counts.added} added`, "green"));
+        if (counts.updated > 0)
+            parts.push(colorize(`~${counts.updated} updated`, "white"));
+        if (counts.merged > 0)
+            parts.push(colorize(`M${counts.merged} merged`, "yellow"));
+        if (counts.backedUp > 0)
+            parts.push(colorize(`!${counts.backedUp} backed up`, "yellow"));
+        if (counts.removed > 0)
+            parts.push(colorize(`-${counts.removed} removed`, "red"));
+        if (counts.warned > 0)
+            parts.push(colorize(`!${counts.warned} modified (skipped)`, "yellow"));
+        if (parts.length === 0) {
+            console.log(colorize("\n  ✓ Everything up to date!", "green"));
+        }
+        else {
+            console.log(colorize("\n  ✓ Done!", "green"));
+            console.log("  " + parts.join(colorize(", ", "dim")));
+        }
     },
 };

package/dist/src/plan.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptySyncChanges = emptySyncChanges;
+exports.diffDesired = diffDesired;
+exports.mergeOpencodeJson = mergeOpencodeJson;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const template_1 = require("./template");
+function emptySyncChanges() {
+    return {
+        added: 0,
+        updated: 0,
+        merged: 0,
+        backedUp: 0,
+        removed: 0,
+        skipped: 0,
+        warned: 0,
+    };
+}
+function diffDesired(desired, manifest, cwd) {
+    const actions = [];
+    for (const [relPath, df] of desired) {
+        const lastEntry = manifest?.files[relPath];
+        const targetPath = (0, path_1.join)(cwd, relPath);
+        let onDiskContent = null;
+        try {
+            onDiskContent = (0, fs_1.readFileSync)(targetPath, "utf-8");
+        }
+        catch {
+            // file doesn't exist
+        }
+        if (onDiskContent === null) {
+            actions.push({ action: "add", relPath, content: df.content });
+            continue;
+        }
+        const normalizedDisk = (0, template_1.stripDates)(onDiskContent);
+        const normalizedDesired = (0, template_1.stripDates)(df.content);
+        if (normalizedDisk === normalizedDesired) {
+            actions.push({ action: "skip", relPath });
+            continue;
+        }
+        const sourceChanged = !lastEntry || lastEntry.sourceHash !== df.identity;
+        if (df.category === "opencode-json") {
+            actions.push({ action: "merge", relPath, content: df.content });
+        }
+        else if (sourceChanged && df.category === "agents-md") {
+            actions.push({ action: "backup", relPath, content: df.content });
+        }
+        else if (sourceChanged) {
+            actions.push({ action: "update", relPath, content: df.content });
+        }
+        else {
+            actions.push({ action: "warn", relPath });
+        }
+    }
+    if (manifest) {
+        for (const relPath of Object.keys(manifest.files)) {
+            if (!desired.has(relPath)) {
+                actions.push({ action: "remove", relPath });
+            }
+        }
+    }
+    return actions;
+}
+function mergeOpencodeJson(desiredContent, currentContent) {
+    const desired = JSON.parse(desiredContent);
+    const current = JSON.parse(currentContent);
+    const result = { ...desired };
+    if (current.mcp && typeof current.mcp === "object") {
+        const resultMcp = result.mcp;
+        for (const [key, value] of Object.entries(current.mcp)) {
+            if (!(key in resultMcp)) {
+                resultMcp[key] = value;
+            }
+        }
+    }
+    if (current.command && typeof current.command === "object") {
+        const resultCmd = result.command;
+        for (const [key, value] of Object.entries(current.command)) {
+            if (!(key in resultCmd)) {
+                resultCmd[key] = value;
+            }
+        }
+    }
+    for (const key of Object.keys(current)) {
+        if (!(key in result)) {
+            result[key] = current[key];
+        }
+    }
+    return JSON.stringify(result, null, 2) + "\n";
+}

package/dist/src/template.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.processTemplate = processTemplate;
+exports.stripDates = stripDates;
 function processTemplate(content) {
     const now = new Date();
     const isoDate = now.toISOString().split("T")[0];
@@ -8,3 +9,8 @@ function processTemplate(content) {
         .replace(/\{\{FOOTER}}/g, `Last updated: ${isoDate}. This file extends the global rules in @AGENTS.md. Always check both files.`)
         .replace(/\{\{AGENTS_FOOTER}}/g, `This file was last updated: ${isoDate}. Always check the \`.agents/rules/\` directory for the most current language-specific guidelines.`);
 }
+function stripDates(content) {
+    return content
+        .replace(/Last updated: \d{4}-\d{2}-\d{2}\. This file extends the global rules in @AGENTS\.md\. Always check both files\./g, "{{FOOTER}}")
+        .replace(/This file was last updated: \d{4}-\d{2}-\d{2}\. Always check the `\.agents\/rules\/` directory for the most current language-specific guidelines\./g, "{{AGENTS_FOOTER}}");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubmatto/ai-kit",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "The AI configuration CLI from Club Matto",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
   },
   "dependencies": {
     "commander": "^14.0.3",
+    "fdir": "6.5.0",
     "gradient-string": "^2.0.0"
   },
   "devDependencies": {

package/src/commands/commit.md

@@ -8,8 +8,21 @@ Create a commit with the following format:
 
 **First line (one-liner):**
 
-- Use conventional commits format: `<type>: <description>`
-- Examples: `feat: add init command`, `fix: resolve path issue`, `docs: update README`
+- Use conventional commits format: `<type>(<scope>): <description>`
+- The **scope** is the project subdirectory — determine it from the changed files.
+
+  | Changed files             | Scope        |
+  |---------------------------|--------------|
+  | `fakedata/**`             | `fakedata`   |
+  | `ai-kit/**`               | `ai-kit`     |
+  | Mixed (multiple projects) | Pick primary |
+
+- If changes span **multiple projects**, pick the one with the most changes, or use
+  `type: description` (without scope) when there is no clear primary project.
+- Root-level files (e.g. `opencode.json`, `.github/`, `AGENTS.md`) and changes
+  spanning **all** projects get no scope.
+- Examples: `feat(fakedata): add csv output`, `fix(ai-kit): resolve sync crash`,
+  `docs: update contributing guide`
 
 **Body (bullet list):**
 
@@ -19,26 +32,41 @@ Create a commit with the following format:
 **Sign-off:**
 
 - End with: `created with the help of <MODEL>`
-- Use the current model name (e.g. "MiniMax", "GPT-4", "Claude")
+- Format the model name as lowercase, hyphenated: `<name>-<variant>`
+- Examples: `DeepSeek V4 Flash` → `deepseek-v4-flash`, `Claude Opus 4` → `claude-opus-4`
+
+## Examples
+
+**Single project — use scope:**
+
+```
+feat(fakedata): add csv output format
+
+- Added --format csv flag to generate command
+- Implemented CSV writer with header detection
+- Added tests for CSV output
+
+created with the help of deepseek-v4-flash
+```
 
-## Example
+**Cross-project or root — no scope:**
 
 ```
-feat: add init and update commands
+ci: add shared release workflow for Go projects
 
-- Created init command for first-time setup
-- Added manifest tracking in .agents/.ai-kit
-- Implemented update command for version sync
-- Added --skip-opencode option
+- Created tools/go-release with build, archive, and formula generation
+- Updated fakedata release workflow to use shared tool
+- Added release documentation
 
-created with the help of MiniMax
+created with the help of deepseek-v4-flash
 ```
 
 ## Process
 
 1. First, review all changes with `git status` and `git diff`
 2. If there changes you did not make, ask if you should include them
-3. Write a concise one-liner following conventional commits
-4. List the key changes as bullet points
-5. Add the sign-off line with the current model
-6. Commit with `git commit -m "your message"`
+3. Determine the scope from the changed file paths
+4. Write a concise one-liner following `<type>(<scope>): <description>`
+5. List the key changes as bullet points
+6. Add the sign-off line with the current model
+7. Commit with `git commit -m "your message"`