Agent Fabric Requirements

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

Requirement intelligence utilities for turning requirement sources into agent-fabric-adapters candidate import bundles.

agent-fabric-requirements is the external intelligence layer around the Fabric ecosystem. It may parse documents, prepare chunks, run extraction, or later connect to Unstructured and RAG pipelines, but its handoff boundary stays simple: it emits agent-fabric.requirement-candidate-import/v1 JSON for @hongruimu/agent-fabric-adapters.

Status

Early MVP. The current CLI is dependency-free and deterministic. It reads Markdown/text sources, can normalize Unstructured-exported JSON elements, can build/query a local keyword RAG index, and emits review-required candidate JSON. It does not install or call Unstructured, vector databases, OpenAI APIs, or any remote service.

Package Role

• @hongruimu/agent-fabric: portable workflow protocol, validation, and runtime generation.
• @hongruimu/agent-fabric-adapters: adapter planning plus source registry, candidate import, review, status, and trace gates.
• @hongruimu/agent-fabric-blueprints: project shapes and feature orchestration.
• @hongruimu/agent-fabric-requirements: requirement intelligence before adapters, ending at candidate JSON.

Requirements

• Node.js >=22.6.0

Quick Start

Create a review workspace from a Markdown/text source:

agent-fabric-requirements prepare ./examples/welcome-prd.md \
  --source-id welcome-prd \
  --project web \
  --project api \
  --output ./requirements-work

Try the real requirements runbook fixture:

npm run demo:runbook

This starts from examples/real-requirements-runbook/source/unstructured-elements.json and writes normalized documents, a local RAG index, candidate JSON, validation, and inspection output under .tmp/real-requirements-runbook-demo/.

This writes a compact review workspace:

requirements-work/
  source/welcome-prd.md
  normalized-document.json
  candidate-import.json
  validation.json
  inspection.json
  README.md

Review candidate-import.json, validation.json, and inspection.json, then import the candidate bundle into adapters.

The lower-level commands remain available when you need to inspect or replace each handoff step manually.

Normalize a Markdown/text source into the parser handoff contract:

agent-fabric-requirements normalize \
  --input ./examples/welcome-prd.md \
  --source-id welcome-prd \
  --output ./normalized-document.json

Normalize JSON elements already exported by Unstructured:

agent-fabric-requirements normalize \
  --input ./unstructured-elements.json \
  --backend unstructured-json \
  --source-id member-profile-prd \
  --output ./normalized-document.json

Need to create that JSON from a real PDF, DOCX, HTML, or mixed source first? See docs/unstructured-python-recipe.md for a copyable Python Unstructured export recipe, then use docs/parser-artifact-contract.md and docs/real-requirements-runbook.md for the governed source-to-feature workflow.

Build and query a local deterministic RAG index from normalized documents:

agent-fabric-requirements rag index \
  --input-normalized ./normalized-document.json \
  --input-normalized ./architecture-normalized.json \
  --output ./rag-index.json

agent-fabric-requirements rag query \
  --index ./rag-index.json \
  --query "member profile avatar api" \
  --format text

Local RAG is deterministic lexical retrieval, not vector search. See docs/local-rag-contract.md for the scoring and warning contract, and docs/context-corpus-hygiene.md for corpus selection rules.

Generate a candidate import bundle from a Markdown requirement source:

agent-fabric-requirements extract \
  --input ./examples/welcome-prd.md \
  --source-id welcome-prd \
  --project web \
  --project api \
  --output ./candidate-import.json

Or generate the candidate bundle from the normalized document contract:

agent-fabric-requirements extract \
  --input-normalized ./normalized-document.json \
  --context-index ./rag-index.json \
  --context-limit 5 \
  --project web \
  --project api \
  --output ./candidate-import.json

When --context-index is provided, matching local RAG entries are attached as supporting sourceReferences and rag-context trace links. The candidate still remains review-required and must go through adapters governance.

Validate and inspect the bundle before handing it to adapters:

agent-fabric-requirements validate --input ./candidate-import.json --format text
agent-fabric-requirements inspect --input ./candidate-import.json --format text

Import the generated bundle into adapters:

agent-fabric-adapters requirements candidate import \
  --target ./requirements \
  --input ./candidate-import.json

Then continue the existing governed loop:

agent-fabric-adapters requirements candidate review \
  --target ./requirements \
  --candidate REQ-CAND-001 \
  --decision approved \
  --reviewer product-owner

agent-fabric-adapters requirements status --target ./requirements --format text

agent-fabric-blueprints feature run \
  --target ./workspace \
  --source candidate \
  --requirements ./requirements \
  --candidate REQ-CAND-001 \
  --project web \
  --project api \
  --change welcome-message

