threadlight-customize

Files (12)

• SKILL.md
• customer-profile.md.tmpl · references/
• customization-map.md · references/
• field-notes-telco-pilot.md · references/
• fork-runbook.md · references/
• non-coverage.md · references/
• azure-ml-vscode.md · references/private-env-test/
• codespaces.md · references/private-env-test/
• private-vnet-checklist.md · references/private-env-test/
• test_no_secrets_in_templates.py · tests/
• test_structure.py · tests/
• test_version.py · tests/

SKILL.md (first lines)

# Threadlight Customize — fork the pipeline, onboard a real customer

> The final leg. It answers "**how do I take Threadlight and stand it up
> inside *this* customer — their landing zones, their RBAC, their pipelines,
> their governance — and actually test it on *their* environment?**" It does
> this with **instructions and fill-in runbooks, not automation.** Production
> onboarding is too high-variance to encode; this skill gives you the frame,
> the intake, and the customer-env test loop, then gets out of the way.

## Why this skill exists (and why it is not a generator)

Every other Threadlight skill is opinionated and deterministic because its
inputs are bounded (a SPEC section, a set of selectors, an `azd env`). The
**production onboarding of a specific customer is not bounded.** Their
landing-zone topology, identity model, allowed regions, private DNS, egress
rules, mandated IaC modules, change-management gates, and approval chains are
all theirs — and no two are the same. Trying to cover every permutation in
code produces a generator that is wrong for everyone.

So this skill is **prose + templates**. It captures what you must learn from
the customer, tells you which Threadlight skills to fork-and-override vs keep
as-is, and shows you how to run the dev/test loop **inside the customer's
boundary** (the part the field kept getting stuck on). What it deliberately
does **not** do is generate the onboarding for you. See
[`references/non-coverage.md`](references/non-coverage.md) — that honesty is a
feature.

## Where it sits in the pipeline

```
… → threadlight-production-ready (advisory gate) →
    threadlight-cicd (prod-deploy pipeline, locked-down env) →
    threadlight-customize  ◄── you are here (fork + customer onboarding)
```

It is a **manual handoff leg**, like `threadlight-cicd`. **`threadlight-auto`
does not drive it** — `auto` is a pilot driver, not a customer-onboarding
orchestrator. Run it when the pilot has proven out and the conversation turns
to "now make this live inside *our* environment." You can also start the
**intake gate (Move 1) early**, in parallel with the pilot, because the
intake is the long pole.

## Audience

Written for **two operators**, SE-led path first:

- **SE / GBB (primary).** You fork Threadlight, run the intake with the
  customer, customize the production-onboarding leg, and run the test loop
  inside their environment.
- **Customer platform / engineering team (secondary).** Everything here is
  also a self-serve runbook a customer team can follow to adopt Threadlight
  internally. Where the two paths differ, the step says so.

## The four moves

Run them in order. Each move produces one durable artifact under
`docs/threadlight-customize/` so the engagement is auditable and resumable.

### Move 1 — Intake gate (the long pole)

**You cannot customize what you have not been given.** The field's #1 blocker
was getting the customer inputs, not writing code. Open the engagement by
filling in the intake workbook **with** the customer:

- Copy [`references/customer-profile.md.tmpl`](references/customer-profile.md.tmpl)
  to `docs/threadlight-customize/customer-profile.md`.
- Work it top to bottom with the customer's cloud/platform owner. It has four
  blocks: **customer documents**, **environment setup**, **requirements**, and
  **mandated template/starter code**.
- Treat every unfilled field as a **blocker**, not a TODO. A blank
  "private DNS zones" or "allowed regions" line will stop the deploy later;
  surface it now.

The workbook is the single source of truth every later move reads. Do not
proceed to Move 2 until the **environment setup** and **mandated template
code** blocks are complete — those two drive every override decision.

### Move 2 — Customization map (what to fork vs keep)

Decide, per skill, what you change and what you leave alone. Read
[`references/customization-map.md`](references/customization-map.md): it
classifies every Threadlight skill as **customer-agnostic (keep as-is)** or
**needs per-customer override**, and names the exact SPEC section / selector /
`azd env` hook to change.

**Production-onboarding skills are priority #1** — they are where the
customer's environment actually bites:

| Skill | Typical customer override |
|---|---|
| `threadlight-deploy` | landing-zone targeting (sub/RG), resource selectors, region allow-list, private-endpoint + private-DNS wiring |
| `threadlight-safe-check` | customer resource selectors + naming standard the gate validates against |
| `threadlight-cicd` | pipeline shape, federated identity model, scoped RBAC, runner topology (this skill *generates* it; you feed it the customer's constraints) |
| `threadlight-production-ready` | pillar thresholds + `customer_overrides` to match the customer's policy baseline |

Capture the decisions in `docs/threadlight-customize/customization-map.md`
(copy the table from the reference and fill the right-hand column). Keep your
overrides in an **overlay**, not by editing forked skills in place — see the
fork runbook below — so you can still pull upstream Threadlight updates.

### Move 3 — Test it on the customer's environment

The pilot proves the agent works on an SE sandbox. Production onboarding only
proves out when you can run the loop **inside the customer's boundary** —
often a **fully-private (private-VNet) environment** with no public egress.
This is the move the field repeatedly got stuck on; two patterns work:

- **GitHub Codespaces** (private networking) —
  [`references/private-env-test/codespaces.md`](references/private-env-test/codespaces.md).
- **Azure ML compute instance + VS Code (Remote)** —
  [`references/private-env-test/azure-ml-vscode.md`](references/private-env-test/azure-ml-vscode.md).

Before you run the Threadlight `local-test` / `deploy` loop from inside the
boundary, work the pre-flight in
[`references/private-env-test/private-vnet-checklist.md`](references/private-env-test/private-vnet-checklist.md):
private DNS resolution, egress posture, and reachability of the Foundry,
ACR, Cosmos, and Key Vault **private endpoints**. A green pre-flight is the
gate to running deploy — a half-resolved private DNS zone fails the deploy in
a way that looks like an auth error and burns an afternoon.

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills