Requirements Agent

Self-contained Spec Circuit requirements agent: multi-persona BMAD review → quality score → refine → BRD → Markdown/PDF.

No Atlas / FastAPI / Mongo dependency. Configure LLMs in JSON, agent settings in YAML, run from CLI or Textual TUI.

Install & init

cd Requirement_Agent
pip install -e ".[dev]"

# Scaffold config in the current directory
req-agent init

# Or into ~/.config/requirements-agent/
req-agent init --global

npm launcher (optional)

The agent is Python. For npx / npm discoverability there is a thin wrapper in npm/:

cd npm && npm install && npm link
npx req-agent --help

Publish PyPI for the real package; publish npm only as the launcher (see npm/README.md).

One-shot release (same version on both registries; assumes you already ran twine/npm login):

./scripts/publish.sh           # current pyproject version
./scripts/publish.sh 0.2.0     # bump + publish
./scripts/publish.sh --dry-run # build only

init writes:

Configure LLMs (llms.json)

{
  "default": "azure-gpt4o",
  "models": {
    "azure-gpt4o": {
      "provider": "azure",
      "model": "gpt-4o",
      "deployment": "gpt-4o",
      "endpoint": "https://YOUR.openai.azure.com/",
      "api_key_env": "RA_AZURE_API_KEY",
      "temperature": 0.3
    },
    "ollama-llama": {
      "provider": "ollama",
      "model": "llama3.2",
      "endpoint": "http://127.0.0.1:11434/v1"
    },
    "mock": { "provider": "mock", "model": "mock" }
  }
}

List profiles: req-agent models

Configure agent (requirements-agent.yaml)

llm:
  models_file: ./llms.json
  active: azure-gpt4o          # or override with --profile

context:
  providers: [folder]
  folder_paths: [./docs]

prompts:
  personas:
    architect:
      system_extra: "Emphasize zero-trust boundaries."

export:
  default_format: both
  out_dir: ./out

Examples: config.example.yaml, llms.example.json. Legacy TOML still loads if present.

Env overrides: RA_CONFIG, RA_LLMS_JSON, RA_LLM_PROFILE, RA_LLM_PROVIDER, RA_LLM_MODEL, RA_API_KEY / OPENAI_API_KEY / RA_AZURE_*.

CLI

# Chat-first shell (TTY): 60% conversation / 40% progress, input always active
req-agent run \
  --title "Identity Hub SSO" \
  --design-file ./brief.md \
  --docs ./contracts/ \
  --profile azure-gpt4o \
  --out ./out/identity-hub

# Inside the shell:
#   /ref ./docs          attach references (menu via plain /ref)
#   /analyse             start Spec Circuit (also auto-starts from run)
#   /section 8           pin a section, then type plain English to refine
#   /report --format pdf
#   /stop                cancel
#   /help

# Headless / CI
req-agent run --title "..." --design-file brief.md --profile mock --plain --out ./out

# Continue against an existing report
req-agent chat -t "Identity Hub SSO" -f brief.md -r ./out/02-requirements-report.md --docs ./contracts/

# Interactive BA chat (pin section, plain-language refine, attach docs, score)
req-agent chat \
  --title "Identity Hub SSO" \
  --design-file ./brief.md \
  --report ./out/02-requirements-report.md \
  --docs ./contracts/ \
  --section "Non-functional"

req-agent refine --title "..." --design-file brief.md --report ./out/02-requirements-report.md \
  --list-sections
req-agent refine --title "..." --design-file brief.md --report ./out/02-requirements-report.md \
  --section "Non-functional" --message "Add p95 latency and availability targets"
# updates the same file immediately; optional --out to write elsewhere
req-agent refine -r ./out/02-requirements-report.md -t "..." -f brief.md -i   # interactive picker
req-agent consolidate --title "..." --design-file brief.md --report ./out/01-refined.md \
  --out ./out/02-requirements-report.md
req-agent export --report ./out/02-requirements-report.md --out ./out/report --format both

Context injection

Personas

Eight BMAD roles (vendored bmad-core-spec): orchestrator → analyst → pm → po → architect → dev → qa → sm.

TUIOS

Optional: when running inside tuios, the agent calls tuios set-agent-state. Force with RA_TUIOS_HOOK=1.

vs Atlas Requirements Architect

Same Spec Circuit brain and BMAD pack; Memory AI → local folder (future RAG/MCP); LLMs from llms.json instead of Mongo Settings. See REQUIREMENTS_ARCHITECT.md.