From 9d30b4897d209f1eec80a549847a645a0656de77 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 16 Nov 2026 12:13:52 -0300 Subject: [PATCH 1/2] docs: add the `php-forge-debug` skill with AI assistance guidance; add Security and Built with AI sections; update `README.md` badges. --- .agents/skills/php-forge-debug | 1 + .claude/skills/php-forge-debug | 1 + .gitattributes | 15 ++++++ .github/workflows/build.yml | 2 +- .github/workflows/dependency-check.yml | 2 +- .github/workflows/ecs.yml | 2 +- .github/workflows/mutation.yml | 2 +- .github/workflows/quality.yml | 2 +- .github/workflows/scorecard.yml | 23 +++++++++ .github/workflows/security.yml | 2 +- .github/workflows/static.yml | 2 +- .gitignore | 38 +++++++++----- CHANGELOG.md | 2 + README.md | 35 ++++++++++--- composer.json | 5 +- docs/agents.md | 61 +++++++++++++++++++++++ skills/php-forge-debug/SKILL.md | 47 +++++++++++++++++ skills/php-forge-debug/agents/openai.yaml | 4 ++ 18 files changed, 220 insertions(+), 26 deletions(-) create mode 120000 .agents/skills/php-forge-debug create mode 120000 .claude/skills/php-forge-debug create mode 100644 .github/workflows/scorecard.yml create mode 100644 docs/agents.md create mode 100644 skills/php-forge-debug/SKILL.md create mode 100644 skills/php-forge-debug/agents/openai.yaml diff --git a/.agents/skills/php-forge-debug b/.agents/skills/php-forge-debug new file mode 120000 index 0000000..1feab5f --- /dev/null +++ b/.agents/skills/php-forge-debug @@ -0,0 +1 @@ +../../skills/php-forge-debug \ No newline at end of file diff --git a/.claude/skills/php-forge-debug b/.claude/skills/php-forge-debug new file mode 120000 index 0000000..1feab5f --- /dev/null +++ b/.claude/skills/php-forge-debug @@ -0,0 +1 @@ +../../skills/php-forge-debug \ No newline at end of file diff --git a/.gitattributes b/.gitattributes index 2360366..1eabe40 100644 --- a/.gitattributes +++ b/.gitattributes @@ -22,21 +22,36 @@ *.ttf binary # Exclude files from the archive +.env export-ignore +.env.* export-ignore +.env.example -export-ignore +.agents export-ignore +.claude export-ignore +/.codex export-ignore +/.config export-ignore /.editorconfig export-ignore /.gitattributes export-ignore /.github export-ignore /.gitignore export-ignore +/.phpunit.cache export-ignore +/.phpunit.result.cache export-ignore +/.stryker-tmp export-ignore /.styleci.yml export-ignore /codeception.yml export-ignore /composer-require-checker.json export-ignore +/composer.lock export-ignore /docs export-ignore /ecs.php export-ignore /infection.json* export-ignore +/internal export-ignore +/node_modules export-ignore /phpstan*.neon* export-ignore /phpunit.xml.dist export-ignore /rector.php export-ignore +/reports/mutation export-ignore /runtime export-ignore /tests export-ignore +/vendor export-ignore # Avoid merge conflicts in CHANGELOG # https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/ diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f39234e..f62f871 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,7 +17,7 @@ permissions: jobs: phpunit: - uses: php-forge/actions/.github/workflows/phpunit.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/phpunit.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 with: php-version: '["8.3","8.4","8.5"]' secrets: diff --git a/.github/workflows/dependency-check.yml b/.github/workflows/dependency-check.yml index 543f666..75d0bc0 100644 --- a/.github/workflows/dependency-check.yml +++ b/.github/workflows/dependency-check.yml @@ -17,4 +17,4 @@ permissions: jobs: composer-require-checker: - uses: php-forge/actions/.github/workflows/composer-require-checker.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/composer-require-checker.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml index a446051..a2a78fd 100644 --- a/.github/workflows/ecs.yml +++ b/.github/workflows/ecs.yml @@ -17,4 +17,4 @@ permissions: jobs: easy-coding-standard: - uses: php-forge/actions/.github/workflows/ecs.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/ecs.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 diff --git a/.github/workflows/mutation.yml b/.github/workflows/mutation.yml index ee275be..1ca945f 100644 --- a/.github/workflows/mutation.yml +++ b/.github/workflows/mutation.yml @@ -17,7 +17,7 @@ permissions: jobs: mutation: - uses: php-forge/actions/.github/workflows/infection.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/infection.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 with: phpstan: true secrets: diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index 765cdfc..46cb8d5 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -10,7 +10,7 @@ permissions: jobs: quality: - uses: php-forge/actions/.github/workflows/quality.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/quality.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 permissions: contents: read with: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 0000000..0640a44 --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,23 @@ +--- +on: + branch_protection_rule: + push: + branches: + - main + schedule: + - cron: "30 1 * * 6" + +name: scorecard + +permissions: + contents: read + +jobs: + scorecard: + uses: php-forge/actions/.github/workflows/scorecard.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 + permissions: + contents: read # Required to check out the repository. + id-token: write # Required to sign published results with the GitHub OIDC token. + security-events: write # Required to upload SARIF results to code scanning. + with: + publish-results: true diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index b3b632c..29b8119 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -10,7 +10,7 @@ permissions: jobs: security: - uses: php-forge/actions/.github/workflows/security.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/security.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 permissions: contents: read with: diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index 97bd4cf..455657f 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -17,4 +17,4 @@ permissions: jobs: phpstan: - uses: php-forge/actions/.github/workflows/phpstan.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/phpstan.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 diff --git a/.gitignore b/.gitignore index a2389e2..247f01c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,13 @@ -# AI agents (if present) -.codex +.agents .claude +# artifacts (if present) +artifacts + +# Local AI agent, editor, and GitHub CLI config (if present) +.codex +.config/gh + # codecoverage (if present) code_coverage @@ -11,11 +17,7 @@ c3.php # composer composer.lock -# local notes and scaffold drafts (if present) -examples/ -internal/ - -# gitHub copilot config (if present) +# GitHub Copilot config (if present) .github/agents/** .github/copilot-instructions.md .github/copilot/** @@ -31,19 +33,26 @@ nbproject # node_modules (if present) node_modules -package-lock.json -!src/assets/package-lock.json - -# phpactor (if present) -.phpactor.* # phpstorm project (if present) .idea +# phpactor (if present) +.phpactor.* + # phpunit (if present) .phpunit.cache .phpunit.result.cache +# Private maintainer files (if present) +/internal/ + +# Report (if present) +reports + +# Stryker (if present) +.stryker-tmp + # vagrant (if present) .vagrant @@ -60,3 +69,8 @@ Thumbs.db .buildpath .project .settings + +# Local environment files +.env +.env.* +!.env.example diff --git a/CHANGELOG.md b/CHANGELOG.md index a74c436..56cfba6 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.4.2 Under development +- docs: add the `php-forge-debug` skill with AI assistance guidance; add Security and Built with AI sections; update `README.md` badges. + ## 0.4.1 September 26, 2026 - feat(panel-view): add `hero()` for `HeroBlock`, the header naming the subject a panel describes with its status badge and metric row; update `README.md`. diff --git a/README.md b/README.md index c922b11..d9075d3 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,15 @@ PHPUnit + + Coverage + Mutation Testing PHPStan - - Security -

