SPX - Spec-Driven Development

This repository hosts the documentation and marketing website for the SPX framework, built with Hugo using the Hugo Claris theme.

What is SPX?

SPX is a framework for Spec-Driven Development — a methodology that combines fast, deterministic CLI tooling with Claude Code plugins to streamline AI-assisted development workflows.

• spx CLI: Fast, deterministic workflow management (<100ms, zero token cost)
• SPX-Claude: Claude Code marketplace with plugins for testing, coding, and documentation

Continuous Integration and Deployment (CI/CD)

This repository uses GitHub Actions to deploy to Cloudflare Pages.

Git branch	Cloudflare Pages project	Custom domain
main	spx-sh	https://spx.sh
stage	spx-sh-stage	https://stage.spx.sh

Local Development

Prerequisites

1. Hugo (extended edition, version 0.153.x) - Use hvm for version management
2. Dart Sass (version 1.70.0+)
3. Node.js (version 18+)

On macOS with Homebrew:

brew install sass/sass/sass node
# Hugo is managed via hvm (see package.json scripts)

Setup

# Clone the repository
git clone https://github.com/outcomeengineering/spx.sh.git
cd spx.sh

# Install Node dependencies
npm ci

Development Server

# Start development server (uses hvm for correct Hugo version)
npm run devel

The site will be available at http://localhost:1613

Build for Production

# Build with local module worktrees
npm run build:workspace

# Build with published module versions
npm run build

Output goes to public/.

Repository Structure

├── config/                 # Hugo configuration
│   └── _default/          # Default configuration files
├── content/               # Website content (Markdown)
│   ├── _index.md         # Home page
│   ├── cli/              # CLI documentation
│   ├── marketplace/      # Marketplace documentation
│   ├── concepts/         # Spec-driven development concepts
│   └── about/            # About page
├── assets/               # Site assets (images, SCSS)
├── specs/                # SPX specifications
│   ├── spx-website.prd.md           # Product requirements
│   ├── decisions/                    # Architecture decisions
│   └── work/                         # Work items (backlog/doing/done)
└── .github/workflows/    # CI/CD configuration

NPM Scripts

Script	Purpose
npm run devel	Development server with hot reload (port 1613)
npm run stage	Staging server (port 1614)
npm run prod	Production server (port 1615)
npm run build	Production build using published modules
npm run build:workspace	Production build using local module worktrees
npm run clean	Remove public/ and resources/_gen/
npm run rebuild:workspace	Clean + build with local modules

Note: Only modify package.hugo.json for dependencies and scripts. The package.json is auto-generated by hugo mod npm pack.

Technology Stack

• Static Site Generator: Hugo (extended edition)
• Theme: Hugo Claris
• Hosting: Cloudflare Pages
• CI/CD: GitHub Actions

See ADR: Hugo + Cloudflare Stack for architectural decision rationale.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE for details.