### QMD Setup and Initialization

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-REFERENCE.md

Install the QMD package, run the setup command, and then start the development server with the QMD search backend enabled.

```bash
npm install -g @tobilu/qmd
pnpm qmd:setup
VERITAS_SEARCH_BACKEND=qmd pnpm dev
```

--------------------------------

### Install QMD and Setup Collections

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/features/qmd-search.md

Install the QMD package globally using npm and run the setup command to initialize the necessary collections for search.

```bash
npm install -g @tobilu/qmd
pnpm qmd:setup
```

--------------------------------

### Run Veritas Kanban Setup Wizard

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/GETTING-STARTED.md

Execute the setup wizard to verify your environment and optionally create a sample task. Ensure the `vk` command is installed or complete manual setup first.

```bash
vk setup
```

--------------------------------

### Minimal Local Setup for Veritas Kanban

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/SETUP-PATHS.md

Clone the repository, install dependencies, set up the environment file, and start the development server. Access the board at http://localhost:3000 and the API at http://localhost:3001.

```bash
git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
pnpm install
cp server/.env.example server/.env
pnpm dev
```

```bash
VERITAS_AUTH_ENABLED=true
VERITAS_AUTH_LOCALHOST_BYPASS=true
VERITAS_AUTH_LOCALHOST_ROLE=read-only
```

--------------------------------

### Set up Veritas Kanban from Source

Source: https://github.com/bradgroux/veritas-kanban/blob/main/README.md

Clone the repository, install dependencies, configure environment variables, and start the development server for local source development.

```bash
git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
pnpm install
cp server/.env.example server/.env   # Edit to change VERITAS_ADMIN_KEY
pnpm dev
```

--------------------------------

### Verify CLI Installation

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/CLI-GUIDE.md

After linking the CLI, verify the installation by checking the help message and running the setup command.

```bash
vk --help
vk setup
```

--------------------------------

### Start Development Server

Source: https://github.com/bradgroux/veritas-kanban/blob/main/CONTRIBUTING.md

Start the development server using pnpm. The board will auto-seed with example tasks on the first run. To re-seed manually, use 'pnpm seed'.

```bash
pnpm dev
```

--------------------------------

### Start Veritas Kanban Server and Build MCP

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/mcp/README.md

Commands to start the Veritas Kanban server and build the shared code and MCP server. Ensure Node.js and pnpm are installed.

```bash
cd veritas-kanban
pnpm dev                          # Server on http://localhost:3001

pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/mcp build
```

--------------------------------

### Copy Environment Example

Source: https://github.com/bradgroux/veritas-kanban/blob/main/demo/README.md

Copy the example environment file to create a local configuration for customization.

```bash
cp demo/.env.example demo/.env
```

--------------------------------

### Agent Workflow Prompt Example

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/GETTING-STARTED.md

An example prompt to guide an agent runner on how to pick up, process, and complete a task, including status updates and timer management.

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

--------------------------------

### Clone and Build Veritas Kanban

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/guides/SELF_HOST.md

Clone the repository, install dependencies using pnpm, and build the project packages. Configure the server environment by copying the example .env file and setting the VERITAS_ADMIN_KEY.

```bash
# 1. Clone the repository
git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban

# 2. Install all workspace dependencies
pnpm install --frozen-lockfile

# 3. Build all packages (shared → server + web)
pnpm build

# 4. Configure environment
cp server/.env.example server/.env
# Edit server/.env — at minimum set VERITAS_ADMIN_KEY
```

--------------------------------

### Re-seed Example Tasks

Source: https://github.com/bradgroux/veritas-kanban/blob/main/README.md

Restore the example tasks by running the `pnpm seed` command. This is useful for re-populating the board with examples when it is empty.

```bash
pnpm seed
```

--------------------------------

### Quick Start Docker Deployment

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/DEPLOYMENT.md

Use this command sequence for a rapid production deployment of Veritas Kanban via Docker. Ensure you configure the .env file with a strong admin key. This setup persists data in a Docker volume.

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

cp server/.env.example server/.env
# Edit server/.env — at minimum, set VERITAS_ADMIN_KEY to a strong secret

docker compose up -d --build

