systeminit · stack72 · Jan 28, 2026 · Jan 28, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -34,12 +34,14 @@ Use `deno run` to get a complete list of custom tasks.
 - Uses LogTape for logging
 - Uses JSON for non-interactive output
 - Every command _must_ support both interactive and non-interactive output
+- You can read the files in `design/*.md` to understand elements of the design
 
 ## Testing
 
 - Unit tests live next to source files: `foo.ts` → `foo_test.ts`
 - Integration tests live in `integration/` directory (sibling to `src/`)
-- Use `@std/assert` for assertions (`assertEquals`, `assertStringIncludes`, etc.)
+- Use `@std/assert` for assertions (`assertEquals`, `assertStringIncludes`,
+  etc.)
 - Use `ink-testing-library` for testing Ink components
 - Test private functions indirectly through public APIs
 - Run tests with `deno task test`
diff --git a/deno.json b/deno.json
@@ -13,6 +13,8 @@
     "@std/assert": "jsr:@std/assert@1",
     "@std/fs": "jsr:@std/fs@1",
     "@std/path": "jsr:@std/path@1",
+    "@std/yaml": "jsr:@std/yaml@1",
+    "zod": "npm:zod@3",
     "@cliffy/command": "jsr:@cliffy/[email protected]",
     "@logtape/logtape": "jsr:@logtape/[email protected]",
     "ink": "npm:ink@5",

diff --git a/deno.lock b/deno.lock
diff --git a/design/high-level.md b/design/high-level.md
@@ -0,0 +1,25 @@
+# Swamp
+
+## Purpose
+
+Swamp is an AI Native Automation tool. It has 1:1 models of external APIs or CLI
+tools (for example, AWS or Azure cloud resources, or the GitHub CLI), which it
+can then validate are correct. Each model has a Type, which specifies some
+metadata about the model, input data that is specified, methods that take the
+input data and produce outputs of either more model inputs or resources (which
+are specified by each model as well.) Model inputs and resources are stored as
+separate YAML files in a 'inputs' or 'resources' directory. Model inputs have a
+simple expression language (like github actions) for inserting data.
+
+Swamp also has workflows, which allow for executing workflow steps in parallel
+groups. A workflow step can be a method on a model, or an external script.
+
+Swamp allows for organizing model inputs and resources into applications and
+environments, which can be used to compare resources and inputs to detect
+configuration drift.
+
+All this is stored in a 'swamp repo', which is a git repository.
+
+## Models
+
+See [./models.md].
diff --git a/design/models.md b/design/models.md
@@ -0,0 +1,90 @@
+# Models
+
+A model in swamp specifies _inputs_, that are passed to _methods_, that produce
+_outputs_, which may be _model inputs_ or _resources_.
+
+## Type
+
+All models in swamp are of a unique _type_. Types are defined by the thing that
+they model - for example, a swamp model to manage AWS VPCs using the Cloud
+Control API would be named 'AWS::EC2::VPC', because that is what the cloud
+control api calls it. They should map semantically to the domain.
+
+They _must_ include a domain identifier at the start of the type. For example:
+
+AWS: AWS::EC2::VPC, AWS::Budget::Budgets Docker CLI: docker run, docker pull
+Azure: Microsoft.Resources/resourceGroup
+
+Each type also has a normalized representation, where special characters are
+mapped into directory structures like 'aws/ec2/vpc' or 'docker/run' or
+'microsoft/resources/resourceGroup'.
+
+## ID
+
+Each instance of a model has a unique ID that is a uuidv4.
+
+## Version
+
+Each model has a version number, starting with 1. Models must support data
+written by all earlier versions, but not later versions.
+
+For example, a model '4' can read data from version 1-4, but not '5'.
+
+## Migration
+
+A model can migrate its inputs and resources from one version to the next.
+
+## Inputs
+
+Inputs are specified as YAML files that live in the /inputs directory of a
+repository, underneath the normalized type as a directory. The file name is
+'${id}.yaml'. For example,
+'aws/ec2/vpc/input-fc7fd41e-ae16-4b31-b57a-86de716e3ece.yaml'.
+
+The valid shape of an input is specified with a Zod 4 schema.
+
+Each input has the following core properties:
+
+- id: the models unqiue id
+- resourceId: an optional resource id, if one exists
+- name: a unique human readable name
+- tags: string based key value pairs
+- attributes: domain specific data for the input (for example, the model of a
+  VPC from above).
+
+## Methods
+
+Are named functions that take the model as an input, and produce other model
+inputs or resources as outputs.
+
+The method should use a MethodInput zod schema to validate that any specific
+inputs it needs are present in the input model.
+
+## Resources
+
+Resources are specified as YAML files that live in the /resources directory of a
+repository, underneath the normalized type as a directory. The file name is
+'${id}.yaml'. For example,
+'aws/ec2/vpc/resource-fc7fd41e-ae16-4b31-b57a-86de716e3ece.yaml'.
+
+The valid shape of a resource is specified with a Zod 4 schema.
+
+## CLI Commands
+
+### model create <type> <name>
+
+Creates a new instance of a type with the given unqiue name. Type should accept
+either the domain specific type or the normalized type. It should return the id
+and path to the model that is created.
+
+### model get <model_id_or_name>
+
+Shows the models input, schema, resource, methods, etc.
+
+### model validate <model_id_or_name>
+
+Runs the models zod validations for the models inputs and resources. Run them in parallel and print the output as it comes.
+
+### model method run <model_id_or_name> <method_name>
+
+Runs a method for the given model.
diff --git a/inputs/swamp/echo/4062501b-7b72-475e-8235-9d780fec4e18.yaml b/inputs/swamp/echo/4062501b-7b72-475e-8235-9d780fec4e18.yaml
@@ -0,0 +1,5 @@
+id: 4062501b-7b72-475e-8235-9d780fec4e18
+name: test-name
+version: 1
+tags: {}
+attributes: {}