Repository navigation
docs(skills): add the package skill and AI guide; add README.md Security and Built with AI sections and Scorecard badge.
#96
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../../skills/php-forge-debug-core | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../../skills/php-forge-debug-core |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # AI assistance | ||
|
|
||
| Use the package-owned [php-forge-debug-core](../skills/php-forge-debug-core/SKILL.md) skill for integrating PHP Forge debugger snapshots, storage and adapter boundaries. 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-core` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by | ||
| copying an example. | ||
|
|
||
| ```bash | ||
| composer install | ||
| composer skills:show | ||
| ``` | ||
|
|
||
| With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise run | ||
| `composer skills:update` 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-core --list | ||
| npx skills@1.7.2 add /absolute/path/to/debug-core --skill php-forge-debug-core --agent claude-code codex opencode | ||
| ``` | ||
|
|
||
| Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there. | ||
| After upgrading the package, repeat the `npx skills@1.7.2 add` installation command above to refresh copied and | ||
| symlinked installations. Symlinks point to the installer's canonical copy, which does not update with the package. | ||
| 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-core/` and supports | ||
| `$php-forge-debug-core` or its skill picker. Claude Code uses `.claude/skills/php-forge-debug-core/` and `/php-forge-debug-core`. 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-core | ||
| Outline an adapter using the installed snapshot and routing contracts. Verify missing/corrupt snapshot handling and request isolation without changing production routes or exposing diagnostics. | ||
| ``` | ||
|
|
||
| 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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| --- | ||
| name: php-forge-debug-core | ||
| description: Use when building or maintaining a debugger adapter on php-forge/debug-core, covering snapshot storage, capture redaction, panel URL generation, toolbar injection and the shared frontend sources. Not for installing the debugger in an application, which goes through yii2-extensions/debug or yii3/debug, nor for framework routes, access policy or asset publishing. | ||
| license: BSD-3-Clause | ||
| --- | ||
|
|
||
| # Use php-forge/debug-core | ||
|
|
||
| ## Resolve the package | ||
|
|
||
| Inspect the installed package path, actual source and Composer metadata before choosing APIs. The current PHP constraint | ||
| is `>=8.3`. 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 | ||
|
|
||
| Applications normally install a framework adapter; this package owns common storage, snapshots, renderers and | ||
| frontend resources. Adapters own routing, access policy, assets and the decision to inject the toolbar. Collectors | ||
| implement `PHPForge\Debug\CollectorInterface` from `php-forge/debug`. Implement | ||
| `PHPForge\Debug\Routing\DebugUrlGeneratorInterface` rather than importing a framework URL manager into the core. | ||
|
|
||
| These behaviors are intended; do not "fix" them as incidental cleanups: | ||
|
|
||
| - `Storage\SnapshotStore::readSnapshot()` returns `null` for a missing, corrupt or invalid-tag snapshot and hides the | ||
| cause. Use `readSnapshotResult()` when the diagnostic matters: a missing snapshot yields no snapshot and no error, | ||
| while a corrupt file or an invalid tag yields a `StorageException` in `error`. | ||
| - `Panel\Log\LogContext::normalize()` applies the host `Capture\CapturePolicy` to the PSR-3 context only. The core | ||
| does not redact the log message text; do not add redaction there. | ||
| - `Toolbar\ToolbarInjector::inject()` inserts the markup before the last case-insensitive `</body>` found by string | ||
| search, not by parsing HTML, and appends it when there is none. | ||
|
|
||
| Keep the debugger limited to local/development use. Test corrupt or missing snapshots, request isolation and response | ||
| injection separately. PHP storage tests do not prove browser toolbar behavior; frontend source is under | ||
| `resources/src`, with generated output under `resources/assets/dist`. | ||
|
|
||
| ## 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| interface: | ||
| display_name: "PHP Forge Debug Core" | ||
| short_description: "Build debugger adapters on the shared debug core" | ||
| default_prompt: "Use $php-forge-debug-core to build or review a debugger adapter on the shared snapshot, storage and toolbar contracts." |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.