pcli/openspec/changes/archive/2026-02-11-add-status-command/specs/status-command/spec.md

ADDED Requirements

Requirement: Status command summary output

The system SHALL provide a top-level pcli status command that outputs a summary of all boards, their lists, and card counts. The summary SHALL include the total number of boards. For each board, the summary SHALL include the board name and a breakdown of each list within that board showing the list name, the number of open cards (where isClosed is false), and the number of closed cards (where isClosed is true). Empty lists SHALL be included in the output with 0 open and 0 closed cards.

Scenario: Status with multiple boards and lists

• WHEN pcli status is executed and there are boards with lists containing cards
• THEN the output SHALL include the total board count
• AND each board SHALL list all its lists with open and closed card counts

Scenario: Status with empty lists

• WHEN a board contains a list with no cards
• THEN that list SHALL appear in the output with 0 open cards and 0 closed cards

Scenario: Status with no boards

• WHEN pcli status is executed and there are no boards
• THEN the output SHALL indicate 0 boards

Scenario: Status with closed cards

• WHEN a list contains both open and closed cards
• THEN the open card count SHALL exclude closed cards
• AND the closed card count SHALL be shown separately

Requirement: Status command JSON output

The system SHALL output the status summary in the standard JSON envelope format ({"data": ..., "error": null}) when --format json is used or no format flag is provided. The data field SHALL contain an object with totalBoards (integer) and boards (array). Each board object SHALL contain id (string), name (string), and lists (array). Each list object SHALL contain id (string), name (string), openCards (integer), and closedCards (integer).

Scenario: JSON output structure

• WHEN pcli status is executed with --format json or no format flag
• THEN the output SHALL be a JSON envelope with the status summary as the data field

Scenario: JSON output field types

• WHEN the JSON output is parsed
• THEN totalBoards SHALL be an integer
• AND each list's openCards and closedCards SHALL be integers

Requirement: Status command table output

The system SHALL output the status summary in a human-readable table format when --format table is specified. The table output SHALL begin with a line showing the total number of boards (e.g., 3 boards). For each board, the output SHALL display a board header line (e.g., Board: Sprint Planning) followed by a table with columns LIST and CARDS. The CARDS column SHALL display the open card count, and if there are closed cards, append (<n> closed) (e.g., 12 (2 closed)). If there are no closed cards, only the open count SHALL be displayed (e.g., 12).

Scenario: Table output with closed cards

• WHEN pcli status --format table is executed and a list has 12 open and 2 closed cards
• THEN the CARDS column for that list SHALL display 12 (2 closed)

Scenario: Table output with no closed cards

• WHEN pcli status --format table is executed and a list has 5 open and 0 closed cards
• THEN the CARDS column for that list SHALL display 5

Scenario: Table output with empty list

• WHEN pcli status --format table is executed and a list has 0 open and 0 closed cards
• THEN the CARDS column for that list SHALL display 0

Scenario: Table output board count line

• WHEN pcli status --format table is executed
• THEN the first line of output SHALL show the total board count (e.g., 3 boards)