name: mcs-build description: "Use this skill to build an agent in Copilot Studio from a researched brief.json. Runs pre-build validation (auth, env, connections, tools, model), then creates the agent, configures instructions, knowledge, tools, model, topics, and publishes. Supports single-agent, multi-agent, and connected-agent architectures. Use after /mcs-research when brief.json is ready, or to resume a partially completed build."

MCS Agent Builder — Unified Hybrid Build Stack

Build agents in Microsoft Copilot Studio using the optimized hybrid approach: PAC CLI for listing agents and solution ALM, LSP wrapper for instructions, model, topics, knowledge, and full component sync, Dataverse API for file uploads and PvaPublish, and user-guided manual steps for new OAuth connections.

This skill handles all build modes:

• Single Agent — standalone build
• Multi-Agent — builds specialists first, then orchestrator with child connections

Build Discipline — Verify-Then-Mark

These rules apply to every build step, because unverified changes silently accumulate into broken agents.

1. Atomic tasks: Every build step is a separate task. "Generate file" and "upload file" and "run eval" are three tasks, not one.
2. Verify after every action: After each change, snapshot or read-back to confirm it worked.
3. Do not mark a task complete until verified: If you can't verify, say "I did X but couldn't verify Y".
4. File generation is not deployment: Writing a local file is not the same as uploading it to MCS.
5. Environment check: Before PAC CLI ops, verify the agent's environment matches PAC CLI's active profile.
6. Attempt every MVP item: Attempt every item in the brief tagged phase: "mvp". If an item fails, document: (a) what was tried, (b) the specific error, (c) what's needed to unblock it. A failed attempt with a clear error is valuable; a silently skipped item is a build gap.
7. End-of-build reconciliation: After all changes, walk the brief's component list and snapshot-verify each item. Every MVP item shows MATCH, PARTIAL (with reason), FAILED (with error), or BLOCKED (with dependency). Zero items should show SKIPPED.

Input

/mcs-build {projectId} {agentId}              # Full build (includes full guard)
/mcs-build {projectId} {agentId} --quick      # Quick guard (auth + env only, skip connection/knowledge/tool/model checks)

Reads from:

• Build-Guides/{projectId}/agents/{agentId}/brief.json — the single source of truth (architecture, tools, instructions, model, topics, everything)

Writes to:

• Build-Guides/{projectId}/agents/{agentId}/brief.json — updates buildStatus field
• Build-Guides/{projectId}/agents/{agentId}/build-report.md — customer-shareable summary

Progress Markers

Emit ##PROGRESS## JSON markers at each step transition. Steps: auth, context, create, instructions, knowledge, tools, model, topics, publish, validate. Format: ##PROGRESS## {"step":"...","label":"...","status":"running|completed|failed|skipped","detail":"..."}. Emit ##BUILD_COMPLETE## at the end. Emit ##AUTH_REQUIRED## when user action needed (e.g., OAuth consent). Always emit regardless of headless or interactive mode.

Smart Build Account & Environment Gate

Every build targets a specific tenant and environment. This gate reads persisted context, confirms with the user, and verifies Azure CLI + Dataverse + PAC CLI (optional) all work before proceeding.

Full protocol: see reference/auth-gate.md

Step 0.9: Populate Build Context

After auth is verified, capture all derived state into brief.json.buildStatus so every subsequent step reads from one place instead of re-deriving URLs, IDs, and GUIDs.

1. From session-config.json (looked up by accountId + environment name):

   • dataverseUrl, gatewayUrl, environmentId

2. From Dataverse (if mcsAgentId exists — resume build):

   • botSchemaName — GET bots(<mcsAgentId>) full entity (query without $select because it can miss fields)
   • gptComponentId — FetchXML query for botcomponent where parentbotid=<mcsAgentId> AND componenttype=15. Use FetchXML with parentbotid (logical name) because OData filter with _parentbotid_value is unreliable.

3. Persist to brief.json.buildStatus — write all fields atomically.

4. Log Build Context:

   Build Context:
     Agent: {name} ({mcsAgentId || "new — will be created in Step 1"})
     Environment: {environment} ({environmentId})
     Dataverse: {dataverseUrl}
     Gateway: {gatewayUrl}
     Workspace: {workspacePath || "will be created in Step 1e"}
     Tenant: {azTenantId}
   

All subsequent steps use buildStatus fields directly: Dataverse calls use dataverseUrl + mcsAgentId, Gateway calls use gatewayUrl + environmentId, LSP push/pull uses workspacePath, description PATCH uses gptComponentId, PAC CLI uses botSchemaName.

After Step 1 (create agent): update mcsAgentId, botSchemaName, gptComponentId from the newly created agent.

Phase 0: Pre-Build Validation (Guard)

Validate all prerequisites before expensive operations begin. Catches auth failures, missing connections, unreachable knowledge sources, and model gaps that would otherwise waste build time. Runs automatically at the start of every build — no separate guard step needed.

Supports two modes:

• Full (default): all 7 checks
• Quick (--quick flag on /mcs-build): checks 1-3 only (auth + env + PAC)

Each check produces pass, warn, fail, or skipped (when a dependency check failed). Run all checks even if early ones fail — report everything at once.

Check 1: Azure CLI Auth

Validates current Azure CLI session is authenticated to the correct tenant.

az account show --query "{user:user.name, tenant:tenantId}" -o json
az account get-access-token --resource https://{org}.crm.dynamics.com --query accessToken -o tsv

If fail: stop checks that depend on Dataverse. Report: "Run az login --tenant {tenantId} to authenticate."

Check 2: Environment Reachability

Validates target Dataverse environment responds.

node -e "const {get} = require('./tools/lib/http'); get('{dvUrl}/api/data/v9.2/WhoAmI').then(r => console.log(JSON.stringify(r)))"

Check 3: PAC CLI Profile

Validates PAC CLI targets the same environment. pac auth list + pac env who.

PAC CLI failure is always a warn for overall status (API fallback exists).

Check 4: Required Connections

Validates all connections from brief.json.integrations[] exist in the target environment.

1. Read brief.json.integrations[] — extract required connector names
2. Run add-tool.js discover-connections --dataverse-url <url>
3. Match each required integration against discovered connections

If fail: report which connections are missing with manual creation instructions.

Check 5: Knowledge Sources Accessibility

Validates all knowledge sources from brief.json.knowledge[] are reachable.

• Public URLs: HTTP HEAD request, check for 200/301/302
• SharePoint sites: Graph API GET /sites/{hostname}:/{path}
• Dataverse files: Check annotation table for file existence

Check 6: Tool / MCP Server Availability

Validates all tools from brief.json.tools[] are configured and responsive.

1. Read brief.json.tools[] — extract tool names and types
2. For MCP servers: check add-tool.js list-connections output
3. For Work IQ servers: verify Work IQ MCP is configured

Check 7: Model Availability

Validates requested AI model is available for the target environment.

node tools/island-client.js list-models --env {envUrl}

Match brief.json.model.name against available models.

Guard Output

Write results to brief.json.guardReport:

{
  "guardReport": {
    "status": "pass|warn|fail",
    "mode": "full|quick",
    "checkedAt": "2026-03-31T12:00:00Z",
    "checks": [{ "name": "...", "status": "...", "summary": "...", "evidence": [], "fix": null }],
    "blockingIssues": [],
    "warnings": [],
    "nextAction": "..."
  }
}

Status precedence: fail > warn > pass. Any hard fail = overall fail.

• All pass: proceed to Step 1
• Warnings only: log warnings, proceed
• Any fail: stop build, report blocking issues with remediation steps

Guard Progress Markers

##PROGRESS## {"step":"guard-auth","label":"Checking Azure CLI auth","status":"running"}
##PROGRESS## {"step":"guard-env","label":"Checking environment","status":"running"}
##PROGRESS## {"step":"guard-connections","label":"Checking connections","status":"running"}
##PROGRESS## {"step":"guard-knowledge","label":"Checking knowledge sources","status":"running"}
##PROGRESS## {"step":"guard-tools","label":"Checking tools/MCP","status":"running"}
##PROGRESS## {"step":"guard-model","label":"Checking model availability","status":"running"}

Brief Completeness (always runs, even in quick mode)

1. Brief completeness: instructions non-empty and < 8000 chars, agent name non-empty, agent description present (warn if missing), at least 1 MVP capability

If workspace is missing, clear workspacePath and re-clone in Step 1e. If agent was deleted, clear mcsAgentId and re-create in Step 1.

MVP Phase Filtering

