diff --git a/.agents/skills/php-forge-coding-standard b/.agents/skills/php-forge-coding-standard
new file mode 120000
index 0000000..e30c4d0
--- /dev/null
+++ b/.agents/skills/php-forge-coding-standard
@@ -0,0 +1 @@
+../../skills/php-forge-coding-standard
\ No newline at end of file
diff --git a/.claude/skills/php-forge-coding-standard b/.claude/skills/php-forge-coding-standard
new file mode 120000
index 0000000..e30c4d0
--- /dev/null
+++ b/.claude/skills/php-forge-coding-standard
@@ -0,0 +1 @@
+../../skills/php-forge-coding-standard
\ No newline at end of file
diff --git a/.gitattributes b/.gitattributes
index 2360366..8f4bdd7 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -41,3 +41,25 @@
# Avoid merge conflicts in CHANGELOG
# https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/
/CHANGELOG.md merge=union
+
+/.agents export-ignore
+
+/.claude export-ignore
+
+/internal export-ignore
+/vendor export-ignore
+/node_modules export-ignore
+/.env export-ignore
+/.env.* export-ignore
+
+/.phpunit.cache export-ignore
+
+/.phpunit.result.cache export-ignore
+
+/.stryker-tmp export-ignore
+
+/.codex export-ignore
+
+/.config export-ignore
+
+/reports/mutation export-ignore
diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml
index 86889c3..a3ac3a7 100644
--- a/.github/workflows/ecs.yml
+++ b/.github/workflows/ecs.yml
@@ -17,6 +17,6 @@ permissions:
jobs:
easy-coding-standard:
- uses: yii2-framework/actions/.github/workflows/ecs.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/ecs.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
with:
command-options: check src --config src/ecs-83.php --ansi
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index ea2c87f..165fd2f 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
quality:
- uses: yii2-framework/actions/.github/workflows/quality.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/quality.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
permissions:
contents: read
with:
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index 6a771ba..b3b632c 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
security:
- uses: yii2-framework/actions/.github/workflows/security.yml@a28eb7d4ab03abd53ccd7c79014b3b27d09932ff # v2.0.1
+ uses: php-forge/actions/.github/workflows/security.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
permissions:
contents: read
with:
diff --git a/.gitignore b/.gitignore
index f5ae66e..e05e634 100644
--- a/.gitignore
+++ b/.gitignore
@@ -114,3 +114,16 @@ Thumbs.db
.buildpath
.project
.settings
+
+# Package skill discovery; keep other local client state private.
+!/.agents/
+/.agents/*
+!/.agents/skills/
+/.agents/skills/*
+!/.agents/skills/php-forge-coding-standard
+!/.claude/
+/.claude/*
+!/.claude/skills/
+/.claude/skills/*
+!/.claude/skills/php-forge-coding-standard
+/internal/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 105aa3e..ccb662a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## 0.3.5 Under development
+- chore: standardize package guidance, skill discovery, configuration checks and security reporting.
+
## 0.3.4 September 07, 2026
- fix: support ECS `13.3.2+` with the native PER-CS set and explicit PHP `8.1-8.4` migration rules instead of the removed `withPhpCsFixerSets()` arguments.
diff --git a/README.md b/README.md
index f97717e..3441429 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
-
+
Coding standard
@@ -40,21 +40,21 @@ Then run `composer update`.
This package ships shared ECS and Rector configurations under `vendor/php-forge/coding-standard/src/`:
-| File | Purpose |
-| ------------------- | ------------------------------------------------------- |
-| `src/ecs.php` | Shared ECS base rules, no PHP migration set |
-| `src/ecs-81.php` | Base + `@PHP81Migration` PHP-CS-Fixer set |
-| `src/ecs-82.php` | Base + `@PHP82Migration` |
-| `src/ecs-83.php` | Base + `@PHP83Migration` |
-| `src/ecs-84.php` | Base + `@PHP84Migration` |
-| `src/rector.php` | Shared Rector base rules, no PHP level set |
-| `src/rector-81.php` | Base + `SetList::PHP_81` + `LevelSetList::UP_TO_PHP_81` |
-| `src/rector-82.php` | Base + `SetList::PHP_82` + `LevelSetList::UP_TO_PHP_82` |
-| `src/rector-83.php` | Base + `SetList::PHP_83` + `LevelSetList::UP_TO_PHP_83` |
-| `src/rector-84.php` | Base + `SetList::PHP_84` + `LevelSetList::UP_TO_PHP_84` |
-
-Pick the version that matches the **minimum** PHP your project supports; Rector upgrades code up to that level and
-PHP-CS-Fixer enforces matching syntax. The plain `ecs.php` / `rector.php` apply no PHP-version migrations.
+| File | Purpose |
+| ----------------- | -------------------------------------------------- |
+| src/ecs.php | Shared ECS base rules, no PHP migration set |
+| src/ecs-81.php | Base + `@PHP81Migration` |
+| src/ecs-82.php | Base + `@PHP82Migration` |
+| src/ecs-83.php | Base + `@PHP82Migration` (no additional 8.3 rules) |
+| src/ecs-84.php | Base + `@PHP84Migration` |
+| src/rector.php | Shared Rector base rules, no PHP level set |
+| src/rector-81.php | Base + `LevelSetList::UP_TO_PHP_81` |
+| src/rector-82.php | Base + `LevelSetList::UP_TO_PHP_82` |
+| src/rector-83.php | Base + `LevelSetList::UP_TO_PHP_83` |
+| src/rector-84.php | Base + `LevelSetList::UP_TO_PHP_84` |
+
+Pick the version that matches the **minimum** PHP your project supports; Rector applies migrations up to that level and
+ECS applies the corresponding non-risky migration rules. These tools do not prove minimum-version compatibility. The plain `ecs.php` / `rector.php` apply no PHP-version migrations.
### ECS wrapper (ecs.php)
@@ -187,6 +187,16 @@ Follow the same convention used across PHP Forge repositories:
}
```
+## Testing
+
+Run `composer tests` to check that each versioned ECS and Rector configuration detects a sample transformation
+without modifying the input. Development dependencies require PHP 8.3 or later; the package runtime supports PHP 8.1.
+
+## AI assistance
+
+Use the [php-forge-coding-standard skill](skills/php-forge-coding-standard/SKILL.md) and the [AI assistance guide](docs/agents.md) for
+package-specific setup, invocation examples and verification.
+
## Package information
[](https://www.php.net/releases/8.1/en.php)
@@ -196,8 +206,8 @@ Follow the same convention used across PHP Forge repositories:
## Project status
[](https://github.com/php-forge/coding-standard/actions/workflows/quality.yml)
-[](https://github.com/php-forge/coding-standard/actions/workflows/security.yml)
-[](https://github.styleci.io/repos/1141292628?branch=main)
+[](https://github.com/php-forge/coding-standard/actions/workflows/security.yml)
+[](https://github.styleci.io/repos/1141292628?branch=main)
## Our social networks
diff --git a/composer.json b/composer.json
index 3830292..33d4ef4 100644
--- a/composer.json
+++ b/composer.json
@@ -41,6 +41,9 @@
"allowed-packages": [
"php-forge/baseline"
]
+ },
+ "skills": {
+ "source": "skills"
}
},
"config": {
@@ -50,7 +53,6 @@
}
},
"scripts": {
- "tests": "php tests/ecs.php",
"ecs": "./vendor/bin/ecs check src --config src/ecs-83.php --fix",
"rector": "./vendor/bin/rector process src --config src/rector-83.php"
}
diff --git a/docs/agents.md b/docs/agents.md
new file mode 100644
index 0000000..e778020
--- /dev/null
+++ b/docs/agents.md
@@ -0,0 +1,55 @@
+# AI assistance
+
+Use the package-owned [php-forge-coding-standard](../skills/php-forge-coding-standard/SKILL.md) skill for selecting PHP Forge ECS and Rector configurations for a supported PHP target. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source.
+
+## Install in an application
+
+Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does
+not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust
+`php-forge/coding-standard` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by
+copying an example. With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise use
+`composer skills:update` and inspect `composer skills:show`. Composer exit zero is not proof of client activation.
+
+An optional pinned installer can use a local checkout or an installed package that contains the bundle:
+
+```bash
+npx skills@1.7.2 add /absolute/path/to/coding-standard --list
+npx skills@1.7.2 add /absolute/path/to/coding-standard --skill php-forge-coding-standard --agent claude-code codex opencode
+```
+
+Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there.
+Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation.
+
+## Discover and invoke
+
+Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-coding-standard/` and supports
+`$php-forge-coding-standard` or its skill picker. Claude Code uses `.claude/skills/php-forge-coding-standard/` and `/php-forge-coding-standard`. For OpenCode, verify the
+installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another.
+
+## Example prompts
+
+Explicit Codex invocation:
+
+```text
+$php-forge-coding-standard
+Prepare ECS and Rector wrappers for a PHP 8.1 consumer using this package. Preserve its src/tests paths and demonstrate dry-run commands; do not upgrade syntax to the host PHP version.
+```
+
+Natural selection:
+
+```text
+My project supports PHP 8.1 but runs tools on PHP 8.5. Configure its ECS and Rector wrappers using php-forge/coding-standard, preserve src and tests paths, and show non-mutating checks.
+```
+
+Record whether the client loads this skill rather than a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the
+repository or loading package skills.
+
+## Verify the result
+
+Capture the native load/tool evidence and selected source path, then execute the generated task checks against the
+installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect
+generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks
+and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying
+its body in a prompt does not prove native activation or functional execution.
+
+[Back to README](../README.md)
diff --git a/docs/svgs/features-mobile.svg b/docs/svgs/features-mobile.svg
index 26db843..6a1941c 100644
--- a/docs/svgs/features-mobile.svg
+++ b/docs/svgs/features-mobile.svg
@@ -24,15 +24,15 @@
- Metadata & Linter Standards
- .editorconfig, .gitignore, .gitattributes, Prettier, stylelint baselines
- Super-Linter configs: actionlint, codespell, gitleaks, markdownlint
+ Independent Configurations
+ Shared ECS and Rector rules have no project-specific paths
+ Choose the target matching the minimum supported PHP version
Scaffold Provider
- yii2-extensions/scaffold integration distributes files on install
- Modes replace, append and preserve protect local edits
+ Optional scaffold integration distributes wrapper templates
+ Preserve mode keeps consumer wrapper edits
diff --git a/docs/svgs/features.svg b/docs/svgs/features.svg
index 2a0aa70..b0cada8 100644
--- a/docs/svgs/features.svg
+++ b/docs/svgs/features.svg
@@ -25,16 +25,16 @@
- Metadata & Linter Standards
- .editorconfig, .gitignore, .gitattributes, Prettier and stylelint baselines
- Super-Linter configs: actionlint, codespell, gitleaks, markdownlint
+ Independent Configurations
+ Shared ECS and Rector rules have no project-specific paths
+ Choose the target matching the minimum supported PHP version
Scaffold Provider
- yii2-extensions/scaffold integration distributes files on install
- Modes replace, append and preserve protect local edits
+ Optional scaffold integration distributes wrapper templates
+ Preserve mode keeps consumer wrapper edits
diff --git a/ecs.php b/ecs.php
new file mode 100644
index 0000000..9ff5e15
--- /dev/null
+++ b/ecs.php
@@ -0,0 +1,35 @@
+withPaths([
+ __DIR__ . '/src',
+ __DIR__ . '/tests',
+ ])
+ // include *.php files in the root directory
+ ->withRootFiles()
+
+ // add a single rule
+ ->withRules([
+ NoUnusedImportsFixer::class,
+ ])
+
+ // add sets - group of rules, from easiest to more complex ones
+ // uncomment one, apply one, commit, PR, merge and repeat
+ //->withPreparedSets(
+ // spaces: true,
+ // namespaces: true,
+ // docblocks: true,
+ // arrays: true,
+ // comments: true,
+ //)
+
+ // ...but first: take it step by step
+ ->withSpacesLevel(0)
+ ->withArrayLevel(0)
+ ->withControlStructuresLevel(0)
+ ->withDocblockLevel(0);
diff --git a/skills/php-forge-coding-standard/SKILL.md b/skills/php-forge-coding-standard/SKILL.md
new file mode 100644
index 0000000..197975e
--- /dev/null
+++ b/skills/php-forge-coding-standard/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: php-forge-coding-standard
+description: Use when selecting PHP Forge ECS and Rector configurations for a supported PHP target.
+license: BSD-3-Clause
+---
+
+# Use php-forge/coding-standard
+
+## Resolve the package
+
+Inspect the installed package path, actual source and Composer metadata before choosing APIs. The current PHP constraint
+is `>=8.1`. A lockfile or branch alias alone does not prove the installed files match it. Use
+local guides at that revision; if a guide is excluded from the archive, consult the matching repository revision, not
+unverified current documentation. Installing this skill does not install dependencies or authorize mutations.
+
+## Package contracts
+
+Select `src/ecs-81.php` through `ecs-84.php` and the corresponding Rector configuration from the consumer's minimum
+supported PHP version, not the interpreter currently running. For other minimum versions, inspect the available sets and explain that no matching wrapper is provided. Plain
+`ecs.php` and `rector.php` do not select a migration level. Inspect actual configuration files: an ECS entrypoint returns a builder; the Rector configuration returns a
+closure that receives `RectorConfig`. Do not assume interchangeable wrapper shapes.
+
+Preserve consumer paths and justified skips. Run non-mutating checks first; ECS/Rector fix commands change files.
+Do not raise the language target merely to clear a finding. Verify installed ECS/Rector compatibility and the selected
+configuration with the consumer's tests.
+
+## Verify the task
+
+Run the relevant existing package checks and independent assertions for the selected operation. Read `composer.json`
+scripts before executing them: fixers, installers and cleanup commands can mutate files. Use isolated synthetic inputs
+for side-effecting behavior. Report the PHP version and missing dependencies. Distinguish native skill discovery,
+activation, generated snippets and executed functional results; none substitutes for the others.
diff --git a/src/ecs.php b/src/ecs.php
index 62fdd6a..ca7b9a8 100644
--- a/src/ecs.php
+++ b/src/ecs.php
@@ -9,7 +9,7 @@
use PhpCsFixer\Fixer\PhpUnit\PhpUnitTestCaseStaticMethodCallsFixer;
use PhpCsFixer\Fixer\Strict\{DeclareStrictTypesFixer, StrictComparisonFixer, StrictParamFixer};
use PhpCsFixer\Fixer\StringNotation\SingleQuoteFixer;
-use PhpCsFixer\Fixer\Whitespace\HeredocIndentationFixer;
+use PhpCsFixer\Fixer\Whitespace\{HeredocIndentationFixer, NoExtraBlankLinesFixer};
use Symplify\EasyCodingStandard\Config\ECSConfig;
return ECSConfig::configure()
@@ -86,5 +86,8 @@
],
)
->withSkip(
- [HeredocIndentationFixer::class],
+ [
+ HeredocIndentationFixer::class,
+ NoExtraBlankLinesFixer::class,
+ ],
);
diff --git a/src/rector.php b/src/rector.php
index 99aa40a..e6dc808 100644
--- a/src/rector.php
+++ b/src/rector.php
@@ -14,7 +14,7 @@
* import either this file (no version target) or one of the version-pinned wrappers (`rector-81.php`, `rector-82.php`,
* `rector-83.php`, `rector-84.php`) and set their own paths.
*
- * The version-pinned wrappers add the matching `SetList::PHP_XX` and `LevelSetList::UP_TO_PHP_XX` on top of this base.
+ * The version-pinned wrappers add the matching `LevelSetList::UP_TO_PHP_XX` on top of this base.
*/
return static function (RectorConfig $rectorConfig): void {
$rectorConfig->parallel();