environment-setup

  <step number="4">
    <title>Run practical validation when feasible</title>
    <description>Use runtime evidence to confirm install/start assumptions without over-expanding scope. Local validation should prove that the app serves successfully on localhost when a browser UI exists, without relying on direct browser automation from this workflow.</description>
    <actions>
      <action>Run validation workflow in order:

1. Inspect the repository statically.
2. Draft the initial config.
3. For every command added to repositories[].commands, run that exact command in config order when practical instead of validating only a representative subset.
4. For each command you run, confirm the result immediately from exit status, stdout/stderr, created artifacts, log output, readiness checks, localhost reachability, or other command-appropriate runtime evidence.
5. For detached commands, confirm both that the process launched and that its logfile or readiness check shows the expected service actually started.
6. If a test suite exists and is practical to run, execute the canonical test command.
7. Treat that test result as a blocker when it points to missing setup, broken environment definition, unavailable required services or secrets, or another problem that environment-setup can fix or that prevents local startup from being trusted.
8. When the test failure instead appears to be a clearly pre-existing repository or unit-test failure outside environment-setup scope, record the exact command and failure, keep the suite referenced in agentInstructions, and continue only if install/start/localhost validation is otherwise sufficient.
9. If the app exposes an HTTP UI, set initialUrl to the best validated absolute localhost URL (or keep about:blank only when no better landing page exists), confirm that localhost URL through loopback HTTP reachability and startup evidence, and record the exact URL plus the evidence used. Do not use direct browser automation from environment-setup.
10. When the config includes a ports entry for a validated HTTP surface, confirm its port number matches the actual validated listening port and that any initial_path responds successfully over loopback. 10a. When the config includes docker_projects, run docker compose config --quiet against the selected files or an equivalent generated one-service Compose model, start the selected services, wait for readiness, and confirm mapped HTTP ports over loopback. Capture docker compose ps --all and recent service logs when startup fails.
11. If the app exposes only an HTTP API or a non-browser surface, verify localhost reachability using loopback addresses only.
12. If any command in the draft config fails or cannot be confirmed, either revise or remove that command from the YAML, or report the exact blocker; do not leave unrun or unconfirmed commands in the final config.
13. As soon as repository evidence or early validation makes it clear that specific environment variables or secrets will be required and values are unavailable, request them immediately instead of waiting for a later failure.
14. In web dashboard tasks and Slack-started setup tasks, use request_environment_variables to request the needed keys securely instead of asking the user to paste secret values into the conversation.
15. In Slack-started setup tasks, send a concise send_chat_reply update with purpose set to progress that names the required keys and explains what they unblock, but do not include the secure /setup link yourself because the platform automatically accompanies the request with that secure-entry link after request_environment_variables succeeds.
16. In non-web surfaces where that tool is unavailable, ask the user to add the missing environment variables locally in the current running task, including exact variable names, what command each one blocks, and exact actions to set them.
17. If a required real service still cannot be installed, started, or connected after checking repository evidence and supported worker tooling, ask the user for help with that service instead of substituting a mocked or fake service.
18. If local install/test/start validation is blocked by missing environment variables or secrets, do not create an environment yet.
19. Keep the drafted YAML best-effort and revise it so it will work once those variables are provided, without fabricating values.
20. After the user confirms variables were added locally or provides guidance for the blocked real service, rerun the blocked or otherwise affected local validation steps and re-confirm every affected command.
21. Revise the config based on actual observations, using runtime evidence for startup details.
22. Only after local install/test/start works (or is otherwise sufficiently validated), persist the drafted YAML by creating a new environment or updating the specified existing environment, depending on the task context.
23. If environment persistence fails because the YAML still needs adjustment, revise the config based on the failure and retry at most 2 times.
24. After environment persistence succeeds, use the Roomote MCP task tools to launch one lightweight follow-up verification task against that environment before finishing this setup task.
25. For that follow-up task launch, call the Roomote MCP tool mcp__roomote__manage_tasks with action: "list_environments" first so you can confirm the created or updated environment appears as a current launch target and copy the exact returned environmentId.
26. Then call the Roomote MCP tool mcp__roomote__manage_tasks with action: "launch", environmentId set to that created or updated environment ID, notifyOnSettle set to true, and a concrete prompt such as Confirm that this environment is running correctly. First read .roomote/setup-status.json in the workspace root: while its state is "running", environment setup commands are still executing in the background — wait for it to reach a terminal state (you will get an in-session notification when it settles) instead of concluding startup is stuck. Re-read .roomote/setup-status.json every 10-15 seconds while it is still running, rather than sleeping for several minutes at a time. Once setup has settled, use localhost or the environment's initial URL to verify the expected service responds successfully and confirm there are no obvious startup failures blocking basic use. If any setup command failed, report each failing command's name and exit code from .roomote/setup-status.json plus the relevant error lines from .roomote/setup-logs/. Report the exact step that fails plus any visible error messages or logs. If everything works, say that the environment looks ready..
27. Keep the returned taskId for internal monitoring only. Do not expose the spawned verification task link in the user-facing response. 27a. Because the launch used notifyOnSettle: true, the platform delivers a Spawned task update message into this session when the verification task settles (completes, fails, is canceled, or goes idle after reporting). Treat that message as the primary completion signal: it is safe to finish other pending work or wait between summary checks, because the settle notification arrives even if this task has gone idle. When it arrives, immediately fetch the verification outcome with action: "get_summary" and action: "get_messages" and continue the workflow from step 31.
28. While waiting for that settle notification, check the verification task every 10-15 seconds with the Roomote MCP tool mcp__roomote__manage_tasks using action: "get_summary" and the returned taskId as a fallback signal. Use that per-task summary as the source of truth for task state, including any surfaced startup or runtime failure details and the Environment Setup line, which reports the ground-truth lifecycle of the verification task's environment setup commands: treat still running in the background as normal active startup rather than a stall, treat failed or completed with warnings as direct evidence that specific setup commands failed even when the verification task has not described the failure yet, and when Environment Setup is completed immediately inspect the latest task messages instead of sleeping for another long interval.
29. Narrate concise, plain-language progress updates while the follow-up check runs, so the user can see that setup is still being checked without being asked to wait. Say what is being checked (for example, I'm confirming the environment starts cleanly) rather than mentioning a spawned task, task status, polling, or monitoring.
30. Continue checking the verification task while the summary shows an active startup or running state, or until it clearly reports a startup or runtime blocker through the summary. Preparing the environment can take several minutes, so do not stop monitoring just because startup is taking a long time; keep checks frequent enough that a completed setup or completed verification is noticed promptly.
31. If the monitored summary reaches Completed without a surfaced startup or runtime failure, treat that as a successful spawned-task run and report that observed outcome directly instead of asking the user to confirm it manually.
32. If the monitored summary reaches Ready, Idle, or Needs input, do not keep polling that same state indefinitely. Inspect the latest task messages to determine whether the verification task already reported success, surfaced a blocker, or is unexpectedly waiting for follow-up input.
33. If those latest task messages clearly report that the environment looks ready, treat that as a successful spawned-task run and report the observed success directly.
34. If those latest task messages surface a startup or runtime blocker, request unexpected user input, or otherwise fail to give a clear success outcome, treat that as a blocker or verification failure instead of pretending the environment is verified. 34a. The persisted environment metadata is the source of truth for the web UI's verification state, so you must record the verification outcome explicitly. Once you have a clear outcome, call the Roomote MCP tool mcp__roomote__manage_environments with action: "record_verification" and environmentId set to the created or updated environment id: use success: true only when the explicit "environment looks ready" criterion above is satisfied, and use success: false with a short, user-safe error message when verification reaches a terminal failure or cannot be completed. Never put secrets or the full environment YAML in the error text. You do not need to pass any task id; Roomote derives the recording task automatically. 34b. If record_verification is rejected because a newer verification attempt or a runtime-affecting edit superseded this one, do not retry recording; treat this verification attempt as superseded and stop, since a newer attempt now owns the environment's verification state.
35. If the settle notification or the monitored summary reports Failed, Canceled, a startup or runtime error, or an Environment Setup state of failed or completed with warnings, inspect the exact status and error — asking the verification task for the failing command names, exit codes, and log excerpts from .roomote/setup-status.json and .roomote/setup-logs/ when they are not already surfaced — and decide whether the problem appears fixable within environment-setup scope, such as revising commands, services, environment variables, startup order, readiness checks, or other environment-definition details.
36. When the spawned verification task reveals a fixable setup or environment-definition error, try to fix it yourself, rerun any affected local validation, recreate or update the environment with the revised YAML, launch a fresh verification task, and repeat the monitoring process instead of stopping after the first failure.
37. Treat each fix attempt as a real retry loop: revise based on the observed error, revalidate the affected setup steps, persist the updated environment again, relaunch the verification task with notifyOnSettle: true, and wait for the new settle notification rather than assuming the old failure is resolved.
38. Keep this verification-repair loop bounded. Retry at most 2 additional full environment-update-plus-verification attempts after the first spawned verification task unless the task context explicitly justifies a smaller limit.
39. If the observed verification error appears to require product or source-code changes outside environment-setup scope, missing external credentials, unsupported infrastructure, or another user decision you cannot safely make, report that blocker instead of pretending the environment can be repaired automatically.
40. If the verification task remains in an active startup or running state without surfacing a blocker you can act on, keep monitoring instead of handing the waiting back to the user.
41. If the environment was persisted but the follow-up check could not be completed, explain that readiness could not be confirmed and name the real blocker in user terms. Do not pretend the environment is ready.
42. If full validation or environment persistence is blocked by missing dependencies, localhost reachability limits, permissions, unavailable environment APIs, or a required real service that still needs user guidance after local validation, keep the config minimal and report the blocker. The final config reflects observed install/test/start behavior where practical and clearly reports any validation limits.

<completion_criteria> All included fields are supported by repository evidence or practical validation.Uncertain fields are omitted rather than guessed.Validation outcomes and blockers are reported explicitly.When a repository test suite is practical to run, it is executed and the result is reported explicitly. Test failures block environment creation when they indicate an environment-definition or setup problem; clearly pre-existing repository failures may be carried forward only when install/start validation is otherwise sufficient.The final environment definition is best-effort and should be runnable once required environment variables are provided.Environment creation or update is attempted only after local install/test/start validation is successful enough to proceed.When environment persistence succeeds, a lightweight Roomote verification task is launched against that environment and monitored by calling the Roomote MCP tool mcp__roomote__manage_tasks with action: "get_summary" before this setup task finishes, unless an explicit blocker prevents launch or monitoring.The verification outcome is recorded through mcp__roomote__manage_environments with action: "record_verification" (success: true only when the environment explicitly looks ready, otherwise success: false with a user-safe error), unless a blocker prevents launch or monitoring or the recording is rejected as superseded.The final response summarizes the environment name, whether it was created or updated, key validation outcomes, and any blockers - without including the raw YAML config or internal orchestration details.A successful onboarding final response ends by telling the user that the environment is ready and linking [Create a new task](/) as the clear next action.If the follow-up verification task reaches Completed without a surfaced startup or runtime failure, the final response reports that the environment is ready to use instead of asking the user to confirm it manually or describing the verification task.If the spawned verification task reveals a fixable setup or environment-definition error, the skill attempts to repair it, update the environment, relaunch verification, and report the final bounded retry outcome instead of stopping after the first failed verification task.If the app exposes a browser UI and local startup succeeds, the localhost URL is verified through loopback reachability or other non-browser startup evidence before persistence continues.If required environment variables or secrets are known but unavailable, the skill requests them immediately through request_environment_variables in web tasks and Slack-started setup tasks, or asks the user to set them locally in the current task before proceeding with affected validation.Every command present in the final repositories[].commands list was run and explicitly confirmed during validation, or an explicit blocker explains why validation could not proceed.No secrets, credentials, fabricated env values, or unsupported keys are introduced. </completion_criteria>

<schema_reference>

<docker_project_config>

<docker_project_port>

<named_port_config>

<repository_config>

<command_config>

<allowed_services> redis6redis7postgres15postgres16postgres17mysql8mariadb10clickhouseaws </allowed_services>

</schema_reference>

<hard_rules> Check each target repo's developer local-setup documentation before inferring sandbox setup commands from manifests, scripts, or CI.When repo-local setup docs and lower-level evidence disagree, prefer the documented local developer workflow unless direct runtime validation proves the docs are stale or incomplete.Treat repositories referenced by the task or environment as already checked out in the current workspace unless the user explicitly says otherwise.Preserve every task-provided repository identifier exactly in repositories[].repository; never shorten or reconstruct it from a checkout path. Azure DevOps identifiers must retain organization/project/repository.Never include the full environment YAML in your visible response or Slack reply. The environment is already persisted through manage_environments; re-dumping the config into the transcript is redundant and risks exposing secret values that were kept out of the conversation through request_environment_variables.Use repository default branch unless strong evidence supports another branch.Include only commands strongly supported by repository evidence.Do not run git clone, ask the user to re-clone a repository that is already present, or include clone steps in repositories[].commands.Use repositories[].commands only for executing commands and setting configuration needed to validate the environment.If setup requires configuration or runtime file creation or modification, represent it with repositories[].commands entries instead of asking the user to edit files directly.Do not use repositories[].commands to write, generate, or patch application or source code; if source changes are required, report that as a blocker or separate follow-up work.Treat each run field as newline-split before execution. Do not rely on YAML multiline blocks to preserve shell control flow across lines.Do not emit YAML run: | blocks for if ... fi, case, loops, heredocs, or multiline shell functions unless the entire block is wrapped inside one explicit shell command such as bash -lc '...'.When setup logic needs conditional or multiline behavior, prefer multiple simple command entries or one explicit shell wrapper command over raw multiline shell fragments.Prefer runtime-only configuration file modifications outside the git repository when possible to avoid unstaged repo changes.Include only services clearly required by repository evidence.Use docker_projects only when a checked-in Compose project or Dockerfile is the evidence-backed development path, and validate the exact model before persistence.All Docker project paths must be relative and stay inside the selected configured repository.Include tool_versions only when clearly discoverable.When a repository exposes a browser UI or stable localhost landing page, set initialUrl to the best validated absolute URL unless about:blank is intentionally required.When a validated human-facing HTTP surface exists (particularly a web app UI), configure a matching top-level ports entry so the environment publishes a shareable preview URL for it; keep the ports list limited to validated human-facing surfaces and confirm each configured port number against the actual validated listening port.Always derive a best-effort environment definition that is ready to work once required environment variables are supplied.Treat agentInstructions as instructions for future agents running inside the created environment, not as setup progress notes or setup next-step guidance for this skill run.When the app exposes a browser UI, agentInstructions must explain how agents access it, including any authentication steps. Do not assume agents will discover auth flows, test credentials, or dev-mode conventions on their own.If a repository test suite exists, include a concrete test command in agentInstructions and state that the suite should pass before completing future code changes, even when setup validation reports a clearly pre-existing repo failure.If tests are practical to run during validation, execute the suite and treat failures as blockers when they indicate missing setup, broken environment definition, unavailable required services or secrets, or another environment-setup problem.Do not treat clearly pre-existing repository or unit-test failures as automatic blockers to environment creation when install/start/localhost validation succeeds and the failure appears outside environment-setup scope; report the exact failing command and keep the issue visible as a known repo problem.Every command added to repositories[].commands must be run during validation in config order unless an explicit blocker prevents it.Every command added to repositories[].commands must be explicitly confirmed from execution evidence appropriate to that command, such as exit status, log inspection, artifact creation, localhost reachability, or other command-appropriate runtime evidence.Do not depend on prompt-wide browser bootstrap or direct browser automation inside environment-setup; keep localhost validation in this skill to loopback reachability and startup evidence.If any configured command cannot be run or confirmed, remove it from the final environment definition or report the exact blocker; do not leave speculative or unverified commands in the final config.Do not replace required real services with mocks, stubs, fake servers, or no-op stand-ins merely to make validation appear successful.If repository evidence and supported worker tooling are still insufficient to get a required real service running, ask the user for help with that service before proceeding instead of inventing a fallback.If repository evidence or validation shows that required environment variables or secrets are needed, request them as soon as their names are known instead of waiting for a later command failure.If local install/test/start cannot run due to missing environment variables or secrets, do not create an environment until the missing variables are provided through request_environment_variables in web tasks and Slack-started setup tasks, or the user adds them locally and validation is retried.When required environment variables or secrets are known but unavailable in a web dashboard task or Slack-started setup task, use request_environment_variables and never ask the user to paste secret values into the conversation.In Slack-started setup tasks, send a concise send_chat_reply message with purpose set to progress naming the required keys and what they unblock, but do not include the secure /setup link yourself because the platform automatically accompanies the request with that secure-entry link after request_environment_variables succeeds.In non-web surfaces, ask only for local environment variable additions in the current task, and provide exact variable names and exact actions.For this skill, create a new environment or update the specified existing environment only after localhost startup and loopback reachability are successful enough to proceed, including validation of initialUrl through non-browser evidence when the app exposes a browser UI.When the task explicitly identifies an existing environment to revise, update that environment instead of creating a duplicate.After successful environment persistence, use the Roomote MCP tool mcp__roomote__manage_tasks to launch a lightweight verification task against the created or updated environment and monitor it yourself instead of leaving verification as an implicit manual next step.Before launching that verification task, call the Roomote MCP tool mcp__roomote__manage_tasks with action: "list_environments" so the environment target is grounded in current Roomote data and you can copy the exact returned environmentId.When the verification task launch succeeds, monitor it every 10-15 seconds with the Roomote MCP tool mcp__roomote__manage_tasks using action: "get_summary" and use that per-task summary surface as the source of truth for task status and surfaced startup failures.While the follow-up check runs, narrate concise progress updates in plain language instead of silently waiting or pushing the waiting back onto the user. Do not mention a spawned task, task status, polling, or monitoring in those user-facing updates.Preparing the environment can take several minutes. Do not stop monitoring solely because the verification task is taking a long time to start; keep checking until it reaches a terminal state or surfaces a blocker you can report or act on, and keep checks frequent enough that a completed setup or completed verification is noticed promptly.If the monitored summary settles into Ready, Idle, or Needs input, inspect the latest task messages instead of polling that state forever, and only treat it as success when those messages clearly report that the environment looks ready.Record the verification outcome explicitly through the Roomote MCP tool mcp__roomote__manage_environments with action: "record_verification" and the created or updated environmentId: success: true only when the explicit "environment looks ready" criterion is satisfied, and success: false with a short, user-safe error when verification reaches a terminal failure or cannot be completed. Do not include secrets or the full environment YAML in the error, and do not pass a task id (Roomote derives the recording task from the current run).Treat a rejected record_verification result as a superseded attempt: do not retry recording, because a newer verification attempt or a runtime-affecting edit now owns the environment's verification state.If the spawned verification task surfaces a fixable setup or environment-definition problem, attempt to fix it yourself, recreate or update the environment, launch a fresh verification task, and repeat the monitoring loop instead of stopping after the first discovered error.Bound that environment-repair loop to at most 2 additional full retries after the first spawned verification task unless the task context clearly justifies fewer attempts.Do not claim automatic repair for failures that actually require product/source changes outside environment-setup scope, unsupported infrastructure, missing external credentials, or a user decision you cannot safely infer; report those as blockers.Do not tell the user to verify the environment in that spawned task before clicking Continue, and do not include the spawned verification task link in the user-facing response; report the monitored outcome yourself.If the follow-up check cannot be launched or completed after the environment is persisted, report that readiness could not be confirmed and explain the real blocker in user terms; do not imply the environment is ready.When a browser UI is validated locally, report the exact localhost URL and the loopback or startup evidence that confirmed it rather than capturing screenshots from this skill.Any long-running service command (for example dev, start, serve, preview, or watchers) must use detached: true.Any command with detached: true must set logfile to capture runtime output.Do not encode pm2 start, nohup, shell trailing &, or another process supervisor in run for environment repository commands. Use the normal foreground command with detached: true; Roomote supervises it with PM2 and restarts it if it exits unexpectedly.Do not include unsupported keys.Do not fabricate env values.If secrets are required but unavailable, omit them and report the blocker. </hard_rules>

<example_notes>

<best_practices> Treat examples as patterns, not templates to copy blindly.Repository-specific evidence should determine final fields.Prefer the smallest config that matches the repository's real workflow.Minimal configs are easier to run, validate, and maintain.Prefer command-driven setup over manual repo edits.Encoding file writes in commands keeps setup reproducible and avoids asking the user for avoidable code changes.Prefer one-line run commands.The executor splits run on literal newlines, so one-line commands or explicit shell wrappers are much less error-prone than YAML block-scalar shell scripts.Prefer runtime-only files outside the git repo.Writing temporary setup files to locations like /tmp reduces repository noise and prevents unexpected unstaged changes. </best_practices>

<error_handling> Repository evidence does not clearly support a field.Omit the field and document the uncertainty in Assumptions or Blockers instead of guessing.Install or startup cannot complete due to unavailable secrets, credentials, or external systems.Keep the config minimal, report exactly what blocked validation, and avoid fabricated env values.The app starts locally, but the expected localhost URL cannot be confirmed through loopback reachability or other non-browser startup evidence.Report the blocker explicitly, include any successful loopback checks you did perform, and do not claim browser-surface validation succeeded.Local validation succeeded, but creating the environment failed.Report the exact creation error, revise the YAML if the failure reveals a concrete config issue, and retry within the normal retry budget.Local install, test, or startup fails because required environment variables or secrets are missing.Keep the YAML best-effort, stop at the blocked local validation step, ask the user to add exact keys locally in the current task, then rerun blocked validation steps after confirmation.The canonical test command fails, but the failure appears to come from the repository's current test state rather than the drafted environment definition.Record the exact failing command, explain why the failure appears outside environment-setup scope, keep the test command in agentInstructions, and continue with environment persistence only when install/start/localhost validation is otherwise sufficient.Setup cannot succeed via environment variables or setup changes encoded in generated environment config commands (including command-driven runtime file creation).Ask for the minimal user code change only as a last resort, and explain why commands-based setup and non-repo file options were insufficient. </error_handling>