From 680b584bd94c3f5472dbe6a04256b77420d3208f Mon Sep 17 00:00:00 2001 From: brianhdk Date: Sun, 15 Feb 2026 20:54:16 +0100 Subject: [PATCH 1/2] feat: upgrade and create agents.md --- .github/workflows/ci.yml | 8 +-- .github/workflows/publish.yml | 12 ++--- AGENTS.md | 97 +++++++++++++++++++++++++++++++++++ DEVELOPMENT.md | 2 +- Generator/Generator.csproj | 2 +- 5 files changed, 109 insertions(+), 12 deletions(-) create mode 100644 AGENTS.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 42435cd2..29112e9b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,14 +8,14 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v6 - uses: php-actions/composer@v6 - - name: Setup .NET 8 preview - uses: actions/setup-dotnet@v1 + - name: Setup .NET 10 + uses: actions/setup-dotnet@v5 with: - dotnet-version: '8.0.x' + dotnet-version: '10.0.x' - name: Generate PHP classes run: ./generate.sh diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 8177520a..3135f5d9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -9,20 +9,20 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v6 - - uses: php-actions/composer@v5 + - uses: php-actions/composer@v6 - - name: Setup .NET 8 preview - uses: actions/setup-dotnet@v1 + - name: Setup .NET 10 + uses: actions/setup-dotnet@v5 with: - dotnet-version: '8.0.x' + dotnet-version: '10.0.x' - name: Generate PHP classes run: ./generate.sh - name: PHPUnit Tests - uses: php-actions/phpunit@v2 + uses: php-actions/phpunit@v3 with: bootstrap: vendor/autoload.php configuration: tests/phpunit.xml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..1e75fabe --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,97 @@ +# AGENTS.md + +## Purpose +This file is the operating guide for contributors and coding agents working in `relewise-sdk-php`. + +The repository is a PHP SDK with generated client/models and integration-heavy tests. Follow this guide to keep changes scoped, reproducible, and aligned with CI. + +## Repository Map +- `src`: PHP SDK source (clients, infrastructure, models, factories). +- `tests`: PHPUnit bootstrap, env loader, and test suites (`php/integration`, `php/unit`). +- `Generator`: .NET generator project that writes SDK code into `src`. +- `.github/workflows`: CI, publish, and Trello automation workflows. +- `generate.ps1` / `generate.sh`: entry points for code generation. +- `composer.json`: package metadata and PHP/test dependencies. +- `DEVELOPMENT.md`: local development notes. + +## Core Working Conventions +- Run commands from repository root unless explicitly noted. +- Keep changes minimal and directly related to the task. +- Do not commit secrets (`DATASET_ID`, `API_KEY`, tokens). +- Treat generator output as generated code: + - `src/Models` is generator-owned. + - Client surfaces in `src` are also produced by generator workflows. +- Prefer updating `Generator` + running generation scripts over manual edits in generated files. + +## Generation Workflow +Prerequisite: .NET 10 SDK or newer. + +Use one of: + +```powershell +./generate.ps1 +``` + +```bash +./generate.sh +``` + +Both scripts run the .NET generator and write output to `src`. + +## Runbook +Install dependencies: + +```powershell +composer install +``` + +Generate SDK code: + +```powershell +./generate.ps1 +``` + +```bash +./generate.sh +``` + +Run all tests configured by CI: + +```powershell +vendor/bin/phpunit --configuration tests/phpunit.xml --testsuite Unit +``` + +Run unit-only folder (optional fast loop): + +```powershell +vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml +``` + +## Testing and Credentials +- Many tests require `DATASET_ID` and `API_KEY`. +- CI injects those from secrets. +- Local runs can load them from `tests/.env` via `tests/Bootstrap_phpunit.php` and `tests/DotEnv.php`. +- If credentials are unavailable, report integration coverage as not run. + +## Validation Policy (CI-Aligned, Pragmatic) +- Required for normal changes: + - Run generation if change touches generator-owned code paths. + - Run PHPUnit with `tests/phpunit.xml`. +- Required for behavior/API changes: + - Run tests that exercise affected flows. + - Include integration-oriented coverage when credentials are available. +- For workflow/tooling changes: + - Validate relevant command paths still run locally. + +## PR Expectations +Each PR should include: +- Scope: what changed and why. +- Risk notes: behavioral areas potentially impacted. +- Validation: commands run and outcomes. +- Generation note: whether `generate.ps1` / `generate.sh` was run. + +## Known Pitfalls +- Manual edits to generated code will drift from generator output. +- `tests/phpunit.xml` points at `tests/php`, so default suite includes both unit and integration folders. +- Tests depending on `DATASET_ID`/`API_KEY` fail fast when env is missing. +- Keep runtime assumptions aligned with `composer.json` (`php: ^8.1`). diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 24f0c7e7..25f33549 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,7 +6,7 @@ This document describes the process for running this application on your local c This project uses .NET to automatically generate the models used in the PHP client. -To run the generator you need to have .NET 7 or newer installed on your machine. [Download .NET 7](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) +To run the generator you need to have .NET 10 or newer installed on your machine. [Download .NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) Then to generate the models and clients of the SDK run `generate.ps1` if you're on Windows, else run `generate.sh`. diff --git a/Generator/Generator.csproj b/Generator/Generator.csproj index 68266854..3690c3ea 100644 --- a/Generator/Generator.csproj +++ b/Generator/Generator.csproj @@ -2,7 +2,7 @@ Exe - net8.0 + net10.0 enable enable From c543d00b0c9e63aaac94dda21c53948a69c0be3c Mon Sep 17 00:00:00 2001 From: brianhdk Date: Mon, 16 Feb 2026 05:47:21 +0100 Subject: [PATCH 2/2] skill to update sdk --- .agents/skills/update-sdk/SKILL.md | 177 +++++++++++++++++++ .agents/skills/update-sdk/agents/openai.yaml | 4 + AGENTS.md | 15 ++ 3 files changed, 196 insertions(+) create mode 100644 .agents/skills/update-sdk/SKILL.md create mode 100644 .agents/skills/update-sdk/agents/openai.yaml diff --git a/.agents/skills/update-sdk/SKILL.md b/.agents/skills/update-sdk/SKILL.md new file mode 100644 index 00000000..291e266a --- /dev/null +++ b/.agents/skills/update-sdk/SKILL.md @@ -0,0 +1,177 @@ +--- +name: update-sdk +description: Regenerate relewise-sdk-php from the Generator project with a strict git and PR flow. Use when asked to update generated PHP SDK code. Require a Trello card URL, run clean-main preflight checks, create a timestamped chore branch, run generation and validation, then push and open a PR with the Trello URL as the first line. +--- + +# Update SDK (PHP) + +## Goal +Regenerate SDK code in `src` from `Generator`, validate the result, and deliver a reviewed PR to `main`. + +## Required Input +Require a Trello card URL before running SDK update work. + +If the request does not include a Trello URL: +- Ask for it. +- Do not continue until it is provided. + +## Preflight Git Safety +Run from repository root. + +1. Require a clean worktree: +```powershell +git status --porcelain +``` +Abort when any output exists. + +2. Ensure `origin` exists: +```powershell +git remote get-url origin +``` +Abort on failure. + +3. Fetch refs: +```powershell +git fetch origin --prune +``` +Abort on failure. + +4. Switch to `main`: +```powershell +git switch main +``` +Abort if switch is not safe. + +5. Fast-forward `main`: +```powershell +git pull --ff-only origin main +``` +Abort if not fast-forward. + +Do not continue when any preflight step fails. + +## Branch Creation +Use a timestamped branch: + +```powershell +$stamp = Get-Date -Format 'yyyyMMdd-HHmm' +$branchName = "chore/update-sdk-$stamp" +``` + +Abort if branch exists: + +```powershell +git show-ref --verify --quiet "refs/heads/$branchName" +git ls-remote --exit-code --heads origin $branchName +``` + +Create and switch: + +```powershell +git switch -c $branchName +``` + +## SDK Regeneration +1. Install dependencies: +```powershell +composer install --no-interaction --no-progress +``` + +2. Regenerate SDK code: +```powershell +./generate.ps1 +``` + +Alternative on non-Windows: +```bash +./generate.sh +``` + +## Expected Changes Check +Inspect changed files and ensure the update is coherent. + +Expected change locations: +- `src/Models/*` generated model files +- generated client surfaces in `src/*.php` +- generator changes only when intentionally included + +If unrelated files changed unexpectedly, stop and investigate. + +## Validation (Required) +Run this command: + +```powershell +vendor/bin/phpunit --configuration tests/phpunit.xml --testsuite Unit +``` + +Integration-heavy tests depend on `DATASET_ID` and `API_KEY`. + +When credentials are unavailable, run the unit subset and report integration-heavy coverage as not run: + +```powershell +vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml +``` + +## Acceptance Criteria +Treat update as successful only when: +- generation succeeds (`generate.ps1` or `generate.sh`) +- validation command(s) pass for available credentials +- changed files are expected and reviewable + +## Commit, Push, and Pull Request +1. Commit SDK update changes: +```powershell +git add . +git commit -m "chore(php): update sdk generation ($stamp)" +``` + +2. Push branch: +```powershell +git push -u origin $branchName +``` + +3. Create PR to `main`. + +Preferred flow with GitHub CLI: +```powershell +$prBodyPath = ".\\update-sdk-pr-body.md" +@" +$TrelloCardUrl + +## Summary +- Regenerated PHP SDK code via Generator +- Updated generated models/client surfaces + +## Validation +- `composer install --no-interaction --no-progress`: +- `./generate.ps1`: +- `vendor/bin/phpunit --configuration tests/phpunit.xml --testsuite Unit`: +- `vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml`: + +## Notes +- +"@ | Set-Content $prBodyPath + +$prUrl = gh pr create --base main --head $branchName --title "chore(php): update sdk generation ($stamp)" --body-file $prBodyPath +if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' } +Write-Host "PR URL: $prUrl" +``` + +Manual fallback: +```powershell +git push -u origin $branchName +Write-Host "Create PR: https://github.com/Relewise/relewise-sdk-php/compare/main...$branchName?expand=1" +Write-Host "PR title: chore(php): update sdk generation ($stamp)" +Write-Host "PR body file: $prBodyPath" +``` + +Keep the Trello URL as the first line of the PR description. + +## Output Expectations +Provide a final summary with: +- Trello URL used +- branch name +- changed file groups +- validation command results +- pushed branch URL +- PR URL, or exact manual fallback instructions diff --git a/.agents/skills/update-sdk/agents/openai.yaml b/.agents/skills/update-sdk/agents/openai.yaml new file mode 100644 index 00000000..34134c10 --- /dev/null +++ b/.agents/skills/update-sdk/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Update SDK" + short_description: "Regenerate relewise-sdk-php code and open Trello-linked PR" + default_prompt: "Use $update-sdk to regenerate relewise-sdk-php, validate tests, and create a branch and PR with the Trello URL as the first line." diff --git a/AGENTS.md b/AGENTS.md index 1e75fabe..47ab79ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,12 @@ The repository is a PHP SDK with generated client/models and integration-heavy t - `composer.json`: package metadata and PHP/test dependencies. - `DEVELOPMENT.md`: local development notes. +## Repository Skills +- `update-sdk`: + - Location: `.agents/skills/update-sdk/SKILL.md` + - Use when asked to regenerate generated SDK code from `Generator`. + - This skill enforces Trello URL pre-requisite, clean-main preflight checks, timestamped chore branch creation, validation commands, and Trello-first PR descriptions. + ## Core Working Conventions - Run commands from repository root unless explicitly noted. - Keep changes minimal and directly related to the task. @@ -83,6 +89,15 @@ vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml - For workflow/tooling changes: - Validate relevant command paths still run locally. +## SDK Update Guidance +For generation-driven SDK refresh tasks, prefer using the `update-sdk` skill: + +```text +$update-sdk +``` + +Use `update-sdk` when the goal is regenerating PHP SDK code and opening a branch/PR flow tied to a Trello card. + ## PR Expectations Each PR should include: - Scope: what changed and why.