Relationships
#1106 agent setup silently selects a destructive overwrite mode, with no way to choose otherwise and no documentation
Opened by jeremy · 7/13/2026· Shipped 7/13/2026
Problem
instructionsMode: "owned" causes repo upgrade/repo init to fully
overwrite the tool's instructions file on every run -- no managed-section
markers, no preservation of surrounding content, no warning, no backup.
This already affects two built-in integrations today, not just custom
tools: Cursor (.cursor/rules/swamp.mdc) and Kiro
(.kiro/steering/swamp-rules.md) are both hardcoded to "owned", so any
hand-edits to those specific files are destroyed on the next upgrade.
Claude and OpenCode/Codex/Copilot get the safer "shared" mode (managed
section, migrates legacy unmarked content instead of destroying it,
preserves everything else) purely because their instructions filenames
happen to match a hardcoded 4-name allowlist (AGENTS.md, AGENT.md,
CLAUDE.md, CONVENTIONS.md).
For custom tools via swamp agent setup, the mode is derived silently
from that same allowlist check against whatever filename the user types
-- there is no prompt, no flag, and no way to select "shared" mode for
a custom filename through the wizard. The wizard's own completion
summary only annotates the safe case (Instructions: foo.md (shared))
-- when the destructive "owned" mode is selected, the summary says
nothing at all, so a user has no way to know their file will be fully
overwritten on every future upgrade unless they separately run
swamp agent list and notice the Mode: owned line, or read the
source.
Verified directly against the latest published source
(v20260711.232311.0-sha.6bda08e7, confirmed to be both the tip of main
and the version this report's environment has installed): manually
editing .swamp-custom-tools.yaml to change instructionsMode: owned
to instructionsMode: shared for a non-allowlisted filename works and
is honored by repo upgrade -- the field is validated only against the
two literal string values, not re-derived against the filename
allowlist. So the safe behavior is fully functional today; it's just
undiscoverable without reading source.
Proposed solution
- Have the wizard explicitly ask whether the target file may already
contain content worth preserving (it already offers to scan an
existing repo for detection -- this is the natural place to also
ask), and offer
"shared"as a real, presented choice regardless of filename, rather than deriving it silently from a hardcoded list. - When
"owned"is selected (by the wizard or by filename derivation), say so explicitly in the completion summary and inagent listoutput -- e.g. "Instructions: foo.md (owned -- this file will be fully overwritten on everyrepo upgrade)". - Document
instructionsModein the shipped skill materials: what the two values mean, and that"shared"is usable for any instructions filename via.swamp-custom-tools.yaml, not just the four built-in allowlisted names. - Consider changing the built-in Cursor and Kiro configs to
"shared"mode as well, matching the other four built-in tools, since"shared"mode already handles the "file has legacy content with no markers" migration case gracefully.
Alternatives considered
Adding a blanket confirmation prompt before any overwrite -- rejected as noisy for the common case (a genuinely fresh repo with no pre-existing content), where scanning already tells the wizard there's nothing to protect. The better fix is making the existing detection-and-choice machinery (which already exists for the scan-an-existing-repo step) also drive the mode decision, rather than adding friction uniformly.
Shipped
Click a lifecycle step above to view its details.