Comparison

A · Cursor rules · devopsfactory-io/neptune B · CLAUDE.md · devopsfactory-io/neptune

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	1	9	0%
Commands	1	0	11	8%
Section tags	0	0	9	0%

What each file covers

Sections

0 shared · 1 only in A · 9 only in B

− Issue creation (/feature and /bug)
+ Neptune
+ Mandatory Rules
+ DCO Sign-off
+ Documentation After Changes
+ Issue Creation Validation
+ Go Standards
+ Config Schema (`.neptune.yaml`)
+ CI and Release
+ Agents, Commands, and Skills

Commands

1 shared · 0 only in A · 11 only in B

+ git config user.name
+ git config user.email
+ git config user.name "<resolved name>"
+ git config user.email "<resolved email>"
+ go.mod
+ git commit -s
+ git commit --amend -s --no-edit
+ gh api user --jq '.name,.email'
+ gh api user/emails --jq '.[].email'
+ make check-fmt
+ go-developer
gh issue create

Section tags

0 shared · 0 only in A · 9 only in B

+ lint-format
+ code-style
+ types
+ testing-strategy
+ git-pr
+ database
+ deployment
+ do-not
+ docs

Line diff

+127 added−5 removed6 unchanged4.5% identical

devopsfactory-io/neptune · .cursor/rules/issue-creation.mdc

@@ −1 @@

1---

2description: When creating issues via /feature or /bug, validate the draft with issue-reviewer before calling gh issue create.

3alwaysApply: true

4---

6# Issue creation (/feature and /bug)

8When handling **`/feature`** or **`/bug`**, the agent must validate the draft (title and body) with the **issue-reviewer** subagent before calling `gh issue create`. Do not upload the issue to GitHub until the review is done and the draft is approved or refined accordingly.

10See [.cursor/agents/issue-writer.md](.cursor/agents/issue-writer.md) (step 3.5) and [.cursor/agents/issue-reviewer.md](.cursor/agents/issue-reviewer.md) (draft-content workflow).

devopsfactory-io/neptune · CLAUDE.md

@@ +1 @@

1# Neptune

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.

5**Language**: Go. See `go.mod` for the current version.

7---

9## Mandatory Rules

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

13### DCO Sign-off

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

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.

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

22```sh

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

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

25```

27If either is missing, resolve the values before committing:

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.

33Once resolved:

35```sh

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

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

38```

40### Documentation After Changes

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

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

46**From terminal:**

48```bash

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

50```

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

54### Issue Creation Validation

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.

58---

60## Go Standards

62Applies to all `**/*.go` files:

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.

71---

73## Config Schema (`.neptune.yaml`)

75Top-level keys:

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

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

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

97---

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

116| ---- | ---- | ------- | -------- |

118| Agent | `em` | Engineering Manager — coordinates Neptune team | hub |

125| Agent | `qa` | Code quality and test coverage | hub |

133

@@ −1 +1 @@

1+# Neptune

3+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.

5+**Language**: Go. See `go.mod` for the current version.

17 ---

2−description: When creating issues via /feature or /bug, validate the draft with issue-reviewer before calling gh issue create.

3−alwaysApply: true

9+## Mandatory Rules

10+

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

12+

13+### DCO Sign-off

14+

15+Every 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+

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

21+

22+```sh

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

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

25+```

26+

27+If either is missing, resolve the values before committing:

28+

29+1. Try to infer them from context — run `gh api user --jq '.name,.email'` to retrieve the authenticated GitHub user's name and email.

30+2. If the email is private or empty, try `gh api user/emails --jq '.[].email'` and pick the primary address.

31+3. If the values still cannot be determined, **ask the user** what `user.name` and `user.email` should be — do not use placeholder values.

32+

33+Once resolved:

34+

35+```sh

36+git config user.name "<resolved name>"

37+git config user.email "<resolved email>"

38+```

39+

40+### Documentation After Changes

41+

42+After 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

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

50+```

51+

52+The 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+

56+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.

57+

458 ---

559

6−# Issue creation (/feature and /bug)

60+## Go Standards

761

8−When handling **`/feature`** or **`/bug`**, the agent must validate the draft (title and body) with the **issue-reviewer** subagent before calling `gh issue create`. Do not upload the issue to GitHub until the review is done and the draft is approved or refined accordingly.

62+Applies to all `**/*.go` files:

963

10−See [.cursor/agents/issue-writer.md](.cursor/agents/issue-writer.md) (step 3.5) and [.cursor/agents/issue-reviewer.md](.cursor/agents/issue-reviewer.md) (draft-content workflow).

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+

75+Top-level keys:

76+

77+```yaml

78+repository:

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

85+workflows:

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+

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

94+

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

96+

97+---

98+

99+## CI and Release

100+

101+Applies 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+

113+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/`:

114+

116+| ---- | ---- | ------- | -------- |

118+| Agent | `em` | Engineering Manager — coordinates Neptune team | hub |

125+| Agent | `qa` | Code quality and test coverage | hub |

11133