1-2-3 How to Create V2 Project Plans

Version: 1.0.0 Created: 2025-12-14 Architecture: ADR-006 Work Item Hierarchy Status: Production Ready

Overview

This guide provides the optimal methodology for creating comprehensive V2 project plans using the ADR-006 Work Item Hierarchy standard. Follow these steps in order for maximum efficiency and consistency.

Prerequisites

Before starting, ensure you have:

Read ADR-005-work-item-hierarchy.md
Read CODITECT-STANDARD-WORK-ITEMS.md
SQLite database initialized (context-storage/context.db)
V2 directory structure exists (docs/05-project-planning/v2/)

The 1-2-3 Methodology

Phase 1: Foundation (Do Once)

Step 1.1: Initialize Database Schema

# Create work item tables in context.db
python3 scripts/init-work-item-db.py

# Verify tables created
sqlite3 context-storage/context.db ".tables" | grep -E "projects|work_items|sprints"

Step 1.2: Create Project Record

-- Insert master project
INSERT INTO projects (id, name, description, status, owner)
VALUES ('P001', 'CODITECT Platform', 'Complete Autonomous Development System', 'active', 'Hal Casteel');

Step 1.3: Create Sub-Projects (for each submodule)

-- Example: coditect-core
INSERT INTO sub_projects (id, project_id, name, path, status)
VALUES ('SP001', 'P001', 'coditect-core', 'submodules/core/coditect-core', 'active');

Phase 2: Epic Creation (Per Epic)

For each epic (E001-E010), follow this workflow:

Step 2.1: Create Epic Overview File

Location: v2/epics/E00N-NAME/EPIC-OVERVIEW.md

Template:

# E00N: Epic Name

**Epic ID:** E00N
**Status:** Planned | Active | Complete
**Sprint Range:** XX-YY
**Total Tasks:** NNN
**Story Points:** NNN

---

## Goal

[One sentence describing what this epic achieves]

## Business Value

[Why this epic matters - user impact, revenue, risk reduction]

## Success Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

---

## Features

### F00N.1: Feature Name
**Tasks:** XX | **Points:** YY | **Sprints:** AA-BB

[Feature description]

**Deliverables:**
- Deliverable 1
- Deliverable 2

### F00N.2: Feature Name
...

---

## Dependencies

- **Depends On:** [List epics/features this depends on]
- **Blocks:** [List epics/features this blocks]

## Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| ... | ... | ... | ... |

---

## Timeline

| Sprint | Focus | Deliverables |
|--------|-------|--------------|
| XX | ... | ... |

Step 2.2: Create Epic Tasklist File

Location: v2/epics/E00N-NAME/TASKLIST.md

Template:

# E00N: Epic Name - Task List

**Total Tasks:** NNN
**Completed:** 0 (0%)
**Last Updated:** YYYY-MM-DD

---

## F00N.1: Feature Name

### Phase 1: [Phase Name]

- [ ] T001: Task description (~Xh)
- [ ] T002: Task description (~Xh)
- [ ] T003: Task description (~Xh)

### Phase 2: [Phase Name]

- [ ] T004: Task description (~Xh)
...

---

## F00N.2: Feature Name

### Phase 1: [Phase Name]

- [ ] T0XX: Task description (~Xh)
...

---

## Summary

| Feature | Tasks | Completed | % |
|---------|-------|-----------|---|
| F00N.1 | XX | 0 | 0% |
| F00N.2 | XX | 0 | 0% |
| **Total** | **NNN** | **0** | **0%** |

Step 2.3: Insert Epic into Database

-- Insert epic
INSERT INTO work_items (id, type, title, description, project_id, sub_project_id, status, priority)
VALUES ('E00N', 'epic', 'Epic Name', 'Epic description', 'P001', 'SP001', 'planned', 80);

-- Insert features
INSERT INTO work_items (id, type, title, parent_id, project_id, status)
VALUES ('F00N.1', 'feature', 'Feature Name', 'E00N', 'P001', 'planned');

