Multi-Agent Documentation Pattern
The Multi-Agent Documentation Pattern ensures SDLC artifacts receive comprehensive, multi-perspectiv
Multi-Agent Documentation Pattern
Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.
Overview
The Multi-Agent Documentation Pattern ensures SDLC artifacts receive comprehensive, multi-perspective review by having specialized agents collaborate on document creation. This approach produces higher-quality, more complete documentation than single-agent generation.
Pattern Architecture
Workflow
1. Primary Agent (Domain Expert)
↓ Creates initial draft
2. Working Draft (.aiwg/working/{type}/{name}/drafts/v0.1)
↓ Distributed to reviewers
3. Parallel Review (Responsible Roles from template metadata)
├─ Security Architect → security perspective
├─ Test Architect → testability perspective
├─ Requirements Analyst → requirements alignment
└─ Technical Writer → clarity and consistency
↓ Each adds inline comments/feedback
4. Documentation Archivist (tracks versions, manages workflow)
↓ Collects all feedback
5. Documentation Synthesizer (merges all perspectives)
↓ Resolves conflicts, creates unified document
6. Final Document (.aiwg/{type}/{name}.md - BASELINED)
↓ Archived for audit trail
7. Archive (.aiwg/archive/{date}/{name}/ - complete history)Roles
| Role | Responsibility | Model | When Invoked |
|---|---|---|---|
| Primary Author | Creates initial draft from domain expertise | opus | Always (starts workflow) |
| Responsible Reviewers | Provide domain-specific feedback | opus/sonnet | Parallel (after draft) |
| Technical Writer | Ensures clarity, consistency, quality | sonnet | Parallel (with reviewers) |
| Documentation Archivist | Manages versions, tracks workflow | sonnet | Throughout (version control) |
| Documentation Synthesizer | Merges feedback, resolves conflicts | opus | After all reviews complete |
Specialized Documentation Agents
Created for this pattern: 1. Documentation Synthesizer - Merges multi-agent feedback 2. Technical Writer - Clarity and consistency 3. Documentation Archivist - Version history and audit trails 4. Requirements Documenter - Requirements artifacts specialist 5. Architecture Documenter - Architecture artifacts specialist 6. Test Documenter - Test artifacts specialist
Existing domain agents used:
- Architecture Designer, Security Architect, Test Architect, Requirements Analyst, etc.
Template Metadata
Templates define collaboration structure via "Ownership & Collaboration" section:
## Ownership & Collaboration
- Document Owner: {primary-author-role}
- Contributor Roles: {reviewer-role-1}, {reviewer-role-2}, {reviewer-role-3}
- Automation Inputs: {what primary author needs}
- Automation Outputs: {final document path and name}Example (Software Architecture Document):
## Ownership & Collaboration
- Document Owner: Software Architect
- Contributor Roles: System Analyst, Designer, Test Architect
- Automation Inputs: Approved requirements set, non-functional drivers
- Automation Outputs: `software-architecture.md` including views and decisionsImplementation in Flow Commands
Step-by-Step Pattern
1. Initialize Documentation Workflow
# Archivist creates working directory structure
mkdir -p .aiwg/working/architecture/software-architecture-doc/{drafts,reviews,synthesis}
# Initialize metadata tracking
cat > .aiwg/working/architecture/software-architecture-doc/metadata.json <<EOF
{
"document-id": "software-architecture-doc",
"template-source": "~/.local/share/ai-writing-guide/.../software-architecture-doc-template.md",
"primary-author": "architecture-designer",
"reviewers": ["security-architect", "test-architect", "requirements-analyst", "technical-writer"],
"synthesizer": "architecture-documenter",
"status": "DRAFT",
"current-version": "0.1"
}
EOF2. Primary Author Creates Draft
# Architecture Designer reads template
TEMPLATE=~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/templates/analysis-design/software-architecture-doc-template.md
# Creates initial draft
# (Agent reads requirements, designs architecture, structures per template)
# Archivist saves v0.1
cp draft.md .aiwg/working/architecture/software-architecture-doc/drafts/v0.1-primary-draft.md3. Distribute for Parallel Review
# Launch all reviewers in parallel (single message, multiple Task tool calls)
# Each reviewer:
# - Reads v0.1 draft
# - Adds inline comments (<!-- ROLE: feedback -->)
# - Saves review summary to reviews/{role}-review.md
# - Updates draft to v0.2, v0.3, etc. (or same version with comments)4. Collect and Synthesize
# Synthesizer reads:
# - Latest draft with all inline comments
# - All review summaries from reviews/
# Synthesizer:
# - Resolves conflicts (documented in synthesis report)
# - Merges complementary feedback
# - Creates unified final document
# - Generates synthesis report
# Output final version
cp synthesized.md .aiwg/architecture/software-architecture-doc.md
# Generate synthesis report
cat > .aiwg/working/architecture/software-architecture-doc/synthesis/synthesis-report.md5. Archive Workflow
# Archivist archives complete workflow
mv .aiwg/working/architecture/software-architecture-doc \
.aiwg/archive/2025-10/software-architecture-doc-2025-10-15/
# Generate audit trail
cat > .aiwg/archive/2025-10/software-architecture-doc-2025-10-15/audit-trail.mdExample: flow-inception-to-elaboration Implementation
Step 3: Develop Architecture Baseline (SAD) - Multi-Agent Pattern
### Step 3: Develop Architecture Baseline (SAD)
Create comprehensive Software Architecture Document with multi-agent review.
**Multi-Agent Workflow:**
1. **Initialize** (Documentation Archivist)Create working structure
mkdir -p .aiwg/working/architecture/sad/{drafts,reviews,synthesis}
Read template metadata
TEMPLATE=~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/templates/analysis-design/software-architecture-doc-template.md
Extract responsible roles:
- Owner: architecture-designer (or architecture-documenter)
- Reviewers: security-architect, test-architect, requirements-analyst
- Writer: technical-writer
- Synthesizer: architecture-documenter
2. **Primary Draft** (Architecture Designer or Architecture Documenter)Architecture Designer provides technical design
Architecture Documenter structures into SAD template
Save v0.1
cp sad-draft.md .aiwg/working/architecture/sad/drafts/v0.1-primary-draft.md
3. **Parallel Review** (Launch all reviewers simultaneously)Use Task tool to launch in parallel:
- Security Architect: Validates security architecture
- Test Architect: Validates testability
- Requirements Analyst: Maps use cases to components
- Technical Writer: Ensures clarity and consistency
Each reviewer:
- Reads v0.1
- Adds inline feedback:
- Saves review: reviews/{role}-review.md
- Status: APPROVED | CONDITIONAL | NEEDS_WORK
4. **Synthesis** (Architecture Documenter + Documentation Synthesizer)Documentation Synthesizer:
- Reads all review feedback
- Resolves conflicts (e.g., TLS 1.3 vs 1.2 for test env)
- Merges complementary additions
- Creates unified final SAD
Architecture Documenter validates technical accuracy
Output final v1.0
cp sad-final.md .aiwg/architecture/software-architecture-doc.md
Generate synthesis report
cat > .aiwg/working/architecture/sad/synthesis/synthesis-report.md
5. **Archive** (Documentation Archivist)Archive complete workflow
mv .aiwg/working/architecture/sad \ .aiwg/archive/2025-10/sad-2025-10-15/
Generate audit trail
cat > .aiwg/archive/2025-10/sad-2025-10-15/audit-trail.md
**Output:** Software Architecture Document (BASELINED)
- Location: `.aiwg/architecture/software-architecture-doc.md`
- Status: BASELINED (all reviewers approved)
- Archive: `.aiwg/archive/2025-10/sad-2025-10-15/` (complete history)Benefits
Quality Improvements
1. Depth: Multiple expert perspectives vs. single agent 2. Completeness: Reviewers catch gaps (missing security, testability issues) 3. Accuracy: Domain experts validate technical correctness 4. Clarity: Technical writer ensures readability 5. Consistency: Terminology and structure uniform
Process Improvements
1. Traceability: Complete audit trail (versions, reviews, decisions) 2. Accountability: Clear ownership and sign-offs 3. Transparency: All feedback documented and addressed 4. Compliance: Meets audit requirements for documentation rigor
Example Quality Gains
Single-Agent Output:
- Architecture Designer creates SAD alone
- Missing: Security details, test strategy, requirements traceability
- Issues: Jargon heavy, inconsistent terminology
- Time: 2 hours (fast but incomplete)
Multi-Agent Output:
- Architecture Designer + 4 reviewers + synthesizer
- Complete: All sections filled, security validated, testability confirmed
- Quality: Professional, clear, consistent
- Time: 4 hours total (2h draft + 1h reviews + 1h synthesis)
- 2x time → 5x quality improvement
Directory Structure
Active Workflow
.aiwg/working/
├── document-index.json # Master index
├── architecture/
│ └── software-architecture-doc/
│ ├── drafts/
│ │ ├── v0.1-primary-draft.md
│ │ ├── v0.2-with-security-review.md
│ │ ├── v0.3-with-test-review.md
│ │ └── v0.4-synthesis-ready.md
│ ├── reviews/
│ │ ├── security-architect-review.md
│ │ ├── test-architect-review.md
│ │ ├── requirements-analyst-review.md
│ │ └── technical-writer-review.md
│ ├── synthesis/
│ │ └── synthesis-report.md
│ └── metadata.jsonFinal Output
.aiwg/architecture/
└── software-architecture-doc.md # BASELINED final versionArchive
.aiwg/archive/2025-10/
└── software-architecture-doc-2025-10-15/
├── drafts/ # All draft versions
├── reviews/ # All review feedback
├── synthesis/ # Synthesis report
├── metadata.json # Complete version history
└── audit-trail.md # Human-readable timelineAgent Coordination Examples
Example 1: Parallel Review (Preferred)
Launch all reviewers simultaneously:
# Pseudo-code for flow command
# Single message with multiple Task tool calls
reviewers = [
{"role": "security-architect", "task": "Review SAD security architecture"},
{"role": "test-architect", "task": "Review SAD testability"},
{"role": "requirements-analyst", "task": "Validate component mapping"},
{"role": "technical-writer", "task": "Review clarity and consistency"}
]
# Launch all in parallel (one message, multiple tool uses)
for reviewer in reviewers:
Task(
subagent_type=reviewer["role"],
description=reviewer["task"],
prompt=f"Review {draft_path} and provide {reviewer['role']} perspective feedback"
)
# Wait for all to complete, then proceed to synthesisExample 2: Sequential Review (When Dependencies Exist)
Reviews build on each other:
# Step 1: Security review (adds security section)
Task("security-architect", "Review and add security architecture")
# Step 2: Test review (builds on security section)
Task("test-architect", "Review testability including security test strategy")
# Step 3: Technical writer (polishes everything)
Task("technical-writer", "Review final draft for clarity")
# Step 4: Synthesize
Task("documentation-synthesizer", "Merge all feedback")Example 3: Iterative Review (Complex Documents)
Multiple review rounds:
# Round 1: Initial feedback
parallel_review(["security-architect", "test-architect"])
synthesize_round_1()
# Round 2: Address conflicts
parallel_review(["security-architect", "test-architect"]) # Re-review
synthesize_round_2()
# Round 3: Final polish
parallel_review(["technical-writer"])
final_synthesis()Template Path Reference
All templates located at:
~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/templates/Key templates:
- `analysis-design/software-architecture-doc-template.md`
- `analysis-design/architecture-decision-record-template.md`
- `requirements/use-case-spec-template.md`
- `requirements/supplemental-specification-template.md`
- `test/master-test-plan-template.md`
- `test/test-strategy-template.md`
Agents have read-only access to the agent-owned install operation location via Claude settings.
Success Metrics
Quality:
- 100% of required sections completed (vs. ~60% single-agent)
- Zero critical gaps flagged in reviews
- All responsible roles sign off (APPROVED or CONDITIONAL)
Traceability:
- Complete audit trail (versions, reviews, decisions)
- Bidirectional links (requirements ↔ components ↔ tests)
- Synthesis report documents all changes
Timeliness:
- Parallel review: Complete in 1 business day
- Sequential review: 2-3 business days
- Iterative review: 3-5 business days
Common Patterns by Document Type
| Document Type | Primary Author | Reviewers | Synthesizer | Pattern |
|---|---|---|---|---|
| SAD | Architecture Designer | Security Architect, Test Architect, Requirements Analyst, Technical Writer | Architecture Documenter | Parallel |
| Master Test Plan | Test Architect | Test Engineer, Security Architect, DevOps Engineer, Technical Writer | Test Documenter | Parallel |
| Use Case Specs | Requirements Analyst | Architecture Designer, Test Engineer, Technical Writer | Requirements Documenter | Parallel |
| Risk Report | Project Manager | Architecture Designer, Security Architect, Requirements Analyst | Documentation Synthesizer | Sequential |
| ADR | Architecture Designer | Security Architect, Technical Writer | Architecture Documenter | Sequential |
Error Handling
Incomplete reviews:
- Archivist tracks pending reviewers
- Alerts after 1 business day SLA breach
- Escalate to flow coordinator if blocked
Conflicting feedback:
- Synthesizer documents all conflicts
- Resolves based on domain expertise hierarchy:
- Security matters: Security Architect decides
- Testing matters: Test Architect decides
- Architecture patterns: Architecture Designer decides
- Escalates unresolvable conflicts to PM/Executive Sponsor
Missing metadata:
- Flow command infers responsible roles from document type
- Requests clarification if ambiguous
- Proceeds with best-effort review assignment
Integration with SDLC Flows
Flows using multi-agent pattern:
- `/flow-inception-to-elaboration` (SAD, Risk Report, Requirements Baseline)
- `/flow-elaboration-to-construction` (ABM Report, Master Test Plan)
- `/flow-construction-to-transition` (Deployment Plans, ORR)
- `/flow-deploy-to-production` (Deployment Reports)
Each flow implements: 1. Initialize working directory (Archivist) 2. Primary draft creation (Domain agent) 3. Parallel review (Responsible roles) 4. Synthesis (Synthesizer + domain agent) 5. Baseline final document (Archivist) 6. Archive workflow (Archivist)