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: repoArchitecture 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
| Step | Source to inspect | State or output | Verification |
|---|---|---|---|
| Resolve scope | skills/helix/SKILL.md, Activation Discipline; .helix.yml | Authorized flow and root | tests/validate-plugin-catalog-resolution.sh checks catalog availability, not live routing |
| Bind catalog | Skill, Catalog Resolution; workflows/graph.yml | One catalog source supplies graph and type files | tests/validate-plugin-package.sh checks packaged source agreement |
| Choose behavior | workflows/modes/design.md, workflows/modes/_authoring.md | Design instructions and authority boundary | tests/validate-actions.sh checks action registration and shape |
| Gather design context | workflows/activities/02-design/artifacts/solution-design/prompt.md and adjacent files | Requirements, alternatives, component decomposition | Human review checks that claims match governing evidence |
| Write instance | Type meta.yml output convention and template.md | docs/helix/02-design/solution-designs/SD-…md with ddx.id | skills/helix/scripts/validate-instance.py checks supported metadata rules |
| Review result | Type quality checks and governing artifacts | Reviewed design or explicit unresolved gaps | tests/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"
}
]
}