Skip to main content

Work Item Management Skill

Work Item Management Skill

How to Use This Skill​

  1. Review the patterns and examples below
  2. Apply the relevant patterns to your implementation
  3. Follow the best practices outlined in this skill

Comprehensive work item hierarchy management for CODITECT projects following ADR-006.

Skill Overview​

Name: work-item-management Version: 1.0.0 Category: Project Management Dependencies: scripts/work_items.py, scripts/context-db.py

Capabilities​

This skill enables:

  • Project hierarchy creation and management (P → SP → E → F → T → ST)
  • Sprint planning and velocity tracking
  • Automatic progress rollup calculations
  • Session-to-work-item linking
  • Work item search and querying
  • Export to multiple formats (Markdown, JSON, CSV)

When to Use​

Invoke this skill when:

  • Creating or managing project structures
  • Breaking down work into epics, features, and tasks
  • Planning sprints with story point estimation
  • Tracking progress on work items
  • Generating project reports or exports
  • Linking development sessions to tasks

ID Convention​

TypePatternExample
ProjectP{NNN}P001
Sub-ProjectSP{NNN}SP001
EpicE{NNN}E001
FeatureF{NNN}F001
TaskT{NNNN}T0001
SubtaskST{NNNN}ST0001
SprintS{NN}S01

Status Workflow​

backlog → planned → in_progress → review → completed
                  ↓
               blocked → in_progress

Core Patterns​

Pattern 1: Project Setup​

# Create project with hierarchy
python3 scripts/work_items.py project create "Project Name" --description "Description"
python3 scripts/work_items.py sub-project create P001 "Backend"
python3 scripts/work_items.py epic create P001 "Epic Title" --priority 90

Pattern 2: Sprint Planning​

# Create and populate sprint
python3 scripts/work_items.py sprint create P001 "Sprint 1" --start 2025-12-16 --end 2025-12-30
python3 scripts/work_items.py sprint add S01 F001 F002 F003
python3 scripts/work_items.py sprint start S01

Pattern 3: Task Workflow​

# Complete task workflow
python3 scripts/work_items.py task start T0001
python3 scripts/work_items.py task link-session T0001 "$SESSION_ID"
python3 scripts/work_items.py task log T0001 --hours 2.5
python3 scripts/work_items.py task complete T0001 --actual-hours 3.0

Pattern 4: Progress Tracking​

# Check progress at any level
python3 scripts/work_items.py progress P001  # Project level
python3 scripts/work_items.py progress E001  # Epic level
python3 scripts/work_items.py progress F001  # Feature level

Pattern 5: Export and Reporting​

# Export hierarchy
python3 scripts/work_items.py export P001 --format markdown
python3 scripts/work_items.py sprint burndown S01
python3 scripts/work_items.py dashboard

Python API Usage​

from work_items import WorkItemManager

manager = WorkItemManager()

# Create hierarchy
project = manager.create_project("Name", "Description")
epic = manager.create_epic(project, "Epic Title", priority=90)
feature = manager.create_feature(epic, "Feature", estimate_points=8)
task = manager.create_task(feature, "Task", estimate_hours=4.0)

# Track progress
manager.update_status(task, 'in_progress')
manager.link_session(session_id, task)
manager.update_status(task, 'completed')
manager.update_actual_hours(task, 3.5)

# Query
progress = manager.get_progress(epic)
hierarchy = manager.get_hierarchy(project)
burndown = manager.get_sprint_burndown(sprint_id)

Integration Points​

With /cxq (Context Query)​

# Query work items from context database
/cxq --epics --project P001
/cxq --tasks --status in_progress --mine
/cxq --sprint-report S01

With Session Management​

# Link current session
/task link-session T0001

# Query sessions for task
/cxq --sessions-for T0001

With Checkpoint System​

# Include work item status in checkpoint
/checkpoint --include-work-items

Best Practices​

  1. Start with Epics: Break down large initiatives into epics first
  2. Estimate Features: Use Fibonacci points (1, 2, 3, 5, 8, 13, 21)
  3. Track Hours on Tasks: Estimate and log actual hours for velocity
  4. Link Sessions: Always link Claude Code sessions to tasks
  5. Regular Progress Checks: Use dashboard daily
  6. Sprint Retrospectives: Run /sprint retro after each sprint

Error Handling​

ErrorCauseSolution
"Parent not found"Invalid parent_idCheck ID format and existence
"Invalid status transition"Blocked → completedMove to in_progress first
"Sprint capacity exceeded"Too many pointsRemove items or extend sprint
"Circular dependency"Task is own parentCheck parent_id assignment

