Skip to content

chatgpt-coding-workflow.md

Latest commit

 

History

History
231 lines (179 loc) · 7.48 KB

chatgpt-coding-workflow.md

File metadata and controls

231 lines (179 loc) · 7.48 KB
Raw

ChatGPT Coding Workflow

DevSpace gives ChatGPT web a small execution-scoped surface for approved local Projects. Project files, repository instructions and Skills, model-authored checkpoint summaries, and process output are untrusted input. User, admin, bundled, DevSpace, and explicitly configured Skills retain explicit trusted provenance. No content can expand OAuth authority or replace a user decision.

1. Select a Project and Task

With one approved Project, open directly:

{"action":"open","operationId":"open-001"}

With multiple Projects, call list_projects, select its opaque projectRef, then call project_control:

{"action":"open","projectRef":"project_...","operationId":"open-001"}

Checkout mode uses the approved directory. For a Git top-level Project, request an isolated managed worktree explicitly:

{
  "action":"open",
  "projectRef":"project_...",
  "operationId":"open-worktree-001",
  "checkoutKind":"worktree"
}

To continue a saved task in a new conversation, call list_projects. The global result has Project refs, labels, and resumableTaskCount only. Select a Project, then request its bounded Task metadata:

{"projectRef":"project_..."}
{
  "action":"resume",
  "projectRef":"project_...",
  "taskRef":"task_...",
  "operationId":"resume-001"
}

The scoped listing returns taskRef, title, version, and updatedAt, with top-level taskTrust:"untrusted". Do not infer paths or choose a Task by recency. Thread discovery, status, activity, and lifecycle are Project App controls, not model tool calls.

2. Complete root instructions

Successful open and resume select an execution for the trusted openai/session and Actor and return one bounded instruction page. The execution identity remains server-side. If the page has nextCursor, continue with:

{
  "action":"hydrate",
  "cursor":"dcur1_..."
}

Repeat until no nextCursor remains. Continuation pages contain only new instructions and an optional cursor. If the cursor is lost, hydrate without a cursor to restart the sequence. Other Project tools remain gated until the final page, then are called directly without an execution reference.

Targeted reads and inspection may return newly applicable nested instruction deltas. A patch or command encountering unseen instructions returns instructions_required before starting any effect.

3. Load Skills lazily

Search only when a Skill is relevant:

{"query":"testing"}

Load one advertised result:

{"skillId":"skill_..."}

Repository Skills remain untrusted. User, admin, bundled, DevSpace, and explicitly configured Skills retain explicit trusted provenance, but no Skill can grant access or authority beyond the current OAuth grant and approved roots.

4. Read and inspect efficiently

  • Use read_files for one to eight known files and current versions.
  • Use inspect for one to eight grep, glob, or directory-list operations.
  • Use show_changes with an explicit repository or apply_patch_history source for a bounded review.

Keep paths Project-relative. Narrow large searches instead of repeatedly requesting the whole repository.

5. Apply guarded patches

Reuse the current version object from read_files as the path's ifMatch; use null for a path expected not to exist:

{
  "operationId":"patch-001",
  "ifMatch":{"src/example.ts":{"contentHash":"sha256:...","mtimeNs":"..."}},
  "patch":"*** Begin Patch\n*** Update File: src/example.ts\n@@\n-old\n+new\n*** End Patch\n"
}

After editing, call show_changes with source:"repository" for the full Git working-tree view, or source:"apply_patch_history" for this execution's successful DevSpace patches. Confirm only intended files changed, then run the smallest relevant verification.

Successful patches automatically append a bounded server-observed Thread checkpoint. The checkpoint stores effect metadata, not file bodies.

6. Run commands

Prefer direct argv mode:

{
  "operationId":"command-001",
  "program":"npm",
  "args":["run","typecheck"],
  "workingDirectory":".",
  "environment":{"CI":"1"},
  "tty":false
}

Only use Shell mode for syntax such as pipes, redirection, or loops:

{
  "operationId":"command-002",
  "shell":true,
  "command":"npm test | tee test.log"
}

If a process remains live, poll with read_process_output(sessionId). DevSpace owns the wait and output budgets. Use write_stdin with a fresh operation ID only for input, close, or interrupt. All process fields are camelCase.

Command directory validation is not an OS sandbox. The child has the file and network authority of the DevSpace OS user.

7. Maintain the Project-file handoff

For non-trivial work with Project write access, write or update a concise handoff after each meaningful phase. Use .agent/handoffs/<task-slug>.md unless the Project instructions specify another location. Record the objective, completed work, verification, blockers, and exact next steps. When the task is complete, update the same file with its final status and verification.

This handoff is part of the Project filesystem. It complements rather than replaces DevSpace saved progress, which supports recovery in a new ChatGPT conversation.

8. Save semantic progress

Save a concise summary before changing conversations or at a meaningful checkpoint:

{
  "operationId":"progress-001",
  "title":"Finish parser cleanup",
  "progress":"Re-read src/parser.ts and focused tests, then run typecheck."
}

The first save omits ifMatch. Later updates use the returned task.version. On a Task revision conflict, call list_projects(projectRef), reconcile the latest Task, then retry with the same operationId and current ifMatch. The result returns task.taskRef and may include private Thread metadata, but does not echo the summary. If the session binding is missing or stale after reauthorization, call list_projects, select tasks[].taskRef, and resume with a new operationId; do not infer a recent or sole Task. On resume, the summary appears once in checkpoint.untrustedSummary, separate from trusted checkpoint.serverObserved; reread relevant files and reconcile current Git state.

Automatic checkpoints also occur after completed foreground commands. They do not store raw command output or hidden reasoning.

9. Manage lifecycle in the Project App

The App-only project_thread_control shows Actor-private Thread listings and owns resolve, list, status, activity, pause, archive, complete, and close for those Threads. It does not manage the shared saved Task, and the model must not call it. Close refuses active operations and dirty managed worktrees; review or hand off changes first. Complete the saved Task and release resumable capacity with save_progress(status:"completed") from its active execution.

End-to-end loop

list_projects when needed
  → project_control open/resume
  → project_control hydrate until root instructions complete
  → skills search/load when relevant
  → read_files / inspect
  → apply_patch
  → show_changes(source: repository | apply_patch_history), then cursor-only pages
  → exec_command
  → read_process_output / write_stdin when needed
  → save_progress
  → Project App lifecycle controls when needed

Deployment, backend restart, service replacement, publication, and process termination are administrative actions outside this coding workflow and require an explicit user command.

See ChatGPT Tool Contract for the normative contract.