threadlight-design

name	threadlight-design
description	Spec out a business process or customer use case for an enterprise pilot, then generate agent architecture (AGENTS.md + Skills) — a durable SpecKit specification first (process flow, business rules, data models, tool contracts, mock data, KPIs, governance), then implementation artifacts derived from the spec. Targets named LOB processes in regulated industries (FSI, Mfg, Retail, Telco, Healthcare, Utilities) where a customer SME will judge the SPEC on industry realism before the demo even runs. USE FOR: design a process, spec out a use case, create agent architecture, automate a regulated workflow, threadlight design, skill factory, business process specification, speckit, define a customer scenario, mock backend systems, seller prep guide, demo script, demo prompts, lock the stack/model/hosting foundation. DO NOT USE FOR: running existing skills, executing code, deploying (use threadlight-deploy), general Q&A, internal Microsoft tooling automation, generic chatbot prototyping.
metadata	{"version":"1.10.0"}

Threadlight Design

Turn a business process or customer use case into a durable specification (SpecKit) and then derive AGENTS.md + Skills from it — ready for a credible enterprise pilot that holds up in front of an industry SME.

When to Use

Invoke this skill when the user wants to:

• Spec out a business process or customer scenario (any regulated LOB domain)
• Design agent architecture for a workflow that will face a CIO / CCO / COO / CDO
• Create a structured skill folder with a formal, audit-ready specification
• Mock backend systems they can't access yet (SAP, CRM, core banking, OSS/BSS)
• Turn vague requirements into a concrete, reviewable spec with cited industry data

From-scratch path vs Kratos-export path. This skill is the "from scratch" entry point — it produces specs/SPEC.md, AGENTS.md, and src/agent/skills/ that the rest of the Threadlight chain consumes. If you are instead starting from a Kratos-exported project (src/hosted-agent/ + use-cases/<x>/, from the Kratos Deploy tab), you bypass threadlight-design entirely: the bundle is already designed, so go straight to threadlight-deploy (Kratos-export mode) and the production-hardening skills. See docs/KRATOS-BRIDGE.md. No change to this skill is needed for that path — the two starting points are intentionally separate.

Using this skill in Microsoft Copilot Cowork

This skill is designed for two personas:

• Sellers (non-technical) — usually in Microsoft Copilot Cowork. Use Cowork to tailor-craft a use-case pitch with the customer's named pain, sourced industry stats, and a customer-facing specs/demo-deck.html you can screen-share on the next call. Fast-PoC mode is the right default in Cowork for basic scenarios — the skill asks 2–3 essential questions, assumes sensible defaults, and produces everything in one pass. You don't need to be a developer to drive this. For anything richer than basic — regulated domains, consequential actions, case lifecycles, multi-phase workflows — the skill runs a complexity triage first (see Mode-selection triage below) and steers you to Full mode so a few extra questions improve the outcome.
• Solution Engineers (technical) — usually in GitHub Copilot CLI / Claude Code. Use Full mode when the design will face a customer SME for industry-realism review, or when the design is a prelude to a workshop deploy. After the spec is committed, hand off to threadlight-local-test for fast inner-loop iteration or directly to threadlight-deploy for the customer sandbox.

[!NOTE] Audience modes (declared in Step 1.5 below, Full mode only): the seller flow above is external-demo, but this skill also serves internal-pilot (an org IT team / centre-of-excellence building for its own users) and third-party-build (an SI / partner building inside a customer tenant). Step 1.5 collects audience_mode first and steers brand, tone, and artifact framing accordingly — neutral defaults for internal / 3P, no "customer logo" prompt, runbook framing instead of demo-deck framing where it fits. unspecified keeps today's behaviour.

[!TIP] Cowork-specific tips: keep the customer's industry vocabulary inline (don't abstract to generic "the customer"); attach the generated specs/demo-deck.html directly to the conversation so the customer can react to the visual; if the customer wants to see the agent run live, ask the SE to invoke threadlight-local-test and screen-share back into Cowork.

Workflow Overview

Clarify → Discover → SpecKit (CHECKPOINT — stop/resume here)
                                    ↓
                        Agents.md + Skills (derived from spec)

Two modes:

Mode	When	Flow
Full	Anything non-basic — production-bound work, stakeholder/SME review, regulated domains, consequential actions, case lifecycles, multi-phase workflows, or a workshop-deploy prelude	Full discovery → triage (Step 1.5) → checkpoint → review → Phase B
Fast-PoC	Basic scenarios only — simple demos / rapid prototypes with no regulatory or PII weight, read-only (or trivially reversible) actions, and a conversational / single-step shape	Essential questions → assume defaults → generate everything in one pass

To activate fast-PoC mode the user says "quick PoC", "fast demo", or similar — but Fast-PoC is only appropriate for basic scenarios. Run the complexity triage below before accepting (or suggesting) Fast-PoC. The skill should suggest Fast-PoC for a short or vague brief only after the triage confirms the scenario is basic — never as a blanket default.

Mode-selection triage (run before locking a mode)

A scenario is basic — Fast-PoC is fine — only when all of these hold:

• Read-only or trivially reversible actions — no payments, approvals, or irreversible external writes
• Stateless or session-based — no long-lived case lifecycle
• Agent-shaped — conversational / Q&A / summarize / single routing step, not a deterministic ≥ 3-phase workflow with persona gates
• No heavy compliance weight — not a regulated domain (FSI / Healthcare / public sector) and no material PII / GDPR / HIPAA handling
• Narrow surface — roughly 1–2 system integrations, no human approval / escalation gates
• No SME / stakeholder industry-realism review, and not a prelude to a workshop deploy

If any non-basic signal is present, do not silently run Fast-PoC. Ask the user one triage question, naming the signal you detected — for example:

This looks like a {regulated / consequential-action / multi-phase / case-based} process. Running Full mode adds a short triage round (Step 1.5: audience, posture, lifecycle) that materially improves the result. Proceed in Full mode, or force Fast-PoC anyway (neutral defaults, recorded in SPEC § 12)?

Default to Full mode for non-basic scenarios; the user can override and force Fast-PoC, in which case the silent-default § 12 callout (see Step 3) still applies. This one triage question is the difference between a credible pilot and a demo that collapses under the first SME question.

Fast-PoC Minimum Baseline

Every PoC, regardless of mode, MUST have:

• ✅ Keyless auth (DefaultAzureCredential) — no API keys
• ✅ At least one MCP server (mock or real) — agent must have callable tools
• ✅ Mock MCP server for inaccessible systems — FastMCP backed by sample data, customer swaps endpoint later
• ✅ SpecKit spec with assumptions documented in § 13
• ✅ specs/foundation.md — the up-front technical decision record (framework, model + region + capacity, hosting, tools, identity, observability) that Step 0 locks and Step 3 pre-populates the SPEC from. From-scratch path; skipped on Kratos-export (already designed), house-defaulted in Fast-PoC.
• ✅ AGENTS.md + skills derived from spec
• ✅ Deployable scaffold (azd up ready)
• ✅ Eval dataset from spec § 9 scenarios — so the demo can be scored
• ✅ specs/demo-deck.html — cinematic talk deck for the live customer moment (always — primary customer-facing artifact; see Step 6 § 7). Skip ONLY when spec § 13 assumptions explicitly flag internal-no-demo: true. Replaces the legacy overview.html — see migration note in references/demo-deck-template.md.
• ✅ specs/experience.html — bespoke cinematic customer journey (optional — on request; see Step 6 § 8). Generate when the user asks for a "cinematic", "experience", or "journey", or when spec § 13 sets experience: true. Skip otherwise.
• ✅ tests/killer-prompts.md — 5–10 ranked wow-prompts wired into STARTER_{1,2,3}_TITLE/PROMPT env vars (see Step 6 § 11). Mandatory under the same condition as the deck.
• ✅ specs/demo-rehearsal.md — beat-by-beat run-of-show (T-24h / T-15min / T-5min / T-0) with backup paths (see Step 6 § 12). Mandatory under the same condition as the deck.

[!IMPORTANT] Fast-PoC skips Step 1.5 (Audience & Presentation Context). Audience mode, customer / org context, brand identity, tone / language, and deployment posture are NOT collected interactively — neutral external-demo defaults apply (no logo prompt, default tone, demo-deck framing). Step 3 (Generate SpecKit) MUST then surface a one-line callout in SPEC § 13 reading roughly: "Fast-PoC mode: audience mode, customer context, brand, and production posture were not collected; using neutral demo defaults. Override later in SPEC § 1 / § 11f / § 13." Downstream skills key off this so silent defaults stay auditable.

---

Runtime capability probe (run before Phase A)

Before starting discovery, probe what the runtime can actually do. Some runtimes (Cowork sandbox, locked-down Cloud Shell images, hardened corporate Codespaces) lack browser automation or media tooling — finding out at T-0 of a live demo is the worst failure mode. Probe once at session start; record the result in specs/SPEC.md § 13 so downstream skills degrade gracefully instead of crashing.

Run these probes from your active shell:

