Tick Coordination

tick init

Get current status

tick status

Common Workflows

1. User Asks You to Do Something

User: "Can you refactor the authentication system?"

Your Actions:

# 1. Create task
tick add "Refactor authentication system" --priority high --tags backend,security

# 2. Register yourself (first time only)
tick agent register @your-name --type bot --roles "engineer,refactoring"

# 3. Claim the task
tick claim TASK-XXX @your-name

# 4. Work on it (do the actual work)

# 5. Add progress comments
tick comment TASK-XXX @your-name --note "Analyzing current auth flow"
tick comment TASK-XXX @your-name --note "Refactored to use JWT tokens"

# 6. Mark complete
tick done TASK-XXX @your-name

2. User Asks About Project Status

User: "What tasks are we working on?"

# Get comprehensive status
tick status

# Or get specific info
tick agent list --verbose

Summarize the output naturally for the user.

3. Coordination with Other Agents

User: "Have the other agents finished their tasks?"

# Check overall status
tick status

# List agents and their work
tick agent list --verbose

# Validate the project
tick validate

4. Breaking Down Complex Work

User: "Build a user dashboard with charts and data export"

Your Actions:

# Create parent task
tick add "Build user dashboard" --priority high --tags frontend

# Create subtasks
tick add "Design dashboard layout" --priority high --tags frontend,design
tick add "Implement data charts" --priority medium --tags frontend,charts --depends-on TASK-XXX
tick add "Add CSV export" --priority low --tags frontend,export --depends-on TASK-XXX

# Show user the plan
tick status

Command Reference

Project Management

tick init                          # Initialize new project
tick status                        # View project overview
tick validate                      # Check for errors
tick sync --push                   # Commit and push to git

Task Operations

tick add "Task title" \
  --priority high \                # urgent|high|medium|low
  --tags backend,api \             # Comma-separated tags
  --assigned-to @agent \           # Assign to agent
  --depends-on TASK-001 \          # Dependencies
  --estimated-hours 4              # Time estimate

tick claim TASK-001 @agent         # Claim task (sets in_progress)
tick release TASK-001 @agent       # Release task (back to todo)
tick done TASK-001 @agent          # Complete task
tick comment TASK-001 @agent \     # Add note
  --note "Progress update"

Agent Management

tick agent register @name \        # Register new agent
  --type bot \                     # human|bot
  --roles "dev,qa" \               # Comma-separated roles
  --status idle                    # working|idle|offline

tick agent list                    # List all agents
tick agent list --verbose          # Detailed info
tick agent list --type bot         # Filter by type
tick agent list --status working   # Filter by status

MCP Tools (Alternative to CLI)

If using Model Context Protocol, use these tools instead of CLI commands:

Status and Inspection

• tick_status - Get project status (agents, tasks, progress)
• tick_validate - Validate TICK.md structure
• tick_agent_list - List agents with optional filters

Task Management

• tick_add - Create new task
• tick_claim - Claim task for agent
• tick_release - Release claimed task
• tick_done - Complete task (auto-unblocks dependents)
• tick_comment - Add note to task

Agent Operations

• tick_agent_register - Register new agent

MCP Example:

// Create task via MCP
await tick_add({
  title: "Refactor authentication",
  priority: "high",
  tags: ["backend", "security"],
  assignedTo: "@bot-name"
})

// Claim it
await tick_claim({
  taskId: "TASK-023",
  agent: "@bot-name"
})

Best Practices

1. Natural Conversation First

✅ Good: User says "refactor the auth", you create task automatically ❌ Bad: Making user explicitly create tasks

2. Always Use Your Agent Name

Register once:

tick agent register @your-bot-name --type bot --roles "engineer"

Then use consistently:

tick claim TASK-001 @your-bot-name
tick done TASK-001 @your-bot-name

3. Provide Context in Comments

# ✅ Good - explains what and why
tick comment TASK-005 @bot --note "Switched from REST to GraphQL for better type safety and reduced over-fetching"

# ❌ Bad - too vague
tick comment TASK-005 @bot --note "Updated API"

4. Break Down Large Tasks

Create subtasks with dependencies:

tick add "Set up CI/CD pipeline" --priority high
tick add "Configure GitHub Actions" --depends-on TASK-010
tick add "Add deployment scripts" --depends-on TASK-011
tick add "Set up staging environment" --depends-on TASK-011

5. Check Status Before Claiming

# Make sure task exists and isn't claimed
tick status

# Then claim
tick claim TASK-XXX @your-name

Common Scenarios

Scenario 1: Starting Fresh

# Project doesn't have Tick yet
tick init

# Register yourself
tick agent register @bot --type bot --roles "assistant,developer"

# Ask user what they want to accomplish
# Create tasks based on conversation
tick add "First task based on user input" --priority high

# Claim and start working
tick claim TASK-001 @bot

Scenario 2: Joining Existing Project

# Check current status
tick status

# Register yourself
tick agent register @new-bot --type bot --roles "qa,testing"

# Look for unassigned tasks
tick status  # Review todo items

# Claim relevant task
tick claim TASK-XXX @new-bot

Scenario 3: Coordinating with Humans

# Human asks: "What's left to do?"
tick status  # Show tasks by status

# Human: "Can you take the API task?"
tick claim TASK-API @bot

# Work on it, provide updates
tick comment TASK-API @bot --note "Completed 3 of 5 endpoints"

# Complete when done
tick done TASK-API @bot

Scenario 4: Handling Blockers

# You're blocked on something
tick comment TASK-XXX @bot --note "Blocked: waiting for API credentials"

# Release the task if you can't proceed
tick release TASK-XXX @bot

# Or keep it claimed if you're actively working around the blocker

Understanding TICK.md Structure

The file has three sections:

1. Frontmatter (YAML): Project metadata
2. Agents Table (Markdown): Who's working on what
3. Task Blocks (YAML + Markdown): Individual tasks with history

Example:

---