/document

allowed-tools: Read, Write, Bash(fd:*), Bash(rg:*), Bash(git:*), Bash(jq:*), Bash(gdate:*), Task
name: "Document"
description: "Generate comprehensive user-facing documentation with intelligent analysis and state management"
author: "wcygan"
tags: ["docs","generate"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N 2>/dev/null || date +%s000000000 2>/dev/null || echo "session-$(date +%s)000000000"`
• Current directory: !`pwd`
• Target scope: $ARGUMENTS
• Project files: !`fd "(package\.json|Cargo\.toml|go\.mod|deno\.json|pom\.xml|build\.gradle)" . | head -5 || echo "No project files detected"`
• Documentation status: !`fd "(README\.md|CHANGELOG\.md)" . | head -3 || echo "No existing documentation"`
• API specs: !`fd "(openapi\.(yaml|yml|json)|swagger\.(yaml|yml|json)|\.proto$)" . | head -5 || echo "No API specifications found"`
• Config files: !`fd "(config\.(yaml|yml|json|toml)|\.(env|example)$)" . | head -5 || echo "No config files found"`
• Source code files: !`fd "\.(js|ts|go|rs|java|py|rb|php|cs|swift|kt)$" . | wc -l | tr -d ' ' || echo "0"`
• Git repository: !`git status --porcelain 2>/dev/null | head -3 || echo "Not a git repository"`
• Recent commits: !`git log --oneline -5 2>/dev/null || echo "No git history"`
• Technology stack: !`rg "(import|require|use|from)" . --type typescript --type javascript --type rust --type go | head -5 || echo "No imports detected"`

Your Task

Generate comprehensive, user-facing documentation through systematic analysis and intelligent content creation.

STEP 1: Initialize documentation generation session

• CREATE session state file: `/tmp/documentation-session-$SESSION_ID.json`
• SET initial state:

  {
    "sessionId": "$SESSION_ID",
    "phase": "discovery",
    "scope": "$ARGUMENTS or all",
    "project_info": {},
    "documentation_plan": [],
    "generated_files": [],
    "analysis_results": {}
  }

STEP 2: Project discovery and analysis

Think hard about the optimal documentation strategy based on project complexity and structure.

IF source code files > 100 OR multiple project files detected:

• USE sub-agent delegation for comprehensive analysis
• SET scope to "comprehensive"
• CREATE inter-agent communication directory: `/tmp/doc-agents-$SESSION_ID/`

ELSE IF $ARGUMENTS contains specific flags (--readme-only, --changelog-only, etc.):

• SET scope to "targeted"
• FOCUS on specified documentation type

ELSE:

• PERFORM sequential analysis
• SET scope to "standard"

STEP 3: Strategic documentation analysis

FOR comprehensive scope:

• DELEGATE to 5 parallel sub-agents:

1. **Project Structure Agent**: Analyze codebase architecture and technology stack

• SAVE findings to: `/tmp/doc-agents-$SESSION_ID/structure-analysis.json`

2. **API Documentation Agent**: Extract API endpoints, schemas, and specifications

• SAVE findings to: `/tmp/doc-agents-$SESSION_ID/api-analysis.json`

3. **Configuration Agent**: Document environment variables and configuration options

• SAVE findings to: `/tmp/doc-agents-$SESSION_ID/config-analysis.json`

4. **Git History Agent**: Analyze commits for changelog generation

• SAVE findings to: `/tmp/doc-agents-$SESSION_ID/changelog-analysis.json`

5. **Usage Patterns Agent**: Identify CLI commands, scripts, and usage examples

• SAVE findings to: `/tmp/doc-agents-$SESSION_ID/usage-analysis.json`

FOR targeted scope:

• ANALYZE only the requested documentation type
• FOCUS analysis on specific requirements

FOR standard scope:

• PERFORM sequential analysis of all documentation needs
• PRIORITIZE based on project characteristics

STEP 4: Documentation generation strategy

CASE documentation_type: WHEN "readme" OR "all":

• GENERATE README.md with sections:
• Project overview from package metadata
• Technology stack badges and detection
• Installation instructions (auto-detected package manager)
• Usage examples from scripts and CLI commands
• Development setup and contribution guidelines
• API documentation links (if applicable)

WHEN "changelog" OR "all":

• ANALYZE git history for conventional commits
• GROUP commits by type: feat, fix, docs, refactor, test, chore
• EXTRACT breaking changes and version information
• GENERATE structured CHANGELOG.md with:
• Semantic versioning based on commit types
• Grouped changes by release version
• Links to issues and pull requests
• Release dates and contributor attribution

WHEN "api-docs" OR "all":

• DETECT API specification format (OpenAPI, gRPC, GraphQL)
• PARSE specification files for endpoint documentation
• GENERATE human-readable API documentation
• CREATE endpoint examples and authentication guides
• INCLUDE error handling and response documentation

STEP 5: Content generation and file creation

TRY:

• CREATE documentation files based on analysis results
• APPLY project-specific templates if available
• ENSURE consistent formatting and structure
• VALIDATE markdown syntax and links

FOR EACH documentation file to generate:

1. **Load or synthesize analysis data** 2. **Apply intelligent content generation** 3. **Use project-specific context and examples** 4. **Validate output quality and completeness** 5. **Save to appropriate location**

CATCH (generation_failed):

• LOG errors to session state
• CONTINUE with partial generation
• PROVIDE manual generation guidance
• SAVE progress for resumability

STEP 6: Documentation optimization and enhancement

• APPLY SEO-friendly heading hierarchy
• GENERATE appropriate badges and metadata
• CREATE table of contents for longer documents
• ADD social media preview metadata
• ENSURE accessibility with alt text and semantic structure

STEP 7: Quality assurance and validation

• VALIDATE all generated markdown syntax
• CHECK internal and external link functionality
• VERIFY code examples and configuration accuracy
• ENSURE all public APIs are documented
• TEST documentation completenes