[coisa]

Closes #76. Refs #4 (the broader PHPDoc/Rector migration remains partial).

Add the canonical fast-forward-phpdoc authoring skill beside the existing tooling-consumption skill. It teaches short summaries, implementer-independent interface contracts, proportionate BCP 14 language, meaningful tags and preservation of inherited documentation. README, the instruction map and root contract expose the new payload; Git/Composer archive tests verify its complete shipped contents.

The procedure adapts DevTools' real phpdoc-code-style skill at 84e154046e07cafa6ac09a9e12434b1ff5dcb5e0; source/ref and MIT attribution are retained. The revised global PHPDoc skill was consulted but not copied or modified. DevTools remains unchanged: replacement with a released-payload compatibility pointer is a separate migration, preserving its consumers.

Validation of signed HEAD 4e43857354d27fb2d701af4c2fc0dc3255d7324f, tree 9ff3c4ea1d54a1d7e465e2b70b698020e9a0fa3e:

• Independent exact-tree content, licence, discoverability and source-contract review: no blocking findings.
• Official skills-ref validates both bundled skills. Existing validator source is agentskills/agentskills@69ef37e9424c0a7ea9dd2293b559e43ec8176379; its seven installed modules byte-match the source. No Python or validator dependency is added to this PHP repository.
• Own locked installation: 57 packages, zero updates, no plugins/scripts, manifest/lock unchanged.
• composer check: 156 tests / 1,256 assertions / one explicit skip for an unavailable DOM-free runtime. Strict Composer/platform, Git and Composer ArchiveTest, syntax and ECS pass.
• Relative links, root-license equality and whitespace checks pass.

This independent branch targets main. Its parent is 6d15522; current main includes the separately merged contracts PR #74. Hosted PR checks must validate the resulting main integration before merge. No installer, consumer rollout, global activation, dependency change or release is included.

[coderabbitai]

📝 Summary

Summary by CodeRabbit

• New Features

  • Added a portable PHPDoc authoring and review skill with guidance for documenting interface contracts, preserving meaning, and verifying documentation against project behavior.
  • The skill is available as a separate resource and does not automatically install or activate for consumers.

• Documentation

  • Updated project guidance to clarify the distinct roles of the code-standards and PHPDoc skills.
  • Added guidance on preserving existing documentation, checking rendered output, and validating PHPDoc changes.

Adds a portable PHPDoc authoring skill with guidance for contract documentation, preservation, and verification. Updates repository skill guidance and discovery references, and adds archive checks for the new skill payload and license.

Changes: PHPDoc Skill

Layer / File(s)	Summary
PHPDoc guidance and payload resources/skills/fast-forward-phpdoc/*	Adds authoring, interface-contract, cleanup, and verification guidance. Includes attribution and license files.
Skill ownership and discovery AGENTS.md, README.md, docs/instruction-map.rst, resources/skills/fast-forward-code-standards/SKILL.md, .changelog/phpdoc-authoring-skill.md, resources/skills/fast-forward-phpdoc/SKILL.md	Updates skill ownership, discovery, and use guidance. States that skill selection and activation remain explicit.
Archive payload checks tests/Distribution/ArchiveTest.php	Copies regular files under resources/skills into the archive fixture and checks the PHPDoc skill files and license against their sources.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Possibly related issues

• [architecture] Plan domain-owned tooling extraction and DevTools orchestration dev-tools#240: Defines domain-owned portable skills, with Code Standards as the owner of PHPDoc policy.
• Extract PHPDoc policy and opt-in semantic refactoring #4: Assigns source PHPDoc policy and a canonical procedure or skill to Code Standards.
• Document normative interface contracts and preserve their PHPDoc #72: Specifies PHPDoc summaries, interface contracts, BCP 14 usage, and inheritance preservation addressed by the new guidance.
• [architecture] Map domain-owned skills and replace redundant agent distribution dev-tools#195: Calls for domain-owned skill sources and visible provenance without a replacement installer or synchronization mechanism.
• [architecture] Make DevTools the profile-based bootstrap and upgrade orchestrator for domain packages dev-tools#384: Calls for portable, domain-owned skills with explicit provenance and no copied procedures in DevTools.

Possibly related PRs

• php-fast-forward/code-standards#7: Established the canonical skill distribution model and archive coverage extended here.
• php-fast-forward/code-standards#70: Established per-skill licensing and archive checks that this change applies to the PHPDoc payload.
• php-fast-forward/code-standards#74: Defined interface-contract and BCP 14 guidance reflected in the new PHPDoc skill.

Merge Risk: Minimal · up to 4e438

No concrete merge-blocking issue is established by the repository evidence.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title "feat: add a portable PHPDoc authoring skill" matches the main change. The PR adds the fast-forward-phpdoc skill under resources/skills, with its references, license, and notice, and exposes…
Description check		The description is specific and related to the changeset. It names the new fast-forward-phpdoc skill and describes its adapted source, MIT attribution, and README, instruction map, and root contract u…
Linked Issues check		Issue #76 is the only directly linked active issue. Its coding requirements are met at the reviewed head, as far as the evidence shows. (1) Payload under resources/skills: resources/skills/fast-forwa…
Out of Scope Changes check		All changed paths relate to issue #76 or to its acceptance criteria. - resources/skills/fast-forward-phpdoc/** (SKILL.md, LICENSE, NOTICE, references/*): the new canonical payload. [#76] - resources/…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within survi…

Full details: Title check

Explanation

The title "feat: add a portable PHPDoc authoring skill" matches the main change. The PR adds the fast-forward-phpdoc skill under resources/skills, with its references, license, and notice, and exposes it in the README, instruction map, and AGENTS.md. The title is short, specific, and uses a conventional commit prefix.

Full details: Description check

Explanation

The description is specific and related to the changeset. It names the new fast-forward-phpdoc skill and describes its adapted source, MIT attribution, and README, instruction map, and root contract updates. It also covers archive tests that verify the shipped skill contents, and it lists validation performed and scope exclusions such as no installer, dependency change, or release.

Full details: Linked Issues check

Explanation

Issue #76 is the only directly linked active issue. Its coding requirements are met at the reviewed head, as far as the evidence shows.

(1) Payload under resources/skills: resources/skills/fast-forward-phpdoc/ contains SKILL.md, LICENSE, NOTICE, and references/{contracts,cleanup,verification}.md. The SKILL.md links to these references with relative paths. [#76]

(2) Provenance: NOTICE attributes the adapted guidance to php-fast-forward/dev-tools at commit 84e154046e07cafa6ac09a9e12434b1ff5dcb5e0 and includes MIT terms. The explicit local/remote published-revision distinction requested in #76 is not visible in the summaries; this is a documentation detail and is not verified in this review. [#76]

(3) Interface guidance: SKILL.md step 3 requires that interface obligations apply to any conforming implementer. It keeps concrete class names and mechanisms on implementations. SKILL.md does not contain a positive-float alias. The reference files were not read directly, so their absence of that alias rests on the change summary. [#76]

(4) Summaries, tags, and inheritance: SKILL.md step 2 requires short single-sentence summaries. Step 4 requires preserving descriptions, units, sentinels, types, and inheritance markers. cleanup.md covers preservation and cleanup limits. [#76]

(5) Discovery and sole-skill instruction: AGENTS.md, README.md, and docs/instruction-map.rst now list both canonical payloads. Code Standards SKILL.md refers semantic PHPDoc work to fast-forward-phpdoc. [#76]

(6) Archive tests: tests/Distribution/ArchiveTest.php copies all regular files under resources/skills and rejects symlinks. Its Git-archive assertions check SHA-256 hashes of SKILL.md, LICENSE, NOTICE, and the three reference files against the source. The phpdoc LICENSE hash is compared with the root LICENSE hash, which covers exact license bytes. The Composer-archive side is covered by the existing equal-export test, which was not re-read in full here. [#76]

(7) Scope exclusions: no DevTools change, no new runtime dependency, and no installer or release change appear in the summaries or file list. [#76]

The Code Standards check route is referenced in the phpdoc skill as an optional command example. This is acceptable because the execution logic stays in the Code Standards skill.

Full details: Out of Scope Changes check

Explanation

All changed paths relate to issue #76 or to its acceptance criteria.

• resources/skills/fast-forward-phpdoc/** (SKILL.md, LICENSE, NOTICE, references/*): the new canonical payload. [#76]
• resources/skills/fast-forward-code-standards/SKILL.md: redirects semantic PHPDoc work to the new skill and changes the payload wording from "sole source" to "canonical payload". This is the sole-skill instruction update that #76 requests. [#76]
• AGENTS.md, README.md, docs/instruction-map.rst: discovery and catalog links for the new skill. [#76]
• tests/Distribution/ArchiveTest.php: archive coverage for the complete skill payloads and the exact license bytes. [#76]
• .changelog/phpdoc-authoring-skill.md: a changelog entry for the new payload. It is a documentation change that supports the feature. [#76]

No unrelated source, dependency, DevTools, or release change was found in the summaries. The reviewed files do not show out-of-scope changes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 2 functions across 1 files. (11 skipped: 11 unsupported.)

Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit drafts contracts, precise and clear,
It keeps useful tags and wording near.
It checks each claim against the source,
Then packs the skill with license, of course.
Hop, archive checks confirm the course!}

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-27T17:47:47.063769Z	4e43857	PR opened
🔒 Security Review	✅ Completed 2026-10-27T17:49:29.663803Z	4e43857	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

Changelog

✅ Contribution check passed.

Head: 4e43857354d27fb2d701af4c2fc0dc3255d7324f

Base: b352cdec815d3eda9c0fd951710fe2051b129836

Contribution: 1 new valid fragment(s). Policy: ordinary.

• phpdoc-authoring-skill.md — added, minor

  Ship a dedicated portable PHPDoc authoring skill with concise interface-contract guidance, semantic-preservation checks and independent distribution references.

[coisa]

@coderabbitai full review

Current HEAD: 4e43857354d27fb2d701af4c2fc0dc3255d7324f.

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

🔇 Additional comments: 1

.changelog/phpdoc-authoring-skill.md-6-6: 1

6-6: Minor · Maintainability & Code Quality · Quick win

⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Resolve the MD041 warning for this changelog fragment.

Line [6] is the first content after the YAML front matter, but it is plain prose. markdownlint-cli2 reports MD041 for this file. If .changelog/*.md is included in the Markdown lint scope, the check can fail. Add a top-level heading only if the changelog parser accepts it; otherwise exclude these front-matter fragments from MD041 and verify the release tooling.

Source: Linters/SAST tools

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 39c6e457-a148-49ca-a446-d1c5f0620365

Commits

Reviewing files that changed from the base of the PR and between b352cde and 4e43857.

Files selected for processing: 12

• .changelog/phpdoc-authoring-skill.md
• AGENTS.md
• README.md
• docs/instruction-map.rst
• resources/skills/fast-forward-code-standards/SKILL.md
• resources/skills/fast-forward-phpdoc/LICENSE
• resources/skills/fast-forward-phpdoc/NOTICE
• resources/skills/fast-forward-phpdoc/SKILL.md
• resources/skills/fast-forward-phpdoc/references/cleanup.md
• resources/skills/fast-forward-phpdoc/references/contracts.md
• resources/skills/fast-forward-phpdoc/references/verification.md
• tests/Distribution/ArchiveTest.php

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

[coisa]

Reviewed the additional, explicitly unverified MD041 suggestion in review 5672213196.

Disposition: no change. This repository has no markdownlint configuration, npm manifest or MD041 workflow/check; the warning is conditional on a lint scope that does not exist here. The fragment follows the existing canonical Changelog format (front matter plus release-note prose), and its exact-head native contribution check passes. Adding a heading or introducing a lint exclusion solely for an absent check would not fix a current repository defect.

All current-head checks and Codex code/security reviews pass on 4e43857354d27fb2d701af4c2fc0dc3255d7324f. No source change or new review request is introduced by this assessment.