Skip to content

CLAUDE.md

Latest commit

 

History

History
92 lines (62 loc) · 5.49 KB

CLAUDE.md

File metadata and controls

92 lines (62 loc) · 5.49 KB
Raw

php-core-developer

Claude Code plugin for developing the PHP language core (php/php-src).

Execution model

One agent (php-core-dev), eight skills, one living document per task. Each step is one slash command run by the user.

Workflow Living doc Skills (run in order)
Bug fix SPEC.md /bug-context <gh-issue> → /research → /bug-reproduce-test → /bug-fix → /bug-verify
Upmerge (after a bug fix on a non-master branch) UPMERGE.md /upmerge (dry-run) → /upmerge --execute
Idea prototype SPEC.md /idea-prototype "<one-line hypothesis>" (advances Context → Hypothesis & Metric) → /research (Research phase) → /idea-prototype (Survey & Plan → Prototype → Verdict)
Code review (local) REVIEW.md /review-local [base-ref]
Code review (PR) REVIEW.md /review-pr <pr-number>

/research gating differs by flow:

  • Bug fix: soft-gated. /bug-reproduce-test / /bug-fix / /bug-verify warn if Research is todo but proceed anyway.
  • Idea prototype: hard-gated. /idea-prototype refuses to advance past Hypothesis & Metric until Research is done or explicitly skipped in SPEC.md. Prior-art sweeps catch declined RFCs and abandoned attempts that would otherwise waste a prototype.

Mark the phase skipped in SPEC.md (with reason) to bypass either gate.

SPEC.md is the state

For bug and idea workflows the entire task state lives in SPEC.md in the working directory. It's organised as Phase → Step → Guardrail:

  • A phase is a top-level workflow stage (Context, Reproduction, Analysis & Plan, …).
  • A step is a concrete action with its own status (todo / in-progress / done / skipped / blocked).
  • A guardrail is a pre- or post-condition gated against a step. Pre-guardrail fails → skill refuses to start; post-guardrail fails → step marked blocked.

Each skill on every invocation: read SPEC.md, find the first non-done phase / step, run pre-guardrails, do the work, run post-guardrails, mark done, append one line to the Progress Log. Close the terminal mid-phase; the next slash command resumes from there.

See plugins/php-core-developer/skills/_shared/spec-md-format.md for the full schema.

REVIEW.md is one-shot

Code reviews don't resume. Re-running a review skill overwrites REVIEW.md after backing up the prior version to REVIEW.md.bak. Format spec: plugins/php-core-developer/skills/_shared/review-md-format.md.

Working-directory convention

The user cds into a per-task scratch directory before invoking skills. SPEC.md or REVIEW.md is written to pwd. The plugin does not create or hunt for task directories — that's the user's choice.

Examples:

mkdir -p ~/php-work/gh-12345 && cd ~/php-work/gh-12345
# /bug-context 12345
# /bug-reproduce-test
# /bug-fix
# /bug-verify

mkdir -p ~/php-work/idea-zstring-cache && cd ~/php-work/idea-zstring-cache
# /idea-prototype "caching common zend_string parameter names could speed up function calls"
# /idea-prototype   # rerun to advance to the next phase

Configuration

No configuration step. Skills auto-resolve PHP_SRC_DIR per invocation:

  1. If PHP_SRC_DIR env var is set and valid → use it (override).
  2. Else walk up from $PWD looking for a php-src checkout (Zend/ + main/ + ext/ + configure.ac) → use that.
  3. Else refuse with instructions.

Common case: cd anywhere inside the php-src checkout (the user's preferred convention is a .work/<task>/ subdir, gitignored) and the plugin activates automatically. For work outside the checkout, export PHP_SRC_DIR=/path/to/php-src first.

See plugins/php-core-developer/skills/_shared/php-src-detection.md for the full resolution algorithm.

Reference files used by skills

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

File Purpose
spec-md-format.md SPEC.md canonical schema and resume algorithm
review-md-format.md REVIEW.md canonical schema and severity rubric
php-coding-standards.md Condensed php-src CODING_STANDARDS.md
phpt-format.md .phpt test format and run-tests.php reference
build-and-test.md ./buildconf, ./configure, make, test commands, gh CLI reference
search-strategies.md Keyword extraction + Algolia/gh/git-log queries used by /research
php-src-detection.md How skills resolve PHP_SRC_DIR (env-var override + cwd walk-up)
task-dir.md Where SPEC.md / REVIEW.md / UPMERGE.md live + .current marker semantics
test-modification-policy.md Provenance lookup required before changing any existing .phpt; blocks unjustified regression-test rewrites
branch-detection.md Runtime resolution of maintained php-src branches via .github/matrix.php; placeholder convention; lowest-affected-branch resolver

Skills point at these files instead of restating them. When the official php-src docs change, refresh these copies.

What this plugin is NOT

  • Not a code generator for RFCs. /idea-prototype ends with a verdict (pursue-as-rfc / reframe / kill) but does not draft the wiki.php.net RFC document — that's still on the human.
  • Not remote git-mutating. Skills do commit locally at defined checkpoints (one commit per /bug-fix; per-phase commits in /idea-prototype). They never git push, never modify git remote *, never git pull, and never post to GitHub without explicit user "yes". Commits land on whatever branch is checked out — skills don't create or switch branches.