Skip to content

ADR-017: Flows bind to a graph profile through an optional `profile:` key

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.

Source identity (from 02-design/adr/ADR-017-flow-profile-binding.md):

ddx:
  id: ADR-017
  authoring:
    home: repo
  status: accepted
  depends_on:
    - helix.prd

ADR-017: Flows bind to a graph profile through an optional profile: key

DateStatusDecidersRelatedConfidence
2026-11-06AcceptedHELIX maintainers.helix.yml, catalog resolution, SD-003Medium

Problem

HELIX must govern a technology-intelligence graph (Atlas) beside the software-delivery graph, in a different folder, without forcing either into the other’s artifact set or authority model. Today every flow resolves the same catalog and the same workflows/graph.yml; scripts/generate_graph.py is single-methodology and emits only informs edges.

Decision

Keep flows: in .helix.yml. Add an optional profile: per entry, default software-delivery. A profile is a catalog file (workflows/profiles/<id>.yml) that selects artifact types, allowed edge kinds, the authority model, and validation tiers. Artifact types stay reusable across profiles. No separate methodology engine, no graphs: rename, no helix_version bump.

Why we chose this

The skill already binds a graph per flow and enforces per-root scope, so a profile only narrows and parameterizes the catalog. An absent key preserves current behavior exactly, and the open schema lets older consumers ignore it.

Alternatives

OptionEvaluation
Rename flows to graphs, bump helix_version: 3Rejected: breaks every existing marker for vocabulary only.
Separate Atlas catalog and toolingRejected: competing framework; duplicates authoring, validation, voice.
Infer profile from folder conventionsRejected: implicit; violates “never silently pick”.

Consequences

TypeImpact
PositiveFully backward compatible; Atlas reuses authoring, validation, voice and present.
Negativegenerate_graph.py and validate-skills.sh need a per-profile mode.
NeutralAn unknown profile id is a malformed marker: stop and report, per existing rules.
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/adr/ADR-017-flow-profile-binding.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:05ec854b…829bf646

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/adr/ADR-017-flow-profile-binding/",
        "digest": {
          "alg": "sha256",
          "value": "05ec854bfc20b8f17d5a5d9750b6884fe2445912445d4bc2b70be4eb829bf646"
        }
      }
    ],
    "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": "EcVFtRdvGkMDtbH9D6WZLAqFx1zm_zqIQZ0qSyqxEXvpSsvV6G2MZyxMiXqxamvXVJeExaQalpNm1aAOYBKkAA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}