feat: Integrate Task Master improvements across MAP Framework#10
feat: Integrate Task Master improvements across MAP Framework#10
Conversation
…hancements Performed comprehensive competitive analysis of claude-task-master task management system to identify applicable improvements for MAP framework. Key Deliverables: - Complete strategic analysis document (docs/analysis/task-master-integration.md) - Tier-based recommendations (3 tiers: adopt/evaluate/reject) - 5 new playbook patterns for workflow orchestration (pending application) - Enhanced task-decomposer with numeric complexity scoring framework (partial) Analysis Findings: - Task Master strengths: operational workflow, complexity pre-analysis, TDD state machine - MAP strengths: knowledge accumulation, agent orchestration, flexible execution - Identified 3 high-value improvements: complexity scoring, research integration, dependency validation - Documented WHY NOT to adopt: TDD state machine conflicts with MAP philosophy Methodology: - Used mcp__sequential-thinking (10 thoughts) for deep framework comparison - TaskDecomposer generated 8 implementation subtasks - Pivoted from full implementation (300k+ tokens) to analysis document (100k tokens) - Reflector extracted 5 strategic patterns - Curator proposed 3 new playbook sections (WORKFLOW_PATTERNS, ANALYSIS_PATTERNS, DECISION_FRAMEWORKS) New Patterns Documented: 1. Competitive Analysis Workflow Mode - analysis as first-class deliverable 2. Sequential Thinking for Strategic Analysis - proactive use for framework comparison 3. Monitor Agent Mode-Specific Validation - different validation for implementation/analysis/docs 4. Rejection Rationale Documentation - prevent feature creep by documenting why NOT to adopt 5. Token Budget Pragmatic Pivots - estimate cost, pivot to docs if >250k tokens Task-Decomposer Enhancement (Partial): - Added numeric complexity scoring framework (1-10 scale) - Scoring ranges: 1-3 (simple), 4-6 (moderate), 7-8 (complex), 9-10 (very high) - Score calculation method: base + novelty + dependencies + scope + risk - Note: Full integration with examples pending (see playbook-changes-pending.md) Next Steps: - Apply 5 playbook bullets to .claude/playbook.json (instructions in docs/analysis/playbook-changes-pending.md) - Complete task-decomposer examples with new complexity_score fields - Implement Tier 1 recommendations: research integration, dependency validation utility Analysis completed: 2025-10-26 Tokens used: ~120k for deep strategic analysis Estimated value: Prevents 40+ hours of misdirected implementation (rejected TDD state machine)
Implemented all 9 subtasks from task-master-integration.md analysis: ## Subtask 1: TaskDecomposer test_strategy field - Added 65-line decision table for test strategy selection - Criteria based on complexity, criticality, and user-facing impact - 4 playbook updates ## Subtask 2: TaskDecomposer output schema - Verified schema completeness - Fixed 64-line duplication in test_strategy section - All required fields documented ## Subtask 3: Enhanced complexity scoring examples - Enhanced all 20 examples with complexity scores (range 2-8) - Added granular breakdowns for each subtask - 3 playbook updates ## Subtask 4: Research step integration - Added research guidelines to Actor template (489 lines) - Updated Monitor validation criteria (111 lines) - Updated Evaluator completeness scoring (4 lines) - 3 playbook updates ## Subtask 5: Dependency validation utility - Created scripts/validate-dependencies.py (684 lines) - DFS cycle detection algorithm O(V+E) - Detects: circular deps, forward refs, self-deps, orphans - 4 playbook updates ## Subtask 6: ASCII graph visualization - Added ASCIIGraphRenderer class (284 lines) - Box-drawing unicode characters with --no-color fallback - 54 comprehensive tests (100% pass rate) - 2 iterations: 6.75/10 → 8.75/10 - 4 playbook updates ## Subtask 7: Validation utility documentation - Added 190-line USAGE.md section - Documented exit codes, CLI usage, CI/CD integration - 2 iterations: 5.9/10 → 8.1/10 - 3 playbook updates ## Subtask 8: TaskDecomposer final checklist - Added 6-item dependency validation checklist - Command examples and verification steps - 8.2/10 quality score ## Subtask 9: CLI integration (user-identified gap) - Created src/mapify_cli/tools/validate_dependencies.py - Added 'mapify validate graph' command with Typer sub-app - Enables pip install users to run validation - All flags: --visualize, --no-color, -f/--format - Updated tests to import from new module - 7.95/10 quality score ## Playbook Updates (Total: 14 new + 3 updated) - NEW SECTION: CLI_TOOL_PATTERNS - cli-0001: Deployment Model as Explicit Requirement - TESTING_STRATEGIES: - test-0015: 3-Layer CLI Testing (updated, synced to cipher) - ARCHITECTURE_PATTERNS: - arch-0014: Typer Sub-App Integration Pattern - IMPLEMENTATION_PATTERNS: - impl-0052: Aggressive Deprecation Over Code Duplication ## Key Achievement Solved critical gap identified by user: dependency validator now accessible to pip install users via CLI, not just dev environment scripts/. All subtasks completed with full MAP workflow cycles (Actor → Monitor → Predictor → Evaluator → Reflector → Curator).
There was a problem hiding this comment.
Pull Request Overview
This PR integrates Task Master analysis insights into the MAP Framework, enhancing task decomposition with numeric complexity scoring (1-10 scale), structured test strategies, and CLI-accessible dependency validation. The changes improve sprint planning precision, test coverage expectations, and prevent circular dependency issues before workflow execution.
Key Changes:
- Added numeric complexity scoring framework alongside categorical estimates for backward compatibility
- Introduced structured test_strategy field with unit/integration/e2e breakdown per subtask
- Integrated dependency validator into mapify CLI for pip install users
Reviewed Changes
Copilot reviewed 13 out of 15 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
.claude/agents/task-decomposer.md |
Added 249-line complexity scoring framework (1-10 scale), decision table for test strategies, and 20 updated examples with new fields |
.claude/agents/actor.md |
Added 477-line research step guidance for MCP tools (context7/deepwiki/codex-bridge) with fallback strategies |
.claude/agents/monitor.md |
Added 111-line research quality validation section to verify Actor research completeness |
.claude/agents/evaluator.md |
Added 4-line research completeness checklist item |
src/mapify_cli/__init__.py |
Added validate_app Typer sub-app and validate graph command integration |
src/mapify_cli/tools/validate_dependencies.py |
New 748-line validator module with DFS cycle detection, ASCII rendering, and CLI interface |
src/mapify_cli/tools/__init__.py |
New module exports for validator components |
scripts/validate-dependencies.py |
Standalone 746-line validator script (duplicate of CLI tool for development) |
tests/test_validate_dependencies.py |
New 796-line test suite with 54 tests covering validation logic and CLI integration |
docs/USAGE.md |
Added 190-line dependency validation guide with examples and CI/CD integration |
README.md |
Added quick reference to validation commands and documentation link |
docs/analysis/task-master-integration.md |
New 309-line competitive analysis document with tier-based recommendations |
docs/analysis/playbook-changes-pending.md |
New 133-line playbook update guide with 5 new bullets across 3 sections |
Comments suppressed due to low confidence (1)
.claude/agents/task-decomposer.md:1
- [nitpick] The table header in line 686 appears to be documentation about comparison rather than template content for TaskDecomposer. This belongs in analysis documentation (task-master-integration.md) rather than in the agent template, as it adds cognitive overhead without providing actionable guidance for task decomposition.
---
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
## Critical Fix Synchronized agent templates from .claude/agents/ to src/mapify_cli/templates/agents/ so that users running 'mapify init' get the latest improvements, not outdated templates. ## Files Synchronized - task-decomposer.md - test_strategy field, enhanced examples, validation checklist - actor.md - research step integration (489 lines) - monitor.md - research quality validation (111 lines) - evaluator.md - research completeness scoring (4 lines) ## New Development Documentation Created .claude/CLAUDE.md with critical reminders: ### Template Synchronization Protocol - ALWAYS sync .claude/agents/ → src/mapify_cli/templates/agents/ after changes - Why: 'mapify init' uses distribution templates, not .claude/agents/ - Missing sync = new users get outdated templates ### Included in .claude/CLAUDE.md: - Template sync process (step-by-step) - Automatic sync check script (scripts/check-template-sync.sh) - Git pre-commit hook suggestion - MAP workflow enforcement rules - Template variable protection - Testing and commit message guidelines ## Impact Users installing via 'pip install mapify-cli' and running 'mapify init' will now receive all improvements from this PR, including: - TaskDecomposer test_strategy field - Enhanced complexity scoring examples - Research step in Actor template - Dependency validation checklist ## Related Part of PR #10 - Integrate Task Master improvements
Added scripts/check-template-sync.sh to verify agent templates are in sync between .claude/agents/ and src/mapify_cli/templates/agents/. Usage: ./scripts/check-template-sync.sh Exit codes: 0 - All templates synchronized 1 - Some templates out of sync (shows which ones) Checks all 8 agent files: - task-decomposer.md - actor.md - monitor.md - predictor.md - evaluator.md - reflector.md - curator.md - documentation-reviewer.md Can be integrated into: - Git pre-commit hooks - CI/CD pipelines - Developer workflow Prevents distributing outdated templates via 'mapify init'.
Fixed all issues identified by Copilot Pull Request Reviewer in PR #10. ## Issue 1: Class attribute mutation (CRITICAL) **Files**: scripts/validate-dependencies.py:460, src/mapify_cli/tools/validate_dependencies.py:462 **Problem**: Mutating ANSIColors class attributes at runtime created side effects. If render() called multiple times with different use_colors values, subsequent calls would not respect color preference. **Fix**: Replaced class attribute mutation with instance-level color mapping: - Created local color mapping (C) in render() method - If use_colors=True: C = ANSIColors (actual colors) - If use_colors=False: C = NoColors (empty strings) - Updated _get_task_color() to accept use_colors parameter - Updated _render_tree_node() to accept and propagate use_colors **Impact**: Thread-safe color handling, no side effects between calls. ## Issue 2: Wrong command in TaskDecomposer checklist **File**: .claude/agents/task-decomposer.md:1590 **Problem**: Checklist referenced `python scripts/validate-dependencies.py` but per PR's own CLI integration goal, should recommend `mapify validate graph`. **Fix**: Updated checklist to: - Primary: `mapify validate graph output.json` - Fallback: `python scripts/validate-dependencies.py output.json` (for development) **Impact**: Users directed to correct CLI command post-installation. ## Issue 3: Knowledge cutoff date inconsistency **File**: .claude/agents/monitor.md:857 **Problem**: Example stated "Next.js 14 Server Actions (released 2023, post-training-cutoff)" but knowledge cutoff is January 2025. This confuses what constitutes post-cutoff content. **Fix**: Changed to generic example: - Old: "Next.js 14 Server Actions (released 2023, post-training-cutoff)" - New: "latest framework features (released after training cutoff, e.g., Next.js 15+ features)" **Impact**: No confusion about cutoff dates, future-proof example. ## Testing All 54 tests pass (0.22s): ```bash pytest tests/test_validate_dependencies.py -v # 54 passed in 0.22s ✓ ``` ## Template Synchronization Synced updated agent templates: - .claude/agents/task-decomposer.md → src/mapify_cli/templates/agents/ - .claude/agents/monitor.md → src/mapify_cli/templates/agents/ Users installing via `mapify init` will receive corrected templates. ## Copilot Low-Confidence Comment (Rejected) **.claude/agents/task-decomposer.md:686** - "Table header appears to be documentation about comparison rather than template content" **Decision**: REJECTED - This is the Test Layer Decision Table that provides actionable guidance for TaskDecomposer to determine test_strategy for different subtask types (Data Model, API Endpoint, UI Component, etc.). This is critical template content, not comparison documentation.
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 6 comments.
Comments suppressed due to low confidence (1)
scripts/validate-dependencies.py:1
- This script is an exact duplicate of
src/mapify_cli/tools/validate_dependencies.py(761 identical lines). The PR description states this is for 'development use' while the CLI module is for 'pip install users', but maintaining two identical copies violates DRY principles and creates maintenance burden. Consider making the script import from the CLI module:from mapify_cli.tools.validate_dependencies import main; if __name__ == '__main__': main()
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Fixed all issues from second Copilot review of PR #10. ## Issue 1: Confusing variable naming (in_degree) **File**: src/mapify_cli/tools/validate_dependencies.py:370 **Problem**: Variable named `in_degree` actually counted how many tasks depend on each task (out-degree), not how many dependencies each task has (in-degree). **Fix**: Renamed to `dependency_count` with clarifying comments: - Explains graph semantics: adjacency[A] = [B] means "A depends on B" - Documents that we count how many times each task appears as a dependency - Clarifies algorithm starts with leaf nodes (tasks no one depends on) ## Issue 2: Missing rounding rule **File**: src/mapify_cli/templates/agents/task-decomposer.md:651 **Problem**: Example showed "3 + 1 = 4 → round down to 3" but didn't explain the rounding rule. **Fix**: Added explicit ROUNDING RULES section: - Scores are integers (no decimals) - Well-known patterns round DOWN to milestones (3, 6, 9) - Novel/risky implementations round UP - Milestone thresholds: 3 (simple), 6 (medium), 9 (complex) ## Issue 3: Categorical vs numeric complexity relationship **File**: src/mapify_cli/templates/agents/task-decomposer.md:1501 **Problem**: `analysis.complexity` described as categorical (low/medium/high) but new numeric scoring (1-10) introduced without explaining the relationship. **Fix**: Added aggregation guidelines: - **low**: Most subtasks 1-4, feature in 1-2 sprints - **medium**: Mix of subtasks 3-7, 2-4 sprints, architectural decisions - **high**: Multiple subtasks 6-10, cross-cutting concerns, >4 sprints, high risk ## Issue 4: Citation format unclear **File**: src/mapify_cli/templates/agents/actor.md:684 **Problem**: Citation `(context7: /vercel/next.js)` unclear - is it a URL or library ID? **Fix**: Added Citation Format section explaining: - `/vercel/next.js` is a library identifier, NOT a URL - context7 tool resolves ID to documentation content - Format: `(context7: <library-id>)` with optional version - Also documented deepwiki and codex-bridge formats ## Issue 5 & 6: Exit code handling (CRITICAL) **Files**: src/mapify_cli/__init__.py:1977, docs/USAGE.md:180 **Problem**: Exit code 1 for warnings too strict for CI/CD. Documentation promised exit code 2 for malformed input but implementation used 1 for all failures. Mismatch between docs and code. **Fix**: Added `--strict` flag for flexible CI/CD integration: - Exit 0: No critical errors (warnings OK by default) - Exit 1: Critical errors OR warnings with `--strict` flag - Exit 2: Malformed input (invalid JSON, missing fields) Updated documentation with examples: ```bash # Default: only critical errors fail mapify validate graph plan.json || exit 1 # Strict: warnings also fail mapify validate graph --strict plan.json || exit 1 ``` ## Issue 7: Code duplication (low-confidence) **File**: scripts/validate-dependencies.py **Problem**: 761-line exact duplicate of src/mapify_cli/tools/validate_dependencies.py created maintenance burden. **Fix**: Replaced with 14-line import wrapper: ```python from mapify_cli.tools.validate_dependencies import main if __name__ == "__main__": main() ``` Maintains backward compatibility, eliminates duplication. ## Template Synchronization Synced updated templates to distribution: - .claude/agents/task-decomposer.md → src/mapify_cli/templates/agents/ - .claude/agents/actor.md → src/mapify_cli/templates/agents/ ## Testing All 54 tests pass (0.21s): ```bash pytest tests/test_validate_dependencies.py -v # 54 passed in 0.21s ✓ ``` Scripts wrapper verified working: ```bash python scripts/validate-dependencies.py --help # Works ✓ ``` ## Summary - 6 substantive issues fixed (plus 1 low-confidence) - Exit code behavior now CI/CD friendly with --strict flag - Code duplication eliminated (761 lines → 14 line wrapper) - Variable naming clarified (dependency_count vs in_degree) - Documentation gaps filled (rounding rules, aggregation, citation format)
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Round 3 Copilot reviewer comments addressed: 1. **Test: Confusing topological sort comment** (test_validate_dependencies.py:445) - Replaced incorrect comment with proper verification loop - Verifies dependencies appear before dependents in sorted order - Exposed existing bug in _topological_sort() algorithm 2. **Test: Replace DFS jargon 'back-edge'** (test_validate_dependencies.py:761) - Changed "back-edge" to clearer terminology - Now: "introduce a dependency from a descendant back to an ancestor" 3. **Algorithm fix: Topological sort produced reverse order** - Root cause: Algorithm counted OUT-degree instead of IN-degree - Fixed to count proper in-degree (how many dependencies each task has) - Now starts with root nodes (no dependencies) instead of leaf nodes - Produces correct topological order where dependencies appear before dependents Test results: ✅ All 54 tests pass Co-authored-by: GitHub Copilot <noreply@github.com>
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
src/mapify_cli/tools/validate_dependencies.py:1
- Line 766 contains a comment embedded within test code that explains cycle creation, but this comment appears in the production validator module rather than in the test file where it would be more appropriate. This documentation should be moved to the test file (tests/test_validate_dependencies.py) around line 766-778 where the cyclic_data test case is defined.
#!/usr/bin/env python3
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Round 4 Copilot reviewer comments addressed: 1. **Test: Confusing '# No cycle!' comment** (test_validate_dependencies.py:764) - Changed from: "# No cycle!" - To: "# Valid DAG - no cycle detected" - Clarifies that test verifies absence of cycles is correctly detected 2. **Validator: Misleading in_degree comment** (validate_dependencies.py:367) - Added clarification about graph theory terminology - Explains these are "outgoing edges from A in dependency graph" - Added note explaining why we call it "in-degree" despite being outgoing edges - Relates to incoming dependencies that must be satisfied before execution 3. **CLI: Unclear --strict flag help text** (__init__.py:1950) - Changed from: "Fail on warnings (exit code 1), not just critical errors" - To: "Fail on warnings (e.g., orphaned tasks), not just critical errors (cycles, forward refs)" - Provides concrete examples of warnings and critical errors 4. **Docs: Missing --strict flag in reference table** (USAGE.md:306) - Added --strict flag row to Command-Line Flags Reference table - Description: "Fail on warnings (e.g., orphaned tasks), not just critical errors" Test results: ✅ All 54 tests pass Co-authored-by: GitHub Copilot <noreply@github.com>
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Round 5 Copilot reviewer comments addressed: 1. **Test: Misleading DAG comment about multiple paths** (test_validate_dependencies.py:755-757) - Changed from: "This is NOT a cycle! 5 depends on both 2 and 4, which is valid in a DAG" - To: "This creates two paths to node 5: (1->2->3->4->5) and (1->2->5)" - Added: "Multiple paths to the same node do NOT create a cycle in a DAG" - Added: "This is valid: 5 depends on both 2 and 4 (diamond dependency pattern)" - Clarifies that having multiple paths doesn't create cycles 2. **Validator: Incorrect command in docstring** (validate_dependencies.py:13) - Changed from: `mapify validate <file>` - To: `mapify validate graph <file> [--visualize] [--no-color] [-f json|text] [--strict]` - Added missing `graph` subcommand (required) - Added missing `--strict` flag to usage example Test results: ✅ All 54 tests pass Co-authored-by: GitHub Copilot <noreply@github.com>
There was a problem hiding this comment.
Pull Request Overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…-35) MEDIUM fixes: - #8: Remove dead RETRY_LOOP phase from orchestrator STEP_PHASES - #10: Fix plan path to branch-scoped .map/<branch>/task_plan_<branch>.md - #11: Fix findings path to branch-scoped .map/<branch>/findings_<branch>.md - #12: Remove references to non-existent ralph-loop-config.json - #13/#14: Rewrite map-resume to use step_state.json instead of progress.md - #15: Fix INIT_PLAN heading format (### ST-XXX with - **Status:** prefix) - #16: Fix regex in step_runner to match plan format (### heading, - **Status:**) - #17: Fix map-learn contradiction about automatic learning LOW fixes: - #9/#31: Document dual state file system (step_state.json vs workflow_state.json) - #19: Document intentional Evaluator/Reflector/Curator omission in map-efficient - #20: Fix line count reference (~150 → ~540 lines) - #21: Standardize all AskUserQuestion to Python function call syntax - #22: Rename Steps 2.5/2.6 to 2a/2b to avoid phase number collision - #23/#24: Fix map-debate comparison table (map-efficient uses single Actor) - #25: Replace cat commands with Read tool comments in map-check - #28/#29: Replace undefined thrashing_detected()/max_redecompositions - #30: Add - **Status:** pending field to map-plan template - #32: Note map-fast max 3 vs map-efficient max 5 intentional difference - #33: Remove Evaluator from map-fast skipped agents list - #34: Move AskUserQuestion to "Built-in Tools" section in map-release - #35: Replace parallel bash & processes with sequential && in map-release Template sync: All .claude/ changes mirrored to src/mapify_cli/templates/
Summary
Integrated all 9 subtasks from Task Master analysis (
docs/analysis/task-master-integration.md), enhancing MAP Framework with improved task decomposition, dependency validation, and CLI accessibility.Key Improvements
🎯 Core Enhancements
🔧 CLI Integration (Critical User-Identified Gap)
Problem: Dependency validator only worked in dev environment (scripts/ not distributed via pip)
Solution: Integrated validator into mapify CLI with
mapify validate graphcommandImpact: Pip install users can now validate task dependencies without cloning repository
📊 Validation Features
--visualizeflag📚 Documentation
Implementation Quality
All subtasks completed with full MAP workflow cycles:
Playbook Updates
Added 14 new patterns + updated 3 existing:
CLI_TOOL_PATTERNS- deployment model requirementsFiles Changed
Templates (4 files):
.claude/agents/task-decomposer.md- test_strategy, examples, checklist.claude/agents/actor.md- research step (489 lines).claude/agents/monitor.md- research validation (111 lines).claude/agents/evaluator.md- research completeness (4 lines)CLI (3 files):
src/mapify_cli/__init__.py- validate_app Typer sub-appsrc/mapify_cli/tools/validate_dependencies.py- validator module (684 lines)src/mapify_cli/tools/__init__.py- exportsUtilities (1 file):
scripts/validate-dependencies.py- standalone validator (684 lines)Tests (1 file):
tests/test_validate_dependencies.py- 54 tests (760 lines)Documentation (2 files):
docs/USAGE.md- comprehensive validation guideREADME.md- quick referenceKnowledge (1 file):
.claude/playbook.json- 14 new + 3 updated patternsTesting
Breaking Changes
None - all changes are additive and backward compatible.
Migration Notes
Users can now validate TaskDecomposer outputs via CLI:
Related Issues
Addresses user feedback: "и как предполагается его запускать если пользователь поставил map через pip install? Я полагаю он должен быть встроен в mapify"
Checklist