From 9d30b4897d209f1eec80a549847a645a0656de77 Mon Sep 17 00:00:00 2001
From: Wilmer Arambula
+
+
+
-
-
-
@@ -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
-[](https://codecov.io/gh/php-forge/debug)
[](https://github.com/php-forge/debug/actions/workflows/quality.yml)
-[](https://github.styleci.io/repos/php-forge/debug?branch=main)
+[](https://github.styleci.io/repos/1363905740?branch=main)
+
+## Security
+
+[](https://scorecard.dev/viewer/?uri=github.com/php-forge/debug)
+[](https://github.com/php-forge/debug/actions/workflows/security.yml)
+
+## Built with AI
+
+[](https://claude.com/claude-code)
+[](https://openai.com/codex)
+[](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