-- Insert tasks (batch)
INSERT INTO work_items (id, type, title, parent_id, sprint_id, status, estimate_hours)
VALUES
    ('T001', 'task', 'Task description', 'F00N.1', 'Sprint-25', 'planned', 4),
    ('T002', 'task', 'Task description', 'F00N.1', 'Sprint-25', 'planned', 2),
    ...;

Phase 3: Sprint Planning (Per Sprint)

Step 3.1: Create Sprint Plan File

Location: v2/sprints/Sprint-NN/SPRINT-PLAN.md

Template:

# Sprint NN Plan

**Sprint ID:** Sprint-NN
**Dates:** YYYY-MM-DD to YYYY-MM-DD (2 weeks)
**Goal:** [One sentence sprint goal]
**Status:** Planned | Active | Complete

---

## Sprint Metrics

| Metric | Planned | Actual |
|--------|---------|--------|
| Tasks | XXX | - |
| Story Points | XXX | - |
| Capacity (hours) | XXX | - |

---

## Epics in Sprint

### E00N: Epic Name (XX tasks)

**Sprint Goal:** [What we aim to complete from this epic]

#### F00N.1: Feature Name

- [ ] T001: Task description (~Xh)
- [ ] T002: Task description (~Xh)

#### F00N.2: Feature Name

- [ ] T003: Task description (~Xh)

---

## Dependencies & Risks

**Blockers:**
- None identified

**Risks:**
- [Risk 1]: [Mitigation]

---

## Definition of Done

- [ ] All tasks completed and checked off
- [ ] Code reviewed and merged
- [ ] Tests passing (80%+ coverage)
- [ ] Documentation updated
- [ ] Sprint retrospective completed

---

## Daily Standup Template

**Date:** YYYY-MM-DD

**Progress:**
- Completed: [tasks]
- In Progress: [tasks]

**Blockers:**
- [None / List blockers]

**Plan Today:**
- [tasks to work on]

Step 3.2: Insert Sprint into Database

INSERT INTO sprints (id, project_id, name, goal, start_date, end_date, status, velocity_planned)
VALUES ('Sprint-NN', 'P001', 'Sprint NN', 'Sprint goal statement', 'YYYY-MM-DD', 'YYYY-MM-DD', 'planned', 100);

Step 3.3: Assign Tasks to Sprint

UPDATE work_items SET sprint_id = 'Sprint-NN' WHERE id IN ('T001', 'T002', 'T003', ...);

Optimal Execution Order

For a new project with 10 epics and 32 sprints:

Day 1: Foundation

Initialize database schema
Create project and sub-project records
Create V2 directory structure

Day 2-3: Epic Population

Create E001 epic (detailed - already done)
Create E002-E010 epic overviews (high-level)
Create E002-E010 tasklists (detailed breakdowns)

Day 4: Sprint Planning

Create Sprint 25-34 plans (10 sprints = 20 weeks)
Assign tasks to sprints
Calculate velocity targets

Day 5: Validation

Run completion rollup queries
Verify all relationships
Export to JSON for dashboards

Automation Scripts

Batch Epic Creation

#!/usr/bin/env python3
"""Create epic structure from JSON definition."""

import json
import os

EPICS = [
    {"id": "E001", "name": "AUTONOMY", "title": "Core Platform Autonomy"},
    {"id": "E002", "name": "TOON-INTEGRATION", "title": "Toon UI Integration"},
    {"id": "E003", "name": "MEMORY-INTELLIGENCE", "title": "Memory Intelligence"},
    {"id": "E004", "name": "WORKFLOW-AUTOMATION", "title": "Workflow Automation"},
    {"id": "E005", "name": "QUALITY-ASSURANCE", "title": "Quality Assurance"},
    {"id": "E006", "name": "DEPLOYMENT-INFRASTRUCTURE", "title": "Deployment Infrastructure"},
    {"id": "E007", "name": "DOCUMENTATION-SYSTEM", "title": "Documentation System"},
    {"id": "E008", "name": "SECURITY-COMPLIANCE", "title": "Security & Compliance"},
    {"id": "E009", "name": "ANALYTICS-OBSERVABILITY", "title": "Analytics & Observability"},
    {"id": "E010", "name": "ROLLOUT-GTM", "title": "Rollout & GTM"},
]

