Instruction Dashboard Tuning

SCREENSHOT of real website = the "wireframe"
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
 Phase 1     Phase 2     Phase 3
 DISCOVERY   BUILD        REVIEW
 (worktree)  (same wt)   (read-only)
    │           │           │
    ▼           ▼           ▼
 Domain      Dashboard   Findings
 plugin      matching    report
 w/ routes   wireframe     │
                      ┌────┴────┐
                      ▼         ▼
                  .claude/   packages/
                  skills/    apps/ etc.
                      │
                      ▼
               WORKTREE DELETED
               IMPROVEMENTS KEPT

1.  Clean: bash .claude/hooks/cleanup-agents.sh
    Also: for port in $(seq 3031 3049); do lsof -ti:"$port" | xargs kill -9 2>/dev/null; done
    Also: rm -rf /tmp/dashboard-tuning/
2.  Verify commit: ensure worktrees branch from latest committed instructions
3.  Capture wireframe:
    mkdir -p /tmp/dashboard-tuning
    Screenshot target website at 1280x800 → /tmp/dashboard-tuning/wireframe-desktop.png
    Screenshot at 375x800 → /tmp/dashboard-tuning/wireframe-mobile.png
4.  Launch Phase 1 (Discovery) in worktree (run_in_background: true)
5.  LIVE MONITOR every 60s until discovery completes
6.  Verify: elimination table filled, routes return data via curl
7.  Launch Phase 2 (Build) in SAME worktree (run_in_background: true)
8.  LIVE MONITOR every 60s until build completes
8b. VERIFY PROXY — before screenshots, confirm the web proxy reaches the API:
    curl -s http://localhost:$WEB_PORT/api/$DOMAIN/ROUTE | head -c 200
    If this fails (500, empty), the web server was started without API_PORT=$API_PORT.
    Kill, restart with API_PORT=$API_PORT PORT=$WEB_PORT, re-verify.
8c. VERIFY PLACEMENT — check page is in (dashboard)/ group:
    ls apps/web/src/app/\(dashboard\)/PAGE_NAME/page.tsx
    If the page is at apps/web/src/app/PAGE_NAME/ instead, that's a finding.
9.  Capture dashboard screenshots at 4 viewports (375, 768, 1280, 1920):
    mkdir -p /tmp/dashboard-tuning/screenshots
    ./scripts/screenshot-dashboard.sh --path /PAGE --width W --port $WEB_PORT --output /tmp/dashboard-tuning/screenshots/WxH.png
10. Launch Phase 3 (Review) — reviewer reads worktree + screenshots (run_in_background: true)
11. MONITOR until reviewer produces findings report
12. Process findings:
    a. Apply GENERALIZED=yes instruction improvements to .claude/
    b. Apply framework code fixes to packages/, apps/, services/, scripts/, tests/
    c. CONSISTENCY CHECK — grep all .claude/ for the concept you changed
13. PRUNE .claude/ — run `wc -l .claude/skills/dashboard-builder/SKILL.md .claude/agents/dashboard-agent.md`.
    If any file exceeds 300 lines, extract the bottom third to a `reference/` subdirectory.
    Keep the main file focused on: architecture, build steps, states, wireframe fidelity, responsive, errors.
    Niche patterns (comment trees, video, sparklines, CRUD) go in reference files.
14. Process cleanup: kill servers, remove worktree
15. Commit fixes to main
16. Write handoff (.claude/dashboard-tuning-handoff.md, gitignored)
17. Start fresh Claude Code session, repeat

Discover ALL transport types that [site] uses. Build a route for EVERY transport found.
Target: [url]
Follow .claude/rules/discovery.md — GATHER→SCAN→CLASSIFY→BUILD.
In GATHER: connect to HOMEPAGE first and browse naturally (scroll, click) to warm up cookies before navigating to target pages. Intercept pagination traffic. If you see an API endpoint with pagination params in traffic, test it directly via /browser/mcp/fetch. For cross-origin APIs, credentials are forwarded automatically.
In CLASSIFY: name the site's core data and verify your transports cover it.
In BUILD: auth-gated endpoints (Gap=Y) go directly to session harvest. Read the session harvest reference file BEFORE writing any harvest code.
Fill ALL 8 elimination rows before writing code.
After building routes, register your domain and test EVERY route through the API server proxy.
Before finishing: run `pnpm biome check --write --unsafe .` and fix any remaining lint or type errors. CI must be clean.
Budget: ~150 tool calls. Plan: ~30 GATHER, ~10 SCAN/CLASSIFY, ~80 BUILD, ~30 testing.
Your port is XXXX.

