hufu
Machine-authoritative AI-first software delivery workflows.
Open source Open in the app JSON README (API)
About
Machine-authoritative AI-first software delivery workflows.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- vpcoderli
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2026-08-18T09:25:25Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
vpcoderli/hufu
README
# Hufu (虎符)
**English** | [简体中文](README.zh-CN.md)
*(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.
- [Why Hufu](#why-hufu)
- [How it works](#how-it-works)
- [Quick start](#quick-start)
- [Installation](#installation)
- [Claude Code](#claude-code)
- [OpenAI Codex](#openai-codex)
- [Gemini CLI](#gemini-cli)
- [Antigravity](#antigravity)
- [Trae](#trae)
- [GitHub Copilot](#github-copilot)
- [Cursor and other AGENTS.md tools](#cursor-and-other-agentsmd-tools)
- [Any other agent](#any-other-agent)
- [Usage](#usage)
- [CLI reference](#cli-reference)
- [Trust model](#trust-model)
- [Project structure](#project-structure)
- [Testing](#testing)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
## 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
```bash
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
```bash
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):
```bash
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
```bash
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:
```bash
mkdir -p .agents/skills
ln -s /absolute/path/to/hufu/skills/* .agents/skills/
```
then add the [universal `AGENTS.md` snippet](#any-other-agent) 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:
```markdown
# 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`](#any-other-agent) 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):
```markdown
# 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
```text
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
```text
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
```bash
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](LICENSE) © 2026 vpcoderli. The `package.json` stays `private: true`
only to prevent accidental npm publication; it does not affect this
repository's license.