ai-team 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [1.4.0](https://github.com/seanwuapps/ai-team/compare/v1.3.0...v1.4.0) (2026-02-24)
+
+
+### Features
+
+* add ambiguity handling guidelines across agent definitions ([f5a71cb](https://github.com/seanwuapps/ai-team/commit/f5a71cb0400364df3bbdfd7b07de1775f654573a))
+
+# [1.3.0](https://github.com/seanwuapps/ai-team/compare/v1.2.0...v1.3.0) (2026-02-23)
+
+
+### Features
+
+* ensure mandatory agents are included in profiles and templates ([f48c99c](https://github.com/seanwuapps/ai-team/commit/f48c99c3953303dfee9e552c56dffe36979a692c))
+* update mandatory agents to include product-team-orchestrator ([16bbc8e](https://github.com/seanwuapps/ai-team/commit/16bbc8e5a1292f6c68a00e01be68d14073817741))
+
 # [1.2.0](https://github.com/seanwuapps/ai-team/compare/v1.1.0...v1.2.0) (2026-02-23)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-team",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "AI agent team management CLI tool",
   "type": "module",
   "main": "src/cli.js",

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

@@ -38,6 +38,8 @@ body: |
   - 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.
+  - If user intent or requirements are ambiguous, ask clarifying questions and wait before creating or modifying agent definitions.
+  - Do not proceed to the next workflow step until scope and constraints are explicitly confirmed.
 
   ## Deliverables
 

package/src/agents/definitions/backend-dev.yaml

@@ -59,6 +59,8 @@ body: |
   - Keep API contracts stable unless plan explicitly changes them.
   - Keep secrets server-side only.
   - Use explicit error handling and deterministic behavior.
+  - If requirements, API contracts, data rules, or acceptance criteria are ambiguous, ask clarifying questions and wait for answers before implementation.
+  - Do not change code, schemas, or contracts based on unconfirmed assumptions.
 
   ## Custom Project Extensions
 

package/src/agents/definitions/cli-dev.yaml

@@ -43,6 +43,8 @@ body: |
   - 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
+  - If command behavior, flags, UX expectations, or constraints are ambiguous, ask clarifying questions and wait for answers before implementing
+  - Do not modify CLI flows based on assumptions that were not explicitly confirmed
 
   ## Deliverables
 

package/src/agents/definitions/code-reviewer.yaml

@@ -50,6 +50,8 @@ body: |
   - Keep recommendations scoped to the active feature.
   - Separate must-fix findings from optional improvements.
   - Prefer concrete, file-level guidance with clear next actions.
+  - If review scope, acceptance criteria, or expected behavior is ambiguous, ask clarifying questions before finalizing findings.
+  - Do not produce definitive pass/fail or severity conclusions on ambiguous requirements.
 
   ## Review Checklist
 

package/src/agents/definitions/documentation-writer.yaml

@@ -50,6 +50,8 @@ body: |
   - Use concrete language and examples over abstract descriptions.
   - Document assumptions, prerequisites, and limitations explicitly.
   - Keep scope tight to the active feature or change set.
+  - If behavior, scope, audience, or requirements are ambiguous, ask clarifying questions and wait for answers before drafting.
+  - Do not publish guidance that depends on unconfirmed assumptions.
 
   ## Deliverables
 

package/src/agents/definitions/frontend-dev.yaml

@@ -58,6 +58,8 @@ body: |
   - Reuse existing components/patterns.
   - Keep changes focused and traceable to plan tasks.
   - No hardcoded new design primitives without approval.
+  - If requirements, acceptance criteria, or UX expectations are ambiguous, ask clarifying questions and wait for answers before implementation.
+  - Do not edit files or execute tasks based on unconfirmed assumptions.
 
   ## Custom Project Extensions
 

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

@@ -54,6 +54,8 @@ body: |
   - No new requirements without analyst/user confirmation.
   - Flag conflicts between PRD, progress, and stories.
   - Prefer smallest shippable sequence and explicit dependencies.
+  - If any requirement, dependency, acceptance check, or constraint is ambiguous, ask clarifying questions and wait for answers before continuing.
+  - Do not draft or update plans, handoffs, or implementation steps on unconfirmed assumptions.
 
   ## Planning Standard
 

package/src/agents/definitions/product-team-orchestrator.yaml

@@ -61,6 +61,13 @@ body: |
 
   If available, use the Task tool to spawn the appropriate subagent for each phase. Pass the feature ID and relevant context in the task description.
 
+  ## Ambiguity Gate (Mandatory)
+
+  - If any part of the user's prompt, requirements, scope, constraints, or success criteria is ambiguous, conflicting, or missing, ask clarifying questions first.
+  - Do not route to another agent, create handoffs, or execute any next workflow step until the user resolves the ambiguity.
+  - If multiple ambiguities exist, ask a concise prioritized list of questions and wait for answers.
+  - Do not proceed on assumptions unless the user explicitly confirms them.
+
   ## Handoff Rules
 
   - Every transition must create/update a handoff file in `docs/agents/handoffs/<feature-id>/`.

package/src/agents/definitions/requirement-analyst.yaml

@@ -34,6 +34,8 @@ body: |
   ## Behavior
 
   - Ask concise high-value questions before recommending scope.
+  - If any requirement, term, scope boundary, or constraint is ambiguous, ask clarifying questions and pause until the user answers.
+  - Do not provide recommendations, options, or next-step handoff instructions until ambiguity is resolved.
   - Challenge assumptions and identify risks/anti-goals.
   - Offer 2-3 options with tradeoffs, then recommend one.
   - If requirements change, update:

package/src/agents/definitions/tester.yaml

@@ -68,6 +68,8 @@ body: |
   - Every failure requires repro steps.
   - Every pass/fail item must cite evidence.
   - Distinguish blockers vs polish issues.
+  - If acceptance checks, expected outcomes, or environment setup are ambiguous, ask clarifying questions and wait for answers before running verification.
+  - Do not execute QA steps or report definitive pass/fail against unclear requirements.
 
   ## MCP Tools
 

package/src/lib/prompts.js

@@ -4,6 +4,10 @@ import { fileURLToPath } from "node:url";
 import { readdir, readFile } from "node:fs/promises";
 import { confirm, select, checkbox } from "@inquirer/prompts";
 import YAML from "yaml";
+import {
+  MANDATORY_AGENTS,
+  ensureMandatoryAgents,
+} from "./template-registry.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const definitionsDir = path.resolve(__dirname, "../agents/definitions");
@@ -47,7 +51,7 @@ export async function collectInteractiveProfile({
       ide: ide ?? "vscode",
       team: team ?? "web-product",
       includeMcp: includeMcp ?? true,
-      agents: agents ?? null,
+      agents: ensureMandatoryAgents(agents),
     };
   }
 
@@ -80,6 +84,7 @@ export async function collectInteractiveProfile({
         name: def.emoji ? `${def.emoji}  ${def.name}` : def.name,
         value: def.name,
         checked: true,
+        disabled: MANDATORY_AGENTS.includes(def.name) ? "required" : undefined,
         description: def.description,
       })),
     });
@@ -87,6 +92,8 @@ export async function collectInteractiveProfile({
       selected.length > 0 ? selected : definitions.map((d) => d.name);
   }
 
+  agentsAnswer = ensureMandatoryAgents(agentsAnswer);
+
   let includeMcpAnswer = includeMcp;
   if (includeMcpAnswer === undefined) {
     includeMcpAnswer = await confirm({

package/src/lib/sync-engine.js

@@ -7,6 +7,7 @@ import {
   createManifest,
   bumpManifest,
 } from "./manifest.js";
+import { ensureMandatoryAgents } from "./template-registry.js";
 import { readTextIfExists, writeText } from "./fs-utils.js";
 import { hashText } from "./hash.js";
 import { detectLegacyLayout, applyLegacyMigration } from "./migration.js";
@@ -102,11 +103,16 @@ export async function planSync({
   force = false,
   command = "plan",
 }) {
+  const normalizedProfile = {
+    ...profile,
+    agents: ensureMandatoryAgents(profile.agents),
+  };
+
   const { templateVersion, schemaVersion, entries } =
     await collectTemplateEntries({
-      ide: profile.ide,
-      includeMcp: profile.includeMcp,
-      agents: profile.agents ?? null,
+      ide: normalizedProfile.ide,
+      includeMcp: normalizedProfile.includeMcp,
+      agents: normalizedProfile.agents,
     });
 
   const installedManifest = await loadInstalledManifest(targetDir);
@@ -176,7 +182,7 @@ export async function planSync({
   return {
     command,
     targetDir,
-    profile,
+    profile: normalizedProfile,
     schemaVersion,
     templateVersion,
     hasManifest: Boolean(installedManifest),

package/src/lib/template-registry.js

@@ -8,6 +8,26 @@ import { generateAgentEntriesForIde } from "../agents/generate.js";
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 export const TEMPLATE_ROOT = path.resolve(dirname, "../../templates/bootstrap");
+export const MANDATORY_AGENTS = ["agent-manager", "product-team-orchestrator"];
+
+export function ensureMandatoryAgents(agents) {
+  if (!Array.isArray(agents) || agents.length === 0) {
+    return null;
+  }
+
+  const normalized = new Set(
+    agents
+      .filter((value) => typeof value === "string")
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+
+  for (const mandatoryAgent of MANDATORY_AGENTS) {
+    normalized.add(mandatoryAgent);
+  }
+
+  return Array.from(normalized);
+}
 
 export async function loadTemplateManifest() {
   const filePath = path.join(TEMPLATE_ROOT, "manifest.json");
@@ -87,8 +107,8 @@ export async function collectTemplateEntries({ ide, includeMcp, agents }) {
   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;
+  const normalizedAgents = ensureMandatoryAgents(agents);
+  const agentFilter = normalizedAgents ? new Set(normalizedAgents) : null;
 
   for (const absolutePath of baseFiles) {
     const relative = path.relative(baseRoot, absolutePath);

package/tests/sync-engine.test.js

@@ -105,3 +105,26 @@ test("json merge keeps local MCP servers in safe mode", async () => {
   const updated = JSON.parse(await fs.readFile(mcpPath, "utf8"));
   assert.ok(updated.servers["custom-local"]);
 });
+
+test("applySync persists mandatory agent-manager in manifest profile", async () => {
+  const targetDir = await makeTempDir();
+  const profile = {
+    ide: "vscode",
+    team: "web-product",
+    includeMcp: true,
+    agents: ["planning-agent"],
+  };
+
+  const plan = await planSync({ targetDir, profile });
+  const result = await applySync(plan);
+
+  assert.deepEqual(result.manifest.profile.agents, [
+    "planning-agent",
+    "agent-manager",
+  ]);
+  assert.ok(
+    plan.actions.some(
+      (action) => action.targetPath === ".github/agents/agent-manager.agent.md",
+    ),
+  );
+});

package/tests/template-registry.test.js

@@ -30,6 +30,21 @@ test("collectTemplateEntries omits MCP output when includeMcp is false", async (
   assert.ok(result.entries.every((entry) => entry.targetPath !== ".mcp.json"));
 });
 
+test("collectTemplateEntries always includes agent-manager", async () => {
+  const result = await collectTemplateEntries({
+    ide: "vscode",
+    includeMcp: false,
+    agents: ["planning-agent"],
+  });
+
+  const generatedAgents = result.entries
+    .filter((entry) => entry.targetPath.startsWith(".github/agents/"))
+    .map((entry) => entry.targetPath);
+
+  assert.ok(generatedAgents.includes(".github/agents/planning-agent.agent.md"));
+  assert.ok(generatedAgents.includes(".github/agents/agent-manager.agent.md"));
+});
+
 test("getIdePack supports legacy packs.overlays manifest shape", () => {
   const legacyManifest = {
     packs: {