| name | provider-golangci-lint-uplift |
| description | Uplift a Terraform provider's golangci-lint config to the HashiCorp terraform-provider-scaffolding-framework standard by fetching the latest baseline from GitHub and additively merging missing linters, settings, and sections. Use this skill when the user wants to align golangci-lint config with HashiCorp standards, add scaffolding-framework linters, uplift or upgrade lint configuration, or bring a provider's linting in line with the official template. Also applies when the user mentions "scaffolding lint config", "standard linters", or "HashiCorp lint baseline". |
| user-invocable | true |
| argument-hint | [path-to-golangci-yml] - Defaults to .golangci.yml in the repo root |
Uplift golangci-lint Config to Scaffolding Framework Standard
Fetch the latest golangci-lint config from the HashiCorp
terraform-provider-scaffolding-framework repo and additively merge any
missing linters, settings, and sections into the local project's config. Local
customizations are always preserved.
Why Additive Only
Teams invest effort tuning their lint config — extra linters, custom
thresholds, project-specific exclusions. Removing or overwriting those
decisions causes friction and breaks trust. The scaffolding config represents a
minimum standard; anything the local project already has beyond that baseline
is the team's prerogative.
| Scenario | Action | Reason |
|---|
| Item in baseline, missing locally | Add | Bring up to minimum standard |
| Item in local, not in baseline | Keep | Local exceeds baseline |
| Item in both, values differ | Keep local | Local customization wins |
This applies uniformly across linters, settings, formatters, exclusions, and
top-level sections. Never remove, replace, or overwrite existing config.
Execution Steps
1. Fetch the Latest Baseline
The remote scaffolding repo is always the source of truth. Fetch it first:
gh api repos/hashicorp/terraform-provider-scaffolding-framework/contents/.golangci.yml --jq '.content' | base64 -d
If the fetch fails (no network, rate limit, auth issue), fall back to the
snapshot in references/baseline.yml — but inform the user that you're using a
cached version and suggest they retry with network access later.
2. Read the Target Config
Read .golangci.yml (or the path provided as argument).
- File missing: Inform the user and offer to create one from the fetched
baseline as a starting point.
- v1 format (no
version key, uses linters-settings instead of
linters.settings): Inform the user that a v1-to-v2 migration is needed
before this skill can be applied, and stop. The golangci-lint v2 migration
guide is at https://golangci-lint.run/product/migration-guide/.
3. Delta Analysis
Compare the local config against the fetched baseline. Present a delta report
before making any changes:
To add — items in baseline, missing locally:
- Each missing linter with a one-line description of what it catches
- Each missing setting block
- Each missing section or exclusion preset
Already present — items in both configs (no action needed)
Local extras — items in local only (will be preserved as-is)
Wait for user confirmation before proceeding to changes.
4. Apply Changes
- Linters — add missing entries to
linters.enable, maintaining
alphabetical order.
- Settings — add missing setting blocks under
linters.settings. For
compound settings like depguard, merge missing deny rules into existing
rule groups without duplicating or removing existing rules.
- Sections — add missing top-level sections (e.g.,
issues, formatters).
- Exclusions — add missing presets and paths to
linters.exclusions.
- Formatters — add missing entries to
formatters.enable.
5. Validate
Run both checks and report results:
go build ./...
For linting, use whichever is available:
golangci-lint run ./...
go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest run ./...
- Config must parse without errors.
- New lint findings are expected from newly enabled linters — report as a
summary (count per linter).
- Build must pass with no regressions.
6. Document
Create a spec history file at spec/history/NNN-uplift-golangci-lint-config.md
with:
- Date of uplift
- Delta analysis summary (what was added, what was kept)
- Verification results (build status, lint issue counts by linter)
Use the next available number prefix.
