App

App Builder

⚠️💣 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 "Phase 0: Classify."

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 all skills that access external websites.

Turn a plain-language description into a working application with domain plugins and dashboard UI.

The developer says WHAT. This skill figures out HOW — interactively.

Phase 0: Classify

Before anything else, determine what the developer needs:

Ask: Is this a full app (API + dashboard), or API only (domain plugin with routes, no frontend)?

• API only: Phases 1-3 only. Deliver working proxy routes.
• Full app: All 5 phases. API first, then dashboard.

Phase 1: Understand (interactive)

Have a conversation with the developer. Ask these questions — skip any already answered:

Type

App with dashboard, or API only?

Sites

Which website(s)? Can you give me a specific URL with the data you want? Example: "example.com — here's a page with 400+ listings: [url]"

A specific URL is 10x more valuable than a site name. It tells us the page structure, item count, and exactly where to look.

Data

What data do you need? Be specific about fields. Example: "ticket listings with section, row, seat, price" / "job postings with title, company, salary, location"

Completeness

All results (full pagination) or just the first page?

Matching (multi-site only)

How should I match the same entity across sites? Example: "by venue + date" / "by job title + company"

View (full app only)

What should the dashboard show? Example: "side-by-side price comparison" / "timeline" / "search with filters"

Route (full app only)

Dashboard URL path? (default: based on the domain name)

Do not proceed until the developer answers.

Phase 2: Explore & Confirm

For each site, explore it together with the developer before launching any build work.

2a. Connect browser and explore.

./scripts/connect-browser.sh --profile <domain> --url <homepage> --port 3001

Navigate to the URLs the developer provided. Check traffic, count items, identify APIs.

2b. Report findings to the developer:

Here's what I found on [site]:

• [N] traffic entries: [list key endpoints]
• Page has [N] items with [pagination type]
• Embedded data: [yes/no, what framework]
• API endpoints: [list with response shapes]

Does this match what you expect? Anything I should look at more closely?

2c. Developer confirms or redirects. They might say "no, the ticket data loads when you click 'View Listings'" or "try searching for X instead." This saves the agent from guessing.

2d. Write the spec at prompts/.app-spec.md with everything learned:

# App Spec: [name]

## Type: [app / api-only]

## Sites
### site1.com
- Target URL: [specific URL developer provided]
- Transport: [what we found — embedded JSON, XHR, GraphQL, etc.]
- Key endpoints: [URLs with methods and response shapes]
- Auth: [public / needs cookies / needs API key]
- Pagination: [type and params]
- Fields needed: [from developer's answer]

## Matching (if multi-site)
[compound key and normalization]

## Dashboard (if full app)
Path: /[route]
Layout: [description]

Phase 3: Build API

Create a branch first:

git checkout -b app/<name>

All app work happens on this branch. Main stays clean.

Follow .claude/rules/discovery.md for the full protocol, but with the advantage of knowing exactly what to look for from Phase 2.

3a. Build the domain plugin — routes, config, interceptor, index. Use the spec from 2d.

3b. Register and test every route through the API proxy:

curl -s http://localhost:3001/api/<domain>/<route> | head -50

3c. Cache real data for dashboard development. Hit every route with representative inputs and save responses:

mkdir -p tmp/cache/<domain>
# Search/list results
curl -s "http://localhost:3001/api/<domain>/search?q=example" > tmp/cache/<domain>/search.json
# Detail page
curl -s "http://localhost:3001/api/<domain>/detail/123" > tmp/cache/<domain>/detail-123.json
# Pagination page 2
curl -s "http://localhost:3001/api/<domain>/search?q=example&page=2" > tmp/cache/<domain>/search-page2.json
# Edge cases: empty results, single result, max results

Cache enough data to build every view in the dashboard without hitting the live API: list views, detail views, empty states, pagination, cross-site matching samples.

3d. Commit checkpoint. The working domain plugin + cached data is a safe checkpoint. If dashboard iterations go sideways, we never lose the API work.

git add domains/<name>/ apps/api/src/register-domains.ts apps/api/package.json
git commit -m "feat: add <domain> domain plugin with <N> routes"

If API only: Done. Show the developer the route list and sample responses.