ai-driven-dev-v2 0.1.0a6

Runtime-agnostic, document-first orchestration for AI-driven software delivery.

ai_driven_dev_v2

Runtime-agnostic orchestration for document-first AI software delivery.

AIDD runs a governed staged workflow over a local project. It asks a runtime such as Claude Code, Codex, OpenCode, or a generic CLI to produce Markdown stage artifacts, then validates those artifacts before the workflow can advance.

The canonical stage flow is:

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

Alpha status and safety

Latest published prerelease: 0.1.0a5. Current release-candidate package version on this branch: 0.1.0a6. Latest accepted published prerelease evidence before this candidate: 0.1.0a5. The main branch is development source and may contain unreleased changes.

AIDD is alpha software for local evaluation and controlled operator trials. It is not ready for unattended production automation. AIDD launches external runtime CLIs against a local working tree; review runtime commands before execution and prefer a disposable branch, workspace, or sandboxed checkout for trials.

Beta-readiness work on main is a preparation gate, not a production-readiness claim. Before any beta-oriented release note is published, maintainers must confirm that the README, main user stories, and target architecture still match the code, deterministic release checks pass, and manual live evidence is refreshed outside CI/CD.

Do not commit .aidd/ unless your repository policy explicitly allows it. The workspace can contain raw runtime logs, prompts, repository context, operator answers, and other sensitive evidence.

What is AIDD?

ai_driven_dev_v2 (AIDD) is for teams that want AI-assisted software work to leave inspectable evidence instead of only chat transcripts or opaque runtime state.

AIDD provides:

• a runtime-agnostic core with adapter-based runtime integration;
• Markdown-first stage inputs and outputs;
• validator gates before stage progression;
• bounded self-repair after invalid outputs;
• durable questions, answers, logs, validation reports, and run artifacts;
• a CLI and local operator UI over the same repository-local .aidd/ workspace;
• deterministic harnesses and manual live E2E evaluation support.

AIDD does not bundle third-party runtime binaries. Operators install and authenticate Claude Code, Codex, OpenCode, or other runtime CLIs separately.

Install with pipx

Install the latest published prerelease:

pipx install "ai-driven-dev-v2==0.1.0a5"
aidd --version
aidd doctor

Install with uv tool

Install the latest published prerelease:

uv tool install "ai-driven-dev-v2==0.1.0a5"
aidd --version
aidd doctor

Container support

AIDD does not publish or support Docker/GHCR images during the alpha phase. The supported alpha installation paths are PyPI via pipx, uv tool, and source checkout.

Container support may be reconsidered after the runtime permission model, release provenance, and operator workflows stabilize.

Source checkout

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 latest published prerelease with accepted install evidence is v0.1.0a5. Source checkouts from main may contain unreleased changes; future release candidates must again pass GitHub Release, PyPI publish, pipx, and uv tool verification before they are accepted.

Run your first local workflow

Start from the local project root that should receive AIDD workflow state:

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

This creates .aidd/ inside the local project and seeds the required intake context documents for the first stage. Treat .aidd/ as project-local operator state that may include sensitive raw runtime logs, prompts, repository context, questions, answers, and validation evidence.

From a source checkout without installing globally, replace aidd with:

uv tool run --from /path/to/ai_driven_dev_v2 aidd

The product operator path starts from a local project root. aidd init --github-issue <url> is out of product scope. Public GitHub repositories are live E2E targets and support/reporting evidence sources only, not a product intake path.

Choose a runtime

Use aidd doctor to check provider availability, configured execution commands, support tiers, and default timeout settings.

Runtime	External dependency	Default execution mode	Typical use
generic-cli	Python	adapter-flags	Advanced AIDD-compatible wrapper and deterministic checks
claude-code	Authenticated claude CLI	native	Claude Code-backed workflow runs
codex	Authenticated codex CLI	native	Codex-backed workflow runs and live evals
opencode	Authenticated opencode CLI	native	OpenCode-backed workflow runs and live evals
qwen	Authenticated qwen CLI	native	Experimental Qwen Code workflow runs

Product workflow and stage execution require an explicit runtime id:

