Demos
Demos
Eight scenarios show HELIX in motion against the four-step Core Workflow Contract from the PRD: write the brief, check alignment, create the work plan, run it in the factory.
Every demo is a session record — a committed session.jsonl
(source) under docs/demos/<slug>/. The asciinema casts on
this page are deterministic re-renders produced at build time by
scripts/demos/render_session.py. Capture the session once, verify it,
rebuild the cast whenever you like.
adopt — Drop HELIX into an existing project
One install, one ask. The skill lands; the agent gains the artifact catalog and can scan whatever’s already in the repo. No CLI to learn.
brief — Author the governing artifacts
Vision → PRD → concerns → first feature spec, all populated from HELIX templates by the same skill the agent invokes. The brief is what the agent will defend code against on day n.
align — Detect drift across the artifact graph
PRD says one thing; a recent ADR says another. The alignment skill walks the graph in authority order and reports an ordered plan to close the gap.
plan — Turn aligned artifacts into bounded work
The planning side of the same skill: decomposes feature specs into beads with deterministic acceptance criteria and named evidence. Ready for a runtime to execute.
evolve — Thread a new requirement through the stack
The product-vision scenario, made concrete: a team adds OAuth alongside existing API-key auth. One sentence in; six authority-ordered steps out, spanning security architecture, ADRs, feature specs, designs, tests, and beads.
concerns — Catch technology drift before it ships
A project declares typescript-bun as its stack concern. The agent
writes idiomatic-looking code that nonetheless drifts to Node defaults.
Alignment catches all three drift signals.
review — Fresh-eyes audit against the same artifacts
A second agent inspects completed work against the artifacts that govern it. Two blocking findings (missing revocation enforcement, missing test), one warning (token leak in error log), filed as tracker issues.
execute — Run a bead end-to-end in the factory
The hand-off to the runtime. DDx selects the bead, FZO routes to the right model + harness, work runs in a worktree, acceptance gates fire, a different model does a cross-review, evidence appends, the bead closes.
Rebuilding the casts locally
python3 scripts/demos/render_session.py docs/demos/helix-align/session.jsonl
bash tests/validate-demos.shvalidate-demos.sh asserts schema soundness for every committed
session.jsonl and re-renders each into a byte-identical .cast. If
your render differs, either the record changed (rebuild + commit) or
the renderer changed (test will fail on every demo).