AIDD

A reviewable, document-first workflow around the AI coding runtimes you already use.

AIDD (ai_driven_dev_v2) is an open-source orchestration layer for AI-assisted software delivery. It runs one staged workflow through Claude Code, Codex, OpenCode, Qwen Code, or an AIDD-compatible CLI without making the workflow depend on one provider.

Instead of turning a prompt directly into an opaque code change, AIDD saves the requirements, decisions, outputs, questions, validation results, and available runtime logs in the local project. Each stage produces readable Markdown and must pass its document contract before the workflow can advance.

Why AIDD?

Coding agents are useful, but a one-off agent run often leaves important questions unanswered: What requirements did it use? Why did it make a decision? Was the output checked? Can the same process run with another provider? What evidence remains after the session ends?

AIDD validates conformance to its declared contracts; it does not guarantee that generated software is correct. Human product ownership, code review, and appropriate testing remain essential.

The local Operator UI presents project work, decisions, documents, and retained run evidence.

Project status and safety

AIDD is prerelease alpha software. See PyPI for the latest published package and the changelog for release history. The latest accepted prerelease is v0.1.0a22; the main branch may contain unreleased changes.

Warning: AIDD is intended for local evaluation and controlled operator trials. It is not ready for unattended production automation, and its interfaces may change.

Beta readiness is a future evidence gate, not a current production-readiness claim.

Current alpha builds support the current configuration and artifact formats. Recreate workspaces from older versions before resuming work, and remove the obsolete [logging] configuration section. See the compatibility policy for the current-format boundary.

Before running AIDD:

• use a disposable branch, sandboxed checkout, or otherwise controlled workspace;
• review the provider command and permission policy—the selected runtime may have broad access to the working tree;
• install and authenticate the provider CLI separately;
• treat .aidd/ as sensitive local state because it can contain prompts, repository context, operator answers, raw logs, and provider evidence;
• do not commit .aidd/ unless your repository policy explicitly allows it;
• keep the local Operator UI on loopback unless you have deliberately reviewed the exposure. It is a local, no-auth operator surface rather than a remote multi-user service.

Requirements

• CPython 3.12, 3.13, or 3.14
• Linux for the release-blocking platform path, or macOS on a best-effort basis
• pipx or uv for installation
• an installed and authenticated provider CLI, or a configured generic wrapper, for runtime execution

Windows is not currently supported. AIDD does not bundle AI runtimes, provider credentials, or model access. Docker/GHCR images are not published or supported during alpha.

Install

Install the latest published package with either supported tool:

pipx install ai-driven-dev-v2

or:

uv tool install ai-driven-dev-v2

Then verify the installation and inspect runtime readiness:

aidd --version
aidd doctor

To reproduce a specific alpha release, append ==<version> to the package name. aidd doctor checks local configuration and command availability; it does not prove that provider authentication, quota, or remote API access will succeed.

Run your first workflow

Start in the local project root that should receive the workflow state. For a first trial, use a disposable or feature branch.

UI-first path

cd /path/to/local-project
aidd doctor
aidd ui

aidd ui prints a loopback URL. A new project opens Guided Setup; an existing .aidd/ workspace opens the project Inbox. Create or select a work item, then choose a runtime when you are ready to launch. The UI and CLI use the same project-local files.

CLI-first path

This bounded example runs only the strategy stages through plan; it does not reach the code-changing implement stage:

cd /path/to/local-project
aidd doctor
aidd init --work-item WI-001 --request "Implement a small, specific task" --root .aidd
aidd run --work-item WI-001 --runtime codex --from-stage idea --to-stage plan --root .aidd
aidd run show --work-item WI-001 --root .aidd

Inputs, outputs, logs, and reports are retained under the project-local .aidd/ directory. A run may stop with blocking questions instead of advancing. That is an explicit operator checkpoint, not a silent failure.

The complete UI and CLI path is documented in the Operator Handbook.

How it works

The canonical workflow is:

idea -> research -> plan -> review-spec -> tasklist -> implement -> review -> qa

Every stage follows the same provider-independent loop:

1. AIDD gathers the declared Markdown inputs and builds a stage brief.
2. The selected adapter launches an external AI runtime.
3. The runtime writes stage documents while AIDD retains available logs and evidence.
4. AIDD validates the output against structural, semantic, and cross-document rules.
5. A valid result advances. An invalid result receives a bounded repair attempt. A blocking question pauses the run until the operator answers it.

operator CLI / UI
        |
        v
    AIDD core ------> validator / repair / interview
        |
        v
     adapter -------> external AI runtime
        |
        v
project-local .aidd/ documents, logs, and evidence

The core owns workflow semantics, stage order, validation, and artifact policy. Adapters own runtime-specific process launch, streaming, and capability mapping. See the target architecture for the complete model.

Supported runtimes

Support tiers describe maintenance and release impact, not feature identity. Runtime capabilities can differ, and AIDD reports explicit degraded behavior when needed.

generic-cli is not the default product onboarding runtime. It is a portability baseline for operators who intentionally provide an AIDD-compatible wrapper command. For exact capabilities and support commitments, see the runtime matrix.

Scope and non-goals

AIDD is an orchestration and evidence layer. It is not:

• an AI model, coding agent, IDE, or hosted SaaS product;
• a replacement for human requirements, review, security analysis, or release decisions;
• a guarantee that a runtime will produce correct code or that a repair will succeed;
• a promise of identical capabilities across every AI runtime;
• a production-ready platform for unattended or remote multi-user automation.

The product starts from a local project root. Manual external repository evaluations are maintainer audit evidence, not a product intake path or release automation. See the manual evaluation catalog and scenario matrix for the maintained evaluation boundaries.

Documentation

Development from source

git clone https://github.com/GrinRus/ai_driven_dev_v2.git
cd ai_driven_dev_v2
uv sync --locked --extra dev
uv run aidd --version
uv run aidd doctor

The contribution guide describes the repository structure, quality checks, and review expectations.

Contributing

Contributions to code, adapters, contracts, prompts, documentation, scenarios, and tests are welcome. Start with the contribution guide, review the governance model, and follow the Code of Conduct.

Use the issue chooser for a reproducible bug, operator support request, or feature proposal. For a large change, open an issue or draft pull request before investing in the full implementation.

Security and support

Report vulnerabilities through the process in SECURITY.md. Do not put tokens, private repository contents, provider credentials, or unredacted runtime logs in a public issue.

For reproducible operator problems, see SUPPORT.md.

License

AIDD is available under the Apache License 2.0.