visual-agent-tasks

In-repo task/plan system for AI agents (vibe coding), with a read-only Kanban board. State lives in .claude/tasks/ — gitignored, local per developer, no merge conflicts.

Install

cd cli
make install          # builds and puts `tasks` in $(go env GOPATH)/bin

Make sure $(go env GOPATH)/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Quickstart

# Initialize in any git project
tasks init

# Create a plan, epic, and tasks
PLAN=$(tasks plan add "My feature" --goal "Ship it")
EPIC=$(tasks epic add "Backend" --plan $PLAN)
tasks add "Create endpoint" --parent $EPIC --priority high
tasks add "Write tests"     --parent $EPIC --depends TASK-0001

# Work
tasks next                          # what to do now
tasks move TASK-0001 "In Progress"
tasks move TASK-0001 "Done"

# Inspect
tasks tree
tasks list --json
tasks validate

# Board (opens in VSCode with Mermaid preview)
tasks board
open .claude/tasks/BOARD.md

Hook setup (Claude Code)

Add to your project's .claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "command": "bash /path/to/visual-agent-tasks/hook/validate-and-board.sh" }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "command": "bash /path/to/visual-agent-tasks/hook/validate-and-board.sh"
      }
    ]
  }
}

The hook validates frontmatter + parent-chain on every agent stop and regenerates BOARD.md automatically. Skips silently if the project isn't initialized.

Skill setup

Copy skills/SKILL.md into your project's .claude/ or reference it in CLAUDE.md:

<!-- in CLAUDE.md -->
Read `skills/SKILL.md` for task management commands.

CLI reference

tasks init                                     # initialize .claude/tasks/
tasks plan add <title> [--goal "..."]          # create plan
tasks epic add <title> --plan PLAN-0001        # create epic
tasks add <title> --parent EPIC|PLAN [flags]   # create task
  --priority low|med|high
  --depends TASK-xxxx (repeatable)
  --status <status>
  --owner <handle>
  --tag <tag> (repeatable)
tasks move <id> <status>                       # move task to column
tasks set  <id> [--priority] [--owner]         # update task fields
           [--depends] [--blocked] [--tag]
           [--clear priority|owner|...]
tasks list [--status] [--plan] [--tag] [--json]
tasks show <id> [--json]
tasks next [--json]                            # 1-3 actionable tasks
tasks tree [PLAN-id]
tasks board                                    # regenerate BOARD.md
tasks validate [--json]                        # schema + chain + cycles

Design

See DESIGN.md for the authoritative spec.

Key principles: CLI is deterministic (owns all writes), LLM owns judgment, skill is a thin adapter (no logic). Board is read-only — all writes via CLI.