Agent Fabric

Documentation: https://hongruimu.github.io/packages/agent-fabric

Portable agent workflow toolkit for OpenSpec, GSD-style planning, Superpowers quality gates, and multi-runtime agent instructions.

Agent Fabric turns a small project configuration into a reusable agent workflow baseline:

• Agent Registry for multi-project boundaries.
• Quality-gate policy inspired by Superpowers discipline.
• Phase wrapper metadata for OpenSpec + GSD-style planning.
• Runtime instructions for Claude, Codex, and Gemini.
• Local verification suites and generated runtime drift checks.

Links

• Documentation: https://hongruimu.github.io/packages/agent-fabric
• Website: https://hongruimu.github.io/
• npm: https://www.npmjs.com/package/@hongruimu/agent-fabric

Status

Early preview. The CLI is dependency-free and runs on Node.js 24+ with experimental type stripping.

Requirements

• Node.js >=24.0.0
• No runtime npm dependencies for the current preview CLI
• Node.js 24 is the project baseline because local workflow capability provisioning may execute provider CLIs such as @opengsd/gsd-core that require Node.js >=24.0.0.

The published CLI uses a small JavaScript wrapper that runs the TypeScript source from a temporary runtime directory with Node.js type stripping, so agent-fabric and agentfabric work as package binaries after npm installation.

Quick Start

Run without installing:

npx -p @hongruimu/agent-fabric agent-fabric init-config --preset web-api --stdout
npx -p @hongruimu/agent-fabric agent-fabric schema > agent-fabric.schema.json
npx -p @hongruimu/agent-fabric agent-fabric init-config --preset web-api --output agent-fabric.config.json
npx -p @hongruimu/agent-fabric agent-fabric doctor --config agent-fabric.config.json
npx -p @hongruimu/agent-fabric agent-fabric init --config agent-fabric.config.json --target .
npx -p @hongruimu/agent-fabric agent-fabric generate --runtime all --target .
npx -p @hongruimu/agent-fabric agent-fabric verify --target .
npx -p @hongruimu/agent-fabric agent-fabric handoff start --target . --change <change-id> --phase <phase-id> --write
npx -p @hongruimu/agent-fabric agent-fabric handoff complete --target . --change <change-id> --phase <phase-id> --check

Or install as a project-local dev tool:

npm install -D @hongruimu/agent-fabric
agent-fabric init-config --preset web-api --output agent-fabric.config.json
agent-fabric schema > agent-fabric.schema.json
agent-fabric doctor --config agent-fabric.config.json
agent-fabric init --config agent-fabric.config.json --target .
agent-fabric generate --runtime all --target .
agent-fabric verify --target .
agent-fabric handoff start --target . --change <change-id> --phase <phase-id> --write
agent-fabric handoff complete --target . --change <change-id> --phase <phase-id> --check

For an already initialized Agent Fabric workspace, generate a portable config draft from workflow sources:

agent-fabric inspect --target . --stdout
agent-fabric inspect --target . --output agent-fabric.config.json
agent-fabric inspect --target . --from legacy-yaml --stdout

For step-by-step migration paths, see docs/migration.md.

For release validation and publishing steps, see docs/release.md.

Commands

init-config

Generates a starter agent-fabric.config.json from a reusable preset:

agent-fabric init-config --preset web-api --output agent-fabric.config.json
agent-fabric init-config --preset monorepo --output agent-fabric.config.json
agent-fabric init-config --preset multi-project --output agent-fabric.config.json
agent-fabric init-config --preset web-api --stdout

Available presets:

• web-api: apps/web and apps/api.
• monorepo: apps/app and packages/core.
• multi-project: apps/web, apps/api, and apps/admin.

init

Generates portable workflow files:

• agent-workflow/agents.json
• agent-workflow/capabilities.json
• agent-workflow/policies.json
• agent-workflow/phase-wrappers.json
• agent-workflow/verification.json
• agent-workflow/templates/implementation-log.md
• agent-workflow/templates/phase-handoff.md
• openspec/config.yaml
• openspec/project.md
• openspec/schemas/agent-fabric-governed/schema.yaml
• openspec/schemas/agent-fabric-governed/templates/proposal.md
• openspec/schemas/agent-fabric-governed/templates/design.md
• openspec/schemas/agent-fabric-governed/templates/tasks.md
• openspec/schemas/agent-fabric-governed/templates/spec.md
• openspec/changes/_template/proposal.md
• openspec/changes/_template/design.md
• openspec/changes/_template/tasks.md
• openspec/specs/_template/spec.md
• .planning/README.md
• .planning/PROJECT.md
• .planning/STATE.md
• .planning/ROADMAP.md
• .planning/phases/_template/CONTEXT.md
• .planning/phases/_template/OPEN_SPEC_HANDOFF.md
• .planning/phases/_template/PLAN.md
• .planning/phases/_template/SUMMARY.md
• .planning/phases/_template/UAT.md
• .planning/phases/_template/VERIFICATION.md
• tools/agent-workflow-verify.sh

