# Neptune

Neptune 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.

**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):

```sh
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:

```sh
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:**

```bash
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:

```yaml
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](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/`:

| 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 |