Kanban Task Execution

The Spectral Agent can execute your Kanban backlog task by task. Give it a goal, and it will pick up TODO tasks in priority order, implement each one using its full toolset, record results, and move them to DONE.

This closes the loop from specification → planning → execution — the full Aexol workflow in one session.

Prerequisites

1. Authentication

spectral login

Your tokens are stored in ~/.spectral/config.json. The agent reads them automatically.

2. Project Binding

spectral bind <project-id>

This creates .aexol/aexol.jsonc with your project ID. The agent needs this to know which board to work on.

3. Start the Agent

spectral serve

Your machine appears in the Studio UI. Open the agent chat in your project.

The Execution Cycle

The agent's task-driven execution follows this loop:

┌─────────────────────────────────────────┐
│  kanban_next                            │
│  → picks highest-priority TODO          │
│  → moves it to IN PROGRESS              │
│  → returns full task details            │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Agent reads description                │
│  → understands acceptance criteria      │
│  → plans implementation approach        │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Agent implements changes               │
│  → read, write, edit, bash              │
│  → creates/modifies files               │
│  → runs tests, linters                  │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  kanban_update                          │
│  → records what was done               │
│  → updates description with results     │
│  → adds relevant tags                   │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  kanban_move to DONE                    │
│  → task marked complete                 │
│  → completedAt timestamp set            │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  kanban_next → next task or all done    │
│  → repeat until TODO/BACKLOG empty      │
└─────────────────────────────────────────┘

Getting Started

Option A: Full Autonomous Execution

In the agent chat, give a single command:

Execute the entire kanban backlog.
Start with the highest-priority TODO,
implement each task, move it to DONE,
then continue with the next.
Stop when all TODO and BACKLOG tasks are complete.

The agent will work through the board autonomously.

Option B: Task-by-Task Control

If you prefer more oversight, guide the agent step by step:

> Show me the kanban board

> Start the task about "JWT auth middleware"

> Implement it

> Move it to DONE

> Show me the next task

Option C: Specific Task

> Start the kanban task "Build user registration page" and implement it

The agent uses kanban_next with an explicit taskId to pick that specific task.

Available Tools

The agent has 7 Kanban tools at its disposal:

kanban_next

Start execution of the next task. Picks the highest-priority TODO (or BACKLOG if TODO is empty), moves it to IN PROGRESS, and returns the full task details including description and acceptance criteria. Output includes instructions for the implementation cycle.

kanban_next
kanban_next taskId: "task_abc123"

kanban_list

View the board. Returns all tasks grouped by column, with ID, title, priority, and tags for each.

kanban_list
kanban_list column: "TODO"

kanban_get

Inspect a task in detail. Returns full metadata including description, assignee, timestamps.

kanban_get taskId: "task_abc123"

kanban_create

Add a new task to the board. Useful when the agent discovers work that wasn't planned.

kanban_create title: "Add rate limiting" description: "Implement rate limiting on login endpoint to prevent brute force. Use in-memory store with configurable window." priority: 85 tags: "security,api"

kanban_update

Update task metadata. The agent typically uses this to record what was implemented, update the description with results, and add tags.

kanban_update taskId: "task_abc123" description: "COMPLETED: JWT middleware validates tokens on all /api/* routes. Files: middleware/auth.ts, config/jwt.ts. Tests passing." tags: "auth,api,done"

kanban_move

Move a task between columns.

kanban_move taskId: "task_abc123" targetColumn: "DONE"
kanban_move taskId: "task_abc123" targetColumn: "TODO"

kanban_delete

Remove a task from the board.

kanban_delete taskId: "task_abc123"

Agent Prompt Examples

Full backlog execution

I have a Kanban board with tasks generated from my Aexol spec.
Please execute the entire backlog:

1. Check the board with kanban_list
2. Call kanban_next to start the first task
3. Read the task description carefully — implement exactly what it asks for
4. Write implementation files, run relevant tests
5. Use kanban_update to record what was done
6. Use kanban_move to mark the task DONE
7. Call kanban_next to get the next task
8. Repeat until there are no more TODO or BACKLOG tasks

Stop when all tasks are in DONE.

Single entity implementation

Execute all Kanban tasks related to the User entity.
Start with the User type/schema task, then move through
authentication, profile management, and permissions.

Frontend-only execution

Execute only the frontend tasks from the kanban board.
Skip any backend or infrastructure tasks.
Tag completed tasks with "frontend,done".

Troubleshooting

"Kanban bridge not configured"

The agent doesn't have authentication or project binding.

# Check auth
cat ~/.spectral/config.json | grep teamApiKey

# Check project binding
cat .aexol/aexol.jsonc | grep projectId

# Fix
spectral login
spectral bind <your-project-id>

"No TODO or BACKLOG tasks available"

All tasks are either IN PROGRESS or DONE. Check the board:

kanban_list

If you need to re-run a task, move it back to TODO:

kanban_move taskId: "task_xyz" targetColumn: "TODO"

Agent picks the wrong task

Use explicit task ID to override auto-selection:

kanban_next taskId: "task_specific_id"

Board not updating

The board refreshes via SSE polling every 1–2 seconds. If changes aren't visible in Studio immediately, wait a moment or refresh the page.

Architecture

The Kanban execution bridge is a built-in pi extension at cli-node/src/extensions/kanban-bridge.ts. It:

  1. Reads authorization from ~/.spectral/config.json (teamApiKey or userJwt)
  2. Resolves the project ID from the Studio binding (.aexol/aexol.jsonc)
  3. Registers 7 tools via pi.registerTool() that the agent can invoke
  4. Makes direct GraphQL calls to {backendUrl}/graphql with Bearer auth
Agent chat (Studio UI)
    │
    ▼ (WebSocket relay)
spectral serve daemon
    │
    ▼ (pi subprocess)
Kanban Bridge Extension
    │
    ▼ (HTTPS GraphQL)
Aexol Backend → PostgreSQL

The bridge does not use the relay protocol for Kanban operations — it connects directly to the backend GraphQL API, following the same pattern as the aexol-mcp extension.