thomas-agentkit 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Howard Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -32,18 +32,42 @@ Overwrite existing files:
 npx thomas-agentkit init --force
 ```
 
+Update AgentKit-managed template sections:
+
+```bash
+npx thomas-agentkit update
+```
+
+Preview updates without writing files:
+
+```bash
+npx thomas-agentkit update --dry-run
+```
+
 Use the optional interactive flow:
 
 ```bash
 npx thomas-agentkit init --interactive
 ```
 
+Install stack-specific agent guidance:
+
+```bash
+npx thomas-agentkit init --preset next
+```
+
 List bundled templates:
 
 ```bash
 npx thomas-agentkit --list
 ```
 
+List available presets:
+
+```bash
+npx thomas-agentkit --list-presets
+```
+
 ## Installed Files
 
 AgentKit copies these bundled files into the target project:
@@ -59,13 +83,37 @@ AgentKit copies these bundled files into the target project:
 - `.github/copilot-instructions.md`
 - `.github/pull_request_template.md`
 
+When a preset is selected, AgentKit also installs `STACK.md` and adds a note in `AGENTS.md` telling agents to read it before changing stack-specific code.
+
 Existing files are skipped by default so local edits are preserved. Use `--force` when you intentionally want to refresh files from the bundled package version.
 
+New installs wrap generated template content in AgentKit managed block markers:
+
+```html
+<!-- agentkit:start agents -->
+Generated content
+<!-- agentkit:end agents -->
+```
+
+`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.
+
+## Presets
+
+Presets add stack-specific guidance without scaffolding framework app files.
+
+- `next`
+- `sveltekit`
+- `express`
+- `convex`
+- `fullstack` (`Next.js` + `Convex`)
+
 ## CLI Reference
 
 ```text
-agentkit init [target] [--force] [--dry-run] [--interactive] [--yes]
+agentkit init [target] [--force] [--dry-run] [--interactive] [--yes] [--preset <name>]
+agentkit update [target] [--dry-run] [--preset <name>]
 agentkit --list
+agentkit --list-presets
 agentkit --help
 agentkit --version
 ```
@@ -76,10 +124,14 @@ Options:
 - `--dry-run`: print planned changes without writing files
 - `-i, --interactive`: prompt for install options
 - `-y, --yes`: accept defaults for non-interactive runs
+- `--preset <name>`: install stack-specific guidance (`next`, `sveltekit`, `express`, `convex`, `fullstack`)
 - `--list`: list bundled template files
+- `--list-presets`: list available presets
 - `-h, --help`: show help
 - `-v, --version`: show package version
 