capabilities.json records project-local workflow capabilities without vendoring third-party skill content. The default Codex capabilities point to official/provider-owned provisioning for OpenSpec, GSD Core, and Superpowers:

agent-fabric capabilities provision --target . --runtime codex

Agent Fabric uses this file to route generated runtime instructions to local skills such as .agents/skills/openspec-*/SKILL.md, .codex/skills/gsd-*/SKILL.md, and .codex/skills/superpowers-*/SKILL.md; OpenSpec, GSD Core, and Superpowers remain responsible for maintaining their skill content.

Initialized projects opt in to the explicit agent-fabric-governed OpenSpec schema. This project-local schema adds Fabric governance templates without shadowing OpenSpec package schemas such as spec-driven.

inspect

Reads initialized workflow sources and writes an agent-fabric.config.json draft:

agent-fabric inspect --target . --stdout
agent-fabric inspect --target . --output agent-fabric.config.json
agent-fabric inspect --target . --from auto --stdout
agent-fabric inspect --target . --from fabric-json --stdout
agent-fabric inspect --target . --from legacy-yaml --stdout
agent-fabric inspect --target . --from codex-agents --stdout
agent-fabric inspect --target . --from claude-agents --stdout
agent-fabric inspect --target . --from gemini-agents --stdout
agent-fabric inspect --target . --from codex-agents --stdout --report

Importers:

