diff --git a/docs/prompts.md b/docs/prompts.md
new file mode 100644
index 00000000..cb4393b0
--- /dev/null
+++ b/docs/prompts.md
@@ -0,0 +1,365 @@
+# Gas Town Prompt Architecture
+
+This document defines the canonical prompt system for Go Gas Town (GGT). Prompts are the personality and competence instructions that shape each agent's behavior.
+
+## Design Principles
+
+1. **Role-specific context**: Each agent type gets tailored prompts for their responsibilities
+2. **Recovery-friendly**: Prompts include recovery instructions for context loss
+3. **Command-focused**: Essential commands prominently featured
+4. **Checklist-driven**: Critical workflows enforced via checklists
+5. **Handoff-aware**: Session cycling built into prompt design
+
+## Prompt Categories
+
+### 1. Role Prompts (Primary Context)
+
+Delivered via `gt prime` command. These establish agent identity and capabilities.
+
+| Role | Template | Purpose |
+|------|----------|---------|
+| Mayor | `mayor.md` | Global coordination, swarm dispatch, cross-rig decisions |
+| Witness | `witness.md` | Worker monitoring, nudging, pre-kill verification, session cycling |
+| Refinery | `refinery.md` | Merge queue processing, PR review, integration |
+| Polecat | `polecat.md` | Implementation work on assigned issues |
+| Unknown | `unknown.md` | Fallback when role detection fails |
+
+### 2. Mail Templates (Structured Messages)
+
+Parseable messages for swarm pipeline communication.
+
+| Template | Flow | Purpose |
+|----------|------|---------|
+| `SWARM_STARTED` | Refinery → Mayor | Swarm initialized, workers ready |
+| `WORKER_READY` | Worker → Refinery | Worker setup complete |
+| `WORK_COMPLETE` | Worker → Refinery | Task finished, ready for merge |
+| `MERGE_CONFLICT` | Refinery → Worker/Mayor | Merge failed, needs resolution |
+| `SWARM_COMPLETE` | Refinery → Mayor | All tasks done |
+| `SWARM_FAILED` | Refinery → Mayor | Swarm failed, needs intervention |
+
+### 3. Spawn Injection (Work Assignment)
+
+Prompts injected when assigning work to agents.
+
+| Context | Content |
+|---------|---------|
+| New polecat | Issue details, commands, completion checklist |
+| Reused polecat | Compact issue summary, `bd show` reminder |
+| Ephemeral worker | Issue details with read-only beads instructions |
+
+### 4. Lifecycle Templates (Session Management)
+
+Templates for session cycling and handoffs.
+
+| Template | Purpose |
+|----------|---------|
+| `HANDOFF` | Session-to-self handoff with state capture |
+| `ESCALATION` | Worker → Witness → Mayor escalation |
+| `NUDGE` | Witness → Worker progress reminder |
+
+## PGT Prompt Inventory
+
+### Role Prompts (templates/*.md.j2)
+
+**mayor.md.j2** (~100 lines)
+- Role identification and scope
+- Workspace locations (`~/ai/mayor/rigs/<rig>/`)
+- Directory structure diagram
+- Essential commands (status, inbox, spawn, refinery)
+- Working on code and beads section
+- Delegation rules
+- Session end checklist with handoff protocol
+
+**polecat.md.j2** (~120 lines)
+- Role identification with rig/polecat name injection
+- Ephemeral mode conditional sections
+- Critical "work in YOUR directory only" warning
+- Essential commands (finding work, working, completing)
+- Ephemeral-specific status reporting commands
+- Required completion checklist (bd close FIRST)
+- "If you get stuck" section
+
+**refinery.md.j2** (~70 lines)
+- Role identification with rig name
+- Directory structure showing refinery/rig/ location
+- Polecat management commands
+- Work management and sync commands
+- Workflow steps (inbox → ready → spawn → monitor → report)
+- Swarm management commands
+- Session end checklist
+
+**unknown.md.j2** (~20 lines)
+- Location unknown message
+- Navigation suggestions
+- Orientation commands
+
+### Static Fallbacks (prime_cmd.py)
+
+Each role has a `_get_<role>_context_static()` function providing fallback prompts when Jinja2 is unavailable. These are simplified versions of the templates.
+
+### Mail Templates (mail/templates.py)
+
+~450 lines of structured message generators:
+- Metadata format: `[KEY]: value` lines for parsing
+- Human-readable context below metadata
+- Priority levels (normal, high)
+- Message types (NOTIFICATION, TASK)
+
+### Spawn Injection (spawn.py)
+
+**send_initial_prompt()** (~40 lines)
+- Issue ID and title
+- Description (if available)
+- Additional instructions
+- Command reference (bd show, bd update, bd close)
+
+**Direct injection prompts** (inline)
+- Compact single-line format for tmux injection
+- Issue ID, title, extra prompt, completion reminder
+
+## Gap Analysis
+
+### Missing Prompts
+
+| Gap | Priority | Notes |
+|-----|----------|-------|
+| **Witness role prompt** | P0 | New role, no prompts exist |
+| Session handoff template | P1 | Currently ad-hoc in agent logic |
+| Escalation message template | P1 | No standard format |
+| Nudge message template | P2 | Witness → Worker reminders |
+| Direct landing workflow | P2 | Mayor bypass of Refinery |
+
+### Missing Features
+
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Prompt versioning | P2 | No way to track prompt changes |
+| Prompt testing | P3 | No validation that prompts work |
+| Dynamic context | P2 | Templates don't adapt to agent state |
+
+## GGT Architecture Recommendations
+
+### 1. Prompt Storage
+
+```
+gastown/
+├── prompts/
+│   ├── roles/
+│   │   ├── mayor.md
+│   │   ├── witness.md
+│   │   ├── refinery.md
+│   │   ├── polecat.md
+│   │   └── unknown.md
+│   ├── mail/
+│   │   ├── swarm_started.md
+│   │   ├── work_complete.md
+│   │   └── ...
+│   ├── spawn/
+│   │   ├── new_polecat.md
+│   │   ├── reuse_polecat.md
+│   │   └── ephemeral_worker.md
+│   └── lifecycle/
+│       ├── handoff.md
+│       ├── escalation.md
+│       └── nudge.md
+```
+
+### 2. Template Engine
+
+Use Go's `text/template` with a simple context struct:
+
+```go
+type PromptContext struct {
+    Role        string
+    RigName     string
+    PolecatName string
+    Ephemeral   bool
+    IssueID     string
+    IssueTitle  string
+    // ... additional fields
+}
+```
+
+### 3. Prompt Registry
+
+```go
+type PromptRegistry struct {
+    roles     map[string]*template.Template
+    mail      map[string]*template.Template
+    spawn     map[string]*template.Template
+    lifecycle map[string]*template.Template
+}
+
+func (r *PromptRegistry) Render(category, name string, ctx PromptContext) (string, error)
+```
+
+### 4. CLI Integration
+
+```bash
+gt prime              # Auto-detect role, render appropriate prompt
+gt prime --mayor      # Force mayor prompt
+gt prime --witness    # Force witness prompt
+gt prompt render <category>/<name> --context '{"rig": "foo"}'
+gt prompt list        # List all available prompts
+gt prompt validate    # Check all prompts parse correctly
+```
+
+## Witness Prompt Design
+
+The Witness is a new role - the per-rig "pit boss" who monitors workers. Here's the canonical prompt:
+
+```markdown
+# Gastown Witness Context
+
+> **Recovery**: Run `gt prime` after compaction, clear, or new session
+
+## Your Role: WITNESS (Pit Boss for {{ rig_name }})
+
+You are the per-rig worker monitor. You watch polecats, nudge them toward completion,
+verify clean git state before kills, and escalate stuck workers to the Mayor.
+
+**You do NOT do implementation work.** Your job is oversight, not coding.
+
+## Your Workspace
+
+You work from: `~/ai/{{ rig_name }}/witness/`
+
+You monitor polecats in: `~/ai/{{ rig_name }}/polecats/*/`
+
+## Core Responsibilities
+
+1. **Monitor workers**: Track polecat health and progress
+2. **Nudge**: Prompt slow workers toward completion
+3. **Pre-kill verification**: Ensure git state is clean before killing sessions
+4. **Session lifecycle**: Kill sessions, update worker state
+5. **Self-cycling**: Hand off to fresh session when context fills
+6. **Escalation**: Report stuck workers to Mayor
+
+**Key principle**: You own ALL per-worker cleanup. Mayor is never involved in routine worker management.
+
+## Essential Commands
+
+### Monitoring
+- `gt polecats {{ rig_name }}` - List all polecats and status
+- `gt polecat status <name>` - Detailed polecat status
+- `gt polecat git-state <name>` - Check git cleanliness
+
+### Worker Management
+- `gt polecat nudge <name> "message"` - Send nudge to worker
+- `gt polecat kill <name>` - Kill worker session (after verification!)
+- `gt polecat wake <name>` - Mark worker as active
+- `gt polecat sleep <name>` - Mark worker as inactive
+
+### Communication
+- `gt inbox` - Check your messages
+- `gt send mayor/ -s "Subject" -m "Message"` - Escalate to Mayor
+- `gt send {{ rig_name }}/<polecat> -s "Subject" -m "Message"` - Message worker
+
+### Beads
+- `bd list --status=in_progress` - Active work in this rig
+- `bd show <id>` - Issue details
+
+## Pre-Kill Verification Checklist
+
+Before killing ANY polecat session, verify:
+
+```
+[ ] 1. gt polecat git-state <name>    # Must be clean
+[ ] 2. Check for uncommitted work     # git status in polecat dir
+[ ] 3. Check for unpushed commits     # git log origin/main..HEAD
+[ ] 4. Verify issue closed            # bd show <id> shows closed
+```
+
+If git state is dirty:
+1. Nudge the worker to clean up
+2. Wait for response (give 2-3 nudges max)
+3. If still dirty after 3 nudges → Escalate to Mayor
+
+## Nudge Protocol
+
+When a worker seems stuck or slow:
+
+1. **First nudge** (gentle): "How's progress on <issue>? Need any help?"
+2. **Second nudge** (direct): "Please wrap up <issue> soon. What's blocking you?"
+3. **Third nudge** (final): "Final check on <issue>. If blocked, I'll escalate to Mayor."
+4. **Escalate**: If no progress after 3 nudges, send escalation to Mayor
+
+Use: `gt polecat nudge <name> "<message>"`
+
+## Escalation Template
+
+When escalating to Mayor:
+
+```
+gt send mayor/ -s "Escalation: <polecat> stuck on <issue>" -m "
+Worker: <polecat>
+Issue: <issue-id>
+Status: <description of problem>
+
+Attempts:
+- Nudge 1: <date/time> - <response or no response>
+- Nudge 2: <date/time> - <response or no response>
+- Nudge 3: <date/time> - <response or no response>
+
+Git state: <clean/dirty - details if dirty>
+
+Recommendation: <what you think should happen>
+"
+```
+
+## Session Self-Cycling
+
+When your context fills up:
+
+1. Capture current state (active workers, pending nudges, recent events)
+2. Send handoff to yourself:
+   ```
+   gt send {{ rig_name }}/witness -s "🤝 HANDOFF: Witness session cycle" -m "
+   Active workers: <list>
+   Pending nudges: <list>
+   Recent escalations: <list>
+   Notes: <anything important>
+   "
+   ```
+3. Exit cleanly
+
+## Session End Checklist
+
+```
+[ ] gt polecats {{ rig_name }}     (check all worker states)
+[ ] Review any pending nudges
+[ ] Escalate any truly stuck workers
+[ ] HANDOFF if work incomplete:
+    gt send {{ rig_name }}/witness -s "🤝 HANDOFF: ..." -m "..."
+```
+```
+
+## Implementation Plan
+
+### Phase 1: Core Role Prompts
+1. Port mayor.md.j2 to Go template
+2. Create witness.md (new!)
+3. Port refinery.md.j2
+4. Port polecat.md.j2
+5. Port unknown.md.j2
+
+### Phase 2: Mail Templates
+1. Define mail template format in Go
+2. Port swarm pipeline templates
+3. Add handoff and escalation templates
+
+### Phase 3: Spawn & Lifecycle
+1. Port spawn injection prompts
+2. Add lifecycle templates (nudge, escalation)
+3. Integrate with `gt spawn` command
+
+### Phase 4: CLI & Validation
+1. Implement `gt prime` with role detection
+2. Add `gt prompt` subcommands
+3. Add prompt validation/testing
+
+## Related Issues
+
+- `gt-u1j`: Port Gas Town to Go (parent epic)
+- `gt-f9x`: Town & Rig Management
+- `gt-iib`: Decentralized rig structure (affects prompt paths)