@@ -281,7 +281,20 @@ $html = match (true) { ## Documentation -- [Testing guide](docs/testing.md) +- 🧪 [Testing guide](https://github.com/php-forge/debug/blob/main/docs/testing.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://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill +installation, client setup and verification. + +- 🤖 [`php-forge-debug` skill](https://github.com/php-forge/debug/blob/main/docs/agents.md): portable collectors, + declarative panels built with `PanelView`, and the presentation value objects a host renders. + +See the [repository guides](#documentation), the [skill source](skills/php-forge-debug/SKILL.md), the source PHPDoc and +the [changelog](CHANGELOG.md). ## Package information @@ -292,9 +305,19 @@ $html = match (true) { ## Code quality -[![Codecov](https://img.shields.io/codecov/c/github/php-forge/debug.svg?style=for-the-badge&logo=codecov&logoColor=white&label=Coverage)](https://codecov.io/gh/php-forge/debug) [![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/debug/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/debug/actions/workflows/quality.yml) -[![StyleCI](https://img.shields.io/badge/StyleCI-Passed-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/php-forge/debug?branch=main) +[![StyleCI](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fgithub.styleci.io%2Frepos%2F1363905740%2Fshield%3Fbranch%3Dmain&query=%2F%2F*%5Blocal-name%28%29%3D%27text%27%5D%5B2%5D&label=StyleCI&style=for-the-badge&logo=github&logoColor=white&color=4F5D95)](https://github.styleci.io/repos/1363905740?branch=main) + +## Security + +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/php-forge/debug/badge?style=for-the-badge)](https://scorecard.dev/viewer/?uri=github.com/php-forge/debug) +[![Zizmor](https://img.shields.io/github/actions/workflow/status/php-forge/debug/security.yml?style=for-the-badge&label=Zizmor&logo=github)](https://github.com/php-forge/debug/actions/workflows/security.yml) + +## 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) +[![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) ## Social networks diff --git a/composer.json b/composer.json index ed9b75b..5871eb5 100644 --- a/composer.json +++ b/composer.json @@ -37,6 +37,9 @@ "extra": { "branch-alias": { "dev-main": "0.5.x-dev" + }, + "skills": { + "source": "skills" } }, "config": { @@ -50,7 +53,7 @@ "check-dependencies": "./vendor/bin/composer-require-checker check", "ecs": "./vendor/bin/ecs --fix", "mutation": "./vendor/bin/infection --threads=4 --ignore-msi-with-no-mutations --min-msi=100 --min-covered-msi=100", - "mutation-static": "./vendor/bin/infection --threads=4 --ignore-msi-with-no-mutations --min-msi=100 --min-covered-msi=100 --static-analysis-tool=phpstan --static-analysis-tool-options='--memory-limit=-1'", + "mutation-static": "php -d memory_limit=-1 ./vendor/bin/infection --initial-tests-php-options='-d memory_limit=-1' --test-framework-extra-args='-d memory_limit=-1' --threads=4 --ignore-msi-with-no-mutations --min-msi=100 --min-covered-msi=100 --static-analysis-tool=phpstan --static-analysis-tool-options='--memory-limit=-1'", "rector": "./vendor/bin/rector process", "static": "./vendor/bin/phpstan --memory-limit=-1", "tests": "./vendor/bin/phpunit" diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..fc149d4 --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,61 @@ +# AI assistance + +Use the package-owned [php-forge-debug](../skills/php-forge-debug/SKILL.md) skill for implementing PHP Forge portable diagnostic collectors and declarative panels. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source. + +## Install in an application + +### Automatic Composer installation + +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/debug` 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: + +```bash +composer install +composer skills:show +``` + +Otherwise run `composer skills:update` explicitly and inspect `composer skills:show`. Composer exit zero is not proof +of client activation. + +### Optional npx installation + +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/debug --list +npx skills@1.7.2 add /absolute/path/to/debug --skill php-forge-debug --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-debug/` and supports +`$php-forge-debug` or its skill picker. Claude Code uses `.claude/skills/php-forge-debug/` and `/php-forge-debug`. 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-debug +Implement a minimal collector and matching panel using the installed contracts. Verify null versus empty capture and that startup/shutdown prevent one request from leaking into the next. +``` + +For natural selection, repeat the task without the first line. 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/skills/php-forge-debug/SKILL.md b/skills/php-forge-debug/SKILL.md new file mode 100644 index 0000000..01dff6a --- /dev/null +++ b/skills/php-forge-debug/SKILL.md @@ -0,0 +1,47 @@ +--- +name: php-forge-debug +description: Implement portable diagnostic collectors and declarative panels with the php-forge/debug contracts (CollectorInterface, Panel, PanelView and the Presenter value objects). Use when writing or reviewing a collector or panel that a host such as php-forge/debug-core renders. Not for the debugger engine, host wiring, storage, toolbar rendering or frontend code, which live in the host packages. +license: BSD-3-Clause +--- + +# Use php-forge/debug + +## Resolve the package + +The package requires PHP 8.3 or later. Choose APIs from the installed source: the Composer archive excludes `docs/`, so +in `vendor/php-forge/debug` the PHPDoc in `src/` is the reference for the installed version. A lockfile or branch alias +alone does not prove which files are installed. Installing this skill does not install dependencies or authorize +mutations. + +## Package contracts + +This package supplies contracts and presentation models, not a debugger engine or automatic activation. +`CollectorInterface` coordinates `startup()`, `capture()`, `shutdown()` and a stable `id()`. A null capture means absence; +an empty array remains a capture. The host validates JSON serializability before persistence, and nested values must +survive strict JSON encoding within 500 levels. Providers must omit secrets before returning data. + +Read `Panel`, `PanelView` and the selected `Presenter` value objects before constructing a panel. Keep the collector +and panel identifiers aligned. Test repeated request lifecycles and released state. Debugger integrations are for local +development, not production; installing these contracts does not make an application safe to expose diagnostics. + +Intended behavior that can look like a defect: + +- `Panel::id()`, `name()` and `icon()` are final and throw `InvalidArgumentException` when the `ID`, `TITLE` or `ICON` + constant is empty. Declare the constants; do not override the accessors. The host may override the title and icon. +- `Panel::present()` builds the view from the stored capture only. Do not query live services or the container there. +- `PanelView` is a `final readonly` class created with `PanelView::create()`. Every content method returns a new view, + so discarding the return value loses the block. +- Inline content accepts scalars, `null` and `Presenter\Inline` values. `null`, `true` and `false` render as the text + `null`, `true` and `false`; arrays and objects are rejected with `InvalidArgumentException`. Use `PanelView::value()` + to display structured data. +- Table rows must be lists whose width matches the headers; a keyed or short row is rejected. +- `PanelView::link()` accepts only relative targets and the `http`, `https` and `mailto` schemes, and rejects targets + with control characters or surrounding spaces. This blocks executable targets built from captured values; do not + relax it. + +## Verify the task + +Run the relevant existing package checks and independent assertions for the selected operation. In this package's +checkout, `composer tests`, `composer static` and `composer check-dependencies` only read; `composer ecs` and +`composer rector` rewrite files. Use isolated synthetic inputs for side-effecting behavior. Report the PHP version and +missing dependencies. diff --git a/skills/php-forge-debug/agents/openai.yaml b/skills/php-forge-debug/agents/openai.yaml new file mode 100644 index 0000000..f5b6d58 --- /dev/null +++ b/skills/php-forge-debug/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "PHP Forge Debug" + short_description: "Build portable debug collectors and panels" + default_prompt: "Use $php-forge-debug to implement a collector and its matching declarative panel." From e2b0c4da8ee6bbacfabb0f2442afa772dc28f534 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 16 Nov 2026 12:27:09 -0300 Subject: [PATCH 2/2] docs: update `.gitattributes` and `.gitignore` to refine export-ignore patterns and organize local environment files. --- .gitattributes | 19 ++++++++++++------- .gitignore | 27 ++++++++++++++------------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/.gitattributes b/.gitattributes index 1eabe40..65346ef 100644 --- a/.gitattributes +++ b/.gitattributes @@ -22,21 +22,26 @@ *.ttf binary # Exclude files from the archive -.env export-ignore -.env.* export-ignore -.env.example -export-ignore -.agents export-ignore -.claude export-ignore +.agents export-ignore +.claude export-ignore +.env export-ignore +.env.* export-ignore +.env.example export-ignore /.codex export-ignore /.config export-ignore /.editorconfig export-ignore /.gitattributes export-ignore /.github export-ignore /.gitignore export-ignore +/.nvmrc export-ignore /.phpunit.cache export-ignore -/.phpunit.result.cache export-ignore +/.prettierignore export-ignore +/.prettierrc.json export-ignore /.stryker-tmp export-ignore /.styleci.yml export-ignore +/.vscode export-ignore +/artifacts export-ignore +/code_coverage export-ignore /codeception.yml export-ignore /composer-require-checker.json export-ignore /composer.lock export-ignore @@ -48,7 +53,7 @@ /phpstan*.neon* export-ignore /phpunit.xml.dist export-ignore /rector.php export-ignore -/reports/mutation export-ignore +/reports export-ignore /runtime export-ignore /tests export-ignore /vendor export-ignore diff --git a/.gitignore b/.gitignore index 247f01c..8e270f3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,9 @@ +# agents (if present) .agents -.claude # artifacts (if present) artifacts -# Local AI agent, editor, and GitHub CLI config (if present) -.codex -.config/gh - # codecoverage (if present) code_coverage @@ -25,6 +21,16 @@ composer.lock .github/prompts/** .github/skills/** +# Local AI agent, editor, and GitHub CLI config (if present) +.claude +.codex +.config/gh + +# Local environment files +.env +.env.* +!.env.example + # mac ds_store (if present) .DS_Store @@ -44,13 +50,13 @@ node_modules .phpunit.cache .phpunit.result.cache -# Private maintainer files (if present) +# private maintainer files (if present) /internal/ -# Report (if present) +# report (if present) reports -# Stryker (if present) +# stryker (if present) .stryker-tmp # vagrant (if present) @@ -69,8 +75,3 @@ Thumbs.db .buildpath .project .settings - -# Local environment files -.env -.env.* -!.env.example