Skip to main content
File: agents/sdlc/03-documentation.md · Model: Sonnet · Tools: Bash, Read, Write

​
Purpose

The documentation agent produces the professional, enterprise-grade documents that get sent to the client for sign-off: a Business Requirements Document, a Functional Requirements Document, and a draft Statement of Work. It writes for two audiences at once — “the engineer who picks this up at midnight with no context, and the executive who needs the key decision in 30 seconds” — and treats vague language as a real risk, since a sentence like “the system will support user roles” is exactly the kind of gap that turns into a disputed change request three months later. It is also the first stage to write spec-anchor.md, a short orientation document that every later stage (04–14) reads first when its own context is full.

​
How it works

Input: $RSTACK_RUN_DIR/artifacts/requirements/requirement_spec.json (stage 02’s output). The agent stops and reports which upstream agent needs to run if this file is missing, and reports the parse error if it’s malformed. Context budget: stage 3 of 15, capped at 5 files read before writing begins; if requirement_spec.json is large (>200 lines) it reads only functional_requirements, non_functional_requirements, and out_of_scope. Spec anchor first. Before any client document, it writes ${RUN_BASE}artifacts/spec-anchor.md — run id, one-sentence goal, primary stack, top 5 core requirements, out-of-scope summary, key constraints, and a stage-status line (00=PASS 01=PASS 02=PASS 03=IN_PROGRESS 04=PENDING ...). This is the “steering document” pattern: it survives context compaction and gives any downstream agent orientation in under 200 tokens. Adopted runs (brownfield). If the run was created by rstack-agents adopt, the agent checks manifest.json for "mode": "adopt" and looks for a harvested documentation.json tagged "source": "brownfield-adoption". If found, that baseline’s docs array indexes the project’s real existing documents — the agent reads those first as the authoritative record, and only writes BRD/FRD/SOW content for the change being made or for gaps the baseline exposes. It never regenerates documentation for functionality that already ships. Once oriented, it runs four tasks against $RSTACK_RUN_DIR/artifacts/documents/: Every requirement ID in the FRD must trace back to an ID in requirement_spec.json — that’s a pinned quality rule, not just a convention.

​
Output contract

documentation_output.json is what the next stage reads:
The agent file itself mixes two path conventions: the newer .rstack/runs/<run_id>/artifacts/ layout used by the Spec Anchor and Context Recovery sections, and the legacy $RSTACK_RUN_DIR/artifacts/documents/ layout used by the Task 1–4 instructions (with a documented legacy fallback lookup at $RSTACK_RUN_DIR/artifacts/documents/). Both are honored by the agent’s own recovery logic — this page describes both rather than picking one.

​
Optional publishing step

After generating the local files, the agent offers an interactive publishing menu — local-only (default), Confluence, Notion, SharePoint/OneDrive, PDF export (via the pdf skill), or a combination. Each remote option is gated on the relevant credentials being present (CONFLUENCE_URL/CONFLUENCE_TOKEN/CONFLUENCE_SPACE_KEY, NOTION_API_KEY/NOTION_DATABASE_ID, or an MS Graph token); the choice is recorded in user_preferences.documentation_platform.

​
Gate and handoff

There is no dedicated validator profile named in this stage’s agent file — its own Quality Self-Check is the mechanism: before reporting done, it verifies the BRD covers every business goal from the transcript, the FRD traces every functional requirement to a source ID, and a non-technical reader would follow the executive summary. Any “no” answer means fix it before reporting status (“a fast DONE_WITH_CONCERNS is better than a wrong DONE”). Completion is reported as STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT, following the shared Task Contract shape in agents/OPERATING-STANDARD.md. BLOCKED covers a missing or malformed requirement_spec.json; NEEDS_CONTEXT is used to ask one question about a critical document gap. On success, the agent hands off directly to the Planning Agent (stage 04), passing documentation_output.json and requirement_spec.json as inputs and instructing it not to stop until the next agent is triggered in turn.

​
Where it sits in the pipeline

Stage 03 sits between 02 — Requirements (its input) and 04 — Planning (its handoff target), in the documentation/requirements branch of the pipeline alongside 10-summary — see the pipeline overview’s routing map.