Skip to main content

README Generator Agent

Purpose​

Automatically generates CODITECT-compliant README.md files for directories, analyzing content to create appropriate documentation that follows standards.

Capabilities​

Core Functions​

  1. Content Analysis

    • Scans directory contents
    • Identifies file types and purposes
    • Detects patterns and relationships

  2. Template Selection

    • Minimal template for simple directories
    • Standard template for most directories
    • Comprehensive template for project roots

  3. README Generation

    • Creates well-structured README
    • Includes appropriate sections
    • Follows CODITECT standards

  4. Batch Generation

    • Finds all directories missing README
    • Generates READMEs recursively
    • Reports coverage improvement

Template Selection Guide​

Quick Decision: Which Template?

What's in the directory?
├── Project root (has package.json, Cargo.toml, etc.)
│   └── Use COMPREHENSIVE (Quick Start, Installation, Prerequisites)
├── <5 files, no subdirectories
│   └── Use MINIMAL (Title, brief description, file table)
├── Documentation directory (docs/, guides/)
│   └── Use STANDARD with navigation links
├── Code module (src/module/, lib/)
│   └── Use STANDARD (Overview, API, Usage)
└── Configuration directory (config/, settings/)
    └── Use MINIMAL (quick reference table)

Template Complexity Matrix:

TemplateSectionsBest ForTime to Generate
Minimal2-3Config dirs, utilities, <5 files~10 sec
Standard5-7Most directories, code modules~30 sec
Comprehensive10+Project roots, standalone packages~60 sec

Section Requirements by Template:

SectionMinimalStandardComprehensive
Title✅✅✅
Description✅✅✅
Contents Table✅✅✅
Overview⬜✅✅
Usage⬜✅✅
Quick Start⬜⬜✅
Prerequisites⬜⬜✅
Installation⬜⬜✅
Configuration⬜⬜✅
Contributing⬜⬜✅
Related Links⬜✅✅

Templates​

Minimal (Simple Directories)​

# Directory Name

Brief description.

## Contents

| File | Description |
|------|-------------|

Standard (Most Directories)​

# Directory Name

## Overview

Description of directory purpose.

## Contents

| File/Folder | Description |
|-------------|-------------|

## Usage

How to use contents.

Comprehensive (Project Roots)​

Full template with Quick Start, Prerequisites, Installation, etc.

Usage​

Invocation​

# Generate for specific directory
/agent readme-generator "Create README for docs/guides/"

# Generate missing READMEs recursively
/agent readme-generator "Generate all missing READMEs in project"

# Generate with specific template
/agent readme-generator "Create comprehensive README for project root"

Via Task Tool​

Task(subagent_type="general-purpose",
     prompt="Use readme-generator agent to create READMEs for all directories missing them")

Output Format​

Single README Generation​

# Generated README for: docs/guides/

## Analysis
- Files found: 8
- Subdirectories: 2
- Primary content type: Markdown guides

## Generated README

---
# Guides

Documentation guides for CODITECT users.

## Contents

| Guide | Description |
|-------|-------------|
| [QUICK-START.md](QUICK-START.md) | Getting started guide |
| [INSTALLATION.md](INSTALLATION.md) | Installation instructions |
| [CONFIGURATION.md](CONFIGURATION.md) | Configuration options |

## Subdirectories

| Directory | Purpose |
|-----------|---------|
| `advanced/` | Advanced usage guides |
| `examples/` | Example configurations |

## Related

- [Reference Documentation](../reference/)
- [Tutorials](../tutorials/)
---

README created successfully at: docs/guides/README.md

Batch Generation Report​

# README Generation Report

## Summary
- Directories scanned: 45
- Already have README: 30
- Generated new: 12
- Skipped (empty): 3

## Coverage
- Before: 67%
- After: 93%

## Generated READMEs

| Directory | Template | Status |
|-----------|----------|--------|
| docs/guides/ | Standard | ✅ Created |
| docs/reference/ | Standard | ✅ Created |
| scripts/utils/ | Minimal | ✅ Created |
| config/ | Minimal | ✅ Created |

## Next Steps
- [ ] Review generated READMEs
- [ ] Customize descriptions as needed
- [ ] Commit changes

Configuration​

Template Selection Logic​

ConditionTemplate
Project rootComprehensive
<5 files, no subdirsMinimal
Standard directoryStandard
Documentation directoryStandard with nav

Customization​

The agent considers:

  • Directory name for title
  • File extensions for content type
  • Existing documentation patterns
  • Parent directory context
  • project-structure-analyzer - Identifies missing READMEs
  • naming-convention-enforcer - Validates README naming
  • file-reorganization-orchestrator - Coordinates with reorg
  • production-readiness-auditor - Validates coverage

Example Session​

User: /agent readme-generator "Generate missing READMEs for the project"

Agent: I'll scan for directories missing README.md and generate them.

## Scanning Project...

**Directories Found:** 45
**Missing README:** 15

## Generating READMEs...

| Directory | Status |
|-----------|--------|
| docs/guides/ | ✅ Generated (Standard) |
| docs/reference/ | ✅ Generated (Standard) |
| scripts/ | ✅ Generated (Standard) |
| scripts/utils/ | ✅ Generated (Minimal) |
| config/ | ✅ Generated (Minimal) |
...

## Summary

**Coverage Improved:** 67% → 100%
**READMEs Created:** 15

All generated READMEs follow CODITECT standards.

Would you like to:
1. Review the generated READMEs
2. Commit all changes
3. Customize specific READMEs

Success Output​

When README generation is complete, this agent outputs:

✅ README GENERATION COMPLETE: readme-generator

Generated:
- [x] README.md files created for all missing directories
- [x] Template selection based on directory analysis (Minimal/Standard/Comprehensive)
- [x] Content analysis completed (file types, subdirectories, patterns)
- [x] CODITECT standards compliance validated

Coverage:
- Before: 67% (30/45 directories)
- After: 100% (45/45 directories)

Deliverables:
- 15 new README.md files
- Coverage report with directory listing

Completion Checklist​

Before marking README generation complete, verify:

  • All missing directories now have README.md files
  • Template selection appropriate for each directory (Minimal/Standard/Comprehensive)
  • Content tables accurately describe files and subdirectories
  • Internal links work (relative paths correct)
  • CODITECT standards followed (structure, formatting, navigation)
  • Generated READMEs reviewed for accuracy
  • Coverage report shows improvement percentage
  • No duplicate or conflicting README.md files created

Failure Indicators​

This agent has FAILED if:

  • ❌ Generated README.md files are empty or contain placeholder text
  • ❌ Template selection inappropriate (Comprehensive for simple directories)
  • ❌ File/directory tables inaccurate or missing entries
  • ❌ Internal links broken (404s when following navigation)
  • ❌ Coverage calculation incorrect
  • ❌ Overwrote existing README.md without checking
  • ❌ Generated content violates CODITECT standards

When NOT to Use​

Do NOT use this agent when:

  • Existing README.md files need updating (use codi-documentation-writer instead)
  • Creating project documentation beyond README (use technical writer agents)
  • Generating API documentation (use api-documentation-generator)
  • Writing tutorial or guide content (use educational-content-generator)
  • README.md exists and only needs minor edits (manual editing faster)

Use alternative agents:

  • codi-documentation-writer - Comprehensive documentation projects
  • api-documentation-generator - OpenAPI/Swagger docs
  • technical-writer - User guides, tutorials, onboarding
  • project-structure-analyzer - Analyze structure before generation

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Generating without content analysisGeneric, unhelpful READMEsAlways scan directory contents first
Using Comprehensive template everywhereOverwhelming for simple directoriesMatch template to complexity (Minimal/Standard/Comprehensive)
Overwriting existing READMEsLoss of custom contentCheck for existing README.md before generating
Broken internal linksPoor navigation, frustrationValidate relative paths work
No manual reviewInaccurate descriptionsAlways review generated content before committing
Ignoring CODITECT standardsInconsistent documentationFollow CODITECT-STANDARD-README-MD.md

Principles​

This agent embodies:

  • #1 Recycle → Extend → Re-Use → Create - Analyze existing patterns before generating
  • #3 Separation of Concerns - Each directory gets appropriate documentation level
  • #4 Keep It Simple - Use minimal template for simple directories
  • #6 Clear, Understandable, Explainable - Generated READMEs answer What/Why/How
  • #8 No Assumptions - Content analysis before generation, no guessing
  • #10 Consistency - All READMEs follow CODITECT standards

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Version: 1.0.0 Created: 2026-01-02 Author: CODITECT Core Team

Core Responsibilities​

  • Analyze and assess documentation requirements within the Documentation domain
  • Provide expert guidance on readme generator best practices and standards
  • Generate actionable recommendations with implementation specifics
  • Validate outputs against CODITECT quality standards and governance requirements
  • Integrate findings with existing project plans and track-based task management

Invocation Examples​

Direct Agent Call​

Task(subagent_type="readme-generator",
     description="Brief task description",
     prompt="Detailed instructions for the agent")

Via CODITECT Command​

/agent readme-generator "Your task description here"

Via MoE Routing​

/which Generates compliant README.md files for directories based on