Source identity (from 01-frame/features/FEAT-003-principles.md):

ddx:
  id: FEAT-003
  depends_on:
    - helix.prd

Feature Specification: FEAT-003 - First-Class Principles

Feature ID: FEAT-003 Status: Draft Priority: P1 Owner: HELIX maintainers

Overview

Principles are cross-cutting design concerns that guide decision-making across all HELIX activities. They are not workflow rules or process enforcement — they are lenses applied when choosing between two valid options.

Today, principles exist as a gate artifact: produce the document, check the box, move on. Nothing downstream reads them. The six “principles” in workflows/principles.md are actually workflow rules (test-first, spec completeness) that belong in enforcers and ratchets.

This feature makes principles a live, injectable artifact that shapes every downstream judgment — from architecture decisions to implementation trade-offs to review criteria.

Problem Statement

• Current situation: workflows/principles.md contains workflow rules mislabeled as principles. The per-project artifact scaffolding exists (meta.yml, template.md, prompt.md) but no project has ever generated a concrete principles document. No skill or action prompt reads principles.
• Pain points: Agents make judgment calls (design trade-offs, abstraction boundaries, error handling strategies) without reference to what the project values. Each skill re-derives its own implicit principles from context, producing inconsistent guidance across activities.
• Desired outcome: A small, project-owned set of design principles that HELIX injects into every skill and action that makes judgment calls. Agents apply the same values whether they are framing requirements, designing architecture, implementing code, or reviewing work.

Design

Two-layer model

Layer 1 — HELIX defaults (workflows/principles.md): A small set (~5) of non-controversial design principles that consistently produce good results. These are not methodology opinions — they are things virtually every well-run project agrees on.

Example defaults (illustrative, not final):

1. Design for change — Prefer structures that are easy to modify over structures that are easy to describe today.
2. Design for simplicity — Start with the minimal viable approach. Additional complexity requires justification.
3. Validate your work — Every change should be verified through the most appropriate means available (tests, type checks, manual verification).
4. Make intent explicit — Code, configuration, and documentation should make the why visible, not just the what.
5. Prefer reversible decisions — When uncertain, choose the option that is easiest to undo or change later.

Layer 2 — Project principles (docs/helix/01-frame/principles.md): The project’s own principles. Users can add, modify, reorder, or remove any principle, including HELIX defaults. The only constraint: principles cannot negate HELIX mechanics (artifact hierarchy, activity gates, tracker semantics).

Bootstrap and precedence

1. If docs/helix/01-frame/principles.md exists, it is the active principles document. HELIX defaults are ignored entirely.
2. If it does not exist, HELIX defaults from workflows/principles.md are used as the active principles.
3. On first helix frame (or when the user explicitly asks to initialize principles), HELIX copies the defaults into the project location and invites the user to customize. From that point, the project owns the file.
4. The bootstrap prompt should ask the user what their project values, what trade-offs they lean toward, and what past mistakes they want to avoid — then synthesize project-specific principles alongside the defaults.

Downstream injection

Every skill and action prompt that makes a judgment call must load the active principles and include them as context. Specifically:

The injection mechanism is selective: each skill includes the principles most relevant to its judgment domain, not a full dump of the document. The right injection strategy is an open research question — what phrasing, selection, and positioning in the prompt actually changes agent behavior?

Prompt engineering research (tracked separately) will use DDx agent execution, logging, and metrics to measure whether principles injection produces measurably better alignment with stated project values. This research should iterate on:

• Which principles matter for which skill types
• Whether full-document vs. selected-subset injection performs better
• Where in the prompt principles have the most effect (preamble, inline, closing constraint)
• Whether principles need rephrasing per skill context or work verbatim

Until research produces evidence, the initial implementation uses a simple preamble with the full principles document:

## Active Principles
{contents of the active principles document}

Apply these principles when making judgment calls in this task.
When two options are both valid, prefer the one that better aligns
with the principles above.

This is the baseline to measure against, not the final design.

Principle management

A principle management capability (within helix frame or as a dedicated sub-action) handles:

1. Add a principle — user states a new principle; the system checks for conflicts with existing principles and either adds it cleanly or flags the tension.
2. Tension detection — when principles pull in opposite directions (e.g., “design for simplicity” vs. “design for extensibility”), the system requires a resolution strategy documented in the principles file. This could be a priority ordering, a scoping rule (“simplicity wins for internal tools, extensibility wins for public APIs”), or an explicit acknowledgment of the tension with guidance.
3. Review principles — triggered when the principles document changes (tracked via the DDx document graph). The DDx document graph should track principles.md as a dependency of downstream artifacts; when principles change, dependents are marked stale for re-review. If the DDx document graph lacks features needed for this dependency tracking, open beads on the DDx repo to evolve the capability there.
4. Remove / modify — straightforward editing with a coherence check afterward.

Relationship with helix evolve

helix evolve threads changes through the artifact stack. When evolving, it must:

• Read and respect the active principles — use them as guidance when deciding how to thread the change.
• Never modify the principles document as a side effect. Principles are upstream authority; evolve operates downstream of them.
• If an evolve operation reveals that a principle is now misaligned with project direction, evolve should flag this for the user rather than silently editing the principles file.

Tension resolution format

When principles can conflict, the principles document should include a resolution section:

## Tension Resolution

- **Simplicity vs. Extensibility**: For internal components, prefer
  simplicity. For public interfaces, prefer extensibility. When unclear,
  prefer simplicity and refactor when the extension point proves necessary.

