@yemi33/minions 0.1.813 → 0.1.814

package/docs/teams-setup.md

@@ -0,0 +1,300 @@
+# Teams Integration Setup
+
+End-to-end guide for connecting Minions to Microsoft Teams via Azure Bot Framework. After completing these steps, messages sent to a Teams channel will be routed to the Minions Command Center, and agent events (completions, PR merges, plan updates) will be posted back to Teams.
+
+**Prerequisites:**
+
+- An Azure subscription (free tier works)
+- Azure CLI installed (`az --version`) or access to the [Azure Portal](https://portal.azure.com)
+- Dev Tunnel CLI installed (`devtunnel --version`) — see [Step 5](#step-5-set-up-dev-tunnel) for installation
+- Minions dashboard running locally (`minions dash`)
+- Admin or owner permissions on the target Teams team (for side-loading)
+
+## Step 1: Create an Azure Bot Resource
+
+1. Open the [Azure Portal](https://portal.azure.com) and search for **Azure Bot** in the top search bar.
+2. Click **Create**.
+3. Fill in the basics:
+   - **Bot handle**: A unique name (e.g., `minions-bot`). This is the internal identifier — it doesn't appear in Teams.
+   - **Subscription**: Select your Azure subscription.
+   - **Resource group**: Create a new one (e.g., `rg-minions`) or use an existing one.
+   - **Data residency**: Choose **Global** unless you have regional compliance requirements.
+   - **Pricing tier**: Select **F0 (Free)** for development.
+4. Under **Microsoft App ID**, select **Single Tenant**.
+   - Choose **Create new Microsoft App ID**.
+   - This creates a new Entra ID (Azure AD) app registration for the bot.
+
+   > **Why Single Tenant?** Single-tenant bots only accept tokens from your Azure AD tenant, which is more secure for an internal tool like Minions. Multi-tenant is needed only if the bot must work across organizations.
+
+5. Click **Review + create**, then **Create**.
+6. Wait for deployment to complete (usually under 1 minute), then click **Go to resource**.
+
+## Step 2: Configure the Teams Channel
+
+1. In your Azure Bot resource, click **Channels** in the left sidebar.
+2. Click the **Microsoft Teams** icon in the available channels list.
+3. Accept the Terms of Service.
+4. Leave the channel settings at defaults:
+   - **Messaging** tab: Enabled (default).
+   - **Calling** and **Group Chat** tabs: Leave disabled unless needed.
+5. Click **Apply**.
+
+The Teams channel should now appear as **Running** in the channels list.
+
+## Step 3: Obtain App ID and App Password
+
+You need two credentials: the **App ID** (also called Microsoft App ID or Client ID) and the **App Password** (a client secret).
+
+### Get the App ID
+
+1. In your Azure Bot resource, click **Configuration** in the left sidebar.
+2. Copy the **Microsoft App ID** value. This is a GUID like `a1b2c3d4-e5f6-7890-abcd-ef1234567890`.
+3. Save it — you'll add it to your Minions config.
+
+### Create an App Password (Client Secret)
+
+1. On the same **Configuration** page, click **Manage Password** next to the Microsoft App ID. This opens the Entra ID app registration.
+2. In the app registration, click **Certificates & secrets** in the left sidebar.
+3. Click **New client secret**.
+4. Enter a description (e.g., `minions-bot-secret`) and choose an expiry (e.g., 24 months).
+5. Click **Add**.
+6. **Immediately copy the secret Value** (not the Secret ID). It is shown only once — if you navigate away, you cannot retrieve it again.
+
+### Add Credentials to Minions Config
+
+Add a `teams` section to your `config.json`:
+
+```json
+{
+  "projects": [ ... ],
+  "agents": { ... },
+  "engine": { ... },
+  "teams": {
+    "enabled": true,
+    "appId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "appPassword": "your-client-secret-value-here",
+    "notifyEvents": ["pr-merged", "agent-completed", "plan-completed", "agent-failed"],
+    "ccMirror": true,
+    "inboxPollInterval": 15000
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `enabled` | Master switch — `true` to activate Teams integration |
+| `appId` | Microsoft App ID from the Azure Bot Configuration page |
+| `appPassword` | Client secret value from Entra ID Certificates & secrets |
+| `notifyEvents` | Which events trigger Teams notifications (see below) |
+| `ccMirror` | Mirror CC dashboard responses to Teams (`true`/`false`) |
+| `inboxPollInterval` | How often to check for new Teams messages, in ms (default: 15000) |
+
+**Available notification events:** `pr-merged`, `agent-completed`, `plan-completed`, `agent-failed`, `pr-abandoned`, `pr-approved`, `pr-build-failed`, `plan-approved`, `plan-rejected`, `verify-created`
+
+> **Security note:** `config.json` is gitignored by default and should never be committed. For shared machines, consider setting the app password via an environment variable and reading it in your config setup.
+
+## Step 4: Set the Messaging Endpoint
+
+The messaging endpoint is the URL that Azure Bot Framework sends incoming messages to. It must point to your Minions dashboard's `/api/bot` route.
+
+1. In your Azure Bot resource, click **Configuration** in the left sidebar.
+2. Set the **Messaging endpoint** to:
+   ```
+   https://<your-tunnel-url>/api/bot
+   ```
+   For local development, this will be your Dev Tunnel URL (see [Step 5](#step-5-set-up-dev-tunnel)).
+
+   For example: `https://abc123.devtunnels.ms/api/bot`
+
+3. Click **Apply** to save.
+
+> The endpoint must be **HTTPS**. Bot Framework will not send messages to plain HTTP URLs. Dev Tunnels and production hosting (Azure App Service, etc.) both provide HTTPS by default.
+
+> Changes to the messaging endpoint take effect immediately — no need to reinstall the bot in Teams.
+
+## Step 5: Set Up Dev Tunnel
+
+[Dev Tunnels](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/overview) create a public HTTPS URL that forwards traffic to your local machine. This lets Azure Bot Framework reach your locally running dashboard.
+
+### Install Dev Tunnel CLI
+
+If you don't have it installed:
+
+```bash
+# Windows (winget)
+winget install Microsoft.devtunnel
+
+# macOS (Homebrew)
+brew install --cask devtunnel
+
+# Linux (curl)
+curl -sL https://aka.ms/DevTunnelCliInstall | bash
+```
+
+### Authenticate
+
+```bash
+devtunnel user login
+```
+
+This opens a browser for Microsoft account authentication. Sign in with the same account that has access to your Azure subscription.
+
+### Start the Tunnel
+
+```bash
+devtunnel host -p 7331 --allow-anonymous
+```
+
+- `-p 7331` forwards to the Minions dashboard port.
+- `--allow-anonymous` allows Bot Framework to reach the endpoint without additional auth (the Bot Framework adapter handles its own authentication via the App ID and Password).
+
+You'll see output like:
+
+```
+Connect via browser: https://abc123.devtunnels.ms
+Inspect network activity: https://abc123-7331.devtunnels.ms
+
+Hosting port: 7331
+  Connect via browser: https://abc123-7331.devtunnels.ms
+```
+
+### Copy the Forwarding URL to Azure Bot
+
+1. Copy the **port-specific** tunnel URL from the output (e.g., `https://abc123-7331.devtunnels.ms`).
+2. Go back to your Azure Bot resource > **Configuration**.
+3. Set the **Messaging endpoint** to:
+   ```
+   https://abc123-7331.devtunnels.ms/api/bot
+   ```
+4. Click **Apply**.
+
+### Persistent Tunnel (Optional)
+
+By default, the tunnel URL changes each time you restart `devtunnel host`. To get a persistent URL:
+
+```bash
+# Create a named tunnel
+devtunnel create minions-tunnel
+
+# Add the port
+devtunnel port create minions-tunnel -p 7331
+
+# Host with anonymous access
+devtunnel host minions-tunnel --allow-anonymous
+```
+
+The named tunnel keeps the same URL across restarts — you won't need to update the Azure Bot messaging endpoint each time.
+
+### Verify Connectivity
+
+With the tunnel running and the dashboard started (`minions dash`), open the tunnel URL in a browser:
+
+```
+https://abc123-7331.devtunnels.ms/api/routes
+```
+
+You should see the Minions API route list as JSON. If you get a connection error, check that:
+- The dashboard is running (`minions dash`)
+- The tunnel is active (`devtunnel host` is still running)
+- The port number matches (7331)
+
+## Step 6: Install the Bot in Teams
+
+There are two ways to add the bot to a Teams channel: via App Studio / Teams Developer Portal (recommended for development) or via the Teams Admin Center (for org-wide deployment).
+
+### Option A: Teams Developer Portal (Recommended for Development)
+
+1. Open [Teams Developer Portal](https://dev.teams.microsoft.com/apps) in a browser.
+2. Click **New app**.
+3. Fill in the app details:
+   - **Name**: `Minions Bot` (or any display name)
+   - **Short description**: `Minions agent orchestration`
+   - **Developer name**: Your name or team name
+   - **Website**: `https://github.com/yemi33/minions` (or any URL)
+   - **Privacy policy** and **Terms of use**: Can be any URL for development
+4. Under **App features**, click **Bot**.
+5. Select **Enter a bot ID manually** and paste the **App ID** from [Step 3](#step-3-obtain-app-id-and-app-password).
+6. Check the scopes:
+   - **Team** — enables the bot in team channels
+   - **Group chat** — optional, enables the bot in group chats
+7. Click **Save**.
+8. Click **Publish** > **Publish to your org** (or **Download app package** to side-load manually).
+
+### Side-Load the App Package
+
+If your organization doesn't allow direct publishing:
+
+1. In the Developer Portal, click **Download app package** to get a `.zip` file.
+2. Open Microsoft Teams.
+3. Click **Apps** in the left sidebar.
+4. Click **Manage your apps** > **Upload an app**.
+5. Select **Upload a custom app** (or **Upload a custom app for [org name]** if you have admin rights).
+6. Choose the downloaded `.zip` file.
+7. In the app details dialog, click **Add to a team**.
+8. Select the team and channel where you want the bot.
+9. Click **Set up a bot**.
+
+### Option B: Teams Admin Center (Org-Wide Deployment)
+
+For deploying to all users or specific groups:
+
+1. Open [Teams Admin Center](https://admin.teams.microsoft.com/).
+2. Go to **Teams apps** > **Manage apps**.
+3. Click **Upload new app** and upload the app package `.zip`.
+4. Go to **Teams apps** > **Setup policies**.
+5. Edit the relevant policy and add the Minions Bot to the **Installed apps** list.
+
+### Verify the Bot Works
+
+1. Open the Teams channel where you installed the bot.
+2. Send a message that @mentions the bot:
+   ```
+   @Minions Bot hello
+   ```
+3. If everything is configured correctly, the message will:
+   - Reach your dashboard via the Dev Tunnel
+   - Be written to `engine/teams-inbox.json`
+   - Be processed by the CC on the next poll cycle
+   - The CC response will appear as a thread reply in Teams
+
+If you don't see a response, check:
+- **Dashboard logs**: Look for incoming `/api/bot` requests
+- **Dev Tunnel**: Ensure it's still running and the URL matches the Azure Bot messaging endpoint
+- **Azure Bot**: Test the bot connection in the Azure Portal via **Test in Web Chat** (Configuration page)
+- **Config**: Verify `config.json` has `teams.enabled: true` and correct `appId`/`appPassword`
+
+## Troubleshooting
+
+### "Unauthorized" or 401 Errors
+
+The App ID or App Password in `config.json` doesn't match what's registered in Azure. Double-check:
+- The App ID matches the Azure Bot's **Microsoft App ID** on the Configuration page.
+- The App Password is the client secret **Value** (not the Secret ID) from Entra ID.
+- The client secret hasn't expired.
+
+### "Endpoint not reachable" in Azure Bot Test
+
+- Verify the Dev Tunnel is running: `devtunnel host -p 7331 --allow-anonymous`
+- Verify the messaging endpoint URL ends with `/api/bot`
+- Verify the dashboard is running: `minions dash`
+- Try opening the tunnel URL in a browser to confirm it's accessible
+
+### Bot Doesn't Respond in Teams
+
+- Check `engine/teams-inbox.json` — if messages appear there, the webhook is working but the CC processing loop may not be running.
+- Check that the engine is running: `minions start`
+- Check the engine logs for Teams-related errors.
+- Ensure `config.teams.enabled` is `true`.
+
+### "App not found" When Side-Loading
+
+- Your Teams admin may have disabled custom app side-loading. Contact your Teams admin to enable **Upload custom apps** in the Teams Admin Center > Setup policies.
+- Alternatively, ask an admin to upload the app via the Admin Center (Option B above).
+
+## What's Next
+
+Once the bot is responding to messages in Teams:
+
+- **Agent notifications** will appear in the Teams channel when agents complete work, PRs are merged, or plans are finished.
+- **CC mirror** mode (enabled by default) posts Command Center responses from the dashboard to Teams so the whole team sees orchestration activity.
+- For production deployment (replacing Dev Tunnel with a stable public URL), see [docs/teams-production.md](teams-production.md).

package/engine/ado.js

@@ -441,6 +441,13 @@ async function pollPrStatus(config) {
           pr.buildErrorLog = logParts.join('\n\n');
           log('info', `PR ${pr.id}: fetched error logs from ${logParts.length} failing pipeline(s)`);
         }
+
+        // Teams notification for build failure — non-blocking
+        try {
+          const teams = require('./teams');
+          const prFilePath = shared.projectPrPath(project);
+          teams.teamsNotifyPrEvent(pr, 'build-failed', project, prFilePath).catch(() => {});
+        } catch {}
       }
     }
 

package/engine/cli.js

@@ -372,6 +372,19 @@ const commands = {
       }
     }, 3000);
 
+    // Teams inbox poll timer — process incoming Teams messages through CC
+    const teams = require('./teams');
+    const teamsInboxInterval = config.teams?.inboxPollInterval ?? shared.ENGINE_DEFAULTS.teams.inboxPollInterval;
+    const teamsInboxTimer = teams.isTeamsEnabled() ? setInterval(() => {
+      try {
+        const ctrl = getControl();
+        if (ctrl.state !== 'running') return;
+        teams.processTeamsInbox().catch(err => {
+          shared.log('warn', `Teams inbox poll error: ${err.message}`);
+        });
+      } catch {}
+    }, teamsInboxInterval) : null;
+
     console.log(`Tick interval: ${interval / 1000}s | Max concurrent: ${config.engine?.maxConcurrent || 5}`);
     console.log('Press Ctrl+C to stop');
 
@@ -422,6 +435,7 @@ const commands = {
       console.log(`\n${signal} received — initiating graceful shutdown...`);
       clearInterval(tickTimer);
       clearInterval(fastPollTimer);
+      if (teamsInboxTimer) clearInterval(teamsInboxTimer);
       for (const f of _watchedFiles) { try { fs.unwatchFile(f); } catch { /* cleanup */ } }
       safeWrite(CONTROL_PATH, { state: 'stopping', pid: process.pid, stopping_at: e.ts() });
       e.log('info', `Graceful shutdown initiated (${signal})`);
@@ -894,9 +908,9 @@ const commands = {
     const e = engine();
     console.log('\n=== Kill All Active Work ===\n');
     const config = getConfig();
-    const dispatch = getDispatch();
     const shared = require('./shared');
 
+    // Kill processes via PID files (expensive — outside dispatch lock)
     const pidFiles = fs.readdirSync(ENGINE_DIR).filter(f => f.startsWith('pid-'));
     for (const f of pidFiles) {
       const pid = safeRead(path.join(ENGINE_DIR, f)).trim();
@@ -904,7 +918,15 @@ const commands = {
       fs.unlinkSync(path.join(ENGINE_DIR, f));
     }
 
-    const killed = dispatch.active || [];
+    // Atomically read and clear dispatch.active (locked read-modify-write)
+    let killed = [];
+    e.mutateDispatch((dispatch) => {
+      killed = dispatch.active || [];
+      dispatch.active = [];
+      return dispatch;
+    });
+
+    // Reset work items outside the dispatch lock (work-items.json has its own lock)
     for (const item of killed) {
       if (item.meta) {
         e.updateWorkItemStatus(item.meta, WI_STATUS.PENDING, '');
@@ -932,8 +954,6 @@ const commands = {
 
       console.log(`Killed dispatch: ${item.id} (${item.agent}) — work item reset to pending`);
     }
-    dispatch.active = [];
-    safeWrite(DISPATCH_PATH, dispatch);
 
     // Agent status derived from dispatch.json — clearing dispatch.active is sufficient.
     console.log('All agents reset to idle (dispatch cleared)');

package/engine/github.js

@@ -411,6 +411,13 @@ async function pollPrStatus(config) {
               pr.buildErrorLog = errorLog;
               log('info', `PR ${pr.id}: fetched ${errorLog.split('\n').length} lines of build error log`);
             }
+
+            // Teams notification for build failure — non-blocking
+            try {
+              const teams = require('./teams');
+              const prFilePath = shared.projectPrPath(project);
+              teams.teamsNotifyPrEvent(pr, 'build-failed', project, prFilePath).catch(() => {});
+            } catch {}
           }
         }
       }

package/engine/lifecycle.js

@@ -277,10 +277,25 @@ function checkPlanCompletion(meta, config) {
       });
     });
     log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
+
+    // Teams notification for verify creation — non-blocking
+    try {
+      const teams = require('./teams');
+      teams.teamsNotifyPlanEvent({ name: plan.plan_summary || planFile, file: planFile }, 'verify-created').catch(() => {});
+    } catch {}
   }
 
   // Archive deferred until verify completes
 
+  // Teams notification for plan completion — non-blocking
+  try {
+    const teams = require('./teams');
+    teams.teamsNotifyPlanEvent({
+      name: plan.plan_summary || planFile, file: planFile, project: plan.project,
+      doneCount: doneItems.length, totalCount: planFeatureIds.size,
+    }, 'plan-completed').catch(() => {});
+  } catch {}
+
   log('info', `PRD ${planFile} completed: ${doneItems.length} done, ${failedItems.length} failed, runtime ${runtimeMin}m`);
   return true;
 }
@@ -751,9 +766,13 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary)
     if (!Array.isArray(prs)) return prs;
     const target = prs.find(p => p.id === pr.id);
     if (!target) return prs;
-    // Once approved, stays approved permanently — no path can downgrade
-    if (postReviewStatus && target.reviewStatus !== 'approved') {
-      target.reviewStatus = postReviewStatus;
+    // Once approved, stays approved — only changes-requested can override
+    if (postReviewStatus) {
+      if (target.reviewStatus === 'approved' && postReviewStatus !== 'changes-requested') {
+        // Keep approved — don't downgrade
+      } else {
+        target.reviewStatus = postReviewStatus;
+      }
     }
     target.lastReviewedAt = ts();
     target.minionsReview = {
@@ -1019,16 +1038,13 @@ async function handlePostMerge(pr, project, config, newStatus) {
     });
   }
 
-  const teamsUrl = process.env.TEAMS_PLAN_FLOW_URL;
-  if (teamsUrl) {
-    try {
-      await fetch(teamsUrl, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ text: `PR ${pr.id} merged: ${pr.title} (${project.name}) by ${pr.agent || 'unknown'}` })
-      });
-    } catch (err) { log('warn', `Teams post-merge notify failed: ${err.message}`); }
-  }
+  // Teams PR lifecycle notification — non-blocking
+  try {
+    const teams = require('./teams');
+    const prEvent = newStatus === PR_STATUS.MERGED ? 'pr-merged' : 'pr-abandoned';
+    const prFilePath = project ? projectPrPath(project) : null;
+    teams.teamsNotifyPrEvent(pr, prEvent, project, prFilePath).catch(() => {});
+  } catch {}
 
   log('info', `Post-merge hooks completed for ${pr.id}`);
 }
@@ -1630,6 +1646,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const metricsResult = isAutoRetry ? 'retry' : finalResult;
   updateMetrics(agentId, dispatchItem, metricsResult, taskUsage, prsCreatedCount, model);
 
+  // Teams notification — non-blocking
+  try {
+    const teams = require('./teams');
+    teams.teamsNotifyCompletion(dispatchItem, finalResult, agentId).catch(() => {});
+  } catch {}
+
   return { resultSummary, taskUsage, autoRecovered, structuredCompletion };
 }
 

