Source identity (from 02-design/architecture.md):

ddx:
  id: helix.architecture
  depends_on:
    - helix.prd
    - CONTRACT-003
  status: active

Architecture

HELIX is a methodology and artifact catalog for AI-assisted software teams. It ships portable content and a single routing skill. Architecturally it is three things:

1. An artifact catalog in workflows/ — templates, prompts, metadata, and examples for every artifact type across the seven HELIX activities.
2. A routing skill in skills/helix/SKILL.md — the single agent-facing surface that reads and writes the catalog’s artifact instances.
3. A methodology specification in workflows/ — authority order, activity conventions, artifact-type schema, principles, and the alignment skill contract, expressed in runtime-neutral terms.

HELIX does not provide a CLI, tracker, queue, or execution loop. Those are runtime concerns. The boundary between HELIX portable content and any specific runtime is defined in CONTRACT-003.

Level 1: System Context

    graph TB
    team["Software team<br/>(engineer, PM, tech lead)"]
    skill["HELIX routing skill<br/>skills/helix/SKILL.md"]
    catalog["Artifact catalog<br/>workflows/activities/…"]
    artifacts["Project artifact graph<br/>docs/&lt;project&gt;/helix/"]
    runtime["Runtime<br/>(DDx / Claude Code / Genie / …)"]

    team -->|"invokes skill via agent"| runtime
    runtime -->|"loads and runs"| skill
    skill -->|"reads artifact types from"| catalog
    skill -->|"reads/writes instances in"| artifacts
    runtime -->|"executes work derived from"| artifacts
  

The team never invokes a HELIX command, because there is not one. They invoke their agent runtime, and the runtime invokes the HELIX routing skill.

Level 2: Container Diagram

    graph TB
    subgraph helix["HELIX (this system)"]
        skill["skills/helix/SKILL.md<br/>Routing skill"]
        catalog["workflows/activities/…<br/>Artifact catalog<br/>templates · prompts · meta.yml"]
        schema["workflows/artifact-schema.md<br/>Instance schema"]
        wfdocs["workflows/<br/>Methodology spec<br/>principles · concerns · activities"]
    end

    subgraph project["Project (dogfood or adopter)"]
        instances["docs/helix/<br/>Artifact instances<br/>activity-numbered layout"]
    end

    subgraph runtime["Any compliant runtime"]
        engine["Execution engine<br/>tracker · queue · loop · evidence"]
        packages["Per-runtime packages<br/>DDx plugin · Claude Code skill · Genie skill"]
    end

    skill -->|"reads artifact types"| catalog
    skill -->|"reads/writes"| instances
    catalog -->|"instances conform to"| schema
    packages -->|"wraps same source"| skill
    packages -->|"wraps same source"| catalog
    engine -->|"loads skill into agent session"| skill
    engine -->|"installs per runtime contract"| packages
  

Artifact Catalog

The artifact catalog is HELIX’s primary structural element. It defines every artifact type a HELIX-governed project may produce, organized by the seven HELIX activities:

Each artifact type in the catalog provides four files:

The full meta.yml schema — required fields, recommended fields, validation entries, id-format, dependency declarations, and extension sections — is specified in workflows/artifact-schema.md.

Authority order

Every artifact type declares its position in the authority order. Higher-level artifacts govern lower-level ones; conflicts resolve upward:

product vision
  └─ PRD
       └─ feature specs / user stories
            └─ architecture · ADRs
                 └─ solution designs · technical designs
                      └─ test plans
                           └─ implementation plans · code

The routing skill’s evolve mode threads changes downward through this order; align mode audits consistency across it. Authority order is a HELIX invariant — no runtime changes it.

Artifact instance frontmatter

Project artifact instances carry YAML frontmatter under the ddx: key. The namespace is historical (DDx is the reference consumer); it does not mean artifacts require DDx. Minimal instance frontmatter:

---
ddx:
  id: FEAT-001
  type: feature-spec
  depends_on:
    - helix.prd
  status: draft
---

