thomas-agentkit 0.3.0 → 0.4.0

package/README.md

@@ -14,16 +14,26 @@ Install templates into the current directory:
 npx thomas-agentkit init
 ```
 
+By default, `init` opens a short interactive setup flow in terminals. After choosing install options, you can optionally personalize repository-level template placeholders such as project name, description, issue tracker, docs paths, stack summary, and project commands.
+
 Install into another directory:
 
 ```bash
 npx thomas-agentkit init ./my-project
 ```
 
+Accept defaults without prompts:
+
+```bash
+npx thomas-agentkit init --yes
+```
+
+`--yes` keeps installed templates generic and leaves placeholders for later editing.
+
 Preview changes without writing files:
 
 ```bash
-npx thomas-agentkit init --dry-run
+npx thomas-agentkit init --yes --dry-run
 ```
 
 Overwrite existing files:
@@ -44,7 +54,7 @@ Preview updates without writing files:
 npx thomas-agentkit update --dry-run
 ```
 
-Use the optional interactive flow:
+Explicitly request the interactive flow:
 
 ```bash
 npx thomas-agentkit init --interactive
@@ -97,6 +107,8 @@ Generated content
 
 `agentkit update` only replaces content inside matching managed blocks. User edits before or after those blocks are preserved. Existing legacy files without managed blocks are reported as unmanaged and left untouched.
 
+Interactive personalization only applies during `agentkit init` when files are created or overwritten. It does not write a config file, and `agentkit update` does not reapply personalized values.
+
 ## Presets
 
 Presets add stack-specific guidance without scaffolding framework app files.
@@ -122,8 +134,8 @@ Options:
 
 - `--force`: overwrite existing files
 - `--dry-run`: print planned changes without writing files
-- `-i, --interactive`: prompt for install options
-- `-y, --yes`: accept defaults for non-interactive runs
+- `-i, --interactive`: explicitly prompt for install options
+- `-y, --yes`: accept defaults without prompts
 - `--preset <name>`: install stack-specific guidance (`next`, `sveltekit`, `express`, `convex`, `fullstack`)
 - `--list`: list bundled template files
 - `--list-presets`: list available presets
@@ -136,7 +148,7 @@ For `agentkit update`, `--preset <name>` refreshes preset-specific managed conte
 
 ```bash
 npm install
-npm run dev -- init ./tmp-demo --dry-run
+npm run dev -- init ./tmp-demo --yes --dry-run
 npm run build
 npm test
 ```

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { confirm, isCancel, select, text } from "@clack/prompts";
+import { confirm, intro, isCancel, multiselect, select, text } from "@clack/prompts";
 import { Command } from "commander";
 import { constants as fsConstants } from "node:fs";
 import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
@@ -11,6 +11,8 @@ const packageRoot = path.resolve(__dirname, "..");
 const templatesDir = path.join(packageRoot, "templates");
 const packageJsonPath = path.join(packageRoot, "package.json");
 const validPresets = ["next", "sveltekit", "express", "convex", "fullstack"];
+const validProjectTypes = ["generic", ...validPresets];
+const validAiTools = ["codex", "cursor", "claude", "copilot"];
 const presetLabels = {
     next: "Next.js",
     sveltekit: "SvelteKit",
@@ -18,6 +20,17 @@ const presetLabels = {
     convex: "Convex",
     fullstack: "Fullstack",
 };
+const aiToolFiles = {
+    codex: ["AGENTS.md"],
+    cursor: [".cursor/rules/agentkit.md"],
+    claude: ["CLAUDE.md"],
+    copilot: [".github/copilot-instructions.md"],
+};
+const templateSetFiles = {
+    minimal: ["AGENTS.md"],
+    standard: ["AGENTS.md", "CODE-QUALITY.md", "DESIGN-SYSTEM.md", "WORKFLOWS.md"],
+    full: [],
+};
 const stackGuidance = {
     next: `# Stack Guidance
 
