Cross-Cutting Concerns

Cross-cutting concerns are a core concept in HELIX. They capture technology choices, quality requirements, and conventions that cut across phases, beads, and artifacts — and they do it declaratively, so agents can load the right context without being told twice.

The Problem Concerns Solve

In a multi-phase, multi-agent workflow, the same decisions need to be honored 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. Digest — Context digests carry concern practices into individual beads, 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 align, reporting findings that keep the project honest to its own decisions.

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)
      → Context Digest (injected into beads)

When a referenced ADR is superseded, polish flags the affected concern for re-evaluation — ensuring that decisions propagate forward rather than silently going stale.

Where Concerns Are Used

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.