ddx.id is the only required field. ddx.depends_on builds the traceability graph the routing skill traverses. Full field definitions are in workflows/artifact-schema.md.

Routing Skill

skills/helix/SKILL.md is the single agent-facing surface. Any runtime that loads the skill exposes the same capability set.

What the skill reads and writes

The skill never writes to a tracker, queue, or evidence store. Those are runtime responsibilities.

Routing modes

Skill composability

The routing skill reads the artifact catalog at runtime; it does not bundle catalog content inside the skill body. This means:

• Any runtime that installs the HELIX package exposes the same routing modes.
• Catalog updates (new artifact types, revised templates) take effect without changing the skill body.
• The skill body contains zero runtime-specific commands (PRD R-4). Per-runtime packaging notes live in docs/install/<runtime>.md.

The skill’s normative behavior is self-contained. Runtimes may surface additional affordances (bead authoring, execute-loop delegation, prose checking) through their own packaging layers; those extensions live in per-runtime packaging, not in the skill body.

Artifact Schema as Runtime Contract

workflows/artifact-schema.md is the contract that lets any compliant runtime register and consume HELIX artifact types. A runtime claiming HELIX compatibility must:

1. Read meta.yml for artifact-type metadata.
2. Resolve ddx.id and ddx.depends_on in instance frontmatter for graph traversal.
3. Treat workflows/artifact-schema.md as the schema authority — not its own internal documentation.
4. Preserve unknown fields rather than stripping them.

The schema is intentionally open. Runtimes may add extension fields under ddx: for operational state, but those fields must be ignorable by other runtimes without changing artifact meaning.

Minimum runtime primitives required to run the alignment skill:

1. Read markdown files from the project filesystem.
2. Write markdown files to the project filesystem.
3. Search files by path or pattern.

Shell execution (item 4) is optional. A runtime satisfying only items 1–3 can run every HELIX routing mode that does not involve direct code execution.

Packaging

HELIX ships as three distribution packages around the same source content (PRD R-7). The source in workflows/ and skills/helix/ is never forked.

Per-runtime packaging notes — install paths, invocation details, DDx-specific bead conventions, Genie-specific descriptor fields — live in docs/install/. None of that detail appears in the routing skill body or the artifact catalog.

The adapter boundary between HELIX portable content and DDx-specific surfaces is specified in CONTRACT-003. DDx is one reference runtime, not the architecture center.

Documentation Projection

HELIX maintains two complementary documentation trees:

workflows/ is what adopters install; docs/helix/ demonstrates the methodology applied to HELIX’s own development. The Hugo microsite (when generated) is a read-only projection of both trees, not a source of truth.

Methodology invariants — principles, ratchets, activity contracts — are maintained in workflows/principles.md and workflows/ratchets.md. Before relying on either for design decisions, verify the current state in the file; both are in active flux.

DDx as One Reference Runtime

DDx is the reference runtime for HELIX’s own development. HELIX uses DDx for bead tracking, execute-loop dispatch, and execution evidence on its own work items. This is HELIX-using-DDx, not HELIX-coupled-to-DDx — the same relationship any adopter has with their chosen runtime.

The DDx adapter boundary is defined in CONTRACT-003. In brief:

• HELIX provides to DDx: artifact catalog, routing skill, artifact-type schema.
• DDx provides to HELIX (as runtime): bead tracker, execute-loop, evidence store, plugin packaging, prose checker.
• Neither side owns the other’s internals.

CONTRACT-003 also catalogs known boundary leaks — places in the current codebase where runtime-specific language has crept into HELIX portable content — and describes the resolution for each.

Quality Attributes

References

• Product Vision
• PRD — especially R-4 (runtime-neutral), R-5 (methodology spec), R-7 (packaging)
• CONTRACT-003: DDx Adapter Boundary — the boundary between HELIX and DDx
• Artifact Schema — normative schema for meta.yml and ddx: frontmatter
• Routing Skill — the single agent-facing surface
• workflows/principles.md
• workflows/ratchets.md