AIDD-K - AI Development Driver: KiloCode

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

Inspired by Anthropic's Claude Quickstarts (https://github.com/anthropics/claude-quickstarts) - Autonomous Coding Agent Demo (https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding)

And an improved version (https://github.com/NomadicDaddy/autonomous_agent_demo).

Specifications

AIDD-K uses project specifications in xml-like format. All specs are located in the specs/ directory with .txt extensions.

Usage

Bash/Linux/macOS

./aidd-k.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

./aidd-k.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 kilocode session (default: 600)
• --idle-timeout / -IdleTimeout: Abort an iteration if kilocode 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 kilocode

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 kilocode output).

Examples

New Project Example

./aidd-k.sh --project-dir ../new-project --spec ./specs/todolist.md --max-iterations 5

Existing Codebase Example

./aidd-k.sh --project-dir ../existing-app --max-iterations 10

PowerShell Examples

# New project
./aidd-k.ps1 -ProjectDir "../new-project" -Spec "./specs/todolist.md" -MaxIterations 5

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

Prompts Used

• Initializer prompt (new projects): cat ./prompts/initializer.md | kilocode --mode code --auto --timeout <timeout>
• Onboarding prompt (existing codebases): cat ./prompts/onboarding.md | kilocode --mode code --auto --timeout <timeout>
• Coding prompt (subsequent iterations): cat ./prompts/coding.md | kilocode --mode code --auto --timeout <timeout>

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

Feature Detection

AIDD-K 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.