# Threadlight — Pilot Pipeline Skills
**Threadlight is** a library of skills that GitHub Copilot follows in your
repository to turn a business process into a working agent pilot on Microsoft
Foundry, then carry it toward production with selected runtime controls and the
evidence for each. It is an open-source pattern from Microsoft GBB · AI Apps,
**not an official Microsoft product or support offering**, provided as is under
the [MIT License](LICENSE).
- **Who it is for:** Microsoft solution engineers and customer teams shaping an
agent pilot together.
- **What you need:** GitHub Copilot (CLI or IDE). Design, code generation and
local checks can run without an Azure subscription; a live pilot needs an
Azure subscription with Microsoft Foundry, where the agent runs as a hosted agent.
- **What it does not do:** certify production. A readiness assessment
identifies gaps with owners; governance is evidenced per selected action,
never for the whole agent.
**Start here:** the [visual site](https://aiappsgbb.github.io/threadlight-skills/)
· [documentation index](docs/README.md) ·
[glossary](https://aiappsgbb.github.io/threadlight-skills/glossary.html) ·
[your first governed workflow](docs/first-governed-workflow.md) ·
[from demo to production](#from-demo-to-production) ·
[install](#install).
## Install
### As a plugin (recommended)
```bash
copilot plugin marketplace add aiappsgbb/threadlight-skills
copilot plugin install threadlight-skills@threadlight-skills
```
### Individual skills
```bash
gh skill install aiappsgbb/threadlight-skills threadlight-design
gh skill install aiappsgbb/threadlight-skills threadlight-deploy
# ... etc
```
### Companion skills: official first
Official Microsoft skills are the default. Threadlight composes with
`azure@azure-skills` from [microsoft/azure-skills](https://github.com/microsoft/azure-skills)
(source: `microsoft/GitHub-Copilot-for-Azure`) for Foundry agents, azd, deploy,
diagnostics, RBAC, private networking, AI services and cost. The full mapping,
with the official tag checked and the evidence for every exception, is in
[`skills/_shared/skill-dependencies.json`](skills/_shared/skill-dependencies.json).
The official release Threadlight is tested against is pinned by tag, commit and
file hashes in [`skills/_shared/official-skills-lock.json`](skills/_shared/official-skills-lock.json);
`python3 scripts/verify_official_skills_lock.py` recomputes it from the tag.
To check what your Copilot actually loads, run `python3 skills/_shared/official_skills.py`:
it reports each locked official skill as OK, MISSING or DRIFT (including a stale
personal copy that shadows the plugin), with the install fix and the
Threadlight fallback recorded under `official.fallbacks` in the manifest. It
reports ORDER when the official plugins were installed before threadlight-skills,
or when personal skills and other plugins listed earlier would leave
`threadlight-auto`, `-design` or `-deploy` without a description (see the install order below), and UNCHECKED (exit 2) when the `copilot` CLI cannot list skills.
`threadlight-auto` runs it in Stage 0 and continues with a warning.
| Need | Use |
|---|---|
| Foundry hosted/prompt agents, toolbox, skills, routines, evals, traces, RBAC, private network | `microsoft-foundry` (official) |
| azd prepare, validate, deploy | `azure-prepare`, `azure-validate`, `azure-deploy` (official) |
| Diagnostics, AI services, App Insights | `azure-diagnostics`, `azure-ai`, `appinsights-instrumentation` (official) |
| Cost analysis, estimation, governance and optimization | `azure-cost@azure-skills` (official: `cost-analysis`, `cost-estimation`, `cost-governance`, `cost-optimization`) |
| Subscription quotas and usage before provisioning | `azure-quotas` (official, in `azure@azure-skills`) |
| Advisor recommendations and service retirements | `azure-advisor@azure-skills` (official, separate plugin) |
Where no official skill covers a capability Threadlight needs, Threadlight
ships its own skill or reference, labelled **Threadlight-owned** with a
`PROVENANCE.md` recording the source revision it was ported from:
| Capability | Threadlight-owned home |
|---|---|
| Citadel governance hub (APIM AI gateway) | `threadlight-citadel-hub` |
| Citadel spoke onboarding | `threadlight-citadel-spoke` |
| Tenant isolation | `threadlight-tenant-isolation` |
| MCP servers on Azure Container Apps | `threadlight-mcp-aca` |
| In-process AGT/ACS governance | `threadlight-govern` (`references/agt-inprocess/`) |
| Composable azd/Bicep module catalog | `threadlight-deploy` (`references/azd-modules/`) |
| Native-SDK hosted-agent contract (MAF, GHCP) | `threadlight-deploy` (`references/hosted-agent/`) |
The pipeline needs only the official plugins and threadlight-skills. A few
optional GBB pattern skills outside the pilot path (Teams publishing, AgentOps,
SRE Agent, backup and alert baselines, PAYG/PTU break-even) remain in
[awesome-gbb](https://github.com/aiappsgbb/awesome-gbb), labelled
**GBB pattern, not a Microsoft product skill**; install them only when you need
that capability. `foundry-iq` exists under the same name in both catalogs; use the
official `foundry-iq-skills@azure-skills`. Live demos keep their recorded pins;
this mapping does not change them.
**Install threadlight-skills first, then the official plugins.** Copilot CLI
(observed on 1.0.91) describes plugin skills in install order up to a prompt
budget and lists the rest by name only. Installed after the official plugins,
no `threadlight-*` skill is described and prompts such as "deploya il pilota"
route to `azure-deploy` (offline routing matrix: 88% official-first vs 100%
threadlight-first). The budget (about 15,000 characters) is shared with personal
skills (`~/.copilot/skills`, `~/.agents/skills`) and every other plugin listed
earlier: on a machine with Work IQ, Microsoft 365 Agents Toolkit and awesome-gbb
installed first, no `threadlight-*` skill was described even without the
official plugins. Install threadlight-skills before other skill-heavy plugins
too. `official_skills.py` simulates the budget from `copilot skill list --json`
and reports either case as `ORDER`, naming the plugins listed ahead.
```bash
copilot plugin marketplace add aiappsgbb/threadlight-skills
copilot plugin install threadlight-skills@threadlight-skills
copilot plugin marketplace add microsoft/azure-skills
copilot plugin install azure@azure-skills
copilot plugin install azure-cost@azure-skills # cost analysis/estimation
copilot plugin install foundry-iq-skills@azure-skills # Foundry IQ (preview)
copilot plugin install azure-advisor@azure-skills # optional: Advisor recommendations
```
The official plugins (v1.2.113) ship `SessionStart` and `PostToolUse` hooks that
send usage telemetry to Microsoft. To opt out, set
`AZURE_MCP_COLLECT_TELEMETRY=false` in the environment that starts Copilot.
Already have the official plugins (or other skill-heavy plugins)? Reinstall
them after threadlight-skills, or disable the ones you do not need in workshops:
```bash
copilot plugin uninstall azure@azure-skills && copilot plugin uninstall azure-cost@azure-skills && copilot plugin uninstall foundry-iq-skills@azure-skills
copilot plugin install azure@azure-skills && copilot plugin install azure-cost@azure-skills && copilot plugin install foundry-iq-skills@azure-skills
```
## Contract for coding agents
The rules below bind every coding agent that uses these skills. People can
skim them; agents must follow them.
> **A business process becomes a working pilot with selected runtime governance and an evidence-backed path to production.**
>
> Twenty-seven pipeline skills plus one agent-guided lifecycle planner (28 total) take a brief into a working pilot. Governance is evidenced per selected binding, not asserted for the whole agent. A working session produces the pilot and auditable evidence; production certification, settled Azure actuals, and customer-environment onboarding each have their own timelines.
>
> **Idea to production, alongside the build tools you already use.** Threadlight
> is complementary to the GBB Agentic Loop and to Kratos exports: it designs the
> business process and carries the pilot to production evidence, and it can
> [hand its design to the Agentic Loop](#handing-a-design-to-the-agentic-loop) or
> [harden a Kratos export](#starting-from-a-kratos-export). Use only the skills
> you need.
>
> SPEC § 14 is the value-model contract: baseline, target, owner, timeframe,
> measurement source, and maturity policy. Its public arc is forecast →
> settled Azure actuals → reconciliation → cost per successful interaction.
>
> **Foundry-only agents (non-negotiable).** Every agent that Threadlight
> produces runs in **Microsoft Foundry**. The default is **always** a Foundry
> **hosted agent**. A **prompt agent** is allowed only for trivial cases (one
> model, no custom code tools, no multi-step orchestration, no state beyond the
> thread) and only on an explicit opt-in: the user explicitly asks for one, recorded
> in the SPEC as `agent_type: prompt` with `prompt_opt_in_source: user` and a
> `trivial_justification` (an agent-written value is not an opt-in). Never pick a
> prompt agent on your own initiative, and never when refusing an app-side request:
> a refusal always routes to a hosted agent.
> A Foundry voice agent (preview) is used only on an explicit user opt-in
> (`agent_type: voice` with `voice_opt_in_source: user` and
> `preview_acknowledged: true`), built with the official `microsoft-foundry` skill.
> Other preview-only Foundry features, Voice Live calls from app code and any agent loop in application
> code are **not supported**, and are never chosen or offered. That includes
> ACA, App Service, Functions, a web app, or direct Responses / Chat Completions
> tool loops. Container Apps hosts only the UI, a thin proxy to the Foundry
> agent, MCP tool servers or jobs. See
> [`skills/_shared/foundry-only-agents.md`](skills/_shared/foundry-only-agents.md).
>
> **Full Foundry package (mandatory).** A pilot is complete only with a real
> Foundry agent (no fake or fallback agent), Application Insights with a trace
> visible in Foundry, a Foundry eval run with built-in evaluators plus a
> SPEC-derived custom rubric, executed against the deployed agent. Continuous
> evaluation is optional (GA evaluation rules reject hosted agents). Otherwise
> deploy, auto and production-ready report **INCOMPLETE** and list the missing evidence.
## What is a skill?
A **skill is a reusable instruction package**: a `SKILL.md` describes when to
use it, the procedure, inputs, outputs and boundaries; companion files can
provide templates, scripts and references. Markdown is not a model, a tool
implementation, permission or runtime enforcement.
Threadlight has **two distinct libraries and agents**:
- The **construction agent** reads this catalog's `skills/threadlight-*` to
qualify a brief, design a system, generate code, run available checks or hand
work to an operator.
- The **generated business agent** uses its own domain
`src/agent/skills/*/SKILL.md`, host instructions, registered tools and SDK
runtime. For example, the public returns assistant has intake, eligibility,
fraud-escalation and disposition skills—not Design or Deploy skills.
The reviewed SPEC connects the two: brief → foundation/SPEC checkpoint →
`AGENTS.md` and domain skills → concrete tools/data/tests → local iteration →
approved deployment → evidence. Orchestration belongs to instructions/runtime
or an explicit deterministic workflow, not a new domain “orchestrator” skill.
The local policy defaults to GHCP SDK / agent / Invocations, with conditional
MAF agent or workflow / Responses routes. A local MAF quickstart is not hosted
parity, and a running host is not proof it consumed its skills.
## From demo to production
A customer first sees a **recommend-only Fast-PoC**: a Foundry hosted agent that
reads, cites the business rule and proposes, while a person records the
decision ([1-hour workshop](docs/WORKSHOP-1H-QUICKSTART.md)). The same pilot
then moves toward production without a rewrite. What exists today, and how far
each step is proven (live runs on Threadlight's own returns-triage pilot in an
internal nonproduction subscription, not a customer certification):
| Capability | Proof | Still open | Read |
|---|---|---|---|
| Recommend-only Fast-PoC | Proven live | Grounding on customer data (deferred to `threadlight-ground`) | [Workshop](docs/WORKSHOP-1H-QUICKSTART.md) |
| Governed write, one-click approval (panel or email) | Proven live, with limits: panel click on GHCP, one binding | No GHCP Outlook decision yet; not whole-agent governance | [Kit](examples/governed-write-ghcp/README.md), [S8](docs/governed-returns-validation.md#s8-governed-write-on-ghcp-workshop-kit) |
| Voice in the caller's language (Hosted Voice, preview, opt-in) | Proven live, with limits: synthetic callers | Real human voice, real phone line | [Voice readiness](docs/production-readiness.md#voice-readiness-only-when-the-pilot-has-a-voice-front-end) |
| Private network: VNet, private endpoints, API Management or customer gateway, landing zone, egress firewall | Proven live, with limits: stand-in hub and gateway | Developer gateway tier, Cosmos DB private endpoints, DR, budgets, Defender | [Private profile](skills/threadlight-deploy/references/private-profile.md) |
| Identity: least-privilege agent identity, OBO, A2A, kill switch | Proven live, with limits | Conditional Access (Microsoft 365 E7, or Agent 365 plus Entra ID P1), Teams/Microsoft 365 channels, OBO on the governed write | [Identity model](docs/agent-operations.md#identity-model-who-acts-with-which-permissions) |
| Load test and latency waterfall | Proven live, with limits: up to 50 concurrent | An SLA; voice turns in the waterfall | [Performance](docs/production-readiness.md#performance-evidence-load-test-with-latency-waterfall) |
| Only the SPEC's tools (no Copilot CLI built-ins) | Proven live | Quality change beyond one 28-row evaluation | [Tool allowlist](skills/threadlight-deploy/references/hosted-agent/ghcp/README.md#tool-allowlist-no-copilot-cli-built-ins-by-default) |
| Pilot value page for the sponsor | Offline only | No live run recorded | [Pilot value](docs/production-readiness.md#pilot-value-page-sponsor-view) |
| EU AI Act customer handoff | Offline only | No legal review; never a compliance claim | [Handoff](docs/eu-ai-act-evidence.md#customer-handoff-bundle) |
| Cost per use case and per agent | Proven live, with limits: read-only, one subscription | Token-weighted allocation, Copilot Studio meters | [Portfolio](skills/threadlight-consumption-iq/SKILL.md#portfolio-cost-per-use-case-and-per-agent-opt-in-read-only) |
| One agent or several | Offline only | No runtime multi-agent wiring is generated | [Agent topology](skills/threadlight-design/references/process-traits.md#trait-agent-topology-one-agent-with-skills-or-several-agents) |
The visual version, with one diagram and the dated figures, is
[From demo to production](https://aiappsgbb.github.io/threadlight-skills/demo-to-production.html).
## Choose your learning path
| Public chapter | What you will learn |
|---|---|
| [Home](https://aiappsgbb.github.io/threadlight-skills/index.html) | What Threadlight offers and where its evidence stops |
| [Basics](https://aiappsgbb.github.io/threadlight-skills/basics.html) | Skills, the two agents, tools and runtime responsibilities |
| [Build](https://aiappsgbb.github.io/threadlight-skills/funnel.html) | Construction choices and the brief-to-pilot path |
| [Case study](https://aiappsgbb.github.io/threadlight-skills/case-study.html) | A concrete process, decisions and implementation boundaries |
| [From demo to production](https://aiappsgbb.github.io/threadlight-skills/demo-to-production.html) | What a pilot can show today, each step with its proof level and what is still open |
| [Production](https://aiappsgbb.github.io/threadlight-skills/production.html) | From a working pilot to a controlled release: foundation, validated release, governed actions, evidence and owners ([technical companion](docs/production-governance.md)) |
| [Glossary](https://aiappsgbb.github.io/threadlight-skills/glossary.html) | Plain definitions of SAFE, ACS, PEP, AGT, Citadel and the levels of evidence |
For a hands-on starting point, follow
[Your first governed workflow](docs/first-governed-workflow.md): one returns
decision, six practical phases, and explicit handoffs from local rehearsal to
native Outlook review and a controlled release.
For the **L400/L500 engineering mental model**, read
[Skill-based agents: construction, runtime and evidence](docs/skill-based-agents.md).
It includes actual runtime loading, the local skill catalog, Cowork versus
engineering-host requirements and safe offline checks.
[`THREADLIGHT.md`](THREADLIGHT.md) retains the exhaustive per-skill reference.
The governance section below preserves the current control and evidence contract;
it is not a prerequisite for understanding what a skill is.
For an explicitly requested repeatable demonstration, use the opt-in
[presenter-ready PoC contract](docs/presenter-ready.md): one process-owned handoff,
selected deployment consumer, exact packaged integration evidence, business UX,
durable result retrieval where promised, and distinct source/deployment/backend/
script/human acceptance states. It is not mandatory production governance and
does not turn offline catalog checks into hosted acceptance.
The paid live workflow has two evidence meanings. **Live smoke** proves the
design, deployment, invocation, and assurance producers executed; it does not
assert production readiness. **Readiness proof** additionally requires a green
post-deploy safe-check, current per-binding runtime evidence, comprehensive evals,
hardened red-team evidence, a ready production scorecard, and measured outcome KPIs.
The `local-native-contract` CI job is local proof only. The separate protected
`readiness-proof` job fails without actual signed policy, registered services,
explicit preproduction probe opt-in and fresh hosted evidence; it does not
substitute a noop result for an unverified business binding.
## Controlled releases: choose your depth
| Level | Start here | Purpose |
|---|---|---|
| Public overview (L200/L300) | [Production: AgentOps and release](https://aiappsgbb.github.io/threadlight-skills/production.html#operating-controls) | Understand candidate validation, production approval and the boundaries of a release |
| Repository explanation | [From a working pilot to a controlled release](docs/agentops-deep-dive.md) | Learn the terms, responsibilities, delivery sequence and what has or has not been exercised |
| Operator contract (L400/L500) | [Verified release contract](skills/threadlight-cicd/references/release-contract.md) | Configure actual adapters, evidence, identities, receipt checks and failure recovery |
CI/CD 0.6.0 validates a separate preproduction candidate before admitting
promotion of the same immutable image. The application team supplies deployment,
observation and evidence-producing adapters; the platform team supplies approved
identities, runners and protected environments. Generation does not supply those
integrations or grant access.
**Three separate decisions:** releasing a version, authorizing a selected runtime
action, and accepting the application for business go-live. None implies the
other two. Catalog tests and the real loopback AgentOps test are **not cloud acceptance**;
customer-pipeline execution, production Doctor and live business checks remain
separately authorized work.
## Runtime governance: method, enforcement and evidence
**Choose your depth:** the **L200/L300**
[visual walkthrough: Governance & AgentOps](https://aiappsgbb.github.io/threadlight-skills/governance.html)
explains action controls and evidence boundaries; the **L400/L500**
[operative guide](docs/agent-operations.md) connects configure → generate →
validate → approved deployment → collect → rescore, with prerequisites, artifacts
and recovery. It also covers the **opt-in AgentOps integration (merged PR #128)**,
with separate source and preview-maturity boundaries. Lifecycle evidence
integration does not replace runtime enforcement, quality gates or readiness.
For an existing hub, [Citadel action execution](docs/citadel-governance.md)
adds an opt-in APIM-to-native-PEP path with independent producer/consumer
policies. Its [dated live record](docs/governed-returns-validation.md#s7-citadel-public-route-and-isolated-producer-ack-loss)
separates public routing, job-only producer ACK loss and genuine requester
confirmation; it does not certify a new deployment or the whole agent.
**SAFE is the method** for defining business invariants. **ACS is the PDP**
(policy decision point), evaluating native Rego through OPA locally.
**Agent Hooks is the host/interceptor contract SDK**; the **native host or
governed-tool gateway is the PEP** (policy enforcement point) at the selected
action lifecycle boundary. **AGT is the toolkit**, not automatic all-tools
protection. **ASSERT is assurance**, not an enforcement engine.
Select tool, intervention point and execution path explicitly. Report each as
`enforced`, `observed`, `unbound`, `unverified`, `unsupported` or `bypassable`.
A policy file, green CI, or one enforced binding never means whole-agent
`governed` or SAFE-complete. Unbound read tools remain usable without ACS;
unbound consequential actions require current scoped risk acceptance for
readiness, not an arbitrary boolean. Invalid selected configuration is not `off`.
Required controls fail closed **before effects**: a trusted, signed, fresh
policy; authenticated human approval bound to tenant, roles, full action scope
and a one-use CAS nonce; trusted target/schema and dynamic backend facts; and
centrally durable audit ACK. Local spool fsync is retry safety, not hosted
durability. Host facts, not model claims, supply SAFE evidence; authorization
must survive waits and be rechecked at terminal dispatch.
- **Native MAF:** selected local hooks support tool/lifecycle and buffered-output
controls. Selection is not automatic full SAFE. Compaction, provider-hosted
tools and incremental streaming/custom clients remain unsupported.
- **GHCP:** only registered gateway action paths can claim effect closure.
No arbitrary URL/shell routing, full lifecycle or full-output coverage.
- **Distribution:** actual registered ACA control-plane/gateway services use
Cosmos, Blob, Key Vault and separate UAMIs/permissions. ACS stays the local
policy engine; signing/publishing is distinct from runtime verify/read.
The authoritative [shared pin](skills/_shared/governance-upstream-pin.json)
uses `agent-governance-toolkit-core==5.0.0` (not the old umbrella installer),
ACS `0.3.1b0`, Agent Hooks `0.1.0a5`, MAF core `1.14.0`, Foundry `1.11.0`,
hosting `1.0.0b260813`, OPA `1.18.2`. Preview/alpha integrations and explicit
experimental defaults require review. The immutable official runtime is not
patched: the corrected CTK **test-only oracle** covers 47 declared vectors;
four incremental-output vectors are undeclared, not “51 passed”.
Evidence remains separated: offline inventory → executed **LOCAL-14** proof and
exact-published native/CTK tests (local only) → ARM/Foundry-observed deployment
and fresh hosted invocation. The Task11 collector registers fresh allow/deny
nonces, observes tenant/subscription/RG/version/image/principal and closed config
before/after, and joins authenticated producer/fixture counters with control-plane
receipts. Only reserved `governance_probe_noop` is probed; business bindings stay
unverified. The current canonical [returns example](examples/returns-triage-governed/)
records a Cosmos decision/audit, not payment settlement; its business binding
has local proof, not live proof.
Current artifacts are `specs/governance-manifest.json`
(`threadlight-governance-manifest/v1`), `tests/governed-actions-manifest.json`,
and `.threadlight/governance-live.json`. Legacy v2 verdicts are historical
provenance only. A new deployment attempt needs new **after-deployment** proof;
file mtime, a prior empty gaps array or a changed signing envelope cannot renew it.
See [production guidance and CI inputs](docs/production-readiness.md#runtime-governance-lifecycle)
and [coding-agent guidance](AGENTS.md).
**The model proposes; trusted components authorize effects.**
[Production: governed actions](docs/production.html#effect-authority) explains
the actors, model-versus-tool gateways and selected action paths.
The [existing-pilot guide](docs/agent-governance.html) reuses your Threadlight
SPEC, code and tools through five governed-release prompts and verification
checkpoints. The approved Markdown workbook remains the detailed reference.
After promotion, the [day-2 operating guide](docs/operate.html) covers fresh
evidence after each deployment, change gates, weekly review, unknown outcomes
and turning incidents into regression cases.
Validation facts and implementation limits remain in the engineering references.
For the actual
identity, policy, approval, transport and durable-audit boundaries, read the
[engineering deep dive](docs/agent-governance-deep-dive.md). The separate
[dated execution record](docs/governed-returns-validation.md) distinguishes the
historical public hosted two-tool vertical, the private BASIC model smoke,
subsequent private governed allow/deny evidence, and the verified private native Outlook approval
with same-session resume and replay without a second business effect. This is
historical reference evidence, not current authority or live acceptance of the
canonical example above. The
[Pages/readiness specification](docs/production-readiness-pages-spec.md) records
the presentation and evidence boundaries; rapid prototyping remains unchanged and
additional governance is explicit opt-in.
| Skill | What it does |
|-------|-------------|
| [`threadlight-qualify`](skills/threadlight-qualify/) | **No-repo / Cowork qualification & sizing entry — *before* Design.** Turns a declared interview (no Azure, `az`, `azd`, Bicep, Docker, or customer credentials) into a deterministic sizing package — `qualification/sizing.md`, `sizing-manifest.json`, `discovery.md`, optional `roi.md` — and seeds SPEC § 12 `load_profile{}`. **Not a deployed runtime skill.** |
| [`threadlight-design`](skills/threadlight-design/) | Locks the technical foundation (framework, model, hosting, identity, observability) up front, then produces SPEC.md, demo deck, prep guide, experience page from a brief |
| [`threadlight-local-test`](skills/threadlight-local-test/) | Boots the agent locally for rapid iteration (Pattern 0 quickstart) |
| [`threadlight-deploy`](skills/threadlight-deploy/) | 7-phase `azd up` orchestration — ACR, Bicep, hooks, Foundry, Citadel |
| [`threadlight-safe-check`](skills/threadlight-safe-check/) | Pre/post-deploy gate — resource selectors plus mandatory scoped collector evidence for selected governance |
| [`threadlight-demo-data-factory`](skills/threadlight-demo-data-factory/) | Generates industry-realistic seed data for demos |
| [`threadlight-event-triggers`](skills/threadlight-event-triggers/) | Wires ACA Jobs, Event Grid, and cron receivers into the deploy lifecycle |
| [`threadlight-connect`](skills/threadlight-connect/) | the **CONNECT leg** (manual hand-off). Evidence-based swap of a scaffolded **mock** Foundry tool for a **real** endpoint — extracts the contract the tool source actually reads, generates conformance tests, and gates `mock → real` on conformance **AND** OBO user-scoped evidence **AND** required-role revalidation vs the current identity. Config writes need `--apply` + a validated `--real-endpoint`; emits `specs/connect-manifest.json` (INT-001..004). `threadlight-auto` does **not** run it. |
| [`threadlight-ground`](skills/threadlight-ground/) | the **GROUND leg** (manual hand-off). Assesses caller-supplied ACL / citation / refusal probe evidence into `specs/ground-manifest.json` (GRD-001..004) — a proven ACL leak is `must-fix`, missing/ambiguous evidence is `not-verified` (never guessed). A **coordinator**, not a retrieval engine: it never calls Foundry IQ or runs a live probe. `threadlight-auto` never runs probes. |
| [`threadlight-hitl-patterns`](skills/threadlight-hitl-patterns/) | Human-in-the-loop gates via Teams Adaptive Cards + audit trail |
| [`threadlight-workspace-ui`](skills/threadlight-workspace-ui/) | Framework-agnostic vanilla HTML/JavaScript reference patterns behind Easy Auth (not React) |
| [`threadlight-consumption-iq`](skills/threadlight-consumption-iq/) | Current forecast + read-only actuals + reconciliation + measured cost per successful interaction; actuals are later-pilot. Walks Bicep + `azd env`, reads SPEC § 12 `load_profile{}` (wizard writes it if absent), hits Azure Retail Prices for current SKUs + 2–3 alternatives per resource (AOAI, Foundry, ACA, Cosmos, Storage, APIM, AI Search), emits `docs/cost-projection.md` + `specs/cost-manifest.json`. Soft-advisory; consumed by `production-ready`'s tightened COST-005 + new COST-006. |
| [`threadlight-evals`](skills/threadlight-evals/) | the **DISCOVER/GOVERN evals leg**. Runs offline batch quality evals (delegates invoke+score to `microsoft-foundry`), wires **Foundry Continuous Evaluation** on live threads (`create_agent_evaluation` → App Insights), and an **A/B champion–challenger** comparison gate before a model/prompt swap. Emits `specs/evals-manifest.json` that `production-ready` pillar 6 (EVAL-001..004) consumes as leg-verified evidence. |
| [`threadlight-redteam`](skills/threadlight-redteam/) | the **DISCOVER safety leg**. Runs the **AI Red Teaming Agent** (PyRIT-based) adversarial scan for jailbreak / prompt-injection / data-exfiltration / harmful-content, emits `docs/redteam-report.md` + `specs/redteam-manifest.json`. Maps attack-success-rate to `production-ready` pillar 7 SAFE-101..106 findings. |
| [`threadlight-govern`](skills/threadlight-govern/) | Authors and validates native ACS/Rego bundles, routes explicit host/service generation, emits offline per-binding `specs/governance-manifest.json`; never declares runtime enforcement from policy/CI. |
| [`threadlight-governed-actions`](skills/threadlight-governed-actions/) | Produces selected runtime templates through the real generator and assesses inventory, executed LOCAL-14/native path proof, approvals, audit and the change plane. `--emit --gate` writes `tests/governed-actions-manifest.json` and the Governance Evidence Pack. Local conformance is not live enforcement or certification. |
| [`threadlight-production-ready`](skills/threadlight-production-ready/) | Advisory scorecard/handoff, not certification; remediation and deployment are explicit separate choices. BicepGraph parser, 13 pillars, Defender / Policy / quota / restore-drill checks, `--gate-preview`, `--diff`, `--remediate`, `--trend-csv`, OIDC CI. Hard dep on `bicep` CLI; no regex fallback. Pillars 2/6/7 consume the govern/evals/red-team leg manifests when present + fresh, plus the connect/ground/load/upgrade gap-evidence legs. |
| [`threadlight-loadtest`](skills/threadlight-loadtest/) | the **LOAD leg** (manual, live, cost-bearing). Runs one budget-capped load profile through **k6 / locust** (or an injected adapter) and emits `specs/load-manifest.json` (`threadlight.load/v1`, LOAD-001..003) with real p50/p95/p99 latency, error-rate, and tokens/request evidence. Aborts before any run if the projected cost exceeds `budget_ceiling_usd`, or if a production endpoint lacks explicit `allow_production`; never installs k6/locust; never loops. `threadlight-auto` does **not** run it. |
| [`threadlight-upgrade`](skills/threadlight-upgrade/) | the **UPGRADE leg** (plan-only). Scans dependency pins, hosted-agent runtime policy, governance profile, and model families against a dated `compatibility-matrix.json` and emits `specs/upgrade-manifest.json` (UPG-001..003) + **one ordered migration plan**. No network calls, no `--apply` — it **never edits the project**. Acting on the plan is a manual, human-driven step. |
| [`threadlight-cicd`](skills/threadlight-cicd/) | **v0.6.0** — verified-release pipeline for **GitHub Actions or Azure DevOps**: isolated candidate, executed eval/red-team/MCP checks, bound receipt and approved same-image promotion. Optional two-tool returns adapters add observed behavior, closed admission and explicit reconciliation. Application operators and environment protection remain customer-owned. Keeps the workload pipeline **separate** from `threadlight-citadel-hub`. |
| [`threadlight-customize`](skills/threadlight-customize/) | the **fork-and-customize final leg**. Instructions/runbooks (not automation) for forking the Threadlight pipeline and onboarding it into **one customer's environment** — landing zones, RBAC, pipelines, governance — with **production onboarding priority #1**. Four moves: intake gate (customer-profile workbook), customization map (fork-vs-keep), test-in-customer-env runbook (private-VNet via **Azure ML VS Code** / **GH Codespaces**), and an explicit non-coverage boundary. Ships a fork-runbook (`upstream-pin` + overlay). Manual handoff — `threadlight-auto` does **not** drive it. |
| [`threadlight-router-bench`](skills/threadlight-router-bench/) | the **IMPROVE leg**. Offline self-improvement cold-path: `learn <run_id>` harvests ONE finished CI run (green *or* red) into a grounded learnings digest — phase parity, a reality-tuned failure taxonomy, and recommendations; optional `bench <candidate> <baseline>` is a paired model-router **cost/quality scorecard** from Azure Monitor token metrics. Offline — `threadlight-auto` does **not** drive it. |
| [`threadlight-auto`](skills/threadlight-auto/) | **Agent-guided lifecycle planner** — `orchestrator.py` decides, coding agent executes; manual/live/cost-bearing/plan-only legs are handoffs. Reads evidence, chooses the next stage, resumes from `.threadlight/auto-state.json`, and smart-recovers quota/RBAC/ImagePull failures. Does **not** drive the manual legs (qualify, connect, ground, loadtest, upgrade, cicd, customize) or the offline router-bench. |
| [`threadlight-agentops`](skills/threadlight-agentops/) | Optional per-agent operations evidence. `agentops.yaml` opts each agent in; missing opt-in is not a gap. Validates native provenance and emits `specs/agentops-manifest.json`; canonical eval/red-team consumers reuse compatible evidence without rerunning it. Production-ready owns the residual `AOPS-001` aggregate; governance and Citadel authority are unchanged. |
| **Threadlight Lifecycle Canvas** | **GitHub Copilot App enhancement** for the process owner: where the pilot stands, what is in the way and the one next step, read from `threadlight-auto`'s committed plan (`.threadlight/auto-next.json`). Shows the process from `specs/SPEC.md` (rules with derivable proof), the planner's real gate chain with "you are here", go-live readiness and the cost estimate; skills and evidence files stay under technical details. Actions are chat requests that need confirmation. Optional; existing CLI/Cowork/Coding Agent flows are unchanged. |
### Optional AgentOps adoption
Use [foundry-agentops in awesome-gbb](https://github.com/aiappsgbb/awesome-gbb/tree/2db28d1f52bf288f2d0fd40b7c8beb913ceeee09/skills/foundry-agentops)
to install/configure the pinned native accelerator; use `threadlight-agentops`
to normalize existing evidence. This integration does not install a second eval,
red-team or governance engine. `threadlight-cicd` remains the workflow owner.
An executed smoke, a quality threshold result and production readiness are
different outcomes; native Doctor `ready` never replaces Threadlight's verdict.
The optional Canvas entry is a non-gating `manifest-observed` view. It does not
re-execute the Python binding validator or independently prove Azure state;
production-ready consumes the strictly validated manifest.
### Canonical lifecycle classification
| Stage class | What runs | Evidence boundary |
|---|---|---|
| No-repo entry | qualify; declared evidence, no Azure | sizing only; no runtime artifacts |
| Agent-guided pilot path | design, local iteration, deploy, safe-check, forecast, invoke, evals and red-team; selected bindings require govern + governed-actions gate before deploy and hosted probe after it | Auto plans; caller-owned work and actual gate artifacts provide pilot evidence |
| Manual live evidence | connect, ground, load-test | live, customer, and cost-bearing evidence captured by handoff |
| Optional handoff | production-ready, CI/CD, customize | advisory or deployment/runbook handoffs |
| Later-pilot evidence | settled actuals and reconciliation | post-pilot value evidence and cost reconciliation |
| Offline improvement | router-bench and upgrade | finished-run learning and compatibility scans |
## Capability flow, not one universal execution order
The catalog is a set of capabilities, not a universal execution DAG. In
particular, **selected-binding governance is prepared and gated before deploy**,
then probed after deploy. The current Auto sequence and manual handoffs are
documented in the [engineering guide](docs/skill-based-agents.md#auto-is-construction-lifecycle-orchestration).
The sketch below groups work; it does not authorize or automatically run it.
```
threadlight-qualify (no-repo / Cowork sizing — before any repo exists) →
threadlight-design → threadlight-local-test →
SELECTED BINDINGS: threadlight-govern + threadlight-governed-actions pre-deploy gate →
threadlight-deploy → selected-binding governance probe →
threadlight-safe-check (gate) → threadlight-consumption-iq (cost) →
CONNECT: threadlight-connect (mock→real tool swap — manual, evidence-gated) →
DISCOVER: threadlight-evals (offline + online CE) + threadlight-redteam (adversarial scan) +
threadlight-ground (ACL / citation / refusal grounding — manual) →
PROTECT: maintain selected runtime policy, bindings and fresh scoped evidence →
threadlight-deploy/references/observability →
threadlight-loadtest (budget-capped, production-confirmed load evidence — manual) →
threadlight-production-ready (advisory; verifies the legs ran) → customer architecture review →
threadlight-cicd (prod deploy pipeline, when the customer env is locked down) →
threadlight-customize (fork + onboard into the customer's own environment)
↻ IMPROVE / LIFECYCLE (offline / plan-only, after any CI run):
threadlight-router-bench — learnings digest (failure taxonomy + recommendations)
+ optional model-router cost/quality scorecard
threadlight-upgrade — plan-only compatibility / preview-drift lifecycle scan (no --apply)
```
The spine maps to the Microsoft Responsible-AI-for-Foundry operating loop —
**Design → Build/Deploy → Discover → Protect → Govern → Improve**. The
**Discover** legs (`threadlight-evals`, `threadlight-redteam`, and the
`threadlight-ground` grounding leg) and the **Protect** legs
(`threadlight-govern` for runtime governance policy, and
`threadlight-governed-actions` for consequential-action mediation, enforcement,
approval, and audit evidence) run *before* the readiness gate so that
`threadlight-production-ready` verifies each control-plane leg actually ran and
its artefact is fresh, rather than only scoring whether one was declared. The
loop's **Improve** phase is `threadlight-router-bench` — an offline leg that
turns a finished CI run into a grounded learnings digest (failure taxonomy +
recommendations) and, optionally, a model-router cost/quality scorecard, so each
pilot feeds the next.
`threadlight-qualify` sits *ahead* of the spine as the **no-repo entry**: it is
Cowork-safe qualification & sizing that runs before any repository exists and
seeds SPEC § 12 for `threadlight-design`. It is **not a deployed runtime skill**.
`threadlight-auto` is the **agent-guided lifecycle planner**. It reads the
latest evidence and chooses the next stage. `decide()` plans;
`execute(workspace, worker, ...)` delegates actual work to a caller-supplied
worker callback and rechecks selected gate evidence. A zero worker exit is not
gate proof; the planner is not the generated business agent.
Manual / live / cost-bearing / plan-only legs are explicit handoffs, not
auto-run steps: **`threadlight-connect`** (mock→real tool swap),
**`threadlight-ground`** (grounding evidence), **`threadlight-loadtest`**
(budget-capped load evidence), **`threadlight-cicd`** (pipeline handoff), and
**`threadlight-customize`** (customer onboarding) stay human-led. The offline
**`threadlight-router-bench`** improve leg and the plan-only
**`threadlight-upgrade`** lifecycle scan sit outside the pilot loop entirely.
The full technical briefing is in [`THREADLIGHT.md`](THREADLIGHT.md).
## Starting from a Kratos export
Threadlight skills also compose on a **Kratos-exported agent project**. An SE
can run the Kratos `Agent Manager → Deploy tab` export, `azd up` the bundle, then
layer in Threadlight production-hardening — no rewrite, additive to the
`threadlight-design` flow above.
```bash
unzip <use-case>-foundry-agent.zip && cd <use-case>-agent
azd auth login
azd up -e <use-case>-prod
```
Then invoke, in order: `threadlight-safe-check` → `threadlight-deploy`
(Kratos-export mode: enrich/validate + backfill `evals/`) → `microsoft-foundry` →
`threadlight-consumption-iq` → `threadlight-production-ready`, plus on-demand
`threadlight-hitl-patterns` / `threadlight-event-triggers` /
`threadlight-workspace-ui`. The canonical reference — detection signal,
skills-root convention, what's intentionally trimmed, and the full invocation
order — is in [`docs/KRATOS-BRIDGE.md`](docs/KRATOS-BRIDGE.md).
## Handing a design to the Agentic Loop
Threadlight and the GBB **Foundry Agentic Loop** are complementary: Threadlight
designs the business process and carries it to production evidence; the loop
builds it. After `threadlight-design`, one command exports the SPEC as a
self-contained brief for the loop's SDD mode (published plugin
`foundry-agentic-loop@awesome-copilot`), keeping every business rule, human gate
and evaluation scenario traceable:
```bash
python3 skills/threadlight-design/scripts/export_agentic_loop_spec.py specs/SPEC.md -o docs/threadlight-brief.md
```
Legacy `/spec2cloud` workspaces can still export `docs/spec.md` with
`--target spec2cloud`. The export is one-way and marks gaps as `[NEEDS CLARIFICATION: ...]`;
`specs/SPEC.md` stays the source of truth. Mapping, worked example and limits:
[`docs/AGENTIC-LOOP-BRIDGE.md`](docs/AGENTIC-LOOP-BRIDGE.md).
## Quickstart in GitHub Codespaces
Want to try the skills without installing anything? Open this repo in a
Codespace and you get **GitHub Copilot CLI with all 28 threadlight skills
pre-wired** from the checkout.
[](https://codespaces.new/aiappsgbb/threadlight-skills)
The [`.devcontainer`](.devcontainer/) installs Copilot CLI and registers the
skills automatically. Once it boots:
```bash
copilot # start Copilot CLI
/login # first launch only — sign in via device flow
```
Then just prompt, e.g. *"use threadlight-design to draft a SPEC from this
brief: …"*.
Prefer the released plugin over the local checkout? Swap in the marketplace
version any time:
```bash
copilot plugin marketplace add aiappsgbb/threadlight-skills
copilot plugin install threadlight-skills@threadlight-skills
```
### In a GitHub cloud sandbox
Just enabled **[cloud sandboxes](https://docs.github.com/en/copilot/how-tos/cloud-and-local-sandboxes)**
for your org? You can run the skills in a fully isolated, **ephemeral Linux box
hosted by GitHub** — nothing installed locally, and you can pick the session back
up from any machine:
```bash
copilot --cloud # launch an ephemeral cloud sandbox (public preview)
```
A cloud sandbox **does not read `.devcontainer/`**, so the auto-wiring above
doesn't apply — install the skills from the marketplace the same way you would
anywhere:
```bash
copilot plugin marketplace add aiappsgbb/threadlight-skills
copilot plugin install threadlight-skills@threadlight-skills
```
A few things to know:
- **Governance is inherited.** Each session runs under your org's existing
**Copilot cloud agent policies** — the firewall/allow-list your admins already
trust — with no extra setup. For the deploy and cost skills to reach Azure,
that policy needs to allow the hosts they call: `management.azure.com`,
`*.services.ai.azure.com`, `ai.azure.com`, `login.microsoftonline.com`,
`sts.windows.net`, `prices.azure.com`, `github.com`, `ghcr.io`,
`mcr.microsoft.com` and `learn.microsoft.com`.
- **No Azure deploy tooling.** Like the Codespace, a cloud sandbox has no
`az` / `azd` / `bicep` / Docker or subscription credentials preloaded, so the
deploy and production-hardening legs still need a full local or in-VNet box.
- **Preview + usage-billed.** Cloud sandboxes are in **public preview** and
billed by usage — stopping a session snapshots it; deleting it frees the
storage.
### Limitations
The Codespace is a **thin, consumer-focused** box for authoring and exploring
skills — not a full deploy environment:
- **Auth:** the first `copilot` launch needs `/login`. Codespaces injects a
repo-scoped `GITHUB_TOKEN` that lacks the *Copilot Requests* permission; if it
interferes with sign-in, run `unset GITHUB_TOKEN` in the terminal and retry
`/login`.
- **No Azure deploy tooling** (`azd`, `az`, `bicep`, Docker) — the deploy and
production-hardening legs (`threadlight-deploy`, `threadlight-safe-check`,
`threadlight-production-ready`, …) need a full local or in-VNet environment.
See [`threadlight-customize`](skills/threadlight-customize/) for private-env
testing patterns.
- Some MCP/agent tools (e.g. workiq) may not function in a Codespace.
> **Tip:** to let anyone clone this setup with **Use this template**, a repo
> admin can enable *Settings → Template repository*. That is independent of the
> devcontainer above — no code change required.
## Live experience
The [Threadlight experience page](https://aiappsgbb.github.io/threadlight-skills/)
showcases what the pipeline produces.
## License
[MIT](LICENSE)