feat(repo): custom agent tool definitions via swamp agent setup

[stack72]

Summary

• Adds swamp agent setup interactive wizard for defining custom AI agent tools
• Custom tools get skills + instructions + gitignore scaffolding, stored in .swamp-custom-tools.yaml at repo root
• swamp repo init --tool <custom-name> works once defined
• Built-in tools (claude, cursor, kiro, etc.) retain full audit/hooks/doctor integration
• Custom tools skip audit subsystems — promoted to built-in when adoption warrants

How it works

1. swamp agent setup asks the tool name, optionally scans an existing repo for config patterns (.windsurf/rules/, AGENTS.md, etc.), then asks where the tool reads instructions from
2. Defaults are derived: skills go to .<name>/skills/, instructions mode (shared vs owned) from the file location
3. Definition saved to .swamp-custom-tools.yaml — committable, copyable between repos
4. swamp repo init --tool <name> resolves custom tools via ToolResolver, copies skills, generates instructions

Architecture

• ToolConfig value object unifies built-in and custom tools at the scaffolding layer
• AiTool union stays closed for built-in exhaustiveness checks
• Boundary types (RepoMarkerData.tools, init/upgrade options/results) widened to string[]
• ToolResolver checks built-in tools first (O(1)), then custom-tools.yaml (lazy-loaded)
• DDD: ToolResolver accepts an injected CustomToolLoader to avoid domain→infrastructure import

New files

• src/domain/repo/custom_tool.ts — types, factories, validation, detection, defaults derivation
• src/domain/repo/tool_resolver.ts — resolution layer (built-in + custom)
• src/infrastructure/persistence/custom_tools_repository.ts — YAML persistence
• src/cli/commands/agent_setup.ts — swamp agent setup/list/rm commands
• Tests for all new modules (41 tests)

Ecosystem research

Researched 12 AI coding tools (Windsurf, Zed, Amp, Aider, Cline, Roo Code, Kilo Code, Trae, Augment, Tabnine, PearAI, Pi). AGENTS.md is converging as the cross-tool standard. Most tools use .<toolname>/rules/ for config. Skills at .<toolname>/skills/ works for tools with native support (Pi, Kilo) and via instructions references for others.

Test plan

• deno check passes
• deno lint clean on new files
• deno fmt applied
• deno run test — 6007 passed, 0 failed
• deno run compile — binary compiles
• Manual: swamp agent setup → define custom tool → swamp repo init --tool <name> → verify scaffolding
• Manual: swamp agent list / swamp agent rm
• Manual: swamp repo init --tool nonexistent → helpful error

🤖 Generated with Claude Code

[github-actions]

Code Review

Clean, well-designed PR. The DDD patterns are solid — ToolConfig as a value object, ToolResolver as a domain service with an injected CustomToolLoader port to avoid domain→infrastructure coupling, and exhaustive builtInToolConfig factory. Test coverage for the new domain and infrastructure modules is thorough (custom_tool_test.ts, tool_resolver_test.ts, custom_tools_repository_test.ts).

Blocking Issues

None.

Suggestions

1. No test file for agent_setup.ts — The domain logic it delegates to is well-tested, but repo_init_test.ts and doctor_audit_test.ts set a precedent for CLI command tests. At minimum, testing that agentListCommand and agentRemoveCommand wire up correctly (or that the --json guard on agentSetupCommand throws UserError) would be lightweight wins.

2. Unused re-export in ai_tool.ts — isBuiltInTool is re-exported from ai_tool.ts (line 39) but the only consumer (doctor_service.ts) imports from custom_tool.ts directly. The re-export is harmless but creates an odd dependency direction (ai_tool.ts → custom_tool.ts → ai_tool.ts type import). Consider removing it until a consumer actually needs it from that path.

3. Fixed 1024-byte stdin buffer in promptLine — Extremely unlikely to matter for tool names and paths, but Deno.stdin.read(buf) with a 1024-byte buffer silently truncates longer input. A TextLineStream or readline approach would be more robust if this wizard grows more prompts over time.

[github-actions]

CLI UX Review

Blocking

None.

Suggestions

1. No .example() calls on new agent subcommands (src/cli/commands/agent_setup.ts). All three (setup, list, rm) have descriptions but no examples. Every other command with a comparable shape (e.g. repoInitCommand, datastoreSetupFilesystemCommand) shows examples in help. swamp agent setup --help gives the user no sample invocation to copy. Consider adding even one example per command — e.g. swamp agent rm windsurf.

