Agentic Engineering Framework

A modular, vendor-neutral standard for how autonomous coding agents should operate within software engineering teams. Drop the parts you need into any project, with any capable agent, in any language.

Adding ADW to a repository? Start with Consuming the Framework — the four-step contract: install the package, adws init, pin the version, add the drift gate. Your repo gets three files, not three hundred.

Already onboarded and learning the workflow? See the day-to-day guide.

Key Features

• Single-step installation — Install, auto-detect, and configure in one command (uvx adws init)
• Multi-language detection — Python, JavaScript, Rust, Go, Ruby, Java, Solidity
• GitHub integration — Create issues, generate plans, track progress
• Git worktrees — Parallel development with isolated branches
• Slash commands — Claude Code workflow commands, projected at the repo pin
• Vendor-neutral — Use any AI coding agent with the same workflow
• Structured logging — JSON/text log formatters with correlation IDs for request tracing
• Centralized configuration — Pydantic Settings with ADW_ prefix and validation
• Secret scrubbing — Automatic detection and redaction of API keys, tokens, passwords
• Provider health checks — Built-in provider availability and response time monitoring
• Isolated execution (ISO) — SDLC workflows run in isolated git worktrees with unique ports
• Persistent state — File-based state management across workflow stages
• Framework modules — Reusable adw_modules/ for agent execution, git ops, worktree management

Design Principles

Quick Start (30 Seconds — Tier 1)

Prerequisites

• uv — required, not optional. Every workflow script and agent hook is a PEP 723 script run via uv run; pip cannot substitute because it has no script runner. Install with curl -LsSf https://astral.sh/uv/install.sh | sh
• Python 3.10+
• Git

Run adws health at any time to verify all of the above.

What changed

The framework ships as the adws package; its version is the one in pyproject.toml. Every release and what it changed is in docs/changelog.md (adws standards show changelog from an installed package).

Option A: Install from PyPI (Recommended)

The adws CLI is published on PyPI. With uv there is nothing to set up — no virtual environment needed:

# 1. Initialize ADW in your project (one-off, nothing installed)
cd your-repo/
uvx adws init

# Or install the CLI permanently:
uv tool install adws     # or: pipx install adws, or: pip install adws
adws init

# 2. Fill in your environment variables
$EDITOR .env

# Done. Your agent now has project context and a work standard.

adws init auto-detects your project (language, framework, paths) and writes only your project's own files (AGENTS.md, manifest.yml, .env, .mcp.json) plus machine-local .claude/ projections. The framework content itself (docs, skills, adapters) stays inside the installed package and is resolved from there — read it with adws standards list.

Adding this to a real repository? Read docs/consuming-the-framework.md — why the framework is consumed as a pinned package rather than copied in, what lands in your repo (three files) versus what stays in the package, and the four onboarding steps: init, pin, drift gate, gitignore.

Option B: Work on the framework itself

git clone https://github.com/Superlogic/AgenticEngineeringFramework.git
cd AgenticEngineeringFramework && uv venv && uv pip install -e . && pytest adws/tests/

An editable install of this checkout, for changing the framework. It is not an installation method for a project: the pre-2.1.0 source installer (install.sh, which cloned this repo into a project's .adws/) was removed in 3.0.0 — projects consume the pinned package (Option A).

Option C: Manual Copy (Minimal)

# `adws init` writes both files for you — this is the manual equivalent.
# No CLI exposes templates/, and this repository is private, so fetch them with
# an authenticated client (`gh auth login` first):
gh api repos/Superlogic/AgenticEngineeringFramework/contents/templates/AGENTS.md \
  --jq '.content' | base64 -d > AGENTS.md
gh api repos/Superlogic/AgenticEngineeringFramework/contents/templates/manifest.yml \
  --jq '.content' | base64 -d > manifest.yml

# Then fill in the CUSTOMIZE sections
$EDITOR AGENTS.md

That's minimum viable adoption: your agent reads AGENTS.md for project context and follows the lifecycle described in adws standards show workflow. You will not get slash commands, hooks or the drift gate this way — for those, use Option A.

Using Claude Code? After installation, use slash commands like /prime, /feature, and /implement for guided workflows.

Installation

How It Works

The adws CLI ships with the complete framework bundled inside the package. Running adws init in your project:

1. Auto-detects your project type from existing config files (pyproject.toml, package.json, Cargo.toml, …)
2. Populates manifest.yml and AGENTS.md with the detected values
3. Generates .claude/ projections for detected agent tools — machine-managed copies of the packaged workflow commands (adapters/claude-code/projected-skills.txt — the procedure skills such as /prime and /pr-review come from the aef-engineering marketplace plugin since 3.0.0) and hooks, refreshed on every adws init/adws upgrade (and, in Claude Code, at session start whenever the version stamped in the manifest no longer matches the repo's pin — see docs/hooks.md), pruned when a skill disappears upstream, and gitignored via a generated .gitignore manifest inside each directory. They are copies rather than symlinks on purpose: a symlink into uv's ephemeral cache dangles after uv cache clean, and a dangling hook fails open — silently disabling the pre_tool_use guard. Skills you write in your own skills/ get relative, committable symlinks and take precedence over the packaged ones

Installation Options

Core and Extras

pip install adws installs a core package, and the core runs every command. The orchestrator, the webhook server and the pollers are PEP 723 scripts that adws launches with uv run, which resolves their dependencies at launch, so the environment adws is installed into never needs them. The extras are not gates on functionality: they add those dependencies to that environment, for running the subsystems' test suites with pytest or importing them as libraries.

adws health lists which extras are installed; a missing one is informational, never a failure. See docs/packaging.md.

Authentication

Every integration accepts either OAuth or an API key, resolved in one place with consistent precedence — an explicit credential always beats an ambient CLI session:

Setting none of them and relying on an interactive claude login is fully supported. Run adws health to see which method resolved. See docs/auth.md.

Requirements

• uv — required. adws health fails without it. The workflow scripts (adw_plan_build.py, adw_*_iso.py), the orchestrator engine, the pollers, and the agent hooks in .claude/hooks/ all declare their dependencies as PEP 723 inline metadata and launch via uv run. pip installs the adws CLI package but cannot run those scripts
• Python 3.10+ (any install method)
• Git (for repo detection and operations)
• GitHub CLI (gh) — optional, for PR/issue operations
• Node 18+ — optional, for the Playwright MCP E2E stage (npx @playwright/mcp)
• Virtual environment — only needed for the pip method

What Gets Installed

Written into your repo — yours to edit and commit:

Generated by the adapters (run when agent tools are detected) — machine-local, regenerated on every adws init/adws upgrade, and gitignored via a .gitignore manifest the adapter writes inside each directory:

What is not written into your repo. docs/, skills/, adapters/, scripts/ and ai_docs/ stay inside the installed adws package — read the docs with adws standards list / adws standards show <doc>, and the skills reach your tools as the projections above. If those directories exist at your repo root they are pre-2.1 vendored leftovers and adws doctor will flag them. (specs/ is different again: it is yours, created by /feature, /bug and /chore — the framework never writes or removes it.)

Note on slash commands: .claude/commands/ is generated artifacts — never edit them. Framework skills come from the installed package; your own live in your repo's skills/*/SKILL.md and win on name collisions. To regenerate after adding a skill:

adws upgrade   # re-runs the adapters for every detected tool

(Working inside the framework repo itself, you can still call bash adapters/<tool>/generate.sh directly.)

Upgrading

Upgrading is always two steps: update the CLI, then refresh the framework files in your repo. Updating the CLI alone does not change any file in your project. See docs/upgrading.md for the full guide.

PyPI installs:

uv tool upgrade adws      # or: pipx upgrade adws, or: pip install -U adws
adws upgrade              # restamp + regenerate the projections in your repo

The consumer contract: adws doctor

The drift gate ships inside the package, so it upgrades with your pin. One line in consumer CI:

uvx --from adws==<pin> adws doctor --strict   # non-zero exit on any drift

It flags vendored framework trees (adws/, adapters/, skills/, …), local copies shadowing shipped standards docs, legacy or out-of-sync command projections, committed machine-managed files, and a missing/stale framework_version stamp. Without --strict it reports the same findings as warnings (exit 0) plus environment checks.

adws upgrade updates the framework_version stamp and regenerates the machine-managed .claude/ projections — framework content itself lives in the installed package (AITOK-766), so upgrading the package upgrades every doc, skill, and hook at once. It never touches user-owned files: your AGENTS.md, manifest.yml (except its framework_version stamp), .env, and specs/ content stay exactly as you left them. Run adws status to see whether your project's stamp is older than the installed CLI.

Re-running adws init on an initialized project is a reset, not an upgrade: it replaces AGENTS.md/manifest.yml with fresh templates (after writing timestamped .backup copies) but always preserves an existing .env.

Docker

No local Python, Node.js, git, gh, uv, or Claude Code CLI needed — just Docker:

cp .env.example .env    # fill in GITHUB_PAT, ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN), ...
docker compose up -d              # orchestrator dashboard + issue-sync + GitHub cron poller
docker compose run --rm cli init  # ad-hoc CLI usage against the repo mounted at /workspace

See docs/docker.md for the full guide, including OAuth-based Anthropic auth and Linear polling.

Uninstalling

Remove only what the framework wrote — see What Gets Installed.

⚠️ Do not delete docs/, scripts/, skills/ or specs/. In a real project those are yours, and specs/ holds every plan /feature, /bug and /chore has ever written. The framework does not create them (a pre-2.1 install may have left framework copies there — review before removing anything).

# 1. Files `adws init` created
rm -f AGENTS.md manifest.yml .mcp.json playwright-mcp-config.json

# 2. Machine-local projections (each dir's generated .gitignore lists what adws manages)
rm -rf .claude/commands .claude/hooks

# 3. Runtime state (trigger and dashboard pid files)
rm -rf .adws/

# 4. The CLI itself
uv tool uninstall adws

.env holds your secrets and is left alone — remove it deliberately, not as part of an uninstall. Finally, drop the logs/ rule adws init appended to your .gitignore.

Agent/CI Mode (Non-Interactive)

For automated installations without prompts (agents, CI/CD pipelines):

# One-off run from PyPI, no setup
uvx adws init --non-interactive

Available flags:

• --non-interactive — Run without user prompts
• --force — Overwrite existing files without confirmation
• --skip-detection — Use template files only, skip auto-detection

What happens in agent mode:

1. Project auto-detected from existing config files
2. AGENTS.md and manifest.yml written with the detected values; .env copied only when absent; .mcp.json merged
3. Adapters run for detected agent tools → .claude/ projections generated
4. No human interaction required — ready for agent operation

Note: Framework files (docs/, scripts/, skills/, adapters/) stay inside the installed adws package and are not copied into the project. Read the docs with adws standards list / adws standards show <doc>.

CLI Usage

The adws CLI provides unified commands for the framework:

# Service management
adws start              # Start project services (auto-discovers backend/frontend)
adws stop               # Stop all running services

# Workflow
adws plan <issue>       # Generate implementation plan for GitHub issue #<issue>
adws build <issue>      # Build/Implement solution for issue #<issue>

# Diagnostics
adws health             # Run system health check
adws status             # Show ADW status for current project
adws doctor             # Report agent-stack drift (warnings)
adws doctor --strict    # Same checks, non-zero exit — the consumer CI gate

# Framework standards docs (they are not copied into your repo)
adws standards list             # List the shipped standards docs
adws standards show workflow    # Print one
adws standards path risk-model  # Its on-disk path, for an editor or pager

# Issue management
adws create-issue "Title" --body "Description" --labels "bug"
                        # Create new GitHub issue

# Worktree management (parallel development)
adws worktree create feature/branch-name [--init]
                        # Create new worktree for parallel development
adws worktree list      # List all worktrees
adws worktree remove <path> [--force]
                        # Remove a worktree

# Multi-agent orchestrator dashboard
adws dashboard start    # Start the orchestrator dashboard (background process)
adws dashboard stop     # Stop the orchestrator dashboard
adws dashboard status   # Show whether the orchestrator dashboard is running

# Issue-sync poller (posts run status back to GitHub/Linear/Jira)
adws sync start          # Start the issue-sync poller
adws sync stop           # Stop the issue-sync poller
adws sync status         # Show issue-sync poller status

# Triggers — start everything needed to pick up new issues in one command
adws triggers start      # dashboard + sync + GitHub/Linear/Jira cron pollers
adws triggers start --webhook  # ...cron pollers replaced by the webhook server
adws triggers stop       # Stop trigger(s) only (dashboard/sync keep running)
adws triggers status     # Show dashboard/sync/trigger status, all at once

# Maintenance
adws init               # Initialize ADW in current directory (auto-detects project type)
adws init --force       # Reinitialize (backs up AGENTS.md/manifest.yml, preserves .env)
adws init --non-interactive  # Skip prompts (for CI/CD)
adws upgrade            # Restamp + regenerate projections (preserves user-owned files)

Repo-Agnostic Operation

By default, ADW reads the repository from git remote get-url origin. To operate on a different repository:

# Via environment variable
export ADW_REPO="owner/repo"
adws plan 123

# Via CLI flag
adws plan 123 --repo owner/repo

Multi-Agent Orchestration (Dashboard)

adws dashboard start launches a long-lived orchestration engine (SQLite-backed, supports N concurrent runs) with a lightweight built-in web dashboard — no Node/npm required, the UI is plain HTML/CSS/JS served directly by the engine's own FastAPI process.

• Requires ANTHROPIC_API_KEY — the orchestrator talks to the Anthropic API directly via the Claude Agent SDK, which is a separate mechanism from CLAUDE_CODE_PATH (used by the single-agent claude_cli provider, which shells out to the Claude Code CLI binary instead).
• Only Claude is supported for orchestration in v1 — ADW_AGENT_PROVIDER=venice_api users, and users of the deprecated opencode provider, keep the existing single-agent flow.

adws dashboard start    # Start the orchestrator dashboard (background process)
                         # Prints the dashboard URL, e.g. http://localhost:9403
adws dashboard status   # Show whether the dashboard is running (and its PID)
adws dashboard stop     # Stop the dashboard

Starting a job doesn't require an issue tracker — click + New Run in the dashboard's run list to start one directly (repo/issue fields optional, prompt required). For issue-tracker-driven runs, adws triggers start is the single command that gets everything going: it starts the dashboard and adws sync (the poller that posts progress comments back to GitHub/Linear/Jira) if they aren't already running, then starts the GitHub + Linear + Jira cron pollers (or the webhook server with --webhook). adws triggers stop only stops the trigger(s) — the dashboard and sync poller keep running so in-flight runs aren't interrupted; use adws dashboard stop/adws sync stop for a full teardown.

How an issue reaches the orchestrator

adws/trigger_webhook.py (/gh-webhook, /linear-webhook, /jira-webhook) and the polling scripts adws/trigger_cron.py / adws/trigger_linear_cron.py / adws/trigger_jira_cron.py all route through one shared gate, adws/orchestration_router.py:

• Default (ADW_ORCHESTRATOR_MODE=label): only issues labeled orchestrate go to the orchestrator; everything else keeps using the existing single-agent adw_plan_build.py flow, unchanged. This is deliberate — upgrading never silently changes existing behavior.
• ADW_ORCHESTRATOR_MODE=always routes every triggering issue to the orchestrator; off disables orchestrator routing entirely (single-agent only, an emergency kill-switch).
• adws/adw_issue_sync.py polls active runs and posts a 🤖 ADW: "started" comment, then a "complete"/"blocked" comment (with the run's latest_summary/error) back to the originating GitHub, Linear, or Jira issue once it finishes.
• Jira and Linear only work through the orchestrator today — adw_plan_build.py (the single-agent path used when use_orchestrator is false) is GitHub-only, so Jira/Linear issues need ADW_ORCHESTRATOR_MODE=always or the orchestrate label to actually run.

Repo isolation

Every orchestrator run gets its own real, isolated working directory — adws/adw_orchestrator/repo_isolation.py clones the triggering issue's actual repo (via gh repo clone, so it works for public and private repos alike) into trees/<adw_id>/ and checks out a fresh branch adw-<adw_id>, instead of operating wherever the server process happens to be running. This matters even for interactive dashboard use: without it, an orchestrator run for some-org/other-repo would silently read/edit files in this repo. Cleanup is currently manual (rm -rf trees/<adw_id>) — there's no automated GC yet.

The dashboard UI

Open the printed URL in a browser for a run list (status, cost, token usage, updated-at) — click into a run for its detail view: the agents the orchestrator spawned, a live activity/chat log (streamed over the engine's /ws WebSocket), and a message box to send it new instructions interactively.

REST API

For programmatic/CI use, the engine also exposes a small HTTP contract independent of the dashboard UI: POST /orchestrator/runs (start or idempotently reuse a run by adw_id), GET /orchestrator/runs/{run_id} (poll status/cost/latest_summary), and GET /orchestrator/runs (list, used by the dashboard's run list). See adws/orchestrator_client.py for the Python wrapper used by the trigger/routing layer.

See .env.example for orchestrator-related environment variables (ORCHESTRATOR_PORT, ADW_ORCHESTRATOR_MODE, LINEAR_WEBHOOK_SECRET, GITHUB_WEBHOOK_SECRET, JIRA_WEBHOOK_SECRET) and docs/upgrading.md for upgrades. The orchestration engine runs from the installed package, so upgrading the package upgrades it.

manifest.yml — Universal Entry Point

manifest.yml is the machine-readable project entry point. Every tool (Claude Code, the ADW pipelines) reads it from the repo root. It eliminates discovery overhead and provides canonical paths.

framework_version: "X.Y.Z"  # the adws package version; written by `adws init`, refreshed by `adws upgrade`
project:
  name: "my-project"
  language: "Python 3.12"
  framework: "FastAPI"
entry_points:
  readme: "README.md"
  agents: "AGENTS.md"
  env: ".env"
paths:
  source: "src/"
  tests: "tests/"
  docs: "docs/"
  scripts: "scripts/"

The full schema — which blocks are required, and which names the shipped skills read — is templates/manifest.yml, explained in docs/bootstrap-protocol.md.

Auto-Detection

When you run adws init, the framework automatically detects your project type by parsing existing configuration files:

Detection populates manifest.yml with:

• Project name from config (falls back to directory name)
• Language and version from requires-python, go 1.21, etc.
• Framework from dependency analysis
• Source and test paths from conventional layouts
• Validation commands (test, lint, format, typecheck) from installed tools

When manifest.yml exists and is valid, the prime skill skips discovery and uses it directly (Step 0).

Framework Structure

The top level of this repository. For the layout of a repository that consumes the framework, and where each part of the framework lives once installed, see docs/repository-structure.md.

Adoption Tiers

Tier 1: Minimum Viable (30 seconds)

The standards docs referenced below are not files in your repo — read them from the installed package with adws standards show <name>.

Result: Agent has project awareness, machine-readable entry point, and a structured work process.

Tier 2: Standard (30 minutes)

Result: Full lifecycle with validation, planning, and risk-appropriate controls.

Tier 3: Advanced (2 hours)

Result: Production-grade agentic engineering with cross-tool portability.

The templates/ files (plan-template.md, review-template.md, Justfile, validate-manifest.yml) are not exposed by the CLI — adws init writes the ones a project needs. To get the others, browse the repo's templates/ directory (this repository is private, so you need access) or fetch them with gh api as shown under Option C above.

Document Index

Contributing

This framework is designed to evolve. To propose changes:

1. Open an issue describing the problem and proposed solution
2. Reference the specific document(s) affected
3. Maintain the design principles above in any modification
4. Add an entry under ## [Unreleased] in docs/changelog.md naming the ticket

License

This framework is released for use by any engineering team. Adapt freely.