Steve Cliff
22d5848e1a
- 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.
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# 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 `/kanban-sync`.
|
|
If the sync fails, log a brief warning and continue. Never block or retry —
|
|
Planka sync is best-effort.
|