Hands-on tutorial for AIDA (aida-cli), built in the spirit of
rustlings.
aida-tutor is a generalized AIDA launchpad with Help / Tutorials as one
of its paths:
aida-tutor onboard— a 15-minute first-contact tour: initialize a scratch project, capture one requirement, trace code to it, commit it, and show the link back through AIDA.- The 41-exercise track — the fuller workflow: project setup, capture, trace comments, AIDA-format commits, docs, search/status, push/pull, the distributed store, roles and queues, relationships, scoped sessions, review, plans, store audit, and MCP.
The tutor verifies your work by inspecting on-disk state and selected command output. It never edits your exercise files. If a verifier passes, you actually did the thing.
git clone <this repo>
cd aida-tutor
./run.sh # AIDA launchpad: agent, status, shell, help
./run.sh shell # direct `aida>` command shell
./run.sh commands # browse colorized help for all AIDA commands
./run.sh commands queue # start with a filtered command list
# choose Help from the launchpad for the tutorial menu
./run.sh onboard # full onboarding lesson
./run.sh next # terse next action
./run.sh reset --yes # bootstrap workspace/
./run.sh show # see the current exercise
./run.sh hint # get a one-paragraph nudge
./run.sh verify # check your work
./run.sh list # see all exercises + state
./run.sh progress # e.g. 5/41 done - 12%The launch banner is configurable in .aida-tutor.toml:
banner = "shimmer" # "static", "shimmer", or "off"
logo = "pyramid" # "pyramid" or "arch"shimmer is the default. AIDA_TUTOR_BANNER overrides the file setting for
one invocation, and --logo arch selects the Rust port of shimmer.py's
metallic arch for that invocation.
The launchpad's shell option accepts normal AIDA commands, for example
list, history, or show FR-1; type exit to return to the launchpad.
The help option opens the interactive Help / Tutorials menu.
Choose Commands under Help / Tutorials to browse the installed AIDA's
command reference, sorted alphabetically by full command path. Type to filter
command names, descriptions, and flags;
use up/down to select, Page Up/Page Down to move a page through the list,
and Enter to open help. In a help page, left/right
moves through the filtered results, up/down scrolls, and Page Up/Page Down
scrolls a page. Esc returns to the list with your filter and selection intact;
Esc from the list exits. Ctrl-U clears the filter and Ctrl-C exits anywhere.
Hidden commands are included and marked [hidden]. Headings, flags, values,
and examples use distinct colors, respecting NO_COLOR.
The browser reads aida help commands --hidden --json and loads each
command's --help on demand, caching pages for the current visit. It needs
an AIDA version supporting that catalog command. It does not depend on a
checkout of AIDA or its golden snapshot. When piped, commands prints the
filtered catalog without entering the interactive screen.
AIDA's upstream aida-cli-lib/src/tests/golden/cli_help_snapshot.txt is a
generated test fixture covering help and the command catalog. Maintainers
regenerate it from the AIDA repository with
AIDA_UPDATE_SNAPSHOTS=1 cargo test -p aida-cli-lib story_1728_command_registry
and review the diff. The fixture deliberately disables color for stable
comparisons; the tutor styles live help for reading.
You'll need aida on PATH for the exercises themselves. aida-tutor
spawns it as a subprocess to give you the real CLI surface.
For a new production project, the normal path is full git-canonical init:
mkdir my-project
cd my-project
aida init --git-init --name my-projectIf the repo already exists, run aida init from the repository root and
review the scaffolded files like any other change. Current AIDA scaffolds
the requirement store, local cache, MCP config, agent instructions, skills,
roles, and commit hooks. See
docs/aida-setup-flows.md for the new-project
and existing-project checklists.
aida init --minimal is a quick markdown-only trial. It is useful for a
first look, but it does not enable the full store, MCP, hooks, skills, or
agent workflow until you run full aida init.
aida-tutor/
├── Cargo.toml
├── README.md you are here
├── CLAUDE.md project context for AI agents
├── AGENTS.md Codex / MCP-compatible agent guidance
├── content/ exercise descriptions (markdown — edit freely)
├── docs/ maintainer notes and setup guides
├── src/ Rust binary
│ ├── main.rs CLI dispatch
│ ├── exercise.rs trait + verify result types
│ ├── exercises/ one module per exercise (verifier + hint)
│ ├── verify.rs on-disk state inspection helpers
│ └── progress.rs progress persistence
├── .aida/ tutor's own AIDA store cache/config
├── .aida-store/ orphan worktree for the tutor's requirements
├── workspace/ where YOU work the exercises (gitignored)
└── .aida-tutor-progress.toml your completion record
- Write the description as
content/NN-slug.md. - Implement the verifier as
src/exercises/eNN_slug.rs. - Register it in
src/exercises/mod.rs. - File it as a STORY in the tutor's own AIDA store:
aida add --type story ....
The principle (PRIN-1, in this repo's store) is that verifiers inspect, never patch. Read the workspace, never write to it.
MIT OR Apache-2.0