add_context_repo
ChatGPTLink a GitHub repository to this project so agents can understand the codebase. A Code Wiki (structured architecture docs) will be generated automatically. This does NOT bring the code into the project — to import a repository as a new, runnable project, use import_github_repo. IMPORTANT: Always ask the user for confirmation before linking a repository.
analyze_survey_responses
ChatGPTPull all responses for a survey in this project and return per-question statistics (distributions, averages, top open-text answers). YOU interpret them: write the headline, a 2-paragraph PM-grade narrative, and a confirmed / partially_confirmed / refuted / new_finding verdict against each of your prior hypotheses, into your research run doc. Use this once you've collected at least a handful of responses to a previously-generated survey. Pass surveyId from a prior generate_survey result.
ask_user
ChatGPTThis is the ONLY permitted way to ask the user a question. Ask up to 5 questions in one card; never put questions or response invitations in ordinary chat text. The UI renders a stepper and submits all answers together. Use options for yes/no or short picks. For an open-ended response, omit options or pass an empty array. log_open_question records backlog questions but does not surface them to the user. For one question, still pass questions as a one-item array. When options is present, pass one flat string array such as ["Yes", "No"] — never nest the array. After calling this tool, STOP your turn — the user's answers arrive as a single hidden message on the next turn.
bash
ChatGPTExecute a bash command in the project's REMOTE cloud sandbox (working dir /home/user — the project root). This is NOT the local machine: all coding happens on the ProductOS sandbox, so you can drive a project from any device without a local clone. Full shell semantics: pipes, &&, globs, redirection, git, npm, tsc — anything installed in the sandbox. Synchronous commands time out at 55s: for anything longer (next build, a full test suite, prisma generate) pass background:true to get a jobId back immediately, then call again with that jobId to poll RUNNING/SUCCESS/FAILED/CANCELLED and read its output. File edits made via shell are auto-committed to GitHub like the file tools. Requires project:exec scope.
browser_act
ChatGPTPerform one interaction. Targets are @eN refs from browser_snapshot or CSS selectors. Actions: click, double_click, hover, fill (clear then type), type (append), select (dropdown), check/uncheck, press (a key or combo like 'Enter' or 'Control+a'), scroll, scroll_into_view, wait (for an element, text, or a pause — use before snapshotting an async UI). Re-snapshot afterwards — refs go stale. Requires project:exec scope.
browser_debug
ChatGPTRead the page's debugging state: console output (log/warn/error/info), uncaught JavaScript exceptions, or captured network requests. THIS is how you find out why the app being built misbehaves in the browser — check errors after any flow that should have worked but didn't. Set clear:true to empty a buffer so the next read shows only what happens after this point. Requires project:exec scope.
browser_navigate
ChatGPTNavigate the project sandbox's Chromium to a URL. The app being built is at http://localhost:3000 — reachable ONLY from inside the sandbox, which is why this tool exists rather than fetching the URL yourself. Follow with browser_snapshot to see what is on the page. Shares one browser session with the in-app agents and the user's live Browser panel. Requires project:exec scope.
browser_read
ChatGPTPull content out of the current page: visible text, innerHTML, an input's value, an attribute, the page title, or the current URL. Omit target for whole-page text. Use this rather than a screenshot when you need to READ something. Requires project:exec scope.
browser_screenshot
ChatGPTCapture the page as an image you can actually look at. Use ONLY for genuinely visual questions — layout, spacing, alignment, colour, overflow — or when the user asked to see something. To read content or find elements use browser_snapshot: far cheaper, and it gives you refs to act on. Requires project:exec scope.
browser_snapshot
ChatGPTTHIS is how you see a page: an accessibility tree with @eN refs for the interactive elements, which browser_act then acts on. Prefer it over browser_screenshot — a fraction of the tokens and it gives you refs. Refs go stale after ANY page change, so re-snapshot after every click, fill, or navigation. Requires project:exec scope.
browser_tabs
ChatGPTManage tabs in the shared browser session: list them, open a new one, switch by id/label (t1, t2, …), or close one. Requires project:exec scope.
check_deploy_status
ChatGPTCheck the latest deployment's live Vercel status for this project. Use whenever the user asks 'is it done?', 'what's the status?', 'did the deploy finish?', or asks for the public URL after a prior delegate_to_deploy. By DEFAULT this BLOCKS up to ~3 minutes polling Vercel until the deployment reaches a terminal state (READY/FAILED/CANCELLED) — that is what 'wait for the deploy' means. Pass wait: false for an instant non-blocking snapshot. Returns a structured JSON string.
clone_project
ChatGPTDuplicate an existing project — copies its documents, stage data, settings (framework/template), and project memory into a new project owned by you. The clone gets its own sandbox and Git repo lazily on first open. Requires project:write scope on the source project.
create_project
ChatGPTCreate a new ProductOS project: registers it in the workspace, initializes its Git repository, applies the chosen template, and optionally provisions + boots its sandbox. Returns the project id, repo, and sandbox/preview URLs. IMPORTANT — pick template from what the user actually wants, don't just default to web: a MOBILE app / iOS / Android / React Native / Expo → 'mobile'; a Flutter / Dart app, or a mobile app that must build a real native Android APK → 'flutter'; a marketing/landing/brand/blog/SEO site → 'website'; a web app / dashboard / SaaS → 'web-app'. If the user says 'app' without qualifying and the context is mobile, prefer 'mobile'; if genuinely unsure, ask them. Requires project:write scope and a non-viewer workspace role.
create_skill
ChatGPTSave a reusable playbook (a SKILL.md) into this workspace or project so future agents and teammates can follow it. Use when you've worked out a repeatable procedure worth keeping — team conventions, a deployment ritual, a recurring fix. The skill is immediately usable in this workspace; set submit_to_platform to also offer it to ProductOS admins for publication to every workspace. Requires project:write.
delegate_to_architect
ChatGPTDelegate an architecture task to the Architecture sub-agent. Only valid during the DEFINE stage, after PRD sections are complete. When a section parameter is provided, the sub-agent writes ONLY that one section. When omitted, the sub-agent writes all sections (full mode). Returns a short status string.
delegate_to_deploy
ChatGPTDelegate publish-and-deploy to the Deploy sub-agent. Use this whenever the user asks to publish, deploy, or ship the project. The sub-agent runs next build in the sandbox to verify, pushes to the ProductOS GitHub org, triggers a Vercel deployment, polls for completion, and auto-fixes build errors up to 3 times before asking the user. Available in any stage where Develop has produced files. This tool returns a short status string with the public URL on success — use read_file on /home/user/wiki/agents/deploy/output.md if you want the full deploy log.
delegate_to_design
ChatGPTDelegate a flows/screens design task to the UI/UX sub-agent. Only valid when the current stage is design, and only AFTER the user has explicitly asked for flows or screens (per the design rules). DO NOT use this for brand work — brand guidelines are owned by ProductOS directly via the brand tools (set_brand_identity, generate_brand_palette, generate_font_pairing, generate_vibe_report, generate_mood_board). The sub-agent reads prior-stage artifacts (ideation brief, research findings, PRD) and produces structured design documents in the sandbox. This tool returns a short status string — use read_file to see the actual deliverables.
delegate_to_ideation
ChatGPTDelegate an ideation task (idea exploration, sharpening the concept, logging open questions and assumptions) to the Ideation sub-agent. Only valid when the current stage is ideation. The sub-agent runs autonomously and writes its deliverable to the ideation notes. This tool returns a short status string — use read_file to see the actual brief.
delegate_to_prd
ChatGPTDelegate a PRD task to the PRD sub-agent. Only valid when the current stage is prd. When a section parameter is provided, the sub-agent writes ONLY that one section (per-section mode). When omitted, the sub-agent writes all sections (legacy full mode). This tool returns a short status string.
delegate_to_qa
ChatGPTRun the ProductOS QA Agent against the user's preview URL. It drives a headless browser to test critical flows, capture screenshots, hit backend APIs, and run accessibility and console checks. Its activity streams into this chat as live steps. BLOCKS until the run finishes (~1-5 minutes). Returns the verdict (pass/partial/fail), summary, and findings count. If verdict is fail, consider following up with delegate_to_engineer to fix the critical issues it found.
delegate_to_research
ChatGPTDelegate a research task (competitor audit, market signals, user validation, technical feasibility, regulatory scan) to the Research sub-agent. Only valid when the current stage is research. The sub-agent uses Exa semantic search (fast/auto/deep modes) to gather sourced findings and writes a cumulative research brief. This tool returns a short status string — use read_file to see the actual brief and findings list.
delete_file
ChatGPTDelete a file or directory from the project sandbox. Pass recursive:true to delete a non-empty directory. The project root cannot be deleted. Requires project:write scope.
delete_project
ChatGPTPermanently delete a ProductOS project — its sandbox and volume are reaped, project storage is cleaned up, the cross-surface registry entry is tombstoned, and the project row is removed. This cannot be undone. Requires project:write scope and workspace permission to manage the project.
edit_file
ChatGPTModify an existing file by replacing exact strings — the right tool for surgical code edits and refactors without rewriting the whole file. Edits apply in order; each oldString must appear exactly once unless replaceAll is set. Requires project:write scope.
estimate_infrastructure_cost
ChatGPTEstimate infrastructure costs for different deployment options. Compares serverless vs container vs VM strategies at multiple scale tiers. Use this when writing the Infrastructure & Deployment architecture section. The result is formatted as a markdown comparison table that you should include in the architecture section body.
exa_fetch
ChatGPTFetch extracted text for a list of URLs you already have (from a prior exa_search or from the user). Each page is capped at 4000 characters to keep token usage sane.
exa_search
ChatGPTSemantic web search via Exa. Use fast for quick lookups, auto for most queries, deep for landscape/synthesis (4-15s). Returns a compact list of { title, url, summary } — call exa_fetch for full page text on results worth a deeper look.
find_files
ChatGPTFind files by filename glob across the project sandbox (build artifacts pruned, capped at 500 results). Matches the file NAME, e.g. 'page.tsx', '.config.', 'tailwind.config.*'. To search file CONTENTS use search_files. Requires project:read scope.
generate_brand_palette
ChatGPTStep 2 — generate a psychologically-grounded color palette and save it to the Brand tab. Pass keywords derived from the vibe/target audience (e.g. 'trustworthy', 'energetic'). If the user hasn't supplied keywords, pick 2–4 yourself from the recalled facts.
generate_font_pairing
ChatGPTStep 3 — generate a font pairing (primary + secondary + body) and save it to the Brand tab. brandVibe is a short descriptor like 'modern', 'editorial', 'playful'. Grounds choices in readability and brand personality.
generate_mood_board
ChatGPTGenerate a mood board image summarizing the brand's visual direction. Should be called ONLY after the design system has been generated — the image model grounds itself against DESIGN.md + the preview HTML so the board reflects the locked design language, not just the raw palette/fonts. Requires color palette and typography to already exist. Normally the user triggers this themselves from the Mood Board sub-tab inside the Design System; only call it programmatically if explicitly asked.
generate_vibe_report
ChatGPTStep 4 — generate a Brand Vibe Report covering brand essence, ideal client, founder story, touchpoints. Requires color palette and typography to already exist on the Brand tab.
get_brand_guidelines
ChatGPTRead the current Brand Guidelines state from the Design tab. Use this on every turn BEFORE asking the user or generating anything — the user may have filled fields directly in the form. Returns a summary of which steps are complete plus the mode and active step.
get_decision
ChatGPTRead the full body of one logged decision (PRD section, page) from this project's sandbox wiki. Pass an id from list_decisions (a wiki-relative path like 'agents/prd/sections/overview.md'). Returns markdown with title + stage + body. Live data — no DB lag.
get_deploy_logs
ChatGPTReturn build AND runtime logs for a deployment. Build logs explain why a deploy failed to compile; runtime logs explain why a deployed route returns 500 (missing env var, Prisma init failure, DB unreachable). Falls back to fetching live from Vercel when nothing was captured at deploy time. Secrets and connection strings are redacted. Defaults to the latest deployment. Requires project:read scope.
get_deploy_status
ChatGPTCheck a deployment's status for this project. Returns status (QUEUED/PUSHING/DEPLOYING/READY/DEGRADED/FAILED/CANCELLED), the exact source commit deployed, the deployment URL, GitHub repo info, and the full post-deploy verification report — including any routes that failed their release check with expected vs actual HTTP status. DEGRADED means the build succeeded but verification failed, so it was not promoted to production. Defaults to the latest deployment.
get_eas_build_logs
ChatGPTReturn the real failure logs for a mobile EAS build — the 'Run gradlew' (Android) / Xcode (iOS) phase output, plus the extracted cause. Use this whenever a Play Store / App Store build fails, ESPECIALLY when the status says "unknown error — see logs for the Run gradlew phase": that message is EAS's classifier giving up, and this tool fetches what it points at. Defaults to the project's most recent mobile build. Pass grep to filter (e.g. 'Execution failed|e: file://'). Requires project:read scope.
get_product_context
ChatGPTOrient in ProductOS Product mode — a Product groups several platform projects (web / mobile / website) that share ONE frozen spec, one database, and one orchestrator agent. Call this FIRST whenever the project you're working on might belong to a Product: it lists the sibling surfaces, whether the shared contract is frozen (and at which version), and what the ProductOS Agent is doing. With no arguments it resolves the Product owning the connection's active project, or — if that project is standalone — lists every Product this connection can reach. Follow up with read_shared_context (the contract each surface must satisfy) and product_agent (the main agent). Requires project:read.
get_project_context
ChatGPTReturns a markdown summary of this ProductOS project: name, current stage, overview, PRD, research, design notes. Reads live wiki files from the project's sandbox — always the latest, no staleness. Call this first when the user wants you to work in their ProductOS project. v1 read-only.
get_project_metadata
ChatGPTQuery a project's configuration and live GitHub repository permissions in one call: name, stage, project type + framework template, GitHub repo/branch and read/push access, workspace, database/storage state, and sandbox identity. Checks the project's bound repository independently of personal repository discovery; a list_available_repos warning does not imply this project is blocked. Database metadata recognizes configured URLs but does not test database connection health. Requires project:read scope.
get_recent_activity
ChatGPTReturns a dated summary of recent project activity from canonical wiki memory and sub-agent outputs. Use it on demand when the request depends on earlier work; it is not a prerequisite for starting a turn.
get_sandbox_logs
ChatGPTTail the dev-server log for a project's sandbox — use to debug build errors, runtime crashes, or a preview that won't load. Returns the last N lines (default 200) of the type-aware log file. Requires project:read scope.
get_sandbox_status
ChatGPTReport a project's sandbox health: instance status (DEPLOYED/…), whether the dev server is responding, whether it's currently compiling, last-active time, and the sandbox id. Requires project:read scope.
get_sandbox_urls
ChatGPTReturn the live preview URL for a project's running sandbox (and the Expo tunnel URL for mobile projects). Use to view or share the running app. If the sandbox isn't running, start it first with start_sandbox / open_project. Requires project:read scope.
get_skill
ChatGPTRead the full instructions for one skill by slug (get slugs from list_skills). Returns the complete SKILL.md — a step-by-step playbook you should then FOLLOW for the current task, not summarise. Use this before improvising on any task a skill already covers.
get_stage
ChatGPTRead the project's current stage from /home/user/wiki/stage.md. Use this if you're unsure whether a recent set_stage succeeded or you need to confirm state before delegating.
get_usage
ChatGPTShow the user's ProductOS credits: how many are left, when they refresh, where credits went recently (agent runs, sandbox time, search, generation), the most recent costly actions, and the Free plan's limits (projects, databases; publishing needs a paid plan). Call this when the user asks about credits, usage, costs or limits, or after a call was refused for credits. Uses no credits.
git_sync
ChatGPTGit operations on the project sandbox. action='status' shows the working tree + recent commits (project:read). action='commit-push' commits the live sandbox state and pushes it to the project's GitHub repo via the durable commit pipeline — file writes via MCP already auto-commit, so use this to force an immediate sync point (project:write). action='pull' pulls the latest from the project's GitHub repo INTO the sandbox — it first backs up the current tree to S3 so the pull is undoable, and refuses while an agent turn is mid-write (project:write).
grep_design_brief
ChatGPTSearch for specific text or sections within the current DESIGN.md. Returns matching lines with line numbers and surrounding context. Use this before patch_design_brief to find the exact text you want to edit — avoids loading or rewriting the full document.
import_github_repo
ChatGPTImport an existing GitHub repository (an existing codebase) as a new ProductOS project: downloads the code into a live sandbox, detects the stack (Next.js, Vite, Astro, Expo, Flutter, Node, Python, PHP, Go, static — anything else runs on a universal image), starts installing dependencies and the dev server, and returns the project id + preview URL. The project stays linked to the repository. Use this — not create_project — when the user wants to work on code they already have on GitHub; add_context_repo only attaches a repo as reference docs to an existing project. The user's GitHub account must be connected to ProductOS; list_available_repos shows the repositories it can read. Importing the same repository and branch again returns the existing project instead of a duplicate. Takes a few minutes on a cold start. Requires project:write scope and a non-viewer workspace role.
list_available_repos
ChatGPTDiscover the user's personal GitHub repositories for import_github_repo or add_context_repo. This is NOT a prerequisite or health check for existing projects: use open_project/start_sandbox or get_project_metadata for those. Returns a repository array when discovery succeeds. If discovery is unavailable, returns a scoped warning and independently verified access to the selected project's bound repository. Never infer that all project operations are blocked from a discovery warning.
list_decisions
ChatGPTList the design / PRD / research decisions logged in this ProductOS project, read straight from the live sandbox wiki (no DB lag). Returns a JSON array with id (wiki-relative path), title, type, position, updatedAt for each. v1 returns PRD section files and pages; structured alternatives / rationale fields ship in v1.1.
list_files
ChatGPTList files and subdirectories in one directory of the project sandbox (non-recursive). Build artifacts (node_modules, .git, .next, dist, build) are hidden. For a full recursive tree use read_project_structure. Requires project:read scope.
list_organizations
ChatGPTList the ProductOS organizations (workspaces) this MCP connection can access, with your role in each. Use list_projects to see the projects inside them. Requires project:read scope.
list_projects
ChatGPTList the ProductOS projects this MCP connection can access, with each project's access level (READ / WRITE / FULL_DEV), current stage, and id. Projects that are platforms of a multi-platform Product are grouped under it — use get_product_context for that Product's shared spec and orchestrator agent. The active project is marked — switch it with open_project, or pass projectId to any file/sandbox tool to target another project directly.
list_skills
ChatGPTList the reusable agent skills (playbooks) available to this connection — platform skills shipped by ProductOS plus any this workspace or project defines. Each entry is a slug + description; call get_skill with a slug to read the full instructions. CHECK THIS FIRST when a task sounds like a repeatable workflow (cloning a website, an SEO pass, a design-system import) — following an existing skill beats improvising.
load_constraints
ChatGPTLoad all active project constraints (legacy APIs, compliance requirements, tech debt, security, performance, infrastructure). ALWAYS call this before writing PRD sections, architecture docs, or making technical decisions. Constraints are structured inputs from the project owner that MUST influence your output.
log_assumption
ChatGPTRecord ideation assumptions. Pass every new assumption in ONE assumptions array so the file is read and written once. The legacy singular shape remains supported.
log_competitor
ChatGPTRecord ALL competitors discovered this turn in a single call. Pass every competitor as an entry in the competitors array — do NOT call this tool per competitor.
log_finding
ChatGPTRecord ALL validated research findings for this turn in a single call. Pass every finding as an entry in the findings array — do NOT call this tool multiple times in the same turn.
log_open_question
ChatGPTRecord open ideation questions. Pass every new question in ONE questions array so the file is read and written once. The legacy singular question + why shape remains supported.
log_source
ChatGPTRecord ALL worthwhile source URLs for this turn in a single call. Pass every source as an entry in the entries array — do NOT call this tool per URL.
manage_dependencies
ChatGPTAdd, remove, or install npm dependencies in the project sandbox. 'add' installs the given packages, 'remove' uninstalls them, 'install' installs everything in package.json. Package names are validated. Requires project:exec scope.
manage_env_vars
ChatGPTList, set, or delete a project's environment variables (the Secret Manager backing the sandbox's .env). 'list' returns key names only — values are encrypted and never exposed. 'set'/'delete' also sync the sandbox .env so the running app picks the change up. DATABASE_URL is reserved (use provision_database). Requires project:write scope.
manage_product
ChatGPTCreate and steer a ProductOS Product (several platform projects — web / mobile / website — sharing one frozen spec, one database and one orchestrator agent). Actions: 'create' (from a brief + surfaces: provisions the shared database, creates one project per surface, and starts the ProductOS Agent in PLAN MODE — nothing builds until you approve its plan with product_agent); 'add_surface' (add a platform to an existing product and build it against the existing contract); 'sync_spec' (re-freeze the shared contract — this REBUILDS EVERY SURFACE, so confirm with the user); 'resume' (recover a stalled product: backfill missing platform projects, restart a dead orchestrator, re-dispatch dead builds). Every action spends credits. Use create_project instead when the user wants ONE standalone app. Requires project:write.
mobile_publish
ChatGPTThe Expo/EAS pipeline for MOBILE_EXPO projects — app identity → EAS build → App Store / Play Store submission. Use this instead of trigger_deploy for any mobile app (trigger_deploy is the web/Vercel pipeline and will not produce an app). Actions: 'status' (ALWAYS start here — app identity, which store credentials are connected, what can run now, and the in-flight/latest build); 'configure' (set packageName + displayName — required before any build; the package name is permanent once published); 'build' (EAS build producing a downloadable APK/AAB, no store submission and no Google Play account needed — Android only, because iOS binaries are signed during the build); 'submit' (build AND submit to the store — TestFlight for iOS, internal testing track for Play); 'cancel' (stop the in-flight run). Builds take 10–30 minutes: poll 'status', and on failure read get_eas_build_logs for the real cause. Connecting Apple / Google Play is done BY THE USER in the ProductOS app — this tool never accepts store credentials. 'status' needs project:read; the rest need project:write.
move_file
ChatGPTRename or move a file or directory within the project sandbox. Parent directories of the destination are created automatically. Requires project:write scope.
open_project
ChatGPTSwitch this MCP connection's active project and connect to its sandbox — auto-provisioning one (correct template image, state restored from GitHub/volume) when missing. Subsequent file/command tools default to this project. Returns sandbox status and preview URL. Requires project:read (sandbox creation needs project:write).
patch_design_brief
ChatGPTEdit a specific section of the DESIGN.md by replacing exact text in-place — without rewriting the whole file. Much cheaper than write_design_brief for refinements. Use grep_design_brief first to locate the exact text. oldText must match exactly (whitespace included). Updates the sandbox file, compact brief, and DB row.
product_agent
ChatGPTRead and drive the ProductOS Agent — the orchestrator that plans a Product, freezes its shared contract, and dispatches the per-surface builds. It is not a project and can't be reached with the project tools. Actions: 'status' (what it last said, whether it's mid-turn, and — crucially — whether it is parked awaiting plan approval, with the proposed plan); 'approve' (approve the parked plan so the builds start — this SPENDS CREDITS and dispatches real work across every surface, so confirm with the user first); 'answer' (reply to a parked question, or send plan feedback instead of approving — pass message); 'message' (send a new instruction to an idle agent — e.g. 'add a pricing page to web and mirror it on the website'). You share ONE session with the Product page's chat, so the user sees your messages live. 'status' needs project:read; the rest need project:write.
propose_design_plan
ChatGPTShow the user a Design kickoff plan card. Automation covers the first two pieces only — brand & visual direction and the design system. User flows and UI screens are USER-DRIVEN: list them on the plan card as their own user-led steps so the user knows they can drive that part themselves (or ask you to help later). Call this on the FIRST turn of the design stage (right after greeting) — it REPLACES writing the plan as a bullet list in your text reply. DO NOT call delegate_to_design, delegate_to_design_system, or dispatch_to_design_builder on the same turn — wait for the user to approve the plan via the card. The user clicks 'Run plan' to approve, which arrives as a hidden message on the next turn; then you proceed with execution.
propose_develop_plan
ChatGPTShow the user a Develop kickoff plan card with the concrete features/screens you'll build in the develop stage. CRITICAL: The sandbox ALREADY has a pre-built Next.js project — DO NOT include a step like 'Set up the Next.js project structure' or any scaffolding/install work. The plan MUST focus on user-visible feature work (core flows, gameplay, screens, auth, integrations, leaderboards, etc.). Call this on the FIRST turn of the develop stage (right after greeting) — it REPLACES writing the plan as a bullet list in your text reply. DO NOT start building or dispatching any builder tools on the same turn — wait for the user to approve the plan via the card. The user clicks 'Run plan' to approve, which arrives as a hidden message on the next turn; then you proceed with execution.
propose_prd_plan
ChatGPTShow the user a PRD kickoff plan card with the 4 phases you'll run through (read ideation + research context, present PRD template options, confirm the section outline, generate sections one by one). Call this on the FIRST turn of the PRD stage (right after greeting). DO NOT call setup_prd_outline or delegate_to_prd on the same turn — wait for the user to approve the plan via the card. The user clicks 'Run plan' to approve, which arrives as a hidden message on the next turn; then you proceed with Phase 1 (read context, present templates, etc.).
propose_research_plan
ChatGPTShow the user a research plan card with 1-6 concrete research questions you intend to investigate. Default to 3-5, but honor the user when they ask for fewer (e.g. a single focused investigation like 'just the competitor landscape') — a one-step plan is valid. Call this on the FIRST turn of the research stage (right after greeting). DO NOT call delegate_to_research on the same turn — wait for the user to approve the plan via the card. The user clicks 'Run plan' to approve, which arrives as a hidden message on the next turn; then you can delegate with confidence.
propose_stage_transition
ChatGPTSignal to the UI that the current stage is done and the user may advance to the next stage. Renders a 'Move to <stage>' CTA button. Call ONCE per turn when all stage exit criteria are met. When leaving ideation, a user-supplied or explicitly confirmed brand/product name is mandatory; an AI-generated or placeholder name does not count. Does NOT change state — the user clicks to confirm.
provision_database
ChatGPTProvision a Postgres database for Build projects (Neon) and configure the sandbox: DATABASE_URL in .env, Prisma setup, and a db client. Idempotent — reuses an existing URL. For Develop-only projects, set an existing DATABASE_URL with manage_env_vars first; this tool wires Prisma without creating another database. The sandbox must be running. Requires project:write scope.
provision_storage
ChatGPTProvision isolated file storage for the project (an S3 prefix with a project-scoped upload token) and write the PRODUCTOS_STORAGE_* credentials into the sandbox .env. Idempotent — safe to call again. The sandbox must be running. Requires project:write scope.
publish_file
ChatGPTPublish files to the user-visible public folder. Prefer passing a files array in ONE call — do NOT call this tool multiple times. For each file, PREFER sourcePath (an absolute path to an existing sandbox file) over content: the sandbox copies the file in place, which is MUCH faster than re-sending the full body over the network. Legacy single-file shape { stage, fileName, content } is still accepted.
push_to_github
ChatGPTPush the project's sandbox code to its GitHub repository. Dispatches an async job — check progress with get_deploy_status. Requires project:write scope.
qa_log_finding
ChatGPTLog 1-30 QA findings in a single call. ALWAYS batch — do not call this once per finding. Each finding needs severity, type, title, and (recommended) evidence with the route + screenshot URL.
qa_write_qa_report
ChatGPTTERMINAL tool — call this EXACTLY ONCE at the end of the run. Writes the final QA report (verdict, summary, severity counts, routes tested) to the QARun row + wiki. After this call, the agent loop will halt.
read_file
ChatGPTRead a file from the project's sandbox by path (relative to /home/user, e.g. 'src/app/page.tsx', or absolute). Text is returned inline (truncated at 200 KB); pass asBase64 for binary assets like images or fonts. Requires project:read scope.
read_project_structure
ChatGPTReturn the recursive file/directory tree of the project sandbox in one call (node_modules/.git/.next/dist/build pruned, capped at 2000 entries). Use this to understand project layout before reading specific files. Requires project:read scope.
read_shared_context
ChatGPTRead the FROZEN shared contract every surface of a ProductOS Product is built against: spec/prd.md (requirements), spec/flows.md (user flows), spec/components.md (component spec), spec/design-tokens.json, spec/schema.prisma (the shared database), design-system/DESIGN.md, and progress/<surface>.md (what each sibling surface has done so far). Read the relevant parts BEFORE changing any surface of a Product — code that contradicts this contract will drift from the other platforms. Omit path to list what's available. This contract is READ-ONLY and has a single writer: never write into it (not via write_file into /home/user/shared either) — to change it, use manage_product({ action: "sync_spec" }). Requires project:read.
record_architecture_decision
ChatGPTRecord an Architecture Decision Record (ADR). Persists to the database and writes to wiki for agent context. Use for major decisions: database choice, framework, deployment strategy, API pattern, etc.
remember_fact
ChatGPTSave important facts, decisions, or context to long-term project memory. These persist across sessions and are searchable by in-app agents and via search_memory. Pass all facts for the turn in one call. Requires project:write scope.
restart_sandbox
ChatGPTRestart a project's sandbox. Default (soft) restarts just the dev server process — fixes a wedged/stuck preview quickly. Pass hard:true to recreate the sandbox instance (persistent volume preserved) — use when the sandbox itself is broken; this returns immediately with a restart handle and runs in the background. Poll with action:'status' until it reports READY or FAILED. Requires project:exec scope.
run_release_checks
ChatGPTRun the project's release checks against its live deployment and report each route's expected vs actual HTTP status. Uses the project's configured checks when it has them, otherwise derives them from the routes in the last deploy. Also re-checks that every built route exists in production and that the database is reachable. Use this to confirm whether a deployment is actually healthy, or to see exactly which routes are failing and with what status. Does not deploy or change anything.
search_app_stores
ChatGPTFetch real customer reviews from the iOS App Store (via iTunes RSS) and/or Google Play (via SerpAPI). Use this for consumer mobile apps. You must supply at least one of iosAppId or androidPackageId — find them by inspecting the App Store / Play URL or asking the user. The iOS feed is rich (rating + body); the Android side returns search-snippet approximations because Google Play has no public reviews API.
search_files
ChatGPTSearch file contents across the project sandbox with a regular expression (grep -E). Build artifacts are excluded; results are capped at 200 matches. Returns 'path:line:match' rows. Requires project:read scope.
search_github
ChatGPTSearch GitHub for issues, PRs, and release notes mentioning a product. Use this for developer tools, SDKs, libraries, or any product whose users file public bug reports. Filters by repo name/description match before fetching, so 'Linear' won't return random unrelated repos. Returns the top-comments open issues plus the latest releases.
search_memory
ChatGPTSemantic search over this ProductOS project's long-form memory (ideation notes, prior decisions, file uploads, agent transcripts). Returns the top-matching snippets with a similarity score. Use this when get_project_context / get_wiki_section didn't surface the answer — memory often has detail the wiki summary omits. v1 read-only.
search_reddit
ChatGPTSearch Reddit or Quora for unfiltered user complaints, frustrations, and opinions about a product. Use this when you want unvarnished community sentiment that Exa's general web search would dilute. Reddit has the highest signal for B2C / consumer products; Quora skews more toward question-and-answer threads.
search_reviews
ChatGPTSearch structured B2B review platforms (G2, Trustpilot) for reviews and complaints about a product. Use this for SaaS or service-based products where buyers post deliberate written reviews. Returns search snippets, not the full review text — follow up with exa_fetch on the most interesting URLs if you need the body.
set_active_brand_step
ChatGPTAdvance the Brand Guidelines wizard UI to a specific step (1–4). Call BEFORE prompting the user about that step so the form visibly moves. 1=Brand name/logo, 2=Colors, 3=Typography, 4=Vibe report. Mood board is NOT a wizard step anymore — it moved to the Design System tab and is triggered there after the design system locks in.
set_active_design_tab
ChatGPTSwitch the main Design page tab in the user's UI. Call this BEFORE talking about or generating content for a different tab so the user actually sees the panel you are working in. Tabs: 'brand' (Brand Guidelines wizard), 'design-system' (Design System picker/generator), 'flows' (User Flows canvas), 'screens' (UI Screens grid), 'builder' (Design Agent build panel). Example: when the user says 'let's go to user flows and UI screens', call this with 'flows' before doing any user-flow work.
set_brand_identity
ChatGPTStep 1 — persist the brand name, tagline, and/or logo URL. Omit fields the user did not supply. Writes to the Design tab immediately; the form UI picks up the change via polling.
set_brand_setup_mode
ChatGPTPersist the user's chosen mode for the Brand Guidelines wizard. 'guided' means the orchestrator walks the user through the 5 steps with ask_user; 'automatic' means the UI/UX sub-agent fills everything from recalled context. Use this when the user picks in chat rather than the form's mode banner.
set_project_framework
ChatGPTSet or CONVERT the project's tech stack — updates both the framework and the project type, so this is how you turn a web project into a mobile (Expo) app, a marketing site (Astro), etc. The sandbox is rebuilt with the new template on the next open_project/start_sandbox (a mismatched sandbox is replaced automatically, its files re-seeded). Requires project:write. Confirm the stack choice with the user before calling.
set_stage
ChatGPTTransition the project to a new stage. Call this ONLY after the user has explicitly consented in their most recent message (e.g. 'yes move to research', 'let's do PRD now'). Prefer propose_stage_transition when you believe the stage is done but the user hasn't yet said yes. IDEATION EXIT GATE: when the current stage is ideation, do not call this until the user has supplied or explicitly confirmed the brand/product name; an AI-generated or placeholder project name does not count. IMPORTANT: Calling set_stage creates a NEW chat session for the next stage and seeds it with a hidden auto-kickoff message — the agent on that new page will greet the user and start the work automatically. After calling this tool, you MUST emit exactly one short acknowledgment line ('Moving us into research now.') and STOP — do NOT call delegate_to_<next_stage> or any other tool in this turn. The work continues on the new stage's page.
start_sandbox
ChatGPTCreate or wake a project's sandbox with the correct template image and restore its files from the persistent volume / GitHub. Returns the preview URL, or a 'starting' note if the dev server is still coming up (poll get_sandbox_status). Requires project:write scope.
stop_sandbox
ChatGPTStop a project's sandbox to free compute. Blaxel has no pause API, so this deletes the sandbox instance — the persistent volume and GitHub repo are preserved, and start_sandbox restores the exact same files. Does NOT delete project data. Requires project:exec scope.
trigger_deploy
ChatGPTDeploy the active project to production: GitHub push → Vercel deployment (deterministic, no auto-fix). Works in both Manual and Automatic deployment mode — calling it is the user's explicit deploy. Runs asynchronously and shows live in the ProductOS UI. On a build failure it stops at FAILED with the build logs — read get_deploy_logs, fix the code (edit_file/bash), and call trigger_deploy again. Poll get_deploy_status for status/URL. Requires project:write scope.
write_architecture_section
ChatGPTSave an architecture section to /home/user/wiki/agents/architecture/sections/<slug>.md. Call this once per section (e.g. 'system-overview', 'database-design', 'api-design'). Each section should be self-contained. Include Mermaid diagrams inline where appropriate.
write_design_brief
ChatGPTSave the full 5-section DESIGN.md brief. Writes /home/user/wiki/design-system/DESIGN.md (canonical full brief) AND auto-emits /home/user/wiki/design-system/design-brief.md (token-efficient companion: CSS vars, font URL, radii, component anchors only) so the Build agent can reload tokens cheaply on every turn. Also updates the DesignSystemConfig row and removes any stale /home/user/DESIGN.md. Call ONCE per run.
write_design_doc
ChatGPTSave a design artifact to /home/user/wiki/agents/design/outputs/<slug>.md. Call this once per artifact (e.g. 'brand-guidelines', 'onboarding-flow', 'home-screen'). Each doc should be self-contained and actionable.
write_design_preview
ChatGPTLegacy compatibility writer for both self-contained HTML previews in one call. Prefer write_design_preview_dark followed by write_design_preview_light so each payload stays below provider output limits.
write_design_preview_dark
ChatGPTSave the DARK-mode standalone HTML preview after write_design_brief. Writes /home/user/wiki/design-system/preview.html and DesignSystemConfig.previewHtml. Keep the document focused (roughly 100-220 lines) while demonstrating hero, typography, buttons, cards, input, badges, tokens, and color swatches. Call once, then call write_design_preview_light.
write_design_preview_light
ChatGPTSave the LIGHT-mode standalone HTML preview after write_design_preview_dark. Writes /home/user/wiki/design-system/preview-light.html and DesignSystemConfig.previewHtmlLight. Mirror the dark preview's sections and copy using the independently crafted light palette; keep it roughly 100-220 lines. Call once, then stop.
write_file
ChatGPTCreate or overwrite a file in the project sandbox (source code, configs, components, or a base64-encoded binary asset). Parent directories are created automatically. Use edit_file for targeted changes to a large file. Requires project:write scope.
write_prd_section
ChatGPTCreate or update a Product Requirements Document section. Each section is a separate markdown file with YAML frontmatter (title, position). The in-app PRD view reads these files directly. Requires project:write scope.
write_research_run
ChatGPTSave a standalone research document for ONE topic to /home/user/wiki/agents/research/runs/<slug>.md. Call this once per research topic (e.g. 'competitor-audit', 'market-sizing'). Each doc should be self-contained — includes its own findings + cited sources. The UI lists all run docs on the right panel so the user can browse them.
write_wiki_section
ChatGPTCreate or overwrite a markdown file in the project's wiki. Path is wiki-relative (e.g. 'agents/research/runs/competitor-audit.md'). Parent directories are created automatically. Requires project:write scope.
