Cross-Cutting Concerns

Cross-cutting concerns are a core concept in HELIX. They capture technology choices, quality requirements, and conventions that cut across activities, runtime work items, and artifacts. They do it declaratively, so agents load the right context without you repeating yourself.

The Problem Concerns Solve

In a multi-activity, multi-agent workflow, every agent must honor the same decisions everywhere:

• “We use Bun, not Node” affects build scripts, test runners, CI, and design docs.
• “OWASP Top 10 compliance” affects every endpoint, every input handler, every dependency choice.
• “OpenTelemetry tracing” affects middleware, error paths, and deployment config.

Without a mechanism to declare these once and inject them everywhere, each agent invocation risks rediscovering (or contradicting) a prior decision. Concerns are that mechanism.

How They Work

1. Declare: during Frame, list active concerns in docs/helix/01-frame/concerns.md
2. Filter: each concern declares which areas it applies to (all, ui, api, data, infra, cli)
3. Inject: at execution time, HELIX loads area-matched concerns and their practices into the agent’s context
4. Attach runtime context: runtime work context carries concern practices into individual work items, making each work item self-contained

Concern Library

HELIX ships a library of concerns under workflows/concerns/. Each concern consists of two files:

Tech Stack Concerns

Quality and Infrastructure Concerns

Testing Concerns

Tooling Concerns

See the full concerns catalog for detailed component listings and all available concerns.

Drift Detection

Tech-stack concerns declare drift signals: patterns that indicate the project is straying from its declared technology choices. For example, the typescript-bun concern flags npm run instead of bun run, eslint instead of Biome, and jest instead of bun:test.

HELIX checks for drift signals during review and alignment, reporting findings that keep the project true to its own decisions.

Artifact-Impact Contract

Each concern declares an Artifact Impact section: the artifacts that must change when you select that concern. Choosing security-owasp, for instance, obligates the corresponding ADR, technical-design, and test-plan updates. Selecting a concern without making those changes is drift, and the alignment reconcile check catches it. This makes a concern bite on both

generated and hand-edited artifacts, not just on runtime work context.

The Knowledge Chain

Concerns connect to the rest of the HELIX artifact graph through a knowledge chain:

Spike/POC (gather evidence)
  → ADR (record decision with rationale)
    → Concern (index for context assembly)
      → Runtime work context (injected into work items)

When a referenced ADR is superseded, review and alignment

flags the affected concern for re-evaluation, ensuring that decisions

propagate forward rather than silently going stale.

Where HELIX Uses Concerns

Every HELIX action that involves technology or quality choices loads active concerns:

See the full concerns reference for the complete library catalog and project configuration format.