Development Guide

Prerequisites

• Git: Required for cloning the repository
• Node.js 20+: Required for SPT Orchestrator
• Go 1.24+: Required for the CLI
• Docker: Required for local DevPod or containerized setup
• DevPod (Optional): For cloud development environments

Environment Setup

Quick Start (Coder - Recommended)

1. Install spt CLI:

   go install github.com/smartpointstech/spt/cli/cmd/sptx@latest

2. Initialize and create workspace:

   spt init
   # Enter URL: https://coder.smartpoints.tech
   # Enter token: <your-session-token>
   
   spt up my-workspace

3. Connect:

   spt ssh my-workspace
   # Or use VS Code: coder open my-workspace

Quick Start (DevPod)

1. Install DevPod:

   • macOS: brew install loft-sh/devpod/devpod
   • Windows: choco install devpod
   • Linux: curl -L -o devpod "https://github.com/loft-sh/devpod/releases/latest/download/devpod-linux-amd64" && sudo install devpod /usr/local/bin

2. Launch Workspace:

   devpod up https://github.com/smartpointstech/spt --ide vscode

GitHub Codespaces

1. Create a new Codespace from the repository

2. Run the setup script:

   cd scripts/bootstrap && ./setup.sh

3. Connect to tmux: tmux attach -t workspace

Local Setup (macOS/Linux)

1. Clone the repository:

   git clone https://github.com/smartpointstech/spt.git
   cd spt/scripts/bootstrap

2. Run the setup script:

   • macOS: ./macos.sh
   • Linux: ./linux.sh

3. Attach to the workspace: tmux attach -t workspace

---

Development Workflow (SPT Flow)

Session Start Protocol

Every development session should follow this sequence:

# 1. Check Beads memory from previous sessions
bd-ready

# 2. Index codebase if needed
gnx-analyze

# 3. Create worktree for isolated work (if parallel execution)
wt-add feature-name

# 4. Start development
rf-swarm "your task description"

3-Tier Memory Usage

Tier 1: Beads (Cross-Session)

bd-ready              # Load previous session context
bd-add "Decision: Use JWT for auth"  # Store decisions
bd-search "auth"      # Recall past decisions
bd-list               # View all stored beads

Tier 2: Native Tasks (Session)

Automatic within Claude Code. No explicit commands needed.

Tier 3: SptDB (Semantic)

mem-store "key" "value"   # Store semantic memory
mem-search "query"        # Semantic retrieval
mem-stats                 # Memory statistics

GitNexus Workflow

Before modifying shared code:

# Check blast radius
gnx-blast src/auth/handler.go

# View dependencies
gnx-deps src/auth/handler.go

# Get structural context
gnx-context src/auth/handler.go

Rule: If blast radius > 5 files, pause and consult before proceeding.

Worktree Isolation

For parallel agent work:

# Create isolated worktree
wt-add feature-auth

# Work in the worktree
cd ../.worktrees/feature-auth

# When done, merge and cleanup
git checkout main
git merge feature-auth
wt-remove feature-auth

---

Tmux Workspace

The environment uses tmux with 4 pre-configured windows:

Window	Name	Purpose
0	Claude-1	Main workspace
1	Claude-2	Secondary workspace
2	Claude-Monitor	Usage tracking
3	htop	System monitor

Commands:

• Switch windows: Ctrl+b then 0-3
• Detach: Ctrl+b then d
• Reattach: tmux attach -t workspace

---

Common Commands

SPT Core (rf-*)

rf "your request"           # Direct SPT command
rf-swarm "build feature"    # Swarm with context
rf-hive "complex task"      # Hive-mind with context
rf-mesh "coordinated work"  # Mesh topology
rf-doctor                   # Auto-fix issues
rf-plugins                  # List installed plugins

Beads Memory (bd-*)

bd-ready                    # Session start
bd-add "note"               # Store note
bd-search "query"           # Search notes
bd-list                     # List all

GitNexus (gnx-*)

gnx-analyze                 # Index codebase
gnx-blast <file>            # Check impact
gnx-deps <file>             # Show dependencies
gnx-context <file>          # Get context

Worktrees (wt-*)

wt-add <name>               # Create worktree
wt-list                     # List worktrees
wt-remove <name>            # Remove worktree
wt-clean                    # Prune stale

QE (sqe-*)

sqe-generate                # Generate tests
sqe-gate                    # Run QE gate

OpenSpec (os-*)

os init                     # Initialize specs
os generate                 # Generate from specs

---

Testing

Unit Tests

# Go CLI tests
cd cli && go test ./...

# With coverage
cd cli && go test -coverprofile=coverage.out ./...

Integration Tests

# Run Playwright tests
npx playwright test

# With UI
npx playwright test --ui

QE Gate

# Run full QE gate (TDD, coverage, security)
sqe-gate

---

Building

Go CLI

cd cli
go build -o sptx ./cmd/sptx

Docker Image

cd infra/images/coder-base
docker build -t coder-base:local .

Full Build Verification

# Run from repo root
cd cli && go build ./cmd/... && cd ..
bash -n scripts/bootstrap/setup.sh
bash -n scripts/generate-claude-md.sh

---

Code Organization

spt/
├── agents/                 # 600+ AI agents
├── cli/                    # Go CLI
│   ├── cmd/sptx/           # Entry point
│   ├── internal/coder/     # Coder API client
│   ├── internal/config/    # Configuration
│   └── internal/ssh/       # SSH handling
├── infra/                  # Infrastructure
│   ├── images/             # Docker images
│   └── terraform/          # Coder templates
├── scripts/
│   ├── bootstrap/          # Setup scripts
│   │   └── setup.sh        # Main setup (SPT Orchestrator)
│   └── generate-claude-md.sh
├── docs/                   # Documentation
├── .spt/           # SPT configuration
│   ├── config.yaml         # Topology
│   └── plugins/            # 6 plugins
└── .beads/                 # Cross-session memory

---

Boot Sequence

When a workspace starts, the following happens:

1. System prerequisites installed (build-essential, python3, git, curl, jq)
2. Node.js 20+ installed or verified
3. Claude Code installed
4. SPT Orchestrator initialized (sptx init)
5. SPT MCP registered with Claude Code
6. SPT doctor runs auto-fixes
7. 6 plugins installed:
   • Agentic QE
   • Code Intelligence
   • Test Intelligence
   • Perf Optimizer
   • Teammate Plugin
   • Gastown Bridge
8. UI UX Pro Max skill installed
9. GitNexus installed and workspace indexed
10. Beads initialized for cross-session memory
11. Agent Teams enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
12. Workspace directories created
13. Statusline Pro v4.0 configured
14. Aliases loaded (50+ rf-, bd-, gnx-, wt-, mem-*, etc.)

---

Troubleshooting

Node.js Version

# Check version (must be 20+)
node --version

# Update via nvm
nvm install 20 && nvm use 20

SPT Issues

# Run doctor
sptx doctor --fix

# Reinitialize
sptx init

Memory Not Persisting

# Check Beads initialization
ls -la .beads/

# Reinitialize
bd init

Aliases Not Working

# Reload shell config
source ~/.bashrc  # or ~/.zshrc

# Check aliases exist
alias | grep rf-

Go CLI Build Fails

# Update dependencies
cd cli && go mod tidy

# Clean and rebuild
cd cli && go clean && go build ./cmd/...