Skip to content

Architecture walkthrough: authoring a project document

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/architecture-walkthrough.md):

ddx:
  id: helix.architecture-walkthrough
  status: draft
  authoring:
    home: repo

Architecture walkthrough: authoring a project document

Scenario and scope

A developer asks their agent to create a solution design for an existing feature. The observable result is a project document whose scope, governing references, and sections can be reviewed. This walkthrough explains the current content contracts; it is not a transcript or proof of a live model session. Architecture remains the structural authority.

Sequence

Question: which inputs constrain the agent before it writes a document? Participants are a person, a runtime, and repository content. Calls to content mean file reads or writes performed by the agent through the runtime.

    sequenceDiagram
    actor Developer
    participant Runtime as Agent runtime
    participant Skill as HELIX skill contract
    participant Project as Marker and governing artifacts
    participant Catalog as Mode and artifact type
    Developer->>Runtime: Create a solution design for an existing feature
    Runtime->>Skill: Load routing and activation instructions
    Skill->>Project: Resolve .helix.yml and active root
    Skill->>Catalog: Bind graph and select design mode
    Catalog->>Project: Read feature, architecture, decisions, contracts
    Catalog->>Catalog: Read authoring rules and type files
    Catalog->>Project: Write solution design within active root
    Runtime->>Catalog: Run instance validation against metadata
    Runtime-->>Developer: Return document, evidence, unresolved questions
  

Steps and evidence

StepSource to inspectState or outputVerification
Resolve scopeskills/helix/SKILL.md, Activation Discipline; .helix.ymlAuthorized flow and roottests/validate-plugin-catalog-resolution.sh checks catalog availability, not live routing
Bind catalogSkill, Catalog Resolution; workflows/graph.ymlOne catalog source supplies graph and type filestests/validate-plugin-package.sh checks packaged source agreement
Choose behaviorworkflows/modes/design.md, workflows/modes/_authoring.mdDesign instructions and authority boundarytests/validate-actions.sh checks action registration and shape
Gather design contextworkflows/activities/02-design/artifacts/solution-design/prompt.md and adjacent filesRequirements, alternatives, component decompositionHuman review checks that claims match governing evidence
Write instanceType meta.yml output convention and template.mddocs/helix/02-design/solution-designs/SD-…md with ddx.idskills/helix/scripts/validate-instance.py checks supported metadata rules
Review resultType quality checks and governing artifactsReviewed design or explicit unresolved gapstests/validate-instance.sh exercises validator behavior; review establishes semantic fit

The ddx: YAML namespace carries document identity; it does not require a tracker. The runtime performs file operations and invokes available validation. The skill and catalog supply instructions, not executable service calls.

Failure paths

  • A malformed marker stops authoring. Multiple unresolved active scopes require a scope choice before a write.
  • A broken catalog pointer warns and falls through the skill’s ordered catalog sources. Failure to bind any source stops authoring.
  • Missing required authority or contradictory governing artifacts must be surfaced; a plausible invented requirement cannot substitute for evidence.
  • Validation errors return the document for correction. Passing structural checks does not establish design correctness or approval.
  • A checked-out externally authored governing artifact is undependable; follow its origin and checkout rules before relying on its content.

Safe change points

To improve the decomposition instructions, edit the Solution Design type’s prompt/template/example together. Change routing only in the public skill and its mode contracts. Change validation mechanics in the packaged validator and its tests. Regenerate the graph after changing metadata relationships. Use the developer guide for commands and gates.

Maintenance

Review this walkthrough when activation, catalog binding, design mode, instance validation, or authoring-home rules change. Trace every row to its named source. A future unfamiliar-developer session should check whether readers can locate the write surface and explain a failure path without assistance.

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/architecture-walkthrough.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:375a7882…d6222575

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/architecture-walkthrough/",
        "digest": {
          "alg": "sha256",
          "value": "375a78828c25e559690579fe04e63d20bcf09be5cc09666e38f15b44d6222575"
        }
      }
    ],
    "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": "GCvXtsF22pqYFDO28MN9ePhhvaDfXulsa7qMYLTInR7Ngaq-CNQ9SWvmMQxCLnf_zITmTFzo3FyjQ-eyNOk3Dg",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}