Metadata-Version: 2.4
Name: devprotocol
Version: 0.0.1
Summary: Structured pre-code protocol and agentic development framework
Project-URL: Homepage, https://github.com/giovannimanzoni/DEVPROTOCOL
Project-URL: Repository, https://github.com/giovannimanzoni/DEVPROTOCOL
Project-URL: Documentation, https://github.com/giovannimanzoni/DEVPROTOCOL/blob/main/docs/quickstart.md
Project-URL: Bug Tracker, https://github.com/giovannimanzoni/DEVPROTOCOL/issues
Author-email: Giovanni Manzoni <dev@giovannimanzoni.com>
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: agentic,agents,ai-agents,code-generation,devprotocol,domain-driven-design,llm,orchestration,pre-code,protocol
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: check-wheel-contents>=0.6.3
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: langchain>=0.2.0
Requires-Dist: langsmith==0.8.4
Requires-Dist: mypy==2.1.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: ruff==0.15.13
Requires-Dist: twine>=6.2.0
Requires-Dist: types-requests==2.33.0.20260513
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Provides-Extra: langsmith
Requires-Dist: langsmith>=0.1.0; extra == 'langsmith'
Description-Content-Type: text/markdown

![DEVPROTOCOL Level: 4](https://img.shields.io/badge/DEVPROTOCOL_Level-4-blue) 
[![Known Vulnerabilities](https://snyk.io/test/github/giovannimanzoni/DEVPROTOCOL/badge.svg)](https://snyk.io/test/github/giovannimanzoni/DEVPROTOCOL)
[![Qodana](https://github.com/giovannimanzoni/DEVPROTOCOL/actions/workflows/security.yml/badge.svg)](https://github.com/giovannimanzoni/DEVPROTOCOL/actions/workflows/security.yml)
![Metrics](https://github.com/giovannimanzoni/DEVPROTOCOL/actions/workflows/metrics.yml/badge.svg)

# DEVPROTOCOL

> The protocol for protocols.

## What This Is

**DEVPROTOCOL** is both:

1. **A methodology** — a 5-phase protocol that guides teams from discovery
   to behavior specification, producing every required document in the
   correct order — whether you're starting from scratch or adopting it
   on an existing codebase.
   → Read the [MANIFESTO](./MANIFESTO.md)
   → Study the DEVPROTOCOL implemented by [Agents](./agents/README.md) (agents)

2. **A software product** — an AI-powered tool that implements the
   methodology using LLMs and autonomous agent orchestration.
   It works with local models (Ollama, LM Studio) or cloud APIs
   (OpenAI, Anthropic), runs agents across five specialized roles,
   and persists state across sessions for long-term projects.  
   → [Install and run](./docs/quickstart.md)  
   → [Architecture](./docs/devprotocol)  
   → [Infrastructure](./docs/devprotocol/phase3/INFRA.md)  
   → [Full documentation](./docs)  

---

## See It in Action

**DEVPROTOCOL Writes Its Own Future | Claude Code + AI-Driven Epics & Stories**
[![DEVPROTOCOL Writes Its Own Future | Claude Code + AI-Driven Epics & Stories](https://img.youtube.com/vi/kzUkMWKmyt4/maxresdefault.jpg)](https://youtu.be/kzUkMWKmyt4)

**How DEVPROTOCOL implements an epic story**
[![How DEVPROTOCOL implements an epic story](https://img.youtube.com/vi/KvQv1SK2DX0/maxresdefault.jpg)](https://youtu.be/KvQv1SK2DX0)

---

## The Problem

Developers start coding before the problem is fully understood — working from scattered documents, inconsistent specs, and no shared language between themselves, domain experts, and stakeholders.

This happens on **new projects** and on **existing codebases** alike. Legacy systems accumulate implicit assumptions, undocumented decisions, and terminology drift that no single person fully understands.

The result is AI-generated code that reflects the tool's assumptions rather than the domain's reality — technically functional, but structurally wrong from day one.

---

## The Solution

DEVPROTOCOL solves this in two steps:

**Step 1 — Pre-code pipeline (Phases 1–5)**
Five structured phases produce every document the project needs. Each phase has a gate — no phase starts until the previous gate is closed. Works in three modes:

| Mode            | When to use                                                                                 |
|-----------------|---------------------------------------------------------------------------------------------|
| **New project** | Greenfield — scaffold dirs, config, and .gitignore, then run phases 1–5                     |
| **Import**      | Existing codebase — scan files, map them to DEVPROTOCOL phases, confirm per file, fill gaps |
| **Resume**      | Pick up an interrupted run — skips artefacts already completed                              |

`devprotocol bootstrap` detects which mode applies and routes accordingly.

**Step 2 — Agentic dev loop**
Papa Agent reads the baselined docs and dispatches specialised Agent agents story by story, each operating from domain-accurate context, each following the Think → Task → Execute workflow.

---

### The Agents Village

The core agents that run DEVPROTOCOL — named after the Agent characters they embody:

| Agent           | File                            | Job                                                                                     |
|-----------------|---------------------------------|-----------------------------------------------------------------------------------------|
| Papa Agent      | `agents/core/papaAgent.py`      | Orchestrates everything — dispatches agents, manages phase gates, drives the TTE loop   |
| Brainy Agent    | `agents/core/brainyAgent.py`    | Reads all parallel phase outputs and detects semantic contradictions                    |
| Handy Agent     | `agents/core/handyAgent.py`     | Builds context packages — extracts declared sections, applies summarisation on overflow |
| Grouchy Agent   | `agents/core/grouchyAgent.py`   | Blocks the door — validates preset against PDR before any agent runs                    |
| Vanity Agent    | `agents/core/vanityAgent.py`    | Watches for changes — detects semantic drift in living documents                        |
| Bootstrap Agent | `agents/core/bootstrapAgent.py` | Detects project state (new / import / resume) before any action                         |
| Scaffold Agent  | `agents/core/scaffoldAgent.py`  | Creates dirs, config template, .gitignore for new projects; re-run safe                 |
| Import Agent    | `agents/core/importAgent.py`    | Scans existing project, maps files to DEVPROTOCOL phases, per-file dev confirmation     |
| Gap Agent       | `agents/core/gapAgent.py`       | Audits expected artefacts vs manifest+fs, writes GAP_REPORT.md, per-gap dev decision    |
| AI Tool Agent   | `agents/core/aiToolAgent.py`    | Detects dev AI tool, writes appropriate rule file; no silent overwrite                  |

### AGENTS-ROUTER

A separate repository that handles all LLM inference. Papa Agent sends requests over REST on port 8700. AGENTS-ROUTER manages GPU scheduling, model loading/unloading, LRU eviction, and multi-backend routing. It has zero knowledge of DEVPROTOCOL phases or documents.

→ [AGENTS-ROUTER](https://github.com/giovannimanzoni/agents-router)

### Coordinator Presets

Papa Agent runs from a preset YAML file in `papaAgents/` that defines which agents run and in what order. Five presets ship out of the box:

| Preset             | Use case                                             |
|--------------------|------------------------------------------------------|
| `fullstack`        | Web app with DB + backend + frontend                 |
| `api-only`         | Headless API or microservice                         |
| `secure-fullstack` | Regulated or compliance-driven full stack            |
| `ml`               | ML / AI project with data pipeline and model serving |
| `infra`            | Infrastructure / DevOps / IaC project                |

Drop a new YAML into `papaAgents/` to define your own — no code change required.

---

## Extending DEVPROTOCOL

DEVPROTOCOL is designed to be adapted to any tech stack without forking. You can add custom skill files, define new coordinator presets, override gate modes per phase, and inject domain reference material — all through configuration.

→ [Extension Guide](./docs/EXTENSION_GUIDE.md) — Fixed vs configurable parts, custom skill files, custom gate modes, custom phase sequences, environment overrides, and a full end-to-end example.

---

## Quick Links

| Document                                         | Purpose                                                                                                |
|--------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| [Lifecycle](./docs/lifecycle.md)                 | Protocol lifecycle                                                                                     |
| [Comparison matrix](./docs/comparison-matrix.md) | DEVPROTOCOL vs. existing standards                                                                     |
| [MATURITY](./MATURITY.md)                        | Software maturity taken from [maturity-model](./docs/maturity-model.md), DEVPROTOCOL applies to itself |
| [Contributing & Dogfooding](CONTRIBUTING.md)     |                                                                                                        |
| [Agents](./agents/README.md)                     | Describe vertical agents and protocol itself                                                           |

---

## Setup

```bash
conda create -n envDevprotocol python=3.14.3
conda activate envDevprotocol
pip install uv
uv sync --extra dev
```

---

## Commands

**Deps:** PostgreSQL 14+, `agents.config.yaml` configured, AGENTS-ROUTER port 8700.

```bash
# Install (uv — preferred)
uv sync --extra dev             # creates .venv, installs all deps + dev extras

# Install (pip-compatible fallback)
uv pip install -e ".[dev]"

# CLI — Bootstrap
devprotocol bootstrap           # detect project state (new/import/resume), route to correct path
devprotocol scaffold            # create dirs + agents.config.yaml + .gitignore for new project
devprotocol import <preset>     # scan existing project files, map to DEVPROTOCOL structure, confirm per-file
devprotocol health-check <preset>  # audit expected artefacts, surface gaps, dev decides per gap
devprotocol register-ai-tool    # write rule file for detected AI tool (.cursorrules / AGENTS.md / copilot-instructions.md)

# CLI — Pipeline
devprotocol run <preset>        # run pre-code pipeline (fullstack|api-only|secure-fullstack|ml|infra)
devprotocol resume <preset>     # resume from last failure — skips complete artefacts
devprotocol validate <preset>   # pre-flight validation only (Grouchy), no agents run
devprotocol status              # show phase completion and stale/failed artefacts

# Tests
uv run pytest                                        # all tests + coverage
uv run pytest tests/unit/test_config.py              # single file
uv run pytest tests/unit/test_config.py::test_name  # single test
uv run pytest tests/unit/                            # unit tests only (no Postgres needed)

# Lint / format / types
uv run ruff check .
uv run ruff format .
uv run mypy agents/
```

---

## Release

Before publishing to PyPI, run the pre-publish validation script:

```bash
# Install dev deps first (once)
uv pip install twine check-wheel-contents

# Full validation including TestPyPI upload
bash scripts/check-package.sh

# Local-only validation (skip TestPyPI steps 5-6)
SKIP_TESTPYPI=1 bash scripts/check-package.sh
```

The script runs these checks in order, failing fast on the first error:

1. `uv build` — produces `dist/*.whl` + `dist/*.tar.gz`
2. `twine check dist/*` — validates PyPI metadata and README rendering
3. `check-wheel-contents dist/*.whl` — catches accidental inclusions (`.env`, `__pycache__`, test files)
4. Clean venv install: installs wheel, runs `devprotocol --help`, imports `devprotocol` + `agents`
5. TestPyPI upload via `twine upload --repository testpypi dist/*` *(skipped if `SKIP_TESTPYPI=1`)*
6. TestPyPI reinstall: installs from `test.pypi.org`, runs `devprotocol --help` *(skipped if `SKIP_TESTPYPI=1`)*

On success: `All checks passed. Safe to publish.`

---

## Claude Code Hooks

Hooks live in `.claude/hooks/` and are configured in `.claude/settings.json`. Disable for session: `/hooks`.

| File | Event | Trigger | Effect |
|---|---|---|---|
| `branch-guard.sh` | `PreToolUse` | Edit / Write / NotebookEdit | Blocks file edits on `main`/`master`/`develop` — forces story branch first |
| `story-lifecycle-check.sh` | `UserPromptSubmit` | `implement [Ee]\d+-[Ss]\d+` | Detects VCS (hg/git), injects story lifecycle + branch workflow |
| `pre-merge-gate.sh` | `PreToolUse` | `git merge .* story/` | Runs Ruff → Mypy → Pytest → Qodana → Snyk → GitNexus; blocks merge on failure; injects errors into Claude context |

---

## License

GNU GPL v3 — see [LICENSE](LICENSE) for details.

DEVPROTOCOL is inspired by [BEMYAGENT](https://github.com/vitotafuni/bemyagent) (MIT). Concepts around TTE workflow, lazy loading, and session restore are adapted from that project.
