Skip to content

tutorial · 5 steps

Getting Started with AIDLC

Learn how to set up AIDLC in your project and run your first lifecycle session.

  1. 1. Install and Set Up AIDLC

    AIDLC works with Claude Code, Cursor, Windsurf, Kiro, Codex, and GitHub Copilot. One command sets everything up — run it interactively to choose platforms, scope, and a default template, or pass --platform to skip the prompts:

    # Interactive setup — choose platforms, scope, and default template
npx @rasensio/aidlc init

# Or set up directly for a single platform, no prompts
npx @rasensio/aidlc init --platform claude-code

    Either way, init creates a .aidlc/ directory with the canonical lifecycle skills, plus platform-native activation files (for example .claude/skills/ for Claude Code or .cursor/rules/ for Cursor). It also scans your codebase and generates context documents under .aidlc/context/ so your AI assistant starts with real knowledge of the project.

  2. 2. Choose a Workflow Template

    Templates define which lifecycle phases apply to a piece of work, so a one-line fix doesn't go through the same ceremony as a new feature. AIDLC ships with five:

    • full-feature — the full lifecycle from ideation through maintenance, with adversarial review gates on requirements and design.
    • quick-feature — standard scope, from requirements through deployment.
    • bugfix — like quick-feature but with reproduction steps and no design phase.
    • spike — research and exploration, ending in a findings document.
    • micro-task — implementation and testing only, for small changes.

    For your first session, try the full-feature template — it exercises every phase, so you see the whole process once.

  3. 3. Start a Session

    Start a lifecycle instance from the template. The instance gets its own state directory under .aidlc/state/, tracking which phase is active and which artifacts are complete:

    aidlc start full-feature --name my-feature

    The first phase for a full-scope instance is ideation. When you open your AI assistant in this project, the aidlc-ideation skill activates and guides it to explore the problem space and produce an idea.md artifact before any code is written.

  4. 4. Check Progress and Continue

    Each phase produces required artifacts, and phase transitions are gated on their completion. Three commands drive the day-to-day loop:

    aidlc status                  # progress across all active instances
aidlc continue                # resume the active instance at its next step
aidlc transition my-feature   # evaluate gates and advance to the next phase

    If a transition is blocked, the output lists exactly what's missing — incomplete artifacts, unresolved review findings, or phases that must finish first. Your AI assistant reads the same state, so aidlc continue in a fresh session picks up precisely where the last one left off.

  5. 5. Enforce Gates in CI

    Gates aren't just advisory — aidlc gate <instance> <phase> exits with code 0 when a phase is complete and 1 when it isn't, so your pipeline can block merges until the lifecycle catches up. This sample GitHub Actions workflow is inlined from the repository at build time, so it always matches the current release:

    # Contents inlined from ci/aidlc-gate.yml at build time

    That's the whole loop: set up once, pick a template per piece of work, and let the gates keep quality honest. Browse the rest of the docs to see what each phase skill does in detail.

    Ready for the rest of it? The deep dive is eight short chapters covering everything past this first session — cost, the notes it keeps about your code, working alongside somebody else, and why any of it is shaped this way.