Skip to content
BranchesTags

Repository files navigation

Hufu (虎符)

English | 简体中文

(Formerly AxiomForge.)

Hufu takes its name from the tiger tally (虎符) — a bronze token split in two, its halves surrendered only when they interlock exactly — because this machine-authoritative AI-first SDLC runtime enforces the same rule in code: an agent's proposed hash must match the runtime's independently recomputed half before any authority to act is granted.

Hufu turns software intent into exact, registered, machine-validated artifacts that AI coding agents can execute reliably — requirements, architecture, designs, test specifications, execution plans, and materialized Tasks, each registered as an exact-hash Markdown artifact with a closed Machine JSON section. A single external runtime, artifact-graph, owns approval, routing, coverage, invalidation, Plan materialization, the Task lifecycle, and delivery finalization. The agent proposes; the runtime decides.

Node Tests Skills Runtimes

Why Hufu

Process documents written for humans are ambiguous to agents, and agents left to self-certify their own work drift. Hufu inverts both defaults:

  • Artifacts are written for the AI, not the human. Every stage produces a closed Machine JSON contract — exact keys, exact IDs, fail-closed validation — plus human-readable prose that is a review surface, never the execution authority.
  • The model never grades itself. Approval gates, RED-before-implement observations, per-Task review reports, independent delivery replay, and SHA-256 registration of every artifact all live in an external runtime the agent must call and cannot bypass.
  • Decisions are preserved, not just conclusions. Authoring skills run a grilling-style frontier protocol — facts are the agent's job, decisions are yours — and every settled decision lands in the artifact with its rejected alternatives and provenance (user-decided / recommended-accepted / agent-observed), so the next session's agent knows what is renegotiable.
  • Brownfield is first-class. Existing projects take a two-gate light track instead of the full ten-artifact chain, then share the exact same execution and delivery machinery.

How it works

One canonical skill tree, one runtime, thin per-tool adapters:

┌────────────────────────────── skills/ (13 canonical skills) ─────────────────────────────┐
│ using-ai-sdlc (router entry)                                                             │
│ profiling-project → authoring skills → planning → executing → reviewing → validating     │
└───────────────┬──────────────────────────────────────────────────────────────────────────┘
                │ every state change goes through
┌───────────────▼──────────────────────────────────────────────────────────────────────────┐
│ scripts/artifact-graph.mjs (the runtime — approval, routing, hashes, lifecycle)          │
└───────────────┬──────────────────────────────────────────────────────────────────────────┘
                │ registers exact-hash artifacts in
┌───────────────▼──────────────────────────────────────────────────────────────────────────┐
│ your product repo: PROF-*, REQ-*, ARCH-*, HLD-*, DLD-*, TEST-*, PLAN-*, TASK-*,          │
│                    INT-*, DSN-*, REPORT-*, EVID-*  (+ .ai-sdlc/ manifest)                │
└──────────────────────────────────────────────────────────────────────────────────────────┘

Two tracks, one delivery machine:

Greenfield / architecture-level change:
  Profile → Requirements(gate) → Architecture(gate) → HLD → DLD → Test Spec
          → Plan → Task → execute → Delivery Report → Delivery Evidence → DELIVERED

Brownfield increment (Profile mode: existing):
  Profile → Increment Intent(gate) → Increment Design(gate)
          → Plan → Task → execute → Delivery Report → Delivery Evidence → DELIVERED

The router decides which track applies. An increment that turns out to be an architecture-level change is blocked with REQUIRES_FULL_CHAIN and rerouted. Coding begins only after the router returns executing-ai-plan; each materialized Task carries an exact RED observation that must reproduce before a single authorized write is made, and finalize-delivery independently re-runs every bound command before the workflow can reach complete/DELIVERED.

Quick start

git clone https://github.com/<your-org>/hufu.git
cd hufu
npm install        # dev dependencies only (ajv, commonmark)
npm test           # full contract/unit/integration suite

