ai-team 1.0.2 → 1.2.0

package/docs/agents/plans/REL-NO-IDE-OVERLAYS/plan.md

@@ -0,0 +1,106 @@
+# Implementation Plan — REL-NO-IDE-OVERLAYS
+
+Date: 2026-02-23  
+Agent: planning-agent
+
+## Closeout Status (2026-02-23)
+
+- Lifecycle status: **NOT COMPLETE**
+- QA disposition: **FAIL** with execution checks **BLOCKED**
+- Reason: required command execution evidence is missing for targeted tests, full suite, and CLI parity/drift checks.
+- Required next commands:
+  - `node --test tests/template-registry.test.js`
+  - `node --test tests/sync-engine.test.js`
+  - `node --test tests/cli.integration.test.js`
+  - `pnpm test`
+  - `node src/cli.js init --target /tmp/rel-no-ide-overlays-vscode --ide vscode --team web-product --include-mcp --yes`
+  - `node src/cli.js doctor --target /tmp/rel-no-ide-overlays-vscode`
+  - `node src/cli.js init --target /tmp/rel-no-ide-overlays-claude --ide claude-code --team web-product --include-mcp --yes`
+  - `node src/cli.js doctor --target /tmp/rel-no-ide-overlays-claude`
+  - Edit an installed agent file, then run:
+    - `node src/cli.js plan --target <target>`
+    - `node src/cli.js update --target <target>`
+    - `node src/cli.js update --target <target> --force`
+
+## Objective
+
+Remove committed IDE overlay agent files as an operational dependency and move to generation-driven IDE outputs while preserving existing CLI behavior for `init`, `plan`, `update`, and `doctor` across `vscode` and `claude-code`.
+
+## Implementation Approach
+
+1. **Decouple runtime install from committed overlay agent files**
+   - Shift agent-content sourcing from `templates/bootstrap/overlays/*/.../agents` to generated-in-memory (or generated-at-build) artifacts derived from `src/agents/definitions/*.yaml`.
+   - Keep IDE-specific rendering (filename/frontmatter/body) exactly aligned with current outputs.
+2. **Retain manifest-driven target mapping for IDE outputs**
+   - Keep manifest as authoritative for install target paths and MCP paths, but remove assumptions that agent source files must be present as committed overlay files.
+3. **Wire generation into template entry collection path**
+   - Update template collection flow so `collectTemplateEntries` receives generated agent entries per selected IDE, then feeds unchanged sync conflict/merge logic.
+4. **Preserve sync semantics and migration compatibility**
+   - Ensure `plan`/`update`/`doctor` drift detection and manifest hashing remain deterministic.
+   - Keep legacy layout migration behavior untouched unless strictly required for overlay removal.
+5. **Align docs with architecture change**
+   - Update repo docs to describe generation-driven IDE artifacts and remove wording that implies maintained overlay agent files.
+
+## File-Level Change List (implementation phase)
+
+1. `src/agents/generate.js`
+   - Refactor from “write directly into overlay directories” script toward reusable generation API consumed by runtime/template registry (CLI-safe import surface).
+   - Preserve current render logic for frontmatter/body/file naming parity.
+2. `src/lib/template-registry.js`
+   - Replace direct overlay agent file enumeration with generated IDE agent entries.
+   - Keep base assets and MCP handling behavior intact.
+3. `templates/bootstrap/manifest.json`
+   - Remove or simplify overlay metadata that assumes committed overlay agent roots while preserving IDE target path contracts (`.github/agents`, `.claude/agents`, MCP paths).
+4. `src/lib/sync-engine.js` (if needed only)
+   - Minimal compatibility adjustments if manifest shape or entry metadata changes require it.
+5. `README.md`
+   - Update architecture/behavior descriptions to reflect generated IDE agent outputs.
+6. `docs/cli.md`
+   - Update source-of-truth and layout contract language to non-overlay architecture.
+7. `templates/bootstrap/overlays/**` (agent files only)
+   - Remove committed IDE agent files once generation-backed sourcing is in place.
+   - Keep MCP template files unless relocated by agreed design.
+8. `tests/sync-engine.test.js`
+   - Update/add assertions proving generated agent entries still map to expected install targets and preserve drift behavior.
+9. `tests/cli.integration.test.js`
+   - Ensure end-to-end `init`/`doctor` still pass for at least one IDE after overlay agent removal.
+
+## Acceptance Checks (clear and testable)
+
+1. **No committed overlay agents required**
+   - Repository can remove `templates/bootstrap/overlays/*/*/agents/*` and `pnpm test` still passes.
+2. **Generated output parity — vscode**
+   - `ai-team init --ide vscode --team web-product --yes` installs expected agent files under `.github/agents/*.agent.md` with unchanged naming/frontmatter/body shape.
+3. **Generated output parity — claude-code**
+   - `ai-team init --ide claude-code --team web-product --yes` installs expected agent files under `.claude/agents/*.md` with unchanged naming/frontmatter/body shape.
+4. **Sync behavior unchanged**
+   - After local edit to an installed agent file, `ai-team plan`/`ai-team update` report conflict/skip in safe mode, and `--force` allows overwrite.
+5. **Doctor behavior unchanged**
+   - `ai-team doctor` still reports drift/missing files based on manifest and generated source hashes.
+6. **MCP path handling retained**
+   - `--include-mcp` continues to write `.vscode/mcp.json` for vscode and `.mcp.json` for claude-code with existing merge semantics.
+7. **Docs aligned**
+   - `README.md` and `docs/cli.md` no longer imply committed overlay agent files are maintained sources.
+
+## Rollback / Risk Notes
+
+### Key risks
+
+1. **Hash drift from rendering differences**
+   - Small frontmatter or whitespace changes could trigger broad overwrite plans.
+2. **Manifest/schema compatibility breakage**
+   - Aggressive manifest shape changes could break existing installs and `doctor`.
+3. **IDE path regression**
+   - Incorrect mapping could place agents in wrong folders and fail runtime discovery.
+
+### Mitigations
+
+1. Keep rendering logic centralized and re-used across generation + registry paths to avoid parity drift.
+2. Prefer additive/minimal manifest changes; avoid schema bump unless unavoidable.
+3. Add fixture/assertion coverage for both IDE target paths and MCP target paths.
+
+### Rollback strategy
+
+1. Revert generation/registry/manifest/doc changes in one commit to restore overlay-file sourcing.
+2. If released with path regression, ship immediate patch restoring prior target mapping and re-run integration tests.
+3. If schema changes are introduced, provide explicit compatibility gate or revert schema changes before release.

