Skip to content

ByteTerrace/Puck / .claude/skills/tooling

tooling

Verified

Maps shared build/CLI architecture, compiler assembly identity, candidate installation, generated sections, and host admission.

---
name: tooling
description: "Maps shared build/CLI architecture, compiler assembly identity, candidate installation, generated sections, and host admission."
---

# Build and CLI tooling

Load [verification](../verification/SKILL.md) for builds, private CLI copies and
leases, and [symbol-analysis](../symbol-analysis/SKILL.md) for finding callers.
[CI and releases](../../../docs/development/ci.md) owns repository automation;
the [CLI reference](../../../docs/reference/cli.md) owns verb behavior.
File publication, paths, Git inventories, project ownership and Markdown parsing route to
[tooling-files](../tooling-files/SKILL.md).

| Capability | Shared home | Callers and boundary |
|---|---|---|
| Parse project declarations and evaluate architecture policy | `ArchitectureModel` in `build/ProjectArchitecture.cs` | The build task and `Puck.Cli.Core` compile this source. MSBuild supplies evaluated policy and resolved references; `ArchitectureCommand` supplies declared facts. Keep resolved-route enforcement (`PUCKARCH006`) in `PuckArchitectureGate`. A declared report cannot prove resolved references. |
| Walk project dependencies | [ArchitectureGraph](../../../build/ProjectArchitecture.cs) | Architecture closures follow assembly edges; affected and shader selection follow all build references. Choose the edge set; share the walk. |
| Traverse assemblies for derivation identity | `AssemblyReach.Of` | The default follows `Puck.*`; `WorldCompileSession` includes all non-framework compiler dependencies and records missing trimmed modules. `WorldCodeWarmer` uses the same walk. Keep identity folds with their derivations. |
| Splice generated document sections | `CliGeneratedSection.TryReplace` | Packages and the architecture map preserve delimiters and surrounding text, then use `CliGeneratedFile.WriteOrCheck`, including index agreement. |
| Install an isolated CLI candidate | `CandidateCliInstall` in `build/CandidateCliInstall.cs` | Compiled into `Puck.Cli.Release` and run as a file-based bootstrap by `setup-puck`, before a CLI exists. One exclusive feed, private package cache, fresh tool path and version check. The CLI supplies `CliProcess`; bootstrap `Main` supplies process I/O only. |
| Acquire and admit leased work | `LeasedAdmission.AcquireAsync` and `CliLease` in `Puck.Cli.Core` | Heavy work and device Worlds park their ticket during unleased admission, then reserve with a zero wait under the grant guard. Lost headroom parks the same ticket without serving the lane. `WorldLaunch` owns live worker holds, shared through `WorldWorkHold`. The total caller deadline includes acquisition and admission. |
| Bound a measurement window | `OperationDeadline` in `Puck.Abstractions`, owned by `MeasureCommand` | One clock and cancellation lifetime covers acquisition, settling and draining. `MeasureCommand.DrainAsync` checks it before each request and sample, and incomplete requests remain pending. `CliProcess.RunCapturedAsync` stops and reaps the active child tree before the quiet hold is disposed. |
| Recover abandoned lease metadata | `CliLease.PruneReleased` in `Puck.Cli.Core` | Inspection and quiet-priority checks share cleanup under the resource's exclusive guard. Acquisition already replaces metadata once it owns that same guard; process identity and metadata age never override a free guard. |
| Pause a suite budget while waiting for another run | `SuiteBudget` in `Puck.Cli.Core` | Sweep, motion, frame benchmarks and offscreen legs share remaining-time calculation, cancellation and scoped pauses. Offscreen callers lend their existing suite stopwatch. Canary's concurrent leg context already uses `CliProcess.RemainingBudget`; it does not pause a shared clock while other legs run. |
| Enumerate the live console vocabulary across boot shapes | `WorldConsoleVerbs.TryEnumerate` in `Puck.Cli.Harness` | `verbs` and `docs citations` read the structured `world.affordances` manifest. The catalog excludes authored commands; citation checking includes them. |
| Sample and judge host headroom | `HostAdmission`, `HostProbe`, `HostStartTracker` in `Puck.Cli.Harness/Host` | `WorldAdmission` installs real admission by default, including standalone `Puck.Cli.Worlds`. `Install` is a test override; no entry point needs to remember an install call. `HostStartTracker.Expected` is the one expected-peak door: the high percentile of `HostPeakWindow`'s last ten observed processes of the kind, persisted per kind under `HostStartTracker.ObservationDirectory` in the lease root, where the file decides and a process adds only what it observed since its last write; one outlier session never ratchets it, and an estimate the machine could not hold even with every admitted start gone judges by the lesser of itself and the kind's fallback (`HostStartTracker.Lone`), so a refused kind can still run and teach the window a lower figure. Each observation carries private bytes (judged against commit), private working set (judged against free RAM; `Puck.Hosting.HostMemory.PrivateResidentBytes` reads it for another process) and whole working set (reported only, since its clean mapped pages are reclaimable). A change to those lines renames the directory and raises `CliLease.Protocol`. `HostLoadThresholds.NeverFits` names a start the idle machine could not hold, and `HostAdmission.Wait` refuses it at once. |
| Turn captured processes into gate outcomes | `GateStepResult.Captured` | Gate execution and lock restore preserve merged stream order, refusal exit on timeout, and one timeout annotation. |
| Move every external dependency by one rule and report moves and holds | `DepsCommand` in `Puck.Cli.Gate/Deps`, one `*Dependencies` class per ecosystem over `DependencyContext` | NuGet reuses `LockFiles.Record` with `update`. `NuGetDependencies` restores file-app moves before accepting them and retries a failed batch one move at a time. `DependencyFiles` puts every touched file back for `--check` and a failed run. A new ecosystem is a class beside them and a name in `DependencyEcosystems`, never a second verb. `deps.yml` orchestrates `update` then `submit` ([CI](../../../docs/development/ci.md#dependency-updates)); GitHub REST calls go through `CliGitHub`. |
| Read published package versions | `NuGetFeed` and `DependencyVersion` in `Puck.Cli.Core` | The dependency updater and NuGet release preparation share one NuGet flat-container reader and retry policy. `DependencyVersion` orders versions for NuGet, npm and Git tags. |
| Re-record lock files without advancing pinned packages | `LockFiles.Record` and `LockPins.Hold` in `Puck.Cli.Gate/Locks` | The restore evaluates the graph afresh (current project closure, every floating range at the newest package); `Hold` takes each package back to the version its lock file pinned wherever the project asks for it the same way, and a locked restore judges the set. `--update` skips the hold. |
| Read `name=value` fields of a World's narration line | `CliLineFields` in `Puck.Cli.Core` | `StartupBake` reads residency identities from `[sdf.mesh-bake]` lines; `world player` sums their `baking=`/`loading=` counts. `CanaryAssertions.TryReadField` reads console answers whose values may be parenthesized, a grammar of its own. |
| Assemble the folder a consumer machine runs | `WorldPlayerCommand` in `Puck.Cli.Release/Automation` | Composes the existing steps: Puck.World's self-contained publish (`PuckSelfContained`, which keeps the RID out of referenced projects' locked restores) and its prewarm target, `compile --tree`, `WorldPrepareCommand.Compose` and `PrepareShading`, then the published engine's own baking boots through `WorldLaunch` with `Executable` set (a headless boot with `--no-bake`), and publishes the stub and `Puck.Launcher.Setup` self-contained into `launcher/`. A new cache a player may ship joins here, filled by the shipped binary or keyed independently of the process that fills it. `PlayerBuildLayout` (Puck.Launcher) names the parts the producer, `puck publish` and the installer share. |
| Carry a GPU-baked mesh store to a release built without a GPU | `WorldCachesCommand` in `Puck.Cli.Release/Automation` | `produce` packs a player folder's mesh set per backend, named by `MeshBuildIdentity` (the store's set identity, read from the folder's own build), into a cache set; `--push` makes it the asset of the GitHub prerelease `caches/<backend>-<identity>` through `gh`. `fetch` verifies every content pin before unpacking, then holds the channel's publish (exit 1) for a backend with no matching set or a set whose recorded world plan (`WorldCachePlan`) differs from the release's own. |
| Sign a release and write it to a channel's host | `ChannelCommand` and `ReleaseChannelHost` in `Puck.Cli.Release/Channel` | `ReleaseSigner` (Puck.Launcher) signs; the host owns the root key's custody and the upload, objects before manifests. A provider contributes a host through its CLI extension (Azure: `AzureCliExtension`, the deployment vault and official-content container); `DirectoryReleaseChannelHost` mirrors locally with a key file. No provider type reaches the verb. |

The framework-facade MSBuild task runs before Puck projects build; a project
reference to the runtime CLI would create a bootstrap dependency and target the
wrong runtime. Shared source is intentional. Add a new shared build source to
the task's compiler inputs and its assembly-cache identity together.

Only the reservation under a lease's own guard is a single reading. Every other
admission waits for its bound, whatever this process or an ancestor already
holds: a lane's second start (`WorldWorkHold`'s joining share) and another
lane's start in the same adapter judge headroom on their own readings, and one
share cannot release another live start's hold. `WorldLaunchRequest.AdmissionWait`
is that bound (`puck_world_start` passes its `timeoutSeconds`); a start that can
never fit (`NeverFits`) is refused at once and `HostAdmissionRefusedException.Reason`
names why. Cross-process growth
reservations also remain process-local; machine leases serialize device and
heavy starts. Do not describe those reservations as machine-wide exclusion.

This map earns its place by naming the cross-assembly homes and distinctions a
name search misses: declared versus resolved references, assembly versus build
edges, compiler dependencies versus Puck-only warmup, and bootstrap versus
installed CLI execution. Update it with a move or a new caller.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall