Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .cfgcaddy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ links:
os: "Linux Darwin"
- src: .claude/hooks/cmdcrush-wrap.sh
os: "Linux Darwin"
- src: .claude/hooks/pr-review-reminder.sh
os: "Linux Darwin"
- src: .config/ssq-hooks
os: "Linux Darwin"
- src: .config/finicky/finicky.js
Expand Down
2 changes: 1 addition & 1 deletion .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Use the serena MCP server for complex multi-file structural edits when available

- **Self-explanatory code first.** A good name or a clean structure removes the need for a comment; reach for one only after that fails.
- **Why, not what.** Comment a hidden constraint, a non-obvious tradeoff, or a workaround for a specific bug — never restate what the code already says.
- **Short beats long.** One line over a paragraph. If a comment needs more than a line, the code usually needs a rename instead.
- **Short beats long.** One line over a paragraph, and never more than 5 lines or one paragraph — the same ceiling `code:review`'s Code Quality check flags as MAJOR, so writing past it just means a reviewer sends it back. If a comment covers more than one distinct rationale (root cause vs. an accepted tradeoff vs. a pointer to a test), split it or cut to the single fact a reviewer would actually ask for — don't stack every consideration into one block.
- **Docstrings on entry points only.** Give a public function or module an overview when its purpose isn't obvious from its name and signature; skip it for private helpers.
- **Name assumptions and limits.** If a function assumes sorted input, a bounded range, or has a known failure mode, say so once at the point of use.

Expand Down
18 changes: 18 additions & 0 deletions .claude/hooks/pr-review-reminder.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
#!/bin/bash
# PreToolUse(Bash) hook: before `gh pr create|ready|merge` (including env-prefixed
# and chained forms), inject a reminder to run the full adversarial review loop.
# PreToolUse so it lands before a chained `gh pr ready && gh pr merge` completes.
#
# Hot path: runs on EVERY Bash call, so it must not spawn anything. `read` is a
# builtin and `case` early-exits on the raw hook JSON; jq/grep run only on a hit.
IFS= read -r -d '' input
case $input in
*"gh pr "*) ;;
*) exit 0 ;;
esac
cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null)
if printf '%s' "$cmd" | grep -qE 'gh pr (create|ready|merge)'; then
cat <<'JSON'
{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"MANDATORY REVIEW GATE (Tyler standing policy): you are about to open/ready/merge a PR. Before handing it to Tyler, marking it ready, or merging it you MUST run the full adversarial review loop — your own verified pass + fresh UNANCHORED reviewers across the right lenses (correctness, concurrency, domain-semantics vs the code being replaced, tests/security) + a round-2 convergence pass — and address every real finding. Bitbot + a glance is NOT enough. If this PR is docs/config-only, say so explicitly and scope the review lenses accordingly rather than skipping review."}}
JSON
fi
115 changes: 115 additions & 0 deletions .claude/skills/demo-assets/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
name: demo-assets
description: "Capture and share demo assets on a GitHub PR: terminal-recording GIFs (vhs) and PNG screenshots, including browser screenshots of web pages (Playwright). Use for 'screenshots for the PR', 'demo gif', 'attach images/gifs to a PR', 'show the UI change'. Hosts files on a throwaway orphan branch deleted after merge"
allowed-tools: Bash(vhs:*) Bash(ffmpeg:*) Bash(git:*) Bash(gh:*) Bash(npx:*) Bash(node:*)
---

# Demo assets (GIFs and screenshots) for a PR comment

Use when a PR needs visual evidence: a CLI/TUI flow (GIF) or a UI change (PNG). Posting is outward-facing:
draft the comment, get the user's approval before `gh pr comment`, and label it agent-authored if it goes out
under the user's login.

**Rule: never commit assets into the PR branch.** They live only on the `qa-assets/pr-<N>` branch (step 2).

## 1a. Record a terminal GIF

```sh
brew install vhs # pulls ttyd; runs headless
vhs demo.tape # tape: Output demo.gif / demo.mp4
```

- Open the tape with a title card (PR number, scenarios shown) so the clip is self-describing.
- vhs drops frames at large sizes. Use `Set Framerate 12` and about 1500x860; a 1700x950 render of a 70s run came out 15s.
- Keep the GIF under ~5 MB: trim waits with `Sleep` and shorten timeouts via env overrides. Ship the MP4 too.
- Check it: `ffmpeg -ss 25 -i demo.mp4 -frames:v 1 f.png`, then look at a few frames. Don't claim it's legible unseen.

## 1b. Capture PNG screenshots

1. **List every page, tab and state the PR changes first** (including empty, error and loading states). One
image per state; tick each off before moving on.
2. Run the app locally, preferably against synthetic/fixture data.
3. Capture with Playwright (chromium) into `/tmp/<name>/`:

```js
// shots.js — run: npx playwright install chromium && node shots.js
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1500, height: 1000 } });
const shots = [['capacity', 'http://localhost:3000/capacity', '[data-testid=chart]']];
for (const [name, url, ready] of shots) {
await page.goto(url);
await page.waitForSelector(ready); // wait for content, not a fixed sleep
await page.addStyleTag({ content: '*,*::before,*::after{animation:none!important;transition:none!important}' });
await page.screenshot({ path: `/tmp/pr-assets/${name}.png` }); // viewport only; fullPage only if needed
}
await browser.close();
})();
```

- **Naming:** kebab-case, `<page>[-<tab-or-state>].png`, e.g. `capacity.png`, `capacity-empty.png`. Names become
URLs; no spaces or uppercase.
- **Size:** viewport screenshots, not full-page, unless the page's point is its length. If installed, shrink
with `oxipng -o2 *.png` or `pngquant --force --ext .png 256 *.png`.
- **Look at every image** (Read the PNG) before publishing. Don't claim it's right unseen.
- **Sensitive data:** inspect each image for real hostnames, account IDs, emails, tokens, customer names or
internal URLs in the address bar, tabs or content. Prefer fixture data; otherwise re-capture or crop. In a
public repo anyone can see these files.

## 2. Host on a throwaway orphan branch

An orphan branch shares no history with the PR, so the PR diff and the default branch are untouched.

```sh
git worktree add --orphan -b qa-assets/pr-<N> /tmp/qa-assets-<N> # git >= 2.42
cp /tmp/pr-assets/*.png demo.gif demo.mp4 /tmp/qa-assets-<N>/ # whichever you have
git -C /tmp/qa-assets-<N> add .
git -C /tmp/qa-assets-<N> commit -m "qa assets for PR <N> (delete after merge)"
git -C /tmp/qa-assets-<N> push origin qa-assets/pr-<N>
git worktree remove /tmp/qa-assets-<N>
```

Embed:

```md
<!-- public repo -->
![demo](https://raw.githubusercontent.com/<owner>/<repo>/qa-assets/pr-<N>/capacity.png)
<!-- private repo: raw.githubusercontent URLs need a token; use the repo-relative raw URL and check it renders -->
![demo](https://github.com/<owner>/<repo>/raw/qa-assets/pr-<N>/capacity.png)
```

For a GitHub Enterprise Server host, use `https://<host>/<owner>/<repo>/raw/...` (there is no
`raw.githubusercontent.com`).

## 3. Comment template

```md
**Screenshots (agent-captured for this PR, not the author's own words)**

| Page | Image |
|---|---|
| Capacity, default | ![capacity](<raw-url>/capacity.png) |
| Capacity, empty state | ![capacity-empty](<raw-url>/capacity-empty.png) |

Demo: ![demo](<raw-url>/demo.gif)
```

Post it, then open the PR and confirm every image renders inline. If not, fall back to drag-and-drop upload in
the comment box and delete the branch.

## 4. Clean up after merge

```sh
git push origin --delete qa-assets/pr-<N>
```

## Caveats

- **Clones fetch it.** A default `git clone`/`git fetch` downloads every branch, so the blobs ride along for
everyone until the branch is deleted and the server garbage-collects. It is not checked out by default.
`--single-branch` clones skip it. Delete promptly.
- Anyone with read access sees the files, and in a public repo anyone does. Don't capture secrets or tokens.
- Branch protection or push rules matching `qa-assets/*` can block the push.
- The private-repo and GHES embed URLs are untested here; the render check is mandatory.
- Simplest alternative that leaves nothing in the repo: drag the files into the PR comment box by hand.
14 changes: 14 additions & 0 deletions .claude/skills/playwright-skill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -393,6 +393,7 @@ For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFER
- **Parameterize URLs** - Put detected/provided URL in a `TARGET_URL` constant at the top of every script
- **DEFAULT: Visible browser** - Always use `headless: false` unless user explicitly asks for headless mode
- **Headless mode** - Only use `headless: true` when user specifically requests "headless" or "background" execution
- **GPU acceleration** - Headed Chromium uses the GPU by default. Playwright's default headless mode (the headless shell) renders in software (SwiftShader), so for headless runs that need real GPU (WebGL, canvas, perf timing) launch with `channel: 'chromium'` (new headless) or add `args: ['--use-angle=metal', '--enable-gpu', '--ignore-gpu-blocklist']` (macOS; use `--use-angle=gl`/`vulkan` per platform). Don't pass `--disable-gpu` unless Chrome's GPU process crashes on that machine. Verify with CDP: `const { gpu } = await (await browser.newBrowserCDPSession()).send('SystemInfo.getInfo'); console.log(gpu.devices, gpu.featureStatus)` and look for `gpu_compositing: "enabled"` and a real device instead of SwiftShader (checked on Apple Silicon macOS: headed and `channel: 'chromium'` both report the Metal device; the default headless shell reports SwiftShader)
- **Slow down:** Use `slowMo: 100` to make actions visible and easier to follow
- **Wait strategies:** Use `waitForURL`, `waitForSelector`, `waitForLoadState` instead of fixed timeouts
- **Error handling:** Always use try-catch for robust automation
Expand All @@ -412,6 +413,19 @@ Ensure running from skill directory via `run.js` wrapper
**Browser doesn't open:**
Check `headless: false` and ensure display available

**Headed window renders only part of the page:**
A fixed `viewport` (or `setViewportSize`) larger than the actual window clips what the user sees. For
visible, user-driven sessions launch with `viewport: null` and `args: ['--start-maximized']` so the page
follows the window size (verified: switching from `viewport: { width: 1600, height: 1000 }` to this
rendered the full page). Keep explicit viewports for headless or screenshot-at-size runs.

**Page behind SSO / login you can't script:**
Use `chromium.launchPersistentContext(profileDir, { headless: false, viewport: null, args: ['--start-maximized'] })`
with a private profile dir (`mkdir -m 700`), let the user sign in once in the window, and poll `page.url()`
until the app URL is reached before measuring. Reuse the same profile on later runs. To record traffic add
`recordHar: { path, content: 'omit' }` (keeps sizes/timings, drops bodies); the HAR still contains auth
headers, so keep it local and never print header values.

**Element not found:**
Add wait: `await page.waitForSelector('.element', { timeout: 10000 })`

Expand Down
25 changes: 15 additions & 10 deletions .claude/skills/sdd/skills/6-verify/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,19 +220,24 @@ with the unresolved list. Do not proceed to <next step>.
### Layer 2 — Architecture & Design Quality (always two agents, regardless of technology)

**Step 0: kibitzer mechanical pre-pass (optional, degrades gracefully)**
- If an MCP connection to `kibitzer` is available and the repo has a `.claude/inspect.json`:
call its `architecture_assessment` tool scoped (via `scope`) to the packages/modules
touched by the diff. If MCP isn't connected but `kibitzer` is on `PATH`, use the CLI
equivalent instead: `kibitzer run <touched-dir> --trigger batch`. This is a mechanical
pre-pass, not a replacement for the architecture-review agent below — it covers what's
cheaply checkable (import cycles, layering violations, coupling thresholds, a Mermaid
dependency diagram via MCP, plus — if `.claude/inspect.json` declares
- `.claude/inspect.json` is NOT required — kibitzer's built-in checks (import cycles,
layering violations, coupling thresholds) run against any repo out of the box. The file
only adds optional custom rules on top (`architecture.components`/`dependency_rules`/
`content_rules`/`naming_rules`) — treat its absence as "no custom rules," not "kibitzer
unavailable."
- If an MCP connection to `kibitzer` is available: call its `architecture_assessment` tool
scoped (via `scope`) to the packages/modules touched by the diff. If MCP isn't connected
but `kibitzer` is on `PATH`, use the CLI equivalent instead: `kibitzer run <touched-dir>
--trigger batch`. This is a mechanical pre-pass, not a replacement for the
architecture-review agent below — it covers what's cheaply checkable (import cycles,
layering violations, coupling thresholds, a Mermaid dependency diagram via MCP, plus —
if `.claude/inspect.json` exists and declares
`architecture.components`/`dependency_rules`/`content_rules`/`naming_rules` — cross-component
dependency, content, and naming-convention violations), not qualitative judgment (SOLID,
testability, over-engineering).
- If neither is reachable, or the repo has no `.claude/inspect.json`: skip this step
silently and proceed straight to the architecture-review agent with no pre-pass context.
Phase 6 must never fail or stall because kibitzer isn't set up.
- If kibitzer is neither MCP-connected nor on `PATH`: skip this step silently and proceed
straight to the architecture-review agent with no pre-pass context. Phase 6 must never
fail or stall because kibitzer isn't installed.
- If it returns findings: pass its raw output (findings text + Mermaid diagram, if any) into
the architecture-review agent's prompt below as grounding context.

Expand Down
Loading
Loading