thomas-agentkit 0.7.0 → 0.9.0-alpha.0

package/README.md

@@ -6,14 +6,81 @@ It installs reusable agent instructions, workflow guides, quality checklists, de
 
 AgentKit is not an AI agent. It is a small scaffolding tool for making repositories easier and safer to work on with AI-assisted development.
 
+## Bootstrap paths
+
+AgentKit supports two first-time setup paths. Pick one — they are not interchangeable.
+
+| | Template path | Skill path |
+| --- | --- | --- |
+| **CLI command** | `agentkit init` | `agentkit skill install` |
+| **When to use** | Immediate offline setup; you want files now | Agent-guided setup; guidance created from your repo in a later session |
+| **What you get** | Bundled `.md` templates copied into the project | Bundled `agentkit` Agent Skill installed; no guidance `.md` files yet |
+| **Ongoing maintenance** | CLI `agentkit update` (managed-block merge) | Skill routes in your agent: `/agentkit update`, `/agentkit doctor`, `/agentkit repair`, `/agentkit learn` |
+| **Config** | `installMode: template` | `installMode: skill` |
+
+```text
+FIRST-TIME SETUP (terminal)
+├── agentkit init              → copies templates, installMode: template
+└── agentkit skill install     → copies skill to .agents/skills/agentkit/, installMode: skill
+
+ONGOING WORK (agent + skill path only)
+├── /agentkit init   → agent creates AGENTS.md and companion files from repo context
+├── /agentkit update → agent syncs guidance after code changes
+├── /agentkit doctor → agent audits guidance quality
+├── /agentkit repair → agent repairs guidance structure when explicitly requested
+└── /agentkit learn  → agent teaches what changed after implementation
+```
+
+Interactive `agentkit init` asks whether to copy templates or install the AgentKit skill, then runs the chosen path in the same session.
+
 ## Usage
 
+### Template path
+
 Install templates into the current directory:
 
 ```bash
 npx thomas-agentkit init
 ```
 
