Repository navigation
Add a design-by-contract Agent Skill, installable as a Claude Code plugin - #73
Merged
Merged
Conversation
The skill teaches AI coding agents to turn a business specification into self-checking PHP code: extract and number the rules, map each one to a precondition, postcondition, invariant or business error, write the classes, check the expressions, and derive PHPUnit tests from the contracts (specification examples, precondition boundaries, business errors and seeded random sequences of valid calls). This is the AI-assisted take on contract-based test generation from #36. - skills/design-by-contract: SKILL.md, references for setup, expressions, rule patterns and testing, and a worked inventory example that the test suite weaves and runs, so it can not go stale - scripts/lint-contracts.php: a dependency-free checker for contract expressions (syntax, unknown variables, $__old/$__result misuse, $this in static methods, names that `use` imports would not resolve, quoting) - .claude-plugin: the repository is a plugin marketplace, so Claude Code users install it with /plugin marketplace add php-deal/framework Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir
A fresh agent implemented a new specification (meeting-room bookings) with the skill alone; its feedback is folded in here. - Checker: warn about $__result and $__old in constructors, contracts that read the clock or random values, and in_array()/array_search()/ array_keys() without their strict argument - Skill: constructors, private and final classes are supported; check the items of a variadic, not the list; record implied API data as assumptions; weaving check when there is no composer.json; "Where" column in the rule table - References: break-the-code tip to prove that contracts catch bugs, and a note on opcache JIT crashes on the first weaving run Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir
lisachenko
marked this pull request as ready for review
November 10, 2026 17:39
This was referenced Nov 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #36. The issue asks for tests generated from contracts. This PR goes one step earlier: an AI agent turns a business specification into contracted code, then derives the tests from those contracts and from the spec.
Skill or plugin?
Both, with the skill as the core:
/php-deal:design-by-contract). An MCP server or hooks would add nothing here: there is no external system to call, and an always-on hook would be intrusive.What's in it
skills/design-by-contract/SKILL.md: an 8-step workflow. Check the setup, extract and number the rules, classify each one, design the API, write the code, run the checker, derive the tests, then report a table that maps each rule to its contract and test, plus assumptions and open questions. The skill separates contracts (programming errors, which may be off in production) from business errors that users see (handled in code).references/: setup, the expression reference and its pitfalls (shallow$__old, floats,useimports, variadics, constructors, dates), a catalogue of rule patterns (ranges, state machines, collections, implications), and tests from contracts.scripts/lint-contracts.php: a contract checker with no dependencies. Contracts are strings, so PHP and PHPStan never see their mistakes. It reports:$__old/$__resultin the wrong contract or in a constructor, and$thisin static methods;useimports would not resolve, and double-quoted strings;in_array()without strict comparison;It is useful without an AI too.
examples/inventory/: a worked example from start to end.SPEC.mdholds rules R1–R9,StockItem.phpthe contracted class, andStockItemTest.phpthe four kinds of derived tests: spec examples, precondition boundaries, business errors, and seeded random sequences of valid calls checked by the contracts.The test suite now weaves and runs the example (new
skillsuite), and the checker has its own tests, so the docs can't go stale.Other changes:
skills/is added to the PHPStan and PHP-CS-Fixer paths, and README (AI coding agents section), CHANGELOG and AGENTS.md are updated..claude-plugin/is export-ignored.Verification
composer test: style, PHPStan level 10 and 168 tests all pass. CI passes.claude plugin validate . --strictpasses. Its only warning, a missing icon, applies to Anthropic's plugin directory listing.claude plugin marketplace addandclaude plugin install, and the skill was found.StockItem::ship()was caught by the postconditions in every random run.Possible follow-up
A PHPStan rule based on the checker would report contract mistakes inside the existing PHPStan run.
🤖 Generated with Claude Code
https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir