agentcohort 0.1.1 → 0.2.0

package/README.md

@@ -93,6 +93,20 @@ production-grade correctness, no shallow fixes, no fixing without evidence, and
 **a bug audit never fixes** — it produces a recommendation and stops at a human
 approval gate.
 
+### How agents respect your CLAUDE.md and skills
+
+Every installed agent boots by reading your project's `CLAUDE.md`
+content **outside** the `# Agentcohort Routing Rules` section and by
+checking for installed skills that match the current task. The rules:
+
+- Your project rules take precedence over an agent's default prompt.
+- An agent invokes a matching skill instead of re-implementing it.
+- Agentcohort's defaults apply only where your project is silent.
+
+This means `agentcohort` slots into a project that already has its own
+CLAUDE.md and skills (e.g. `superpowers`) — it does not override what
+you've already set up.
+
 ## Using the workflow commands (inside Claude Code)
 
 | Command | Pipeline | Use it for |
@@ -113,6 +127,58 @@ approval gate.
 - **Sonnet** — implementation, testing, bug & performance hunting.
 - **Opus** — architecture, root-cause analysis, expert council, final review.
 
+## Customizing model strategy
+
+`agentcohort init` will (interactively) prompt you to either use the
+default Claude model IDs or pick your own for each tier. Your choice is
+saved to `.agentcohort.json` at the project root and reused on later
+runs.
+
+To revisit your choice without re-installing everything, run:
+
+```bash
+agentcohort config
+```
+
+This re-prompts for the three tier model IDs, shows a diff of which
+installed agents would change, and applies the changes with your
+confirmation.
+
+To force a re-prompt during install (instead of using the existing
+`.agentcohort.json`), run:
+
+```bash
+agentcohort init --reconfigure
+```
+
+### `.agentcohort.json` schema (v1)
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/Thiendekaco/agentcohort/main/schema/agentcohort-config-v1.json",
+  "version": 1,
+  "models": {
+    "premium": "claude-opus-4-7",
+    "mid": "claude-sonnet-4-6",
+    "cheap": "claude-haiku-4-5-20251001"
+  }
+}
+```
+
+- **premium** — architecture, root-cause analysis, expert council, final
+  review.
+- **mid** — implementation, testing, bug & performance hunting.
+- **cheap** — fast read-only repo scout.
+
+Hand-editing one of the installed `.claude/agents/*.md` files to use a
+specific model ID is respected: subsequent `agentcohort init` and
+`agentcohort config` runs leave that hand-edit alone (the tool only
+rewrites lines that are still tier aliases or match the previous
+config's IDs).
+
+Model IDs are not validated by the tool — if the ID is invalid, Claude
+Code will fail at agent spawn time.
+
 ## Customizing agents
 
 The installed files are plain Markdown and **yours to edit**:
@@ -146,7 +212,8 @@ before changing them (or back them up with `--backup`).
 - **`--dry-run`** performs zero writes and zero backups.
 - Backups are written next to the original as
   `<file>.backup-YYYYMMDD-HHMMSS` and never overwrite an existing backup.
-- Cross-platform (Windows/macOS/Linux), zero runtime dependencies, no
+- Cross-platform (Windows/macOS/Linux); a single runtime dependency
+  (`@inquirer/prompts` for the interactive model-tier prompt), no
   shell-specific behavior.
 
 ## Development
@@ -157,27 +224,36 @@ npm run build      # tsc -> dist/, then copies templates
 npm test           # vitest
 ```
 
-## Releases
+## Branching & releases
+
+Two long-lived branches:
+
+- **`dev`** — integration / staging. All feature PRs target `dev`. Nothing
+  here publishes to npm; this is the place to bundle PRs together, run
+  manual smoke tests, and verify the release as a whole.
+- **`main`** — production. Only ever updated by merging `dev` → `main`.
+  Every push to `main` triggers the [`Release`](.github/workflows/release.yml)
+  workflow.
 
-Publishing is automated. **The version in `package.json` is the version that
-gets published.** Every push to `main` runs the
-[`Release`](.github/workflows/release.yml) workflow, which:
+The workflow does:
 
 1. installs, builds and runs the full test suite;
 2. publishes the **current** `package.json` version to npm —
    https://www.npmjs.com/package/agentcohort (so the very first
-   release is exactly `0.1.0`, nothing skipped);
+   release was exactly `0.1.0`, nothing skipped);
 3. creates the annotated git tag `vX.Y.Z` on the published commit;
 4. bumps to the next dev version (`patch` by default) and pushes a
    `chore(release): published vX.Y.Z, open vX.Y.(Z+1) [skip ci]` commit back
    to `main`.
 
-So: to cut a normal release, just push to `main`. To release a `minor`/`major`
-instead, bump `package.json` yourself in a regular commit before pushing (or
-use the *Run workflow* button to control how the **next** pending version is
-opened). If the pending version is already on npm, publish is skipped and the
-job still succeeds (safe re-runs). The `[skip ci]` marker stops the release
-commit from re-triggering the workflow (no publish loop).
+So the normal release cycle is: open PR → `dev` → review & merge → smoke
+test on `dev` → open PR `dev` → `main` → merge → workflow publishes. To
+ship a `minor`/`major` instead of `patch`, bump `package.json` yourself
+in the PR before merging (or use the *Run workflow* button to control
+how the **next** pending version is opened). If the pending version is
+already on npm, publish is skipped and the job still succeeds (safe
+re-runs). The `[skip ci]` marker stops the release commit from
+re-triggering the workflow (no publish loop).
 
 **One-time setup:** add an npm **Automation** access token as the repository
 secret `NPM_TOKEN` (GitHub → Settings → Secrets and variables → Actions →

package/dist/args.d.ts

@@ -4,6 +4,7 @@ export interface ParsedArgs {
     dryRun: boolean;
     force: boolean;
     backup: boolean;
+    reconfigure: boolean;
     help: boolean;
     version: boolean;
     unknown: string[];

package/dist/args.js

@@ -9,6 +9,7 @@ const FLAGS = {
     '--dry-run': 'dryRun',
     '--force': 'force',
     '--backup': 'backup',
+    '--reconfigure': 'reconfigure',
     '--help': 'help',
     '-h': 'help',
     '--version': 'version',
@@ -22,6 +23,7 @@ function parseArgs(argv) {
         dryRun: false,
         force: false,
         backup: false,
+        reconfigure: false,
         help: false,
         version: false,
         unknown: [],
@@ -56,6 +58,9 @@ ${b('USAGE')}
 ${b('COMMANDS')}
   init                 Install agents, workflow commands and routing rules
                        into ./.claude and ./CLAUDE.md of the current project.
+  config               Re-prompt the model-tier strategy, show a diff of
+                       any pending changes to installed agents, and apply
+                       them with confirmation.
 
 ${b('OPTIONS')}
   --yes, -y            Non-interactive. Safe defaults: new files created;
@@ -67,6 +72,9 @@ ${b('OPTIONS')}
                        section without prompting (no backup unless --backup).
   --backup             Always back up a file before overwriting it.
                        Backup name: <file>.backup-YYYYMMDD-HHMMSS
+  --reconfigure        (init only) Re-prompt model-tier strategy even if a
+                       .agentcohort.json already exists. Requires a TTY;
+                       not compatible with --yes.
   --help, -h           Show this help.
   --version, -v        Print the version.
 
@@ -75,6 +83,7 @@ ${b('WHAT GETS INSTALLED')}
                        reviewer, bug-hunter, root-cause-analyst, ...).
   .claude/commands/    7 workflow commands.
   CLAUDE.md            Appends a "# Agentcohort Routing Rules" section.
+  .agentcohort.json    (Only when user customizes model-tier strategy.)
 
 ${b('WORKFLOW COMMANDS (run inside Claude Code)')}
   /auto-flow           Classify the task and pick the right workflow.

package/dist/cli.js

@@ -2,8 +2,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
+const prompts_1 = require("@inquirer/prompts");
+const core_1 = require("@inquirer/core");
 const installer_1 = require("./installer");
 const prompt_1 = require("./prompt");
+const promptModels_1 = require("./promptModels");
+const configCmd_1 = require("./configCmd");
+const config_1 = require("./config");
 const logger_1 = require("./logger");
 const paths_1 = require("./paths");
 const args_1 = require("./args");
@@ -55,11 +60,15 @@ async function main(argv = process.argv.slice(2)) {
         process.stdout.write((0, args_1.helpText)() + '\n');
         return 0;
     }
-    if (args.command !== 'init') {
+    if (args.command !== 'init' && args.command !== 'config') {
         process.stderr.write((0, logger_1.paint)(`✗ Unknown command: ${args.command}\n`, 'red'));
         process.stdout.write((0, args_1.helpText)() + '\n');
         return 1;
     }
+    if (args.reconfigure && (args.yes || args.force)) {
+        process.stderr.write((0, logger_1.paint)('✗ --reconfigure requires interactive mode (cannot combine with --yes or --force).\n', 'red'));
+        return 1;
+    }
     const stdinTTY = Boolean(process.stdin.isTTY);
     const stdoutTTY = Boolean(process.stdout.isTTY);
     const interactive = !args.yes && !args.force && !args.dryRun && stdinTTY && stdoutTTY;
@@ -73,10 +82,39 @@ async function main(argv = process.argv.slice(2)) {
         logger.info('Non-interactive environment detected — using safe defaults (like --yes).');
     }
     try {
+        const cwd = process.cwd();
+        if (args.command === 'config') {
+            if (!interactive) {
+                process.stderr.write((0, logger_1.paint)('✗ `agentcohort config` requires interactive mode (TTY). Edit .agentcohort.json directly to set models non-interactively.\n', 'red'));
+                return 1;
+            }
+            const result = await (0, configCmd_1.runConfigCmd)({
+                cwd,
+                promptModelStrategy: promptModels_1.promptModelStrategy,
+                confirm: (message) => (0, prompts_1.confirm)({ message, default: true }),
+            });
+            const msg = {
+                'no-changes': 'No changes. Configuration is up to date.',
+                'no-agents': 'Config saved. No installed agents found — run `agentcohort init` to install.',
+                'cancelled': 'Cancelled. No changes made.',
+                'applied': `Applied ${result.changes.length} change(s) to installed agents.`,
+            }[result.status];
+            process.stdout.write(`${(0, logger_1.paint)('•', 'cyan')} ${msg}\n`);
+            return 0;
+        }
+        // command === 'init'
+        let existingConfig = (0, config_1.loadConfig)(cwd);
+        let models = (0, config_1.resolveModels)(existingConfig);
+        if (interactive && (existingConfig === null || args.reconfigure)) {
+            const newModels = await (0, promptModels_1.promptModelStrategy)(existingConfig?.models);
+            // Persist config BEFORE install so a partial install can be re-run idempotently.
+            (0, config_1.writeConfig)(cwd, { version: 1, models: newModels });
+            models = newModels;
+        }
         if (interactive)
             resolverHandle = (0, prompt_1.createInteractiveResolver)();
         const result = await (0, installer_1.runInit)({
-            cwd: process.cwd(),
+            cwd,
             yes: args.yes,
             dryRun: args.dryRun,
             force: args.force,
@@ -84,12 +122,17 @@ async function main(argv = process.argv.slice(2)) {
             interactive,
             resolver: resolverHandle?.resolve,
             logger,
+            models,
         });
         printSummary(result);
         return 0;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        if (err instanceof core_1.ExitPromptError) {
+            process.stderr.write((0, logger_1.paint)('\nCancelled. No changes made.\n', 'yellow'));
+            return 130;
+        }
         process.stderr.write((0, logger_1.paint)(`\n✗ ${message}\n`, 'red'));
         return 1;
     }

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+export declare const CONFIG_FILENAME = ".agentcohort.json";
+export interface ModelsConfig {
+    premium: string;
+    mid: string;
+    cheap: string;
+}
+export interface AgentcohortConfig {
+    version: 1;
+    models: ModelsConfig;
+}
+/**
+ * Validate that `raw` is a well-formed AgentcohortConfig. Returns the
+ * parsed config (with unknown top-level keys stripped). Throws on any
+ * violation.
+ */
+export declare function validateConfig(raw: unknown): AgentcohortConfig;
+/**
+ * Load `.agentcohort.json` from `projectRoot`. Returns null if absent.
+ * Throws a structured error if the file exists but is malformed.
+ */
+export declare function loadConfig(projectRoot: string): AgentcohortConfig | null;
+/**
+ * Write `cfg` to `.agentcohort.json` in `projectRoot`. Includes a
+ * `$schema` field for editor autocomplete. Idempotent at the byte
+ * level: writing the same config twice produces identical bytes.
+ */
+export declare function writeConfig(projectRoot: string, cfg: AgentcohortConfig): void;
+/**
+ * Resolve a ModelsConfig from a possibly-null config. When null,
+ * returns DEFAULT_MODELS.
+ */
+export declare function resolveModels(cfg: AgentcohortConfig | null): ModelsConfig;

package/dist/config.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILENAME = void 0;
+exports.validateConfig = validateConfig;
+exports.loadConfig = loadConfig;
+exports.writeConfig = writeConfig;
+exports.resolveModels = resolveModels;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const defaults_1 = require("./defaults");
+exports.CONFIG_FILENAME = '.agentcohort.json';
+const TIERS = ['premium', 'mid', 'cheap'];
+function fail(reason) {
+    throw new Error(`Invalid .agentcohort.json: ${reason}. Expected schema: { version: 1, models: { premium: string, mid: string, cheap: string } }`);
+}
+/**
+ * Validate that `raw` is a well-formed AgentcohortConfig. Returns the
+ * parsed config (with unknown top-level keys stripped). Throws on any
+ * violation.
+ */
+function validateConfig(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        fail('not an object');
+    }
+    const obj = raw;
+    if (obj.version !== 1) {
+        fail(`unsupported version ${JSON.stringify(obj.version)}; expected 1`);
+    }
+    const models = obj.models;
+    if (models === null || typeof models !== 'object' || Array.isArray(models)) {
+        fail('models must be an object');
+    }
+    const m = models;
+    const out = {};
+    for (const tier of TIERS) {
+        const v = m[tier];
+        if (typeof v !== 'string') {
+            fail(`models.${tier} must be a string`);
+        }
+        if (v.trim().length === 0) {
+            fail(`models.${tier} must be a non-empty, non-whitespace string`);
+        }
+        out[tier] = v;
+    }
+    return { version: 1, models: out };
+}
+/**
+ * Load `.agentcohort.json` from `projectRoot`. Returns null if absent.
+ * Throws a structured error if the file exists but is malformed.
+ */
+function loadConfig(projectRoot) {
+    const path = (0, node_path_1.join)(projectRoot, exports.CONFIG_FILENAME);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        fail(`malformed JSON (${msg})`);
+    }
+    return validateConfig(parsed);
+}
+const SCHEMA_URL = 'https://raw.githubusercontent.com/Thiendekaco/agentcohort/main/schema/agentcohort-config-v1.json';
+function serializeConfig(cfg) {
+    const ordered = {
+        $schema: SCHEMA_URL,
+        version: cfg.version,
+        models: {
+            premium: cfg.models.premium,
+            mid: cfg.models.mid,
+            cheap: cfg.models.cheap,
+        },
+    };
+    return JSON.stringify(ordered, null, 2) + '\n';
+}
+/**
+ * Write `cfg` to `.agentcohort.json` in `projectRoot`. Includes a
+ * `$schema` field for editor autocomplete. Idempotent at the byte
+ * level: writing the same config twice produces identical bytes.
+ */
+function writeConfig(projectRoot, cfg) {
+    const path = (0, node_path_1.join)(projectRoot, exports.CONFIG_FILENAME);
+    (0, node_fs_1.writeFileSync)(path, serializeConfig(cfg), 'utf8');
+}
+/**
+ * Resolve a ModelsConfig from a possibly-null config. When null,
+ * returns DEFAULT_MODELS.
+ */
+function resolveModels(cfg) {
+    if (cfg === null) {
+        return {
+            premium: defaults_1.DEFAULT_MODELS.premium,
+            mid: defaults_1.DEFAULT_MODELS.mid,
+            cheap: defaults_1.DEFAULT_MODELS.cheap,
+        };
+    }
+    return cfg.models;
+}