curl http://localhost:3001/health
# → {"status":"ok","timestamp":"..."}
```

--------------------------------

### Assistant-Safe Setup Prompt for Veritas Kanban

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/SETUP-PATHS.md

Use this prompt when instructing an assistant to install or configure Veritas Kanban. It prioritizes the board-only local path and specifies conditions for configuring additional layers.

```text
Set up Veritas Kanban from the official repo and docs only. Start with the board-only local path first. Do not configure OpenClaw, MCP, Squad Chat webhooks, workflow gates, or notification delivery unless I explicitly ask for that layer. After the board runs, verify localhost:3000 and localhost:3001/api/health. If configuring CLI or MCP writes, use VK_API_URL and VK_API_KEY exactly as documented.
```

--------------------------------

### Mac Desktop App Setup Prompt

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/V5-UPGRADE-INSTALL-ADMIN-GUIDE.md

Steps for installing and initially configuring the Veritas Kanban Mac desktop application. Emphasizes saving the recovery key and verifying system health before network exposure.

```text
Install the signed Veritas Kanban Mac app, choose Board Only first-run setup,
save the recovery key, and verify Settings -> Maintenance health. Do not expose
the app to the network or configure integrations yet.
```

--------------------------------

### Start Veritas Kanban Server

Source: https://github.com/bradgroux/veritas-kanban/blob/main/load-tests/README.md

Start the Veritas Kanban API server from the repository root using pnpm.

```bash
# From repo root
pnpm dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/bradgroux/veritas-kanban/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm, the recommended package manager.

```bash
pnpm install
```

--------------------------------

### Start Task Timer with vk begin

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/BEST-PRACTICES.md

Begin tracking time for a task as soon as you start working on it. This data is crucial for estimation and billing.

```bash
vk begin
```

--------------------------------

### Install Veritas Kanban with Homebrew

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/DESKTOP-RELEASE.md

Use these commands to tap the BradGroux repository and install the Veritas Kanban cask.

```bash
brew tap BradGroux/tap
brew install --cask veritas-kanban
```

--------------------------------

### Sprint Planning Input Example

Source: https://github.com/bradgroux/veritas-kanban/blob/main/prompt-registry/sprint-planning.md

Example input for the sprint planning prompt, specifying the goal, project, sprint ID, and duration.

```text
Goal: Add GitHub Issues sync to Veritas Kanban
Project: veritas-kanban
Sprint: US-1300
Duration: 1 week
```

--------------------------------

### Set Up Server Environment Variables

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/DEPLOYMENT.md

Copies the example environment file for the server and instructs to edit it for configuring essential settings like the admin key.

```bash
# Set up environment
cp server/.env.example server/.env
# Edit server/.env — configure VERITAS_ADMIN_KEY and other settings
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/bradgroux/veritas-kanban/blob/main/CONTRIBUTING.md

Copy the example environment file and edit it with your local configuration. Ensure VERITAS_ADMIN_KEY is set.

```bash
cp server/.env.example server/.env
```

--------------------------------

### Quick Start Docker Deployment

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/guides/SELF_HOST.md

Clone the repository, configure environment variables in `.env`, and then build and start the Docker containers. Verify the deployment by checking the health endpoint.

```bash
# Clone and configure
git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
cp server/.env.example server/.env
# Edit server/.env — set VERITAS_ADMIN_KEY to a strong secret (≥ 32 chars)

# Build and start
docker compose up -d --build

