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β
- YAML Frontmatter: Project metadata
- Executive Summary: High-level overview
- OKRs: Measurable objectives
- Phases: Breakdown with status, dates, budget
- Dependencies: Cross-phase and external
- Risks: Identified risks with mitigations
- Budget: Phase-by-phase breakdown
- Success Metrics: Clear completion criteria
4. Task ID Conventionβ
Formatβ
TASK-{PROJECT_SHORT}-{NUMBER}
Rulesβ
- PROJECT_SHORT: 2-6 uppercase letters from
.coditect/project.yml - NUMBER: Sequential integer, padded to 4 digits
- Uniqueness: Each task ID must be unique within project
- 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.mdto 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β
- Keep Tasks Atomic: Each task should be completable in 1-40 hours
- Write Clear Acceptance Criteria: Use checkboxes for verification
- Track Time Honestly: Update actual hours regularly
- Update Status Promptly: Move to "In Progress" when starting
- Document Blockers Immediately: Don't wait for standup
- Link Commits: Always reference task IDs in commit messages
Project Planningβ
- Review Weekly: Update completion percentages and dates
- Manage Risks Actively: Review risk register biweekly
- Track Dependencies: Update as new dependencies discovered
- Communicate Changes: Update stakeholders on scope/timeline changes
- Learn from Retrospectives: Document lessons in Notes
Documentation Qualityβ
- Version Everything: Increment version on significant changes
- Date Stamp Updates: Always update
last_updatedfield - Use Templates: Start from templates for consistency
- Validate Before Commit: Run
coditect_lint.pybefore git commit - 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 configurationtasklist.md.template- Full tasklist with all fieldsproject-plan.md.template- Complete project plantask.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.ymlconfiguration- 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.