package/docs/agents/plans/REL-SEMVER-AUTOPUBLISH/plan.md

@@ -0,0 +1,148 @@
+# Implementation Plan — REL-SEMVER-AUTOPUBLISH
+
+Date: 2026-02-23  
+Agent: planning-agent
+
+## Scope (MVP)
+
+Implement minimal semantic version auto-publish for `ai-team` on pushes to `main` using `semantic-release`, with changelog + package version committed back to `main`.
+
+## Exact Files to Change (implementation phase)
+
+1. `package.json`
+   - Add release stack devDependencies.
+   - Add a release script (`"release": "semantic-release"`) for local/CI consistency.
+2. `pnpm-lock.yaml`
+   - Lockfile update from added devDependencies.
+3. `.releaserc.json` (new)
+   - Define `main` as release branch.
+   - Configure semantic-release plugins and plugin order.
+4. `.github/workflows/release.yml` (new)
+   - Push-to-main release workflow with explicit permissions and npm auth.
+5. `CHANGELOG.md` (new/managed by release process)
+   - Created/updated automatically by `@semantic-release/changelog`.
+
+## Dependency Additions (semantic-release stack)
+
+Add to `devDependencies` in `package.json`:
+
+- `semantic-release`
+- `@semantic-release/commit-analyzer`
+- `@semantic-release/release-notes-generator`
+- `@semantic-release/changelog`
+- `@semantic-release/npm`
+- `@semantic-release/git`
+- `@semantic-release/github`
+
+No additional runtime dependencies.
+
+## Semantic-Release Config Approach
+
+Use one repo-root config file: `.releaserc.json`.
+
+Proposed MVP config:
+
+- `branches`: `["main"]`
+- `tagFormat`: `"v${version}"`
+- `plugins` in this order:
+  1. `@semantic-release/commit-analyzer`
+  2. `@semantic-release/release-notes-generator`
+  3. `@semantic-release/changelog` with `changelogFile: "CHANGELOG.md"`
+  4. `@semantic-release/npm` with `npmPublish: true`
+  5. `@semantic-release/github`
+  6. `@semantic-release/git` with assets:
+     - `package.json`
+     - `pnpm-lock.yaml`
+     - `CHANGELOG.md`
+       and message pattern:
+     - `chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}`
+
+Why this approach (minimal):
+
+- Single declarative config file.
+- Keeps release behavior explicit and reproducible.
+- Ensures changelog/version updates are committed after publish.
+
+## GitHub Actions Workflow Details
+
+Workflow file: `.github/workflows/release.yml`
+
+Trigger:
+
+- `on.push.branches: [main]`
+
+Job permissions (explicit):
+
+- `contents: write` (tags + release commit + GitHub release)
+- `issues: write` (plugin capability)
+- `pull-requests: write` (plugin capability)
+
+Auth and environment:
+
+- `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
+- `NPM_TOKEN: ${{ secrets.NPM_TOKEN }}`
+- Add preflight step: fail fast if `NPM_TOKEN` missing.
+- Node setup with npm registry URL and pnpm install using lockfile (`pnpm install --frozen-lockfile`).
+
+Minimal job steps:
+
+1. `actions/checkout` with full history (`fetch-depth: 0`)
+2. `pnpm/action-setup`
+3. `actions/setup-node` (Node LTS + npm registry)
+4. Install deps (`pnpm install --frozen-lockfile`)
+5. Run release (`pnpm release`)
+
+## Step-by-Step Execution Checklist
+
+1. Add release dependencies and script in `package.json`.
+2. Install deps to update `pnpm-lock.yaml`.
+3. Add `.releaserc.json` with branch/plugins configuration.
+4. Add `.github/workflows/release.yml` with trigger/permissions/auth.
+5. Confirm repository secret `NPM_TOKEN` is configured.
+6. Merge to `main` with a Conventional Commit (`feat:` or `fix:`) to validate end-to-end.
+
+## Acceptance Checks Mapped to Requirement Criteria
+
+1. **Workflow runs on push to main**
+   - Check Actions tab shows `release` workflow for a `main` push.
+2. **No-op release succeeds when no semver-relevant commits**
+   - Push commit such as `docs: ...`; verify workflow exits success with "no release" behavior.
+3. **Semver-relevant commits publish and create release artifacts**
+   - Push `fix:` and verify:
+     - computed next version,
+     - npm package published,
+     - git tag `vX.Y.Z` exists,
+     - GitHub release created,
+     - commit back to `main` includes `package.json` + `CHANGELOG.md` (+ lockfile if updated).
+4. **Missing/invalid NPM_TOKEN fails clearly**
+   - Temporarily remove/rotate invalid secret in test repo; verify release job fails with explicit auth/preflight error.
+5. **No manual version bump required**
+   - Verify release succeeds from commit messages only without editing `version` manually.
+
+## Rollback / Failure Notes
+
+1. If publish fails before git commit step:
+   - Fix token/permissions and rerun workflow; no repo file rollback needed.
+2. If git release commit is undesirable:
+   - Revert release commit on `main` and delete erroneous tag/release in GitHub.
+3. If wrong version was published to npm:
+   - Do **not** unpublish stable versions broadly; publish a corrective next version and document in changelog.
+4. If semantic-release config causes repeated failures:
+   - Revert `.releaserc.json` and `.github/workflows/release.yml` via a single rollback commit to restore previous non-automated state.
+
+## Out-of-Scope Guardrails
+
+- No multi-branch channels.
+- No monorepo/workspace release orchestration.
+- No extra CI jobs/quality gates added in this feature.
+
+## Closeout Status (2026-02-23)
+
+- **Current state:** **Blocked (QA not approved)**.
+- **Why blocked:** QA handoff reports end-to-end acceptance is blocked by unresolved lockfile integrity and unavailable runtime CI/publish validation in current environment.
+- **Completion criteria to close feature:**
+  1.  Regenerate and commit `pnpm-lock.yaml` with full semantic-release dependency resolution.
+  2.  Enforce deterministic install in `.github/workflows/release.yml` using `pnpm install --frozen-lockfile`.
+  3.  Execute CI validation on `main` for no-op (`docs:`) and release (`fix:`/`feat:`) paths.
+  4.  Verify `NPM_TOKEN` secret presence and confirm missing/invalid token failure behavior.
+- **Planning decision:** Do not mark feature complete until QA re-runs and returns APPROVED.

package/docs/cli.md

@@ -8,12 +8,13 @@
 - `ai-team update` — apply bundled template updates with drift protection
 - `ai-team plan` (or `diff`) — dry-run preview
 - `ai-team doctor` — validate manifest health and local drift
+- `ai-team version` (or `--version`) — print installed CLI version
 
 ## Runtime Profile
 
 Profile options are selected with flags or interactive prompts:
 
-- `--ide <vscode>`
+- `--ide <vscode|claude-code>`
 - `--team <web-product>`
 - `--include-mcp` or `--no-include-mcp`
 - `--target <path>`
@@ -32,6 +33,13 @@ For `--ide vscode`:
 - MCP config (optional): `.vscode/mcp.json`
 - Install manifest: `.agents/manifest.json`
 
+For `--ide claude-code`:
+
+- Shared assets: `.agents/skills/**`, `.agents/teams/web-product/**`
+- Agent entry files (generated install targets): `.claude/agents/*.md`
+- MCP config (optional): `.mcp.json`
+- Install manifest: `.agents/manifest.json`
+
 Customization is project-owned and out-of-band for the CLI:
 
 - `.agents/custom/skills/`
@@ -43,7 +51,7 @@ Customization is project-owned and out-of-band for the CLI:
 `update` runs in safe mode by default:
 
 - copy-tracked files changed locally are skipped and reported as conflicts
-- JSON assets (`.vscode/mcp.json`) use structured merge
+- JSON assets (`.vscode/mcp.json` / `.mcp.json`) use structured merge
 - `--force` allows overwrite behavior for copy-tracked conflicts
 
 ## Versioning Flow
@@ -52,6 +60,7 @@ Template source of truth:
 
 - Agent templates: `src/agents/definitions/*.yaml`
 - Template pack metadata and path resolution: `templates/bootstrap/manifest.json`
+- Runtime accepts both `packs.ide` (current) and `packs.overlays` (legacy compatibility shim) in the template manifest.
 - `templateVersion` is copied into installed `.agents/manifest.json`
 - `update` compares installed template version and bundled template version
 - change risk should be documented by version in release notes/changelog

package/docs/plan.md

@@ -10,7 +10,7 @@ Build a Node CLI that installs and updates agent template assets from this repo
 
 - Agent template definitions live under `src/agents/definitions/*.yaml`.
 - Platform-neutral base templates live under `templates/bootstrap/base/.agents/**`.
-- VSCode/Copilot overlay templates live under `templates/bootstrap/overlays/vscode-copilot/**`.
+- IDE-specific agent files are rendered from definitions at runtime and can be preview-generated under `templates/bootstrap/base/.agents/generated/agents/**`.
 - Template source metadata lives in `templates/bootstrap/manifest.json` and includes semantic `templateVersion`.
 
 ### Downstream install contract (`--ide vscode`)

package/package.json

@@ -1,29 +1,38 @@
 {
   "name": "ai-team",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "AI agent team management CLI tool",
   "type": "module",
   "main": "src/cli.js",
   "bin": {
     "ai-team": "src/cli.js"
   },
+  "scripts": {
+    "test": "node --test",
+    "ai-team": "node ./src/cli.js",
+    "release": "semantic-release"
+  },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "publishConfig": {
     "access": "public"
   },
+  "packageManager": "pnpm@10.28.1",
   "dependencies": {
-    "@inquirer/prompts": "^8.2.1",
+    "@inquirer/prompts": "^8.3.0",
     "chalk": "^5.6.2",
+    "mustache": "^4.2.0",
     "ora": "^9.3.0",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "mustache": "^4.2.0"
-  },
-  "scripts": {
-    "test": "node --test",
-    "ai-team": "node ./src/cli.js"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^13.1.4",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "semantic-release": "^25.0.3"
   }
-}
+}

package/src/agents/definitions/agent-manager.yaml

@@ -34,7 +34,7 @@ body: |
 
   - Analyze requirements for new or changed agent roles.
   - Create or update source agent definitions in `src/agents/definitions/*.yaml`.
-  - Regenerate agent overlay files from definitions after changes.
+  - Regenerate agent files from definitions after changes.
   - Ensure agents are properly integrated with existing skills and workflows.
   - Update team documentation to reflect the agent structure.
   - Execute the `adopt` command to tailor the agent setup for the current project.
@@ -42,7 +42,7 @@ body: |
   ## Deliverables
 
   - New or updated definition file in `src/agents/definitions/*.yaml`
-  - Regenerated overlay files under `templates/bootstrap/overlays/**`
+  - Regenerated files under `templates/bootstrap/base/.agents/generated/agents/**`
   - Updates to `.agents/teams/web-product/README.md` listing the new agent
   - Updates to `docs/agents/README.md` if workflow changes are significant
 

package/src/agents/generate.js

@@ -3,8 +3,17 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import Mustache from "mustache";
 import YAML from "yaml";
+import { hashText } from "../lib/hash.js";
 
-const IDE_KEYS = ["vscode", "claude"];
+const IDE_TEMPLATE_KEYS = {
+  vscode: "vscode",
+  "vscode-copilot": "vscode",
+  copilot: "vscode",
+  claude: "claude",
+  "claude-code": "claude",
+};
+
+const DEFAULT_SOURCE_PATH_PREFIX = ".generated/agents";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -12,6 +21,18 @@ const repoRoot = path.resolve(__dirname, "../..");
 
 const definitionsDir = path.join(repoRoot, "src/agents/definitions");
 const manifestPath = path.join(repoRoot, "templates/bootstrap/manifest.json");
+const generatedRoot = path.join(
+  repoRoot,
+  "templates/bootstrap/base/.agents/generated/agents",
+);
+
+const normalizeIdeKey = (ide) => {
+  const normalized = IDE_TEMPLATE_KEYS[ide];
+  if (!normalized) {
+    throw new Error(`Unsupported IDE key: ${ide}`);
+  }
+  return normalized;
+};
 
 const pickByIde = (value, ide) => {
   if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -103,34 +124,20 @@ const loadManifest = async () => {
   return JSON.parse(raw);
 };
 
-const getOverlayPaths = (manifest) => {
-  const templateRoot = path.join(repoRoot, "templates/bootstrap");
-  const overlays = manifest.packs?.overlays || {};
-  const vscodeOverlay = overlays.vscode;
-  const claudeOverlay = overlays["claude-code"];
+const getManifestIdePacks = (manifest) => {
+  const idePacks = manifest?.packs?.ide;
+  if (idePacks && typeof idePacks === "object") {
+    return idePacks;
+  }
 
-  if (!vscodeOverlay || !claudeOverlay) {
-    throw new Error("Missing overlay configuration for vscode or claude-code.");
+  const legacyOverlayPacks = manifest?.packs?.overlays;
+  if (legacyOverlayPacks && typeof legacyOverlayPacks === "object") {
+    return legacyOverlayPacks;
   }
 
-  return {
-    vscode: {
-      outputDir: path.join(
-        templateRoot,
-        vscodeOverlay.root,
-        vscodeOverlay.agents,
-      ),
-      agentDir: vscodeOverlay.agents,
-    },
-    claude: {
-      outputDir: path.join(
-        templateRoot,
-        claudeOverlay.root,
-        claudeOverlay.agents,
-      ),
-      agentDir: claudeOverlay.agents,
-    },
-  };
+  throw new Error(
+    "Missing packs.ide (or legacy packs.overlays) configuration in template manifest.",
+  );
 };
 
 const getBody = (definition, ide) => {
@@ -140,17 +147,17 @@ const getBody = (definition, ide) => {
   return pickByIde(definition.body, ide);
 };
 
-const getTemplateVariables = (definition, ide, overlay) => {
+const getTemplateVariables = (definition, ide, config) => {
   const baseName = definition.filename || definition.name;
   return {
-    agentDir: overlay.agentDir,
+    agentDir: config.agents,
     agentFileExt: ide === "vscode" ? "agent.md" : "md",
     agentName: definition.name,
     agentFileName: baseName,
   };
 };
 
-const generateForIde = async (definition, ide, overlay) => {
+const renderAgentDefinition = ({ definition, ide, config }) => {
   const rawBody = getBody(definition, ide);
   if (!rawBody) {
     throw new Error(`Missing body for ${definition.name} (${ide}).`);
@@ -158,18 +165,15 @@ const generateForIde = async (definition, ide, overlay) => {
 
   const frontmatter = buildFrontmatter(definition, ide);
   const fileName = resolveFileName(definition, ide);
-  const variables = getTemplateVariables(definition, ide, overlay);
+  const variables = getTemplateVariables(definition, ide, config);
   const body = Mustache.render(rawBody, variables);
-  const content = `${formatFrontmatter(frontmatter)}${body.trimEnd()}\n`;
-  const outputPath = path.join(overlay.outputDir, fileName);
-
-  await mkdir(path.dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, content, "utf8");
-
-  return outputPath;
+  return {
+    fileName,
+    content: `${formatFrontmatter(frontmatter)}${body.trimEnd()}\n`,
+  };
 };
 
-const loadDefinitions = async () => {
+export const loadDefinitions = async () => {
   const entries = await readdir(definitionsDir, { withFileTypes: true });
   const definitionFiles = entries
     .filter((entry) => entry.isFile())
@@ -191,23 +195,75 @@ const loadDefinitions = async () => {
   return definitions;
 };
 
-const main = async () => {
-  const manifest = await loadManifest();
-  const outputDirs = getOverlayPaths(manifest);
+function normalizeIdeConfig(ideConfig, ideKey) {
+  if (!ideConfig || typeof ideConfig !== "object") {
+    throw new Error(`Missing IDE configuration for ${ideKey}.`);
+  }
+
+  if (!ideConfig.agents) {
+    throw new Error(`Missing agents path for ${ideKey}.`);
+  }
+
+  return ideConfig;
+}
+
+export async function generateAgentEntriesForIde({
+  ide,
+  config,
+  sourcePathPrefix = DEFAULT_SOURCE_PATH_PREFIX,
+}) {
+  const templateIde = normalizeIdeKey(ide);
+  const sourcePathIde = templateIde === "vscode" ? "vscode" : "claude-code";
+  const ideConfig = normalizeIdeConfig(config, ide);
   const definitions = await loadDefinitions();
 
+  return definitions.map(({ definition }) => {
+    const { fileName, content } = renderAgentDefinition({
+      definition,
+      ide: templateIde,
+      config: ideConfig,
+    });
+
+    return {
+      sourcePath: path.posix.join(sourcePathPrefix, sourcePathIde, fileName),
+      targetPath: path.posix.join(ideConfig.agents, fileName),
+      mode: "copy",
+      sourceHash: hashText(content),
+      sourceContent: content,
+    };
+  });
+}
+
+async function writeGeneratedFiles(manifest) {
+  const ideConfigs = getManifestIdePacks(manifest);
+
   const outputs = [];
-  for (const { definition } of definitions) {
-    for (const ide of IDE_KEYS) {
-      const outputPath = await generateForIde(definition, ide, outputDirs[ide]);
+  for (const [ide, config] of Object.entries(ideConfigs)) {
+    const entries = await generateAgentEntriesForIde({ ide, config });
+    const outputDir = path.join(generatedRoot, ide);
+    await mkdir(outputDir, { recursive: true });
+
+    for (const entry of entries) {
+      const fileName = path.basename(entry.targetPath);
+      const outputPath = path.join(outputDir, fileName);
+      await writeFile(outputPath, entry.sourceContent, "utf8");
       outputs.push(outputPath);
     }
   }
 
+  return outputs;
+}
+
+const main = async () => {
+  const manifest = await loadManifest();
+  const outputs = await writeGeneratedFiles(manifest);
+
   console.log(`Generated ${outputs.length} agent files.`);
 };
 
-main().catch((error) => {
-  console.error(error);
-  process.exitCode = 1;
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
+  main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}

package/src/cli.js

@@ -19,8 +19,10 @@ Commands:
   plan      Dry-run preview of changes
   diff      Alias of plan
   doctor    Validate install health and report drift
+  version   Print installed CLI version
 
 Options:
+  -v, --version             Print installed CLI version
   --ide <vscode|claude-code>
   --team <web-product>
   --target <path>           Default: current directory
@@ -33,6 +35,12 @@ Options:
 `);
 }
 
+async function printVersion() {
+  const packageJsonPath = new URL("../package.json", import.meta.url);
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+  console.log(packageJson.version);
+}
+
 function createSpinner(values, text) {
   const canUseSpinner = !values.json && process.stdout.isTTY;
   return ora({ text, isEnabled: canUseSpinner }).start();
@@ -272,6 +280,11 @@ function asJson(values, payload) {
 
 async function run() {
   const [, , commandArg] = process.argv;
+  if (["version", "--version", "-v"].includes(commandArg)) {
+    await printVersion();
+    process.exit(0);
+  }
+
   const command = commandArg === "diff" ? "plan" : commandArg;
 
   if (!command || ["-h", "--help", "help"].includes(command)) {