Skip to main content

Work Item Hierarchy Implementation - Multi-Agent Orchestration Plan

Document: WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN
Version: 1.0.0
Status: ACTIVE
Created: 2025-12-13
Owner: CODITECT Orchestrator Agent
Related ADR: ADR-006-WORK-ITEM-HIERARCHY
Related Standard: CODITECT-STANDARD-WORK-ITEMS
Execution Model: Multi-Agent Coordination with Parallel Work Streams
Estimated Duration: 8-12 weeks (320-480 engineering hours)
Token Budget: 180K total (90% of 200K budget, 10% reserved for coordination)

🎯 Executive Summary​

Implementation Goal​

Implement comprehensive Work Item Hierarchy system (Project → Sub-Project → Epic → Feature → Task → Subtask) with Sprint management, automatic completion rollup, and full /cxq integration.

Success Criteria​

  • ✅ Complete database schema with 4 core tables + 7 views
  • ✅ 6 new slash commands operational (/project, /epic, /feature, /task, /sprint, /workitems)
  • ✅ Extended /cxq with 10+ new query modes
  • ✅ Import/export functionality for markdown round-tripping
  • ✅ Automatic percentage rollup working correctly
  • ✅ 95%+ test coverage for all new functionality
  • ✅ Migration path for existing PROJECT-PLAN.md files
  • ✅ Complete documentation and HOW-TO guides

Orchestration Approach​

Multi-agent coordination with bounded parallelism:

  • Phase 1-2: Sequential (foundation must be solid)
  • Phase 3: 3-way parallel (commands development)
  • Phase 4: 2-way parallel (import/export + templates)
  • Phase 5: Sequential (integration and migration)

Agent Team (9 Specialists)​

  1. database-architect - Schema design and migration
  2. backend-engineer - Python module development
  3. command-developer (×3) - Slash command implementation
  4. integration-engineer - /cxq extension
  5. template-designer - Template and standards creation
  6. test-engineer - Test suite development
  7. orchestrator - Coordination and synthesis

📊 Gap Analysis​

Current State Assessment​

What Exists:

  • ✅ scripts/context-db.py - SQLite foundation (1,000+ lines)
  • ✅ /cxq command - Query interface operational
  • ✅ PROJECT-PLAN-TEMPLATE.md - Basic template
  • ✅ TASKLIST-WITH-CHECKBOXES-TEMPLATE.md - Checkbox tracking
  • ✅ ADR-006 - Complete specification approved
  • ✅ CODITECT-STANDARD-WORK-ITEMS - Naming convention standard

What's Missing:

  • ❌ Work item hierarchy tables (projects, sub_projects, work_items, sprints)
  • ❌ Completion rollup views (7 SQL views)
  • ❌ Python CRUD module for work items
  • ❌ 6 new slash commands
  • ❌ /cxq extensions (--epic-progress, --sprint-status, etc.)
  • ❌ Markdown import/export parser
  • ❌ Updated templates (V2 versions)
  • ❌ HOW-TO guides (5 guides needed)
  • ❌ Migration scripts for existing data
  • ❌ Test coverage for new features

Impacted Files Analysis​

Database Layer (2 files):

  • scripts/context-db.py - Add 4 tables + 7 views + indexes (~500 new lines)
  • scripts/work_items.py - NEW: CRUD operations module (~800 lines)

Command Layer (7 files):

  • commands/project.md - NEW: Project/sub-project management
  • commands/epic.md - NEW: Epic CRUD operations
  • commands/feature.md - NEW: Feature CRUD operations
  • commands/task.md - NEW: Task/subtask management
  • commands/sprint.md - NEW: Sprint planning
  • commands/workitems.md - NEW: Import/export operations
  • commands/cxq.md - MODIFY: Add 10+ new query modes (~300 new lines)

Template Layer (7 files):

  • CODITECT-CORE-STANDARDS/TEMPLATES/PROJECT-PLAN-TEMPLATE-V2.md - NEW
  • CODITECT-CORE-STANDARDS/TEMPLATES/TASKLIST-TEMPLATE-V2.md - NEW
  • CODITECT-CORE-STANDARDS/PROJECT-REPORTING-STANDARD.md - NEW
  • CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-EPIC.md - NEW
  • CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-FEATURE.md - NEW
  • CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-TASK.md - NEW
  • CODITECT-CORE-STANDARDS/HOW-TO-PLAN-SPRINT.md - NEW

Migration Layer (2 files):

  • scripts/migrate-project-plans.py - NEW: Import existing PROJECT-PLAN.md files
  • scripts/work-items-demo.py - NEW: Demo data generator for testing

Test Layer (3 files):

  • scripts/test-suite.py - MODIFY: Add work_items test category
  • tests/test_work_items.py - NEW: Unit tests for CRUD module
  • tests/test_work_item_commands.py - NEW: Integration tests for commands

Documentation Layer (5 files):

  • docs/02-user-guides/WORK-ITEM-HIERARCHY-GUIDE.md - NEW: User guide
  • docs/03-architecture/adrs/ADR-005-work-item-hierarchy.md - EXISTS: Already created
  • CODITECT-CORE-STANDARDS/CODITECT-STANDARD-WORK-ITEMS.md - EXISTS: Already created
  • docs/08-agent-reference/WORK-ITEMS-COMMAND-REFERENCE.md - NEW: Command reference
  • CHANGELOG.md - UPDATE: Document v2.0.0 release

Configuration (2 files):

  • config/component-counts.json - UPDATE: Add 6 new commands
  • .coditect/component-activation-status.json - UPDATE: Add 6 new commands

Total Impact:

  • 2 modified files (context-db.py, cxq.md, test-suite.py, component configs)
  • 23 new files created
  • ~4,200 lines of code to implement
  • ~8,000 lines of documentation to write

🏗️ Implementation Phases​

Phase 1: Database Schema & Core Infrastructure (P0)​

Duration: 2 weeks (80 hours) Token Budget: 30K tokens Agent: database-architect Dependencies: None (foundation layer)

Tasks (Detailed)​

  1. Schema Design (16 hours)

    • T0001: Create projects table with constraints
    • T0002: Create sub_projects table with FK to projects
    • T0003: Create sprints table with date validation
    • T0004: Create work_items unified table
    • T0005: Add all indexes (8 indexes across tables)
    • T0006: Add foreign key constraints with ON DELETE actions
    • T0007: Write schema migration script
    • T0008: Unit test schema creation

  2. View Creation (24 hours)

    • T0009: Create work_item_children_stats view
    • T0010: Create work_item_progress view with rollup logic
    • T0011: Create epic_progress summary view
    • T0012: Create sprint_burndown view
    • T0013: Create project_progress overview view
    • T0014: Create sub_project_progress view
    • T0015: Create work_item_dependencies view (optional)
    • T0016: Test view performance with 1000+ work items

  3. CRUD Module (32 hours)

    • T0017: Create scripts/work_items.py module
    • T0018: Implement Project CRUD operations
    • T0019: Implement Sub-Project CRUD operations
    • T0020: Implement Work Item CRUD (generic for E/F/T/ST)
    • T0021: Implement Sprint CRUD operations
    • T0022: Implement completion rollup calculation
    • T0023: Implement recursive descendant queries
    • T0024: Add transaction support and error handling
    • T0025: Write comprehensive unit tests (95%+ coverage)

  4. Migration Integration (8 hours)

    • T0026: Integrate schema into context-db.py get_db()
    • T0027: Add database version tracking
    • T0028: Create migration rollback functionality
    • T0029: Test on existing context.db databases

Deliverables:

  • ✅ 4 tables created with all constraints
  • ✅ 7 views operational
  • ✅ scripts/work_items.py module with 100% test coverage
  • ✅ Schema integrated into context-db.py
  • ✅ Migration path tested

Acceptance Criteria:

  • Can create Project → Epic → Feature → Task hierarchy
  • Completion % calculates correctly (by count and by points)
  • All queries run in <100ms for 1000+ work items
  • No SQL injection vulnerabilities
  • All foreign keys enforce referential integrity

Phase 2: Command Implementation (P0)​

Duration: 3 weeks (120 hours) Token Budget: 45K tokens Agents: command-developer (×3) in parallel Dependencies: Phase 1 complete

Parallel Work Streams​

Stream A: Project & Sprint Commands (40 hours, command-developer-1)

  • T0030: Create /project command spec
  • T0031: Implement /project create
  • T0032: Implement /project list
  • T0033: Implement /project status
  • T0034: Implement /project archive
  • T0035: Create /sprint command spec
  • T0036: Implement /sprint create
  • T0037: Implement /sprint list
  • T0038: Implement /sprint active
  • T0039: Implement /sprint burndown
  • T0040: Implement /sprint plan (interactive)
  • T0041: Implement /sprint close
  • T0042: Write integration tests (both commands)
  • T0043: Update component activation status

Stream B: Epic & Feature Commands (40 hours, command-developer-2)

  • T0044: Create /epic command spec
  • T0045: Implement /epic create
  • T0046: Implement /epic list
  • T0047: Implement /epic progress
  • T0048: Implement /epic details --tree
  • T0049: Create /feature command spec
  • T0050: Implement /feature create
  • T0051: Implement /feature list
  • T0052: Implement /feature progress
  • T0053: Implement /feature assign (to epic)
  • T0054: Write integration tests (both commands)
  • T0055: Update component activation status

Stream C: Task & Work Items Commands (40 hours, command-developer-3)

  • T0056: Create /task command spec
  • T0057: Implement /task create
  • T0058: Implement /task list with filters
  • T0059: Implement /task start (status update)
  • T0060: Implement /task complete
  • T0061: Implement /task block / /task unblock
  • T0062: Implement /task assign (sprint/assignee)
  • T0063: Create /workitems command spec
  • T0064: Implement /workitems import
  • T0065: Implement /workitems export (JSON/CSV/Markdown)
  • T0066: Write integration tests (both commands)
  • T0067: Update component activation status

Deliverables:

  • ✅ 6 new commands fully operational
  • ✅ All commands activated in component registry
  • ✅ Integration tests with 90%+ coverage
  • ✅ Command reference documentation

Acceptance Criteria:

  • All commands accessible via /command-name
  • Error handling for invalid inputs
  • Helpful error messages with suggestions
  • JSON output available for automation
  • Commands respect ID validation rules

Phase 3: Query Interface Extension (P0)​

Duration: 2 weeks (80 hours) Token Budget: 35K tokens Agent: integration-engineer Dependencies: Phase 1-2 complete

Tasks​

  1. Core Query Extensions (40 hours)

    • T0068: Modify commands/cxq.md to add new modes
    • T0069: Implement --epic-progress <ID>
    • T0070: Implement --feature-progress <ID>
    • T0071: Implement --sprint-status <ID>
    • T0072: Implement --project-status <ID>
    • T0073: Implement --velocity --sprints N
    • T0074: Implement --blocked (all blocked items)
    • T0075: Implement --overdue (past due items)
    • T0076: Implement --unassigned (tasks without assignee)
    • T0077: Implement --my-tasks (current user filter)
    • T0078: Add --work-item <ID> (detailed work item view)

  2. Output Formatting (24 hours)

    • T0079: Design progress bar visualization
    • T0080: Design hierarchical tree output
    • T0081: Design sprint burndown chart (ASCII)
    • T0082: Implement table formatting for lists
    • T0083: Implement JSON output for all queries
    • T0084: Add color coding (green=completed, yellow=in_progress, red=blocked)

  3. Integration Testing (16 hours)

    • T0085: Test all query modes with demo data
    • T0086: Performance test with 1000+ work items
    • T0087: Test edge cases (empty projects, orphaned items)
    • T0088: Update cxq.md documentation with examples

Deliverables:

  • ✅ /cxq extended with 10+ new query modes
  • ✅ Beautiful ASCII visualizations for progress
  • ✅ JSON output for automation
  • ✅ Updated documentation with examples

Acceptance Criteria:

  • All queries return results in <1 second
  • Output is human-readable and informative
  • JSON output is valid and complete
  • Help text updated with new modes

Phase 4: Templates & Standards (P1)​

Duration: 2 weeks (80 hours) Token Budget: 30K tokens Agents: template-designer + documentation-writer (parallel) Dependencies: Phase 1-3 complete

Parallel Work Streams​

Stream A: Templates (40 hours, template-designer)

  • T0089: Create PROJECT-PLAN-TEMPLATE-V2.md with hierarchy
  • T0090: Create TASKLIST-TEMPLATE-V2.md with rollup
  • T0091: Create PROJECT-REPORTING-STANDARD.md
  • T0092: Create SPRINT-RETROSPECTIVE-TEMPLATE.md
  • T0093: Test templates with real data
  • T0094: Add templates to CODITECT-CORE-STANDARDS/

Stream B: HOW-TO Guides (40 hours, documentation-writer)

  • T0095: Create HOW-TO-CREATE-NEW-EPIC.md
  • T0096: Create HOW-TO-CREATE-NEW-FEATURE.md
  • T0097: Create HOW-TO-CREATE-NEW-TASK.md
  • T0098: Create HOW-TO-PLAN-SPRINT.md
  • T0099: Create HOW-TO-MIGRATE-EXISTING-PLAN.md
  • T0100: Create WORK-ITEM-HIERARCHY-GUIDE.md (comprehensive)
  • T0101: Update COMPONENT-REFERENCE.md with new commands

Deliverables:

  • ✅ 4 new templates ready for use
  • ✅ 5 HOW-TO guides complete
  • ✅ 1 comprehensive user guide

Acceptance Criteria:

  • Templates follow CODITECT standard format
  • HOW-TO guides are actionable (copy-paste commands)
  • User guide covers all major workflows
  • Documentation reviewed for clarity

Phase 5: Import/Export & Migration (P1)​

Duration: 2 weeks (80 hours) Token Budget: 30K tokens Agent: backend-engineer Dependencies: Phase 1-4 complete

Tasks​

  1. Markdown Parser (32 hours)

    • T0102: Design parser for PROJECT-PLAN.md format
    • T0103: Implement Phase detection
    • T0104: Implement Epic extraction (### Epic: E001 - Title)
    • T0105: Implement Feature extraction (#### Feature: F001 - Title)
    • T0106: Implement Task extraction (- [ ] T001: Title)
    • T0107: Handle checkbox states ([ ], [x], [>], [!])
    • T0108: Extract story points from task lines
    • T0109: Parse sprint assignments (#S23)
    • T0110: Write comprehensive parser tests

  2. Export Functionality (24 hours)

    • T0111: Implement JSON export (full hierarchy)
    • T0112: Implement CSV export (flat task list)
    • T0113: Implement Markdown export (round-trip format)
    • T0114: Test round-trip (import → export → import)
    • T0115: Validate exported data integrity

  3. Migration Script (24 hours)

    • T0116: Create scripts/migrate-project-plans.py
    • T0117: Auto-discover PROJECT-PLAN.md files
    • T0118: Batch import with progress reporting
    • T0119: Handle import errors gracefully
    • T0120: Generate migration report (summary statistics)
    • T0121: Create rollback functionality
    • T0122: Test on real CODITECT projects

Deliverables:

  • ✅ Markdown import parser operational
  • ✅ 3 export formats (JSON, CSV, Markdown)
  • ✅ Migration script tested on existing data
  • ✅ Migration report generated

Acceptance Criteria:

  • Parser handles 95%+ of existing PROJECT-PLAN.md files
  • Round-trip preserves all data
  • Migration script runs without errors
  • Rollback functionality tested

Phase 6: Testing & Documentation (P0)​

Duration: 1 week (40 hours) Token Budget: 20K tokens Agent: test-engineer Dependencies: Phase 1-5 complete

Tasks​

  1. Test Suite Expansion (24 hours)

    • T0123: Add work_items category to test-suite.py
    • T0124: Write unit tests for CRUD module (target 95%+)
    • T0125: Write integration tests for commands
    • T0126: Write end-to-end tests (create → update → query → delete)
    • T0127: Write performance tests (1000+ items)
    • T0128: Test error handling and edge cases
    • T0129: Run full test suite and fix failures

  2. Documentation Finalization (16 hours)

    • T0130: Create WORK-ITEMS-COMMAND-REFERENCE.md
    • T0131: Update CHANGELOG.md for v2.0.0
    • T0132: Update README.md with work items feature
    • T0133: Create demo video/GIF showing workflows
    • T0134: Review all documentation for consistency
    • T0135: Create troubleshooting section

Deliverables:

  • ✅ Test coverage 95%+ for all new code
  • ✅ All tests passing
  • ✅ Complete command reference
  • ✅ Updated CHANGELOG and README

Acceptance Criteria:

  • Test suite runs in <5 minutes
  • No failing tests
  • Documentation is clear and complete
  • Demo materials ready for users

🔀 Dependency Graph​

Phase 1: Database Schema (Foundation)
    ↓
Phase 2: Commands (3 parallel streams)
    ├─→ Stream A: /project, /sprint
    ├─→ Stream B: /epic, /feature
    └─→ Stream C: /task, /workitems
    ↓
Phase 3: /cxq Integration
    ↓
Phase 4: Templates & Docs (2 parallel streams)
    ├─→ Stream A: Templates
    └─→ Stream B: HOW-TO Guides
    ↓
Phase 5: Import/Export & Migration
    ↓
Phase 6: Testing & Documentation

Critical Path: Phase 1 → Phase 2 → Phase 3 → Phase 5 → Phase 6 (9 weeks) Parallel Optimization: Phase 2 saves 6 weeks, Phase 4 saves 2 weeks Total Duration: 10 weeks (vs. 18 weeks sequential)

👥 Agent Assignment Matrix​

PhaseAgentRoleToolsEstimated Tokens
1database-architectSchema designRead, Write, Bash30K
2Acommand-developer-1/project, /sprintWrite, Read15K
2Bcommand-developer-2/epic, /featureWrite, Read15K
2Ccommand-developer-3/task, /workitemsWrite, Read15K
3integration-engineer/cxq extensionEdit, Read, Bash35K
4Atemplate-designerTemplatesWrite15K
4Bdocumentation-writerHOW-TO guidesWrite15K
5backend-engineerImport/exportWrite, Read, Bash30K
6test-engineerTestingWrite, Bash20K
-orchestratorCoordinationAll10K

Total: 200K tokens (100% of budget) Agents: 9 specialists + 1 orchestrator

📈 Progress Tracking​

Phase Completion Checklist​

Phase 1: Database Schema ✅​

  • All 4 tables created
  • All 7 views operational
  • CRUD module complete (800 lines)
  • Unit tests passing (95%+ coverage)
  • Migration integrated

Phase 2: Commands ✅​

  • 6 commands implemented
  • All commands activated
  • Integration tests passing
  • Documentation complete

Phase 3: Query Extension ✅​

  • 10+ new query modes
  • Visualizations working
  • JSON output validated
  • Performance tests passing

Phase 4: Templates & Standards ✅​

  • 4 templates created
  • 5 HOW-TO guides written
  • User guide complete
  • Documentation reviewed

Phase 5: Import/Export ✅​

  • Markdown parser working
  • 3 export formats operational
  • Migration script tested
  • Round-trip verified

Phase 6: Testing & Docs ✅​

  • Test coverage 95%+
  • All tests passing
  • Command reference complete
  • CHANGELOG updated

Success Metrics​

MetricTargetActual
Database tables4-
SQL views7-
New commands6-
Lines of code4,200+-
Lines of docs8,000+-
Test coverage95%+-
Query performance<1s for 1000+ items-
Migration success rate95%+-

🚨 Risk Mitigation​

Technical Risks​

Risk 1: Schema Migration Breaks Existing Database

  • Probability: Medium
  • Impact: High
  • Mitigation:
    • Create backup before migration
    • Test on copy of production database
    • Implement rollback functionality
    • Version database schema

Risk 2: Performance Degradation with Large Datasets

  • Probability: Medium
  • Impact: Medium
  • Mitigation:
    • Add comprehensive indexes
    • Use pre-computed views
    • Benchmark with 10K+ work items
    • Optimize recursive queries

Risk 3: Import Parser Fails on Edge Cases

  • Probability: High
  • Impact: Low
  • Mitigation:
    • Extensive test suite with real data
    • Graceful error handling
    • Manual import fallback
    • Import validation report

Risk 4: Agent Coordination Failures

  • Probability: Low
  • Impact: High
  • Mitigation:
    • Clear handoff protocols
    • Phase completion validation
    • Checkpoints between phases
    • Orchestrator oversight

Project Risks​

Risk 5: Scope Creep

  • Mitigation: Strict adherence to ADR-006 specification, defer nice-to-haves to Phase 7

Risk 6: Token Budget Exceeded

  • Mitigation: Monitor token usage per phase, compress outputs, use checkpoints

Risk 7: Timeline Slippage

  • Mitigation: Weekly progress reviews, adjust parallel work streams if needed

🎯 Quality Gates​

Gate 1: After Phase 1 (Database)​

  • ✅ All tables created without errors
  • ✅ All views return correct results
  • ✅ CRUD module has 95%+ test coverage
  • ✅ Performance benchmarks met (<100ms queries)
  • Decision: Proceed to Phase 2 OR fix issues

Gate 2: After Phase 2 (Commands)​

  • ✅ All 6 commands functional
  • ✅ Integration tests pass
  • ✅ Commands activated in registry
  • ✅ No critical bugs
  • Decision: Proceed to Phase 3 OR fix issues

Gate 3: After Phase 3 (Integration)​

  • ✅ All /cxq modes working
  • ✅ Output formatting correct
  • ✅ JSON output validated
  • ✅ Performance acceptable
  • Decision: Proceed to Phase 4 OR fix issues

Gate 4: After Phase 5 (Import/Export)​

  • ✅ Round-trip import/export working
  • ✅ Migration script tested
  • ✅ 95%+ import success rate
  • ✅ Data integrity validated
  • Decision: Proceed to Phase 6 OR fix issues

Gate 5: Final Release Gate​

  • ✅ All tests passing (95%+ coverage)
  • ✅ Documentation complete
  • ✅ CHANGELOG updated
  • ✅ Demo materials ready
  • ✅ Migration path validated
  • Decision: RELEASE v2.0.0 OR hold for fixes

📋 Execution Plan (Week-by-Week)​

Week 1-2: Phase 1 - Database Foundation​

Agent: database-architect

Week 1:

  • Days 1-2: Schema design and review
  • Days 3-4: Table creation and view implementation
  • Day 5: CRUD module scaffolding

Week 2:

  • Days 1-3: CRUD operations implementation
  • Day 4: Unit test development
  • Day 5: Migration integration and testing

Checkpoint: Database schema operational, CRUD module complete

Week 3-5: Phase 2 - Commands (Parallel)​

Agents: command-developer-1, command-developer-2, command-developer-3

Week 3:

  • All agents: Command spec design and review
  • All agents: Start implementation of primary commands

Week 4:

  • All agents: Complete command implementations
  • All agents: Integration testing

Week 5:

  • All agents: Bug fixes and refinement
  • All agents: Documentation and activation
  • Orchestrator: Synthesis and validation

Checkpoint: All 6 commands operational and tested

Week 6-7: Phase 3 - Query Extension​

Agent: integration-engineer

Week 6:

  • Days 1-3: Implement core query modes
  • Days 4-5: Output formatting and visualization

Week 7:

  • Days 1-2: Remaining query modes
  • Days 3-4: Integration testing
  • Day 5: Documentation update

Checkpoint: /cxq extended with all new modes

Week 8-9: Phase 4 - Templates & Standards (Parallel)​

Agents: template-designer, documentation-writer

Week 8:

  • template-designer: Create all 4 templates
  • documentation-writer: Create 3 HOW-TO guides

Week 9:

  • template-designer: Test templates with real data
  • documentation-writer: Create remaining 2 HOW-TO guides + user guide
  • Orchestrator: Review and synthesis

Checkpoint: Templates and HOW-TO guides complete

Week 10-11: Phase 5 - Import/Export & Migration​

Agent: backend-engineer

Week 10:

  • Days 1-3: Markdown parser implementation
  • Days 4-5: Export functionality (JSON, CSV, Markdown)

Week 11:

  • Days 1-3: Migration script development
  • Days 4-5: Testing on real data, migration report

Checkpoint: Import/export operational, migration tested

Week 12: Phase 6 - Final Testing & Documentation​

Agent: test-engineer

Week 12:

  • Days 1-2: Test suite expansion
  • Days 3-4: Documentation finalization
  • Day 5: Final review and release preparation

Checkpoint: v2.0.0 READY FOR RELEASE

🔧 Handoff Protocols​

Phase Completion Handoff​

From: Completing Agent To: Orchestrator Format: JSON + Markdown

Required Information:

  1. Completion Status:

    • All tasks marked complete (checkbox tracking)
    • Test results (pass/fail counts)
    • Known issues or limitations

  2. Deliverables:

    • List of created/modified files with paths
    • Line counts for new code
    • Token usage actual vs. estimated

  3. Next Phase Requirements:

    • Prerequisites for next phase
    • Any blocking issues
    • Recommended adjustments

Example Handoff:

{
  "phase": "Phase 1: Database Schema",
  "agent": "database-architect",
  "status": "COMPLETE",
  "completion_date": "2025-12-20",
  "tasks_completed": 29,
  "tasks_total": 29,
  "test_results": {
    "passed": 47,
    "failed": 0,
    "coverage": "96.2%"
  },
  "deliverables": [
    {
      "file": "scripts/context-db.py",
      "type": "modified",
      "lines_added": 523,
      "description": "Added 4 tables + 7 views"
    },
    {
      "file": "scripts/work_items.py",
      "type": "created",
      "lines": 847,
      "description": "CRUD module for work items"
    }
  ],
  "token_usage": {
    "estimated": 30000,
    "actual": 28547,
    "efficiency": "95.2%"
  },
  "known_issues": [],
  "next_phase_ready": true,
  "notes": "All performance benchmarks exceeded expectations. Ready for Phase 2."
}

Between-Agent Handoff (Parallel Streams)​

Coordination Points:

  • Daily standup (async via checkpoint files)
  • Shared component registry updates
  • Test suite integration
  • Documentation cross-references

📊 Final Deliverables Checklist​

Code Artifacts​

  • scripts/context-db.py - Modified (+500 lines)
  • scripts/work_items.py - Created (800 lines)
  • scripts/migrate-project-plans.py - Created (400 lines)
  • commands/project.md - Created
  • commands/epic.md - Created
  • commands/feature.md - Created
  • commands/task.md - Created
  • commands/sprint.md - Created
  • commands/workitems.md - Created
  • commands/cxq.md - Modified (+300 lines)

Test Artifacts​

  • tests/test_work_items.py - Created (500 lines)
  • tests/test_work_item_commands.py - Created (400 lines)
  • scripts/test-suite.py - Modified (work_items category)

Documentation Artifacts​

  • docs/02-user-guides/WORK-ITEM-HIERARCHY-GUIDE.md - Created
  • docs/08-agent-reference/WORK-ITEMS-COMMAND-REFERENCE.md - Created
  • CODITECT-CORE-STANDARDS/TEMPLATES/PROJECT-PLAN-TEMPLATE-V2.md - Created
  • CODITECT-CORE-STANDARDS/TEMPLATES/TASKLIST-TEMPLATE-V2.md - Created
  • CODITECT-CORE-STANDARDS/PROJECT-REPORTING-STANDARD.md - Created
  • CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-EPIC.md - Created
  • CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-FEATURE.md - Created
  • CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-TASK.md - Created
  • CODITECT-CORE-STANDARDS/HOW-TO-PLAN-SPRINT.md - Created
  • CHANGELOG.md - Updated (v2.0.0 entry)
  • README.md - Updated (work items feature)

Configuration Artifacts​

  • config/component-counts.json - Updated (+6 commands)
  • .coditect/component-activation-status.json - Updated (+6 commands)

Demo & Training Artifacts​

  • scripts/work-items-demo.py - Created (demo data generator)
  • Demo video/GIF showing workflows
  • Example PROJECT-PLAN-V2.md with hierarchy

🎉 Success Criteria Summary​

Functional Requirements​

  • ✅ Create Project → Sub-Project → Epic → Feature → Task → Subtask hierarchy
  • ✅ Completion % rolls up correctly through hierarchy (by count and by points)
  • ✅ Sprint burndown calculates correctly
  • ✅ Import from existing PROJECT-PLAN.md works
  • ✅ Export to JSON/CSV/Markdown works
  • ✅ Round-trip import/export preserves data

Performance Requirements​

  • ✅ Queries complete in <1s for 1000+ work items
  • ✅ Recursive rollup efficient for deep hierarchies (10+ levels)
  • ✅ Views update automatically on data changes
  • ✅ Import processes 100+ work items in <5s

Usability Requirements​

  • ✅ Commands are intuitive and well-documented
  • ✅ Output is human-readable with progress bars
  • ✅ JSON output is complete for automation
  • ✅ Error messages are helpful with suggestions

Quality Requirements​

  • ✅ Test coverage 95%+ for all new code
  • ✅ All tests passing
  • ✅ No critical bugs or security issues
  • ✅ Code follows CODITECT standards

📞 Contact & Support​

Orchestrator Agent: workflow-orchestrator Project Owner: CODITECT Core Team Related ADR: ADR-006-WORK-ITEM-HIERARCHY Related Standard: CODITECT-STANDARD-WORK-ITEMS

Questions or Issues:

  • Review this orchestration plan
  • Check phase-specific handoff documents
  • Consult related ADR or standard
  • Contact orchestrator for coordination

Document Version: 1.0.0 Last Updated: 2025-12-13 Status: ACTIVE - Ready for Execution Total Estimated Effort: 480 engineering hours (12 weeks) Token Budget: 180K tokens (90% of available budget) Expected Completion: March 2026

END OF ORCHESTRATION PLAN