Swarm Project Management

Full project management for AI agents. Hierarchical tasks, claim leases, policy-driven governance, blocking propagation, and operator-visible observability for complex multi-agent workflows.

Shipped coordination layer

Organize work into 4-level hierarchies (Initiative → Feature → Workstream → Task) with configurable policies, evidence requirements, blocking propagation, and operator-readable liveness state.

Overview

Snipara Swarm coordinates agents through claims, shared state, presence/liveness, and canonical hierarchical tasks. Legacy snipara_task_* queue aliases are no longer advertised in the canonical MCP registry; use snipara_htask_* for new work.

Surface	Best For	Key Features
Hierarchical Tasks (`snipara_htask_*`)	Agent project execution, governance, proof capture	4 levels, policies, evidence, liveness, audit trail
Legacy Queue Aliases (`snipara_task_*`)	Existing direct callers during migration	Compatibility path only, not advertised for new agents

Hierarchical Task System

Task Hierarchy

Task hierarchy

Rendering diagram...

Level	Name	Description	Typical Owner
N0	Initiative	Strategic goal spanning multiple features	Product lead / Architect
N1	Feature	End-user deliverable	Feature lead
N2	Workstream	Parallel work track (API, Frontend, QA)	Tech lead
N3	Task	Atomic unit of work	Individual agent

Creating Tasks

// Create an N3 task

