steve/pcli

Files

T

Steve Cliff 22d5848e1a feat: Add openspec-sync-specs and openspec-verify-change skills

- Introduced `openspec-sync-specs` skill to sync delta specs to main specs, allowing intelligent merging of requirements.
- Added `openspec-verify-change` skill to verify implementation against change artifacts, ensuring completeness, correctness, and coherence before archiving.

docs: Create CLAUDE.md for project guidance

- Added CLAUDE.md to provide an overview of the PCLI project, including build, test commands, architecture, and resource addition guidelines.

chore: Add new change and design documents for project filter in status command

- Created `.openspec.yaml`, `design.md`, `proposal.md`, and `tasks.md` for the `add-project-filter-to-status` change.
- Updated specs for CLI commands and status command to include project filtering functionality.

feat: Expand board included parsing in API client

- Added parsing for `labels`, `cardLabels`, and `cardMemberships` in the `GetBoard` response.
- Updated `ListCardsByBoard` to enrich card output with label names, enhancing usability in kanban sync workflows.

2026-02-18 21:27:02 +00:00

2.7 KiB

Raw Blame History

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

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

Define model structs in model/types.go
Add client methods in client/<resource>.go
Add command definitions in cmd/<resource>.go with subcommands (list, get, create, update, delete)
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 /kanban-sync. If the sync fails, log a brief warning and continue. Never block or retry — Planka sync is best-effort.

2.7 KiB Raw Blame History