package/engine/preflight.js

@@ -192,6 +192,19 @@ function doctor(minionsHome) {
     } else {
       runtimeResults.push({ name: 'Agents configured', ok: false, message: 'no agents in config.json' });
     }
+
+    // Check Teams integration
+    const teams = config.teams;
+    if (teams && teams.enabled === true) {
+      if (!teams.appId || !teams.appPassword) {
+        const missing = [!teams.appId && 'appId', !teams.appPassword && 'appPassword'].filter(Boolean).join(', ');
+        runtimeResults.push({ name: 'Teams integration', ok: 'warn', message: `enabled but missing: ${missing}` });
+      } else {
+        runtimeResults.push({ name: 'Teams integration', ok: true, message: 'configured' });
+      }
+    } else {
+      runtimeResults.push({ name: 'Teams integration', ok: 'warn', message: 'disabled — see docs/teams-setup.md' });
+    }
   } catch {
     runtimeResults.push({ name: 'Config', ok: false, message: `missing or invalid — run: minions init` });
   }

package/engine/shared.js

@@ -553,6 +553,15 @@ const ENGINE_DEFAULTS = {
   ccModel: 'sonnet', // model for Command Center and doc-chat (sonnet, haiku, opus)
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
   ccMaxTurns: 50, // max tool-use turns for CC/doc-chat before CLI stops
+  // Teams integration — config.teams shape: { enabled, appId, appPassword, notifyEvents, ccMirror, inboxPollInterval }
+  teams: {
+    enabled: false,
+    appId: '',
+    appPassword: '',
+    notifyEvents: ['pr-merged', 'agent-completed', 'plan-completed', 'agent-failed'],
+    ccMirror: true,
+    inboxPollInterval: 15000,
+  },
 };
 
 // ─── Status & Type Constants ─────────────────────────────────────────────────

