merge: integrate roehrijn/goblet infrastructure and tooling

.claude/agents/README.md

@@ -0,0 +1,75 @@
+# Agent Workflows
+
+Token-efficient AI agent workflows for Goblet development tasks.
+
+## Available Agents
+
+| Agent | Purpose | Key Tasks |
+|-------|---------|-----------|
+| **release.md** | Manage releases | Version determination, GoReleaser workflow, artifact verification |
+| **testing.md** | Run test suites | CI pipeline, offline mode tests, race detection |
+| **offline-mode.md** | Verify offline features | Fallback testing, thread safety, monitoring |
+| **documentation.md** | Maintain docs | Standards, structure, conventional commits |
+
+## Usage
+
+Each agent provides:
+- **Core Workflow**: Step-by-step process for the task
+- **Quick Commands**: Copy-paste command reference
+- **Key Files**: Related source files and documentation
+- **Verification Steps**: How to validate success
+
+## Design Principles
+
+1. **Token Efficient**: Concise, actionable content
+2. **Self-Contained**: Each agent is independently usable
+3. **Standards-Based**: Uses project conventions (GoReleaser, conventional commits)
+4. **Practical**: Real commands, not abstract concepts
+
+## When to Use
+
+**Release Agent**: Before creating a version tag
+**Testing Agent**: Before committing code changes
+**Offline Mode Agent**: When modifying cache/offline features
+**Documentation Agent**: When updating project docs
+
+## Integration with Development
+
+These agents complement:
+- `Taskfile.yml` - Development task automation
+- `.github/workflows/` - CI/CD pipelines
+- `RELEASING.md` - Full release documentation
+- `testing/TEST_COVERAGE.md` - Test details
+
+## Contributing Agent Workflows
+
+When adding new agents:
+1. Keep under 2 pages (200-300 lines)
+2. Lead with core workflow
+3. Include quick command reference
+4. Link to detailed documentation
+5. Focus on actionable steps
+6. Use existing agents as templates
+
+## Example Usage
+
+```bash
+# Before creating a release
+cat .claude/agents/release.md
+# Follow the workflow: verify CI, check commits, create tag
+
+# When writing offline mode tests
+cat .claude/agents/offline-mode.md
+# Use the test commands and verification steps
+
+# For test-driven development
+cat .claude/agents/testing.md
+# Run baseline tests, implement, verify with CI
+```
+
+## Project Context
+
+**Repository**: github-cache-daemon (Goblet)
+**Purpose**: Git caching proxy server
+**Key Technologies**: Go, GoReleaser, GitHub Actions
+**Main Features**: Offline mode, multi-platform releases, comprehensive testing

.claude/agents/documentation.md