Capability	Probe	Used by	If unavailable
playwright (browser drive)	python -c "from playwright.sync_api import sync_playwright; p=sync_playwright().start(); p.chromium.launch().close(); p.stop()" && echo OK	Step 8 visual validation; @playwright/mcp MCP tools; auto-demo-producer recording phase	Visual validation drops to manual ("open specs/demo-deck.html at 1440×900, advance through every slide"); document the manual checklist in tests/demo-rehearsal.md. Drop @playwright/mcp from mcp-config.json. Disable auto-demo-producer.
ffmpeg (media assembly)	command -v ffmpeg && ffmpeg -version | head -1	auto-demo-producer (mandatory); any skill that stitches narration + screen recording	auto-demo-producer cannot run — note "record manually via OBS / Loom / Teams meeting recording" in specs/demo-rehearsal.md.
node + npx	command -v node && command -v npx && node --version	@playwright/mcp, any Node-based MCP installer, npx -y MCP shorthand	Drop Node-based MCP servers from mcp-config.json; prefer Python-based equivalents (e.g. fastmcp over @playwright/mcp if web scraping is in scope).
uv (Astral)	command -v uv && uv --version	threadlight-local-test Pattern 0 bootstrap; threadlight-deploy container.py prebuilds	Fall back to pip + python -m venv (slower); local-test Quickstart still works, just adds ~30 s to bootstrap.
docker + daemon	docker info > /dev/null 2>&1 && echo OK	threadlight-deploy Phase 6 image build; ACR az acr build is a remote fallback when this fails	If daemon absent (Cowork, some CI runners), threadlight-deploy MUST use az acr build (remote build); skip any local-image smoke step.

Then write the result into specs/SPEC.md § 13 assumptions:

runtime:
  name: cowork                    # cowork | copilot-cli | cursor | codespace | local-mac | local-windows | local-linux
  playwright_available: false     # browser-based visual checks + @playwright/mcp
  ffmpeg_available: false         # auto-demo-producer video assembly
  node_available: true
  uv_available: true
  docker_available: false         # if false, deploy must use az acr build
workflow_model: agent             # agent (default) | workflow
  # agent   — MAF Agent.run() with skills + tools (current threadlight default)
  # workflow — MAF DurableWorkflow with typed executors + HITL pause points
  #            (deterministic multi-phase processes; Zava-style orchestration)
  # The trait matrix (Phase A) auto-suggests based on the process:
  #   - Deterministic multi-phase with persona gates → workflow
  #   - Open-ended chat / Q&A / RAG-heavy → agent
  # The operator confirms or overrides in § 11e.

Known-bad combinations:

Runtime	Typical posture	Implication
Cowork sandbox	python+pip+node+npx ✅; ffmpeg ❌; playwright Chromium launch ❌ (sandbox blocks); docker ❌; uv ⚠️ (only if pre-installed)	Use manual visual validation; skip auto-demo-producer; use az acr build for any container; prefer Python MCP servers
Azure Cloud Shell	az/azd ✅; python ✅; node ✅; docker ❌; playwright ⚠️ (works for HTML inspection, may fail for full-page screenshots)	Use az acr build; visual validation is half-OK (DOM inspection works, screenshots are flaky)
GitHub Codespaces (default image)	Almost everything ✅; playwright install needs playwright install chromium first	Run npx playwright install chromium once at session start; otherwise full capability
Local laptop (Mac/Win/Linux)	Full capability when the contributor has installed the tools	Probe is still mandatory — the contributor may not have ffmpeg/playwright/docker installed

Downstream contract. Every other skill in the chain reads SPEC § 13 → runtime.* and either runs the full path or its documented manual fallback. No skill silently skips a step it can't run — it either degrades to a documented manual flow or errors loudly with a pointer back to this probe.

---

Phase A: Discovery → SpecKit

Step 0: Foundation (from-scratch path only)

Goal: lock the pilot's technical foundations up front — before discovery sharpens the process and before Step 3 writes the spec — so the SPEC is authored on decided ground, not on silent defaults back-filled during generation. This is the left-of-design gate: framework, model + region + capacity, hosting shape, tool binding, identity/RBAC, and the observability baseline are deliberate, recorded choices an operator can sign off on in one review.

When Step 0 runs. From-scratch path only. Kratos-export projects skip it — the exported bundle is already designed (see the path note at the top of this skill). In Fast-PoC mode, do not interview: fill every row with the house default, mark source: defaulted-after-skip, and let Step 3 surface the one-line callout in SPEC § 13. In Full mode, walk the operator through the rows below, defaulting anything they don't have an opinion on.

Consume the runtime capability probe output (above) as the first input — it already fixes the agent-vs-workflow shape and what tooling the shell can run. Step 0 then locks the higher-order house standards the probe does not cover:

1. Framework & runtime shape — microsoft-agent-framework (MAF) is the house default; copilot-agent-sdk (M365/Teams-native surface) or foundry-native (SDK-lite hosted agent) are deliberate deviations. The agent-vs-workflow shape defers to the probe / § 11e; the Step 2 trait matrix may refine it, confirmed at the Step 4 checkpoint.
2. Model & capacity — default gpt-5.4, plus region, fallback_region, capacity_type (GlobalStandard/PTU), and data_boundary (EU) — the region/boundary/fallback triad § 7b does not capture but that decides where capacity is provisioned and whether an EU-resident pilot can run in the primary region. See references/model-selection.md for the tier / capacity / region decision procedure that fills this block.
3. Hosting shape — aca-hosted-agent (default) | azure-functions | aca-job; plus the deployment_target lever (demo-sandbox | customer-pilot | production-bound).
4. Tools & data — tool binding (mcp default), the curated toolbox (versioned alongside skills), mock-first for inaccessible systems.
5. Identity & RBAC — user-assigned managed identity, least-privilege, secretless (DefaultAzureCredential end-to-end) — the house default; any deviation is a flag.
6. Observability baseline — OTel + Application Insights wired from day one, gen_ai.* trace conventions. Observability is a foundation, not an add-on.
7. Data residency & compliance — region pinning, retention, and a deferred_decisions list for rows acknowledged but out of pilot scope (WAF/Front Door, DR runbook).

Emit specs/foundation.md using references/foundation-template.md (YAML decision blocks + a short prose rationale + a decision-summary table).

Downstream contract. Step 3 (Generate SpecKit) reads specs/foundation.md and pre-populates SPEC § 7b (model — extended with region / boundary / fallback), § 11c (tech stack), § 11e (workflow model), § 11f (deployment posture), and § 13 (runtime / observability) from it instead of re-deciding. Absent → today's behavior: Step 3 applies the same documented defaults inline, so older runs and skipped-Step-0 runs are unaffected. Authority order on rerun: specs/foundation.md → the SPEC sections it feeds → azd env; a later SPEC edit that disagrees is surfaced as a conflict, not silently overwritten.

Step 1: Clarify Purpose

Goal: Understand what the user wants to build. Be helpful, not gatekeeping.

Ask the user:

What process or use case would you like to design? Give me a brief description of what it does, who's involved, and what outcome you expect.

Guidance:

• Accept anything — customer service flows, document processing, backend automation, content research, monitoring, reporting, internal ops, or anything else
• Help the user articulate their need if they start vague — ask clarifying follow-ups
• It's fine to be broad at this stage — discovery will sharpen scope

Capture:

