veritas-kanban/docs/GETTING-STARTED.md

Getting Started with Veritas Kanban

Credit: This guide exists because Neal (@nealmummau) asked how to get Veritas Kanban working with AI agents in under five minutes. Thank you for pushing us to document the real workflow.

Whether you are standing up the board for yourself or for a fleet of agents, this guide walks you from zero ➝ working board ➝ agents picking up work. Each section is short, copy/paste friendly, and mirrors how we run Veritas Kanban internally.

If you are evaluating VK for the first time, start with the board-only path. MCP, OpenClaw, Squad Chat webhooks, notification delivery, workflow gates, and governance policies are optional layers. The setup paths are broken out in Setup Paths.

A working board is not the same as agent-ready or external wake/delivery-ready. First verify the UI and API health endpoint, then use the readiness levels to decide whether CLI, MCP, runners, webhooks, or notifications are actually needed.

---

Table of Contents

1. Prerequisites (30 seconds)
2. Installation & Setup Wizard
3. Create Your First Task (UI path)
4. Create Your First Task (API/CLI path)
5. Connect an Agent + Agent Pickup Checklist
6. Sanity Checks & Quick Fixes
7. Shared Resources & Prompt Registry
8. Documentation Freshness & Repo Rules
9. Multi-Repo / Multi-Agent Notes
10. OpenClaw Browser Relay (Optional)
11. What's Next?

---

Prerequisites (30 seconds)

What	Command	Notes
Node.js	node -v	Requires 22+. Install via Volta/nvm if older.
pnpm	pnpm -v	Requires 11.1.1+. Prefer corepack prepare pnpm@11.1.1 --activate.
Git	git --version	Any current version works.
(Optional) Docker	docker --version	Needed only if you prefer containers.

That's it. No database, no extra services.

---

Installation & Setup Wizard

Quick Start with vk setup

After cloning and starting the server, run the setup wizard to verify your environment. If the vk command is not installed yet, finish the manual setup first and then build/link the CLI from the CLI guide.

vk setup

This checks Node version, server health, API access, and optionally creates a sample task to get you started.

For a deeper support-safe setup check, run:

vk doctor
vk doctor --json
vk snapshot --format markdown

vk doctor checks the CLI link, API reachability, auth context, task identity conflicts, configured agent executables, routing fallbacks, prompt registry, Codex readiness, and notification/webhook configuration. Output redacts local paths and delivery URLs by default; use --show-paths only when you explicitly want local paths in the report.

vk snapshot exports a paste-safe runtime support snapshot with version, project, sprint, agent, global agent status, routing, prompt, task-count, notification, and maintenance-health sections. Use --output <path> to write JSON or Markdown to a file.

Manual Setup

If you prefer step-by-step control, follow the manual wizard below:

1. Clone & install

git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
pnpm install

2. Configure server

a. Copy the sample env

cp server/.env.example server/.env

b. Edit the new file:

• VERITAS_ADMIN_KEY → 32+ chars (use node -e "console.log(crypto.randomBytes(32).toString('hex'))")
• VERITAS_AUTH_ENABLED=true (default)
• VERITAS_AUTH_LOCALHOST_BYPASS=true to avoid auth friction locally
• Optional: set TRUST_PROXY when running behind a reverse proxy (nginx, Caddy, Traefik, Synology DSM). For example, TRUST_PROXY=1 to trust a single proxy hop. See the Deployment Guide for details.
• Optional: set HOST=127.0.0.1 (avoids proxy ambiguity)

3. Start the dev stack

pnpm dev

Web boots on 3000, API on 3001. First boot seeds demo tasks so you have something to look at.

4. Run the in-app setup

Visit http://localhost:3000 → follow the onboarding form:

• Create your admin password
• Save the recovery key (seriously; it's the only way to regain access)
• Log in and confirm you can see the seeded board

🧙 Tip: Run vk setup for the guided first-run flow and vk doctor when you need a deeper setup health report.

---

Create Your First Task (UI path)

1. Click New Task on the board.
2. Fill title, description (Markdown), pick a type + priority.
3. Optional: assign a sprint/project.
4. Hit Create and watch it appear in Todo.
5. Drag it to In Progress to feel the flow.

Need a clean slate? Remove the example tasks: rm tasks/active/task_example_*.md

---

Create Your First Task (API/CLI path)

REST call (curl)

curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_ADMIN_KEY>" \
  -d '{
    "title": "Wire up MCP server",
    "description": "Create CLI + MCP parity",
    "type": "feature",
    "priority": "high"
  }'

CLI (after cd cli && npm link)

pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/cli build
cd cli
npm link
export VK_API_URL=http://localhost:3001
vk create "Wire up MCP server" --type feature --priority high
vk list --status todo

CLI commands fully mirror the API and are the fastest way to script agent workflows. Write commands need VK_API_KEY unless localhost bypass grants an agent or admin role.

---

Connect an Agent + Agent Pickup Checklist

This section is optional. Agents interact through HTTP + WebSocket; nothing is hard-coded to a particular provider. Creating an agent request records the work VK wants done, but an external runner/provider still has to execute it.

1. Create an agent API key in server/.env:

   VERITAS_API_KEYS=my-agent:super-secret-key:agent,ops:another-key:admin
   

2. Restart pnpm dev so the key loads.
3. Export the key for CLI, MCP, or agent scripts:

   export VK_API_URL=http://localhost:3001
   export VK_API_KEY=super-secret-key
   

4. Confirm a runner/provider is installed and running if you expect autonomous execution. Examples: OpenClaw, Codex CLI/SDK, Codex Cloud, or a custom process that polls VK and updates task state.
5. Create an agent request (UI → Start Agent) or drop a JSON file in .veritas-kanban/agent-requests/.
6. Watch pending agents in the UI or via CLI:

   vk agents:pending
   

