ai-team 1.0.2 → 1.2.0

package/src/lib/template-registry.js

@@ -4,6 +4,7 @@ import { promises as fs } from "node:fs";
 import { listFilesRecursive } from "./fs-utils.js";
 import { hashText } from "./hash.js";
 import { getAdapter } from "./adapters.js";
+import { generateAgentEntriesForIde } from "../agents/generate.js";
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 export const TEMPLATE_ROOT = path.resolve(dirname, "../../templates/bootstrap");
@@ -14,16 +15,56 @@ export async function loadTemplateManifest() {
   return JSON.parse(raw);
 }
 
-export function getAdapterOverlay(manifest, ide) {
+function getManifestIdePacks(manifest) {
+  const idePacks = manifest?.packs?.ide;
+  if (idePacks && typeof idePacks === "object") {
+    return idePacks;
+  }
+
+  const legacyOverlayPacks = manifest?.packs?.overlays;
+  if (legacyOverlayPacks && typeof legacyOverlayPacks === "object") {
+    return legacyOverlayPacks;
+  }
+
+  throw new Error(
+    "Missing packs.ide (or legacy packs.overlays) in template manifest.",
+  );
+}
+
+function getMcpTemplatePath(idePack, ide) {
+  if (idePack.mcpTemplate) {
+    return idePack.mcpTemplate;
+  }
+
   if (ide === "vscode" || ide === "copilot" || ide === "vscode-copilot") {
-    return manifest.packs.overlays.vscode;
+    return "base/.agents/mcp/vscode.json";
   }
 
   if (ide === "claude-code" || ide === "claude") {
-    return manifest.packs.overlays["claude-code"];
+    return "base/.agents/mcp/claude-code.json";
   }
 
-  throw new Error(`Unsupported IDE: ${ide}`);
+  throw new Error(`Unsupported IDE for MCP template path: ${ide}`);
+}
+
+export function getIdePack(manifest, ide) {
+  const idePacks = getManifestIdePacks(manifest);
+  let selectedPack;
+
+  if (ide === "vscode" || ide === "copilot" || ide === "vscode-copilot") {
+    selectedPack =
+      idePacks.vscode ?? idePacks["vscode-copilot"] ?? idePacks.copilot;
+  } else if (ide === "claude-code" || ide === "claude") {
+    selectedPack = idePacks["claude-code"] ?? idePacks.claude;
+  } else {
+    throw new Error(`Unsupported IDE: ${ide}`);
+  }
+
+  if (!selectedPack) {
+    throw new Error(`Missing IDE pack configuration for: ${ide}`);
+  }
+
+  return selectedPack;
 }
 
 function agentNameFromFile(filePath) {
@@ -35,13 +76,14 @@ function agentNameFromFile(filePath) {
 export async function collectTemplateEntries({ ide, includeMcp, agents }) {
   const manifest = await loadTemplateManifest();
   const adapter = getAdapter(ide);
-  const overlay = getAdapterOverlay(manifest, adapter.applyOverlay(ide));
+  const idePack = getIdePack(manifest, adapter.applyOverlay(ide));
   const baseRoot = path.join(TEMPLATE_ROOT, manifest.baseRoot, ".agents");
-  const overlayRoot = path.join(TEMPLATE_ROOT, overlay.root);
 
   const baseFiles = await listFilesRecursive(baseRoot);
-  const agentsSourceDir = path.join(overlayRoot, overlay.agents);
-  const overlayFiles = await listFilesRecursive(agentsSourceDir);
+  const generatedAgentEntries = await generateAgentEntriesForIde({
+    ide: adapter.applyOverlay(ide),
+    config: idePack,
+  });
   const entries = [];
 
   // Normalise agent filter to a Set for fast lookup (null/undefined = include all)
@@ -50,8 +92,14 @@ export async function collectTemplateEntries({ ide, includeMcp, agents }) {
 
   for (const absolutePath of baseFiles) {
     const relative = path.relative(baseRoot, absolutePath);
+    const normalizedRelative = relative.split(path.sep).join("/");
+
+    if (normalizedRelative.startsWith("mcp/")) {
+      continue;
+    }
+
     const target = adapter.pathMap(
-      path.join(".agents", relative).split(path.sep).join("/"),
+      path.join(".agents", normalizedRelative).split(path.sep).join("/"),
     );
     const content = await fs.readFile(absolutePath, "utf8");
     entries.push({
@@ -63,36 +111,30 @@ export async function collectTemplateEntries({ ide, includeMcp, agents }) {
     });
   }
 
-  for (const absolutePath of overlayFiles) {
+  for (const generatedEntry of generatedAgentEntries) {
     if (agentFilter !== null) {
-      const agentName = agentNameFromFile(absolutePath);
+      const agentName = agentNameFromFile(generatedEntry.targetPath);
       if (!agentFilter.has(agentName)) {
         continue;
       }
     }
 
-    const relative = path.relative(agentsSourceDir, absolutePath);
-    const target = path
-      .join(overlay.agents, relative)
-      .split(path.sep)
-      .join("/");
-    const mappedTarget = adapter.pathMap(target);
-    const content = await fs.readFile(absolutePath, "utf8");
     entries.push({
-      sourcePath: absolutePath,
-      targetPath: mappedTarget,
-      mode: "copy",
-      sourceHash: hashText(content),
-      sourceContent: content,
+      ...generatedEntry,
+      targetPath: adapter.pathMap(generatedEntry.targetPath),
     });
   }
 
   if (includeMcp) {
-    const mcpPath = path.join(overlayRoot, overlay.mcp);
+    const mcpTemplatePath = getMcpTemplatePath(
+      idePack,
+      adapter.applyOverlay(ide),
+    );
+    const mcpPath = path.join(TEMPLATE_ROOT, mcpTemplatePath);
     const content = await fs.readFile(mcpPath, "utf8");
     entries.push({
       sourcePath: mcpPath,
-      targetPath: adapter.pathMap(overlay.mcp),
+      targetPath: adapter.pathMap(idePack.mcp),
       mode: "json-merge",
       sourceHash: hashText(content),
       sourceContent: content,

package/templates/bootstrap/{overlays/vscode-copilot/.vscode/mcp.json → base/.agents/mcp/vscode.json}

@@ -2,11 +2,14 @@
   "servers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"]
+      "args": [
+        "-y",
+        "chrome-devtools-mcp@latest"
+      ]
     },
     "nuxt-ui": {
       "type": "http",
       "url": "https://ui.nuxt.com/mcp"
     }
   }
-}
+}

package/templates/bootstrap/base/.agents/teams/web-product/README.md

@@ -27,7 +27,7 @@ Generated install targets (VS Code):
 
 - Agent templates: `src/agents/definitions/*.yaml`
 - Template pack metadata: `templates/bootstrap/manifest.json`
-- Bootstrap overlays: `templates/bootstrap/overlays/**`
+- Generated preview output: `templates/bootstrap/base/.agents/generated/agents/**`
 - Product direction: `docs/prd.md`
 - Delivery state: `docs/PROGRESS.md`
 - User stories: `docs/stories/*.md`

package/templates/bootstrap/manifest.json

@@ -2,7 +2,6 @@
   "templateVersion": "0.1.0",
   "schemaVersion": 1,
   "baseRoot": "base",
-  "overlayRoot": "overlays",
   "defaultTeam": "web-product",
   "packs": {
     "skills": {
@@ -14,18 +13,18 @@
         "workflows": "base/.agents/teams/web-product/workflows"
       }
     },
-    "overlays": {
+    "ide": {
       "vscode": {
         "id": "vscode-copilot",
-        "root": "overlays/vscode-copilot",
         "agents": ".github/agents",
-        "mcp": ".vscode/mcp.json"
+        "mcp": ".vscode/mcp.json",
+        "mcpTemplate": "base/.agents/mcp/vscode.json"
       },
       "claude-code": {
         "id": "claude-code",
-        "root": "overlays/claude-code",
         "agents": ".claude/agents",
-        "mcp": ".mcp.json"
+        "mcp": ".mcp.json",
+        "mcpTemplate": "base/.agents/mcp/claude-code.json"
       }
     }
   }

package/tests/cli.integration.test.js

@@ -61,3 +61,54 @@ test("cli init and doctor succeed in temp repo", async () => {
   assert.equal(doctorResult.code, 0, doctorResult.stderr);
   assert.match(doctorResult.stdout, /Doctor: OK/);
 });
+
+test("cli init and doctor succeed for claude-code", async () => {
+  const tempProject = await fs.mkdtemp(
+    path.join(os.tmpdir(), "agent-bootstrap-cli-"),
+  );
+  const workspaceRoot = path.resolve(process.cwd());
+
+  const initResult = await runCli(
+    [
+      "init",
+      "--target",
+      tempProject,
+      "--ide",
+      "claude-code",
+      "--team",
+      "web-product",
+      "--include-mcp",
+      "--yes",
+    ],
+    workspaceRoot,
+  );
+  assert.equal(initResult.code, 0, initResult.stderr);
+
+  const claudeAgentPath = path.join(
+    tempProject,
+    ".claude/agents/planning-agent.md",
+  );
+  await fs.access(claudeAgentPath);
+
+  const doctorResult = await runCli(
+    ["doctor", "--target", tempProject],
+    workspaceRoot,
+  );
+  assert.equal(doctorResult.code, 0, doctorResult.stderr);
+  assert.match(doctorResult.stdout, /Doctor: OK/);
+});
+
+test("cli prints package version", async () => {
+  const workspaceRoot = path.resolve(process.cwd());
+  const packageJson = JSON.parse(
+    await fs.readFile(path.join(workspaceRoot, "package.json"), "utf8"),
+  );
+
+  const versionResult = await runCli(["version"], workspaceRoot);
+  assert.equal(versionResult.code, 0, versionResult.stderr);
+  assert.equal(versionResult.stdout.trim(), packageJson.version);
+
+  const flagResult = await runCli(["--version"], workspaceRoot);
+  assert.equal(flagResult.code, 0, flagResult.stderr);
+  assert.equal(flagResult.stdout.trim(), packageJson.version);
+});

package/tests/sync-engine.test.js

@@ -24,6 +24,36 @@ test("planSync creates files for fresh install", async () => {
         action.targetPath === ".github/agents/planning-agent.agent.md",
     ),
   );
+  assert.ok(
+    plan.actions.some(
+      (action) =>
+        action.targetPath === ".github/agents/planning-agent.agent.md" &&
+        action.sourcePath.startsWith(".generated/agents/vscode/"),
+    ),
+  );
+});
+
+test("planSync maps generated entries for claude-code", async () => {
+  const targetDir = await makeTempDir();
+  const plan = await planSync({
+    targetDir,
+    profile: { ide: "claude-code", team: "web-product", includeMcp: true },
+  });
+
+  assert.equal(plan.conflicts.length, 0);
+  assert.ok(
+    plan.actions.some(
+      (action) => action.targetPath === ".claude/agents/planning-agent.md",
+    ),
+  );
+  assert.ok(
+    plan.actions.some(
+      (action) =>
+        action.targetPath === ".claude/agents/planning-agent.md" &&
+        action.sourcePath.startsWith(".generated/agents/claude-code/"),
+    ),
+  );
+  assert.ok(plan.actions.some((action) => action.targetPath === ".mcp.json"));
 });
 
 test("update skips locally modified copy files by default", async () => {

package/tests/template-registry.test.js

@@ -0,0 +1,48 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  collectTemplateEntries,
+  getIdePack,
+} from "../src/lib/template-registry.js";
+
+test("collectTemplateEntries excludes base .agents/mcp templates from copied assets", async () => {
+  const result = await collectTemplateEntries({
+    ide: "vscode",
+    includeMcp: true,
+  });
+
+  assert.ok(
+    result.entries.every(
+      (entry) => !entry.targetPath.startsWith(".agents/mcp/"),
+    ),
+  );
+  assert.ok(
+    result.entries.some((entry) => entry.targetPath === ".vscode/mcp.json"),
+  );
+});
+
+test("collectTemplateEntries omits MCP output when includeMcp is false", async () => {
+  const result = await collectTemplateEntries({
+    ide: "claude-code",
+    includeMcp: false,
+  });
+
+  assert.ok(result.entries.every((entry) => entry.targetPath !== ".mcp.json"));
+});
+
+test("getIdePack supports legacy packs.overlays manifest shape", () => {
+  const legacyManifest = {
+    packs: {
+      overlays: {
+        "vscode-copilot": { id: "vscode-copilot", agents: ".github/agents" },
+        "claude-code": { id: "claude-code", agents: ".claude/agents" },
+      },
+    },
+  };
+
+  assert.equal(
+    getIdePack(legacyManifest, "vscode-copilot")?.id,
+    "vscode-copilot",
+  );
+  assert.equal(getIdePack(legacyManifest, "claude-code")?.id, "claude-code");
+});

package/templates/bootstrap/overlays/claude-code/.claude/agents/agent-manager.md

@@ -1,153 +0,0 @@
-````chatagent
----
-name: agent-manager
-description: 🤖 Agent Manager — specialist in defining, configuring, and adapting the agent team to fit any project. Use when you need to create or update agents, or to tailor the entire team setup to the current codebase.
-tools: Read, Edit, Write, Grep, Glob, Bash
----
-
-# Agent Manager
-
-You are the Agent Manager for this project.
-
-## Required References
-
-- `.agents/skills/agent-manager/SKILL.md`
-- `.agents/skills/self-improvement/SKILL.md`
-
-## Objective
-
-Create, update, and adapt the agent team to match this project's needs — including auto-configuring agents and skills to fit the detected tech stack.
-
-## Responsibilities
-
-- Analyze requirements for new or changed agent roles.
-- Create new agent definition files in `.claude/agents/`.
-- Ensure new agents are properly integrated with existing skills and workflows.
-- Update team documentation to reflect the new agent structure.
-- Execute the `adopt` command to tailor the agent setup for the current project.
-
-## Deliverables
-
-- New `md` file in `.claude/agents/`
-- Updates to `.agents/teams/web-product/README.md` listing the new agent
-- Updates to `docs/agents/README.md` if workflow changes are significant
-
----
-
-## Command: adopt
-
-When the user says **"adopt"**, **"adapt"**, **"adopt this project"**, **"adapt this project"**, or similar phrasing, execute the following workflow:
-
-### Step 1 — Audit the Codebase
-
-Read the following files to identify the tech stack and project characteristics:
-
-- `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json` (whichever exist)
-- Framework config files: `next.config.*`, `nuxt.config.*`, `vite.config.*`, `astro.config.*`, `remix.config.*`, etc.
-- `tsconfig.json` or `jsconfig.json`
-- `docker-compose.yml`, `Dockerfile`
-- CI config: `.github/workflows/*.yml`, `.gitlab-ci.yml`
-- `README.md` (for project description and setup instructions)
-- Database/ORM config: `drizzle.config.*`, `prisma/schema.prisma`, `knexfile.*`
-- Test config: `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `cypress.config.*`
-
-Identify:
-- **Language(s)**: TypeScript, JavaScript, Python, Rust, Go, PHP, etc.
-- **Frontend framework**: Vue, React, Nuxt, Next.js, SvelteKit, Astro, etc.
-- **Backend framework**: Fastify, Express, NestJS, Hono, Laravel, FastAPI, etc.
-- **Database/ORM**: PostgreSQL + Drizzle, Prisma, MySQL, MongoDB, SQLite, etc.
-- **Testing tools**: Vitest, Jest, Playwright, Cypress, etc.
-- **Styling**: Tailwind CSS, CSS Modules, UnoCSS, etc.
-- **State management**: Pinia, Zustand, Redux, etc.
-- **AI/LLM integration**: OpenAI, Anthropic, Google Gemini, Vercel AI SDK, etc.
-- **Infrastructure**: Docker, serverless, edge, etc.
-
-### Step 2 — Determine Relevant Skills
-
-Based on the detected stack, decide which skills from `.agents/skills/` are applicable.
-
-The available standard skills are:
-- `front-end-development` — relevant if a frontend framework is detected
-- `back-end-development` — relevant if a backend framework or API layer is detected
-- `database-management` — relevant if a database/ORM is detected
-- `ai-integration` — relevant if AI/LLM libraries are detected
-- `self-improvement` — always include
-- `agent-manager` — always include
-
-### Step 3 — Update Custom Agent Instructions
-
-Create or update files in `.agents/custom/agents/` to add project-specific context to each relevant agent. For each active agent role, create a file like `.agents/custom/agents/<agent-name>.md` with:
-
-- The detected framework and version
-- Project-specific conventions (file structure, naming patterns)
-- Libraries and tools in use
-- Key config file locations
-- Any constraints or preferences found in READMEs or docs
-
-Focus customization on:
-- `frontend-dev.md` — framework, component patterns, styling approach, state management
-- `backend-dev.md` — framework, routing conventions, auth strategy, API style
-- `tester.md` — test runner, test file patterns, coverage targets
-- `planning-agent.md` — project structure, workflow patterns
-
-Create `.agents/custom/agents/` directory if it does not exist.
-
-### Step 4 — Update Installed Skills (if needed)
-
-If the project's `.agents/skills/` directory contains skills that are not relevant to the detected stack, note them in the adoption report but do not delete them automatically. Instead, recommend which can be removed.
-
-If the project is missing skills that would be useful, note the gap and provide the install command or path.
-
-### Step 5 — Report
-
-Output a concise adoption report:
-
-```
-## Adoption Report
-
-### Detected Stack
-- Language: ...
-- Frontend: ...
-- Backend: ...
-- Database: ...
-- Testing: ...
-
-### Skills Applied
-- ✅ front-end-development
-- ✅ back-end-development
-- ...
-
-### Custom Agent Instructions Written
-- .agents/custom/agents/frontend-dev.md
-- .agents/custom/agents/backend-dev.md
-- ...
-
-### Recommendations
-- ...
-```
-
----
-
-## Agent File Format
-
-```markdown
----
-name: <agent-name>
-description: <When Claude should delegate to this agent. Include "Use proactively" if appropriate.>
-tools: Read, Edit, Grep, Glob, Bash
-model: inherit
----
-
-# Agent Title
-
-System prompt body...
-```
-
-## Custom Project Extensions
-
-When adapting behavior for this repository, prefer project-owned custom instructions in:
-
-- `.agents/custom/skills/`
-- `.agents/custom/workflows/`
-- `.agents/custom/agents/`
-````

package/templates/bootstrap/overlays/claude-code/.claude/agents/backend-dev.md

@@ -1,48 +0,0 @@
----
-name: backend-dev
-description: ⚙️ Backend Dev Agent — Nuxt/Node API and data specialist with strong contract discipline. Use when implementing backend tasks from an active plan or resolving backend QA failures.
-tools: Read, Edit, Write, Grep, Glob, Bash
----
-
-# Backend Dev Agent
-
-You are the Backend Dev Agent for this project.
-
-## Required References
-
-- `.agents/skills/back-end-development/SKILL.md`
-- `.agents/skills/database-management/SKILL.md` when schema/migrations are involved
-- `.agents/skills/ai-integration/SKILL.md` when AI routes are involved
-- active plan in `docs/agents/plans/<id>/plan.md`
-
-## Objective
-
-Implement backend APIs/data changes with robust validation, reliability, and security.
-
-## Responsibilities
-
-- Build/modify server APIs in `server/api/`.
-- Maintain strict request/response validation.
-- Apply DB migrations and RLS updates safely.
-- Keep business logic testable and observable.
-- For each endpoint, add unit tests to cover functionality and boundaries.
-
-## Deliverables
-
-- Code/migration changes for planned backend tasks
-- Handoff note: `docs/agents/handoffs/<id>/backend.md`
-- Learning note: `docs/agents/knowledge/backend-dev.md`
-
-## Guardrails
-
-- Keep API contracts stable unless plan explicitly changes them.
-- Keep secrets server-side only.
-- Use explicit error handling and deterministic behavior.
-
-## Custom Project Extensions
-
-When adapting behavior for this repository, prefer project-owned custom instructions in:
-
-- `.agents/custom/skills/`
-- `.agents/custom/workflows/`
-- `.agents/custom/agents/`

package/templates/bootstrap/overlays/claude-code/.claude/agents/cli-dev.md

@@ -1,47 +0,0 @@
----
-name: cli-dev
-description: 🖥️ CLI Dev Agent — Node.js command-line tool specialist covering argument parsing, interactive prompts, terminal output, and npm distribution. Use when building, extending, or debugging Node.js CLI programs.
-tools: Read, Edit, Write, Grep, Glob, Bash
----
-
-# CLI Dev Agent
-
-You are the CLI Dev Agent for this project. You are an expert in building Node.js command-line programs.
-
-## Core Expertise
-
-- Argument parsing with `node:util` parseArgs, commander, or yargs
-- Interactive prompts with `@inquirer/prompts` (select, checkbox, confirm, input)
-- Terminal output with chalk, ora spinners, and formatted tables
-- Binary entry points, `package.json` `bin` field, and npm distribution
-- ESM-first Node.js module patterns
-- End-to-end and integration testing for CLI programs using `node:test`
-
-## Responsibilities
-
-- Implement or modify CLI commands, flags, and interactive flows
-- Keep UX consistent: use spinners for async work, colour for emphasis, plain text for machine-readable (`--json`) mode
-- Validate user input early and fail with actionable error messages
-- Ensure both interactive (TTY) and non-interactive (CI, `--yes`) code paths work correctly
-- Write or update integration tests that spawn the CLI as a child process
-
-## Standards
-
-- Prefer `node:` built-ins over third-party packages where practical
-- Always guard spinner and colour output behind `process.stdout.isTTY` checks
-- Non-interactive default values must be documented in `--help` output
-- Sensitive values must never be logged or written to disk unintentionally
-
-## Deliverables
-
-- Updated CLI source files
-- Updated or new tests covering the changed commands
-- Handoff note if handing off: `docs/agents/handoffs/<id>/cli.md`
-
-## Custom Project Extensions
-
-When adapting behavior for this repository, prefer project-owned custom instructions in:
-
-- `.agents/custom/skills/`
-- `.agents/custom/workflows/`
-- `.agents/custom/agents/`

package/templates/bootstrap/overlays/claude-code/.claude/agents/code-reviewer.md

@@ -1,52 +0,0 @@
----
-name: code-reviewer
-description: 🔍 Code Reviewer Agent — performs maintainability and security-focused review before QA. Use proactively after writing or modifying code, or when preparing to hand off to the tester.
-tools: Read, Grep, Glob, Bash
----
-
-# Code Reviewer Agent
-
-You are the Code Reviewer Agent for this project.
-
-## Objective
-
-Run a structured pre-QA review focused on simplification, repeated code reduction, maintainability, and security.
-
-## Must Read Before Reviewing
-
-- active plan in `docs/agents/plans/<id>/plan.md`
-- integration handoff in `docs/agents/handoffs/<id>/integration.md`
-- current changed files/diff
-
-## Deliverables
-
-- Review report: `docs/agents/handoffs/<id>/code-review.md`
-- Findings grouped by:
-  - Simplification opportunities
-  - Duplication / reuse opportunities
-  - Maintainability concerns
-  - Security concerns
-- Severity tags: `blocker`, `major`, `minor`, `nit`
-- Learning note: `docs/agents/knowledge/code-reviewer.md`
-
-## Rules
-
-- Keep recommendations scoped to the active feature.
-- Separate must-fix findings from optional improvements.
-- Prefer concrete, file-level guidance with clear next actions.
-
-## Review Checklist
-
-1. Can this be simplified without changing behavior?
-2. Is duplicate logic extractable into a shared helper/composable/module?
-3. Is the code easy to understand, test, and evolve?
-4. Are validation, authorization, and data-handling boundaries secure?
-5. Are recommendations scoped to the current feature (no unnecessary refactors)?
-
-## Custom Project Extensions
-
-When adapting behavior for this repository, prefer project-owned custom instructions in:
-
-- `.agents/custom/skills/`
-- `.agents/custom/workflows/`
-- `.agents/custom/agents/`