Skip to main content

CODITECT Standard: Work Item Hierarchy and Naming Convention

Standard: CODITECT-STANDARD-WORK-ITEMS
Version: 1.0.0
Status: APPROVED
Category: Project Management
Created: 2025-12-13
Last Updated: 2025-12-13
Author: CODITECT Architecture Team
Related ADR: ADR-006-WORK-ITEM-HIERARCHY

1. Purpose​

This standard defines the naming convention, hierarchy rules, and lifecycle management for work items in CODITECT projects. It establishes a token-efficient, human-readable system optimized for LLM context windows while maintaining enterprise-grade project tracking capabilities.

2. Work Item Types​

2.1 Type Hierarchy​

Project (P)
└── Sub-Project (SP)
    └── Epic (E)
        └── Feature (F)
            └── Task (T)
                └── Subtask (ST)

Sprint (S) ─── [Time-boxed container, orthogonal to hierarchy]

2.2 Type Definitions​

TypeCodePurposeTypical DurationContains
ProjectPTop-level initiative or productMonths-YearsSub-Projects, Epics
Sub-ProjectSPMajor component or moduleMonthsEpics
EpicELarge body of work with business valueWeeks-MonthsFeatures, Tasks
FeatureFUser-facing capability or functionDays-WeeksTasks
TaskTImplementable unit of workHours-DaysSubtasks
SubtaskSTTechnical breakdown of a taskHoursNone
SprintSTime-boxed iteration1-4 WeeksTasks (assigned)

3. ID Convention​

3.1 Primary ID Format​

{TYPE_CODE}{ZERO_PADDED_NUMBER}
TypePatternDigitsRangeExamples
ProjectP{NNN}3001-999P001, P042
Sub-ProjectSP{NNN}3001-999SP001, SP057
EpicE{NNN}3001-999E001, E123
FeatureF{NNN}3001-999F001, F042
TaskT{NNNN}40001-9999T0001, T1234
SubtaskST{NNNN}40001-9999ST0001, ST0042
SprintS{NN}201-99S01, S23

3.2 ID Characteristics​

Token Efficiency:

  • Maximum ID length: 6 characters (ST0001)
  • Minimum ID length: 3 characters (S01)
  • Average ID length: 5 characters
  • 84% more efficient than verbose alternatives

Collision Avoidance:

  • IDs are globally unique within a CODITECT installation
  • Type prefix prevents collision between types
  • Sequential numbering within type

Readability:

  • Type immediately identifiable by prefix
  • Zero-padding ensures consistent sorting
  • Fixed-length per type enables clean table formatting

3.3 Human-Readable Aliases (Optional)​

Work items MAY have an optional alias for human reference:

ID:     E001
Alias:  TOKEN-ACCT
Title:  Token Accounting System

Query:  /epic E001          (by ID)
        /epic TOKEN-ACCT    (by alias)
        /epic "token"       (by title search)

Alias Rules:

  • Maximum 20 characters
  • UPPER-KEBAB-CASE format
  • Alphanumeric and hyphens only
  • Must be unique within type
  • Optional (not required)

Examples:

IDAliasTitle
E001TOKEN-ACCTToken Accounting System
E002WORK-ITEMSWork Item Hierarchy
F001USAGE-EXTRACTUsage Extraction
S23SPRINT-2025-W50Sprint 23 (Week 50)

4. Display Formats​

4.1 Standard Display Format​

{ID}: {Title}

Examples:

E001: Token Accounting System
F001: Usage Extraction
T0001: Extract token fields from JSONL sessions
S23: Sprint 23 (Dec 16-27)

4.2 Compact Display Format (Tables)​

{ID} | {Title (truncated)} | {Status} | {Sprint}

Example Table:

┌────────┬─────────────────────────────────┬──────────┬────────┐
│ ID     │ Title                           │ Status   │ Sprint │
├────────┼─────────────────────────────────┼──────────┼────────┤
│ T0001  │ Extract token fields from JSONL │ Done     │ S23    │
│ T0002  │ Add to unified message format   │ Done     │ S23    │
│ T0003  │ Handle missing usage data       │ WIP      │ S24    │
└────────┴─────────────────────────────────┴──────────┴────────┘

