# 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](SETUP-PATHS.md).

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](SETUP-PATHS.md#readiness-levels) to decide whether CLI, MCP, runners, webhooks, or notifications are actually needed.

---

## Table of Contents

1. [Prerequisites (30 seconds)](#prerequisites-30-seconds)
2. [Installation & Setup Wizard](#installation--setup-wizard)
3. [Create Your First Task (UI path)](#create-your-first-task-ui-path)
4. [Create Your First Task (API/CLI path)](#create-your-first-task-apicli-path)
5. [Connect an Agent + Agent Pickup Checklist](#connect-an-agent--agent-pickup-checklist)
6. [Sanity Checks & Quick Fixes](#sanity-checks--quick-fixes)
7. [Shared Resources & Prompt Registry](#shared-resources--prompt-registry)
8. [Documentation Freshness & Repo Rules](#documentation-freshness--repo-rules)
9. [Multi-Repo / Multi-Agent Notes](#multi-repo--multi-agent-notes)
10. [OpenClaw Browser Relay (Optional)](#openclaw-browser-relay-optional)
11. [What's Next?](#whats-next)

---

## Prerequisites (30 seconds)

| What              | Command            | Notes                                                                   |
| ----------------- | ------------------ | ----------------------------------------------------------------------- |
| Node.js           | `node -v`          | Requires **22.22.1+**. Install via Volta/nvm if older.                  |
| pnpm              | `pnpm -v`          | Use the repository-pinned **11.1.1** release.                          |
| Git               | `git --version`    | Requires **2.38+**.                                                     |
| (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.

```bash
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:

```bash
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

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

### 2. Configure server

a. Copy the sample env

```bash
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

```bash
pnpm dev
```

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

![Dev stack running with dummy v5 tasks](assets/v5/v5-board-overview.png)

### 4. Run the in-app setup

Visit [http://localhost:3000](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.

![Creating and reviewing a task in the v5 task detail drawer](assets/v5/v5-task-work-view.png)

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

---

## Create Your First Task (API/CLI path)

### REST call (curl)

```bash
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`)

```bash
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.

![Board to workflow tour with dummy v5 tasks](assets/v5/v5-board-to-workflow.gif)

---

## 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:
   ```bash
   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:
   ```bash
   vk agents:pending
   ```
7. **Agent workflow** (example prompt to an agent runner):
   ```
   Start the configured agent on task <ID>. Use the persisted task envelope,
   assigned worktree, and run-scoped tool catalog. Return focused verification
   and a concise completion summary through the harness result.
   ```
   Managed agents must not call `vk begin`, `vk done`, or lifecycle callbacks.
   See [AGENTS-TEMPLATE.md](AGENTS-TEMPLATE.md).
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**

![Agent-ready task detail view](assets/v5/v5-task-work-view.png)

> **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)

```bash
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](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   # Optional independent review
├── 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](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](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](SOP-documentation-freshness.md) 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](https://github.com/openclaw/openclaw).
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](API-REFERENCE.md)** — Complete endpoint catalog, auth, examples, WebSocket, and common workflows.
1. Read the SOPs:
   - [Agent Task Workflow](SOP-agent-task-workflow.md)
   - [Sprint Planning with AI Agents](SOP-sprint-planning.md)
   - [Multi-Agent Orchestration](SOP-multi-agent-orchestration.md)
   - [Cross-Model Code Review](SOP-cross-model-code-review.md)
   - [Documentation Freshness](SOP-documentation-freshness.md)
   - [Shared Resources](SOP-shared-resources.md)
   - [Lifecycle Hooks](SOP-lifecycle-hooks.md)
2. Align on [Best Practices](BEST-PRACTICES.md) & [Tips + Tricks](TIPS-AND-TRICKS.md).
3. Browse [Real-world Examples](EXAMPLES-agent-workflows.md) 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.