Genesis
Swift CLI that bootstraps DDD / Event-Sourcing projects from an Event Storming bundle, plus Claude Code skills for the parts that need domain judgment.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/abner-tungchi--genesis)HTML
<a href="/listings/abner-tungchi--genesis"><img src="/api/listings/abner-tungchi--genesis/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# User-global (default) — installs into ~/.claude/skills/ genesis install-skills # Per-project genesis install-skills --scope project --project-dir ./my-project # Overwrite existing skills genesis install-skills --force # Remove the bundled skills again — keeps any skill you've hand-edited (unless --force) genesis uninstall-skills
On a user-scope install, set `GENESIS_WORKSPACE_DIR` to a directory containing your projects and Genesis will warn about project-local copies of the skills that would shadow the global install.
| Skill | Role | |-------|------| | `event-storming` | Model a domain on an Event Storming canvas | | `write-ddd-spec` / `bundle-plan` | Turn a bundle into per-use-case contract-first task specs | | `usecase` | Fill the domain `Usecase.execute()` orchestration body (Create / Update / Delete patterns) | | `api` | Fill the write-side `ApplicationService` + `ApiHandler` bodies | | `readmodel` / `presenter` | Scaffold read models + presenters | | `readmodel-mutation` / `presenter-fill` | Fill read-side projector `when()` + read application-service bodies | | `test-gen` | Emit **enabled-red** Swift Testing tests; two-file split (machine `.generated` + human `.authored`) | | `domain-fill` | Transcription-only: dictate domain logic, the skill writes it into the entity-layer `GenesisTODO.notImplemented` holes (never drafts logic itself) | | `strict-review` | Review pass |
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 198 lines
- # Genesis
- A Swift CLI that bootstraps Swift DDD / Event-Sourcing projects from an Event Storming bundle (JSON), plus a set of Claude Code skills that fill in the parts that need human domain judgment.
- ## What Genesis does
- Genesis bridges the gap between a **business model** (an Event Storming canvas exported as a bundle JSON) and a **working Swift DDD/ES project**. It generates the mechanical scaffolding — aggregates, events, repositories, use-case ports, adapters, test fixtures, business-doc skeletons — as a **scaffold-emitter**: everything mechanically derivable from the bundle is generated, and everything that needs human domain judgment (invariant predicates, command business rules, non-trivial state transitions) is left as a runtime `throw GenesisTODO.notImplemented(...)` hole.
- Genesis is **TDD-first**: a freshly generated project **compiles** (the holes are runtime throw-markers, not compile-time `#error`), but the test for each unfilled feature is **red** until you fill it — write the test, watch it go red, implement, watch it go green, one feature at a time. `grep GenesisTODO.notImplemented` is the honest, greppable to-do list; **`genesis verify`** is the release/CI gate (no unfilled holes; every declared invariant has an enabled test).
- Generated projects build on the public [swift-ddd-kit](https://github.com/gradyzhuo/swift-ddd-kit) package (`DDDKit`, `TestUtility`, and the `ModelGeneratorPlugin` / `DomainEventGeneratorPlugin` build plugins).
- ## A worked example: a library lending system
- Say you modelled a small library on an Event Storming canvas. The bundle describes one bounded context, `LMSContext`, with a `Member` aggregate and use cases such as `createMember`, `borrowBook`, `returnBook`, `transferBranch` and `upgradeMembership`, each emitting a domain event (`memberCreated`, `bookBorrowed`, ...), plus a read model `GetMemberLoanSummary`.
- ```bash
- # 1. Build Genesis
- git clone <this-repo-url> && cd Genesis
- swift build -c release # binary: .build/release/genesis
- # 2. Generate the project from the bundle (run it in a clean git work tree, or pass --no-git)
- mkdir ~/lms && cd ~/lms && git init
- /path/to/Genesis/.build/release/genesis new LMSContext --from-bundle ./bundle.json
- # 3. The project compiles, but the tests for unfilled features are red
- swift build
- swift test # red: borrowBook, returnBook, ... are still GenesisTODO holes
- genesis verify # exit 2 while holes remain
- # 4. Fill the holes (Claude Code skills), then re-run the gate
- genesis install-skills
- # /usecase borrowBook -> orchestration body
- # /api borrowBook -> ApplicationService + ApiHandler bodies
- # /domain-fill -> transcribe the domain rules you dictate (e.g. "a member may hold at most 5 books")
- # /test-gen borrowBook -> enabled-red Swift Testing tests
- genesis verify # exit 0 when everything is filled and tested
- ```
- Requires Swift 6.0+ (macOS 13+) — generated projects use Swift Testing and SwiftPM tools 6.0.
- ## Usage
- ### Bootstrap a project
- ```bash
- # Minimal — uses built-in defaults
- genesis new LMSContext --from-bundle ./bundle.json
- # With an adapter to override type mapping / ID strategy / etc.
- genesis new LMSContext --from-bundle ./bundle.json --adapter ./swift-adapter.yaml
- # Into a specific directory
- genesis new LMSContext --from-bundle ./bundle.json --output ./my-project
- ```
- | Flag | Purpose |
- |------|---------|
- | `--from-bundle <path>` | Event Storming bundle JSON (required) |
- | `--adapter <path>` | `swift-adapter.yaml` to override defaults (optional) |
- | `--output <dir>` | Output directory (default: current directory) |
- | `--no-git` | Skip the git pre-flight check (for CI / sandboxes) |
- | `--skip-build` | Skip the post-generation `swift build` (resolve still runs) |
- `genesis new` runs a git pre-flight (the output dir must be a clean git work tree, unless `--no-git`), generates the project, runs `swift package resolve`, and then (unless `--skip-build`) `swift build`. On failure it rolls back everything it wrote.
- ### Install Claude Code skills
- ```bash
- # User-global (default) — installs into ~/.claude/skills/
- genesis install-skills
- # Per-project
- genesis install-skills --scope project --project-dir ./my-project
- # Overwrite existing skills
- genesis install-skills --force
- # Remove the bundled skills again — keeps any skill you've hand-edited (unless --force)
- genesis uninstall-skills
- ```
- On a user-scope install, set `GENESIS_WORKSPACE_DIR` to a directory containing your projects and Genesis will warn about project-local copies of the skills that would shadow the global install.
- | Skill | Role |
- |-------|------|
- | `event-storming` | Model a domain on an Event Storming canvas |
- | `write-ddd-spec` / `bundle-plan` | Turn a bundle into per-use-case contract-first task specs |
- | `usecase` | Fill the domain `Usecase.execute()` orchestration body (Create / Update / Delete patterns) |
- | `api` | Fill the write-side `ApplicationService` + `ApiHandler` bodies |
- | `readmodel` / `presenter` | Scaffold read models + presenters |
- | `readmodel-mutation` / `presenter-fill` | Fill read-side projector `when()` + read application-service bodies |
- | `test-gen` | Emit **enabled-red** Swift Testing tests; two-file split (machine `.generated` + human `.authored`) |
- | `domain-fill` | Transcription-only: dictate domain logic, the skill writes it into the entity-layer `GenesisTODO.notImplemented` holes (never drafts logic itself) |
- | `strict-review` | Review pass |
- ### Other commands
- ```bash
- genesis --version # print the Genesis version
- genesis bundle-parse ./bundle.json # authoritative bundle parse → canonical FullBundle JSON on stdout
- genesis check-skills # report whether installed skills are in sync with this binary
- genesis verify # run inside a generated project: release/CI gate — fails (exit 2) on any unfilled GenesisTODO hole or any invariant with no enabled test
- ```
- ## What gets generated
- From a bundle with one aggregate (`Member`), several use cases, and a read model, `genesis new` produces on the order of 90 files:
- ```
- {project-root}/
- ├── Package.swift # SwiftPM, depends on gradyzhuo/swift-ddd-kit
- ├── README.md / CLAUDE.md # Boilerplate + Claude Code guide
- ├── Sources/
- │ ├── {Aggregate}Aggregate/ # One SwiftPM target per aggregate
- │ │ ├── event.yaml # SSOT for events; the swift-ddd-kit plugin compiles it
- │ │ ├── event-generator-config.yaml / openapi.yaml
- │ │ ├── {Aggregate}.swift / {Aggregate}GenesisTODO.swift # AggregateRoot + ensureInvariant() (no-op until /domain-fill) + the GenesisTODO marker enum
- │ │ ├── {Aggregate}Error.swift # Error enum + ContextError factories, from bundle invariants
- │ │ ├── Entity/Commands/{Aggregate}+{UC}.swift # Command body (precondition scaffold + GenesisTODO throw) + when(event:) reducer
- │ │ ├── Usecase/Port/In/{UC}/ # Input / Output / Usecase protocol (execute body filled by /usecase)
- │ │ ├── Usecase/Port/Out/{Aggregate}Repository.swift # EventSourcingRepository (KurrentDB-backed)
- │ │ ├── Usecase/Service/{UC}Service.swift # Service conformance struct
- │ │ ├── Usecase/Projector/{RM}/ # ReadModel + Presenter (read side)
- │ │ └── Adapter/ # ApplicationService + ApiHandler + DTOs
- │ └── {Context}Shared/ # Cross-aggregate DTOs / value objects / ContextError / typed IDs
- ├── Tests/{Context}Tests/ # placeholder + SharedUtility/UsecaseCall/{Aggregate}.swift (codegen'd test fixtures); /test-gen adds enabled-red tests
- └── .ai/
- ├── conventions/api.md # Cross-aggregate API conventions
- └── contexts/{Context}/
- ├── .scaffold-manifest.json # sha256 of every generated file
- ├── swift-adapter.yaml # Starter adapter (if --adapter not given)
- └── {Aggregate}/ # Per-aggregate business docs (SSOT)
- ├── config.md / commands.md / invariants.md
- ├── errors.md / api.md / test-scenarios.md
- ├── reference.md
- └── notes/{UC}.md # Per-use-case working notes
- ```
- The `.ai/contexts/` markdown files are the single source of truth for business rules — downstream Claude Code skills read and edit these.
- ## The swift-adapter.yaml
- The adapter file overrides Genesis's built-in heuristics. All fields are optional:
- ```yaml
- adapterVersion: 1
- schemaVersion: 1
- contextName: LMSContext
- bundleId: <must match the bundle if present>
- typeMapping: # bundle type string → Swift type
- "Array[String]": "[String]"
- customTypes: # extra value types emitted into {Context}Shared
- - { name: MembershipStatus, kind: enum, cases: [active, suspended] }
- - { name: EmailAddress, kind: valueObject, underlying: String }
- - { name: MemberID, kind: identifier, underlying: UUID }
- createdEventOverrides: # which use case is the "created" event
- Member: createMember
- aggregateSplit:
- strategy: byBoundedContext
- idStrategy:
- kind: typedStruct # or `direct` (String IDs)
- wrapper: "{Aggregate}ID"
- ```
- Run `genesis new` without `--adapter` once, and a starter `swift-adapter.yaml` is written into `.ai/contexts/{Context}/` for you to edit and pass back on the next run.
- ## Design philosophy
- | Layer | Concern | Tooling |
- |------|---------|---------|
- | **CLI (Genesis)** | Mechanical work — scaffolding, file generation | Swift executable |
- | **Claude Code skills** | LLM judgment — business-rule clarification, code generation with context | Markdown skills in `~/.claude/skills/` |
- | **Filesystem** | SSOT — `.ai/contexts/` (business), `bundle.json` (canvas snapshot), `Sources/` (code) | Git as transaction layer |
- - **Add-only writes** — never destructive without explicit confirmation; `genesis new` rolls back fully on any failure
- - **Git as transaction** — pre-flight check + rollback, no separate transaction infrastructure
- - **Templates bundled with CLI** — versioning aligns naturally with the CLI version
- - **Stateless where possible** — `.scaffold-manifest.json` records generation provenance, not workflow state
- ## Development
- ```bash
- swift build # build CLI + core library
- swift test # run the test suite
- swift run genesis new LMSContext --from-bundle <path> # run from source
- ```
- `Tests/GenesisIntegrationTests/Fixtures/` holds the fictional library-domain bundles (`library-*.json`) used by the end-to-end tests.
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.