Skip to content

Add a design-by-contract Agent Skill, installable as a Claude Code plugin - #73

Merged
lisachenko merged 2 commits into
masterfrom
feature/laughing-thompson-gr3zue
Nov 10, 2026
Merged

lisachenko merged 2 commits into
masterfrom
feature/laughing-thompson-gr3zue

Conversation

@lisachenko

@lisachenko lisachenko commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

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:

  • The skill holds the logic. The job is knowledge plus a workflow: how to classify a rule, the expression rules, the testing patterns. That is what an Agent Skill is for, and agents load it only when it is relevant. The Agent Skills format is an open standard, so the same folder works in Claude Code and in other agents that read skills. It also ships in the Composer package, so its version matches the installed library.
  • The plugin is only packaging. Two small JSON files make the repository a Claude Code marketplace, so installing takes one command and the skill gets a namespace (/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.
/plugin marketplace add php-deal/framework
/plugin install php-deal@php-deal

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, use imports, 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:

    • syntax errors, and misspelled or unknown variables;
    • $__old/$__result in the wrong contract or in a constructor, and $this in static methods;
    • class names that use imports would not resolve, and double-quoted strings;
    • assignments, reads of the clock or random values, and in_array() without strict comparison;
    • contracts on the wrong target.

    It is useful without an AI too.

  • examples/inventory/: a worked example from start to end. SPEC.md holds rules R1–R9, StockItem.php the contracted class, and StockItemTest.php the 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 skill suite), 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 . --strict passes. Its only warning, a missing icon, applies to Anthropic's plugin directory listing.
  • Installed the plugin from a local checkout with claude plugin marketplace add and claude plugin install, and the skill was found.
  • Every code snippet in the references was run under real weaving and passes the checker.
  • A planted bug in StockItem::ship() was caught by the postconditions in every random run.
  • Test run on a new spec: an agent with no other context implemented a meeting-room booking spec from the skill alone. The result: 46 tests and 46 contracts, a checker run with 0 issues, and a rule table with assumptions and open questions. It planted five bugs on purpose, and contracts caught all five. Its feedback is applied in the second commit.

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

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
lisachenko marked this pull request as ready for review November 10, 2026 17:39
@lisachenko
lisachenko merged commit 2117116 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