Only build items tagged phase: "mvp". Skip items tagged phase: "future".

Scan the brief and compute build scope across capabilities, integrations, knowledge, and topics. Output a scope summary:

## Build Scope (MVP filter)
- Capabilities: {N} MVP, {M} deferred
- Integrations: {N} MVP, {M} deferred
- Knowledge: {N} MVP, {M} deferred
- Topics: {N} MVP, {M} deferred

If all items of a type are future, skip that entire build step and note it. Deferred items are listed in the build report (Section 9) so the customer knows what's coming next.

Step 0.25: Solution Type Gate

Reads brief.json.architecture.solutionType. If "agent" or not set — proceed. If "hybrid" — proceed, log which capabilities are flow-only. If "flow" or "not-recommended" — hard stop with explanation and override instructions (architecture.solutionTypeOverride = true).

Step 0.5: Decision Gate

Reads brief.json.decisions[], filters to MVP-relevant decisions, categorizes as hard-block (architecture, infrastructure) or soft-warning (integration, model, topic-implementation). Hard blocks stop the build. Soft warnings proceed with recommended defaults pre-applied.

Before Building — Enrichment Check + Knowledge Cache + Learnings

Enrichment-Aware Build

If the brief was created via the Agent Wizard and background enrichment ran (check brief.json._enrichment):

• Instructions: Enrichment may have generated instructions via Claude Sonnet. Review them during Step 2 — if quality is sufficient, use as-is. If not, spawn PE to revise (not regenerate from scratch).
• Eval sets: Enrichment may have generated eval test sets. Review during Step 4.5 — if coverage is sufficient, use as-is. QA validates and enhances rather than regenerating.
• Architecture scoring: Enrichment ran deterministic scoring (build path, first-party agent matching, channel suggestions). These are pre-applied to the brief.
• Research flags: Check brief.json.recommendations[] where source === "enrichment" — these are integrations the resolver couldn't match. May need live research or manual configuration.

Knowledge Cache + Learnings

1. Read knowledge/cache/api-capabilities.md — check last_verified date
2. If stale (> 7 days), refresh via WebSearch + MS Learn
3. Read knowledge/patterns/dataverse-patterns.md for API call patterns
4. Read knowledge/learnings/build-methods.md — check for creation precedents and known gotchas
5. Update cache files if new findings

Route: Determine Build Mode

Read brief.json -> architecture.type:

On-Demand Teammates During Build

Two teammates are available on-demand when issues arise (not spawned at build start — only when specific conditions trigger them). This keeps simple builds fast while making complex builds resilient.

Research Analyst — spawned when tool configuration fails (connector not found, auth mode mismatch, unexpected parameters). RA searches official docs and community, reports correct name/auth/alternatives. Lead applies the fix, updates brief + cache, dismisses RA.

Prompt Engineer — spawned when instructions need adjustment after tools are configured (tool names differ, planned tool unavailable, action parameters changed, instructions exceed 8000 chars). PE uses GPT co-generation (generate-instructions) to produce and merge revised instructions. QA reviews, lead applies via LSP push, dismisses PE.

Standalone Build (Single Agent)

Dataverse API Shorthand

All Dataverse calls use buildStatus fields from Step 0.9:

TOKEN=$(az account get-access-token --resource <buildStatus.dataverseUrl> --query accessToken -o tsv)
DV="<buildStatus.dataverseUrl>"
BOT="<buildStatus.mcsAgentId>"
GPT="<buildStatus.gptComponentId>"

Publish + verify pattern:

curl -s -X POST "$DV/api/data/v9.2/bots($BOT)/Microsoft.Dynamics.CRM.PvaPublish" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
sleep 5
# Query WITHOUT $select (synchronizationstatus returns null with $select)
curl -s "$DV/api/data/v9.2/bots($BOT)" -H "Authorization: Bearer $TOKEN" | node -e "
let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
  const data=JSON.parse(d);
  const ss=JSON.parse(data.synchronizationstatus||'{}');
  const status=(ss.lastFinishedPublishOperation||{}).status||'pending';
  console.log('Publish status: '+status);
})"

Description PATCH: Now handled automatically by mcs-lsp.js push (patches lines 1-2 of GptComponent data field after LSP sync).

Step 0: Resume Detection & Environment Verification

Read brief.json.buildStatus.completedSteps. If the array has entries, this is a resumed build — log which steps will be skipped. Mapping: "created" -> skip Step 1, "instructions" -> skip Step 2 instructions, "knowledge" -> skip Step 2 knowledge, "tools" -> skip Step 3 tools, "model" -> skip Step 3 model, "topics" -> skip Step 4. Step 5 (publish) re-runs on every build because it's cheap and ensures latest state.

Step 1: Find or Create Agent

Check for existing agent before creating, to prevent duplicates on build resume or session restart.

1a. Check brief.json.buildStatus.mcsAgentId — if set, verify via pac copilot list. If found, skip creation. If not found (deleted), clear ID and proceed.

1b. If no ID, search pac copilot list for matching displayName. If found, store ID and skip creation.

1c. Create new agent via Dataverse POST + PvaProvision:

1. POST bots with:
   • name, schemaname, language: 1033, runtimeprovider: 0
   • authenticationmode: 1 (Integrated — "Authenticate with Microsoft")
   • authenticationtrigger: 1 (AsNeeded)
   • configuration JSON including GenerativeAIRecognizer and contentModeration: "Medium"
   • Example configuration: { settings: { GenerativeActionsEnabled: true }, aISettings: { model: { modelNameHint: "GPT5Auto" }, contentModeration: "Medium" }, recognizer: { kind: "GenerativeAIRecognizer" } }
2. POST PvaProvision bound action
3. Wait for statuscode to transition to Provisioned(1) (~5-15s)
4. PATCH bot name field (LSP push updates GptComponent displayName but not the bot entity name)

Fallback: pac copilot create (requires template extraction first).

1d. Persist mcsAgentId to brief.json.buildStatus immediately. Add "created" to completedSteps.

1e. Clone Agent Workspace (LSP)

node tools/mcs-lsp.js clone \
  --workspace "Build-Guides/{projectId}/agents/{agentId}/workspace" \
  --agent-id "<mcsAgentId>" --agent-name "<displayName>" \
  --env-id "<environmentId>" --dataverse-url "<dataverseUrl>" --gateway-url "<gatewayUrl>"

Store the agent subfolder (the one containing .mcs/conn.json) in buildStatus.workspacePath — not the parent directory. Push/pull commands need the subfolder path.

Skip if buildStatus.workspacePath exists and the directory has .mcs/conn.json.

Pre-push Validation (run before every LSP push)

Before running mcs-lsp.js push:

1. Workspace exists: <workspacePath>/.mcs/conn.json present
2. agent.mcs.yml line 1: starts with # Name: and is not # Name: default
3. agent.mcs.yml line 2: is not # default (has actual description)
4. Conversation starters: every entry has both title and text (missing title causes silent publish failure)
5. Instructions: < 8000 chars
6. Freshness: if last pull was > 30 min ago, pull first to avoid ConcurrencyVersionMismatch

mcs-lsp.js push now automatically patches botcomponent.description, botcomponent.name, and comment headers via Dataverse API after LSP sync.

Step 2: Configure Agent Metadata, Instructions & Knowledge

Skip check: If "instructions" and "knowledge" are both in completedSteps, skip this entire step.

2a. Description & Starters: Edit agent.mcs.yml — set lines 1-2 (name, description metadata) and conversationStarters (each entry needs both title and text). Push via LSP.

2b. Instructions: Edit agent.mcs.yml instructions: field. Run instruction-capability alignment check first (verify MVP capabilities are addressed, future capabilities are not). Push via LSP. Checkpoint: add "instructions" to completedSteps.

Knowledge: Create .mcs.yml files in knowledge/ folder for SharePoint sites and URLs. Use Dataverse API for file uploads (PDF, DOCX). Phase filter: only MVP entries. Checkpoint: add "knowledge" to completedSteps.

Initial Publish: pac copilot publish --bot <bot-id>

On-demand PE trigger: After Step 3 configures tools, if tool names differ from brief, spawn PE to adjust instructions.

Before Step 3: Consult Connector & Integration Learnings

Read knowledge/learnings/connectors.md and integrations.md — look for connector name mismatches, auth gotchas, known workarounds.

Step 3: Configure Tools & Model

Skip check: If "tools" and "model" are both in completedSteps, skip this step.