Flow Inputs And Outputs

The user-facing flow should stay short, but the internal handoff has explicit files so every step can be reviewed, tested, and replaced.

requirement source
  -> requirements review workspace
  -> normalized document
  -> candidate import bundle
  -> adapters candidate governance
  -> promoted requirement source
  -> exported requirement bundle
  -> blueprint feature workspace

| Stage | Command | Input | Output | Purpose | | --- | --- | --- | --- | --- | | Source | human or external system | Product requirement material such as Markdown, text, future PDF, Word, HTML, or OCR output. | Original source file, for example prd.md. | Preserve the raw source of truth before any extraction. | | Prepare | agent-fabric-requirements prepare | prd.md. | requirements-work/ containing copied source, normalized document, candidate import, validation, inspection, and README. | Compress the local source-to-review path without taking over adapters governance. | | Normalize | agent-fabric-requirements normalize | prd.md or another parser-readable source. | normalized-document.json with schemaVersion: "agent-fabric.normalized-document/v1". | Convert source content into ordered, parser-neutral elements with source references. | | Normalize Unstructured | agent-fabric-requirements normalize --backend unstructured-json | Unstructured element JSON array or { "elements": [...] }. | normalized-document.json with parser metadata name: "unstructured". | Accept complex document parsing output without coupling the npm package to Python, APIs, or OCR configuration. | | Local RAG Index | agent-fabric-requirements rag index | One or more normalized documents. | rag-index.json with schemaVersion: "agent-fabric.local-rag-index/v1". | Build a deterministic local retrieval index for requirement and project context. | | Local RAG Query | agent-fabric-requirements rag query | rag-index.json plus query text. | Ranked local matches with source references. | Inspect which context would support extraction before attaching it to candidates. | | Extract | agent-fabric-requirements extract --input-normalized | normalized-document.json. | candidate-import.json with schemaVersion: "agent-fabric.requirement-candidate-import/v1". | Convert normalized elements into review-required candidate requirement units. | | Validate | agent-fabric-requirements validate | candidate-import.json. | Validation report, usually stdout or validation.json. | Check candidate JSON structure before governance import. | | Inspect | agent-fabric-requirements inspect | candidate-import.json. | Inspection report, usually stdout or inspection.json. | Summarize quality signals such as acceptance criteria, source references, related projects, open questions, low confidence, and review-required state. | | Candidate Import | agent-fabric-adapters requirements candidate import | candidate-import.json. | requirements-source/candidates/REQ-CAND-001.json. | Store candidate requirements inside the adapters governance workspace. | | Review | agent-fabric-adapters requirements candidate review | requirements-source/candidates/REQ-CAND-001.json. | Updated approved or rejected candidate with review evidence. | Record human/process review without treating extraction output as automatically approved. | | Promote | agent-fabric-adapters requirements promote | Approved candidate. | requirements-source/requirements.json and requirements-source/units/REQ-001.md. | Convert an approved candidate into a formal requirement source unit. | | Status | agent-fabric-adapters requirements status | requirements-source/. | Readiness report with blocking reasons and next actions. | Gate downstream feature work on governance readiness. | | Export | agent-fabric-adapters requirements export | requirements-source/. | requirements/manifest.json and requirements/units/REQ-001.md. | Produce the requirement bundle consumed by feature orchestration. | | Feature Work | agent-fabric-blueprints feature run --source candidate or feature prepare | Approved candidate or exported requirement bundle. | OpenSpec change files and .planning/features/<change>/ handoff files. | Prepare implementation-ready feature context for agents. |

Typical generated files from the current demo:

requirements-work/source/welcome-prd.md
normalized-document.json
candidate-import.json
requirements-source/candidates/REQ-CAND-001.json
requirements-source/requirements.json
requirements-source/units/REQ-001.md
requirements/manifest.json
requirements/units/REQ-001.md

The important boundary is that agent-fabric-requirements stops at candidate generation and local quality checks. agent-fabric-adapters owns review, promote, status, and export. agent-fabric-blueprints owns feature work package generation.

Commands

prepare

Creates a local review workspace from one source file:

agent-fabric-requirements prepare ./prd.md \
  --project web \
  --project api \
  --output ./requirements-work

Internally this runs the same deterministic chain as the manual commands:

source file
  -> normalize
  -> extract --input-normalized
  -> validate
  -> inspect

It does not call adapters, approve candidates, promote requirements, export bundles, run feature work, call Unstructured, call RAG, or call an AI API.

Options:

• <source-file> or --input <file>: requirement source file.
• --output <dir>: review workspace directory. Defaults to ./requirements-work.
• --source-id <id>: stable source ID used by adapters.
• --candidate-id <id>: candidate ID. Defaults to REQ-CAND-001.
• --title <title>: override extracted title.
• --project <id>: related project ID. May be repeated.
• --format json|text: output summary format. Defaults to json.

