--- name: app description: Build a complete application from a short description. Asks the developer clarifying questions, generates data requirements, launches discovery agents, and builds a dashboard. Use when the developer describes what they want to build in plain language — "compare tickets", "track prices", "search jobs across sites". --- # 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.** ```bash ./scripts/connect-browser.sh --profile --url --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: ```markdown # 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:** ```bash git checkout -b app/ ``` 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: ```bash curl -s http://localhost:3001/api// | head -50 ``` **3c. Cache real data for dashboard development.** Hit every route with representative inputs and save responses: ```bash mkdir -p tmp/cache/ # Search/list results curl -s "http://localhost:3001/api//search?q=example" > tmp/cache//search.json # Detail page curl -s "http://localhost:3001/api//detail/123" > tmp/cache//detail-123.json # Pagination page 2 curl -s "http://localhost:3001/api//search?q=example&page=2" > tmp/cache//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. ```bash git add domains// apps/api/src/register-domains.ts apps/api/package.json git commit -m "feat: add domain plugin with routes" ``` **If API only:** Done. Show the developer the route list and sample responses. ## Phase 4: Dashboard (full app only) Build the dashboard UI against cached data. This decouples UI iteration from API reliability — no browser sessions, no rate limits, no WAF while tweaking CSS. **4a. Scaffold the page** at `apps/web/app//page.tsx`. **4b. Wire up data fetching.** Start with cached data to verify layout, then switch to live API calls. **4c. Iterate with the developer.** Use `visual-dev` skill — screenshot after each change, show the developer, get feedback, fix, re-screenshot. Don't build blind. **4d. Use `debug-logs` skill** when data isn't flowing: add targeted DEBUG logs at each layer (route handler → API fetch → response parse → component render), read output, fix, clean up. **4e. Handle multi-source merging** if applicable — match entities across sites using the key from the spec, show source badges, highlight differences. ## Phase 5: Verify (full app only) Bottom-up validation using `systematic-testing` skill: 1. Curl every API route — confirm real data 2. Screenshot the dashboard: empty, loading, populated, error, mobile (375px) 3. Walk the full user journey: search → results → detail → compare 4. Test with 3 different inputs 5. Show the developer screenshots and sample data **Only hand off when verified working on localhost:3000.** ## Python Bridge The project includes a Python worker at `services/python/` that can be called from route handlers or dashboard API routes. Use it for anything that's better in Python than TypeScript: **NLP & Text Analysis:** - Sentiment analysis on reviews, news headlines, social posts (NLTK, TextBlob, transformers) - Named entity recognition — extract people, companies, locations from text - Text summarization — condense long descriptions or reviews - Keyword extraction — pull topics from listings or job postings **Data Science:** - Fuzzy entity matching across sites (fuzzywuzzy, rapidfuzz, scikit-learn cosine similarity) - Statistical outlier detection — flag unusually priced listings - Clustering — group similar items (KMeans, DBSCAN on feature vectors) - Trend analysis — price changes over time, moving averages **Machine Learning:** - Classification — categorize items, detect spam/duplicates - Regression — predict prices, estimate value scores - Feature engineering — normalize and compare across different site schemas **When to use the Python bridge:** - The developer's spec mentions sentiment, scoring, matching, analysis, or ML - Cross-site entity deduplication (Python fuzzy matching >> JS string comparison) - Any computation where numpy/pandas/scikit-learn is the natural tool **How:** Route handlers call the Python bridge via IPC. The bridge runs as a sidecar service. See `services/python/` for the interface. ## Rules - The developer's domain knowledge is the most valuable input. Ask for it. Don't guess. - Commit after Phase 3. The API is the foundation — protect it. - Cache real data. Dashboard iterations should never depend on a live browser session. - If a site requires browser session for some routes, say so in the spec. Don't hide limitations. - The spec file is temporary. The domain plugin, cached data, and dashboard are the product.