Gas City Native Agent Onboarding Playbook¶

Status: Active Playbook
Authority: BluCity-Docs/Engineering-Standard/operating-model/factory-operating-contract.md
Upstream Reference: docs.gascity.com/guides/configuring-an-agent

1. Purpose¶

This playbook governs how standing agents and specialist sessions are onboarded and configured in Gas City using native primitives. Agents are modeled along five orthogonal axes without custom model routers or proprietary provider abstractions.

2. The Five Native Agent Axes¶

Every agent configuration in city.toml or portable pack declarations (pack.toml) MUST declare its profile across five native axes:

Axis	Scope	Description	Supported Options / Values
1. HARNESS	Per Agent	Agent CLI harness	`claude`, `codex`, `opencode`, `gemini`, `cursor`, `copilot`
2. MODEL	Per Agent	Selected LLM model	`claude-3-7-sonnet`, `qwen3-coder:30b`, `gpt-4o`, etc.
3. UPSTREAM	Per Agent	Endpoint provider / gateway	Cloud provider, LiteLLM gateway, or local LM Studio (`http://blu.tailcf98b3.ts.net:1234`)
4. TRANSPORT	Per Agent	Driving mechanism	`exec`, `tmux`, `herdr`
5. RUNTIME	City / Environment-wide	Session execution environment	Host OS, Docker container, SSH remote

Do not collapse these into one field called provider. Use explicit terms: HARNESS, MODEL, UPSTREAM, TRANSPORT, RUNTIME.

3. Configuring Local LM Studio Upstream¶

To route low-cost, bulk, or classification work to local models via LM Studio:

Declare the upstream in city.toml:

[upstreams.lm-studio]
description = "Local LM Studio — qwen3-coder over Tailnet"
[upstreams.lm-studio.env]
OPENAI_BASE_URL = "http://blu.tailcf98b3.ts.net:1234/v1"
OPENAI_MODEL    = "qwen3-coder:30b"

Bind the agent or Polecat pool to the upstream:

[[agent]]
name = "polecat"
harness = "claude"
upstream = "lm-studio"

Secrets MUST remain environment variable references ($VAR), backed by 1Password (STD-AUTH-001 / AUTHENTICATE_ONCE=YES).

4. Onboarding Checklist for New Standing Agents¶

For every active agent onboarding:

[ ] AGENT= name specified in pack or city.toml
[ ] ROLE= functional responsibility documented
[ ] SCOPE= city (root) or rig (project-scoped)
[ ] HARNESS= selected CLI harness
[ ] MODEL= task-appropriate model
[ ] UPSTREAM= native upstream provider bound
[ ] TRANSPORT= session driver selected
[ ] RUNTIME= host/container runtime set
[ ] SECRET_REFERENCE= $VAR used, no plaintext tokens