Skip to content

Product Requirements 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 01-frame/prd.md):

ddx:
  id: helix.prd
  authoring:
    home: repo
  review:
    self_hash: 48c38800e987ab54c72d79dcd9ceed6e20afbd197b87c05699c51b49f3cd1f41
    deps: {}
    reviewed_at: "2026-10-04T02:22:27Z"

Product Requirements Document

Summary

HELIX is a software development methodology and artifact catalog for AI-assisted teams. It ships portable content (templates for 53 artifact types, authoring prompts, methodology documentation) plus a single routing skill that operates HELIX workflow modes against a project’s governing artifacts. The primary user experience is invoking the helix skill through an agent runtime to frame, validate, align, evolve, review, polish, or present the project’s documents and produce the next document-driven plan or a human-facing deliverable.

HELIX does not provide a CLI, a tracker, an execution loop, or any runtime infrastructure. Those are runtime concerns. DDx is the reference runtime; Databricks Genie and Claude Code are target runtimes. HELIX is the discipline; the runtime is the engine.

Problem and Goals

Problem

AI-assisted software development is now the default practice, but the practice itself is unpracticed. Teams using AI agents to write production code see three failure modes:

  1. Artifact drift. Specifications, designs, and tests fall out of sync with code because no one walks the artifacts between work sessions.
  2. Inconsistent agent behavior. Without a shared methodology, agents make locally-good decisions that conflict with global intent — a feature gets built, but its design contradicts an earlier ADR; a refactor lands without updating the technical design that documented its predecessor.
  3. Lossy session boundaries. Each new conversation re-improvises the same workflow. Specs that should be written are not; reviews that should happen do not. Context evaporates.

Human teams developed disciplines for these problems decades ago: PRDs, design documents, test plans, alignment reviews. The agents that now write our code have not been given that discipline in a portable, tool-agnostic form.

Goals

  1. Catalog. Define a minimal, complete catalog of artifact types covering software development from intent through deployment to feedback. Each type carries a template, an authoring prompt, and quality criteria.
  2. Routing skill. Provide a single runtime-portable skill that routes HELIX-owned workflow modes against a project’s governing artifacts. Alignment is a required mode: it identifies drift, gaps, and contradictions, then produces a plan for closing them.
  3. Methodology spec. Specify the artifact authority hierarchy, the seven-activity control loop, the artifact-type schema, and the routing skill contract as a runtime-neutral document.
  4. Stay small. HELIX is content + one skill. Not a tool, not a platform, not a CLI. Resist scope creep into runtime territory.

Core Workflow Contract

HELIX supports a four-step user workflow. Homepage language may be simpler, but product behavior should preserve this contract:

  1. Write the brief. Users create or update governing artifacts that describe intent, requirements, constraints, and decisions.
  2. Check alignment. HELIX compares the artifacts affected by the request and identifies relevant drift, contradictions, stale assumptions, and missing context. A project-wide implementation audit is a separate, explicitly scoped request.
  3. Create the work plan. HELIX turns aligned artifacts into bounded implementation work with scope, non-scope, acceptance criteria, and evidence expectations.
  4. Run it in the factory. A runtime or software factory executes the work plan, measures the result, and returns evidence that can update the artifact graph.

DDx is the reference software factory because it provides the full operator loop: plan, execute, measure, and adapt through specs, beads, runs, evidence, metrics, and staleness. Other runtimes can implement the same handoff with their own execution surfaces.

Living-document behavior

Committed artifacts express current working intent without a separate document approval lifecycle. Agents prioritize material gaps that affect user outcomes, requirements, scope, safety, design choices, or completion evidence. Light drift, old lifecycle labels, missing review stamps, and incomplete graph edges do not by themselves block authorized work or justify separate housekeeping tasks. Resolve ordinary drift from higher authority within the requested task. Keep implementation progress in the relevant plan, selected work item, or factual report. Preserve explicit domain approvals and evidence for completion claims.

Success Metrics

These product goals inform learning and priorities. They do not gate implementation, version progression, release, or engineering completion.

MetricTargetMeasurement MethodTimeline
Runtime breadth3 documented runtime deployments (DDx, Databricks Genie, one other)Release audit12 months
Adoption50+ repos using HELIX templates as their artifact catalogGitHub search; community survey18 months
Alignment qualityHealthy artifact sets average < 3 findings per align mode runPeriodic sample across reference reposOngoing
Authoring qualityHELIX-template PRDs pass first-pass review at higher rates than free-form equivalentsComparative review study12 months
Skill portabilityZero runtime-specific commands in skill bodyAutomated check on every releaseOngoing

