paralleldrive/aidd: the AIDD Framework for AI Driven Development

What AIDD Framework solves, and who it is written for

The README opens with a blunt claim: AI agents ship features fast, and the framework exists to keep them working, secure and maintainable. The supporting argument is quantitative. It cites GitClear tracking 211 million lines from 2020 to 2024 and finding 8x more code duplication as AI adoption increased, and a Google DORA report correlating AI adoption with 9% higher bug rates and degraded stability. The failure modes it names are specific: agents skip tests, couple modules, duplicate logic and miss vulnerabilities.

That framing defines the audience. AIDD Framework is not for someone who wants a model to generate a first draft of a function. It is for teams that have already handed feature work to an agent and now spend their time cleaning up after it. The README describes the target methodology as AI systems taking primary responsibility for generating, testing and documenting code, with humans focused on the big picture. If your workflow still has a human writing most of the implementation, the specification and task-planning machinery here is overhead you will not repay.

The distribution reflects that audience. The package ships as an npx-invokable CLI plus a folder of agent skills, not as a library you import into application code. Its unit of adoption is a project scaffold, not a dependency.

How the agent runtime, skills and SudoLang fit together

The mechanism is a folder convention plus a set of chat commands. Running the CLI writes an ai/ directory into your project. That directory holds skills, and the README points to ai/skills/aidd-please/SKILL.md as the main orchestrator. Skills are Markdown files an agent reads; the framework's leverage comes from the agent following them rather than from any runtime enforcement.

On top of that sit workflow commands typed into the assistant chat rather than the shell. The README lists /discover for what to build, /task to plan a task epic from a discovery, /execute to implement epics with TDD, /review for the results, /log for the activity log, /commit for the repository, and /user-test for post-deploy validation scripts. The ordering is the point: discovery produces the specification, the specification produces the epic, the epic is executed test-first. Nothing in the repository listing suggests the CLI itself blocks you from running /execute before /discover. The sequence is a convention the prompts encode.

SudoLang is the third piece, described as a pseudocode language for prompting large language models with clear structure, strong typing and explicit control flow. It is a prompt format, not an execution engine. The README's installation steps tell you to install SudoLang syntax highlighting separately from the sudolang-llm-support repository, which confirms the language is consumed by humans and models in an editor, not compiled by the aidd binary.

The fourth piece is a server framework, a composable backend for Node and Next.js. The package exports ./server, ./agent, ./agent-config and ./utils as entry points, so the agent runtime and server are importable separately from the CLI. The dependencies tell you what the server leans on: @sinclair/typebox for schemas, commander for CLI parsing, gray-matter for front matter in the skill Markdown, js-yaml, and tsmetrics-core, which suggests the framework measures TypeScript complexity as part of its review story.

Installing the AIDD CLI and running a first agent prompt

The README's quick start is a single npx call, so nothing is installed globally. The package declares engines.node as >=18 in package.json while the README requirements section says Node.js 16.0.0+ with ESM support. Treat the package.json value as the stricter one.

Start by reading the CLI surface:

npx aidd --help

That prints the available commands and options. The README shows three ways to scaffold. For Cursor users, the recommended form creates an ai/ folder plus a .cursor symlink so the editor picks the skills up automatically:

npx aidd --cursor my-project

Without the flag you get the ai/ folder alone and integrate manually. You can also pass a project folder as a positional argument. After scaffolding, the README's step four is to inspect what landed:

cd my-project
ls ai/
cat ai/skills/aidd-please/SKILL.md

You should see the skill set and the orchestrator document. Step three, which the README marks as important, is creating a vision.md in the project root before you prompt anything. The README states plainly that this file serves as the source of truth for AI agents; without it the discovery and task commands have no grounding. There is also an AGENTS.md file, and the README documents migrating an existing one.

Once scaffolded, you can run an agent directly from the CLI rather than from the editor:

npx aidd agent --prompt "Set up authentication"

Or scaffold and prompt in one command:

npx aidd create my-app --prompt "Set up authentication"

For npx aidd create against a GitHub repository URL, the README says authentication prefers the GitHub CLI when available. Run gh auth login first so private repositories, including org repos you do not own, work without exporting a long-lived token. If gh is missing or not logged in, GITHUB_TOKEN or GH_TOKEN still work for CI and compatibility. The README also points to docs/agent-cli.md for full usage, and that file is included in the published package.

Where AIDD Framework stops helping

The environment requirement is the first hard boundary. The README requires a Unix/Linux shell such as bash or zsh, or Windows with WSL. That rules out plain Windows terminals, and it is a real constraint rather than a formality because the scaffolding relies on a .cursor symlink and shell behaviour.

The second boundary is the nature of the enforcement. Skills are Markdown instructions. The README never describes a validator that fails a build when an agent edits source without a corresponding test, or when a commit lands without a logged activity entry. The commands /review, /log and /commit are prompts you or your agent invoke. A disciplined agent follows them; a distracted one can ignore them, and the framework's own cited research on duplication and bug rates is exactly what happens when that discipline slips. If you need a gate that cannot be skipped, this is the wrong layer.

The third is model dependence. The README says the framework works with any sufficiently advanced LLM and recommends Claude 4.5 Sonnet as of the writing. The workflows involve long specification documents, multi-step task epics and a pseudocode prompt language. Smaller or cheaper models will follow the structure less reliably, and the README does not publish an evaluation of how behaviour degrades across models, though the repository does contain an ai-evals/ directory.

Finally, the README does not document rollback or uninstall. If you scaffold into an existing project and dislike the result, removing the ai/ directory and the .cursor symlink is something you infer from the layout, not something the documentation describes.

How AIDD differs from plain Claude Code or Cursor workflows

The honest comparison is not against another framework but against the default setup most teams already have: an agent, a chat window, and a repository. In that setup the specification lives in the conversation, tests are whatever the agent decides to write, and review is a human reading a diff. AIDD Framework's difference is that it externalises the specification into vision.md and the task plan into the /discover and /task steps, so the agent reads a durable artifact instead of reconstructing intent from chat history.

The second difference is SudoLang. Where a normal prompt is prose, SudoLang is described as typed pseudocode with explicit control flow. That matters for orchestration prompts that need to branch, loop or define interfaces, because prose prompts drift across sessions while a typed structure is easier to keep stable and review. It costs you a separate syntax highlighting install from the sudolang-llm-support repository and a language your team has to learn.

The third difference is scope. AIDD bundles a Node and Next.js server framework and a component and utilities library alongside the agent tooling. If you only want the workflow commands, you are pulling in a backend framework as part of the same package. The exports map does let you import ./agent or ./utils on their own, so the coupling is at the package level rather than the module level, but it is still more surface than a prompt-only toolkit.

Licence, maintenance and what upgrading costs

The licence is MIT, which permits commercial and private use, modification and redistribution. The practical implication for a tool that scaffolds files into your repository is that the generated ai/ folder and the skills inside it are covered by the same permissive terms, so you can edit them and keep the edits without publishing anything. This is not legal advice; read the LICENSE file in the repository for the actual terms.

The repository is not archived, and the last push was on 2026-06-12. Recent releases are v3.1.0 on 2026-03-30, v3.0.0 on 2026-03-29 and v2.8.0 on 2026-03-14. The jump from 2.8.0 to 3.0.0 within a month of 2.8.0 signals that the project is willing to make breaking changes at the major-version boundary, and the presence of a .release-it.json plus a release.js and a CHANGELOG.md means releases are scripted rather than ad hoc.

Upgrade cost is concentrated in the ai/ folder. Because the CLI scaffolds skills into your project rather than installing them as a dependency, a new major version can change the skill files and the command set your agents rely on. The repository ships an aidd-custom/ directory described as project customisation, which is the intended place for your own changes so that re-scaffolding does not overwrite them. Before upgrading, diff your ai/ folder against the version the new CLI produces. The README does not describe an upgrade command or a migration path between major versions, so the diff is manual work.

Editorial conclusion

Adopt AIDD Framework if your team already runs an agent such as Claude Code and the recurring failure is process, not model quality: skipped tests, duplicated logic, no written specification. Skip it if you work on Windows without WSL, or if you cannot commit to writing vision.md and running /discover, /task and /execute in order, because the framework is a set of skills and commands that only pay off when followed. Before adopting, run npx aidd --help, then npx aidd --cursor into a throwaway folder and read ai/skills/aidd-please/SKILL.md to see what the orchestrator actually instructs your agent to do.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. paralleldrive/aidd on GitHub
4. README
5. Releases