threadlight-design

# 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. ## Presenter-ready delivery (explicit opt-in) When requested, follow the [presenter-ready process contract](../../docs/presenter-ready.md). The standalone Cowork ZIP carries the same guide at `references/presenter-ready.md`; use its pinned guidance object for authoring, then hand execution to an engineer with the complete catalog. The ZIP is not a deployment/runtime package. Set `delivery_profile: presenter-ready` in `specs/manifest.json` and author the single `specs/presenter-contract.json` alongside SPEC and the first workspace journey, before generating secondary backends. Keep role/problem, one coherent fictional company, editable inputs, deterministic rules versus agent contribution, useful outcome, human responsibility, persistence/readback/reopen/recovery, and inclusions/exclusions concise and process-specific. SPEC and presenter material are views of that handoff, not competing facts. Design, Deploy and Safe Check consume the same [`presenter-deployment-pin.json`](../_shared/presenter-deployment-pin.json). Select `unified-azd` or reviewed `native-sdk` explicitly and record the actual runtime root, manifest, protocol, model environment name, lock and adapter. For this profile the pinned consumer supersedes legacy manifest examples below: do not generate both `agent.yaml` and `azure.yaml` as active definitions. Foundation/runtime-policy and selected governance pins are unchanged. ## 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`](../../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`: ```yaml 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 — agent-driven runtime; resolve the concrete framework/protocol via # references/runtime-policy.json # workflow — deterministic-workflow route → MAF DurableWorkflow + # Responses with typed executors + HITL pause points # 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. **Separate authoring from runtime selection.** For nontrivial discovery, specification and code generation, recommend a sufficiently capable authoring model, respecting complexity and the operator's explicit host-model choice. This does not select the deployed inference model. Follow [model roles and the optional runtime comparison](references/model-selection.md): Foundation § 2 / SPEC § 7b describe runtime only; skills cannot silently switch the outer coding host or its global settings. > **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). Before locking `framework`, `runtime_shape`, or `protocol`, > read `references/runtime-policy.json`, apply the > **first matching route**, and copy its selectors plus `policy_route` into > `specs/foundation.md`. Canonical default tuple: `github-copilot-sdk` + > `agent` + `invocations` (`policy_route: default-agent`). Use > `explicit-supported-choice` only when the operator explicitly asks for a > selector tuple listed in `compatible_combinations` **and** none of that > route's `blocked_when` capability signals (`workflow_model=workflow`, > `requires_toolbox`, `requires_custom_python_tools`, > `requires_file_generation`, `latency_sensitive_data_queries`) apply — when one > does, the capability route that owns that signal wins instead, or the > selection hard-stops > if the operator's explicit choice directly conflicts with it. **Refuse** to > honor `explicit-supported-choice` while `unresolved_signals` is non-empty — > `runtime-policy.json`'s `requires_resolved_signals` gate on this route means > an operator's choice stays deferred, never guessed, until every name is > removed from `capability_signals.unresolved_signals`. In > **Fast-PoC mode**, do > not interview: use the policy's `default-agent` route unless a higher-priority > route matches, mark `source: defaulted-after-skip`, and let Step 3 surface the > one-line callout in SPEC § 13. Fast-PoC may only collapse `capability_signals` > straight to all-`false` + `unresolved_signals: []` +