Non-Goals

  • HELIX will not provide a CLI, tracker, queue, or execution engine. The skill never requires a tool; the repository hosts one optional host tool, documentor (R-13), that adopters may run and need not install.
  • HELIX will not impose technology choices or fork by language ecosystem.
  • HELIX will not replace product, design, or architectural judgment.
  • HELIX will not hard-code one autonomy level: autonomy is a first-class, controllable spectrum (review-every-edit → full one-shot). HELIX expresses the autonomy policy; a capable runtime supplies the agency. (HELIX still ships no execution engine of its own — see above.)
  • HELIX will not flatten the seven-activity loop into one generic prompt.

Users and Scope

Primary Persona: HELIX Adopter

Role: Tech lead, staff engineer, or principal engineer guiding a team’s adoption of AI-assisted development. Goals: Establish a methodology that produces durably reviewable software output from agents. Reduce the cost of onboarding new team members or new agent runtimes. Pain Points: Inconsistent agent output across sessions; artifact drift; the cost of writing a methodology from scratch for each project.

Secondary Persona: AI Agent

Role: Any AI runtime (Claude Code, Genie, Cursor, etc.) executing work against a HELIX-governed artifact set. Goals: Have a defined set of artifacts to read, a defined set to produce, and a single skill to invoke for HELIX workflow modes, including alignment. Pain Points: Ambiguous context, drift between sessions, no standard for “is this work complete.”

Tertiary Persona: HELIX Maintainer

Role: Maintainer of the HELIX content catalog, the methodology spec, and the routing skill. Goals: Keep the catalog tight; keep the methodology coherent; ship portable improvements. Pain Points: Resisting feature creep into runtime territory; pruning legacy surfaces that crept across the boundary.

In Scope

  • Artifact-type catalog (templates, prompts, quality criteria, examples)
  • Methodology specification (artifact authority hierarchy, seven-activity loop, principles)
  • Single routing skill (route HELIX workflow modes; find drift; produce a plan)
  • Runtime-portable packaging of all of the above (per-runtime packages for DDx, Databricks Genie, Claude Code)
  • HELIX’s own self-application — its development artifacts in docs/helix/ are themselves authored from HELIX templates

Out of Scope

  • CLI, tracker, queue, execution loop, IDE integration
  • Runtime-specific tooling beyond minimal per-runtime packages
  • Domain-specific extensions (HELIX is general-purpose)

Requirements

Functional Requirements

P0

R-1: Artifact-type catalog. HELIX ships templates, prompts, and metadata for every activity in the seven-activity loop. Each artifact type carries a template (markdown skeleton), a prompt (authoring guidance), quality criteria, and an example.

R-2: Authority-hierarchy relationships. Every artifact type declares its position in the artifact authority hierarchy. Higher-level artifacts govern lower-level ones; conflicts resolve up.

R-3: Routing skill. A single skill, deployable to any runtime that can read and write markdown, routes a user’s intent to HELIX-owned workflow modes for a project artifact graph. The skill must support alignment as a core mode: given a requested change, it reads the relevant authorities and affected artifacts, then produces: (a) a human-readable report of relevant gaps, drift, and contradictions; (b) a plan describing the artifact updates needed to close them, ordered by authority. The user or a runtime may request structured output.

R-4: Runtime-neutral content. The catalog and skill body contain no references to specific runtime commands, file layouts, or runtimes beyond the minimal “read markdown, write markdown, search files” contract.

R-5: Methodology specification. A runtime-neutral specification document defines the artifact authority hierarchy, the seven-activity loop, the artifact-type schema, and the routing skill contract. New runtime consumers can implement HELIX compliantly from this spec alone.

R-6: Self-application. HELIX’s own development artifacts in docs/helix/ are authored from HELIX templates. The repo dogfoods its own catalog; inconsistencies in the dogfood are themselves alignment findings.

P1

R-7: Distribution packages for each target runtime. HELIX ships as a DDx plugin, a Databricks Genie skill, and a Claude Code skill. The source content is the same in every case; the package metadata around it differs per runtime. Packages are not forks.

