Project Builder

Phase 0: SKILL DISCOVERY & REQUIRED READING

⚠️ CRITICAL — UI Design Quality Gate: If the project produces ANY visual HTML output (dashboard, web app, landing page, portfolio, any page the user will see), you MUST read_file the ui-design skill's SKILL.md and follow it BEFORE writing any HTML/CSS. This is not optional. project-builder handles engineering; ui-design handles visual quality (and tells you when to reach for a component library like shadcn/ui, HeroUI, or coss ui instead of hand-writing). Skipping ui-design produces generic AI slop.

A. Pick the sources and tools. For research and API documentation, use web search. For live market numbers or external actions, reuse the relevant installed skill. Read its SKILL.md before use; search missing skills with auto_install=false and install only with user approval. Write custom API code only after checking that no suitable skill covers the operation; verify endpoints and response shapes against current official documentation.

B. Read the platform rules for what the project touches. These rules live in references (not in your system prompt) so you must read_file them before writing code. Skipping this is the #1 cause of 401s, broken paths, and "worked locally, fails in preview" bugs.

Phase 1: DESIGN

Translate vague requests into concrete specs. If intent is ambiguous, ask ONE question.

Architecture decision tree:

Periodic alerts/reports?  → Scheduled Task
Live visual interface?    → Preview Server (dashboard)
One-time analysis?        → Inline (no build needed)
Reusable tool?            → Script in workspace

For medium+ projects, present to user BEFORE writing code:

1. Data flow — sources → processing → output
2. Architecture choice and why
3. Cost estimate — (cost/run) × frequency × 30 = monthly
4. Known limitations

UI Design Gate (required, blocking — for visual projects): If the architecture choice is Preview Server or any project that outputs HTML the user will see:

1. read_file the ui-design skill's SKILL.md now (if you haven't already in this session) and pick a track (hand-built vs component library).
2. For hand-built UI, run the Design Dials (in ui-design's references/design-process.md) to determine Surface, Accent, Typography, and Aesthetic Family.
3. Include the Design Dials output line in your phase plan below.

If you skip this step, the UI will look like generic AI output. This gate is blocking — do not proceed to Phase 2 without completing it.

Design gate: Present a short phase plan for multi-stage work. If the user has already authorized a clear, reversible implementation, proceed without asking for the same approval again. Ask only when scope is genuinely ambiguous, a material cost needs approval, or the next action is irreversible/external (publish, send, trade, delete). An active Plan Mode remains read-only until the user approves execution.

Phase 1.5: SCAFFOLD (mandatory for shareable projects)

After design is confirmed, before writing any code, scaffold the project under the standard layout. This makes the project shareable via community-publish skill from day one — no migration later.

Standard project location: output/projects/{slug}/

output/projects/{slug}/
├── project.yaml          # name, version (start 0.1.0), type, description, license, entry, env_required
├── PROJECT.md            # 4 required sections: What / Required env / How to start / Outputs / Troubleshooting
├── .env.example          # every env var the code reads, with placeholder values
├── .gitignore            # at minimum: .env, *.key, *.pem, __pycache__, node_modules
└── src/                  # all code lives here, NOT scattered
    ├── run.py            # type=task — first line MUST be: # -*- task-system: v3 -*-
    ├── server.py         # type=service
    ├── main.py           # type=script
    └── index.html / app.py + frontend  # type=preview

Project type → entry mapping:

Skip scaffold only when:

• Pure inline analysis with no persistent code
• Modifying an existing output/projects/... project (keep its layout)
• User explicitly says "just throw a script in /tmp" or similar

During Phase 2 BUILD, maintain the scaffold:

• Every new env var read by code → add to .env.example in same edit
• Every behavioral change → update PROJECT.md
• Never write code outside src/ (configs, fixtures: project root or src/data/)

Why this matters: Projects already in standard layout publish in one command. Projects scattered across tasks/, output/scripts/, dashboards/, etc. need tidy_project() migration before they can be shared, and the user often doesn't want to rebuild PROJECT.md from memory.

For existing scattered code: call community-publish skill → tidy_project(any_dir) to reorganize before publishing.

API cost & rate limits: All external API calls go through sc-proxy, which bills per request and enforces rate limits. Before designing, read `config/context/references/sc-proxy.md` for pricing table and limits.

• Estimate cost: credits_per_request × requests_per_run × runs_per_day × 30
• Respect rate limits: e.g. CoinGecko 60 req/min — a task polling 10 coins every minute is fine; 100 coins is not
• Prefer batch endpoints over N single calls (e.g. coin_price with multiple ids vs N separate calls)
• Pure script tasks (no API): ~0 credits/run
• LLM cost warning: high-end models can exceed $0.10 per single call. Pricing varies dramatically by model tier; expensive models can be 100x+ the cost of budget models for the same workflow.
• Model-aware estimate required: break LLM cost down by model (model_price_per_call × expected_calls_per_run × runs_per_day × 30) instead of using a single generic number.
• Dashboard auto-refresh costs credits — default to manual refresh unless user asks otherwise
• Spending protection: if projected monthly LLM cost is high, explicitly ask whether to enforce per-caller limits before implementation.
• Per-caller tracking (required): every proxied request must include SC-CALLER-ID (e.g. job:{JOB_ID}, preview:{preview_id}, chat:{thread_id}) so usage can be traced and capped. Details in config/context/references/sc-proxy.md § Caller Credit Limit

Data reliability: Native tools > proxied APIs > direct requests > web scraping > LLM numbers (never). Iron rule: Scripts fetch data. LLMs analyze text. Final output = script variables + LLM prose.

Task scripts can import skill functions directly:

from core.skill_tools import coingecko, coinglass  # auto-discovers skills/*/exports.py
prices = coingecko.coin_price(coin_ids=["bitcoin"], timestamps=["now"])

Tool names = SKILL.md frontmatter tools: list. See build-patterns.md § Using Skill Functions.

Phase 2: BUILD

Every piece follows this cycle: