doc: consolidate claude skills and add gh cli workflow

.claude/skills/code-standards/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: code-standards
+description: Project code standards covering context usage, DI, workflow, errors, testing, API design, and Swagger docs. Always load when working with code in this repo.
+---
+
+# Barnacle Code Standards
+
+This project follows consistent patterns for Go development. Load the relevant reference documents below based on the area you're working in.
+
+## References
+
+| Reference | Load when... |
+|---|---|
+| [context-standards](references/context-standards.md) | Working with `context.Context` parameters or propagation |
+| [dependency-injection](references/dependency-injection.md) | Adding, modifying, or wiring dependencies via `internal/dependencies` |
+| [development-workflow](references/development-workflow.md) | Creating branches, commits, or PRs |
+| [environment-dependencies](references/environment-dependencies.md) | Adding dev tools or updating `make tools` |
+| [error-handling](references/error-handling.md) | Handling errors, defining sentinel errors, or returning HTTP errors |
+| [api-swagger-support](references/api-swagger-support.md) | Adding or updating Swagger/OpenAPI annotations |
+| [swagger-annotation-patterns](references/swagger-annotation-patterns.md) | Writing handler-level swagger comment blocks |
+| [swagger-model-documentation](references/swagger-model-documentation.md) | Documenting DTOs with struct tags, enums, or generics for swagger |
+| [internal-api-standards](references/internal-api-standards.md) | Building internal management API endpoints or DTOs |
+| [unit-testing-patterns](references/unit-testing-patterns.md) | Writing or modifying unit tests |

.claude/skills/api-swagger-support/SKILL.md → .claude/skills/code-standards/references/api-swagger-support.md

