HELIX solution overview
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/solution-overview.md):
ddx:
id: helix.solution-overview
type: solution-overview
status: draft
authoring:
home: repoHELIX solution overview
Purpose and audience
HELIX gives software teams and their agents a shared set of documents and rules for keeping product intent, designs, tests, and implementation aligned. Start here to understand the system; use the developer guide to make a change. This is an explanatory view of the current repository. Architecture governs system structure; the product requirements govern product scope.
System map

Editable architecture field guide (HTML) · Editable SVG · Visual design and review

The presentation view preserves the six entities and relationships below. The shaded region identifies HELIX-owned portable content. Solid arrows describe actions/information; dashed arrows describe guidance/constraints. The catalog label summarizes templates, prompts, metadata, and mode contracts. Validation and packaging details are covered by the architecture walkthrough.
Semantic source
Question: how does a team’s request become a project document? Arrows describe information or actions; boxes are content or actors, not running services.
flowchart LR
Team[Software team] -->|asks through| Runtime[Agent runtime]
Runtime -->|loads| Skill[HELIX routing skill]
Marker[Project .helix.yml] -->|bounds scope for| Skill
Catalog[Templates, prompts, metadata, mode contracts] -->|guides| Skill
Skill -->|authors and reconciles| Docs[Project artifact instances]
Docs -->|govern authorized execution by| Runtime
The runtime provides model access, file operations, execution, and source control. HELIX supplies portable Markdown and YAML content plus one routing skill. A request to plan does not authorize implementation.
Parts and boundaries
| Part | Responsibility | Where to inspect |
|---|---|---|
| Routing skill | Resolve project scope, catalog, and workflow mode | skills/helix/SKILL.md |
| Methodology | Authority order, authoring rules, mode behavior | workflows/modes/, workflows/artifact-schema.md |
| Artifact catalog | Define each document type through template, prompt, metadata, example | workflows/activities/*/artifacts/ |
| Type graph | Describe catalog relationships; generated from metadata | workflows/graph.yml, scripts/generate_graph.py |
| Project documents | Apply HELIX to HELIX itself | docs/helix/ |
| Delivery tooling | Validate, package, and publish source content | tests/, scripts/, docs/website/, website/ |
The project marker declares active document roots. Catalog definitions under
workflows/ are maintained by contributors; ordinary adopting-project authoring
writes instances under the marker’s root. Runtime integration is governed by
CONTRACT-003.
Critical flows
- Author a document: resolve marker and catalog, choose a mode, read governing artifacts and type instructions, write within scope, validate, review. Follow the end-to-end walkthrough.
- Change the methodology: edit canonical content, regenerate derived graph and reference pages as applicable, run repository gates, review the diff. Follow the developer guide’s change recipes.
- Deliver to a runtime: package the same skill and catalog with generated
references.
tests/validate-plugin-package.shchecks source/package agreement. Installation instructions live in docs/install.
Vocabulary and reading path
An artifact type is a reusable document definition; an instance is a
project’s document made from it. A flow applies a methodology to a marker’s
bounded root. A mode is a workflow inside the single public helix skill.
A concern supplies cross-cutting practices such as module boundaries.
Read this overview → architecture walkthrough → developer guide for a first contribution. Consult Architecture for structural decisions, the catalog for document contracts, and installation guidance for host setup.
Maintenance
Contributors update this map when routing, packaging, catalog ownership, or artifact boundaries change. Review it alongside Architecture. Check every linked path and trace the critical flow after such changes; generated graph and reference pages remain derived outputs. This pilot has repository evidence, but has not yet been tested by an unfamiliar developer.
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/solution-overview.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:b875dfd3…8621dcb4
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/solution-overview/",
"digest": {
"alg": "sha256",
"value": "b875dfd3a631bf1bed98971be76cfcfecca12e35fa0166540c6a135f8621dcb4"
}
}
],
"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": "Zn5rWxMLRg9H4dlVq0BIoApPpUVZgGQJZX_696N3w1Mz8LW0rFQf-yHkYgnF6MQARWWFFWFSfHQBdf5nu2S0Cg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}