# AIDD-O - AI Development Driver: OpenCode

A shell script that orchestrates autonomous development sessions using OpenCode AI. AIDD-O supports both bash (aidd-o.sh) and PowerShell (aidd-o.ps1) environments.

## Specifications

AIDD-O uses project specifications in Markdown format aligned with Spernakit template standards. All specs are located in the `specs/` directory with `.md` extensions.

## Usage

### Bash/Linux/macOS
```bash
./aidd-o.sh --project-dir <dir> [--spec <file>] [--max-iterations <num>] [--timeout <seconds>] [--idle-timeout <seconds>] [--model <model>] [--init-model <model>] [--code-model <model>] [--no-clean] [--quit-on-abort <num>]
```

### PowerShell/Windows
```powershell
./aidd-o.ps1 -ProjectDir <dir> [-Spec <file>] [-MaxIterations <num>] [-Timeout <seconds>] [-IdleTimeout <seconds>] [-Model <model>] [-InitModel <model>] [-CodeModel <model>] [-NoClean] [-QuitOnAbort <num>] [-Help]
```

### Required Arguments
- `--project-dir` / `-ProjectDir`: Target project directory

### Optional Arguments
- `--spec` / `-Spec`: Specification file (.md) to copy to project-dir/.aidd/spec.txt
  - Required for new projects or empty directories
  - Optional for existing codebases (will be generated by onboarding prompt)
- `--max-iterations` / `-MaxIterations`: Number of iterations to run (unlimited if not specified)
- `--timeout` / `-Timeout`: Timeout in seconds for each opencode session (default: 600)
- `--idle-timeout` / `-IdleTimeout`: Abort if opencode produces no output for N seconds (default: 180)
- `--model` / `-Model`: Model to use (optional)
- `--init-model` / `-InitModel`: Model to use for initializer/onboarding prompts (overrides `--model`)
- `--code-model` / `-CodeModel`: Model to use for coding prompt (overrides `--model`)
- `--no-clean` / `-NoClean`: Skip log cleaning on exit
- `--quit-on-abort` / `-QuitOnAbort`: Quit after N consecutive failed iterations (default: 0 = continue indefinitely)
- `-h` / `--help` / `-Help`: Show help message

## Workflows

### New Project Workflow
For empty or non-existent directories:
1. Creates project directory if it doesn't exist
2. Copies scaffolding files from `scaffolding/` directory
3. Copies artifacts into `project-dir/.aidd/`
4. Copies spec file to `.aidd/spec.txt` (only if `--spec` is provided)
5. Uses `initializer.md` prompt to set up initial project structure
6. Creates `feature_list.json` based on the provided spec

### Existing Codebase Workflow
For directories containing code but no `.aidd/` files:
1. Skips copying scaffolding files
2. Does NOT copy spec file
3. Uses `onboarding.md` prompt to:
   - Analyze existing codebase
   - Generate `spec.txt` based on discovered functionality
   - Create `feature_list.json` with existing features marked as complete
   - Document project structure and technical debt

If `.aidd/feature_list.json` exists but still appears to be a template (placeholders like `{yyyy-mm-dd}`), onboarding is treated as incomplete and the onboarding prompt is used again.

### Subsequent Iterations
Once `.aidd/spec.txt` and `.aidd/feature_list.json` exist:
- Uses `coding.md` prompt for continued development
- Implements remaining features from the feature list

## How It Works

The script runs in a loop based on max-iterations:

1. Detects if the target directory is an existing codebase
2. Checks if both `project-dir/.aidd/spec.txt` AND `project-dir/.aidd/feature_list.json` exist
3. Creates a per-iteration transcript log at `project-dir/.aidd/iterations/001.log`, `002.log`, ...
   - The log index is chosen as the next number after the highest existing numeric `*.log` in that directory
   - Logs are not overwritten across re-runs
4. If either is missing:
   - Creates `.aidd` directory if needed
   - For new projects: copies spec file and uses initializer prompt
   - For existing codebases: uses onboarding prompt without copying spec
5. If both exist:
   - Sends coding prompt to opencode

If an iteration fails repeatedly, the run can stop early when `--quit-on-abort` / `-QuitOnAbort` reaches its threshold.

## Iteration Transcripts

Each iteration writes a transcript file under:

- `project-dir/.aidd/iterations/001.log`
- `project-dir/.aidd/iterations/002.log`
- ...

The transcript captures the console output for that iteration (including `opencode` output).

## Examples

### New Project Example
```bash
./aidd-o.sh --project-dir ../new-project --spec ./specs/todolist.md --max-iterations 5
```

### Existing Codebase Example
```bash
./aidd-o.sh --project-dir ../existing-app --max-iterations 10
```

### PowerShell Examples
```powershell
# New project
./aidd-o.ps1 -ProjectDir "../new-project" -Spec "./specs/todolist.md" -MaxIterations 5

# Existing codebase
./aidd-o.ps1 -ProjectDir "../existing-app" -MaxIterations 10
```

## Prompts Used

- **Initializer prompt** (new projects): `cat ./prompts/initializer.md | opencode run --model <model> --timeout <timeout>`
- **Onboarding prompt** (existing codebases): `cat ./prompts/onboarding.md | opencode run --model <model> --timeout <timeout>`
- **Coding prompt** (subsequent iterations): `cat ./prompts/coding.md | opencode run --model <model> --timeout <timeout>`

All prompts are executed from within the project directory to ensure proper context.

## Feature Detection

aidd-o automatically detects existing codebases by checking for files and directories (excluding common ignored items like `.git`, `.aidd`, `.DS_Store`, `node_modules`, `.vscode`, `.idea`). This enables the appropriate workflow for both new and existing projects.