@@ -0,0 +1,142 @@
+# Documentation Agent
+
+Maintain comprehensive documentation following project standards.
+
+## Documentation Structure
+
+```
+├── README.md                    # Main project overview, usage
+├── RELEASING.md                 # Release process (GoReleaser)
+├── CHANGELOG.md                 # Keep a Changelog format
+├── CONTRIBUTING.md              # Contribution guidelines
+├── TESTING.md                   # Test infrastructure overview
+├── testing/TEST_COVERAGE.md     # Detailed test coverage
+├── testing/README.md            # Test details
+└── .claude/agents/*.md          # Agent workflows
+```
+
+## Documentation Standards
+
+**Format**: GitHub-flavored Markdown
+**Style**:
+- Clear, concise, actionable
+- Code blocks with language hints
+- Examples before explanations
+- Commands before concepts
+
+**Structure**:
+1. Quick start / TL;DR section
+2. Detailed explanations
+3. Examples and code snippets
+4. Troubleshooting (if applicable)
+5. Related resources
+
+## Conventional Commits for Docs
+
+```bash
+# Documentation changes
+git commit -m "docs: update offline mode configuration examples"
+git commit -m "docs: add troubleshooting section to RELEASING.md"
+git commit -m "docs: clarify semantic versioning guidelines"
+
+# Documentation fixes
+git commit -m "fix(docs): correct Docker image registry URL"
+```
+
+## Key Documentation Areas
+
+### 1. README.md
+- Project overview and purpose
+- Quick start usage
+- Offline mode features
+- Testing instructions
+- Basic configuration
+
+### 2. RELEASING.md
+- Complete release process
+- Conventional commit guidelines
+- GoReleaser workflow
+- Troubleshooting releases
+- Release checklist
+
+### 3. CHANGELOG.md
+- Follow [Keep a Changelog](https://keepachangelog.com/)
+- Semantic versioning links
+- Group by: Added, Changed, Fixed, Deprecated, Removed, Security
+- Update on each release (automated by GoReleaser)
+
+### 4. Testing Documentation
+- Test coverage details (`testing/TEST_COVERAGE.md`)
+- Test infrastructure (`testing/README.md`)
+- Quick test commands in README
+
+## Documentation Workflow
+
+1. **When adding features**
+   - Update README.md with usage
+   - Add examples and configuration
+   - Update test documentation if applicable
+   - Consider agent workflow updates
+
+2. **When fixing bugs**
+   - Add troubleshooting section if useful
+   - Update examples if bug was in docs
+
+3. **When releasing**
+   - Verify CHANGELOG.md updated (automatic)
+   - Check version references
+   - Verify all new features documented
+
+4. **For breaking changes**
+   - Add migration guide
+   - Update UPGRADING.md
+   - Clear examples of before/after
+   - Use `BREAKING CHANGE:` in commit
+
+## Documentation Verification
+
+```bash
+# Check markdown formatting
+markdownlint **/*.md
+
+# Verify links
+markdown-link-check README.md
+
+# Test code examples
+# Extract and run code blocks to verify accuracy
+```
+
+## Writing Guidelines
+
+**Code Examples**:
+- Include full commands, not fragments
+- Show expected output
+- Use realistic paths and values
+- Test before documenting
+
+**Structure**:
+- Use headers (##, ###) for organization
+- Bullet points for lists
+- Numbered lists for sequences
+- Code fences with language hints
+
+**Cross-references**:
+- Link to related docs
+- Reference specific files with full paths
+- Use anchor links for long documents
+
+## Agent Workflow Documentation
+
+Agent files (`.claude/agents/*.md`) should:
+- Be concise (1-2 pages max)
+- Lead with core workflow
+- Include quick command reference
+- Link to detailed docs
+- Focus on actionable steps
+
+## Related Resources
+
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Keep a Changelog](https://keepachangelog.com/)
+- [Semantic Versioning](https://semver.org/)
+- [GitHub Flavored Markdown](https://github.github.com/gfm/)

.claude/agents/offline-mode.md

@@ -0,0 +1,94 @@
+# Offline Mode Verification Agent
+
+Verify offline mode functionality and resilience features.
+
+## Core Capabilities
+
+Goblet automatically falls back to local cache when upstream is unavailable:
+- ls-refs requests served from local git repository
+- Graceful degradation during outages
+- Thread-safe configuration with atomic operations
+- Staleness warnings (>5 minutes old refs)
+
+## Verification Workflow
+
+1. **Test automatic fallback**
+   ```bash
+   # Integration test with warm cache
+   go test ./testing -v -run TestOfflineModeWithWarmCache
+
+   # Upstream failure scenarios
+   go test ./testing -v -run TestUpstreamFailureFallback
+   ```
+
+2. **Test thread safety**
+   ```bash
+   # Race detection for concurrent access
+   go test -race ./testing -run TestConcurrentOfflineRequests
+   go test -race ./testing -run "Offline"
+   ```
+
+3. **Verify configuration**
+   - Default: `UpstreamEnabled` = true with auto-fallback
+   - Testing: Use `SetUpstreamEnabled(&false)` to disable upstream entirely
+   - Thread-safe: Uses atomic operations for concurrent access
+
+## Expected Behaviors
+
+**Normal operation** (upstream available):
+- Forwards ls-refs to upstream
+- Caches response locally
+- Serves fetches from cache when possible
+
+**Upstream failure** (network down):
+- Detects failure on ls-refs
+- Reads refs from local git repo
+- Logs fallback event
+- Serves cached refs to client
+
+**Staleness warnings**:
+- Logs warning if refs >5 minutes old
+- Format: "Warning: serving stale ls-refs for /path (last update: Xm ago)"
+
+## Monitoring Log Patterns
+
+```bash
+# Fallback events
+"Upstream ls-refs failed (connection refused), attempting local fallback"
+
+# Stale cache warnings
+"Warning: serving stale ls-refs for /cache/path (last update: 10m ago)"
+```
+
+## Limitations
+
+- Fetch operations for uncached objects still fail (expected)
+- Cold cache (no prior fetches) will error when upstream down (expected)
+- Only ls-refs can be served offline, not fetch with new objects
+
+## Key Configuration
+
+```go
+// Production (default) - auto-fallback enabled
+config := &goblet.ServerConfig{
+    LocalDiskCacheRoot: "/path/to/cache",
+    // UpstreamEnabled defaults to true
+}
+
+// Testing - disable upstream entirely
+falseValue := false
+config.SetUpstreamEnabled(&falseValue)
+```
+
+## Test Coverage
+
+- 4 integration tests: End-to-end offline scenarios
+- 8 unit tests: Edge cases, concurrency, filtering
+- Thread safety verified with race detector
+- See `testing/TEST_COVERAGE.md` for details
+
+## Related Documentation
+
+- `README.md` - Offline mode features and configuration
+- `testing/TEST_COVERAGE.md` - Test details
+- `testing/README.md` - Test infrastructure

.claude/agents/release.md

@@ -0,0 +1,58 @@
+# Release Agent
+
+Guide releases using GoReleaser with semantic versioning and conventional commits.
+
+## Core Workflow
+
+1. **Verify readiness**
+   - Check `gh run list --branch main --limit 1` for CI status
+   - Run `git log --oneline -10` to verify conventional commits
+   - Run `task ci` locally to ensure all checks pass
+
+2. **Version determination**
+   - MAJOR (v2.0.0): Breaking changes, incompatible API
+   - MINOR (v1.1.0): New features, backwards compatible
+   - PATCH (v1.0.1): Bug fixes only
+
+3. **Create release**
+   ```bash
+   git tag -a vX.Y.Z -m "Release vX.Y.Z"
+   git push origin vX.Y.Z
+   gh run watch
+   ```
+
+4. **Verify artifacts**
+   - Check `gh release view vX.Y.Z` for all 5 platform archives
+   - Verify checksums.txt exists
+   - Test Docker image: `docker pull ghcr.io/jrepp/goblet-server:X.Y.Z`
+
+## Conventional Commit Types
+
+- `feat:` → Features (MINOR bump)
+- `fix:` → Bug fixes (PATCH bump)
+- `feat!:` or `BREAKING CHANGE:` → Major version bump
+- `perf:`, `docs:`, `test:` → Included in changelog
+- `chore:`, `ci:` → Excluded from changelog
+
+## Quick Commands
+
+```bash
+# Test locally before release
+goreleaser build --snapshot --clean
+goreleaser check
+
+# Create pre-release
+git tag -a v1.0.0-rc.1 -m "Release candidate"
+git push origin v1.0.0-rc.1
+
+# Delete failed release
+gh release delete vX.Y.Z
+git push origin :refs/tags/vX.Y.Z
+git tag -d vX.Y.Z
+```
+
+## Key Files
+
+- `.goreleaser.yml` - Build configuration
+- `.github/workflows/release.yml` - CI pipeline
+- `RELEASING.md` - Full documentation