Skip to main content

CODITECT Project Documentation Standard v1.0

Status: Production Ready Version: 1.0.0 Last Updated: 2025-11-28 Maintainer: CODITECT Core Team

Overview​

This document defines the standardized format for CODITECT project documentation, enabling automated parsing, AI-powered analysis, and intelligent commit-task linking in Dashboard 2.0.

Key Benefits:

  • πŸ“Š Structured Data Capture: YAML frontmatter + markdown enables machine parsing
  • πŸ”— Enhanced Linking: Unique task IDs enable precise commit-task relationships
  • πŸ“ˆ Rich Analytics: Time tracking, complexity, dependencies enable insights
  • πŸ€– AI Integration: Standardized format improves AI analysis accuracy
  • βœ… Validation: Automated linting catches errors early
  • πŸ”„ Backward Compatible: Old format still works, migration tools provided

1. Project Configuration File​

Location: .coditect/project.yml

Schema​

# Project Configuration (CODITECT Standard v1.0)
project:
# Core Identification
name: "Project Name"
short_name: "PROJ" # 2-6 uppercase letters for task IDs (TASK-PROJ-0001)
version: "1.0.0"
description: "Brief project description"

# Project Metadata
repository: "https://github.com/org/repo"
documentation_url: "https://docs.example.com"
status: "active" # active | on-hold | completed | archived

# Team
owner: "Team Name"
lead: "Lead Name"
team_members:
- "Developer 1"
- "Developer 2"

# Dates
start_date: "2025-01-15"
target_completion: "2025-06-30"

# Task ID Configuration
task_id_prefix: "TASK-PROJ" # Generated as {prefix}-{number}
task_id_start: 1000 # First task ID: TASK-PROJ-1000

# Standards Compliance
coditect_version: "1.0"
schema_version: "1.0"

# Optional: Integration Settings
integrations:
git:
default_branch: "main"
commit_task_linking: true

ai:
embedding_model: "text-embedding-3-small"
enable_ai_analysis: true

Example​

project:
name: "CODITECT Cloud Backend"
short_name: "CCB"
version: "2.0.0"
description: "Cloud-native backend services for CODITECT platform"
repository: "https://github.com/coditect-ai/coditect-cloud-backend"
status: "active"
owner: "Backend Team"
lead: "Hal Casteel"
team_members:
- "Claude Code"
- "Developer 2"
start_date: "2025-10-01"
target_completion: "2026-03-11"
task_id_prefix: "TASK-CCB"
task_id_start: 1000
coditect_version: "1.0"
schema_version: "1.0"

2. Enhanced tasklist.md Format​

Structure​

---
# YAML Frontmatter (Required)
project: "Project Short Name"
version: "1.0.0"
last_updated: "2025-11-28"
total_tasks: 150
completed_tasks: 45
in_progress_tasks: 10
blocked_tasks: 2
status: "active"
---

# Project Name - Task List

**Project Status**: Active
**Completion**: 30% (45/150 tasks)
**Last Updated**: 2025-11-28

## Task Categories

### Phase 1: Foundation (40 tasks)

#### TASK-PROJ-1001: Setup Development Environment
- **Status**: βœ… Completed
- **Priority**: P0 (Critical)
- **Complexity**: 3 points (8 hours)
- **Assignee**: Developer 1
- **Due Date**: 2025-11-15
- **Tags**: #infrastructure #devops #setup
- **Dependencies**: None
- **Blockers**: None
- **Time Tracking**:
- Estimated: 8h
- Actual: 6h
- Remaining: 0h
- **Acceptance Criteria**:
- [ ] Docker environment running
- [ ] All dependencies installed
- [ ] CI/CD pipeline configured
- [ ] Documentation updated
- **Notes**: Completed ahead of schedule. Docker Compose configuration reused from previous project.
- **Related Commits**:
- abc123f: "feat: Add Docker Compose setup"
- def456a: "docs: Update README with setup instructions"

#### TASK-PROJ-1002: Database Schema Design
- **Status**: πŸ”„ In Progress
- **Priority**: P0 (Critical)
- **Complexity**: 5 points (13 hours)
- **Assignee**: Developer 2
- **Due Date**: 2025-11-20
- **Tags**: #database #schema #postgresql
- **Dependencies**: TASK-PROJ-1001
- **Blockers**: Waiting for stakeholder approval on data model
- **Time Tracking**:
- Estimated: 13h
- Actual: 8h
- Remaining: 5h
- **Acceptance Criteria**:
- [ ] ERD diagram created
- [ ] Migration scripts written
- [ ] Indexes optimized
- [ ] Performance tested (>1000 TPS)
- **Notes**: 60% complete. Blocked on approval, but can proceed with draft implementation.

#### TASK-PROJ-1003: API Endpoint Implementation
- **Status**: ⏸️ Pending
- **Priority**: P1 (High)
- **Complexity**: 8 points (21 hours)
- **Assignee**: Unassigned
- **Due Date**: 2025-11-30
- **Tags**: #api #backend #rest
- **Dependencies**: TASK-PROJ-1002
- **Blockers**: None
- **Time Tracking**:
- Estimated: 21h
- Actual: 0h
- Remaining: 21h
- **Acceptance Criteria**:
- [ ] All CRUD endpoints implemented
- [ ] OpenAPI spec generated
- [ ] Unit tests (>80% coverage)
- [ ] Integration tests passing
- **Notes**: Waiting for schema design completion.

#### TASK-PROJ-1004: Frontend Dashboard
- **Status**: ❌ Blocked
- **Priority**: P2 (Medium)
- **Complexity**: 13 points (34 hours)
- **Assignee**: Developer 3
- **Due Date**: 2025-12-15
- **Tags**: #frontend #react #ui
- **Dependencies**: TASK-PROJ-1003
- **Blockers**: API endpoints not ready, design mockups pending
- **Time Tracking**:
- Estimated: 34h
- Actual: 0h
- Remaining: 34h
- **Acceptance Criteria**:
- [ ] Dashboard UI matches design
- [ ] All API integrations working
- [ ] Responsive (mobile + desktop)
- [ ] Accessibility compliant (WCAG 2.1 AA)
- **Notes**: Can start component scaffolding while waiting for API.

### Summary Statistics

**By Status**:
- βœ… Completed: 45 tasks (30%)
- πŸ”„ In Progress: 10 tasks (6.7%)
- ⏸️ Pending: 93 tasks (62%)
- ❌ Blocked: 2 tasks (1.3%)

**By Priority**:
- P0 (Critical): 20 tasks
- P1 (High): 50 tasks
- P2 (Medium): 60 tasks
- P3 (Low): 20 tasks

**Time Tracking**:
- Total Estimated: 1,250 hours
- Total Actual: 320 hours
- Total Remaining: 930 hours
- Average Complexity: 5.2 points

Required Fields​