package/dist/configCmd.d.ts

@@ -0,0 +1,27 @@
+import { ModelsConfig } from './config';
+import { ModelChange } from './diff';
+export type ConfigCmdStatus = 'no-changes' | 'no-agents' | 'cancelled' | 'applied';
+export interface ConfigCmdResult {
+    status: ConfigCmdStatus;
+    changes: ModelChange[];
+}
+export interface ConfigCmdOptions {
+    cwd: string;
+    /** Inject the prompt function — production passes the real TUI, tests pass a mock. */
+    promptModelStrategy: (current?: ModelsConfig) => Promise<ModelsConfig>;
+    /** Inject the diff-confirm function — same reason. */
+    confirm: (message: string) => Promise<boolean>;
+}
+/**
+ * Run the `agentcohort config` subcommand.
+ *
+ *  1. Load existing config (or null → defaults).
+ *  2. Prompt user for a new ModelsConfig (pre-filled with current).
+ *  3. If no models changed: write config (idempotent) → 'no-changes'.
+ *  4. Compute the diff of installed agent files.
+ *  5. If diff is empty (e.g. no .claude/agents dir): write config → 'no-agents'.
+ *  6. Otherwise: confirm with user. Decline → 'cancelled'. Accept →
+ *     write config + rewrite each affected file's `model:` line in
+ *     place (preserves the rest byte-for-byte) → 'applied'.
+ */
+export declare function runConfigCmd(opts: ConfigCmdOptions): Promise<ConfigCmdResult>;