# Verify
curl http://localhost:3001/health
# → {"status":"ok","timestamp":"..."}
```

--------------------------------

### Auto Telemetry - Run Started Event

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/enforcement.md

Example of the telemetry event emitted when a task status changes to 'in-progress', indicating the start of a run.

```json
{
  "type": "run.started",
  "taskId": "US-42",
  "agent": "VERITAS",
  "timestamp": "2026-02-10T14:30:00Z"
}
```

--------------------------------

### Start Development Server

Source: https://github.com/bradgroux/veritas-kanban/blob/main/desktop/README.md

Launches the local development server for the desktop application. Use `desktop:dev:fresh` to test onboarding and startup behavior with a fresh profile.

```bash
pnpm desktop:dev
```

```bash
pnpm desktop:dev:fresh
```

--------------------------------

### Get OpenClaw Version

Source: https://github.com/bradgroux/veritas-kanban/blob/main/README.md

Command to retrieve the installed OpenClaw version, useful for reporting issues.

```bash
openclaw --version
```

--------------------------------

### CLI Setup and Configuration

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/SETUP-PATHS.md

Build the shared and CLI packages, link the CLI locally, and set the API URL. For write commands, configure API keys in the server's .env file and export the same key for the CLI.

```bash
pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/cli build
cd cli
npm link
```

```bash
export VK_API_URL=http://localhost:3001
```

```bash
VERITAS_API_KEYS=local-agent:replace-with-a-long-secret:agent
```

```bash
export VK_API_KEY=replace-with-a-long-secret
vk setup
```

--------------------------------

### Multi-Repo Directory Structure

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/SOP-shared-resources.md

Example directory structure for a multi-repository setup utilizing a shared 'workspace' for common resources across projects.

```plaintext
workspace/
├── shared/                    # Shared across all repos
│   ├── prompt-registry/       # Universal prompts
│   │   ├── sprint-planning.md
│   │   └── cross-model-review.md
│   ├── skills/                # Agent skills/capabilities
│   │   ├── github.md
│   │   └── research.md
│   └── guidelines/            # Universal rules
│       ├── AGENTS-BASE.md
│       └── SECURITY-RULES.md
│
├── project-a/                 # Project-specific
│   ├── AGENTS.md              # Extends shared/guidelines/AGENTS-BASE.md
│   ├── prompt-registry/       # Project-specific prompts
│   │   └── deploy-checklist.md
│   └── ...
│
└── project-b/
    ├── AGENTS.md
    └── ...
```

--------------------------------

### Quick Start Task Workflow

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/CLI-GUIDE.md

Manage the complete task lifecycle using three core commands: create a task, begin working on it, and then mark it as done with a summary.

```bash
# 1. Create a task
vk create "Implement OAuth login" --type code --project my-app

# 2. Start working — one command handles everything
vk begin task_20260201_abc123

# 3. Finish up — one command wraps it all
vk done task_20260201_abc123 "Added OAuth2 with Google and GitHub providers"
```

--------------------------------

### Add Optional Setup Phase to Workflow YAML

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/WORKFLOW_ENGINE_ARCHITECTURE.md

Define an optional 'setup' section in workflow YAML to run pre-workflow tasks like environment preparation and dependency installation before the main steps. This section supports standard step configurations including agent, input, on_fail policies, and timeouts.

```yaml
id: feature-dev
name: Feature Development Workflow
version: 1

# ✅ Setup phase (runs before main steps)
setup:
  - id: prep-env
    name: 'Setup: Prepare environment'
    agent: system
    input: |
      Prepare the development environment.

      REPO: {{task.git.worktreePath}}
      BRANCH: {{task.git.branch}}

      Instructions:
      1. cd {{task.git.worktreePath}}
      2. git fetch origin
      3. git checkout {{task.git.branch}} || git checkout -b {{task.git.branch}}
      4. npm install (or yarn install)
      5. Run any pre-flight checks

      Reply with:
      STATUS: done
      ENV: <environment summary>

    on_fail:
      escalate_to: human

    timeout: 600

steps:
  # Main workflow steps (run after setup completes)
  - id: plan
    # ...

```

--------------------------------

### Create Project

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/CLI-GUIDE.md

Create a new project with a name. Optional flags include --color for project color and --description for a project description. Use --json for JSON output.

```bash
vk project create "my-app"
```

```bash
vk project create "rubicon" --color "#7c3aed" --description "Main product"
```

--------------------------------

### MCP/CLI Setup Prompt

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/V5-UPGRADE-INSTALL-ADMIN-GUIDE.md

Instructions for setting up Veritas Kanban's CLI or MCP server. Requires setting environment variables for API URL and key, and performing smoke checks without using owner credentials for routine writes.

```text
Build the CLI or MCP server from this checkout, set VK_API_URL and a scoped
VK_API_KEY, run the documented read/write smoke checks, and do not use owner or
admin credentials for routine agent writes.
```

--------------------------------

### Workflow Run Response Example

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-WORKFLOWS.md

Illustrates the structure of the response when a workflow run is successfully started. It includes the run ID, status, context, and details of the initial steps.

```json
{
  "id": "run_20260209_abc123",
  "workflowId": "feature-dev",
  "workflowVersion": 2,
  "taskId": "US-42",
  "status": "running",
  "currentStep": "plan",
  "context": {
    "task": {
      "id": "US-42",
      "title": "Implement user registration",
      "description": "Add registration endpoint with email validation"
    },
    "priority": "high",
    "deadline": "2026-02-15"
  },
  "startedAt": "2026-02-09T12:00:00Z",
  "steps": [
    {
      "stepId": "plan",
      "status": "running",
      "agent": "planner",
      "startedAt": "2026-02-09T12:00:00Z",
      "retries": 0
    },
    {
      "stepId": "implement",
      "status": "pending",
      "retries": 0
    }
  ]
}
```

--------------------------------

### Run a Workflow via API

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/WORKFLOW-GUIDE.md

Initiate a workflow run using a cURL command. This example shows how to send a POST request to the API endpoint for starting a workflow.

```bash
# Start a workflow run
curl -X POST http://localhost:3001/api/workflows/hello-world/runs \
  -H "Content-Type: application/json" \
  -d '{}'

