tinytown 0.10.0

A simple, fast multi-agent orchestration system using Redis for message passing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# tt plan

Plan tasks in a file before starting work.

## Synopsis

```bash
tt plan [OPTIONS]
tt plan --init
```

## Description

The `plan` command lets you define tasks in `tasks.toml` before syncing them to Redis. This enables:

1. **Version control** — Check in your task plan with your code
2. **Offline planning** — Edit tasks without Redis running
3. **Review before execution** — Plan the work, then start the train

## Options

| Option | Short | Description |
|--------|-------|-------------|
| `--init` | `-i` | Create a new tasks.toml file |
| `--town <PATH>` | `-t` | Town directory (default: `.`) |

## Examples

### Initialize a Task Plan

```bash
tt plan --init
```

Creates `tasks.toml`:

```toml
[meta]
description = "Task plan for this project"

[[tasks]]
id = "example-1"
description = "Example task - replace with your own"
status = "pending"
tags = ["example"]
```

### View Current Plan

```bash
tt plan
```

Output:
```
📋 Tasks in plan (./tasks.toml):
  ⏳ [unassigned] example-1 - Example task - replace with your own
```

### Edit and Sync

```bash
# Edit tasks.toml with your editor
vim tasks.toml

# Push to Redis
tt sync push
```

## Task File Format

```toml
[meta]
description = "Sprint 1 tasks"
default_agent = "developer"  # Optional default

[[tasks]]
id = "auth-api"
description = "Build user authentication API"
agent = "backend"
status = "pending"
tags = ["auth", "api"]

[[tasks]]
id = "auth-tests"
description = "Write auth API tests"
agent = "tester"
status = "pending"
parent = "auth-api"  # Optional parent task

[[tasks]]
id = "auth-review"
description = "Review auth implementation"
status = "pending"
# No agent = unassigned
```

## Task Status Values

| Status | Icon | Meaning |
|--------|------|---------|
| `pending` | ⏳ | Not started |
| `assigned` | 📌 | Given to an agent |
| `running` | 🔄 | In progress |
| `completed` | ✅ | Done |
| `failed` | ❌ | Error |

## Workflow

1. **Plan**: `tt plan --init` → edit `tasks.toml`
2. **Review**: `tt plan` to see the plan
3. **Start**: `tt sync push` to send to Redis
4. **Execute**: Agents receive tasks
5. **Snapshot**: `tt sync pull` to save state

## Why Plan in a File?

- **Git history** — Track how the plan evolved
- **Code review** — Review task definitions in PRs
- **Templates** — Reuse task structures across projects
- **Offline** — Plan without starting Redis

Redis remains the source of truth at runtime; the file is for planning and version control.

## See Also

- [tt sync](./sync.md) — Sync tasks.toml ↔ Redis
- [tt conductor](./conductor.md) — Interactive mode
- [Tasks Concept](../concepts/tasks.md)