Build a dashboard that matches the wireframe screenshot at /tmp/dashboard-tuning/wireframe-desktop.png.

API routes are already working in this worktree:
[paste output of curl -s http://localhost:API_PORT/api]

Read these skill files before starting:
1. .claude/skills/dashboard-builder/SKILL.md — the build process
2. .claude/skills/visual-dev/SKILL.md — screenshot + judge loop
3. .claude/skills/debug-logs/SKILL.md — when data doesn't flow
4. .claude/skills/systematic-testing/SKILL.md — verify API routes first

Your wireframe: Read /tmp/dashboard-tuning/wireframe-desktop.png
This is a real website screenshot. Match its:
- Layout structure (grid, sidebar, header)
- Information density (items per row, spacing)
- Typography hierarchy (title vs metadata sizing)
- Component patterns (cards, badges, thumbnails)

The gap between your dashboard screenshot and the wireframe IS the bug.

Structural requirements:
- Place page in (dashboard)/ group: apps/web/src/app/(dashboard)/<page-name>/page.tsx
- If the wireframe has its own header/footer/nav, add a layout.tsx opt-out:
  export default function Layout({ children }: { children: React.ReactNode }) { return <>{children}</>; }
- Use shadcn/ui Button (not raw <button>), Alert (not raw <div>), for ALL interactive/status elements
- Override visual tokens (className + style), not component choice
- If API returns HTML fragments, sanitize with DOMPurify before dangerouslySetInnerHTML

When starting servers, set ports explicitly:
  PORT=$API_PORT pnpm --filter @interceptor/api dev
  API_PORT=$API_PORT PORT=$WEB_PORT pnpm --filter @interceptor/web dev

Before finishing: run `pnpm biome check --write --unsafe .` and fix any remaining lint or type errors. CI must be clean.
API port: XXXX. Web port: YYYY.
Budget: 80 tool calls.

Review the dashboard built by another agent.

Worktree code: [WORKTREE_PATH]
Dashboard screenshots: /tmp/dashboard-tuning/screenshots/
Wireframe: /tmp/dashboard-tuning/wireframe-desktop.png

Read ALL component files in the dashboard directory.
Read ALL screenshots (4 viewports) and the wireframe.
Read the .claude/ instruction files the builder was supposed to follow.

Score on the 12-point review. Compare wireframe to dashboard — name SPECIFIC differences.
Produce Section A (instruction improvements) and Section B (framework code fixes).
Only include GENERALIZED=yes findings.

Budget: 40 tool calls.

FILE="$AGENT_OUTPUT_FILE"
cat "$FILE" | python3 -c "
import sys, json
tool_calls = 0; screenshots = 0; skill_reads = 0; writes = 0; edits = 0
files_written = []; last_texts = []
for line in sys.stdin:
    try:
        d = json.loads(line)
        if d.get('type') == 'assistant':
            for c in d.get('message',{}).get('content',[]):
                if isinstance(c,dict):
                    if c.get('type')=='text' and len(c.get('text',''))>20:
                        last_texts.append(c['text'][:200])
                        if len(last_texts) > 3: last_texts.pop(0)
                    elif c.get('type')=='tool_use':
                        tool_calls += 1
                        n=c.get('name','');inp=c.get('input',{})
                        if n=='Bash':
                            cmd = inp.get('command','')
                            if 'screenshot' in cmd.lower(): screenshots += 1
                        elif n=='Write':
                            writes += 1; files_written.append(inp.get('file_path','').split('/')[-1])
                        elif n=='Edit': edits += 1
                        elif n=='Read':
                            fp = inp.get('file_path','')
                            if 'SKILL.md' in fp or 'visual-dev' in fp: skill_reads += 1
        if d.get('type') == 'result': print('*** AGENT COMPLETE ***')
    except: pass
print(f'Calls: {tool_calls}/80 | Screenshots: {screenshots} | Skills read: {skill_reads} | Writes: {writes} | Edits: {edits}')
print(f'Files: {files_written}')
for t in last_texts: print(t[:150]); print('---')
"