R-8: Quality criteria as deterministic checks. Where artifact quality criteria are deterministic (regex patterns, section presence, word counts), they are expressed in a form that runtimes with prose-checker support (notably DDx via ddx doc prose) can enforce.

R-9: Per-artifact-type rule scoping. Quality criteria attach to artifact types; the align workflow mode applies type-scoped checks to instances based on ID prefix or path. Runtime-specific prose checkers may enforce those rules, but the rule source remains the artifact catalog.

R-12: Human-facing outputs. The present workflow mode projects governed artifacts into a deliverable (deck, one-pager, or brief): a governed Markdown script in the human-facing voice profile, with claim titles, a visual per unit, speaker notes, and a Sources appendix that traces every figure to a governing artifact section. The script must pass a deterministic gate (title and shape rules, horizontal logic, sourced numbers, no HELIX vocabulary in bodies, concept coverage) before it counts as done. Rendering to .pptx, PDF, or HTML is optional host tooling: a host without it stops after the script and names a host that can render. The skill body stays runtime-neutral (R-4).

R-13: Repository guide. The guide workflow mode projects governed artifacts and code into the pages a repository’s readers need: developers, operators, users, and data consumers, each page one Diátaxis kind with a reader task, an outline, and a budget, in the onboarding or public-site voice profile. Every page carries a provenance header naming its sources with digests; a deterministic check fails when a source moved, a generated page would differ, a page is missing or unreviewed, a link or path breaks, or a page matches a handling pattern. Detection, generated pages, architecture views, the check, and the site are optional host tooling: documentor, a package in this repository under tools/documentor/, outside the skill and never copied into an install. A host without it does each step by hand and says so. The skill body stays runtime-neutral (R-4).

R-14: UMF-based design and schema publication. For new or changed schemas, structured interfaces, and domain models, design workflows inspect UMF core, extensions and domain packs and reuse suitable definitions by default. A specific gap justifies an alternative. Exact shapes have one authoritative source; Contracts explain behavior and compatibility. Versioned local schema references are discoverable by the publishing pipeline, which renders them using the UMF schema browser with source provenance and definition links. Publication validates references and freshness; rendering does not establish semantic conformance. Narrative-only work requires no model or runtime dependency.

P2

R-10: Catalog versioning. Artifact-type changes are reviewable; consumers can pin to a known catalog version.

R-11: Onboarding deliverable. A guided first-project walkthrough usable without the creator present. The new-teammate review is a release criterion.

Acceptance Test Sketches

R-1 (catalog): Given a fresh repo with no HELIX content, when HELIX content is installed, then 7 activity directories exist under workflows/ activities/, each with at least one artifact-type directory; each artifact-type directory contains template.md, prompt.md, meta.yml, and an example.

R-3 (routing skill): Given a project with vision, PRD, feature specs, but no design artifacts, when the helix skill routes the request to its align workflow mode, then the output report identifies the design gap and the plan describes which solution designs to author, in what order, with traceability back to the affected features. Given a request that names another document workflow mode, the same skill routes to that mode without requiring a separate public skill.

R-4 (runtime-neutral): Given the routing skill source, when tests/validate-skills.sh greps the skill’s normative body for tracker vocabulary (bead), bench machinery (bench, grader, matcher), host invocation commands (claude -p, codex exec), host tool vocabulary (tool_use; Bash, Write, Edit outside code fences and the one host tool names: mapping sentence), plugin environment variables (CLAUDE_PLUGIN_ROOT, GROK_PLUGIN_ROOT), and verbatim-output doctrine, then zero hits. References are allowed only in per-runtime package metadata (the DDx-plugin manifest, the Genie skill descriptor, etc.) and install guides.

R-6 (self-application): Given the HELIX repo at a release tag, when align runs over docs/helix/ with a structured report, then it reports zero DIVERGENT findings, and instance validation passes every artifact in docs/helix/ with no blocking findings.

R-12 (human-facing outputs): Given a project with a vision and a PRD, when the present mode is asked for an evaluation deck, then a DEL-nnn script exists under the flow root, the deliverable gate reports zero blocking findings, every number in a body appears in Sources, and on a host without the render toolchain the run ends with the script and a statement of which host renders it.

