Metadata-Version: 2.4
Name: adws
Version: 3.3.2
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
Project-URL: Changelog, https://github.com/Superlogic/AgenticEngineeringFramework/blob/main/CHANGELOG.md
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

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](docs/consuming-the-framework.md) — 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](docs/ONBOARDING.md).

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

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

### 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](docs/changelog.md) (`adws standards show
changelog` from an installed package).

### 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/` 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](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

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

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

| 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 |
| **Non-interactive** | `adws init --non-interactive` | CI/CD pipelines — no prompts |
| **Manual** | Copy templates individually | Understanding each component |

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

| Install | Adds |
|---|---|
| `pip install adws` | Core — every command, including `adws dashboard`, `adws sync` and `adws triggers` (with `uv` on `PATH`) |
| `pip install 'adws[orchestrator]'` | The orchestration engine's dependencies (`claude-agent-sdk`, `aiosqlite`, `fastapi`, `uvicorn[standard]`) |
| `pip install 'adws[webhook]'` | The webhook server's dependencies (`fastapi`, `uvicorn`) |
| `pip install 'adws[cron]'` | The pollers' dependency (`schedule`) |
| `pip install 'adws[full]'` | All of the above |

`adws health` lists which extras are installed; a missing one is informational, never a failure. 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.** `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:

| File | Purpose | Commit it? |
|---|---|---|
| `AGENTS.md` | Human-readable project configuration (auto-populated with detected values) | ✅ yes |
| `manifest.yml` | Machine-readable project entry point; carries the `framework_version` stamp | ✅ yes |
| `.env` | Environment variables, copied from the template only when absent | ❌ never |
| `.mcp.json` | Playwright MCP registration — **merged**; your existing servers are preserved | ✅ yes |
| `playwright-mcp-config.json` | Playwright MCP settings, written only when absent | ✅ yes |
| `.gitignore` | A `logs/` rule is appended when absent; the file is never rewritten | ✅ yes |
| `.adws/` | Runtime state only (trigger and dashboard pid files). A framework checkout here is the removed pre-2.1.0 source install — `adws doctor` reports it | ❌ never |

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

| Directory | Purpose | Commit it? |
|---|---|---|
| `.claude/commands/`, `.claude/hooks/` | Claude Code slash commands and hooks | ❌ never |
| `.claude/settings.json` | Seeded once when absent, then **yours** | your call |

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

### The consumer contract: `adws doctor`

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

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

```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 only what the framework wrote — see [What Gets Installed](#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).

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

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

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

```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=venice_api` users, and users of the deprecated `opencode` provider, 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 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.

```yaml
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](templates/manifest.yml), explained in
[docs/bootstrap-protocol.md](docs/bootstrap-protocol.md#step-2-generate-manifestyml-required--level-2).

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

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](docs/repository-structure.md).

| Path | What it holds |
|---|---|
| `adws/` | The `adws` package: the CLI (`cli.py`, `commands/`), the workflow scripts (`adw_*_iso.py`), `adw_modules/`, the orchestrator (`adw_orchestrator/`) and the test suite (`adws/tests/`) |
| `adws/framework/` | The payload that ships in the wheel: a generated copy of `adapters/`, `ai_docs/`, `docs/`, `scripts/`, `skills/`, `specs/` and `.claude/` (exclusions in `scripts/framework_payload.yml`). Never edit it: run `python scripts/sync_framework.py --write` |
| `skills/` | The packaged skills, one `<name>/SKILL.md` each |
| `skills-internal/` | Skills for this repository only; never shipped |
| `adapters/` | The Claude Code, Agent Zero and pi-mono adapters |
| `templates/` | What `adws init` writes into a project (`AGENTS.md`, `manifest.yml`, `.env.example`, the CI workflows), plus the plan and review templates |
| `docs/` | The standards docs `adws standards` serves, including `changelog.md` |
| `scripts/` | Ops scripts that ship, plus this repository's build and CI tooling |
| `.claude/` | The Claude Code hooks and `settings.json` the payload ships, and `commands/` links that give this repository's own sessions the procedure skills |

---

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

| What | Why |
|---|---|
| `uvx adws init` | Writes `AGENTS.md`, `manifest.yml`, `.env`, `.mcp.json` and the tool projections |
| `adws standards show workflow` | 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 |
| Pin the version + add the drift gate — [docs/consuming-the-framework.md](docs/consuming-the-framework.md) | Reproducible adoption; framework content cannot creep back in |
| Fill in `manifest.yml`'s `validation:` block | `/test` and the workflow stages read your real commands from it |
| `adws standards show risk-model` | Calibrate controls to change risk |
| `adws doctor` | See drift before it reaches CI |

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

### Tier 3: Advanced (2 hours)

| What | Why |
|---|---|
| Everything in Tier 2 | Foundation |
| `adws standards show bootstrap-protocol` | Full repo audit and setup |
| `adws standards show cross-tool-standard` | Reusable, portable agent skills |
| `adws standards show repository-structure` | Canonical file organization |
| `adws dashboard start` / `adws triggers start` | Multi-agent orchestration and issue-tracker triggers |
| Write your own skills in `skills/<name>/SKILL.md` | They project alongside the packaged ones and win on name collisions |

**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](https://github.com/Superlogic/AgenticEngineeringFramework/tree/main/templates)
> (this repository is private, so you need access) or fetch them with `gh api` as shown under
> Option C above.

---

## Document Index

| Document | Purpose | Adoption Tier |
|---|---|---|
| [docs/consuming-the-framework.md](docs/consuming-the-framework.md) | **Start here to adopt it in a repo** — why it is a pinned dependency, what lands in your repo, the four onboarding steps | Tier 1 |
| [docs/ONBOARDING.md](docs/ONBOARDING.md) | Working with ADW day to day, once a repo is onboarded (learning the workflow) | 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 the 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/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 (Claude CLI, Venice API; OpenCode deprecated) | 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) | Reports which optional extras are installed (`adws health`); gates no command | 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. Add an entry under `## [Unreleased]` in [docs/changelog.md](docs/changelog.md) naming the ticket

---

## License

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