{
  "markdown": "# Hufu (虎符)\n\n**English** | [简体中文](README.zh-CN.md)\n\n*(Formerly AxiomForge.)*\n\n**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.**\n\nHufu turns software intent into exact, registered, machine-validated\nartifacts that AI coding agents can execute reliably — requirements,\narchitecture, designs, test specifications, execution plans, and materialized\nTasks, each registered as an exact-hash Markdown artifact with a closed\nMachine JSON section. A single external runtime, `artifact-graph`, owns\napproval, routing, coverage, invalidation, Plan materialization, the Task\nlifecycle, and delivery finalization. The agent proposes; the runtime\ndecides.\n\n![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)\n![Tests](https://img.shields.io/badge/tests-1599%2F1599-brightgreen)\n![Skills](https://img.shields.io/badge/skills-13-blue)\n![Runtimes](https://img.shields.io/badge/runtimes-Claude%20Code%20%7C%20Codex%20%7C%20Gemini%20CLI%20%2B%20conventions-blue)\n\n- [Why Hufu](#why-hufu)\n- [How it works](#how-it-works)\n- [Quick start](#quick-start)\n- [Installation](#installation)\n  - [Claude Code](#claude-code)\n  - [OpenAI Codex](#openai-codex)\n  - [Gemini CLI](#gemini-cli)\n  - [Antigravity](#antigravity)\n  - [Trae](#trae)\n  - [GitHub Copilot](#github-copilot)\n  - [Cursor and other AGENTS.md tools](#cursor-and-other-agentsmd-tools)\n  - [Any other agent](#any-other-agent)\n- [Usage](#usage)\n- [CLI reference](#cli-reference)\n- [Trust model](#trust-model)\n- [Project structure](#project-structure)\n- [Testing](#testing)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why Hufu\n\nProcess documents written for humans are ambiguous to agents, and agents left\nto self-certify their own work drift. Hufu inverts both defaults:\n\n- **Artifacts are written for the AI, not the human.** Every stage produces a\n  closed Machine JSON contract — exact keys, exact IDs, fail-closed\n  validation — plus human-readable prose that is a review surface, never the\n  execution authority.\n- **The model never grades itself.** Approval gates, RED-before-implement\n  observations, per-Task review reports, independent delivery replay, and\n  SHA-256 registration of every artifact all live in an external runtime the\n  agent must call and cannot bypass.\n- **Decisions are preserved, not just conclusions.** Authoring skills run a\n  grilling-style frontier protocol — facts are the agent's job, decisions are\n  yours — and every settled decision lands in the artifact with its rejected\n  alternatives and provenance (`user-decided` / `recommended-accepted` /\n  `agent-observed`), so the next session's agent knows what is renegotiable.\n- **Brownfield is first-class.** Existing projects take a two-gate light\n  track instead of the full ten-artifact chain, then share the exact same\n  execution and delivery machinery.\n\n## How it works\n\nOne canonical skill tree, one runtime, thin per-tool adapters:\n\n```\n┌────────────────────────────── skills/ (13 canonical skills) ─────────────────────────────┐\n│ using-ai-sdlc (router entry)                                                             │\n│ profiling-project → authoring skills → planning → executing → reviewing → validating     │\n└───────────────┬──────────────────────────────────────────────────────────────────────────┘\n                │ every state change goes through\n┌───────────────▼──────────────────────────────────────────────────────────────────────────┐\n│ scripts/artifact-graph.mjs (the runtime — approval, routing, hashes, lifecycle)          │\n└───────────────┬──────────────────────────────────────────────────────────────────────────┘\n                │ registers exact-hash artifacts in\n┌───────────────▼──────────────────────────────────────────────────────────────────────────┐\n│ your product repo: PROF-*, REQ-*, ARCH-*, HLD-*, DLD-*, TEST-*, PLAN-*, TASK-*,          │\n│                    INT-*, DSN-*, REPORT-*, EVID-*  (+ .ai-sdlc/ manifest)                │\n└──────────────────────────────────────────────────────────────────────────────────────────┘\n```\n\nTwo tracks, one delivery machine:\n\n```\nGreenfield / architecture-level change:\n  Profile → Requirements(gate) → Architecture(gate) → HLD → DLD → Test Spec\n          → Plan → Task → execute → Delivery Report → Delivery Evidence → DELIVERED\n\nBrownfield increment (Profile mode: existing):\n  Profile → Increment Intent(gate) → Increment Design(gate)\n          → Plan → Task → execute → Delivery Report → Delivery Evidence → DELIVERED\n```\n\nThe router decides which track applies. An increment that turns out to be an\narchitecture-level change is blocked with `REQUIRES_FULL_CHAIN` and rerouted.\nCoding begins only after the router returns `executing-ai-plan`; each\nmaterialized Task carries an exact RED observation that must reproduce before\na single authorized write is made, and `finalize-delivery` independently\nre-runs every bound command before the workflow can reach\n`complete/DELIVERED`.\n\n## Quick start\n\n```bash\ngit clone https://github.com/<your-org>/hufu.git\ncd hufu\nnpm install        # dev dependencies only (ajv, commonmark)\nnpm test           # full contract/unit/integration suite\n```\n\nRequires **Node.js >= 20**. The runtime has zero production dependencies.\n\nThen install it into your coding agent (next section), open your product\nrepository, and tell the agent:\n\n> Use Hufu to route this task.\n\n## Installation\n\nThe canonical workflows live only in `skills/`. Adapters translate discovery\nand invocation per tool — they never change the contracts. Three runtimes are\nfirst-class (adapter files ship in this repo and are covered by the test\nsuite); the rest integrate through documented conventions.\n\n| Tool | Mechanism | Status |\n|---|---|---|\n| Claude Code | `.claude-plugin/plugin.json` | ✅ First-class |\n| OpenAI Codex | `.codex-plugin/plugin.json`, `.agents/skills/` | ✅ First-class |\n| Gemini CLI | `gemini-extension.json`, `.agents/skills/` | ✅ First-class |\n| Antigravity | open Agent Skills convention (`SKILL.md`), `AGENTS.md` | 🔶 Convention |\n| Trae | project rules + CLI contract | 🔶 Convention |\n| GitHub Copilot | `.github/copilot-instructions.md`, `AGENTS.md` | 🔶 Convention |\n| Cursor / others | `AGENTS.md` / rules file | 🔶 Convention |\n\n> 🔶 **Convention** means: the skill files and the runtime work unmodified\n> (skills are plain Markdown with YAML frontmatter; the runtime is a plain\n> Node CLI), but this repo ships no tested adapter for the tool — you wire\n> the discovery with the snippet below and your tool's custom-instructions\n> mechanism. Config file names in third-party tools change; if a path below\n> does not match your version, check your tool's documentation for\n> \"custom instructions\", \"rules\", or \"skills\".\n\n### Claude Code\n\n```bash\nclaude --plugin-dir /absolute/path/to/hufu\n```\n\nAll 13 skills appear under the `hufu` plugin namespace, and\n`using-ai-sdlc` triggers when you ask for a routed SDLC task. To make it\npermanent, add the directory as a local plugin (or publish it to your plugin\nmarketplace) via `/plugin` inside Claude Code.\n\n### OpenAI Codex\n\nCodex discovers the skills through the package-root `.codex-plugin/plugin.json`\nwhen the package is opened, or system-wide via the interoperable skills\ndirectory (symlinks are supported):\n\n```bash\nmkdir -p ~/.agents/skills\nln -s /absolute/path/to/hufu/skills/* ~/.agents/skills/\n```\n\nPer-repository instead: create `.agents/skills/` in your product repo and\nsymlink the same skill directories there.\n\n### Gemini CLI\n\n```bash\ngemini extensions link /absolute/path/to/hufu\n```\n\nor use the same `.agents/skills/` alias as Codex.\n\n### Antigravity\n\nAntigravity understands the same open `SKILL.md` skill format this repo uses.\nExpose the skills through the interoperable skills directory in your\nworkspace:\n\n```bash\nmkdir -p .agents/skills\nln -s /absolute/path/to/hufu/skills/* .agents/skills/\n```\n\nthen add the [universal `AGENTS.md` snippet](#any-other-agent) to the\nworkspace root so the planner knows to start from `using-ai-sdlc`. If your\nAntigravity version manages skills from its own settings UI instead, point it\nat `/absolute/path/to/hufu/skills/`.\n\n### Trae\n\nTrae drives integration through project rules. Create\n`.trae/rules/project_rules.md` in your product repository:\n\n```markdown\n# Hufu SDLC rules\n\nFor any feature, fix, or delivery task in this repository, follow the\nHufu workflow:\n\n1. Read /absolute/path/to/hufu/skills/using-ai-sdlc/SKILL.md and obey it.\n2. Every workflow state change must go through\n   `node /absolute/path/to/hufu/scripts/artifact-graph.mjs <command>`.\n   Never edit the manifest or artifact hashes by hand.\n3. Only the skill named by `artifact-graph route` may act next.\n```\n\nTrae's agent then reads each skill file on demand and shells out to the\nruntime like any other terminal command.\n\n### GitHub Copilot\n\nCopilot's coding agent and agent mode read repository custom instructions.\nCreate `.github/copilot-instructions.md` in your product repository with the\nsame three rules as the Trae snippet above (adjusting the absolute paths),\nand additionally drop the [universal `AGENTS.md`](#any-other-agent) at the\nrepo root — recent Copilot coding-agent versions read `AGENTS.md` directly.\nCopilot Chat in the IDE will follow the instructions; the autonomous coding\nagent will follow `AGENTS.md`.\n\n### Cursor and other AGENTS.md tools\n\nAny tool that honors `AGENTS.md` (Cursor, and most 2025+ agent IDEs) needs\nonly the universal snippet below at your product repo root. Cursor users can\nalternatively place the same content in `.cursor/rules/hufu.mdc`.\n\n### Any other agent\n\nIf your agent can read Markdown and run shell commands, it can run\nHufu. Drop this `AGENTS.md` at your product repository root (adjust the\npath):\n\n```markdown\n# Hufu\n\nThis repository is developed under the Hufu machine-authoritative\nSDLC. Before any feature, fix, or delivery work:\n\n1. Read /absolute/path/to/hufu/skills/using-ai-sdlc/SKILL.md and\n   follow it exactly. It routes you via:\n   node /absolute/path/to/hufu/scripts/artifact-graph.mjs route <root>\n2. Invoke only the skill the router names, reading its SKILL.md (and its\n   references/) from the same skills directory.\n3. All state changes go through the artifact-graph CLI. Never hand-edit\n   .ai-sdlc/ manifests, artifact hashes, or approval records. Approvals\n   are made by the human, never by you.\n4. Do not write product code until the router returns executing-ai-plan.\n```\n\n## Usage\n\n### The loop\n\nEvery unit of work is the same loop, on both tracks:\n\n1. **Route.** The agent runs `artifact-graph route <root>`; the runtime\n   returns exactly one action — invoke a named skill, request a human\n   approval, or report blocked with diagnostics.\n2. **Author through grilling.** Authoring skills interview you in frontier\n   rounds — every currently-answerable question at once, each with a\n   recommended answer. The agent gathers facts itself (subagent exploration);\n   you make decisions. Settled decisions are persisted with provenance.\n3. **Gate.** Requirements and Architecture (full chain) or Increment Intent\n   and Increment Design (light track) stop at human approval gates:\n   `artifact-graph approve <root> <artifact-id> <approved-by> <reason>`.\n4. **Plan → Tasks.** Plan registration materializes atomic Tasks, each with\n   bounded writes, exact source baselines, and one exact RED observation.\n5. **Execute.** `executing-ai-plan` reproduces RED, performs only the\n   authorized writes, runs the closed verification commands, and marks the\n   Task implemented — all through atomic public CLI transactions.\n6. **Review → validate → finalize.** One Machine Delivery Report per Task\n   (changes-required authorizes `rework`, with cascade invalidation and\n   ordered replay), ready Delivery Evidence, then `finalize-delivery`\n   independently re-runs every bound command and atomically produces the\n   `complete/DELIVERED` route.\n\n### Greenfield example\n\n```text\nYou:   Use Hufu to build a URL-shortener service in this empty repo.\nAgent: [routes] → profiling-project → registers PROF-SYS-001\n       [routes] → writing-ai-requirements → grilling rounds → REQ-SYS-001\n       → requests your approval (gate 1)\nYou:   artifact-graph approve . REQ-SYS-001 you \"scope agreed\"\nAgent: [routes] → designing-ai-architecture → ... (gate 2) → HLD → DLD →\n       Test Spec → Plan → materialize → executes Tasks under RED/GREEN →\n       per-Task reviews → evidence → finalize-delivery → DELIVERED\n```\n\n### Brownfield example\n\n```text\nYou:   Use Hufu: add CSV export to the reports page.\nAgent: [routes; Profile mode=existing] → writing-ai-increment\n       → blast-radius probe + grilling → INT-INC-001 (intent + acceptance)\n       → your approval (gate 1)\n       → designing-ai-increment → delta scope + exact RED bindings +\n         decision tree → DSN-INC-001 → your approval (gate 2)\n       → Plan → Tasks → execute → review → evidence → DELIVERED\n```\n\nIf the intent probe discovers the change is architecture-level, the intent is\nblocked with `REQUIRES_FULL_CHAIN` and the router walks you onto the full\nchain instead.\n\n### What the agent can never do\n\nApprove its own gated artifacts; write product code before\n`executing-ai-plan` is routed; touch files outside a Task's authorized\nwrites; skip a failed RED reproduction; edit manifests, hashes, approval\nrecords, or recorded evidence; or continue past any failed public command.\nEvery one of these is enforced by the runtime and its test suite, not by\nprompt discipline.\n\n## CLI reference\n\n```\nartifact-graph init <root> <project-id>                      initialize a project manifest\nartifact-graph register <root> <artifact-file>               register/refresh an exact-hash artifact\nartifact-graph validate <root>                               validate manifest + all artifact files\nartifact-graph approve <root> <id> <approved-by> <reason>    human approval for a gated artifact\nartifact-graph invalidate <root> <id> <reason>               invalidate an artifact + stale successors\nartifact-graph ready <root>                                  list executable Tasks\nartifact-graph coverage <root>                               requirement/test/task coverage counts\nartifact-graph route <root>                                  the single authoritative next action\nartifact-graph context <root> <expected-skill>               stable authoring context receipt\nartifact-graph materialize-plan <root> <plan-id>             atomically materialize Plan Tasks\nartifact-graph task <start|implement|rework|complete|block> <root> <task-id> [reason]\nartifact-graph finalize-delivery <root> <evidence-id>        independent replay → DELIVERED\n```\n\nAll commands print canonical JSON and fail closed with a nonzero exit code.\n\n## Trust model\n\n- **Exact-hash registration.** Every artifact is registered by full-file\n  SHA-256; edits invalidate dependents transitively (stale propagation).\n- **Closed Machine shapes.** JSON schemas and an independent runtime\n  validator must accept/reject identically (equivalence-tested).\n- **RED before implement.** A Task cannot start until its recorded failing\n  observation reproduces byte-for-byte.\n- **Independent replay.** Delivery finalization re-runs every bound command\n  itself and compares exit/stdout/stderr before `DELIVERED`.\n- **Evidence immutability.** Recorded evidence under `test-results/` is\n  add-only; superseded evidence is chained (`supersedes` + SHA-256\n  pointers), never rewritten.\n- **Sealed releases.** Each release seals its complete surface with an\n  independently re-derived verifier and an unbroken hash-bound\n  predecessor chain back to the runtime's first sealed release\n  (`v48 → … → latest`).\n\n## Project structure\n\n```\nhufu/\n├── skills/                  13 canonical skills (SKILL.md + references/)\n├── scripts/artifact-graph.mjs   the public runtime CLI\n├── scripts/                 test runner, suite policy, seal + evidence tooling\n├── lib/                     runtime internals (router, manifest, catalog, transactions)\n├── schemas/                 JSON Schemas mirrored by the runtime validators\n├── policies/                generated requirements label policies (v33…v38)\n├── adapters/                per-runtime discovery notes (Claude / Codex / Gemini)\n├── tests/                   contract, unit, integration, scenario suites\n├── test-results/            immutable recorded evidence + release seals\n└── docs/superpowers/        design specs and implementation plans (per release)\n```\n\n## Testing\n\n```bash\nnpm test                 # full suite: 31 batches, 1599 tests\nnpm run validate:fixture # runtime self-check against the bundled fixture\n```\n\nThe suite includes schema/runtime equivalence tests, router matrices,\nend-to-end CLI walks of both tracks (including a brownfield fixture with\nsuperseded full-chain history), a failure battery (forged evidence, source\ndrift, mixed-track abort — each asserting byte-identical manifests), and the\nrelease seal verifier.\n\n## Roadmap\n\n- Pressure-evidence campaigns for the two increment skills and refreshed\n  captures for the reworded skills (blind live-agent runs).\n- Multi-increment brownfield ergonomics (follow-on increments on delivered\n  projects).\n- Cross-skill wording consistency pass.\n\nSee `docs/superpowers/` for per-release specs, plans, and the sealed\nfollow-up ledger.\n\n## Contributing\n\nThe house rules are enforced by the contract suite — read them before\nopening a PR:\n\n- TDD is mandatory: RED observed before GREEN, evidence in the task report.\n- Machine JSON is closed: exact keys, no duplicates, errors never echo keys\n  or values.\n- `SKILL.md` files stay ≤ 700 words and start descriptions with \"Use when\".\n- Recorded evidence and historical `writing-ai-requirements-v*` tests are\n  immutable; retirement happens only through `scripts/test-suite-policy.mjs`\n  gates with measured-fact reasons.\n- Every release ends with a green clean-shell `npm test` and a new surface\n  seal.\n\n## License\n\n[MIT](LICENSE) © 2026 vpcoderli. The `package.json` stays `private: true`\nonly to prevent accidental npm publication; it does not affect this\nrepository's license.\n",
  "bytes": 18367,
  "sha": "72b3316a77b3ff927dd27c0d3e7737d262b81de92a321fe93d1574023763e0ed",
  "repo_slug": "vpcoderli/hufu",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_vpcoderli_hufu_288f4933/readme"
}