Metadata-Version: 2.4
Name: adws
Version: 2.1.0
Summary: AI Developer Workflow System - Agentic Engineering Framework CLI
Author: ADW Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/Superlogic/AgenticEngineeringFramework
Project-URL: Documentation, https://github.com/Superlogic/AgenticEngineeringFramework#readme
Project-URL: Repository, https://github.com/Superlogic/AgenticEngineeringFramework
Project-URL: Issues, https://github.com/Superlogic/AgenticEngineeringFramework/issues
Keywords: ai,developer,workflow,agent,github,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28
Provides-Extra: full
Requires-Dist: adws[cron,orchestrator,webhook]; extra == "full"
Provides-Extra: webhook
Requires-Dist: fastapi>=0.100; extra == "webhook"
Requires-Dist: uvicorn>=0.23; extra == "webhook"
Provides-Extra: cron
Requires-Dist: schedule>=1.2; extra == "cron"
Provides-Extra: orchestrator
Requires-Dist: claude-agent-sdk>=0.1; extra == "orchestrator"
Requires-Dist: aiosqlite>=0.19; extra == "orchestrator"
Requires-Dist: fastapi>=0.100; extra == "orchestrator"
Requires-Dist: uvicorn[standard]>=0.23; extra == "orchestrator"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: httpx2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: aiosqlite>=0.19; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Agentic Engineering Framework

> **Version**: v2.1 (framework standard) — distributed as the `adws` package, versioned 2.1.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.1.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](docs/ONBOARDING.md) — 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

| Principle | What It Means |
|---|---|
| **Vendor-neutral** | Core docs never reference a specific agent tool. Vendor specifics live in `adapters/`. |
| **Modular** | Every document is independent. Adopt one file or all of them. |
| **Incremental adoption** | Start with a 30-second setup (Tier 1) and grow into advanced orchestration (Tier 3). |
| **Any language, any agent** | The lifecycle and risk model work whether you ship Solidity, Python, Rust, TypeScript, or COBOL. |
| **Actionable over aspirational** | Every section tells you what to *do*, not what to *think about*. |
| **Templates are real files** | Copy-paste ready, with `<!-- CUSTOMIZE: -->` markers where you fill in your specifics. |

---

## Quick Start (30 Seconds — Tier 1)

### Prerequisites

- **[uv](https://docs.astral.sh/uv/)** — required, not optional. Every workflow script and agent hook is a [PEP 723](https://peps.python.org/pep-0723/) 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

| Module | Purpose |
|---|---|
| `config.py` | Pydantic Settings with `ADW_` prefix — centralized, typed, validated |
| `logging_config.py` | Structured JSON/text logging with correlation IDs and provider event helpers |
| `secret_scrubber.py` | Automatic detection and redaction of API keys, tokens, passwords |
| `providers.py` | Provider health checks, duration tracking, project root discovery |
| `adw_modules/` | Reusable framework modules: state, worktree, git ops, workflow orchestration |

### Option A: Install from PyPI (Recommended)

The `adws` CLI is published on [PyPI](https://pypi.org/project/adws/). With [uv](https://docs.astral.sh/uv/) there is nothing to set up — no virtual environment needed:

```bash
# 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

```bash
# 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)

```bash
# 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](docs/SLASH_COMMANDS.md) 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

| Method | Command | Best For |
|--------|---------|----------|
| **PyPI via uv** (Recommended) | `uv tool install adws` or one-off `uvx adws init` | All users — no virtual environment, isolated install |
| **PyPI via pipx / pip** | `pipx install adws` or `pip install adws` | Users without uv |
| **From source** | `git clone ... && bash install.sh` | Tracking or modifying the framework source (`.adws/`) |
| **Non-interactive** | `bash install.sh --non-interactive` or `adws init --non-interactive` | CI/CD pipelines — no prompts |
| **Skip detection** | `bash install.sh --skip-detection` | Manual configuration — uses templates only |
| **Manual** | Copy templates individually | Understanding each component |

### 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:

| Install | Adds |
|---|---|
| `pip install adws` | Core — `init`, `health`, `plan`, `build`, `worktree`, GitHub + Linear, Playwright E2E |
| `pip install 'adws[orchestrator]'` | `adws dashboard *` — multi-agent engine and web dashboard |
| `pip install 'adws[webhook]'` | `adws triggers start --webhook` — FastAPI webhook server |
| `pip install 'adws[cron]'` | `adws sync *`, `adws triggers start` — polling triggers |
| `pip install 'adws[full]'` | Everything |

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](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:

| Service | OAuth | API key |
|---|---|---|
| Anthropic | `CLAUDE_CODE_OAUTH_TOKEN`, or an interactive `claude` login | `ANTHROPIC_API_KEY` |
| Linear | `LINEAR_OAUTH_TOKEN` (sent as `Bearer`) | `LINEAR_API_KEY` (sent raw) |
| GitHub | `gh auth login` session | `GITHUB_PAT` |

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](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

| File/Directory | Purpose |
|---|---|
| `AGENTS.md` | Human-readable project configuration (auto-populated with detected values) |
| `manifest.yml` | Machine-readable project entry point (auto-populated with detected values) |
| `.env` | Environment variables (from template) |
| `.adws/` | Framework source (source installs only) — single source of truth for source installs, updated via `adws update` |

**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
> 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](docs/upgrading.md) for the full guide.

**PyPI installs:**

```bash
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/`):

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

`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:

```bash
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](docs/docker.md) for the full guide, including OAuth-based Anthropic auth and Linear polling.

### Uninstalling

Remove everything listed under [What Gets Installed](#what-gets-installed):

```bash
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):

```bash
# 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:

```bash
# 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:

```bash
# 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.

```bash
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](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.

```yaml
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:

| Detected File | Language | Frameworks Recognized |
|---|---|---|
| `pyproject.toml` | Python | FastAPI, Flask, Django, Streamlit, and 20+ more |
| `package.json` | JavaScript/TypeScript | Next.js, React, Vue, Express, NestJS, and 20+ more |
| `Cargo.toml` | Rust | Actix Web, Axum, Rocket, Tauri, and 10+ more |
| `go.mod` | Go | Gin, Echo, Fiber, Beego, and 10+ more |
| `Gemfile` | Ruby | Rails, Sinatra, Hanami, and 8+ more |
| `pom.xml` / `build.gradle` | Java | Spring Boot, Quarkus, Micronaut, and 15+ more |
| `foundry.toml` / `hardhat.config.js` | Solidity | Foundry, Hardhat, Truffle, Brownie, Ape |

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)

| What | Why |
|---|---|
| Run `curl ... | bash` to install | Installs AGENTS.md, manifest.yml, .env, and .adws/ into your project |
| Read `docs/workflow.md` | Understand the 7-stage lifecycle your agent should follow |

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

### Tier 2: Standard (30 minutes)

| What | Why |
|---|---|
| Everything in Tier 1 | Foundation |
| Copy `templates/plan-template.md` | Structured task planning |
| Copy `templates/review-template.md` | Consistent review checklists |
| Copy `templates/validation-readme.md` | Documented validation commands |
| Read `docs/risk-model.md` | Calibrate controls to change risk |
| Copy `templates/Justfile` | One-command lifecycle actions |

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

### Tier 3: Advanced (2 hours)

| What | Why |
|---|---|
| Everything in Tier 2 | Foundation |
| Run bootstrap protocol (`docs/bootstrap-protocol.md`) | Full repo audit and setup |
| Adopt skill standard (`docs/cross-tool-standard.md`) | Reusable, portable agent skills |
| Align repo structure (`docs/repository-structure.md`) | Canonical file organization |
| Create tool adapter (`adapters/README.md`) | Map to your specific agent tool |
| Configure CI validation (`templates/validate-manifest.yml`) | Automated manifest validation |

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

---

## Document Index

| Document | Purpose | Adoption Tier |
|---|---|---|
| [docs/ONBOARDING.md](docs/ONBOARDING.md) | **Start here** — step-by-step engineer onboarding guide | Tier 1 |
| [docs/auth.md](docs/auth.md) | OAuth and API-key authentication for Anthropic, Linear, and GitHub | Tier 1 |
| [docs/packaging.md](docs/packaging.md) | Core package vs optional extras, and what each unlocks | Tier 1 |
| [docs/e2e-testing.md](docs/e2e-testing.md) | Playwright MCP end-to-end testing — setup, writing tests, the result contract | Tier 2 |
| [docs/SLASH_COMMANDS.md](docs/SLASH_COMMANDS.md) | Quick reference for OpenCode/Claude Code slash commands | Tier 1 |
| [docs/upgrading.md](docs/upgrading.md) | Upgrade guide — file ownership, per-method procedures, backups | Tier 1 |
| [docs/workflow.md](docs/workflow.md) | Core 7-stage lifecycle and agent execution rules | Tier 1 |
| [docs/hooks.md](docs/hooks.md) | Agent hooks — the `.env`/`rm -rf` guard, the exit-code contract, safe customization | Tier 1 |
| [docs/code-quality.md](docs/code-quality.md) | Local lint/coverage loop, what each tool catches, and the SonarCloud cognitive-complexity gap | Tier 2 |
| [docs/risk-model.md](docs/risk-model.md) | Risk classification, controls matrix, escalation policy | Tier 2 |
| [docs/bootstrap-protocol.md](docs/bootstrap-protocol.md) | Repository audit and bootstrap procedure | Tier 3 |
| [docs/cross-tool-standard.md](docs/cross-tool-standard.md) | Cross-tool skill sharing standard | Tier 3 |
| [docs/repository-structure.md](docs/repository-structure.md) | Canonical repository structure | Tier 3 |
| [docs/tutorial.md](docs/tutorial.md) | End-to-end lifecycle tutorial (Medium risk example) | Tier 2 |
| [docs/docker.md](docs/docker.md) | Running `adws` and its services in Docker (no local Python/Node/git/gh/uv needed) | Tier 2 |
| [templates/AGENTS.md](templates/AGENTS.md) | Project configuration for agents | Tier 1 |
| [templates/manifest.yml](templates/manifest.yml) | Universal machine-readable entry point | Tier 1 |
| [templates/SKILL.md](templates/SKILL.md) | Skill definition template | Tier 3 |
| [templates/plan-template.md](templates/plan-template.md) | Task planning template | Tier 2 |
| [templates/review-template.md](templates/review-template.md) | Review checklist template | Tier 2 |
| [templates/validation-readme.md](templates/validation-readme.md) | Validation command reference | Tier 2 |
| [templates/bootstrap-prompt.md](templates/bootstrap-prompt.md) | Universal bootstrap prompt | Tier 3 |
| [templates/prime.md](templates/prime.md) | Repository auto-bootstrap prompt | Tier 3 |
| [templates/validate-manifest.yml](templates/validate-manifest.yml) | CI workflow for manifest validation | Tier 3 |
| [templates/Justfile](templates/Justfile) | Lifecycle automation commands | Tier 2 |
| [adapters/README.md](adapters/README.md) | Tool adapter creation guide | Tier 3 |
| [adapters/agent-zero/](adapters/agent-zero/) | Agent-Zero adapter (mapping + generator) | Tier 3 |
| [adapters/claude-code/](adapters/claude-code/) | Claude Code adapter (mapping + generator) | Tier 3 |
| [adapters/opencode/](adapters/opencode/) | OpenCode adapter (mapping + generator) | Tier 3 |
| [adapters/pi-mono/](adapters/pi-mono/) | Pi Mono adapter (mapping + generator) | Tier 3 |
| [adws/README.md](adws/README.md) | AI Developer Workflow — setup, usage, and configuration | Tier 3 |
| [adws/cli.py](adws/cli.py) | CLI entry point (`adws` command) | Tier 3 |
| [adws/agent.py](adws/agent.py) | Agent provider interface (backward-compatible) | Tier 3 |
| [adws/providers.py](adws/providers.py) | Agent provider implementations (OpenCode, Claude CLI, Venice API) | Tier 3 |
| [adws/auth.py](adws/auth.py) | Credential resolution — OAuth or API key for Anthropic, Linear, GitHub | Tier 3 |
| [adws/capabilities.py](adws/capabilities.py) | Optional-extra gating for CLI commands | Tier 3 |
| [adws/data_types.py](adws/data_types.py) | Pydantic models for type safety | Tier 3 |
| [adws/github.py](adws/github.py) | GitHub API operations (repo-agnostic via ADW_REPO) | Tier 3 |
| [adws/tests/](adws/tests/) | Smoke tests for ADW modules (`pytest adws/tests/` from root) | Tier 3 |
| [skills/agent-experts/SKILL.md](skills/agent-experts/SKILL.md) | Deploy self-improving domain experts (act → learn → reuse) for High-risk codebase areas | Tier 3 |
| [skills/prime/SKILL.md](skills/prime/SKILL.md) | Auto-bootstrap skill implementation | Tier 3 |
| [skills/rust-skills/SKILL.md](skills/rust-skills/SKILL.md) | Rust best practices — 265 rules across 26 categories (adopted from [leonardomso/rust-skills](https://github.com/leonardomso/rust-skills), MIT) | Tier 3 |
| [skills/setup-linting/SKILL.md](skills/setup-linting/SKILL.md) | Linter configuration skill implementation | Tier 3 |
| [scripts/](scripts/) | Development and operational shell scripts | Tier 2 |
| [.env.example](.env.example) | Environment variable template (copy to `.env` and fill in) | Tier 1 |
| [.gitignore](.gitignore) | Git ignore rules (env, pycache, agents, IDE) | Tier 1 |

---

## 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.
