Model or dataset
paralleldrive/aidd avatar
paralleldrive/aidd

AIDD wraps a coding agent in seven slash commands and an ai/ folder

The standard framework for AI Driven Development

389 stars33 forksJavaScriptMIT

At a glance

What is it?
AIDD Framework is a Node CLI plus a directory of agent skills that walks a coding agent through discovery, planning, TDD execution, review, and commit. What it installs is prompts, skills, and a place to keep them; what it asks of you is a vision document and a habit of running the commands in order.
Who is it for?
AIDD fits a team already working inside Cursor or a comparable assistant and willing to keep an ai/ directory and a vision.md in version control as project source. It does not fit a project that wants its process enforced by tooling, because every step here is a prompt an agent may interpret rather than a check that fails.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 156 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • paralleldrive/aidd389 ★ · +8
Star history
Repository2026-09-132026-11-15
paralleldrive/aidd381389

8 Stars in the last 63 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Seven slash commands, and the order they run in is the method

The workflow is a list of commands you type into an assistant chat, in Cursor or anything comparable:

bash
/discover - what to build
/task - plan a task epic to implement a user story from the discovery
/execute - task epics with TDD
/review - the results
/log - log the changes to the activity log
/commit - commit the changes to the repository
/user-test - generate user testing scripts for post-deploy validation

Read as a sequence, the shape is specification first. `/discover` decides what to build, `/task` turns one user story from that discovery into a task epic, `/execute` implements the epic with test driven development, and `/review` looks at what came out. The last three are bookkeeping and handoff: an activity log entry, a commit, and user testing scripts for after deployment.

That ordering is the actual product. The framework's own claim is that agents generate code that runs but fails at scale, and it opens with two cited studies to make the case: GitClear tracked 211 million lines from 2020 to 2024 and found 8x more code duplication as AI adoption increased, and a DORA report cited alongside it correlates AI adoption with 9% higher bug rates and degraded stability. The countermeasure offered is a fixed order of operations rather than a better model.

npx aidd --cursor writes ai/ and symlinks .cursor into it

The whole install is one command. There is no package to add to your manifest and no configuration file to hand-write:

bash
# In your project folder
npx aidd --cursor

Two variants exist and the difference is the integration step. With `--cursor`, the CLI creates an `ai/` folder and a `.cursor` symlink for automatic integration. Without it, you get the `ai/` folder and the symlink is left to you:

bash
# Recommended: Creates ai/ folder + .cursor symlink for automatic integration
npx aidd --cursor my-project

# Alternative: Just the ai/ folder (manual integration required)
npx aidd my-project

The path argument works either way, so scaffolding a new project and retrofitting an existing one are the same command. The README also documents running an agent directly and scaffolding plus running in one step:

bash
# Run an agent directly
npx aidd agent --prompt "Set up authentication"
# Scaffold + run agent in one command
npx aidd create my-app --prompt "Set up authentication"

Authentication for that path is worth a note. Point `create` at a GitHub repository URL and the CLI uses the GitHub CLI first when it is available, so `gh auth login` covers private repositories you can reach, including organisation repositories you do not own, without a long-lived token. When `gh` is missing or logged out, `GITHUB_TOKEN` or `GH_TOKEN` still work, which is the CI path.

The README says Node 16 and the manifest says 18, and Windows needs WSL

Two requirements documents disagree. The requirements section lists Node.js 16.0.0 or newer, noting that ESM support is required. The package manifest declares `engines.node` as `>=18`. If you are provisioning a machine today, follow the manifest and start at 18, but the gap is a fair signal of how quickly the documentation lags the code.

The environment line is stricter than the Node line. A Unix or Linux shell, bash or zsh, is the stated environment, and Windows is supported through WSL. There is no native Windows path in the requirements, so a team on Windows without WSL is out of luck regardless of Node version.

The model requirement is loose by comparison: any sufficiently advanced LLM, with Claude 4.5 Sonnet recommended at the time of writing. The editor line says it works with any editor and is optimised for Cursor. Those two together define who the tool was designed around, even though nothing in the requirements list makes Cursor mandatory, since the `ai/` folder without the symlink is a supported configuration.

vision.md is the file every agent is supposed to read first

Step three of the install instructions is marked important, and it is a file you write yourself. A `vision.md` in the project root becomes the source of truth for AI agents: what the product is, who it is for, what it should never do. The framework treats it as a required step rather than an optional extra, because the slash commands downstream assume an agent already knows the intent.

The repository holds its own copy at the top level, next to a `plan.md`, an `activity-log.md`, a `tasks/` directory, a `plan/` directory, and an `AGENTS.md`. That set is a working example of the state the tooling expects a project to accumulate, and it is worth reading before you install anything, because it shows what a maintained instance looks like.

Customisation has its own place. An `aidd-custom/` directory sits at the repository root for project-specific overrides, and the install steps close by telling you to reference `ai/skills/` in your prompts for better context and to use `ai/commands/` as workflow templates. The split between the generated `ai/` tree and the hand-maintained `aidd-custom/` tree is the whole maintenance model: regenerate the first, edit the second.

SudoLang is a prompt language, and the editor support lives in another repo

