Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .agents/skills/php-forge-debug
1 change: 1 addition & 0 deletions .claude/skills/php-forge-debug
20 changes: 20 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,41 @@
*.ttf binary

# Exclude files from the archive
.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
/.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
/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 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/
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dependency-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/ecs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .github/workflows/mutation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/quality.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
23 changes: 23 additions & 0 deletions .github/workflows/scorecard.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion .github/workflows/security.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/static.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
41 changes: 28 additions & 13 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# AI agents (if present)
.codex
.claude
# agents (if present)
.agents

# artifacts (if present)
artifacts

# codecoverage (if present)
code_coverage
Expand All @@ -11,18 +13,24 @@ 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/**
.github/instructions/**
.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

Expand All @@ -31,19 +39,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

Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
35 changes: 29 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@
<a href="https://github.com/php-forge/debug/actions/workflows/build.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/debug/build.yml?style=for-the-badge&label=PHPUnit&logo=github" alt="PHPUnit">
</a>
<a href="https://codecov.io/github/php-forge/debug" target="_blank">
<img src="https://img.shields.io/codecov/c/github/php-forge/debug.svg?style=for-the-badge&logo=codecov&logoColor=white&label=Coverage" alt="Coverage">
</a>
<a href="https://dashboard.stryker-mutator.io/reports/github.com/php-forge/debug/main" target="_blank">
<img src="https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fphp-forge%2Fdebug%2Fmain" alt="Mutation Testing">
</a>
<a href="https://github.com/php-forge/debug/actions/workflows/static.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/debug/static.yml?style=for-the-badge&label=PHPStan&logo=github" alt="PHPStan">
</a>
<a href="https://github.com/php-forge/debug/actions/workflows/security.yml" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/php-forge/debug/security.yml?style=for-the-badge&label=Security&logo=github" alt="Security">
</a>
</p>

<p align="center">
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down
5 changes: 4 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@
"extra": {
"branch-alias": {
"dev-main": "0.5.x-dev"
},
"skills": {
"source": "skills"
}
},
"config": {
Expand All @@ -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"
Expand Down
61 changes: 61 additions & 0 deletions docs/agents.md
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading