adws 0.3.0

AI Developer Workflow System - Agentic Engineering Framework CLI

Agentic Engineering Framework

Version: v2.0 Date: 2026-04-06

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.

---

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)

Option A: Install Script (Recommended)

# 1. Run the installer in your project root
curl -sSL https://raw.githubusercontent.com/your-org/adws/main/install.sh | bash

# 2. Fill in your .env
cp .env.example .env
$EDITOR .env

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

Option B: Pip Package

# 1. Install the ADW CLI
pip install adws

# 2. Initialize in your project
adws init

# 3. Fill in your .env
$EDITOR .env

Option C: Manual Copy

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

# 2. Create manifest.yml (universal machine-readable entry point)
cp templates/manifest.yml your-repo/manifest.yml

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

# 4. Read the 7-stage lifecycle (10 min read)
open docs/workflow.md

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

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

---

Installation

Requirements

• Python 3.10+
• Git (for repo detection and operations)
• GitHub CLI (gh) — optional, for PR/issue operations

Install via Script

curl -sSL https://raw.githubusercontent.com/your-org/adws/main/install.sh | bash

The installer will:

• Copy AGENTS.md, manifest.yml, and .env into your project
• Create .adws/ with ADW core files
• Copy slash commands into .opencode/commands/ (or .claude/commands/)
• Optionally install the adws pip package

Install via Pip

pip install adws

Optional extras:

pip install adws[webhook]   # FastAPI webhook server
pip install adws[cron]      # Polling-based issue monitor
pip install adws[dev]       # Testing and linting tools

What Gets Installed

File	Purpose
AGENTS.md	Project configuration for agents (coding rules, architecture, commands)
manifest.yml	Universal machine-readable project entry point
.env	Environment variables (from .env.example template)
.adws/	AI Developer Workflow core files (Python scripts, shell scripts)
.opencode/commands/	Slash commands for OpenCode (or .claude/commands/)

---

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

# Maintenance
adws init               # Initialize ADW in current directory
adws update             # Update ADW framework to latest version

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

---

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: "2.0"
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/"

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                     ← Pip package config (pip install adws)
├── .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 issue monitor
│   ├── trigger_webhook.py            ← Webhook-based issue processor
│   ├── utils.py                       ← Shared utilities
│   ├── py.typed                       ← Type hint marker
│   └── tests/                         ← Smoke tests (89 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_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 install.sh or pip install adws && adws init	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/workflow.md	Core 7-stage lifecycle and agent execution rules	Tier 1
docs/risk-model.md	Risk classification, controls matrix, escalation policy	Tier 2
docs/bootstrap-protocol.md	Repository audit and bootstrap procedure	Tier 3
docs/cross-tool-standard.md	Cross-tool skill sharing standard	Tier 3
docs/repository-structure.md	Canonical repository structure	Tier 3
docs/tutorial.md	End-to-end lifecycle tutorial (Medium risk example)	Tier 2
templates/AGENTS.md	Project configuration for agents	Tier 1
templates/manifest.yml	Universal machine-readable entry point	Tier 1
templates/SKILL.md	Skill definition template	Tier 3
templates/plan-template.md	Task planning template	Tier 2
templates/review-template.md	Review checklist template	Tier 2
templates/validation-readme.md	Validation command reference	Tier 2
templates/bootstrap-prompt.md	Universal bootstrap prompt	Tier 3
templates/prime.md	Repository auto-bootstrap prompt	Tier 3
templates/validate-manifest.yml	CI workflow for manifest validation	Tier 3
templates/Justfile	Lifecycle automation commands	Tier 2
adapters/README.md	Tool adapter creation guide	Tier 3
adapters/agent-zero/	Agent-Zero adapter (mapping + generator)	Tier 3
adapters/claude-code/	Claude Code adapter (mapping + generator)	Tier 3
adapters/opencode/	OpenCode adapter (mapping + generator)	Tier 3
adapters/pi-mono/	Pi Mono adapter (mapping + generator)	Tier 3
adws/README.md	AI Developer Workflow — setup, usage, and configuration	Tier 3
adws/cli.py	CLI entry point (adws command)	Tier 3
adws/agent.py	Agent provider interface (backward-compatible)	Tier 3
adws/providers.py	Agent provider implementations (OpenCode, Claude CLI, Venice API)	Tier 3
adws/data_types.py	Pydantic models for type safety	Tier 3
adws/github.py	GitHub API operations (repo-agnostic via ADW_REPO)	Tier 3
adws/tests/	Smoke tests for ADW modules (pytest adws/tests/ from root)	Tier 3
skills/prime/SKILL.md	Auto-bootstrap skill implementation	Tier 3
skills/setup-linting/SKILL.md	Linter configuration skill implementation	Tier 3
scripts/	Development and operational shell scripts	Tier 2
.env.example	Environment variable template (copy to .env and fill in)	Tier 1
.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.