Workspace templates.

A workspace template is a group of agents you share as one. Import from GitHub and everything is ready to use.

What this is

Chapter 3 covered building a single agent. But most real products need several agents working together. A tax practice needs a bookkeeper, a document reviewer, and a client communicator. A sales team needs a lead researcher, an outreach agent, and a CRM manager.

A workspace template bundles multiple agents into one GitHub repo. When someone imports it, Houston creates a workspace with all the agents ready to go. No setup. No picking agents one by one.

Repo structure

A workspace template repo has a workspace.json at the root and an agents/ folder with one subfolder per agent.

my-workspace/
├── workspace.json
└── agents/
    ├── bookkeeper/
    │   ├── houston.json
    │   ├── CLAUDE.md
    │   └── icon.png
    ├── document-reviewer/
    │   ├── houston.json
    │   └── CLAUDE.md
    └── client-comms/
        ├── houston.json
        └── CLAUDE.md

Each agent subfolder follows the exact same format as a standalone agent repo (Chapter 3). The only addition is the workspace.json that ties them together.

The workspace.json

{
  "name": "Tax Practice",
  "description": "A complete workspace for tax professionals.",
  "agents": ["bookkeeper", "document-reviewer", "client-comms"]
}

Three fields. That's it.

Importing a workspace

1. In Houston, open the workspace switcher and click New workspace.
2. Switch to the Import from GitHub tab.
3. Paste the repo URL or owner/repo.
4. Click Import.

Houston downloads the workspace template, installs every agent definition, creates the workspace, and creates all agent instances with their CLAUDE.md and seed files. When it's done, you're looking at a workspace with every agent ready to chat.

If a workspace with the same name already exists, Houston appends "(imported)" to avoid conflicts.

Full example

Here's a complete workspace template for a small accounting firm. Three agents, each with its own prompt and tabs.

workspace.json

{
  "name": "Accounting Firm",
  "description": "Bookkeeping, tax prep, and client communication.",
  "agents": ["bookkeeper", "tax-prep", "client-comms"]
}

agents/bookkeeper/houston.json

{
  "id": "acme-bookkeeper",
  "name": "Bookkeeper",
  "description": "Categorize expenses and reconcile accounts.",
  "icon": "Calculator",
  "category": "business",
  "tabs": [
    { "id": "board", "label": "Tasks", "builtIn": "board", "badge": "activity" },
    { "id": "files", "label": "Files", "builtIn": "files" },
    { "id": "job-description", "label": "Instructions", "builtIn": "job-description" }
  ]
}

agents/bookkeeper/CLAUDE.md

# Bookkeeper

You categorize transactions, reconcile accounts, and flag
anomalies. Ask which period the user wants before starting.
Round to two decimal places. When unsure about a category, ask.

The other two agents follow the same pattern. Push the repo to GitHub. Anyone who imports it gets a workspace with three agents, each with its own instructions and tabs, ready to work.