paralleldrive/aidd: an agent workflow scaffold that assumes you already have a vision.md
The standard framework for AI Driven Development
At a glance
- What is it?
- AIDD Framework packages a CLI, a prompt language called SudoLang, and a set of slash-command workflows for driving coding agents through discovery, TDD, review and commit. It is a process scaffold rather than a library, and it only pays off if you commit to its file layout.
- Who is it for?
- Adopt it if your team already runs coding agents in Cursor or Claude Code and keeps losing track of what the agent was asked to do; the /discover to /commit chain and the vision.md source-of-truth file are the parts worth copying even if you never run npx aidd. Do not adopt it if you are on Windows without WSL, or if you want a library you can call from application code, since this is a scaffold of markdown skills and prompt conventions.
- 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 95 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 September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode AIDD is aimed at
The README opens with a specific complaint: agents ship features fast but produce code that "runs but fails at scale." It cites GitClear's tracking of 211 million lines from 2020 to 2024 and a finding of 8x more code duplication as AI adoption rose, and a DORA report showing AI adoption correlating with 9% higher bug rates. Those numbers are the project's own framing, not independent verification, and the README does not reproduce methodology. Still, the diagnosis is concrete: agents skip tests, couple modules, duplicate logic, and miss vulnerabilities. The proposed answer is not a linter or a static analyser. It is a set of enforced process steps, expressed as prompts and skill files, that an agent is expected to follow in order. The audience is a team already using an agent in an editor, most likely Cursor, that wants the agent's work to leave a trail: a discovery document, a task plan, tests written before implementation, a review pass, an activity log, and a commit. If you are not already running an agent, there is nothing here for you to automate.
What the CLI actually puts on disk
The scaffold is the core artefact. Running npx aidd my-project creates an ai/ directory in the target folder. Running npx aidd --cursor my-project creates the same ai/ folder plus a .cursor symlink, which is how Cursor picks up the skills without manual wiring. The README's own exploration step is instructive: cd my-project, then ls ai/ and cat ai/skills/aidd-please/SKILL.md. That last path is described as the main orchestrator, which tells you the design intent. The behaviour lives in markdown skill files that the agent reads, not in JavaScript modules your application imports. A separate aidd-custom/ directory is documented for project-level customisation, and the structure section lists skills, an AI system directory, and an AGENTS.md file, with a documented path for migrating an existing AGENTS.md into the framework's layout. The practical consequence is that upgrading the framework means reconciling your edits against new skill files, and the aidd-custom/ directory exists precisely to keep your changes out of the files that get replaced.
The workflow chain from /discover to /commit
The README lists six workflow commands used inside the assistant chat rather than the shell: /discover for what to build, /task to plan a task epic from a user story produced by discovery, /execute to implement those epics with TDD, /review for the results, /log for the activity log, and /commit for the repository. /user-test is listed separately as generating testing scripts for post-deploy validation, which places it outside the main chain. The ordering is the point. Discovery produces the user story, the task command turns that story into a plan, and execution is scoped to the plan rather than to a free-form prompt. That is the mechanism that is supposed to prevent an agent from inventing scope mid-task. Note what is absent from the README: there is no description of how a task epic is stored, no schema for the activity log, and no statement about what happens when /review finds problems. The chain is documented as a sequence of commands, not as a state machine with defined transitions, so the enforcement is only as strong as the skill files the agent is reading.
vision.md is a hard prerequisite, not a suggestion
The installation instructions flag the vision document as important and tell you to create vision.md in the project root, describing it as the source of truth for AI agents. The README devotes a dedicated section to why you need one, how to create it, and how agents consume it. This is the load-bearing assumption of the whole framework. Every downstream command, from /discover onward, reads that file to decide what the project is for. If vision.md is vague, the discovery step has nothing to anchor to and the task plan inherits the vagueness. The README does not publish a schema or a worked example of a vision document in the material available here, which is the weakest point in the onboarding path: you are told the file is essential but not shown what a correct one looks like. A team evaluating this should treat writing vision.md as the first real cost, before any agent runs.
SudoLang and the server framework sit at different maturity levels
SudoLang is described as a pseudocode language for prompting large language models, with clear structure, strong typing, and explicit control flow. It is a notation, not a runtime: the README does not claim an interpreter executes it. The setup instructions ask you to install syntax highlighting from the separate sudolang-llm-support repository, which confirms the tooling is editor-side. Separately, the project ships a server framework described as a composable backend for Node and Next.js, with an authentication middleware section in the table of contents, plus a utilities and component library. These are traditional JavaScript artefacts bundled under the same banner as the agent methodology. The two halves have different risk profiles. A prompt convention fails loudly when it is wrong, because the agent produces obviously bad output. A server framework with authentication middleware fails quietly if it is misconfigured. Treating them as one adoption decision is a mistake; the README presents them as one package.
Constraints that will stop some teams cold
The requirements section is unusually explicit. Node.js 16.0.0 or higher with ESM support, and a Unix/Linux shell such as bash or zsh, or Windows with WSL. That last clause rules out native Windows shells for the documented workflow, and it is stated as a requirement rather than a caveat, so a Windows team without WSL should stop reading here. The README also notes it works with any sufficiently advanced LLM and recommends Claude 4.5 Sonnet as of the time of writing, which is a moving target rather than a pinned dependency. The deeper limitation is architectural. Because the framework is a set of instructions an agent reads, its guarantees are probabilistic. Nothing in the material describes a check that fails a build when /review is skipped or when tests are not written first. Compare that to a test runner or a CI gate, which refuses to proceed. AIDD asks the agent to behave, and the README's own cited statistics about duplication and bug rates are an argument that agents do not reliably behave on their own. The framework does not resolve that tension; it documents a process and trusts the model to follow it.
Where a different tool is the better answer
If your problem is that generated code is not covered by tests, a conventional test runner with a coverage threshold in CI addresses it directly, because it fails the build on a number rather than on a prompt. If your problem is duplicated logic, a duplication detector run in CI gives you a count and a location. AIDD operates one level up: it tries to shape what the agent produces before any of those gates run. The honest comparison is that AIDD is complementary to those tools, not a replacement, and the README's framing as "the standard framework" overstates the case. For a solo developer writing a small script with an agent, the six-command chain and the vision document are overhead with no matching benefit. The framework earns its keep when multiple people are driving agents against the same repository and need a shared record of intent, which is a coordination problem rather than a code quality problem.
Licence, maintenance and what to check first
The repository is MIT licensed and not archived, with the most recent push dated 2026-06-12 and releases at v3.1.0, v3.0.0 and v2.8.0 within roughly three months of each other. That release cadence matters for a scaffold of skill files: the v3.0.0 major bump suggests the file layout changed between v2 and v3, which is exactly the kind of change that collides with local edits. The aidd-custom/ directory is the documented escape hatch for that, and anyone adopting this should put every local modification there rather than editing ai/skills/ directly. MIT means you can fork and vendor the skill files, and given that the value is in markdown rather than in a runtime, vendoring is a defensible option. This is not legal advice; read the LICENSE file in the repository. The verification step before adopting is narrow and specific: run npx aidd --help to see the real command surface, scaffold into a scratch directory with npx aidd my-project, and read ai/skills/aidd-please/SKILL.md in full. If the orchestrator's instructions match how your team already wants agents to work, the framework saves you writing them. If they do not, you are better off writing your own AGENTS.md.
Editorial conclusion
Adopt it if your team already runs coding agents in Cursor or Claude Code and keeps losing track of what the agent was asked to do; the /discover to /commit chain and the vision.md source-of-truth file are the parts worth copying even if you never run npx aidd. Do not adopt it if you are on Windows without WSL, or if you want a library you can call from application code, since this is a scaffold of markdown skills and prompt conventions. Before committing, run npx aidd --help, then npx aidd my-project in a throwaway directory and read ai/skills/aidd-please/SKILL.md end to end. That file is the orchestrator, and whether you agree with its instructions decides the whole question.
Community notes