The Kanban System

01 Core Concepts

The kanban system is a Next.js app artifact published at /pub/main/kanban-v2/. It manages work through a hierarchy of projects, columns, and tasks, all backed by a shared SQLite database.

Database Tables

All data lives in the shared SQLite database. Key tables:

02 API Reference

All endpoints are relative to the kanban artifact base URL. From agents running in the same system, use the Dashboard API proxy.

Projects

Tasks

Subtasks & Tests

Dependencies

Example: Create a Full Task

# Create the task
curl -s -X POST "http://localhost:4000/pub/main/kanban-v2/api/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "[Build] Add search to web3-skills explorer",
    "description": "## Objective\nAdd fuzzy search...\n\n## Target Artifact\n/workspace/group/pub/web3-skills/",
    "project_id": 11,
    "column_id": 41,
    "priority": "high",
    "labels": "build, artifact, search",
    "size_category": "M"
  }'

# Add subtasks
curl -s -X POST "http://localhost:4000/pub/main/kanban-v2/api/tasks/735/subtasks" \
  -H "Content-Type: application/json" \
  -d '{"title": "Implement fuzzy search index"}'

# Add a dependency (depends on task 724)
curl -s -X POST "http://localhost:4000/pub/main/kanban-v2/api/tasks/735/dependencies" \
  -H "Content-Type: application/json" \
  -d '{"depends_on_task_id": 724}'

# Assign an AI agent to work on it
curl -s -X POST "http://localhost:4000/pub/main/kanban-v2/api/tasks/735/assign-agent"

03 Task Lifecycle

Task Fields

• title — Short, action-oriented. Prefix with category: [Build], [Discovery], [Review]
• description — Detailed instructions with Objective, Tasks, Target Artifact, Acceptance Criteria sections
• priority — low, medium, high, urgent
• labels — Comma-separated tags for filtering: "build, artifact, sprint-1"
• size_category — XS (1-2h), S (2-4h), M (4-8h), L (8-16h), XL (16h+)
• agent_task_id — Set when an agent is assigned. Links to the scheduled task.

Moving Tasks

Move a task between columns using the move endpoint. This is how agents signal completion:

# Move task 721 to "Done" column (column_id 43)
curl -s -X POST "http://localhost:4000/pub/main/kanban-v2/api/tasks/721/move" \
  -H "Content-Type: application/json" \
  -d '{"column_id": 43, "position": 0}'

04 Agent Assignment

Assigning an agent to a task spawns a scheduled task that runs in the group's context. The agent reads the task description as its instructions.

How It Works

1. Call POST /api/tasks/[id]/assign-agent
2. The kanban server creates a scheduled task via the Dashboard API
3. The task description becomes the agent's prompt
4. The agent runs autonomously and interacts with the kanban API to update progress
5. When done, the agent moves the task to Done

Agent Prompt Structure

The agent receives a structured prompt built from the task. Write task descriptions that work as agent instructions:

## Objective
What the agent should accomplish in one sentence.

## Context
Background knowledge. Reference vault notes, previous tasks, existing code.

## Tasks
1. Specific step with file paths
2. Another step with expected output
3. Final step with verification

## Target Artifact
Path to the artifact this task modifies.
Include restart_artifact instructions.

## Acceptance Criteria
- Verifiable outcome 1
- Verifiable outcome 2
- Verifiable outcome 3

05 Dependencies & Ordering

Dependencies create a directed acyclic graph (DAG) that enforces execution order. A task is "blocked" if any of its dependencies are not in the Done column.

Setting Dependencies via DB

You can also set dependencies directly via the database for bulk operations:

-- Add sequential dependencies for tasks 727-733
INSERT INTO task_dependencies (task_id, depends_on_task_id)
VALUES (728, 727), (729, 728), (730, 729),
       (731, 730), (732, 731), (733, 732);

Checking Blocked Status

# Get the next unblocked task for a project
curl -s "http://localhost:4000/pub/main/kanban-v2/api/dependencies/next?project_id=11"

# Check which tasks are blocked
curl -s "http://localhost:4000/pub/main/kanban-v2/api/dependencies/blocked?project_id=11"

06 Auto Mode