+For `agentkit update`, `--preset <name>` refreshes preset-specific managed content, including `STACK.md`.
+
 ## Local Development
 
 ```bash
@@ -91,6 +143,35 @@ npm test
 
 The npm package is `thomas-agentkit`. The installed CLI command is `agentkit`, backed by the compiled TypeScript entrypoint at `dist/cli.js`.
 
+## Release
+
+Before publishing a new package version:
+
+1. Update the version in `package.json` intentionally.
+2. Run the full test suite:
+
+   ```bash
+   npm test
+   ```
+
+3. Run the package build step:
+
+   ```bash
+   npm run prepack
+   ```
+
+4. Inspect the publish contents:
+
+   ```bash
+   npm pack --dry-run
+   ```
+
+5. Publish to npm:
+
+   ```bash
+   npm publish
+   ```
+
 ## Philosophy
 
 AgentKit should stay:

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { confirm, isCancel, text } from "@clack/prompts";
+import { confirm, isCancel, select, text } from "@clack/prompts";
 import { Command } from "commander";
 import { constants as fsConstants } from "node:fs";
-import { access, copyFile, mkdir, readdir, readFile, stat } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
@@ -10,6 +10,63 @@ const __dirname = path.dirname(__filename);
 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 presetLabels = {
+    next: "Next.js",
+    sveltekit: "SvelteKit",
+    express: "Express",
+    convex: "Convex",
+    fullstack: "Fullstack",
+};
+const stackGuidance = {
+    next: `# Stack Guidance
+
+## Next.js
+
+- Follow the app's existing routing model before adding new routes or layouts.
+- Keep server and client component boundaries explicit.
+- Prefer server components for data loading unless interactivity requires a client component.
+- Keep mutations in server actions, route handlers, or existing API layers based on local patterns.
+- Use established styling primitives and design tokens before adding new UI conventions.
+- Validate external input at route, action, and API boundaries.
+- Run the project's Next.js build or typecheck before handoff when touching routing, rendering, or data loading.
+`,
+    sveltekit: `# Stack Guidance
+
+## SvelteKit
+
+- Follow the existing route, load, action, and server module patterns before adding new files.
+- Keep browser-only code out of server load functions and server modules.
+- Use SvelteKit form actions and load functions where they fit the workflow.
+- Validate external input at action, endpoint, and server boundary entrypoints.
+- Reuse existing stores, components, and styling conventions before creating new ones.
+- Run the project's SvelteKit check or build before handoff when touching routes, rendering, or data loading.
+`,
+    express: `# Stack Guidance
+
+## Express
+
+- Keep route handlers small and move repeated business logic only when duplication is real.
+- Validate request params, query strings, and bodies at the route boundary.
+- Return explicit status codes and predictable response shapes.
+- Use the project's existing middleware order and error handling pattern.
+- Avoid adding global middleware or dependencies for narrow endpoint changes.
+- Add focused tests for route behavior, validation failures, and error paths.
+`,
+    convex: `# Stack Guidance
+
+## Convex
+
+- Follow generated Convex types and local function patterns before editing schema or functions.
+- Keep queries, mutations, and actions focused on one clear responsibility.
+- Validate arguments with Convex validators at public function boundaries.
+- Preserve explicit authorization checks for user-scoped data.
+- Prefer indexes and schema changes that match real query needs.
+- Run Convex codegen or the project's Convex validation command after schema or function changes.
+`,
+};
+const fullstackGuidance = `${stackGuidance.next}
+${stackGuidance.convex.replace("# Stack Guidance\n\n", "")}`;
 async function exists(filePath) {
     try {
         await access(filePath, fsConstants.F_OK);
@@ -41,9 +98,52 @@ async function getTemplateFiles(dir = templatesDir, base = templatesDir) {
     }));
     return files.flat().sort();
 }
+function isPresetName(value) {
+    return validPresets.includes(value);
+}
+function formatPresetList() {
+    return validPresets.join(", ");
+}
+function resolvePreset(preset) {
+    if (!preset) {
+        return undefined;
+    }
+    const normalizedPreset = preset.toLowerCase();
+    if (!isPresetName(normalizedPreset)) {
+        throw new Error(`Unknown preset "${preset}". Valid presets: ${formatPresetList()}.`);
+    }
+    return normalizedPreset;
+}
+function getStackGuidance(preset) {
+    return preset === "fullstack" ? fullstackGuidance : stackGuidance[preset];
+}
+function getTemplateId(file) {
+    return file
+        .replace(/\.[^/.]+$/, "")
+        .replace(/^\./, "")
+        .split("/")
+        .filter(Boolean)
+        .join("-")
+        .toLowerCase();
+}
+function wrapManagedBlock(file, content) {
+    const id = getTemplateId(file);
+    return `<!-- agentkit:start ${id} -->\n${content.trimEnd()}\n<!-- agentkit:end ${id} -->\n`;
+}
+function addStackReference(file, content, preset) {
+    if (file !== "AGENTS.md" || !preset) {
+        return content;
+    }
+    const stackNote = `\nPreset: ${presetLabels[preset]}. Agents must read \`STACK.md\` before changing stack-specific code.\n`;
+    if (content.includes("## Guidelines")) {
+        return content.replace("\n## Guidelines", `${stackNote}\n## Guidelines`);
+    }
+    return `${content.trimEnd()}\n${stackNote}`;
+}
 async function installTemplates(targetArg, options) {
     const targetDir = path.resolve(process.cwd(), targetArg || ".");
     const files = await getTemplateFiles();
+    const preset = resolvePreset(options.preset);
     const created = [];
     const skipped = [];
     if (!options.dryRun) {
@@ -60,11 +160,104 @@ async function installTemplates(targetArg, options) {
         created.push(file);
         if (!options.dryRun) {
             await mkdir(path.dirname(destination), { recursive: true });
-            await copyFile(source, destination);
+            if (preset && file === "AGENTS.md") {
+                const content = await readFile(source, "utf8");
+                await writeFile(destination, wrapManagedBlock(file, addStackReference(file, content, preset)));
+            }
+            else {
+                const content = await readFile(source, "utf8");
+                await writeFile(destination, wrapManagedBlock(file, content));
+            }
+        }
+    }
+    if (preset) {
+        const stackFile = "STACK.md";
+        const destination = path.join(targetDir, stackFile);
+        const destinationExists = await exists(destination);
+        if (destinationExists && !options.force) {
+            skipped.push(stackFile);
+        }
+        else {
+            created.push(stackFile);
+            if (!options.dryRun) {
+                await writeFile(destination, wrapManagedBlock(stackFile, getStackGuidance(preset)));
+            }
         }
     }
     return { targetDir, created, skipped };
 }
+function replaceManagedBlock(file, existingContent, nextContent) {
+    const id = getTemplateId(file);
+    const startMarker = `<!-- agentkit:start ${id} -->`;
+    const endMarker = `<!-- agentkit:end ${id} -->`;
+    const startIndex = existingContent.indexOf(startMarker);
+    const endIndex = existingContent.indexOf(endMarker);
+    if (startIndex === -1 && endIndex === -1) {
+        return undefined;
+    }
+    if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+        throw new Error(`Malformed managed block in ${file}.`);
+    }
+    const afterEndIndex = endIndex + endMarker.length;
+    const replacement = wrapManagedBlock(file, nextContent).trimEnd();
+    return `${existingContent.slice(0, startIndex)}${replacement}${existingContent.slice(afterEndIndex)}`;
+}
+async function buildTemplateContent(file, preset) {
+    if (file === "STACK.md") {
+        if (!preset) {
+            throw new Error("STACK.md requires a preset.");
+        }
+        return getStackGuidance(preset);
+    }
+    const source = path.join(templatesDir, file);
+    const content = await readFile(source, "utf8");
+    return addStackReference(file, content, preset);
+}
+async function updateTemplates(targetArg, options) {
+    const targetDir = path.resolve(process.cwd(), targetArg || ".");
+    const preset = resolvePreset(options.preset);
+    const files = preset ? [...(await getTemplateFiles()), "STACK.md"] : await getTemplateFiles();
+    const created = [];
+    const updated = [];
+    const skipped = [];
+    const malformed = [];
+    const unchanged = [];
+    for (const file of files) {
+        const destination = path.join(targetDir, file);
+        const nextContent = await buildTemplateContent(file, preset);
+        const destinationExists = await exists(destination);
+        if (!destinationExists) {
+            created.push(file);
+            if (!options.dryRun) {
+                await mkdir(path.dirname(destination), { recursive: true });
+                await writeFile(destination, wrapManagedBlock(file, nextContent));
+            }
+            continue;
+        }
+        const existingContent = await readFile(destination, "utf8");
+        let updatedContent;
+        try {
+            updatedContent = replaceManagedBlock(file, existingContent, nextContent);
+        }
+        catch {
+            malformed.push(file);
+            continue;
+        }
+        if (updatedContent === undefined) {
+            skipped.push(file);
+            continue;
+        }
+        if (updatedContent === existingContent) {
+            unchanged.push(file);
+            continue;
+        }
+        updated.push(file);
+        if (!options.dryRun) {
+            await writeFile(destination, updatedContent);
+        }
+    }
+    return { targetDir, created, updated, skipped, malformed, unchanged };
+}
 function printInstallResult(result, dryRun = false) {
     const action = dryRun ? "Would install" : "Installed";
     console.log(`${action} AgentKit files in ${result.targetDir}`);
@@ -79,7 +272,35 @@ function printInstallResult(result, dryRun = false) {
         console.log("No bundled templates found.");
     }
 }
