Getting-started guide

Get Started — your first SDD cycle in one day

From installation to your first PR locked by the Drift Lock: this guide condenses everything you need to switch to SDD Mode. One command to install, one morning to frame, one afternoon to ship your first spec-anchored feature.

Prerequisites

• Node.js 18+ — the aiad-sdd CLI runs through npx, no global install required;
• an AI development agent — Claude Code first and foremost, but also Cursor, GitHub Copilot, Codex, Gemini or Kiro: since aiad-sdd 1.12, SDD Mode is multi-runtime (Kiro since 1.19.0), with rules emitted for each tool from a single source (npx aiad-sdd emit-rules);
• a Git repository — new or existing, both paths are covered below.

1-minute install

npx aiad-sdd init

This single command installs into your project: the .aiad/ structure (PRD, ARCHITECTURE and AGENT-GUIDE templates, intent and SPEC indexes), the 4 Tier 1 governance agents (AI-ACT, RGPD, RGAA, RGESN) complemented by the CRA agent for software products, the 33 slash commands (17 /sdd + 16 /aiad) grouped under the /sdd, /aiad and /aiad-help routers, the 9 reusable skills, and a CLAUDE.md configured with the cycle, the documentation hierarchy and the absolute rules.

Then, inside your agent, run /sdd init. The command first displays a recommended-restart message: to load all the freshly installed commands into the session, restart the agent (/exit, then a new session) before continuing. You can carry on without restarting, but some skills may not be available.

Framing: three foundational artifacts

/sdd init guides the interactive writing of the three documents that structure everything else — and offers two dedicated discovery assistants:

• /sdd prd — the PRD assistant asks the questions a Product Manager would: vision, users, outcomes. The PRD is only injected during the framing phase, never during development;
• /sdd arch — the ARCHITECTURE assistant asks the questions an architect would: stack, patterns, constraints. The document is injected in condensed form (~500 tokens) into every agent session;
• the AGENT-GUIDE — the agent's permanent context: absolute rules, conventions, then over the iterations the Lessons Learned and Human Learnings.

Your first cycle, step by step

The SDD cycle has seven steps — none is ever skipped. For a well-bounded feature, the whole thing fits in a single day:

Adopting it on an existing project

You don't need to start from scratch. /aiad init performs a progressive bootstrap: it analyses the actual codebase and generates the initial artifacts from the project's current state — the ARCHITECTURE from the observed patterns, the AGENT-GUIDE from the conventions in place. Zero disruption: the SDD cycle first applies to new features, and SPEC coverage expands iteration after iteration.

When a new member joins the team, /aiad onboard generates a contextualised briefing from the artifacts (PRD, ARCHITECTURE, active SPECs, Lessons Learned) with a prioritised reading list.

Dual-mode: --guided and --fast

Every command supports two modes. --guided is the beginner mode: one question at a time, concepts explained (SQS, Drift Lock…), examples offered — use it the first time. --fast is the expert mode: inputs in one block, direct output. With no flag, the agent auto-detects: an empty or nearly empty .aiad/ structure → guided, otherwise → fast. For your first day, stay in --guided.

Tips for the first iteration

• Start small — pick a well-bounded feature, not the quarter's structural overhaul;
• one atomic SPEC only — one agent session = one SPEC. It is the Context Engineering Budget rule, and the best protection against context rot;
• measure from the very first iteration — SQS, detected drifts, first-time success: metrics only have value with a trend, and the trend starts at the first data point.

Staying up to date

npx aiad-sdd update

Updates the commands, skills and governance agents to the package version, without touching your .aiad/ artifacts (PRD, Intents, SPECs, metrics). In CI, npx aiad-sdd update --check fails if the project diverges from the package. Next release — upcoming: update will back up any governance agent you have adapted locally (AIAD-X.md.bak-YYYY-MM-DD) before overwriting it — see the CLI reference.

Checking your maturity

npx aiad-sdd status

The command computes an SDD maturity score from 0 to 5: artifact freshness, active SPECs and their SQS, governance enabled, immediate recommendations. Run it after every iteration — the score's progression tells the adoption story better than any gut feeling.