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. If a new shell cannot find aidlc, apply the PATH instruction printed by the installer.

If you prefer to manage the project files manually, install the matching native aidlc command, download aidlc-runtime-X.Y.Z.tar.gz from the release, and copy runtime/<harness>/ into the project.

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 distribution ships configured for Amazon Bedrock. Codex also ships with a Bedrock provider default; other harnesses use their own provider configuration.

Why Bedrock is the default

AI-DLC needs a predictable runtime baseline across the conductor and its tier-pinned subagents. Bedrock lets the distribution pin exact global inference profiles and context variants, avoiding silent model-alias differences between machines. It also uses the standard AWS SDK credential chain and IAM controls, so teams do not need to commit provider keys to a project.

This is a distribution default, not a methodology requirement. AI-DLC does not call the Bedrock API directly and remains provider-independent.

Configure Bedrock

Before the first Claude Code run:

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. The shipped default is us-east-1.
4. Start claude and choose Amazon Bedrock at the provider prompt. You can run /setup-bedrock later to change the account or region.

The shipped Claude settings map these aliases:

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 use another Claude Code-supported provider, remove or replace the Bedrock environment mappings in .claude/settings.json and any higher-precedence .claude/settings.local.json, then complete that provider's Claude Code authentication flow. 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:

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

• 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