Each task MUST include:

  • Task ID: TASK-{PROJECT_SHORT}-{NUMBER} (unique, sequential)
  • Status: One of βœ… Completed, πŸ”„ In Progress, ⏸️ Pending, ❌ Blocked
  • Priority: P0 (Critical), P1 (High), P2 (Medium), P3 (Low)
  • Complexity: Story points or hours (integer)
  • Assignee: Name or "Unassigned"
  • Due Date: ISO 8601 format (YYYY-MM-DD)
  • Tags: Hash-prefixed keywords (#tag1 #tag2)
  • Dependencies: List of task IDs or "None"
  • Blockers: Description or "None"
  • Acceptance Criteria: Checkbox list of completion conditions

Optional Fields​

  • Time Tracking: Estimated, Actual, Remaining hours
  • Notes: Additional context, decisions, learnings
  • Related Commits: Git commit hashes and messages

3. Enhanced project-plan.md Format​

Structure​

---
# YAML Frontmatter (Required)
project: "Project Short Name"
version: "2.0.0"
last_updated: "2025-11-28"
status: "active"
completion_percentage: 30
total_phases: 5
current_phase: 2
---

# Project Name - Project Plan

**Version**: 2.0.0
**Status**: Active (Phase 2 of 5)
**Completion**: 30%
**Last Updated**: 2025-11-28

## Executive Summary

[2-3 paragraph overview of project goals, scope, and current status]

## Project Objectives

### OKRs (Objectives and Key Results)

**Objective 1**: Deliver production-ready cloud backend
- **KR1**: 99.9% uptime SLA achieved (Target: Q2 2026)
- **KR2**: <200ms API response time (Target: Q1 2026)
- **KR3**: 80%+ test coverage (Target: Q1 2026)

**Objective 2**: Enable team scalability
- **KR1**: Reduce onboarding time to <1 week (Target: Q2 2026)
- **KR2**: Automate 90% of deployment tasks (Target: Q1 2026)

## Project Phases

### Phase 1: Foundation (Weeks 1-4)
- **Status**: βœ… Completed
- **Duration**: 4 weeks (Oct 1 - Oct 28, 2025)
- **Completion**: 100% (40/40 tasks)
- **Budget**: $15,000 (actual: $14,200)
- **Key Deliverables**:
- βœ… Development environment setup
- βœ… Database schema design
- βœ… CI/CD pipeline operational
- βœ… Documentation framework

### Phase 2: Core Development (Weeks 5-12)
- **Status**: πŸ”„ In Progress
- **Duration**: 8 weeks (Oct 29 - Dec 23, 2025)
- **Completion**: 35% (21/60 tasks)
- **Budget**: $40,000 (spent: $12,000)
- **Key Deliverables**:
- πŸ”„ API endpoints (60% complete)
- πŸ”„ Authentication system (40% complete)
- ⏸️ Frontend dashboard (0% complete)
- ⏸️ Integration tests (0% complete)
- **Dependencies**: Phase 1 completion
- **Risks**:
- HIGH: Design approval delays blocking frontend (Mitigation: Start component scaffolding)
- MEDIUM: Third-party API integration complexity (Mitigation: Spike task scheduled)

### Phase 3: Testing & Hardening (Weeks 13-16)
- **Status**: ⏸️ Pending
- **Duration**: 4 weeks (Dec 24, 2025 - Jan 20, 2026)
- **Completion**: 0% (0/30 tasks)
- **Budget**: $20,000
- **Dependencies**: Phase 2 completion
- **Key Deliverables**:
- Load testing (target: 10,000 RPS)
- Security audit
- Performance optimization
- Bug fixes

### Phase 4: Beta Testing (Weeks 17-20)
- **Status**: ⏸️ Pending
- **Duration**: 4 weeks (Jan 21 - Feb 17, 2026)
- **Completion**: 0% (0/15 tasks)
- **Budget**: $10,000
- **Dependencies**: Phase 3 completion

### Phase 5: Production Launch (Weeks 21-24)
- **Status**: ⏸️ Pending
- **Duration**: 4 weeks (Feb 18 - Mar 17, 2026)
- **Completion**: 0% (0/5 tasks)
- **Budget**: $5,000
- **Target Date**: March 11, 2026

## Dependencies

### Cross-Phase Dependencies
- Phase 2 β†’ Phase 3: API completion required for load testing
- Phase 3 β†’ Phase 4: Security audit must pass before beta
- Phase 4 β†’ Phase 5: Beta feedback incorporated before launch

### External Dependencies
- **Third-Party APIs**: Payment provider integration (Q1 2026)
- **Infrastructure**: GCP quota increase approval (In progress)
- **Legal**: Terms of Service review (Q4 2025)

## Risk Management

### High Risks
1. **Design Approval Delays** (Impact: High, Probability: Medium)
- Mitigation: Weekly stakeholder syncs, async approval process
- Contingency: Proceed with draft design, iterate post-approval

2. **Third-Party API Changes** (Impact: Medium, Probability: Low)
- Mitigation: API versioning, abstraction layer
- Contingency: Fallback to alternative provider

### Medium Risks
1. **Team Capacity Constraints** (Impact: Medium, Probability: Medium)
- Mitigation: Cross-training, contractor backup
- Contingency: Reduce scope, extend timeline

## Budget Summary

| Phase | Budget | Actual | Remaining | Status |
|-------|--------|--------|-----------|--------|
| Phase 1 | $15,000 | $14,200 | $800 | βœ… Complete |
| Phase 2 | $40,000 | $12,000 | $28,000 | πŸ”„ In Progress |
| Phase 3 | $20,000 | $0 | $20,000 | ⏸️ Pending |
| Phase 4 | $10,000 | $0 | $10,000 | ⏸️ Pending |
| Phase 5 | $5,000 | $0 | $5,000 | ⏸️ Pending |
| **Total** | **$90,000** | **$26,200** | **$63,800** | **29% spent** |

## Success Metrics

- **Technical**: 99.9% uptime, <200ms latency, 80%+ test coverage
- **Business**: Launch on March 11, 2026, within $90K budget
- **Team**: <1 week onboarding time, 90% deployment automation

## Stakeholders

- **Project Sponsor**: Executive Name
- **Product Owner**: Product Manager Name
- **Tech Lead**: Lead Developer Name
- **Key Stakeholders**: Marketing, Sales, Customer Success

## Communication Plan

- **Daily**: Standup (15 min, async Slack)
- **Weekly**: Sprint review (Friday 2pm)
- **Biweekly**: Stakeholder sync (Tuesday 10am)
- **Monthly**: Executive briefing (first Monday)

## Change Management

All scope changes require:
1. Impact analysis (timeline, budget, resources)
2. Stakeholder approval (Product Owner + Tech Lead)
3. project-plan.md update
4. Communication to team

## Appendix

### Glossary
- **OKR**: Objectives and Key Results
- **SLA**: Service Level Agreement
- **RPS**: Requests Per Second

### References
- [Architecture Decision Records](docs/adrs/)
- [Technical Specifications](docs/specs/)
- [API Documentation](docs/api/)

Required Sections​

  1. YAML Frontmatter: Project metadata
  2. Executive Summary: High-level overview
  3. OKRs: Measurable objectives
  4. Phases: Breakdown with status, dates, budget
  5. Dependencies: Cross-phase and external
  6. Risks: Identified risks with mitigations
  7. Budget: Phase-by-phase breakdown
  8. Success Metrics: Clear completion criteria

4. Task ID Convention​

Format​

TASK-{PROJECT_SHORT}-{NUMBER}

Rules​

  1. PROJECT_SHORT: 2-6 uppercase letters from .coditect/project.yml
  2. NUMBER: Sequential integer, padded to 4 digits
  3. Uniqueness: Each task ID must be unique within project
  4. Immutability: Task IDs never change once assigned

Examples​

TASK-CCB-1001   # CODITECT Cloud Backend, task 1001
TASK-FE-2047 # Frontend, task 2047
TASK-DOCS-0015 # Documentation, task 15
TASK-SEC-9999 # Security, task 9999

Generation​

# Automatic generation from .coditect/project.yml
prefix = config['project']['task_id_prefix'] # "TASK-CCB"
start = config['project']['task_id_start'] # 1000
next_id = f"{prefix}-{start + task_count:04d}" # "TASK-CCB-1001"

5. Commit Message Integration​

Standard Format​

<type>(<scope>): <subject>

<body>

TASK: TASK-{PROJECT_SHORT}-{NUMBER}
TASK: TASK-{PROJECT_SHORT}-{NUMBER2} # Multiple tasks if applicable

πŸ€– Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

Examples​

feat(api): Add user authentication endpoints

Implement JWT-based authentication with refresh tokens.
Includes login, logout, and token refresh endpoints.

TASK: TASK-CCB-1015
TASK: TASK-CCB-1016

πŸ€– Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
fix(db): Resolve connection pool exhaustion

Increase pool size from 10 to 50 connections.
Add connection timeout handling.

TASK: TASK-CCB-1087

πŸ€– Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

Benefits​

  • Automated Linking: Dashboard 2.0 extracts task IDs from commits
  • Traceability: See all commits related to a task
  • Progress Tracking: Commit activity indicates task progress
  • AI Analysis: Commit messages provide context for AI understanding

6. Migration Guide​

From Legacy Format to v1.0​

Step 1: Create .coditect/project.yml​

# Use template
cp templates/project.yml.template .coditect/project.yml

# Edit with your project details
vim .coditect/project.yml

Step 2: Migrate tasklist.md​

# Run migration script (dry-run first)
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 \
--project-config .coditect/project.yml \
--backup

Step 3: Validate New Format​

# Run validation tool
python backend/tools/coditect_lint.py validate .

# Fix any errors reported
# Re-run until clean

Step 4: Update Commit Templates​

# Add task ID to git commit template
cat >> .git/commit_template.txt << 'EOF'

TASK: TASK-PROJ-XXXX

πŸ€– Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
EOF

git config commit.template .git/commit_template.txt

Migration Checklist​

  • Create .coditect/project.yml
  • Migrate tasklist.md to new format
  • Add YAML frontmatter to project-plan.md
  • Validate with coditect_lint.py
  • Update git commit template
  • Train team on new standards
  • Update CI/CD to run validation
  • Archive legacy documentation

7. Validation and Linting​

coditect-lint Tool​

# Validate entire project
python backend/tools/coditect_lint.py validate .

# Validate specific file
python backend/tools/coditect_lint.py validate tasklist.md

# Output format options
python backend/tools/coditect_lint.py validate . --format json
python backend/tools/coditect_lint.py validate . --format yaml
python backend/tools/coditect_lint.py validate . --format github # For CI/CD

# Strict mode (warnings as errors)
python backend/tools/coditect_lint.py validate . --strict

Validation Rules​

Critical Errors (block CI/CD):

  • Missing .coditect/project.yml
  • Invalid YAML frontmatter
  • Duplicate task IDs
  • Missing required task fields
  • Invalid date formats
  • Invalid priority values
  • Broken task dependencies (reference non-existent tasks)

Warnings (should fix):

  • Missing optional fields (Notes, Related Commits)
  • Inconsistent formatting
  • Tasks without acceptance criteria
  • Estimated time > 40 hours (should split)
  • Overdue tasks without updates

CI/CD Integration​

# .github/workflows/validate-docs.yml
name: Validate CODITECT Documentation

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

8. Best Practices​

Task Management​

  1. Keep Tasks Atomic: Each task should be completable in 1-40 hours
  2. Write Clear Acceptance Criteria: Use checkboxes for verification
  3. Track Time Honestly: Update actual hours regularly
  4. Update Status Promptly: Move to "In Progress" when starting
  5. Document Blockers Immediately: Don't wait for standup
  6. Link Commits: Always reference task IDs in commit messages

Project Planning​

  1. Review Weekly: Update completion percentages and dates
  2. Manage Risks Actively: Review risk register biweekly
  3. Track Dependencies: Update as new dependencies discovered
  4. Communicate Changes: Update stakeholders on scope/timeline changes
  5. Learn from Retrospectives: Document lessons in Notes

Documentation Quality​

  1. Version Everything: Increment version on significant changes
  2. Date Stamp Updates: Always update last_updated field
  3. Use Templates: Start from templates for consistency
  4. Validate Before Commit: Run coditect_lint.py before git commit
  5. Keep It Current: Stale docs are worse than no docs

9. Examples and Templates​

Complete Example Project​

See templates/ directory for:

  • project.yml.template - Sample project configuration
  • tasklist.md.template - Full tasklist with all fields
  • project-plan.md.template - Complete project plan
  • task.md.template - Single task entry

Real-World Example​

Project: Dashboard 2.0 POC

  • Short Name: D20
  • Total Tasks: 89
  • Current Phase: Phase 2 (Development)
  • Status: Active
  • Example Task ID: TASK-D20-1045

10. Frequently Asked Questions​

Q: Do I need to migrate existing projects immediately?​

A: No. The parser supports both old and new formats. Migrate when convenient (recommended within 3 months).

Q: What if my task IDs don't start at 1000?​

A: Configure task_id_start in .coditect/project.yml. Can start at any number (1, 100, 1000, etc.).

Q: Can I use custom task statuses?​

A: Standard statuses are recommended (βœ… πŸ”„ ⏸️ ❌), but you can extend. Update parser if needed.

Q: How do I handle subtasks?​

A: Use hierarchical numbering:

  • TASK-PROJ-1001 (Parent)
    • TASK-PROJ-1001.1 (Subtask 1)
    • TASK-PROJ-1001.2 (Subtask 2)

Q: What about multi-repo projects?​

A: Each repo gets its own .coditect/project.yml with unique short_name. Cross-repo dependencies use full task IDs.

Q: Can I automate task creation from code?​

A: Yes. See backend/api_v2.py for API endpoints to create/update tasks programmatically.


11. Versioning and Changes​

Version History​

  • v1.0.0 (2025-11-28): Initial release
    • Enhanced tasklist.md format with YAML frontmatter
    • Enhanced project-plan.md format with OKRs
    • Task ID convention standardized
    • .coditect/project.yml configuration
    • Migration tools and validation

Future Enhancements (Roadmap)​

  • v1.1: Templates for different project types (web app, API, library, etc.)
  • v1.2: Integration with GitHub Issues, JIRA
  • v1.3: AI-powered task estimation and risk prediction
  • v2.0: Multi-project portfolio management

12. Support and Resources​

Documentation​

  • This Document: CODITECT Project Documentation Standard v1.0
  • Migration Guide: docs/migration-guide.md
  • Templates: templates/ directory
  • Parser Documentation: backend/parsers/README.md
  • Validation Tool: backend/tools/README.md

Tools​

  • Parser: backend/parsers/coditect_parser.py
  • Validator: backend/tools/coditect_lint.py
  • Migration: backend/tools/migrate_legacy_tasklist.py

Getting Help​

  • Issues: GitHub Issues in project repository
  • Discussions: GitHub Discussions
  • Email: support@coditect.ai (if applicable)

Appendix A: Schema Definitions​

.coditect/project.yml JSON Schema​

{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["project"],
"properties": {
"project": {
"type": "object",
"required": ["name", "short_name", "version"],
"properties": {
"name": {"type": "string", "minLength": 1},
"short_name": {
"type": "string",
"pattern": "^[A-Z]{2,6}$",
"description": "2-6 uppercase letters for task ID prefix"
},
"version": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+$"
},
"description": {"type": "string"},
"repository": {"type": "string", "format": "uri"},
"status": {
"type": "string",
"enum": ["active", "on-hold", "completed", "archived"]
},
"owner": {"type": "string"},
"lead": {"type": "string"},
"team_members": {
"type": "array",
"items": {"type": "string"}
},
"start_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"target_completion": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"task_id_prefix": {
"type": "string",
"pattern": "^TASK-[A-Z]{2,6}$"
},
"task_id_start": {
"type": "integer",
"minimum": 1
},
"coditect_version": {"type": "string"},
"schema_version": {"type": "string"}
}
}
}
}

tasklist.md YAML Frontmatter Schema​

{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["project", "version", "last_updated"],
"properties": {
"project": {"type": "string"},
"version": {"type": "string"},
"last_updated": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"total_tasks": {"type": "integer", "minimum": 0},
"completed_tasks": {"type": "integer", "minimum": 0},
"in_progress_tasks": {"type": "integer", "minimum": 0},
"blocked_tasks": {"type": "integer", "minimum": 0},
"status": {
"type": "string",
"enum": ["active", "on-hold", "completed", "archived"]
}
}
}

End of CODITECT Project Documentation Standard v1.0

For questions or suggestions, please open an issue in the project repository.