Initial commit

2025-11-29 18:01:55 +08:00
commit 60782a2f51
22 changed files with 5228 additions and 0 deletions
--- a/commands/update-readme.md
+++ b/commands/update-readme.md
@@ -0,0 +1,514 @@
+---
+description: Refactor existing README.md to conform to   standards
+---
+
+# Update README
+
+## Activated Agent
+
+**Activate**: `readme-author` agent
+
+The agent will refactor your existing README.md to meet Personal minimal standards.
+
+## Objective
+
+Update existing README.md to conform to   8-section minimal structure, preserving compliant content while adding missing sections and integrating business context.
+
+## Command Parameters
+
+| Parameter | Options | Default | Description |
+|-----------|---------|---------|-------------|
+| `--sections` | Comma-separated: `title`, `badges`, `description`, `installation`, `documentation`, `components`, `contributing`, `bugs` | All missing/incomplete | Specific sections to update |
+| `--tier` | `prototype`, `mvp`, `production` | Auto-detect | Target project tier |
+| `--format` | `console`, `markdown` | `console` | Output format (console display vs. write file) |
+| `--output` | `<path>` | `./README.md` | Output path (use different path to preserve original) |
+| `--interactive` | `true`, `false` | `true` | Show diffs and prompt for approval |
+
+**Examples:**
+```bash
+/document-generator:update-readme                                      # Interactive, all sections
+/document-generator:update-readme --sections=description,documentation
+/document-generator:update-readme --tier=mvp --format=markdown --interactive=false
+/document-generator:update-readme --output=./README-new.md --format=markdown
+```
+
+## Activated Skills
+
+The agent will activate these skills:
+
+1. **`readme-authoring`** - Templates for missing sections
+2. **`readme-standards`** - Validation criteria and compliance checking
+
+## Process
+
+The agent will follow this workflow:
+
+### 1. Pre-flight Checks
+
+**Check if README.md exists**:
+- If `README.md` not found:
+  ```
+  ❌ No README.md found in current directory.
+
+  Use `/document-generator:generate-readme` to create one.
+
+  Aborting update.
+  ```
+  - Stop execution
+
+**Create backup** (before making changes):
+```bash
+cp README.md README.md.backup
+```
+
+Notify user:
+```
+📁 Backup created: README.md.backup
+```
+
+### 2. Validate Current README
+
+**Run validation first** (same logic as `validate-readme`):
+- Parse structure
+- Identify missing/incomplete sections
+- Check content quality
+- Validate links
+
+**Display current state**:
+```
+📊 Current README Status
+
+Tier: MVP (detected)
+Compliance: ✅ Minimal
+
+Issues found:
+⚠️  1. Short Description - Missing business problem context
+⚠️  2. Documentation - ADRs not linked (adr/ exists)
+❌ 3. Contributing - Section missing
+ℹ️  4. Badges - Not present (recommended for MVP tier)
+
+Ready to fix these issues.
+```
+
+### 3. Determine Sections to Update
+
+**If `--sections` parameter provided**:
+- Only update specified sections
+- Skip sections not in the list
+
+**If no `--sections` parameter**:
+- Update all missing sections (❌)
+- Update all incomplete sections (⚠️)
+- Note optional sections (ℹ️) but don't auto-add unless requested
+
+**Priority order**:
+1. Missing required sections (Contributing, Installation, etc.)
+2. Incomplete sections (missing business context, broken links)
+3. Optional enhancements (Badges, Supporting Components)
+
+### 4. Extract Context for Updates
+
+Same extraction logic as `generate-readme`:
+
+**For missing/incomplete sections, gather**:
+- Project metadata (from pyproject.toml, package.json, etc.)
+- Business context (from docs, code, or user input)
+- Existing documentation to link
+- Issue tracker URL
+- CONTRIBUTING.md location
+
+**Preserve existing content**:
+- Don't regenerate compliant sections
+- Extract and reuse content from non-compliant sections
+- Maintain user's formatting choices where possible
+
+### 5. Generate Section Updates
+
+For each section needing update:
+
+**Title & One-Liner**:
+- Preserve existing title if present
+- Add one-liner if missing
+- Improve vague descriptions
+
+**Badges** (if missing and tier >= MVP):
+- Generate minimal badge set
+- Insert after title, before description
+
+**Short Description**:
+- **If "## Overview" exists instead of "## Description"**:
+  - Keep as "## Overview" (both acceptable per standards)
+  - Only update if content lacks business context
+
+- **If separate "Business Problem" and "Solution" sections exist**:
+  - Note: This is acceptable per flexible standards
+  - Offer to merge into single `## Description` or `## Overview` paragraph for conciseness (optional)
+  - If user prefers merged format: Extract, merge, show diff
+  - If user prefers separate: Keep as-is if content is brief and focused
+
+- **If description/overview lacks business context**:
+  - Prompt user for business problem/solution
+  - Integrate into existing description or overview
+  - Preserve technical details
+
+**Installation**:
+- If missing: Generate from project type
+- If incomplete: Add link to setup guide if exists
+- If overly detailed: Suggest moving to docs/setup.md
+
+**Documentation**:
+- Check if docs are in dedicated `## Documentation` section OR within `## Guides` or similar
+- Add links to discovered docs not currently linked (anywhere in README)
+- If docs scattered across multiple sections, offer to consolidate (optional)
+- Verify all existing links still valid
+- Organize in logical order (Quickstart, API, Architecture, ADRs)
+
+**Supporting Components**:
+- Only add if dependencies detected
+- Skip if standalone project
+
+**Contributing**:
+- Check if contributing link exists in dedicated `## Contributing` section OR within `## Documentation`/`## Guides`
+- If CONTRIBUTING.md exists but not linked anywhere: Add link (in existing docs section or create new Contributing section)
+- If no CONTRIBUTING.md: Offer to create basic Contributing section with inline guidance
+- Add test command if detectable
+
+**Issue Reporting**:
+- Check if issue reporting exists in dedicated `## Bugs` section OR within `## Contributing`/`## Documentation`
+- If missing anywhere: Add link (in existing section or create new Bugs section)
+- GitHub Issues link if GitHub repo detected
+- Prompt user for issue tracker if not detectable
+
+### 6. Present Diffs (Interactive Mode)
+
+For each section being updated, show before/after diff:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+UPDATE: Short Description
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+BEFORE:
+────────────────────────────────────────────────
+## Business Problem
+Marketing teams struggle with customer segmentation.
+
+## Solution
+This tool provides automated clustering.
+
+## Description
+The Customer Segmentation Engine uses ML to group customers.
+────────────────────────────────────────────────
+
+AFTER:
+────────────────────────────────────────────────
+## Description
+
+Marketing teams struggle with customer segmentation, leading to ineffective campaign targeting and low conversion rates. This tool provides automated clustering capabilities using machine learning to group customers by purchasing behavior. The Customer Segmentation Engine processes transaction history and demographic data to generate actionable segments for targeted marketing campaigns.
+────────────────────────────────────────────────
+
+Changes:
+- Merged Business Problem and Solution sections into Description
+- Integrated business context into cohesive paragraph
+- Preserved technical details from original Description
+
+Apply this update? (y/n/edit):
+```
+
+**User options**:
+- `y`: Apply this update
+- `n`: Skip this update
+- `edit`: Modify the generated content before applying
+- `all`: Apply all remaining updates without prompting
+
+**If user chooses "edit"**:
+```
+Enter updated content for Short Description:
+(Paste content, then press Ctrl+D or type 'done' on new line)
+
+> ___
+```
+
+Accept user's edited content and continue.
+
+### 7. Apply Updates
+
+**Build updated README**:
+
+1. Start with existing README content
+2. For each section to update:
+   - If section exists: Replace content
+   - If section missing: Insert in correct position (maintain 8-section order)
+   - If section needs removal (e.g., separate Business Problem): Remove it
+
+3. Maintain proper structure:
+   - Title first (`#`)
+   - Badges after title (if present)
+   - Sections in order (`##`)
+   - Preserve custom sections not in standard 8 (at end)
+
+**Example transformation**:
+
+**Before (non-compliant)**:
+```markdown
+# My Project
+
+## Business Problem
+Teams have issues.
+
+## Solution
+This fixes it.
+
+## Setup
+Install stuff.
+```
+
+**After (compliant)**:
+```markdown
+# My Project
+
+Brief description of what this does and why.
+
+## Description
+
+Teams struggle with X problem, leading to Y consequence. This project provides Z solution by implementing W approach. The system handles A, B, and C use cases.
+
+## Installation
+
+\`\`\`bash
+pip install my-project
+\`\`\`
+
+## Documentation
+
+- [Architecture](docs/architecture.md) - System design
+- [ADRs](adr/) - Key decisions
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Bugs & Enhancements
+
+Report issues via [GitHub Issues](https://github.com/org/my-project/issues).
+```
+
+### 8. Write Updated README
+
+**If `--format=markdown`** (write file):
+
+```bash
+# Write updated README
+cat > ./README.md <<'EOF'
+{updated content}
+EOF
+```
+
+**Confirm success**:
+```
+✓ README.md updated successfully
+
+Sections updated:
+  1. Short Description - Merged Business Problem/Solution, added context
+  2. Documentation - Added links to ADRs and architecture docs
+  3. Contributing - Added link to CONTRIBUTING.md
+
+Backup saved to: README.md.backup
+
+Next steps:
+- Review the updated README
+- Run `/document-generator:validate-readme` to verify compliance
+- Consider creating suggested documentation:
+  - docs/quickstart.md
+```
+
+**If `--format=console`** (display only):
+- Show full updated README
+- Don't write file
+- Note that backup was NOT created (no changes made)
+
+### 9. Cleanup
+
+**If changes were successfully applied**:
+- Keep backup file (README.md.backup)
+- User can delete backup later
+
+**If user cancelled**:
+- Remove backup file
+- Leave original README unchanged
+
+## Interactive Patterns
+
+### Prompt for Business Context
+
+If description lacks business problem/solution:
+
+```
+The Short Description section is missing business context.
+
+To update it, I need to know:
+
+1. What business problem does this project solve?
+   (1-2 sentences describing the problem and its impact)
+
+   > ___
+
+2. What solution does this project provide?
+   (1-2 sentences describing how it addresses the problem)
+
+   > ___
+```
+
+### Confirm Major Changes
+
+For significant restructuring (merging sections, removing content):
+
+```
+⚠️  Major Restructure Detected
+
+This update will:
+- Merge "Business Problem" and "Solution" sections into "Description"
+- Remove separate sections (content will be preserved)
+- Add 2 new sections (Contributing, Bugs & Enhancements)
+
+This is a significant change. Continue? (y/n):
+```
+
+### Handle Custom Sections
+
+If README has custom sections beyond the standard 8:
+
+```
+ℹ️  Custom Sections Detected
+
+Your README contains custom sections:
+- ## FAQ
+- ## Troubleshooting
+- ## Changelog
+
+These will be preserved at the end of the README.
+
+Continue? (y/n):
+```
+
+## Constraints
+
+- **Preserve compliant content** - Don't regenerate sections that meet standards
+- **Maintain user intent** - Keep custom sections, preserve formatting preferences
+- **Show diffs for transparency** - User should see all changes before applying
+- **Create backups** - Always backup before modifying
+- **Link validation** - Only add links to docs that actually exist
+- **Respect tier** - Apply tier-appropriate standards
+
+## Error Handling
+
+**README.md not found**:
+- Suggest using `generate-readme`
+- Stop execution
+
+**README.md not writable**:
+- Check file permissions
+- Suggest alternative output path
+
+**Backup creation fails**:
+- Warn user
+- Prompt to continue without backup or cancel
+
+**User cancels mid-update**:
+- Restore from backup
+- Clean up partial changes
+
+## Success Criteria
+
+Updated README should:
+- ✅ Preserve all compliant existing content
+- ✅ Fix identified compliance issues
+- ✅ Integrate business context into Description
+- ✅ Link to all discovered documentation
+- ✅ Follow 8-section minimal structure
+- ✅ Pass validation via `/document-generator:validate-readme`
+
+## Special Cases
+
+### Optional: Merging Business Problem/Solution Sections
+
+**Note**: Per updated standards, separate Business Problem/Solution sections are acceptable if brief and focused.
+
+**If README has** separate sections and user prefers merged format:
+```markdown
+## Business Problem
+{problem text}
+
+## Solution
+{solution text}
+
+## Description
+{technical details}
+```
+
+**Offer to transform to** (optional):
+```markdown
+## Description
+
+{problem text}. {solution text}. {technical details}.
+```
+
+**Or keep as-is** if user prefers separate sections (compliant per flexible standards)
+
+### Handling Overly Detailed Installation
+
+**If Installation section has**:
+```markdown
+## Installation
+
+1. Install Python 3.9+
+2. Create virtual environment
+3. Install dependencies: pip install -r requirements.txt
+4. Set up database: ...
+5. Run migrations: ...
+6. Configure environment: ...
+```
+
+**Suggest**:
+```
+⚠️  Installation section is overly detailed.
+
+Recommendation: Move detailed setup to docs/setup.md
+
+Updated Installation section:
+───────────────────────────────────────
+## Installation
+
+\`\`\`bash
+pip install my-project
+\`\`\`
+
+For detailed setup and configuration, see [Setup Guide](docs/setup.md).
+───────────────────────────────────────
+
+Apply this simplification? (y/n):
+```
+
+### Preserving Custom Content
+
+If README has unique sections (FAQ, Roadmap, Changelog):
+- Keep them at the end of README
+- Maintain their order
+- Don't flag as non-compliant
+- Note in update summary
+
+## Related Commands
+
+- **`/document-generator:validate-readme`** - Check README before/after update
+- **`/document-generator:generate-readme`** - Create new README instead
+
+## Batch Update Mode
+
+**For non-interactive batch updates** (`--interactive=false`):
+
+- Apply all fixes automatically
+- No user prompts
+- Create detailed update log
+- Save to `./reports/readme-update-log.md`
+
+**Use with caution** - Review changes carefully after batch update.