@outcomeeng/spx

Developer CLI for code validation and session management.

What is spx?

spx is a command-line interface (CLI) tool that provides code validation and session management for projects that implement the spec-as-source methodology named Outcome Engineering. The spx CLI works hand-in-hand with the Claude Code and Codex plugin marketplace for Outcome Engineering.

The spx CLI orchestrates linting, type checking, circular dependency detection, markdown validation, literal reuse checks, and work handoffs between agent contexts.

Key Benefits

• Run the full quality gate through a single spx validation all command
• Queue, claim, and hand off work between agents with spx session
• Text and JSON output for CI and automation
• OIDC Trusted Publishing with Sigstore provenance via GitHub Actions

All commands are domain-scoped (e.g., spx validation, spx session) and support --quiet and --json flags for CI and automation.

Installation

npm install -g @outcomeeng/spx

From Source

git clone https://github.com/outcomeeng/spx.git
cd spx
pnpm install && pnpm run build
pnpm link --global

Usage

Code Validation

# Full validation pipeline
spx validation all

# Individual checks
spx validation lint              # ESLint
spx validation lint --fix        # ESLint with auto-fix
spx validation typescript        # TypeScript type checking (alias: spx validation ts)
spx validation circular          # Circular dependency detection
spx validation knip              # Unused code detection
spx validation markdown          # Markdown link validation (alias: spx validation md)
spx validation literal           # Source/test literal reuse detection

# Scope and targeting
spx validation all --scope production        # Exclude tests/scripts
spx validation all --fix                     # Auto-fix across all checks
spx validation all --files src/session/      # Validate specific files or directories

All validation commands support --quiet for CI and --json for machine-readable output.

Session Management

Manage work sessions for agent handoffs and task queuing:

# Create a handoff session (JSON header at start of stdin, then body bytes verbatim)
printf '%s\n' \
  '{"priority":"high","goal":"Implement change X","next_step":"Run the focused validation","specs":[],"files":[]}' \
  '# Implement change X' \
  '' \
  'Body text — `#`, `---`, and code fences are literal because the body is not parsed.' \
  | spx session handoff

# List all sessions
spx session list

# List todo sessions only
spx session todo

# Claim the highest priority session
spx session pickup --auto

# Release one or more sessions back to the todo queue
spx session release [id...]

# Archive a session after adding a non-empty result field to its frontmatter
spx session archive <session-id>

# Show session content
spx session show <session-id>

# Remove old todo sessions (keeps 5 by default)
spx session prune [--keep <n>] [--dry-run]

# Delete a session
spx session delete <session-id>

Sessions are stored in .spx/sessions/ with priority-based ordering (high > medium > low) and FIFO within the same priority. Commands output parseable <PICKUP_ID>, <HANDOFF_ID>, and <SESSION_FILE> tags for automation.

Spec Management (deprecated)

The spx spec and spx spx CLI domains are deprecated. Spec tree management has moved to the spec-tree Claude Code plugin, available at outcomeeng/plugins. The plugin provides skills for understanding, authoring, decomposing, contextualizing, testing, refactoring, and aligning specification trees.

Development

Setup

git clone https://github.com/outcomeeng/spx.git
cd spx
pnpm install
pnpm run build
pnpm link --global  # Optional: makes 'spx' available in your shell

Build and Test

pnpm run build          # Build with tsup
pnpm run dev            # Build in watch mode
pnpm test               # Build, then run all tests
pnpm run test:watch     # Run tests in watch mode
pnpm run test:unit      # Unit tests only
pnpm run test:e2e       # Build, then run end-to-end tests
pnpm run test:coverage  # Tests with coverage

Validation (Required Before Commits)

pnpm run validate              # Source CLI: full validation pipeline
pnpm run validate:production   # Source CLI: production scope only
pnpm run lint                  # Source CLI: ESLint only
pnpm run lint:fix              # Source CLI: ESLint with auto-fix
pnpm run typecheck             # Source CLI: TypeScript only
pnpm run circular              # Source CLI: circular dependency detection
pnpm run knip                  # Source CLI: unused code detection

The development validation scripts run tsx src/cli.ts, so they validate the current source tree. The packaged executable at bin/spx.js requires dist/cli.js; run pnpm run build before invoking it directly or through a global link.

Publish Validation

pnpm run publish:check        # Source validation, build, tests, packaged validation
pnpm run validate:published   # Packaged executable validation; requires dist/cli.js

pnpm run publish:check is the required pre-publish gate. It runs source validation, builds dist/, runs the test suite, and then runs node bin/spx.js validation all --scope production against the built executable.

CI/CD

The project uses GitHub Actions for continuous integration and publishing:

• ci.yml — Runs validate, test, and build on Node 22 and 24 for every push to main and every pull request. Includes dependency review to block PRs introducing vulnerable dependencies.
• publish.yml — Triggered by v* tags. Uses OIDC Trusted Publishing (no stored npm tokens) with Sigstore provenance attestation. Requires manual approval via the npm-publish GitHub Environment.
• scorecard.yml — Weekly OpenSSF Scorecard assessment, results published to the GitHub Security tab.

Publishing a Release

1. Run pnpm run publish:check
2. Bump the version in package.json
3. Commit and tag: git tag vX.Y.Z
4. Push: git push origin main && git push origin vX.Y.Z
5. Approve the deployment in the GitHub Actions npm-publish environment
6. Verify provenance with npm audit signatures

Technical Stack

• TypeScript — type-safe implementation (ESM)
• Commander.js — CLI framework
• Vitest — testing framework
• tsup — build tool (esbuild-based)
• ESLint 9 — linting with flat config
• GitHub Actions — CI/CD with OIDC Trusted Publishing

Architecture

src/
├── commands/      # CLI command implementations
│   ├── session/     # spx session subcommands
│   ├── validation/  # spx validation subcommands
│   └── spec/        # spx spec subcommands (deprecated)
├── domains/       # Domain routers
├── validation/    # Lint, typecheck, circular dep logic
├── session/       # Session lifecycle and storage
├── config/        # Configuration loading
├── git/           # Git integration utilities
├── scanner/       # Directory walking, pattern matching
├── status/        # Status state machine
├── reporter/      # Output formatting
├── tree/          # Hierarchical tree building
├── precommit/     # Pre-commit hook orchestration
└── lib/           # Shared utilities

License

MIT