Deployment Checklist — HELIX Plugin and Website Release

Example from HELIX’s own docs. This generated page comes from docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.

Deployment Checklist — HELIX Plugin and Website Release

Release Scope

Service or component: HELIX plugin (.claude-plugin/, skills/, workflows/) and the public website (website/, deployed to GitHub Pages).
Version or commit: vX.Y.Z tag at the release commit SHA.
Deployment window: Operator-driven; HELIX releases ship when the release bead reaches Go on this checklist. There is no fixed schedule.
Release owner: HELIX maintainer cutting the tag.
Rollback owner: Same operator (single-operator release flow).

Pre-Deploy Checks

Area	Check	Evidence or Command	Status
Build	Skill packaging tests are green	`bash tests/validate-skills.sh`	[ ]
Build	Website builds clean (no Hugo errors, no broken shortcodes)	`cd website && hugo --gc --minify`	[ ]
Build	Reference generator runs without stale-mapping errors	`uv run scripts/generate-reference.py`	[ ]
Build	Workflow-paths pre-commit check passes	`lefthook run pre-commit --all-files` (or `git diff --check`)	[ ]
Config	No tracked secrets in repo	`git grep -nE ‘OPENROUTER_API_KEY	ANTHROPIC_API_KEY
Config	Plugin manifest version matches the tag	`grep '"version"' .claude-plugin/plugin.json`	[ ]
Data	No tracker drift between live `.ddx/beads.jsonl` and any docs being shipped as examples	`uv run scripts/generate-reference.py` (validates HELIX_REAL_EXAMPLES paths)	[ ]
Ops	`ddx work --dry-run` produces a coherent next-action summary against the release tag	`ddx work --dry-run`	[ ]
Ops	Release notes draft exists and references the tag	`docs/helix/05-deploy/release-notes.md`	[ ]
Ops	Demos still record cleanly	`cd website && bash record-demos.sh` (when demos changed in the release)	[ ]

Rollout Plan

Stage	Action	Exit Condition
Local proof	Run all pre-deploy checks against the release commit	All checks above are checked
Tag and push	`git tag -a vX.Y.Z -m "..."` then `git push origin main vX.Y.Z`	Tag visible on origin; CI starts
Plugin publication	Plugin is consumed by users via repo URL — no separate registry push	Tag exists; `git fetch --tags` from a fresh clone resolves the manifest
Website rollout	GitHub Actions builds the site from the tagged commit and publishes to GitHub Pages	Pages workflow run succeeds; public URL serves the new content
Full rollout	Smoke-test the public site for the released artifact pages	Critical pages (`/`, `/why/`, `/use/`, `/artifacts/<each>/`) return 200

Verification Checks

Signal or Check	Expected Result	Evidence or Command	Status
Public site root reachable	HTTP 200	`curl -fsS -o /dev/null -w '%{http_code}' https://documentdrivendx.github.io/helix/`	[ ]
Released artifact pages render	HTTP 200 with expected H1	`curl -fsS https://documentdrivendx.github.io/helix/artifacts/contract/ \| grep -q "DDx"`	[ ]
Plugin install from tag works	A fresh clone of the tag installs and `ddx work --dry-run` runs	Manual: clone tag, run `ddx install helix --local . --force`, then `ddx work --dry-run`	[ ]
`ddx work` against a sample bead succeeds	`NEXT_ACTION` is one of the documented values	`ddx work --dry-run` in a sample repo	[ ]
No regressions in deterministic tests	All pass	`bash tests/validate-skills.sh` against the tag	[ ]

Rollback Triggers

Trigger	Threshold or Condition	Immediate Action	Owner
Public site fails to build under the new tag	Pages workflow run fails	Re-run the workflow once; if still failing, revert the tag commit and re-tag	Operator
Plugin install breaks for a fresh consumer	`ddx install helix --local . --force` exits non-zero on a clean checkout	Move the `vX.Y.Z` tag back one commit (`git tag -d` + force-push) only if no downstream consumers have pulled; otherwise issue a `vX.Y.Z+1` patch	Operator
Skill packaging tests regressed in CI on the tag	`tests/validate-skills.sh` fails on the tag in CI	Revert the offending change in a follow-up tag; do not silently amend the released tag	Operator
Critical artifact-reference page renders empty	A `HELIX_REAL_EXAMPLES_PUBLISHABLE` slug ships with a missing example	Patch release that flips the slug back off in `scripts/generate-reference.py`	Operator

Go or No-Go Decision

Decision: [Go / Hold / Roll Back]
Decision time: [ISO-8601 timestamp]
Notes: Capture any deferred checks, exceptions, or known follow-up beads here. Reference the release-notes commit and the tag SHA so the decision is reconstructable from the tracker.

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: artifacts/deployment-checklist.md
Signed: 2026-09-23T14:11:58Z
Content digest: sha256:90da1d29…2c32c163

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-09-23T14:11:58Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifacts/deployment-checklist/",
        "digest": {
          "alg": "sha256",
          "value": "90da1d29c41bee794da71f09356269cd9af05b4993d8a60c9c421aa42c32c163"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "c0hiBJ7JIVOCTlQRo6zHbxMtqaSRIy7YplQ-iwVFy7xHTpkSePl4LQsuXDVPiXm3mXljz8TMrpIL5hhYKX2rBw",
      "signed_at": "2026-09-23T14:11:58Z"
    }
  ]
}

attestation file · issuer keys