7. Agent workflow (example prompt to an agent runner):

   Hey Veritas, pick up task <ID>. Set status to in-progress, start the timer, do the work, then call `vk done <id> "summary"` when finished. Use cross-model review if you wrote code.
   

8. Agent completion
   • Verify tasks/active/... reflects status/time tracking
   • Check .veritas-kanban/logs/agents.log for run details
   • Confirm UI Agent Status indicator flips back to Idle

Automation tip: Keep a prompts/ folder (see below) so agents get consistent instructions for sprint planning, reviews, research, etc.

---

Sanity Checks & Quick Fixes

These cover the "something feels off" moments before you deep-dive logs.

1. API health (up in <1s)

curl -s http://localhost:3001/api/health | jq

Expect { "ok": true, "service": "veritas-kanban", ... }. If the call hangs or returns HTML, something else is on the port.

2. UI health

• Browser hard refresh (Cmd/Ctrl + Shift + R)
• If blank, open devtools → Console for errors.
• Verify WebSocket indicator (top right) shows Connected; if not, check proxies/CORS.

3. Agent pickup sanity

• .veritas-kanban/agent-requests/ should have JSON per request. If files accumulate, agents are not acknowledging them.
• vk agents:pending returning nothing while UI shows pending usually means API key mismatch; regenerate and restart.

4. Common failure modes & instant fixes

Symptom	Quick Fix
Ports collide / UI hung	pnpm dev:clean
Health endpoint returns 404	Wrong project running on 3001 (restart)
Auth spamming rate limit	Ensure request IP is 127.0.0.1 or increase limiter
Agents "never pick up"	Verify the external runner/provider is running, API key role is agent, and network access works

For deeper debugging see docs/TROUBLESHOOTING.md.

---

Shared Resources & Prompt Registry

BoardKit Orchestrator inspired us here: keep prompts, skills, and guidelines in one place so every repo/agent stays in sync.

Veritas Kanban includes a starter prompt-registry/ with 10 templates:

prompt-registry/
├── sprint-planning.md      # Break epics into sprints
├── worker-handoff.md       # PM → Worker assignment
├── cross-model-review.md   # Claude ↔ GPT review gate
├── feature-development.md  # E2E feature implementation
├── bug-triage.md           # Investigation and fix
├── research-report.md      # Deep research deliverable
├── task-completion.md      # Pre-completion checklist
├── blocked-escalation.md   # Blocker reporting
├── pm-orchestration.md     # PM agent managing workers
└── standup-summary.md      # Daily status report

Usage:

1. Reference in task descriptions: See prompt: prompt-registry/cross-model-review.md
2. Copy and customize for your team's conventions
3. Preview runtime registry changes: vk prompts import prompt-registry --dry-run
4. Apply new templates: vk prompts import prompt-registry
5. When spawning agents (OpenClaw sessions_spawn), paste the relevant prompt

vk prompts import derives stable template IDs from frontmatter id values or filenames, skips README.md by default, and reports created, updated, unchanged, conflicting, and malformed files. Existing runtime templates that differ from disk are reported as conflicts unless you pass --force.

Multi-repo setup: See SOP-shared-resources.md for patterns on sharing prompts across multiple repositories.

---

Documentation Freshness & Repo Rules

Stale docs = hallucinating AI. Keep these files current:

File	Purpose
CLAUDE.md	Agent rules, architecture, lessons learned. Current repo source.
AGENTS.md	Optional local agent instructions if your deployment uses that file.
SOUL.md	Optional tone/voice guide if your team keeps one.
GPT.md / CODEX.md	Optional model-specific guardrails.
docs/BEST-PRACTICES.md	Patterns and anti-patterns all agents follow.

Cadence:

• Update immediately after a mistake or new learning.
• Run monthly freshness audits (see SOP-documentation-freshness.md).
• During sprint closure, skim the "Lessons Learned" field on each task and propagate anything evergreen into AGENTS/CLAUDE.

Automation: Future versions will include a "Doc Steward" agent that summarizes recent commits and suggests doc updates. See the Doc Freshness SOP for the roadmap.

---

Multi-Repo / Multi-Agent Notes

Running multiple projects or repos with the same agent pool? Borrow BoardKit's approach:

• Keep shared assets (skills, prompts, SOPs) under a top-level shared/ folder.
• For each repo, mount/symlink only what you need (manual today; native support in US-1611).
• Use consistent naming for agent API keys so dashboards stay readable (project-agent-name).
• Record sub-agent usage with vk agent sub-agent <count> so the Agent Status sidebar matches reality.

---

OpenClaw Browser Relay (Optional)

Use OpenClaw's Browser Relay only for auth-required browser workflows such as research behind Okta, customer dashboards, or other tasks where the runner must use your active browser session:

1. Install the extension + helper from the OpenClaw docs.
2. Launch the relay; attach your tab.
3. Agents can now run headless instructions through your actual browser session while respecting your credentials.

Skip this for board-only use, REST/CLI/MCP task management, or agents that do not need your browser cookies.

---

What's Next?

0. API Reference — Complete endpoint catalog, auth, examples, WebSocket, and common workflows.
1. Read the SOPs:
   • Agent Task Workflow
   • Sprint Planning with AI Agents
   • Multi-Agent Orchestration
   • Cross-Model Code Review
   • Documentation Freshness
   • Shared Resources
   • Lifecycle Hooks
2. Align on Best Practices & Tips + Tricks.
3. Browse Real-world Examples and steal the prompts.
4. Keep docs/TROUBLESHOOTING.md handy for deeper diagnostics.

You now have a board, agents that can pick up work, and a safety net when things wobble. Go ship something.