package/dist/configCmd.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runConfigCmd = runConfigCmd;
+const node_path_1 = require("node:path");
+const config_1 = require("./config");
+const diff_1 = require("./diff");
+const node_fs_1 = require("node:fs");
+/**
+ * Run the `agentcohort config` subcommand.
+ *
+ *  1. Load existing config (or null → defaults).
+ *  2. Prompt user for a new ModelsConfig (pre-filled with current).
+ *  3. If no models changed: write config (idempotent) → 'no-changes'.
+ *  4. Compute the diff of installed agent files.
+ *  5. If diff is empty (e.g. no .claude/agents dir): write config → 'no-agents'.
+ *  6. Otherwise: confirm with user. Decline → 'cancelled'. Accept →
+ *     write config + rewrite each affected file's `model:` line in
+ *     place (preserves the rest byte-for-byte) → 'applied'.
+ */
+async function runConfigCmd(opts) {
+    const existing = (0, config_1.loadConfig)(opts.cwd);
+    const oldModels = (0, config_1.resolveModels)(existing);
+    const newModels = await opts.promptModelStrategy(existing?.models);
+    const noChange = newModels.premium === oldModels.premium &&
+        newModels.mid === oldModels.mid &&
+        newModels.cheap === oldModels.cheap;
+    const newConfig = { version: 1, models: newModels };
+    const agentDir = (0, node_path_1.join)(opts.cwd, '.claude', 'agents');
+    if (noChange) {
+        (0, config_1.writeConfig)(opts.cwd, newConfig);
+        if (!(0, node_fs_1.existsSync)(agentDir)) {
+            return { status: 'no-agents', changes: [] };
+        }
+        return { status: 'no-changes', changes: [] };
+    }
+    const changes = (0, diff_1.computeFrontmatterModelDiff)(agentDir, oldModels, newModels);
+    if (changes.length === 0) {
+        (0, config_1.writeConfig)(opts.cwd, newConfig);
+        return { status: 'no-agents', changes: [] };
+    }
+    const message = `Apply ${changes.length} model change${changes.length === 1 ? '' : 's'}?`;
+    const accepted = await opts.confirm(message);
+    if (!accepted) {
+        return { status: 'cancelled', changes };
+    }
+    (0, config_1.writeConfig)(opts.cwd, newConfig);
+    for (const c of changes) {
+        const path = (0, node_path_1.join)(agentDir, c.file);
+        const current = (0, node_fs_1.readFileSync)(path, 'utf8');
+        const rewritten = current.replace(/^model:[ \t]+\S+[ \t]*$/m, `model: ${c.to}`);
+        (0, node_fs_1.writeFileSync)(path, rewritten, 'utf8');
+    }
+    return { status: 'applied', changes };
+}