R-13 (repository guide): Given a repository whose .helix.yml names an audience, when a section a page cites changes, then the check reports the page stale and exits non-zero, and passes after the page is regenerated and reviewed; on a host without documentor the pages are written with headers, unstamped sources carry sha256:-, and the handoff names the steps done by hand.

Technical Context

HELIX content is authored in Markdown with YAML frontmatter using the ddx: namespace (an open schema HELIX adopts; DDx happens to consume it). The routing skill is authored in Markdown with frontmatter compatible with mainstream agent skill formats (Claude Code-compatible). Artifact templates and prompts are plain Markdown.

HELIX ships per-runtime packages around the same source content:

  • DDx plugin — installed with ddx install helix; the catalog and skill show up under DDx’s plugin mechanism.
  • Databricks Genie skill — the content + skill bundled in Genie’s skill format.
  • Claude Code skill — the content + skill bundled as a Claude Code skill.

HELIX does not impose a programming language, framework, or toolchain on the projects that adopt it. The repo itself uses Markdown + YAML; each per-runtime package uses whatever metadata format its target requires.

Constraints, Assumptions, Dependencies

Constraints:

  • HELIX cannot assume any particular runtime is present at runtime. The skill must work given only “read file, write file, search files” as runtime primitives.
  • The skill body cannot reference runtime-specific commands.
  • The catalog cannot fork by language ecosystem.

Assumptions:

  • AI agents capable of executing the routing skill have file-read/write tools and a reasonable context window for governing artifacts (typically tens of files).
  • Packages can package markdown content for their runtime; the packaging mechanics vary but the source content is uniform.

Dependencies:

  • DDx (reference runtime). HELIX uses DDx for its own bead tracking and execution. This is HELIX-using-DDx, not HELIX-coupled-to-DDx — the relationship is the same one Databricks users would have with their own runtime.
  • Markdown/YAML toolchain. No specialized parser beyond standard YAML frontmatter.

Risks

RiskLikelihoodImpactMitigation
Methodology adoption is slow because “just write the code” is the durable defaultHighHighKeep HELIX minimal; the routing skill must produce value on the first run; ship a strong getting-started narrative
Runtime fragmentation makes package maintenance unsustainableMediumHighDefine minimal runtime contract early; small packages, not forks; treat runtime breadth as a release-quality metric
Align mode produces noisy or wrong findingsMediumHighThe routing skill’s alignment behavior is a primary development focus; quality criteria in templates are explicit and testable; ratchets on finding precision
Old HELIX work leaks runtime coupling into new contentMediumMediumKeep the product boundary explicit; automated check on each release for runtime refs in skill body
Documentation stalenessMediumMediumThe align workflow mode catches stale documents; HELIX dogfoods its own catalog
Transferability — HELIX cannot be taught without its creator presentMediumHighOnboarding doc is P1 deliverable; verify the documented installation and first-run path with a bounded onboarding scenario

Open Questions

  • Resolved 2026-09-15: does HELIX need tooling beyond the routing skill, and where does it live? HELIX ships small deterministic scripts beside the skill (instance validation, the deliverable gate, the corpus inventory, deck rendering and inspection) and a release-time portability check in the test suite. The skill body stays runtime-neutral and works with read, write, and search alone; the scripts are optional host tooling, and each mode that names one states what happens when it is absent (the model performs the check by hand, or the mode stops after the script and names a host that can render). Nothing moves into DDx.

Success Criteria

HELIX is successful when:

  1. A new team can adopt the methodology by reading the vision, the PRD, and the methodology spec, and installing the content catalog via a runtime package — without further guidance from a HELIX maintainer.
  2. The align workflow mode runs against a real project’s governing artifacts and produces a plan that a human can review and approve in under 10 minutes.
  3. At least three runtimes have working packages; teams can pick the one that fits their environment.
  4. HELIX’s own docs/helix/ is visibly authored from its own catalog — the dogfood is healthy by the align workflow mode’s own measure.
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/prd.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:66a61dad…d760d82c

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/prd/",
        "digest": {
          "alg": "sha256",
          "value": "66a61dad022996e9cd83625391c0646e2d588b0b71918c8e872df971d760d82c"
        }
      }
    ],
    "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": "ZNKA1WmqzoEpyShT_rCE0nedlptxr6-qeDza1vmVAjYF9dItG5GcFdS9KT_zQaPNLmh_34dOJ1SjfwN5yKf9BA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}