Requires Node.js >= 20. The runtime has zero production dependencies.

Then install it into your coding agent (next section), open your product repository, and tell the agent:

Use Hufu to route this task.

Installation

The canonical workflows live only in skills/. Adapters translate discovery and invocation per tool — they never change the contracts. Three runtimes are first-class (adapter files ship in this repo and are covered by the test suite); the rest integrate through documented conventions.

Tool Mechanism Status
Claude Code .claude-plugin/plugin.json ✅ First-class
OpenAI Codex .codex-plugin/plugin.json, .agents/skills/ ✅ First-class
Gemini CLI gemini-extension.json, .agents/skills/ ✅ First-class
Antigravity open Agent Skills convention (SKILL.md), AGENTS.md 🔶 Convention
Trae project rules + CLI contract 🔶 Convention
GitHub Copilot .github/copilot-instructions.md, AGENTS.md 🔶 Convention
Cursor / others AGENTS.md / rules file 🔶 Convention

🔶 Convention means: the skill files and the runtime work unmodified (skills are plain Markdown with YAML frontmatter; the runtime is a plain Node CLI), but this repo ships no tested adapter for the tool — you wire the discovery with the snippet below and your tool's custom-instructions mechanism. Config file names in third-party tools change; if a path below does not match your version, check your tool's documentation for "custom instructions", "rules", or "skills".

Claude Code

claude --plugin-dir /absolute/path/to/hufu

All 13 skills appear under the hufu plugin namespace, and using-ai-sdlc triggers when you ask for a routed SDLC task. To make it permanent, add the directory as a local plugin (or publish it to your plugin marketplace) via /plugin inside Claude Code.

OpenAI Codex

Codex discovers the skills through the package-root .codex-plugin/plugin.json when the package is opened, or system-wide via the interoperable skills directory (symlinks are supported):

