Skip to content

chatgpt-coding-workflow.md

Latest commit

 

History

History
193 lines (137 loc) · 6.18 KB

chatgpt-coding-workflow.md

File metadata and controls

193 lines (137 loc) · 6.18 KB
Raw

ChatGPT Coding Workflow

DevSpace brings a Codex-style coding-agent loop to ChatGPT and other MCP hosts: inspect the repo, follow local instructions, make scoped edits, run verification, and show the user what changed.

Open One Workspace

ChatGPT should call open_workspace once for a project folder:

{
  "path": "~/work/my-project"
}

The result includes a workspaceId. All later file, search, edit, show-changes, and shell calls should reuse that same workspaceId.

Do not reopen the same folder unless:

  • the workspaceId is rejected as unknown
  • the user switches to another folder
  • the user switches between checkout and worktree mode
  • the user explicitly asks to reopen

Checkout Mode

Checkout mode is the default. DevSpace opens the actual directory:

{
  "path": "~/work/my-project"
}

Use this when the user wants ChatGPT to work in the current checkout.

Worktree Mode

Use worktree mode for isolated parallel work:

{
  "path": "~/work/my-project",
  "mode": "worktree"
}

Managed worktrees are created under:

~/.devspace/worktrees

Worktree mode requires a Git repository with at least one commit. It starts from HEAD unless baseRef is provided.

Uncommitted source checkout changes are not copied into the managed worktree. DevSpace reports when the source checkout was dirty so the model can decide how to proceed with the user.

Project Instructions

When a workspace opens, DevSpace loads root-level instruction files:

  • AGENTS.md
  • AGENTS.MD
  • CLAUDE.md
  • CLAUDE.MD

Nested instruction files are returned as availableAgentsFiles. The model should read the relevant nested file before working under that directory.

This keeps instructions explicit and inspectable instead of silently injecting new context during later tool calls.

Skills

Skills are enabled by default for coding-agent workflows.

DevSpace discovers standard Agent Skills from:

  • ~/.agents/skills
  • project .agents/skills
  • ~/.devspace/skills

It also includes:

  • the package-managed subagents skill when the Subagents capability is enabled
  • the package-managed dynamic-workflows skill when the Dynamic Workflows capability is enabled
  • DEVSPACE_AGENT_DIR/skills, defaulting to ~/.codex/skills
  • additional paths from DEVSPACE_SKILL_PATHS

When Subagents are enabled, DevSpace discovers agent profiles from ~/.devspace/agents/*.md and project .devspace/agents/*.md. open_workspace exposes a compact catalog with profile names, descriptions, providers, and optional models/effort levels so the model can choose a configured agent without seeing provider-specific launch details.

Example profiles are packaged under examples/agents/ for users who want starter templates. Copy or adapt them into one of the active profile directories before use.

Legacy project paths such as .pi/skills can be added through DEVSPACE_SKILL_PATHS when needed.

When open_workspace returns matching skills, the model should read the advertised SKILL.md before following that skill.

Skill paths may be outside the workspace. DevSpace only permits reading:

  • advertised SKILL.md files
  • files under a skill directory after that skill's SKILL.md has been read

Set DEVSPACE_SKILLS=0 to hide skills from workspace output. Set DEVSPACE_SUBAGENTS=1 to expose the experimental subagent catalog and subagents skill. That skill can use target information already supplied by the host or discover it with devspace agents targets. devspace agents ls lists existing subagent sessions for the current workspace.

Set DEVSPACE_WORKFLOWS=1 to enable Dynamic Workflows independently. When the variable is omitted, Dynamic Workflows follows the effective Subagents setting, including persisted config and any environment override. Disabled features are omitted from the open_workspace schema and response rather than returned as empty capability arrays.

Tool Names

DevSpace exposes these tool names:

  • open_workspace
  • read
  • write
  • edit
  • bash

By default, DevSpace also runs in DEVSPACE_TOOL_MODE=minimal, so dedicated grep, glob, and ls tools are hidden. Use bash with command-line tools such as rg, find, and ls for search and directory inspection.

Use DEVSPACE_TOOL_MODE=full to restore dedicated search and directory tools.

The experimental Codex-style surface is enabled with DEVSPACE_TOOL_MODE=codex. It exposes:

  • open_workspace
  • read
  • apply_patch
  • exec_command
  • write_stdin

In this mode, write, edit, bash, grep, glob, and ls are not registered. exec_command returns a process session ID when a command is still running after its yield window. Use write_stdin to poll it, send input, resize a PTY, or send Ctrl-C. Set tty: true only for commands that need a terminal.

Widget UI and Show Changes

By default, DEVSPACE_WIDGETS=full.

In that mode, DevSpace attaches widget UI to the exposed workspace, workflow, file, edit, and shell tools. The open_workspace dropdown presents the opened root, loaded skills and instructions, available agent providers/profiles, and currently active workflows for that workspace.

Dynamic Workflow views are read-only. They refresh through app-only MCP tools and show observed phases, agent calls, replay state, worktree isolation, errors, and recent activity. When the host supports MCP Apps fullscreen display mode, the card offers an Open dashboard presentation control. It does not add cancel, resume, apply, or cleanup actions.

The aggregate show_changes tool is not exposed by default.

Use DEVSPACE_WIDGETS=off to disable widget UI, or DEVSPACE_WIDGETS=changes to expose the aggregate show-changes flow.

When show_changes is exposed, models should call it exactly once after the final file modification in any turn that changes files. The tool only requires the workspaceId; DevSpace automatically compares against the last shown checkpoint and advances that checkpoint after rendering the aggregate diff.

Shell Use

The shell tool is for commands that belong in a terminal:

  • tests
  • builds
  • git inspection
  • package scripts
  • environment checks

File writes should go through the edit/write tools rather than shell redirection, heredocs, tee, sed -i, or generated scripts.