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.prdADR-017: Flows bind to a graph profile through an optional profile: key
| Date | Status | Deciders | Related | Confidence |
|---|---|---|---|---|
| 2026-11-06 | Accepted | HELIX maintainers | .helix.yml, catalog resolution, SD-003 | Medium |
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
| Option | Evaluation |
|---|---|
Rename flows to graphs, bump helix_version: 3 | Rejected: breaks every existing marker for vocabulary only. |
| Separate Atlas catalog and tooling | Rejected: competing framework; duplicates authoring, validation, voice. |
| Infer profile from folder conventions | Rejected: implicit; violates “never silently pick”. |
Consequences
| Type | Impact |
|---|---|
| Positive | Fully backward compatible; Atlas reuses authoring, validation, voice and present. |
| Negative | generate_graph.py and validate-skills.sh need a per-profile mode. |
| Neutral | An 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"
}
]
}