BASE_PATH = "docs/05-project-planning/v2/epics"

for epic in EPICS:
    epic_dir = f"{BASE_PATH}/{epic['id']}-{epic['name']}"
    os.makedirs(epic_dir, exist_ok=True)

    # Create EPIC-OVERVIEW.md
    overview_path = f"{epic_dir}/EPIC-OVERVIEW.md"
    if not os.path.exists(overview_path):
        with open(overview_path, 'w') as f:
            f.write(f"# {epic['id']}: {epic['title']}\n\n")
            f.write("**Status:** Planned\n\n")
            f.write("## Goal\n\n[TODO: Define epic goal]\n\n")
            f.write("## Features\n\n[TODO: Break down into features]\n")

    # Create TASKLIST.md
    tasklist_path = f"{epic_dir}/TASKLIST.md"
    if not os.path.exists(tasklist_path):
        with open(tasklist_path, 'w') as f:
            f.write(f"# {epic['id']}: {epic['title']} - Task List\n\n")
            f.write("**Total Tasks:** 0\n")
            f.write("**Completed:** 0 (0%)\n\n")
            f.write("## Tasks\n\n[TODO: Add tasks]\n")

print(f"Created {len(EPICS)} epic directories")

Batch Sprint Creation

#!/usr/bin/env python3
"""Create sprint plan files."""

from datetime import datetime, timedelta
import os

START_SPRINT = 25
END_SPRINT = 56
START_DATE = datetime(2025, 12, 16)
SPRINT_DURATION = 14  # days

BASE_PATH = "docs/05-project-planning/v2/sprints"

for sprint_num in range(START_SPRINT, END_SPRINT + 1):
    sprint_start = START_DATE + timedelta(days=(sprint_num - START_SPRINT) * SPRINT_DURATION)
    sprint_end = sprint_start + timedelta(days=SPRINT_DURATION - 1)

    sprint_dir = f"{BASE_PATH}/Sprint-{sprint_num}"
    os.makedirs(sprint_dir, exist_ok=True)

    plan_path = f"{sprint_dir}/SPRINT-PLAN.md"
    if not os.path.exists(plan_path):
        with open(plan_path, 'w') as f:
            f.write(f"# Sprint {sprint_num} Plan\n\n")
            f.write(f"**Dates:** {sprint_start.strftime('%Y-%m-%d')} to {sprint_end.strftime('%Y-%m-%d')}\n")
            f.write("**Goal:** [TODO: Define sprint goal]\n")
            f.write("**Status:** Planned\n\n")
            f.write("## Tasks\n\n[TODO: Assign tasks]\n")

print(f"Created {END_SPRINT - START_SPRINT + 1} sprint directories")

Database Import from Markdown

#!/usr/bin/env python3
"""Import existing TASKLIST.md into SQLite database."""

import re
import sqlite3
from pathlib import Path

DB_PATH = "context-storage/context.db"
EPIC_PATH = "docs/05-project-planning/v2/epics"

def extract_tasks(tasklist_path: str) -> list:
    """Extract tasks from markdown tasklist."""
    tasks = []
    with open(tasklist_path, 'r') as f:
        content = f.read()

    # Match: - [ ] T001: Task description (~4h)
    pattern = r'- \[([ x])\] (T\d+): (.+?)(?:\s*\(~?(\d+)h?\))?$'

    for match in re.finditer(pattern, content, re.MULTILINE):
        completed = match.group(1) == 'x'
        task_id = match.group(2)
        title = match.group(3).strip()
        hours = int(match.group(4)) if match.group(4) else 4

        tasks.append({
            'id': task_id,
            'title': title,
            'status': 'completed' if completed else 'planned',
            'estimate_hours': hours
        })

    return tasks