+function printUpdateResult(result, dryRun = false) {
+    const action = dryRun ? "Would update" : "Updated";
+    console.log(`${action} AgentKit files in ${result.targetDir}`);
+    if (result.created.length > 0) {
+        console.log(`${dryRun ? "Would create" : "Created"}: ${result.created.join(", ")}`);
+    }
+    if (result.updated.length > 0) {
+        console.log(`${dryRun ? "Would update" : "Updated"}: ${result.updated.join(", ")}`);
+    }
+    if (result.unchanged.length > 0) {
+        console.log(`Already current: ${result.unchanged.join(", ")}`);
+    }
+    if (result.skipped.length > 0) {
+        console.log(`Skipped unmanaged: ${result.skipped.join(", ")}`);
+        console.log("Add AgentKit managed block markers before updating these files.");
+    }
+    if (result.malformed.length > 0) {
+        console.log(`Skipped malformed: ${result.malformed.join(", ")}`);
+        console.log("Fix AgentKit managed block markers before updating these files.");
+    }
+    if (result.created.length === 0 &&
+        result.updated.length === 0 &&
+        result.skipped.length === 0 &&
+        result.malformed.length === 0) {
+        console.log("All managed AgentKit files are current.");
+    }
+}
 async function resolveInteractiveTarget(target, options) {
+    const providedPreset = resolvePreset(options.preset);
     if (!options.interactive) {
         return target;
     }
@@ -98,6 +319,22 @@ async function resolveInteractiveTarget(target, options) {
     if (isCancel(forceResponse)) {
         process.exit(130);
     }
+    const presetResponse = await select({
+        message: "Which preset should AgentKit use?",
+        initialValue: providedPreset || "generic",
+        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" },
+        ],
+    });
+    if (isCancel(presetResponse)) {
+        process.exit(130);
+    }
+    options.preset = presetResponse === "generic" ? undefined : presetResponse;
     options.force = forceResponse;
     return targetResponse || ".";
 }
