sugarcraft

Scaffolds a new SugarCraft monorepo port end-to-end across every touchpoint: creates <slug>/composer.json + phpunit.xml + README.md + CALIBER_LEARNINGS.md + src/<Class>.php, then wires it into root composer.json (require + repositories[]), docs/MATCHUPS.md, PROJECT_NAMES.md, root README.md table, docs/index.html tiles, docs/_data/<slug>.{json,body.html} → tools/gen-docs.php, media/icons/<slug>.png, .github/workflows/vhs.yml matrix, and codecov.yml (flag + component). Use when the user says 'add a library', 'port <upstream>', 'scaffold lib <slug>', 'new candy-/sugar-/honey- lib', 'create SugarX'. Do NOT use to edit an existing lib's metadata (use direct Edit), add a feature to an existing lib (follow that lib's CALIBER_LEARNINGS.md), rename a lib, or add a plain sugarcraft dep to an existing lib (use path-repo-closure).

Adds a translation file at `<slug>/lang/<code>.php` by copying the library's `en.php` and translating only the values while preserving every array key and `{placeholder}` token verbatim; locale codes come from `LOCALES.md`. Use when the user says 'add <language> translation', 'translate <lib> to <code>', 'add Japanese/French/etc. locale', or 'add es.php to sugar-charts'. Do NOT use to edit `en.php` (it is the source of truth), to first-time-wire `Lang::t()` into a lib that has no `lang/` directory yet, or to change the base `SugarCraft\Core\I18n\Lang`/`T` machinery.

Propagates a new sugarcraft/<dep> dependency across every consuming composer.json — adds the require entry plus a {type:path, url:"../<dep>", options:{symlink:true}} repository for the FULL transitive closure (mirrors sugar-charts/composer.json), then verifies with tools/check-path-repos.php. Use when the user says 'add dep on <slug>', 'wire up <slug>', 'new transitive dep', or edits a require["sugarcraft/..."] line. Do NOT use for non-sugarcraft Packagist deps (those need only a require bump, no path-repo) or for scaffolding a whole new library (use scaffold-library / add-library-checklist).

Scaffolds a new immutable+fluent SugarCraft class — `final`, `declare(strict_types=1)`, a private constructor with public `readonly` promoted props, `::new()` factory, `with*()` setters that return a new instance, bare accessors (no `get`), and (for TUI roots) the candy-core `Model` contract `init()`/`update(Msg): [Model, ?Cmd]`/`view()`/`subscriptions()`. Mirror `candy-sprinkles/src/Style.php` (value object) or `sugar-bits/src/Stopwatch/Stopwatch.php` (Model). Use when the user says 'add a Model', 'new TUI widget', 'scaffold a SugarCraft class', 'port from charmbracelet/<x>', or creates files under `<slug>/src/`. Do NOT use for editing an existing class (use direct Edit), tests-only changes (use write-phpunit-test), scaffolding a whole new library skeleton (use scaffold-library), or non-SugarCraft repos.

Writes PHPUnit 10 tests for SugarCraft TEA libs in the four project modes — snapshot byte (view()→raw SGR), cell-grid (SugarCraft\Vt\Terminal / Buffer), behaviour (update()→[Model,?Cmd]), and coercion (clamp/throw edges) — plus golden-file and program-driving helpers from candy-testing (Assertions::assertGoldenAnsi/assertCellGrid/assertViewIdempotent, ProgramSimulator, ScriptedInput). Use when the user says 'write a test', 'add snapshot test', 'add golden test', 'test this Model', 'test update()', or 'test view() output' for any candy-*/sugar-*/honey-* lib. Do NOT use to duplicate a canonical lib's suite into a class_alias façade lib (ship a single AliasesTest asserting each alias resolves to its canonical FQN instead), and do NOT use for non-TUI plain-PHP unit tests that have no view()/update()/Model.

Processes docs/plans/AUDIT_*.md files by marking items ✅/⏭️ inline where they live (never moving them — readers see history in place), skipping 'credit upstream author' and UPGRADE_GUIDE items (out of scope pre-1.0), and splitting multi-lib audits into one PR per lib sequenced by dependency order (candy-core → candy-sprinkles → honey-bounce → leaf libs). Use when the user says 'work through audit', 'process AUDIT_*.md', 'fix audit findings', or names a docs/plans/AUDIT_*.md file. Do NOT bundle multiple libs into one PR, do NOT use for net-new feature work, and do NOT retroactively rewrite or force-push already-merged audit PRs.

