AgileFlow

README Updater

PreviousNext

README specialist for auditing and updating all documentation files across project folders.

README Updater Agent

The README Updater Agent (AG-README-UPDATER) is your specialist in auditing and updating README.md files across your project. This agent ensures that folder documentation stays current, accurately describes contents, and provides clear navigation between related sections.

Capabilities

  • README Auditing: Scan folders and identify documentation gaps, outdated information, and missing file descriptions
  • Content Documentation: Document all files and folders in a folder with clear descriptions
  • Navigation Links: Ensure clear navigation between related folders and parent/child directories
  • Structure Standardization: Apply consistent README format across all project folders
  • Broken Link Detection: Identify and fix links that point to non-existent files or folders
  • Folder-Specific Guidance: Understand purpose and conventions for each folder type (00-meta through 10-research)
  • Parallel Execution: Work independently on assigned folder when spawned by /readme-sync command

When to Use

Use this agent when you need to:

  • Audit all READMEs across your project (via /agileflow:readme-sync)
  • Update a specific folder's README to reflect current contents
  • Add documentation to a folder that's missing README.md
  • Ensure consistent navigation and cross-folder linking
  • Fix broken documentation links
  • Update README after adding/removing files from a folder
  • Create documentation for new project folders
  • Standardize README format across teams

How It Works

  1. Context Loading: Agent reads expertise file and scans assigned folder (via /readme-sync)

  2. Audit: Agent lists all files/folders in target folder and reads current README (if exists)

  3. Gap Analysis: Agent identifies:

    • Files not documented in README
    • Files mentioned in README that no longer exist
    • Outdated descriptions or folder purpose
    • Broken navigation links
    • Missing "how to use" guidance

  4. Planning: Agent proposes improvements:

    • Better folder structure documentation
    • Updated file descriptions
    • Fixed or added navigation links
    • New sections (How to Use, Known Issues, Next Steps)

  5. Updating: Agent uses Edit tool (if README exists) or Write tool (if creating new) to apply improvements

  6. Reporting: Agent summarizes what was added/updated/removed

Example

# Single folder update
/agileflow:readme-updater
> "Update README for docs/02-practices/ folder"
 
# Parallel update of all folders
/agileflow:readme-sync
> "Audit and update all README.md files across docs/"

The README Updater Agent would:

  1. Scan docs/02-practices/ for all files
  2. Read current README.md
  3. Identify missing files (testing.md, security.md, etc.)
  4. Identify broken links
  5. Update README with complete file list
  6. Add clear "How to Use" section
  7. Fix navigation links to parent/related folders
  8. Report: "Updated docs/02-practices/README.md - added 3 sections, fixed 2 links, documented all files"

Key Behaviors

  • Complete File List: Every file in folder should be documented in README
  • Clear Descriptions: Each file description explains purpose and when to use it
  • Navigation First: READMEs provide clear paths to parent, related, and child folders
  • Current Information: Automatically updates when folder contents change
  • Consistent Format: Uses standard README template across all folders
  • No Broken Links: All cross-folder links are verified
  • Helpful to New Users: READMEs assume reader doesn't know project structure

Tools Available

This agent has access to:

  • Bash: Discover files/folders (ls, find, wc commands)
  • Read: Read current README and understand structure
  • Edit: Update existing README.md files
  • Write: Create new README.md files
  • Glob: Find files by pattern
  • Grep: Search documentation content

Standard README Structure

Every README.md follows this template for consistency:

# Folder Name
 
[1-2 sentence description of folder purpose]
 
## Contents
 
- **File/Folder 1** - Brief description of what it contains
- **File/Folder 2** - Brief description of what it contains
- **File/Folder 3** - Brief description of what it contains
 
## Quick Navigation
 
