php-core-developer

A Claude Code plugin for working on the PHP language core (php/php-src).

Three workflows: bug fixing, idea prototyping, and code review. Every task is captured in a living document (SPEC.md for bugs and ideas, REVIEW.md for reviews) under .claude/php-core-dev/<slug>/ inside your php-src checkout, so work is stoppable mid-flow and resumable from exactly where the last invocation left off.

---

Quickstart

# 1. One-time install in Claude Code:
/plugin marketplace add /path/to/php-src-developer
/plugin install php-core-developer

# 2. In a terminal, go to your php-src checkout and cut a branch:
cd ~/projects/php-src
git checkout -b fix/gh-12345 master      # name the branch after the task

# 3. Launch Claude Code from there:
claude

Then drive the workflow with prompts:

You want to…	First prompt
Fix a bug	Fix php-src issue GH-12345
Prototype an idea	/idea-prototype "caching common zend_string parameter names could speed up function calls"
Review your local diff	/review-local
Review a GitHub PR	/review-pr 12345

Prerequisites: the plugin runs inside a php-src checkout (any subdirectory works — the plugin walks up to find the root). Recommended before first use:

cd ~/projects/php-src
./buildconf && ./configure --enable-debug && make -j$(nproc)
gh auth login     # for /bug-context, /research, /review-pr

---

Workflows

Bug fix — /bug-context → /research → /bug-reproduce-test → /bug-fix → /bug-verify

cd ~/projects/php-src
git checkout -b fix/gh-12345 master
claude

In Claude Code:

Step	Slash command	What it does
1	/bug-context 12345	Fetches the GH issue with gh issue view, writes Context phase of SPEC.md, stubs out the remaining phases.
2	/research	Sweeps prior discussion across four sources: php.internals (via externals.io Algolia), gh issue list, gh pr list, git log --grep. Populates Research phase with synthesised findings. Soft-gated — downstream steps warn if skipped, never block.
3	/bug-reproduce-test	Writes a minimal repro.php, converts it into a .phpt test under tests/..., runs run-tests.php, asserts FAIL (post-guardrail). Stages the test (git add) — does not commit yet.
4	/bug-fix	Pins the root cause in C code (consulting Research findings), plans the change, implements it, rebuilds, asserts the .phpt now PASSES. Commits test + fix as one commit (Fix GH-NNNNN: <subject>) on the current branch.
5	/bug-verify	Runs the related test directory + checks for new compiler warnings. Marks the task done.

Close the terminal at any point. Re-open it, cd back to the checkout, and run the next prompt (or re-run the last) — the skill reads SPEC.md from .claude/php-core-dev/gh-12345/, finds the first non-done phase, and continues.

Idea prototype — /idea-prototype "<one-line hypothesis>"

cd ~/projects/php-src
git checkout -b idea/zstring-cache master
claude

/idea-prototype "caching common zend_string parameter names could speed up function calls"

One skill that walks the hypothesis through six phases: Context → Hypothesis & Metric → Research → Survey & Plan → Prototype → Measurement & Verdict. Re-run /idea-prototype (no argument) to advance to the next phase. When the next phase is Research, run /research instead (it owns that phase across both bug and idea flows). The metric must be falsifiable — the skill refuses fuzzy hypotheses ("it'll be faster") at the Hypothesis & Metric guardrail.

End state: SPEC.md with a verdict of pursue-as-rfc / reframe / kill, plus the prototype patch and the benchmark or example evidence. Commits land at the end of Prototype and Measurement phases.

Code review (local) — /review-local [base-ref]

cd ~/projects/php-src
git checkout my-fix-branch
claude

/review-local

Defaults to git merge-base HEAD origin/master. Override with /review-local PHP-8.3 or a SHA. Writes REVIEW.md with severity-graded findings (Blocker / Major / Minor / Nit) anchored to path:line. Read-only against the source tree.

Code review (GitHub PR) — /review-pr <pr-number>

/review-pr 12345

Fetches the PR via gh, reviews against the same rubric as review-local, writes REVIEW.md. After writing, asks whether to post findings as inline PR comments. On yes, posts Blockers + Majors by default; asks again before including Minors; never posts Nits.

---

SPEC.md and REVIEW.md

Living documents written to .claude/php-core-dev/<slug>/ inside your php-src checkout (gitignored). Slugs:

• gh-NNNNN for bug fixes
• idea-<kebab> for idea prototypes
• pr-NNNNN for PR reviews
• review-<short-sha> for local reviews

SPEC.md is organised as Phase → Step → Guardrail:

---
type: bug
status: in-progress
title: array_filter() with ARRAY_FILTER_USE_KEY loses references
created: 2026-05-20
php_src_ref: master@a3b1c2d
linked: https://github.com/php/php-src/issues/12345
---

# array_filter() with ARRAY_FILTER_USE_KEY loses references

## Context
…

## Phase: Reproduction — status: done
### Guardrails
- [x] **pre**: sapi/cli/php exists
- [x] **post**: new .phpt fails on current build
### Steps
- [x] **repro-script** — …
- [x] **phpt-failing** — …

## Phase: Analysis & Plan — status: in-progress
…

## Open Questions
…

## Progress Log
- 2026-05-20 14:02 — bug-context — Context filled from GH-12345
- 2026-05-20 14:18 — bug-reproduce-test — phpt-failing at … FAILs as expected

Status values used at phase and step level: todo · in-progress · done · skipped · blocked.

The full schema lives in plugins/php-core-developer/skills/_shared/spec-md-format.md.

REVIEW.md is simpler — frontmatter, severity-grouped findings, no phases (a review is a single pass over a diff).

---

Optional configuration

The plugin auto-detects your php-src checkout by walking up from the current directory until it finds one (Zend/ + main/ + ext/ + configure.ac). No /install step.

For non-standard layouts (e.g. running Claude Code outside the checkout), set:

export PHP_SRC_DIR=/absolute/path/to/php-src

The env var takes precedence over the walk-up. Optional second env var:

export PHP_CORE_TASK_DIR=/absolute/path/where/SPEC.md/should/live

Lets you keep task state outside the checkout (e.g. a separate scratch dir per machine).

---

Reference docs the skills read

In plugins/php-core-developer/skills/_shared/:

File	Purpose
spec-md-format.md	Canonical SPEC.md schema and resume algorithm
review-md-format.md	Canonical REVIEW.md schema and severity rubric
php-coding-standards.md	Condensed php-src CODING_STANDARDS.md (K&R tabs, emalloc/efree, naming, error phrasing)
phpt-format.md	.phpt test format with section reference, format specifiers, and run-tests.php examples
build-and-test.md	./buildconf, ./configure, make, parallel testing, warning baseline, gh CLI usage
search-strategies.md	Keyword extraction + Algolia/gh/git-log queries used by /research
php-src-detection.md	How skills resolve the php-src checkout (env-var override + cwd walk-up)
task-dir.md	Where SPEC.md / REVIEW.md live + .current marker semantics
test-modification-policy.md	Provenance lookup required before changing any existing .phpt — blocks fixes that silently rewrite intentional regression coverage

When the official php-src docs change, refresh these copies — they're snapshots, not the source of truth.