+### Skill path
+
+Install the bundled AgentKit skill (v0.9.x+). This does **not** create `AGENTS.md` or other guidance files — run `/agentkit init` in your agent afterward:
+
+```bash
+npx thomas-agentkit skill install
+```
+
+Preview skill install without writing files:
+
+```bash
+npx thomas-agentkit skill install --dry-run
+```
+
+Overwrite an existing skill install:
+
+```bash
+npx thomas-agentkit skill install --force
+```
+
+After install, the CLI prints:
+
+```text
+Installed AgentKit skill in .agents/skills/agentkit/
+Wrote agentkit.config.json (installMode: skill)
+
+Next step: In your agent, run agentkit init.
+The skill will create AGENTS.md and companion files from your repository.
+```
+
+After skill install, use the project-local skill from your agent:
+
+- `/agentkit init` creates missing guidance files from repository context.
+- `/agentkit update` syncs managed guidance with current repository context.
+- `/agentkit doctor` audits guidance quality without editing by default.
+- `/agentkit repair` repairs guidance structure, such as malformed managed blocks or thick AI adapters, after an explicit request.
+- `/agentkit learn` teaches recent codebase changes, design decisions, edge cases, validation, and impact without writing files by default.
+
 If the package is installed in a project, use the local `agentkit` binary:
 
 ```bash
@@ -77,6 +144,8 @@ Standardize install defaults with `agentkit.config.json`:
 
 ```json
 {
+  "installMode": "template",
+  "agentkitVersion": "0.9.0",
   "preset": "next",
   "templateSet": "standard",
   "designSystem": "linear",
@@ -105,7 +174,9 @@ npx thomas-agentkit init --write-config
 
 `--write-config` writes `agentkit.config.json` in the target directory. Existing config files are skipped by default; use `--force` to overwrite one intentionally.
 
-Config values are validated when loaded. Unknown config keys, invalid preset/template/design-system names, invalid AI tool names, and non-string personalization values exit with an error.
+`installMode` is `"template"` or `"skill"` and records how the project was bootstrapped. `agentkitVersion` records the package version at install time. Configs without `installMode` are treated as template-path installs.
+
+Config values are validated when loaded. Unknown config keys, invalid preset/template/design-system names, invalid AI tool names, invalid `installMode` values, and non-string personalization values exit with an error.
 
 List bundled templates:
 
@@ -166,7 +237,7 @@ Interactive personalization only applies during `agentkit init` when files are c
 Template set mappings:
 
 - `minimal`: `AGENTS.md`
-- `standard`: `AGENTS.md`, `CHANGE-EXPLANATION.md`, `CODE-QUALITY.md`, `DESIGN-SYSTEM.md`, `WORKFLOWS.md`, `.github/pull_request_template.md`
+- `standard`: `AGENTS.md`, `CHANGE-EXPLANATION.md`, `CODE-QUALITY.md`, `DESIGN-SYSTEM.md`, `.github/pull_request_template.md`
 - `full`: all bundled templates, including AI tool adapters and planning/testing/security guides
 
 AI tool mappings:
@@ -188,10 +259,30 @@ Presets add stack-specific guidance without scaffolding framework app files.
 - `convex`
 - `fullstack` (`Next.js` + `Convex`)
 
+## CLI vs agent commands
+
+The same names mean different things in the terminal vs in an agent session:
+
+| Name | Where | What |
+| --- | --- | --- |
+| `agentkit init` | Terminal | Install **templates** |
+| `agentkit skill install` | Terminal | Install **bundled skill** + config |
+| `agentkit init` | Agent | Create **guidance files** (skill path) |
+| `agentkit update` | Terminal | Template-path managed-block merge only |
+| `agentkit update` | Agent | Sync guidance to repo changes |
+| `agentkit doctor` | Agent | Audit guidance quality |
+| `agentkit repair` | Agent | Repair guidance structure after explicit request |
+| `agentkit learn` | Agent | Teach recent codebase changes and check understanding |
+
+Never use CLI `agentkit init` for skill installation.
+
+On skill-path repos (`installMode: skill`), CLI `agentkit update` prints an informational message and does not modify guidance files. Use `/agentkit update` in your agent for skill-path guidance sync.
+
 ## CLI Reference
 
 ```text
 agentkit init [target] [--force] [--dry-run] [--interactive] [--yes] [--write-config] [--preset <name>] [--design-system <name>]
+agentkit skill install [target] [--force] [--dry-run] [--yes] [--preset <name>] [--design-system <name>]
 agentkit update [target] [--dry-run] [--preset <name>] [--design-system <name>]
 agentkit --list
 agentkit --list-presets
@@ -206,7 +297,7 @@ Options:
 - `--dry-run`: print planned changes without writing files
 - `-i, --interactive`: explicitly prompt for install options
 - `-y, --yes`: accept defaults without prompts
-- `--write-config`: write resolved install defaults to `agentkit.config.json`
+- `--write-config`: write resolved template install defaults to `agentkit.config.json`
 - `--preset <name>`: install stack-specific guidance (`next`, `sveltekit`, `express`, `convex`, `fullstack`)
 - `--design-system <name>`: design system variant for `DESIGN-SYSTEM.md` (`linear`, `apple`)
 - `--list`: list bundled template files
@@ -268,3 +359,5 @@ AgentKit should stay:
 - safe by default
 - useful immediately
 - not overengineered
+
+Installed guidance is **AGENTS-first**: `AGENTS.md` is enough for daily coding, including required change explanations after file edits. Companion files are loaded on explicit triggers (UI, review, security, stack, planning when requested), not on every task. The `full` template set adds optional guides such as `WORKFLOWS.md`, `TESTING.md`, and planning templates.

package/dist/cli.js

@@ -5,6 +5,7 @@ import { constants as fsConstants, realpathSync } from "node:fs";
 import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { getSkillDestinationPaths, getSkillSourceDir, installSkill, listSkillFiles, printSkillInstallResult, } from "./skill-install.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, "..");
@@ -20,7 +21,16 @@ const designSystemLabels = {
     apple: "Apple-inspired",
 };
 const configFileName = "agentkit.config.json";
-const configKeys = ["preset", "templateSet", "aiTools", "designSystem", "personalization"];
+const configKeys = [
+    "installMode",
+    "agentkitVersion",
+    "preset",
+    "templateSet",
+    "aiTools",
+    "designSystem",
+    "personalization",
+];
+const validInstallModes = ["template", "skill"];
 const personalizationKeys = [
     "projectName",
     "projectDescription",
@@ -52,7 +62,6 @@ const templateSetFiles = {
         "CHANGE-EXPLANATION.md",
         "CODE-QUALITY.md",
         "DESIGN-SYSTEM.md",
-        "WORKFLOWS.md",
         ".github/pull_request_template.md",
     ],
     full: [],
@@ -129,7 +138,7 @@ async function collectInstallableTemplatePaths(dir, base) {
     for (const entry of entries) {
         const absolutePath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            if (dir === templatesDir && entry.name === "design-systems") {
+            if (dir === templatesDir && (entry.name === "design-systems" || entry.name === "skills")) {
                 continue;
             }
             discovered.push(...(await collectInstallableTemplatePaths(absolutePath, base)));
@@ -258,13 +267,31 @@ function readConfigPersonalization(value) {
     }
     return personalization;
 }
+function resolveInstallMode(installMode) {
+    const normalizedInstallMode = installMode.toLowerCase();
+    if (!validInstallModes.includes(normalizedInstallMode)) {
+        throw new Error(`Unknown install mode "${installMode}". Valid install modes: ${validInstallModes.join(", ")}.`);
+    }
+    return normalizedInstallMode;
+}
+export function getInstallMode(config) {
+    return config?.installMode ?? "template";
+}
 function parseConfig(rawConfig, configPath) {
     assertPlainObject(rawConfig, configFileName);
     assertKnownKeys(rawConfig, configKeys, configFileName);
     const preset = optionalConfigString(rawConfig, "preset");
     const templateSet = optionalConfigString(rawConfig, "templateSet");
     const designSystem = optionalConfigString(rawConfig, "designSystem");
+    const installMode = optionalConfigString(rawConfig, "installMode");
+    const agentkitVersion = optionalConfigString(rawConfig, "agentkitVersion");
     const config = {};
+    if (installMode !== undefined) {
+        config.installMode = resolveInstallMode(installMode);
+    }
+    if (agentkitVersion !== undefined) {
+        config.agentkitVersion = agentkitVersion;
+    }
     if (preset !== undefined) {
         config.preset = resolvePreset(preset);
     }
@@ -395,8 +422,10 @@ function cleanPersonalizationValue(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
-function getResolvedConfig(options) {
+function getResolvedConfig(options, installMode, agentkitVersion) {
     const config = {
+        installMode,
+        agentkitVersion,
         templateSet: options.templateSet ?? "standard",
         aiTools: options.aiTools ?? [],
         designSystem: effectiveDesignSystem(options.designSystem),
@@ -574,7 +603,7 @@ async function resolveInitTemplateFiles(options) {
     }
     return getSelectedTemplateFiles(options.templateSet ?? "standard", options.aiTools ?? [], allTemplateFiles);
 }
-async function installTemplates(targetArg, options) {
+async function installTemplates(targetArg, options, agentkitVersion) {
     const targetDir = path.resolve(process.cwd(), targetArg || ".");
     const files = await resolveInitTemplateFiles(options);
     const preset = resolvePreset(options.preset);
@@ -584,7 +613,7 @@ async function installTemplates(targetArg, options) {
         await mkdir(targetDir, { recursive: true });
     }
     if (options.writeConfig) {
-        await installFileIfAllowed(targetDir, configFileName, options, result, () => serializeConfig(getResolvedConfig(options)));
+        await installFileIfAllowed(targetDir, configFileName, options, result, () => serializeConfig(getResolvedConfig(options, "template", agentkitVersion)));
     }
     for (const file of files) {
         await installFileIfAllowed(targetDir, file, options, result, async () => {
@@ -791,7 +820,23 @@ async function promptForConflictStrategy(existingFiles) {
         ],
     }));
 }
-async function applyInteractiveSelections(resolvedTarget, providedPreset, options) {
+async function promptForBootstrapPath() {
+    return resolvePrompt(await select({
+        message: "How do you want to set up AgentKit?",
+        initialValue: "template",
+        options: [
+            {
+                label: "Copy templates now (install AGENTS.md and companion files)",
+                value: "template",
+            },
+            {
+                label: "Install AgentKit skill (create guidance files later in your agent)",
+                value: "skill",
+            },
+        ],
+    }));
+}
+async function collectInstallOptions(resolvedTarget, providedPreset, options) {
     if (!providedPreset) {
         options.preset = await promptForProjectPreset();
     }
@@ -804,25 +849,50 @@ async function applyInteractiveSelections(resolvedTarget, providedPreset, option
     if (templateSet === "standard" || templateSet === "full") {
         options.designSystem = await promptForDesignSystem(options.designSystem);
     }
-    if (!options.force) {
+}
+async function resolveConflictForInstall(resolvedTarget, options, bootstrapPath) {
+    if (options.force) {
+        return;
+    }
+    let installFiles;
+    if (bootstrapPath === "skill") {
+        const skillFiles = await listSkillFiles(getSkillSourceDir(packageRoot));
+        installFiles = [...getSkillDestinationPaths(skillFiles), configFileName];
+    }
+    else {
         const preset = resolvePreset(options.preset);
-        const installFiles = preset ? [...options.files, "STACK.md"] : options.files;
-        const existingFiles = await findExistingInstallFiles(resolvedTarget, installFiles);
-        if (existingFiles.length > 0) {
-            options.force = (await promptForConflictStrategy(existingFiles)) === "overwrite";
-        }
+        installFiles = preset ? [...(options.files ?? []), "STACK.md"] : (options.files ?? []);
+    }
+    const existingFiles = await findExistingInstallFiles(resolvedTarget, installFiles);
+    if (existingFiles.length > 0) {
+        options.force = (await promptForConflictStrategy(existingFiles)) === "overwrite";
     }
 }
-async function resolveInteractiveTarget(target, options) {
+async function runInteractiveInstall(target, options, agentkitVersion) {
+    intro("Welcome to AgentKit");
+    const bootstrapPath = await promptForBootstrapPath();
     const providedPreset = resolvePreset(options.preset);
-    if (!shouldPromptForInit(options, process)) {
-        return target;
+    const resolvedTarget = await promptForTarget(target);
+    await collectInstallOptions(resolvedTarget, providedPreset, options);
+    options.personalization = await promptForPersonalization(options.personalization);
+    await resolveConflictForInstall(resolvedTarget, options, bootstrapPath);
+    if (bootstrapPath === "skill") {
+        const result = await installSkill(resolvedTarget, options, packageRoot, agentkitVersion);
+        printSkillInstallResult(result, Boolean(options.dryRun));
+        return;
     }
+    const result = await installTemplates(resolvedTarget, options, agentkitVersion);
+    printInstallResult(result, Boolean(options.dryRun));
+}
+async function runSkillInstallInteractive(target, options, agentkitVersion) {
     intro("Welcome to AgentKit");
+    const providedPreset = resolvePreset(options.preset);
     const resolvedTarget = await promptForTarget(target);
-    await applyInteractiveSelections(resolvedTarget, providedPreset, options);
+    await collectInstallOptions(resolvedTarget, providedPreset, options);
     options.personalization = await promptForPersonalization(options.personalization);
-    return resolvedTarget;
+    await resolveConflictForInstall(resolvedTarget, options, "skill");
+    const result = await installSkill(resolvedTarget, options, packageRoot, agentkitVersion);
+    printSkillInstallResult(result, Boolean(options.dryRun));
 }
 async function main() {
     if (process.argv.slice(2).includes("--list")) {
@@ -856,6 +926,7 @@ async function main() {
 
 Examples:
   agentkit init
+  agentkit skill install
   agentkit update
   agentkit init --preset next
   agentkit init ./my-project --yes --dry-run
@@ -875,10 +946,35 @@ Examples:
         .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
         .action(async (target, options) => {
         await applyInitConfig(options, await loadConfigForTarget(target));
-        const resolvedTarget = await resolveInteractiveTarget(target, options);
-        const result = await installTemplates(resolvedTarget, options);
+        const agentkitVersion = await readPackageVersion();
+        if (shouldPromptForInit(options, process)) {
+            await runInteractiveInstall(target, options, agentkitVersion);
+            return;
+        }
+        const result = await installTemplates(target, options, agentkitVersion);
         printInstallResult(result, Boolean(options.dryRun));
     });
+    const skill = program.command("skill").description("install the bundled AgentKit Agent Skill");
+    skill
+        .command("install")
+        .description("install the bundled agentkit skill and write agentkit.config.json")
+        .argument("[target]", "target project directory", ".")
+        .option("--force", "overwrite existing skill files and config")
+        .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>", `store stack preset in config (${formatPresetList()})`)
+        .option("--design-system <name>", `store design system choice in config (${formatDesignSystemList()})`)
+        .action(async (target, options) => {
+        await applyInitConfig(options, await loadConfigForTarget(target));
+        const agentkitVersion = await readPackageVersion();
+        if (shouldPromptForInit(options, process)) {
+            await runSkillInstallInteractive(target, options, agentkitVersion);
+            return;
+        }
+        const result = await installSkill(target, options, packageRoot, agentkitVersion);
+        printSkillInstallResult(result, Boolean(options.dryRun));
+    });
     program
         .command("update")
         .description("update AgentKit managed template blocks in a project")
@@ -887,7 +983,14 @@ Examples:
         .option("--preset <name>", `update stack-specific guidance (${formatPresetList()})`)
         .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
         .action(async (target, options) => {
-        applyUpdateConfig(options, await loadConfigForTarget(target));
+        const config = await loadConfigForTarget(target);
+        if (getInstallMode(config) === "skill") {
+            console.log("This project uses installMode: skill.");
+            console.log("Run agentkit update in your agent to sync guidance files.");
+            console.log("(CLI agentkit update applies to template-path installs.)");
+            return;
+        }
+        applyUpdateConfig(options, config);
         const result = await updateTemplates(target, options);
         printUpdateResult(result, Boolean(options.dryRun));
     });

package/dist/skill-install.js

@@ -0,0 +1,125 @@
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const SKILL_DEST_DIR = ".agents/skills/agentkit";
+export const CONFIG_FILE_NAME = "agentkit.config.json";
+export function getSkillSourceDir(packageRoot) {
+    return path.join(packageRoot, "templates", "skills", "agentkit");
+}
+export async function listSkillFiles(sourceDir) {
+    const files = [];
+    async function walk(dir, prefix) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath, relative);
+            }
+            else if (entry.isFile()) {
+                files.push(relative);
+            }
+        }
+    }
+    await walk(sourceDir, "");
+    return files.sort();
+}
+export function buildSkillConfig(options, agentkitVersion) {
+    const config = {
+        installMode: "skill",
+        agentkitVersion,
+        templateSet: options.templateSet ?? "standard",
+        aiTools: options.aiTools ?? [],
+        designSystem: options.designSystem ?? "linear",
+    };
+    if (options.preset) {
+        config.preset = options.preset;
+    }
+    if (options.personalization) {
+        const personalization = {};
+        for (const [key, value] of Object.entries(options.personalization)) {
+            const trimmed = value?.trim();
+            if (trimmed) {
+                personalization[key] = trimmed;
+            }
+        }
+        if (Object.keys(personalization).length > 0) {
+            config.personalization = personalization;
+        }
+    }
+    return config;
+}
+export function getSkillDestinationPaths(skillFiles) {
+    return skillFiles.map((file) => path.posix.join(SKILL_DEST_DIR, file.replace(/\\/g, "/")));
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function installSkill(targetArg, options, packageRoot, agentkitVersion) {
+    const targetDir = path.resolve(process.cwd(), targetArg || ".");
+    const sourceDir = getSkillSourceDir(packageRoot);
+    const skillFiles = await listSkillFiles(sourceDir);
+    const result = { targetDir, created: [], skipped: [] };
+    if (!options.dryRun) {
+        await mkdir(targetDir, { recursive: true });
+    }
+    for (const file of skillFiles) {
+        const destination = path.join(targetDir, SKILL_DEST_DIR, file);
+        const destinationRelative = path.posix.join(SKILL_DEST_DIR, file.replace(/\\/g, "/"));
+        if ((await pathExists(destination)) && !options.force) {
+            result.skipped.push(destinationRelative);
+            continue;
+        }
+        result.created.push(destinationRelative);
+        if (!options.dryRun) {
+            await mkdir(path.dirname(destination), { recursive: true });
+            const content = await readFile(path.join(sourceDir, file), "utf8");
+            await writeFile(destination, content);
+        }
+    }
+    const configPath = path.join(targetDir, CONFIG_FILE_NAME);
+    const configRelative = CONFIG_FILE_NAME;
+    if ((await pathExists(configPath)) && !options.force) {
+        if (!result.skipped.includes(configRelative)) {
+            result.skipped.push(configRelative);
+        }
+    }
+    else {
+        if (!result.created.includes(configRelative)) {
+            result.created.push(configRelative);
+        }
+        if (!options.dryRun) {
+            const configContent = `${JSON.stringify(buildSkillConfig(options, agentkitVersion), null, 2)}\n`;
+            await writeFile(configPath, configContent);
+        }
+    }
+    return result;
+}
+export function printSkillInstallResult(result, dryRun = false) {
+    if (dryRun) {
+        console.log(`Would install AgentKit skill in ${SKILL_DEST_DIR}/`);
+        if (result.created.length > 0) {
+            console.log(`Would create: ${result.created.join(", ")}`);
+        }
+        if (result.skipped.length > 0) {
+            console.log(`Would skip existing: ${result.skipped.join(", ")}`);
+            console.log("Use --force to overwrite existing files.");
+        }
+        return;
+    }
+    console.log(`Installed AgentKit skill in ${SKILL_DEST_DIR}/`);
+    console.log(`Wrote ${CONFIG_FILE_NAME} (installMode: skill)`);
+    console.log("");
+    console.log("Next step: In your agent, run agentkit init.");
+    console.log("The skill will create AGENTS.md and companion files from your repository.");
+    if (result.skipped.length > 0) {
+        console.log(`Skipped existing: ${result.skipped.join(", ")}`);
+        console.log("Use --force to overwrite existing files.");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.7.0",
+  "version": "0.9.0-alpha.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "build": "tsc",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
+    "validate:skill": "skills-ref validate ./templates/skills/agentkit",
     "prepack": "npm run build"
   },
   "dependencies": {
@@ -40,6 +41,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "skills-ref": "^0.1.5",
     "@types/node": "^22.10.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",

package/templates/.cursor/rules/agentkit.md

@@ -6,21 +6,22 @@ Use this rule as a repository guidance router for Cursor agents and composer wor
 
 - Follow `AGENTS.md` first.
 - Treat `AGENTS.md` as the source of truth for repository-wide agent behavior.
-- Keep context focused. Read companion files only when relevant to the task.
+- Do not load companion files for routine coding unless a trigger in `AGENTS.md` applies or the user asks.
 
-## Read When Relevant
+## When Relevant
 
-- `CODE-QUALITY.md`: code quality, review, refactors, dependencies.
-- `WORKFLOWS.md`: planning, implementation, review, release.
-- `CHANGE-EXPLANATION.md`: final handoff and developer-facing explanation.
-- `DESIGN-SYSTEM.md`: UI, styling, layout, navigation, components.
-- `TESTING.md`: tests, fixtures, mocks, QA strategy.
-- `SECURITY-CHECKLIST.md`: auth, permissions, secrets, PII, data handling.
-- `STACK.md`: stack-specific rules when present.
+- **File edits (final message):** change-explanation format in `AGENTS.md` and `CHANGE-EXPLANATION.md`.
+- **UI / styling / layout:** `DESIGN-SYSTEM.md` or the project design-system path from `AGENTS.md`.
+- **Review / refactor / dependencies:** `CODE-QUALITY.md`.
+- **Tests / QA strategy:** `TESTING.md` if present.
+- **Auth / secrets / PII:** `SECURITY-CHECKLIST.md` if present.
+- **Stack-specific code:** `STACK.md` if present.
+- **Planning docs requested:** create from `PRD-TEMPLATE.md` or `IMPLEMENTATION-BRIEF-TEMPLATE.md` under the project's briefs path.
+- **Process map (optional):** `WORKFLOWS.md` if present.
 
 ## Cursor Behavior
 
 - Prefer existing repository patterns over generic generated patterns.
 - Keep changes scoped and reviewable.
 - Do not change foundational architecture, schema, dependencies, or theme primitives without explicit approval.
-- Summarize changed files, checks run, risks, and review focus before handoff.
+- After modifying files, end every task with a change explanation per `AGENTS.md` (summary, what changed, verification, risks, review focus). Scale depth to the change; do not skip for small fixes.

package/templates/.github/copilot-instructions.md

@@ -2,15 +2,7 @@
 
 Follow `AGENTS.md` first. It is the primary source of truth for this repository's AI-agent guidance.
 
-When relevant, also read:
-
-- `CODE-QUALITY.md`
-- `WORKFLOWS.md`
-- `CHANGE-EXPLANATION.md`
-- `DESIGN-SYSTEM.md`
-- `TESTING.md`
-- `SECURITY-CHECKLIST.md`
-- `STACK.md`
+Do not load companion files for routine coding. Use `AGENTS.md` triggers: change explanation after file edits; `CODE-QUALITY.md` for review/refactors; design-system path or `DESIGN-SYSTEM.md` for UI; `TESTING.md`, `SECURITY-CHECKLIST.md`, or `STACK.md` when present and relevant; planning templates only when explicitly requested.
 
 For files covered by additional GitHub instructions under `.github/instructions/`, apply those path-specific instructions together with this file.