package/engine/teams-cards.js

@@ -0,0 +1,137 @@
+/**
+ * engine/teams-cards.js — Adaptive Card templates for Teams notifications.
+ * All cards use schema version 1.4 and include fallback text.
+ */
+
+const SCHEMA = 'http://adaptivecards.io/schemas/adaptive-card.json';
+const VERSION = '1.4';
+const DASHBOARD_URL = 'http://localhost:7331';
+
+function wrapCard(body, actions, fallbackText) {
+  return {
+    type: 'AdaptiveCard',
+    $schema: SCHEMA,
+    version: VERSION,
+    fallbackText: fallbackText || 'Minions notification',
+    body,
+    actions: actions || [],
+  };
+}
+
+/**
+ * Agent completion card — shows agent name, task title, result, PR link.
+ * @param {string} agent — agent name/id
+ * @param {object} item — { title, id }
+ * @param {string} result — 'success' or 'error'
+ * @param {string} [prUrl] — PR URL if available
+ */
+function buildCompletionCard(agent, item, result, prUrl) {
+  const isSuccess = result === 'success';
+  const badge = isSuccess ? 'Done' : 'Failed';
+  const color = isSuccess ? 'good' : 'attention';
+  const title = item?.title || item?.id || 'Unknown task';
+
+  const body = [
+    { type: 'TextBlock', text: `${badge} — ${agent}`, weight: 'bolder', size: 'medium', color },
+    { type: 'TextBlock', text: title, wrap: true },
+  ];
+
+  const actions = [
+    { type: 'Action.OpenUrl', title: 'Open Dashboard', url: DASHBOARD_URL },
+  ];
+  if (prUrl) {
+    actions.unshift({ type: 'Action.OpenUrl', title: 'View PR', url: prUrl });
+  }
+
+  return wrapCard(body, actions, `${badge}: ${agent} — ${title}`);
+}
+
+/**
+ * PR lifecycle card — shows PR title, event, author, project.
+ * @param {object} pr — { id, title, url, agent }
+ * @param {string} event — 'pr-merged', 'pr-abandoned', 'build-failed', etc.
+ * @param {object} [project] — { name }
+ */
+function buildPrCard(pr, event, project) {
+  const title = pr?.title || pr?.id || 'Unknown PR';
+  const agent = pr?.agent || 'unknown';
+  const projectName = project?.name || '';
+
+  const body = [
+    { type: 'TextBlock', text: `${event}`, weight: 'bolder', size: 'medium' },
+    { type: 'ColumnSet', columns: [
+      { type: 'Column', width: 'stretch', items: [
+        { type: 'TextBlock', text: title, wrap: true, weight: 'bolder' },
+        { type: 'TextBlock', text: `${agent}${projectName ? ' | ' + projectName : ''}`, isSubtle: true, spacing: 'none' },
+      ]},
+    ]},
+  ];
+
+  const actions = [
+    { type: 'Action.OpenUrl', title: 'Open Dashboard', url: DASHBOARD_URL },
+  ];
+  if (pr?.url) {
+    actions.unshift({ type: 'Action.OpenUrl', title: 'View PR', url: pr.url });
+  }
+
+  return wrapCard(body, actions, `${event}: ${title} (${agent})`);
+}
+
+/**
+ * Plan lifecycle card — shows plan name, event, item counts.
+ * @param {object} plan — { name, file, doneCount, totalCount }
+ * @param {string} event — 'plan-completed', 'plan-approved', 'plan-rejected', 'verify-created'
+ */
+function buildPlanCard(plan, event) {
+  const name = plan?.name || plan?.file || 'Unknown plan';
+  const hasCounts = plan?.doneCount != null && plan?.totalCount != null;
+
+  const body = [
+    { type: 'TextBlock', text: `${event}`, weight: 'bolder', size: 'medium' },
+    { type: 'TextBlock', text: name, wrap: true },
+  ];
+
+  if (hasCounts) {
+    body.push({ type: 'TextBlock', text: `${plan.doneCount}/${plan.totalCount} items completed`, isSubtle: true });
+  }
+
+  const actions = [
+    { type: 'Action.OpenUrl', title: 'Open Dashboard', url: `${DASHBOARD_URL}/prd` },
+  ];
+
+  return wrapCard(body, actions, `${event}: ${name}${hasCounts ? ` (${plan.doneCount}/${plan.totalCount})` : ''}`);
+}
+
+/**
+ * CC response mirror card — shows user question and CC answer.
+ * @param {string} question — user's CC input
+ * @param {string} answer — CC response (truncated if needed)
+ */
+function buildCCResponseCard(question, answer) {
+  const maxLen = 3000;
+  const truncated = answer.length > maxLen
+    ? answer.slice(0, maxLen) + '...'
+    : answer;
+
+  const body = [
+    { type: 'TextBlock', text: 'Command Center', weight: 'bolder', size: 'medium' },
+    { type: 'TextBlock', text: `> ${question.slice(0, 200)}`, wrap: true, isSubtle: true },
+    { type: 'TextBlock', text: truncated, wrap: true },
+  ];
+
+  const actions = [
+    { type: 'Action.OpenUrl', title: 'Open Dashboard', url: DASHBOARD_URL },
+  ];
+
+  return wrapCard(body, actions, `CC: ${question.slice(0, 100)} — ${answer.slice(0, 200)}`);
+}
+
+module.exports = {
+  buildCompletionCard,
+  buildPrCard,
+  buildPlanCard,
+  buildCCResponseCard,
+  SCHEMA,
+  VERSION,
+  DASHBOARD_URL,
+};