ai-team 1.0.0

package/src/lib/prompts.js

@@ -0,0 +1,104 @@
+import process from "node:process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readdir, readFile } from "node:fs/promises";
+import { confirm, select, checkbox } from "@inquirer/prompts";
+import YAML from "yaml";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const definitionsDir = path.resolve(__dirname, "../agents/definitions");
+
+async function loadAgentDefinitions() {
+  const files = await readdir(definitionsDir);
+  const yamlFiles = files.filter(
+    (f) => f.endsWith(".yaml") || f.endsWith(".yml"),
+  );
+
+  const definitions = [];
+  for (const file of yamlFiles) {
+    try {
+      const raw = await readFile(path.join(definitionsDir, file), "utf8");
+      const def = YAML.parse(raw);
+      if (def?.name) {
+        definitions.push({
+          name: def.name,
+          emoji: def.emoji ?? "",
+          description:
+            typeof def.description === "string" ? def.description : "",
+        });
+      }
+    } catch {
+      // skip unparseable definitions
+    }
+  }
+
+  return definitions.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function collectInteractiveProfile({
+  ide,
+  team,
+  includeMcp,
+  agents,
+  yes,
+}) {
+  if (yes || process.env.CI === "true") {
+    return {
+      ide: ide ?? "vscode",
+      team: team ?? "web-product",
+      includeMcp: includeMcp ?? true,
+      agents: agents ?? null,
+    };
+  }
+
+  const ideAnswer =
+    ide ??
+    (await select({
+      message: "Select IDE",
+      default: "vscode",
+      choices: [
+        { name: "VS Code (GitHub Copilot)", value: "vscode" },
+        { name: "Claude Code", value: "claude-code" },
+      ],
+    }));
+
+  const teamAnswer =
+    team ??
+    (await select({
+      message: "Select team pack",
+      default: "web-product",
+      choices: [{ name: "web-product", value: "web-product" }],
+    }));
+
+  let agentsAnswer = agents;
+  if (agentsAnswer === undefined || agentsAnswer === null) {
+    const definitions = await loadAgentDefinitions();
+    const selected = await checkbox({
+      message: "Select agents to install",
+      instructions: "  <space> toggle  <a> select all  <enter> confirm",
+      choices: definitions.map((def) => ({
+        name: def.emoji ? `${def.emoji}  ${def.name}` : def.name,
+        value: def.name,
+        checked: true,
+        description: def.description,
+      })),
+    });
+    agentsAnswer =
+      selected.length > 0 ? selected : definitions.map((d) => d.name);
+  }
+
+  let includeMcpAnswer = includeMcp;
+  if (includeMcpAnswer === undefined) {
+    includeMcpAnswer = await confirm({
+      message: "Include MCP config?",
+      default: true,
+    });
+  }
+
+  return {
+    ide: ideAnswer,
+    team: teamAnswer,
+    includeMcp: includeMcpAnswer,
+    agents: agentsAnswer,
+  };
+}

package/src/lib/sync-engine.js

@@ -0,0 +1,319 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { collectTemplateEntries } from "./template-registry.js";
+import {
+  loadInstalledManifest,
+  writeInstalledManifest,
+  createManifest,
+  bumpManifest,
+} from "./manifest.js";
+import { readTextIfExists, writeText } from "./fs-utils.js";
+import { hashText } from "./hash.js";
+import { detectLegacyLayout, applyLegacyMigration } from "./migration.js";
+
+function classifyConflict(entry, reason, currentHash) {
+  return {
+    targetPath: entry.targetPath,
+    type: "conflict",
+    mode: entry.mode,
+    reason,
+    currentHash,
+    sourceHash: entry.sourceHash,
+  };
+}
+
+function mergeJsonObjects(baseValue, sourceValue, preferSource) {
+  if (Array.isArray(baseValue) || Array.isArray(sourceValue)) {
+    return preferSource ? sourceValue : baseValue;
+  }
+
+  if (typeof baseValue !== "object" || baseValue === null) {
+    return sourceValue;
+  }
+
+  if (typeof sourceValue !== "object" || sourceValue === null) {
+    return preferSource ? sourceValue : baseValue;
+  }
+
+  const keys = new Set([
+    ...Object.keys(sourceValue),
+    ...Object.keys(baseValue),
+  ]);
+  const result = {};
+
+  for (const key of keys) {
+    if (!(key in baseValue)) {
+      result[key] = sourceValue[key];
+      continue;
+    }
+
+    if (!(key in sourceValue)) {
+      result[key] = baseValue[key];
+      continue;
+    }
+
+    result[key] = mergeJsonObjects(
+      baseValue[key],
+      sourceValue[key],
+      preferSource,
+    );
+  }
+
+  return result;
+}
+
+function mergeMcpJson(existingRaw, sourceRaw, force) {
+  const sourceJson = JSON.parse(sourceRaw);
+  if (!existingRaw) {
+    return `${JSON.stringify(sourceJson, null, 2)}\n`;
+  }
+
+  const existingJson = JSON.parse(existingRaw);
+  const merged = {
+    ...sourceJson,
+    ...existingJson,
+    servers: mergeJsonObjects(
+      existingJson.servers ?? {},
+      sourceJson.servers ?? {},
+      force,
+    ),
+  };
+
+  return `${JSON.stringify(merged, null, 2)}\n`;
+}
+
+function getFileState(manifestFile, currentText) {
+  const currentHash = currentText === null ? null : hashText(currentText);
+  const installedHash = manifestFile?.installedHash ?? null;
+  const localModified = Boolean(
+    installedHash && currentHash && currentHash !== installedHash,
+  );
+
+  return {
+    currentHash,
+    installedHash,
+    localModified,
+  };
+}
+
+export async function planSync({
+  targetDir,
+  profile,
+  force = false,
+  command = "plan",
+}) {
+  const { templateVersion, schemaVersion, entries } =
+    await collectTemplateEntries({
+      ide: profile.ide,
+      includeMcp: profile.includeMcp,
+      agents: profile.agents ?? null,
+    });
+
+  const installedManifest = await loadInstalledManifest(targetDir);
+  const actions = [];
+  const conflicts = [];
+
+  for (const entry of entries) {
+    const absoluteTargetPath = path.join(targetDir, entry.targetPath);
+    const existingText = await readTextIfExists(absoluteTargetPath);
+    const manifestFile = installedManifest?.files?.[entry.targetPath] ?? null;
+    const state = getFileState(manifestFile, existingText);
+
+    if (entry.mode === "copy") {
+      if (existingText === null) {
+        actions.push({ ...entry, action: "create" });
+        continue;
+      }
+
+      if (state.currentHash === entry.sourceHash) {
+        actions.push({ ...entry, action: "unchanged" });
+        continue;
+      }
+
+      if (state.localModified && !force) {
+        conflicts.push(
+          classifyConflict(entry, "locally-modified", state.currentHash),
+        );
+        actions.push({ ...entry, action: "skip" });
+        continue;
+      }
+
+      actions.push({ ...entry, action: "overwrite" });
+      continue;
+    }
+
+    if (entry.mode === "json-merge") {
+      try {
+        const merged = mergeMcpJson(existingText, entry.sourceContent, force);
+        const mergedHash = hashText(merged);
+
+        if (existingText === merged) {
+          actions.push({
+            ...entry,
+            action: "unchanged",
+            mergedContent: merged,
+            mergedHash,
+          });
+        } else {
+          actions.push({
+            ...entry,
+            action: existingText === null ? "create" : "merge",
+            mergedContent: merged,
+            mergedHash,
+          });
+        }
+      } catch {
+        conflicts.push(
+          classifyConflict(entry, "invalid-json", state.currentHash),
+        );
+        actions.push({ ...entry, action: "skip" });
+      }
+    }
+  }
+
+  const legacyMoves = await detectLegacyLayout(targetDir);
+
+  return {
+    command,
+    targetDir,
+    profile,
+    schemaVersion,
+    templateVersion,
+    hasManifest: Boolean(installedManifest),
+    installedManifest,
+    actions,
+    conflicts,
+    legacyMoves,
+  };
+}
+
+export async function applySync(plan, { applyMigration = false } = {}) {
+  const fileMap = plan.installedManifest?.files
+    ? { ...plan.installedManifest.files }
+    : {};
+  const written = [];
+  const skipped = [];
+
+  for (const action of plan.actions) {
+    const absoluteTargetPath = path.join(plan.targetDir, action.targetPath);
+
+    if (action.action === "skip" || action.action === "unchanged") {
+      skipped.push({ targetPath: action.targetPath, reason: action.action });
+      continue;
+    }
+
+    const payload =
+      action.mode === "json-merge"
+        ? action.mergedContent
+        : action.sourceContent;
+    await writeText(absoluteTargetPath, payload);
+
+    written.push({ targetPath: action.targetPath, action: action.action });
+    fileMap[action.targetPath] = {
+      sourcePath: path
+        .relative(plan.targetDir, action.sourcePath)
+        .split(path.sep)
+        .join("/"),
+      mode: action.mode,
+      sourceHash: action.sourceHash,
+      installedHash: hashText(payload),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  let migration = [];
+  if (applyMigration && plan.legacyMoves.length > 0) {
+    migration = await applyLegacyMigration(plan.targetDir, plan.legacyMoves);
+  }
+
+  const profile = {
+    ide: plan.profile.ide,
+    team: plan.profile.team,
+    includeMcp: plan.profile.includeMcp,
+    agents: plan.profile.agents ?? null,
+  };
+
+  const manifest = plan.hasManifest
+    ? bumpManifest(plan.installedManifest, {
+        schemaVersion: plan.schemaVersion,
+        templateVersion: plan.templateVersion,
+        profile,
+        files: fileMap,
+      })
+    : createManifest({
+        schemaVersion: plan.schemaVersion,
+        templateVersion: plan.templateVersion,
+        profile,
+        files: fileMap,
+      });
+
+  await writeInstalledManifest(plan.targetDir, manifest);
+
+  return {
+    written,
+    skipped,
+    conflicts: plan.conflicts,
+    migration,
+    manifest,
+  };
+}
+
+export async function doctor({ targetDir }) {
+  const manifest = await loadInstalledManifest(targetDir);
+  const issues = [];
+
+  if (!manifest) {
+    issues.push({
+      level: "error",
+      code: "manifest-missing",
+      message: "No .agents/manifest.json found",
+    });
+    return {
+      ok: false,
+      issues,
+      legacyMoves: await detectLegacyLayout(targetDir),
+    };
+  }
+
+  const plan = await planSync({
+    targetDir,
+    profile: manifest.profile,
+    force: false,
+    command: "doctor",
+  });
+
+  if (manifest.templateVersion !== plan.templateVersion) {
+    issues.push({
+      level: "warn",
+      code: "template-outdated",
+      message: `Installed template ${manifest.templateVersion} differs from bundled ${plan.templateVersion}`,
+    });
+  }
+
+  for (const [targetPath] of Object.entries(manifest.files ?? {})) {
+    const absPath = path.join(targetDir, targetPath);
+    try {
+      await fs.access(absPath);
+    } catch {
+      issues.push({
+        level: "warn",
+        code: "missing-file",
+        message: `Missing installed file: ${targetPath}`,
+      });
+    }
+  }
+
+  for (const conflict of plan.conflicts) {
+    issues.push({
+      level: "warn",
+      code: "local-drift",
+      message: `Local drift detected for ${conflict.targetPath}`,
+    });
+  }
+
+  return {
+    ok: issues.every((issue) => issue.level !== "error"),
+    issues,
+    legacyMoves: plan.legacyMoves,
+  };
+}

package/src/lib/template-registry.js

@@ -0,0 +1,107 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promises as fs } from "node:fs";
+import { listFilesRecursive } from "./fs-utils.js";
+import { hashText } from "./hash.js";
+import { getAdapter } from "./adapters.js";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+export const TEMPLATE_ROOT = path.resolve(dirname, "../../templates/bootstrap");
+
+export async function loadTemplateManifest() {
+  const filePath = path.join(TEMPLATE_ROOT, "manifest.json");
+  const raw = await fs.readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+export function getAdapterOverlay(manifest, ide) {
+  if (ide === "vscode" || ide === "copilot" || ide === "vscode-copilot") {
+    return manifest.packs.overlays.vscode;
+  }
+
+  if (ide === "claude-code" || ide === "claude") {
+    return manifest.packs.overlays["claude-code"];
+  }
+
+  throw new Error(`Unsupported IDE: ${ide}`);
+}
+
+function agentNameFromFile(filePath) {
+  const base = path.basename(filePath);
+  // Strip known agent file extensions: .agent.md, .md
+  return base.replace(/\.agent\.md$/, "").replace(/\.md$/, "");
+}
+
+export async function collectTemplateEntries({ ide, includeMcp, agents }) {
+  const manifest = await loadTemplateManifest();
+  const adapter = getAdapter(ide);
+  const overlay = getAdapterOverlay(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 entries = [];
+
+  // Normalise agent filter to a Set for fast lookup (null/undefined = include all)
+  const agentFilter =
+    Array.isArray(agents) && agents.length > 0 ? new Set(agents) : null;
+
+  for (const absolutePath of baseFiles) {
+    const relative = path.relative(baseRoot, absolutePath);
+    const target = adapter.pathMap(
+      path.join(".agents", relative).split(path.sep).join("/"),
+    );
+    const content = await fs.readFile(absolutePath, "utf8");
+    entries.push({
+      sourcePath: absolutePath,
+      targetPath: target,
+      mode: "copy",
+      sourceHash: hashText(content),
+      sourceContent: content,
+    });
+  }
+
+  for (const absolutePath of overlayFiles) {
+    if (agentFilter !== null) {
+      const agentName = agentNameFromFile(absolutePath);
+      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,
+    });
+  }
+
+  if (includeMcp) {
+    const mcpPath = path.join(overlayRoot, overlay.mcp);
+    const content = await fs.readFile(mcpPath, "utf8");
+    entries.push({
+      sourcePath: mcpPath,
+      targetPath: adapter.pathMap(overlay.mcp),
+      mode: "json-merge",
+      sourceHash: hashText(content),
+      sourceContent: content,
+    });
+  }
+
+  return {
+    templateVersion: manifest.templateVersion,
+    schemaVersion: manifest.schemaVersion,
+    entries,
+  };
+}

package/templates/bootstrap/base/.agents/skills/agent-creator/SKILL.md

@@ -0,0 +1,28 @@
+# Agent Creator Skill
+
+This skill defines the process and best practices for creating new custom agents in this workspace.
+
+## Reference
+
+- [Custom Agents in VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+
+## Purpose
+
+Standardize how new agents are defined and integrated into the team workflow.
+
+## Process for Creating a New Agent
+
+1. **Identify the Role**: Determine the specific responsibilities, inputs, and outputs for the agent.
+2. **Create Agent Definition**: Create a new source definition in `src/agents/definitions/<role-name>.yaml`.
+3. **Follow the Template**: Use existing definition files as a template (e.g., `src/agents/definitions/backend-dev.yaml`).
+   - Define `name`, `description`, `argumentHint`, `target`, `tools`, and `handoffs` in YAML.
+   - Write clear instructions in the `body` block.
+4. **Regenerate Outputs**: Regenerate overlay agent files from definitions.
+5. **Register Skills**: Ensure the agent has access to relevant skills by listing them in the "Required References" section.
+6. **Update Documentation**: Add the new agent to `.agents/teams/web-product/README.md` and `docs/agents/README.md` if necessary.
+
+## Best Practices
+
+- Keep agent scope focused and single-purpose where possible.
+- Define clear handoffs to other agents (e.g., "Handoff to Tester").
+- Ensure the agent updates knowledge artifacts (`knowledge/`, `plans/`, etc.) as part of its workflow.

package/templates/bootstrap/base/.agents/skills/ai-integration/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ai-integration
+description: Guidelines for using Gemini with OpenAI compatibility, specifically for handling Structured Outputs and Zod schema limitations.
+---
+
+# AI Integration & Gemini Compatibility
+
+This project uses Google Gemini models via the OpenAI compatibility layer. While this allows us to use the standard OpenAI SDK, there are specific constraints and workarounds required for **Structured Outputs** (JSON Schema).
+
+For the official list of supported JSON Schema features, refer to the [Gemini API Structured Output Documentation](https://ai.google.dev/gemini-api/docs/structured-output#json-schema-support).
+
+## Zod Schema Compatibility
+
+When defining Zod schemas for AI structured outputs, follow these guidelines to ensure compatibility with Gemini:
+
+### 1. Avoid `z.tuple()`
+
+Gemini's JSON Schema validator has issues with `prefixItems` which `z.tuple()` generates.
+**❌ Avoid:**
+
+```typescript
+reps: z.tuple([z.number(), z.number()])
+```
+
+**✅ Use:**
+
+```typescript
+reps: z.array(z.number()) // You can add .length(2) if needed, though strict length validation might also be tricky
+```
+
+### 2. Nullable Fields & Unions
+
+Zod's `.nullable()` often generates an `anyOf` structure (e.g., `anyOf: [{type: 'string'}, {type: 'null'}]`). Gemini prefers a single schema with a type array (e.g., `type: ['string', 'null']`).
+
+We have implemented a `patchSchema` utility in `server/utils/ai.ts` that automatically handles this conversion at runtime. However, keeping schemas simple helps.
+
+### 3. `exclusiveMinimum`
+
+Gemini prefers `minimum` (inclusive) over `exclusiveMinimum`. The `patchSchema` utility automatically converts `exclusiveMinimum` to `minimum + 1` for integers.
+
+## Schema Patching (`server/utils/ai.ts`)
+
+We use a custom `patchSchema` function that intercepts the JSON Schema generated by `zodResponseFormat` before sending it to the API.
+
+**What it does:**
+
+1.  **Flattens `anyOf`**: Recursively flattens nested `anyOf` structures (common with complex unions + nullable).
+2.  **Merges Types**: Collects all types from the flattened options into a single `type` array (e.g., `type: ["integer", "array", "null"]`).
+3.  **Merges Properties**: Naively merges properties from all union members.
+4.  **Converts `exclusiveMinimum`**: Transforms to `minimum`.
+
+**Important:** When using this patching logic, we explicitly set `strict: false` in the API request, as the patched schema might not strictly adhere to the original Zod definition's structure (though it validates the same data).
+
+## Example Usage
+
+```typescript
+// Define schema
+const MySchema = z.object({
+  name: z.string(),
+  tags: z.array(z.string()).nullable(), // Will be patched to type: ['array', 'null']
+})
+
+// Call AI
+const response = await callAI({
+  // ...
+  responseSchema: MySchema,
+  schemaName: 'MySchema',
+})
+```

package/templates/bootstrap/base/.agents/skills/back-end-development/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: back-end-development
+description: Best practices for Nuxt/Node backend development, API contracts, error handling, and observability.
+---
+
+# Back-End Development Skill
+
+## Scope
+
+Use this skill for:
+
+- `server/api/` route implementation
+- validation and API contract design
+- business logic isolation in `server/shared/`
+- data access and migration-safe schema changes
+
+## Standards
+
+1. Define strict input/output schemas.
+2. Return stable error shapes and HTTP semantics.
+3. Keep handlers thin; move logic to shared services.
+4. Add structured logs for failures and key state transitions.
+5. Enforce idempotency for mutating operations when relevant.
+6. Protect secrets and sensitive payload fields.
+7. For each endpoint, add unit tests that cover core functionality and boundary conditions.
+
+## Data & Migration Rules
+
+- For DB work, follow `.agents/skills/database-management/SKILL.md`.
+- Migrations must be reversible when feasible.
+- Update RLS policies and verify access paths.
+
+## AI Route Rules
+
+- For model integration and structured outputs, follow `.agents/skills/ai-integration/SKILL.md`.
+- Validate model output before persistence.
+
+## Definition of Done
+
+- Contract documented and validated
+- Endpoint unit tests cover functionality and boundaries
+- Error paths covered
+- Logging and monitoring hooks added
+- Handoff note includes API examples and edge cases