4.3 Hierarchical Display Format​

E001: Token Accounting System (56%)
├── F001: Usage Extraction (100%) ✓
│   ├── T0001: Extract token fields ✓
│   ├── T0002: Add to JSONL format ✓
│   └── T0003: Handle missing data ✓
├── F002: Query Interface (67%)
│   ├── T0004: Add --tokens flag ✓
│   ├── T0005: Add --cost flag ✓
│   └── T0006: Add date filtering □
└── F003: Cache Analytics (0%)
    ├── T0007: Calculate hit rate □
    └── T0008: Estimate savings □

4.4 Progress Bar Format​

E001: Token Accounting System
Progress: ████████████░░░░░░░░ 56% (5/9 tasks)
Points:   █████████████░░░░░░░ 62% (13/21 pts)

5. Status Definitions​

5.1 Work Item Status​

StatusCodeDescriptionTransitions To
backlogBNot yet planned for workplanned
plannedPScheduled for a sprintin_progress, backlog
in_progressIActively being workedreview, blocked, completed
blockedXCannot proceed (dependency/issue)in_progress
reviewRIn review/testingcompleted, in_progress
completedCDone and verified(terminal)
cancelled-Will not be done(terminal)

5.2 Status Icons​

StatusIconCheckboxColor
backlog○[ ]Gray
planned◐[P]Blue
in_progress◑[>]Yellow
blocked⊘[!]Red
review◕[R]Purple
completed●[x]Green
cancelled⊖[-]Gray strikethrough

5.3 Sprint Status​

StatusDescription
plannedFuture sprint, not started
activeCurrent sprint in progress
completedSprint finished
cancelledSprint cancelled

6. Priority Scale​

6.1 Numeric Priority (0-100)​

RangeLabelDescriptionResponse Time
90-100P0-CRITICALSystem down, blocking all workImmediate
70-89P1-HIGHMajor functionality impairedWithin sprint
40-69P2-MEDIUMImportant but not urgentNext 2-3 sprints
20-39P3-LOWNice to haveWhen capacity allows
0-19P4-BACKLOGFuture considerationNo commitment

6.2 Default Priority​

  • New items default to priority 50 (P2-MEDIUM)
  • Epics/Features inherit highest child priority
  • Blocked items auto-escalate +10 after 3 days

7. Estimation​

7.1 Story Points (Fibonacci)​

PointsEffortComplexityRiskExample
1HoursTrivialNoneFix typo, update config
2Half daySimpleLowAdd simple flag, small refactor
31 dayModerateLowNew function, simple feature
52-3 daysComplexMediumNew component, integration
81 weekVery complexMediumMajor feature, new system
132 weeksHighly complexHighArchitecture change
211 monthExtremely complexHighMajor initiative (split recommended)

7.2 Time Estimates​

  • Optional supplement to story points
  • Format: decimal hours (e.g., 2.5 = 2h 30m)
  • Used for: capacity planning, actual vs estimate tracking

8. Completion Rollup​

8.1 Rollup Rules​

Task Completion:

  • A task is 100% complete when status = completed
  • A task is 0% complete otherwise (no partial completion)

Feature Completion (by count):

percent = (completed_tasks / total_tasks) × 100

Feature Completion (by points):

percent = (completed_points / total_points) × 100

Epic Completion:

percent = average of child feature percentages
        OR sum of all descendant task completion

Project Completion:

percent = average of child epic percentages

8.2 Rollup Display​

E001: Token Accounting System
├── By Tasks: 56% (5/9 completed)
├── By Points: 62% (13/21 points)
└── By Features: 56% (1.67/3 features)

9. Relationships​

9.1 Parent-Child Hierarchy​

Parent TypeValid Children
ProjectSub-Project, Epic
Sub-ProjectEpic
EpicFeature, Task
FeatureTask
TaskSubtask
SubtaskNone

9.2 Sprint Assignment​

  • Only Tasks and Subtasks can be assigned to Sprints
  • Epics and Features span multiple sprints (not assigned directly)
  • A task can only be in one sprint at a time

9.3 Dependencies​

Dependency Types:

TypeMeaningExample
blocksMust complete beforeT0001 blocks T0002
blocked_byCannot start untilT0002 blocked_by T0001
relates_toRelated but independentT0001 relates_to T0005

Dependency Format:

T0002:
  blocked_by: [T0001]
  blocks: [T0003, T0004]
  relates_to: [E002]

10. Labels and Tags​

10.1 Standard Labels​

CategoryLabels
Typebug, feature, enhancement, refactor, docs, test
Componentbackend, frontend, api, database, infra, ci-cd
Effortquick-win, spike, tech-debt, research
Riskhigh-risk, needs-review, breaking-change

10.2 Label Format​

  • LOWER-KEBAB-CASE
  • Maximum 20 characters
  • Stored as JSON array: ["bug", "backend", "high-risk"]

11. Database Schema Reference​

See ADR-006: Work Item Hierarchy for complete schema.

Core Tables:

  • projects - Top-level containers
  • sub_projects - Module/component groupings
  • work_items - Unified table for E/F/T/ST
  • sprints - Time-boxed iterations
  • work_item_history - Audit log
  • work_item_comments - Discussion threads

12. Command Reference​

12.1 Creation Commands​

/project create "CODITECT Platform" --id P001
/subproject create "coditect-core" --project P001 --path submodules/core
/epic create "Token Accounting" --id E001 --project P001
/feature create "Usage Extraction" --id F001 --epic E001
/task create "Extract token fields" --id T0001 --feature F001 --points 3
/sprint create "Sprint 23" --id S23 --start 2025-12-16 --end 2025-12-27

12.2 Status Commands​

/task start T0001                    # → in_progress
/task complete T0001                 # → completed
/task block T0001 --reason "text"    # → blocked
/task unblock T0001                  # → in_progress

12.3 Query Commands​

/cxq --epic-progress E001            # Epic completion
/cxq --sprint-status S23             # Sprint burndown
/cxq --project-status P001           # Project overview
/cxq --blocked                       # All blocked items
/cxq --my-tasks                      # Current user's tasks

12.4 Assignment Commands​

/task assign T0001 --sprint S23
/task assign T0001 --assignee hal
/task move T0001 --sprint S24        # Reassign sprint

13. Markdown Integration​

13.1 Inline Task Format​

- [ ] T0001: Extract token fields @hal #S23 (3pt)
- [x] T0002: Add to JSONL format @hal #S23 (2pt) ✓
- [>] T0003: Handle missing data @hal #S24 (2pt) WIP
- [!] T0004: Blocked task @hal #S24 (3pt) BLOCKED

13.2 Epic Section Format​

## Epic: E001 - Token Accounting System
**Status:** In Progress | **Progress:** 56% | **Points:** 13/21

### Feature: F001 - Usage Extraction (100%)
| ID | Task | Status | Sprint | Pts | Assignee |
|----|------|--------|--------|-----|----------|
| T0001 | Extract token fields | Done | S23 | 3 | @hal |
| T0002 | Add to JSONL format | Done | S23 | 2 | @hal |

13.3 Sprint Section Format​

## Sprint: S23 (2025-12-16 → 2025-12-27)
**Goal:** Complete Token Accounting MVP
**Velocity:** 13 points | **Progress:** 77% (10/13 pts)

### Committed Items
| ID | Title | Epic | Status | Pts |
|----|-------|------|--------|-----|
| T0001 | Extract token fields | E001 | Done | 3 |
| T0002 | Add to JSONL format | E001 | Done | 2 |
| T0003 | Handle missing data | E001 | WIP | 2 |

14. Validation Rules​

14.1 ID Validation​