@@ -101,6 +114,12 @@ async function getTemplateFiles(dir = templatesDir, base = templatesDir) {
 function isPresetName(value) {
     return validPresets.includes(value);
 }
+function isProjectTypeName(value) {
+    return validProjectTypes.includes(value);
+}
+function isAiToolName(value) {
+    return validAiTools.includes(value);
+}
 function formatPresetList() {
     return validPresets.join(", ");
 }
@@ -114,6 +133,38 @@ function resolvePreset(preset) {
     }
     return normalizedPreset;
 }
+export function resolveProjectPreset(projectType) {
+    if (!projectType) {
+        return undefined;
+    }
+    const normalizedProjectType = projectType.toLowerCase();
+    if (!isProjectTypeName(normalizedProjectType)) {
+        throw new Error(`Unknown project type "${projectType}". Valid project types: ${validProjectTypes.join(", ")}.`);
+    }
+    return normalizedProjectType === "generic" ? undefined : normalizedProjectType;
+}
+export function getFilesForAiTools(aiTools) {
+    const files = new Set();
+    for (const aiTool of aiTools) {
+        if (!isAiToolName(aiTool)) {
+            throw new Error(`Unknown AI tool "${aiTool}". Valid AI tools: ${validAiTools.join(", ")}.`);
+        }
+        for (const file of aiToolFiles[aiTool]) {
+            files.add(file);
+        }
+    }
+    return [...files].sort();
+}
+export function getFilesForTemplateSet(templateSet, allTemplateFiles) {
+    if (templateSet === "full") {
+        return [...allTemplateFiles].sort();
+    }
+    return templateSetFiles[templateSet].filter((file) => allTemplateFiles.includes(file)).sort();
+}
+export function getSelectedTemplateFiles(templateSet, aiTools, allTemplateFiles) {
+    const files = new Set([...getFilesForTemplateSet(templateSet, allTemplateFiles), ...getFilesForAiTools(aiTools)]);
+    return [...files].filter((file) => allTemplateFiles.includes(file)).sort();
+}
 function getStackGuidance(preset) {
     return preset === "fullstack" ? fullstackGuidance : stackGuidance[preset];
 }
@@ -140,9 +191,190 @@ function addStackReference(file, content, preset) {
     }
     return `${content.trimEnd()}\n${stackNote}`;
 }