3a. Model Selection: Default to GPT5Auto (GPT-5 Auto — dynamically routes between general and reasoning). Edit agent.mcs.yml -> aISettings.model.modelNameHint: GPT5Auto. Only change if brief specifies a different model or the environment doesn't support preview models. Check available models via island-client.js get-models. Checkpoint: add "model".

3b. Settings (type: "setting" integrations): Patch bot.configuration via Dataverse. Always set: GenerativeActionsEnabled: true, recognizer: GenerativeAIRecognizer. Per-brief: web browsing, model knowledge, content moderation.

3c. Tool/Connector/MCP Configuration:

Work IQ first: For any M365 data integration (email, calendar, teams, sharepoint, onedrive, user profile, files, search), add Work IQ from the agent overview page. This adds 2 MCP servers that cover everything:

• Work IQ Copilot (mcp_M365Copilot) — cross-M365 search and actions for mail, calendar, teams, sharepoint, onedrive, files, everything
• Work IQ User (mcp_MeServer) — people, org chart, manager, direct reports

No need to add individual Mail, Calendar, Teams, SharePoint servers separately. These 2 replace all individual M365 MCP servers and connectors. Requires M365 Copilot license. Status: Preview (Mar 2026).

1. Auto-discover connection refs: node tools/add-tool.js discover-connections --dataverse-url <url>
2. Check if shared_a365mcpservers connection exists (covers Work IQ)
3. Match discovered connections to brief integrations — prefer Work IQ matches from the resolver's workiqRecommended field
4. For matched: write YAML action files to workspace/actions/, push via LSP
5. For unmatched: guide user to add Work IQ from overview page in MCS UI, re-discover, then write YAML + push

Gaps (use connectors instead): Planner, Excel, Approvals, PowerPoint have no Work IQ equivalent — use Power Platform connectors.

When NOT to use Work IQ: Non-M365 integrations (Dynamics 365, Dataverse, Fabric, third-party) use their own MCP servers or connectors as before.

Checkpoint: add "tools" to completedSteps. Verify via LSP pull that actions/ has all expected tools.

Before Step 4: Consult Topic & Trigger Learnings

Read knowledge/learnings/topics-triggers.md — look for YAML patterns, adaptive card gotchas, node type issues.

Step 4: Author Topics (LSP Push)

Skip check: If "topics" is in completedSteps, skip this step.

Use Topic Engineer for validated YAML (dual model co-generation for 3+ node topics). Phase filter: only MVP topics. Topic type filter: only custom or system (customized) — generative topics are handled by orchestration, no YAML needed.

For each MVP custom/system topic:

1. TE generates topic definition (trigger phrases, actions, description)
2. QA reviews definitions
3. Create via Gateway API (required — LSP push does not produce renderable new topics):

   node tools/island-client.js create-topic --env <envId> --bot <botId> --topic-file <path>
   

4. For adaptive card topics: create with text placeholder via Gateway, pull workspace, edit YAML to add SendMessage + AdaptiveCardTemplate, push via LSP (LSP can update existing topics safely)
5. For system topic customization: edit in workspace, push via LSP
6. Conversation Start welcome card (ALWAYS): Replace the default plain-text ConversationStart with an adaptive card welcome. Use welcome-card.yaml template — fill {{AGENT_NAME}}, {{WELCOME_MESSAGE}}, and capability action buttons from brief.json capabilities. Write to workspace/Agent/topics/ConversationStart.mcs.yml, then push via LSP (system topic update, not new topic creation). This is not optional — every agent gets a welcome card.
7. Available adaptive card styles for topics (see knowledge/patterns/topic-patterns/): welcome-card.yaml (welcome), adaptive-card.yaml (data display + form), table-list-card.yaml (tables/lists), carousel-card.yaml (multi-card), status-card.yaml (progress/status), approval-card.yaml (approve/reject), confirmation-card.yaml (review before submit), feedback-card.yaml (thumbs up/down). Choose the style that best fits each topic's purpose.

Do not use mcs-lsp.js push to create new custom topics because the LSP skips internal MCS registration (NLU trigger indexing, compilation). Gateway API BotComponentInsert handles all registration automatically.

Checkpoint: add "topics" to completedSteps.

Step 4.5: Post-Build Eval