One of the five components is SudoLang, described as a pseudocode language for prompting large language models with clear structure, strong typing, and explicit control flow. It is not a runtime and not a compiler. It is a notation for writing instructions, which is why the first install step has nothing to do with npm at all: visit the SudoLang repository and install syntax highlighting for your editor.

That step is easy to skip and worth not skipping. SudoLang files read as typed pseudocode, and without highlighting you are reviewing control flow in an unstyled wall of text. The highlighting lives in a separate repository, `paralleldrive/sudolang-llm-support`, so the framework is deliberately split between the CLI you run and the editor support you install.

The remaining three components are conventional by comparison. The AIDD CLI handles project bootstrap and automation. The agent runtime carries workflows from product discovery through commit and release. The server framework is a composable backend for Node and Next.js, and a utilities and component library supplies common patterns. The slash commands are the seam between all five.

Four subpath exports ship the CLI, the agent runner, and the server together

The manifest declares one binary, `aidd`, pointing at `bin/aidd.js`, and four subpath exports that make the package more than a scaffolder. `./agent` and `./agent-config` resolve into `lib/agent-cli/`, `./server` into `src/server/index.js`, and `./utils` into `utils/index.js`. A team can therefore import the agent runner or the server framework from the same install that wrote the skills folder.

The published file list matches that intent. The `ai`, `bin`, `docs`, `lib`, `src`, and `utils` trees all ship to npm, with test files excluded, plus README, LICENSE, CHANGELOG, and CONTRIBUTING. Dependencies are the usual scaffolding set: commander for the CLI, chalk, fs-extra, gray-matter and js-yaml for front matter and config, js-sha3 and @paralleldrive/cuid2 for identifiers, and @sinclair/typebox for schemas. TypeScript is a runtime dependency rather than a dev one, which is a choice worth noticing in a package whose whole job is generating typed prompts.

Development tooling around it is Vitest, Biome, husky, doctoc, and release-it, with a `.release-it.json` and a `release.js` at the root. Tags v3.0.0 and v3.1.0 are a day apart, both in March 2026, and the last push to the repository was on 2026-06-12.

Every step is a prompt, so nothing here fails a build when it is skipped

Set expectations about what this framework can enforce. A slash command is text handed to an agent, and whether `/review` catches a missed test case depends on the model reading it carefully. There is no hook in the manifest that fails a commit because ERRORS.md was not updated, and no test that asserts the vision document exists.

The README is organised as though the discipline is the product. It documents user testing as a first-class step rather than an afterthought, and it includes sections on when to use `--cursor` and when not to, plus manual integration and troubleshooting for the cases where the symlink is the wrong choice. The optional `ai-evals/` directory at the repository root suggests the framework's own prompt behaviour is something the project evaluates rather than assumes.

What you get at the end of an install is a directory of instructions and a set of habits. That is a real contribution when an agent has no memory between sessions and no shared sense of what the product is for, because the vision document and the skills carry that context in a form any assistant can read. It is a weaker contribution when your team already enforces its process in CI, since nothing AIDD adds would fail a build that your existing checks do not already catch.

Editorial conclusion

AIDD fits a team already working inside Cursor or a comparable assistant and willing to keep an ai/ directory and a vision.md in version control as project source. It does not fit a project that wants its process enforced by tooling, because every step here is a prompt an agent may interpret rather than a check that fails. Before adopting it, read `ai/skills/aidd-please/SKILL.md` after running `npx aidd --cursor` and confirm the orchestrator's assumptions match how your team actually reviews code, since that file is the part you will end up editing.

Frequently asked questions

What is the AIDD framework?

AIDD Framework is a collection of reusable agent skills, orchestration systems, symbolic code libraries, and CLI tools that put specification-driven development, task planning with TDD, and automated code review on rails for an AI coding agent. It ships as the `aidd` npm CLI.

How do I install AIDD in my project?

Run `npx aidd --cursor` in the project folder. That creates an `ai/` folder plus a `.cursor` symlink for automatic integration. Use `npx aidd my-project` if you want only the `ai/` folder and will wire up the editor yourself.

Which slash commands does AIDD define?

Seven: `/discover` for what to build, `/task` to plan a task epic, `/execute` to implement it with TDD, `/review` the results, `/log` the changes to the activity log, `/commit` them, and `/user-test` to generate post-deploy validation scripts.

What is vision.md in the AIDD framework?

It is a file you create in the project root that becomes the source of truth for AI agents, and the install instructions mark the step as important. AIDD also ships its own vision.md, plan.md, activity-log.md, tasks/, and plan/ as a working example.

What are the Node and shell requirements for the AIDD CLI?

The requirements section lists Node.js 16.0.0 or newer with ESM support, while the package manifest declares node >=18. The environment must be a Unix or Linux shell such as bash or zsh, or Windows with WSL.

Official sources

  1. Issues
  2. License: MIT
  3. paralleldrive/aidd on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/paralleldrive-aidd.svg)](https://hysenlabs.com/projects/paralleldrive-aidd)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/paralleldrive-aidd.svg)](https://hysenlabs.com/projects/paralleldrive-aidd)

Was this useful?