mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 02:44:59 +00:00

Brad Groux d3976f1d74 chore: harden audit findings and release QA

Add release validation and scheduled QA workflows.

Harden webhook URL handling, API helper edge cases, and runtime version reporting.

Split heavy web bundles, centralize view metadata, and stabilize full-suite tests.

2026-05-16 18:59:40 -05:00

12 KiB

Raw Permalink Blame History

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.

Prerequisites (30 seconds)
Installation & Setup Wizard
Create Your First Task (UI path)
Create Your First Task (API/CLI path)
Connect an Agent + Agent Pickup Checklist
Sanity Checks & Quick Fixes
Shared Resources & Prompt Registry
Documentation Freshness & Repo Rules
Multi-Repo / Multi-Agent Notes
OpenClaw Browser Relay (Optional but recommended)
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 9+. `npm install -g pnpm` if missing.
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.

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 at any time to verify your environment is correctly configured.

Create Your First Task (UI path)

Click New Task on the board.
Fill title, description (Markdown), pick a type + priority.
Optional: assign a sprint/project.
Hit Create and watch it appear in Todo.
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

Agents interact through HTTP + WebSocket; nothing is hard-coded to a particular provider. Follow this checklist to verify they can pick up work:

Create an agent API key in server/.env:

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

Restart pnpm dev so the key loads.

Export the key for CLI, MCP, or agent scripts:

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

Create an agent request (UI → Start Agent) or drop a JSON file in .veritas-kanban/agent-requests/.
Watch pending agents in the UI or via CLI:
```
vk agents:pending
```

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.

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 API key role `agent`, check firewall/Docker networking

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:

Reference in task descriptions: See prompt: prompt-registry/cross-model-review.md
Copy and customize for your team's conventions
When spawning agents (OpenClaw sessions_spawn), paste the relevant prompt

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 but Recommended)

For auth-required workflows (LinkedIn research, dashboards behind Okta, etc.) you'll want OpenClaw's Browser Relay:

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

This is invaluable for Champions-style research tasks or anything needing a real login flow.

What's Next?

API Reference — Complete endpoint catalog, auth, examples, WebSocket, and common workflows.
Read the SOPs:
Align on Best Practices & Tips + Tricks.
Browse Real-world Examples and steal the prompts.
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.

12 KiB Raw Permalink Blame History