- [Parent Folder](../README.md)
- [Related Folder](../sibling/README.md)
- [Next Steps](#next-steps)
 
## How to Use This Folder
 
[Step-by-step guidance on what to do with files in this folder]
 
## Key Files Explained
 
### important-file.md
[Explain what this file is for and why it matters]
 
### another-important-file.md
[Explain purpose and when to use it]
 
## Standards & Patterns
 
[Document any conventions used in this folder]
- Naming patterns
- File organization
- How to add new items
 
## Known Issues / Open Questions
 
- [Open question or known issue](link if applicable)
- [Another open question]
 
## Next Steps / TODO
 
- [ ] [Item to complete]
- [ ] [Another item]
 
## Related Documentation
 
- [Link to related folder](../other/README.md)
- [Link to architectural docs](../04-architecture/README.md)

Folder-Specific Purposes

docs/00-meta/

  • Purpose: AgileFlow system documentation and setup guides
  • Contains: Installation guides, configuration templates, workflow instructions
  • Key sections: Setup guide, command reference, workflow guides

docs/01-brainstorming/

  • Purpose: Early-stage ideas, sketches, and initial concepts
  • Contains: Feature proposals, design sketches, brainstorming notes
  • Key sections: By feature area, prioritized ideas, ready to formalize

docs/02-practices/

  • Purpose: YOUR project's codebase practices (not AgileFlow practices)
  • Contains: Coding standards, testing strategies, git workflows, security practices
  • Key sections: By domain (UI, API, testing, git, CI/CD)

docs/03-decisions/

  • Purpose: Architecture Decision Records (ADRs) - trace important decisions over time
  • Contains: ADR files following adr-NNNN-title.md pattern
  • Key sections: By date, indexed by decision domain

docs/04-architecture/

  • Purpose: Technical specification and system design documentation
  • Contains: System architecture, data models, API specs, component diagrams
  • Key sections: Overview, data models, API, UI components, database schema

docs/05-epics/

  • Purpose: Epic definitions and feature breakdowns
  • Contains: Epic files following ep-NNNN-title.md pattern
  • Key sections: Active epics, completed epics, planned epics

docs/06-stories/

  • Purpose: User story implementations with acceptance criteria and learnings
  • Contains: Story files following US-NNNN.md pattern
  • Key sections: By epic, by status, implementation notes

docs/07-testing/

  • Purpose: Test plans, test cases, and coverage analysis
  • Contains: Test strategies, test case documentation, coverage reports
  • Key sections: Test cases by feature, coverage reports, testing tools

docs/08-project/

  • Purpose: Project management (roadmap, backlog, milestones)
  • Contains: Roadmap documentation, backlog prioritization, milestone tracking
  • Key sections: Roadmap, backlog, milestones, progress tracking

docs/09-agents/

  • Purpose: Multi-agent execution coordination
  • Contains: status.json (story tracking), bus/log.jsonl (message log), coordination docs
  • Key sections: Current agent assignments, message bus logs, patterns

docs/10-research/

  • Purpose: Technical research notes and findings
  • Contains: Research files following YYYYMMDD-slug.md pattern
  • Key sections: By topic, by date, indexed findings

Audit Checklist

Before completing README update, verify:

  • Folder purpose clearly explained (1-2 sentences)
  • All key files listed with descriptions
  • Navigation links current and working
  • Open questions documented
  • Next steps/TODOs listed
  • Links to related folders
  • No broken references
  • Consistent formatting with other READMEs
  • Up-to-date with current folder contents
  • Helpful to someone new to the project

Update Process

Step 1: Read Current README

  • If README.md exists, read it completely
  • Understand what's currently documented
  • Note what's outdated or missing

Step 2: Scan Folder Contents

  • List all files and folders
  • Understand structure and organization
  • Identify new files not in README
  • Identify files mentioned that no longer exist

Step 3: Identify Gaps

  • What's in folder but not documented?
  • What documentation is outdated?
  • Are links still valid?
  • Is folder purpose still accurate?

Step 4: Plan Updates

  • Reorganize if needed (better structure?)
  • Update descriptions
  • Add missing files
  • Remove obsolete content
  • Fix broken links

Step 5: Apply Updates

  • Rewrite README.md with improvements
  • Use standard format (see template above)
  • Keep consistent with other READMEs
  • Ensure all links work

Step 6: Report

  • Summary of what was updated
  • Files added to documentation
  • Files removed from documentation
  • Structural improvements made

Parallel Execution

When /agileflow:readme-sync runs:

  • 11 agents spawn simultaneously (one per folder)
  • Each agent works independently on their folder
  • All updates happen in parallel
  • Results are collected and reported back

Each agent:

  • Does NOT wait for other agents
  • Focuses only on assigned folder
  • Works at full speed
  • Completes independently

Examples

Example 1: Update docs/02-practices/README.md

1. Bash: ls -la docs/02-practices/
   → Shows: README.md, testing.md, git-branching.md, ci.md, security.md
 
2. Read: docs/02-practices/README.md
   → Current README lists some docs but misses security.md
 
3. Plan: Add missing files to documentation
 
4. Edit: Update docs/02-practices/README.md
   → Add security.md with description
   → Add "How to contribute" section
   → Fix navigation links
 
5. Report: "Updated README.md - added 2 files, fixed 1 link"

Example 2: Create docs/04-architecture/README.md

1. Bash: ls docs/04-architecture/
   → Shows: system-overview.md, api-design.md, database-schema.md, components.md
 
2. Read: Folder exists but no README.md
 
3. Plan: Create comprehensive README documenting architecture folder
 
4. Write: Create docs/04-architecture/README.md
   → Document folder purpose (technical specs)
   → List all architecture files
   → Explain key concepts
   → Add navigation links
 
5. Report: "Created README.md documenting 4 architecture files"

Quality Checklist

Before reporting completion:

  • Folder purpose clearly documented
  • All key files listed with descriptions
  • Navigation to other folders included
  • How-to guidance provided
  • Open questions/issues documented
  • Next steps/TODOs listed
  • All links verified and working
  • Consistent formatting with other READMEs
  • Helpful to someone new to the project
  • No broken references or outdated info

Related Agents

  • documentation - Creates detailed documentation that READMEs link to
  • mentor - May request README updates for clarity
  • babysit - Can trigger /readme-sync for comprehensive audit
  • epic-planner - May note documentation gaps when planning features

Common Patterns

Navigation Web

  • Each README links to parent, siblings, and children
  • Readers can traverse entire docs/ structure
  • No dead ends or broken paths

Descriptive Filenames

  • File descriptions explain PURPOSE, not just WHAT
  • "Coding standards for UI components" vs just "ui-standards"
  • "Test framework selection rationale" vs just "testing-adr"

Clear Structure

  • Contents section lists all files
  • Key Files section explains most important ones
  • How to Use section gives step-by-step guidance
  • Standards section documents conventions

Maintenance Trigger

  • After adding files to folder
  • After moving/renaming files
  • After deleting/archiving files
  • Before marking folder as "complete"
  • During quarterly documentation audits

Consistency Rules

  • Same headers across all READMEs
  • Same formatting for links and code
  • Same naming for navigation sections
  • Links to parent always use ../README.md
  • Links to siblings use ../sibling-folder/README.md