Shayan Rais
6.3 KiB
6.3 KiB
Update README Command
Analyze the project structure and update the README.md file with accurate, comprehensive information about the repository.
Purpose
This command automates README documentation by:
- Analyzing the project structure and codebase
- Identifying key features and components
- Generating or updating README sections
- Ensuring documentation is accurate and helpful
User Input
$ARGUMENTS
If the user provides specific instructions (e.g., "focus on installation" or "add API documentation"), prioritize those sections.
Outline
- Analyze Project: Scan repository structure, files, and existing documentation
- Identify Components: Detect tech stack, features, and key functionality
- Generate Content: Create comprehensive README sections
- Update README: Write or update the README.md file
- Validate: Ensure completeness and accuracy
Execution Flow
Phase 1: Project Analysis
Prerequisites: Repository must exist
Process:
- Read existing README.md (if present)
- Scan directory structure to identify:
- Programming languages used
- Frameworks and libraries
- Configuration files
- Source code organization
- Tests and documentation
- Identify the project type (library, application, tool, etc.)
- Check for package.json, requirements.txt, go.mod, Cargo.toml, etc.
- Review git history for context about the project
Outputs:
- Project type and purpose
- Tech stack list
- Key directories and files
- Existing README content (if any)
Validation:
- Project structure successfully scanned
- Tech stack identified
- Project type determined
Phase 2: Content Generation
Prerequisites: Phase 1 completed
Process:
- Delegate to the readme-writer agent to generate content
- Provide the agent with:
- Project analysis from Phase 1
- User-specified requirements (if any)
- Existing README content
- Agent should generate sections:
- Title and Description: Clear project overview
- Features: Key capabilities and highlights
- Installation: Setup instructions for the tech stack
- Usage: Examples and basic usage patterns
- Project Structure: Directory layout explanation
- Configuration: Environment variables and config files
- Development: How to contribute and develop
- License: License information (if detected)
- Ensure all content is accurate and based on actual code/files
- Make content beginner-friendly with clear examples
Outputs:
- Complete README content organized by sections
Validation:
- All standard sections included
- Content is accurate based on actual project files
- Examples are practical and correct
- Installation instructions match the tech stack
Phase 3: Update README
Prerequisites: Phase 2 completed with validated content
Process:
- If README.md exists:
- Preserve any custom sections or notes
- Update outdated sections
- Add missing sections
- If README.md doesn't exist:
- Create new file with generated content
- Format the content with proper markdown
- Ensure consistent style and formatting
- Add table of contents if README is lengthy
Outputs:
- Updated or created README.md file
Validation:
- README.md file exists
- Markdown is properly formatted
- All sections are present
- No placeholder text remains
Phase 4: Final Verification
Prerequisites: Phase 3 completed
Process:
- Read the final README.md
- Verify:
- Links are valid (if any)
- Code examples use correct syntax
- File paths match actual structure
- No broken markdown formatting
- Check for completeness:
- Is the purpose clear?
- Are setup instructions complete?
- Are examples helpful?
Outputs:
- Verification report
- List of any issues found
Validation:
- No markdown errors
- Code syntax is correct
- File references are accurate
- README is comprehensive
Sub-Agent Delegation
readme-writer Agent
Invoke the readme-writer agent (.claude/agents/readme-writer.md) for Phase 2 content generation.
What to provide:
Project Type: [application/library/tool]
Tech Stack: [languages, frameworks, tools]
Directory Structure: [key directories and their purposes]
Existing Content: [current README content if any]
User Requirements: [specific user instructions]
Package Info: [dependencies, scripts from package files]
Expected output:
# Project Title
[Generated comprehensive README content with all sections]
Verification:
- Ensure agent used actual project information (not hallucinated)
- Check that examples reference real files/code
- Verify installation steps match the tech stack
- Confirm content is appropriate for the audience
Error Handling
If project structure is unclear:
- Ask user to clarify project type
- Request focus areas for documentation
If existing README has custom sections:
- Preserve custom content
- Inform user about sections kept vs. updated
If tech stack is ambiguous:
- List detected possibilities
- Ask user to confirm the stack
If agent generates incorrect content:
- Iterate with corrections
- Provide agent with specific file examples
- Ask user to review and approve
Completion Report
After successful execution, report:
✅ README updated successfully!
## Changes Made
- [Created new README.md | Updated existing README.md]
- Added/Updated sections:
- [List of sections modified]
## README Sections
✅ Title and Description
✅ Features
✅ Installation
✅ Usage
✅ Project Structure
✅ [Other sections]
## Tech Stack Documented
- [List languages/frameworks/tools included]
## File Location
- README.md (root directory)
## Next Steps
1. Review the updated README for accuracy
2. Add any project-specific details
3. Update screenshots or badges if needed
4. Commit the changes
## Verification Results
[Report any warnings or issues]
Notes
- Accuracy First: Only document what actually exists in the code
- User-Friendly: Write for developers who are new to the project
- Maintainable: Structure content so it's easy to update
- Comprehensive: Cover installation, usage, and development
- Preserve Custom Content: Don't overwrite user's custom sections without warning