docs: improve README accuracy and readability for v2.3.0 (Vibe Kanban)#65
Conversation
…what was updated: ## Summary of Changes ### Factual Corrections 1. **Agent count**: Updated from "10" to "11" in 3 locations (intro, architecture section, troubleshooting) 2. **Added debate-arbiter** to the architecture section 3. **Removed Auto-Activation System section** (lines 152-174) - this feature doesn't exist in the codebase 4. **Added map-cli-reference** to the Skills section (was missing) 5. **Fixed Cost Optimization section** - all agents now use sonnet (not haiku), cost savings come from workflow selection 6. **Added /map-debate** to troubleshooting available commands list ### Readability Improvements 1. **Added version badges** (PyPI, Python version) at the top 2. **Added "What's New in v2.3.0" section** highlighting recent features 3. **Added /map-debate** to Quick Start examples 4. **Added /map-debate** to "Which Workflow Should You Use?" guidance section 5. **Added /map-debate** to workflow variants table 6. **Clarified token cost column** renamed from "Token Usage" to "Cost (% of baseline)" for clarity 7. **Updated cost comments** in Quick Start code block to be consistent ### Documentation Consistency - All 7 workflow commands now documented: `/map-efficient`, `/map-debug`, `/map-review`, `/map-debate`, `/map-fast`, `/map-learn`, `/map-release` - All 11 agents listed in troubleshooting section - All 3 skills documented in Skills section
📝 WalkthroughWalkthroughREADME.md was updated to document new project features and changes: agent count increased from 10 to 11 with explicit Debate Arbiter inclusion; new workflow commands /map-debate and /map-planning added; documentation references expanded; cost narrative reframed from token-based to workflow-based savings; and troubleshooting and architecture sections updated accordingly. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 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. ✨ Finishing touches
Comment |
azalio
changed the title
![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 @README.md:
- Around line 125-134: The `/map-learn` row uses token units while the table
header says "Cost (% of baseline)"; update the table header to a neutral label
like "Cost" or "Cost (units vary)" so the `/map-learn` cell can remain "~5-8K
tokens" and all other rows stay unchanged, and ensure the header text
replacement applies to the same Markdown table that contains the `/map-learn`
row.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Agent
🔇 Additional comments (2)
README.md (2)
11-14: Verify /map-planning documentation completeness.
/map-planningis announced in "What's New in v2.3.0" but does not appear in the Quick Start examples (lines 28–47), Workflow Variants table (lines 125–134), or troubleshooting commands list (line 348). If it's a v2.3.0 feature, users will look for usage guidance in these standard locations.Either:
- Add
/map-planningto Quick Start, the table, and troubleshooting, or- Clarify in the What's New section that full documentation is coming in a future release.
348-348: All workflow commands and agents properly documented. ✓Lines 348 and 357 correctly list all 7 workflow commands and all 11 agents (including the new
debate-arbiter.md). This aligns with PR objectives.Also applies to: 357-357
| | Command | Cost (% of baseline) | Learning | Quality Gates | Best For | | ||
| |---------|---------------------|----------|---------------|----------| | ||
| | **`/map-efficient`** ⭐ | **50-60%** | Optional via `/map-learn` | ✅ Essential agents | **RECOMMENDED: Most production tasks** | | ||
| | **`/map-debug`** | 50-60% | Optional via `/map-learn` | ✅ Essential agents | Bug fixes and debugging | | ||
| | **`/map-review`** | 30-40% | Optional via `/map-learn` | Monitor + Predictor + Evaluator | Pre-commit code review | | ||
| | **`/map-fast`** ⚠️ | 40-50% | ❌ None | ⚠️ Basic only | Throwaway prototypes, experiments (NOT production) | | ||
| | **`/map-debate`** | 80-100% | Optional via `/map-learn` | 3 Actor variants + Opus arbiter | Architecture decisions with trade-offs | | ||
| | **`/map-fast`** ⚠️ | 40-50% | ❌ None | ⚠️ Basic only | Throwaway prototypes (NOT production) | | ||
| | **`/map-learn`** | ~5-8K tokens | ✅ Full | Reflector + Curator | Capture patterns after any workflow | | ||
| | **`/map-release`** | Variable | Optional via `/map-learn` | 12 validation gates | Package releases | | ||
|
|
There was a problem hiding this comment.
Fix inconsistent cost unit in /map-learn row.
Line 132 shows ~5-8K tokens for /map-learn, but the table header specifies Cost (% of baseline). This mixes units—all other rows use percentages.
Align this row with the column semantics:
- If
/map-learncost should be in tokens (different from others), rename the column toCostorCost (units vary). - If it should be a percentage, provide the equivalent percentage of a baseline workflow.
🤖 Prompt for AI Agents
In @README.md around lines 125 - 134, The `/map-learn` row uses token units
while the table header says "Cost (% of baseline)"; update the table header to a
neutral label like "Cost" or "Cost (units vary)" so the `/map-learn` cell can
remain "~5-8K tokens" and all other rows stay unchanged, and ensure the header
text replacement applies to the same Markdown table that contains the
`/map-learn` row.
There was a problem hiding this comment.
Pull request overview
This PR updates the README to document new features and clarify the cost model for better reader-friendliness. The changes reflect the addition of the /map-debate workflow command and DebateArbiter agent (bringing the total from 10 to 11 agents), while clarifying that cost optimization comes from workflow selection rather than per-agent model switching.
Changes:
- Added
/map-debatecommand documentation with the DebateArbiter agent (11th agent) - Updated cost model explanation from model-based to workflow-based optimization
- Removed auto-activation system documentation
- Added version badges, "What's New" section, and
map-cli-referenceskill
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **map-workflows-guide** - Helps you choose the right workflow | ||
| **map-planning** - Persistent file-based plans for long `/map-efficient` sessions (`.map/task_plan_<branch>.md`) | ||
| **map-cli-reference** - CLI command corrections and syntax reference for mapify commands |
There was a problem hiding this comment.
The new skill map-cli-reference is added without a description format consistent with the other skills. The description "CLI command corrections and syntax reference for mapify commands" could be formatted more consistently with the pattern used by map-workflows-guide and map-planning (e.g., starting with a verb like "Provides" or "Helps").
| **map-cli-reference** - CLI command corrections and syntax reference for mapify commands | |
| **map-cli-reference** - Provides CLI command corrections and syntax reference for mapify commands |
| MAP Framework optimizes costs through workflow selection, not model switching: | ||
|
|
||
| **Result:** 40-60% cost reduction vs all-sonnet while maintaining code quality. | ||
| - **All agents use sonnet** for consistent quality (upgraded in v1.6.0) |
There was a problem hiding this comment.
The cost optimization section states "All agents use sonnet for consistent quality (upgraded in v1.6.0)" but doesn't explain what changed in v1.6.0. Since the old text mentioned Predictor & Evaluator used haiku, it would be helpful to clarify that v1.6.0 upgraded these agents from haiku to sonnet, explaining why the cost structure changed from model selection to workflow selection.
| - **All agents use sonnet** for consistent quality (upgraded in v1.6.0) | |
| - **All agents use sonnet** for consistent quality — as of v1.6.0, Predictor & Evaluator were upgraded from haiku to sonnet, so cost differences now come from which agents run, not which model they use |
| | **`/map-debug`** | 50-60% | Optional via `/map-learn` | ✅ Essential agents | Bug fixes and debugging | | ||
| | **`/map-review`** | 30-40% | Optional via `/map-learn` | Monitor + Predictor + Evaluator | Pre-commit code review | | ||
| | **`/map-fast`** ⚠️ | 40-50% | ❌ None | ⚠️ Basic only | Throwaway prototypes, experiments (NOT production) | | ||
| | **`/map-debate`** | 80-100% | Optional via `/map-learn` | 3 Actor variants + Opus arbiter | Architecture decisions with trade-offs | |
There was a problem hiding this comment.
The /map-debate command is documented with "80-100%" cost but no corresponding savings percentage is mentioned elsewhere in the documentation. For consistency with other workflows, consider documenting the savings percentage (0-20% savings) or cost increase compared to baseline in the usage examples or workflow comparison sections.
| | **`/map-debate`** | 80-100% | Optional via `/map-learn` | 3 Actor variants + Opus arbiter | Architecture decisions with trade-offs | | |
| | **`/map-debate`** | 80-100% (0-20% savings vs baseline) | Optional via `/map-learn` | 3 Actor variants + Opus arbiter | Architecture decisions with trade-offs | |
|
|
||
| **What's New in v2.3.0:** | ||
| - `/map-planning` skill for file-based workflow planning with branch-scoped task tracking | ||
| - `/map-debate` command (v2.2.0) for multi-variant synthesis with Opus arbiter |
There was a problem hiding this comment.
The version mentioned "v2.2.0" for /map-debate appears before "v2.3.0" which introduces /map-planning. This suggests v2.2.0 is older. However, the phrasing "(v2.2.0)" in parentheses after /map-debate could be clarified to indicate this feature was introduced in v2.2.0 and is still available in v2.3.0, to avoid confusion about whether this is current functionality.
| - `/map-debate` command (v2.2.0) for multi-variant synthesis with Opus arbiter | |
| - `/map-debate` command (introduced in v2.2.0; available in v2.3.0) for multi-variant synthesis with Opus arbiter |
| **Solution:** | ||
| - Ensure you're in a directory with `.claude/commands/` containing `map-*.md` files | ||
| - Available commands: `/map-efficient`, `/map-debug`, `/map-review`, `/map-fast`, `/map-learn`, `/map-release` | ||
| - Available commands: `/map-efficient`, `/map-debug`, `/map-review`, `/map-debate`, `/map-fast`, `/map-learn`, `/map-release` |
There was a problem hiding this comment.
The list of available commands is updated to include /map-debate, but the order differs from other command listings in the document. For consistency, consider using the same ordering as shown in lines 27-48 (efficient, debug, fast, learn, review, debate, release) throughout the README.
| - Available commands: `/map-efficient`, `/map-debug`, `/map-review`, `/map-debate`, `/map-fast`, `/map-learn`, `/map-release` | |
| - Available commands: `/map-efficient`, `/map-debug`, `/map-fast`, `/map-learn`, `/map-review`, `/map-debate`, `/map-release` |
Summary
Comprehensive README.md update to fix factual inaccuracies and improve readability for the v2.3.0 release.
Changes Made
Factual Corrections
map-cli-referencewas not documented in Skills sectionReadability Improvements
Documentation Completeness
All 7 workflows now properly documented:
/map-efficient,/map-debug,/map-review,/map-debate,/map-fast,/map-learn,/map-releaseAll 11 agents now listed:
All 3 skills now documented:
Why These Changes
The README contained several inaccuracies that accumulated over multiple releases:
This PR was written using Vibe Kanban