snipara_htask_create({

  swarm_id: "swarm_abc123",

  level: "N3_TASK",

  parent_id: "htask_ws_api",

  title: "Implement JWT token generation",

  description: "Add signing and verification",

  owner: "agent_backend",

  priority: "P1",

  acceptance_criteria: [

    { id: "ac1", text: "JWT signed with RS256" },

    { id: "ac2", text: "Access tokens expire after 24 hours" }

],

  evidence_required: [

    { type: "test", description: "Unit tests passing" }

})

Create Feature with Workstreams

Quickly scaffold a feature with standard workstream structure:

snipara_htask_create_feature({

  swarm_id: "swarm_abc123",

  title: "User Authentication",

  owner: "alice",

  workstreams: ["API", "FRONTEND", "QA"]

})

// Response:

  feature_id: "htask_feat_001",

  workstream_ids: {

    API: "htask_ws_api",

    FRONTEND: "htask_ws_fe",

    QA: "htask_ws_qa"

Blocking & Propagation

When a task is blocked, the status propagates up the hierarchy automatically:

Blocking propagation

Rendering diagram...

Block a Task

snipara_htask_block({

  swarm_id: "swarm_abc123",

  task_id: "htask_001",

  blocker_type: "DEPENDENCY",

  blocker_reason: "Waiting for auth API",

  blocked_by_task_id: "htask_auth_api",

  eta_recovery: "2026-03-20T10:00:00Z",

  escalation_to: "tech-lead@company.com"

})

Blocker Types

Type	Description
`TECH`	Technical issue (bug, architecture)
`DEPENDENCY`	Waiting on another task
`ACCESS`	Missing permissions/credentials
`PRODUCT`	Needs product decision
`INFRA`	Infrastructure issue
`SECURITY`	Security review required

Unblock a Task

snipara_htask_unblock({

  swarm_id: "swarm_abc123",

  task_id: "htask_001",

  resolution: "Auth API is now available"

})

Policy Engine

Each swarm has configurable policies that govern task behavior:

// Get policy

snipara_htask_policy_get({ swarm_id: "swarm_abc123" })

// Response:

  maxDepth: 4,

  closurePolicy: "STRICT_ALL_CHILDREN",

  requireEvidenceOnComplete: true,

  failedIsBlockingDefault: true,

  allowParentCloseWithWaiver: true

Policy	Default	Description
`closurePolicy`	STRICT	STRICT: all children must complete. ALLOW_EXCEPTIONS: can close with waiver
`requireEvidenceOnComplete`	true	N3 tasks require evidence to complete
`allowParentCloseWithWaiver`	true	Allow closing parents with documented exceptions
`maxDepth`	4	Maximum hierarchy depth (N0-N3)

Closure & Evidence

Complete Task with Evidence

snipara_htask_complete({

  swarm_id: "swarm_abc123",

  task_id: "htask_task_001",

  evidence: [

    { type: "test", description: "15 unit tests passing" },

    { type: "review", description: "PR #123 approved" }

],

  result: { files_modified: ["src/auth/jwt.ts"] }

})

Verify Before Closing Parent

snipara_htask_verify_closure({

  swarm_id: "swarm_abc123",

  task_id: "htask_ws_001"

})

// Response:

  can_close: false,

  blockers: ["2 blocking children not completed"],

  needs_waiver: true

Close with Waiver

snipara_htask_close({

  swarm_id: "swarm_abc123",

  task_id: "htask_ws_001",

  waiver_reason: "Error handling moved to next sprint",

  waiver_approved_by: "tech-lead"

})

Observability

View Hierarchy Tree

snipara_htask_tree({

  swarm_id: "swarm_abc123",

  root_id: "htask_init_001",

  max_depth: 3

})

Get Metrics

snipara_htask_metrics({ swarm_id: "swarm_abc123", period_hours: 24 })

// Response:

  total: 45,

  by_status: { pending: 10, in_progress: 8, blocked: 3, completed: 23 },

  by_level: { N0: 1, N1: 3, N2: 9, N3: 32 },

  throughput: { closures_total: 15, per_hour: 0.63 },

  aging_days: { N0: 14.5, N1: 7.2, N2: 3.1, N3: 1.8 },

  blocked_recovered_ratio: 0.85

Audit Trail

Every action is logged for compliance and debugging:

snipara_htask_audit_trail({ swarm_id: "swarm_abc123", task_id: "htask_001" })

// Events: create, update, block, unblock, complete, close, delete, waiver

Canonical Htasks vs Legacy Queue Aliases

Feature	Legacy aliases (`snipara_task_*`)	Canonical htasks (`snipara_htask_*`)
Structure	Compatibility queue view	4 levels (N0-N3)
Blocking	Compatibility behavior only	Automatic propagation
Policies	Not the recommended surface	Configurable per swarm
Evidence	Optional result	Required with verification
Waivers	No	Documented exceptions
Audit	Basic events	Full audit trail
Metrics	Retired from advertised registry	throughput, aging, recovery ratio

All HTask Tools

Tool	Purpose
`snipara_htask_create`	Create task at any level
`snipara_htask_create_feature`	Create N1 with workstreams
`snipara_htask_get`	Get task with children
`snipara_htask_tree`	Get full hierarchy tree
`snipara_htask_update`	Update task fields
`snipara_htask_block`	Block task with payload
`snipara_htask_unblock`	Unblock task
`snipara_htask_complete`	Complete N3 with evidence
`snipara_htask_verify_closure`	Check if parent can close
`snipara_htask_close`	Close parent (with waiver)
`snipara_htask_delete`	Soft/hard delete
`snipara_htask_recommend_batch`	Get ready N3 tasks
`snipara_htask_policy_get`	Get swarm policy
`snipara_htask_policy_update`	Update policy (admin)
`snipara_htask_metrics`	Get observability metrics
`snipara_htask_audit_trail`	Get task event history
`snipara_htask_checkpoint_delta`	Incremental sync

Best Practices

Use consistent owners — Assign clear ownership at each level
Set realistic acceptance criteria— Define what "done" means upfront
Require evidence for N3 tasks — Prevents premature closure
Use blocking propagation wisely — Mark non-critical tasks as non-blocking
Document waivers — Always provide clear waiver reasons
Monitor blocked_recovered_ratio — Low ratio indicates systemic blockers
Archive completed initiatives — Keep active tree clean

Next Steps

Multi-Agent Coordination

Resource locking, shared state, and flat task queues.

Agent Memory

Persistent memory across sessions.

Agents Overview

Introduction to Snipara Agents.

Go to Dashboard

Start building with hierarchical tasks.