spikes: Instructions file for Codex

<coding_guidelines>

Spikes — Agent Instructions

Project Overview

Spikes is the feedback loop tool for AI-assisted building. Building prototypes is easy now (Claude Code, Cursor, v0). The bottleneck is turning feedback into action. Spikes makes feedback structured, precise, and agent-ready.

Two core use cases:

1. You reviewing agent work — Click elements, leave comments, agent gets exact CSS selectors
2. Collecting feedback from others — Share a link, they spike it, you get JSON for your agent

Components:

• Widget: Vanilla JS (widget/spikes.js, ~14KB gzipped, zero dependencies)
• CLI: Rust binary (cli/, v0.4.0, 36 subcommands)
• MCP Server: 16 tools via spikes mcp serve (stdio or HTTP transport)
• Site: Landing page and docs (site/, deployed to Cloudflare Pages)
• Worker: Cloudflare Workers backend (D1 + R2)
• NPM: spikes-mcp package for zero-install MCP

Work Tracking with werk

This project uses werk for all task/tension tracking. Always check werk before starting work.

werk tree                    # See full tension tree
werk show <id>               # Tension details + history
werk list                    # List all active tensions
werk reality <id> "new..."   # Update current reality
werk note add <id> "text"    # Add observational note
werk resolve <id>            # Mark tension resolved
werk add "desired" "actual" --parent <id>  # Create child tension

The root goal is "Have 10 paying users on spikes.sh"; all work should relate to it. If werk tree reports no tensions (no .werk/ workspace in this repo as of 2026-09-16), use GitHub issues in bierlingm/spikes and bierlingm/spikes-hosted as the tracking surface.

Architecture

widget/
  spikes.js           # Drop-in widget (14KB gzipped, IIFE pattern)

cli/
  Cargo.toml
  src/
    main.rs           # 36 subcommands via clap
    commands/         # list, show, export, inject, serve, mcp, login, share, status, watch, reply, versions, questions, etc.
    spike.rs          # Spike data structure
    storage.rs        # JSONL persistence (.spikes/feedback.jsonl)
    state.rs          # .spikes/state.json pull stamp + stale-cache warning
    api.rs            # Hosted API client + credential precedence (repo config > SPIKES_TOKEN > auth file)
    auth.rs           # Token/API key management
    config.rs         # TOML config (.spikes/config.toml)
    output.rs         # JSON/table formatting
    error.rs          # Error types
  templates/
    cloudflare/       # Self-host scaffold (Worker + D1 + R2)

site/
  index.html          # Landing page
  docs.html           # Documentation
  agents.md           # Machine-readable agent discovery
  llms.txt            # LLM context index
  spikes.js           # Widget served from spikes.sh

packages/
  spikes-mcp/         # NPM package for zero-install MCP (npx spikes-mcp)

action/               # GitHub Action for CI gating on feedback