Success Output​

When this skill completes successfully, output:

✅ SKILL COMPLETE: work-item-management

Completed:
- [x] Project hierarchy created (P → SP → E → F → T → ST)
- [x] Sprint planned with estimated velocity
- [x] Task workflow executed (start → link → log → complete)
- [x] Progress rolled up across all hierarchy levels
- [x] Work items exported in requested format

Work Item Summary:
- Projects: [count] | Sub-Projects: [count] | Epics: [count]
- Features: [count] | Tasks: [count] | Subtasks: [count]
- Sprints: [count] active
- Velocity: [points/sprint]
- Progress: [percentage]% complete

Outputs:
- context-storage/context.db (work_items table)
- Exported to: [markdown|json|csv]

Completion Checklist​

Before marking this skill as complete, verify:

  • Work item hierarchy created with valid parent relationships
  • All IDs follow convention (P{NNN}, E{NNN}, F{NNN}, T{NNNN}, etc.)
  • Status transitions valid (backlog → planned → in_progress → completed)
  • Sprint capacity not exceeded (total points within velocity)
  • Sessions linked to tasks for traceability
  • Actual hours logged for completed tasks
  • Progress rolled up correctly from children to parents
  • Export generated in requested format
  • Database integrity verified (no orphaned items)

Failure Indicators​

This skill has FAILED if:

  • ❌ Work item created with invalid parent_id (orphaned item)
  • ❌ Invalid status transition attempted (blocked → completed)
  • ❌ Sprint capacity exceeded without warning
  • ❌ Circular dependency detected (task is own parent)
  • ❌ Progress calculation incorrect (doesn't match children)
  • ❌ Session not linked to task (lost traceability)
  • ❌ Export failed or generated empty/corrupt file
  • ❌ Database constraints violated (duplicate IDs, invalid foreign keys)

When NOT to Use​

Do NOT use this skill when:

  • Simple todo list sufficient (use TodoWrite instead)
  • No sprint planning needed (use simple task list)
  • Single-person project with <10 tasks (over-engineering)
  • No velocity tracking required (simple checklist works)
  • Project lifecycle <1 week (setup overhead not worth it)
  • No hierarchy needed (flat task list sufficient)
  • Working outside CODITECT framework

Use instead:

  • TodoWrite for simple task tracking
  • Markdown checklists for small projects
  • GitHub Issues for code-centric projects
  • Jira/Linear for enterprise project management
  • Simple spreadsheet for basic tracking

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Flat structureNo epics/features, just tasksUse proper hierarchy (E → F → T)
Over-nesting5+ levels deep, too complexMax 3 levels (E → F → T or SP → E → F)
No estimationCan't track velocity or plan sprintsEstimate features (points) and tasks (hours)
Orphaned itemsItems with invalid parent_idValidate parent exists before creating
Wrong status flowSkip statuses, invalid transitionsFollow workflow: backlog → planned → in_progress → completed
Sprint overloadToo many points, team can't completeTrack velocity, use historical data
No session linkingCan't trace work to tasksAlways link sessions with /task link-session
Duplicate IDsID conflicts cause database errorsUse auto-increment or validate uniqueness

Principles​

This skill embodies CODITECT principles:

  • #1 Recycle → Extend → Re-Use → Create - Reuses ADR-006 hierarchy pattern
  • #2 First Principles - Understands WHY hierarchy matters (organization, rollup)
  • #3 Keep It Simple - Simple 6-level hierarchy, clear ID convention
  • #4 Separation of Concerns - Work items separate from code, sessions, context
  • #5 Eliminate Ambiguity - Explicit IDs, clear status workflow, defined relationships
  • #6 Clear, Understandable, Explainable - Self-documenting IDs (P001, E001)
  • #8 No Assumptions - Validates parent exists, checks status transitions
  • #9 Measurable & Traceable - Velocity tracking, session linking, progress rollup

Full Standard: CODITECT-STANDARD-AUTOMATION.md

  • Commands: /project, /epic, /feature, /task, /sprint, /work-item
  • Agent: work-item-manager
  • Workflows: sprint-planning-cycle, project-kickoff
  • Scripts: work_items.py, context-db.py
  • Standard: CODITECT-STANDARD-WORK-ITEMS.md
  • ADR: ADR-005-work-item-hierarchy.md

Version: 1.0.0 Last Updated: 2026-01-04 Author: CODITECT Team