Auto Mode automatically assigns an agent to the next unblocked task when the current one completes. Combined with dependencies, this creates a fully autonomous pipeline.

Enabling Auto Mode

# Toggle auto mode on
curl -s -X POST "http://localhost:4000/pub/main/kanban-v2/api/auto-mode/toggle" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Check status
curl -s "http://localhost:4000/pub/main/kanban-v2/api/auto-mode/status"

07 Research Engine

The kanban board includes a built-in research engine that can run multi-round AI research sessions attached to tasks. Research findings can be converted into new tasks.

Research Patterns

• single — One-shot analysis. Good for quick assessments.
• breadth_depth — First round scans broadly, subsequent rounds dive deep into promising areas.
• deep_dive — All rounds focus on a single area with increasing depth.

08 Recursive Task Resolution

The most powerful pattern in the kanban system: tasks that create tasks. A task-designer task is like a Promise — unresolved at write time, it synthesizes all prior work just-in-time when executed.

The Promise Analogy

Task Type Taxonomy

The Self-Improving Loop

Artifact Accumulation

Promise tasks become even more powerful when every task targets the same artifact:

09 Expansion Tasks

Beyond the standard task types, Expansion tasks are a higher-order pattern. They don't just continue a project — they reimagine it. An expansion task takes the current state of an artifact and asks: what could this become?

Three Expansion Modes

Expansion Task Template

## Objective
[Expand / Refine / Reimagine] the {artifact-name} artifact.

## Expansion Mode
[goal-driven | synthesized | reimagined]

## Goals (if goal-driven)
- Goal 1: ...
- Goal 2: ...

## Context Sources (read all before designing)
- Current artifact: /workspace/group/pub/{artifact-name}/
- Vault notes: search vault for related knowledge
- Research findings: check research_findings table for this project
- User feedback: check kanban_comments on completed tasks
- Shared vault: vault_search_shared("{domain}") for cross-group insights

## Tasks
1. Read and analyze the current artifact thoroughly
2. If synthesized mode: identify 3-5 expansion directions, rank by value
3. If reimagined mode: challenge 3 core assumptions, propose alternatives
4. Design 8-12 implementation tasks for the chosen direction
5. Each task must target the existing artifact (not create a new one)
6. Include a backup task BEFORE any destructive changes
7. End with a new expansion task for the next cycle

## Acceptance Criteria
- Expansion direction justified with evidence from context sources
- All new tasks reference the target artifact
- Backup created before any architectural changes
- Next expansion task created at the end

How Expansion Differs from Sprint Design

The Expansion Cycle

Expansion tasks create a second loop on top of the sprint loop:

Expansion + Artifact Merging

The most powerful expansion pattern: merging two artifacts into one. When an expansion task notices that two artifacts serve overlapping purposes, it can propose a merge:

## Expansion: Merge web3-skills into idealabs
The web3-skills explorer (52 skills, filtering, taxonomy) would be
more valuable embedded in the ideaLabs platform as a "capabilities"
tab that links skills to hackathon ideas.

## Merge Plan
1. backup_artifact_db(name="web3-skills")
2. backup_artifact_db(name="idealabs")
3. Copy web3-skills data into idealabs schema
4. Build "Capabilities" tab in idealabs UI
5. Redirect web3-skills to idealabs/capabilities
6. Unpublish standalone web3-skills after verification

10 Platform Safety & Backup

Every task that modifies an artifact should include safety checkpoints. Emblem:build provides backup, restore, and cross-publish tools that agents should use proactively.

Backup Capabilities

Table Registration (Required)

Before backup/restore works, tables must be registered in the artifact's package.json:

{
  "name": "my-artifact",
  "emblem_build": {
    "tables": [
      {
        "name": "items",
        "schema": "CREATE TABLE IF NOT EXISTS items (id TEXT PRIMARY KEY, name TEXT, data TEXT, created_at TEXT DEFAULT (datetime('now')))"
      }
    ]
  }
}

When to Backup

Rollback Pattern

If something goes wrong during a sprint or expansion:

# 1. Before risky work — create checkpoint
backup_artifact_db(name="web3-skills")

# 2. Do the risky work...
#    (schema migration, data transform, etc.)

# 3. If something broke — rollback
restore_artifact_db(name="web3-skills")
restart_artifact(name="web3-skills")

# 4. If everything worked — backup the new state
backup_artifact_db(name="web3-skills")

Cross-Publishing for Redundancy

For critical artifacts, cross-publish to a linked peer as an off-site backup:

# 1. Backup database to include data in the push
backup_artifact_db(name="web3-skills")

# 2. Check available peers
list_peer_links()

# 3. Push to remote peer
cross_publish_artifact(
  peer_id="peer-xxx",
  name="web3-skills",
  source_path="pub/web3-skills",
  type="app",
  entry_point="node server.js",
  is_public=true
)

# Remote restores db-backup.sql automatically on boot

Safety Checklist for Tasks

Every task description that modifies an artifact should include these safety steps:

Kanban Project Export

Export an entire project's state for archival, migration, or cross-instance transfer:

# Export full project state as JSON
curl -s "http://localhost:4000/pub/main/kanban-v2/api/projects/11/export" \
  | jq . > /workspace/group/backups/recursiveWeb3-export.json

# Includes: project metadata, columns, tasks, subtasks,
# acceptance criteria, tests, comments, dependencies,
# research sessions, findings, proposals

Vault as Backup Context

The vault provides semantic backup — even if an artifact is lost, vault notes preserve the knowledge that built it:

11 Database Patterns

Every artifact that persists data uses the shared SQLite database. Understanding how to design, document, and manage schemas is critical for building reliable artifacts.

Access Methods

Schema Design Principles

• Prefix table names with the artifact name: kanban_tasks, research_sessions — avoids collisions in the shared database
• Always CREATE TABLE IF NOT EXISTS — idempotent schemas that can run on every boot
• Include created_at and updated_at on every table — essential for debugging and activity feeds
• Use ON DELETE CASCADE explicitly — SQLite's default is NO ACTION, which blocks deletes on parent rows
• Add indexes for columns you filter/join on frequently

Documenting Schemas

Every artifact's schema should be documented in three places:

Schema Documentation Template

---
description: Database schema for {artifact-name} — {N} tables covering {domain}
topics: [platform, database, {artifact-name}]
---

# {Artifact Name} Database Schema

## Overview
Brief description of what data the artifact manages and why.

## Tables

### {table_name}
Purpose: What this table stores and why.
Relationships: FK to {other_table}, referenced by {other_table}.

| Column | Type | Description |
|--------|------|-------------|
| id | INTEGER PK | Auto-increment primary key |
| name | TEXT NOT NULL | Display name |
| created_at | TEXT | ISO timestamp, defaults to now |

Key queries:
- List active items: `SELECT * FROM {table} WHERE status = 'active'`
- Count by category: `SELECT category, COUNT(*) FROM {table} GROUP BY category`

### {next_table}
...

## Migrations
| Date | Change | SQL |
|------|--------|-----|
| 2026-04-19 | Added status column | `ALTER TABLE items ADD COLUMN status TEXT DEFAULT 'active'` |

## Relationships Diagram
{table_a} 1──N {table_b} (via table_a_id FK)
{table_b} 1──N {table_c} (via table_b_id FK, CASCADE)

Migration Patterns

SQLite has limited ALTER TABLE support. Use these patterns:

# Adding a column (safe, always works)
db_execute("ALTER TABLE items ADD COLUMN status TEXT DEFAULT 'active'")

# Adding an index (safe)
db_execute("CREATE INDEX IF NOT EXISTS idx_items_status ON items(status)")

# Renaming a column (SQLite 3.25+)
db_execute("ALTER TABLE items RENAME COLUMN old_name TO new_name")

# Complex migration (recreate table)
# 1. Backup first!
backup_artifact_db(name="my-app")

# 2. Create new table with desired schema
db_execute("CREATE TABLE items_new (id INTEGER PRIMARY KEY, ...)")

# 3. Copy data
db_execute("INSERT INTO items_new SELECT ... FROM items")

# 4. Swap tables
db_execute("DROP TABLE items")
db_execute("ALTER TABLE items_new RENAME TO items")

# 5. Verify and backup new state
backup_artifact_db(name="my-app")

