Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ cmd/ - CLI commands (cobra)
├── worker.go - ttal worker close/list
├── today.go - ttal today list/completed/add/remove (daily focus)
├── task.go - ttal task get/find (taskwarrior queries)
└── advance.go - ttal task advance (pipeline stage engine)
└── go.go - ttal task go (pipeline stage engine)

internal/
├── agentfs/ - Filesystem-based agent discovery (CLAUDE.md frontmatter)
Expand All @@ -127,7 +127,7 @@ inter-agent and human-agent messaging. **Do not add fallback logic** — each pa
| `ttal send --to kestrel` | tmux send-keys | `handleTo` |
| `ttal send --to kestrel` (with TTAL_AGENT_NAME) | tmux send-keys + attribution | `handleAgentToAgent` |
| on-add hook (task created) | Inline enrichment (project_path, branch) | `HookOnAdd` → `enrichInline` |
| `ttal task advance <uuid>` | Pipeline advance via CLI | `handlePipelineAdvance` → `advanceToStage` |
| `ttal task go <uuid>` | Pipeline advance via CLI | `handlePipelineAdvance` → `advanceToStage` |
| Cleanup watcher (fsnotify) | Close worker + mark done | `startCleanupWatcher` → `worker.Close` → `MarkDone` |

Socket protocol uses `SendRequest{From, To, Message}` — direction is inferred from which fields
Expand Down
11 changes: 4 additions & 7 deletions CLAUDE.user.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Workers automatically look for flicknote notes in projects named `*plan*` or `*f

### Step 3: Execute
```bash
ttal task execute <uuid> # spawns a worker in isolated worktree
ttal task go <uuid> # spawns a worker in isolated worktree
```

## GitHub & Forgejo
Expand Down Expand Up @@ -126,13 +126,11 @@ ttal task get <uuid> # get formatted task prompt
Route tasks to the right agent instead of doing everything yourself.

```bash
ttal task route <uuid> --to <agent> # route to agent for design/research/brainstorm
ttal task execute <uuid> # spawn a worker to implement the task
ttal task go <uuid> # advance task through pipeline stage (route to agent or spawn worker)
```

**When to use:**
- `ttal task route` — task needs design, research, or brainstorming. Use `/task-route` command to classify readiness and pick the right agent.
- `ttal task execute` — task has a plan/design doc annotated and is ready to implement. Spawns a Claude Code worker in its own tmux session + git worktree.
- `ttal task go` — advances the task to the next pipeline stage. Routes to the right agent (design/research) or spawns a worker, based on `pipelines.toml`.

### Ask

Expand Down Expand Up @@ -210,8 +208,7 @@ ttal task add --project <alias> "description" --tag <tag> --priority M --annotat
ttal task get <uuid> # rich prompt with inlined docs
ttal task find <keyword> # search pending tasks
ttal task find <keyword> --completed # search completed tasks
ttal task route <uuid> --to <agent> # route to a specific agent
ttal task execute <uuid> # spawn worker
ttal task go <uuid> # advance task through pipeline stage
```

## PRs
Expand Down
10 changes: 2 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,8 @@ All automatic. All in your terminal.
# Create a task
ttal task add --project myapp "Add JWT authentication to the API"

# Route to researcher — she investigates options, writes findings
ttal task route abc12345 --to athena

# Route to designer — he reads research, writes the implementation plan
ttal task route abc12345 --to inke

# Execute — worker spawns in its own worktree, follows the plan, opens a PR
ttal task advance abc12345
# Advance — routes to researcher, designer, or spawns worker based on pipeline stage
ttal task go abc12345

# Meanwhile, you're on your phone
# Review agents post verdicts, worker triages feedback, you merge from Telegram
Expand Down
3 changes: 1 addition & 2 deletions RULE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,7 @@ ttal task add --project <alias> "description" --tag <tag> --priority M --annotat
ttal task get <uuid> # rich prompt with inlined docs
ttal task find <keyword> # search pending tasks
ttal task find <keyword> --completed # search completed tasks
ttal task route <uuid> --to <agent> # route to a specific agent (legacy — prefer advance)
ttal task advance <uuid> # advance task through pipeline stage
ttal task go <uuid> # advance task through pipeline stage
```

## PRs
Expand Down
26 changes: 0 additions & 26 deletions cmd/advance_test.go

This file was deleted.

8 changes: 4 additions & 4 deletions cmd/advance.go → cmd/go.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ import (
"github.com/tta-lab/ttal-cli/internal/taskwarrior"
)

var taskAdvanceCmd = &cobra.Command{
Use: "advance <uuid>",
var taskGoCmd = &cobra.Command{
Use: "go <uuid>",
Short: "Advance a task to the next pipeline stage",
Long: `Advance a task through its pipeline stages based on pipelines.toml configuration.

