Lab #2931: gatorwalk-factory skill: an interactive getting-started walkthrough for a first factory, modelled on swamp-getting-started

Make the first factory a guided, interactive walkthrough, borrowing the approach of swamp's getting-started skill (~/sc/swamp/.claude/skills/swamp-getting-started/SKILL.md, plus its references/ and evals/).

Why

Direction from Seth and Paul (2026-10-01) for the first release. Creating a first factory should feel like swamp's onboarding: guided, verified at each step, and tailored to what the person wants to do.

The authoring skill (#2818, references/authoring.md) already interviews, starts from an example with init --from, validates, and shows the factory in the studio (#2839). But it reads as an authoring reference for an agent, not as a walkthrough for a new person.

The product is a factory maker. You use it to build your own factories, where agents do the work or drive a process. A factory can be for software, web posts, incident reviews, swamp models or extensions, or anything else that can be expressed as stages that produce artifacts and evidence, with gates that set the rules for moving between stages. Inside a stage, the work can be anything, including calling a swamp model or workflow. The walkthrough should make that breadth clear and start from the person's own goal.

What to borrow from swamp-getting-started

A state machine. Each state gates the next. Don't advance until the state's Verify passes, and each state has an On Failure step that leads back to Verify.
A visible checklist of the steps, presented at the start.
"Before starting" detects whether the person is already past onboarding (for example, a factory model exists) and hands off to the normal authoring and driving guidance.
Goals in the person's own words, not implementation terms, with an early exit when they already speak in gatorwalk's terms.
Graduation ends with clear next steps.
Triggers on getting-started phrasing for factories: "set up a factory", "get started with gatorwalk", "first factory", "automate our review process with agents", and the like. Keep the skill's description precise so it doesn't steal swamp's own getting-started triggers.

A starting shape (the implementer decides the details)

start → goal_understood → factory_created → validated → seen_in_studio → simulated → first_work_item → graduated

State	What happens
goal_understood	What process do they want, who are the people, where do humans decide, and what counts as done? Map the answers to stages, products and gates, and pick the closest example.
factory_created	`init --from <example>`, then adapt it to the goal. Verify that the factory model exists and holds a definition (#2884).
validated	`validate` reports no errors. Explain each warning in plain words, then fix it or accept it with the person.
seen_in_studio	Start the studio (#2806), walk through the factory, and take change requests, including Copy reference lines (#2807).
simulated	Write or run a saved scenario (#2805), or walk it in Simulate (#2808), so the person sees work move through it.
first_work_item	Optionally, start one on the built-in tracker and drive it to its first human stop, laid out as #2782 does it.
graduated	Next steps: changing the factory, connecting Linear, writing scenarios, driving work.

Scope

Where it lives. A getting-started reference, or a section of references/authoring.md that SKILL.md routes to for a first factory. Say which and why. Don't duplicate authoring rules; link to them.
Examples. Check the examples in references/examples/ against the breadth above. If they are all software-shaped, decide whether the first release needs one non-software example, for example a content review or incident review. Propose it rather than adding many.
Evals. Add one or two cases for the walkthrough to the eval suite in #2912, if it has landed. Otherwise say what the cases should be. swamp-getting-started has its own evals/ to learn from.

Done when

A fresh agent in a new repo, given only "I want to set up a factory for ", walks a person through the states with a Verify at each step, and ends with a validated factory seen in the studio.
Record that run's transcript in the PR as acceptance evidence.
integration/extension/skill_test.ts passes for every command in the new text.

Out of scope:

the final name (decided separately; write against the current name);
new engine features;
the README and the publishing preparation.

Session-start 'swamp model search --json' in the AGENTS.md template is unfulfillable - wire it to a hook or drop it

Flaky property test: analyzeExpression dot/bracket agreement fails when the generated model name is a CEL keyword

Accept usernames for user subjects in grant files

Docs: enable-managed-config should say to re-run config migrate when its push fails

Docs: grant file reference shows a stale format and omits resources and subjects

Flaky property test: analyzeExpression hyphenated dot access fails when modelName generates a CEL keyword ("in")

extension quality and push crash with IsADirectory when additionalFiles lists a directory

extension push: a required global argument renders with a stray "" ("text": "string""")

Docs: extension publishing reference is stale on bare specifiers, quality output and fmt config (swamp-club#3022)

swamp-extensions: replace bare import specifiers with npm:/jsr: specifiers in first-party extensions

extension push: 'Requested visibility' line prints to stdout without the logger prefix, twice per run

A nested structural swamp that outlives the run that started it keeps skipping that run's lock while the holder writes

Show signal waits to remote clients and the dashboard

Settle expired signal waits from swamp serve

Resume signalled workflow runs automatically under swamp serve

extension push/quality: structured acceptances for agents, a clearer title than For next time, and an optional reason

extension push: the undecided private-entitlement verdict still says the registry may start a trial at publish

seed:collective cannot produce a superseded personal trial or a returned trial, so the UAT cannot cover them

Replayable state fragments: Git-reviewable desired state for resources changed by model methods

extension push: registry metadata and content hash label files relative to the repo dir, so a push with --extensions-dir records ../ paths

registry: store and show declared acceptances sent in contentMetadata.acceptances at confirm (swamp-club#3021)

extension push --dry-run: authentication verdict prints 'Signed in as .' when the credential is an API key with no username

serve --remote-only: step output from workers is never persisted to the run log (history logs always empty)

serve HA: worker enrollment on a replica that lacks the enrollment token's definition may create a second definition (unverified)

serve HA: pull a token's definition on an auth miss so a peer accepts a new token at once

extension push: version-drift check reports 'no previously published version found' when the registry call failed

Search and list output follows directory iteration order in the definition, workflow, vault and output repositories

extension push: accept attestation-backed adversarial-review evidence (lookup by extension and content hash), generated provenance, and carry the evidence to the registry at confirm (design: Lab #3023)

Workflow load errors print the raw Zod issue dump instead of a readable message

Decide a stricter naming rule for workflow step and job names

serve: run scheduled workflows concurrently (per-workflow serialization), and report queue delay

Show expired approval gates as expired, with a Cancel action in the dashboard

digitalocean codegen leaves an orphaned security_secret.ts model file after its endpoint left the spec

extension promote accepts a yanked version and reports it promoted

Docs: doctor install reports a stale or failing autoupdate scheduler

extension push output: double-quoted adjacent interpolations, repo-relative paths, and --json emits three JSON documents

auto-resolve: the Installing line prints the extension's entire multi-line description

s3-datastore/serve: readResource without a version returns an older version; the latest marker is rewritten backwards

Publish agent-facing projections of the manual: /llms.txt, .md pages, and llms-full.txt

Let agent-runner drive more agent CLIs (Kilo Code and others)

s3-datastore: every fast-path miss re-downloads every _index shard, so a busy serve pulls the whole index every poll (~230 GB/day S3 egress)

Feedback: Swamp as an approval-gated control plane for a small fleet

extension safety analyzer's Deno.Command( warning is a plain substring match

Tell timeouts apart from cancels in method-run records, and review the hidden 30 s fallback timer for step-called model methods

Run from a git worktree: definitions from the worktree, state from the shared repo

S3/GCS datastore: a push that fails after uploading drops its recorded deletes, so the retry brings deleted data back

Tests: bring the in-memory remote's default semantics up to @swamp/s3-datastore and @swamp/gcs-datastore 2026.10.01.1

Tell the pushing client when its extension contentMetadata fails validation

Extension datastore: query still returns an item after its delete is pulled

Cancel, reject and supersede of a parent run should settle its suspended nested child runs

Tracking: test baseline required before the datastore refactor (commit-log design)

Tests: serve pollers make a peer's writes, deletes and grants visible with a real catalog (before Phase 5)

datastore setup can overwrite an existing remote config tier when it moves an in-repo tier into an extension datastore

serve: define and supply the collective and owner grant condition variables

No first-class workflow primitive for spawning a permission-scoped agent session

A pulled extension can shadow a built-in type, and removing it leaves serve without the built-in

Decorative animations outside the Lab still repaint on the main thread

s3/gcs datastore: pullChanged overwrites dirty, unpushed cache files

Concurrent first runs in a fresh repo log 'Catalog migration to per-extension-aggregate-v3 failed (database is locked)'

Codegen/DigitalOcean: create-only required fields block list/get/delete in generated DigitalOcean models

Codegen/AWS: create-only required fields block list/get/delete in generated AWS models

End a collective's trial when it begins a paid subscription

A collective that cancels inside its 30-day trial window regains trial access to private extensions

s3-datastore: SWAMP_S3_REQUEST_TIMEOUT_MS does not appear to apply to ListObjectsV2 during pull

s3-datastore: S3Lock.acquire overshoots maxWaitMs by up to a full backoff interval

s3-datastore: a model-scoped pull still lists, walks and indexes the whole namespace

Run the web dashboard locally from the CLI without swamp serve

verify-reviews: adversarial review path guard is a hand-kept list, so new extensions silently skip it

Relationships

#2931 gatorwalk-factory skill: an interactive getting-started walkthrough for a first factory, modelled on swamp-getting-started

Why

What to borrow from swamp-getting-started

A starting shape (the implementer decides the details)

Scope

Done when

Shipped