# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

PCLI is a Go CLI tool for interacting with the Planka (v2.0) project management API. It uses the Cobra framework with minimal dependencies (only Cobra + standard library).

## Build & Test Commands

```bash
go build -o pcli .                # Build for development
./build.sh                        # Multi-platform release build (linux/darwin/windows)
./test.sh                         # Integration tests (requires live Planka instance)
```

Integration tests require `PLANKA_URL` and `PLANKA_API_KEY` environment variables pointing to a running Planka instance.

There is no unit test suite or linter configured — tests are shell-based integration tests in `test.sh`.

## Architecture

**Entry point**: `main.go` → `cmd.Execute()`

**Package layout**:
- `cmd/` — Cobra command definitions, one file per resource (project.go, board.go, card.go, etc.)
- `client/` — HTTP API client, one file per resource matching cmd/ structure
- `model/types.go` — All domain types (Project, Board, Card, List, Label, Task, Comment, etc.)
- `output/output.go` — Dual-format output: JSON envelope (`{data, error}`) or human-readable table via tabwriter
- `logging/logging.go` — slog-based structured JSON logging to stderr

**Command hierarchy**: `pcli <resource> <action>` (e.g., `pcli card create --list <id> --name "task"`)

**Key patterns**:
- Global flags (`--format`, `--url`, `--api-key`, `--log-level`) set in `cmd/root.go` PersistentPreRunE, which validates config and initializes the API client
- Client methods follow `List*/Get*/Create*/Update*/Delete*` naming
- API responses use typed structs with included relationships (e.g., board responses include lists and cards)
- `friendlyAPIError()` in `cmd/errors.go` translates HTTP status codes to contextual messages
- `DoWithFallback` in client supports trying alternate API endpoint patterns
- Output uses reflection-based table rendering per type

**Configuration**: Environment variables `PLANKA_URL` and `PLANKA_API_KEY`, overridable via CLI flags.

## Adding a New Resource

1. Define model structs in `model/types.go`
2. Add client methods in `client/<resource>.go`
3. Add command definitions in `cmd/<resource>.go` with subcommands (list, get, create, update, delete)
4. Wire the parent command into `root.go` init()

## Planka Sync

**IMPORTANT**
After completing any opsx workflow (/opsx:new, /opsx:ff, /opsx:continue,
/opsx:apply, /opsx:verify, /opsx:archive, /opsx:bulk-archive), automatically
reconcile Planka board state by running the sync script:

```bash
PROJECT_NAME=$(yq -r '.planka.project' project.yaml)
BOARD_NAME=$(yq -r '.planka.board' project.yaml)
kanban-project-sync --project "$PROJECT_NAME" --board "$BOARD_NAME" --background
```

The script handles concurrency (flock-based locking with coalescing pending queue).
If the script is not on PATH or fails, log a brief warning and continue.
Never block or retry — Planka sync is best-effort.