mkdir -p ~/.agents/skills
ln -s /absolute/path/to/hufu/skills/* ~/.agents/skills/

Per-repository instead: create .agents/skills/ in your product repo and symlink the same skill directories there.

Gemini CLI

gemini extensions link /absolute/path/to/hufu

or use the same .agents/skills/ alias as Codex.

Antigravity

Antigravity understands the same open SKILL.md skill format this repo uses. Expose the skills through the interoperable skills directory in your workspace:

mkdir -p .agents/skills
ln -s /absolute/path/to/hufu/skills/* .agents/skills/

then add the universal AGENTS.md snippet to the workspace root so the planner knows to start from using-ai-sdlc. If your Antigravity version manages skills from its own settings UI instead, point it at /absolute/path/to/hufu/skills/.

Trae

Trae drives integration through project rules. Create .trae/rules/project_rules.md in your product repository:

# Hufu SDLC rules

For any feature, fix, or delivery task in this repository, follow the
Hufu workflow:

1. Read /absolute/path/to/hufu/skills/using-ai-sdlc/SKILL.md and obey it.
2. Every workflow state change must go through
   `node /absolute/path/to/hufu/scripts/artifact-graph.mjs <command>`.
   Never edit the manifest or artifact hashes by hand.
3. Only the skill named by `artifact-graph route` may act next.

Trae's agent then reads each skill file on demand and shells out to the runtime like any other terminal command.

GitHub Copilot

Copilot's coding agent and agent mode read repository custom instructions. Create .github/copilot-instructions.md in your product repository with the same three rules as the Trae snippet above (adjusting the absolute paths), and additionally drop the universal AGENTS.md at the repo root — recent Copilot coding-agent versions read AGENTS.md directly. Copilot Chat in the IDE will follow the instructions; the autonomous coding agent will follow AGENTS.md.

Cursor and other AGENTS.md tools

Any tool that honors AGENTS.md (Cursor, and most 2025+ agent IDEs) needs only the universal snippet below at your product repo root. Cursor users can alternatively place the same content in .cursor/rules/hufu.mdc.

Any other agent

If your agent can read Markdown and run shell commands, it can run Hufu. Drop this AGENTS.md at your product repository root (adjust the path):

# Hufu

This repository is developed under the Hufu machine-authoritative
SDLC. Before any feature, fix, or delivery work:

1. Read /absolute/path/to/hufu/skills/using-ai-sdlc/SKILL.md and
   follow it exactly. It routes you via:
   node /absolute/path/to/hufu/scripts/artifact-graph.mjs route <root>
2. Invoke only the skill the router names, reading its SKILL.md (and its
   references/) from the same skills directory.
3. All state changes go through the artifact-graph CLI. Never hand-edit
   .ai-sdlc/ manifests, artifact hashes, or approval records. Approvals
   are made by the human, never by you.
4. Do not write product code until the router returns executing-ai-plan.

Usage

The loop

Every unit of work is the same loop, on both tracks:

  1. Route. The agent runs artifact-graph route <root>; the runtime returns exactly one action — invoke a named skill, request a human approval, or report blocked with diagnostics.
  2. Author through grilling. Authoring skills interview you in frontier rounds — every currently-answerable question at once, each with a recommended answer. The agent gathers facts itself (subagent exploration); you make decisions. Settled decisions are persisted with provenance.
  3. Gate. Requirements and Architecture (full chain) or Increment Intent and Increment Design (light track) stop at human approval gates: artifact-graph approve <root> <artifact-id> <approved-by> <reason>.
  4. Plan → Tasks. Plan registration materializes atomic Tasks, each with bounded writes, exact source baselines, and one exact RED observation.
  5. Execute. executing-ai-plan reproduces RED, performs only the authorized writes, runs the closed verification commands, and marks the Task implemented — all through atomic public CLI transactions.
  6. Review → validate → finalize. One Machine Delivery Report per Task (changes-required authorizes rework, with cascade invalidation and ordered replay), ready Delivery Evidence, then finalize-delivery independently re-runs every bound command and atomically produces the complete/DELIVERED route.

Greenfield example

You:   Use Hufu to build a URL-shortener service in this empty repo.
Agent: [routes] → profiling-project → registers PROF-SYS-001
       [routes] → writing-ai-requirements → grilling rounds → REQ-SYS-001
       → requests your approval (gate 1)
You:   artifact-graph approve . REQ-SYS-001 you "scope agreed"
Agent: [routes] → designing-ai-architecture → ... (gate 2) → HLD → DLD →
       Test Spec → Plan → materialize → executes Tasks under RED/GREEN →
       per-Task reviews → evidence → finalize-delivery → DELIVERED

Brownfield example

You:   Use Hufu: add CSV export to the reports page.
Agent: [routes; Profile mode=existing] → writing-ai-increment
       → blast-radius probe + grilling → INT-INC-001 (intent + acceptance)
       → your approval (gate 1)
       → designing-ai-increment → delta scope + exact RED bindings +
         decision tree → DSN-INC-001 → your approval (gate 2)
       → Plan → Tasks → execute → review → evidence → DELIVERED

If the intent probe discovers the change is architecture-level, the intent is blocked with REQUIRES_FULL_CHAIN and the router walks you onto the full chain instead.

What the agent can never do

Approve its own gated artifacts; write product code before executing-ai-plan is routed; touch files outside a Task's authorized writes; skip a failed RED reproduction; edit manifests, hashes, approval records, or recorded evidence; or continue past any failed public command. Every one of these is enforced by the runtime and its test suite, not by prompt discipline.

CLI reference

artifact-graph init <root> <project-id>                      initialize a project manifest
artifact-graph register <root> <artifact-file>               register/refresh an exact-hash artifact
artifact-graph validate <root>                               validate manifest + all artifact files
artifact-graph approve <root> <id> <approved-by> <reason>    human approval for a gated artifact
artifact-graph invalidate <root> <id> <reason>               invalidate an artifact + stale successors
artifact-graph ready <root>                                  list executable Tasks
artifact-graph coverage <root>                               requirement/test/task coverage counts
artifact-graph route <root>                                  the single authoritative next action
artifact-graph context <root> <expected-skill>               stable authoring context receipt
artifact-graph materialize-plan <root> <plan-id>             atomically materialize Plan Tasks
artifact-graph task <start|implement|rework|complete|block> <root> <task-id> [reason]
artifact-graph finalize-delivery <root> <evidence-id>        independent replay → DELIVERED

All commands print canonical JSON and fail closed with a nonzero exit code.

Trust model

  • Exact-hash registration. Every artifact is registered by full-file SHA-256; edits invalidate dependents transitively (stale propagation).
  • Closed Machine shapes. JSON schemas and an independent runtime validator must accept/reject identically (equivalence-tested).
  • RED before implement. A Task cannot start until its recorded failing observation reproduces byte-for-byte.
  • Independent replay. Delivery finalization re-runs every bound command itself and compares exit/stdout/stderr before DELIVERED.
  • Evidence immutability. Recorded evidence under test-results/ is add-only; superseded evidence is chained (supersedes + SHA-256 pointers), never rewritten.
  • Sealed releases. Each release seals its complete surface with an independently re-derived verifier and an unbroken hash-bound predecessor chain back to the runtime's first sealed release (v48 → … → latest).

Project structure

hufu/
├── skills/                  13 canonical skills (SKILL.md + references/)
├── scripts/artifact-graph.mjs   the public runtime CLI
├── scripts/                 test runner, suite policy, seal + evidence tooling
├── lib/                     runtime internals (router, manifest, catalog, transactions)
├── schemas/                 JSON Schemas mirrored by the runtime validators
├── policies/                generated requirements label policies (v33…v38)
├── adapters/                per-runtime discovery notes (Claude / Codex / Gemini)
├── tests/                   contract, unit, integration, scenario suites
├── test-results/            immutable recorded evidence + release seals
└── docs/superpowers/        design specs and implementation plans (per release)

Testing

npm test                 # full suite: 31 batches, 1599 tests
npm run validate:fixture # runtime self-check against the bundled fixture

The suite includes schema/runtime equivalence tests, router matrices, end-to-end CLI walks of both tracks (including a brownfield fixture with superseded full-chain history), a failure battery (forged evidence, source drift, mixed-track abort — each asserting byte-identical manifests), and the release seal verifier.

Roadmap

  • Pressure-evidence campaigns for the two increment skills and refreshed captures for the reworded skills (blind live-agent runs).
  • Multi-increment brownfield ergonomics (follow-on increments on delivered projects).
  • Cross-skill wording consistency pass.

See docs/superpowers/ for per-release specs, plans, and the sealed follow-up ledger.

Contributing

The house rules are enforced by the contract suite — read them before opening a PR:

  • TDD is mandatory: RED observed before GREEN, evidence in the task report.
  • Machine JSON is closed: exact keys, no duplicates, errors never echo keys or values.
  • SKILL.md files stay ≤ 700 words and start descriptions with "Use when".
  • Recorded evidence and historical writing-ai-requirements-v* tests are immutable; retirement happens only through scripts/test-suite-policy.mjs gates with measured-fact reasons.
  • Every release ends with a green clean-shell npm test and a new surface seal.

License

MIT © 2026 vpcoderli. The package.json stays private: true only to prevent accidental npm publication; it does not affect this repository's license.

About

Hufu 得名于虎符——一分为二的青铜兵符，两半严丝合缝才交出兵权。这个机器权威（machine-authoritative）的 AI-first SDLC 运行时在代码里执行同一条规则：agent 提议的哈希，必须与运行时独立重算出的那一半完全吻合，才授予任何行事权力。

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages