Enhance scratchpad prompt and add test mode

.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Verify dependencies
+        run: go mod verify
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Run tests
+        run: go test -v -race -coverprofile=coverage.out ./...
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.out
+          retention-days: 7
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [test]
+    strategy:
+      matrix:
+        goos: [linux, darwin, windows]
+        goarch: [amd64, arm64]
+        exclude:
+          - goos: windows
+            goarch: arm64
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+
+      - name: Build binary
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: |
+          mkdir -p build
+          binary_name="ralph"
+          if [ "$GOOS" = "windows" ]; then
+            binary_name="ralph.exe"
+          fi
+          go build -ldflags="-s -w" -o "build/${binary_name}" ./cmd/ralph
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ralph-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: build/
+          retention-days: 7

.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+
+      - name: Run tests
+        run: go test -v -race ./...
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          distribution: goreleaser
+          version: '~> v2'
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -6,7 +6,8 @@
 
 # Build output
 build/
-ralph
+dist/
+/ralph
 
 # Go
 *.exe

.goreleaser.yml

@@ -0,0 +1,89 @@
+# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
+version: 2
+
+project_name: ralph
+
+before:
+  hooks:
+    - go mod tidy
+    - go mod verify
+
+builds:
+  - id: ralph
+    main: ./cmd/ralph
+    binary: ralph
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+    ignore:
+      - goos: windows
+        goarch: arm64
+    ldflags:
+      - -s -w
+      - -X github.com/hev/ralph/internal/config.Version={{.Version}}
+      - -X github.com/hev/ralph/internal/config.Commit={{.Commit}}
+      - -X github.com/hev/ralph/internal/config.Date={{.Date}}
+    mod_timestamp: '{{ .CommitTimestamp }}'
+
+archives:
+  - id: default
+    format: tar.gz
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- .Version }}_
+      {{- .Os }}_
+      {{- .Arch }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    format_overrides:
+      - goos: windows
+        format: zip
+    files:
+      - README.md
+      - LICENSE*
+
+checksum:
+  name_template: 'checksums.txt'
+  algorithm: sha256
+
+snapshot:
+  version_template: "{{ incpatch .Version }}-next"
+
+changelog:
+  sort: asc
+  use: github
+  filters:
+    exclude:
+      - '^docs:'
+      - '^test:'
+      - '^ci:'
+      - '^chore:'
+      - Merge pull request
+      - Merge branch
+  groups:
+    - title: Features
+      regexp: '^.*?feat(\([[:word:]]+\))??!?:.+$'
+      order: 0
+    - title: Bug Fixes
+      regexp: '^.*?fix(\([[:word:]]+\))??!?:.+$'
+      order: 1
+    - title: Other
+      order: 999
+
+release:
+  github:
+    owner: hev
+    name: ralph
+  draft: false
+  prerelease: auto
+  mode: append
+  header: |
+    ## Ralph {{ .Version }}
+  footer: |
+    **Full Changelog**: https://github.com/hev/ralph/compare/{{ .PreviousTag }}...{{ .Tag }}
+  name_template: "v{{.Version}}"

Makefile

@@ -1,28 +1,41 @@
-.PHONY: build install clean test run run-otel up down logs
+.PHONY: build install clean test test-race run run-otel up down logs snapshot release
 
 # Build variables
 BINARY_NAME=ralph
-VERSION=1.0.0
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+DATE ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
 BUILD_DIR=./build
 GO_FILES=$(shell find . -type f -name '*.go')
 
+# ldflags for version injection
+LDFLAGS=-s -w \
+	-X github.com/hev/ralph/internal/config.Version=$(VERSION) \
+	-X github.com/hev/ralph/internal/config.Commit=$(COMMIT) \
+	-X github.com/hev/ralph/internal/config.Date=$(DATE)
+
 # Build the binary
 build:
-	go build -ldflags="-s -w" -o $(BUILD_DIR)/$(BINARY_NAME) ./cmd/ralph
+	go build -ldflags="$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME) ./cmd/ralph
 
 # Install to GOPATH/bin
 install:
-	go install ./cmd/ralph
+	go install -ldflags="$(LDFLAGS)" ./cmd/ralph
 
 # Clean build artifacts
 clean:
 	rm -rf $(BUILD_DIR)
+	rm -rf dist/
 	go clean
 
 # Run tests
 test:
 	go test -v ./...
 
+# Run tests with race detector
+test-race:
+	go test -v -race ./...
+
 # Run ralph with default settings
 run: build
 	$(BUILD_DIR)/$(BINARY_NAME)
@@ -47,10 +60,19 @@ logs:
 
 # Build for multiple platforms
 build-all:
-	GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./cmd/ralph
-	GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./cmd/ralph
-	GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 ./cmd/ralph
-	GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./cmd/ralph
+	GOOS=linux GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./cmd/ralph
+	GOOS=linux GOARCH=arm64 go build -ldflags="$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./cmd/ralph
+	GOOS=darwin GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 ./cmd/ralph
+	GOOS=darwin GOARCH=arm64 go build -ldflags="$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./cmd/ralph
+	GOOS=windows GOARCH=amd64 go build -ldflags="$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./cmd/ralph
+
+# Create a snapshot release (for testing)
+snapshot:
+	goreleaser release --snapshot --clean
+
+# Create a release (requires GITHUB_TOKEN)
+release:
+	goreleaser release --clean
 
 # Show help
 help:
@@ -59,9 +81,12 @@ help:
 	@echo "  install    - Install ralph to GOPATH/bin"
 	@echo "  clean      - Remove build artifacts"
 	@echo "  test       - Run tests"
+	@echo "  test-race  - Run tests with race detector"
 	@echo "  run        - Build and run ralph"
 	@echo "  run-otel   - Build and run ralph with OTEL enabled"
 	@echo "  up         - Start the observability stack (docker-compose)"
 	@echo "  down       - Stop the observability stack"
 	@echo "  logs       - View docker-compose logs"
 	@echo "  build-all  - Build for multiple platforms"
+	@echo "  snapshot   - Create a snapshot release (testing)"
+	@echo "  release    - Create a release with goreleaser"

README.md

@@ -139,6 +139,9 @@ slack:
   bot_token: xoxb-...
   channel: C0123456789
   notify_users: U0123,U0456
+
+# Custom scratchpad instructions (replaces the default)
+scratchpad_prompt: "Use {{.AgentDir}} for notes. Track tasks in {{.AgentDir}}/TODO.md."
 ```
 
 ### Configuration Precedence
@@ -164,9 +167,16 @@ Ralph runs Claude Code in a loop with `--dangerously-skip-permissions`. Each ite
 
 The scratchpad instructions tell Claude to:
 - Use the agent directory as a scratchpad
-- Track progress in `TODO.md` using checkboxes
-- Make commits after each file edit
-- Work on one task at a time
+- Track progress in `TODO.md` using checkboxes (`- [ ]` pending, `- [-]` in-progress, `- [x]` done)
+- Work on one task at a time and focus on minimal context
+- Run tests before and after changes (no regressions allowed)
+- Keep todo-item artifacts under `.agent/items/<item-name>/` and clean up when done
+- Commit after completing and cleaning up each item
+- If reviewing a fresh plan, validate ordering and dependencies
+- If reviewing a completed plan, verify implementation and add improvement ideas
+- Keep `prompt.md` up to date for the next agent iteration
+
+You can customize these instructions with the `scratchpad_prompt` config option. Use `{{.AgentDir}}` as a placeholder for the agent directory path.
 
 ## Observability