Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
130 lines (99 loc) · 4.61 KB

CONTRIBUTING.md

File metadata and controls

130 lines (99 loc) · 4.61 KB

Contributing to AIDD

Thank you for your interest in contributing to AIDD (AI Development Driver)! This document provides guidelines for contributing to the project.

Code of Conduct

This project follows a simple code of conduct: be respectful, constructive, and collaborative. We welcome contributions from everyone.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue with:

  • A clear, descriptive title
  • Steps to reproduce the bug
  • Expected vs actual behavior
  • Your environment (OS, Bash version, CLI being used)
  • Relevant log files from .aidd/iterations/

Suggesting Enhancements

Enhancement suggestions are welcome! Please open an issue with:

  • A clear description of the enhancement
  • Why it would be useful
  • Example use cases
  • Any implementation ideas you have

Pull Requests

  1. Fork the repository and create your branch from main
  2. Make your changes following the coding style of the project
  3. Test your changes thoroughly:
    • Test with each supported CLI (OpenCode, KiloCode, Claude Code, Codex, ZRun) if your change touches CLI integration
    • Test new project initialization
    • Test existing codebase onboarding
    • Test iteration workflows
  4. Update documentation if needed (README.md, prompts/, etc.)
  5. Commit your changes using Conventional Commits format (e.g., feat(cli): add idle detection, fix(prompts): correct commit template)
  6. Push to your fork and submit a pull request

Pull Request Guidelines

  • Keep PRs focused on a single feature or fix
  • Include a clear description of what the PR does
  • Reference any related issues
  • Update relevant documentation
  • Follow existing code style and conventions

Development Setup

# Clone your fork
git clone https://github.com/your-username/aidd.git
cd aidd

# Make the script executable
chmod +x aidd.sh

# Test with a sample project
./aidd.sh --project-dir /path/to/test/project --spec specs/example.md

Project Structure

  • aidd.sh - Main entry point
  • lib/ - Core library modules
    • config.sh - Configuration constants
    • utils.sh - Utility functions
    • args.sh - Argument parsing
    • cli-factory.sh - CLI abstraction layer
    • cli-{opencode,kilocode,claude-code,codex,zrun}.sh - Per-CLI implementations
    • json-parser.sh / codex-json-parser.sh - Stream parsers for Claude Code / Codex
    • log-cleaner.sh / log-extractor.sh - Iteration log handling
    • project.sh - Project management
    • iteration.sh - Iteration handling
  • prompts/ - Prompt templates for AI agents
    • _common/ - Shared prompt modules
    • _cli/ - Per-CLI prompt variants (one per supported CLI)
    • roles/ - Role-specific prompts (coder, refiner, reviewer_auditor, squad_leader, fire_team_leader)
    • onboarding.md - Existing codebase prompt
    • initializer.md - New project prompt
    • coding.md - Development iterations prompt
    • coordinator.md - Fleet-level multi-project coordinator prompt
    • todo.md - TODO mode prompt
    • validate.md - Feature validation prompt
    • in-progress.md - In-progress feature prompt
  • audits/ - Audit definition files (runnable + reference)
  • benchmarks/ - Benchmark harness manifest, fixtures, schemas, results
  • tools/ - Build/rebuild automation and benchmark runner
  • zrun/ - Bun + TypeScript ZRun agent (Zhipu AI / Ollama)
  • scaffolding/ - Template files for new projects
  • templates/ - Project metadata templates
  • specs/ - Example specification files
  • docs/ - Reference documentation

Coding Style

  • Use 4-space indentation in shell scripts
  • Follow Google Shell Style Guide where applicable
  • Add comments for complex logic
  • Use descriptive variable names
  • Prefer [[ ]] over [ ] for conditionals
  • Use local for function-scoped variables
  • Quote all variables to prevent word splitting

Testing

Before submitting a PR, test your changes with:

  • A new empty project
  • An existing codebase
  • All five supported CLIs — OpenCode, KiloCode, Claude Code, Codex, ZRun — if modifying CLI-related code
  • Edge cases (missing files, invalid arguments, etc.)

Documentation

  • Update README.md if adding new features
  • Update prompt files if changing agent behavior
  • Add comments to shell scripts for complex logic
  • Update CHANGELOG.md (Keep a Changelog format) for any user-visible change

Questions?

Feel free to open an issue with your question or reach out to the maintainers.

License

By contributing to AIDD, you agree that your contributions will be licensed under the MIT License.