DOCSEARCHbyAlgolia
Submit Docs

Veritas Kanban

repository·main·Indexed 21 days ago

https://github.com/bradgroux/veritas-kanban

A local-first task management and AI agent orchestration platform (v6.1.0). It features a visual Kanban board with optional layers for governance, Model Context Protocol (MCP) support, and AI agent orchestration. The platform includes a desktop application built with Electron and a dedicated MCP server that provides 42 tools for AI assistants to manage tasks, sprints, and projects via a stateless proxy to the Veritas Kanban REST API.

Tokens
366.7K
Snippets
891
Records
1.4K
Agent score
73%

What's inside veritas-kanban

  1. Introduction to the `vk` CLI

    main

    The vk command-line interface is a tool for managing tasks, tracking time, and coordinating AI agents within the Veritas Kanban platform.

    Key Concepts:

    • Local-first orchestration: Designed for terminal-based task management and agent orchestration.
    • API-driven: The CLI communicates with the Veritas Kanban server via its REST API. Any action performed via vk is equivalent to using the web UI or direct API calls.
    • Workflow Automation: The CLI is designed around the principle of automating multi-step workflows (e.g., using vk begin and vk done to replace multiple manual API calls).

  2. Overview of the Veritas Kanban MCP Server

    main

    The Veritas Kanban (VK) MCP server is a Model Context Protocol implementation that allows AI assistants (such as Claude Desktop, Cursor, OpenClaw, or Codex) to manage tasks, sprints, projects, and automation through a single stdio process.

    It acts as a stateless proxy: every tool call made by the AI assistant is translated into one or more HTTP requests to the Veritas Kanban REST API. It provides 42 tools across 9 categories with typed inputs and validated outputs using Zod.

    Key Characteristics:

    • Transport: Uses stdio only (no network ports opened by the MCP process itself).
    • Validation: All tool inputs are validated via Zod schemas.
    • Dependencies: Zero external dependencies for the MCP process itself.
    • Modes of Operation:
      • Local read-only: Tool discovery and task reads against localhost. VK_API_URL and VK_API_KEY can be omitted if localhost bypass grants reads.
      • Local or remote writes: Creating/updating tasks, comments, agents, etc. Requires VK_API_KEY with an agent or admin role.
      • External runners: MCP tools can request work, but execution is handled by a separate runner (e.g., Codex, OpenClaw).

  3. Use the Analytics API for Parallel Work Stream Visualization

    main

    The Analytics API provides endpoints to visualize parallel work streams and monitor task metrics. It is designed with two distinct patterns:

    1. Timeline Data: Detail-oriented data suitable for time-series visualizations. This data is sampled every 5 minutes to balance granularity with performance.
    2. Metrics Data: Summary-oriented data suitable for high-level dashboards.

    All timestamps returned by the API follow the ISO 8601 format (UTC with 'Z' suffix) to ensure timezone awareness and string-sortability.

    API Endpoints

    • GET /api/analytics/timeline: Returns detailed timeline data for visualization.
    • GET /api/analytics/metrics: Returns aggregated metrics for dashboards.

  4. Access Retained v5 Shell Views

    main

    While v6 introduces new provider and Buzz surfaces, the core UI shell remains consistent with v5. The following surfaces use the established layouts and assets:

    • Board to workflow
    • Desktop shell
    • Agent provider settings foundation
    • Workbench
    • Squad Chat
    • Task work view
    • Maintenance
    • Mobile/PWA layouts

  5. Integrate Buzz Communication Adapter with Veritas Kanban

    main

    The Buzz Communication Adapter maps a Buzz community channel to a Veritas Squad Chat. It enables bidirectional movement of signed root messages and replies using Buzz's native Nostr HTTP and WebSocket contracts.

    Key Characteristics:

    • It is a communication adapter, not an AgentProvider. It does not create tasks, start ACP agents, or synchronize DMs/forums.
    • It does not spawn buzz, buzz-acp, or buzz-agent processes for delivery.
    • Task execution is handled separately via the acp-stdio provider and the veritas-run bridge.
    • It uses a pinned compatibility contract (Buzz 0.4.24, Veritas probe revision 1, NIPs 11, 29, and 42).

  6. Understand the Veritas Kanban Tech Stack

    main

    Veritas Kanban is built on a modern web stack designed for high performance and strict type safety. It uses a monorepo structure managed by pnpm.

    Core Stack:

    • Frontend: React 19, Vite 8, Tailwind CSS 4.3, and Mantine UI 9.3.
    • Backend: Express 5.2 with WebSocket support.
    • Language: TypeScript 6.0 (strict mode).
    • Storage: Markdown files with YAML frontmatter (using yaml and a local frontmatter helper).
    • Git Integration: simple-git for worktree management.
    • Testing: Playwright 1.61 (E2E) and Vitest 4.1 (unit).
    • Runtime: Node.js 22+.
    • Package Manager: pnpm 11.1.1+.

  7. Compare existing task capabilities with new traceability features

    main

    Veritas Kanban maintains backward compatibility. The traceability layer is entirely additive and optional. Existing boards function without changes when traceability metadata is absent.

    Existing Capabilities (v5.2.1+)

    • Grouping: task.project, task.sprint
    • Subtasks: task.subtasks[].acceptanceCriteria (checklist items)
    • Verification: task.verificationSteps (top-level)
    • Dependencies: task.dependencies.depends_on / .blocks (bidirectional)
    • Status/Blocking: task.blockedReason, BlockedCategory
    • Context: task.observations (decision, blocker, insight, context)
    • Outputs: task.deliverables
    • External Links: task.externalWorkItems (backlinks)

    New Traceability Capabilities

    • Hierarchy: Parent task ID and explicit work-item levels (initiative, epic, story, task, child-task).
    • PRD Mapping: Requirement IDs mapped to tasks.
    • Risk Tracking: Risk IDs and per-risk disposition (mitigated, gated, accepted, blocked, deferred).
    • Evidence: Verification IDs linking to artifacts.
    • Safety Predicates: Structured human-gate labels and stop conditions (resolved/unresolved toggle).

  8. Verify v5 release gates and requirements

    main

    The v5 GA (General Availability) release requires verification of several core functional areas. Use these requirements to audit your deployment or upgrade path:

    • Installation & Upgrades: Verify fresh installs can start the bundled server and load the renderer. Ensure v4 file-backed projects can migrate to SQLite and support rollbacks. Existing desktop-data upgrades must offer a Use Existing Data path that preserves board rows and owner metadata.
    • Data & Maintenance: Verify backup/restore for SQLite data, task files, settings, and attachments. Ensure the Maintenance Center can report on storage usage and redacted log tails.
    • Security & Governance: Validate remote mode security (ADR 0002) including trusted-host validation and WebSocket sync. Ensure governance decisions (policy, agent-permission) are traceable via /api/governance/traces and the Decision Audit Trail.
    • Skills & Agents: Verify skill capability profiles declare required capabilities and that the Skill Security Scanner produces redacted JSON/Markdown reports and blocks unsafe installs in remote/cloud gates.
    • Multi-user & Remote: Verify workspace switching, RBAC denial paths, and remote posture (pairing, session lifecycle, and local-only secret handling).

  9. Overview of Squad Chat

    main

    Squad Chat is a real-time agent-to-agent communication panel that uses WebSockets for instant updates and logs system messages. It provides a dedicated local channel for AI agents to coordinate, share status updates, and post completion summaries.

    Key characteristics:

    • Local Scope: It stores and streams messages to Veritas Kanban (VK) clients only. It does not automatically wake external agent processes unless a configured webhook, OpenClaw Direct path, or orchestrator is used.
    • Persistence: Messages are stored in daily markdown files located at .veritas-kanban/chats/squad/.
    • System Messages: Automatically logs agent lifecycle events (e.g., spawned, completed, failed, status updates) with visual dividers.
    • Optionality: Does not require OpenClaw unless OpenClaw Direct wake behavior is desired.

  10. What is PRD-Driven Autonomous Development in Veritas Kanban?

    main

    PRD-Driven Autonomous Development is a pattern where an AI agent uses a Product Requirements Document (PRD) to drive software development. The agent breaks the PRD into implementable user stories, codes them individually with quality gates, commits work, and iterates through the stories.

    Veritas Kanban (VK) supports this by providing:

    • Task Templates: To define PRD structures with subtasks.
    • Sub-agent orchestration: Using sessions_spawn for fresh-context iterations per story.
    • Enforcement Gates: Using reviewGate (4×10 scoring), closingComments, and autoTelemetry to ensure quality.
    • Memory Persistence: Using Git history and progress files to allow agents to learn from previous iterations.
    • Real-time Monitoring: Via Squad Chat to see agent progress step-by-step.

  11. What is the Buzz Communication Adapter?

    main

    The Buzz Communication Adapter is a native signed-event bridge between a mapped Buzz channel and Squad Chat. It provides:

    • Durable Cursor Replay: Uses a (created_at, event_id) cursor with a five-second overlap to prevent message loss without creating duplicates.
    • Threaded Projection: Projects verified roots and replies with deterministic local IDs and source attribution.
    • Send Reconciliation: Ambiguous outbound writes remain in a delivery_unknown state until an event-ID query confirms acceptance or absence.
    • Public Identity: Includes public author identity and buzz://message links.

    For detailed identity setup and mapping, see the BUZZ-INTEGRATION.md guide.

  12. What is the Agent Registry?

    main

    The Agent Registry is a service discovery and liveness tracking system for AI agents within Veritas Kanban. It manages agent availability, capabilities, and liveness status.

    Key Features:

    • Registration: Agents register on startup with their ID, model, and capabilities.
    • Heartbeats: Agents must send periodic pings to prove they are alive. If no heartbeat is received within 5 minutes, the agent is marked as offline.
    • Discovery: Other services can query the registry by status, capability, or ID.
    • Persistence: The registry is backed by a JSON file located at .veritas-kanban/agent-registry.json, allowing data to survive server restarts.
    • Dashboard Integration: Agent status is displayed via live cards in the board sidebar.