pikaboard

# PikaBoard

Agent-first task/kanban dashboard. **PikaBoard is the source of truth for tasks.**

## Quick Start

After install, start the server:
```bash
cd pikaboard/backend && npm start
```

Access dashboard at `http://localhost:3001`

## Configuration

Create `backend/.env`:
```env
DATABASE_PATH=./pikaboard.db
PIKABOARD_TOKEN=your-secret-token
PORT=3001
```

Add to your TOOLS.md:
```markdown
## PikaBoard
- **API:** http://localhost:3001/api/
- **Token:** your-secret-token
```

Agent runtime variables:
```bash
export PIKABOARD_API="http://localhost:3001/api"
export PIKABOARD_TOKEN="your-secret-token"
export AGENT_NAME="bulbi"
```

## Task Commands

Reference tasks by ID:
- `task 12` or `#12` → view task
- `move #12 to done` → status change
- `create task "Fix bug"` → new task

## API Reference

See `backend/API.md` for full endpoint documentation (single canonical doc).

### Common Operations

**List tasks:**
```bash
curl -H "Authorization: Bearer $PIKABOARD_TOKEN" "$PIKABOARD_API/tasks"
```

**Create task:**
```bash
curl -X POST -H "Authorization: Bearer $PIKABOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Fix bug","status":"inbox","priority":"high","tags":["bug","backend"]}' \
  "$PIKABOARD_API/tasks"
```

**Update status:**
```bash
curl -X PATCH -H "Authorization: Bearer $PIKABOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}' \
  "$PIKABOARD_API/tasks/123"
```

## Enums

| Field | Values |
|-------|--------|
| status | `inbox`, `up_next`, `in_progress`, `testing`, `in_review`, `done`, `rejected` |
| priority | `low`, `medium`, `high`, `urgent` |

## Agent Onboarding (Simple Path)

Use the helper to map each agent to a board automatically:

```bash
cd pikaboard
MY_BOARD_ID="$(
  ./skills/pikaboard/scripts/setup-agent-board.sh | sed -n 's/^MY_BOARD_ID=//p' | tail -n1
)"
export MY_BOARD_ID
```

What it does:
- Reads `PIKABOARD_API`, `PIKABOARD_TOKEN`, `AGENT_NAME`
- Finds board by `BOARD_NAME` (default: `AGENT_NAM...

# PikaBoard Skill

This folder contains the ClawHub/OpenClaw skill package for PikaBoard.

## File Naming

- Use `SKILL.md` for the actual skill definition and metadata (canonical for ClawHub/OpenClaw).
- Use `README.md` for human-facing setup and usage docs.
- Do not use `prompt.md` or `clawhub.md` unless your tooling explicitly requires them.

## Quick Setup

1. Install skill from ClawHub: `angelstreet/pikaboard`
2. Start backend:

```bash
cd pikaboard/backend && npm start
```

3. Set env vars:

```bash
export PIKABOARD_API="http://localhost:3001/api"
export PIKABOARD_TOKEN="<token-from-pikaboard/backend/.env>"
export AGENT_NAME="<your-agent-name>"
```

4. Auto-configure board:

```bash
cd pikaboard
MY_BOARD_ID="$(
  ./skills/pikaboard/scripts/setup-agent-board.sh | sed -n 's/^MY_BOARD_ID=//p' | tail -n1
)"
export MY_BOARD_ID
```

5. Validate:

```bash
curl -s http://localhost:3001/health
curl -s -H "Authorization: Bearer $PIKABOARD_TOKEN" "$PIKABOARD_API/boards"
curl -s -H "Authorization: Bearer $PIKABOARD_TOKEN" "$PIKABOARD_API/tasks?board_id=$MY_BOARD_ID&status=up_next"
```

## Ready-To-Send Agent Prompt

```text
Install and use `angelstreet/pikaboard` from ClawHub, end-to-end.

1) Install the skill (from ClawHub) and clone/build PikaBoard from GitHub.
2) Start backend:
   cd pikaboard/backend && npm start
3) Read token from backend env (`PIKABOARD_TOKEN` in `pikaboard/backend/.env`).
4) Set runtime env:
   export PIKABOARD_API="http://localhost:3001/api"
   export PIKABOARD_TOKEN="<token>"
   export AGENT_NAME="<your-agent-name>"
5) Auto-configure board:
   cd pikaboard
   MY_BOARD_ID="$(
     ./skills/pikaboard/scripts/setup-agent-board.sh | sed -n 's/^MY_BOARD_ID=//p' | tail -n1
   )"
   export MY_BOARD_ID
6) Verify:
   curl -s http://localhost:3001/health
   curl -s -H "Authorization: Bearer $PIKABOARD_TOKEN" "$PIKABOARD_API/boards"
   curl -s -H "Authorization: Bearer $PIKABOARD_TOKEN" "$PIKABOARD_API/tasks?board_id=$MY_BOARD_ID&status=up_next"

Operate on...