adws 0.3.0__tar.gz

adws-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ADW Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adws-0.3.0/PKG-INFO

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: adws
+Version: 0.3.0
+Summary: AI Developer Workflow System - Agentic Engineering Framework CLI
+Author: ADW Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-org/agentic-workflow
+Project-URL: Documentation, https://github.com/your-org/agentic-workflow#readme
+Project-URL: Repository, https://github.com/your-org/agentic-workflow
+Project-URL: Issues, https://github.com/your-org/agentic-workflow/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: pyyaml>=6.0
+Requires-Dist: requests>=2.28
+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: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+pip install adws
+```
+
+Optional extras:
+```bash
+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:
+
+```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
+
+# 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:
+
+```bash
+# 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.
+
+```yaml
+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](docs/workflow.md) | Core 7-stage lifecycle and agent execution rules | Tier 1 |
+| [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 |
+| [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/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/prime/SKILL.md](skills/prime/SKILL.md) | Auto-bootstrap skill implementation | 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.