/docs-sync

Synchronize your documentation with codebase changes by detecting new code and ensuring corresponding documentation exists.

Quick Start

Copy/agileflow:docs-sync

To compare against a specific branch:

Copy/agileflow:docs-sync BRANCH=feature-auth BASE=main

Parameters

Examples

Analyze Current Branch

Copy/agileflow:docs-sync

Analyzes your current branch against main and reports:

• New API endpoints without documentation
• New UI components without documentation
• Configuration changes not documented
• Outdated documentation

Compare Feature Branch

Copy/agileflow:docs-sync BRANCH=feature-oauth BASE=main

Compares feature-oauth against main to find all documentation gaps.

Auto-Create Missing Docs

Copy/agileflow:docs-sync BRANCH=feature-payments AUTO_CREATE=yes

Automatically generates stub documentation for all missing items and commits with message docs: sync with codebase changes.

Output

The command generates a comprehensive report:

Copy# Documentation Sync Report
 
**Branch**: feature-auth | **Base**: main | **Generated**: 2025-12-24T10:30:00Z
 
## Missing Documentation
 
### API Endpoints (3)
- ❌ POST /api/auth/login (src/api/auth/login.ts)
- ❌ POST /api/auth/logout (src/api/auth/logout.ts)
- ❌ GET /api/auth/verify (src/api/auth/verify.ts)
 
### UI Components (2)
- ❌ LoginForm (src/components/LoginForm.tsx)
- ⚠️ UserProfile (src/components/UserProfile.tsx) - stub exists, needs details
 
### Configuration (1)
- ❌ New env var: JWT_SECRET (.env.example)
 
## Outdated Documentation
 
### Deprecated
- 📄 docs/04-architecture/api.md mentions /api/v1/login (removed in this branch)
 
## Up-to-Date
- ✅ UserAvatar component documented
- ✅ Database schema up-to-date

How It Works

Change Detection

The command:

1. Compares branches using git diff to identify all code changes
2. Categorizes changes into API endpoints, UI components, services, configuration, and database schemas
3. Maps to documentation locations where docs should exist

Smart Inference

Documentation is inferred from:

• TypeScript types and interfaces - Function signatures and return types
• JSDoc comments - Existing code documentation
• Test files - Usage examples
• OpenAPI decorators - API specifications

Gap Analysis

For each changed file, the command checks:

• Missing documentation: Newly added code with no docs
• Outdated documentation: References to removed or changed code
• Incomplete documentation: Stubs that need details

Documentation Mapping

Code changes are mapped to expected documentation:

Best Practices

Before Committing Code

Run docs-sync to identify documentation gaps early:

Copy/agileflow:docs-sync BRANCH=your-feature BASE=main

When Adding New Endpoints

The command will flag them automatically, making it easy to remember documentation:

Copy/agileflow:docs-sync AUTO_CREATE=yes

This creates stubs marked with "TODO: Add details" for manual review.

Documentation Sections to Maintain

Keep these synchronized with code:

• API request/response examples
• Component prop definitions
• Configuration options
• Database schema changes
• Deprecated API endpoints

Related Commands

• /context - Generate comprehensive context brief
• /readme-sync - Synchronize README files with folder contents
• /adr - Document architectural decisions