gastown/CLAUDE.md

Claude: Gastown Go Port

Run bd prime for beads context.

Strategic Context

For broader project context and design guidance beyond Gas Town's immediate scope:

• Check ~/ai/stevey-gastown/hop/CONTEXT.md if available

This provides architectural direction for decisions that affect the platform's evolution.

Project Info

This is the Go port of Gas Town, a multi-agent workspace manager.

• Issue prefix: gt-
• Python version: ~/ai/gastown-py (reference implementation)
• Architecture: docs/architecture.md

Development

go build -o gt ./cmd/gt
go test ./...

Key Epics

• gt-u1j: Port Gas Town to Go (main tracking epic)
• gt-f9x: Town & Rig Management (install, doctor, federation)

Planning Work with Dependencies

When breaking down large features into tasks, use beads dependencies to sequence work - NOT phases or numbered steps.

Cognitive Trap: Temporal Language Inverts Dependencies

Words like "Phase 1", "Step 1", "first", "before" trigger temporal reasoning that flips dependency direction. Your brain thinks:

• "Phase 1 comes before Phase 2" → "Phase 1 blocks Phase 2" → bd dep add phase1 phase2

But that's backwards! The correct mental model:

• "Phase 2 depends on Phase 1" → bd dep add phase2 phase1

Solution: Use requirement language, not temporal language

Instead of phases, name tasks by what they ARE, and think about what they NEED:

# WRONG - temporal thinking leads to inverted deps
bd create "Phase 1: Create buffer layout" ...
bd create "Phase 2: Add message rendering" ...
bd dep add phase1 phase2  # WRONG! Says phase1 depends on phase2

# RIGHT - requirement thinking
bd create "Create buffer layout" ...
bd create "Add message rendering" ...
bd dep add msg-rendering buffer-layout  # msg-rendering NEEDS buffer-layout

Verification: After adding deps, run bd blocked - tasks should be blocked by their prerequisites, not their dependents.

Example breakdown (for a multi-part feature):

# Create tasks named by what they do, not what order they're in
bd create "Implement conversation region" -t task -p 1
bd create "Add header-line status display" -t task -p 1
bd create "Render tool calls inline" -t task -p 2
bd create "Add streaming content support" -t task -p 2

# Set up dependencies: X depends on Y means "X needs Y first"
bd dep add header-line conversation-region    # header needs region
bd dep add tool-calls conversation-region     # tools need region
bd dep add streaming tool-calls               # streaming needs tools

# Verify with bd blocked - should show sensible blocking
bd blocked