Work Item Hierarchy Implementation Quick Start Guide

Work Item Hierarchy Implementation - Quick Start Guide

Document: WORK-ITEM-HIERARCHY-QUICK-START
Version: 1.0.0
Status: READY FOR EXECUTION
Created: 2025-12-13
For: Project Stakeholders and Implementation Team
Related: WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md

---

🎯 What Is This?

This is the implementation plan for CODITECT's Work Item Hierarchy system - a comprehensive project management framework that enables:

• Hierarchical tracking: Project → Sub-Project → Epic → Feature → Task → Subtask
• Sprint management: Time-boxed iterations with burndown tracking
• Automatic rollup: Completion percentages calculate from child tasks up to parent epics
• Full integration: New /project, /epic, /feature, /task, /sprint commands plus extended /cxq queries

---

📊 At a Glance

Metric	Value
Total Effort	480 engineering hours (12 weeks)
Implementation Phases	6 phases (sequential + parallel)
Specialized Agents	9 agents + 1 orchestrator
New Commands	6 slash commands
Database Changes	4 tables + 7 views
Lines of Code	~4,200 new lines
Lines of Documentation	~8,000 new lines
Test Coverage Target	95%+
Token Budget	180K (90% of 200K available)

---

🚀 Quick Start: How to Execute This Plan

Step 1: Review Planning Documents

Essential Reading (30 minutes):

1. ADR-005-work-item-hierarchy.md - Complete specification
2. CODITECT-STANDARD-WORK-ITEMS.md - Naming conventions
3. WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md - Detailed execution plan (this summary)

Step 2: Verify Prerequisites

Requirements:

• ✅ CODITECT framework installed and operational
• ✅ scripts/context-db.py accessible (current version)
• ✅ Python 3.10+ with SQLite support
• ✅ Git repository with clean working tree
• ✅ 200K token budget available (orchestration uses 180K)

Validation Commands:

# From coditect-core root
python3 --version                    # Should be 3.10+
python3 scripts/context-db.py --help # Should show help
git status                           # Should be clean

Step 3: Execute Phase 1 (Database Foundation)

Agent: database-architect Duration: 2 weeks (80 hours) Token Budget: 30K

Invocation:

# Use Task tool to invoke specialized agent
Task(
    subagent_type="database-architect",
    description="Implement work item hierarchy database schema",
    prompt="""
Execute Phase 1 of Work Item Hierarchy implementation:

**Scope:** Database Schema & Core Infrastructure

**Tasks (29 total):**
1. Create 4 tables: projects, sub_projects, sprints, work_items
2. Create 7 SQL views for completion rollup
3. Implement scripts/work_items.py CRUD module (800 lines)
4. Integrate schema into scripts/context-db.py
5. Write comprehensive unit tests (95%+ coverage)

**Reference Documents:**
- ADR-005-work-item-hierarchy.md (lines 217-494 for complete SQL schema)
- WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md (Phase 1 section)

**Deliverables:**
- scripts/context-db.py modified (+500 lines with schema)
- scripts/work_items.py created (800 lines CRUD module)
- tests/test_work_items.py created (unit tests)
- All tests passing with 95%+ coverage

**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
- Foreign key integrity enforced

**Token Budget:** 30K tokens
**Duration:** 2 weeks (80 hours)
"""
)

Expected Output:

• 4 database tables created
• 7 views operational
• CRUD module with full test coverage
• Migration path validated

Quality Gate 1: All acceptance criteria met before proceeding to Phase 2

---

Step 4: Execute Phase 2 (Commands) - Parallel Execution

Agents: command-developer-1, command-developer-2, command-developer-3 (parallel) Duration: 3 weeks (120 hours total, 40 hours per stream) Token Budget: 45K total (15K per agent)

Invocation (3 parallel Task calls in ONE message):

# Stream A: Project & Sprint Commands
Task(
    subagent_type="command-developer",
    description="Implement /project and /sprint commands",
    prompt="""
Execute Phase 2, Stream A: Project & Sprint Commands

**Tasks (14 tasks, T0030-T0043):**
1. Create commands/project.md specification
2. Implement /project create, list, status, archive
3. Create commands/sprint.md specification
4. Implement /sprint create, list, active, burndown, plan, close
5. Write integration tests for both commands
6. Update component activation status

**Reference:** WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md Phase 2, Stream A

**Deliverables:**
- commands/project.md (complete command spec)
- commands/sprint.md (complete command spec)
- Integration tests passing
- Component registry updated

**Token Budget:** 15K tokens
**Duration:** 3 weeks (40 hours)
"""
)

# Stream B: Epic & Feature Commands (parallel with Stream A)
Task(
    subagent_type="command-developer",
    description="Implement /epic and /feature commands",
    prompt="""
Execute Phase 2, Stream B: Epic & Feature Commands

**Tasks (12 tasks, T0044-T0055):**
1. Create commands/epic.md specification
2. Implement /epic create, list, progress, details --tree
3. Create commands/feature.md specification
4. Implement /feature create, list, progress, assign
5. Write integration tests for both commands
6. Update component activation status

**Reference:** WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md Phase 2, Stream B

**Deliverables:**
- commands/epic.md (complete command spec)
- commands/feature.md (complete command spec)
- Integration tests passing
- Component registry updated

**Token Budget:** 15K tokens
**Duration:** 3 weeks (40 hours)
"""
)

# Stream C: Task & WorkItems Commands (parallel with A & B)
Task(
    subagent_type="command-developer",
    description="Implement /task and /workitems commands",
    prompt="""
Execute Phase 2, Stream C: Task & WorkItems Commands

**Tasks (12 tasks, T0056-T0067):**
1. Create commands/task.md specification
2. Implement /task create, list, start, complete, block/unblock, assign
3. Create commands/workitems.md specification
4. Implement /workitems import, export (JSON/CSV/Markdown)
5. Write integration tests for both commands
6. Update component activation status

**Reference:** WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md Phase 2, Stream C

**Deliverables:**
- commands/task.md (complete command spec)
- commands/workitems.md (complete command spec)
- Integration tests passing
- Component registry updated

**Token Budget:** 15K tokens
**Duration:** 3 weeks (40 hours)
"""
)

Expected Output (after 3 weeks):

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

Quality Gate 2: All commands functional and tested before Phase 3

---

Step 5: Execute Remaining Phases

Phase 3: Query Extension (integration-engineer, 2 weeks)

• Extend /cxq with 10+ new query modes
• Implement progress visualizations
• Duration: 2 weeks, 80 hours, 35K tokens

Phase 4: Templates & Standards (2 agents parallel, 2 weeks)

• Create 4 new templates
• Write 5 HOW-TO guides
• Duration: 2 weeks, 80 hours, 30K tokens

Phase 5: Import/Export (backend-engineer, 2 weeks)

• Markdown parser for project-plan.md
• Export functionality (JSON/CSV/Markdown)
• Migration script for existing data
• Duration: 2 weeks, 80 hours, 30K tokens

Phase 6: Testing & Documentation (test-engineer, 1 week)

• Test suite expansion (95%+ coverage)
• Final documentation review
• Duration: 1 week, 40 hours, 20K tokens

Total Timeline: 12 weeks end-to-end

---

📋 Complete Task List (135 Tasks)

Phase	Tasks	Agent(s)	Duration
Phase 1	T0001-T0029 (29 tasks)	database-architect	2 weeks
Phase 2A	T0030-T0043 (14 tasks)	command-developer-1	3 weeks
Phase 2B	T0044-T0055 (12 tasks)	command-developer-2	3 weeks
Phase 2C	T0056-T0067 (12 tasks)	command-developer-3	3 weeks
Phase 3	T0068-T0088 (21 tasks)	integration-engineer	2 weeks
Phase 4A	T0089-T0094 (6 tasks)	template-designer	2 weeks
Phase 4B	T0095-T0101 (7 tasks)	documentation-writer	2 weeks
Phase 5	T0102-T0122 (21 tasks)	backend-engineer	2 weeks
Phase 6	T0123-T0135 (13 tasks)	test-engineer	1 week

Total: 135 tasks across 6 phases

---

🎯 Success Criteria Summary

Functional Requirements:

• ✅ Create Project → Epic → Feature → Task hierarchy
• ✅ Completion % rolls up correctly
• ✅ Sprint burndown works
• ✅ Import from project-plan.md works
• ✅ Export to JSON/CSV/Markdown works
• ✅ Round-trip preserves data

Performance Requirements:

• ✅ Queries <1s for 1000+ work items
• ✅ Recursive rollup efficient
• ✅ Import processes 100+ items in <5s

Quality Requirements:

• ✅ 95%+ test coverage
• ✅ All tests passing
• ✅ No critical bugs
• ✅ Documentation complete

---

📁 Deliverables Inventory

Code Files (23 total)

Modified (5 files):

• scripts/context-db.py (+500 lines)
• commands/cxq.md (+300 lines)
• scripts/test-suite.py (work_items category)
• config/component-counts.json (+6 commands)
• .coditect/component-activation-status.json (+6 commands)

Created (18 files):

Database/Backend:

• scripts/work_items.py (800 lines)
• scripts/migrate-project-plans.py (400 lines)
• scripts/work-items-demo.py (demo data)

Commands:

• commands/project.md
• commands/epic.md
• commands/feature.md
• commands/task.md
• commands/sprint.md
• commands/workitems.md

Tests:

• tests/test_work_items.py (500 lines)
• tests/test_work_item_commands.py (400 lines)

Documentation:

• docs/02-user-guides/WORK-ITEM-HIERARCHY-GUIDE.md
• docs/08-agent-reference/WORK-ITEMS-COMMAND-REFERENCE.md

Templates:

• CODITECT-CORE-STANDARDS/TEMPLATES/PROJECT-PLAN-TEMPLATE-V2.md
• CODITECT-CORE-STANDARDS/TEMPLATES/TASKLIST-TEMPLATE-V2.md
• CODITECT-CORE-STANDARDS/PROJECT-REPORTING-STANDARD.md

HOW-TO Guides:

• CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-EPIC.md
• CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-FEATURE.md
• CODITECT-CORE-STANDARDS/HOW-TO-CREATE-NEW-TASK.md
• CODITECT-CORE-STANDARDS/HOW-TO-PLAN-SPRINT.md

---

⚠️ Risk Mitigation Summary

Risk	Mitigation
Schema migration breaks DB	Backup, test on copy, rollback functionality
Performance degradation	Comprehensive indexes, views, benchmarking
Import parser failures	Extensive testing, graceful errors
Agent coordination issues	Clear handoffs, checkpoints, validation

---

📞 Next Steps

For Implementation Team:

1. Review this quick start + full orchestration plan
2. Verify prerequisites (Python, SQLite, clean git)
3. Execute Phase 1 using database-architect agent
4. Validate Quality Gate 1 before Phase 2
5. Continue through phases with quality gates

For Project Stakeholders:

1. Review this summary for understanding
2. Monitor progress via phase completion reports
3. Approve quality gate decisions
4. Expect v2.0.0 release in ~12 weeks

For Questions:

• Technical: Consult WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md
• Specification: Consult ADR-005-work-item-hierarchy.md
• Standards: Consult CODITECT-STANDARD-WORK-ITEMS.md

---

📚 Related Documents

1. WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md - Comprehensive 12-week plan (THIS IS THE MAIN PLAN)
2. WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.json - JSON format for automation
3. ADR-005-work-item-hierarchy.md - Complete specification
4. CODITECT-STANDARD-WORK-ITEMS.md - Naming convention standard

---

Document Version: 1.0.0 Last Updated: 2025-12-13 Status: READY FOR EXECUTION Estimated Completion: March 2026

---

🚀 Ready to begin? Start with Phase 1 using the database-architect agent invocation above.