The Dashboard API Pattern (App Artifacts)

Published app artifacts access the database through the Dashboard API. The browser talks to your server, your server talks to the API:

const API = process.env.DASHBOARD_BASE || 'http://localhost:4000';
const TOKEN = process.env.DASHBOARD_TOKEN;
const GROUP = process.env.ARTIFACT_GROUP || 'main';

// Read endpoint
app.get('/api/items', async (req, res) => {
  const sql = 'SELECT * FROM items WHERE status = ? ORDER BY created_at DESC LIMIT 50';
  const r = await fetch(
    `${API}/api/db/${GROUP}/database/query?sql=${encodeURIComponent(sql)}¶ms=${encodeURIComponent(JSON.stringify(['active']))}`,
    { headers: { Authorization: `Bearer ${TOKEN}` } }
  );
  const data = await r.json();
  res.json(data.rows || []);
});

// Write endpoint
app.post('/api/items', express.json(), async (req, res) => {
  const sql = 'INSERT INTO items (name, category) VALUES (?, ?)';
  const r = await fetch(`${API}/api/db/${GROUP}/database/execute`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ sql, params: [req.body.name, req.body.category] })
  });
  res.json(await r.json());
});

Schema Discovery

When working with an unfamiliar artifact, discover its schema:

# 1. Inspect the artifact (shows registered tables)
inspect_artifact(name="kanban-v2")

# 2. Get full schema from the database
db_schema()

# 3. Check package.json for the manifest
cat /workspace/group/kanban-v2/package.json | jq '.emblem_build.tables'

# 4. Run sample queries to understand the data
db_query("SELECT COUNT(*) as n, typeof(id) as id_type FROM kanban_tasks")
db_query("SELECT sql FROM sqlite_master WHERE type='table' AND name LIKE 'kanban_%'")

12 Best Practices

Writing Task Descriptions

Task descriptions are agent instructions. The better they are, the better agents perform.

• Include exact file paths — /workspace/group/pub/web3-skills/server.js not "the server file"
• Specify the target artifact — which published artifact does this modify?
• Include restart instructions — restart_artifact(name="web3-skills")
• Reference vault notes — link to relevant knowledge for context
• Define acceptance criteria — verifiable outcomes, not vague goals

Sprint Sizing

• 10-15 implementation tasks per sprint is the sweet spot
• Mix sizes: quick wins (XS/S) keep momentum, medium tasks (M) deliver value
• Avoid XL tasks — break them down into multiple M tasks
• Max 3 skills or focus areas per task — prevents context overload

Dependency Design

• Sequential chains for ordered work: Discovery -> Plan -> Build -> Review
• Fan-out for parallel work: Task Designer creates 10 independent impl tasks
• Fan-in for gates: Review depends on ALL implementation tasks
• Always end with a meta-task that creates the next sprint

The Golden Rule

Tasks Creating Tasks

Tasks are allowed — and encouraged — to create other tasks. This is what makes the system recursive. But there are rules about when a task should spawn new tasks to protect sprint velocity.

Default Behavior

By default, when an agent discovers additional work during a task, it should:

1. Log the finding as a comment on the current task
2. Create a new task in the To Do column tagged for the next sprint
3. Continue working on its current task without scope creep

This prevents sprint blowout. A discovery task that finds 5 unexpected issues should not spawn 5 urgent tasks mid-sprint — it should document them and let the next sprint's task-designer prioritize them with full context.

Project Notes as Permission Grants

Project notes (kanban_project_notes) can grant agents explicit permission to create tasks for the current sprint. This is the escape hatch for critical issues.

## Task Creation Policy

### Immediate (current sprint)
Agents may create and assign tasks in the current sprint ONLY for:
- Security vulnerabilities discovered during implementation
- Broken dependencies that block other tasks
- Data loss risks that need immediate mitigation

These tasks should be tagged "hotfix" and sized XS or S.

### Deferred (next sprint)
ALL other discovered work goes to the next sprint:
- Feature ideas discovered during implementation
- Refactoring opportunities
- Nice-to-have improvements
- Non-blocking bugs

Tag these "discovered, sprint-N+1" so the next task-designer
can incorporate them with full context.

The Task Creation Decision Tree