| name | team-kanban |
| user-invocable | false |
| description | Manage team kanban boards and tasks. Use when creating, moving, filtering, getting, or editing tasks. Trigger with /team-kanban. Loaded by ai-maestro-plugin |
| allowed-tools | Bash(amp-kanban-list.sh:*), Bash(amp-kanban-get.sh:*), Bash(amp-kanban-create-task.sh:*), Bash(amp-kanban-move.sh:*), Bash(amp-kanban-edit.sh:*), Bash(amp-kanban-archive.sh:*), Bash(aimaestro-teams.sh:*), Bash(jq:*), Bash(kanban-sync.py:*), Read, Edit, Grep, Glob |
| metadata | {"author":"Emasoft","version":"2.1.1"} |
Overview
Manage team kanban boards and tasks via the frozen amp-kanban-* CLIs + aimaestro-teams.sh kanban-config. Create, filter, get, move, edit, archive tasks; configure columns; sync with GitHub Projects v2.
Single board — anti-split-brain (team-kanban vs the ama-* design board). Two
kanban surfaces exist and are NOT interchangeable — each is the SINGLE writer of its own
domain, so there is no split brain. THIS skill is the live team-coordination
board (server-backed: who is assigned what, presence, real-time task state).
The ama-kanban-render / ama-trdd-transition skills render and move the
design/spec board where the TRDD files
under design/ ARE the board and column: is the source of truth for
design-pipeline state. A team task references a TRDD by TRDD-<id> but never
overrides its column:. When they appear to disagree: the TRDD file wins for
pipeline state; this server board wins for live assignment/presence.
Recall first (proactive memory). Before acting on a recurring problem, a design decision, or a repeated alert, recall prior lessons FIRST: /janitor-memory-recall <symptom> (shared wiki memory — index by the symptom / your words, not the fix's jargon) and /memory-search <query> (past discussion). See the proactive memory contract in the plugin CLAUDE.md.
Prerequisites
- AI Maestro running (the
amp-kanban-* / aimaestro-teams.sh CLIs resolve the API base + auth internally)
- The
amp-kanban-* + aimaestro-teams.sh CLIs on PATH; jq installed
- For GitHub sync:
gh CLI authenticated, kanban-sync.py at ~/.local/bin/
Instructions
Approval requirements. Task creation and board operations (create/move/archive/configure) on a team you belong to are min-approval-requirement: none (in-scope) — no proposal needed; act directly. Anything that escalates beyond your slice (creating a team, cross-team work) follows the ama-proposal-approvals skill and the ai-maestro approval overlay (.claude/rules/aimaestro-trdd-approval.md).
-
Identify team: aimaestro-teams.sh list | jq .
-
Create task: amp-kanban-create-task.sh "<title>" [--status S] [--priority N] [--labels "a,b"] [--assignee <id>]
-
List/filter: amp-kanban-list.sh [--status X] [--assignee Y] [--label Z]
-
Get one task: amp-kanban-get.sh <task-id> — full task object, not just the fields list filters return.
-
Move task (status only): amp-kanban-move.sh <task-id> <status>
-
Edit task (any field): amp-kanban-edit.sh <task-id> --set priority=1 --set assigneeAgentId=<uuid> or --set-json blockedBy='["<id>"]' — the general verb; every field the task PUT accepts, repeatable per call.
-
Archive/delete task: amp-kanban-archive.sh <task-id>
-
Configure columns: aimaestro-teams.sh kanban-config <team-id> --get | --set <columns-json>
-
GitHub sync: kanban-sync.py link <team-id> <owner/repo> <project-number> (out of #11 scope — keep)
When the sync posts to GitHub (issue, PR comment, project-item note), per PRRD G1.1 begin the body with a one-line self-identification of the authoring agent, since all agents share the one owner identity.
Quick CLI Reference
| Operation | CLI command |
|---|
| List / filter tasks | amp-kanban-list.sh [--status|--assignee|--label|--task-type] |
| Get one task | amp-kanban-get.sh <task-id> |
| Create task | amp-kanban-create-task.sh "<title>" [--status|--priority|--labels|--assignee] |
| Move task (status) | amp-kanban-move.sh <task-id> <status> |
| Edit task (any field) | amp-kanban-edit.sh <task-id> (--set k=v | --set-json k=<json>)... |
| Archive / delete task | amp-kanban-archive.sh <task-id> |
| Kanban config | aimaestro-teams.sh kanban-config <team-id> --get|--set <json> |
Each CLI auto-detects the team from your agent registration (pass --team <id> to override).
Authentication
The amp-kanban-* / aimaestro-teams.sh CLIs resolve your agent identity + bearer token internally — no Authorization / X-Agent-Id headers to set by hand. Pass --id <uuid> only to act as a specific agent.
Columns
Columns are per-team configurable — status must match a column id in that team's
kanban config, so read the team's real config before moving a card rather than assuming
a vocabulary (aimaestro-teams.sh kanban-config <team-id>).
The ratified vocabulary is the 17 columns — 14 lifecycle:
backburner → todo → design → dispatch → dev → testing → ai_review →
human_review → complete → publish → published → deploy → live → live_auditing
plus 3 orthogonal/terminal: blocked, failed, superseded.
The legacy five (backlog/pending/in_progress/review/completed) are obsolete
and must not be taught as the target vocabulary — but a team whose config was never
migrated may still serve them, which is exactly why you read the config instead of
assuming. Configure a team onto the ratified set with kanban-config --set (see
api-reference).
Write-gate enforcement — not every move is yours to make
The server refuses some moves. This is enforced at the write endpoint, so a move you are
not entitled to make fails with 403 rather than silently succeeding:
- GATE 1 — governed transitions need a MANAGER (by AID) or the human owner. That covers
moving a card into
human_review, complete, publish, deploy, published, live,
failed, or superseded; moving it backward into dev from human_review or
live_auditing; and writing the release-evidence fields publishedVersion / liveSince.
- GATE 2 — self-review ban. You may not render a verdict on a card you are assigned to
— writing
reviewResult, or moving it out of ai_review/human_review into complete.
Any other agent, of any title, may.
- Everything else is a free member move:
backburner, todo, design, dispatch,
dev (forward), testing, ai_review, blocked, live_auditing.
Caveat — teams on a custom column configuration. The gate matches literal column strings,
so this guarantee holds only for columns whose names match the ratified 17-column set; a
renamed governed column is not yet gated (tracked in TRDD-LY442MKH). A default-board team
needs no qualifier.
Enforcement vs. process. The write gate distinguishes only MANAGER-by-AID / owner from
everyone else, plus the self-review ban. The finer per-title routing (todo→design =
ORCHESTRATOR, design→dispatch = ARCHITECT, dispatch→dev = ORCHESTRATOR sets the assignee,
…) is the organizational contract agents follow — it is NOT mechanically enforced. Do not
rely on the server to refuse a contract violation it does not gate; see the
ai-maestro DEP overlay .claude/rules/aimaestro-trdd-approval.md (Part B) for the
routing itself.
Output
- Task list:
{"tasks":[...]} with isBlocked, blocks[], assigneeName
- Single task: object with id, subject, status, priority, timestamps
- Kanban config:
{"columns":[{id,label,color}]}
Error Handling
| HTTP | Error | Fix |
|---|
| 400 | Invalid status | Must match a column ID |
| 400 | Circular dependency | blockedBy creates cycle |
| 403 | Access denied | Agent not team member |
| 403 | Governed transition refused (GATE 1) | Move into a governed column, backward into dev from human_review/live_auditing, or a write to publishedVersion/liveSince — needs a MANAGER (by AID) or the human owner. Not a membership problem; do not go debug membership |
| 403 | Self-review refused (GATE 2) | You are the card's assignee — another agent must render the verdict |
| 404 | Not found | Invalid team/task ID |
Examples
/team-kanban create a task "Fix login bug" with priority 1 in team abc-123
Creates task via POST, returns task object with generated ID.
/team-kanban show blocked tasks in team abc-123
Lists tasks where isBlocked == true.
/team-kanban link team abc-123 to GitHub project Emasoft/ai-maestro #5
Connects team to GitHub Projects v2.
Checklist
Copy this checklist and track your progress:
Resources
- API Reference
- Operations
- List tasks
- Get task
- Create task
- Move task (status)
- Edit task (any field)
- Archive / delete task
- Get kanban config
- Set kanban config
- Team stats (residual)
- Task Lifecycle Examples
- Task Dependencies
- Kanban Configuration
- Velocity and Distribution
- Extended Task Fields
- Error Codes
- Task Storage
- Available Tailwind Colors
- Available Lucide Icons
- GitHub Sync Reference
- Prerequisites
- Setup
- Link a Team to a GitHub Project
- Unlink a Team
- Show Status
- How It Works
- Field Mapping
- Label Taxonomy (AMOA Convention)
- Custom Project Fields
- Dependency Resolution
- Status Column ID Conversion
- Caching
- Rate Limits
- Error Handling
- API Examples
- Legacy: kanban-sync.sh
- Canonical governance rules (R15 written-orders / GitHub trail, R12
minimum team composition): see the
team-governance skill, which
bundles the canonical rules and embeds the full TOC.
Use also
Skill(skill: "team-governance") — the teams and titles the board's tasks belong to.Skill(skill: "agent-messaging") — notify agents about task changes (AMP).
