Run a feature from brief to MR with /hx
hx is an Agent Skill that chains requirement gathering, planning, execution, quality checks, and MR creation into a single verifiable pipeline. Command contracts, fact scripts, and rule templates are layered so the Agent only handles semantic decisions.
01Why hx
Most AI coding workflows fail on context drift and unverifiable steps. hx separates semantics from facts with three distinct layers.
Command Contracts
Each hx-* command defines only its goal, boundaries, and output. Short, executable, reviewable.
Fact Scripts
scripts/tools/*.ts give the Agent structured facts — no more guessing paths, state, or schema.
Templates & Gates
Rule templates, progress.json, and quality gates all live in .hx/. The runtime reads only from config.
02Quickstart
Three steps to wire hx into your project. All commands are invoked with the /hx prefix inside Claude Code or any compatible Agent runtime.
Install the Skill
Install via npx skills — no manual cloning required.
npx skills add hxflow/workflow
Initialize Your Project
Run /hx init in your repo. Single-project repos get config.yaml; multi-service repos get workspace.yaml. Existing config is never overwritten.
/hx init # → single-project: .hx/config.yaml # → multi-project: .hx/workspace.yaml # → rule templates: .hx/rules/
Drive a Feature
Use /hx go <feature> to run the full pipeline end-to-end, or step through manually and review at each checkpoint.
# full auto /hx go login-sso # step by step /hx doc login-sso /hx plan login-sso /hx run login-sso /hx check login-sso /hx mr login-sso
Bun ≥ 1.0.0. If Bun is not available, use Node.js and run scripts via npx tsx hxflow/scripts/**/*.ts.
03Pipeline Overview
/hx go advances through each node in order. At check, a sub-agent runs a quality review — the pipeline only continues on pass.
Constraints
• Never skip the earliest incomplete step
• Only advance to the step returned by the fact script
• --from <step> restarts from a specific step
Artifacts
• docs/requirement/{feature}.md
• docs/plans/{feature}.md
• docs/plans/{feature}-progress.json
04Command Reference
All commands follow the pattern /hx <command> [args]. Omitting the command defaults to go.
| Command | Phase | Description | Next |
|---|---|---|---|
/hx init |
Init | Generate .hx/config.yaml (single) or .hx/workspace.yaml (multi) and rule templates |
doc |
/hx doc <feature> |
Phase 01 | Gather requirements and write docs/requirement/{feature}.md |
plan |
/hx plan <feature> |
Phase 02 | Generate execution plan and progress.json |
run |
/hx run <feature> |
Phase 04 | Execute tasks in batches and write back progress | check |
/hx check <feature> |
Phase 06 | Quality gate, code review, engineering hygiene | mr |
/hx mr <feature> |
Phase 08 | Generate title and description, create Merge Request | — |
/hx go <feature> |
Full | Full pipeline: doc → plan → run → check → mr |
auto |
/hx status |
Status | View current task progress | — |
/hx reset <feature> [plan|doc|code] |
Maintenance | Reset requirement, plan, or execution state | — |
05Project Structure
Framework files and user artifacts are strictly separated: modify behavior in hxflow/, read and write runtime facts in .hx/.
Framework hxflow/
hxflow/ ├─ SKILL.md # Skill entry, routes commands ├─ commands/ # hx-*.md command contracts ├─ scripts/ │ ├─ tools/ # fact scripts (called by Agent) │ └─ lib/ # shared utilities └─ templates/ # rule templates & defaults
User Artifacts .hx/
.hx/ ├─ config.yaml # single-project mode ├─ workspace.yaml # multi-project (workspace) mode ├─ rules/ # rule templates (req / plan etc.) ├─ hooks/ # custom hooks (optional) └─ pipelines/ # custom pipelines (optional)
To change command behavior or default scaffolding, edit hxflow/commands, hxflow/scripts, or hxflow/templates. The .hx/* directory is only the generated output of hx-init — not the source of truth.
06Testing & Publishing
One command for local dev loops; publishing is automated via GitHub Packages on v* tags.
Test Commands
bun run hx:test # full regression bun run hx:test:unit # unit only bun run hx:test:integration # integration only bun run pack:dry-run # verify package contents
Continuous Evals
bun run hx:evals:validate bun run hx:evals:report
Failed samples are deposited into regressions.jsonl for regression comparison against prompt, command, and script changes.