This section is not required when no tensions exist, but the management skill should proactively identify tensions and prompt the user to resolve them.

Requirements

Functional Requirements

1. HELIX must ship a small set of default design principles in workflows/principles.md that are genuine design guidance, not workflow rules.
2. The current workflow rules in workflows/principles.md must be relocated to the appropriate enforcers and ratchets.
3. When no project principles exist, HELIX must use the defaults as the active principles for all downstream injection.
4. helix frame must bootstrap project principles from HELIX defaults when no project principles file exists, prompting the user to customize.
5. Once project principles exist, they take full precedence over HELIX defaults.
6. Every HELIX skill and action that makes judgment calls must load and apply the active principles.
7. The principles artifact scaffolding (meta.yml, template.md, prompt.md) must be updated to reflect the new design.
8. Principle management must detect and flag tensions between principles.
9. The principles document must include a tension resolution section when conflicting principles exist.

Non-Functional Requirements

• Consistency: The same principles must be applied across all activities — no skill should derive its own implicit principles.
• Maintainability: Adding a new skill to HELIX should make it obvious that principles injection is expected.
• Simplicity: The injection mechanism should be simple enough that it does not become a maintenance burden itself.

User Stories

US-001: Bootstrap project principles [FEAT-003]

As a HELIX operator starting a new project I want HELIX to initialize a principles document from sensible defaults So that I have a starting point that I can customize for my project

Acceptance Criteria:

• Given no docs/helix/01-frame/principles.md, when helix frame runs, then HELIX creates the file from defaults and prompts for customization.
• Given the bootstrap runs, when it completes, then the resulting document includes both HELIX defaults and any user-specified principles.
• Given the user removes a HELIX default during bootstrap, then it stays removed — HELIX does not re-add it.

US-002: Principles guide downstream work [FEAT-003]

As a HELIX operator I want my project’s principles to be applied when HELIX generates designs, implementations, and reviews So that the work reflects my project’s values consistently

Acceptance Criteria:

• Given active principles exist, when any judgment-making skill runs, then the skill prompt includes the active principles as context.
• Given a principle like “design for simplicity”, when helix design generates an architecture, then it demonstrably favors simpler options.
• Given a principle like “validate your work”, when helix review runs, then it checks whether the implementation includes appropriate validation.

US-003: Manage principles coherently [FEAT-003]

As a HELIX operator I want to add, modify, and remove principles with automatic tension detection So that my principles document stays internally consistent

Acceptance Criteria:

• Given the user adds a principle that tensions with an existing one, when the management skill runs, then it flags the tension and asks for a resolution strategy.
• Given a principles document with unresolved tensions, when any downstream skill loads it, then the tension resolution section is included in the injection.
• Given the user removes a principle, when the management skill runs, then it checks whether the tension resolution section needs updating.

US-004: Fall back to HELIX defaults [FEAT-003]

As a HELIX operator who has not customized principles I want HELIX to apply sensible defaults rather than operating with no principles at all So that I get consistently reasonable results out of the box

Acceptance Criteria:

• Given no project principles file exists, when a downstream skill runs, then it loads and applies HELIX defaults from workflows/principles.md.
• Given HELIX defaults are active, when they are injected into a skill, then the skill applies them identically to how it would apply project principles.

Edge Cases and Error Handling

• Empty principles file: If the user creates docs/helix/01-frame/principles.md but leaves it empty, treat it as “no active principles” and fall back to defaults. Warn the user.
• Principles that negate HELIX mechanics: If a principle says “never write tests” or “ignore the artifact hierarchy”, the management skill should warn that this may break HELIX but not hard-block it. The user owns the file.
• Very large principles documents: The management skill warns at 8 principles (“consider whether all of these are decision-changing”), nudges consolidation at 12 (“the Agile Manifesto has 12 and most teams can only name 4-5”), and strongly recommends pruning at 15+. Above 12, the document has likely become a wish list rather than a decision framework. Injection adds to every prompt, so size has direct cost.

Success Metrics

• Every judgment-making skill includes active principles in its prompt.
• Projects that customize principles produce work that demonstrably reflects those principles (verifiable through review).
• Principle tensions are caught and resolved before they produce inconsistent downstream artifacts.

Constraints and Assumptions

• The injection mechanism must work with the existing skill/action prompt structure — no new runtime infrastructure.
• Principles are a static document, not a database — they are read at skill invocation time, not queried dynamically.
• The HELIX defaults should be stable and change rarely. They are the “obviously correct” baseline, not a living methodology document.

Dependencies

• FEAT-001: Supervisory control (principles injection into the run loop)
• helix.prd: Principles feature is governed by the PRD
• Workflow contract: Enforcers and ratchets must absorb the relocated workflow rules from the current workflows/principles.md

Out of Scope

• Per-activity principles (e.g., “build-activity principles” distinct from “design-activity principles”) — principles are cross-cutting by definition.
• Automated principle enforcement in CI — principles guide judgment, they are not linting rules.
• Principle versioning or history beyond what git provides.

Research Dependencies

• Prompt engineering for principles injection: What injection strategy (full doc vs. selective, preamble vs. inline, verbatim vs. rephrased) actually changes agent behavior? Use DDx agent execution, logging, and metrics to measure. This should be tracked as a research bead and iterated on across the existing HELIX skills.

Open Questions

• What DDx document graph features are needed to track principles as an upstream dependency of downstream artifacts? Does this require new DDx beads?
• Should principle changes trigger automatic re-review of all dependent artifacts, or only flag them as stale for the next helix align?