Project:     ^P[0-9]{3}$
Sub-Project: ^SP[0-9]{3}$
Epic:        ^E[0-9]{3}$
Feature:     ^F[0-9]{3}$
Task:        ^T[0-9]{4}$
Subtask:     ^ST[0-9]{4}$
Sprint:      ^S[0-9]{2}$

14.2 Alias Validation​

^[A-Z][A-Z0-9-]{0,18}[A-Z0-9]$|^[A-Z]$

14.3 Required Fields​

TypeRequired Fields
Allid, type, title, status, created_at
Epic+project_id
Featureparent_id (Epic)
Taskparent_id (Feature or Epic)
Sprintproject_id, start_date, end_date

15. Migration Guide​

15.1 From Flat Task Lists​

Before:

- [x] Create GitHub repository
- [x] Configure permissions
- [ ] Implement feature

After:

### Feature: F001 - Repository Setup (100%)
| ID | Task | Status | Sprint |
|----|------|--------|--------|
| T0001 | Create GitHub repository | Done | S01 |
| T0002 | Configure permissions | Done | S01 |

### Feature: F002 - Core Development (0%)
| ID | Task | Status | Sprint |
|----|------|--------|--------|
| T0003 | Implement feature | Backlog | - |

15.2 Migration Command​

/workitems import PROJECT-PLAN.md --format legacy
/workitems export PROJECT-PLAN-V2.md --format hierarchical

16. Examples​

16.1 Complete Project Structure​

P001: CODITECT Platform
├── SP001: coditect-core
│   ├── E001: Token Accounting System (56%)
│   │   ├── F001: Usage Extraction (100%) ✓
│   │   │   ├── T0001: Extract token fields ✓
│   │   │   ├── T0002: Add to JSONL format ✓
│   │   │   └── T0003: Handle missing data ✓
│   │   ├── F002: Query Interface (67%)
│   │   │   ├── T0004: Add --tokens flag ✓
│   │   │   ├── T0005: Add --cost flag ✓
│   │   │   └── T0006: Add date filtering □
│   │   └── F003: Cache Analytics (0%)
│   │       ├── T0007: Calculate hit rate □
│   │       └── T0008: Estimate savings □
│   └── E002: Work Item Hierarchy (0%)
│       └── ...
├── SP002: coditect-cloud-backend
│   └── E003: User Authentication
│       └── ...
└── SP003: coditect-frontend
    └── ...

16.2 Sprint Board View​

Sprint S23: Token Accounting MVP
══════════════════════════════════════════════════════════════════

BACKLOG          PLANNED          IN PROGRESS      DONE
─────────────────────────────────────────────────────────────────
                                  T0006 (3pt)      T0001 (3pt) ✓
                                  Date filtering   Extract fields
                                  @hal
                                                   T0002 (2pt) ✓
                                                   JSONL format

                                                   T0003 (2pt) ✓
                                                   Missing data

                                                   T0004 (2pt) ✓
                                                   --tokens flag

                                                   T0005 (2pt) ✓
                                                   --cost flag
─────────────────────────────────────────────────────────────────
Total: 0 pts     0 pts            3 pts            11 pts
Progress: ████████████████░░░░ 79%

17. Compliance Checklist​

17.1 Creating Work Items​

  • ID follows {TYPE}{NUMBER} pattern
  • ID is unique within type
  • Title is descriptive (5-80 characters)
  • Parent relationship is valid
  • Status is from allowed values
  • Priority is 0-100
  • Story points use Fibonacci (if estimated)

17.2 Project Structure​

  • Project has at least one Epic or Sub-Project
  • Epics have clear business value
  • Features represent user-facing capabilities
  • Tasks are implementable in <1 week
  • Subtasks are used for technical breakdown only

17.3 Sprint Management​

  • Sprint has clear goal
  • Sprint duration is 1-4 weeks
  • Only tasks/subtasks are assigned to sprint
  • Committed points match team velocity
  • Sprint has defined start and end dates

Standard Version: 1.0.0 Effective Date: 2025-12-13 Review Date: 2026-03-13 (Quarterly) Owner: CODITECT Architecture Team Copyright: 2025 AZ1.AI INC. All rights reserved.