diff --git a/.agents/skills/devsy/SKILL.md b/.agents/skills/devsy/SKILL.md index e5f93c2068..5c980d75e8 100644 --- a/.agents/skills/devsy/SKILL.md +++ b/.agents/skills/devsy/SKILL.md @@ -10,112 +10,114 @@ metadata: # Devsy -Operate Devsy workspaces and providers on behalf of an end user. This skill is -not the contributor guide for changing Devsy itself; for source-development -tasks follow the repository's `AGENTS.md` and normal development instructions. +Operate Devsy workspaces and providers for an end user. For changes to the +Devsy source code, follow the repository's `AGENTS.md` instead. ## Choose the interface -Use the available Devsy MCP tool when it supports the requested operation. -Client tool names may have a server prefix; discover the actual tools rather -than assuming they are connected. Use the Devsy CLI for capabilities MCP does -not expose, or as fallback when MCP is unavailable and shell access exists. -If neither interface is available, report the missing prerequisite and link to +Use a Devsy MCP tool when it supports the operation. Client tool names can +have a server prefix, so discover the actual tools. Do not assume they are +connected. + +Use the Devsy CLI for operations MCP does not expose, or when MCP is +unavailable and shell access exists. If neither interface is available, report +the missing prerequisite and link to [Devsy MCP setup](https://devsy.sh/docs/developing-in-workspaces/mcp-server). Installing this skill does not install Devsy or configure MCP. -Keep the same Devsy context, provider, and owner scope when switching interfaces. -Do not silently replace Devsy operations with direct Docker, Kubernetes, or -cloud mutations. Devsy owns workspace state; low-level provider diagnosis needs -appropriate user authority and a reason the Devsy diagnostics are insufficient. +Keep the same Devsy context, provider, and owner when you switch interfaces. +Do not replace Devsy operations with direct Docker, Kubernetes, or cloud +changes. Devsy owns workspace state. Low-level provider diagnosis needs the +user's authority and a reason that Devsy diagnostics are not enough. ## Discover and select a workspace -- When identity is uncertain, call `workspace_list` and use a returned name. - Match an explicit user name first, then source/project when unambiguous. -- Reuse an existing suitable workspace when consistent with the request. - An explicit request for another isolated workspace should get a distinct name. -- Inspect saved configuration with `workspace_status`. Its current result is - configuration, **not live running state**. When running state matters, use - `devsy workspace status --result-format json` or `workspace describe` - through the CLI. Existence does not imply the container is running. -- Resolve multiple matching candidates before mutating one. +- If the identity is uncertain, call `workspace_list` and use a returned name. + Match an explicit user name first. Then match source or project, if only one + workspace fits. +- Reuse an existing workspace when it fits the request. A request for another + isolated workspace gets a distinct name. +- `workspace_status` returns saved configuration, not live running state. When + running state matters, run `devsy workspace status --result-format json` + or `workspace describe` through the CLI. A workspace can exist without its + container running. +- Resolve multiple matching candidates before you change one. ## Create and resume -Before creating, list workspaces, determine the source, and consider reuse. -`workspace_create` accepts a Git URL, absolute host-local path, container image, -or canonical source returned by `workspace_list`. A local path belongs to the -host running Devsy, not necessarily the agent's remote filesystem. +Before you create a workspace, list workspaces, identify the source, and check +whether to reuse one. `workspace_create` accepts a Git URL, an absolute +host-local path, a container image, or a canonical source from +`workspace_list`. A local path refers to the host running Devsy, not +necessarily the agent's remote filesystem. -If provider selection matters, call `provider_list` and use the configured name. -Otherwise allow the context's default provider. Add a provider only when setup -is part of the user's request; do not change the global default just to select -one provider for one workspace. Creation starts the workspace. Use its returned -configuration and identity for subsequent work. Use `workspace_start` to resume -an existing workspace, after discovery where needed. +If the provider matters, call `provider_list` and use the configured name. +Otherwise, let the context's default provider apply. Add a provider only when +setup is part of the request. Do not change the global default to pick a +provider for one workspace. Creating a workspace starts it. Use the returned +configuration and identity for later work. Use `workspace_start` to resume an +existing workspace. ### Create timeout recovery -A client timeout does not prove server-side creation stopped. **Do not blindly -retry creation, switch to CLI creation, or pick a second name.** Check +A client timeout does not mean server-side creation stopped. Do not blindly +retry creation, switch to CLI creation, or pick a second name. Check `workspace_status` for the expected name, or `workspace_list` if the name is -uncertain. A newly visible configuration does not by itself prove setup finished; -check live state and operation diagnostics when needed. Use bounded checks -appropriate to the active task. A single not-found result can race creation; -retry only after evidence establishes that the original operation failed or -ended without creating the workspace. Report an unresolved outcome instead of -creating duplicate infrastructure. +uncertain. Saved configuration does not show that setup finished, so check live +state and operation diagnostics. Use bounded checks. A single not-found result +can race with creation. Retry only after evidence shows that the original +operation failed or ended without creating the workspace. If the outcome is +unresolved, report it. Do not create duplicate infrastructure. ## Execute commands -Ensure the workspace is started. `workspace_exec.command` is an **argv array**: +Make sure the workspace is started. `workspace_exec.command` is an **argv array**: ```json {"name":"my-workspace","command":["npm","test"]} ``` -Use a shell only for shell features such as pipes, redirection, expansion, or -chaining, and only when that shell exists in the workspace: +Use a shell only for shell features, such as pipes, redirection, expansion, or +chaining. The shell must exist in the workspace: ```json {"name":"my-workspace","command":["sh","-c","npm test && npm run lint"]} ``` -Separate direct argv calls are also suitable for sequential commands. Determine -test/build commands from the project or user request; do not guess a package -manager. `workdir` is a container path and `env` maps strings to strings. +Separate direct argv calls work for sequential commands. Find test and build +commands in the project or the user's request. Do not guess the package +manager. `workdir` is a container path. `env` maps strings to strings. -Check tool errors and the optional `error` payload as well as `exit_code`, -`stdout`, and `stderr`. `timed_out` means an execution timeout, not a normal -process exit; `truncated` means captured output is incomplete; `clamped` means -the requested timeout was shortened. Do not automatically rerun a command with -side effects after timeout or incomplete output. Defaults are 5 minutes per -exec, a 30-minute maximum, 100 KiB per output stream, and 8 concurrent -create/start/exec operations per server; server flags can change these limits. +Check tool errors and the optional `error` payload, then `exit_code`, `stdout`, +and `stderr`. `timed_out` means the execution timed out. `truncated` means +captured output is incomplete. `clamped` means the requested timeout was +shortened. Do not rerun a command with side effects after a timeout or +incomplete output. Defaults: 5 minutes per exec, a 30-minute maximum, 100 KiB +per output stream, and 8 concurrent create, start, or exec operations per +server. Server flags can change these limits. ## Stop, delete, and configure providers -Stopping compute uses `workspace_stop`; deletion removes workspace resources. -Do not interpret restart, refresh, fix, or vague cleanup as deletion authority. -For deletion or reset, establish unambiguous intent and target. Explicit deletion -can proceed within that authority without repeated confirmation. Do not default -to `force=true`: forced cleanup can leave provider resources behind and, for -imported workspaces, can also enable remote deletion otherwise skipped. +`workspace_stop` stops compute. Deletion removes workspace resources. Do not +treat restart, refresh, fix, or vague cleanup as permission to delete. For +deletion or reset, confirm the intent and the target. Explicit deletion needs no +repeated confirmation. Do not default to `force=true`. Forced cleanup can leave +provider resources behind. For imported workspaces, it can also enable remote +deletion that ordinary deletion skips. -Provider deletion affects shared configuration and may be refused while -workspaces use it. Do not delete a provider to repair one workspace. Treat -`provider_use` as a default change for subsequent creates, not a per-workspace -selection. Commands executed inside a workspace can themselves be destructive; -assess their effects, not just the tool name. +Provider deletion changes shared configuration, and the provider can refuse +deletion while workspaces use it. Do not delete a provider to repair one +workspace. `provider_use` changes the default for later creates, not the +provider for one workspace. Commands run inside a workspace can be destructive. +Assess what they do, not only the tool name. ## References -Read only the reference relevant to the task: +Read only the reference that fits the task: -- [MCP tool contract](references/mcp-tools.md) — inputs, results, limits, and errors. -- [Workspace workflows](references/workspace-workflows.md) — discovery, creation, resume, execution, stop, delete, recreate/reset. -- [CLI fallback and extended capabilities](references/cli.md) — structured output, diagnostics, and CLI-only operations. -- [Provider workflows](references/providers.md) — provider selection and configuration. -- [Safety and authority](references/safety.md) — destructive actions, credentials, and repository content. -- [Troubleshooting](references/troubleshooting.md) — timeouts, partial output, and unavailable interfaces. +- [MCP tool contract](references/mcp-tools.md): inputs, results, limits, and errors. +- [Workspace workflows](references/workspace-workflows.md): discovery, creation, resume, execution, stop, delete, recreate, and reset. +- [CLI fallback and extended capabilities](references/cli.md): structured output, diagnostics, and CLI-only operations. +- [Provider workflows](references/providers.md): provider selection and configuration. +- [Safety and authority](references/safety.md): destructive actions, credentials, and repository content. +- [Troubleshooting](references/troubleshooting.md): timeouts, partial output, and unavailable interfaces. diff --git a/.agents/skills/devsy/references/cli.md b/.agents/skills/devsy/references/cli.md index 8720ce6bac..0c600c09d9 100644 --- a/.agents/skills/devsy/references/cli.md +++ b/.agents/skills/devsy/references/cli.md @@ -1,10 +1,9 @@ # CLI fallback and extended capabilities -Use an available equivalent MCP tool first. Use CLI when MCP is unavailable or -cannot express the requested behavior. Check `devsy version` and command `--help` -if the installed version differs from this reference. Preserve the MCP server's -context/provider/owner scope when switching, using the corresponding global -flags when set. Do not silently operate in a different context. +Use the equivalent MCP tool first. Use the CLI when MCP is unavailable or cannot +express the behavior. If the installed version differs from this reference, run +`devsy version` and check the command `--help`. When you switch from MCP, pass +the matching global flags so the context, provider, and owner stay the same. ## Fallback mappings @@ -22,13 +21,12 @@ flags when set. Do not silently operate in a different context. | `provider_use` | `devsy provider use ` | | `provider_delete` | `devsy provider delete ` | -`workspace up` is create-or-resume, so a missing name can be interpreted as a -source. Never use it as a lookup. Supply `--id ` when intentionally naming -a new workspace and `--provider ` when selecting its provider. -`--ide-launch skip` avoids launching the host editor/browser for automation; -respect a user request to launch an IDE instead. +`workspace up` creates or resumes a workspace. An unknown name becomes a +source, so never use it as a lookup. Pass `--id ` to name a new workspace +and `--provider ` to select its provider. `--ide-launch skip` +keeps the host editor or browser closed. Omit it when the user asks for an IDE. -Prefer JSON where supported: +Prefer JSON output when the command supports it: ```sh devsy workspace list --result-format json @@ -37,66 +35,61 @@ devsy workspace describe my-workspace --result-format json devsy workspace events my-workspace --limit 20 --result-format json ``` -CLI status returns live `state`; describe adds live state to full configuration. -Unlike these commands, MCP `workspace_status` currently returns configuration -only. Do not scrape decorative tables when JSON exists. Exec stdout/stderr are -command streams, not a JSON result object; adding `--result-format json` does -not turn them into MCP's bounded exec response or reproduce its timeout limits. +CLI `status` returns live `state`. `describe` adds live state to the full +configuration. MCP `workspace_status` returns configuration only. Do not scrape +tables when JSON exists. Exec stdout and stderr are command streams. Adding +`--result-format json` does not give them MCP's bounded exec response or +timeout limits. ## Diagnostics - `devsy workspace events --limit 20 --result-format json`: recent - lifecycle journal, useful for pending/failed creation and start/stop operations. -- `devsy workspace logs `: agent logs; unsupported for proxy providers. - Bound log collection with the host tool's timeout and focus on relevant errors. -- `devsy workspace ping `: hidden diagnostic for **Devsy Platform workspaces - only**, not a general container-health probe. -- `devsy workspace troubleshoot `: hidden diagnostic that prints JSON - including config/provider/workspace information and an optional `Errors` - array. Inspect partial errors even if the process exits successfully. Review - and redact sensitive output before sharing; it is not a guaranteed clean bill - of health or a downloadable bundle. + lifecycle journal for pending or failed creation, start, and stop. +- `devsy workspace logs `: agent logs. Proxy providers do not support + them. Set a host timeout. +- `devsy workspace ping `: hidden command for Devsy Platform workspaces + only. It does not check container health. +- `devsy workspace troubleshoot `: hidden command. It prints JSON with + config, provider, and workspace information, plus an optional `Errors` array. + Read the `Errors` array even when the process exits with success. Redact + sensitive output before you share it. ## Additional operations -Use only when requested or necessary; inspect installed `--help` for optional -flags before using them. +Use these when the user asks or the task needs them. Check `--help` for flags. | Command | Purpose and constraint | | --- | --- | -| `devsy workspace build ` | Build/prebuild the workspace environment; publishing behavior depends on flags/configuration. Inspect help and requested destination first. | -| `devsy workspace rename ` | Change workspace identity; refresh discovery afterward. | +| `devsy workspace build ` | Build or prebuild the workspace environment. Flags and configuration decide whether it publishes. Check help and the requested destination first. | +| `devsy workspace rename ` | Change the workspace name. Refresh discovery afterward. | | `devsy workspace edit [--display-name