@hxflow/workflow

Harness Workflow — Agent Skill for requirement-to-delivery pipeline.

类型定义已迁移至 @hxflow/shared，请从 @hxflow/shared/types 导入。

中文文档

---

Introduction

hx is an Agent Skill invoked via /hx <command> that orchestrates the full requirement-to-delivery pipeline.

Runtime config files:

• .hx/config.yaml — single-project config
• .hx/workspace.yaml — workspace root config (multi-project)
• .hx/rules/*.md — project rule templates
• .hx/pipelines/ — custom pipelines (optional)
• .hx/hooks/ — pre/post hooks per command (optional)

---

Installation

npx skills add hxflow/workflow

After installation, run /hx init in your project to initialize.

---

Usage

/hx go feature-name        # full pipeline
/hx doc feature-name       # gather requirements
/hx plan feature-name      # generate plan
/hx run feature-name       # execute tasks
/hx review feature-name    # quality review
/hx mr feature-name        # create MR
/hx reset feature-name [plan|doc|code]

---

Commands

Command	Description
go	Full pipeline: doc → plan → run → review → mr
doc	Gather requirements and create requirement doc
plan	Generate execution plan and progress.json
run	Execute tasks
review	Quality gate (review, gates, engineering hygiene)
mr	Create Merge Request
init	Generate config, rule templates, and default pipeline
status	View task progress
reset	Reset doc, plan, or code state

---

Architecture

The skill entry is hxflow/SKILL.md. It routes /hx <command> to the matching command contract, resolves hooks, and loads only the files needed for the current command.

hxflow/
  SKILL.md              # Skill entry point — routes /hx <command>
  commands/hx-*.md      # Command contracts
  scripts/tools/*.ts    # Fact-fetching scripts (structured JSON for AI)
  templates/            # Rule templates and default pipeline

Project scaffold generated by hx init:

.hx/
  config.yaml           # single-project mode
  workspace.yaml        # multi-project (workspace) mode
  rules/
    requirement-template.md
    plan-template.md
    bugfix-requirement-template.md
    bugfix-plan-template.md
  pipelines/
    default.yaml        # default pipeline definition
  hooks/                # optional pre/post hooks per command

---

Hooks

Configure pre/post hooks per command in .hx/config.yaml:

runtime:
  hooks:
    doc:
      pre:
        - .hx/hooks/pre_doc.md   # injected before hx doc
      post:
        - .hx/hooks/post_doc.md  # injected after hx doc

---

Multi-project Workspace

When the repo contains multiple sub-services, hx init scans candidates and generates .hx/workspace.yaml:

• Root workspace.yaml holds the coordination layer: paths, gates, runtime, rules.templates, projects
• Sub-projects can have their own config.yaml to override only cwd, src, and gates; everything else inherits from workspace
• Requirement and plan docs are maintained at the workspace root; task-level changes are scoped to the target service

---

Agent Sessions

Long-running work continues in background agent or shell sessions. Use list_agents and read_agent to inspect agent output, write_agent only when an idle agent is waiting for input. Use list_bash, read_bash, and write_bash for shell sessions; keep the two session types separate.

---

Requirements

• Bun >= 1.0.0; fall back to npx tsx if Bun is not available

---

Testing

bun run hx:test              # full regression
bun run hx:test:unit         # unit tests
bun run hx:test:integration  # integration tests

---

Publishing

• Repo: https://github.com/hxflow/workflow
• npm registry: https://npm.pkg.github.com (@hxflow scope)
• Push a v* tag to trigger automated release

---

License

MIT