chore: add /sdk-proxy slash command for hitting the API via the SDK app proxy

[serikjensen]

Summary

Adds a Claude/Cursor slash command at .claude/commands/sdk-proxy.md that lets the agent run real curl requests against whatever demo company you already have running in the SDK Dev App. No re-provisioning, no env-file reads, no port hardcoding.

Invocation pattern:

/sdk-proxy create an employee named Alice Johnson
/sdk-proxy list payrolls for the current company
/sdk-proxy show me what a "submit payroll" request body looks like

What the command teaches the agent

• Port discovery via lsof -iTCP:5200-5299 + cwd-match against git rev-parse --show-toplevel. Robust against auto-incremented ports (5201/5202/...) and multiple sibling-repo SDK apps running in parallel; verified with /sdk-app/api/validate-token signature endpoint as a fallback diagnostic.
• Always route through the local Vite proxy (http://localhost:<port>/api/...), never the gws-flows host directly. The proxy's in-memory FLOW_TOKEN is the source of truth; the on-disk env file lags when "Set Manual Token" / "Refresh Token" is used in the Settings panel.
• Discover the live company UUID by hitting /v1/companies, never by reading sdk-app/env/.env.demo.
• Look up endpoints via the gusto-payroll MCP (find_endpoint / generate_curl / check_scopes / validate_workflow) instead of guessing paths from memory.
• Temp-file curl pattern (curl -o $OUT -w "HTTP %{http_code}" && jq < $OUT) so the status code and JSON body never collide in jq's parse stream.
• Per-repo cache in $TMPDIR (120s TTL + single verify probe) so repeat invocations skip discovery entirely — first call ~1.2s, subsequent calls ~150ms.

Two subtle footguns captured as inline author-notes

1. Cursor's slash-command renderer interpolates dollar-digit tokens ($0–$9) as positional args from the user's invocation, before the agent sees the prompt. An awk '{print $2}' literal becomes awk '{print <second word of user message>}'. The discovery snippet uses lsof -F field records + grep/sed instead of awk positional fields, and a verified-grep guard keeps it that way.
2. Cache hygiene relies on unset → source → <rm + unset> on every failure path. Without the pre-source unset, a missing key in a partial cache file inherits prior shell state. Without the post-failure unset, a stale COMPANY_ID lingers in the shell environment and silently leaks into rediscovery in Step 1.

Files touched

Just one new file:

• .claude/commands/sdk-proxy.md (+262 lines)

No source code changes. Cache file lives in $TMPDIR, outside the repo — no .gitignore update needed.

Test plan

• Discovery snippet resolves SDK_APP_PORT=5200 against this repo's running SDK app (verified end-to-end during development).
• Cache write → read → verify-probe round-trips with HTTP 200 (verified).
• All four Step 0 code paths exercised (fresh-hit / expired / verify-fail / no-cache-with-leaked-shell-vars) and produce the expected CACHE_HIT / file / unset state.
• curl -o $OUT -w "HTTP %{http_code}" && jq < $OUT pattern produces clean output (no jq: parse error noise).
• Zero \$<digit> matches remain in the file (verified-grep guard).
• Reviewer: try /sdk-proxy list employees for the current company against a running SDK app to confirm the end-to-end flow works in your environment.

Screen.Recording.2026-06-02.at.4.05.51.PM.mov

Made with Cursor

[mariechatfield]

Ah this is so cool! loved using it to update some data live