From d364d1a42187b2428894b41536f40c6cb4ee8ab7 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Tue, 27 Oct 2026 06:31:06 -0300 Subject: [PATCH 1/2] feat: add the AI skill, discovery configuration, and installation guidance. --- .agents/skills/php-forge-diff | 1 + .claude/skills/php-forge-diff | 1 + AGENTS.md | 8 +++++++ README.md | 16 ++++++++++++- composer.json | 3 +++ docs/agents.md | 42 +++++++++++++++++++++++++++++++++ llms.txt | 11 +++++++++ skills/php-forge-diff/SKILL.md | 43 ++++++++++++++++++++++++++++++++++ 8 files changed, 124 insertions(+), 1 deletion(-) create mode 120000 .agents/skills/php-forge-diff create mode 120000 .claude/skills/php-forge-diff create mode 100644 AGENTS.md create mode 100644 docs/agents.md create mode 100644 llms.txt create mode 100644 skills/php-forge-diff/SKILL.md diff --git a/.agents/skills/php-forge-diff b/.agents/skills/php-forge-diff new file mode 120000 index 0000000..a7023ec --- /dev/null +++ b/.agents/skills/php-forge-diff @@ -0,0 +1 @@ +../../skills/php-forge-diff \ No newline at end of file diff --git a/.claude/skills/php-forge-diff b/.claude/skills/php-forge-diff new file mode 120000 index 0000000..a7023ec --- /dev/null +++ b/.claude/skills/php-forge-diff @@ -0,0 +1 @@ +../../skills/php-forge-diff \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..96b275e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,8 @@ +# Agent guidance + +For php-forge/diff integration use the package-owned [skill](skills/php-forge-diff/SKILL.md), the +[usage examples](docs/examples.md), [algorithms guide](docs/algorithms.md), and source at the installed revision. The +[AI assistance guide](docs/agents.md) explains discovery and installation. The package requires PHP 8.3 or later. + +For repository changes inspect the Git status and diffs, preserve existing staged and unstaged work, and follow +[testing](docs/testing.md). Do not confuse installation or reading a skill with native activation or a passing task. diff --git a/README.md b/README.md index f0598e6..8fd9f5b 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,20 @@ its trade-offs. - ๐Ÿงฎ [Algorithms guide](docs/algorithms.md) - ๐Ÿ’ก [Usage examples](docs/examples.md) - ๐Ÿงช [Testing guide](docs/testing.md) +- ๐Ÿค– [AI assistance](docs/agents.md) + +## AI assistance + +AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version +of a page by appending `index.md` to its URL. The +[AI agents guide](https://yii2-framework.github.io/docs/project/ai-agents/) covers skill installation, client setup and +verification. + +- ๐Ÿค– [`php-forge-diff` skill](docs/agents.md): Line edit scripts and unified diffs. + +If hosted documentation does not match the installed revision or is unavailable, use the +[repository guides](#documentation), the [skill source](skills/php-forge-diff/SKILL.md), the source PHPDoc and the +[changelog](CHANGELOG.md). ## Package information @@ -131,7 +145,7 @@ its trade-offs. ## Built with AI [![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-D97757.svg?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code) -[![Reviewed by Codex](https://img.shields.io/badge/Reviewed%20by-Codex-10A37F.svg?style=for-the-badge&logo=openaigym&logoColor=white)](https://openai.com/codex) +[![Built with Codex](https://img.shields.io/badge/Built%20with-Codex-10A37F.svg?style=for-the-badge&logo=openaigym&logoColor=white)](https://openai.com/codex) [![Reviewed by CodeRabbit](https://img.shields.io/badge/Reviewed%20by-CodeRabbit-FF570A.svg?style=for-the-badge&logo=coderabbit&logoColor=white)](https://www.coderabbit.ai) ## Our social networks diff --git a/composer.json b/composer.json index febe755..21f9076 100644 --- a/composer.json +++ b/composer.json @@ -51,6 +51,9 @@ } }, "extra": { + "skills": { + "source": "skills" + }, "branch-alias": { "dev-main": "0.1.x-dev" } diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..550e88f --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,42 @@ +# AI assistance + +Use the package-owned [`php-forge-diff` skill](../skills/php-forge-diff/SKILL.md) when integrating or troubleshooting +line edit scripts or unified rendering. The canonical source is `skills/php-forge-diff/`; `.agents/skills/` and +`.claude/skills/` link to it for local discovery. + +## Install in an application + +### Automatic Composer installation + +Complete the +[one-time application setup](https://yii2-framework.github.io/docs/project/ai-agents/#composer-installation) to enable +`llm/skills` and set `auto-sync` to `true` in `skills.json`. Explicitly trust `php-forge/diff` in +`dependencies.composer.trusted`. The installed package must include the skill bundle declared by `extra.skills.source`. + +```bash +composer install +composer skills:show +``` + +With `auto-sync` enabled, later dependency installs and updates synchronize the skill. If disabled, run +`composer skills:update` after dependency installation or updates. + +### Optional npx installation + +From the application root, list the source before installing: + +```bash +npx skills@1.7.2 add php-forge/diff --list +npx skills@1.7.2 add php-forge/diff --skill php-forge-diff +``` + +Choose the intended client. Installation, discovery, native loading and successful task behavior are distinct outcomes; +verify each independently. Installing a skill does not install Composer dependencies. Prefer the installed source and +guides at the same revision; report when matching guides are unavailable. + +## Next steps + +- ๐Ÿ’ก [Usage examples](examples.md) +- ๐Ÿงช [Testing guide](testing.md) + +[Back to documentation](../README.md#documentation) diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..0a0b609 --- /dev/null +++ b/llms.txt @@ -0,0 +1,11 @@ +# php-forge/diff + +> Git-compatible line diff for PHP, with a unified diff renderer. + +- [README](https://github.com/php-forge/diff/blob/main/README.md): installation, quick start and package overview. +- [Installation](https://github.com/php-forge/diff/blob/main/docs/installation.md): requirements and setup. +- [Algorithms](https://github.com/php-forge/diff/blob/main/docs/algorithms.md): algorithm and compatibility limits. +- [Usage examples](https://github.com/php-forge/diff/blob/main/docs/examples.md): line scripts and unified rendering. +- [Testing](https://github.com/php-forge/diff/blob/main/docs/testing.md): local verification commands. +- [AI assistance](https://github.com/php-forge/diff/blob/main/docs/agents.md): skill installation and discovery. +- [Skill](https://github.com/php-forge/diff/blob/main/skills/php-forge-diff/SKILL.md): integration guidance. diff --git a/skills/php-forge-diff/SKILL.md b/skills/php-forge-diff/SKILL.md new file mode 100644 index 0000000..8bd4b03 --- /dev/null +++ b/skills/php-forge-diff/SKILL.md @@ -0,0 +1,43 @@ +--- +name: php-forge-diff +description: Integrate or troubleshoot php-forge/diff line edit scripts and unified diff rendering in PHP applications. Use for LineDiffer, DifferInterface, or UnifiedDiffRenderer; exclude applying patches and unrelated Git operations. +license: BSD-3-Clause +metadata: + source: https://github.com/php-forge/diff +--- + +# Use php-forge/diff + +Inspect the installed revision and its `composer.json`, source and guides before choosing an API. For a dependency, +resolve Composer's installed path and reference; a path checkout can contain uncommitted changes. Compare the lock file, +which may describe a different installation. Use documentation matching the installed files and report a gap if it +cannot be found. PHP 8.3 or later is required by the current package. + +## Choose the result + +Use `PHPForge\Diff\LineDiffer::diff($old, $new)` for an ordered list of `DiffLine` objects with `DiffOp::Context`, +`Remove`, or `Add`. It splits both strings literally on `"\n"`: an empty string is one empty line and a trailing newline +produces an empty final line. Remove `Add` entries to reconstruct the old input, or `Remove` entries for the new input, +joining the remaining `line` values with `"\n"`. It does not normalize line endings. + +Use `UnifiedDiffRenderer::render($old, $new, $fromLabel, $toLabel, $context = 3)` for unified text. It normalizes CRLF +and CR to LF, returns an empty string for normalized equal texts and otherwise returns a patch without a trailing +newline or Git's `diff --git` and `index` headers. Negative context is treated as zero. Missing final newlines are +represented by `\ No newline at end of file`. Labels are supplied by the caller; this renderer does not read files, +apply patches, or escape labels for untrusted presentation. + +A custom `DifferInterface` can be injected into the renderer. Its script must reconstruct both inputs in order; +otherwise the renderer can throw `LogicException`. Test a non-empty change as well as empty inputs because the renderer +handles empty sides separately. Do not swallow this exception as an empty diff. + +The default differ follows Git's default xdiff pipeline and indent heuristic, but lacks Git's cost limit. Its edit +script is not guaranteed shortest or identical to Git on expensive inputs. Do not promise binary diff support or exact +byte preservation after renderer line-ending normalization. + +## Verify + +Use the application's existing tests and the package's `docs/examples.md`, `docs/algorithms.md` and `docs/testing.md` at +the matching revision. Assert both reconstructed sides, unchanged inputs, empty sides, trailing-newline differences, +line-ending normalization, requested context and custom-differ failure as relevant. If comparing with Git, disable user +and system Git configuration and document the chosen options. Record installation, client discovery, native skill +loading, actual task behavior and test results separately; reading this file alone proves no activation. From abe7842507be32d22b6fedc14ae46d537884b105 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Tue, 27 Oct 2026 06:52:28 -0300 Subject: [PATCH 2/2] Apply fixed Coderrabbitai review. --- docs/agents.md | 2 +- skills/php-forge-diff/SKILL.md | 30 ++++++++++++++++-------------- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/agents.md b/docs/agents.md index 550e88f..07a4cfb 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -8,7 +8,7 @@ line edit scripts or unified rendering. The canonical source is `skills/php-forg ### Automatic Composer installation -Complete the +Require `php-forge/diff` as described in the [installation guide](installation.md). Then complete the [one-time application setup](https://yii2-framework.github.io/docs/project/ai-agents/#composer-installation) to enable `llm/skills` and set `auto-sync` to `true` in `skills.json`. Explicitly trust `php-forge/diff` in `dependencies.composer.trusted`. The installed package must include the skill bundle declared by `extra.skills.source`. diff --git a/skills/php-forge-diff/SKILL.md b/skills/php-forge-diff/SKILL.md index 8bd4b03..00e790d 100644 --- a/skills/php-forge-diff/SKILL.md +++ b/skills/php-forge-diff/SKILL.md @@ -15,20 +15,22 @@ cannot be found. PHP 8.3 or later is required by the current package. ## Choose the result -Use `PHPForge\Diff\LineDiffer::diff($old, $new)` for an ordered list of `DiffLine` objects with `DiffOp::Context`, -`Remove`, or `Add`. It splits both strings literally on `"\n"`: an empty string is one empty line and a trailing newline -produces an empty final line. Remove `Add` entries to reconstruct the old input, or `Remove` entries for the new input, -joining the remaining `line` values with `"\n"`. It does not normalize line endings. - -Use `UnifiedDiffRenderer::render($old, $new, $fromLabel, $toLabel, $context = 3)` for unified text. It normalizes CRLF -and CR to LF, returns an empty string for normalized equal texts and otherwise returns a patch without a trailing -newline or Git's `diff --git` and `index` headers. Negative context is treated as zero. Missing final newlines are -represented by `\ No newline at end of file`. Labels are supplied by the caller; this renderer does not read files, -apply patches, or escape labels for untrusted presentation. - -A custom `DifferInterface` can be injected into the renderer. Its script must reconstruct both inputs in order; -otherwise the renderer can throw `LogicException`. Test a non-empty change as well as empty inputs because the renderer -handles empty sides separately. Do not swallow this exception as an empty diff. +Use `(new PHPForge\Diff\LineDiffer())->diff($old, $new)` for an ordered list of `DiffLine` objects with +`DiffOp::Context`, `Remove`, or `Add`. It splits both strings literally on `"\n"`: an empty string is one empty line and +a trailing newline produces an empty final line. Remove `Add` entries to reconstruct the old input, or `Remove` entries +for the new input, joining the remaining `line` values with `"\n"`. It does not normalize line endings. + +Use `(new PHPForge\Diff\UnifiedDiffRenderer())->render($old, $new, $fromLabel, $toLabel, $context)` for unified text; +`$context` is optional and defaults to `3`. It normalizes CRLF and CR to LF, returns an empty string for normalized +equal texts and otherwise returns a patch without a trailing newline or Git's `diff --git` and `index` headers. Negative +context is treated as zero. Missing final newlines are represented by `\ No newline at end of file`. Labels are supplied +by the caller; this renderer does not read files, apply patches, or escape labels for untrusted presentation. + +A custom `DifferInterface` can be injected into the renderer. Its script must reconstruct both inputs in order. The +renderer takes the rendered lines from the texts by operation position and does not validate `DiffLine::line`: a script +whose operations do not consume both inputs exactly throws `LogicException`, while a balanced script with wrong +operations renders an incorrect diff without any error. Test a non-empty change as well as empty inputs because the +renderer handles empty sides separately. Do not swallow `LogicException` as an empty diff. The default differ follows Git's default xdiff pipeline and indent heuristic, but lacks Git's cost limit. Its edit script is not guaranteed shortest or identical to Git on expensive inputs. Do not promise binary diff support or exact