Project Principles
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
01-frame/principles.md):
ddx:
id: helix.principles
authoring:
home: repo
depends_on:
- helix.prd
- helix.product-vision
review:
self_hash: 93cd1656916b185cc307151361be40ab1a077117ba5d1e2756ae24fecb1959bb
deps:
helix.prd: 48c38800e987ab54c72d79dcd9ceed6e20afbd197b87c05699c51b49f3cd1f41
helix.product-vision: 1f1e960bc87b10da772f5a37b3947d9908a56820cc84ff786c5258c2c664173d
reviewed_at: "2026-10-04T02:22:27Z"Project Principles
These principles guide choices about HELIX. Workflow contracts define required steps; principles do not add steps or gates.
Principles
- Authority resolves conflicts. Follow the artifact authority hierarchy; implementation does not silently override an accepted specification.
- Specifications describe desired state. Record requirements and consequential decisions in their governing artifacts. Record implementation status in the runtime’s work tracker or a factual report.
- Scope the work. Read the requested target and relevant authorities. A system/component alignment includes affected implementation and tests; document-only alignment stays within its artifacts. A comprehensive audit requires explicit selection. Keep each within the named scope.
- Work flows in every direction. Execution feedback revises plans and enables simplification as responsibilities become clear. Consolidate overlapping mechanisms and retire unnecessary work in specifications, implementation and tests while preserving required behavior and evidence. Activity names locate the kind of work, not its position in a sequence.
- Decisions guide implementation. An accepted decision sets direction; it does not claim that the system implements that direction.
- People decide; agents draft and check. People own intent and material decisions. Agents draft, compare, and surface questions at the governed hand-offs.
- HELIX stays small. HELIX defines methodology and ships one routing skill. Execution and tracking belong to the runtime.
- Prefer useful evidence to ceremony. Keep checks that find real defects. Do not add gates, reports, or checklist sections only for completeness.
- Discipline over improvisation. Agents improvise well; HELIX makes that improvisation reviewable.
Living documents
Committed documents express current working intent. Expect light drift; use higher authority to reconcile relevant gaps during authorized work. A material gap affects user outcomes, scope, requirements, design, safety, or completion evidence. Lifecycle labels, stale review stamps, and missing edges alone never block work or justify housekeeping tasks. Keep progress in the relevant plan, selected work item, or factual report. Explicit domain decisions still apply.
Authority
The vision governs the PRD, the PRD governs features, and features govern
designs and decisions. The catalog and workflow contracts define how those
artifacts are authored and related. See workflows/principles.md for the
methodology statement.
Tension Resolution
| Tension | Resolution |
|---|---|
| Methodology depth vs. simplicity | Keep detail where readers need it; remove repeated process guidance. |
| Runtime convenience vs. HELIX scope | Put execution conveniences in the runtime adapter. |
| Validation vs. machinery | Keep evidence checks that protect quality; omit ceremony without a concrete failure to prevent. |
| Desired state vs. implementation status | Keep requirements authoritative; report observed status separately. |
Size Guidance
Keep this file short. Put workflow requirements in workflows/ and detailed
rationale in the relevant decision record.
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/principles.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:ee3ab4de…11066794
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/principles/",
"digest": {
"alg": "sha256",
"value": "ee3ab4def007b9b6ba2a62295fe9543a18a1b5b90d760e4bc6a675ce11066794"
}
}
],
"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": "QC0Foq7qZn8C6juMozRSTdB3XpfCELNdIKtq9Ndo1Y8i_mfAPqRpF-pQypo0dBYbpr_PTfYKnlS6KccYrxlaCg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}