markitect-main/CONFIG.md

TDDAi Configuration Management

The tddai framework uses a flexible, hierarchical configuration system designed for project-agnostic deployment while supporting per-project customization.

Configuration Hierarchy

Configuration values are loaded in the following priority order (highest to lowest):

1. Environment Variables - Runtime overrides (highest priority)
2. .env.tddai File - Project-specific configuration (auto-loaded)
3. Default Values - Framework defaults (fallback)

Quick Start

Automatic Configuration (Recommended)

The framework automatically loads .env.tddai from the current directory:

# Configuration loaded automatically
make tdd-status
make tdd-start NUM=5

Manual Configuration

You can also source the setup script manually:

source tddai-setup.sh
make tdd-status

Configuration Options

Repository Settings (Required)

Variable	Description	Example	Required
TDDAI_GITEA_URL	Git platform URL	https://github.com	✅
TDDAI_REPO_OWNER	Repository owner/org	myusername	✅
TDDAI_REPO_NAME	Repository name	myproject	✅

Workspace Settings (Optional)

Variable	Description	Default	Example
TDDAI_WORKSPACE_DIR	TDD workspace directory	.tddai_workspace	.myproject_workspace

Test Settings (Framework Defaults)

Setting	Value	Description
tests_dir	tests/	Main test directory
test_file_pattern	test_issue_{issue_num}_{scenario}.py	Test file naming pattern
current_issue_file	current_issue.json	Active issue metadata file

Configuration Files

.env.tddai Format

# TDDAi configuration for YourProject
# Repository settings
TDDAI_GITEA_URL=https://your-git-platform.com
TDDAI_REPO_OWNER=yourusername
TDDAI_REPO_NAME=yourproject

# Workspace settings (optional)
TDDAI_WORKSPACE_DIR=.yourproject_workspace

tddai-setup.sh Format

#!/bin/bash
# TDDAi environment setup script

export TDDAI_GITEA_URL=https://your-git-platform.com
export TDDAI_REPO_OWNER=yourusername
export TDDAI_REPO_NAME=yourproject
export TDDAI_WORKSPACE_DIR=.yourproject_workspace

echo "✅ TDDAi configured for YourProject"

Platform Examples

GitHub Configuration

TDDAI_GITEA_URL=https://github.com
TDDAI_REPO_OWNER=yourusername
TDDAI_REPO_NAME=yourrepo

GitLab Configuration

TDDAI_GITEA_URL=https://gitlab.com
TDDAI_REPO_OWNER=yourusername
TDDAI_REPO_NAME=yourrepo

Self-hosted Gitea

TDDAI_GITEA_URL=https://git.yourcompany.com
TDDAI_REPO_OWNER=yourorganization
TDDAI_REPO_NAME=yourproject

API Integration

The configuration automatically constructs API URLs:

# Constructed from configuration
issues_api_url = f"{TDDAI_GITEA_URL}/api/v1/repos/{TDDAI_REPO_OWNER}/{TDDAI_REPO_NAME}/issues"

Workspace Structure

Default workspace layout (configurable via TDDAI_WORKSPACE_DIR):

.tddai_workspace/
├── current_issue.json          # Active issue metadata
└── issue_X/                   # Issue-specific workspace
    ├── tests/                 # Test files for this issue
    │   └── test_issue_X_*.py  # Generated test files
    ├── requirements.md        # Issue requirements analysis
    └── test_plan.md          # Test planning document

Environment Variable Overrides

You can override any configuration at runtime:

# Override workspace directory for this session
TDDAI_WORKSPACE_DIR=.custom_workspace make tdd-start NUM=5

# Override repository for testing
TDDAI_REPO_NAME=test_repo make tdd-status

Validation

The framework validates configuration on startup:

• Required fields must be non-empty (gitea_url, repo_owner, repo_name)
• URLs should include protocol (http:// or https://)
• Workspace directories are created automatically if they don't exist

Troubleshooting

Common Errors

gitea_url cannot be empty

• Solution: Create .env.tddai with TDDAI_GITEA_URL=your-url
• Alternative: Run source tddai-setup.sh before tddai commands

repo_owner cannot be empty

• Solution: Set TDDAI_REPO_OWNER in .env.tddai or environment

repo_name cannot be empty

• Solution: Set TDDAI_REPO_NAME in .env.tddai or environment

Debug Configuration

# Check current configuration
python -c "from tddai.config import get_config; c=get_config(); print(f'URL: {c.gitea_url}\\nOwner: {c.repo_owner}\\nRepo: {c.repo_name}\\nWorkspace: {c.workspace_dir}')"

Migration from Other Projects

When adapting tddai for a new project:

1. Copy configuration template:

   cp .env.tddai.example .env.tddai
   

2. Update repository settings:

   # Edit .env.tddai
   TDDAI_GITEA_URL=https://your-platform.com
   TDDAI_REPO_OWNER=your-username
   TDDAI_REPO_NAME=your-project
   

3. Test configuration:

   make tdd-status
   

Best Practices

• Use .env.tddai for project-specific settings
• Use environment variables for temporary overrides
• Keep configuration in version control (but exclude sensitive tokens)
• Document custom workspace naming in project README
• Validate configuration before starting development sessions

---

This configuration system supports the TDD8 methodology (ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH) across any software development project with issue tracking.