Skip to content

CLAUDE.md

Latest commit

 

History

History
132 lines (92 loc) · 6.06 KB

CLAUDE.md

File metadata and controls

132 lines (92 loc) · 6.06 KB
Raw

Neptune

Neptune is a Terraform and OpenTofu PR automation tool. It runs plan/apply on pull requests using the Terramate Go SDK for change detection and run order. Object storage (GCS or S3) is used for stack locking; GitHub handles PR requirements and comments.

Language: Go. See go.mod for the current version.

Mandatory Rules

These rules always apply — do not skip them under any circumstances.

DCO Sign-off

Every commit must be signed off with git commit -s. The DCO bot is enabled; PRs with unsigned commits will fail.

  • If you committed without sign-off: git commit --amend -s --no-edit then force-push.
  • Never add Made-with: Cursor or similar trailers to commit messages.

Before every commit, verify user.name and user.email are set in git config (global or local):

git config user.name   # must return a non-empty value
git config user.email  # must return a non-empty value

If either is missing, resolve the values before committing:

  1. Try to infer them from context — run gh api user --jq '.name,.email' to retrieve the authenticated GitHub user's name and email.
  2. If the email is private or empty, try gh api user/emails --jq '.[].email' and pick the primary address.
  3. If the values still cannot be determined, ask the user what user.name and user.email should be — do not use placeholder values.

Once resolved:

git config user.name "<resolved name>"
git config user.email "<resolved email>"

Documentation After Changes

After any change that affects behavior, config, CLI flags, or CI, delegate documentation updates to the documentation-maintainer agent.

Within a Claude Code session: Use the Agent tool with subagent_type: "documentation-maintainer" and describe what changed in the prompt.

From terminal:

claude --agent documentation-maintainer "update docs for: <what changed>"

The agent runs the full checklist: README, docs/, examples/, AGENTS.md, CLAUDE.md, .claude/commands, .claude/skills. Do not skip this step.

Issue Creation Validation

When creating GitHub issues via /feature or /bug, validate the draft with the issue-reviewer agent before calling gh issue create. Do not upload until the draft is approved or refined.

Go Standards

Applies to all **/*.go files:

  • Format: gofmt -s. Run make check-fmt before committing; CI enforces it.
  • Lint: Conform to .golangci.yml. Do not introduce new violations.
  • Packages: Code in internal/ must not be imported from outside this module.
  • Errors: Wrap errors with context: fmt.Errorf("context: %w", err). Never silently ignore errors.
  • Exports: Public functions and types must have doc comments starting with the identifier name.
  • Tests: Place *_test.go in the same package as the code. Use table-driven tests.

Config Schema (.neptune.yaml)

Top-level keys:

repository:
  object_storage: "gs://..."      # GCS or S3 bucket for locking
  branch: main
  plan_requirements: [...]
  apply_requirements: [...]
  allowed_workflow: <string>
  automerge: true/false           # Optional; enables auto-merge after apply
workflows:
  <name>:
    steps:
      - run: <command>
        once: false               # default: run per stack; true: run once in root
    depends_on: [...]             # optional

Required environment variables: NEPTUNE_CONFIG_PATH, GITHUB_REPOSITORY, GITHUB_TOKEN, plus object storage credentials.

When the schema changes, update README, .neptune.example.yaml, examples/, and AGENTS.md.

CI and Release

Applies to .github/**/*.yml, Makefile, .goreleaser.yml:

  • Semver: Tags use vMAJOR.MINOR.PATCH (e.g. v0.2.0). The v prefix is required.
  • Release: Push a tag → CI runs release.yml → GoReleaser creates GitHub Release with binaries, Lambda zip, checksums, and release notes.
  • Release notes: Generated by GitHub (github-native) and categorized by .github/release.yml + PR labels. For breaking changes to appear under "Breaking Changes", apply the breaking-change label before merge.
  • Branch naming for labels: feat/... → feature, fix/... → bug, enhance/... → enhancement, ci/... → github-actions, (deps)/... → dependencies, branch with ! → breaking-change.
  • Keep path filters and job dependencies intact in CI workflows. Do not remove or override Renovate config in .github/renovate.json5.

Agents, Commands, and Skills

Agents are managed centrally in the code-agent-hub at .claude/agents/<role>/AGENTS.md, each loading project-specific context from .claude/skills/neptune/<role>/SKILL.md. Commands and skills remain local in .claude/:

Type Name Purpose Location
Agent documentation-maintainer Runs full doc checklist after code/config/CI changes hub
Agent em Engineering Manager — coordinates Neptune team hub
Agent go-developer Go implementation for Neptune hub
Agent iac-developer IaC modules and GitHub Actions hub
Agent issue-reviewer Triages open issues; validates drafts before upload hub
Agent issue-writer Creates GitHub issues from /feature and /bug commands hub
Agent platform-engineering GitOps, CI/CD, observability hub
Agent pr-reviewer Reviews PRs via gh CLI — DCO, Go style, tests, docs hub
Agent qa Code quality and test coverage hub
Agent security Security scanning for code and IaC hub
Command /bug Create a bug report (invokes issue-writer) local
Command /feature Create a feature request (invokes issue-writer) local
Skill maintain-documentation Delegates doc updates to documentation-maintainer agent local
Skill open-pull-request Commits and opens a PR via gh with DCO sign-off local
Skill release-and-versioning Cuts a semver release with GoReleaser local
Skill testing-and-ci Runs tests, lint, format checks; explains CI local