• auto: prefer Fabric JSON sources, then legacy YAML sources, then Codex AGENTS.md, then Claude .claude/agents/*.md, then Gemini GEMINI.md.
• fabric-json: require initialized agent-workflow/*.json sources.
• legacy-yaml: require legacy agent-workflow/*.yml sources.
• codex-agents: parse AGENTS.md runtime instructions into a reviewable config draft.
• claude-agents: parse .claude/agents/*.md runtime instructions into a reviewable config draft.
• gemini-agents: parse GEMINI.md runtime instructions into a reviewable config draft.

Use --report to print an inspect gap report to stderr without corrupting JSON stdout. The report highlights conservative placeholders and runtime-only migration gaps such as missing policies, missing phase wrappers, unknown stacks, <review-required> fields, and default-only verification suites.

Current JSON sources:

• agent-workflow/agents.json
• agent-workflow/policies.json
• agent-workflow/phase-wrappers.json
• agent-workflow/verification.json

Legacy YAML migration sources are also supported when JSON sources do not exist:

• agent-workflow/agents.yml
• agent-workflow/policies.yml
• agent-workflow/phase-wrappers.yml

Codex runtime migration is best-effort because Markdown runtime files may omit machine-readable fields. Missing values are filled with conservative placeholders such as unknown or <review-required>.

generate

Generates runtime instructions from agent-workflow/agents.json:

agent-fabric generate --runtime claude --target .
agent-fabric generate --runtime codex --target .
agent-fabric generate --runtime gemini --target .
agent-fabric generate --runtime all --target .
agent-fabric generate --runtime codex --target . --stdout
agent-fabric generate --runtime all --target . --check
agent-fabric generate --runtime claude --target . --agent demo-web-agent --stdout

Outputs:

• Claude: .claude/agents/*.md
• Codex: AGENTS.md
• Gemini: GEMINI.md

Use --stdout to preview generated output without writing files. Use --check to detect generated runtime drift without overwriting files. Use --agent <project|agent> with --runtime claude to preview or write a single Claude agent file.

schema

Prints the JSON Schema for agent-fabric.config.json:

agent-fabric schema > agent-fabric.schema.json

The published schema is also available at schemas/agent-fabric.schema.json. Add a $schema field to your config for editor autocomplete:

{
  "$schema": "./schemas/agent-fabric.schema.json"
}

verify

Runs source validation and checks generated runtime files for drift:

agent-fabric verify --target .
agent-fabric verify --list --target .
agent-fabric verify --suite --target .

verify --suite runs commands from agent-workflow/verification.json in order and stops on the first failing command.

handoff start

Creates or previews the bridge files that bind a GSD phase to an OpenSpec change without translating requirements into an execution plan:

agent-fabric handoff start --target . --change <change-id> --phase <phase-id> --check
agent-fabric handoff start --target . --change <change-id> --phase <phase-id> --write

--check reports the files that would be created or updated without writing them. --write creates missing CONTEXT.md and OPEN_SPEC_HANDOFF.md files under .planning/phases/<phase-id>/, updates .planning/STATE.md, and appends OpenSpec references to existing bridge files when they are not already linked. It does not create PLAN.md, VERIFICATION.md, SUMMARY.md, or UAT.md; GSD remains responsible for planning and execution evidence, while OpenSpec remains the durable requirements checklist.

handoff complete

Checks whether a GSD phase can safely prove completion for an OpenSpec change without modifying either source of truth:

agent-fabric handoff complete --target . --change <change-id> --phase <phase-id> --check

The check verifies that the OpenSpec change files exist, the GSD CONTEXT.md and PLAN.md reference the same change, VERIFICATION.md records command evidence, SUMMARY.md records completion evidence, and tasks.md has no unchecked outcome tasks. This is a read-only bridge; execution logs remain in .planning/, while OpenSpec remains the durable contract.

capabilities provision

Runs the official provisioning commands recorded in agent-workflow/capabilities.json and verifies expected local skill paths:

agent-fabric capabilities provision --target . --runtime codex
agent-fabric capabilities provision --target . --runtime codex --list

The default Codex capabilities run the recorded OpenSpec, GSD Core, and Superpowers provider commands that install or refresh local workflow skills. Use --list to inspect commands without executing external tools.

doctor

Validates Agent Fabric source files before runtime generation:

agent-fabric doctor --config agent-fabric.config.json
agent-fabric doctor --target .

Checks include:

• agent-fabric.config.json shape when --config is provided.
• agent-workflow/agents.json registry shape, scopes, runtime agent metadata, and required lists.
• agent-workflow/policies.json risk levels, quality gates, and tool-layer metadata.
• agent-workflow/phase-wrappers.json lifecycle inputs, outputs, and required gates.
• agent-workflow/verification.json configured command suite shape.
• Required planning, workflow, and handoff templates.
• Agent Fabric governed OpenSpec schema files when openspec/config.yaml selects agent-fabric-governed.

Config Shape

The config is intentionally generic. Project-specific rules live in config, not in Agent Fabric source:

• workflow.scope: human-readable scope rendered into every runtime.
• workflow.sourceOfTruth: ordered authoritative artifacts for agents to follow.
• workflow.runtimeRules: shared operating rules for Claude, Codex, and Gemini outputs.
• policies: optional quality policy model for principles, risk levels, gates, fast path, and runtime adaptation.
• phaseWrappers: optional lifecycle model for phase inputs, outputs, tools, gates, fallbacks, and migration rules.
• projects[].root: logical project root used for boundaries and generated docs.
• projects[].actualPath: optional concrete filesystem path for linked projects outside the controller workspace.
• verification.commands: optional command suite persisted to agent-workflow/verification.json and runnable with verify --suite.
• capabilities.capabilities: optional capability contracts persisted to agent-workflow/capabilities.json; use this to route runtimes to official local skills or external workflow tools without copying their implementation into AGENTS.md.

Example Config

See examples/agent-fabric.config.json for the current config shape.

Fabric Model

Agent Fabric abstracts four project-local layers:

• agent-workflow/: agent boundaries, quality gates, phase wrappers, and handoff templates.
• openspec/: facts, change intent, designs, tasks, and stable specs.
• .planning/: GSD-style execution state, plans, verification evidence, and summaries.
• Runtime files: generated Claude, Codex, and Gemini instructions.
• Validation: doctor checks source contracts; verify adds generated runtime drift checks.

See docs/fabric-model.md for the full model and portability rules.

Package Boundaries

• @hongruimu/agent-fabric owns the portable file protocol, validation, and runtime generation.
• @hongruimu/agent-fabric-adapters owns tool adapter planning and requirements governance gateways.
• @hongruimu/agent-fabric-blueprints owns reusable project shapes and feature orchestration.

For the governed requirement-to-feature loop, start with @hongruimu/agent-fabric-adapters docs/requirements-governance-overview.md, then use @hongruimu/agent-fabric-blueprints docs/governed-feature-loop.md for feature package generation.

Development

npm test
npm run verify

Project Governance

• Releases are tracked in CHANGELOG.md.
• Contributions should follow CONTRIBUTING.md and pass npm run verify.
• Security issues should be reported through the private disclosure process in SECURITY.md.
• Community participation is covered by CODE_OF_CONDUCT.md.

Contributing

Issues and pull requests are welcome. Please run npm run verify before opening a pull request.

License

MIT