Skip to content

CLAUDE.md

Latest commit

 

History

History
233 lines (168 loc) · 7.01 KB

CLAUDE.md

File metadata and controls

233 lines (168 loc) · 7.01 KB

AI Agent Context Guide: spx.sh

Quick Start

  1. Read this file for site overview
  2. See ~/Sites/hugo/CLAUDE.md for workspace-level Hugo context
  3. See ~/Sites/hugo/modules/hugo-claris/root/CLAUDE.md for theme details
  4. See specs/spx-website.prd.md for product requirements
  5. See specs/decisions/ for architectural decisions

Project Overview

This is the documentation and marketing website for SPX - Spec-Driven Development, built with Hugo using the hugo-claris theme.

SPX is a framework combining:

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

Content Structure

content/
├── _index.md           # Marketing landing page
├── cli/                # spx CLI documentation
│   └── _index.md       # CLI section landing
├── marketplace/        # SPX-Claude marketplace docs
│   └── _index.md       # Marketplace section landing
├── concepts/           # Spec-driven development methodology
│   └── _index.md       # Concepts section landing
└── about/              # Project information
    └── index.md        # About page

Specifications

specs/
├── spx-website.prd.md                    # Product requirements document
├── decisions/
│   └── adr-21_hugo-cloudflare-stack.md   # Hugo + Cloudflare architecture decision
└── work/
    ├── backlog/                          # Future work items
    ├── doing/                            # Active work items
    └── done/                             # Completed work items

Key Development Requirements

Environment Variables

  • HUGO_CLARIS_AUTHOR_EMAIL: REQUIRED. Set in .env file.

Quick Start Commands

cd ~/Sites/hugo/sites/spx.sh/spx.sh-root

# Development server (port 1613)
npm run devel

# Production build (uses published module versions)
npm run build

# Production build (uses local module worktrees)
npm run build:workspace

Output goes to public/.

All Available Scripts

Script Purpose
devel Development server on port 1613 (go.devel.work)
stage Staging server on port 1614 (go.stage.work)
prod Production server on port 1615 (go.mod versions)
build Production build using published module versions
build:workspace Production build using go.main.work
build:workspace:devel Production build using go.devel.work
build:workspace:stage Production build using go.stage.work
clean Remove public/ and resources/_gen/ directories
rebuild:workspace Shortcut for clean + build:workspace

Dependencies & Setup

npm ci                    # Install Node.js dependencies (required)
hugo mod npm pack         # Regenerate package.json from package.hugo.json

Branching & Deployment

Branch Environment Deployment URL Trigger
main Production https://spx.sh Push to origin/main
stage Staging https://stage.spx.sh Push to origin/stage
devel Development localhost:1613 Local only

Local Development with Modules

The go.work file references local module checkouts:

// go.work
go 1.21
use ../../../modules/hugo-claris/root    // devel branch of theme
use ../../../modules/claris-resources
use ../../../modules/fontawesome

Changes in hugo-claris/root/ are immediately visible without committing.

Technical Stack

  • Static Site Generator: Hugo (extended edition, 0.153.x)
  • Theme: Hugo Claris (Go Module)
  • Hosting: Cloudflare Pages
  • CI/CD: GitHub Actions
  • Languages: HTML, CSS, JavaScript, Go (templates)

See ADR: Hugo + Cloudflare Stack for architectural rationale.

Hugo-Specific Knowledge

NPM Dependencies and Scripts

File Purpose
package.hugo.json Source of truth - edit this file only
package.json Generated - DO NOT EDIT (overwritten)

IMPORTANT: Only modify package.hugo.json. The package.json file is auto-generated by hugo mod npm pack and will be overwritten. This includes both dependencies AND scripts.

To add/remove dependencies or modify scripts:

  1. Edit package.hugo.json in the project AND any modules that declare it
  2. Run hugo mod npm pack to regenerate package.json
  3. Run npm ci to update node_modules

Hugo Version Management

CRITICAL: Hugo 0.154+ has breaking changes with the hugo-claris theme. Use hvm (Hugo Version Manager) to ensure correct version:

# npm scripts automatically use hvm
npm run dev              # Uses hvm for correct Hugo version
npm run build:workspace  # Uses hvm for correct Hugo version

Module Commands

# Update a module dependency (module commands don't need env vars)
hugo mod get -u github.com/simonheimlicher/hugo-claris

# Clear module cache
hugo mod clean

CRITICAL: For running the server or building, ALWAYS use npm scripts:

  • npm run devel - Development server
  • npm run build:workspace - Production build with local modules

NEVER call hugo server or hugo --gc --minify directly - they will fail without env vars loaded by dotenvx and correct Hugo version from hvm.

Content Editing

Adding New Pages

Create page bundles in the appropriate section:

# New CLI documentation page
mkdir -p content/cli/commands
cat > content/cli/commands/index.md << 'EOF'
---
title: Commands Reference
description: Complete reference for spx CLI commands
date: 2025-01-17
---

Your content here...
EOF

Front Matter Template

---
title: Page Title
subtitle: Optional subtitle
description: SEO description (shown in search results)
date: 2025-01-17T00:00:00+0100
lastmod: 2025-01-17
keywords:
  - keyword1
  - keyword2
---

Available Shortcodes

From hugo-claris theme:

  • {{% lede-initial %}}First paragraph emphasis{{% /lede-initial %}}
  • {{< panel page="/cli" float=left relativewidth=45 >}}Panel content{{< /panel >}}

Inspecting Build Output

After npm run build:workspace:

# Check generated pages
ls -la public/
ls -la public/cli/
ls -la public/marketplace/
ls -la public/concepts/

# Check CSS bundles
find public/styles -name "*.css" -exec sh -c \
  'echo "$1: $(wc -c < "$1") bytes"' _ {} \;

# Check inline critical CSS
grep -o '<style[^>]*>' public/index.html | head -5