CLAUDE.md

1# Neptune
2 
3Neptune is a Terraform and OpenTofu PR automation tool. It runs plan/apply on pull requests using the [Terramate](https://github.com/terramate-io/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.
4 
5**Language**: Go. See `go.mod` for the current version.
6 
7---
8 
9## Mandatory Rules
10 
11These rules always apply — do not skip them under any circumstances.
12 
13### DCO Sign-off
14 
15Every commit **must** be signed off with `git commit -s`. The DCO bot is enabled; PRs with unsigned commits will fail.
16 
17- If you committed without sign-off: `git commit --amend -s --no-edit` then force-push.
18- Never add `Made-with: Cursor` or similar trailers to commit messages.
19 
20Before every commit, verify `user.name` and `user.email` are set in git config (global or local):
21 
22```sh
23git config user.name   # must return a non-empty value
24git config user.email  # must return a non-empty value
25```
26 
27If either is missing, resolve the values before committing:
28 
291. Try to infer them from context — run `gh api user --jq '.name,.email'` to retrieve the authenticated GitHub user's name and email.
302. If the email is private or empty, try `gh api user/emails --jq '.[].email'` and pick the primary address.
313. If the values still cannot be determined, **ask the user** what `user.name` and `user.email` should be — do not use placeholder values.
32 
33Once resolved:
34 
35```sh
36git config user.name "<resolved name>"
37git config user.email "<resolved email>"
38```
39 
40### Documentation After Changes
41 
42After any change that affects behavior, config, CLI flags, or CI, delegate documentation updates to the **documentation-maintainer** agent.
43 
44**Within a Claude Code session:** Use the Agent tool with `subagent_type: "documentation-maintainer"` and describe what changed in the prompt.
45 
46**From terminal:**
47 
48```bash
49claude --agent documentation-maintainer "update docs for: <what changed>"
50```
51 
52The agent runs the full checklist: README, docs/, examples/, AGENTS.md, CLAUDE.md, .claude/commands, .claude/skills. Do not skip this step.
53 
54### Issue Creation Validation
55 
56When 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.
57 
58---
59 
60## Go Standards
61 
62Applies to all `**/*.go` files:
63 
64- **Format**: `gofmt -s`. Run `make check-fmt` before committing; CI enforces it.
65- **Lint**: Conform to `.golangci.yml`. Do not introduce new violations.
66- **Packages**: Code in `internal/` must not be imported from outside this module.
67- **Errors**: Wrap errors with context: `fmt.Errorf("context: %w", err)`. Never silently ignore errors.
68- **Exports**: Public functions and types must have doc comments starting with the identifier name.
69- **Tests**: Place `*_test.go` in the same package as the code. Use table-driven tests.
70 
71---
72 
73## Config Schema (`.neptune.yaml`)
74 
75Top-level keys:
76 
77```yaml
78repository:
79  object_storage: "gs://..."      # GCS or S3 bucket for locking
80  branch: main
81  plan_requirements: [...]
82  apply_requirements: [...]
83  allowed_workflow: <string>
84  automerge: true/false           # Optional; enables auto-merge after apply
85workflows:
86  <name>:
87    steps:
88      - run: <command>
89        once: false               # default: run per stack; true: run once in root
90    depends_on: [...]             # optional
91```
92 
93Required environment variables: `NEPTUNE_CONFIG_PATH`, `GITHUB_REPOSITORY`, `GITHUB_TOKEN`, plus object storage credentials.
94 
95When the schema changes, update README, `.neptune.example.yaml`, `examples/`, and AGENTS.md.
96 
97---
98 
99## CI and Release
100 
101Applies to `.github/**/*.yml`, `Makefile`, `.goreleaser.yml`:
102 
103- **Semver**: Tags use `vMAJOR.MINOR.PATCH` (e.g. `v0.2.0`). The `v` prefix is required.
104- **Release**: Push a tag → CI runs `release.yml` → GoReleaser creates GitHub Release with binaries, Lambda zip, checksums, and release notes.
105- **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.
106- **Branch naming for labels**: `feat/...` → feature, `fix/...` → bug, `enhance/...` → enhancement, `ci/...` → github-actions, `(deps)/...` → dependencies, branch with `!` → breaking-change.
107- Keep path filters and job dependencies intact in CI workflows. Do not remove or override Renovate config in `.github/renovate.json5`.
108 
109---
110 
111## Agents, Commands, and Skills
112 
113Agents are managed centrally in the [code-agent-hub](https://github.com/devopsfactory-io/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/`:
114 
115| Type | Name | Purpose | Location |
116| ---- | ---- | ------- | -------- |
117| Agent | `documentation-maintainer` | Runs full doc checklist after code/config/CI changes | hub |
118| Agent | `em` | Engineering Manager — coordinates Neptune team | hub |
119| Agent | `go-developer` | Go implementation for Neptune | hub |
120| Agent | `iac-developer` | IaC modules and GitHub Actions | hub |
121| Agent | `issue-reviewer` | Triages open issues; validates drafts before upload | hub |
122| Agent | `issue-writer` | Creates GitHub issues from `/feature` and `/bug` commands | hub |
123| Agent | `platform-engineering` | GitOps, CI/CD, observability | hub |
124| Agent | `pr-reviewer` | Reviews PRs via `gh` CLI — DCO, Go style, tests, docs | hub |
125| Agent | `qa` | Code quality and test coverage | hub |
126| Agent | `security` | Security scanning for code and IaC | hub |
127| Command | `/bug` | Create a bug report (invokes issue-writer) | local |
128| Command | `/feature` | Create a feature request (invokes issue-writer) | local |
129| Skill | `maintain-documentation` | Delegates doc updates to documentation-maintainer agent | local |
130| Skill | `open-pull-request` | Commits and opens a PR via `gh` with DCO sign-off | local |
131| Skill | `release-and-versioning` | Cuts a semver release with GoReleaser | local |
132| Skill | `testing-and-ci` | Runs tests, lint, format checks; explains CI | local |
133