• Process name (suggest one if user doesn't provide)
• One-line description
• Domain (financial services, healthcare, retail, operations, HR, marketing, etc.)
• Target persona (optional) — who will see the demo/PoC?
  • CIO/CTO → emphasize architecture, governance, platform fit
  • CFO → emphasize ROI, cost reduction, efficiency gains
  • COO/LOB VP → emphasize the workflow, before/after, process improvement
  • CDO → emphasize data strategy, semantic models, lineage
  • CISO → emphasize security, compliance, audit trail
  • Developer → emphasize technical architecture, APIs, extensibility
  • If unknown, design for a mixed audience (default)

Domain Primer (optional)

A primer is a starting-point cheat sheet, not a blueprint. Check references/domains/ for a matching file — if one exists, use it as loose inspiration during discovery:

• Skim for relevant business rules, data models, regulations, and vocabulary
• Cherry-pick what applies — most use cases only overlap partially with a primer
• The user's actual process always overrides primer suggestions

If no primer exists for the domain, that's completely fine — the trait-based discovery works independently. Primers just save a few questions for well-known scenarios.

Available primers are samples; the team can add more over time. See references/domains/README.md.

Step 1.5: Audience & Presentation Context (Full mode only — ask-once round)

Goal: collect the audience-, brand-, and posture-context that today's flow silently defaults — once, before discovery dives in — so SPEC § 1 / § 11f, the brand cascade in Step 6, and threadlight-deploy Phase 1.5 all inherit explicit choices instead of convention-fallbacks.

Skip in Fast-PoC mode. See the Fast-PoC callout above — Fast-PoC applies neutral defaults silently and records that decision in SPEC § 13.

Pattern: mirror Phase 7 (Citadel handoff) in threadlight-deploy — each question is optional, defaults are explicit, and a skipped answer falls through to today's behaviour and gets a row in the SPEC § 13 assumptions table with source: defaulted-after-skip.

Scope is deliberately narrow: this step does NOT re-ask anything Step 2 already covers (Participants, Data Sourcing, Compliance Screen, temporal patterns). Regulatory / PII / retention / secrets / system access stay in Step 2.

Ask the following six items in one batch (operator can answer inline or skip any line):

1. audience_mode (steers every follow-up — ask this first):
   • external-demo — a Microsoft seller / SE pitching a prospect (today's default for backwards compatibility). Brand prompt fires; demo-deck framing.
   • internal-pilot — an org's own IT team / centre-of-excellence building for the org's own users. Brand defaults to neutral unless opt-in; runbook / handover framing.
   • third-party-build — an SI / partner building inside a customer tenant. Brand defaults to neutral unless opt-in; both your org and the customer tenant are captured below.
   • unspecified — preserve today's behaviour; treat as external-demo for prompting purposes but leave a source: open-question flag in § 13.
2. Customer / org context — Org name, sector specifics, region(s). For external-demo this is the prospect; for internal-pilot it's the user's own org; for third-party-build capture both the partner's org and the customer tenant they build inside.
3. Audience & stakeholders — Who reviews this? Examples: external-demo → industry SME / decision-maker; internal-pilot → internal sponsor / arch board; third-party-build → customer IT lead. Drives whether downstream Step 6 generates a demo deck (external) or a runbook / handover doc (internal / 3P).
4. Brand identity — external-demo flows through the Pattern 1 brand cascade (logo URL / primary hex / "the red telco" hint → convention fallback). internal-pilot and third-party-build default to the neutral Threadlight palette unless the operator explicitly opts in; do NOT prompt for a "customer logo" in those modes.
5. Tone & language — Formal / consumer-friendly; language(s) for the output artefacts (deck for external; runbook / handover doc for internal / 3P).
6. Deployment horizon — one-off demo | PoC sandbox | pilot | production-bound. Pre-populates SPEC § 11f deployment_target so threadlight-deploy Phase 1.5 takes Path 1 (no re-prompt). Audience modes do NOT constrain horizon — an internal-pilot may well be production-bound.

Capture in SPEC § 1 (audience_mode, customer.brand_palette, customer.region) and SPEC § 11f (deployment_target + posture overrides as known). Each item carries a source field with one of: provided | inferred | defaulted-after-skip | open-question. Skipped items default to today's behaviour and get a row in the § 13 assumptions table (see Step 3 for the table shape).

Soft-confirmation hook: after Step 2 completes, Step 3 (Generate SpecKit) shows the merged context (Step 1 + Step 1.5 + Step 2) and the defaulted items as one compact table before writing artefacts — see the "Pre-generation confirmation" callout in Step 3.

Step 2: Discover via Trait Detection

Goal: Progressive interview driven by detected traits. Start simple, branch as needed.

Reference: references/process-traits.md

Core Questions (always ask):

1. Who's involved? (Participants)

   • End users / customers
   • Internal staff / operators
   • External systems (APIs, databases, SaaS)
   • Other agents

2. Where does data come from? (Data Sourcing traits)

   • Websites → Web scraping trait
   • APIs / external systems → API integration trait
   • Documents / files → Document intake trait
   • Databases / corporate systems → Database query trait
   • Web search / research → Search/research trait
   • User provides it conversationally → User input trait
   • Events / webhooks / messages → Event-driven trait

3. What happens to the data? (Processing Style traits)

   • Extract → Extraction trait
   • Transform / normalize → Transformation trait
   • Compare / rank → Comparison trait
   • Analyze / score / assess → Analysis trait
   • Summarize / synthesize → Synthesis trait
   • Validate / check → Validation trait
   • Route / triage → Routing trait

4. What gets produced? (Output Mode traits)

   • Reports / documents
   • Structured data / records
   • Notifications / alerts
   • Decisions / recommendations
   • Conversations / responses
   • Actions in external systems

5. How are humans involved? (Interaction Model traits)

   • Fully automated (no human)
   • Human approves at key points
   • Real-time conversation
   • Human reviews output periodically

6. When does it run? (Temporal Pattern traits)

   • On-demand / user-triggered
   • Scheduled (daily, weekly)
   • Event-driven
   • Continuous / streaming

7. Does this process track cases with a lifecycle? (State Model trait)

   • Stateless — each request is independent
   • Session-based — state within a conversation, discarded after
   • Case-based — long-lived cases (open → in-progress → resolved)
   • Pipeline — items flow through ordered stages

   Default: If the user doesn't know yet, ask rather than assume. Stateless is the wrong default for any regulated process — assume case-based for FSI / Healthcare / regulated supplier risk and flag in spec § 13: "Defaulted to case-based; confirm lifecycle with stakeholder."

8. Does the agent take consequential actions? (Action Criticality trait)

   • Read-only — only reads/analyzes data
   • Reversible writes — creates/updates data that can be undone
   • Irreversible actions — payments, approvals, notifications, external writes

   Default: Read-only is the right default only for the first pilot iteration. For any second-iteration spec, ask the user which writes are in scope and document them in § 8 (Human Interaction Points) with their action gates. A regulated process whose write surface stays at "read-only" forever is a tutorial, not a pilot.

9. Is this process better modeled as an agent conversation or a deterministic workflow? (Workflow Model trait)

   • Agent (default) — open-ended chat, RAG-heavy, user-driven exploration, Q&A
   • Workflow — deterministic multi-phase pipeline, ordered stages with persona gates, orchestrated execution, minimal free-form interaction

   Classification heuristic: If the process has ≥ 3 ordered phases AND ≥ 2 persona/approval gates AND the outputs are deterministic (same input → same phases → same outcome), suggest workflow. If the process is primarily conversational, knowledge-grounded, or exploratory, suggest agent. Record the choice in spec § 11e: workflow_model: agent | workflow.

   Both are valid. Agent mode runs as a MAF Agent with skills + tools. Workflow mode runs as a MAF DurableWorkflow with typed executors and HITL pause points. Both deploy to Foundry via threadlight-deploy and get the same governance (Citadel + AGT), telemetry, and eval chain. The choice affects only the runtime container shape.

Trait-Driven Branching

Based on detected traits, ask the relevant follow-up questions from references/process-traits.md. Don't ask all questions — only those relevant to the detected traits.

Data Availability Check

For each system integration identified:

• Available — you have access, credentials, API docs
• Auth required — exists but you need credentials/tokens
• Internal only — corporate system, need VPN/network access
• Mock — system exists but you can't access it for development

For systems marked "mock": The spec will define data models and sample data so the agent can be developed and tested without the real system. When the real system becomes available, replace mock data with an MCP server or API connection.

Compliance Screen

At minimum, confirm:

1. Data sources: All public, or some require auth?
2. PII: Any personal data involved?
3. Secrets: Any API keys or credentials needed?
4. Regulatory: Any legal/regulatory constraints? (GDPR, HIPAA, industry-specific)
5. Retention: How long to keep data?
6. Access: Who can run this and see results?

Step 3: Generate SpecKit

Goal: Produce the specification documents from discovery findings.

Use the template from references/speckit-template.md.

Pre-generation confirmation (Full mode only)

Before writing specs/SPEC.md, read specs/foundation.md if it exists (from-scratch path) and pre-populate SPEC § 7b / § 11c / § 11e / § 11f / § 13 from it — Step 0 locked those foundations, so carry the values and their source forward rather than re-deciding. Then show the user a single compact table merging Step 0 (foundation), Step 1 (clarify), Step 1.5 (audience & presentation context), and Step 2 (trait discovery) — with the source of each field visible — and ask one open question: "Anything to tweak before I generate the spec?"

Table shape (mirrors the SPEC § 13 source-taxonomy table):

| Section / Field          | Effective value                  | Source                |
|--------------------------|----------------------------------|-----------------------|
| § 1.audience_mode        | external-demo                    | provided              |
| § 1.customer.name        | Contoso Retail                   | provided              |
| § 1.customer.region      | EU                               | provided              |
| § 1.customer.brand_palette | Threadlight neutral            | defaulted-after-skip  |
| § 1.tone                 | consumer-friendly                | provided              |
| § 11f.deployment_target  | customer-pilot                   | provided              |
| § 11f.networking         | public                           | defaulted-after-skip  |

Tweaks are applied inline (rewrite the corresponding § 1 / § 11f field + flip source to provided) and the table is re-shown until the user accepts. Skip this step in Fast-PoC mode.

Fast-PoC § 13 callout (mandatory when mode == Fast-PoC)

When Step 1.5 was skipped because the user is in Fast-PoC, SPEC § 13 MUST open with a one-line callout — verbatim shape:

Fast-PoC mode: audience mode, customer context, brand, and production posture were not collected; using neutral demo defaults. Override later in SPEC § 1 / § 11f / § 13.

This is the auditable trail that silently-defaulted decisions left for downstream skills (and for a later reviewer).

Create in the project directory:

specs/SPEC.md — The full SpecKit document

Must include all sections from the template:

1. Process Overview — name, domain, goals, scope, participants
2. Process Flow — step-by-step with actors, inputs, outputs, decision branches
3. Business Rules — numbered BR-XXX, each with condition/action/exception + KPI mapping (drives § 9 continuous-eval contract)
4. Data Models — all entities with field-level schemas and system of record
5. System Integrations — each external system, direction, auth, availability (including mock flag) 5b. External Systems & Mocks (MCP contract) — endpoint shape, tools exposed, mock data scale, reset semantics. INPUT CONTRACT for foundry-mcp-aca. Required for any process that talks to external systems.
6. Tool Contracts — abstract tool definitions (not bound to any runtime)
7. Knowledge Sources — reference documents, policies, search indexes — with explicit foundry-iq / mcp-search / inline-context backing decision 7b. AI Services & Model Selection — chat / vision / DocIntel / Speech models with versions. INPUT CONTRACT for foundry-doc-vision-speech and azure.yaml config.deployments. Use gpt-5.4 family as of May 2026 — gpt-4o is legacy. See references/model-selection.md for the model / capacity / region decision procedure. Required for every process.
8. Human Interaction Points — approvals, escalations, conversational flows — with action-gate taxonomy (approve / edit-and-approve / reject / escalate / signoff / audit-view / request-info). INPUT CONTRACT for threadlight-hitl-patterns. 8b. Human Interaction (Workspace UX) — case-list / inbox / dashboard / console / kanban / map shape with primary filters, detail sections, action toolbar, audit viewer. INPUT CONTRACT for threadlight-workspace-ui. Optional — skip if humans only interact via approval cards.
9. Success Criteria — functional, performance, quality targets + evaluation scenarios (S-XXX linked to BR-XXX) + Business KPIs table (BR → KPI mapping) for continuous evaluation
10. Trigger & Run Model — how/when the process executes, volume, SLA 10b. Triggers (Receiver contract) — receiver type, idempotency key, dedup window, dead-letter rule. INPUT CONTRACT for threadlight-event-triggers. Required for event-driven and scheduled processes.
11. Security, Compliance & Governance — PII, auth, retention, regulatory, audit 11b. Governance Posture (AI Governance Hub spoke — opt-in) — governance_hub.required flag + spoke artifacts needed. INPUT CONTRACT for the optional governance-hub spoke handoff in threadlight-deploy. Required for every regulated process. 11c. Tech Stack (Module selectors) — Bicep module on/off list (cosmos, search, doc-intel, speech, event-grid, service-bus, foundry-iq-index, etc.). INPUT CONTRACT for the azd-patterns Bicep module library and the composer in threadlight-deploy. Required for every process.

Legacy-SPEC backfill — mandatory check before handing off to threadlight-deploy. SPECs generated before § 11c was added to this skill (any SPEC where the section list jumps from § 11 to § 12, or has no kebab-case selector table) must be backfilled before Phase 6 of threadlight-deploy runs. The composer reads § 11c verbatim — without it, it can't tell "no aca-bot deployed" from "aca-bot intentionally not selected", and the post-deploy gate ships partial PoCs as if they were complete (for example, aca-bot and aca-job declared yes but zero deployed). Run a one-shot grep before generating Phase 6 modules:

grep -E '^(##|###) 11c' specs/SPEC.md || echo "MISSING - reverse-engineer from azure.yaml services + infra/main.bicep modules and prepend § 11c table"

If missing: read the existing azure.yaml services + infra/main.bicep modules, write the corresponding kebab-case selector table, prepend it to the SPEC at the right anchor, and re-validate. 11d. Demo Data (Realism rules) — per-entity volumes, distribution, golden cases, reset semantics, industry realism rules. INPUT CONTRACT for threadlight-demo-data-factory. Required for every process with mocked systems. 11e. Workflow Model — workflow_model: agent | workflow. INPUT CONTRACT for threadlight-deploy Phase 2 (determines whether to generate an Agent container or a DurableWorkflow container). Defaults to agent if absent. When workflow, the SPEC additionally emits a WORKFLOW.md alongside AGENTS.md with executor/phase definitions instead of agent/tool definitions. 11f. Deployment Posture — deployment_target: demo-sandbox | customer-pilot | production-bound plus posture overrides (networking, replicas, retention, model_pinning) and a deferred_decisions: list. INPUT CONTRACT for threadlight-deploy Phase 1.5: when populated, Phase 1.5 takes Path 1 (proceed with matching posture defaults, no operator prompt); when absent, Phase 1.5 asks the operator once. Pre-populated by Step 1.5 of this skill (Full mode); left empty by Fast-PoC.

12. Production Readiness — target posture, must-have pillars, residency, RTO/RPO, SLA, incident owner, pricing plan, model list, waivers, Defender/Policy floor. Includes a load_profile{} sub-block (consumed by threadlight-consumption-iq wizard to produce cost projections and SKU recommendations — see references/speckit-template.md § 12).
13. Assumptions & Open Questions — what's given, what needs stakeholder input

The abstract / pure-coding split. Sections 5b, 7b, 8 (action gate), 8b, 9 (KPI table), 10b, 11b, 11c, 11d are input contracts — each one is consumed mechanically by a downstream pure-coding skill. If a section is empty/missing, the corresponding downstream skill cannot generate working code. Always populate them at least minimally; use defaults from this skill's references when the user can't articulate them yet.

Generating Evaluation Scenarios (§ 9)

Every business rule (BR-XXX) must have at least one eval scenario. Derive them systematically:

For each BR-XXX	Generate these scenarios
Happy path	Input that satisfies the condition → verify the action fires correctly
Boundary	Input at the exact threshold → verify correct branch
Negative	Input that violates the condition → verify the exception/rejection
Missing data	Input with required fields missing → verify graceful handling

Naming: S-{NNN} linked to BR-{NNN}. Example:

• BR-001: "Credit score < 580 → auto-decline"
• S-001: Happy path — score 780 → approved
• S-002: Boundary — score 580 → edge of auto-decline
• S-003: Negative — score 520 → auto-declined
• S-004: Missing — no credit score available → error handling

Minimum coverage: At least 3 scenarios per business rule (happy + boundary/negative + error). For a spec with 10 rules, expect 30-50 eval scenarios.

These scenarios feed directly into foundry-evals for post-deployment scoring.

specs/sample-data/{entity}.json — Mock data (for systems marked "mock")

For each entity in § 4 Data Models where the backing system is marked "mock" in § 5:

• Generate enough records to be credible at the scale named in § 11d: the quick-rough default is ≥ 50 records per entity for narrative walkthrough and ≥ 10K records for executive scale-conversation. See references/data-realism/{industry}.md § "Production-realism volume + SLA defaults" for industry-specific volumes — those values win when they conflict with this default.
• Include varied data, hand-curated golden cases (named, story-bearing), some optional fields missing, and skewed distributions matching reality (no random uniform).
• Wrap each file as {"_meta": {...}, "records": [...]}. Do not put _meta as a sibling key to records — threadlight-demo-data-factory and threadlight-workspace-ui both depend on the wrapper shape.

Heavy lift goes to threadlight-demo-data-factory. This skill writes the seed JSONs at narrative scale; the factory skill generates additional records to scale-conversation volume on demand using deterministic seeds, capped concurrency, and the per-industry distributions documented in references/data-realism/{industry}.md.

specs/sample-data/README.md — Migration guide

Explains:

• What each sample file represents and which system it mocks
• The expected schema (references SPEC.md § 4)
• How to replace mock data with a real MCP server or API connection
• Example: "When SAP becomes accessible, replace specs/sample-data/orders.json with an MCP tool call to sap_get_orders — the schema stays the same"

Step 4: Checkpoint

After generating specs/, present the spec summary to the user:

📋 SpecKit: {name}
📌 Traits: {detected traits}

📊 Business Rules: {count} (BR-001 through BR-{N})
📦 Data Models: {list of entities}
🔌 Integrations: {list — marking which are mocked}
🧪 Eval Scenarios: {count}

📁 Generated:
  specs/SPEC.md
  specs/sample-data/{entity}.json (× {count})
  specs/sample-data/README.md

Then also generate specs/manifest.json for resume durability:

{
  "process_name": "{name}",
  "spec_version": "1.0",
  "status": "checkpoint",
  "phase_reached": "A",
  "generated_files": ["specs/foundation.md", "specs/SPEC.md", "specs/sample-data/..."],
  "traits": ["{trait-1}", "{trait-2}"],
  "created_at": "{ISO date}"
}

Then tell the user:

Checkpoint reached. You can:

• Review and edit the specs before continuing
• Share the specs with stakeholders for feedback
• Continue to Phase B to generate AGENTS.md + Skills from these specs
• Stop here and resume later — just say "generate agents from specs" in a future session

In fast-PoC mode: Skip the checkpoint — proceed directly to Phase B.

---

Phase B: SpecKit → Agents.md + Skills

Goal: Read the specs and derive implementation artifacts.

If specs/SPEC.md exists, read it. If not, run Phase A first.

Step 5: Design Architecture from Spec

Read the spec and derive the architecture using these deterministic rules:

Skill Derivation Recipe

1. Map process steps to candidate skills:

   • Group consecutive steps that share the same actor type into a skill
   • Steps with different actor types (agent vs system vs human) usually split into separate skills
   • A single step that is complex enough (multiple sub-actions, branching) can be its own skill

2. Do NOT create "orchestrator" skills. Orchestration is the agent's job (via AGENTS.md instructions), not a skill's job. Skills are domain-specific knowledge and procedures — they don't coordinate other skills. If you need orchestration logic, put it in copilot-instructions.md as behavioral guidelines, e.g.:

   • "When the user asks for X, first use skill A to gather data, then skill B to analyze"
   • "If risk score > threshold, escalate to human review"

3. Human interaction points → dedicated handling:

   • Each approval/escalation flow from spec § 8 maps to approval logic in the relevant skill
   • Conversational interaction points may warrant a dedicated skill

4. Knowledge sources → Foundry IQ or MCP:

   • Documents, policies, regulations, product docs, brand guidelines, runbooks (spec § 7) → Foundry IQ (Azure AI Search with agentic retrieval — query planning, multi-hop, citations). See foundry-iq skill. Foundry IQ is the default knowledge retrieval pattern for every threadlight process — even processes that primarily query transactional data should ship with a Foundry IQ index for their domain policies. Set Backing service: foundry-iq in spec § 7 unless the corpus is genuinely tiny (then inline-context) or genuinely live (then mcp-search).
   • Dynamic/transactional data (spec § 5 integrations) → MCP server (mock for PoC, real for production). See foundry-mcp-aca skill.
   • Cosmos DB → MCPToolKit (10 tools out of the box) as src/mcp/

5. Temporal pattern → trigger design:

   • On-demand → user invocation
   • Scheduled → Azure Functions or cron
   • Event-driven → webhook or message queue trigger

6. Validation checklist (every item must pass):

   • Every BR-XXX rule is covered by at least one skill's procedure
   • Every tool contract from spec § 6 has a concrete implementation (Foundry tool, MCP, or mock)
   • Every mocked system has sample data in specs/sample-data/
   • Every eval scenario (S-XXX) can be tested with the generated skills + mock data
   • No orphan skills — every skill is reachable from the agent's instructions

Feasibility Preflight

Before generating files, verify:

• Required tools are available (Foundry tools, MCP servers, or viable mock alternatives)
• Auth patterns identified for all non-mock system integrations
• Storage strategy defined for any persistent state (no local filesystem in production)
• Model capability matches needs (tool count, context window, reasoning depth)

Architecture Summary

Present to user before generating:

📋 Process: {name} (from specs/SPEC.md)

📁 Skill Structure:
  - {skill-1}: {purpose} (implements BR-001, BR-003)
  - {skill-2}: {purpose} (implements BR-002, BR-004, BR-005)

🔧 Tools:
  - {tool-1} → {Foundry tool or MCP server}
  - {tool-2} → {Foundry tool or MCP server}
  - {tool-3} → mock data (specs/sample-data/{entity}.json)

⚠️ Mock systems: {list — will need real integration later}

Wait for user approval before generating files.

Step 6: Generate Implementation Artifacts

1. src/agent/skills/{skill-name}/SKILL.md (for each skill)

Use the template from references/skill-template.md. Each skill MUST have:

• YAML frontmatter with name and description (include USE FOR / DO NOT USE FOR)
• Spec traceability: "Implements BR-001, BR-003" in the header
• Operational contract (inputs, outputs, deps, idempotency, failure behavior)
• Step-by-step procedure (derived from spec process flow)
• Output schema (derived from spec data models)
• Grounding & honesty contract (knowledge-backed skills only): name the grounding source and a labeled-degradation fallback — if the source lacks the answer, say so explicitly, and label any general-knowledge answer as such. (Citation is already covered by the spec's § 7 Citation requirement.)

Convention: Process skills go directly into src/agent/skills/. Do NOT put them in .github/skills/ — that location is reserved for coding/development skills (skills that help develop the repo itself, not the agent's runtime skills).

2. AGENTS.md

Use the template from references/agents-template.md. Must include:

• Agent identity and purpose (derived from spec § 1)
• Available skills table (derived from step 5 decomposition)
• Foundry tools required (derived from spec § 6 tool contracts)
• Data & storage strategy
• Behavioral guidelines. This section MUST include:
  • Grounding & honesty (always): "Ground substantive answers in the agent's knowledge source (spec § 7). If the knowledge source does not contain the answer, say so explicitly; answer from general knowledge only when clearly labeled as such. Cite sources per spec § 7 Citation requirement."
  • Cross-skill synthesis (only when the agent composes answers from more than one skill — i.e. ≥ 2 knowledge/analysis/synthesis skills, or the Synthesis trait was detected): "When more than one skill contributes to a single answer, reconcile rather than concatenate — preserve technical detail, resolve disagreements explicitly, and surface cross-domain trade-offs."
• Spec reference: "This agent implements specs/SPEC.md"

3. src/agent/config/{name}.json

Configuration file with parameters and thresholds from the spec.

4. mcp-config.json

MCP server configuration for development. Generate:

• .vscode/mcp.json — for VS Code Agent Mode (dev-time, local MCP servers)

Note: Do NOT generate .copilot/mcp-config.json in the project — that's a user-level config. The runtime MCP config lives at src/agent/mcp-config.json and is generated by threadlight-deploy.

Map spec tool contracts to local MCP servers where possible:

Spec Tool Type	Local MCP Server
Web scraping	@playwright/mcp
Knowledge retrieval	Azure AI Search SDK (local) → Foundry IQ (deployed)
Cosmos DB	@azure/mcp with cosmos namespace → MCPToolKit ACA (deployed)
Azure AI Search	@azure/mcp with search namespace
Fabric data	@microsoft/fabric-mcp
Web search	Tavily MCP (remote HTTP)

For tools backed by mock data: document in the project README which tools use sample data files and will need real MCP/API connections later. Do NOT put comments in JSON config files.

5. specs/manifest.json

Machine-readable deployment contract (lives with the spec):

{
  "name": "{process-name}",
  "version": "1.0.0",
  "speckit": "specs/SPEC.md",
  "description": "{one-line description}",
  "traits": ["{trait-1}", "{trait-2}", "{trait-3}"],
  "business_rules_count": 0,
  "skills": [
    {"name": "{skill-1}", "implements": ["BR-001", "BR-003"]},
    {"name": "{skill-2}", "implements": ["BR-002"]}
  ],
  "mock_systems": ["{system-1}"],
  "compliance": {
    "pii": false,
    "auth_required_sources": [],
    "regulatory": []
  },
  "deployment_manifest": {
    "module_selectors": {
      "foundry-account":  "yes",
      "cosmos-db":        "yes",
      "ai-search":        "yes",
      "foundry-iq-index": "yes",
      "aca-mcp":          "yes",
      "aca-bot":          "yes",
      "aca-job":          "yes",
      "workspace-ui":     "yes",
      "key-vault":        "no",
      "event-grid":       "no"
    },
    "services": [
      {"name": "agent",     "host": "azure.ai.agent",   "src": "src/agent"},
      {"name": "mcp",       "host": "containerapp",     "src": "src/mcp"},
      {"name": "bot",       "host": "containerapp",     "src": "src/bot"},
      {"name": "workspace", "host": "containerapp",     "src": "src/workspace"}
    ],
    "scheduled_jobs": [
      {"name": "{job-name}", "schedule": "*/15 * * * *", "tool": "{tool-name}", "src": "src/jobs/{job-name}"}
    ],
    "channels": [
      {"name": "Analyst Workspace",      "type": "web",            "service": "workspace"},
      {"name": "Teams adaptive card",    "type": "teams",          "service": "bot"},
      {"name": "Email deadline alerts",  "type": "email",          "service": "{service or external}"}
    ],
    "expected_resource_types": [
      "Microsoft.CognitiveServices/accounts",
      "Microsoft.DocumentDB/databaseAccounts",
      "Microsoft.Search/searchServices",
      "Microsoft.App/managedEnvironments",
      "Microsoft.App/containerApps",
      "Microsoft.App/jobs",
      "Microsoft.BotService/botServices",
      "Microsoft.ManagedIdentity/userAssignedIdentities",
      "Microsoft.ContainerRegistry/registries",
      "Microsoft.Insights/components"
    ]
  }
}

deployment_manifest is a contract threadlight-deploy reads mechanically. The deploy skill's Phase 3 module-selector check walks module_selectors, confirms each service maps to a folder under src/ with a Dockerfile, and confirms every infra/*.bicep module is wired in main.bicep. Phase 3.5 then takes expected_resource_types and asserts every entry is in az resource list -g <RG> after azd up. The mechanical implementation is the threadlight-safe-check skill — invoke python3 tests/safe_check.py --phase {design|pre-deploy|post-deploy} at the corresponding lifecycle points. If you flip a selector from yes to no mid-pilot, delete the corresponding source folder and Bicep module too ` orphans break the orphan check.

Required for every process where aca-bot, aca-job, workspace-ui, or any other selector that produces a deployable service is yes. Without deployment_manifest, the deploy gate can't tell missing services from intentionally-skipped ones, and ships partial PoCs as if they were complete (aca-bot and aca-job declared yes in SPEC § 11c, deployed as zero resources, and not noticed until someone opens the resource group).

6. README.md

Project documentation covering:

• What this agent does (from spec § 1)
• Architecture overview (text-based diagram)
• Skill catalog with purposes and spec traceability
• Configuration guide
• Mock data status (which systems are mocked, how to replace)
• Deployment path (reference threadlight-deploy)

Cross-cutting HTML artefact patterns (deck / experience / prep-guide)

Seven patterns apply uniformly to the HTML artefacts this skill emits. Patterns 1–3 have surfaced as user gripes during PoC walkthroughs ("nothing matches our brand", "this .md link is dead", "the seller doesn't want to read azd commands"); Patterns 4–7 are battle-scars from the demo-polish phase (persona leaks into the talk deck, internal jargon like "OneAsk" or "Sweden Central" leaking onto customer-facing slides, fabricated tool names contradicting AGENTS.md, and commit-language closings the seller can't defend). Implement them all once at generation time; never reach for them post-hoc.

Pattern 1 — Brand cascade rule (mandatory when brand palette declared)

When SPEC § 1 (Customer / domain) declares a customer brand palette OR the discovery transcript captured brand colours implicitly (logo url, "they're red like that well-known UK telco", "their site is the orange one"), every generated HTML artefact MUST cascade the brand accent + key shadow tokens while preserving the structural neutrals that give each visual paradigm its identity (parchment, charcoal, navy, brass wax-seal accents on the dossier paradigm; ink-blue + slate on the editorial paradigm; etc.).

Detection rule. During Step 6 generation, scan SPEC § 1 + the discovery transcript for any of:

• Explicit customer.brand_palette: { primary: "#XXXXXX", secondary: "#YYYYYY" }
• Brand-colour mention captured in transcript ("they're red like the well-known UK telco", "their site is the orange one")
• Logo URL → fetch + sample dominant non-neutral hex (offline if possible)
• Sector convention ("any NHS trust uses #005EB8")

When a brand palette is detected, inject ONE override block at the top of the artefact's CSS that swaps --accent / --accent-strong / --shadow-key while leaving paradigm tokens (--parchment, --charcoal, --ink, --brass, --linen) untouched.

Cascade table (paradigm tokens that swap vs preserve):

Token category	Swap to brand?	Why
--accent, --accent-strong, --cta	YES	Carries the brand instantly recognisable on hero / CTAs
--shadow-key, --ring-focus	YES (de-saturated brand)	Keeps shadows brand-coherent without screaming
--parchment, --charcoal, --ink, --brass, --linen	NO	Structural neutrals define the paradigm, not the brand. Swapping them collapses the dossier / editorial / blueprint look into a generic web page.
--success, --warn, --danger	NO	Universally legible; do not negotiate

Validation. Before declaring done, grep that the brand accent hex (or its rgb()/rgba() equivalent) IS present in the generated CSS for each of demo-deck.html / experience.html / prep-guide.html. If absent → cascade rule wasn't applied → fix before presenting to user.

Deeper rules for demo-deck.html (the talk deck). A talk deck takes the cascade further than the brief/dossier/crib-sheet artifacts because the brand has to read at projector distance:

• Brand FLOODS — full-bleed bg-{brand}-flood panels: mandatory on friction + follow-up + close (the 3 emotional anchors) + ≥ 1 more chosen from {hero, the-shift, scale, posture} → ≥ 4 flood panels per deck. A dark hero with brand-accent gradient is a valid cinematic opening (the reference deck uses this); it does NOT have to be one of the brand-flood panels.
• Brandmark substitute (when no logo licensed) — a 2-letter monogram rendered on a white circle on the brand-flood panel. Echoed on slide 1 (cold-open) and slide N (close) as bookend. See references/demo-deck-template.md § "Brandmark substitute recipe".
• Microsoft 4-color SVG co-brand bar — canonical hex #F25022 #7FBA00 #00A4EF #FFB900 (verbatim, do not approximate) + "Microsoft × {Customer}" wordmark. Present on hero AND close.
• No third-color accents — if the brand primary is #E60000 red, the deck CANNOT introduce cobalt / amber / purple as section accents. Use brand-darker (--brand-dark) and brand-brighter (--brand-bright) shades only.
• Reveal pacing tuned to brand identity — telco / retail / consumer = bold/fast (200ms stagger); FSI / healthcare / public-sector = serif/measured (400ms stagger). Read the cue from SPEC § 1 domain.
• Convention fallback — when customer.brand_palette.primary is NOT captured and there's no logo URL, consult references/brand-palettes.md for the sector convention (UK telco red #E60000, NHS blue #005EB8, etc.). Annotate SPEC § 13 assumptions with brand_palette_source: convention-fallback so the next iteration confirms with the customer.

Auto-review for deck (in addition to the base validation above): grep for ALL of (a) the brand hex, (b) bg-{brand}-flood class present, (c) brandmark substitute markup present on slide 1 + final slide, (d) MS co-brand block on hero + close.

Pattern 2 — Markdown modal pattern (mandatory in HTML artefacts that link to .md)

Sellers cannot meaningfully open .md files. A <a href="../specs/SPEC.md"> link either 404s on file:// (the most common way sellers open the artefact during a Cowork pitch), or — if hosted — opens raw markdown as a plaintext blob with no formatting. Both outcomes degrade credibility.

Required behaviour. Every .md link in any generated HTML artefact MUST open as a click-to-render dialog with:

1. The markdown rendered in-browser
2. A short explanatory blurb above ("This is the SpecKit specification — the canonical source of truth the agent implements.") so the seller knows what they're looking at before they read it
3. Esc key + overlay click both close the modal
4. Brand-styled dark substrate that looks consistent regardless of the host artefact's theme (parchment / dark / dossier all coexist)

Self-contained anatomy. No fetch() — works on file://. Pattern:

1. Embed the markdown as opaque blobs at the bottom of the host HTML:

   <script type="text/markdown" id="md-spec" data-source="../specs/SPEC.md">
   # SpecKit Specification
   ...full markdown here, no escaping needed because it lives in a script tag...
   </script>
   

   Browsers do not parse the contents of <script type="text/markdown"> — they're inert blobs you read via document.getElementById(...).textContent.

2. Register the link → blob mapping in a small JS object at the top of the artefact:

   const MD_REGISTRY = {
     "../specs/SPEC.md":      { id: "md-spec",     title: "SpecKit Specification",
                                intro: "The canonical source of truth..." },
     "../README.md":          { id: "md-readme",   title: "README",
                                intro: "Quick-start guide..." },
     "../tests/eval-summary.md": { id: "md-eval",  title: "Evaluation Summary",
                                   intro: "Latest quality bar..." }
   };
   

3. Rewrite <a href="*.md"> to <a data-md="*.md"> at generation time. Add a CSS affordance hint:

   a[data-md]::after { content: " ◇"; opacity: .6; font-size: .85em; }
   

4. Single document-level click delegate intercepts:

   document.addEventListener("click", (e) => {
     const a = e.target.closest("a[data-md]");
     if (!a) return;
     e.preventDefault();
     openMdModal(a.dataset.md);
   });
   

5. Renderer with fallback. Try marked.js from CDN (cdn.jsdelivr.net/npm/marked@12) loaded async at modal open; fall back to a ~50-line hand-rolled subset that handles h1-h3, fenced code, blockquotes, lists, tables, links, bold/italic. Do not ship without the fallback — sellers in Cowork frequently have CDN blocked.

6. Modal substrate uses FIXED dark tokens independent of host page tokens (so it looks consistent on parchment + dark hosts):

   .md-modal { background: rgba(10,12,18,.92); }
   .md-modal-card { background: #f6f3ec; color: #1a1c22; /* parchment-on-dark */ }
   

Reusable pattern, NOT shipped reference script. Each pilot writes its own ~120-line generator (gen_md_modal.py or inline Python in the artefact-generation script). The pattern above is more durable than any specific implementation; resist the urge to ship a reference script that turns into the next stale dependency.

Pattern 3 — <details class="se-only"> audience-collapsible

Sellers reading a prep-guide do NOT want to scan past azd up blocks, Bicep walkthroughs, raw GUIDs, or re-deploy procedures to reach the demo script. SA / SE engineering content MUST be wrapped in <details class="se-only"> so seller-mode readers see only seller-relevant content by default.

Anatomy:

<details class="se-only">
  <summary>
    <span class="audience-pill">SA only</span>
    <strong>Re-deploy after corpus refresh</strong>
    <span class="hint">azd deploy agent · ~3 min</span>
    <span class="chev">▸</span>
  </summary>
  <div class="se-body">
    <pre><code>azd deploy agent
azd ai agent invoke "test prompt"</code></pre>
  </div>
</details>

CSS rules:

• .audience-pill — orange-bordered amber pill (use --confidential token, default #eb9700); short label like "SA only" or "Engineer"
• Bold dark <strong> summary text + right-aligned dim hint (margin-left: auto, mono small) describing what's inside without opening
• <span class="chev">▸</span> rotates 90° via details[open] .chev { transform: rotate(90deg) }
• Native summary::-webkit-details-marker { display: none } suppressed
• Mobile-responsive: hint wraps to its own line on narrow viewports
• Default closed — sellers see the affordance (the orange pill is obvious) but are not visually nagged by content they don't need

When to wrap. Any block that contains:

• azd / az / python / pwsh / kubectl commands
• Raw GUIDs (subscription IDs, tenant IDs, resource IDs)
• Bicep / Terraform fragments
• infra/ / tests/ paths sellers have no reason to open
• "If something goes wrong..." troubleshooting

Global dual-mode toggle (mandatory on prep-guide.html).

Individual <details> collapsibles are necessary but not sufficient. Sellers still see se-only section headers and have to scan past them. The prep-guide MUST include a sticky mode toggle bar at the top that globally shows or hides ALL se-only content:

<div class="mode-toggle-bar">
  <span>View mode:</span>
  <button class="mode-toggle-btn is-active" id="btn-seller"
    onclick="setGuideMode('seller')">🎤 Seller</button>
  <button class="mode-toggle-btn" id="btn-se"
    onclick="setGuideMode('se')">🔧 Solution Engineer</button>
</div>

JS pattern:

function setGuideMode(mode) {
  document.body.classList.remove('mode-seller', 'mode-se');
  document.body.classList.add('mode-' + mode);
  // Toggle button active state
  document.getElementById('btn-seller').classList
    .toggle('is-active', mode === 'seller');
  document.getElementById('btn-se').classList
    .toggle('is-active', mode === 'se');
  // In SE mode, auto-open all se-only details
  if (mode === 'se') {
    document.querySelectorAll('details.se-only')
      .forEach(function(d) { d.open = true; });
  }
  try { sessionStorage.setItem('prep-guide-mode', mode); } catch(e) {}
}

CSS:

body.mode-seller details.se-only { display: none; }
body.mode-se details.se-only { display: block; }

Rules:

• Default mode = seller (restored from sessionStorage on load)
• Seller mode: ALL se-only blocks vanish — zero engineering content
• SE mode: ALL se-only blocks appear and auto-open
• The toggle bar is position: sticky; top: 0; z-index: 50
• Mode persists across page refreshes via sessionStorage

Pattern 4 — Internal-jargon deny-list (mandatory on customer-facing artifacts)

Customer-facing artifacts (demo-deck.html, and experience.html if generated) MUST pass a deny-list grep before declaring done. Battle-scar source: a recent live session, where the deck leaked OneAsk, Sweden Central, v1.0, load_skill, and an individual contributor's name across three rejection cycles before the user banned them outright.

prep-guide.html is EXEMPT from this pattern — it's internal-only and legitimately references azd, region labels, command syntax, etc. inside <details class="se-only"> collapsibles (Pattern 3).

Deny-list tokens (case-insensitive grep; zero hits required):

Category	Sample tokens
Microsoft internal product names	OneAsk, OneCRM, MyCSS, OneMSAccount, Substrate, MyOrder, MTS
Azure region / SKU / engineering metadata	Sweden Central, East US 2, S0, v1.0, Phase 26, gpt-5.4-mini-2024-07-18 (the date suffix only — the model name is fine)
Individual seller / engineer PII	first+last name of any contributor, @github_handle, @msft alias, email addresses
Fabricated function names	any _skill / _tool identifier that is NOT in the AGENTS.md Foundry tools required table (catches load_skill, customer_knowledge_base_retrieve, etc.) — see Pattern 6 for the canonical-naming gate

Extensible per pilot. SPEC § 13 assumptions block can carry an additional_denied_tokens: [...] list that gets folded into the grep. Typical additions: customer-internal codenames, prior-vendor product names the customer has explicitly distanced from, regulatory boilerplate they want kept out of the visual narrative.

Validation. Before declaring done, grep the customer-facing artifacts (deck, and experience if generated) for every deny-list token. Any hit → fix → re-grep. Document the grep result in the auto-review hand-off so the user can audit it.

Pattern 5 — Persona placement rule

Personas (named protagonists in the customer journey — e.g. Sarah / Carl / Sophie / Rashid in a Care-journey PoC) live in exactly one artifact:

• ✅ specs/experience.html (the cinematic dossier, if generated) — personas ARE the protagonists of the journey; this is where they belong
• ❌ specs/demo-deck.html — the deck is the customer journey, not the customer. Refer to roles instead of names: "the analyst", "the agent", "the customer", "the case-handler". The talk-deck audience hasn't met the personas; bringing in names mid-talk distracts from the journey.
• ❌ specs/prep-guide.html § Demo Script "Type this:" prompts — the prompts go into the deployed agent as literal strings; the agent's surfaces (Workspace / Teams / Foundry playground) don't know the personas either. Use roles or generic IDs in prompts.

Battle-scar source. A recent live session — the user explicitly banned persona mentions in the deck after the third rejection cycle: "I EXPLICITLY ASKED TO NOT BUG ME ABOUT USER PERSONA!" The fix was a strict grep gate for known persona first-names sourced from experience.html itself.

Validation. Extract the set of persona first-names from experience.html (parse <h*> and <p class="protagonist"> elements matching SPEC § 5 persona schema). Grep the deck for any hit on that set → fail if found. Recommend a fix that swaps the persona name for its role descriptor from the same SPEC § 5 row.

Pattern 6 — Canonical tool-naming gate

Any artifact that depicts the skill chain (deck slide 6, experience trust panel, prep-guide architecture appendix) MUST use tool names verbatim from the AGENTS.md Foundry tools required table — not paraphrased, not abbreviated, not fabricated.

Battle-scar source. A recent live session — slide 7 of the deck originally had customer_knowledge_base_retrieve (paraphrased) and load_skill (entirely fabricated). The user pointed it out: "In the skill chain, why load_skill??". Both names were swapped to the canonical customer_kb name from AGENTS.md.

Validation. Extract every tool name from the deck/prep-guide (and experience if generated) (parse <code> blocks, pill labels, and skill-chain SVG text nodes). Set-diff against the AGENTS.md Foundry tools required table column 1 → fail on any name not in the table. If a tool genuinely needs a display-friendly label, document the alias under AGENTS.md § Tool display aliases and let the diff treat it as canonical.

Pattern 7 — No-commitment closing rule

Microsoft GBB engagements cannot commit dates, effort, or follow-up motions in a customer demo. Customer-facing closing artifacts present concrete options, not commitments.

Battle-scar source. A recent live session — the deck's first closing slide read "Pick one Care journey we'll build together by 12 June." The user killed it: "we can't commit dates or effort, we won't be doing the follow up likely". The fix evolved across v5-v8: first a Discussion slide (3 open questions), then a Follow-up Proposal (3 concrete next steps framed as options on the table, not promises).

Banned phrases (case-insensitive grep over deck slides N-1 and N, plus the experience.html trust panel):

• we'll build, we will build, let's build, build together
• by {date}, by ${MONTH}, any literal future date within 90 days of the deck generation timestamp (regex over ISO + "DD Month" formats)
• let's commit, let's lock, let's confirm dates
• next month, phase 2 dates, Q3 milestones
• pick one journey, pick one process, commit to

Permitted phrasings (style guidance for the Follow-up Proposal slide):

• "Pick 5 high-friction journeys" (action, not commitment)
• "Deploy governance hub" (option, not promise)
• "Establish eval baseline" (technical step, not timeline)
• "happy to explore", "happy to dig in"

Closing shape. The deck's last two slides MUST follow the Follow-up Proposal + Thank-you bookend pattern (see § 7 slide grammar rows 10 and 11). The follow-up presents 3 concrete next steps using <div class="discussion-card"> cards with <span class="qnum">Step 01/02/03</span> labels. Each step is an action the customer could take, framed as an option. Engineer-only commitments (workshop plans, eval runs, effort estimates) belong in prep-guide.html § Suggested Next Steps wrapped in <details class="se-only"> collapsibles (Pattern 3).

Validation. Grep deck slides N-1 and N for banned phrases → fail if found. The Thank-you slide MUST contain literal Thank you. and the MS × {Customer} co-brand bar. The Follow-up slide MUST contain ≥ 3 <div class="discussion-card"> (or equivalent) with step cards; if any card text matches a banned phrase, fail.

7. specs/demo-deck.html — Cinematic Talk Deck (MANDATORY — primary customer-facing artifact)

Read references/demo-deck-template.md for the full kit-of-parts — slide grammar with "use when SPEC has X" rules, CSS token table, JS controller pattern, brandmark substitute recipe, Microsoft 4-color SVG (canonical hex), the 18-symbol icon library, and the "Reasons a deck gets rejected" anti-pattern list drawn directly from prior live-session pain.

Generate a single self-contained HTML file (no external CDNs, no network dependencies) that the seller projects full-screen during the live customer talk. Keyboard-paced; speaker notes panel toggled from the keyboard; ≤ 8 minutes of presentation time.

This artifact REPLACES the legacy overview.html. A long-form scrollable "seller pitch page" is the wrong shape for any live customer moment — too long to skim before the call, too brief and too scrollable to project, and too generic to compete with the bespoke dossier (experience.html). When upgrading an existing PoC, collapse the old overview.html to a 1.8 KB meta-refresh redirect → demo-deck.html (canonical migration recipe in references/demo-deck-template.md § "Migration"); archive the old content as overview.html.bak (add specs/*.html.bak to .gitignore).

Slide grammar — 10 to 13 slides, in order:

#	Slide type	Mandatory?	Use when SPEC has
1	Cold-open (brandmark + customer journey name + headline)	✅ Mandatory	Always
2	Context (customer's stated goal — quote SPEC § 1)	✅ Mandatory	Always
3	Friction (3 numeric pain points — pulled from SPEC § 3 BRs implying current state)	✅ Mandatory	Always
4	The shift (before/after framing — pulled from SPEC § 9 functional success criteria)	Conditional	SPEC § 9 has a quantified primary KPI
5	Preview answer (mock Q&A card with citation pill + version badge — visual insurance before the live demo; if the demo wobbles, flip back to this slide)	Conditional	Any PoC with a live demo path
6	Live-demo cue ("Now let's watch" + optional pure-black holding card for tab-switching)	✅ Mandatory	Always
7	Skill chain (canonical tool sequence — verbatim from AGENTS.md Foundry tools required table)	✅ Mandatory	Always
8	Platform stack (6-7 layer cake: Surfaces · Channel runtime · Agent runtime · Knowledge · Tools+data · Observability · Foundation; each tech pill carries an inline SVG icon from the 18-symbol library)	✅ Mandatory	Always
9	Architecture — hub-spoke + governance (Feature→Service format in hub block, governance cards with repo links; see references/demo-deck-template.md § "Architecture slide")	Conditional	SPEC § 11 governance posture or scale targets
10	Follow-up proposal (3 concrete next steps — options on the table, not commitments)	✅ Mandatory	Always
11	Close (brandmark echo + "Thank you." + Microsoft × {Customer} co-brand bar)	✅ Mandatory	Always

The Follow-up + Close pair on slides N-1 and N is the canonical closing shape for every Microsoft GBB demo. The follow-up slide presents concrete next steps (not open questions) — "Pick 5 high-friction journeys", "Deploy governance hub", "Establish eval baseline" — as options, not commitments. See Cross-cutting Pattern 7 for the banned/permitted phrase enforcement.

Required interactions:

• Keyboard nav — Space / → advance · ← back · F fullscreen · S toggle speaker notes panel · B blackout · 0–9 jump · Home/End first/last
• Sub-state reveals — slides with data-states="N" advance through N reveal states before going to the next slide (Space-paced); used on the cold-open and friction slides for a controlled reveal cadence
• Progress bar + slide counter — always visible, auto-derived from slides.length so adding/removing slides doesn't break the counter
• Speaker notes panel — 1:1 mapping data-for="N" ↔ slide N; toggled by S; rendered in a side-panel that does not project (visible only on the speaker's screen in extended-display mode)

Brand respect (Cross-cutting Pattern 1, deeper rules for the deck):

• Brand FLOODS — full-bleed bg-{brand}-flood panels: friction + follow-up + close mandatory, plus ≥ 1 more chosen from {hero, the-shift, scale, posture} → ≥ 4 flood panels total. Dark hero is allowed (and used in the reference deck).
• Brandmark substitute when no licensed customer logo is available — 2-letter monogram on a white circle on the brand-flood panel; echo on slide 1 + final slide as bookend (e.g. "BC" for Beacon Communications)
• Microsoft 4-color SVG co-brand bar with "Microsoft × {Customer}" wordmark on hero AND close — canonical hex #F25022 #7FBA00 #00A4EF #FFB900
• Canonical tool naming — any deck/prep-guide (and experience if generated) tool name MUST appear verbatim in the AGENTS.md Foundry tools required table (column 1) OR in the optional AGENTS.md Tool display aliases block. See Cross-cutting Pattern 6 for the set-diff gate. Fabricated names (load_skill, paraphrased MCP transports) fail validation.
• Convention fallback — when brand palette isn't explicit in SPEC § 1 and there's no logo URL, look up references/brand-palettes.md; annotate brand_palette_source: convention-fallback in SPEC § 13

Style:

• Single file, no external CDN, fonts, or scripts — everything inline
• Inline <svg> symbol library defined in <defs> once, referenced via <use href="#ico-XXX"> in each tech pill (18 stock symbols documented in references/demo-deck-template.md § "Tech-stack icon library")
• Light-inverse slide (.bg-light + dark text) inserted mid-deck for a rhythm break
• Closing pair (slide N-1 + slide N) uses the Follow-up + Thank you bookend pattern from Cross-cutting Pattern 7

Required validation (mandatory before declaring done): see Step 8 auto-review checklist for the full set; the deck-specific gates include brand-flood panel count ≥ 4, brandmark substitute markup on slide 1 + final slide, MS co-brand block on hero + close, persona deny-list zero hits (Cross-cutting Pattern 5), internal-jargon deny-list zero hits (Pattern 4), tool-name set ⊆ AGENTS.md tool table (Pattern 6), banned closing-phrase zero hits (Pattern 7).

Polish pass (optional but recommended). After generating demo-deck.html, run gbb-humanizer over the speaker-note prose (the <div class="note" data-for="N">…</div> blocks at the bottom of the deck). The seller reads these aloud during the live talk — even small AI-prose tells degrade credibility. Use the pre-canned gbb-seller-pitch.md voice sample. Do not humanize the slide bodies themselves — those are display copy (kickers, headlines, numeric data points) where the prose is already disciplined and the humanizer adds nothing.

8. specs/experience.html — Bespoke Cinematic Customer Journey (OPTIONAL — on request)

A second seller-facing artifact that complements demo-deck.html. Where the deck is a live talk, the experience is a bespoke journey that makes the customer feel the pain, the intervention, the outcome, and the trust posture of this process — through visuals native to its domain.

Generate when requested. This artifact is optional — produce it when:

• The user explicitly asks for a "cinematic", "experience", "journey", or "walkthrough"
• SPEC § 13 assumptions set experience: true
• The process has a clear dramatic moment and a seller will present live

Skip when not requested. The demo-deck.html is the primary customer-facing artifact and is sufficient for most engagements.

⚠️ Bespoke per process — not a template. The single biggest mistake in experience.html generation is reusing the same 4-act layout for every process. The 4-act narrative scroll is the right paradigm for KYC; it is not the right paradigm for a Kanban-shaped order-fallout flow, a graph-shaped network-fault triage, or a geography-shaped supplier-risk monitor. Each process gets its own visual paradigm derived from its protagonist, artifact, and moment of truth. The cinematic toolkit (GSAP, palettes, transitions) is a kit of parts — not a recipe to fill.

The bespoke design discipline:

1. Extract the process DNA from SPEC.md / AGENTS.md / demo-deck.html: protagonist, artifact, moment of truth, backlog number, hard guardrail.
2. Pick the visual paradigm from the catalog (or invent a new one). Examples in the reference doc: 4-act narrative scroll · live topology graph · live Kanban pipeline · world dot-density map · dossier binder · dispatch console split · ledger + regulatory clock · editorial campaign cover · magazine spread · conveyor belt · tender document compose · CAD blueprint annotated · control-room dual-dashboard.
3. Compose three felt movements: density that hurts → zoom into one → the wave processed (with humans in the loop). Land softly on a trust panel.
4. Use the cinematic toolkit (GSAP 3.12.5 + ScrollTrigger from CDN, no defer, inline head gating script with 2.5s fallback, mandatory prefers-reduced-motion: reduce override) — pick 3-5 motion primitives that fit your paradigm (entrance staggers, scroll-scrub, pin-and-scroll, SVG path drawing, color crossfade, camera pull-back).
5. Land on a trust panel (visual inversion, 6 pillars with BR-XXX badges, skill catalog from manifest.json, 3 CTAs to demo-deck/SPEC/back).

Required validation (mandatory before declaring done):

• HTMLParser parses with zero errors
• Whitelabel deny-list grep returns zero hits (file is customer-facing) — including process-domain vendor or product names for the selected industry
• Bespoke check: no id="act-1".."act-4" (those are KYC's), no giant-counter element (KYC's signature), no copy-of-KYC color palette unless the process is KYC
• Playwright at 1440×900: the signature interaction of your paradigm