mirror of
https://github.com/Kilo-Org/kilocode.git
synced 2026-09-24 16:02:55 +08:00
docs(kilo-docs): write full content for all Gastown documentation pages
Flesh out all 7 sub-pages with comprehensive content: - Quick Start: town creation, PAT setup, first task flow - Concepts: towns, beads, convoys, rigs, agents, micro-adversarial loops - The Mayor: capabilities, tools, communication tips - Sling Work: single tasks, convoys, staged convoys, DAG execution - Code Review: refinery pipeline, adversarial loops, merge strategies - Settings: models, GitHub PAT, merge strategy, env vars, custom instructions - Troubleshooting: common failure modes and fixes Includes React Flow diagram placeholders (TODO comments) describing what each interactive diagram should visualize. Also moves Gastown nav link under Platforms section with sub-links and updates page title to 'Gas Town by Kilo'.
This commit is contained in:
John Fawcett
@@ -23,6 +23,19 @@ export const CodeWithAiNav: NavSection[] = [
|
||||
{ href: "/code-with-ai/platforms/mobile", children: "Mobile Apps" },
|
||||
{ href: "/code-with-ai/platforms/slack", children: "Slack" },
|
||||
{ href: "/code-with-ai/app-builder", children: "App Builder" },
|
||||
{
|
||||
href: "/code-with-ai/gastown",
|
||||
children: "Gas Town by Kilo",
|
||||
subLinks: [
|
||||
{ href: "/code-with-ai/gastown/quick-start", children: "Quick Start" },
|
||||
{ href: "/code-with-ai/gastown/concepts", children: "Concepts" },
|
||||
{ href: "/code-with-ai/gastown/mayor", children: "The Mayor" },
|
||||
{ href: "/code-with-ai/gastown/sling-work", children: "Sling Work" },
|
||||
{ href: "/code-with-ai/gastown/code-review", children: "Code Review" },
|
||||
{ href: "/code-with-ai/gastown/settings", children: "Settings" },
|
||||
{ href: "/code-with-ai/gastown/troubleshooting", children: "Troubleshooting" },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
@@ -62,19 +75,7 @@ export const CodeWithAiNav: NavSection[] = [
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: "Gastown",
|
||||
links: [
|
||||
{ href: "/code-with-ai/gastown", children: "Overview" },
|
||||
{ href: "/code-with-ai/gastown/quick-start", children: "Quick Start" },
|
||||
{ href: "/code-with-ai/gastown/concepts", children: "Concepts" },
|
||||
{ href: "/code-with-ai/gastown/mayor", children: "The Mayor" },
|
||||
{ href: "/code-with-ai/gastown/sling-work", children: "Sling Work" },
|
||||
{ href: "/code-with-ai/gastown/code-review", children: "Code Review" },
|
||||
{ href: "/code-with-ai/gastown/settings", children: "Settings" },
|
||||
{ href: "/code-with-ai/gastown/troubleshooting", children: "Troubleshooting" },
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
title: "Productivity Tools",
|
||||
links: [
|
||||
|
||||
@@ -5,16 +5,163 @@ description: "How the refinery agent reviews and merges code"
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: Review flow, merge strategies, approval gates -->
|
||||
Every piece of code produced by Gas Town agents goes through automated review before merging. The **refinery** agent is dedicated to critiquing, verifying, and gatekeeping what lands in your codebase.
|
||||
|
||||
## The Review Pipeline
|
||||
|
||||
When a polecat finishes a bead and pushes its branch, the work enters the review pipeline:
|
||||
|
||||
<!-- TODO: React Flow diagram — Review Pipeline
|
||||
Linear flow with decision points:
|
||||
|
||||
Polecat "pushes branch"
|
||||
→ MR bead created (status: open)
|
||||
→ Refinery dispatched (status: in_progress)
|
||||
→ Refinery reviews diff
|
||||
→ Decision: "Quality check"
|
||||
→ PASS: "Merge" → bead closed ✓
|
||||
→ FAIL: "Send feedback" → Polecat revises → Re-submit → (loop back to Refinery)
|
||||
|
||||
Show retry counter on the loop (max 3 attempts)
|
||||
Caption: "The review pipeline — code must pass refinery review before merging"
|
||||
-->
|
||||
|
||||
The refinery evaluates:
|
||||
- **Correctness** — does the code do what the task asked?
|
||||
- **Style** — does it follow project conventions?
|
||||
- **Completeness** — are tests included? Are edge cases handled?
|
||||
- **Safety** — any security issues, data leaks, or breaking changes?
|
||||
|
||||
## Micro-Adversarial Loops
|
||||
|
||||
The core insight behind Gas Town's review system is **adversarial iteration**. Rather than one agent producing a final answer, two agents with different objectives improve the output through tension:
|
||||
|
||||
<!-- TODO: React Flow diagram — Adversarial Loop Detail
|
||||
Circular/orbital layout showing the tension:
|
||||
|
||||
Center: "The Code" (evolving artifact)
|
||||
|
||||
Orbit 1 (Polecat, blue):
|
||||
Goal: "Ship the feature" → writes code → pushes
|
||||
|
||||
Orbit 2 (Refinery, amber):
|
||||
Goal: "Protect quality" → reviews → sends feedback OR approves
|
||||
|
||||
Connection: feedback arrow from Refinery back to Polecat with example text:
|
||||
"Missing error handling in the catch block. The API endpoint should return
|
||||
a structured error response, not swallow the exception."
|
||||
|
||||
Polecat then: "Revises with feedback" → pushes again → Refinery re-reviews
|
||||
|
||||
Style: animated orbital, showing the push-pull dynamic
|
||||
Caption: "Adversarial tension between 'ship it' and 'make it better'"
|
||||
-->
|
||||
|
||||
This pattern is fundamentally different from having a single agent self-review:
|
||||
- Self-review has a **confirmation bias** — the same "mind" that wrote the code evaluates it
|
||||
- Adversarial review creates **genuine tension** — the refinery has different priorities than the polecat
|
||||
- Each revision cycle **measurably improves** the output because feedback is specific and actionable
|
||||
|
||||
### The Loop in Practice
|
||||
|
||||
A typical bead goes through 1-2 revision cycles:
|
||||
|
||||
| Cycle | What happens |
|
||||
|---|---|
|
||||
| **Write** | Polecat reads the task, writes code, runs tests, pushes |
|
||||
| **Review 1** | Refinery finds 2 issues: missing test case, inconsistent naming |
|
||||
| **Revise 1** | Polecat adds the test, fixes naming, pushes again |
|
||||
| **Review 2** | Refinery approves — code meets quality bar |
|
||||
| **Merge** | Code lands on target branch |
|
||||
|
||||
After 3 failed revision cycles, the bead escalates rather than looping forever.
|
||||
|
||||
## Merge Strategies
|
||||
|
||||
Gas Town supports two merge strategies, configurable per-town or per-rig:
|
||||
|
||||
### Direct Merge
|
||||
|
||||
The refinery merges directly to the target branch (convoy feature branch or main) without creating a GitHub PR. This is faster but gives you less visibility into individual merges.
|
||||
|
||||
**Best for:** trusted agent output, internal projects, rapid iteration.
|
||||
|
||||
### Pull Request Mode
|
||||
|
||||
The refinery creates a GitHub PR for each merge. The PR includes:
|
||||
- The diff
|
||||
- Review comments from the refinery
|
||||
- Status checks from CI
|
||||
|
||||
You can configure whether PRs auto-merge after refinery approval or require human approval.
|
||||
|
||||
**Best for:** production codebases, team environments, audit trails.
|
||||
|
||||
## Convoy-Level Review
|
||||
|
||||
Convoys add an additional review layer beyond per-bead review:
|
||||
|
||||
<!-- TODO: React Flow diagram — Convoy Review Layers
|
||||
Three columns showing review at different scopes:
|
||||
|
||||
Column 1 "Per-Bead Review":
|
||||
Bead 1 → Refinery ✓
|
||||
Bead 2 → Refinery ✓
|
||||
Bead 3 → Refinery ✓ (with one revision cycle shown)
|
||||
|
||||
Column 2 "Landing Review":
|
||||
Combined diff (all 3 beads) → Refinery reviews holistically
|
||||
"Does the combined work make sense as a feature?"
|
||||
|
||||
Column 3 "Human Review" (optional):
|
||||
Final PR to main → Your team reviews
|
||||
|
||||
Caption: "Three layers of review — individual, combined, and human"
|
||||
-->
|
||||
|
||||
| Review Layer | What's checked | Who reviews |
|
||||
|---|---|---|
|
||||
| Per-bead | Individual contribution quality | Refinery agent |
|
||||
| Landing | Combined feature coherence | Refinery agent |
|
||||
| Human (optional) | Business logic, architecture | Your team |
|
||||
|
||||
## Combining with Kilo Code Review
|
||||
|
||||
Gas Town's refinery works independently, but combining it with [Kilo Code Review](/code-with-ai/platforms/cloud-agent) creates an even stronger pipeline:
|
||||
|
||||
1. **Agent writes** → agent-level refinery reviews (fast, automated)
|
||||
2. **Code lands as PR** → Kilo Code Review provides human-readable review (deeper, contextual)
|
||||
3. **Human approves** → code ships
|
||||
|
||||
This gives you automated adversarial review for speed **plus** AI-assisted human review for judgment — the best of both approaches.
|
||||
|
||||
## Review Configuration
|
||||
|
||||
Customize the refinery's behavior in **Town Settings** → **Review**:
|
||||
|
||||
| Setting | Options | Default |
|
||||
|---|---|---|
|
||||
| `review_mode` | `always` / `never` / `pr_only` | `always` |
|
||||
| `merge_strategy` | `direct` / `pr` | `direct` |
|
||||
| `auto_merge` | `true` / `false` | `true` |
|
||||
| `review_gates` | Strictness level (1-5) | 3 |
|
||||
| `max_review_cycles` | How many revision attempts | 3 |
|
||||
|
||||
### Review Mode
|
||||
|
||||
- **`always`** — every bead goes through refinery review (recommended)
|
||||
- **`never`** — skip review, merge directly on polecat completion (fast but risky)
|
||||
- **`pr_only`** — only review work that creates a PR
|
||||
|
||||
### Review Gates
|
||||
|
||||
Higher gate levels make the refinery stricter:
|
||||
- **Level 1** — basic sanity (compiles, doesn't break tests)
|
||||
- **Level 3** — standard (style, tests, correctness) — default
|
||||
- **Level 5** — strict (architecture review, performance, security)
|
||||
|
||||
## Handling Review Feedback
|
||||
|
||||
When the refinery rejects a submission, it provides specific, actionable feedback. The polecat receives this feedback and revises accordingly. You can see the feedback exchange in the bead's event history.
|
||||
|
||||
If a bead fails review 3 times, it transitions to `failed` and creates an **escalation** for human attention. This prevents infinite loops while ensuring difficult code doesn't slip through without proper quality.
|
||||
|
||||
@@ -1,24 +1,193 @@
|
||||
---
|
||||
title: "Concepts"
|
||||
description: "Understand the building blocks of Gastown — towns, beads, convoys, rigs, and agents"
|
||||
description: "Understand the building blocks of Gas Town — towns, beads, convoys, rigs, and agents"
|
||||
---
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: Detailed explanation of each concept with diagrams -->
|
||||
Gas Town by Kilo is built around a small set of composable primitives. Understanding these concepts is key to getting the most out of agent orchestration.
|
||||
|
||||
## Towns
|
||||
|
||||
A **town** is a persistent workspace where agents operate on your code. It maintains:
|
||||
|
||||
- **Configuration** — models, merge strategy, review settings, custom instructions
|
||||
- **Agent state** — which agents exist, what they're working on, their capabilities
|
||||
- **Work history** — every bead that's been created, worked on, reviewed, and closed
|
||||
- **Rig connections** — which repositories are connected and how they're configured
|
||||
|
||||
Think of a town as a team's workspace — it accumulates institutional knowledge over time. Agents in your town learn from the history of what's been built, reviewed, and merged.
|
||||
|
||||
A town can be personal (owned by you) or organizational (shared across a team).
|
||||
|
||||
## Beads
|
||||
|
||||
A **bead** is the fundamental unit of work. Every task, review, and coordination action is represented as a bead with a lifecycle:
|
||||
|
||||
<!-- TODO: React Flow diagram — Bead Lifecycle
|
||||
Nodes: open → in_progress → in_review → closed
|
||||
With branch for: open → in_progress → failed
|
||||
And loop: in_review → open (when review rejects)
|
||||
Style: horizontal flow, status-colored nodes (green=closed, blue=in_progress, amber=in_review, red=failed)
|
||||
-->
|
||||
|
||||
| Status | What's happening |
|
||||
|---|---|
|
||||
| `open` | Waiting to be picked up by an agent |
|
||||
| `in_progress` | An agent is actively working on it |
|
||||
| `in_review` | Work is complete, awaiting review by the refinery |
|
||||
| `closed` | Successfully completed and merged |
|
||||
| `failed` | Could not be completed (agent exhausted retries) |
|
||||
|
||||
### Bead Types
|
||||
|
||||
| Type | Purpose |
|
||||
|---|---|
|
||||
| `issue` | A coding task — bug fix, feature, refactor |
|
||||
| `merge_request` | A review task for the refinery |
|
||||
| `convoy` | A container for multi-step workflows |
|
||||
| `escalation` | An issue the agents couldn't resolve — needs human input |
|
||||
| `message` | Inter-agent communication |
|
||||
|
||||
## Convoys
|
||||
|
||||
A **convoy** is a multi-bead workflow where tasks can depend on each other. Instead of slinging isolated tasks, convoys let you express complex work as a directed graph.
|
||||
|
||||
<!-- TODO: React Flow diagram — Convoy DAG Example
|
||||
Nodes:
|
||||
"Explore codebase" (closed) → "Design schema" (closed) → "Implement API" (in_progress)
|
||||
"Design schema" (closed) → "Write tests" (open)
|
||||
"Implement API" → "Integration tests" (open)
|
||||
Style: DAG layout, edges showing dependencies, node colors by status
|
||||
Caption: "A convoy executing a 5-bead feature implementation"
|
||||
-->
|
||||
|
||||
When you create a convoy, you define:
|
||||
- **Tasks** — what needs to be done (each becomes a bead)
|
||||
- **Dependencies** — which tasks must complete before others can start
|
||||
- **Feature branch** — a shared branch that convoy work lands on
|
||||
|
||||
The reconciler ensures beads are only dispatched when their dependencies are met. This means agents naturally build on each other's work.
|
||||
|
||||
### Staged Convoys
|
||||
|
||||
Convoys can be **staged** — created but not started immediately. This lets you review the plan before agents begin executing. Un-stage when you're ready to go.
|
||||
|
||||
## Rigs
|
||||
|
||||
A **rig** connects a repository to your town. Each rig has:
|
||||
|
||||
- Its own set of agents (polecats, refinery)
|
||||
- Branch configuration (default branch, merge target)
|
||||
- Override settings (model, review mode, merge strategy)
|
||||
|
||||
A town can have **multiple rigs** — useful when your project spans several repositories.
|
||||
|
||||
## Agents
|
||||
|
||||
Agents are the workers in your town. Each has a specialized role:
|
||||
|
||||
### Polecats (Coding Agents)
|
||||
|
||||
Polecats do the actual software engineering:
|
||||
|
||||
- Read and understand your codebase
|
||||
- Write code changes in isolated git worktrees
|
||||
- Run tests and commands to verify their work
|
||||
- Push branches when done
|
||||
|
||||
Multiple polecats can work in **parallel** on different beads. The default is 2 per rig, configurable up to 5+.
|
||||
|
||||
Each polecat gets its own git worktree — they never conflict with each other or with your local development.
|
||||
|
||||
### The Refinery (Review Agent)
|
||||
|
||||
The refinery is the quality gate. When a polecat finishes a bead:
|
||||
|
||||
1. The refinery reviews the diff
|
||||
2. Checks for issues, style violations, missing tests
|
||||
3. Either **approves and merges** or **sends feedback**
|
||||
4. If feedback is sent, the polecat revises and resubmits
|
||||
|
||||
This creates a **micro-adversarial loop** — one agent writes, another critiques, forcing iterative improvement before code lands.
|
||||
|
||||
<!-- TODO: React Flow diagram — Micro-Adversarial Loop
|
||||
Circular flow:
|
||||
Polecat "writes code" → Refinery "reviews" → (approve) → "merge"
|
||||
→ (reject) → Polecat "revises" → Refinery "reviews" (loop back)
|
||||
Style: circular/orbital layout, animated edges showing the loop,
|
||||
highlight the adversarial tension between write and review
|
||||
Caption: "The micro-adversarial loop — code is critiqued before it lands"
|
||||
-->
|
||||
|
||||
### The Mayor (Coordination Agent)
|
||||
|
||||
The mayor is your interface to the town:
|
||||
|
||||
- Plans convoys from high-level descriptions
|
||||
- Reports on status and progress
|
||||
- Triages issues and escalations
|
||||
- Manages agent configuration
|
||||
- Answers questions about the codebase and work history
|
||||
|
||||
The mayor runs persistently — always available for conversation.
|
||||
|
||||
## The Reconciler
|
||||
|
||||
The reconciler is the engine that drives the town forward. It runs on every alarm tick (every 5 seconds when work is active) and:
|
||||
|
||||
1. **Drains events** — agent completions, status changes, failures
|
||||
2. **Evaluates rules** — which beads need agents, which convoys are ready to advance
|
||||
3. **Emits actions** — dispatch an agent, create a review, update convoy progress
|
||||
4. **Enforces invariants** — no double-dispatch, no orphaned hooks, bounded retries
|
||||
|
||||
You don't interact with the reconciler directly — it's the autonomous engine that keeps the town moving.
|
||||
|
||||
## The Micro-Adversarial Loop
|
||||
|
||||
The most powerful concept in Gas Town is the **micro-adversarial loop**. Rather than trusting a single agent's output, every piece of work goes through an adversarial cycle:
|
||||
|
||||
<!-- TODO: React Flow diagram — Full Adversarial Pipeline
|
||||
Multi-lane flow showing:
|
||||
Lane 1 (Polecat): "Read task" → "Write code" → "Run tests" → "Push branch"
|
||||
Lane 2 (Refinery): "Review diff" → decision diamond "Quality?"
|
||||
→ Yes: "Merge to target"
|
||||
→ No: "Send feedback" → (back to Polecat "Revise")
|
||||
Lane 3 (Convoy level): Multiple beads flowing through the pipeline in sequence,
|
||||
each one building on the merged output of the previous
|
||||
|
||||
Caption: "Every bead goes through write → review → revise cycles before landing"
|
||||
-->
|
||||
|
||||
This pattern compounds when combined with **convoys**:
|
||||
|
||||
1. Bead 1: Explore the codebase → reviewed → merged to convoy branch
|
||||
2. Bead 2: Design the schema (builds on bead 1's context) → reviewed → merged
|
||||
3. Bead 3: Implement the feature (builds on beads 1+2) → reviewed → merged
|
||||
4. **Landing review**: The full convoy branch is reviewed as a cohesive unit before merging to main
|
||||
|
||||
At every stage, work is critiqued and refined. Combined with Kilo's [Code Review](/code-with-ai/gastown/code-review) product, this creates a pipeline where code is reviewed multiple times by different agents with different perspectives before it ever reaches your main branch.
|
||||
|
||||
## How It All Fits Together
|
||||
|
||||
<!-- TODO: React Flow diagram — Full Town Architecture
|
||||
Shows the complete flow:
|
||||
User → Mayor (chat) → creates Convoy/Beads
|
||||
Reconciler (center, engine) → dispatches Polecats
|
||||
Polecat → pushes branch → Refinery reviews → merges
|
||||
Container (wrapping polecats) with git worktrees
|
||||
Rig connecting to GitHub repo
|
||||
|
||||
Style: similar to the Connect talk architecture diagram but simplified for docs
|
||||
Caption: "The complete Gas Town architecture"
|
||||
-->
|
||||
|
||||
| Component | Responsibility |
|
||||
|---|---|
|
||||
| **You** | Describe work, review PRs, set direction |
|
||||
| **Mayor** | Plan, coordinate, communicate |
|
||||
| **Reconciler** | Schedule, dispatch, enforce rules |
|
||||
| **Polecats** | Write code, run tests, push branches |
|
||||
| **Refinery** | Review, critique, merge |
|
||||
| **Container** | Isolated environment with git, tools, runtime |
|
||||
| **Rig** | Repository connection and configuration |
|
||||
|
||||
@@ -1,36 +1,103 @@
|
||||
---
|
||||
title: "Gastown"
|
||||
title: "Gas Town by Kilo"
|
||||
description: "Autonomous AI agent orchestration for your codebase"
|
||||
---
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
Gastown is an autonomous agent orchestration platform that manages multiple AI agents working on your codebase. It coordinates polecats (coding agents), a refinery (code review agent), and a mayor (coordination agent) to handle tasks, code reviews, and merges — all without constant human oversight.
|
||||
Gastown by Kilo is an autonomous agent orchestration platform that manages teams of AI agents working on your codebase. Built on [Gastown](https://gastown.dev) — the open protocol for agent orchestration — Kilo's implementation coordinates coding agents, a code review agent, and a conversational coordinator to ship features, fix bugs, and maintain your projects with minimal human intervention.
|
||||
|
||||
## Core Concepts
|
||||
You describe the work. Agents figure out how to do it, write the code, review each other's output, and land clean PRs — while you stay in control of what ships.
|
||||
|
||||
- **Towns** — A workspace that connects to your repository and manages agents working on it
|
||||
- **Beads** — Units of work (issues, tasks, reviews) that agents pick up and complete
|
||||
- **Convoys** — Multi-step workflows that chain beads together in a dependency graph
|
||||
- **Rigs** — Repository connections within a town, each with their own agents and configuration
|
||||
- **The Mayor** — Your primary interface to the town; a conversational agent that coordinates work and answers questions
|
||||
<!-- TODO: Screenshot — town overview page showing active agents, beads in progress, and a recent merge -->
|
||||
|
||||
## What Makes Gastown Different
|
||||
|
||||
Unlike single-agent coding tools that handle one task at a time, Gastown orchestrates **multiple specialized agents** working in parallel:
|
||||
|
||||
| Agent | Role | What it does |
|
||||
|---|---|---|
|
||||
| **Polecats** | Coding | Write code, run tests, push branches. Multiple can work simultaneously on different tasks. |
|
||||
| **Refinery** | Code Review | Reviews polecat output, runs quality checks, merges approved work. |
|
||||
| **Mayor** | Coordination | Your conversational interface. Plans work, answers questions, triages issues, keeps things moving. |
|
||||
|
||||
These agents operate within a **town** — a persistent workspace connected to your repository. The town maintains state across sessions: work history, agent configuration, and institutional knowledge about your codebase.
|
||||
|
||||
<!-- TODO: Screenshot — the mayor chat interface showing a conversation about planning work -->
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Create a town** and connect it to your repository
|
||||
2. **Sling work** — describe what you need done, and agents autonomously pick it up
|
||||
3. **Agents collaborate** — polecats write code, the refinery reviews and merges, the mayor coordinates
|
||||
4. **You stay in control** — review PRs, adjust settings, intervene when needed
|
||||
### 1. Create a town
|
||||
|
||||
Connect a GitHub repository to a new town. Gastown provisions a dedicated environment with agents ready to work.
|
||||
|
||||
### 2. Sling work
|
||||
|
||||
Describe what needs to be done — a bug to fix, a feature to build, a refactor to execute. You can sling a single task or a **convoy** (a multi-step plan where tasks depend on each other).
|
||||
|
||||
<!-- TODO: Screenshot — the "Sling Work" dialog or the convoy creation UI -->
|
||||
|
||||
### 3. Agents pick it up
|
||||
|
||||
The reconciler assigns open work to available polecats. Each agent gets its own git worktree, writes code, runs commands, and pushes a branch when done.
|
||||
|
||||
### 4. Code gets reviewed
|
||||
|
||||
Completed work flows to the refinery for automated code review. Depending on your merge strategy, the refinery either merges directly or creates a PR for your approval.
|
||||
|
||||
### 5. You stay in control
|
||||
|
||||
Monitor progress from the town dashboard. Chat with the mayor. Review PRs. Adjust priorities. Intervene when agents need guidance. Everything the agents do is visible — branches, commits, review comments, and decision reasoning.
|
||||
|
||||
<!-- TODO: Screenshot — beads page showing a mix of closed, in-progress, and open beads -->
|
||||
|
||||
## Core Concepts
|
||||
|
||||
| Concept | What it is |
|
||||
|---|---|
|
||||
| **Town** | A persistent workspace connecting your repo to a team of agents. Maintains configuration, history, and state. |
|
||||
| **Bead** | A unit of work — an issue to fix, a task to complete, a review to perform. Beads have a lifecycle: open, in progress, in review, closed. |
|
||||
| **Convoy** | A multi-bead workflow. Beads within a convoy can depend on each other, forming a DAG that agents execute in order. |
|
||||
| **Rig** | A repository connection within a town. Each rig has its own branch configuration, agents, and settings. A town can have multiple rigs. |
|
||||
| **Mayor** | The coordination agent. Your primary interface for interacting with the town through natural language. |
|
||||
| **Polecat** | A coding agent. Works on individual beads — reads code, makes changes, runs tests, pushes branches. |
|
||||
| **Refinery** | The review agent. Checks polecat output for quality, performs merges, and gates what lands in your codebase. |
|
||||
|
||||
For a deeper dive, see [Concepts](/code-with-ai/gastown/concepts).
|
||||
|
||||
## The Mayor — Your Interface to the Town
|
||||
|
||||
The mayor is how you interact with Gastown conversationally. Think of it as a technical lead that knows your codebase, tracks what all agents are doing, and can take action on your behalf.
|
||||
|
||||
You can ask the mayor to:
|
||||
|
||||
- Plan and create convoys from high-level descriptions
|
||||
- Check on the status of in-progress work
|
||||
- Investigate failures and stuck agents
|
||||
- Update town settings and configuration
|
||||
- Triage incoming issues or bug reports
|
||||
|
||||
The mayor runs persistently in your town — it's always available, even when no coding agents are active.
|
||||
|
||||
<!-- TODO: Screenshot — mayor conversation showing it creating a convoy from a user request -->
|
||||
|
||||
## What You Can Build With Gastown
|
||||
|
||||
- **Feature development** — Describe a feature, get back a PR with tests
|
||||
- **Bug fixes** — Point agents at an issue, they investigate and fix it
|
||||
- **Refactoring** — Large-scale codebase changes executed methodically across convoys
|
||||
- **Maintenance** — Dependency updates, lint fixes, documentation generation
|
||||
- **Code review** — Automated first-pass review on all agent and human PRs
|
||||
|
||||
## Getting Started
|
||||
|
||||
- [Quick Start](/code-with-ai/gastown/quick-start) — Get your first town running in minutes
|
||||
- [Concepts](/code-with-ai/gastown/concepts) — Understand towns, beads, convoys, and agents
|
||||
- [The Mayor](/code-with-ai/gastown/mayor) — How to interact with your town's coordinator
|
||||
- [Quick Start](/code-with-ai/gastown/quick-start) — Create your first town and see agents work in under 5 minutes
|
||||
- [Concepts](/code-with-ai/gastown/concepts) — Detailed explanation of towns, beads, convoys, and the agent lifecycle
|
||||
- [The Mayor](/code-with-ai/gastown/mayor) — How to interact with the coordination agent effectively
|
||||
|
||||
## Guides
|
||||
|
||||
- [Sling Work](/code-with-ai/gastown/sling-work) — Creating tasks and convoys for agents
|
||||
- [Code Review](/code-with-ai/gastown/code-review) — How the refinery reviews and merges code
|
||||
- [Settings](/code-with-ai/gastown/settings) — Configure models, merge strategies, and agent behavior
|
||||
- [Sling Work](/code-with-ai/gastown/sling-work) — Creating tasks, convoys, and staged workflows
|
||||
- [Code Review](/code-with-ai/gastown/code-review) — Merge strategies, review gates, and the refinery pipeline
|
||||
- [Settings](/code-with-ai/gastown/settings) — Model configuration, agent limits, custom instructions, and environment variables
|
||||
- [Troubleshooting](/code-with-ai/gastown/troubleshooting) — Common issues and how to resolve them
|
||||
|
||||
@@ -5,12 +5,100 @@ description: "How to interact with your town's coordination agent"
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: Mayor capabilities, conversation patterns, commands -->
|
||||
The Mayor is your primary interface to a Gas Town. It's a persistent conversational agent that coordinates work, answers questions, and takes action on your behalf.
|
||||
|
||||
## What the Mayor Does
|
||||
|
||||
The Mayor operates as a technical lead that:
|
||||
|
||||
- **Plans work** — converts high-level descriptions into convoys and beads
|
||||
- **Reports status** — knows what every agent is doing, what's stuck, what's shipped
|
||||
- **Triages issues** — investigates failures, stuck agents, and escalations
|
||||
- **Configures the town** — updates settings, manages rigs, adjusts agent behavior
|
||||
- **Answers questions** — about the codebase, work history, and town state
|
||||
|
||||
Unlike polecats (which spin up to work on specific beads), the Mayor runs **persistently**. It's always available, even when no coding agents are active.
|
||||
|
||||
<!-- TODO: Screenshot — Mayor chat interface showing a multi-turn conversation -->
|
||||
|
||||
## Talking to the Mayor
|
||||
|
||||
## Mayor Commands
|
||||
Open the Mayor panel from your town dashboard. The conversation is persistent — the Mayor remembers context from previous messages within the same session.
|
||||
|
||||
### Planning Work
|
||||
|
||||
Ask the Mayor to create work for the town:
|
||||
|
||||
> *"Create a convoy to add authentication to the API. We need JWT token generation, middleware for protected routes, and integration tests."*
|
||||
|
||||
The Mayor will:
|
||||
1. Break this into individual beads with dependencies
|
||||
2. Propose a convoy plan for your review
|
||||
3. Create the convoy (staged by default, so you can review before agents start)
|
||||
|
||||
### Checking Status
|
||||
|
||||
> *"What's everyone working on?"*
|
||||
> *"Is anything stuck?"*
|
||||
> *"How did the last convoy go?"*
|
||||
|
||||
The Mayor has full visibility into agent state, bead progress, and recent history.
|
||||
|
||||
### Investigating Problems
|
||||
|
||||
> *"The auth refactor bead has been in progress for 20 minutes — what's happening?"*
|
||||
> *"Why did the refinery reject the last review?"*
|
||||
|
||||
The Mayor can inspect agent status messages, review feedback, and container logs to diagnose issues.
|
||||
|
||||
### Updating Configuration
|
||||
|
||||
> *"Switch the model to Claude Opus for this town"*
|
||||
> *"Set max polecats to 4"*
|
||||
> *"Add a custom instruction: always use TypeScript strict mode"*
|
||||
|
||||
The Mayor can modify town settings on your behalf through natural language.
|
||||
|
||||
## Mayor Tools
|
||||
|
||||
The Mayor has access to specialized tools for town management:
|
||||
|
||||
| Tool | What it does |
|
||||
|---|---|
|
||||
| `gt_sling` | Create a bead or convoy |
|
||||
| `gt_convoy_close` | Force-close a stuck convoy |
|
||||
| `gt_agent_reset` | Reset a stuck agent |
|
||||
| `gt_bead_delete` | Delete beads (single or bulk) |
|
||||
| `gt_report_bug` | File a bug report about town behavior |
|
||||
| `gt_done` | Mark work as complete |
|
||||
|
||||
These tools are used automatically when you make requests — you don't need to invoke them directly.
|
||||
|
||||
## Tips for Effective Communication
|
||||
|
||||
### Be specific about scope
|
||||
|
||||
Instead of: *"Fix the bugs"*
|
||||
|
||||
Try: *"Fix the TypeScript type errors in src/auth/. There are 3 reported in the CI output."*
|
||||
|
||||
### Use convoys for complex work
|
||||
|
||||
Instead of: *"Add a user dashboard with charts, settings, and notifications"*
|
||||
|
||||
Try: *"Create a staged convoy for the user dashboard. Break it into: 1) dashboard layout and navigation, 2) chart components with mock data, 3) settings page, 4) notification system. Each should build on the previous."*
|
||||
|
||||
### Let the Mayor triage
|
||||
|
||||
When something goes wrong, ask the Mayor before investigating yourself:
|
||||
|
||||
> *"Bead abc123 has been stuck for 30 minutes — can you investigate?"*
|
||||
|
||||
The Mayor can often diagnose and resolve issues (reset agents, close stuck convoys, re-dispatch work) without you needing to dig into the admin panel.
|
||||
|
||||
## Mayor Limitations
|
||||
|
||||
- The Mayor coordinates but doesn't write code itself — that's what polecats are for
|
||||
- It can only see what's happening inside your town, not external systems
|
||||
- Complex multi-repo orchestration may need manual coordination between towns
|
||||
- The Mayor's context window is bounded — very long conversations may lose early context
|
||||
|
||||
@@ -1,8 +1,88 @@
|
||||
---
|
||||
title: "Quick Start"
|
||||
description: "Get your first Gastown town running in minutes"
|
||||
description: "Get your first Gas Town running in minutes"
|
||||
---
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: Step-by-step guide to creating a town and seeing agents work -->
|
||||
This guide walks you through creating your first town, connecting a repository, and watching agents work on real code.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A [Kilo account](https://app.kilo.ai) (free tier works)
|
||||
- A GitHub repository you want agents to work on
|
||||
- A GitHub Personal Access Token (recommended)
|
||||
|
||||
## 1. Create a Town
|
||||
|
||||
From the Kilo dashboard, click **New Town**. Give it a name — this is just for your reference.
|
||||
|
||||
<!-- TODO: Screenshot — "New Town" button and creation dialog -->
|
||||
|
||||
## 2. Connect a Repository
|
||||
|
||||
Add a **rig** to your town. A rig is a connection to a specific repository.
|
||||
|
||||
1. Click **Add Rig**
|
||||
2. Select your GitHub repository (or paste the URL)
|
||||
3. Choose the default branch (usually `main`)
|
||||
4. Click **Connect**
|
||||
|
||||
Gastown uses the [Kilo GitHub App](https://github.com/apps/kilo-code) to access your repository. You'll be prompted to install it if you haven't already.
|
||||
|
||||
<!-- TODO: Screenshot — rig creation flow showing repo selection -->
|
||||
|
||||
## 3. Add a GitHub Personal Access Token
|
||||
|
||||
{% callout type="tip" title="Recommended" %}
|
||||
Adding a GitHub PAT means all commits, branches, and PRs created by your town's agents will appear as **you** — not a bot account. It also enables agents to use `gh` CLI commands (creating issues, commenting on PRs, etc.) on your behalf.
|
||||
{% /callout %}
|
||||
|
||||
1. Go to **Town Settings** → **Git & Authentication**
|
||||
2. Paste your GitHub Personal Access Token
|
||||
3. The token needs `repo` scope (and `workflow` if your repo uses GitHub Actions)
|
||||
|
||||
Without a PAT, agents use the GitHub App installation token — functional but shows up as a bot in your git history.
|
||||
|
||||
## 4. Sling Your First Task
|
||||
|
||||
Now let's give the agents something to do:
|
||||
|
||||
1. Click **Sling Work** (or ask the Mayor)
|
||||
2. Describe a simple task, e.g.: *"Add a CONTRIBUTING.md file with basic setup instructions"*
|
||||
3. Click **Sling**
|
||||
|
||||
<!-- TODO: Screenshot — Sling Work dialog with a sample task -->
|
||||
|
||||
## 5. Watch Agents Work
|
||||
|
||||
The reconciler assigns your task to an available polecat agent. You'll see:
|
||||
|
||||
1. A **bead** appear in the beads list with status `open`
|
||||
2. The bead transitions to `in_progress` as a polecat picks it up
|
||||
3. The agent reads your code, makes changes, and pushes a branch
|
||||
4. The bead moves to `in_review` as the refinery checks the work
|
||||
5. The refinery merges (or creates a PR depending on your settings)
|
||||
6. The bead reaches `closed`
|
||||
|
||||
<!-- TODO: Screenshot — bead lifecycle showing the transitions in real-time -->
|
||||
|
||||
The whole cycle typically takes 2-10 minutes depending on complexity and the model you're using.
|
||||
|
||||
## 6. Talk to the Mayor
|
||||
|
||||
Click the **Mayor** chat to interact with your town's coordinator. Try:
|
||||
|
||||
- *"What's the status of the town?"*
|
||||
- *"Create a convoy to add unit tests for the auth module"*
|
||||
- *"What settings should I change for faster reviews?"*
|
||||
|
||||
The Mayor is always running — it's your primary interface for managing the town conversationally.
|
||||
|
||||
<!-- TODO: Screenshot — Mayor chat with a greeting and status response -->
|
||||
|
||||
## What's Next?
|
||||
|
||||
- [Concepts](/code-with-ai/gastown/concepts) — Understand the building blocks in depth
|
||||
- [Sling Work](/code-with-ai/gastown/sling-work) — Learn about convoys and multi-step workflows
|
||||
- [Settings](/code-with-ai/gastown/settings) — Configure models, merge strategies, and agent behavior
|
||||
|
||||
@@ -5,16 +5,161 @@ description: "Configure models, merge strategies, and agent behavior"
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: All configurable settings with explanations -->
|
||||
Gas Town settings control how your agents behave — which models they use, how they review code, and how they interact with your repositories.
|
||||
|
||||
Access settings from your town dashboard → **Settings**.
|
||||
|
||||
## Models
|
||||
|
||||
### Default Model
|
||||
|
||||
The primary model used by all agents (polecats, refinery, mayor). This affects quality, speed, and cost.
|
||||
|
||||
Popular choices:
|
||||
- **Claude Sonnet** — fast, good for most tasks (default)
|
||||
- **Claude Opus** — highest quality, best for complex work
|
||||
- **Kilo Auto Free** — free tier, great for trying things out
|
||||
|
||||
### Role-Specific Models
|
||||
|
||||
Override the default model for specific agent roles:
|
||||
|
||||
| Role | Recommended | Why |
|
||||
|---|---|---|
|
||||
| Polecat | Claude Sonnet / Opus | Balance of speed and quality for code generation |
|
||||
| Refinery | Claude Opus | Higher reasoning for thorough review |
|
||||
| Mayor | Claude Sonnet | Fast responses for conversational coordination |
|
||||
|
||||
### Small Model
|
||||
|
||||
Used for lightweight tasks (classification, routing, summarization). Usually a smaller, cheaper model.
|
||||
|
||||
## Git & Authentication
|
||||
|
||||
### GitHub Personal Access Token
|
||||
|
||||
{% callout type="tip" title="Strongly Recommended" %}
|
||||
Adding a GitHub PAT ensures that all commits, branches, and PRs created by your agents appear as **you** in git history. Without it, activity shows up under the Kilo GitHub App bot account.
|
||||
{% /callout %}
|
||||
|
||||
**To add a PAT:**
|
||||
1. Go to **Settings** → **Git & Authentication**
|
||||
2. Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens)
|
||||
3. Required scopes: `repo` (full repository access)
|
||||
4. Recommended: also add `workflow` (if your repo uses GitHub Actions)
|
||||
5. Paste the token and save
|
||||
|
||||
**What the PAT enables:**
|
||||
- Commits and PRs appear as you (your avatar, your username)
|
||||
- Agents can use `gh` CLI commands on your behalf
|
||||
- Full access to private repositories you own
|
||||
- Ability to trigger CI workflows
|
||||
|
||||
**Without a PAT:**
|
||||
- The GitHub App installation token is used (functional but less personal)
|
||||
- PRs show as created by the Kilo bot
|
||||
- Some `gh` CLI operations may not work
|
||||
|
||||
### GitHub App Installation
|
||||
|
||||
The [Kilo GitHub App](https://github.com/apps/kilo-code) provides base-level repository access. It's installed per-organization or per-repository and gives agents read/write access to code, PRs, and issues.
|
||||
|
||||
The GitHub App is **required** — it's how Gastown gets installation tokens for cloning and pushing. The PAT is **optional but recommended** — it provides user-level attribution.
|
||||
|
||||
## Merge Strategy
|
||||
|
||||
Controls how reviewed code lands in your repository:
|
||||
|
||||
| Strategy | Behavior | Best for |
|
||||
|---|---|---|
|
||||
| `direct` | Refinery merges directly (no PR) | Speed, trusted environments |
|
||||
| `pr` | Refinery creates a PR | Audit trail, team visibility, CI integration |
|
||||
|
||||
For `pr` mode, you can also configure:
|
||||
- **Auto-merge** — PRs merge automatically after refinery approval
|
||||
- **Require human approval** — PRs wait for a human reviewer
|
||||
|
||||
## Refinery Configuration
|
||||
|
||||
### Review Mode
|
||||
|
||||
| Mode | Behavior |
|
||||
|---|---|
|
||||
| `always` | Every completed bead goes through review (default, recommended) |
|
||||
| `never` | Skip review entirely — merge on polecat completion |
|
||||
| `pr_only` | Only review work that generates a PR |
|
||||
|
||||
### Review Gates
|
||||
|
||||
Strictness level from 1 (lenient) to 5 (strict). Higher levels mean the refinery will reject more frequently but produce higher quality output.
|
||||
|
||||
### Max Review Cycles
|
||||
|
||||
How many write → review → revise cycles before a bead fails and escalates. Default: 3.
|
||||
|
||||
## Agent Limits
|
||||
|
||||
### Max Polecats Per Rig
|
||||
|
||||
How many coding agents can work simultaneously on a single rig. Default: 2.
|
||||
|
||||
Higher values mean more parallel work but also more resource consumption. Consider:
|
||||
- **1-2** — conservative, good for small repos or limited budgets
|
||||
- **3-4** — moderate parallelism, good for medium projects
|
||||
- **5+** — aggressive, best for large repos with lots of independent work
|
||||
|
||||
### Alarm Intervals
|
||||
|
||||
Controls how frequently the reconciler checks for work:
|
||||
- **Active interval** — when agents are working (default: 5s)
|
||||
- **Idle interval** — when no work is pending (default: 60s)
|
||||
|
||||
Lower active intervals mean faster response to events but more compute usage.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Add environment variables that are available to all agents in the container. Useful for:
|
||||
- API keys for external services agents might test against
|
||||
- Database connection strings for test environments
|
||||
- Feature flags or configuration values
|
||||
|
||||
{% callout type="warning" %}
|
||||
Environment variables are visible to all agents in the town. Do not store production secrets here — use test/development credentials only.
|
||||
{% /callout %}
|
||||
|
||||
## Custom Instructions
|
||||
|
||||
Free-form text injected into every agent's system prompt. Use this to communicate:
|
||||
|
||||
- Project conventions: *"Always use TypeScript strict mode"*
|
||||
- Architecture decisions: *"The auth module uses JWT with RS256. Never use HS256."*
|
||||
- Style preferences: *"Use functional components with hooks, never class components"*
|
||||
- Constraints: *"Do not modify files in the `vendor/` directory"*
|
||||
- Testing requirements: *"Every new function must have a corresponding unit test"*
|
||||
|
||||
Custom instructions are powerful — they let you encode institutional knowledge that agents follow consistently.
|
||||
|
||||
## Convoy Settings
|
||||
|
||||
### Staged Convoys Default
|
||||
|
||||
When `true`, new convoys are created as staged (paused until you un-stage). Default: `true`.
|
||||
|
||||
### Convoy Merge Mode
|
||||
|
||||
| Mode | Behavior |
|
||||
|---|---|
|
||||
| `review-then-land` | Each bead merges to a feature branch, then a landing review merges to main (default) |
|
||||
| `review-and-merge` | Each bead goes through review and merges directly to main (no feature branch) |
|
||||
|
||||
`review-then-land` provides the strongest quality guarantees but takes longer. Use `review-and-merge` for simpler tasks or when you want immediate feedback.
|
||||
|
||||
## Per-Rig Overrides
|
||||
|
||||
Any town-level setting can be overridden at the rig level. This lets you:
|
||||
- Use a more powerful model for a complex repository
|
||||
- Set stricter review gates for a production codebase
|
||||
- Allow more polecats on a repo with many independent modules
|
||||
- Disable review for a documentation-only repo
|
||||
|
||||
Access per-rig settings from the rig detail page → **Settings**.
|
||||
|
||||
@@ -5,14 +5,152 @@ description: "Creating tasks and convoys for agents to work on"
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: How to create beads, convoys, staged work -->
|
||||
"Slinging work" is how you give agents something to do. You can sling a single task (a bead) or a structured multi-step plan (a convoy).
|
||||
|
||||
## Creating a Single Task
|
||||
## Single Tasks
|
||||
|
||||
## Creating a Convoy
|
||||
The simplest way to use Gas Town — describe what needs to be done, and an agent picks it up:
|
||||
|
||||
## Staged Convoys
|
||||
1. Click **Sling Work** in the town header
|
||||
2. Write a description: *"Fix the 404 error on the /settings page — the route is missing from the router config"*
|
||||
3. Click **Sling**
|
||||
|
||||
The reconciler assigns the bead to an available polecat. The agent reads the relevant code, makes the fix, runs any tests, and pushes a branch.
|
||||
|
||||
<!-- TODO: Screenshot — Sling Work dialog with a single task -->
|
||||
|
||||
### Writing Good Task Descriptions
|
||||
|
||||
The quality of agent output directly correlates with the clarity of your description:
|
||||
|
||||
| Approach | Example |
|
||||
|---|---|
|
||||
| **Vague** (avoid) | "Fix the auth" |
|
||||
| **Specific** (better) | "Fix the JWT token expiration — tokens should last 24h, not 1h. The constant is in `src/auth/config.ts`" |
|
||||
| **Contextual** (best) | "Fix #142: users are getting logged out after 1 hour. The issue is the JWT expiration in `src/auth/config.ts` is set to 3600 (1h) but should be 86400 (24h). Add a test to verify." |
|
||||
|
||||
Include:
|
||||
- **What** needs to change
|
||||
- **Where** in the codebase (file paths if you know them)
|
||||
- **Why** it's needed (link to issues, error messages)
|
||||
- **How to verify** (tests to run, behavior to check)
|
||||
|
||||
## Convoys
|
||||
|
||||
Convoys are where Gas Town really shines. Instead of one agent doing everything in one pass, convoys break complex work into stages where each builds on the last — with adversarial review at every step.
|
||||
|
||||
### Why Convoys?
|
||||
|
||||
Single-pass agent output has a quality ceiling. The longer an agent works on one task, the more likely it is to accumulate compounding errors. Convoys solve this by:
|
||||
|
||||
1. **Decomposing** complex work into focused, reviewable chunks
|
||||
2. **Sequencing** so later steps build on reviewed, merged code
|
||||
3. **Reviewing** each chunk independently before it becomes the foundation for the next step
|
||||
4. **Containing failures** — if step 3 fails, steps 1 and 2 are already safely merged
|
||||
|
||||
<!-- TODO: React Flow diagram — Convoy vs Single-Pass Comparison
|
||||
Two parallel flows:
|
||||
|
||||
Top (Single-Pass):
|
||||
"Big task" → Polecat works 30min → "Large PR (800 lines)" → Review struggles → Bugs land
|
||||
|
||||
Bottom (Convoy):
|
||||
"Explore" → review ✓ → "Design" → review ✓ → "Implement" → review ✓ → "Test" → review ✓ → Clean merged result
|
||||
Each step: small PR, easy review, bugs caught early
|
||||
|
||||
Caption: "Convoys produce higher quality output through iterative adversarial review"
|
||||
-->
|
||||
|
||||
### Creating a Convoy
|
||||
|
||||
**Via the UI:**
|
||||
1. Click **Sling Work** → **Convoy**
|
||||
2. Add tasks in order
|
||||
3. Define dependencies (which tasks block others)
|
||||
4. Choose **staged** (review plan first) or **immediate** (start right away)
|
||||
|
||||
**Via the Mayor:**
|
||||
> *"Create a convoy to migrate the database from PostgreSQL to MySQL. Steps: 1) audit current schema and queries, 2) design the new schema with migration plan, 3) implement the migration scripts, 4) update the application layer, 5) add integration tests"*
|
||||
|
||||
The Mayor converts this into a convoy with proper dependencies.
|
||||
|
||||
<!-- TODO: Screenshot — Convoy creation UI showing task list with dependency arrows -->
|
||||
|
||||
### Convoy Execution
|
||||
|
||||
Once started, the reconciler manages the convoy:
|
||||
|
||||
<!-- TODO: React Flow diagram — Convoy Execution Flow
|
||||
Animated stage-by-stage flow:
|
||||
|
||||
Stage 1: Bead "Audit schema" dispatched to Polecat-1
|
||||
→ Polecat works → pushes branch → Refinery reviews → MERGE to convoy branch
|
||||
|
||||
Stage 2: Bead "Design migration" dispatched to Polecat-2 (starts from convoy branch)
|
||||
→ Polecat works (has context from stage 1) → pushes → Refinery reviews → MERGE
|
||||
|
||||
Stage 3: Bead "Implement scripts" dispatched (starts from convoy branch with stages 1+2)
|
||||
→ works → pushes → reviews → MERGE
|
||||
|
||||
Final: "Landing Review" — full convoy branch reviewed as cohesive unit → MERGE to main
|
||||
|
||||
Caption: "Each stage builds on merged, reviewed work from previous stages"
|
||||
-->
|
||||
|
||||
Key behaviors:
|
||||
- Each polecat starts from the **convoy feature branch**, which accumulates all previously merged work
|
||||
- Beads only dispatch when their **dependencies are satisfied** (upstream beads closed)
|
||||
- The refinery reviews each sub-PR against the convoy branch
|
||||
- Once all beads close, a **landing review** checks the full combined diff before merging to main
|
||||
|
||||
### The Adversarial Advantage
|
||||
|
||||
The convoy pattern creates **layered adversarial review**:
|
||||
|
||||
1. **Per-bead review** — refinery critiques each individual contribution
|
||||
2. **Context accumulation** — each agent builds on verified, reviewed code
|
||||
3. **Landing review** — the complete feature is reviewed holistically
|
||||
4. **Combined with Kilo Code Review** — if configured, human reviewers see the final PR too
|
||||
|
||||
This means code goes through **3-4 review passes** before landing in your main branch. Bugs get caught at the smallest possible scope where they're cheapest to fix.
|
||||
|
||||
### Staged Convoys
|
||||
|
||||
By default, convoys are created **staged** — the plan exists but agents don't start until you un-stage it. This lets you:
|
||||
|
||||
- Review the task breakdown before execution
|
||||
- Adjust descriptions, add context, reorder
|
||||
- Ensure the plan makes sense before burning compute
|
||||
|
||||
Un-stage via the convoy detail page or ask the Mayor: *"Start the database migration convoy"*
|
||||
|
||||
## Assigning Priority
|
||||
|
||||
Beads have priority levels: `low`, `medium` (default), `high`, `critical`.
|
||||
|
||||
Higher priority beads are dispatched first when multiple beads are waiting for agents. Set priority:
|
||||
- In the Sling Work dialog
|
||||
- Via the Mayor: *"Make the auth fix high priority"*
|
||||
- By editing the bead after creation
|
||||
|
||||
## Watching Progress
|
||||
|
||||
### Beads Page
|
||||
|
||||
The beads list shows all work in your town with real-time status updates. Filter by:
|
||||
- Status (open, in progress, in review, closed, failed)
|
||||
- Type (issue, merge_request, convoy)
|
||||
- Rig (if you have multiple repos)
|
||||
|
||||
<!-- TODO: Screenshot — Beads page with filter controls and mixed status beads -->
|
||||
|
||||
### Town Overview
|
||||
|
||||
The town overview shows a high-level summary:
|
||||
- Active agents and what they're working on
|
||||
- Recent completions
|
||||
- Pending work queue
|
||||
|
||||
### Real-Time Events
|
||||
|
||||
The event timeline shows every state transition as it happens — bead dispatched, review submitted, merge completed. Useful for understanding the flow in real-time.
|
||||
|
||||
@@ -5,14 +5,133 @@ description: "Common issues and how to resolve them"
|
||||
|
||||
# {% $markdoc.frontmatter.title %}
|
||||
|
||||
<!-- TODO: Common failure modes and fixes -->
|
||||
Gas Town is a complex system with multiple agents, containers, and external integrations. When things go wrong, this guide helps you diagnose and fix common issues.
|
||||
|
||||
## Agents Not Picking Up Work
|
||||
|
||||
**Symptom:** Beads stay in `open` status. No agents transition to `working`.
|
||||
|
||||
**Common causes:**
|
||||
|
||||
| Cause | Fix |
|
||||
|---|---|
|
||||
| All polecats at max dispatch attempts | Ask the Mayor: *"Reset agent dispatch attempts"* |
|
||||
| Container not running | Check container status in the admin panel. The Mayor can confirm: *"Is the container running?"* |
|
||||
| Reconciler paused (draining) | Wait for drain to complete, or cancel it in settings |
|
||||
| No available polecats | Check `max_polecats_per_rig` — you may need to increase it |
|
||||
|
||||
**Quick fix:** Ask the Mayor: *"Why aren't beads getting picked up?"* — it can diagnose and often resolve the issue.
|
||||
|
||||
## Container Not Starting
|
||||
|
||||
**Symptom:** The container status shows errors or stays in "starting" indefinitely.
|
||||
|
||||
**Common causes:**
|
||||
- Git clone failure (bad credentials, repo not accessible)
|
||||
- GitHub App not installed on the repository
|
||||
- Environment variables causing startup crash
|
||||
|
||||
**Fix:**
|
||||
1. Check that the [Kilo GitHub App](https://github.com/apps/kilo-code) is installed on your repository
|
||||
2. Verify your GitHub PAT is valid (if configured)
|
||||
3. Remove any environment variables that might cause issues during container init
|
||||
4. Try a container restart from town settings
|
||||
|
||||
## Git Authentication Failures
|
||||
|
||||
## Review Loop Issues
|
||||
**Symptom:** Agents can't clone, push, or fetch. Errors mention "authentication failed" or "permission denied".
|
||||
|
||||
**Common causes:**
|
||||
|
||||
| Cause | Fix |
|
||||
|---|---|
|
||||
| GitHub App uninstalled | Reinstall at [github.com/apps/kilo-code](https://github.com/apps/kilo-code) |
|
||||
| PAT expired or revoked | Generate a new token and update in Settings → Git & Authentication |
|
||||
| Repository visibility changed | Ensure the GitHub App has access to the repo |
|
||||
| Org SSO not authorized | Authorize the token for your organization's SSO |
|
||||
|
||||
**Diagnosis:** The Mayor may report *"git credential refresh failed: no_installation_found"* — this definitively means the GitHub App needs to be reinstalled.
|
||||
|
||||
## Review Loop / Stuck in Review
|
||||
|
||||
**Symptom:** A bead cycles between `in_review` and `in_progress` repeatedly, or MR beads keep failing.
|
||||
|
||||
**Common causes:**
|
||||
- The refinery finds issues the polecat can't fix (e.g., fundamental architecture problems)
|
||||
- Missing PR URL on merge request beads
|
||||
- Convoy feature branch deleted from remote
|
||||
|
||||
**Fix:**
|
||||
1. Check the bead's event history for review feedback
|
||||
2. If the feedback is a dead end, ask the Mayor to close the bead: *"Close bead [id] — the approach isn't working"*
|
||||
3. For stuck convoys, the Mayor can force-close: *"Force close convoy [name]"*
|
||||
|
||||
{% callout type="info" %}
|
||||
Beads automatically escalate after 3 failed review cycles. If a bead is genuinely stuck in a loop, it will eventually fail and notify you rather than running forever.
|
||||
{% /callout %}
|
||||
|
||||
## The Mayor is Unresponsive
|
||||
|
||||
**Symptom:** Messages to the Mayor don't get responses, or the Mayor says it's "unauthenticated".
|
||||
|
||||
**Common causes:**
|
||||
- Container sleeping (wakes up after ~30 seconds)
|
||||
- KILOCODE_TOKEN expired
|
||||
- Gateway authentication failure
|
||||
|
||||
**Fix:**
|
||||
1. Wait 30 seconds — the container may be waking from sleep
|
||||
2. If persistent: go to Settings → refresh the container token
|
||||
3. If still failing: check that your Kilo account is active and the town's billing is current
|
||||
|
||||
## Convoy Stuck / Never Completes
|
||||
|
||||
**Symptom:** A convoy shows open but no beads are being dispatched, or it never reaches "landed".
|
||||
|
||||
**Common causes:**
|
||||
- Upstream dependency bead failed (blocks downstream)
|
||||
- Convoy feature branch doesn't exist on remote
|
||||
- Landing MR repeatedly failing
|
||||
|
||||
**Fix:**
|
||||
1. Check convoy progress: which beads are closed? which are open/failed?
|
||||
2. For failed dependencies: fix or close the blocking bead, then downstream beads will dispatch
|
||||
3. Ask the Mayor: *"What's blocking convoy [name]?"*
|
||||
4. If truly stuck: force-close the convoy and re-create it
|
||||
|
||||
## Agent Permanently Stuck
|
||||
|
||||
**Symptom:** An agent shows as `working` but hasn't produced output for 20+ minutes.
|
||||
|
||||
**Common causes:**
|
||||
- Container process crashed but heartbeat continues
|
||||
- Agent waiting on an external resource (network, API)
|
||||
- Infinite loop in agent execution
|
||||
|
||||
**Fix:**
|
||||
1. Ask the Mayor: *"Reset agent [name]"*
|
||||
2. This clears the hook, resets the agent to idle, and returns the bead to `open`
|
||||
3. The reconciler will re-dispatch the bead to a fresh agent
|
||||
|
||||
## High Failure Rate
|
||||
|
||||
**Symptom:** Many beads ending in `failed` status.
|
||||
|
||||
**Common causes:**
|
||||
- Task descriptions are too vague (agents can't figure out what to do)
|
||||
- The codebase has issues that prevent agents from working (broken build, missing dependencies)
|
||||
- Model quality is too low for the complexity of the work
|
||||
|
||||
**Fix:**
|
||||
1. Review failed bead descriptions — make them more specific
|
||||
2. Ensure the repo builds cleanly (agents struggle with pre-existing broken builds)
|
||||
3. Consider upgrading the model (Sonnet → Opus for complex work)
|
||||
4. Add custom instructions to guide agents: test commands, build steps, conventions
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you can't resolve an issue:
|
||||
|
||||
1. **Ask the Mayor** — it can diagnose most problems
|
||||
2. **Check the event timeline** — see exactly what happened and when
|
||||
3. **Contact support** — reach out at [kilo.ai/discord](https://kilo.ai/discord) with your town ID
|
||||
|
||||
Reference in New Issue
Block a user