Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72

Relationships

#2071 Expose swamp help to agents proactively in the swamp skill

Opened by stack72 · 9/8/2026· Shipped 9/9/2026

Problem

Agents using the swamp skill hallucinate CLI flags because the skill only tells them to run swamp help <command> as a fallback ("if unsure about exact flags"). Agents never think they're unsure — they confidently guess wrong flags and fail.

swamp help outputs structured JSON (the full CLI schema tree), which is exactly what an agent needs to construct correct commands. But this is buried as an afterthought in individual guides and missing entirely from the main workflow and AGENTS.md.

Proposed Changes

1. SKILL.md Workflow — add a verify step

Insert a step between Validate (3) and Execute (4):

Verify args — run swamp help <subcommand> to confirm exact flags, arguments, and options before executing.

This is the main loop every agent follows, so it's the highest-value fix.

2. AGENTS.md Commands section — mention swamp help

Add that swamp help outputs machine-readable JSON and is the canonical way for agents to discover CLI args. This covers agents that don't trigger the swamp skill (e.g. subagents, fresh contexts).

3. Per-guide "Verify CLI syntax" lines — change "If unsure" to "Always"

Every guide currently says:

"If unsure about exact flags or subcommands, run swamp help <command>..."

Change to unconditional ("Always verify...") or remove per-guide lines entirely once the workflow step covers it.

4. Inconsistent --help references — standardize to swamp help

references/report/guide.md and references/model/reference.md reference swamp <cmd> --help (human-readable ANSI output) instead of swamp help <cmd> (structured JSON). Standardize to the JSON variant for agent consumption.

02Bog Flow
OPENTRIAGEDIN PROGRESSSHIPPED+ 1 MOREASSIGNED+ 3 MOREREVIEW+ 19 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

9/9/2026, 12:20:23 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack729/8/2026, 10:16:25 PM

Sign in to post a ripple.