2. Exit-code asymmetry in agent rm for missing tool (agent_setup.ts:298–301). In log mode, swamp agent rm nonexistent throws UserError → non-zero exit. In JSON mode, the same call exits 0 with { removed: false }. A script doing swamp agent rm --json nonexistent || echo "error" will never print "error". The JSON output does carry removed: false, so callers who inspect the payload are fine — but the discrepancy with log mode is surprising. Consider throwing UserError in JSON mode too (or documenting the intended contract).

3. Tab completion for --tool doesn't include custom tools (repo_init.ts:47–48). ToolNameType.complete() returns only the seven built-in names. After a user defines a custom tool with swamp agent setup, pressing <tab> after --tool won't suggest it. Async IO in complete() is awkward, so this is likely an acceptable known limitation — worth a code comment so future contributors don't wonder.

4. agent setup has no --repo-dir flag (agent_setup.ts:89). Most commands that touch the repo accept --repo-dir (e.g. datastore setup). agent setup uses resolveRepoDir(undefined) without exposing the flag, so users running from outside the repo root must cd first. Low priority since this is an interactive wizard, but it's an inconsistency.

Verdict

PASS. The --tool help text update is clear, the ToolResolver error (Unknown tool "X". Available tools: …. Run \swamp agent setup` to define a custom tool.) is actionable, and both JSON and log modes work correctly for agent listandagent rm`. No blocking issues.

[github-actions]

Adversarial Review

Critical / High

None found. The new architecture is well-structured: ToolResolver with injected CustomToolLoader avoids domain→infrastructure import violations, path traversal is checked at scaffolding time via assertPathContained, YAML deserialization is validated through toDefinition with field-level checks, and the exhaustive builtInToolConfig switch keeps the AiTool union closed for built-in tools.

Medium

1. resolveSkillsDir (skill_dirs.ts:44-49) doesn't know about custom tools → wrong extensionsToReinstall advisory during upgrade.
   repo_service.ts:327 calls resolveSkillsDir(repoPath.value, oldPrimary) to find pulled extensions. When oldPrimary is a custom tool (e.g., "windsurf"), resolveSkillsDir falls through to .swamp/pulled-extensions/skills/ instead of the custom tool's actual skills dir (e.g., .windsurf/skills/). Same for repo_service.ts:348. This means listPulledExtensions scans the wrong directory and extensionsToReinstall is incorrect.
   Breaking example: User runs swamp repo init --tool windsurf, pulls extensions, then runs swamp repo upgrade --tool windsurf --tool kiro. The upgrade won't detect pulled extensions in .windsurf/skills/ and won't advise reinstalling them for kiro.
   Suggested fix: Use ToolResolver (or ToolConfig) in the upgrade path to resolve the old primary's skills dir, rather than the static SKILL_DIRS map.

2. Case-sensitive duplicate check in addCustomTool allows filesystem collisions.
   custom_tools_repository.ts:123 checks t.name === tool.name (exact match), but validateCustomToolName (custom_tool.ts:66) checks built-in conflicts case-insensitively (name.toLowerCase()). A user can add both "Windsurf" and "windsurf" as separate custom tools. Both would scaffold to .Windsurf/skills/ and .windsurf/skills/ respectively — which collide on case-insensitive filesystems (macOS HFS+, Windows NTFS).
   Suggested fix: Lowercase-normalize in the addCustomTool duplicate check, or in validateCustomToolName reject names that differ only by case from existing entries.

3. No path traversal validation at tool definition time.
   agent_setup.ts:221 calls addCustomTool(repoDir, def) without checking assertPathContained on the user-supplied instructionsPath or chosenSkillsDir. The traversal check only runs later in applyToolScaffolding (repo_service.ts:452-460). A user could type ../../etc/foo as the skills dir during the wizard, and the invalid definition would be saved to .swamp-custom-tools.yaml. They'd only discover the error later when running swamp repo init --tool <name>.
   Suggested fix: Call assertPathContained in the agentSetupCommand action before addCustomTool, so the wizard rejects traversal paths immediately.

Low

1. promptLine fixed 1024-byte buffer (agent_setup.ts:48-51). Input longer than 1024 bytes is silently truncated. Extremely unlikely in practice (paths are short), but a readAll pattern would be more robust.

2. Tab completion omits custom tools (repo_init.ts:47-49). ToolNameType.complete() only returns built-in names. Custom tools defined via swamp agent setup won't appear in shell completions. A future enhancement could read .swamp-custom-tools.yaml in complete().

Verdict

PASS — The core architecture is solid: DDD boundaries are respected, the ToolResolver abstraction is clean, path traversal is caught at use-time, YAML validation is thorough, and the built-in/custom tool distinction is well-modeled. The medium findings are real but low-impact (advisory messages, UX friction, filesystem edge case). None cause data loss, corruption, or security vulnerabilities. Ship it and address the mediums in a follow-up.