spx CLIFast, Deterministic Workflow Management

spx scans your project’s specs/ directory and provides instant status analysis of work items (capabilities, features, stories). It replaces slow, token-expensive LLM-based status checks with deterministic filesystem operations completing in under 100ms.

  • Fast: Scan entire spec tree in <100ms vs 1-2 minutes with LLM
  • Deterministic: Reliable DONE/IN PROGRESS/OPEN classification
  • Zero token cost: No LLM calls for status checks
  • Multiple formats: Text, JSON, Markdown, Table output
1git clone https://github.com/simonheimlicher/spx-cli.git
2cd spx-cli
3npm install
4npm run build
5npm link  # Makes 'spx' available globally
1npm install -g spx

Display project status with hierarchical tree view:

1spx status              # Text output
2spx status --json       # JSON for scripts/agents
3spx status --format markdown
4spx status --format table

Example output:

1capability-21_core-cli [IN PROGRESS]
2├── feature-21_pattern-matching [DONE]
3│   ├── story-21_parse-capability-names [DONE]
4│   ├── story-32_parse-feature-names [DONE]
5│   └── story-43_parse-story-names [DONE]
6├── feature-32_directory-walking [IN PROGRESS]
7│   ├── story-21_recursive-walk [DONE]
8│   └── story-32_pattern-filter [OPEN]
9└── feature-43_status-determination [OPEN]

Find the next work item to tackle:

1spx next

Manage work sessions for agent handoffs and task queuing:

 1# Create a handoff session
 2echo "# Implement feature X" | spx session handoff --priority high
 3
 4# List all sessions
 5spx session list
 6
 7# Claim the highest priority session
 8spx session pickup --auto
 9
10# Release session back to queue
11spx session release
12
13# Show session content
14spx session show <session-id>
15
16# Delete a session
17spx session delete <session-id>

Sessions are stored in .spx/sessions/ with priority-based ordering (high → medium → low) and FIFO within the same priority.

Status is computed deterministically from the tests/ directory:

ConditionStatus
No tests/ directory or emptyOPEN
tests/ has files but no DONE.mdIN PROGRESS
tests/DONE.md existsDONE

spx expects work items in specs/doing/ following this pattern:

1specs/doing/
2└── capability-NN_{slug}/
3    ├── {slug}.capability.md
4    └── feature-NN_{slug}/
5        ├── {slug}.feature.md
6        └── story-NN_{slug}/
7            ├── {slug}.story.md
8            └── tests/
9                └── DONE.md  # Present when complete

Numbers use BSP (Binary Space Partitioning) for easy insertion: start with 21, 32, 43… and insert between existing items.