Installation

Prerequisites

Before starting, ensure you have:

• Node.js 20+ — for CDK projects and the ADLC CLI
• Docker 24+ — for DevContainer and local validation
• Git 2.x — for submodule management

Consumer Setup (5 minutes)

Git Submodule (Recommended)

# Add ADLC framework as submodule
cd your-project
git submodule add https://github.com/1xOps/adlc-framework.git .adlc

# Create symlinks for Claude Code
ln -s .adlc/.claude .claude
ln -s .adlc/.specify .specify

# Initialize submodule
git submodule update --init --recursive

Symlink (Development)

# For local development with symlink
ln -s /path/to/adlc-framework .adlc
ln -s .adlc/.claude .claude
ln -s .adlc/.specify .specify

Framework Management Tasks

Add these to your Taskfile.yml:

version: '3'

tasks:
  framework:version:
    desc: Show ADLC framework version
    cmds:
      - |
        cd .adlc
        VERSION=$(git describe --tags 2>/dev/null || git rev-parse --short HEAD)
        echo "ADLC Framework: $VERSION"

  framework:update:
    desc: Update framework to latest
    cmds:
      - git submodule update --remote .adlc
      - cd .adlc && git checkout main && git pull

  framework:dev:
    desc: Switch to symlink mode for development
    cmds:
      - rm -rf .adlc
      - ln -s /path/to/local/adlc-framework .adlc

  framework:prod:
    desc: Switch back to submodule mode
    cmds:
      - rm -f .adlc
      - git submodule update --init .adlc

DevContainer Setup

Open in VS Code with DevContainer:

1. Install "Dev Containers" VS Code extension
2. Open project folder
3. Press F1 → "Dev Containers: Reopen in Container"

The DevContainer includes:

• Terraform 1.14.3
• AWS CDK 2.1033.0
• LocalStack endpoint pre-configured
• 30+ DevOps tools

Fastest way to get started

The DevContainer is the fastest path to a working ADLC environment — all tools pre-installed, no manual configuration required. Run F1 → Dev Containers: Reopen in Container and you are ready in under 2 minutes.

MCP Server Configuration

ADLC uses a three-tier MCP architecture. Each tier serves a different purpose:

File	Role	Purpose
.mcp.json	Active runtime	Loaded by claude --mcp-config .mcp.json — minimal servers, fast startup
.claude/mcps/profiles/enterprise.json	Central registry	ALL available MCP servers — reference catalog for the full platform
.claude/mcps/profiles/{persona}.json	Persona profiles	Role-specific MCP subsets — each persona gets exactly the servers they need

Active Runtime (.mcp.json)

The root .mcp.json is what Claude Code loads at startup. Keep it minimal for fast session start:

# Standard alias for ADLC sessions
alias ccm="claude --dangerously-skip-permissions --chrome --mcp-config .mcp.json"

Persona Profiles

Each profile in .claude/mcps/profiles/ provides the MCP servers a specific role needs:

Profile	Persona	Key Servers
pm.json	Product Manager	GitHub, Atlassian (Rovo + CRUD), Context7, Vizro
cloudops.json	CloudOps Engineer	AWS (Cost Explorer, CloudWatch, IAM, Config)
finops.json	FinOps Analyst	Cost Explorer, Billing
security.json	Security Engineer	IAM, CloudTrail, Defender
executive.json	CxO / Manager	Reporting dashboards, Vizro
dev.json	Developer	GitHub, Context7
platform.json	Platform Engineer	Terraform, K8s, CloudFormation
aws-readonly.json	Read-only Operations	AWS read-only MCP servers
enterprise.json	Full Platform	All 24+ servers (superset)

To use a persona profile, copy it to .mcp.json or reference it:

# Switch to PM persona
cp .claude/mcps/profiles/pm.json .mcp.json

# Or use enterprise profile for full access
cp .claude/mcps/profiles/enterprise.json .mcp.json

Adding New MCP Servers

1. Add the server to enterprise.json first (central registry)
2. Add to relevant persona profiles that need it
3. If it should be active by default, add to .mcp.json

Verify Installation

# Check framework version
task framework:version

# Validate constitutional compliance
task spec:validate

# Audit skills health
task skills:audit