+function cleanPersonalizationValue(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function replaceIfProvided(content, placeholder, value) {
+    const replacement = cleanPersonalizationValue(value);
+    return replacement ? content.replaceAll(placeholder, replacement) : content;
+}
+function getProvidedCommands(values) {
+    return [values.testCommand, values.lintCommand, values.buildCommand]
+        .map(cleanPersonalizationValue)
+        .filter((command) => Boolean(command));
+}
+function commandDescription(command, kind) {
+    const descriptions = {
+        test: "Run tests",
+        lint: "Run lint checks",
+        build: "Build or check the project",
+    };
+    return descriptions[kind] ?? command;
+}
+function replaceCommandBlock(content, commands) {
+    if (commands.length === 0) {
+        return content;
+    }
+    const commandBlock = ["```bash", ...commands, "```"].join("\n");
+    return content
+        .replace(/```bash\nnpm install\nnpm test\nnpm run build\nnpm run lint\n```/, commandBlock)
+        .replace(/```bash\nnpm test\nnpm run lint\nnpm run build\n```/, commandBlock);
+}
+function replaceAgentCommandTable(content, values) {
+    const rows = [
+        cleanPersonalizationValue(values.testCommand)
+            ? `| \`${cleanPersonalizationValue(values.testCommand)}\` | ${commandDescription(values.testCommand ?? "", "test")} |`
+            : undefined,
+        cleanPersonalizationValue(values.lintCommand)
+            ? `| \`${cleanPersonalizationValue(values.lintCommand)}\` | ${commandDescription(values.lintCommand ?? "", "lint")} |`
+            : undefined,
+        cleanPersonalizationValue(values.buildCommand)
+            ? `| \`${cleanPersonalizationValue(values.buildCommand)}\` | ${commandDescription(values.buildCommand ?? "", "build")} |`
+            : undefined,
+    ].filter((row) => Boolean(row));
+    if (rows.length === 0) {
+        return content;
+    }
+    const nextTable = ["| Command | Description |", "| --- | --- |", ...rows].join("\n");
+    return content.replace(/\| Command \| Description \|\n\| --- \| --- \|\n\| `npm run dev` \| Start the local development server \|\n\| `npm test` \| Run tests \|\n\| `npm run lint` \| Run lint checks \|\n\| `npm run build` \| Build the project \|/, nextTable);
+}
+function replaceStackSummary(content, stackSummary) {
+    const summary = cleanPersonalizationValue(stackSummary);
+    if (!summary) {
+        return content;
+    }
+    const stackItems = summary
+        .split(/\r?\n|,/)
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => `- ${item}`)
+        .join("\n");
+    return content.replace(/- \[Primary framework\]\n- \[Language\/runtime\]\n- \[Backend\/data layer\]\n- \[Styling system\]\n- \[Test tools\]\n- \[Lint\/format tools\]/, stackItems);
+}
+export function personalizeTemplateContent(file, content, values) {
+    if (!values) {
+        return content;
+    }
+    if (file === "PRD-TEMPLATE.md" ||
+        file === "IMPLEMENTATION-BRIEF-TEMPLATE.md" ||
+        file === ".github/pull_request_template.md") {
+        return content;
+    }
+    let personalized = content;
+    if (file === "AGENTS.md" || file === "DESIGN-SYSTEM.md") {
+        personalized = replaceIfProvided(personalized, "[Project Name]", values.projectName);
+    }
+    if (file === "AGENTS.md") {
+        personalized = replaceIfProvided(personalized, "[short project description]", values.projectDescription);
+        personalized = replaceIfProvided(personalized, "[issue tracker, e.g. Linear or GitHub Issues]", values.issueTracker);
+        personalized = replaceIfProvided(personalized, "[design system path, e.g. docs/design-system.md]", values.designSystemPath);
+        personalized = replaceIfProvided(personalized, "[design system path]", values.designSystemPath);
+        personalized = replaceIfProvided(personalized, "[briefs path, e.g. docs/briefs]", values.briefsPath);
+        personalized = replaceIfProvided(personalized, "[test command, e.g. npm test]", values.testCommand);
+        personalized = replaceIfProvided(personalized, "[lint command, e.g. npm run lint]", values.lintCommand);
+        personalized = replaceIfProvided(personalized, "[build/check command, e.g. npm run build]", values.buildCommand);
+        personalized = replaceAgentCommandTable(personalized, values);
+        personalized = replaceStackSummary(personalized, values.stackSummary);
+    }
+    if (file === "CLAUDE.md" || file === "CODE-QUALITY.md") {
+        personalized = replaceCommandBlock(personalized, getProvidedCommands(values));
+    }
+    return personalized;
+}
+async function promptForPersonalization() {
+    const shouldPersonalize = await confirm({
+        message: "Personalize template placeholders?",
+        initialValue: false,
+    });
+    if (isCancel(shouldPersonalize)) {
+        process.exit(130);
+    }
+    if (!shouldPersonalize) {
+        return undefined;
+    }
+    const projectName = await text({
+        message: "Project name",
+        placeholder: "[Project Name]",
+    });
+    if (isCancel(projectName)) {
+        process.exit(130);
+    }
+    const projectDescription = await text({
+        message: "Short project description",
+        placeholder: "[short project description]",
+    });
+    if (isCancel(projectDescription)) {
+        process.exit(130);
+    }
+    const issueTracker = await text({
+        message: "Issue tracker name",
+        placeholder: "Linear or GitHub Issues",
+    });
+    if (isCancel(issueTracker)) {
+        process.exit(130);
+    }
+    const designSystemPath = await text({
+        message: "Design system path",
+        placeholder: "docs/design-system.md",
+    });
+    if (isCancel(designSystemPath)) {
+        process.exit(130);
+    }
+    const briefsPath = await text({
+        message: "Briefs path",
+        placeholder: "docs/briefs",
+    });
+    if (isCancel(briefsPath)) {
+        process.exit(130);
+    }
+    const testCommand = await text({
+        message: "Test command",
+        placeholder: "npm test",
+    });
+    if (isCancel(testCommand)) {
+        process.exit(130);
+    }
+    const lintCommand = await text({
+        message: "Lint command",
+        placeholder: "npm run lint",
+    });
+    if (isCancel(lintCommand)) {
+        process.exit(130);
+    }
+    const buildCommand = await text({
+        message: "Build/check command",
+        placeholder: "npm run build",
+    });
+    if (isCancel(buildCommand)) {
+        process.exit(130);
+    }
+    const stackSummary = await text({
+        message: "Stack summary",
+        placeholder: "Next.js, TypeScript, Tailwind CSS, Vitest",
+    });
+    if (isCancel(stackSummary)) {
+        process.exit(130);
+    }
+    return {
+        projectName,
+        projectDescription,
+        issueTracker,
+        designSystemPath,
+        briefsPath,
+        testCommand,
+        lintCommand,
+        buildCommand,
+        stackSummary,
+    };
+}
+async function buildInitTemplateContent(file, preset, personalization) {
+    const content = await buildTemplateContent(file, preset);
+    return personalizeTemplateContent(file, content, personalization);
+}
 async function installTemplates(targetArg, options) {
     const targetDir = path.resolve(process.cwd(), targetArg || ".");
-    const files = await getTemplateFiles();
+    const files = options.files ?? (await getTemplateFiles());
     const preset = resolvePreset(options.preset);
     const created = [];
     const skipped = [];
@@ -150,7 +382,6 @@ async function installTemplates(targetArg, options) {
         await mkdir(targetDir, { recursive: true });
     }
     for (const file of files) {
-        const source = path.join(templatesDir, file);
         const destination = path.join(targetDir, file);
         const destinationExists = await exists(destination);
         if (destinationExists && !options.force) {
@@ -161,11 +392,11 @@ async function installTemplates(targetArg, options) {
         if (!options.dryRun) {
             await mkdir(path.dirname(destination), { recursive: true });
             if (preset && file === "AGENTS.md") {
-                const content = await readFile(source, "utf8");
-                await writeFile(destination, wrapManagedBlock(file, addStackReference(file, content, preset)));
+                const content = await buildInitTemplateContent(file, preset, options.personalization);
+                await writeFile(destination, wrapManagedBlock(file, content));
             }
             else {
-                const content = await readFile(source, "utf8");
+                const content = await buildInitTemplateContent(file, preset, options.personalization);
                 await writeFile(destination, wrapManagedBlock(file, content));
             }
         }
@@ -301,42 +532,95 @@ function printUpdateResult(result, dryRun = false) {
 }
 async function resolveInteractiveTarget(target, options) {
     const providedPreset = resolvePreset(options.preset);
-    if (!options.interactive) {
+    const shouldPrompt = !options.yes && (options.interactive || process.stdin.isTTY);
+    if (!shouldPrompt) {
         return target;
     }
-    const targetResponse = await text({
-        message: "Where should AgentKit install templates?",
-        placeholder: target || ".",
-        defaultValue: target || ".",
-    });
-    if (isCancel(targetResponse)) {
-        process.exit(130);
+    intro("Welcome to AgentKit");
+    let resolvedTarget = target;
+    if (!target || target === ".") {
+        const targetResponse = await text({
+            message: "Where should AgentKit install files?",
+            placeholder: ".",
+            defaultValue: ".",
+        });
+        if (isCancel(targetResponse)) {
+            process.exit(130);
+        }
+        resolvedTarget = targetResponse || ".";
     }
-    const forceResponse = await confirm({
-        message: "Overwrite existing files?",
-        initialValue: Boolean(options.force),
+    if (!providedPreset) {
+        const projectTypeResponse = await select({
+            message: "What type of project is this?",
+            initialValue: "generic",
+            options: [
+                { label: "Generic TypeScript project", value: "generic" },
+                { label: "Next.js app", value: "next" },
+                { label: "SvelteKit app", value: "sveltekit" },
+                { label: "Express API", value: "express" },
+                { label: "Convex app", value: "convex" },
+                { label: "Fullstack app", value: "fullstack" },
+            ],
+        });
+        if (isCancel(projectTypeResponse)) {
+            process.exit(130);
+        }
+        options.preset = resolveProjectPreset(projectTypeResponse);
+    }
+    const aiToolResponse = await multiselect({
+        message: "Which AI tools do you use?",
+        initialValues: ["codex", "cursor", "claude"],
+        options: [
+            { label: "Codex", value: "codex" },
+            { label: "Cursor", value: "cursor" },
+            { label: "Claude Code", value: "claude" },
+            { label: "GitHub Copilot", value: "copilot" },
+        ],
     });
-    if (isCancel(forceResponse)) {
+    if (isCancel(aiToolResponse)) {
         process.exit(130);
     }
-    const presetResponse = await select({
-        message: "Which preset should AgentKit use?",
-        initialValue: providedPreset || "generic",
+    const templateSetResponse = await select({
+        message: "Which template set do you want?",
+        initialValue: "standard",
         options: [
-            { label: "Generic", value: "generic" },
-            { label: "Next.js", value: "next" },
-            { label: "SvelteKit", value: "sveltekit" },
-            { label: "Express", value: "express" },
-            { label: "Convex", value: "convex" },
-            { label: "Fullstack", value: "fullstack" },
+            { label: "Minimal", value: "minimal" },
+            { label: "Standard", value: "standard" },
+            { label: "Full", value: "full" },
         ],
     });
-    if (isCancel(presetResponse)) {
+    if (isCancel(templateSetResponse)) {
         process.exit(130);
     }
-    options.preset = presetResponse === "generic" ? undefined : presetResponse;
-    options.force = forceResponse;
-    return targetResponse || ".";
+    const templateFiles = await getTemplateFiles();
+    options.files = getSelectedTemplateFiles(templateSetResponse, aiToolResponse, templateFiles);
+    if (!options.force) {
+        const preset = resolvePreset(options.preset);
+        const installFiles = preset ? [...options.files, "STACK.md"] : options.files;
+        const targetDir = path.resolve(process.cwd(), resolvedTarget || ".");
+        const existingFiles = [];
+        for (const file of installFiles) {
+            if (await exists(path.join(targetDir, file))) {
+                existingFiles.push(file);
+            }
+        }
+        if (existingFiles.length > 0) {
+            const conflictResponse = await select({
+                message: `Existing files found: ${existingFiles.join(", ")}. How should AgentKit handle conflicts?`,
+                initialValue: "skip",
+                options: [
+                    { label: "Skip existing files", value: "skip" },
+                    { label: "Overwrite existing files", value: "overwrite" },
+                ],
+            });
+            if (isCancel(conflictResponse)) {
+                process.exit(130);
+            }
+            options.force = conflictResponse === "overwrite";
+        }
+    }
+    options.personalization = await promptForPersonalization();
+    return resolvedTarget || ".";
 }
 async function main() {
     if (process.argv.slice(2).includes("--list")) {
@@ -365,7 +649,7 @@ Examples:
   agentkit init
   agentkit update
   agentkit init --preset next
-  agentkit init ./my-project --dry-run
+  agentkit init ./my-project --yes --dry-run
   agentkit --list-presets
   agentkit --list`);
     program
@@ -394,8 +678,10 @@ Examples:
     });
     await program.parseAsync(process.argv);
 }
-main().catch((error) => {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(message);
-    process.exitCode = 1;
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        process.exitCode = 1;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
   "repository": {