aidd run --work-item WI-001 --runtime codex --root .aidd
aidd stage run plan --work-item WI-001 --runtime opencode --root .aidd

Codex, OpenCode, Qwen, and Claude Code default to native provider CLI execution. generic-cli is not the default product onboarding runtime; use it when you intentionally configure an AIDD-compatible wrapper command with mode = "adapter-flags" for a deterministic or custom execution surface.

Unknown runtime ids fail fast with unsupported-runtime classification.

Inspect artifacts and logs

AIDD stores workflow evidence under .aidd/:

aidd run show --work-item WI-001 --root .aidd
aidd run logs --work-item WI-001 --stage plan --root .aidd
aidd run artifacts --work-item WI-001 --stage plan --root .aidd
aidd stage questions idea --work-item WI-001 --root .aidd
aidd stage interact plan --work-item WI-001 --runtime codex --request "Add rollback risks" --root .aidd

Stage documents, runtime logs, validator reports, repair briefs, questions, and answers remain ordinary files in the local workspace. The core treats Markdown documents as the contract surface; runtime-authored JSON schemas are not the primary stage output format. When a CLI stage stops on questions, inspect them with aidd stage questions, write answers to .aidd/workitems/<work-item>/stages/<stage>/answers.md, and rerun the stage with aidd stage run <stage> --work-item <id> --runtime <runtime> --root .aidd. When a stage artifact needs a scoped correction or additional analysis, use aidd stage interact <stage> with --request or --request-file; AIDD stores the operator request under operator-requests/request-000N.md and runs a normal validated stage attempt in the current run.

Operator UI

Start the local UI for an initialized work item:

aidd ui --work-item WI-001 --root .aidd

The UI reads the same .aidd/ state as the CLI. It can show stage status, render stage Markdown artifacts, show runtime logs, answer questions, show repair history, submit stage-scoped operator intervention requests, and display runtime readiness details without introducing a separate workflow engine. Operators can run the full workflow, run or resume the next eligible stage, or submit Request change -> Submit & run from the selected stage cockpit; these actions require an explicit runtime selection and there is no hidden generic-cli fallback. New UI launches stream live job logs while the process runs, and the saved runtime.log remains available afterward through the normal log view and CLI. The UI can write question answers as [resolved], [partial], or [deferred] entries in the standard answers.md; only [resolved] answers unblock blocking questions, then rerun the selected stage or workflow after answering. Intervention requests are stored as durable Markdown input under .aidd/workitems/<id>/stages/<stage>/operator-requests/ and are shown in Activity, Evidence Refs, and Recent Artifacts. The UI is a local no-auth operator surface: the default host is loopback, and non-loopback binds print a warning.

After terminal qa, the command center switches to Flow Complete. The completed-run handoff shows final QA status, final artifacts, blockers, repair counts, approval counts, answered questions, recommended next-flow actions, and source-run lineage. Operators can create a new work item, start a follow-up flow, clone the previous flow, hand off to an eval / scenario batch, or archive the run. Follow-up and clone actions create new independent work item or run identities with source-run references; archive records local operator intent without deleting artifacts or mutating the completed source run.

For the local UI evidence lane, see docs/e2e/operator-ui-local-project.md.

How AIDD works

Architecture in one line:

operator CLI / UI -> AIDD core -> adapter -> runtime -> workspace documents

Key design rules:

• the core owns workflow semantics, stage order, validation, repair, and workspace policy;
• adapters own runtime process launch, streaming, and runtime-specific command behavior;
• stage inputs and outputs are Markdown documents;
• validation failures trigger repair or an explicit stop;
• questions and answers are persisted as documents;
• operator intervention requests are persisted as stage-scoped Markdown input and validated through the normal stage chain;
• runtime logs are streamed when possible and saved for replay and eval analysis.

Primary architecture docs:

• docs/architecture/target-architecture.md
• docs/architecture/adapter-protocol.md
• docs/architecture/document-contracts.md
• docs/architecture/runtime-matrix.md
• docs/architecture/operator-frontend.md
• docs/architecture/project-set-workspace.md
• docs/architecture/distribution-and-development.md