Check: If agent uses MCP servers with user-delegated auth, skip automated eval (Direct Line can't authenticate). Generate test cases for manual testing instead.

Auto mode (Direct Line): Acquire token, run boundaries set (target 100%), run quality set (target 85%), write results to brief.json.evalSets[].tests[].lastResult.

Manual mode (Gateway API): Upload eval sets via island-client.js upload-evals, run via run-eval, present summary. User checks results in MCS or runs /mcs-eval later.

No iterative boundaries/quality/edge-cases loop during build. Build is single-pass. User runs /mcs-fix for post-deployment issues.

Step 5: Publish (Dataverse PvaPublish)

Re-runs on every build (even resume) because publishing is cheap and ensures latest state.

curl -s -X POST "$DV/api/data/v9.2/bots($BOT)/Microsoft.Dynamics.CRM.PvaPublish" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'

Verify via synchronizationstatus (not just HTTP 200): query bot without $select, parse lastFinishedPublishOperation.status. Poll up to 6 attempts at 5s intervals. Also check publishedon is today.

Common failures: MissingRequiredProperty: Title (starter without title), ConcurrencyVersionMismatch (stale workspace), InvalidComponent (malformed YAML).

Checkpoint: add "published" to completedSteps after synchronizationstatus shows "Succeeded".

Step 5.5: QA Build Validation Gate

After publish, spawn QA Challenger for formal validation. The lead collects reconciliation snapshots, runs automated drift detection (drift-detect.py), and QA analyzes everything: brief-vs-actual comparison, cross-reference validation, and deviation impact assessment. QA writes qa-validation.md with a verdict of PASS / PASS WITH CAVEATS / FAIL.

Full QA protocol: see reference/qa-validation-gate.md

Step 5.6: GPT Build Review

After QA validation, fire GPT-5.4 via multi-model-review.js: review-brief, review-instructions, and per-topic review-topics. GPT findings merge with QA verdict (union of findings, stricter wins). If GPT finds a critical issue QA missed, escalate to user before writing buildStatus. If GPT is unavailable, proceed with QA verdict alone.

Step 6: Finalize brief.json buildStatus

Write the complete buildStatus. Most fields were written incrementally during checkpoints — this step ensures the final state is clean:

{
  "buildStatus": {
    "status": "published",
    "lastBuild": "2026-02-18T...",
    "mcsAgentId": "<bot-id>",
    "environment": "<env-name>",
    "account": "<account-label>",
    "accountId": "<session-config-account-id>",
    "publishedAt": "2026-02-18T...",
    "completedSteps": ["created", "instructions", "knowledge", "tools", "model", "topics", "critical-gate", "capability-iteration", "edge-cases", "published"],
    "lastCompletedStep": "published",
    "lastError": null
  }
}

Multi-Agent Build

Build specialists first, then orchestrator. Each specialist follows the standalone build flow with specialist-focused instructions and sharing enabled. The orchestrator connects to all specialists via Island Gateway API.

Full multi-agent protocol: see reference/multi-agent-build.md

End-of-Build Reconciliation

After all changes, walk the brief's MVP-scoped component list and snapshot each item: agent name, model, instructions, knowledge sources, tools, triggers, publish status, (multi-agent) specialist connections and sharing. Collect deferred items list. Then spawn QA Challenger (Step 5.5) with the snapshot data, brief.json, and deferred items list.

Output: Build Summary Report

After reconciliation, generate two outputs:

Terminal Output

## Build Complete: [Agent Name]

**Status:** Published | **Environment:** [env] | **Account:** [account]
**QA Validation:** PASS ({N}/{N} items match, {M} cross-ref issues — see qa-validation.md)
**Eval Sets:** boundaries {X}% | quality {X}% | edge-cases {X}%
**Capabilities:** {N} passing, {M} failing, {K} not tested
**Deferred:** {J} future items (see build report Section 9)

Report saved: Build-Guides/{projectId}/agents/{agentId}/build-report.md

**Next:** Review the build report, share with customer for approval. Run /mcs-eval for standalone re-runs.

Build Report File

Write a customer-shareable build report to build-report.md with 11 sections: overview, architecture, capabilities, tools, knowledge, topics/triggers, key behaviors, open questions, spec-vs-actual changes, eval status, and next steps.

Full template: see reference/build-report-template.md

Post-Build Learnings

Tier 1 (auto): bump confirmed counts for routine builds. Tier 2 (user-confirmed): deviations, workarounds, discoveries. See reference/learnings-capture.md and .claude/rules/learnings-system.md.