Save this content to: AGENTS.md

# Agent guidelines — projectsaturnstudios/pocketflow-php

## Knowledge Bundle (OKF)

This package ships an Open Knowledge Format bundle at [`.okf/`](.okf/) (excluded from Composer dist via `.gitattributes` `export-ignore`).

Before changing PocketFlow code or advising on Node/Flow orchestration:

1. Read [`.okf/index.md`](.okf/index.md) first (progressive disclosure).
2. Open only the linked concepts needed for the task.
3. Prefer `status: stable` concepts; treat `deprecated` as historical only. New agent-written concepts stay `status: draft` until a human verifies them.
4. When you learn something durable about **this package**, update the affected `.okf` concept(s) and append `.okf/log.md`.
5. Keep knowledge at the package-root `.okf/` only — do not nest `.okf` under `src/`.
6. Scope claims to **pocketflow-php**. Fabricate Sketches and ScrapyardIO installer details belong in those packages’ own docs / `.okf` bundles.

## Package rules (quick)

- Composer: `projectsaturnstudios/pocketflow-php`. PHP `^8.4`.
- Namespace: `ProjectSaturnStudios\PocketFlow\` → `src/`.
- Port of [The-Pocket/PocketFlow](https://github.com/The-Pocket/PocketFlow): decision-based graph orchestration (not an onion middleware pipeline).
- Sync entry: `Flow::run(&$shared)` / `Node::run(&$shared)`. Async: `run_async(&$shared)` returning ReactPHP promises.
- Durable state lives in `$shared`. Flows clone nodes each hop — do not rely on instance properties across hops.
- Prefer `is_null($x)` over `$x === null`. No class-level constants for value sets — use backed enums if you add enums later.
- Tests: Pest v4 (`composer test`). Do not commit `vendor/` or `.phpunit.cache`.