aiadev 0.11.0

CLI for the AI-Augmented Developer framework: validates skills, scaffolds feature specs, installs presets.

AI-Augmented Developer

AI-Augmented Developer is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them.

How it works

It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it doesn't just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.

Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.

After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.

Next up, once you say "go", the implement skill takes over: it dispatches one fresh subagent per task, runs a spec compliance review and a code quality review after each, and moves forward only when both pass. The agent can run through several tasks unattended as long as the plan stays accurate — your job is to check in, not to babysit every step.

There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has AI-Augmented Developer superpowers.

Installation

Recommended — via the aiadev CLI

From v0.3 onward the supported path is the Python CLI, which renders a preset (variables substituted, files placed) into the current project:

# 1. Install the CLI (editable install from a clone, or a release tag)
pip install -e git+https://github.com/suportly/ai-augmented-developer.git#egg=aiadev

# 2. Install a preset into your project
cd your-project
aiadev install --preset lean              # framework-only pipeline
# or
aiadev install --preset django-drf-react  # full-stack web preset
# or
aiadev install --preset mobile-ops        # operational runbooks for Cloud Run + Expo

# Pick your coding IDE with --platform. All five are wired:
#   claude-code (default), cursor, codex, opencode, gemini.
aiadev install --preset lean --platform cursor
aiadev install --preset lean --platform codex
aiadev install --preset lean --platform gemini

# CI-friendly variant: every variable on the command line, no prompts.
aiadev install --preset lean --non-interactive --vars PROJECT_NAME=MyApp

# Re-run to update; drift from hand-edits is flagged as conflict
# unless you pass --force.
aiadev install --preset lean

# Preview without writing.
aiadev install --preset lean --dry-run

# Remove everything the install wrote.
aiadev install --preset lean --uninstall

# User-scope install: skills land under ~/.codex/skills/, etc. so every
# project on this machine can pick them up. Agent files and constitutions
# stay project-local (they carry project-specific variables) and are
# reported as skipped.
aiadev install --preset mobile-ops --platform codex --scope user \
    --non-interactive --vars PROJECT_NAME=Demo,APP_NAME=Demo,...

aiadev doctor then verifies the repo is in good shape.

Extensions (third-party presets)

Install presets that live in any git repo:

# Add an extension once. The repo must contain an `extension.yaml`
# at its root and a `presets/<preset-name>/` tree.
aiadev extension add https://github.com/example/rails-preset.git

# `aiadev install --preset rails` now works in any project. Built-in
# presets win on name collision; a yellow "note" reports the shadow.
aiadev install --preset rails --non-interactive --vars PROJECT_NAME=Demo

# Inspect or clean up.
aiadev extension list
aiadev extension remove rails-preset

Extensions are git URLs only — no central registry, no signing, no auto-update. Each extension add runs one git clone --depth 1 into ~/.aiadev/extensions/<name>/. Inspect any third-party extension before installing it: it can ship arbitrary skill content.

To author an extension, see the format documented in schemas/extension-manifest.schema.json and the tests/fixtures/extensions/sample-extension/ reference.

Platform-specific plugins (unchanged from v0.2)

The legacy plugin install paths still work; they drop the skills catalog into your agent without creating an install manifest.

Claude Code

/plugin marketplace add suportly/ai-augmented-developer
/plugin install ai-augmented-developer@ai-augmented-developer-marketplace

Cursor

/add-plugin https://github.com/suportly/ai-augmented-developer

Gemini CLI

gemini extensions install https://github.com/suportly/ai-augmented-developer

To update:

gemini extensions update ai-augmented-developer

Codex

Tell Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/suportly/ai-augmented-developer/refs/heads/main/.codex/INSTALL.md

Detailed docs: docs/README.codex.md

OpenCode

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/suportly/ai-augmented-developer/refs/heads/main/.opencode/INSTALL.md

Detailed docs: docs/README.opencode.md

Verify Installation

Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant skill.

The Basic Workflow

1. specify — Activates first. Turns a natural-language demand into a spec.md under specs/<branch>/, surfacing any ambiguity as [NEEDS CLARIFICATION: …] markers instead of guessing.