package/dist/defaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Single source of truth for default Claude model IDs and the
+ * alias-to-tier mapping the installer uses when rewriting agent
+ * templates.
+ *
+ * When a new Claude model ships, update DEFAULT_MODELS here and the
+ * change flows through both the default install path and the prompt
+ * defaults.
+ */
+export declare const DEFAULT_MODELS: {
+    readonly premium: "claude-opus-4-7";
+    readonly mid: "claude-sonnet-4-6";
+    readonly cheap: "claude-haiku-4-5-20251001";
+};
+export declare const TIER_ALIASES: {
+    readonly opus: "premium";
+    readonly sonnet: "mid";
+    readonly haiku: "cheap";
+};
+export type Tier = keyof typeof DEFAULT_MODELS;
+export type TierAlias = keyof typeof TIER_ALIASES;

package/dist/defaults.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Single source of truth for default Claude model IDs and the
+ * alias-to-tier mapping the installer uses when rewriting agent
+ * templates.
+ *
+ * When a new Claude model ships, update DEFAULT_MODELS here and the
+ * change flows through both the default install path and the prompt
+ * defaults.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIER_ALIASES = exports.DEFAULT_MODELS = void 0;
+exports.DEFAULT_MODELS = {
+    premium: 'claude-opus-4-7',
+    mid: 'claude-sonnet-4-6',
+    cheap: 'claude-haiku-4-5-20251001',
+};
+exports.TIER_ALIASES = {
+    opus: 'premium',
+    sonnet: 'mid',
+    haiku: 'cheap',
+};

package/dist/diff.d.ts

@@ -0,0 +1,24 @@
+import type { ModelsConfig } from './config';
+export interface ModelChange {
+    file: string;
+    from: string;
+    to: string;
+}
+/**
+ * For each `.md` file in `installedAgentDir`, decide whether changing
+ * the model config from `oldModels` to `newModels` would alter the
+ * file's frontmatter `model:` line. Returns the list of changes (file
+ * name + from/to model IDs).
+ *
+ * A file is treated three ways:
+ *   1. Tier alias in frontmatter (`model: opus|sonnet|haiku`): treat
+ *      as `oldModels[tier(alias)]` and check whether
+ *      `newModels[tier(alias)]` differs.
+ *   2. Concrete ID matching one of oldModels: that's a previously
+ *      rendered file; we know its tier, so check whether the new
+ *      config differs.
+ *   3. Concrete ID NOT in oldModels: a hand-edit. Skipped.
+ *
+ * Returns [] if the dir does not exist.
+ */
+export declare function computeFrontmatterModelDiff(installedAgentDir: string, oldModels: ModelsConfig, newModels: ModelsConfig): ModelChange[];

