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. Generated from active persona by SessionStart hook.
.claude/mcps/.mcp-enterprise.json	SSOT (Single Source of Truth)	All 24 MCP server configs with _profiles membership tags. Edit here; profiles regenerate via scripts/derive-mcp-profile.py.
.claude/mcps/profiles/{persona}.json	Persona 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.

Persona	Servers	Role
minimal (default)	1 (context7)	Default — non-MCP work (docs, rules, planning). Smallest context footprint.
reviewer	9	Read-only AWS audit, code-reviewer, security review
developer	3	python-engineer, developer-experience-engineer (GitHub + Playwright)
architect	23	cloud-architect design sessions (full superset)
executive	5	CxO read-only (observability + brave-search + context7)
analyst	2	finops-engineer, data-engineer (Cost Explorer + context7)
platform-engineer	6	platform-engineer (GitHub + Backstage + Playwright + cloud)
product-manager	3	product-owner, business-analyst (Atlassian + context7)
security-engineer	6	security-compliance-engineer (cloud read + Azure security)
operator	15	sre-engineer, itsm work (cloud read + Atlassian write)

To switch personas:

# HITL terminal — set before starting Claude Code
export ADLC_MCP_PROFILE=architect    # or any persona name above
# SessionStart hook activates the profile → .mcp.json
# Mid-session switch requires /clear

# Default (no env var) = 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
task framework:version

# Validate constitutional compliance
task spec:validate

# Audit skills health
task skills:audit