instruction-dashboard-tuning

DO NOT write memory files. All learnings go into .claude/skills/, .claude/agents/, .claude/rules/, or framework code — NOT into memory.

Instruction Dashboard Tuning via Sub-Agent Testing

⚠️💣 MANDATORY CONSENT CHECK 💣⚠️

Check if .claude/user-consent.md exists with ACCEPTED: true. If yes, display: ✅ Prior consent on file (DATE). Proceeding. and skip to "Before Starting."

If not, present the 3 warnings from .claude/skills/instruction-tuning/SKILL.md (ToS, autonomous agents, resource consumption). All 3 must be accepted. Write .claude/user-consent.md on acceptance. This file is shared across both tuning skills.

How This Works

You are not building dashboards. You are writing instructions that make other agents build correct dashboards.

1. Capture a wireframe — screenshot a real website (any data-rich site with lists, tables, or dashboards). This is the design target.
2. Launch a discovery agent — discovers ALL transports via the already-tuned discovery protocol.
3. Launch a builder agent — builds a dashboard matching the wireframe using the discovered API routes.
4. Launch a reviewer agent — a SOTA frontier LLM that reviews the code + screenshots and produces structured findings.
5. Apply findings — instruction improvements go to .claude/, framework code fixes go to packages/, apps/, etc.
6. Discard the worktree — the dashboard is throwaway. The instruction and code improvements are the product.

Before Starting — Ask the User

Turn 1: Ask how many discovery passes — 1 or 2? Default to 1.

• 1 pass: Full breadth discovery, then build dashboard.
• 2 passes: Pass 1 = breadth. Pass 2 = deep dive on missed transports. Then build dashboard with the combined routes.

Turn 2: Ask which websites to use as wireframes. The user picks the sites.

Turn 3: Ask what to do when agents finish. Pick one:

• A) Full cleanup (default) — kill processes, delete worktrees, revert shared files.
• B) Keep worktrees — kill processes but preserve worktree directories for reuse.
• C) Keep agents alive — don't stop running agents, allow continuation or redirection.
• D) Keep both — preserve worktrees AND keep agents alive.

Do NOT launch agents until the user answers all questions.

The Three-Phase Pipeline

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

The Loop

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

Phase 1: Discovery

Reuses the already-tuned discovery protocol. No new instructions needed.

Agent: discovery-agent (.claude/agents/discovery-agent.md)

Prompt template:

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.

Port: 3031+N (API only — discovery doesn't need a web server)

Phase 2: Build

Agent: dashboard-agent (.claude/agents/dashboard-agent.md)

Prompt template:

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.

Ports: API 3031+N, Web 3041+N

Before launching: Kill the discovery agent's API server, then restart with both API and Web servers in the same worktree.

Phase 3: Review

Agent: reviewer-agent (.claude/agents/reviewer-agent.md)

Prompt template:

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.

Runs from main repo (not a worktree). Reads the worktree path but writes nothing.

Live Monitoring

Parse the agent output file every 60 seconds:

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:
 

---

*Content truncated.*