package/dist/diff.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeFrontmatterModelDiff = computeFrontmatterModelDiff;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const defaults_1 = require("./defaults");
+/**
+ * For each `.md` file in `installedAgentDir`, decide whether changing
+ * the model config from `oldModels` to `newModels` would alter the
+ * file's frontmatter `model:` line. Returns the list of changes (file
+ * name + from/to model IDs).
+ *
+ * A file is treated three ways:
+ *   1. Tier alias in frontmatter (`model: opus|sonnet|haiku`): treat
+ *      as `oldModels[tier(alias)]` and check whether
+ *      `newModels[tier(alias)]` differs.
+ *   2. Concrete ID matching one of oldModels: that's a previously
+ *      rendered file; we know its tier, so check whether the new
+ *      config differs.
+ *   3. Concrete ID NOT in oldModels: a hand-edit. Skipped.
+ *
+ * Returns [] if the dir does not exist.
+ */
+function computeFrontmatterModelDiff(installedAgentDir, oldModels, newModels) {
+    if (!(0, node_fs_1.existsSync)(installedAgentDir))
+        return [];
+    const oldById = {
+        [oldModels.premium]: 'premium',
+        [oldModels.mid]: 'mid',
+        [oldModels.cheap]: 'cheap',
+    };
+    const changes = [];
+    for (const file of (0, node_fs_1.readdirSync)(installedAgentDir).sort()) {
+        if (!file.endsWith('.md'))
+            continue;
+        const text = (0, node_fs_1.readFileSync)((0, node_path_1.join)(installedAgentDir, file), 'utf8');
+        const m = text.match(/^model:[ \t]+(\S+)[ \t]*$/m);
+        if (!m?.[1])
+            continue;
+        const value = m[1];
+        let tier;
+        let from = '';
+        if (value === 'opus' || value === 'sonnet' || value === 'haiku') {
+            tier = defaults_1.TIER_ALIASES[value];
+            if (!tier)
+                continue; // satisfy strict TS
+            from = oldModels[tier];
+        }
+        else {
+            const tierFromId = oldById[value];
+            if (!tierFromId) {
+                // hand-edited specific ID → skip
+                continue;
+            }
+            tier = tierFromId;
+            from = value;
+        }
+        const to = newModels[tier];
+        if (from !== to) {
+            changes.push({ file, from, to });
+        }
+    }
+    return changes;
+}

package/dist/installer.d.ts

@@ -1,6 +1,7 @@
 import { EntryKind } from './manifest';
 import type { ConflictResolver } from './prompt';
 import type { Logger } from './logger';
+import type { ModelsConfig } from './config';
 export type Disposition = 'created' | 'overwritten' | 'appended-section' | 'replaced-section' | 'skipped' | 'unchanged';
 export interface ActionRecord {
     targetRelPath: string;
@@ -19,6 +20,7 @@ export interface InitOptions {
     backup: boolean;
     /** When false, conflicts are resolved by safe automatic defaults. */
     interactive: boolean;
+    models: ModelsConfig;
     resolver?: ConflictResolver;
     now?: () => Date;
     logger?: Logger;

package/dist/installer.js

@@ -7,6 +7,7 @@ const fileOps_1 = require("./fileOps");
 const claudeMd_1 = require("./claudeMd");
 const manifest_1 = require("./manifest");
 const paths_1 = require("./paths");
+const render_1 = require("./render");
 /** Pick a non-clobbering backup path (never overwrite an existing backup). */
 function uniqueBackupPath(target, date) {
     const base = (0, fileOps_1.backupPathFor)(target, date);
@@ -100,7 +101,10 @@ async function runInit(options) {
     return { projectRoot, actions, dryRun: options.dryRun };
     // ---- per-entry handlers (closures over decide/record/doBackup) ----
     async function handleRegular(entry) {
-        const template = (0, node_fs_1.readFileSync)(entry.templateAbsPath, 'utf8');
+        const rawTemplate = (0, node_fs_1.readFileSync)(entry.templateAbsPath, 'utf8');
+        const template = entry.targetRelPath.startsWith('.claude/agents/')
+            ? (0, render_1.renderAgentTemplate)(rawTemplate, options.models)
+            : rawTemplate;
         const existing = (0, fileOps_1.readIfExists)(entry.targetAbsPath);
         if (existing === null) {
             if (!options.dryRun)

package/dist/promptModels.d.ts

@@ -0,0 +1,13 @@
+import type { ModelsConfig } from './config';
+/**
+ * Interactive 1-step or 2-step prompt that returns a ModelsConfig.
+ *
+ * Step 1: select "Use defaults (auto)" or "Customize each tier".
+ * Step 2 (custom only): three input prompts for premium / mid / cheap.
+ *
+ * When `current` is provided, prompts pre-fill with it. Otherwise the
+ * defaults are pre-filled.
+ *
+ * Throws ExitPromptError on Ctrl+C — the caller catches and exits 130.
+ */
+export declare function promptModelStrategy(current?: ModelsConfig): Promise<ModelsConfig>;

package/dist/promptModels.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptModelStrategy = promptModelStrategy;
+const prompts_1 = require("@inquirer/prompts");
+const defaults_1 = require("./defaults");
+/**
+ * Interactive 1-step or 2-step prompt that returns a ModelsConfig.
+ *
+ * Step 1: select "Use defaults (auto)" or "Customize each tier".
+ * Step 2 (custom only): three input prompts for premium / mid / cheap.
+ *
+ * When `current` is provided, prompts pre-fill with it. Otherwise the
+ * defaults are pre-filled.
+ *
+ * Throws ExitPromptError on Ctrl+C — the caller catches and exits 130.
+ */
+async function promptModelStrategy(current) {
+    const base = current ?? {
+        premium: defaults_1.DEFAULT_MODELS.premium,
+        mid: defaults_1.DEFAULT_MODELS.mid,
+        cheap: defaults_1.DEFAULT_MODELS.cheap,
+    };
+    const mode = await (0, prompts_1.select)({
+        message: 'Model strategy:',
+        choices: [
+            {
+                name: 'Use defaults (recommended)',
+                value: 'auto',
+                description: `premium=${defaults_1.DEFAULT_MODELS.premium}, mid=${defaults_1.DEFAULT_MODELS.mid}, cheap=${defaults_1.DEFAULT_MODELS.cheap}`,
+            },
+            {
+                name: 'Customize each tier',
+                value: 'custom',
+                description: 'Enter a specific model ID for premium / mid / cheap',
+            },
+        ],
+        default: current ? 'custom' : 'auto',
+    });
+    if (mode === 'auto') {
+        return {
+            premium: defaults_1.DEFAULT_MODELS.premium,
+            mid: defaults_1.DEFAULT_MODELS.mid,
+            cheap: defaults_1.DEFAULT_MODELS.cheap,
+        };
+    }
+    const premium = await (0, prompts_1.input)({
+        message: 'Premium tier model ID (architecture, root cause, review):',
+        default: base.premium,
+        validate: (v) => (v.trim().length > 0 ? true : 'must not be empty'),
+    });
+    const mid = await (0, prompts_1.input)({
+        message: 'Mid tier model ID (implementation, tests, hunting):',
+        default: base.mid,
+        validate: (v) => (v.trim().length > 0 ? true : 'must not be empty'),
+    });
+    const cheap = await (0, prompts_1.input)({
+        message: 'Cheap tier model ID (repo scout):',
+        default: base.cheap,
+        validate: (v) => (v.trim().length > 0 ? true : 'must not be empty'),
+    });
+    return {
+        premium: premium.trim(),
+        mid: mid.trim(),
+        cheap: cheap.trim(),
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,11 @@
+import type { ModelsConfig } from './config';
+/**
+ * Rewrite the `model:` line inside the YAML frontmatter from a tier
+ * alias (haiku/sonnet/opus) to the user's concrete model ID. Leaves
+ * everything else (including hand-edited specific IDs in the
+ * frontmatter, and any `model:` text in the body) unchanged.
+ *
+ * Pure and idempotent: rendering an already-rendered file returns it
+ * unchanged.
+ */
+export declare function renderAgentTemplate(content: string, models: ModelsConfig): string;

package/dist/render.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAgentTemplate = renderAgentTemplate;
+const defaults_1 = require("./defaults");
+/**
+ * Rewrite the `model:` line inside the YAML frontmatter from a tier
+ * alias (haiku/sonnet/opus) to the user's concrete model ID. Leaves
+ * everything else (including hand-edited specific IDs in the
+ * frontmatter, and any `model:` text in the body) unchanged.
+ *
+ * Pure and idempotent: rendering an already-rendered file returns it
+ * unchanged.
+ */
+function renderAgentTemplate(content, models) {
+    if (!content.startsWith('---'))
+        return content;
+    // Find the end of the YAML frontmatter (the second `---` on its own line).
+    const fmEndRe = /^---[ \t]*\r?\n([\s\S]*?\r?\n)---[ \t]*\r?\n/;
+    const fmMatch = content.match(fmEndRe);
+    if (!fmMatch)
+        return content;
+    const fmEnd = fmMatch[0].length;
+    const frontmatter = content.slice(0, fmEnd);
+    const body = content.slice(fmEnd);
+    const aliasRe = /^model:[ \t]+(haiku|sonnet|opus)[ \t]*$/m;
+    const aliasMatch = frontmatter.match(aliasRe);
+    if (!aliasMatch)
+        return content;
+    const alias = aliasMatch[1];
+    const tier = defaults_1.TIER_ALIASES[alias];
+    const newModelId = models[tier];
+    const newLine = `model: ${newModelId}`;
+    const newFrontmatter = frontmatter.replace(aliasRe, newLine);
+    return newFrontmatter + body;
+}

package/dist/templates/CLAUDE.section.md

@@ -8,6 +8,25 @@
 This project runs as an **AI software-engineering organization**. Default to
 routing work through the workflow commands instead of ad-hoc editing.
 
+## Interoperability & precedence
+
+These rules govern how the installed agents interact with the rest of
+your project's setup. They apply to every agent and every workflow.
+
+- **Your project rules win.** Anything you write in this CLAUDE.md
+  *outside* this `# Agentcohort Routing Rules` section takes precedence
+  over an installed agent's prompt. On conflict, agents follow your
+  rules.
+- **Installed skills must be invoked when they match.** If you have a
+  skill (e.g. `superpowers:*`, `gstack`, etc.) that fits the current
+  task, the agent invokes it instead of re-implementing the same logic.
+- **Agent prompts are a baseline, not ground truth.** When your
+  CLAUDE.md specifies a tool, framework, commit style, or workflow, the
+  agent uses your choice — not the default in its prompt.
+- **Pipeline commands remain the default routing.** `/dev-flow`,
+  `/bug-audit`, and the others are the default. A user-defined flow in
+  your CLAUDE.md takes precedence when present.
+
 ## Operating standard (all agents)
 
 - Operate at **top 1% principal/staff software-engineer** level.

package/dist/templates/agents/bug-fixer.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Bug Fixer**. You correct the proven root cause of an approved

package/dist/templates/agents/bug-hunter.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Bug Hunter**. You find what is broken or fragile before users

package/dist/templates/agents/expert-council.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep
 model: opus
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Expert Council** — a single agent that deliberates as four

package/dist/templates/agents/feature-implementer.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Edit, Write, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Feature Implementer**. You execute the plan exactly, making the

package/dist/templates/agents/feature-planner.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Feature Planner**. You convert intent into an unambiguous,

package/dist/templates/agents/final-reviewer.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Bash
 model: opus
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Final Reviewer**. You are the last line of defense before code

package/dist/templates/agents/perf-optimizer.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Edit, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Performance Optimizer**. You make it faster without making it

package/dist/templates/agents/perf-reviewer.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Bash
 model: opus
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Performance Reviewer**. You make sure the speedup did not buy

package/dist/templates/agents/performance-hunter.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Performance Hunter**. You locate where time and resources

package/dist/templates/agents/regression-guard.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Edit, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Regression Guard**. Your tests are the bug's permanent tombstone:

package/dist/templates/agents/repo-scout.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep
 model: haiku
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Repo Scout**. You go in first, map the terrain, and come back

package/dist/templates/agents/reproduction-engineer.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Bash, Edit
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Reproduction Engineer**. A bug that cannot be reproduced cannot

package/dist/templates/agents/root-cause-analyst.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Bash
 model: opus
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Root Cause Analyst**. You refuse to stop at the symptom. You

package/dist/templates/agents/solution-architect.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep
 model: opus
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Solution Architect**. You decide *how* the system should change

package/dist/templates/agents/test-verifier.md

@@ -5,6 +5,20 @@ tools: Read, Glob, Grep, Edit, Bash
 model: sonnet
 ---
 
+<!-- boot-directive-start -->
+
+# Boot directive — read before acting
+
+1. Read project CLAUDE.md (especially content OUTSIDE the
+   `# Agentcohort Routing Rules` section). User project rules take
+   precedence over this agent prompt where they conflict.
+2. Check available skills. If any skill matches what you're about to do,
+   invoke it first — don't re-implement what a skill provides.
+3. Your role below is the default playbook. User CLAUDE.md and skills
+   override this playbook on conflict.
+
+<!-- boot-directive-end -->
+
 # Role
 
 You are the **Test Verifier**. You are the evidence gate: after a change, you

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcohort",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Install a principal/staff-level Claude Code AI software engineering organization (agents + workflows + routing rules) into any project with one command.",
   "keywords": [
     "claude",
@@ -43,7 +43,8 @@
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json && node scripts/copy-templates.mjs",
+    "sync-boot": "node scripts/sync-boot-directive.mjs",
+    "build": "npm run clean && npm run sync-boot && tsc -p tsconfig.json && node scripts/copy-templates.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build && npm test"
@@ -52,5 +53,8 @@
     "@types/node": "^20.14.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1"
   }
-}
+}