Requirements Agent architecture

How the self-contained CLI agent turns a brief and local docs into a Spec Circuit draft, quality score, gap-driven refine, and Markdown/PDF — without Atlas, FastAPI, or Mongo.

How to use: HOW_TO_USE.md · open via req-agent docs --open

Shipped inside the installed package under requirements_agent/docs/. Copy with req-agent docs --copy ./docs.

Shell experience Spec Circuit pipeline Refine & export Local knowledge & config External Transcript to Progress pane Progress to Composer Worker to Prompt Assembler Prompt Assembler to Personas Prompts to BMAD pack Folder Memory to Worker /fix to Confirm Confirm to Export Session to Export paths Personas to LLM Quality to LLM /fix refine to LLM Shell to tuios hooks Config to Worker User to Shell Shell to Worker analyse Worker gathers folder context Context into personas Draft scored Gaps to /fix Refine then confirm Export report RequirementsShell Transcriptboards + /fix list Progress panestages · personas Composer/fix · /stop · /exit Shell Workerworker.py Prompt Assemblerbuild_system_prompt BMAD PersonasREVIEW_PIPELINE /fix Nactions.py Confirmyes · undo Exportmd · pdf Quality &Questions Folder Memory Shell Sessionsession.py · ./out BMAD Packbmad-core-spec Configllms.json · yaml tuiosagent rail LLM Providers You 1 2 3 4 5 6 7 8 1Primary analyse → refine → export loop Direct call External system

Scroll sideways to see the full diagram.

Hover or focus a component to trace what it sends to and receives from.

The CLI loop

From brief + refs to gap-driven refine and files under ./out.

  1. 1You open the shell (req-agent start) and set title, brief, and /ref docs.
  2. 2/analyse starts the Shell Worker (soft-cancel with /stop).
  3. 3Folder Memory injects referenced files into the context bundle.
  4. 4Eight BMAD personas write sequential ## sections into the Spec Circuit draft.
  5. 5Quality scoring + open-question extraction produce gaps and a numbered fix list.
  6. 6/fix N maps the item to a section and runs one refine LLM call.
  7. 7Confirm board: yes keeps the change, undo reverts.
  8. 8/report writes Spec Circuit, BRD, quality JSON, and optional PDF.

Gap-driven refine

One command replaces manual BA mapping of gaps → /section.

  • Unified list Quality gaps first, then open questions — indices match /gaps and /questions.
  • /fix N [guidance] Auto-pins best ## via token overlap; otherwise full document.
  • One LLM call Crafted instruction → existing refine → confirm board.
  • Aliases /gap and /resolve.

Shell layout

Textual app — chat-first, input always live.

  • Transcript (~60%) Chat, refine board, findings, confirm.
  • Progress (~40%) Stages, personas, live markdown preview.
  • Composer Messages and /commands; /stop mid-run.
  • Worker Background thread; queues prompts while busy.

BMAD personas

Same review pack as Atlas, vendored under packs/bmad-core-spec.

  • 1–2 Orchestrator → Analyst
  • 3–4 PM → PO
  • 5–6 Architect → Developer
  • 7–8 QA → Scrum Master

LLM & prompt config

Credentials in llms.json; behaviour in requirements-agent.yaml.

  • llms.json Named profiles: provider, model, endpoint, api_key_env, temperature.
  • llm.active Or --profile / RA_LLM_PROFILE to pick one.
  • prompts.step_instruction / guiderails Optional global Spec Circuit overrides.
  • personas.*.system_extra Append guidance per role (preferred).
  • personas.*.system_override Replace entire system prompt for one role.

vs Scrum Studio

Same Spec Circuit brain; different delivery.

  • CLI No FastAPI / Mongo / Electron — files under ./out.
  • Memory Folder /ref today; RAG & MCP stubs later.
  • Refine /fix N instead of web approve UI.
  • ADO / backlog Not in CLI v1 (stub in /ref picker).