@@ -109,17 +346,27 @@ async function main() {
         }
         return;
     }
+    if (process.argv.slice(2).includes("--list-presets")) {
+        for (const preset of validPresets) {
+            console.log(preset);
+        }
+        return;
+    }
     const program = new Command();
     program
         .name("agentkit")
         .description("Bootstrap AI-agent-ready repository docs and workflow templates.")
         .version(await readPackageVersion(), "-v, --version")
         .option("--list", "list bundled template files")
+        .option("--list-presets", "list available presets")
         .addHelpText("after", `
 
 Examples:
   agentkit init
+  agentkit update
+  agentkit init --preset next
   agentkit init ./my-project --dry-run
+  agentkit --list-presets
   agentkit --list`);
     program
         .command("init")
@@ -129,11 +376,22 @@ Examples:
         .option("--dry-run", "print planned changes without writing files")
         .option("-i, --interactive", "prompt for install options")
         .option("-y, --yes", "accept defaults for non-interactive runs")
+        .option("--preset <name>", `install stack-specific guidance (${formatPresetList()})`)
         .action(async (target, options) => {
         const resolvedTarget = await resolveInteractiveTarget(target, options);
         const result = await installTemplates(resolvedTarget, options);
         printInstallResult(result, Boolean(options.dryRun));
     });
+    program
+        .command("update")
+        .description("update AgentKit managed template blocks in a project")
+        .argument("[target]", "target project directory", ".")
+        .option("--dry-run", "print planned changes without writing files")
+        .option("--preset <name>", `update stack-specific guidance (${formatPresetList()})`)
+        .action(async (target, options) => {
+        const result = await updateTemplates(target, options);
+        printUpdateResult(result, Boolean(options.dryRun));
+    });
     await program.parseAsync(process.argv);
 }
 main().catch((error) => {

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/howie1329/Howard-AgentKit.git"
+  },
+  "homepage": "https://github.com/howie1329/Howard-AgentKit#readme",
+  "bugs": {
+    "url": "https://github.com/howie1329/Howard-AgentKit/issues"
+  },
+  "keywords": [
+    "agentkit",
+    "ai",
+    "agents",
+    "codex",
+    "cli",
+    "scaffolding",
+    "templates"
+  ],
   "type": "module",
   "bin": {
     "agentkit": "./dist/cli.js"