@@ -1,8 +1,3 @@
----
-name: api-swagger-support
-description: Guide for generating Swagger/OpenAPI documentation from Go code using swag and serving it via gin-swagger. Use when adding API documentation annotations to handlers, creating or updating Swagger comments, configuring swagger UI routes, running swag init/fmt, or troubleshooting documentation generation.
----
-
 # API Swagger Support (swag + gin-swagger)
 
 This project uses [swag](https://github.com/swaggo/swag) to generate Swagger 2.0 documentation from Go annotations, and [gin-swagger](https://github.com/swaggo/gin-swagger) to serve the interactive Swagger UI.
@@ -237,7 +232,7 @@ type Event struct {
     // time.Time auto-maps, but you can be explicit:
     CreatedAt time.Time `json:"createdAt" swaggertype:"string" format:"date-time"`
 
-    // Custom type → primitive
+    // Custom type -> primitive
     Status AppStatus `json:"status" swaggertype:"string" enums:"running,stopped"`
 
     // Map types
@@ -359,8 +354,8 @@ When adding swagger annotations to this codebase:
 
 ## Detailed References
 
-- See [references/annotation-patterns.md](references/annotation-patterns.md) for complete annotation examples matching this project's patterns
-- See [references/model-documentation.md](references/model-documentation.md) for struct tag patterns, enums, composition, and generics
+- See [swagger-annotation-patterns.md](swagger-annotation-patterns.md) for complete annotation examples matching this project's patterns
+- See [swagger-model-documentation.md](swagger-model-documentation.md) for struct tag patterns, enums, composition, and generics
 
 ## External Resources
 

.claude/skills/context-standards/SKILL.md → .claude/skills/code-standards/references/context-standards.md

@@ -1,7 +1,4 @@
----
-name: context-standards
-description: Code standards whenever working with golang's `context.Context` type
----
+# Context Standards
 
 When working with golang's `context.Context` type, there are a few code standards that should be followed.
 * Always check for cancellation, especially before doing expensive work.
@@ -11,5 +8,5 @@ When working with golang's `context.Context` type, there are a few code standard
 * NEVER pass nil context.
 * context.WithValue should only be used for carrying request-scoped, immutable data across API boundaries and between processes (e.g., security credentials, tracing IDs, or an authenticated user's details).
 * To avoid key collisions when using WithValue, define a custom, unexported type for your context keys, often an empty struct, rather than using basic types like string or int.
-* Do not use Context to pass optional function parameters; use regular function arguments for operational data. 
+* Do not use Context to pass optional function parameters; use regular function arguments for operational data.
 * Avoid storing large data in the context. Use dedicated function parameters or structs for large data payload

.claude/skills/dependency-injection/SKILL.md → .claude/skills/code-standards/references/dependency-injection.md

@@ -1,7 +1,4 @@
----
-name: dependency-injection
-description: Dependency injection patterns and practices for this project
----
+# Dependency Injection
 
 ## Overview
 
@@ -221,4 +218,4 @@ if err != nil {
     return err
 }
 deps.Logger().Info("starting")
-```
+```

.claude/skills/code-standards/references/development-workflow.md

@@ -0,0 +1,169 @@
+# Development Workflow
+
+## Branch Naming Conventions
+
+When starting work, create a branch from `main` using the appropriate prefix:
+
+* `feat/<short-name>` - For new features (e.g., `feat/blob-replication`)
+* `bug/<description>` - For bug fixes (e.g., `bug/redis-connection-timeout`)
+* `doc/<description>` - For documentation changes (e.g., `doc/api-examples`)
+
+## Development Workflow
+
+1. **Create branch** from `main` with the appropriate prefix
+2. **Do the work** - implement the feature, fix, or documentation
+3. **Commit and push** - commit changes with descriptive messages, push to remote
+4. **Create PR** - open a pull request targeting `main`
+5. **Wait for CI** - ensure all pipelines pass
+6. **Get review** - wait for code review approval
+7. **Squash merge** - merge to `main` using squash merge
+
+## Commit Message Style
+
+Follow conventional commits where appropriate:
+* `feat:` - New feature
+* `fix:` - Bug fix
+* `doc:` or `docs:` - Documentation
+* `refactor:` - Code refactoring
+* `test:` - Adding or updating tests
+* `chore:` - Maintenance tasks
+
+## GitHub CLI (`gh`) Reference
+
+This project uses the `gh` CLI for all GitHub interactions. Authentication is handled via `gh auth login` (already configured for this repo).
+
+### Creating a Branch and Pushing
+
+```bash
+# Start from an up-to-date main
+git checkout main
+git pull origin main
+git checkout -b feat/<short-name>
+
+# Stage and commit changes
+git add <files>
+git commit -m "feat: description of changes"
+
+# Push and set upstream tracking (-u only needed on first push)
+git push -u origin feat/<short-name>
+```
+
+### Creating a Pull Request
+
+Use `gh pr create` to open a PR from the current branch:
+
+```bash
+# Basic PR creation (will prompt for title and body if omitted)
+gh pr create --base main --title "feat: description" --body "Summary of changes"
+
+# Use commit messages to auto-fill title and body
+gh pr create --base main --fill
+
+# Use first commit for title, all commits for body
+gh pr create --base main --fill-first --fill-verbose
+
+# Create a draft PR
+gh pr create --base main --title "feat: WIP description" --draft
+
+# Use a heredoc for multi-line body
+gh pr create --base main --title "feat: description" --body "$(cat <<'EOF'
+## Summary
+- Change 1
+- Change 2
+
+## Test Plan
+- [ ] Unit tests pass
+- [ ] E2E tests pass
+EOF
+)"
+```
+
+### Checking PR Status
+
+```bash
+# View the current branch's PR details
+gh pr view
+
+# Check CI status for the current branch's PR
+gh pr checks
+
+# Watch CI checks until they complete (polls every 10s)
+gh pr checks --watch
+
+# Watch with a custom interval (seconds)
+gh pr checks --watch --interval 30
+
+# Only show required checks
+gh pr checks --required
+
+# List your open PRs
+gh pr list --author "@me"
+```
+
+### Merging a Pull Request
+
+Always use **squash merge** for this project:
+
+```bash
+# Squash merge the current branch's PR and delete the branch
+gh pr merge --squash --delete-branch
+
+# Squash merge with a custom commit message
+gh pr merge --squash --delete-branch \
+  --subject "feat: description (#123)" \
+  --body "Detailed description of the squashed changes"
+
+# Enable auto-merge (merges automatically once CI passes and review is approved)
+gh pr merge --squash --delete-branch --auto
+
+# Merge a specific PR by number
+gh pr merge 123 --squash --delete-branch
+```
+
+### Full Workflow Example
+
+```bash
+# 1. Create branch
+git checkout main && git pull origin main
+git checkout -b feat/blob-ttl
+
+# 2. Do the work, commit
+git add internal/registry/cache/disk/cache.go
+git commit -m "feat: add TTL support for disk blob cache"
+
+# 3. Push
+git push -u origin feat/blob-ttl
+
+# 4. Create PR
+gh pr create --base main \
+  --title "feat: add TTL support for disk blob cache" \
+  --body "Adds configurable TTL eviction to the disk-based blob cache."
+
+# 5. Wait for CI (watch checks in terminal)
+gh pr checks --watch
+
+# 6. After approval, squash merge and clean up
+gh pr merge --squash --delete-branch
+
+# 7. Return to main
+git checkout main && git pull origin main
+```
+
+### Auto-Merge Workflow
+
+When CI is still running or review is pending, enable auto-merge so the PR merges as soon as all requirements are met:
+
+```bash
+# Create PR and immediately enable auto-merge
+gh pr create --base main \
+  --title "feat: description" \
+  --body "Summary of changes"
+
+gh pr merge --squash --delete-branch --auto
+```
+
+To disable auto-merge if plans change:
+
+```bash
+gh pr merge --disable-auto
+```

.claude/skills/environment-dependencies/SKILL.md → .claude/skills/code-standards/references/environment-dependencies.md

@@ -1,13 +1,8 @@
----
-name: environment-dependencies
-description: Standards for managing development environment tools and keeping the Makefile tools recipe in sync
----
+# Environment Dependencies
 
-## Environment Dependencies
+This covers the management of external development tools required to build, test, and develop the Barnacle project. All required tools must be documented here and installed via `make tools`.
 
-This skill covers the management of external development tools required to build, test, and develop the Barnacle project. All required tools must be documented here and installed via `make tools`.
-
-### Required Tools
+## Required Tools
 
 The following tools are required for development and are installed by `make tools`:
 
@@ -17,7 +12,7 @@ The following tools are required for development and are installed by `make tool
 | `goimports` | Code formatting with import organization | `go install golang.org/x/tools/cmd/goimports@latest` |
 | `golangci-lint` | Linting and static analysis (v2 required) | `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest` |
 
-### Adding a New Tool
+## Adding a New Tool
 
 When adding a new development tool dependency:
 
@@ -45,9 +40,9 @@ tools:
 	@echo "All tools installed successfully"
 ```
 
-Then update this skill document to include mockgen in the Required Tools table.
+Then update this document to include mockgen in the Required Tools table.
 
-### First-Time Setup
+## First-Time Setup
 
 New developers should run:
 
@@ -57,12 +52,12 @@ make tools
 
 This installs all required development tools. Run this command again if tools are updated or new tools are added.
 
-### Version Pinning
+## Version Pinning
 
 Currently, tools are installed at `@latest`. If version pinning becomes necessary for reproducibility, update the install commands to use specific versions:
 
 ```makefile
 go install github.com/swaggo/swag/cmd/swag@v1.16.6
 ```
 
-Document any pinned versions and the reason for pinning in this file.
+Document any pinned versions and the reason for pinning in this file.

.claude/skills/error-handling/SKILL.md → .claude/skills/code-standards/references/error-handling.md

@@ -1,9 +1,6 @@
----
-name: error-handling
-description: Skill for handling errors in code
----
+# Error Handling
 
-## Error Handling
+## Sentinel Errors
 - **NEVER use inline `fmt.Errorf()` calls in function returns** - Always use global error variables
 - Define global error variables at package level using `errors.New()`:
   ```go
@@ -22,7 +19,7 @@ description: Skill for handling errors in code
 - Always wrap underlying errors with `%w` to preserve the error chain
 - Include relevant context (filenames, paths, etc.) between the sentinel error and wrapped error
 
-### HTTP API Errors
+## HTTP API Errors
 - **ALWAYS use `internal/tk/httptk` error factories for HTTP API errors** - These conform to the OCI distribution specification
 - Use pre-defined factory methods instead of constructing errors manually:
   ```go
@@ -50,4 +47,4 @@ description: Skill for handling errors in code
 
   // BAD:
   c.Error(httptk.ErrManifestUnknown(nil))  // Linter will warn about unchecked error
-   ```
+   ```