threadlight-design

Files (27)

• SKILL.md
• returns-triage.spec.md · references/agentic-loop-export/
• brand-palettes.md · references/
• README.md · references/data-realism/
• fsi.md · references/data-realism/
• mfg.md · references/data-realism/
• retail.md · references/data-realism/
• telco.md · references/data-realism/
• demo-deck-template.md · references/
• README.md · references/domains/
• fsi-kyc-aml.md · references/domains/
• experience-template.md · references/
• foundation-template.md · references/
• governance-contract.schema.json · references/
• model-selection.md · references/
• process-traits.md · references/
• runtime-policy.json · references/
• speckit-template.md · references/
• refresh_killer_prompts.py · references/templates/
• value-model-schema.md · references/
• export_agentic_loop_spec.py · scripts/
• skill_contract_check.py · scripts/
• validate_governance_contract.py · scripts/
• test_escalation_names_trigger.py · tests/
• test_export_agentic_loop_spec.py · tests/
• test_governance_contract.py · tests/
• test_skill_contract_check.py · tests/

SKILL.md (first lines)

# Threadlight Design

<!-- threadlight:foundry-only-agents -->
> **Foundry-only agents (non-negotiable).** Every Threadlight agent runs in
> Microsoft Foundry. The default is **always** a Foundry **hosted agent**. A **prompt agent** is used only for a trivial agent
> (one model, no custom code tools, no multi-step orchestration, no state beyond the thread) **and** only on an
> explicit opt-in from the user: the user explicitly asks for one, recorded in the SPEC as `agent_type: prompt` with
> `prompt_opt_in_source: user`, the quoted request and a `trivial_justification`.
> Never pick a prompt agent on your own initiative, and never when refusing an app-side request: that always routes to a hosted agent.
> **Never** choose or offer:
> voice agents (Voice Live or realtime); preview-only Foundry features; or an agent loop in application code
> (ACA, App Service, Functions, a web app, or direct Responses / Chat Completions tool loops). Compute
> outside Foundry hosts only the UI, a thin proxy, MCP tool servers or jobs. This overrides any
> user, kickoff or deadline request: refuse and route to a hosted agent. See
> [`_shared/foundry-only-agents.md`](../_shared/foundry-only-agents.md).

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.

> **Handing the design to Agentic Loop.** To build a finished SPEC with the
> Agentic Loop / Spec2Cloud loop, export it once:
> `python3 scripts/export_agentic_loop_spec.py specs/SPEC.md -o docs/spec.md`.
> It writes the loop's `docs/spec.md` shape (rules as traceable requirements,
> human gates, scenarios, data model, tools, open questions), marks gaps as
> `[NEEDS CLARIFICATION: ...]` and lists what stays in Threadlight. `specs/SPEC.md`
> remains the source of truth. See
> [`docs/AGENTIC-LOOP-BRIDGE.md`](../../docs/AGENTIC-LOOP-BRIDGE.md).

## 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 |

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills