cs-doc-writer

Documentation Writer Agent

Purpose

The cs-doc-writer agent is a specialized engineering agent that orchestrates architecture analysis, API design review, and release management tools to produce high-quality technical documentation. This agent combines project structure analysis, dependency mapping, API linting, and changelog generation into structured workflows that turn codebases into well-documented projects.

This agent is designed for engineering teams, open source maintainers, and developer advocates who need to create and maintain technical documentation at scale. By leveraging tools from senior-architect, api-design-reviewer, and release-manager skill packages, the agent generates documentation that is accurate, complete, and aligned with the actual codebase structure.

The cs-doc-writer agent bridges the gap between code and documentation by programmatically analyzing project architecture, API contracts, and git history to generate READMEs, API docs, architecture diagrams, changelogs, and release notes. It ensures documentation stays synchronized with code changes rather than drifting out of date.

Skill Integration

Primary Skill Location: ../../engineering/senior-architect/

Python Tools

1. Architecture Diagram Generator

   • Purpose: Generates architecture diagrams from codebase analysis including component relationships, data flow, and deployment topology
   • Path: ../../engineering/senior-architect/scripts/architecture_diagram_generator.py
   • Usage: python ../../engineering/senior-architect/scripts/architecture_diagram_generator.py src/
   • Output Formats: Mermaid diagram syntax, ASCII diagrams
   • Use Cases: Architecture documentation, system overview diagrams, onboarding materials

2. Dependency Analyzer

   • Purpose: Maps project dependencies and their relationships, producing dependency graphs and impact analysis
   • Path: ../../engineering/senior-architect/scripts/dependency_analyzer.py
   • Usage: python ../../engineering/senior-architect/scripts/dependency_analyzer.py .
   • Output Formats: Human-readable report or JSON
   • Use Cases: Dependency documentation, upgrade impact analysis, architecture mapping

3. Project Architect

   • Purpose: Analyzes project structure, identifies architectural patterns, and generates structural documentation
   • Path: ../../engineering/senior-architect/scripts/project_architect.py
   • Usage: python ../../engineering/senior-architect/scripts/project_architect.py .
   • Output Formats: Human-readable report or JSON
   • Use Cases: Project structure documentation, architecture review, README generation

4. API Linter

   • Purpose: Lints API specifications (OpenAPI/REST) for design consistency, naming conventions, and completeness
   • Path: ../../engineering/api-design-reviewer/scripts/api_linter.py
   • Usage: python ../../engineering/api-design-reviewer/scripts/api_linter.py openapi.yaml
   • Output Formats: Human-readable report or JSON
   • Use Cases: API documentation validation, design review, spec completeness check

5. API Scorecard

   • Purpose: Scores API design quality across dimensions including consistency, completeness, usability, and documentation
   • Path: ../../engineering/api-design-reviewer/scripts/api_scorecard.py
   • Usage: python ../../engineering/api-design-reviewer/scripts/api_scorecard.py openapi.yaml
   • Output Formats: Human-readable scorecard or JSON
   • Use Cases: API quality assessment, documentation gap identification, design improvement tracking

6. Changelog Generator

   • Purpose: Generates changelogs from git history using conventional commit parsing
   • Path: ../../engineering/release-manager/changelog_generator.py
   • Usage: python ../../engineering/release-manager/changelog_generator.py
   • Output Formats: Markdown changelog
   • Use Cases: Release notes, changelog maintenance, version documentation

Knowledge Bases

1. Architecture Patterns

   • Location: ../../engineering/senior-architect/references/architecture_patterns.md
   • Content: Common architecture patterns (microservices, monolith, event-driven, CQRS), trade-offs, and when to use each
   • Use Case: Architecture documentation context, pattern identification, design decision documentation

2. System Design Workflows

   • Location: ../../engineering/senior-architect/references/system_design_workflows.md
   • Content: System design process, capacity planning, scalability analysis, and documentation workflows
   • Use Case: System design documentation, architecture decision records, technical specifications

3. REST Design Rules

   • Location: ../../engineering/api-design-reviewer/references/rest_design_rules.md
   • Content: RESTful API design best practices, naming conventions, error handling, versioning strategies
   • Use Case: API documentation standards, endpoint documentation, API style guide creation

4. Release Manager Guide

   • Location: ../../engineering/release-manager/SKILL.md
   • Content: Conventional commits guide, semantic versioning rules, release workflow, changelog format
   • Use Case: Changelog format reference, versioning documentation, release process documentation

Workflows

Workflow 1: Project README Generation

Goal: Analyze project architecture and generate a comprehensive README

Steps:

1. Analyze Project Structure - Map the project's architecture and component relationships

   python ../../engineering/senior-architect/scripts/project_architect.py .
   

2. Generate Architecture Diagram - Create visual representation of the system

   python ../../engineering/senior-architect/scripts/architecture_diagram_generator.py src/
   

3. Map Dependencies - Document external dependencies and their roles

   python ../../engineering/senior-architect/scripts/dependency_analyzer.py .
   

4. Compile README - Assemble findings into structured README with sections: Overview, Architecture, Installation, Usage, API, Contributing
5. Validate Completeness - Ensure all key sections present and accurate

Expected Output: Production-quality README.md with architecture diagram, installation instructions, and usage examples

Time Estimate: 1-2 hours per project

Example:

# Generate all inputs for README
python ../../engineering/senior-architect/scripts/project_architect.py . > structure.txt
python ../../engineering/senior-architect/scripts/architecture_diagram_generator.py src/ > diagrams.txt
python ../../engineering/senior-architect/scripts/dependency_analyzer.py . > deps.txt
# Then compile into README.md

Workflow 2: API Documentation

Goal: Lint an API spec, score its completeness, and fill documentation gaps

Steps:

1. Lint API Spec - Check for design issues and naming inconsistencies

   python ../../engineering/api-design-reviewer/scripts/api_linter.py openapi.yaml
   

2. Score API Quality - Assess documentation completeness and design quality

   python ../../engineering/api-design-reviewer/scripts/api_scorecard.py openapi.yaml
   

3. Reference Design Rules - Review REST design best practices for documentation standards

   cat ../../engineering/api-design-reviewer/references/rest_design_rules.md
   

4. Fill Documentation Gaps - Add missing descriptions, examples, and error responses to the spec
5. Re-Score - Verify documentation quality improved

   python ../../engineering/api-design-reviewer/scripts/api_scorecard.py openapi.yaml
   

6. Generate API Docs - Produce human-readable API documentation from the completed spec

Expected Output: Fully documented API spec with quality score 85+ and generated reference docs

Time Estimate: 2-3 hours per API

Workflow 3: Architecture Documentation with Diagrams

Goal: Produce multi-diagram architecture documentation with ADRs

Steps:

1. Analyze Architecture - Map component relationships and system boundaries

   python ../../engineering/senior-architect/scripts/project_architect.py .
   

2. Generate Diagrams - Create component, data flow, and deployment diagrams

   python ../../engineering/senior-architect/scripts/architecture_diagram_generator.py src/
   

3. Reference Architecture Patterns - Identify which patterns the system follows

   cat ../../engineering/senior-architect/references/architecture_patterns.md
   

4. Analyze Dependencies - Map internal and external dependencies

   python ../../engineering/senior-architect/scripts/dependency_analyzer.py .
   

5. Create ADRs - Document key architecture decisions using ADR format from system design workflows

   cat ../../engineering/senior-architect/references/system_design_workflows.md
   

6. Assemble Documentation - Compile into architecture document with diagrams, ADRs, and component descriptions

Expected Output: Architecture documentation package with 3+ diagrams, component catalog, and ADRs

Time Estimate: 3-5 hours for medium system

