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

# Preferred: open the shell, set everything in chat
req-agent start
# optional: -p azure-gpt5.4

# Inside the shell:
#   /title Identity Hub SSO
#   /brief ./brief.md
#   /ref ./contracts/
#   /analyse          (also /run)
#   /exit

# Same as start (flags are optional shortcuts)
req-agent run
req-agent run -t "Identity Hub SSO" -f ./brief.md --docs ./contracts/ -p azure-gpt5.4

# 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/
# Or from the shell: /open ./out/02-requirements-report.md

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

TUIOS is a terminal window manager (minimize m, close x, zoom z, workspaces, dock/rail, Inbox). Those controls are chrome around the pane, not widgets we draw inside req-agent.

Recommended: run the agent inside TUIOS so the rail shows state:

tuios                    # then in a pane:
req-agent start
# or: RA_TUIOS_HOOK=1 req-agent start

When detected (or with RA_TUIOS_HOOK=1), we report:

• tuios set-agent-state — working / needs_input (confirm) / idle / done / errored
• OSC 9;4 progress % — shown in TUIOS title/progress where supported

Jump to a waiting agent with TUIOS Inbox keys (see Agents track). Hooks: tuios.dev/docs/hooks.

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.