feat: complete v2 rewrite with scaleset SDK

.claude/.gitignore

@@ -0,0 +1 @@
+settings.local.json

.claude/README.md

@@ -0,0 +1,46 @@
+# .claude/ — Project Configuration
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/pm` | Project manager mode — discuss, plan, delegate |
+| `/impl <feature>` | Implement a feature from specs |
+| `/test [packages]` | Run tests with race detector |
+| `/check` | Full CI pipeline (build, vet, fmt, lint, test) |
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| `spec-writer` | Write/update specs from a brief |
+| `developer` | Implement Go code from specs |
+| `code-reviewer` | Review code quality and idioms |
+| `spec-checker` | Verify implementation matches specs |
+
+## Structure
+
+```
+.claude/
+├── CLAUDE.md              # Project instructions (always loaded)
+├── settings.json          # Permissions, env vars
+├── rules/                 # Auto-loaded by file type
+│   ├── go-style.md        #   *.go → naming, errors, concurrency
+│   ├── architecture.md    #   internal/** → packages, interfaces, DI
+│   ├── testing.md         #   *_test.go → table-driven, mocking
+│   └── security.md        #   *.go, *.yaml → secrets, exec safety
+├── skills/                # Loaded on demand
+│   ├── pm/                #   Project manager orchestrator
+│   ├── go-expert/         #   Go patterns (oklog/run, slog, exec...)
+│   └── scaleset-sdk/      #   actions/scaleset SDK reference
+├── agents/                # Specialized subagents
+│   ├── developer.md
+│   ├── spec-writer.md
+│   ├── code-reviewer.md
+│   └── spec-checker.md
+└── commands/              # Slash commands
+    ├── pm.md
+    ├── impl.md
+    ├── test.md
+    └── check.md
+```

.claude/agents/code-reviewer.md

@@ -0,0 +1,24 @@
+---
+name: code-reviewer
+description: Review Go code for correctness, idioms, error handling, concurrency safety, and alignment with project specs.
+model: sonnet
+effort: 3
+allowedTools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# Go Code Reviewer
+
+You review Go code in the ghr project. Focus on:
+
+1. **Correctness**: Does the code do what the spec says? Check against `specs/` files.
+2. **Error handling**: Every error wrapped with context? No ignored errors? Sentinel errors used correctly?
+3. **Concurrency**: Mutex used correctly? No data races? Context propagation complete? Goroutines have shutdown paths?
+4. **Interfaces**: Consumer-side only? Minimal (1-3 methods)? No getter interfaces?
+5. **Go idioms**: Naming follows Go conventions? No Java patterns? Structs with exported fields?
+6. **Security**: No hardcoded secrets? No unsanitized exec input? Permissions checked?
+7. **Tests**: Coverage of error paths? Table-driven? Race detector compatible?
+
+Be specific. Reference line numbers. Suggest concrete fixes, not vague improvements.

.claude/agents/developer.md

@@ -0,0 +1,64 @@
+---
+name: developer
+description: Implement Go code for ghr v2. Receives precise instructions from the PM with spec references, files to create/modify, and expected behavior. Writes production-quality Go code with tests.
+model: opus
+effort: 3
+allowedTools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+---
+
+# Developer
+
+You are a senior Go developer implementing features for the ghr v2 project.
+
+## Input
+
+You receive **implementation instructions** from the PM containing:
+- Which spec(s) to follow (read them first)
+- Which files to create or modify
+- Expected behavior and edge cases
+- Dependencies on other packages
+
+## Process
+
+1. **Read the spec** — understand exactly what's expected
+2. **Read the architecture** — `specs/00-architecture.md` for package placement and patterns
+3. **Read existing code** — understand what's already implemented, import conventions
+4. **Implement** — write the code, following the spec precisely
+5. **Write tests** — alongside the implementation, not after
+6. **Verify** — `go build ./cmd/ghr` and `go test -race ./...`
+7. **Report** — list what was created/modified and any deviations from spec
+
+## Code standards
+
+- Package-by-feature under `internal/`
+- Consumer-side interfaces (defined where consumed, unexported, minimal)
+- Structs with exported fields (no getter interfaces)
+- Error wrapping: `fmt.Errorf("context: %w", err)`
+- `context.Context` as first parameter
+- Table-driven tests with `t.Run`
+- `oklog/run` for top-level actors, internal retry for per-group goroutines
+- Secrets via env vars, never hardcoded
+- No `any` without justification
+- No ignored errors with `_`
+
+## What you do NOT do
+
+- You don't decide architecture — that's in the specs
+- You don't add features not in the spec — flag them to the PM
+- You don't skip tests — every exported function gets tested
+- You don't skip error handling — every error is wrapped and returned
+- You don't use global state — everything via dependency injection
+
+## When something is unclear
+
+If the spec is ambiguous or you find a contradiction:
+1. State what's unclear
+2. State the two (or more) interpretations
+3. State which you'd pick and why
+4. Implement your pick but flag it in your report

.claude/agents/spec-checker.md

@@ -0,0 +1,31 @@
+---
+name: spec-checker
+description: Verify that implementation matches the project specs. Use when implementing a new feature to ensure nothing is missed.
+model: sonnet
+effort: 3
+allowedTools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# Spec Compliance Checker
+
+You verify that Go code matches the specs in `specs/`. For a given feature:
+
+1. Read the relevant spec file(s) from `specs/`
+2. Read the implementation code
+3. Compare point by point:
+   - Are all specified behaviors implemented?
+   - Are all edge cases handled as described?
+   - Do struct fields match the spec?
+   - Do function signatures match?
+   - Are config defaults correct?
+   - Are error messages as specified?
+4. Report:
+   - Implemented correctly
+   - Missing from implementation
+   - Deviations from spec (with reasoning if the deviation seems intentional)
+   - Spec ambiguities discovered during review
+
+Be thorough. Cross-reference between specs (e.g., spec 01 references spec 08 for auth).

.claude/agents/spec-writer.md

@@ -0,0 +1,66 @@
+---
+name: spec-writer
+description: Write detailed technical specs for ghr v2 features. Receives a brief from the PM, reads existing specs for context, and produces a complete spec document.
+model: opus
+effort: 3
+allowedTools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+---
+
+# Spec Writer
+
+You write technical specifications for the ghr v2 project.
+
+## Input
+
+You receive a **brief** from the PM that describes what needs to be specified. The brief contains:
+- What the feature does
+- User's requirements and decisions
+- Related existing specs to reference
+- Any constraints or non-goals
+
+## Process
+
+1. **Read existing specs** for context (especially `specs/00-architecture.md`)
+2. **Read related specs** mentioned in the brief
+3. **Write the spec** following the established format
+
+## Spec format
+
+Follow the same structure as existing specs in `specs/`:
+
+```markdown
+# Spec XX — Title
+
+## Overview
+1-2 sentences describing the feature.
+
+---
+
+## [Feature sections]
+Detailed description with:
+- Go code examples (structs, interfaces, function signatures)
+- Config YAML examples
+- Flow descriptions (startup, shutdown, error handling)
+- Decision rationale (why this approach)
+
+## Config schema
+Relevant YAML fields for this feature.
+
+## Integration points
+How this feature connects to other specs/packages.
+```
+
+## Rules
+
+- Be specific — include Go signatures, YAML examples, concrete values
+- Reference other specs by number (e.g., "see spec 08-auth.md")
+- Use the same terminology as existing specs
+- Flag any contradictions with existing specs
+- Don't over-specify implementation details that should be left to the developer
+- Config secrets via env vars only, never in YAML
+- Follow the architecture from spec 00 (package-by-feature, consumer-side interfaces)

.claude/commands/check.md

@@ -0,0 +1,16 @@
+---
+description: Run full CI checks locally (build, vet, fmt, lint, test)
+allowed-tools: Bash(go *) Bash(golangci-lint *)
+---
+
+# Full CI Check
+
+Run the complete check pipeline:
+
+1. `go build ./cmd/ghr` — must compile
+2. `go vet ./...` — static analysis
+3. Check formatting: `gofmt -l .` — must return empty (all formatted)
+4. `golangci-lint run` — lint (config: `.golangci.yml`)
+5. `go test -race ./...` — all tests with race detector
+
+Report pass/fail for each step. Stop on first failure.

.claude/commands/impl.md

@@ -0,0 +1,17 @@
+---
+description: Implement a feature from a spec. Reads the spec, plans, implements, tests.
+---
+
+# Implement from Spec
+
+Implement $ARGUMENTS following this workflow:
+
+1. **Read the spec**: Find the relevant spec in `specs/` for the requested feature
+2. **Read architecture**: Check `specs/00-architecture.md` for package placement and interfaces
+3. **Plan**: List the files to create/modify, the structs, interfaces, and functions needed
+4. **Implement**: Write the code following the spec precisely
+5. **Test**: Write tests alongside the implementation
+6. **Verify**: Run `go build ./cmd/ghr` and `go test -race ./...`
+7. **Review**: Check against the spec for any missed items
+
+If the spec is ambiguous or contradicts another spec, flag it before implementing.

.claude/commands/pm.md

@@ -0,0 +1,21 @@
+---
+description: Start the project manager mode. Discuss features, create specs, plan and delegate implementation.
+---
+
+# Project Manager Mode
+
+You are now the **project manager** for ghr v2. Read the PM skill at `.claude/skills/pm/SKILL.md` for your full instructions.
+
+Before anything else:
+1. Read `specs/00-architecture.md` to understand the current architecture
+2. Check what exists in `internal/` to know the project state
+3. Greet the user and ask what they want to work on
+
+Task from user: $ARGUMENTS
+
+If no arguments, ask what they want to work on. Options:
+- Discuss a feature or idea
+- Create a new spec
+- Implement a feature from an existing spec
+- Review project status
+- Something else

.claude/commands/test.md

@@ -0,0 +1,16 @@
+---
+description: Run tests with race detector and show results
+allowed-tools: Bash(go test *)
+---
+
+# Run Tests
+
+Run tests for $ARGUMENTS (default: all packages):
+
+```bash
+go test -race -v $ARGUMENTS
+```
+
+If no arguments: `go test -race ./...`
+
+After tests complete, summarize: passed/failed/skipped counts and any failures.

.claude/rules/architecture.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "internal/**/*.go"
+  - "cmd/**/*.go"
+---
+
+# Architecture Rules
+
+## Package structure
+- Package-by-feature under `internal/`, one level deep. No `domain/`, `app/`, `infra/` layers.
+- `internal/model/` contains ONLY shared data structs and enums. No interfaces. No logic. Under 100 LOC.
+- Each package owns its feature end-to-end.
+
+## Interfaces
+- Define interfaces where they are CONSUMED, not where they are implemented.
+- Consumer-side interfaces are unexported (lowercase) and minimal (1-3 methods).
+- Never create a central `ports.go` or `interfaces.go`.
+- Never create getter interfaces (`ID() string`, `Name() string`). Use struct fields.
+
+## Dependencies
+- Dependency injection is manual in `cmd/ghr/main.go`. No DI framework.
+- The `controller/` package defines what it needs from `github/` via a small interface.
+- The `health/` package defines what it needs from `controller/` via a small interface.
+- Import direction: `cli` → `controller` → `github`, `runner`, `notification`. Never the reverse.
+
+## Concurrency
+- `oklog/run.Group` for the top-level daemon actors (controller, health, API server, signal handler).
+- When ONE actor fails, ALL are interrupted — clean deterministic shutdown.
+- Per-group goroutines are managed INSIDE the controller with their own retry logic.
+- A single group failure does NOT kill other groups.
+
+## Configuration
+- All config values come from the config struct. No global variables.
+- Secrets via env vars only, never in YAML.
+- Auth credentials via `ghr login` / credentials file, not config.
+
+## Specs
+- Before implementing a feature, read the corresponding spec in `specs/`.
+- If the spec is unclear or you need to deviate, flag it rather than guessing.

.claude/rules/code-cleanliness.md

@@ -0,0 +1,22 @@
+# Code Cleanliness
+
+## Comments
+- No comments in code (Exception: explain the why). Code must be self-documenting through clear naming.
+- No godoc comments on types, functions, or methods. Names speak for themselves.
+- No inline comments, no section separators (--- lines), no TODO markers.
+- No commented-out code.
+- Exception: required `//go:` directives and `//nolint:` directives.
+
+## File size
+- Source files must stay under 200 LOC (excluding tests).
+- If a file grows beyond 200 LOC, split by logical concern into separate files.
+- One responsibility per file. Name files after what they contain.
+
+## Structure
+- Use subdirectories when a package has more than 5-6 files with distinct concerns.
+- Test files are exempt from the 200 LOC limit but should still be well-organized.
+- Group related types/functions in the same file. Don't scatter a concept across files.
+
+## Naming
+- File names describe their content: `handler.go`, `writer.go`, `validate.go`.
+- No generic names: `utils.go`, `helpers.go`, `common.go`, `misc.go`.