# Response:
# {
#   "id": "run_20260209_abc123",
#   "workflowId": "hello-world",
#   "status": "running",
#   "startedAt": "2026-02-09T12:00:00Z",
#   ...
# }
```

--------------------------------

### Start Veritas Kanban Demo

Source: https://github.com/bradgroux/veritas-kanban/blob/main/demo/README.md

Run the demo environment from the repository root or directly using Docker Compose. Access the demo at http://localhost:3099. The demo binds to 127.0.0.1 and disables authentication by default.

```bash
# From the repo root:
npm run demo

# Or directly:
docker compose -f demo/docker-compose.demo.yml up --build
```

--------------------------------

### Automate Task Lifecycle with Agent Commands

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/CLI-GUIDE.md

Integrate vk workflow commands into agent configurations to manage task lifecycles. This example shows starting and completing a task.

```bash
# In an agent's task handler
TASK_ID="$1"

# Start work
vk begin "$TASK_ID"

# ... perform the work ...

# Complete with summary
vk done "$TASK_ID" "Completed implementation of feature X"
```

--------------------------------

### Get Workflow Run Details

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-WORKFLOWS.md

Retrieves comprehensive details for a specific workflow run, including its status, context, start and end times, and step-by-step execution information.

```APIDOC
## GET /api/workflow-runs/:id

### Description
Get full details of a specific workflow run.

### Method
GET

### Endpoint
/api/workflow-runs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the workflow run.

### Response
#### Success Response (200)
- **id** (string) - The workflow run ID.
- **workflowId** (string) - The ID of the associated workflow.
- **workflowVersion** (integer) - The version of the workflow.
- **taskId** (string) - The ID of the task associated with the run.
- **status** (string) - The current status of the workflow run (e.g., 'completed', 'running', 'blocked').
- **currentStep** (string | null) - The ID of the current step if the run is active, otherwise null.
- **context** (object) - Additional context related to the workflow run.
- **startedAt** (string) - The timestamp when the workflow run started.
- **completedAt** (string | null) - The timestamp when the workflow run completed, or null if not completed.
- **lastCheckpoint** (string | null) - The timestamp of the last checkpoint, or null.
- **steps** (array) - An array of step objects detailing each step's execution.

#### Response Example
```json
{
  "id": "run_20260209_abc123",
  "workflowId": "feature-dev",
  "workflowVersion": 2,
  "taskId": "US-42",
  "status": "completed",
  "currentStep": null,
  "context": {
    "task": { "id": "US-42", "title": "..." },
    "plan": { "stories": [...] },
    "implement": { "changes": "..." }
  },
  "startedAt": "2026-02-09T12:00:00Z",
  "completedAt": "2026-02-09T12:45:00Z",
  "lastCheckpoint": "2026-02-09T12:45:00Z",
  "steps": [
    {
      "stepId": "plan",
      "status": "completed",
      "agent": "planner",
      "sessionKey": "session_xyz",
      "startedAt": "2026-02-09T12:00:00Z",
      "completedAt": "2026-02-09T12:10:00Z",
      "duration": 600,
      "retries": 0,
      "output": ".veritas-kanban/workflow-runs/run_20260209_abc123/step-outputs/plan.yml"
    },
    {
      "stepId": "implement",
      "status": "completed",
      "agent": "developer",
      "startedAt": "2026-02-09T12:10:00Z",
      "completedAt": "2026-02-09T12:35:00Z",
      "duration": 1500,
      "retries": 1,
      "output": ".veritas-kanban/workflow-runs/run_20260209_abc123/step-outputs/implement-0.md",
      "loopState": {
        "totalIterations": 5,
        "currentIteration": 5,
        "completedIterations": 5,
        "failedIterations": 0
      }
    }
  ]
}
```

