Shayan Rais
243 lines
6.3 KiB
Markdown
243 lines
6.3 KiB
Markdown
# 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:
|
|
1. Analyzing the project structure and codebase
|
|
2. Identifying key features and components
|
|
3. Generating or updating README sections
|
|
4. Ensuring documentation is accurate and helpful
|
|
|
|
## User Input
|
|
|
|
```text
|
|
$ARGUMENTS
|
|
```
|
|
|
|
If the user provides specific instructions (e.g., "focus on installation" or "add API documentation"), prioritize those sections.
|
|
|
|
## Outline
|
|
|
|
1. **Analyze Project**: Scan repository structure, files, and existing documentation
|
|
2. **Identify Components**: Detect tech stack, features, and key functionality
|
|
3. **Generate Content**: Create comprehensive README sections
|
|
4. **Update README**: Write or update the README.md file
|
|
5. **Validate**: Ensure completeness and accuracy
|
|
|
|
## Execution Flow
|
|
|
|
### Phase 1: Project Analysis
|
|
|
|
**Prerequisites**: Repository must exist
|
|
|
|
**Process**:
|
|
1. Read existing README.md (if present)
|
|
2. Scan directory structure to identify:
|
|
- Programming languages used
|
|
- Frameworks and libraries
|
|
- Configuration files
|
|
- Source code organization
|
|
- Tests and documentation
|
|
3. Identify the project type (library, application, tool, etc.)
|
|
4. Check for package.json, requirements.txt, go.mod, Cargo.toml, etc.
|
|
5. 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**:
|
|
1. Delegate to the **readme-writer** agent to generate content
|
|
2. Provide the agent with:
|
|
- Project analysis from Phase 1
|
|
- User-specified requirements (if any)
|
|
- Existing README content
|
|
3. 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)
|
|
4. Ensure all content is accurate and based on actual code/files
|
|
5. 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**:
|
|
1. If README.md exists:
|
|
- Preserve any custom sections or notes
|
|
- Update outdated sections
|
|
- Add missing sections
|
|
2. If README.md doesn't exist:
|
|
- Create new file with generated content
|
|
3. Format the content with proper markdown
|
|
4. Ensure consistent style and formatting
|
|
5. 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**:
|
|
1. Read the final README.md
|
|
2. Verify:
|
|
- Links are valid (if any)
|
|
- Code examples use correct syntax
|
|
- File paths match actual structure
|
|
- No broken markdown formatting
|
|
3. 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:
|
|
|
|
```markdown
|
|
✅ 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
|