Skip to content

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).
  • Release version: vX.Y.Z.
  • 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

AreaCheckEvidence or CommandStatus
BuildSkill packaging tests are greenbash tests/validate-skills.sh[ ]
BuildWebsite builds clean (no Hugo errors, no broken shortcodes)cd website && hugo --gc --minify[ ]
BuildReference generator runs without stale-mapping errorsuv run scripts/generate-reference.py[ ]
BuildWorkflow-paths pre-commit check passeslefthook run pre-commit --all-files (or git diff --check)[ ]
ConfigNo tracked secrets in repo`git grep -nE ‘OPENROUTER_API_KEYANTHROPIC_API_KEY
ConfigPlugin manifest version matches the taggrep '"version"' .claude-plugin/plugin.json[ ]
DataNo tracker drift between live .ddx/beads.jsonl and any docs being shipped as examplesuv run scripts/generate-reference.py (validates HELIX_REAL_EXAMPLES paths)[ ]
Opsddx work --dry-run produces a coherent next-action summary against the release tagddx work --dry-run[ ]
OpsRelease notes draft exists and references the tagdocs/helix/05-deploy/release-notes.md[ ]
OpsDemos still record cleanlycd website && bash record-demos.sh (when demos changed in the release)[ ]

Rollout Plan

StageActionExit Condition
Local proofRun all pre-deploy checks against the release candidateAll checks above are checked
Tag and pushgit tag -a vX.Y.Z -m "..." then git push origin main vX.Y.ZTag visible on origin; CI starts
Plugin publicationPlugin is consumed by users via repo URL — no separate registry pushTag exists; git fetch --tags from a fresh clone resolves the manifest
Website rolloutGitHub Actions builds the site for the release tag and publishes to GitHub PagesPages workflow run succeeds; public URL serves the new content
Full rolloutSmoke-test the public site for the released artifact pagesCritical pages (/, /why/, /use/, /artifacts/<each>/) return 200

Verification Checks

Signal or CheckExpected ResultEvidence or CommandStatus
Public site root reachableHTTP 200curl -fsS -o /dev/null -w '%{http_code}' https://documentdrivendx.github.io/helix/[ ]
Released artifact pages renderHTTP 200 with expected H1curl -fsS https://documentdrivendx.github.io/helix/artifacts/contract/ | grep -q "DDx"[ ]
Plugin install from tag worksA fresh clone of the tag installs and ddx work --dry-run runsManual: clone tag, run ddx install helix --local . --force, then ddx work --dry-run[ ]
ddx work against a sample bead succeedsNEXT_ACTION is one of the documented valuesddx work --dry-run in a sample repo[ ]
No regressions in deterministic testsAll passbash tests/validate-skills.sh against the tag[ ]

Rollback Triggers

TriggerThreshold or ConditionImmediate ActionOwner
Public site fails to build under the new tagPages workflow run failsRe-run the workflow once; if still failing, roll back to the previous release tagOperator
Plugin install breaks for a fresh consumerddx install helix --local . --force exits non-zero on a clean checkoutRoll back to the previous release tag only if no downstream consumers have updated; otherwise issue a vX.Y.Z+1 patchOperator
Skill packaging tests regressed in CI on the tagtests/validate-skills.sh fails on the tag in CICorrect the issue in a follow-up tag; do not silently change a published releaseOperator
Critical artifact-reference page renders emptyA HELIX_REAL_EXAMPLES_PUBLISHABLE slug ships with a missing examplePatch release that flips the slug back off in scripts/generate-reference.pyOperator

Go or No-Go Decision

  • Decision: [Go / Hold / Roll Back]
  • Decision time: [ISO-8601 timestamp]
  • Notes: Capture deferred checks, exceptions, or known follow-up work here. Reference the release version and related artifact IDs.
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-11-16T15:52:45Z
Content digest
sha256:1996c04b…c0bff822

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-11-16T15:52:45Z",
    "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": "1996c04b70d6aba075e89ed355173096737dfdd1ad2d71952622b9bfc0bff822"
        }
      }
    ],
    "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": "8WJ_L9lCt8ftDFBF5Yu_2bqQn_TJwGOXBRnfbn-XFuy0DyL9gWOhO5QTgeuhNG6fwLSJU7sWUYkRfG0UXCkeBA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}