**Status Codes**:
- `200 OK` — Success
- `404 Not Found` — Run not found
- `403 Forbidden` — No view permission

**Permissions**: Requires `view` permission on the workflow.
```

--------------------------------

### Create, Begin, and Complete a Task

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/FEATURES.md

Demonstrates the complete lifecycle of a task using the Veritas Kanban CLI. Includes creating a new task, starting work on it, and completing it with a summary.

```bash
# Create a new task
vk create "Implement OAuth" --type code --project my-app

# Start working — sets in-progress, starts timer, marks agent working
vk begin <id>

# Work happens...

# Complete with summary — stops timer, sets done, adds comment, marks agent idle
vk done <id> "Added OAuth2 with Google and GitHub providers"
```

--------------------------------

### Install Veritas Kanban CLI

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/CLI-GUIDE.md

Clone the repository, install pnpm dependencies, build shared code and the CLI, then link the CLI globally. Ensure the Veritas Kanban server is running.

```bash
git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
pnpm install
pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/cli build
cd cli
npm link
```

--------------------------------

### Workflow Engine Pipeline

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/EXAMPLES-agent-workflows.md

Automate the plan-implement-test-review cycle with retry policies using a workflow engine. This example shows how to define a feature development workflow and start a run via API.

```APIDOC
## POST /api/workflows/{workflow_name}/runs

### Description
Starts a new run of a specified workflow.

### Method
POST

### Endpoint
/api/workflows/{workflow_name}/runs

### Request Body
(No specific request body documented, but implies workflow definition is pre-configured)

### Response
(No specific response documented, but implies a success status or run ID)

### Example
```bash
POST /api/workflows/feature-dev/runs
```
```

--------------------------------

### Start Agent with Profile Package

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-REFERENCE.md

Initiate an agent with a portable profile package. This allows applying package-specific configurations like runtime, model, sandbox, and budget.

```json
{
  "profileId": "docs-reviewer"
}
```

--------------------------------

### Start Veritas Kanban and Expose via Tailscale Serve (Root Path)

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/guides/SELF_HOST.md

Starts the Veritas Kanban application and then exposes it via Tailscale Serve, proxying HTTPS traffic to the local server. Access the app from any tailnet device.

```bash
NODE_ENV=production node server/dist/index.js
```

```bash
tailscale serve https / http://localhost:3001
```

--------------------------------

### Local Board Setup Prompt

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/V5-UPGRADE-INSTALL-ADMIN-GUIDE.md

Instructions for setting up Veritas Kanban locally using the board-only path. Verifies local host and API health before configuring advanced features.

```text
Set up Veritas Kanban locally using the board-only path first. Verify
localhost:3000 and localhost:3001/api/health. Do not configure OpenClaw, MCP,
Squad Chat webhooks, workflow gates, notifications, or remote access unless I
ask for that layer.
```

--------------------------------

### Get Risk Inventory

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-REFERENCE.md

Retrieves all shared resources of type 'skill' along with their associated capability profiles, scan data, remediation tasks, and exceptions. It provides details on scan status, risk score, severity, recommendations, install decisions, and finding counts.

```APIDOC
## GET /api/skills/security/inventory

### Description
Returns every shared resource with `type: "skill"` joined to its capability profile, latest persisted scan, open remediation task, and active exception. Each item includes `scanStatus`, `riskScore`, `severity`, `recommendation`, `installDecision`, `declaredCapabilities`, `observedCapabilities`, `mismatches`, `findingCount`, and `highOrCriticalFindingCount`.

`installDecision` values:

- `allow`: no blocking scanner or capability findings, or an active reviewed exception exists.
- `warn`: medium risk or caution findings require acknowledgement or reviewer approval.
- `block`: high, critical, or `do-not-install` risk blocks install and workflow use by default.