def import_epic_tasks(epic_id: str, epic_dir: str):
    """Import all tasks from an epic's TASKLIST.md."""
    tasklist_path = f"{epic_dir}/TASKLIST.md"
    if not Path(tasklist_path).exists():
        print(f"No tasklist found for {epic_id}")
        return

    tasks = extract_tasks(tasklist_path)
    print(f"Found {len(tasks)} tasks in {epic_id}")

    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()

    for task in tasks:
        cursor.execute('''
            INSERT OR REPLACE INTO work_items
            (id, type, title, parent_id, status, estimate_hours)
            VALUES (?, 'task', ?, ?, ?, ?)
        ''', (task['id'], task['title'], epic_id, task['status'], task['estimate_hours']))

    conn.commit()
    conn.close()
    print(f"Imported {len(tasks)} tasks for {epic_id}")

# Run import
for epic_dir in Path(EPIC_PATH).iterdir():
    if epic_dir.is_dir():
        epic_id = epic_dir.name.split('-')[0]
        import_epic_tasks(epic_id, str(epic_dir))

Query Commands

After populating the database, use these queries:

Epic Progress

/cxq epic:E001 --progress
# Returns: E001: Core Platform Autonomy - 45% complete (491/1093 tasks)

Sprint Burndown

/cxq sprint:25 --burndown
# Returns: Sprint 25: 320/547 tasks complete, 227 remaining, 3 days left

Project Dashboard

/cxq project:P001 --dashboard
# Returns: Summary of all epics with completion percentages

Validation Checklist

After creating V2 project plans, verify:

All epic directories exist (v2/epics/E001-E010)
Each epic has EPIC-OVERVIEW.md and TASKLIST.md
All sprint directories exist (v2/sprints/Sprint-25 through Sprint-56)
Each sprint has SPRINT-PLAN.md
Database tables populated (projects, sub_projects, work_items, sprints)
Completion rollup working (query returns percentages)
Tasks assigned to correct sprints
Parent-child relationships valid

Common Issues

Issue: Tasks not rolling up to epic

Solution: Ensure parent_id is set correctly on all tasks/features

Issue: Sprint dates overlapping

Solution: Sprints are 14-day periods, ensure no gaps or overlaps

Issue: Duplicate task IDs

Solution: Use unique IDs per epic (E001-T001, E002-T001, etc.)

Last Updated: 2025-12-14 Author: CODITECT Framework Team

Overview​

Prerequisites​

The 1-2-3 Methodology​

Phase 1: Foundation (Do Once)​

Phase 2: Epic Creation (Per Epic)​

Step 2.1: Create Epic Overview File​

Step 2.2: Create Epic Tasklist File​

Step 2.3: Insert Epic into Database​

Phase 3: Sprint Planning (Per Sprint)​

Step 3.1: Create Sprint Plan File​

Step 3.2: Insert Sprint into Database​

Step 3.3: Assign Tasks to Sprint​

Optimal Execution Order​

Day 1: Foundation​

Day 2-3: Epic Population​

Day 4: Sprint Planning​

Day 5: Validation​

Automation Scripts​

Batch Epic Creation​

Batch Sprint Creation​

Database Import from Markdown​

Query Commands​

Epic Progress​

Sprint Burndown​

Project Dashboard​

Validation Checklist​

Common Issues​

Issue: Tasks not rolling up to epic​

Issue: Sprint dates overlapping​

Issue: Duplicate task IDs​

Related Documentation​

Overview

Prerequisites

The 1-2-3 Methodology

Phase 1: Foundation (Do Once)

Phase 2: Epic Creation (Per Epic)

Step 2.1: Create Epic Overview File

Step 2.2: Create Epic Tasklist File

Step 2.3: Insert Epic into Database

Phase 3: Sprint Planning (Per Sprint)

Step 3.1: Create Sprint Plan File

Step 3.2: Insert Sprint into Database

Step 3.3: Assign Tasks to Sprint

Optimal Execution Order

Day 1: Foundation

Day 2-3: Epic Population

Day 4: Sprint Planning

Day 5: Validation

Automation Scripts

Batch Epic Creation

Batch Sprint Creation

Database Import from Markdown

Query Commands

Epic Progress

Sprint Burndown

Project Dashboard

Validation Checklist

Common Issues

Issue: Tasks not rolling up to epic

Issue: Sprint dates overlapping

Issue: Duplicate task IDs

Related Documentation