instructor-php AGENTS.md

Key Reference Files

Monorepo Root

• CONTRIBUTING.md - Development workflows, package management, and contribution guidelines
• CONTENTS.md - Project structure and package overview
• README.md - Main project documentation
• HARD REFERENCE - CONTRIBUTING.md is the source of truth for QA execution (composer qa, qa:*) and contribution workflow details.

Individual Subpackages

Each package in packages/ may contain:

• README.md - Package-specific documentation
• OVERVIEW.md - Package overview and architecture
• INTERNALS.md - Implementation details and internal structure
• CHEATSHEET.md - Quick reference for package usage

Code Style

• Use strict types and type hints for arguments and return values everywhere
• Do not nest control structures (if, loops) beyond 1 level, exceptionally 2 levels
• Use match for complex conditionals - avoid if/else if chains or switch statements; avoid ternary operators
• Prefer immutable data structures and functional programming paradigms
• Avoid using arrays as collections - use dedicated collection classes
• Avoid exceptions for control flow - do not wrap everything in try/catch; either let exceptions bubble up or use monadic Cognesy\Utils\Result\Result for error handling if error needs to be handled on the same level
• Use namespaces and PSR-4 autoloading

Agents Package Style

• Data classes are readonly final class — all properties readonly, all mutations return new instances via with*() methods
• Interfaces use Can- prefix (CanUseTools, CanEmitAgentEvents, CanInterceptAgentLifecycle)
• Hooks use Hook suffix (StepsLimitHook, ErrorPolicyHook)
• Accessors have no prefix: state(), execution(), currentStep() — not getState()
• Mutators use with prefix and return self: withState(), withCurrentStep()
• Named constructors for defaults: ::empty(), ::fresh(); for hydration: ::fromArray()
• Minimal docblocks — only on class/interface declarations; methods are self-documenting via types and naming
• Method order: constructors → lifecycle/transitions → accessors → mutators → private helpers → serialization (toArray/fromArray)
• Enums are string-backed for serialization; put logic (priority, comparison) as methods on the enum itself
• Use match(true) { ... } for multi-condition branching
• Use $this->field ?? Default::empty() pattern ("ensure pattern") to provide defaults instead of null-checking