normalize

Converts a Markdown/text source into agent-fabric.normalized-document/v1:

agent-fabric-requirements normalize --input ./prd.md --source-id prd --output ./normalized-document.json

This is a deterministic local parser for contract testing and fixture generation. Use --backend unstructured-json to convert JSON elements already exported by Unstructured. The package still does not install Python dependencies, run OCR, or call Unstructured services.

Options:

• --input <file>: requirement source file.
• --output <file>: write output to a file instead of stdout.
• --source-id <id>: stable source ID used for source references.
• --media-type <type>: override detected media type.
• --parser-name <name>: parser name metadata.
• --parser-mode <mode>: parser mode metadata.
• --backend deterministic|unstructured-json: parser backend. Defaults to deterministic.
• --format json|text: output format. Defaults to json.

rag

Builds and queries a deterministic local context index from normalized documents:

agent-fabric-requirements rag index \
  --input-normalized ./normalized-document.json \
  --input-normalized ./architecture-normalized.json \
  --output ./rag-index.json

agent-fabric-requirements rag query \
  --index ./rag-index.json \
  --query "member profile avatar api" \
  --limit 5 \
  --format text

Options:

• rag index --input-normalized <file>: add a normalized document. May be repeated.
• rag query --index <file>: read a local RAG index JSON file.
• --query <text>: query text for local retrieval.
• --limit <n>: maximum matches. Defaults to 5.
• --output <file>: write output to a file instead of stdout.
• --format json|text: output format. Defaults to json.

extract

Converts a Markdown/text source into agent-fabric.requirement-candidate-import/v1:

agent-fabric-requirements extract --input ./prd.md --source-id prd --output ./candidate.json

It can also read agent-fabric.normalized-document/v1:

agent-fabric-requirements extract --input-normalized ./normalized-document.json --output ./candidate.json

To attach local RAG context as supporting source references:

agent-fabric-requirements extract \
  --input-normalized ./normalized-document.json \
  --context-index ./rag-index.json \
  --context-limit 5 \
  --project web \
  --project api \
  --output ./candidate.json

Options:

• --input <file>: requirement source file.
• --input-normalized <file>: normalized document JSON file. Use either --input or --input-normalized.
• --output <file>: write output to a file instead of stdout.
• --source-id <id>: stable source ID used by adapters.
• --candidate-id <id>: candidate ID. Defaults to REQ-CAND-001.
• --title <title>: override extracted title.
• --context-index <file>: local RAG index JSON for supporting references. Applies to normalized input.
• --context-limit <n>: maximum RAG context matches. Defaults to 5.
• --project <id>: related project ID. May be repeated.
• --format json|text: output format. Defaults to json.

validate

Validates candidate import JSON before adapters import:

agent-fabric-requirements validate --input ./candidate-import.json --format text

The report includes valid, structural errors, quality warnings, and candidate summary counts.

inspect

Summarizes candidate quality signals without changing the bundle:

agent-fabric-requirements inspect --input ./candidate-import.json --format text

Use this before agent-fabric-adapters requirements candidate import to catch missing acceptance criteria, source references, related projects, or low confidence.

Extraction Rules

The MVP extractor is intentionally conservative:

• normalize uses Markdown headings, paragraphs, and list items to create ordered normalized elements.
• Uses the first Markdown # heading as the candidate title.
• Uses the first normal paragraph outside special sections as the statement.
• Reads acceptance criteria from headings containing Acceptance, Criteria, or 验收.
• Reads open questions from headings containing Question, 问题, or 待确认.
• Adds an open question when acceptance criteria are missing.
• Marks all output automation.reviewRequired: true.
• Records source references and generation metadata.
• Attaches local RAG matches only as supporting references and rag-context trace links.
• Provides local validation and inspection before adapters import.

Integration Boundary

This package is allowed to become smarter, but adapters should remain the governance gate. Unstructured and RAG integrations still emit the same candidate import protocol instead of bypassing review.

See docs/mvp.md for current scope, docs/normalized-document-contract.md for the parser handoff contract, docs/unstructured-python-recipe.md for producing Unstructured element JSON from real documents, docs/unstructured-and-rag.md for the current Unstructured/RAG path, docs/real-requirements-runbook.md for the practical governance workflow, schemas/agent-fabric.normalized-document.schema.json for the machine-readable schema, and docs/intelligence-roadmap.md for the staged intelligence roadmap.

For a copyable requirements-to-adapters handoff demo, see docs/adapters-integration.md or run:

npm run demo:adapters

Development

npm test
npm run verify

License

MIT