houston

Houston

Multi-context autonomous development orchestrator for Claude Code. Dispatches development pipelines via agent-deck across multiple orgs, Linear workspaces, and source control platforms.

One command — research, plan, code (TDD), review, PR, CI monitor.

Quick Start

git clone https://github.com/yashiels/houston.git
cd houston
./scripts/install.sh

Then in any repo:

/houston SWITCH-167                        # from Linear ticket
/houston SWITCH-167 SWITCH-168 DEV-42      # multi-ticket (dependency-aware)
/houston Add retry logic to the webhook    # from prompt
/houston --spec tasks/retry-spec.md        # from spec file
/houston --from-plan tasks/plan.md         # from pre-approved plan
/houston status                            # running pipelines
/houston resume SWITCH-167                 # resume a crashed pipeline

How It Works

/houston SWITCH-167
        │
        ▼
   ┌─────────────┐     ┌──────────────┐
   │ Detect      │────▶│ Load Profile │ (stitch / personal)
   │ Context     │     │ + Credentials│
   └─────────────┘     └──────┬───────┘
                               │
        ┌──────────────────────┘
        ▼
   ┌─────────────┐
   │ agent-deck  │  launches tmux session
   │ launch      │  with credential isolation
   └──────┬──────┘
          │
          ▼
   ┌──────────────────────────────────────┐
   │        Orchestrator (orchestrate.sh) │
   │                                      │
   │  init → detect → baseline            │
   │    → RESEARCH → GRILL                │
   │    → [gate] → PLAN → GRILL           │
   │    → [gate] → PRE-FLIGHT             │
   │    → PHASE-1 → quality-gate          │
   │    → PHASE-2 → quality-gate          │
   │    → FINAL-REVIEW → CODE-SIMPLIFY    │
   │    → PR-CREATE → CI-MONITOR          │
   │    → LINEAR-UPDATE → complete        │
   │                                      │
   │  Each AI stage = disposable Claude   │
   │  State persisted to disk between     │
   └──────────────────────────────────────┘

Each ticket gets one agent-deck session visible in the TUI. The orchestrator shell script inside that session spawns fresh Claude sessions per stage — no context window exhaustion.

Profiles

Houston uses TOML profiles to manage multiple development contexts. Auto-detected from git remote.

# profiles/stitch.toml
[profile]
name = "stitch"
priority = 10

[identity]
name = "Yashiel Sookdeo"
email = "[email protected]"

[linear]
api_key_env = "LINEAR_API_KEY"
org = "Stitch"
default_team = "Card - Switch"

[reviewers.github]
"stitch-Money/*" = ["damgene", "jeremy-stitch", "shivekiyer"]

[reviewers.gitlab]
"pos/exi-terminal-*" = ["talha535", "pratham.patel", "christopher.cann"]
"*" = ["michael.willans", "shivekiyer", "jamesmaina"]

[detect]
remote_patterns = ["stitch", "exipay"]

Profile detection: git remote URL → match against remote_patterns → load credentials, reviewers, Linear workspace. If ambiguous, highest priority wins.

Pipeline Modes

Mode	Behavior	Use case
Supervised (default)	Pauses at research + plan gates for review	New repos, complex tickets
Autonomous	No gates, alerts only on BLOCKED	Known codebases, routine work
Human-assisted	Pauses at every phase gate	Critical work, learning a codebase

Multi-Ticket Dispatch

/houston SWITCH-167 SWITCH-168 DEV-42

Houston looks up all tickets in Linear, checks for dependency relations (blocks/blocked-by), and:

• Launches independent tickets in parallel
• Sequences dependent tickets automatically
• Works across Linear workspaces (tries each API key)

Quality Gates

Three tiers of increasing rigor, with baseline diffing (pre-existing failures warn, new failures block):

Tier	Runs when	Checks
Story	After each story	Unit tests, typecheck, anti-pattern scan
Phase	After each phase	Full tests, build, lint
Final	Before PR creation	Everything + E2E, docker, security scan

Agent Templates

Each pipeline stage uses a disposable Claude session with a focused prompt template:

Template	Role
researcher.md	Audit codebase before development
planner.md	Convert spec → phased implementation plan (prd.json)
coder.md	TDD implementation per story
phase-supervisor.md	Manage one phase, spawn coders, detect drift
grill-research.md	Adversarial review of research findings
grill-plan.md	Adversarial review of implementation plan
reviewer.md	Phase quality review
final-review.md	E2E review before PR
code-simplify.md	Post-implementation cleanup

Stack Detection

Auto-detects 13+ tech stacks and their tooling: