feat: add README create/update workflow and /readme command #129
Conversation
- Add readme-create-update.md subagent in workflows/ - Add /readme slash command with --sections support - Framework-agnostic stack and deployment detection - Maintainability-first approach (avoid staleness patterns) - AI-CONTEXT blocks for AI-readable documentation - Collapsible sections uncollapsed by default - Adapts to existing README structure when updating Inspired by Shpigford's README skill with aidevops conventions.
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation capabilities by introducing an automated system for creating and updating Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds two documentation artifacts that define a README create/update capability: a command specification for a README agent command and a detailed workflow describing triggers, step-by-step guidance, section mappings, selective Changes
Sequence Diagram(s)(omitted — changes are documentation/workflow additions without a multi-component runtime control flow that needs visualization) Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Tue Jan 20 23:35:25 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The pull request introduces a valuable feature for README management, including a new slash command and a detailed workflow. The documentation is generally comprehensive, but I've identified a minor clarity improvement for the command's argument description and a more significant inconsistency in the section mapping between the command definition and its associated workflow document. Addressing these will enhance user experience and ensure consistent agent behavior.
.agent/scripts/commands/readme.md
Outdated
|
|
||
| Create or update a comprehensive README.md file for the current project. | ||
|
|
||
| Arguments: $ARGUMENTS |
There was a problem hiding this comment.
The line "Arguments: $ARGUMENTS" appears to be a placeholder. For better clarity and user understanding, especially if this document is intended for direct human consumption, it would be beneficial to either explain what $ARGUMENTS represents or provide a more descriptive sentence about how arguments are handled by the /readme command. For example, "Arguments: This command accepts various flags and values, such as --sections."
| | `--sections` value | Updates | | ||
| |--------------------|---------| | ||
| | `installation` | Installation, Prerequisites, Quick Start | | ||
| | `usage` | Usage, Commands, Examples | | ||
| | `config` | Configuration, Environment Variables | | ||
| | `architecture` | Architecture, Project Structure | | ||
| | `troubleshooting` | Troubleshooting section | | ||
| | `deployment` | Deployment, Production Setup | | ||
| | `all` | Full regeneration (default) | |
There was a problem hiding this comment.
The "Section Mapping" table in this workflow document is inconsistent with the one defined in .agent/scripts/commands/readme.md. Specifically:
- The
usagesection in this document lists "Usage, Commands, Examples", while the command definition includes "API". - This document is missing the
badgessection entirely, which is present in the command definition.
These inconsistencies could lead to confusion or incorrect behavior if the agent relies on these mappings. It's important for the workflow guidance to accurately reflect the command's capabilities.
| | `--sections` value | Updates | | |
| |--------------------|---------| | |
| | `installation` | Installation, Prerequisites, Quick Start | | |
| | `usage` | Usage, Commands, Examples | | |
| | `config` | Configuration, Environment Variables | | |
| | `architecture` | Architecture, Project Structure | | |
| | `troubleshooting` | Troubleshooting section | | |
| | `deployment` | Deployment, Production Setup | | |
| | `all` | Full regeneration (default) | | |
| | --sections value | Updates | | |
| |--------------------|---------| | |
| | `installation` | Installation, Prerequisites, Quick Start | | |
| | `usage` | Usage, Commands, Examples, API | | |
| | `config` | Configuration, Environment Variables | | |
| | `architecture` | Architecture, Project Structure | | |
| | `troubleshooting` | Troubleshooting | | |
| | `deployment` | Deployment, Production Setup | | |
| | `badges` | Badge section only | | |
| | `all` | Full regeneration (default) | |
- Add API to usage section mapping for consistency - Add badges section to workflow section mapping - Clarify Arguments description in command file
🤖 Augment PR SummarySummary: Adds a dedicated README generation/update workflow and a new Changes:
Technical Notes: Workflow enables read/write/edit/bash tooling and includes concrete shell commands for quick repository exploration. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| | `architecture` | Architecture, Project Structure | | ||
| | `troubleshooting` | Troubleshooting | | ||
| | `deployment` | Deployment, Production Setup | | ||
| | `badges` | Badge section only | |
There was a problem hiding this comment.
The /readme command’s section mapping includes a badges option, but the workflow’s --sections mapping doesn’t document it; this can lead to users/agents having different expectations about which values are supported.
Other Locations
.agent/workflows/readme-create-update.md:359
🤖 Was this useful? React with 👍 or 👎
| | `--sections` value | Updates | | ||
| |--------------------|---------| | ||
| | `installation` | Installation, Prerequisites, Quick Start | | ||
| | `usage` | Usage, Commands, Examples | |
There was a problem hiding this comment.
The --sections mapping for usage doesn’t mention API updates, but earlier guidance calls out updating “usage/API” and the /readme command mapping includes API; consider reconciling so partial updates don’t accidentally skip API docs.
Other Locations
.agent/workflows/readme-create-update.md:48.agent/scripts/commands/readme.md:84
🤖 Was this useful? React with 👍 or 👎
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Tue Jan 20 23:38:30 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.agent/workflows/readme-create-update.md:
- Around line 359-367: Update the section-mapping table in
.agent/workflows/readme-create-update.md so it exactly matches the mapping in
.agent/scripts/commands/readme.md: add a `badges` entry, change the `usage`
mapping to include "API" (e.g., "Usage, Commands, Examples, API"), and normalize
the troubleshooting wording to match the command file (replace "Troubleshooting
section" with the exact phrase used in the command file); ensure the table keys
(`installation`, `usage`, `config`, `architecture`, `troubleshooting`,
`deployment`, `all`, `badges`) and their mapped values are identical to avoid
divergence.
🧹 Nitpick comments (2)
.agent/workflows/readme-create-update.md (1)
96-110: Documentjqdependency or provide fallback.Line 101 uses
jqto parse JSON, butjqmay not be available in all environments. Since these are example commands for codebase exploration, consider either:
- Documenting
jqas a recommended tool in the frontmatter or prerequisites- Providing a fallback using basic shell tools (e.g.,
grep,sed)Alternative without jq dependency
# Package info -cat package.json 2>/dev/null | jq '{name, description, scripts}' +cat package.json 2>/dev/null | jq '{name, description, scripts}' || cat package.json 2>/dev/nullOr mention the dependency:
# Gather Information**: + +*Note: Examples use `jq` for JSON parsing. Install via package manager if not available.* ```bash.agent/scripts/commands/readme.md (1)
38-44: Path reference may be incomplete.Line 43 references
workflows/readme-create-update.md, but based on the file structure in this PR, the full path should be.agent/workflows/readme-create-update.md. Verify whether the.agent/prefix is implied in the execution context or should be explicitly stated for clarity.-Read: workflows/readme-create-update.md +Read: .agent/workflows/readme-create-update.md
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.agent/scripts/commands/readme.md:
- Around line 40-44: Update the hardcoded reference "Read:
workflows/readme-create-update.md" to the actual workflow file path used in this
PR (replace that literal with the correct concrete path from the repo),
preserving the surrounding code block formatting and ensure any other
occurrences of the same literal are updated so operators/agents see the correct
workflow location.
In @.agent/workflows/readme-create-update.md:
- Around line 25-28: Summary: Hyphenate the compound adjective "high-level" in
the README line. Locate the sentence "Understanding the System - How it works at
a high level" (the second list item in the README section) and change "high
level" to "high-level" so the phrase reads "How it works at a high-level" (or
better, "How it works at a high level" → "How it works at a high level" with
hyphenation applied as "high-level" immediately before "overview" if
restructuring; ensure the compound adjective is hyphenated when used
adjectivally).
| Read the full workflow guidance: | ||
|
|
||
| ```text | ||
| Read: workflows/readme-create-update.md | ||
| ``` |
There was a problem hiding this comment.
Align workflow path with actual location.
To avoid operator/agent confusion, reference the concrete path shown in this PR.
🔧 Proposed tweak
-Read: workflows/readme-create-update.md
+Read: .agent/workflows/readme-create-update.md🤖 Prompt for AI Agents
In @.agent/scripts/commands/readme.md around lines 40 - 44, Update the hardcoded
reference "Read: workflows/readme-create-update.md" to the actual workflow file
path used in this PR (replace that literal with the correct concrete path from
the repo), preserving the surrounding code block formatting and ensure any other
occurrences of the same literal are updated so operators/agents see the correct
workflow location.
| **Three Purposes of a README**: | ||
| 1. **Local Development** - Get running in minutes | ||
| 2. **Understanding the System** - How it works at a high level | ||
| 3. **Production Deployment** - Ship and maintain it |
There was a problem hiding this comment.
Hyphenate the compound adjective (“high-level”).
Static analysis flagged the compound adjective. Small fix to keep docs A‑grade.
🔧 Proposed tweak
-2. **Understanding the System** - How it works at a high level
+2. **Understanding the System** - How it works at a high-level🧰 Tools
🪛 LanguageTool
[uncategorized] ~27-~27: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...anding the System** - How it works at a high level 3. Production Deployment - Ship and...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🤖 Prompt for AI Agents
In @.agent/workflows/readme-create-update.md around lines 25 - 28, Summary:
Hyphenate the compound adjective "high-level" in the README line. Locate the
sentence "Understanding the System - How it works at a high level" (the second
list item in the README section) and change "high level" to "high-level" so the
phrase reads "How it works at a high-level" (or better, "How it works at a high
level" → "How it works at a high level" with hyphenation applied as "high-level"
immediately before "overview" if restructuring; ensure the compound adjective is
hyphenated when used adjectivally).
1 participant
Summary
readme-create-update.mdsubagent inworkflows//readmeslash command with--sectionssupport for partial updatesKey Features
Three Purposes of a README (from Shpigford's skill):
aidevops Enhancements:
Usage
Files Changed
.agent/workflows/readme-create-update.md- Main workflow subagent.agent/scripts/commands/readme.md- Slash command definitionInspiration
Based on Shpigford's README skill with aidevops conventions and build-agent best practices applied.
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.