Skip to main content

CODITECT Standards v1.0 Migration Guide

Version: 1.0.0 Last Updated: 2025-11-28 Target Audience: Project teams migrating to CODITECT Standards v1.0

Quick Migration (5 Minutes)​

For existing Dashboard 2.0 projects:

# 1. Create .coditect/project.yml
cp templates/project.yml.template .coditect/project.yml
# Edit with your project details

# 2. Migrate tasklist.md (with backup)
python backend/tools/migrate_legacy_tasklist.py \
  --input tasklist.md \
  --output tasklist.md \
  --backup

# 3. Validate
python backend/tools/coditect_lint.py validate .

# 4. Done!

What's New in v1.0?​

1. YAML Frontmatter​

All documentation files now include structured metadata:

  • tasklist.md - Task statistics, version tracking
  • project-plan.md - Project status, phase progress

2. Enhanced Task Format​

Tasks now include:

  • Unique Task IDs: TASK-{SHORT}-{NUMBER}
  • Time Tracking: Estimated, actual, remaining hours
  • Acceptance Criteria: Checkbox-based completion tracking
  • Dependencies: Explicit task relationships
  • Tags: Categorization and filtering

3. Database Schema Updates​

New fields in tasks table:

  • task_id (unique identifier)
  • complexity_hours, time_estimate, time_actual, time_remaining
  • tags, acceptance_criteria, blockers (JSON)
  • assignee, due_date, notes

4. Validation & Linting​

New tool: coditect_lint.py

  • Validates project configuration
  • Checks task ID uniqueness
  • Verifies format compliance

Migration Steps​

Step 1: Create Project Configuration​

Create .coditect/project.yml:

project:
  name: "Dashboard 2.0 POC"
  short_name: "D20"  # Used in task IDs: TASK-D20-1001
  version: "4.0.0"
  description: "Intelligent project management dashboard with AI-powered commit-task linking"
  repository: "https://github.com/coditect-ai/dashboard-2.0"
  status: "active"
  start_date: "2025-11-01"
  target_completion: "2025-12-31"
  task_id_prefix: "TASK-D20"
  task_id_start: 1000

Step 2: Migrate tasklist.md​

Option A: Automated Migration (Recommended)

python backend/tools/migrate_legacy_tasklist.py \
  --input tasklist.md \
  --output TASKLIST-v1.md \
  --project-config .coditect/project.yml \
  --dry-run

# Review changes
diff tasklist.md TASKLIST-v1.md

# Apply migration
python backend/tools/migrate_legacy_tasklist.py \
  --input tasklist.md \
  --output tasklist.md \
  --backup

Option B: Manual Migration

  1. Add YAML frontmatter at top:
---
project: "D20"
version: "4.0.0"
last_updated: "2025-11-28"
total_tasks: 89
completed_tasks: 45
in_progress_tasks: 12
blocked_tasks: 3
status: "active"
---
  1. Add task IDs to headers:
#### TASK-D20-1045: Hybrid AI + TF-IDF Commit Linking
  1. Add structured fields to each task:
- **Status**: ✅ Completed
- **Priority**: P0 (Critical)
- **Complexity**: 8 points (21 hours)
- **Assignee**: Developer 1
- **Due Date**: 2025-11-25
- **Tags**: #ai #backend #linking
- **Dependencies**: TASK-D20-1040
- **Blockers**: None
- **Time Tracking**:
  - Estimated: 21h
  - Actual: 18h
  - Remaining: 0h
- **Acceptance Criteria**:
  - [x] AI linker operational
  - [x] TF-IDF fallback working
  - [x] Result merging implemented

Step 3: Run Database Migration​

# Apply schema updates
cd backend
sqlite3 dashboard.db < migrations/001_add_enhanced_task_fields.sql

# Verify migration
sqlite3 dashboard.db "SELECT * FROM migration_log;"

Step 4: Validate​

python backend/tools/coditect_lint.py validate .

Fix any errors reported before proceeding.

Step 5: Update Git Commit Template​

cat >> .git/commit_template.txt << 'EOF'

TASK: TASK-D20-XXXX

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
EOF

git config commit.template .git/commit_template.txt

Backward Compatibility​

Good news: The parser supports both old and new formats!

  • ✅ Old tasklist.md without frontmatter still works
  • ✅ Tasks without structured fields are still parsed
  • ✅ Existing API endpoints remain unchanged

Migration is non-breaking - you can migrate incrementally.

Validation Rules​

Critical Errors (Block CI/CD)​

  • Missing .coditect/project.yml
  • Invalid YAML frontmatter
  • Duplicate task IDs
  • Invalid task ID format
  • Missing required fields (name, short_name, version)

Warnings (Should Fix)​

  • Missing optional fields
  • Inconsistent formatting
  • Tasks without acceptance criteria
  • Overdue tasks without updates

Testing the Migration​

1. Parse Project Config​

cd backend
python3 -c "
from parsers.coditect_parser import CoditectParser
parser = CoditectParser('..')
config = parser.parse_project_config()
print(f'✅ Project: {config.name} ({config.short_name})')
"

2. Parse tasklist.md​

python3 -c "
from parsers.coditect_parser import CoditectParser
parser = CoditectParser('..')
fm, tasks = parser.parse_tasklist()
print(f'✅ Parsed {len(tasks)} tasks')
for task in tasks[:3]:
    print(f'  - {task.task_id}: {task.title}')
"

3. Validate All​

python backend/tools/coditect_lint.py validate . --strict

CI/CD Integration​

GitHub Actions Example​

name: Validate CODITECT Standards

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: pip install pyyaml jsonschema
      - name: Validate documentation
        run: |
          python backend/tools/coditect_lint.py validate . --strict --format github

Rollback Procedure​

If you need to rollback:

# Restore tasklist.md from backup
cp tasklist.md.backup-YYYYMMDD-HHMMSS tasklist.md

# Rollback database
sqlite3 backend/dashboard.db < backend/migrations/rollback_001.sql

# Remove .coditect directory
rm -rf .coditect

FAQ​

Q: Do I need to migrate immediately? A: No. Old format still works. Migrate when convenient.

Q: Will my existing Dashboard 2.0 break? A: No. All existing functionality continues to work.

Q: What if I have custom task formats? A: Parser is flexible. Contact support if issues arise.

Q: Can I customize task IDs? A: Yes. Set task_id_prefix and task_id_start in project.yml.

Q: How do I handle multi-repo projects? A: Each repo gets its own .coditect/project.yml with unique short_name.

Support​

Issues: GitHub Issues Documentation: See docs/coditect-project-standards-v1.md Tools: backend/parsers/, backend/tools/

Next Steps​

After migration:

  1. ✅ Commit migrated files
  2. ✅ Update team on new format
  3. ✅ Setup CI/CD validation
  4. ✅ Monitor for issues
  5. ✅ Provide feedback for v1.1

Migration Complete? Run final validation:

python backend/tools/coditect_lint.py validate . --strict --format text

Look for: ✅ PASSED

Version: 1.0.0 Status: Production Ready Last Updated: 2025-11-28