Expand All @@ -21,8 +21,8 @@ is determined by the task's pipeline stage definition.
Human gate stages block until Telegram approval is received.

Examples:
ttal task advance abc12345
ttal task advance abc12345-1234-1234-1234-123456789abc`,
ttal task go abc12345
ttal task go abc12345-1234-1234-1234-123456789abc`,
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
uuid := args[0]
Expand Down
26 changes: 26 additions & 0 deletions cmd/go_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
package cmd

import (
"testing"
)

func TestGoCmdExists(t *testing.T) {
// Verify go subcommand is registered on the task command.
var found bool
for _, sub := range taskCmd.Commands() {
if sub.Name() == "go" {
found = true
break
}
}
if !found {
t.Error("ttal task go command not found")
}
}

func TestGoCmd_RequiresUUID(t *testing.T) {
// Go requires exactly one UUID argument.
if taskGoCmd.Args == nil {
t.Error("expected Args validator on go command")
}
}
2 changes: 1 addition & 1 deletion cmd/task.go
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ func init() {
taskCmd.AddCommand(taskGetCmd)
taskCmd.AddCommand(taskFindCmd)
taskCmd.AddCommand(taskAddCmd)
taskCmd.AddCommand(taskAdvanceCmd)
taskCmd.AddCommand(taskGoCmd)
taskCmd.AddCommand(taskCommentCmd)
taskCmd.AddCommand(taskHeatmapCmd)

Expand Down
2 changes: 1 addition & 1 deletion docs/blog/philosophy.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ This creates a concrete constraint on design: ttal must be ergonomic for both hu

```bash
# An agent running ttal to spawn another agent's work
ttal task advance a1b2c3d4
ttal task go a1b2c3d4

# An agent querying its own task queue
ttal task find refactor --completed
Expand Down
6 changes: 3 additions & 3 deletions docs/blog/the-glue-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ The key components:
|-----------|--------------|
| **Daemon** | Long-running process; handles socket connections, Telegram, fsnotify watchers |
| **on-add-ttal hook** | Fires when a task is created; enriches with project path and branch |
| **Worker spawn** | `ttal task advance <uuid>` → tmux session + git worktree + coding agent |
| **Worker spawn** | `ttal task go <uuid>` → tmux session + git worktree + coding agent |
| **Cleanup watcher** | Watches for worker completion; closes session, removes worktree, marks task done |
| **ttal send** | Agent-to-agent messaging via daemon socket |

Expand All @@ -88,7 +88,7 @@ The manager/worker distinction survived the migration. It's too useful to abando
│ └─────────────┘ └─────────────┘ └────────┬────────┘ │
│ │ │
└─────────────────────────────────────────────┼───────────┘
│ ttal task execute
│ ttal task go
┌─────────────────────────────────────────────────────────┐
│ Worker Plane (tmux + worktree) │
Expand Down Expand Up @@ -128,7 +128,7 @@ This means the stack doesn't break when a new coding agent appears. Swap the run
## The Full Loop

```
You: ttal task advance a1b2c3d4
You: ttal task go a1b2c3d4
ttal daemon: reads task, resolves project path
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ re_review = "{{skill:pr-review}}\nRe-review the fixes: {{review-scope}}"

| Key | Used by | Template variables |
|-----|---------|-------------------|
| `execute` | `ttal task execute` | `{{task-id}}`, `{{skill:name}}` |
| `execute` | `ttal task go` | `{{task-id}}`, `{{skill:name}}` |
| `triage` | PR review → coder | `{{review-file}}`, `{{skill:name}}` |
| `review` | Reviewer initial prompt | `{{pr-number}}`, `{{pr-title}}`, `{{owner}}`, `{{repo}}`, `{{branch}}`, `{{skill:name}}` |
| `re_review` | Re-review after fixes | `{{review-scope}}`, `{{coder-comment}}`, `{{skill:name}}` |
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/daemon.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The daemon is a long-running process that acts as the communication hub for your
- **Message delivery** — delivers messages to agent tmux sessions via `send-keys`
- **JSONL bridge** — tails active Claude Code session files and sends assistant output to Telegram
- **Cleanup watcher** — processes post-merge cleanup requests (close session, remove worktree, mark task done)
- **Task routing** — handles `ttal task route --to <agent>` by delivering prompts to agent sessions
- **Task routing** — handles `ttal task go <uuid>` by advancing tasks through pipeline stages

## Installation

Expand Down
12 changes: 6 additions & 6 deletions docs/docs/prompts.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,9 @@ as all runtimes require skill invocations at the start of the message.

| Key | Used by | Template variables |
|-----|---------|-------------------|
| `designer` | `ttal task route --to <agent>` (agent with `role: designer`) | `{{task-id}}`, `{{skill:name}}` |
| `researcher` | `ttal task route --to <agent>` (agent with `role: researcher`) | `{{task-id}}`, `{{skill:name}}` |
| `execute` | `ttal task execute` | `{{task-id}}`, `{{skill:name}}` |
| `designer` | `ttal task go <uuid>` (agent with `role: designer`) | `{{task-id}}`, `{{skill:name}}` |
| `researcher` | `ttal task go <uuid>` (agent with `role: researcher`) | `{{task-id}}`, `{{skill:name}}` |
| `execute` | `ttal task go` | `{{task-id}}`, `{{skill:name}}` |
| `triage` | PR review → coder | `{{review-file}}`, `{{skill:name}}` |
| `review` | Reviewer initial prompt | `{{pr-number}}`, `{{pr-title}}`, `{{owner}}`, `{{repo}}`, `{{branch}}`, `{{skill:name}}` |
| `re_review` | Re-review after fixes | `{{review-scope}}`, `{{coder-comment}}`, `{{skill:name}}` |
Expand All @@ -53,19 +53,19 @@ as all runtimes require skill invocations at the start of the message.

### `execute`

The execute prompt is prepended to the worker's spawn prompt. When you run `ttal task advance <uuid>`, the worker receives this prompt followed by the task context (description, annotations, inlined docs).
The execute prompt is prepended to the worker's spawn prompt. When you run `ttal task go <uuid>`, the worker receives this prompt followed by the task context (description, annotations, inlined docs).

Default: invokes the executing-plans skill to implement the task step by step.

### `designer`

Controls what gets sent when you run `ttal task advance <uuid>` where the agent has `role: designer`. The agent receives this prompt with the task UUID, reads the task details, and writes an implementation plan.
Controls what gets sent when you run `ttal task go <uuid>` where the agent has `role: designer`. The agent receives this prompt with the task UUID, reads the task details, and writes an implementation plan.

Default: asks the agent to write a plan document and annotate the task with its path.

### `researcher`

Controls what gets sent when you run `ttal task advance <uuid>` where the agent has `role: researcher`. The agent receives this prompt, investigates the topic, and writes findings.
Controls what gets sent when you run `ttal task go <uuid>` where the agent has `role: researcher`. The agent receives this prompt, investigates the topic, and writes findings.

Default: asks the agent to research the topic and annotate the task with the findings path.

Expand Down
9 changes: 3 additions & 6 deletions docs/docs/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,8 @@ Accepts 8-character UUID prefixes or full UUIDs.
Route tasks to specialized agents based on what needs to happen:

```bash
# Route to a specific agent by name
ttal task route <uuid> --to <agent-name>

# Spawn a worker to implement
ttal task advance <uuid>
# Advance to next pipeline stage (routes to agent or spawns worker)
ttal task go <uuid>
```

### Configuring route targets
Expand All @@ -56,7 +53,7 @@ role: researcher
---
```

Use `ttal task advance <uuid>` to route to any agent by name (role determines which prompt is used).
Use `ttal task go <uuid>` to route to any agent by name (role determines which prompt is used).

## Today's focus

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/workers.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Workers are isolated coding sessions. Each worker runs in its own tmux session w
The primary way to spawn a worker is through task execution:

```bash
ttal task advance <uuid>
ttal task go <uuid>
```

This reads the task's metadata (project path, branch name) and spawns a worker with the right context.
Expand Down Expand Up @@ -100,7 +100,7 @@ This processes any pending cleanup request files that the daemon hasn't handled
Spawn a worker to implement a task:

```bash
ttal task advance <uuid>
ttal task go <uuid>
```

Without `--yes`, shows the project path and prompts for confirmation.
4 changes: 2 additions & 2 deletions docs/guides/building-your-team.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The simplest setup. One persistent agent handles orchestration, and workers are
ttal agent add kestrel --role orchestrator
```

Kestrel manages your tasks, responds to Telegram messages, and spawns workers when you run `ttal task execute`. Each worker is isolated in its own tmux session and git worktree.
Kestrel manages your tasks, responds to Telegram messages, and spawns workers when you run `ttal task go`. Each worker is isolated in its own tmux session and git worktree.

**Best for:** Individual developers who want mobile access and task-driven workflows.

Expand All @@ -36,7 +36,7 @@ ttal agent modify inke role:designer
ttal agent modify athena role:researcher
```

Now `ttal task route <uuid> --to inke` goes to Inke (role: designer), `ttal task route <uuid> --to athena` goes to Athena (role: researcher), and `ttal task advance <uuid>` spawns a worker.
Now `ttal task go <uuid>` advances the task through pipeline stages: routes to Athena (researcher) or Inke (designer) for early stages, and spawns a worker for implementation.

**Best for:** Complex projects where tasks benefit from investigation and planning before implementation.

Expand Down
16 changes: 8 additions & 8 deletions docs/guides/research-design-execute.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The typical ttal workflow follows three phases: research the problem, design the
### 1. Research

```bash
ttal task route <uuid> --to <researcher-agent>
ttal task go <uuid>
```

The research agent investigates the problem, explores options, and writes a findings document. It then annotates the task:
Expand All @@ -22,7 +22,7 @@ Research: ~/clawd/docs/research/2026-03-01-auth-options.md
### 2. Design

```bash
ttal task route <uuid> --to <designer-agent>
ttal task go <uuid>
```

The design agent reads the task (including the research findings via the annotation), writes an implementation plan, and annotates the task:
Expand All @@ -34,7 +34,7 @@ Plan: ~/clawd/docs/plans/2026-03-01-auth-implementation.md
### 3. Execute

```bash
ttal task advance <uuid>
ttal task go <uuid>
```

This spawns a worker in a tmux session with a git worktree. The worker receives the full task context — including the research findings and implementation plan, automatically inlined from annotations.
Expand Down Expand Up @@ -62,23 +62,23 @@ ttal task add --project myapp "Add JWT authentication to the API"
### Step 2: Research

```bash
ttal task route <uuid> --to athena
ttal task go <uuid>
```

Athena (the research agent) investigates JWT libraries, compares options, and writes findings.

### Step 3: Design

```bash
ttal task route <uuid> --to inke
ttal task go <uuid>
```

Inke (the design agent) reads Athena's research, writes an implementation plan with specific files to modify, and annotates the task.

### Step 4: Execute

```bash
ttal task advance <uuid>
ttal task go <uuid>
```

A worker spawns with full context: the task description, Athena's research, and Inke's plan — all inlined in the prompt. The worker follows the plan, implements the feature, creates a PR.
Expand All @@ -91,6 +91,6 @@ The PR goes through automated review (6 specialized review agents), the worker t

Not every task needs all three phases:

- **Simple bug fix** — skip research and design, go straight to `ttal task execute`
- **Well-understood feature** — skip research, route to designer with `ttal task route --to <agent>`, then execute
- **Simple bug fix** — skip research and design, go straight to `ttal task go`
- **Well-understood feature** — skip research, go straight to design stage with `ttal task go <uuid>`, then execute
- **Exploratory work** — research only, then decide next steps based on findings
2 changes: 1 addition & 1 deletion internal/doctor/pipelines.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package doctor

// defaultPipelinesContent is the starter pipelines.toml written by ttal doctor --fix.
// It defines standard/bugfix/hotfix pipelines for the common ttal workflow.
const defaultPipelinesContent = `# Pipeline definitions for ttal task advance.
const defaultPipelinesContent = `# Pipeline definitions for ttal task go.
# Each pipeline defines a sequence of stages with role-based assignment and gates.
# Tasks are matched to pipelines by their tags.

Expand Down
2 changes: 1 addition & 1 deletion internal/open/session.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ func Session(uuid string) error {
if !tmux.SessionExists(sessionName) {
return fmt.Errorf("no worker session assigned to this task\n\n"+
" To spawn a worker for this task:\n"+
" ttal task advance %s", uuid)
" ttal task go %s", uuid)
}

tmuxBin, err := lookPath("tmux")
Expand Down
Loading
Loading