Reviewed exceptions are temporary and require an owner, reason, and future expiration.
```

--------------------------------

### Install and Validate Dependencies

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/V5-GA-CHECKLIST.md

Run these commands to install dependencies with a frozen lockfile, perform type checking, linting, unit tests, build the project, and validate the release before publication.

```bash
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint:budget
pnpm test:unit
pnpm build
pnpm validate:release
pnpm smoke:cli-mcp
pnpm desktop:package:mac:unsigned
pnpm test:load:smoke
```

--------------------------------

### Start Timer

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-REFERENCE.md

Starts a timer for a specific task.

```APIDOC
## POST /api/tasks/:id/time/start

### Description
Starts a timer for a specific task.

### Method
POST

### Endpoint
/api/tasks/:id/time/start
```

--------------------------------

### Start and Complete Task with vk CLI

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/SOP-agent-task-workflow.md

Use 'vk begin' to start a task and timer, and 'vk done' to complete it with a summary. Ensure all work is finished before marking as done.

```bash
vk begin <id>                         # sets in-progress, starts timer, agent status → working
# ...do the work...
vk done <id> "Added OAuth + regression test"
```

--------------------------------

### Start Task

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/AGENTS-TEMPLATE.md

Marks a task as started by an agent.

```APIDOC
## Start Task

### Description
Marks a task as started by an agent.

### Method
POST

### Endpoint
`/api/agents/:taskId/start`

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The ID of the task to start.

### Request Example
```bash
curl -X POST http://localhost:3001/api/agents/task-123/start
```
```

--------------------------------

### Create a Simple 'Hello World' Workflow

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/WORKFLOW-GUIDE.md

Define a basic two-step workflow with a writer agent. This workflow demonstrates agent input/output, acceptance criteria, and retry policies.

```yaml
id: hello-world
name: Hello World Workflow
version: 1
description: A simple 2-step workflow to test the engine.

agents:
  - id: writer
    name: Writer
    role: developer
    model: github-copilot/claude-sonnet-4.5
    description: Writes hello world messages

steps:
  - id: greet
    name: 'Step 1: Greet user'
    type: agent
    agent: writer
    input: |
      Write a friendly hello world message.
      Reply with:
      MESSAGE: <your greeting>
    output:
      file: greeting.md
    acceptance_criteria:
      - 'MESSAGE:'
    on_fail:
      retry: 2
      escalate_to: human

  - id: farewell
    name: 'Step 2: Say goodbye'
    type: agent
    agent: writer
    input: |
      Write a farewell message.
      Previous greeting: {{steps.greet.output}}
      Reply with:
      MESSAGE: <your goodbye>
    output:
      file: farewell.md
    acceptance_criteria:
      - 'MESSAGE:'
```

--------------------------------

### Verify k6 Installation

Source: https://github.com/bradgroux/veritas-kanban/blob/main/load-tests/README.md

Run this command to confirm that k6 has been installed correctly.

```bash
k6 version
```

--------------------------------

### Install k6 with Homebrew

Source: https://github.com/bradgroux/veritas-kanban/blob/main/load-tests/README.md

Use this command to install k6 on macOS using Homebrew.

```bash
brew install k6
```

--------------------------------

### Workflow Step Started Event Payload (JSON)

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/API-WORKFLOWS.md

This JSON payload is emitted when a specific step within a workflow run starts execution. It contains the run ID, step ID, status, and start time.

```json
{
  "type": "workflow:step:started",
  "data": {
    "runId": "run_20260209_abc123",
    "stepId": "plan",
    "status": "running",
    "startedAt": "2026-02-09T12:00:00Z"
  }
}
```

--------------------------------

### List Projects

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/CLI-GUIDE.md

List all available projects. Use the --json flag for JSON output.

```bash
vk project list
```

```bash
vk project list --json
```

--------------------------------

### Example Progress File Entry for Learning

Source: https://github.com/bradgroux/veritas-kanban/blob/main/docs/features/prd-driven-development.md

Capture key learnings and technical details in a progress file for future reference. This helps in documenting decisions and avoiding repeated mistakes.

```markdown
## Iteration 1: US-001 (Google OAuth setup)

**What I learned:**

- Google requires HTTPS redirect URIs in production (localhost OK in dev)
- Token expiry is 1 hour — need refresh token logic for long sessions
- State parameter is critical for CSRF protection — never skip it
- Scopes: `email` and `profile` are sufficient for basic login
```