| name | swamp-getting-started |
| description | Interactive getting-started walkthrough for new swamp users. Guides through understanding the user's goals, creating and running a first model, inspecting output, and choosing next steps. Uses a state-machine checklist with verification at each step. Triggers on "getting started", "get started", "new to swamp", "first time", "tutorial", "walkthrough", "onboarding", "how do I start", "what do I do first", "quickstart", "quick start", "hello world", "first model", "just installed swamp", "show me how swamp works", "intro to swamp", "new user", "set up swamp", "learn swamp".
|
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.
If the command fails, 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
swamp skill (extension
guide). Use command/shell only 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.