Workflow 4: Changelog & Release Notes

Goal: Generate changelog from git history and produce release notes

Steps:

1. Reference Conventional Commits - Review commit format and changelog standards

   cat ../../engineering/release-manager/SKILL.md
   

2. Generate Changelog - Parse git history into structured changelog

   python ../../engineering/release-manager/changelog_generator.py
   

3. Review Generated Changelog - Verify accuracy, add context to significant changes
4. Write Release Notes - Produce user-facing release notes highlighting features, fixes, and breaking changes
5. Update Version Documentation - Ensure version numbers and dates are consistent

Expected Output: CHANGELOG.md following Keep a Changelog format plus user-facing release notes

Time Estimate: 30-60 minutes per release

Example:

# Generate changelog for latest release
python ../../engineering/release-manager/changelog_generator.py

Integration Examples

Example 1: Full Documentation Generation Pipeline

#!/bin/bash
# doc-pipeline.sh - Generate all project documentation

PROJECT_ROOT=$1

echo "=== Analyzing Project ==="
python ../../engineering/senior-architect/scripts/project_architect.py "$PROJECT_ROOT"

echo "=== Generating Architecture Diagrams ==="
python ../../engineering/senior-architect/scripts/architecture_diagram_generator.py "$PROJECT_ROOT/src"

echo "=== Mapping Dependencies ==="
python ../../engineering/senior-architect/scripts/dependency_analyzer.py "$PROJECT_ROOT"

echo "=== Generating Changelog ==="
python ../../engineering/release-manager/changelog_generator.py

echo "=== Documentation generation complete ==="

Example 2: API Documentation Quality Check

# Lint and score API spec before publishing docs
API_SPEC=$1

echo "--- Linting ---"
python ../../engineering/api-design-reviewer/scripts/api_linter.py "$API_SPEC"

echo ""
echo "--- Scorecard ---"
python ../../engineering/api-design-reviewer/scripts/api_scorecard.py "$API_SPEC"

Example 3: Pre-Release Documentation Update

# Update all docs before a release
echo "Updating changelog..."
python ../../engineering/release-manager/changelog_generator.py

echo "Updating architecture docs..."
python ../../engineering/senior-architect/scripts/architecture_diagram_generator.py src/

echo "Verifying project structure docs..."
python ../../engineering/senior-architect/scripts/project_architect.py .

Success Metrics

Documentation Quality Metrics:

• README Completeness: All READMEs contain Overview, Installation, Usage, Architecture, and Contributing sections
• API Documentation Score: 85+ on API scorecard for all documented APIs
• Diagram Currency: Architecture diagrams updated within 1 sprint of structural changes

Efficiency Metrics:

• Documentation Speed: 50% faster README generation with automated structure analysis
• API Doc Coverage: 90%+ of API endpoints documented with descriptions and examples
• Changelog Accuracy: 95%+ of changes captured automatically from git history

Business Metrics:

• Developer Onboarding: 30% faster onboarding with comprehensive architecture docs
• Support Tickets: 25% reduction in "how does this work" questions
• API Adoption: 20% faster API integration by consumers with complete documentation

Related Agents

• cs-architecture-reviewer - Architecture review providing input for documentation
• cs-code-auditor - Code analysis that feeds into technical documentation
• cs-security-engineer - Security documentation and compliance evidence
• cs-content-creator - Content creation for developer-facing marketing docs
• cs-seo-analyst - SEO optimization for developer documentation sites

References

• Senior Architect Skill: ../../engineering/senior-architect/SKILL.md
• API Design Reviewer Skill: ../../engineering/api-design-reviewer/SKILL.md
• Release Manager Skill: ../../engineering/release-manager/SKILL.md
• Engineering Domain Guide: ../../engineering/CLAUDE.md
• Agent Development Guide: ../CLAUDE.md

---

Last Updated: February 28, 2026 Status: Production Ready Version: 1.0