pcli/openspec/specs/status-command/spec.md

ADDED Requirements

Requirement: Status command project filtering

The system SHALL accept an optional --project <name> flag on the pcli status command. When --project is provided, the system SHALL resolve the project name to a project ID using case-insensitive exact matching against all accessible projects. The system SHALL then filter the board list to include only boards whose projectId matches the resolved project ID. The totalBoards count in the output SHALL reflect the filtered board count. When --project is omitted, behavior SHALL be unchanged (all boards shown).

Scenario: Status filtered by project name

• WHEN pcli status --project "MyProject" is executed and the project exists with 2 boards
• THEN the output SHALL include only the 2 boards belonging to "MyProject"
• AND totalBoards SHALL be 2

Scenario: Status filtered by project name case-insensitive

• WHEN pcli status --project "myproject" is executed and a project named "MyProject" exists
• THEN the output SHALL include boards belonging to "MyProject"

Scenario: Status with project filter and no matching boards

• WHEN pcli status --project "EmptyProject" is executed and the project exists but has no boards
• THEN the output SHALL show totalBoards as 0 and an empty boards array

Scenario: Status with project not found

• WHEN pcli status --project "NonExistent" is executed and no project with that name exists
• THEN the system SHALL output an error "project not found: NonExistent"
• AND the system SHALL exit with code 1

Scenario: Status without project flag

• WHEN pcli status is executed without --project
• THEN the output SHALL include all boards across all projects (unchanged behavior)

Requirement: Status command summary output

The system SHALL provide a top-level pcli status command that outputs a summary of all boards (or boards filtered by --project), 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)