diff --git a/AGENTS.md b/AGENTS.md
index 6c0ea8e..0facbe5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,8 @@ Guidance for AI coding agents working on this repository. Human contributors: se
## Project
-`php-deal/framework` is a Design by Contract library for PHP. Contracts are native attributes
+`php-deal/framework` is an AI Design by Contract library for PHP: AI agents turn business specifications into
+contracted code with the bundled Agent Skill, and the library enforces the contracts. Contracts are native attributes
(`#[Verify]`, `#[Ensure]`, `#[Invariant]`, `#[Inherit]`) whose string arguments are PHP expressions. Aspects of
[Go! AOP 4](https://github.com/goaop/framework) weave the annotated classes and evaluate the expressions on every
call.
@@ -88,6 +89,8 @@ lowest-dependencies job and `composer audit`.
Global functions in expressions are written `\is_numeric(...)`, and class names fully qualified, because `use`
imports do not apply inside expressions.
- Keep comments short and useful. Public API classes need a class docblock that explains their purpose.
+- The README leads with the AI workflow (specification โ rules โ contracts โ code โ tests). Present new features
+ from that angle first, then in the contract language reference.
## Testing tips
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f74a376..41ab559 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,8 @@ All notable changes to this project are documented in this file. The format is b
2.0.0 - unreleased
------------------
-A rewrite for modern PHP. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration steps.
+A rewrite for modern PHP and for AI-driven development: an Agent Skill lets AI coding agents turn business
+specifications into contracted code and tests. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration steps.
### Added
diff --git a/README.md b/README.md
index 36314c5..956986b 100644
--- a/README.md
+++ b/README.md
@@ -2,37 +2,50 @@
# PhpDeal
-**Design by Contract for modern PHP**
+**AI Design by Contract for PHP**
-Declare preconditions, postconditions and invariants with native attributes.
-PhpDeal checks them on every call, powered by [Go! AOP](https://github.com/goaop/framework).
+Your AI agent turns business specifications into code that checks its own rules.
+PhpDeal enforces those rules on every call, as native PHP attributes powered by [Go! AOP](https://github.com/goaop/framework).
[](https://github.com/php-deal/framework/actions/workflows/ci.yml)
[](https://packagist.org/packages/php-deal/framework)
[](https://packagist.org/packages/php-deal/framework)
[](https://www.php.net/releases/8.4/)
+[](skills/design-by-contract/SKILL.md)
[](https://github.com/goaop/framework)
[](https://phpstan.org/user-guide/rule-levels)
[](LICENSE)
+You write the rules in plain language:
+
+> **R1.** A deposit is a positive amount.
+> **R2.** A deposit adds the amount to the balance.
+> **R3.** The balance is never negative.
+
+Your agent turns them into contracts, the code and the tests:
+
```php
use PhpDeal\Attribute\{Ensure, Invariant, Verify};
-#[Invariant('$this->balance >= 0')]
+#[Invariant('$this->balance >= 0')] // R3
class Account
{
private float $balance = 0.0;
- #[Verify('$amount > 0')]
- #[Ensure('$this->balance === $__old->balance + $amount')]
+ #[Verify('$amount > 0')] // R1
+ #[Ensure('$this->balance === $__old->balance + $amount')] // R2
public function deposit(float $amount): void
{
$this->balance += $amount;
}
}
+```
+
+When the code or its caller breaks a rule, PhpDeal stops the call and names the rule:
+```php
new Account()->deposit(-10);
// PhpDeal\Exception\PreconditionViolation:
// Precondition "$amount > 0" violated in Account->deposit(-10.0)
@@ -40,45 +53,193 @@ new Account()->deposit(-10);
## Contents
-- [Why Design by Contract?](#why-design-by-contract)
+- [Why AI Design by Contract?](#why-ai-design-by-contract)
+- [How it works](#how-it-works)
+- [Quick start](#quick-start)
+- [What the agent delivers](#what-the-agent-delivers)
+- [The contract checker](#the-contract-checker)
- [Features](#features)
-- [Installation](#installation)
-- [Setup](#setup)
-- [Contracts](#contracts)
- - [Preconditions: `#[Verify]`](#preconditions-verify)
- - [Postconditions: `#[Ensure]`](#postconditions-ensure)
- - [Invariants: `#[Invariant]`](#invariants-invariant)
- - [Inheritance: `#[Inherit]`](#inheritance-inherit)
-- [Writing expressions](#writing-expressions)
-- [Handling violations](#handling-violations)
-- [PHPStan integration](#phpstan-integration)
-- [AI coding agents](#ai-coding-agents)
-- [Production](#production)
+- **The contract language**
+ - [Setup](#setup)
+ - [Contracts](#contracts): [`#[Verify]`](#preconditions-verify), [`#[Ensure]`](#postconditions-ensure),
+ [`#[Invariant]`](#invariants-invariant), [`#[Inherit]`](#inheritance-inherit)
+ - [Writing expressions](#writing-expressions)
+ - [Handling violations](#handling-violations)
+ - [PHPStan integration](#phpstan-integration)
+ - [Production](#production)
- [Upgrading from 1.x](#upgrading-from-1x)
- [Contributing](#contributing)
-## Why Design by Contract?
+## Why AI Design by Contract?
+
+An AI agent writes code faster than anyone can review it. The hard question is no longer *how* to implement a
+feature but *whether the code does what the business asked*. The usual answers fall short:
+
+- **Review** does not scale to every line an agent writes.
+- **Tests written by the same agent** share its reading of the requirements. When the agent misreads a rule, the
+ code and the tests agree with each other, and both are wrong.
+- **Requirements in a ticket** are forgotten by the next change, whether a person or an agent makes it.
+
+[Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) closes that gap. Every business rule becomes
+an executable contract that lives next to the code it constrains:
+
+- **Preconditions** (`#[Verify]`) are what the caller must guarantee before a call.
+- **Postconditions** (`#[Ensure]`) are what the method promises after it returns.
+- **Invariants** (`#[Invariant]`) are what is always true of an object between calls.
+
+PhpDeal checks them on every call. That gives each party something it lacked:
+
+| For... | Contracts give you |
+|------------------|------------------------------------------------------------------------------------------------------------|
+| **You** | A one-line, reviewable statement of each rule, traced to the specification, instead of hundreds of lines of code |
+| **The agent** | An immediate, exact signal: which rule broke, in which method, with which arguments. It fixes the code instead of guessing |
+| **The tests** | An oracle on every call. Any test that drives the object through valid calls also checks every postcondition and invariant |
+| **The next change** | Rules that stay enforced. A later edit, by a person or an agent, can not quietly break one |
+
+A broken contract is a bug, reported at the exact place where it happens, before a corrupt state travels through
+the application.
+
+## How it works
+
+PhpDeal ships an [Agent Skill](https://agentskills.io), [`design-by-contract`](skills/design-by-contract/SKILL.md),
+that teaches your coding agent the whole workflow:
+
+```mermaid
+flowchart LR
+ spec[Business
specification] --> rules[Numbered
rules]
+ rules --> contracts[Contracts:
Verify, Ensure,
Invariant]
+ contracts --> code[Code]
+ code --> checker[Contract
checker]
+ checker --> tests[Tests derived
from contracts]
+ tests --> report[Rule table,
assumptions,
open questions]
+ tests -- violation --> code
+```
+
+1. **Extract the rules.** The agent reads the specification, numbers every rule (`R1`, `R2`, ...), and writes down
+ ambiguities as open questions instead of guessing.
+2. **Classify them.** Each rule becomes a precondition, a postcondition or an invariant. A business error that users
+ see, such as *"this room is already booked"*, stays as explicit code, because contracts are usually off in
+ production.
+3. **Write the code** with the contracts on the classes and interfaces, each one tagged with its rule ID.
+4. **Check the contracts.** A bundled checker finds mistakes inside the contract strings, which neither PHP nor
+ PHPStan see.
+5. **Derive the tests.** These cover the examples of the specification, the boundaries of every precondition,
+ the business errors, and random sequences of valid calls sampled from the preconditions. The contracts judge
+ every step.
+6. **Report.** The agent ends with a table that maps each rule to its contract, its code and its test, plus the
+ assumptions it made and the questions for the business.
+
+## Quick start
+
+**1. Install the library** (PHP 8.4+):
-[Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) treats the public API of a class as a formal
-agreement between the class and its callers:
+```bash
+composer require php-deal/framework
+```
-- **Preconditions** are the requirements upon the caller: what must be true before a method is called.
-- **Postconditions** are the promises of the method: what is true after it returns.
-- **Invariants** are the properties of an object that always hold between calls.
+**2. Start the contract kernel** in your test bootstrap (and in development), before your classes are loaded. See
+[Setup](#setup) for all options:
+
+```php
+use PhpDeal\ContractApplication;
-If the caller meets the requirements, the class delivers the promised service. A broken contract is a bug, and
-PhpDeal reports it at the exact place where it happens instead of letting a corrupt state travel through the
-application. The contracts live next to the code they describe, so they double as precise, executable
-documentation.
+require __DIR__ . '/../vendor/autoload.php';
+
+ContractApplication::getInstance()->init([
+ 'debug' => true,
+ 'appDir' => __DIR__ . '/..',
+ 'cacheDir' => __DIR__ . '/../var/cache/contracts',
+ 'includePaths' => [__DIR__ . '/../src'],
+]);
+```
+
+**3. Give your agent the skill.** In [Claude Code](https://claude.com/claude-code), install the plugin from this
+repository:
+
+```
+/plugin marketplace add php-deal/framework
+/plugin install php-deal@php-deal
+```
+
+Other agents that read the [Agent Skills](https://agentskills.io) format can load the folder
+[`skills/design-by-contract`](skills/design-by-contract) directly. Composer installs it too, at
+`vendor/php-deal/framework/skills/design-by-contract`, in the version that matches your library.
+
+**4. Hand over the specification:**
+
+> Implement docs/booking-spec.md with Design by Contract, and write the tests.
+
+In Claude Code you can also call the skill explicitly with `/php-deal:design-by-contract`.
+
+## What the agent delivers
+
+The [worked example](skills/design-by-contract/examples/inventory) shows a complete run. Our CI weaves and runs it on
+every change:
+
+- [`SPEC.md`](skills/design-by-contract/examples/inventory/SPEC.md): nine stock-keeping rules, written for people;
+- [`StockItem.php`](skills/design-by-contract/examples/inventory/StockItem.php): the class, with each contract
+ tagged by its rule;
+- [`StockItemTest.php`](skills/design-by-contract/examples/inventory/StockItemTest.php): the tests derived from the
+ rules and the contracts;
+- a rule table:
+
+| Rule | Contract or code | Where | Test |
+|------|----------------------------------------------------------------------------|----------------------------|-------------------------------------------|
+| R3 | `#[Invariant('$this->reserved >= 0 && $this->reserved <= $this->onHand')]` | `StockItem` | random sequences |
+| R6 | `#[Verify('$quantity <= $this->available()')]` | `StockItem::reserve()` | precondition boundaries |
+| R8 | `#[Ensure('$this->onHand === $__old->onHand - $quantity')]` | `StockItem::ship()` | specification example, random sequences |
+| R9 | code: throws `CountBelowReserved`, a business error | `StockItem::recordCount()` | `testCountBelowTheReservationsIsRejected` |
+
+The random sequences are contract-based testing with no extra library. The agent samples valid arguments from the
+preconditions, and every postcondition and invariant checks every step:
+
+```php
+$random = new Randomizer(new Mt19937($seed));
+for ($step = 0; $step < 200; ++$step) {
+ if ($item->available() > 0) {
+ $item->reserve($random->getInt(1, $item->available())); // sampled from #[Verify]
+ }
+ $item->receive($random->getInt(1, 50));
+}
+```
+
+**Does it catch bugs?** We gave an agent with no other context a new specification (meeting-room booking) and only
+the skill. It wrote 46 contracts and 46 tests. Then it planted five bugs, one at a time: an off-by-one error, a wrong
+overlap check, a cancel that deleted every booking, reused ids and a broken free-slot check. Contracts caught all
+five.
+
+## The contract checker
+
+Contracts are PHP expressions in strings, so neither PHP nor PHPStan see their mistakes until the method runs. The
+skill bundles a checker that agents run after every edit. You can run it too, in CI or by hand:
+
+```bash
+php vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php --strict src
+```
+
+It reports syntax errors, misspelled variables, `$__old` or `$__result` in the wrong contract, `$this` in static
+methods, class names that `use` imports do not resolve, double-quoted strings, assignments, reads of the clock or
+random values, and `\in_array()` without strict comparison.
## Features
+**For AI-driven development**
+
+- ๐ค **Agent Skill** with the full workflow from specification to tested code, installable as a Claude Code plugin
+ and portable to any agent that reads the Agent Skills format.
+- ๐งญ **Traceable rules**: every contract carries the ID of the business rule it enforces.
+- ๐งช **Tests derived from contracts**: specification examples, precondition boundaries, business errors and seeded
+ random sequences.
+- ๐ **Contract checker** that catches mistakes in expressions before they run.
+- ๐ฏ **Exact feedback**: a violation names the contract, the class, the method and the arguments, and points to the
+ declaring line, so the agent fixes the right place.
+
+**The contract engine**
+
- โ
**Native PHP attributes**: `#[Verify]`, `#[Ensure]`, `#[Invariant]` and `#[Inherit]`, repeatable where it makes sense.
- ๐งฌ **Contract inheritance** from parent classes and interfaces, with clear and predictable rules.
- ๐ **Full access to the object**: expressions run in the scope of the class and can read private state.
- ๐ฐ๏ธ **`$__old` and `$__result`** to compare the state before and after a call, and to check return values.
-- ๐ฏ **Precise exceptions**: `PreconditionViolation`, `PostconditionViolation` and `InvariantViolation`, pointing to
- the method that declares the contract.
- โก **Fast**: each expression is compiled once, contracts are read once per class, and the object is cloned only when
a contract uses `$__old`.
- ๐ **Recursion-safe**: an invariant may call public methods of its own class.
@@ -86,16 +247,18 @@ documentation.
- ๐ **PHPStan extension** included: properties and methods used only by contracts are not reported as unused.
- ๐งช **Thoroughly tested**, analysed with PHPStan at level 10 with strict rules.
-## Installation
+---
-```bash
-composer require php-deal/framework
-```
+# The contract language
-PhpDeal 2 requires **PHP 8.4** or newer and is built on **Go! AOP 4**.
+The rest of this document is the reference for the contracts themselves: what your agent writes and what you
+review. Everything in it works without an AI as well, and contracts can be written by hand.
## Setup
+PhpDeal 2 requires **PHP 8.4** or newer and is built on **Go! AOP 4**. Contracts are checked only in classes
+that Go! AOP weaves, so the kernel must start before they are loaded.
+
Initialize the contract kernel once, as early as possible in your front controller or test bootstrap, before the
classes with contracts are loaded:
@@ -367,35 +530,6 @@ includes:
- vendor/php-deal/framework/extension.neon
```
-## AI coding agents
-
-PhpDeal ships an [Agent Skill](https://agentskills.io) that teaches AI coding agents to turn a business
-specification into self-checking code: it extracts the rules, maps each one to a `#[Verify]`, `#[Ensure]` or
-`#[Invariant]` (or to plain code for business errors), writes the classes, checks the contract expressions and
-derives PHPUnit tests from the contracts. The tests cover the examples of the specification, the boundaries of the
-preconditions and random sequences of valid calls.
-
-In Claude Code, install it as a plugin from this repository:
-
-```
-/plugin marketplace add php-deal/framework
-/plugin install php-deal@php-deal
-```
-
-Then ask for it, e.g. *"Implement docs/booking-spec.md with Design by Contract"*, or run
-`/php-deal:design-by-contract`. Other agents that read the Agent Skills format can use the folder
-[`skills/design-by-contract`](skills/design-by-contract) directly. It is also installed with the package, at
-`vendor/php-deal/framework/skills/design-by-contract`.
-
-The skill bundles a checker for contract expressions, which works without an AI as well. Contracts are strings, so
-neither PHP nor PHPStan see their mistakes. The checker reports syntax errors, misspelled variables, `$__old` or
-`$__result` in the wrong kind of contract, `$this` in static methods, names that `use` imports do not resolve, and
-more:
-
-```bash
-php vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php src
-```
-
## Production
Contracts are a development and testing tool: every checked call costs an expression evaluation. The usual setup is
diff --git a/composer.json b/composer.json
index a1278f9..4a98301 100644
--- a/composer.json
+++ b/composer.json
@@ -1,6 +1,6 @@
{
"name": "php-deal/framework",
- "description": "Design by Contract framework for PHP: preconditions, postconditions and invariants declared with native attributes",
+ "description": "AI Design by Contract for PHP: AI agents turn business specifications into code with preconditions, postconditions and invariants, checked on every call",
"type": "library",
"keywords": [
"dbc",
@@ -11,7 +11,13 @@
"invariant",
"attributes",
"aop",
- "goaop"
+ "goaop",
+ "ai",
+ "ai-agents",
+ "agent-skills",
+ "claude-code",
+ "specification",
+ "contract-based-testing"
],
"license": "MIT",
"authors": [