Get Started

Your first work

This walkthrough takes you from a fresh AID install to a completed, delivered work item. It follows the full path — the complete six-phase pipeline. If your change is small and well-scoped, see Lite path quickstart instead.

Prerequisites: aid is installed and on your PATH. See Install AID if you haven’t done that yet.

1. Configure AID (once per project)

Open a terminal in your project root.

This is the git repository where you want to use AID. All aid commands operate on the current directory.
Add your AI tool profile.
Terminal window
```
aid add claude-code
```
Replace claude-code with your tool’s canonical id: codex, cursor, copilot-cli, or antigravity. This installs the AID skills and agents into the correct location for your tool.

Run aid status to confirm the install.
Scaffold the Knowledge Base.

In your AI coding tool, run the /aid-config skill (it was installed by the previous step):
```
/aid-config
```
This scaffolds the .aid/ directory — the Knowledge Base root — and records your project defaults. Run it once per project; re-running it is safe and non-destructive.

2. Scope your work: Discover and Describe

Discover (brownfield projects only).
```
/aid-discover
```
Scans the codebase and builds the Knowledge Base under .aid/knowledge/. This phase is mandatory for existing codebases; skip it for greenfield projects.

When Discover reaches its APPROVAL state, it presents a summary (overall grade, Q&A totals, fix cycles, remaining minor issues) directly in the conversation and asks you to confirm the Knowledge Base under .aid/knowledge/ is ready for the next phase. Approve it before moving on.
Run the Describe skill.

In your AI tool, invoke:
```
/aid-describe
```
Describe is a full-path-only skill — every run proceeds through all the phases below; there is no lite branch inside it. Answer the intake questions about your work item — what you want to change, what’s in scope, and how it should be built.

If your change is small and well-scoped, you don’t need this walkthrough at all: invoke the matching shortcut (/aid-fix, /aid-create-api, …) or ask /aid-triage instead, and follow the Lite path quickstart.
Review the REQUIREMENTS document.

At the end of Describe, the agent produces a REQUIREMENTS.md in .aid/. Read it, confirm it captures your intent, and approve to advance.

3. Walk the phases

Each phase produces an artifact. Read it, approve it, and the next phase begins.

Specify.
```
/aid-specify
```
Writes a grounded specification (SPEC.md) from the Knowledge Base and REQUIREMENTS. Review the spec carefully — this is where “what we’re building” is locked down.

Approve the spec to advance to planning.
Plan.
```
/aid-plan
```
Sequences your feature specs into a delivery roadmap (PLAN.md) — each delivery a functional, standalone MVP — and creates a deliveries/delivery-NNN/ folder per delivery with its own BLUEPRINT.md (the delivery definition: scope, gate criteria, dependencies) and STATE.md (delivery lifecycle). Review the plan for scope, dependencies, and sequencing.

Approve the plan to advance to detailing.
Detail.
```
/aid-detail
```
Breaks each delivery into small, typed tasks. Each task gets its own deliveries/delivery-NNN/tasks/task-NNN/ folder with a DETAIL.md (the task definition: type, acceptance criteria, scope, dependencies) and a STATE.md (task lifecycle). Review and approve.
Execute.
```
/aid-execute
```
Implements the tasks in sequence, grades its own output, and loops until each task passes. You review each task’s output and approve advancement. Repeat until all tasks are done.

4. What you get at each gate

| Phase | Artifact | Gate action | |-------|----------|-------------| | Discover | Knowledge Base (.aid/knowledge/) | Approve discovery | | Describe | REQUIREMENTS.md | Confirm requirements | | Specify | SPEC.md (per feature) | Approve spec | | Plan | PLAN.md + deliveries/delivery-NNN/BLUEPRINT.md | Approve plan | | Detail | deliveries/delivery-NNN/tasks/task-NNN/DETAIL.md | Approve each task | | Execute | Code + test output | Review, approve, or request revision |

Every gate is a human decision. The pipeline never advances without your explicit approval.

Next steps

Lite path quickstart — for small changes that skip the middle phases.
Installation guide — if you need to reinstall or switch channels.
Methodology — the full philosophy and decision logic behind each phase.

Report an issue with this page →