Development from source

Prerequisites:

• Python 3.12+
• uv
• optional provider CLIs for runtime-specific development
• provider authentication configured outside AIDD

Bootstrap and check the repository:

uv sync --locked --extra dev
uv run aidd --version
uv run aidd doctor
uv run --extra dev ruff check .
uv run --extra dev python -m mypy src
uv run --extra dev pytest -q

Contributor workflow:

1. Read AGENTS.md.
2. Read docs/product/user-stories.md.
3. Pick a local task from docs/backlog/backlog.md.
4. Use docs/backlog/roadmap.md for the full wave/epic/slice/task hierarchy.
5. Keep the core runtime-agnostic and update docs/contracts/prompts when behavior changes.

Eval and release evidence

AIDD includes deterministic harness checks and manual live E2E scenarios. Live E2E is manual local operator audit evidence, not CI/CD, not a release workflow, not GitHub Actions, and not a release gate. CI, security, and release workflows must not run live scenarios, require provider credentials, or depend on public live target repositories.

Example black-box live E2E evaluator command:

uv run python -m aidd.harness.live_e2e_black_box harness/scenarios/live/sqlite-utils-detect-types-header-only.yaml --runtime codex --work-root /tmp/aidd-live-e2e --report-root .aidd/reports/evals

Manual live E2E scenarios snapshot tracked AIDD HEAD into ${TMPDIR:-/tmp}/aidd-live-e2e/<run_id>/source/aidd, build and install through an isolated uv tool home/cache, clone the pinned target repository under <work-root>/<run_id>/target/<repo-slug>, run from the target repository root, execute each stage through public aidd stage run and inspection commands plus loopback aidd ui UI/API checkpoints, write stage-audits/<stage>.json and .md per-stage audits, record acceptance coverage, UI/UX checkpoint summaries, and operator-quality-analysis validation, and preserve durable audit bundles under .aidd/reports/evals/. The evaluator always builds a local wheel from the clean tracked source checkout containing the scenario manifest. Published-package install proof is a separate release/install evidence lane, not part of public-repository live E2E.

Public GitHub repositories are live E2E targets for evaluator evidence only. See:

• docs/e2e/live-e2e-catalog.md
• docs/e2e/scenario-matrix.md
• harness/scenarios/live/

Release and install evidence for PyPI, pipx, and uv tool is recorded in docs/release-checklist.md. Docker/GHCR is intentionally outside the alpha release contract.

Docs map

• docs/operator-handbook.md — operator install, config, and runtime guidance
• docs/operator-troubleshooting.md — diagnostics and common failure modes
• docs/operator-support-policy.md — support and evidence expectations
• docs/product/user-stories.md — product outcomes and scope boundaries
• docs/architecture/ — stable architecture decisions and protocols
• docs/e2e/ — manual live E2E and local operator UI evidence
• docs/backlog/roadmap.md — canonical plan
• docs/backlog/backlog.md — short actionable queue
• docs/compatibility-policy.md — Python and platform compatibility

Repository map

• src/aidd/ — Python package with core orchestration, adapters, validators, CLI, harness, and evals
• contracts/ — stage and document contracts
• prompt-packs/ — file-based stage prompts
• harness/scenarios/ — smoke and live scenario manifests
• .agents/skills/ — reusable team skills for Codex-style development
• tests/ — deterministic unit, integration, docs, adapter, harness, and eval checks
• MANIFEST.md — historical archive contents snapshot, not the current source-of-truth inventory

Contributing

See CONTRIBUTING.md.

The short version:

• keep changes aligned with the user stories;
• keep runtime-specific logic inside adapters;
• update docs, contracts, prompts, scenarios, and tests when behavior changes;
• run the narrowest useful checks locally before opening a PR.

Security and support

Use SECURITY.md for vulnerability reporting and SUPPORT.md for operator support scope. Do not file public issues containing secrets, private repository contents, provider logs, or tokens. Release notes and user-visible changes are tracked in CHANGELOG.md.

License

This project is licensed under the Apache License 2.0. See LICENSE.