2. clarify — Walks the user through the clarification markers one at a time and rewrites the spec with the answers. The spec stays unapproved while any marker is unresolved.

3. plan — Turns the clean spec into a plan.md that fills the Constitution Check table, maps project structure changes, and splits the work into phases.

4. tasks — Decomposes the plan into an ordered tasks.md where each task = one failing test + one implementation + one commit, with dependencies declared.

5. implement — Dispatches one fresh subagent per task with a two-stage review (spec compliance, then code quality) before advancing. One task per commit; never skip either review.

6. analyze, checklist — Cross-checks. analyze reports drift between spec, plan, tasks, and actual code. checklist runs a category pass (security, performance, accessibility, i18n, privacy, observability).

7. test-driven-development, systematic-debugging — Invoked inside implement. RED-GREEN-REFACTOR for new work; four-phase root-cause investigation for failures.

8. requesting-code-review, finishing-a-branch — Pre-PR review and merge hygiene. Close the loop back to the spec.

The agent checks for relevant skills before any task. These are mandatory workflows, not suggestions.

What's Inside

Skills (14 generic + preset)

Pipeline

• specify — Natural-language demand → numbered spec.md with [NEEDS CLARIFICATION] markers for ambiguity.
• clarify — Surfaces those markers one at a time and rewrites the spec with the answers.
• plan — Turns an approved spec into plan.md with a mandatory Constitution Check.
• tasks — Ordered tasks.md; one task = one test + one implementation + one commit.
• implement — Fresh subagent per task with two-stage review (spec compliance, then code quality).
• analyze — Gap report between spec, plan, tasks, and code.
• checklist — Category pass: security, performance, accessibility, i18n, privacy, observability.
• constitution — Amend the framework/preset/project constitution through the documented process.

Quality

• using-ai-augmented-developer — Meta-skill that orients the agent to the catalog and skill rule.
• test-driven-development — RED-GREEN-REFACTOR cycle, strictly enforced.
• systematic-debugging — 4-phase root-cause investigation before any fix.
• requesting-code-review — Pre-PR checklist and reviewer agent dispatch.
• finishing-a-branch — PR creation, merge decision, cleanup.
• frontend-design — Production-grade UI with distinctive, non-generic aesthetics.

Stack skills (via presets)

Stack-specific skills live under presets/<preset>/skills/ and load only when that preset is active. The bundled django-drf-react preset ships:

• django-patterns — App / model / serializer / view / URL conventions.
• ai-integration — LiteLLM + Claude Agent SDK providers.
• celery-async — Background task patterns, scheduling, retries.
• autodev-pipeline — Proactive auto-development pipeline.
• deploy — Cloud Run + EAS deployment runbooks.
• run-tests — pytest backend + Jest frontend entry point.

A minimal lean preset is also available for projects with an exotic stack. See presets/catalog.json for the full list.

Commands

Skills are invoked directly by name — there are no thin command wrappers in v0.2. Earlier versions shipped /brainstorm, /write-plan, /execute-plan, /speckit, /debug; these redirected to skills with no added behavior and were removed. Call the skills themselves instead.

Agents (3 total)

• spec-document-reviewer — Validates specs for completeness, clarity, and testability
• plan-document-reviewer — Validates plans for TDD compliance, exact file paths, and step granularity
• code-reviewer — Reviews code for security, spec alignment, and quality

Philosophy

• Test-Driven Development — Write tests first, always
• Design before code — No implementation without an approved spec
• Systematic over ad-hoc — Process over guessing
• Complexity reduction — Simplicity as primary goal
• Evidence over claims — Verify before declaring success

Updating

/plugin update ai-augmented-developer

Contributing

See CONTRIBUTING.md for the full workflow (issue-first, one concern per PR, skill frontmatter rules). Bug reports and security issues follow SECURITY.md. Changes are logged in CHANGELOG.md.

Credits

This framework builds on prior work from obra/superpowers and github/spec-kit. See CREDITS.md for the full attribution list.

License

MIT License — see LICENSE file for details

Support

• Issues: https://github.com/suportly/ai-augmented-developer/issues