Skip to content
Skills Library
Programming · Building & coding

add-module

/add-module

Create a new module (bounded context) — runtime + Contracts projects, IModule, DbContext, permissions, migrations, and the four registration sites. Use when adding a distinct business domain. For a feature in an existing module, use add-feature.

Licence
MIT
Last repository change
09.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create a new module (bounded context) — runtime + Contracts projects, IModule, DbContext, permissions, migrations, and the four registration sites. Use when adding a distinct business domain. For a feature in an existing module, use add-feature.

Arguments

/add-module [ModuleName]
Original author description

Create a new module (bounded context) — runtime + Contracts projects, IModule, DbContext, permissions, migrations, and the four registration sites. Use when adding a distinct business domain. For a feature in an existing module, use add-feature.

How it works

  1. Projects
  2. Step 1 — [FshModule] is an ASSEMBLY attribute (not class-level)
  3. Step 2 — Permissions (Contracts/Authorization)
  4. Step 3 — DbContext (extends BaseDbContext)
  5. Step 4 — Solution + project references
  6. Step 5 — Migrations folder
  7. Step 6 — ⚠️ Register in ALL FOUR places (the footgun)
  8. Step 7 — Verify
  9. Checklist
Original SKILL.md headings · 133 lines, 565 words
SKILL.md preview
---
name: add-module
description: Create a new module (bounded context) — runtime + Contracts projects, IModule, DbContext, permissions, migrations, and the four registration sites. Use when adding a distinct business domain. For a feature in an existing module, use add-feature.
argument-hint: "[ModuleName]"
---

# Add Module

High-ceremony. The part people get wrong is **registration — a module must be wired in FOUR places**
(see Step 6). Architecture rules: `.agents/rules/architecture.md`.

## Projects

```
src/Modules/{Name}/
├── Modules.{Name}/            ← runtime (internal): Domain/, Data/, Features/v1/, {Name}Module.cs
└── Modules.{Name}.Contracts/  ← public API: v1/ (commands/queries), Dtos/, Authorization/, Events/
```

**Copy an existing module's two `.csproj` files** (e.g. `Modules.Catalog`) and rename — don't hand-write
project references. The runtime project references its Contracts project + the BuildingBlocks it needs;
the Contracts project references `Mediator` + shared contracts.

## Step 1 — `[FshModule]` is an ASSEMBLY attribute (not class-level)

In `{Name}Module.cs`, above the namespace:

```csharp
[assembly: FshModule(typeof(FSH.Modules.{Name}.{Name}Module), 900)]   // (Type, order)

namespace FSH.Modules.{Name};

public sealed class {Name}Module : IModule
{
    public void ConfigureServices(IHostApplicationBuilder builder)
    {
        ArgumentNullException.ThrowIfNull(builder);
        PermissionConstants.Register({Name}Permissions.All);
        builder.Services.AddHeroDbContext<{Name}DbContext>();
        builder.Services.AddScoped<IDbInitializer, {Name}DbInitializer>();

        // Only if the module HANDLES integration events:
        // builder.Services.AddIntegrationEventHandlers(typeof({Name}Module).Assembly);
        //
        // Publishing needs no registration at all — the outbox is framework-owned
        // (host calls AddEventingCore once). Inject IOutboxWriter and publish.
        // Never register a per-module outbox store; see .agents/rules/eventing.md.

        builder.Services.AddHealthChecks()
            .AddDbContextCheck<{Name}DbContext>(name: "db:{name}");
    }

    public void ConfigureMiddleware(IApplicationBuilder app) { }   // optional, runs after auth

    public void MapEndpoints(IEndpointRouteBuilder endpoints)
    {
        ArgumentNullException.ThrowIfNull(endpoints);
        var versionSet = endpoints.NewApiVersionSet().HasApiVersion(new ApiVersion(1)).ReportApiVersions().Build();
        var group = endpoints.MapGroup("api/v{version:apiVersion}/{name}")
            .WithTags("{Name}").WithApiVersionSet(versionSet).RequireAuthorization();
        // group.MapCreate{Entity}Endpoint();  …
    }
}
```

`Order` controls load sequence (Auditing 300, Files 350, Webhooks 400, Billing 500, Catalog 600, Tickets 700, Notifications 750, Chat 800). If your module consumes another's events, load after it.

## Step 2 — Permissions (Contracts/Authorization)

`{Name}Permissions` with nested resource classes and an `All` collection registered via `PermissionConstants.Register({Name}Permissions.All)`. Mirror the shape of `CatalogPermissions`.

## Step 3 — DbContext (extends `BaseDbContext`)

