Skip to content

Position the documentation around AI Design by Contract - #74

Merged
lisachenko merged 1 commit into
masterfrom
feature/laughing-thompson-gr3zue
Nov 10, 2026
Merged

lisachenko merged 1 commit into
masterfrom
feature/laughing-thompson-gr3zue

Conversation

@lisachenko

Copy link
Copy Markdown
Member

This is a follow-up to php-deal/framework#73. The README now presents PhpDeal as AI Design by Contract for PHP from its first line.

README

The new opening shows the whole idea in one screen:

  • business rules in plain language (R1–R3);
  • the contracts an agent writes from them, each tagged with its rule ID;
  • the violation that names the broken rule.

New sections:

  • Why AI Design by Contract? Review doesn't scale, and tests written by the same agent share its misreading of the requirements. A table shows what contracts give you, the agent, the tests and the next change.
  • How it works: a Mermaid diagram of the skill's loop (spec → rules → contracts → code → checker → tests → report) and the six steps.
  • Quick start: install the library, start the kernel, give the agent the skill (Claude Code plugin or any Agent Skills reader), hand over the spec.
  • What the agent delivers: the worked example, part of its rule table, the contract-based random test, and the test run in which contracts caught 5 of 5 planted bugs.
  • The contract checker, and Features split into "For AI-driven development" and "The contract engine".

The existing reference follows unchanged under The contract language: setup, contracts, expressions, violations, PHPStan, production. The old "AI coding agents" section is folded into the top, and the separate Installation section into Quick start.

Elsewhere

  • composer.json: new description and keywords (ai, ai-agents, agent-skills, claude-code, specification, contract-based-testing). Packagist shows these.
  • AGENTS.md: the project summary, plus a rule to present new features from the AI workflow first.
  • CHANGELOG.md: the 2.0.0 intro.

Checks

  • composer test passes.
  • The new hero example passes the checker and behaves as shown under real weaving.

Generated by Claude Code

The README now opens with the AI workflow: rules in plain language, the
contracts an agent writes from them, and the violation that names the
broken rule. New sections explain why contracts matter for AI-written code,
how the skill works (specification, rules, contracts, code, checker, tests,
report), a quick start that installs the skill, what the agent delivers and
the contract checker. The existing reference follows as "The contract
language", and the old "AI coding agents" section is folded into the top.

The Composer description and keywords, AGENTS.md and the CHANGELOG intro
follow the same positioning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir
@lisachenko
lisachenko marked this pull request as ready for review November 10, 2026 17:48
@lisachenko
lisachenko merged commit afba723 into master Nov 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants