Skip to main content
← Back to list
01Issue
FeatureClosedSwamp CLI
AssigneesNone

Relationships

#641 Extension author gitignore guidance: add .swamp.yaml and CLAUDE.md to recommended excludes

Opened by josephholsten · 6/12/2026

Problem

The recommended .gitignore in the repo structure skill (references/repo/references/structure.md) covers .swamp/ secrets and .claude/, but not .swamp.yaml or CLAUDE.md. Extension authors following the skill docs will accidentally commit both files.

.swamp.yaml contains a machine-specific absolute path (written by swamp repo init) and behaves like a .git directory marker — it should be regenerated on each clone, not checked in. CLAUDE.md is agent instructions generated for the local developer environment, also not meaningful to share.

The swamp-extensions reference repo excludes both in practice, but this convention is nowhere in the published skill docs. Discovered while publishing a first extension (@josephholsten/freebsd/appjail) and comparing the resulting .gitignore against what swamp-extensions does.

Proposed Solution

Update the recommended .gitignore in references/repo/references/structure.md to:

# Swamp managed defaults
.swamp/
.swamp.yaml
.swamp-sources.yaml
CLAUDE.md
.claude/

And add a rationale row to the "Files to Never Commit" table:

Path Reason
.swamp.yaml Machine-specific absolute path; regenerated by swamp repo init
CLAUDE.md Agent instructions for local dev environment; not shareable

The same note would be useful in the extension publishing pre-push checklist in references/extension-publish/references/publishing.md.

Alternatives

Leave it undocumented and rely on authors discovering it by reading swamp-extensions. This is how the current situation arose.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

6/14/2026, 9:33:18 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

josephholsten commented 6/12/2026, 5:17:29 PM

Additional scope: the SWAMP_EXTENSION_REVIEW_DIR override and its effect on .gitignore guidance.

The adversarial review docs note that SWAMP_EXTENSION_REVIEW_DIR can be set to store review reports inside the repo (for CI, so reports survive across runners). When set, review files land at e.g. .swamp-review/swamp-extension-review/<hash>.json inside the working tree.

This creates a second gitignore decision that the docs don't address:

  • If SWAMP_EXTENSION_REVIEW_DIR is set intentionally for CI, the review directory should be committed — that's the whole point.
  • If it's set by accident or the author switches back to the temp-dir default, .swamp-review/ becomes untracked noise that should be gitignored.

Found this in a sibling extension repo (swamp-zfs) where .swamp-review/ exists on disk, is untracked, and the .gitignore has no entry for it — a half-state with no guidance on which way to go.

Suggested addition to the gitignore guidance: a note explaining the two cases and a recommended default (gitignore .swamp-review/ unless you're explicitly using SWAMP_EXTENSION_REVIEW_DIR for CI, in which case commit it).

stack72 commented 6/14/2026, 9:33:17 PM

Hey @josephholsten, thanks for filing this — but I believe both files should actually be checked in. Let me walk through why.

.swamp.yaml

The marker file doesn't contain machine-specific absolute paths. Looking at what swamp repo init actually writes (RepoMarkerData in src/infrastructure/persistence/repo_marker_repository.ts), the file stores:

  • swampVersion — the swamp version the repo was initialized/upgraded with
  • initializedAt / upgradedAt — timestamps
  • repoId — a stable UUID identifying the repo
  • tools — the list of enrolled AI tools (e.g. ["claude"])
  • datastore — datastore configuration
  • trustedCollectives / trustMemberCollectives — extension trust settings
  • Optional relative directory overrides (modelsDir, workflowsDir, etc.)

None of these are machine-specific. This is repo-level configuration that collaborators need to share. In fact, when the file is missing but a .swamp/ directory exists, the CLI explicitly tells users to "Restore .swamp.yaml from version control" — it expects this file to be checked in.

You may be thinking of the .swamp/ directory, which is gitignored — that's where runtime data, secrets, and workflow run artifacts live.

CLAUDE.md

The Claude tool config defines CLAUDE.md with instructionsMode: "shared" — it's intentionally designed to be committed. swamp repo init generates it with a managed section containing skill references, and users add their own project-level instructions on top. It's analogous to a .editorconfig or Makefile — it describes how to work with the repo so all collaborators get consistent agent behavior.

The things that are gitignored for Claude are the truly local artifacts: .claude/worktrees/, .claude/settings.local.json, .claude/scheduled_tasks.lock, and .claude/scheduled_tasks.json. These are managed by the gitignore section that swamp repo init generates automatically.

.swamp-sources.yaml

This one is correctly gitignored already — it's in the managed gitignore section that swamp repo init writes, under the comment "Local extension sources (developer-specific, not shared)."

Summary

The current gitignore setup is correct as-is. The managed section covers .swamp/ (runtime data), .swamp-sources.yaml (local dev extension paths), and tool-specific local config. Both .swamp.yaml and CLAUDE.md are repo-level shared files that should be committed.

I'm going to close this one out — but appreciate you raising it, since it highlights that the distinction between "what's shared" and "what's local" could be documented more clearly.

Sign in to post a ripple.