Getting Started

This guide takes you from installation to a verified first workflow. The native installer includes every supported harness runtime and does not require Bun or Node.js.

Quick Start

1. Install AI-DLC

macOS, Linux, or WSL:

curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.ps1 | iex

The installer adds the native aidlc command and every harness runtime. On Windows, it installs for the current account, registers the bin directory in persistent User PATH, and updates the current PowerShell process. Run it from a normal PowerShell window; one opened with "Run as administrator" gets a warning and a prompt, since installing as administrator is less safe. If another session cannot find aidlc, open a new terminal. Use -NoModifyPath to skip both PATH changes and invoke the printed direct command instead. On macOS, Linux, or WSL, apply the installer's PATH instruction if aidlc is not found.

If you cannot install a native executable or prefer to manage the project files manually, install Bun, download aidlc-copy-runtime-X.Y.Z.tar.gz from the release, and copy the complete runtime/<harness>/ directory into the project. The manual-copy path does not require the native aidlc command.

2. Configure a project

From the project root:

cd /path/to/your-project
aidlc config --harness claude
aidlc doctor

Replace claude with the harness you use:

A bare aidlc config starts the interactive setup when a terminal is available. It detects installed harnesses, provider state, runtime needs, and trust actions before writing anything.

3. Start the first workflow

Open the configured harness in the project and describe the work:

/aidlc Build a REST API for inventory management

Codex CLI uses:

$aidlc Build a REST API for inventory management

AI-DLC selects a workflow profile from the request. You can also choose one:

/aidlc express
/aidlc feature Add customer notifications
/aidlc bugfix Fix the login timeout

See Workflow Profiles for the available workflows and Your First Workflow for an annotated walkthrough.

Harness Prerequisites

Install and authenticate the host harness before opening it. The native AI-DLC runtime itself does not require Git, Bun, or Node.js, but host requirements still apply.

AWS Bedrock Setup

The Claude Code, Codex, and opencode distributions preserve the provider already configured by the user. Amazon Bedrock is an explicit option.

Provider-neutral default

AI-DLC does not select a model provider in the shipped Claude Code, Codex, or opencode project configuration. The harness keeps the provider, authentication, model, and context settings already configured by the user. Balanced reviewer agents may cap reasoning effort, but they do not pin a provider-specific model.

Configure Bedrock (optional)

Run aidlc config providers and select amazon-bedrock, or configure Claude Code directly:

1. Enable access to the configured Anthropic models in the Amazon Bedrock model catalog.
2. Provide AWS credentials through the normal SDK credential chain, for example aws configure or aws sso login --profile <profile>.
3. Use a region where those models are available.
4. Start claude and choose Amazon Bedrock at the provider prompt. You can run /setup-bedrock later to change the account or region.

Keep credentials and personal overrides out of the shared .claude/settings.json. Put them in .claude/settings.local.json or the standard AWS credential files.

To keep the provider already selected in Claude Code, choose keep current in aidlc config providers (or pass --provider current). To record a different Claude Code-supported provider explicitly, run aidlc config providers --provider other --yes. This removes old AI-DLC-owned Bedrock overrides from the shared project settings and leaves the manual setup step pending. Complete that provider's authentication flow, then run aidlc config providers --acknowledge --yes to mark the step done. See the Claude Code authentication guide.

For IAM detail, model access, SSO, and regional troubleshooting, see Claude Code on Amazon Bedrock and the Amazon Bedrock documentation.

MCP Servers (optional)

Claude projects can install the shipped MCP defaults during config:

aidlc config --harness claude --mcp defaults

Use --mcp none to omit them. The default set is:

The four AWS servers require uvx and use the standard AWS credential chain.

Every agent in the Claude session inherits available MCP servers. Missing credentials make a server unavailable but do not block a workflow. Never put secrets in the committed .mcp.json.

Configuration and Trust

aidlc config is local-only and transactional. It writes the selected harness runtime, creates the aidlc/ workspace, merges managed project integrations, and records an ownership baseline for later refreshes.

Preview any change:

aidlc config --dry-run

After config, complete any action named in its output:

In Kiro IDE, the aidlc agent appears in the agent picker only after you trust the folder and reload the window: if the Restricted Mode banner shows, select Manage on it, then Trust, and run Developer: Reload Window (see First run).

Run aidlc doctor after completing the action. It reports runtime, project, provider, hook, trust, and workflow-state problems with a remediation command.

Updating

aidlc update updates the machine runtime. It does not rewrite configured projects. Refresh each project between workflows:

aidlc update
cd /path/to/your-project
aidlc doctor
aidlc config

Config preserves project-owned content and refuses to refresh while a workflow is active. Projects using plugins should run /aidlc plugin sync after an engine refresh.

For version selection, project pins, offline installation, mirrors, custom CAs, release authentication, automation, and uninstall, see Install and Lifecycle.

What Config Creates

A configured project contains the harness integration plus an aidlc/ workspace. The first workflow creates an intent record under:

aidlc/spaces/<space>/intents/<YYMMDD>-<label>/

That record contains workflow state, audit shards, questions, decisions, and stage artifacts. Team knowledge and learned rules live at the space level so later intents can reuse them.

See Spaces and Intents for the layout and State and Audit for the recorded evidence.

Troubleshooting

Start with:

aidlc doctor

Then use Troubleshooting for hooks, provider access, approval gates, stale state, and diagnostics. Harness-specific setup problems belong in the matching harness guide.

Next Steps

• Onboarding: A Guided First Week - the mental model and a guided five-run path for first-time teams
• Workflow Profiles - choose the right workflow
• Your First Workflow - follow a complete run
• Spaces and Intents - understand project state
• Interaction Modes - work with questions and gates
• Install and Lifecycle - manage the native runtime