/readme-sync

Keep folder README.md files up-to-date by automatically generating a contents section that matches the actual files in the folder.

Quick Start

Copy/agileflow:readme-sync FOLDER=docs/02-practices

To sync all documentation folders at once:

Copy/agileflow:readme-sync FOLDER=all

Parameters

Examples

Sync Single Folder

Copy/agileflow:readme-sync FOLDER=docs/02-practices

Scans docs/02-practices/ for all files and subdirectories, then updates the ## Contents section of docs/02-practices/README.md with current items.

Sync All Documentation Folders

Copy/agileflow:readme-sync FOLDER=all

Automatically syncs all folders in docs/ directory in parallel:

• docs/00-meta/
• docs/01-brainstorming/
• docs/02-practices/
• docs/03-decisions/
• ... and more

Interactive Folder Selection

Copy/agileflow:readme-sync

If you don't specify a folder, the command asks you to choose:

CopyWhich folder should I sync?
 
1. docs/02-practices (Recommended)
2. docs/04-architecture
3. all
4. Other (enter custom path)

Output

The command generates a ## Contents section in the README:

Copy## Contents
 
- **testing.md** – Test strategy, patterns, and test infrastructure
- **git-branching.md** – Git workflow, branching strategy, and commit conventions
- **ci.md** – CI/CD pipeline configuration and testing gates
- **security.md** – Security practices, input validation, and authentication
- **releasing.md** – Release procedures, versioning, and changelog management
 
### Sub-folder: design/
- **design/colors.md** – Color palette and branding guidelines
- **design/typography.md** – Font stack and text styling rules

How It Works

Step 1: List Contents

The command scans the folder for:

• All markdown and other files
• Subdirectories and their contents

Step 2: Extract Descriptions

For each file, it extracts:

• Markdown files: The first heading (# Heading) or first sentence
• Other files: First line or filename-based description

Step 3: Build Contents Section

Generates a clean bullet-list format with:

• Filenames in bold
• One-sentence descriptions
• Nested structure for subdirectories

Step 4: Preview & Confirm

Shows you the proposed changes:

Copy📁 Syncing docs/02-practices/README.md
=====================================
 
Proposed Changes to ## Contents Section:
─────────────────────────────────────────
- **testing.md** – Test strategy, patterns, test infrastructure
- **git-branching.md** – Git workflow, branching strategy, commit conventions
...
 
Update README.md with these changes? (YES/NO)

Best Practices

Keep Contents Updated

Run after adding new files to a folder:

Copy# Just added a new file
vim docs/02-practices/performance-tuning.md
 
# Update the README
/agileflow:readme-sync FOLDER=docs/02-practices

Pre-Release Checklist

Before major releases, sync all documentation:

Copy/agileflow:readme-sync FOLDER=all

Quarterly Maintenance

Schedule regular documentation audits:

Copy# Sync entire docs/ and review changes
/agileflow:readme-sync FOLDER=all

When Reorganizing

After restructuring a folder, immediately sync:

Copy/agileflow:readme-sync FOLDER=docs/your-folder

What It Updates

The command only updates the ## Contents section:

• Removes old file listings
• Adds all current files with descriptions
• Maintains all other README sections unchanged
• Preserves custom notes and links
• Keeps header, intro, and footer sections intact

This means you can safely use the command without losing custom documentation.

File Description Extraction

The command intelligently extracts descriptions:

Copy# Testing Strategy
 
Guidelines for writing and running tests...

Extracts as: "Testing Strategy – Guidelines for writing and running tests"

Copy<!-- This file documents git workflow -->
Guidelines for branching and committing

Extracts the first meaningful line as description.

Related Commands

• /docs-sync - Synchronize documentation with code changes
• /context - Generate comprehensive project context
• /template - Create custom documentation templates