Skip to main content

Installation

Time-to-first-value: A CTO's team is running ADLC in one command. Prerequisites, install options, and multi-tier MCP setup follow — collapse the raw shell to focus on the outcome first.

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
For engineers: Consumer Setup (5 minutes)

Consumer Setup (5 minutes)​

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

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

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

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:

FileRolePurpose
.mcp.jsonActive runtimeLoaded by claude --mcp-config .mcp.json — minimal servers, fast startup. Generated from active persona by SessionStart hook.
.claude/mcps/.mcp-enterprise.jsonSSOT (Single Source of Truth)All 33 MCP server configs with _profiles and _access tags. Edit here; profiles regenerate via scripts/derive-mcp-profile.py.
.claude/mcps/profiles/{persona}.jsonPersona profiles (generated)Role-specific MCP subsets — each persona gets exactly the servers they need. Do not edit by hand; regenerate from SSOT.

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​

Profiles in .claude/mcps/profiles/ are generated from the SSOT .claude/mcps/.mcp-enterprise.json. Do not edit profile files directly — edit the SSOT and re-run the derive script. Reference: .claude/mcps/MATRIX.md.

PersonaServersRole
minimal (default)1Context7 docs only. Smallest context footprint
reviewer6AWS review (API, cost, network, ECS, CloudFormation) + Context7
executive4CxO view: Vizro dashboards, Azure, AWS cost + Context7
security-engineer2Azure security review + Context7
delivery2Jira and Confluence (Atlassian Rovo + Atlassian tools)
portfolio-enterprise9Enterprise portfolio: Atlassian, Azure, AWS (API, cost, network, ECS, CloudFormation) + Context7
portfolio-startup5Startup portfolio: Atlassian tools, AWS API and cost, Slack + Context7

To switch personas:

# HITL terminal — start Claude Code with a specific profile
claude --mcp-config .claude/mcps/profiles/reviewer.json --strict-mcp-config
# Replace "reviewer" with any persona: minimal, reviewer, executive, security-engineer, delivery, portfolio-enterprise, portfolio-startup

# Default (no flag) = minimal (1 server)

Adding New MCP Servers​

  1. Add the server to .claude/mcps/.mcp-enterprise.json (the SSOT)
  2. Tag with _profiles: ["persona-A", "persona-B", ...] for membership
  3. Regenerate profiles: python3 .claude/mcps/scripts/derive-mcp-profile.py --all
  4. Validate: python3 .claude/mcps/scripts/derive-mcp-profile.py --check (exit 0 = no drift)

Verify Installation​

# Check framework version
cat VERSION                # -> 3.8.0

# Audit skills health
task skills:audit          # -> STATUS: HEALTHY (88/100)

# Confirm every MCP config still matches the SSOT (no drift)
task mcp:profile:check     # -> All 7 profiles, the plugin core set, and every project, tenant, and slice config match SSOT