```csharp
public sealed class {Name}DbContext : BaseDbContext
{
    public const string Schema = "{name}";

    public {Name}DbContext(
        IMultiTenantContextAccessor<AppTenantInfo> multiTenantContextAccessor,
        DbContextOptions<{Name}DbContext> options,
        IOptions<DatabaseOptions> settings,
        IHostEnvironment environment)
        : base(multiTenantContextAccessor, options, settings, environment) { }

    public DbSet<{Entity}> {Entities} => Set<{Entity}>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        ArgumentNullException.ThrowIfNull(modelBuilder);
        modelBuilder.HasDefaultSchema(Schema);
        modelBuilder.ApplyConfigurationsFromAssembly(typeof({Name}DbContext).Assembly);
        base.OnModelCreating(modelBuilder);   // MUST be last — applies tenant + soft-delete filters
    }
}
```

## Step 4 — Solution + project references

```bash
dotnet sln src/FSH.Starter.slnx add src/Modules/{Name}/Modules.{Name}/Modules.{Name}.csproj
dotnet sln src/FSH.Starter.slnx add src/Modules/{Name}/Modules.{Name}.Contracts/Modules.{Name}.Contracts.csproj
```

Add a `<ProjectReference>` to the runtime module from **both** `FSH.Starter.Api` and `FSH.Starter.DbMigrator`, and reference the runtime project from `FSH.Starter.Migrations.PostgreSQL`.

## Step 5 — Migrations folder

Add a `{Name}/` folder in `src/Host/FSH.Starter.Migrations.PostgreSQL`, then create the initial migration (see **create-migration**) with `--context {Name}DbContext`.

## Step 6 — ⚠️ Register in ALL FOUR places (the footgun)

Identical edits in **both** `FSH.Starter.Api/Program.cs` **and** `FSH.Starter.DbMigrator/Program.cs`:

1. Mediator `o.Assemblies` — add **two** markers: a Contracts type (e.g. `typeof(FSH.Modules.{Name}.Contracts.{Name}ContractsMarker)`) **and** the module type (`typeof({Name}Module)`).
2. `moduleAssemblies` array — add `typeof({Name}Module).Assembly`.

Miss the Mediator marker → handlers silently undiscovered. Miss the assembly entry → module never loads. Miss the DbMigrator pair → migrate/seed skips the module.

## Step 7 — Verify

```bash
dotnet build src/FSH.Starter.slnx                  # 0 warnings
dotnet test src/Tests/Architecture.Tests           # boundary + tenant-isolation rules must pass
dotnet test src/FSH.Starter.slnx
```

## Checklist

- [ ] Two projects (copied csproj), added to `.slnx`, referenced from Api + DbMigrator (+ Migrations)
- [ ] `[assembly: FshModule(typeof({Name}Module), order)]` (assembly-level, positional)
- [ ] `IModule`: `AddHeroDbContext<T>()`, `PermissionConstants.Register`, version-set group, eventing trio if needed
- [ ] `{Name}DbContext : BaseDbContext`, 4-arg ctor, `base.OnModelCreating` last
- [ ] `{Name}Permissions` in Contracts/Authorization
- [ ] Migrations folder + initial migration (`--context {Name}DbContext`)
- [ ] **Registered in all four places** (Api + DbMigrator × Mediator + moduleAssemblies)
- [ ] Build + Architecture.Tests green

Versions

RepositoryScoreLicence
This page · fullstackhero/dotnet-starter-kit100MIT
TurbineKit/turbinekit100MIT
Q-Sharp/CloudGround100MIT
a-pavithraa/springboot-skills-marketplace96MIT

Database snapshot: 13.11.2026 · package version d3bdd5b708f7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ef-add-migration
    Add an EF Core migration in the open workspace. Discovers startup project, DbContext, and migrations folder. Use when adding a migration or invoking /ef-add-migration.
  • 100core-add-module
    Add a new module to the core package (src/packages/core/). Use when adding shared UI framework infrastructure that all packages can use — e.g., a new extension system feature, a new utility, a new shared component pattern, a new picker, or a new workspace primitive. Core modules…
  • 100module
    What a LangWatch module is and how to start one: the four packages (contract, process, browser, client), modules/catalogue.json, pnpm generate:modules, the specs/ and adrs/ folders, the dependency direction between halves, and what another module may import. Use when someone…
  • 100create-module
    Create a new NestJS module with repository, service, controller, schema, and Drizzle table definition. Use when adding new feature modules, API endpoints, or business domains.
  • 100general-create-package
    Create a new package in the Umbraco backoffice client with its first module. Use when adding a new domain feature area that needs its own package under src/packages/ — e.g., a new CMS feature like data types, tags, or relations. Packages are self-contained domain modules that…
  • 100dbcontext-config-auditor
    Audit EF Core DbContext and entity configuration for correctness and performance pitfalls — tracking defaults, lazy loading, missing configuration, connection setup, sensitive data logging, and pooling. Use this skill whenever the user shares a DbContext, OnModelCreating,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.