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:

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

### Manual Configuration
You can also source the setup script manually:

```bash
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
```bash
# 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
```bash
#!/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
```bash
TDDAI_GITEA_URL=https://github.com
TDDAI_REPO_OWNER=yourusername
TDDAI_REPO_NAME=yourrepo
```

### GitLab Configuration
```bash
TDDAI_GITEA_URL=https://gitlab.com
TDDAI_REPO_OWNER=yourusername
TDDAI_REPO_NAME=yourrepo
```

### Self-hosted Gitea
```bash
TDDAI_GITEA_URL=https://git.yourcompany.com
TDDAI_REPO_OWNER=yourorganization
TDDAI_REPO_NAME=yourproject
```

## API Integration

The configuration automatically constructs API URLs:

```python
# 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:

```bash
# 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
```bash
# 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**:
   ```bash
   cp .env.tddai.example .env.tddai
   ```

2. **Update repository settings**:
   ```bash
   # Edit .env.tddai
   TDDAI_GITEA_URL=https://your-platform.com
   TDDAI_REPO_OWNER=your-username
   TDDAI_REPO_NAME=your-project
   ```

3. **Test configuration**:
   ```bash
   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.*