Agentic Engineering Framework

Version: v2.2 (framework standard) — distributed as the adws package, versioned 2.2.x on PyPI Date: 2026-07-10

The framework standard (these docs, templates, and banners) is versioned v2.x, and the adws package that ships it tracks the same major.minor (2.2.x). Generated manifest.yml files are stamped with the package version, which is what adws status and adws upgrade compare.

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.

New to ADW? Start with the Engineer Onboarding Guide — a step-by-step tutorial to get productive in 30 minutes.

Key Features

• Single-step installation — Clone, install, auto-detect, and configure in one command
• 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 — Works with OpenCode, Claude Code, and other AI tools
• 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.

New in v2.1

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//.opencode/ projections. The framework content itself (docs, skills, adapters) stays inside the installed package and is resolved from there — read it with adws standards list.

Option B: Install from Source

# 1. Clone and install (auto-detects and configures everything)
git clone https://github.com/Superlogic/AgenticEngineeringFramework.git
bash AgenticEngineeringFramework/install.sh

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

This clones the framework into .adws/ in your project and installs the CLI in editable mode — best if you want to track or modify the framework source. Requires an activated virtual environment.

Option C: Manual Copy (Minimal)

# 1. Copy the agent config template into your repo
cp templates/AGENTS.md your-repo/AGENTS.md

# 2. Create manifest.yml
cp templates/manifest.yml your-repo/manifest.yml

# 3. Fill in the CUSTOMIZE sections
$EDITOR your-repo/AGENTS.md

# Done.

That's it for minimum viable adoption. Your agent reads AGENTS.md for project context and follows the lifecycle in workflow.md.

Using OpenCode or 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//.opencode/ projections for detected agent tools — machine-local symlinks into the installed package (AITOK-766: framework directories are not copied into your repo)

The source installer (install.sh) additionally clones the framework into .adws/ within your project and installs the CLI in editable mode, so you can track or modify the framework source.

Installation Options

Core and Extras

pip install adws installs a core package: the plan → build → test → review loop against Claude Code, GitHub, Linear, and Playwright E2E. Heavier subsystems are opt-in:

A command needing a missing extra prints the exact install line rather than failing inside a subprocess. adws health lists which extras are present. 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. install.sh refuses to run without it, and 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/ and .opencode/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 and source (install.sh) methods

What Gets Installed

Generated by adapters (run automatically when agent tools are detected): | .claude/ | Claude Code configuration and slash commands | | .opencode/ | OpenCode configuration and slash commands |

Framework directories (copied into your repo by adws init; also present inside .adws/ on source installs): | docs/ | Framework documentation | | specs/ | Specification files for plans (where /feature, /bug, /chore write plans) | | scripts/ | Development and utility scripts | | skills/ | Canonical skill definitions (single source of truth) | | adapters/ | Tool-specific adapter generators | | ai_docs/ | AI-generated documentation |

Note on slash commands: .claude/commands/ and .opencode/commands/ are generated artifacts. The canonical source lives in skills/*/SKILL.md. After adding new skills, regenerate commands:

bash adapters/opencode/generate.sh
bash adapters/claude-code/generate.sh

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

Source installs (framework cloned into .adws/):

adws update               # git pull + reinstall + safe file refresh, in one command

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//.opencode/ 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 everything listed under What Gets Installed:

rm -rf .adws/ AGENTS.md manifest.yml .env
rm -rf .claude/ .opencode/ docs/ specs/ scripts/ skills/ adapters/ ai_docs/

Agent/CI Mode (Non-Interactive)

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

# Simplest: one-off run from PyPI, no setup
uvx adws init --non-interactive

# Or from source:
git clone https://github.com/Superlogic/AgenticEngineeringFramework.git /tmp/adw
bash /tmp/adw/install.sh --non-interactive

# Or combine flags
bash /tmp/adw/install.sh --non-interactive --force --skip-detection

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. Framework cloned → .adws/
2. Minimum viable files copied → project root (AGENTS.md, manifest.yml, .env)
3. Adapters run for detected agent tools → .claude/, .opencode/ generated
4. adws package installed (editable mode)
5. adws init --non-interactive runs automatically
6. Project auto-detected from existing config files
7. manifest.yml and AGENTS.md populated with detected values
8. No human interaction required — ready for agent operation

Note: Framework files (docs/, scripts/, skills/, adapters/) live inside .adws/ and are not copied to the project root. Access them via .adws/docs/, .adws/scripts/, etc.

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

# 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)
adws update             # Source installs: git pull + reinstall + upgrade

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=opencode/venice_api users 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 how the orchestration engine (.adws/adw_orchestrator/) is refreshed.

manifest.yml — Universal Entry Point

manifest.yml is the machine-readable project entry point. All tools (OpenCode, Claude Code, etc.) read it from the repo root. It eliminates discovery overhead and provides canonical paths.

framework_version: "0.4.0"  # stamped with the adws package version that initialized the project
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/"
  adws: ".adws/"

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

AgenticEngineeringFramework/
├── README.md                          ← You are here
├── install.sh                         ← Universal installer for any project
├── pyproject.toml                     ← Python package configuration for editable installs
├── .env.example                       ← Environment variable template
├── .gitignore                         ← Git ignore rules
├── docs/
│   ├── workflow.md                    ← Core 7-stage lifecycle standard
│   ├── risk-model.md                  ← Risk classification & controls
│   ├── bootstrap-protocol.md          ← Repository bootstrap guide
│   ├── cross-tool-standard.md         ← Cross-tool skill sharing
│   ├── repository-structure.md        ← Standard repo structure
│   └── tutorial.md                    ← End-to-end lifecycle tutorial
├── templates/
│   ├── AGENTS.md                      ← Project config for agents
│   ├── manifest.yml                   ← Universal machine-readable entry point
│   ├── SKILL.md                       ← Canonical skill template
│   ├── plan-template.md               ← Task plan template
│   ├── review-template.md             ← Review checklist template
│   ├── validation-readme.md           ← Validation entrypoints
│   ├── bootstrap-prompt.md            ← Universal bootstrap prompt
│   ├── prime.md                       ← Repository auto-bootstrap prompt
│   ├── validate-manifest.yml          ← CI workflow for manifest validation
│   └── Justfile                       ← Lifecycle entry points
├── adapters/
│   ├── README.md                      ← How to create tool adapters
│   ├── agent-zero/                    ← Agent-Zero adapter
│   ├── claude-code/                   ← Claude Code adapter
│   ├── opencode/                      ← OpenCode adapter
│   └── pi-mono/                       ← Pi Mono adapter
├── adws/                              ← AI Developer Workflow system (Python)
│   ├── __init__.py                    ← Package metadata
│   ├── cli.py                         ← CLI entry point (adws command)
│   ├── README.md                      ← ADW setup and usage guide
│   ├── adw_plan_build.py             ← Main workflow orchestration
│   ├── agent.py                       ← Agent provider interface (backward-compatible)
│   ├── providers.py                   ← Agent provider implementations (OpenCode, Claude CLI, Venice)
│   ├── data_types.py                  ← Pydantic models for type safety
│   ├── github.py                      ← GitHub API operations (repo-agnostic via ADW_REPO)
│   ├── health_check.py               ← Health check endpoint
│   ├── trigger_cron.py               ← Polling-based GitHub issue monitor
│   ├── trigger_linear_cron.py        ← Polling-based Linear issue monitor
│   ├── trigger_jira_cron.py          ← Polling-based Jira issue monitor
│   ├── trigger_webhook.py            ← Webhook processor (/gh-webhook, /linear-webhook, /jira-webhook)
│   ├── webhook_security.py           ← GitHub/Linear/Jira webhook signature verification
│   ├── orchestration_router.py       ← Shared single-agent-vs-orchestrator routing gate
│   ├── orchestrator_client.py        ← HTTP client for the orchestrator engine's REST API
│   ├── adw_issue_sync.py             ← Syncs orchestrator run progress back to issue comments
│   ├── linear.py                     ← Linear GraphQL API operations
│   ├── jira.py                       ← Jira Cloud REST API operations
│   ├── utils.py                       ← Shared utilities
│   ├── py.typed                       ← Type hint marker
│   ├── adw_orchestrator/              ← Multi-agent orchestration engine (`adws dashboard start`)
│   │   ├── main.py                    ← FastAPI app: REST + WebSocket + static dashboard UI
│   │   ├── service.py                 ← Orchestrator agent execution (Claude Agent SDK)
│   │   ├── agent_manager.py           ← Sub-agent lifecycle + the 8 management tools
│   │   ├── repo_isolation.py          ← Per-run repo clone/branch isolation (trees/<adw_id>/)
│   │   ├── database.py                ← SQLite persistence (N concurrent runs)
│   │   └── static/                    ← Lightweight dashboard UI (plain HTML/CSS/JS, no build step)
│   └── tests/                         ← Test suite (310+ tests)
│       ├── conftest.py                ← Shared test fixtures
│       ├── test_data_types.py
│       ├── test_utils.py
│       ├── test_health_check.py
│       ├── test_github.py
│       ├── test_providers.py
│       ├── test_trigger_webhook.py
│       ├── test_orchestration_router.py
│       ├── test_orchestrator_database.py
│       ├── test_repo_isolation.py
│       ├── test_webhook_security.py
│       ├── test_adw_issue_sync.py
│       ├── test_linear.py
│       ├── test_jira.py
│       └── test_cli.py                ← CLI and repo-agnostic tests
├── .claude/
│   ├── CLAUDE.md                      ← Claude Code project context (generated from AGENTS.md)
│   └── commands/                      ← Claude Code slash commands (generated from skills/)
│       ├── prime.md
│       └── setup-linting.md
├── .opencode/
│   └── commands/                      ← OpenCode slash command definitions
│       ├── prime.md                   ← Prime / bootstrap command
│       ├── feature.md                 ← Feature planning command
│       ├── bug.md                     ← Bug planning command
│       ├── chore.md                   ← Chore planning command
│       ├── implement.md               ← Implementation command
│       ├── commit.md                  ← Git commit command
│       ├── pull_request.md            ← PR creation command
│       ├── install.md                 ← Install & prime command
│       ├── start.md                   ← Start services command
│       └── tools.md                   ← List tools command
├── skills/                            ← Executable skill implementations
│   ├── prime/                         ← Auto-bootstrap a repo for agents
│   │   └── SKILL.md
│   └── setup-linting/                 ← Configure and enable a code linter
│       └── SKILL.md
├── scripts/                           ← Development and operational scripts
│   ├── start.sh                       ← Start backend and frontend servers
│   ├── stop_apps.sh                   ← Stop all running services
│   ├── expose_webhook.sh             ← Expose webhook via Cloudflare tunnel
│   ├── kill_trigger_webhook.sh      ← Kill the webhook server process
│   ├── clear_issue_comments.sh      ← Clear all comments from a GitHub issue
│   ├── delete_pr.sh                  ← Delete a PR and optionally its branch
│   └── copy_dot_env.sh              ← Copy .env from sibling project
├── .env.example                       ← Environment variable template
├── ai_docs/                           ← AI-generated documentation
│   └── README.md
└── specs/                             ← Specification files
    └── README.md

Adoption Tiers

Tier 1: Minimum Viable (30 seconds)

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.

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. Update version headers when making breaking changes

License

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