Scaffolds a new SugarCraft library end-to-end per the AGENTS.md checklist. Creates <slug>/composer.json (path-repo closure copied from sugar-charts), README.md, CALIBER_LEARNINGS.md, phpunit.xml, src/<Class>.php with declare(strict_types=1) + PSR-4 namespace, tests/ stub, and updates root composer.json + MATCHUPS.md + PROJECT_NAMES.md + README.md table + docs/index.html tile + docs/lib/<slug>.html + .github/workflows/ci.yml + .github/workflows/vhs.yml + codecov.yml. Use when user says 'add new library', 'port <upstream>', 'create candy-X', 'create sugar-Y', or 'create honey-Z'. Do NOT use for adding features to an existing lib (follow that lib's CALIBER_LEARNINGS.md instead) or for renaming libs (separate flow).

Creates a VHS .tape file at <slug>/.vhs/<demo>.tape driving php examples/<demo>.php with TokyoNight theme and the standard FontSize/Width/Height/Type/Enter/Sleep sequence. Also adds the lib to the hand-maintained matrix in .github/workflows/vhs.yml when missing. Use when user says 'add VHS demo', 'record gif', 'new tape file', 'add a tape for <slug>'. Do NOT use for editing an existing tape's visual style, rendering GIFs locally (CI does that via vhs.yml), or for non-visual libs (candy-pty, FFI/syscall wrappers) — those are exempt from the .vhs/ + matrix requirement.

Authors a `<slug>/.vhs/*.tape` VHS demo file and wires it into `.github/workflows/vhs.yml` so CI re-renders the GIF. Sets `Set Theme "TokyoNight"`, 800x480 dims, `Type "php examples/<demo>.php"` boilerplate. Use when user says 'add a demo', 'record VHS', 'new tape', 'regenerate GIF', or creates/edits a file under `<slug>/.vhs/`. Capabilities: scaffolds the .tape file, adds the slug to the workflow `all=(...)` array, registers required non-default PHP extensions (ext-ssh2/ext-gd/ext-ffi) in `extensions:`. Do NOT use for non-visual primitive libs (`candy-pty`, FFI bindings, codecs) — they're matrix-exempt; do NOT use for changes to the rendered `.gif` itself (CI overwrites it).

Writes a PHPUnit 10 test in <slug>/tests/<Class>Test.php for SugarCraft monorepo libs. Use when the user says 'add test', 'write a phpunit test', 'cover <Class>', 'test this method', or modifies files under <slug>/src/. Produces snapshot tests for renderers (asserting raw \x1b[…m SGR bytes), behaviour tests for state machines (driving update() with scripted KeyMsg/MouseMsg/Tick), coercion tests for fluent setters (clamped/no-op on bad input), and immutability checks for with*() builders. Uses namespace SugarCraft\<Sub>\Tests, final class extending PHPUnit\Framework\TestCase, runs via vendor/bin/phpunit from the lib root. Do NOT use for integration tests, CI workflow files, JS/frontend tests, or non-PHPUnit testing frameworks.

Scaffolds a new SugarCraft TUI class following the canonical immutable + fluent pattern: final class, declare(strict_types=1), readonly props, private mutate() helper, with*() setters, and (for TUI roots) the Model::init/update/view contract from candy-core. Use when user says 'add a new Model', 'new TUI widget', 'port from charmbracelet/<x>', 'scaffold a SugarCraft class', or creates new files under <slug>/src/. Do NOT use for editing existing Models, for non-SugarCraft PHP libs, for tests-only changes (use phpunit-skill), for adding new libraries from scratch (use scaffold-library), or for cross-lib refactors.

Runs the SugarCraft ship-as-you-go PR cadence for a cohesive change-set: stage → commit (author Joe Huss <detain@interserver.net>) → push → unset GITHUB_TOKEN && gh pr create → gh pr merge <n> --merge --delete-branch → git checkout master && git pull --ff-only. Bundles 2-4 related items per PR. Use when user says 'ship this', 'open PR', 'merge and continue', 'next phase', 'ship as you go', or after a cohesive change-set passes tests. Do NOT use to amend already-merged PRs, push directly to master, force-push, skip pre-commit hooks, or for work that has not passed `vendor/bin/phpunit` for every touched lib.

Rules pertaining to Composer dependency management, promoting best practices for declaring and updating dependencies.

Guides PHP project upgrades using Composer commands. Use when helping users upgrade PHP packages, check for security vulnerabilities with `composer audit`, prioritize which packages to upgrade first, understand dependency conflicts, interpret `composer outdated` output, use `composer why-not` to diagnose version constraints, use `composer why` to trace dependencies, use `composer bump` to harden version constraints after upgrading, plan safe upgrade paths, resolve package version conflicts in composer.json, or resolve merge conflicts in composer.lock. Trigger this skill whenever the user mentions composer packages, PHP dependencies, outdated packages, CVEs in PHP projects, or security advisories.

Use when building PHP applications with modern PHP 8.3+ features, Laravel, or Symfony frameworks. Invokes strict typing, PHPStan level 9, async patterns with Swoole, and PSR standards. Creates controllers, configures middleware, generates migrations, writes PHPUnit/Pest tests, defines typed DTOs and value objects, sets up dependency injection, and scaffolds REST/GraphQL APIs. Use when working with Eloquent, Doctrine, Composer, Psalm, ReactPHP, or any PHP API development.