Swamp Adoption
Guides new users through mapping their domain onto swamp primitives. Conducts structured discovery interviews, produces versioned extension designs, and generates implementation scaffolds.
Uses swamp to teach swamp — the adoption journey itself is modeled as typed, versioned state.
2026.10.14.2
Added: scaffold takes an optional license argument: an SPDX expression
such as Apache-2.0, MIT, or MIT OR Apache-2.0. When given, the scaffolded
manifest.yaml declares license: <spdx> directly after name:, lists
LICENSE.md under additionalFiles:, and the generated LICENSE.md is a
placeholder (identifier, copyright line, link to spdx.org) that you replace
with the full license text. The generated mod.ts header carries the same
SPDX identifier. Ids come from a short allow-list of common licenses in exact
SPDX case; LicenseRef-* and unrecognised ids are rejected.
Changed: There is no default license. Without license, the scaffold logs
a warning and emits no license: line and no LICENSE.md, so the result scores
below 100% on swamp extension quality until you add them. The generated
mod.ts no longer hard-codes // SPDX-License-Identifier: Apache-2.0; the
header appears only when you pass license.
Upgrade note: No schema changes. Existing stored scaffold data is unaffected.
| Argument | Type | Description |
|---|---|---|
| system? | string | Target system name from landscape (uses suggestedFirstExtension if omitted) |
| Argument | Type | Description |
|---|---|---|
| sourceSkill? | string | Name or path of the skill being converted (e.g., .claude/skills/foo/SKILL.md) |
| Argument | Type | Description |
|---|---|---|
| outputFormat? | enum | Whether to write files as a resource or print to stdout |
| license? | string | SPDX license expression for the generated extension (e.g. |
Resources
2026.10.14.1
Fixed: The scaffold method failed on current swamp with
Data name 'latest' is reserved for internal use.
Changed: The scaffold result is now written as scaffold-current instead of
latest. Anything that read data.latest("<model>", "latest") or queried
name == "latest" must use the new name.
Upgrade note: Data stored under latest is not migrated; re-run the method
to populate scaffold-current. No attribute schemas changed.
Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.
2026.09.30.1
Changed: Scaffolded deno.json files now pin
jsr:@swamp-club/swamp-testing@0.20260928.39 (was 0.20260917.35), so new
extensions generated by the adoption flow start on the same testing SDK
release as the rest of the repository. No change to methods, resources, or
schemas.
Upgrade note: No schema change. A no-op upgrade-chain entry is appended so
existing instances advance their typeVersion on the next method call.
2026.09.19.1
Changed: Scaffolded deno.json files now import the testing SDK from
@swamp-club/swamp-testing instead of the deprecated @systeminit/swamp-testing
scope, matching the current swamp core package. New extensions generated by the
adoption flow pin jsr:@swamp-club/swamp-testing@0.20260917.35.
Upgrade note: No schema change. A no-op upgrade-chain entry is appended so
existing instances advance their typeVersion on the next method call.
2026.09.18.1
Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the
repo. No behavioral changes in this extension.
2026.09.15.1
Changed: Bump zod 4.4.3 → 4.6.5
2026.08.28.1
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.28.1
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.26.1
Fixed: Added missing description field to upgrade entry for version
2026.08.24.2. The omission caused swamp extension pull to fail with a catalog
validation error ("upgrades.N.description: Invalid input: expected string,
received undefined").
2026.08.24.3
Added: Output metadata attributes for observability.
durationMs: Method execution duration in milliseconds.collectedBy: Extension name that produced the data.fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).
2026.08.24.2
Added Troubleshooting section documenting design system requirement, scaffold prerequisite, import_skill partial-write handling, and array global arg CLI syntax.
2026.08.21.2
Changed: design and import_skill no longer silently substitute a
placeholder name when a required identifier is missing. Previously, running
design with no system argument and no prior discover landscape wrote an
extension design named unknown-system with no indication anything was
wrong; running import_skill with no sourceSkill did the same with
unknown-skill. Both methods now throw a descriptive error telling you what
to provide (system, or run discover first; sourceSkill, a name or
path) instead of producing a resource that looks legitimate but points at
nothing.
Upgrade note: No schema changes. If you were relying on the
unknown-system/unknown-skill fallback behavior, pass the argument
explicitly going forward.
2026.08.21.1
Changed: Added .describe() to previously undocumented fields on the
InteractionSchema, SystemSchema, DataFlowSchema, and LandscapeSchema
resource schemas (e.g. verb, direction, frequency, pain, type,
from, to, manual, suggestedFirstExtension). No behavioral change.
2026.08.01.1
Added: New import_skill method. If you already have a skill (SKILL.md
or similar agent instructions) that you're trying to formalize into a swamp
extension, this method converts it directly — seeding both landscape and
extensionDesign from the skill's structure instead of running a full systems
interview. scaffold and next work unchanged from either path.
Changed: discover's interview now opens with a phase 0 question asking
whether you have an existing skill to convert. Answering yes routes to
import_skill and skips the systems interview; answering no continues as
before. Existing discover behavior for users starting from scratch is
unchanged.
Fixed: scaffold no longer splices the extension design's name field
into generated files unescaped. A design name containing a newline or a
double quote (reachable via design's free-text system argument, and now
also via import_skill's skill-path-derived name) could break out of the
quoted name: line in the generated manifest.yaml and inject arbitrary
YAML, or break the generated mod.ts/mod_test.ts string literals. The name
is now sanitized the same way the description field already was.
Upgrade note: No globalArguments changes — this is an additive method
only. Existing adoption model instances upgrade with a no-op transform.
2026.08.21.1
Changed: Added .describe() to previously undocumented fields on the
InteractionSchema, SystemSchema, DataFlowSchema, and LandscapeSchema
resource schemas (e.g. verb, direction, frequency, pain, type,
from, to, manual, suggestedFirstExtension). No behavioral change.
2026.08.01.1
Added: New import_skill method. If you already have a skill (SKILL.md
or similar agent instructions) that you're trying to formalize into a swamp
extension, this method converts it directly — seeding both landscape and
extensionDesign from the skill's structure instead of running a full systems
interview. scaffold and next work unchanged from either path.
Changed: discover's interview now opens with a phase 0 question asking
whether you have an existing skill to convert. Answering yes routes to
import_skill and skips the systems interview; answering no continues as
before. Existing discover behavior for users starting from scratch is
unchanged.
Fixed: scaffold no longer splices the extension design's name field
into generated files unescaped. A design name containing a newline or a
double quote (reachable via design's free-text system argument, and now
also via import_skill's skill-path-derived name) could break out of the
quoted name: line in the generated manifest.yaml and inject arbitrary
YAML, or break the generated mod.ts/mod_test.ts string literals. The name
is now sanitized the same way the description field already was.
Upgrade note: No globalArguments changes — this is an additive method
only. Existing adoption model instances upgrade with a no-op transform.
2026.08.01.1
Added: New import_skill method. If you already have a skill (SKILL.md
or similar agent instructions) that you're trying to formalize into a swamp
extension, this method converts it directly — seeding both landscape and
extensionDesign from the skill's structure instead of running a full systems
interview. scaffold and next work unchanged from either path.
Changed: discover's interview now opens with a phase 0 question asking
whether you have an existing skill to convert. Answering yes routes to
import_skill and skips the systems interview; answering no continues as
before. Existing discover behavior for users starting from scratch is
unchanged.
Fixed: scaffold no longer splices the extension design's name field
into generated files unescaped. A design name containing a newline or a
double quote (reachable via design's free-text system argument, and now
also via import_skill's skill-path-derived name) could break out of the
quoted name: line in the generated manifest.yaml and inject arbitrary
YAML, or break the generated mod.ts/mod_test.ts string literals. The name
is now sanitized the same way the description field already was.
Upgrade note: No globalArguments changes — this is an additive method
only. Existing adoption model instances upgrade with a no-op transform.
Modified 1 behaviors
2026.07.26.1
Changed: Extensions scaffolded by this model now pin
@systeminit/swamp-testing at 0.20260604.20, the current release, instead of
0.20260504.10. The old pin was hard-coded in the generated deno.json, so every
extension created through the adoption workflow started life on a test library
that was three releases behind and inconsistent with the rest of the repo.
Upgrade note: Nothing to do for extensions already scaffolded — they keep the
pin they were created with. Update their deno.json and regenerate deno.lock
with deno install if you want them on the current version.
2026.07.18.2
Added: An upgrades array entry (no-op) to mod.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.
2026.07.18.1
Changed: Added @module-level JSDoc documentation to mod.ts. No
runtime behavior change.
2026.07.18.1
Changed: Added @module-level JSDoc documentation to mod.ts. No
runtime behavior change.
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned