Skip to content

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: repo

HELIX 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

HELIX overview: a team asks an agent runtime, which loads the HELIX skill. The catalog and project scope guide the skill as it authors project documents; those documents govern authorized execution.

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

Architecture field guide with responsibility lanes and a numbered developer walkthrough.

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

PartResponsibilityWhere to inspect
Routing skillResolve project scope, catalog, and workflow modeskills/helix/SKILL.md
MethodologyAuthority order, authoring rules, mode behaviorworkflows/modes/, workflows/artifact-schema.md
Artifact catalogDefine each document type through template, prompt, metadata, exampleworkflows/activities/*/artifacts/
Type graphDescribe catalog relationships; generated from metadataworkflows/graph.yml, scripts/generate_graph.py
Project documentsApply HELIX to HELIX itselfdocs/helix/
Delivery toolingValidate, package, and publish source contenttests/, 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.sh checks 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"
    }
  ]
}