# CCD for AI CLI
A Python-based command-line interface for CCD for AI (Continuous Context Documentation for AI) methodology.
## Features
- **Project Initialization**: Set up new CCD projects with proper structure
- **Context Generation**: Automatically generate context cards, module indexes, and CODEMAP
- **AI-CONTEXT Integration**: Add and manage context comments in source code files
- **Validation**: Validate CCD documentation against JSON schemas
- **Health Monitoring**: Check project health and coverage metrics
- **Automation**: CI/CD integration and automated context updates
- **Rich Output**: Beautiful terminal output with colors and formatting
## Installation
### From PyPI (Recommended)
```bash
pip install ccd-cli
```
### From Source
```bash
git clone https://github.com/yegorferrieres/ccd-ai.git
cd ccd-ai/tools/ccd-cli
pip install -e .
```
## Publishing to PyPI
### Building the Package
```bash
# Install build tools
pip install build twine
# Build the package
python -m build
# This creates dist/ directory with wheel and source distribution
```
### Publishing to TestPyPI
```bash
# Upload to TestPyPI first
twine upload --repository testpypi dist/*
# Test installation from TestPyPI
pip install --index-url https://test.pypi.org/simple/ ccd-cli
```
### Publishing to PyPI
```bash
# Upload to PyPI
twine upload dist/*
# Verify installation
pip install ccd-cli
```
### Development Installation
```bash
git clone https://github.com/yegorferrieres/ccd-ai.git
cd ccd-ai/tools/ccd-cli
pip install -e ".[dev]"
```
### Verify Installation
```bash
ccd --help
```
## Quick Start
### 1. Install CCD for AI CLI
```bash
git clone https://github.com/yegorferrieres/ccd-ai.git
cd ccd-ai/tools/ccd-cli
pip install -e .
```
### 2. Initialize a New CCD for AI Project
```bash
ccd init --project-name "My Project" --domain "web-application"
```
### 3. Prepare Context for AI
```bash
# Generate complete project context for AI developer
ccd prepare-context
# Generate to specific file
ccd prepare-context --output my-task-context.txt
```
### Generate Context Cards
```bash
ccd generate-cards --files "src/**/*.py" --output docs/context-cards/
```
### Validate Context
```bash
ccd validate-contexts --contexts docs/ --schemas docs/schemas/
```
### Check Health
```bash
ccd health --detailed
```
### Work with AI-CONTEXT Comments
```bash
# Add context comments to source files
ccd add-context-comments --file "src/main.go" --context "docs/contexts/files/src/main.go.ctx.md"
# Extract existing context comments
ccd extract-context --file "src/main.go"
# Validate comment format
ccd validate-context-comments --file "src/main.go"
# Update context comments
ccd update-context-comments --file "src/main.go" --context "docs/contexts/files/src/main.go.ctx.md"
# Check context freshness
ccd context-freshness --file "src/main.go"
```
## Commands
### `ccd init`
Initialize a new CCD for AI project.
```bash
ccd init --project-name "Project Name" --domain "web-application" --output-dir "./my-project"
```
**Options:**
- `--project-name, -n`: Project name (required)
- `--domain, -d`: Project domain (required)
- `--yes, -y`: Skip prompts and use defaults
- `--output-dir, -o`: Output directory (default: current directory)
**Supported Domains:**
- `web-application`
- `mobile-app`
- `api-service`
- `library`
- `cli-tool`
- `data-pipeline`
- `ml-ai`
- `infrastructure`
- `other`
### `ccd add-context-comments`
Add AI-CONTEXT comments to source code files.
```bash
ccd add-context-comments --file "src/main.go" --context "docs/contexts/files/src/main.go.ctx.md"
```
**Options:**
- `--file, -f`: Source file path (required)
- `--context, -c`: Context card file path (required)
- `--force, -F`: Overwrite existing comments
- `--dry-run`: Show what would be added without making changes
### `ccd extract-context`
Extract AI-CONTEXT comments from source code files.
```bash
ccd extract-context --file "src/main.go"
ccd extract-context --files "src/**/*.go"
ccd extract-context --project .
```
**Options:**
- `--file, -f`: Single file path
- `--files, -F`: Glob pattern for multiple files
- `--project, -p`: Extract from entire project
- `--output, -o`: Output file for extracted comments
### `ccd validate-context-comments`
Validate AI-CONTEXT comment format and content.
```bash
ccd validate-context-comments --file "src/main.go"
ccd validate-context-comments --files "src/**/*.go"
ccd validate-context-comments --project .
```
**Options:**
- `--file, -f`: Single file path
- `--files, -F`: Glob pattern for multiple files
- `--project, -p`: Validate entire project
- `--strict`: Fail on any validation errors
- `--report`: Generate detailed validation report
### `ccd update-context-comments`
Update AI-CONTEXT comments with new information.
```bash
ccd update-context-comments --file "src/main.go" --context "docs/contexts/files/src/main.go.ctx.md"
ccd update-context-comments --project . --refresh-timestamps
```
**Options:**
- `--file, -f`: Source file path
- `--context, -c`: Context card file path
- `--project, -p`: Update entire project
- `--refresh-timestamps`: Update all timestamps
- `--dry-run`: Show what would be updated
### `ccd context-freshness`
Check context freshness and health across the project.
```bash
ccd context-freshness --file "src/main.go"
ccd context-freshness --project .
ccd context-freshness --project . --report --output freshness-report.json
```
**Options:**
- `--file, -f`: Single file path
- `--project, -p`: Check entire project
- `--report`: Generate detailed report
- `--output, -o`: Output file for report
- `--threshold`: Set freshness threshold (default: 24h)
### `ccd context-health`
Check context health across the project.
```bash
ccd context-health --file "src/main.go"
ccd context-health --project . --detailed
```
**Options:**
- `--file, -f`: Single file path
- `--project, -p`: Check entire project
- `--detailed`: Show detailed health information
### `ccd drift-detection`
Detect context drift in the project.
```bash
ccd drift-detection --project .
ccd drift-detection --project . --output drift-report.json
```
**Options:**
- `--project, -p`: Check entire project
- `--output, -o`: Output file for drift report
### `ccd quality-gates`
Run all quality gates for the project.
```bash
ccd quality-gates --project .
ccd quality-gates --project . --output quality-report.json
```
**Options:**
- `--project, -p`: Check entire project
- `--output, -o`: Output file for quality report
### `ccd update-engineering-log`
Update ENGINEERING_LOG.md with a new entry.
```bash
ccd update-engineering-log --description "Implemented new feature" --impact "Medium"
```
**Options:**
- `--log-file, -l`: Path to ENGINEERING_LOG.md file (default: ./docs/ENGINEERING_LOG.md)
- `--description, -d`: Description of the development task (required)
- `--impact, -i`: Impact scope (High/Medium/Low, default: Medium)
- `--severity, -s`: Severity (High/Medium/Low, default: Medium)
- `--technical-changes, -t`: Description of technical changes made
- `--resolution, -r`: How the task was resolved
- `--lessons-learned`: Key insights gained from the task
- `--follow-up`: Next steps or follow-up actions
### `ccd update-roadmap`
Update roadmap.md to mark milestones as completed or in progress.
```bash
ccd update-roadmap --milestone "API integration" --status "completed"
```
**Options:**
- `--roadmap-file, -r`: Path to roadmap.md file (default: ./docs/roadmap.md)
- `--milestone, -m`: Milestone to update (required)
- `--status, -s`: New status (completed/in_progress, default: completed)
- `--notes, -n`: Additional notes about the milestone
### `ccd create-adr`
Create a new Architecture Decision Record (ADR).
```bash
ccd create-adr --title "Database Schema Changes" --status "Proposed"
```
**Options:**
- `--decisions-dir, -d`: Path to decisions directory (default: ./docs/decisions)
- `--title, -t`: Title of the ADR (required)
- `--status, -s`: Status (Proposed/Accepted/Deprecated/Superseded, default: Proposed)
- `--context, -c`: Context and forces at play
- `--decision`: The decision made
- `--consequences`: Consequences of the decision
### `ccd update-development-rules`
Update DEVELOPMENT_RULES.md with new workflow patterns.
```bash
ccd update-development-rules --new-rule "Feature Flag Pattern" --context "When implementing feature flags"
```
**Options:**
- `--rules-file, -r`: Path to DEVELOPMENT_RULES.md file (default: ./docs/DEVELOPMENT_RULES.md)
- `--new-rule, -n`: Name of the new workflow pattern (required)
### `ccd prepare-context`
Prepare complete project context for AI developer.
```bash
ccd prepare-context
ccd prepare-context --output my-task-context.txt
ccd prepare-context --no-architecture
ccd prepare-context --dry-run
```
**Options:**
- `--project-dir, -p`: Project directory to analyze (default: current directory)
- `--output, -o`: Output file for context (default: task-context-YYYYMMDD-HHMMSS.txt)
- `--no-architecture`: Skip architecture decisions and codemap
- `--dry-run`: Show what would be generated without creating file
### `ccd methodology-status`
Show status of all methodological files in the project.
```bash
ccd methodology-status --project-dir .
```
**Options:**
- `--project-dir, -p`: Project directory to analyze (default: current directory)
### `ccd validate`
Validate CCD schemas and contexts.
```bash
ccd validate-schemas --schemas ./docs/schemas
ccd validate-contexts --contexts ./docs --schemas ./docs/schemas
```
**Options:**
- `--schemas, -s`: Path to schemas directory
- `--contexts, -c`: Path to contexts directory
- `--output-format, -f`: Output format (text, json, yaml)
- `--detailed, -d`: Show detailed validation results
### `ccd generate`
Generate CCD documentation files.
```bash
ccd generate-cards --files "src/**/*.py" --output docs/context-cards/
ccd generate-index --modules "services/*" --output docs/modules/
ccd update-codemap --output docs/CODEMAP.yaml
```
**Options:**
- `--files, -f`: File pattern to process
- `--output, -o`: Output directory
- `--type, -t`: What to generate (cards, index, codemap)
- `--force`: Overwrite existing files
### `ccd health`
Check CCD project health.
```bash
ccd health --detailed --output-format json
```
**Options:**
- `--detailed, -d`: Show detailed health information
- `--output-format, -f`: Output format (text, json, yaml)
### `ccd coverage`
Show CCD coverage statistics.
```bash
ccd coverage --modules --files --min-coverage 80
```
**Options:**
- `--modules, -m`: Show module coverage
- `--files, -f`: Show file coverage
- `--min-coverage`: Minimum coverage percentage
- `--output-format, -o`: Output format (text, json, yaml)
### `ccd freshness`
Check CCD documentation freshness.
```bash
ccd freshness --days 30 --output-format yaml
```
**Options:**
- `--days, -d`: Number of days to check
- `--output-format, -o`: Output format (text, json, yaml)
### `ccd pack`
Package CCD contexts into archive.
```bash
ccd pack --output ./ccd-contexts.zip --include-schemas --include-templates
```
**Options:**
- `--output, -o`: Output archive path
- `--include-schemas`: Include JSON schemas
- `--include-templates`: Include templates
### `ccd monitor`
Monitor CCD project status.
```bash
ccd monitor --watch --interval 60
```
**Options:**
- `--watch, -w`: Watch for file changes
- `--interval, -i`: Check interval in seconds
- `--output-format, -o`: Output format (text, json, yaml)
### `ccd version`
Show CCD CLI version.
```bash
ccd version
```
## Configuration
### Environment Variables
- `CCD_CONFIG_PATH`: Path to configuration file
- `CCD_VERBOSE`: Enable verbose output
- `CCD_QUIET`: Suppress output
### Configuration File
Create a `ccd.config.yaml` file in your project root:
```yaml
# CCD Configuration
project:
name: "My Project"
domain: "web-application"
schemas_path: "./docs/schemas"
contexts_path: "./docs"
generation:
auto_update: true
include_tests: false
include_docs: true
validation:
strict_mode: true
fail_fast: false
output:
default_format: "text"
colors: true
progress_bars: true
```
## Examples
### Complete Workflow
```bash
# 1. Initialize project
ccd init --project-name "My API Service" --domain "api-service"
# 2. Generate context cards for all Python files
ccd generate-cards --files "src/**/*.py" --output docs/context-cards/
# 3. Generate module indexes
ccd generate-index --modules "src/*" --output docs/modules/
# 4. Update CODEMAP
ccd update-codemap --output docs/CODEMAP.yaml
# 5. Validate everything
ccd validate-contexts --contexts docs/ --schemas docs/schemas/
# 6. Check health
ccd health --detailed
# 7. Package for distribution
ccd pack --output ./ccd-contexts.zip --include-schemas
```
### AI-CONTEXT Integration
```bash
# Add AI-CONTEXT comments to source files
ccd add-context-comments --file src/main.py --context docs/contexts/files/src/main.py.ctx.md
# Extract and validate AI-CONTEXT comments
ccd extract-context --file src/main.py
ccd validate-context-comments --file src/main.py --report
# Check context freshness and health
ccd context-freshness --project . --threshold 48
ccd context-health --project . --detailed
```
### Methodology Loop Management
```bash
# Update engineering log after completing a task
ccd update-engineering-log \
--description "Implemented user authentication" \
--impact "High" \
--technical-changes "Added JWT middleware and user model" \
--resolution "Successfully deployed to staging"
# Mark roadmap milestone as completed
ccd update-roadmap --milestone "User Authentication" --status "completed"
# Create ADR for architectural decision
ccd create-adr \
--title "JWT vs Session-based Authentication" \
--status "Accepted" \
--decision "We will use JWT for stateless authentication"
# Check overall methodology status
ccd methodology-status --project-dir .
```
### Quality Assurance
```bash
# Run all quality gates
ccd quality-gates --project . --output quality-report.json
# Detect context drift
ccd drift-detection --project . --output drift-report.json
# Monitor specific quality metrics
ccd context-freshness --project . --threshold 24
ccd context-health --project . --detailed
```
### CI/CD Integration
```yaml
# .github/workflows/ccd-validation.yml
name: CCD Validation
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
validate-ccd:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install CCD CLI
run: |
git clone https://github.com/yegorferrieres/ccd-ai.git
cd ccd-ai/tools/ccd-cli
pip install -e .
- name: Validate CCD Contexts
run: ccd validate-contexts --contexts docs/ --schemas docs/schemas/
- name: Check Health
run: ccd health --output-format json > health-report.json
- name: Upload Health Report
uses: actions/upload-artifact@v3
with:
name: ccd-health-report
path: health-report.json
```
### Automated Monitoring
```bash
# Watch for changes and auto-update
ccd monitor --watch --interval 30
# Check freshness every day
ccd freshness --days 1 --output-format json > freshness-report.json
# Generate coverage report
ccd coverage --modules --files --min-coverage 90 --output-format yaml > coverage-report.yaml
```
## Output Formats
### Text (Default)
Human-readable output with colors and formatting.
### JSON
Machine-readable output for automation and integration.
```json
{
"status": "success",
"data": {
"coverage_percentage": 85.5,
"total_modules": 12,
"total_files": 156,
"health_score": 78.2
}
}
```
### YAML
Human-readable structured output.
```yaml
status: success
data:
coverage_percentage: 85.5
total_modules: 12
total_files: 156
health_score: 78.2
```
## Error Handling
The CLI provides clear error messages and exit codes:
- `0`: Success
- `1`: General error
- `130`: User interruption (Ctrl+C)
## Troubleshooting
### Common Issues
**Import Errors**
```bash
# Ensure you're using the right Python environment
python -m pip install --upgrade ccd-cli
```
**Permission Errors**
```bash
# Use user installation
pip install --user ccd-cli
```
**Schema Validation Failures**
```bash
# Check schema files exist and are valid JSON
ccd validate-schemas --schemas ./docs/schemas --verbose
```
### Debug Mode
Enable verbose output for debugging:
```bash
ccd --verbose health --detailed
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/yegorferrieres/ccd-ai.git
cd ccd-ai
pip install -e "tools/ccd-cli/.[dev]"
```
### Run Tests
```bash
pytest
pytest --cov=ccd_cli --cov-report=html
```
### Code Quality
```bash
# Format code
black ccd_cli/
# Sort imports
isort ccd_cli/
# Lint code
flake8 ccd_cli/
# Type checking
mypy ccd_cli/
```
### Pre-commit Hooks
```bash
pre-commit install
pre-commit run --all-files
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [https://github.com/yegorferrieres/ccd-ai](https://github.com/yegorferrieres/ccd-ai)
- **Issues**: [GitHub Issues](https://github.com/yegorferrieres/ccd-ai/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yegorferrieres/ccd-ai/discussions)
- **Email**: yegor@martlive.ai
## Related Projects
- [CCD Methodology](https://github.com/yegorferrieres/ccd-ai) - Core CCD methodology
- [CCD Website](https://github.com/yegorferrieres/ccd-ai) - Documentation website
- [CCD Examples](https://github.com/yegorferrieres/ccd-ai/tree/main/docs/examples) - Implementation examples
Raw data
{
"_id": null,
"home_page": null,
"name": "ccd-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Yegor Ferrieres aka Egor Borodavko <yegor@martlive.ai>",
"keywords": "ccd, documentation, context, rag, software-development, ai-context, code-integration",
"author": null,
"author_email": "Yegor Ferrieres aka Egor Borodavko <yegor@martlive.ai>",
"download_url": "https://files.pythonhosted.org/packages/b5/98/f239334140f6f2d2dae0e803ce5d27c7dd2898c268188b17ae241af46c4f/ccd_cli-0.1.0.tar.gz",
"platform": null,
"description": "# CCD for AI CLI\n\nA Python-based command-line interface for CCD for AI (Continuous Context Documentation for AI) methodology.\n\n## Features\n\n- **Project Initialization**: Set up new CCD projects with proper structure\n- **Context Generation**: Automatically generate context cards, module indexes, and CODEMAP\n- **AI-CONTEXT Integration**: Add and manage context comments in source code files\n- **Validation**: Validate CCD documentation against JSON schemas\n- **Health Monitoring**: Check project health and coverage metrics\n- **Automation**: CI/CD integration and automated context updates\n- **Rich Output**: Beautiful terminal output with colors and formatting\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install ccd-cli\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/yegorferrieres/ccd-ai.git\ncd ccd-ai/tools/ccd-cli\npip install -e .\n```\n\n## Publishing to PyPI\n\n### Building the Package\n\n```bash\n# Install build tools\npip install build twine\n\n# Build the package\npython -m build\n\n# This creates dist/ directory with wheel and source distribution\n```\n\n### Publishing to TestPyPI\n\n```bash\n# Upload to TestPyPI first\ntwine upload --repository testpypi dist/*\n\n# Test installation from TestPyPI\npip install --index-url https://test.pypi.org/simple/ ccd-cli\n```\n\n### Publishing to PyPI\n\n```bash\n# Upload to PyPI\ntwine upload dist/*\n\n# Verify installation\npip install ccd-cli\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/yegorferrieres/ccd-ai.git\ncd ccd-ai/tools/ccd-cli\npip install -e \".[dev]\"\n```\n\n### Verify Installation\n\n```bash\nccd --help\n```\n\n## Quick Start\n\n### 1. Install CCD for AI CLI\n\n```bash\ngit clone https://github.com/yegorferrieres/ccd-ai.git\ncd ccd-ai/tools/ccd-cli\npip install -e .\n```\n\n### 2. Initialize a New CCD for AI Project\n\n```bash\nccd init --project-name \"My Project\" --domain \"web-application\"\n```\n\n### 3. Prepare Context for AI\n\n```bash\n# Generate complete project context for AI developer\nccd prepare-context\n\n# Generate to specific file\nccd prepare-context --output my-task-context.txt\n```\n\n### Generate Context Cards\n\n```bash\nccd generate-cards --files \"src/**/*.py\" --output docs/context-cards/\n```\n\n### Validate Context\n\n```bash\nccd validate-contexts --contexts docs/ --schemas docs/schemas/\n```\n\n### Check Health\n\n```bash\nccd health --detailed\n```\n\n### Work with AI-CONTEXT Comments\n\n```bash\n# Add context comments to source files\nccd add-context-comments --file \"src/main.go\" --context \"docs/contexts/files/src/main.go.ctx.md\"\n\n# Extract existing context comments\nccd extract-context --file \"src/main.go\"\n\n# Validate comment format\nccd validate-context-comments --file \"src/main.go\"\n\n# Update context comments\nccd update-context-comments --file \"src/main.go\" --context \"docs/contexts/files/src/main.go.ctx.md\"\n\n# Check context freshness\nccd context-freshness --file \"src/main.go\"\n```\n\n## Commands\n\n### `ccd init`\n\nInitialize a new CCD for AI project.\n\n```bash\nccd init --project-name \"Project Name\" --domain \"web-application\" --output-dir \"./my-project\"\n```\n\n**Options:**\n- `--project-name, -n`: Project name (required)\n- `--domain, -d`: Project domain (required)\n- `--yes, -y`: Skip prompts and use defaults\n- `--output-dir, -o`: Output directory (default: current directory)\n\n**Supported Domains:**\n- `web-application`\n- `mobile-app`\n- `api-service`\n- `library`\n- `cli-tool`\n- `data-pipeline`\n- `ml-ai`\n- `infrastructure`\n- `other`\n\n### `ccd add-context-comments`\n\nAdd AI-CONTEXT comments to source code files.\n\n```bash\nccd add-context-comments --file \"src/main.go\" --context \"docs/contexts/files/src/main.go.ctx.md\"\n```\n\n**Options:**\n- `--file, -f`: Source file path (required)\n- `--context, -c`: Context card file path (required)\n- `--force, -F`: Overwrite existing comments\n- `--dry-run`: Show what would be added without making changes\n\n### `ccd extract-context`\n\nExtract AI-CONTEXT comments from source code files.\n\n```bash\nccd extract-context --file \"src/main.go\"\nccd extract-context --files \"src/**/*.go\"\nccd extract-context --project .\n```\n\n**Options:**\n- `--file, -f`: Single file path\n- `--files, -F`: Glob pattern for multiple files\n- `--project, -p`: Extract from entire project\n- `--output, -o`: Output file for extracted comments\n\n### `ccd validate-context-comments`\n\nValidate AI-CONTEXT comment format and content.\n\n```bash\nccd validate-context-comments --file \"src/main.go\"\nccd validate-context-comments --files \"src/**/*.go\"\nccd validate-context-comments --project .\n```\n\n**Options:**\n- `--file, -f`: Single file path\n- `--files, -F`: Glob pattern for multiple files\n- `--project, -p`: Validate entire project\n- `--strict`: Fail on any validation errors\n- `--report`: Generate detailed validation report\n\n### `ccd update-context-comments`\n\nUpdate AI-CONTEXT comments with new information.\n\n```bash\nccd update-context-comments --file \"src/main.go\" --context \"docs/contexts/files/src/main.go.ctx.md\"\nccd update-context-comments --project . --refresh-timestamps\n```\n\n**Options:**\n- `--file, -f`: Source file path\n- `--context, -c`: Context card file path\n- `--project, -p`: Update entire project\n- `--refresh-timestamps`: Update all timestamps\n- `--dry-run`: Show what would be updated\n\n### `ccd context-freshness`\n\nCheck context freshness and health across the project.\n\n```bash\nccd context-freshness --file \"src/main.go\"\nccd context-freshness --project .\nccd context-freshness --project . --report --output freshness-report.json\n```\n\n**Options:**\n- `--file, -f`: Single file path\n- `--project, -p`: Check entire project\n- `--report`: Generate detailed report\n- `--output, -o`: Output file for report\n- `--threshold`: Set freshness threshold (default: 24h)\n\n### `ccd context-health`\n\nCheck context health across the project.\n\n```bash\nccd context-health --file \"src/main.go\"\nccd context-health --project . --detailed\n```\n\n**Options:**\n- `--file, -f`: Single file path\n- `--project, -p`: Check entire project\n- `--detailed`: Show detailed health information\n\n### `ccd drift-detection`\n\nDetect context drift in the project.\n\n```bash\nccd drift-detection --project .\nccd drift-detection --project . --output drift-report.json\n```\n\n**Options:**\n- `--project, -p`: Check entire project\n- `--output, -o`: Output file for drift report\n\n### `ccd quality-gates`\n\nRun all quality gates for the project.\n\n```bash\nccd quality-gates --project .\nccd quality-gates --project . --output quality-report.json\n```\n\n**Options:**\n- `--project, -p`: Check entire project\n- `--output, -o`: Output file for quality report\n\n### `ccd update-engineering-log`\n\nUpdate ENGINEERING_LOG.md with a new entry.\n\n```bash\nccd update-engineering-log --description \"Implemented new feature\" --impact \"Medium\"\n```\n\n**Options:**\n- `--log-file, -l`: Path to ENGINEERING_LOG.md file (default: ./docs/ENGINEERING_LOG.md)\n- `--description, -d`: Description of the development task (required)\n- `--impact, -i`: Impact scope (High/Medium/Low, default: Medium)\n- `--severity, -s`: Severity (High/Medium/Low, default: Medium)\n- `--technical-changes, -t`: Description of technical changes made\n- `--resolution, -r`: How the task was resolved\n- `--lessons-learned`: Key insights gained from the task\n- `--follow-up`: Next steps or follow-up actions\n\n### `ccd update-roadmap`\n\nUpdate roadmap.md to mark milestones as completed or in progress.\n\n```bash\nccd update-roadmap --milestone \"API integration\" --status \"completed\"\n```\n\n**Options:**\n- `--roadmap-file, -r`: Path to roadmap.md file (default: ./docs/roadmap.md)\n- `--milestone, -m`: Milestone to update (required)\n- `--status, -s`: New status (completed/in_progress, default: completed)\n- `--notes, -n`: Additional notes about the milestone\n\n### `ccd create-adr`\n\nCreate a new Architecture Decision Record (ADR).\n\n```bash\nccd create-adr --title \"Database Schema Changes\" --status \"Proposed\"\n```\n\n**Options:**\n- `--decisions-dir, -d`: Path to decisions directory (default: ./docs/decisions)\n- `--title, -t`: Title of the ADR (required)\n- `--status, -s`: Status (Proposed/Accepted/Deprecated/Superseded, default: Proposed)\n- `--context, -c`: Context and forces at play\n- `--decision`: The decision made\n- `--consequences`: Consequences of the decision\n\n### `ccd update-development-rules`\n\nUpdate DEVELOPMENT_RULES.md with new workflow patterns.\n\n```bash\nccd update-development-rules --new-rule \"Feature Flag Pattern\" --context \"When implementing feature flags\"\n```\n\n**Options:**\n- `--rules-file, -r`: Path to DEVELOPMENT_RULES.md file (default: ./docs/DEVELOPMENT_RULES.md)\n- `--new-rule, -n`: Name of the new workflow pattern (required)\n\n### `ccd prepare-context`\n\nPrepare complete project context for AI developer.\n\n```bash\nccd prepare-context\nccd prepare-context --output my-task-context.txt\nccd prepare-context --no-architecture\nccd prepare-context --dry-run\n```\n\n**Options:**\n- `--project-dir, -p`: Project directory to analyze (default: current directory)\n- `--output, -o`: Output file for context (default: task-context-YYYYMMDD-HHMMSS.txt)\n- `--no-architecture`: Skip architecture decisions and codemap\n- `--dry-run`: Show what would be generated without creating file\n\n### `ccd methodology-status`\n\nShow status of all methodological files in the project.\n\n```bash\nccd methodology-status --project-dir .\n```\n\n**Options:**\n- `--project-dir, -p`: Project directory to analyze (default: current directory)\n\n### `ccd validate`\n\nValidate CCD schemas and contexts.\n\n```bash\nccd validate-schemas --schemas ./docs/schemas\nccd validate-contexts --contexts ./docs --schemas ./docs/schemas\n```\n\n**Options:**\n- `--schemas, -s`: Path to schemas directory\n- `--contexts, -c`: Path to contexts directory\n- `--output-format, -f`: Output format (text, json, yaml)\n- `--detailed, -d`: Show detailed validation results\n\n### `ccd generate`\n\nGenerate CCD documentation files.\n\n```bash\nccd generate-cards --files \"src/**/*.py\" --output docs/context-cards/\nccd generate-index --modules \"services/*\" --output docs/modules/\nccd update-codemap --output docs/CODEMAP.yaml\n```\n\n**Options:**\n- `--files, -f`: File pattern to process\n- `--output, -o`: Output directory\n- `--type, -t`: What to generate (cards, index, codemap)\n- `--force`: Overwrite existing files\n\n### `ccd health`\n\nCheck CCD project health.\n\n```bash\nccd health --detailed --output-format json\n```\n\n**Options:**\n- `--detailed, -d`: Show detailed health information\n- `--output-format, -f`: Output format (text, json, yaml)\n\n### `ccd coverage`\n\nShow CCD coverage statistics.\n\n```bash\nccd coverage --modules --files --min-coverage 80\n```\n\n**Options:**\n- `--modules, -m`: Show module coverage\n- `--files, -f`: Show file coverage\n- `--min-coverage`: Minimum coverage percentage\n- `--output-format, -o`: Output format (text, json, yaml)\n\n### `ccd freshness`\n\nCheck CCD documentation freshness.\n\n```bash\nccd freshness --days 30 --output-format yaml\n```\n\n**Options:**\n- `--days, -d`: Number of days to check\n- `--output-format, -o`: Output format (text, json, yaml)\n\n### `ccd pack`\n\nPackage CCD contexts into archive.\n\n```bash\nccd pack --output ./ccd-contexts.zip --include-schemas --include-templates\n```\n\n**Options:**\n- `--output, -o`: Output archive path\n- `--include-schemas`: Include JSON schemas\n- `--include-templates`: Include templates\n\n### `ccd monitor`\n\nMonitor CCD project status.\n\n```bash\nccd monitor --watch --interval 60\n```\n\n**Options:**\n- `--watch, -w`: Watch for file changes\n- `--interval, -i`: Check interval in seconds\n- `--output-format, -o`: Output format (text, json, yaml)\n\n### `ccd version`\n\nShow CCD CLI version.\n\n```bash\nccd version\n```\n\n## Configuration\n\n### Environment Variables\n\n- `CCD_CONFIG_PATH`: Path to configuration file\n- `CCD_VERBOSE`: Enable verbose output\n- `CCD_QUIET`: Suppress output\n\n### Configuration File\n\nCreate a `ccd.config.yaml` file in your project root:\n\n```yaml\n# CCD Configuration\nproject:\n name: \"My Project\"\n domain: \"web-application\"\n schemas_path: \"./docs/schemas\"\n contexts_path: \"./docs\"\n\ngeneration:\n auto_update: true\n include_tests: false\n include_docs: true\n\nvalidation:\n strict_mode: true\n fail_fast: false\n\noutput:\n default_format: \"text\"\n colors: true\n progress_bars: true\n```\n\n## Examples\n\n### Complete Workflow\n\n```bash\n# 1. Initialize project\nccd init --project-name \"My API Service\" --domain \"api-service\"\n\n# 2. Generate context cards for all Python files\nccd generate-cards --files \"src/**/*.py\" --output docs/context-cards/\n\n# 3. Generate module indexes\nccd generate-index --modules \"src/*\" --output docs/modules/\n\n# 4. Update CODEMAP\nccd update-codemap --output docs/CODEMAP.yaml\n\n# 5. Validate everything\nccd validate-contexts --contexts docs/ --schemas docs/schemas/\n\n# 6. Check health\nccd health --detailed\n\n# 7. Package for distribution\nccd pack --output ./ccd-contexts.zip --include-schemas\n```\n\n### AI-CONTEXT Integration\n\n```bash\n# Add AI-CONTEXT comments to source files\nccd add-context-comments --file src/main.py --context docs/contexts/files/src/main.py.ctx.md\n\n# Extract and validate AI-CONTEXT comments\nccd extract-context --file src/main.py\nccd validate-context-comments --file src/main.py --report\n\n# Check context freshness and health\nccd context-freshness --project . --threshold 48\nccd context-health --project . --detailed\n```\n\n### Methodology Loop Management\n\n```bash\n# Update engineering log after completing a task\nccd update-engineering-log \\\n --description \"Implemented user authentication\" \\\n --impact \"High\" \\\n --technical-changes \"Added JWT middleware and user model\" \\\n --resolution \"Successfully deployed to staging\"\n\n# Mark roadmap milestone as completed\nccd update-roadmap --milestone \"User Authentication\" --status \"completed\"\n\n# Create ADR for architectural decision\nccd create-adr \\\n --title \"JWT vs Session-based Authentication\" \\\n --status \"Accepted\" \\\n --decision \"We will use JWT for stateless authentication\"\n\n# Check overall methodology status\nccd methodology-status --project-dir .\n```\n\n### Quality Assurance\n\n```bash\n# Run all quality gates\nccd quality-gates --project . --output quality-report.json\n\n# Detect context drift\nccd drift-detection --project . --output drift-report.json\n\n# Monitor specific quality metrics\nccd context-freshness --project . --threshold 24\nccd context-health --project . --detailed\n```\n\n### CI/CD Integration\n\n```yaml\n# .github/workflows/ccd-validation.yml\nname: CCD Validation\n\non:\n push:\n branches: [ main, develop ]\n pull_request:\n branches: [ main ]\n\njobs:\n validate-ccd:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n \n - name: Set up Python\n uses: actions/setup-python@v4\n with:\n python-version: '3.11'\n \n - name: Install CCD CLI\n run: |\n git clone https://github.com/yegorferrieres/ccd-ai.git\n cd ccd-ai/tools/ccd-cli\n pip install -e .\n \n - name: Validate CCD Contexts\n run: ccd validate-contexts --contexts docs/ --schemas docs/schemas/\n \n - name: Check Health\n run: ccd health --output-format json > health-report.json\n \n - name: Upload Health Report\n uses: actions/upload-artifact@v3\n with:\n name: ccd-health-report\n path: health-report.json\n```\n\n### Automated Monitoring\n\n```bash\n# Watch for changes and auto-update\nccd monitor --watch --interval 30\n\n# Check freshness every day\nccd freshness --days 1 --output-format json > freshness-report.json\n\n# Generate coverage report\nccd coverage --modules --files --min-coverage 90 --output-format yaml > coverage-report.yaml\n```\n\n## Output Formats\n\n### Text (Default)\n\nHuman-readable output with colors and formatting.\n\n### JSON\n\nMachine-readable output for automation and integration.\n\n```json\n{\n \"status\": \"success\",\n \"data\": {\n \"coverage_percentage\": 85.5,\n \"total_modules\": 12,\n \"total_files\": 156,\n \"health_score\": 78.2\n }\n}\n```\n\n### YAML\n\nHuman-readable structured output.\n\n```yaml\nstatus: success\ndata:\n coverage_percentage: 85.5\n total_modules: 12\n total_files: 156\n health_score: 78.2\n```\n\n## Error Handling\n\nThe CLI provides clear error messages and exit codes:\n\n- `0`: Success\n- `1`: General error\n- `130`: User interruption (Ctrl+C)\n\n## Troubleshooting\n\n### Common Issues\n\n**Import Errors**\n```bash\n# Ensure you're using the right Python environment\npython -m pip install --upgrade ccd-cli\n```\n\n**Permission Errors**\n```bash\n# Use user installation\npip install --user ccd-cli\n```\n\n**Schema Validation Failures**\n```bash\n# Check schema files exist and are valid JSON\nccd validate-schemas --schemas ./docs/schemas --verbose\n```\n\n### Debug Mode\n\nEnable verbose output for debugging:\n\n```bash\nccd --verbose health --detailed\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/yegorferrieres/ccd-ai.git\ncd ccd-ai\npip install -e \"tools/ccd-cli/.[dev]\"\n```\n\n### Run Tests\n\n```bash\npytest\npytest --cov=ccd_cli --cov-report=html\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack ccd_cli/\n\n# Sort imports\nisort ccd_cli/\n\n# Lint code\nflake8 ccd_cli/\n\n# Type checking\nmypy ccd_cli/\n```\n\n### Pre-commit Hooks\n\n```bash\npre-commit install\npre-commit run --all-files\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [https://github.com/yegorferrieres/ccd-ai](https://github.com/yegorferrieres/ccd-ai)\n- **Issues**: [GitHub Issues](https://github.com/yegorferrieres/ccd-ai/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yegorferrieres/ccd-ai/discussions)\n- **Email**: yegor@martlive.ai\n\n## Related Projects\n\n- [CCD Methodology](https://github.com/yegorferrieres/ccd-ai) - Core CCD methodology\n- [CCD Website](https://github.com/yegorferrieres/ccd-ai) - Documentation website\n- [CCD Examples](https://github.com/yegorferrieres/ccd-ai/tree/main/docs/examples) - Implementation examples\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI tools for Continuous Context Documentation (CCD)",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/yegorferrieres/ccd-ai/issues",
"Documentation": "https://github.com/yegorferrieres/ccd-ai/tree/main/docs",
"Homepage": "https://github.com/yegorferrieres/ccd-ai",
"Repository": "https://github.com/yegorferrieres/ccd-ai"
},
"split_keywords": [
"ccd",
" documentation",
" context",
" rag",
" software-development",
" ai-context",
" code-integration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "84cb8fea24a7a805232465a6a9553925a65e9b3b437fdc030702f6a64689d56c",
"md5": "53f6a249fa3237b0a7dc5d99f04335b5",
"sha256": "17fa44f0fefcc046e701beb2941022026a22bac90a1716356feb17bee118bb4f"
},
"downloads": -1,
"filename": "ccd_cli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53f6a249fa3237b0a7dc5d99f04335b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 59795,
"upload_time": "2025-08-29T18:32:52",
"upload_time_iso_8601": "2025-08-29T18:32:52.650633Z",
"url": "https://files.pythonhosted.org/packages/84/cb/8fea24a7a805232465a6a9553925a65e9b3b437fdc030702f6a64689d56c/ccd_cli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b598f239334140f6f2d2dae0e803ce5d27c7dd2898c268188b17ae241af46c4f",
"md5": "ac415a30715cf516138ffef595c3c34b",
"sha256": "8523cb8dd37f7929c63aac8458845f4a269dd49569636aac1f5a7d12765c182f"
},
"downloads": -1,
"filename": "ccd_cli-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ac415a30715cf516138ffef595c3c34b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 55394,
"upload_time": "2025-08-29T18:32:54",
"upload_time_iso_8601": "2025-08-29T18:32:54.229825Z",
"url": "https://files.pythonhosted.org/packages/b5/98/f239334140f6f2d2dae0e803ce5d27c7dd2898c268188b17ae241af46c4f/ccd_cli-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 18:32:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yegorferrieres",
"github_project": "ccd-ai",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ccd-cli"
}
JSON
