Getting Started with Swamp
A state machine. Each state gates the next — do not advance until the current
state's Verify passes. If Verify fails, run On Failure and re-verify. If
unsure a subcommand or flag exists, run swamp <command> --help rather than
guessing.
start → goals_understood → model_created → method_run → output_inspected → graduated
Before Starting
Run swamp model search --json. If it returns models, the user is past
onboarding — say so and stop:
You already have models set up. You're past the getting-started stage — just tell me what you'd like to work on and I'll use the right skill.
Every swamp command needs a swamp-club.com account. If the command fails with
code auth_gate_blocked, have the user run swamp auth login (it opens a
browser sign-in; they finish it themselves), confirm with
swamp auth whoami --json, then rerun the search. In CI, the user sets
SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN from a collective token instead.
If the command fails for another reason, surface the error and suggest
swamp repo init (use the swamp skill for guidance), then return here. If no
models exist, present the 5-step checklist (Goals → Create → Run → Inspect →
Graduate) and begin State 1.
State 1: goals_understood
Gate: None (first state).
Action: Ask what they want to automate, in their own words (not by implementation type). Tell them they can skip if they already know swamp.
Early exit: If they describe a task with swamp terminology (e.g., "create a
model for X", "set up a workflow"), skip ahead and delegate directly to the
swamp skill — its routing table will load the right guide.
Verify: The user described a goal. Then find a model type:
swamp extension search <keywords> --json— prefer@swamp/*official extensions first- If an extension matches:
swamp extension pull <package> swamp model type search <keywords> --json— check local/installed types- Extend an existing type if it covers the domain but lacks the method you need
- If nothing exists, offer a custom extension via the
swampskill (extension guide). Usecommand/shellonly for genuine one-off ad-hoc commands.
Store the goal — use it to name the model and tailor later examples.
On Failure: If the user is unsure, default to a command/shell model — no
credentials needed, demonstrates the full lifecycle.
State 2: model_created
Gate: State 1 passed.
Action: Follow the resolution flow in
references/tracks.md. Pick a name from the goal (e.g.,
"check disk space" → check-disk-space). Pattern:
- Find or install the model type
swamp model create <type> <name> --json- Edit the YAML to match the goal
Verify: swamp model validate <name> --json passes with no errors. Show
warnings to the user.
On Failure: See "On Failure Recovery → State 2" in references/tracks.md.
State 3: method_run
Gate: State 2 passed.
Action: Tell the user what's about to happen, then run
swamp model method run <name> <method>. Pick <method>:
command/shell:execute- Local typed: a read-only method first (
sync,get) - Extension: check
swamp model type describe <type> --compact --json
Verify: The run completes with succeeded.
On Failure: See "On Failure Recovery → State 3" in references/tracks.md. Re-run and re-verify.
State 4: output_inspected
Gate: State 3 passed.
Action: swamp model output get <name> --json.
Verify: Output data is returned. Present to the user, highlighting status, captured artifacts, datastore path, and the CEL reference path for wiring into other models — see references/tracks.md for the CEL pattern.
On Failure: See "On Failure Recovery → State 4" in references/tracks.md.
State 5: graduated
Gate: State 4 passed.
Action: Summarize what they built. Suggest 2-3 concrete next steps tied to their goal (e.g., "store your AWS credentials in a vault" — not "use the vault skill"). Ask which they want, then delegate with full context. See the Delegation Map in references/tracks.md.
References
references/tracks.md — model type resolution, credential setup, method selection, CEL patterns, On Failure recovery per state, delegation map.
