Skip to content
Back to search

Genesis

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abner-tungchi--genesis/badge.svg)](/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

i

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
  1. # Genesis
  2. 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.
  3. ## What Genesis does
  4. 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.
  5. 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).
  6. 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).
  7. ## A worked example: a library lending system
  8. 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`.
  9. ```bash
  10. # 1. Build Genesis
  11. git clone <this-repo-url> && cd Genesis
  12. swift build -c release # binary: .build/release/genesis
  13. # 2. Generate the project from the bundle (run it in a clean git work tree, or pass --no-git)
  14. mkdir ~/lms && cd ~/lms && git init
  15. /path/to/Genesis/.build/release/genesis new LMSContext --from-bundle ./bundle.json
  16. # 3. The project compiles, but the tests for unfilled features are red
  17. swift build
  18. swift test # red: borrowBook, returnBook, ... are still GenesisTODO holes
  19. genesis verify # exit 2 while holes remain
  20. # 4. Fill the holes (Claude Code skills), then re-run the gate
  21. genesis install-skills
  22. # /usecase borrowBook -> orchestration body
  23. # /api borrowBook -> ApplicationService + ApiHandler bodies
  24. # /domain-fill -> transcribe the domain rules you dictate (e.g. "a member may hold at most 5 books")
  25. # /test-gen borrowBook -> enabled-red Swift Testing tests
  26. genesis verify # exit 0 when everything is filled and tested
  27. ```
  28. Requires Swift 6.0+ (macOS 13+) — generated projects use Swift Testing and SwiftPM tools 6.0.
  29. ## Usage
  30. ### Bootstrap a project
  31. ```bash
  32. # Minimal — uses built-in defaults
  33. genesis new LMSContext --from-bundle ./bundle.json
  34. # With an adapter to override type mapping / ID strategy / etc.
  35. genesis new LMSContext --from-bundle ./bundle.json --adapter ./swift-adapter.yaml
  36. # Into a specific directory
  37. genesis new LMSContext --from-bundle ./bundle.json --output ./my-project
  38. ```
  39. | Flag | Purpose |
  40. |------|---------|
  41. | `--from-bundle <path>` | Event Storming bundle JSON (required) |
  42. | `--adapter <path>` | `swift-adapter.yaml` to override defaults (optional) |
  43. | `--output <dir>` | Output directory (default: current directory) |
  44. | `--no-git` | Skip the git pre-flight check (for CI / sandboxes) |
  45. | `--skip-build` | Skip the post-generation `swift build` (resolve still runs) |
  46. `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.
  47. ### Install Claude Code skills
  48. ```bash
  49. # User-global (default) — installs into ~/.claude/skills/
  50. genesis install-skills
  51. # Per-project
  52. genesis install-skills --scope project --project-dir ./my-project
  53. # Overwrite existing skills
  54. genesis install-skills --force
  55. # Remove the bundled skills again — keeps any skill you've hand-edited (unless --force)
  56. genesis uninstall-skills
  57. ```
  58. 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.
  59. | Skill | Role |
  60. |-------|------|
  61. | `event-storming` | Model a domain on an Event Storming canvas |
  62. | `write-ddd-spec` / `bundle-plan` | Turn a bundle into per-use-case contract-first task specs |
  63. | `usecase` | Fill the domain `Usecase.execute()` orchestration body (Create / Update / Delete patterns) |
  64. | `api` | Fill the write-side `ApplicationService` + `ApiHandler` bodies |
  65. | `readmodel` / `presenter` | Scaffold read models + presenters |
  66. | `readmodel-mutation` / `presenter-fill` | Fill read-side projector `when()` + read application-service bodies |
  67. | `test-gen` | Emit **enabled-red** Swift Testing tests; two-file split (machine `.generated` + human `.authored`) |
  68. | `domain-fill` | Transcription-only: dictate domain logic, the skill writes it into the entity-layer `GenesisTODO.notImplemented` holes (never drafts logic itself) |
  69. | `strict-review` | Review pass |
  70. ### Other commands
  71. ```bash
  72. genesis --version # print the Genesis version
  73. genesis bundle-parse ./bundle.json # authoritative bundle parse → canonical FullBundle JSON on stdout
  74. genesis check-skills # report whether installed skills are in sync with this binary
  75. 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
  76. ```
  77. ## What gets generated
  78. From a bundle with one aggregate (`Member`), several use cases, and a read model, `genesis new` produces on the order of 90 files:
  79. ```
  80. {project-root}/
  81. ├── Package.swift # SwiftPM, depends on gradyzhuo/swift-ddd-kit
  82. ├── README.md / CLAUDE.md # Boilerplate + Claude Code guide
  83. ├── Sources/
  84. │ ├── {Aggregate}Aggregate/ # One SwiftPM target per aggregate
  85. │ │ ├── event.yaml # SSOT for events; the swift-ddd-kit plugin compiles it
  86. │ │ ├── event-generator-config.yaml / openapi.yaml
  87. │ │ ├── {Aggregate}.swift / {Aggregate}GenesisTODO.swift # AggregateRoot + ensureInvariant() (no-op until /domain-fill) + the GenesisTODO marker enum
  88. │ │ ├── {Aggregate}Error.swift # Error enum + ContextError factories, from bundle invariants
  89. │ │ ├── Entity/Commands/{Aggregate}+{UC}.swift # Command body (precondition scaffold + GenesisTODO throw) + when(event:) reducer
  90. │ │ ├── Usecase/Port/In/{UC}/ # Input / Output / Usecase protocol (execute body filled by /usecase)
  91. │ │ ├── Usecase/Port/Out/{Aggregate}Repository.swift # EventSourcingRepository (KurrentDB-backed)
  92. │ │ ├── Usecase/Service/{UC}Service.swift # Service conformance struct
  93. │ │ ├── Usecase/Projector/{RM}/ # ReadModel + Presenter (read side)
  94. │ │ └── Adapter/ # ApplicationService + ApiHandler + DTOs
  95. │ └── {Context}Shared/ # Cross-aggregate DTOs / value objects / ContextError / typed IDs
  96. ├── Tests/{Context}Tests/ # placeholder + SharedUtility/UsecaseCall/{Aggregate}.swift (codegen'd test fixtures); /test-gen adds enabled-red tests
  97. └── .ai/
  98. ├── conventions/api.md # Cross-aggregate API conventions
  99. └── contexts/{Context}/
  100. ├── .scaffold-manifest.json # sha256 of every generated file
  101. ├── swift-adapter.yaml # Starter adapter (if --adapter not given)
  102. └── {Aggregate}/ # Per-aggregate business docs (SSOT)
  103. ├── config.md / commands.md / invariants.md
  104. ├── errors.md / api.md / test-scenarios.md
  105. ├── reference.md
  106. └── notes/{UC}.md # Per-use-case working notes
  107. ```
  108. The `.ai/contexts/` markdown files are the single source of truth for business rules — downstream Claude Code skills read and edit these.
  109. ## The swift-adapter.yaml
  110. The adapter file overrides Genesis's built-in heuristics. All fields are optional:
  111. ```yaml
  112. adapterVersion: 1
  113. schemaVersion: 1
  114. contextName: LMSContext
  115. bundleId: <must match the bundle if present>
  116. typeMapping: # bundle type string → Swift type
  117. "Array[String]": "[String]"
  118. customTypes: # extra value types emitted into {Context}Shared
  119. - { name: MembershipStatus, kind: enum, cases: [active, suspended] }
  120. - { name: EmailAddress, kind: valueObject, underlying: String }
  121. - { name: MemberID, kind: identifier, underlying: UUID }
  122. createdEventOverrides: # which use case is the "created" event
  123. Member: createMember
  124. aggregateSplit:
  125. strategy: byBoundedContext
  126. idStrategy:
  127. kind: typedStruct # or `direct` (String IDs)
  128. wrapper: "{Aggregate}ID"
  129. ```
  130. 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.
  131. ## Design philosophy
  132. | Layer | Concern | Tooling |
  133. |------|---------|---------|
  134. | **CLI (Genesis)** | Mechanical work — scaffolding, file generation | Swift executable |
  135. | **Claude Code skills** | LLM judgment — business-rule clarification, code generation with context | Markdown skills in `~/.claude/skills/` |
  136. | **Filesystem** | SSOT — `.ai/contexts/` (business), `bundle.json` (canvas snapshot), `Sources/` (code) | Git as transaction layer |
  137. - **Add-only writes** — never destructive without explicit confirmation; `genesis new` rolls back fully on any failure
  138. - **Git as transaction** — pre-flight check + rollback, no separate transaction infrastructure
  139. - **Templates bundled with CLI** — versioning aligns naturally with the CLI version
  140. - **Stateless where possible** — `.scaffold-manifest.json` records generation provenance, not workflow state
  141. ## Development
  142. ```bash
  143. swift build # build CLI + core library
  144. swift test # run the test suite
  145. swift run genesis new LMSContext --from-bundle <path> # run from source
  146. ```
  147. `Tests/GenesisIntegrationTests/Fixtures/` holds the fictional library-domain bundles (`library-*.json`) used by the end-to-end tests.
  148. ## License
  149. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.