BubbleBuffer/using-workspaces

Using Workspaces

Overview

OpenCode workspaces provide directory-level isolation for feature work. Each workspace gets its own directory (backed by git worktrees), enabling true parallel agent dispatch without file conflicts.

Core principle: Simple workspace creation + clean baseline verification = reliable isolation.

Announce at start: "I'm using the using-workspaces skill to set up an isolated workspace."

Base Branch Detection

1. Try Common Base Branches

git merge-base HEAD main 2>/dev/null && echo "main" || echo "master"

2. Ask if Ambiguous

If the repo has multiple potential base branches, ask:

Which branch should be the base for this feature?
1. main
2. master
3. Other (specify)

Creation Steps

1. Create Workspace

Call the workspace_create tool:

workspace_create(name="feature/<name>", base_branch="<detected-base>")

Where the name follows the pattern feature/<name> or fix/<name>.

The tool returns { id, name, directory }. Record the workspace id — you will need it for finishing-a-workspace.

2. Run Project Setup

Auto-detect and run appropriate setup in the workspace directory:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

3. Verify Clean Baseline

Run tests to ensure workspace starts clean:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

If tests fail: Report failures, ask whether to proceed or investigate.

If tests pass: Report ready.

4. Report Status

Workspace ready: <workspace-name>
Directory: <workspace-directory>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

| Situation | Action | |-----------|--------| | On main/master | Create workspace directly | | Already in a workspace | Already isolated, verify tests pass | | Tests fail during baseline | Report failures + ask | | No package.json/Cargo.toml | Skip dependency install |

Cleanup

To remove stale workspaces, use the workspace_clean tool:

workspace_clean(olderThanDays=7)

This removes workspaces older than the specified number of days. You can also target a specific workspace:

workspace_clean(workspaceId="<workspace-id>")

Run cleanup periodically or when workspace directories accumulate.

When NOT to Use

• Already working in an isolated workspace from a prior session
• Docs-only or scratch work the user has explicitly asked to perform on the current workspace
• Inside a subagent that inherits the controller's workspace context
• When the user has pinned the working workspace for the session

In those cases, verify the baseline instead of creating a new workspace.

Common Mistakes

Working on main/master

• Problem: Changes mix with main history
• Fix: Always create a workspace first

Skipping baseline tests

• Problem: Can't distinguish new bugs from pre-existing issues
• Fix: Report failures, get explicit permission to proceed

Example Workflow

You: I'm using the using-workspaces skill to set up an isolated workspace.

[Detect base branch: main]
[Create workspace: workspace_create("feature/auth", "main")]
[Run npm install]
[Run npm test - 47 passing]

Workspace ready: feature/auth
Directory: /home/user/project/.opencode/workspaces/feature-auth-abc123
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Red Flags

Never:

• Start implementation on main/master without explicit user consent
• Skip baseline test verification
• Proceed with failing tests without asking

Always:

• Create workspace first
• Verify clean test baseline
• Auto-detect and run project setup

Integration

Use after:

• brainstorming — once the design is approved and you are about to commit the spec or any planning artifact

Prerequisite for:

• writing-plans — plans must be authored in the workspace
• subagent-driven-development — tasks execute in the workspace created here
• Any skill that produces committed artifacts

Pairs with:

• finishing-a-workspace — handles the workspace once work is complete