For bigger changes, open an issue first so we can discuss.
Two-language project (compiler/runtime in PHP, standard library in Phel):
src/php/ → Compiler, runtime, CLI tools (PHP, Gacela modules)
src/phel/ → Core standard library (Phel source, Clojure-inspired)
tests/php/ → PHPUnit tests
tests/phel/ → Phel tests
docs/ → Guides, examples, internals
Compiler pipeline: Lexer → Parser → Reader → Analyzer → Emitter. Each src/php/ module exposes a Facade as its public API.
For a deeper architecture overview, see docs/internals/architecture.md.
Requires PHP 8.5+ and Composer.
composer install
COMPOSER_PROCESS_TIMEOUT=0 composer test # baseline after setup- Branch from
main(prefixes:feat/,fix/,ref/,docs/) - Write code and tests
- Run the targeted test command for your change
- Run
composer fixto auto-format - Open a PR following the PR template
Day-to-day:
COMPOSER_PROCESS_TIMEOUT=0 composer test # Run everything (quality + compiler + core)
composer fix # Auto-format (Rector + CS Fixer)
composer create-pr # Open a PRTesting:
composer test-compiler # PHPUnit (unit + integration)
composer test-core # Phel's own test framework
composer test-quality # Static analysis + lintingStatic analysis:
composer psalm # Psalm
composer phpstan # PHPStan
composer csrun # Code style check
composer rector # Rector checkBenchmarks:
composer phpbench # Run benchmarks
composer phpbench-base # Create baseline
composer phpbench-ref # Compare to baselineBuild:
./build/phar.sh # Produce build/out/phel.pharStart with tests for the changed behavior and its affected integration path. Broaden for cross-cutting changes, failures or explicit requirements. Run affected quality checks after reviewing the final diff, and reuse passing results on unchanged code.
| Scope | Command | Notes |
|---|---|---|
| PHP behavior | ./vendor/bin/phpunit --filter=ClassOrMethod |
Include affected integration tests |
| Single Phel file | ./bin/phel test tests/phel/<file> |
Target specific test |
| Compiler fixture | ./vendor/bin/phpunit --testsuite=integration --filter=fixture-stem |
Generate expected PHP from the actual output |
| Compiler test group | composer test-compiler |
PHPUnit unit + integration |
| Standard library test group | composer test-core |
Phel core tests |
| Quality checks | composer test-quality |
Formatter, static analysis and config; use affected checks when isolating a change |
| Full gate | COMPOSER_PROCESS_TIMEOUT=0 composer test |
Run when broader coverage is needed |
See the testing docs for more on the Phel test framework.
Optional but recommended:
tools/git-hooks/init.shInstalls a pre-commit hook that runs composer test-all when PHP or Phel files are staged. Let required hooks complete and reuse a successful gate on unchanged code. Fixture-only changes still need the selected checks because .test files do not trigger this hook.
We use conventional commits:
feat: add new string utility function
fix: correct off-by-one in map iteration
ref: simplify compiler analyzer phase
docs: update quickstart guide
test: add integration tests for try/catch
chore: bump phpstan to v2
For user-facing changes (feat:, fix:), update CHANGELOG.md under ## Unreleased. Sections come in this order, each once: Changed, Added, Removed, Performance, Fixed. Write short entries that say what the user sees, merge bullets about the same change, and end with the refs: (#1234). Full style: .agnostic-ai/rules/changelog.md.
.agnostic-ai/ is the single source for the agent config used on this repository. agnostic-ai generates Claude Code (.claude/, CLAUDE.md) and Codex (.codex/, .agents/, AGENTS.md) from it. The generated files are gitignored, so run sync after cloning and after every spec change. agnostic-ai.yaml pins stable 0.90.0 to match CI; agnostic-ai upgrade --version v0.90.0 installs it.
Each PHP module is documented by a rule scoped to its directory, .agnostic-ai/rules/module-<name>.md. Sync emits it as src/php/<Module>/AGENTS.md for Codex and as a path-scoped rule under .claude/rules/ for Claude Code. Edit the rule, not the output.
brew install Chemaclass/tap/agnostic-ai # or: go install github.com/chemaclass/agnostic-ai/cmd/agnostic-ai@v0.90.0
agnostic-ai syncEdit the specs under .agnostic-ai/, never the generated files. Add a target (Gemini, Cursor, ...) under targets: in agnostic-ai.yaml. Run agnostic-ai validate, agnostic-ai lint --strict, agnostic-ai sync, and agnostic-ai sync --check after spec changes. CI runs the same checks. For scope changes, inspect a representative file with agnostic-ai explain --file <path> --target codex and --target claude; for instruction size, use agnostic-ai explain --context --target <target>.
Issues labeled good first issue are scoped and newcomer-friendly.
| Interest | Start here | Tests |
|---|---|---|
| Fix/add a language feature | src/php/Compiler/ |
composer test-compiler |
| Improve the standard library | src/phel/ |
composer test-core |
| Improve tooling (REPL, formatter) | src/php/Run/, src/php/Formatter/ |
composer test-compiler |
| Improve documentation | docs/ |
none |
| Add PHP interop wrappers | src/php/Interop/ |
composer test-compiler |
composer test fails after fresh clone? Check PHP 8.5+ (php -v) and run composer install again.
Tests pass locally but CI fails? Inspect the failing job and reproduce its affected test or group. Broaden local coverage when the failure shows the initial scope was incomplete.
Code style errors? Run composer fix.