CI Integration — Documentation Strategy

CI Integration — Documentation Strategy

Why these docs exist, who they serve, and how they will eventually be consumed by an automated integration skill.

What we’re trying to achieve

Make WonderTwin twins trivially usable in any customer’s CI pipeline — regardless of platform — with the value (replay artifacts, deterministic seeding, real rate limits, run isolation) captured cleanly enough to drive license conversions.

The goal is not “ship a GitHub Action.” The goal is the customer integrates a twin in under 30 minutes on whatever CI they happen to use. Native marketplace integrations are convenience layers that may or may not be worth building later, downstream of measured demand.

Two-layer plan

These docs are layer 1.

Layer 1 — Docs (this directory)

Authoritative, copy-pasteable integration guides per CI platform. Customers self-serve. Power users prefer this regardless of automation availability — they want to read, customize, and own their integration.

Stable from the public CI v2 launch onward.

Layer 2 — twin-setup-ci skill (future)

A Crush / Claude Code skill that automates the integration end-to-end:

1. Detects the customer’s existing CI from filesystem signals (.github/workflows/, .circleci/config.yml, .gitlab-ci.yml, etc.).
2. Reads their existing test workflow.
3. Loads the matching template from this docs directory.
4. Adapts placeholders to the customer’s repo (twin name, secret name, test command).
5. Optionally opens a PR with the change.
6. Optionally watches the next CI run for the artifact.

Sits alongside /twin-evaluate, /twin-research, /twin-pipeline in wondertwin-docs/skills/. Ships as a fast-follow once telemetry validates which CI platforms warrant deep automation.

Why docs first, skill as fast-follow

1. Telemetry signal. Real customer attribution is now flowing (post Wave 1D). Building the skill before we know which CI platforms dominate would mean guessing priorities.
2. The skill consumes the docs. They’re the canonical templates regardless of the automation layer. We have to write them anyway.
3. Power users want docs forever. Some customers will never run the skill — they want full manual control. Docs serve them indefinitely.
4. Launch scope risk. A skill is meaningfully more complex than markdown. Adding it to the public CI v2 launch line risks delaying the launch.

Design principle: skill-ready structure

Every per-platform doc follows the same template so the future skill can programmatically extract the snippet:

# WonderTwin in <Platform>

> One-paragraph what & why.

## Snippet (copy-paste this into <file>)

```<lang>
# the actual snippet

Setup checklist

Variations

Troubleshooting

Reference

A machine-readable index — [`_templates.json`](_templates.json) — maps platform → snippet path → placeholder spec. The skill consumes that index. Docs and skill share one source of truth.

## Coverage policy

**Launch set (this directory):**
- [GitHub Actions](github-actions.md) — broadest market default
- [CircleCI](circleci.md) — startup + enterprise popularity
- [GitLab CI](gitlab-ci.md) — enterprise + self-hosted
- [Plain shell / Docker Compose](shell.md) — universal escape hatch for non-CI use, custom CI, local dev

**Follow-on candidates** (added when telemetry shows demand or community contributes):
- Buildkite
- Jenkins
- TeamCity
- Argo Workflows
- Tekton

Adding a platform is mechanical: copy the template, fill in the platform's native YAML/script syntax, register in `_templates.json`. Pull requests welcome from anyone who wants their CI platform first-class.

## Maintenance contract

- Each snippet is **smoke-tested** at least once before publication: a real workflow on a real CI runner producing a real replay artifact. Document the smoke result in the platform doc's footer.
- When `wt runs` adds new flags or changes existing behavior, every platform snippet is re-reviewed. The `last-reviewed` frontmatter field is the gating signal.
- Breaking changes to `wt` versions trigger a docs sweep. Versioned doc snapshots may eventually live in `wondertwin-docs/guides/ci/v<N>/`; today the docs target the latest `wt` version only.

## What the docs deliberately don't do

- **They don't ship a custom GitHub Action / CircleCI orb / GitLab Component.** Native marketplace integrations are convenience layers, not required capability. They wait for measured demand.
- **They don't try to teach CI fundamentals.** Customers are assumed to know their own CI platform. The docs only show the WonderTwin-specific glue.
- **They don't re-document the `wt runs` CLI.** That lives in the CLI reference (eventually). Per-platform docs link to it.

## Reading order for a new contributor

1. This file (strategy)
2. [`concepts.md`](concepts.md) — what `wt runs` does, glossary
3. [`index.md`](index.md) — platform picker
4. The platform doc you care about

## Non-goals

This strategy is about **integration mechanics**. It is not:
- A pricing or licensing strategy (see `gtm/`)
- A scope decision about which twins exist (see twin development docs)
- A roadmap for hosted twin infrastructure (see CI v2 PRD's Beat 3)