@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/dknet-feature-lifecycle/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: dknet-feature-lifecycle
+description: The add/remove lifecycle of a DKNet vertical-slice business feature — how to choose the manual vs automated flow, the exact file footprint a feature occupies across all six projects, and the out-of-folder touchpoints a delete must clean up. Use before /dknet-feature or /dknet-feature-remove, and whenever you need to enumerate or retire an existing feature.
+---
+
+# DKNet feature lifecycle
+
+A **feature** in this template is one business capability delivered as a vertical slice. It is
+addressable by a single PascalCase folder name (`<Feature>`) that appears literally in fixed roots
+across six projects. That is what makes a feature addable and removable as a unit.
+
+Two worked examples ship with the template and are the canonical reference for each flow:
+
+| Flow | Exemplar feature | Exemplar entity |
+|---|---|---|
+| `manual` | `ManualSample` | `PurchaseOrder` |
+| `auto` | `AutomatedSample` | `Product` |
+
+## 1. Choosing the flow
+
+Pick **one flow per aggregate** and do not mix them for the same entity. Mixing means some routes
+are generated and some hand-mapped, and the two halves have different validation and idempotency
+behavior — which is exactly the confusion this section exists to prevent.
+
+### At a glance: which one should I copy?
+
+**Copy `manual` (mirror `PurchaseOrder`)** when the feature needs any of:
+
+- Idempotent writes — safe client retries on `POST`.
+- An attribute-declared (`DataAnnotations`) rule that must actually return `400`, not just be
+  present on the generated request.
+- An operation that writes more than one aggregate in one transaction.
+- A filtered or customized list/get query beyond the generic list route's `filter`/`search`/`orderBy`
+  contract.
+- The acting user must come from a claim on the request itself (`[FromClaim]`).
+
+**Copy `auto` (mirror `Product`)** only when the aggregate is genuinely plain CRUD:
+
+- Create/update/delete carry no rule a `[Required]`/`[StringLength]`/`[Range]` can't express — and
+  you accept those attributes are forwarded but never enforced on a generated route (see the gap
+  below).
+- No idempotency requirement on create.
+- The DTO can be every audited property, narrowed at most with `Exclude`/`Include`.
+- Any extra operations fit `[CrudAction]`'s shape (mutate, return `200` + DTO) or can be excluded and
+  hand-written when they can't.
+
+A rule that must **refuse** an operation is *not* by itself a reason to choose `manual`. A
+FluentValidation validator written against a generated request still runs — `UseEndpointConfigs`
+applies `AddFluentValidationAutoValidation()` to every endpoint group, generated routes included —
+so it can read stored data through `IRepositorySpec` and refuse before the generated handler runs.
+`Product` ships two such rules (`CreateProductRequestValidator`, `DeleteProductRequestValidator`),
+both answering `409` via a `PreconditionCodes`-prefixed error code.
+
+| Trade-off | `manual` | `auto` |
+|---|---|---|
+| Attribute-declared validation (`[Range]`, `[Required]` on a `[CrudCreate]`/`[CrudUpdate]` param) | enforced — literal `Map*` calls, seen by the .NET 10 validation source generator | forwarded onto the generated request but **never enforced** — every generated route goes through `DKNet.AspCore.Extensions`'s generic `Map*<TRequest,TDto>` wrapper, which the source generator can't see into |
+| Idempotency on create | `.RequiredIdempotentKey()` — a replayed `X-Idempotency-Key` returns the original response | none — the generated create route has no such call; a duplicate submit creates a duplicate row |
+| DTO default shape | hand-picked fields only (`PurchaseOrderDto` exposes 5) | every audited property by default (`Id`, `CreatedBy/On`, `UpdatedBy/On` + entity props); narrow with `[GenerateDto(..., Exclude=[...])]` |
+| Filtered list / custom get-by-id | a hand-written `Specification<T>` + query handler, any shape | the generic list route only (`filter`/`search`/`orderBy`/paging against the DTO); a bespoke predicate or a "check tenant ownership on get" still forces a hand-written route |
+| Event naming | you choose the record name (`AddEvent(new PurchaseOrderCreatedEvent(...))`) | composed by convention: `<Entity><NarrowingProps><Operation>Event` — e.g. `[RaisesEvent(EventOperations.Updated, nameof(Price))]` on `Product` → `ProductPriceUpdatedEvent`, never `ProductUpdatedEvent`; verify the composed name in the compiled assembly, it has no source file |
+| Acting-user attribution | `[FromClaim(ClaimTypes.Name)]` on the request — visible in the request shape | never a request property (the generator forwards only `DataAnnotations` attributes) — comes from `DKNet.EfCore.DataAuthorization`'s `DataOwnerHook`/audit hook instead, wired once for every entity on `CoreDbContext`; the forgery guarantee is identical, only the visibility differs |
+| External broker (Azure Service Bus) | not wired for `PurchaseOrder` at all — a deliberate scope split | `azb.Produce<T>`/`azb.Consume<T>` in `ServiceBusSetup.cs` works on a declaratively-raised event exactly like a hand-raised one, but only when `EnableServiceBus` is on **and** `ConnectionStrings:AzureBus` is non-empty |
+
+A mixed aggregate is a smell, but dropping **one** operation out of `auto` to a hand-written route
+is legitimate when only that operation needs what the generator can't express —
+`CrudMapOptions.Exclude("Discontinue")` plus a literal `MapPut` below it is exactly how `Product`
+handles the one operation that writes two aggregates in one transaction. Say so explicitly when you
+do it.
+
+## 2. Feature footprint
+
+Every path below is scoped by the feature folder name. `<Feature>` is PascalCase (`Orders`),
+`<Plural>` is the BDD folder (usually the same). Root for the first six: `ApiEndpoints/`. Verified
+against the real tree under both sample features.
+
+| # | Path | `manual` | `auto` |
+|---|---|---|---|
+| 1 | `Minimal.Domains/Features/<Feature>/Entities/` | entity + hand-written event record(s) | entity only — `[RaisesEvent]`/`[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]` carry the rest |
+| 2 | `Minimal.Infra/Features/<Feature>/Mappers/` | `IEntityTypeConfiguration<T>` | same — **no generator produces this** |
+| 3 | `Minimal.Infra/Features/<Feature>/StaticData/` | optional `DataSeedingConfiguration<T>` | optional (neither sample ships one for `Product`) |
+| 4 | `Minimal.Infra/Features/<Feature>/ExternalEvents/` | not used by `PurchaseOrder` | optional broker consumer (`ProductCreatedNotificationHandler`) |
+| 5 | `Minimal.AppServices/<Feature>/V1/Actions/` | command requests + handlers | only operations excluded from the generated map (e.g. `Discontinue.cs`) |
+| 6 | `Minimal.AppServices/<Feature>/V1/Queries/` | hand-written read requests + handlers | custom read shapes the generic list can't express (e.g. a price-summary query) |
+| 7 | `Minimal.AppServices/<Feature>/V1/Specs/` | `Specification<T>` filters | specs backing a validator or an excluded query |
+| 8 | `Minimal.AppServices/<Feature>/V1/Events/` | domain event consumers | domain event consumers only — the generator raises, it does not consume |
+| 9 | `Minimal.AppServices/<Feature>/V1/Validators/` | not needed — validation is enforced on literal routes | validators against a **generated** request that must refuse (`CreateXRequestValidator`, `DeleteXRequestValidator`) |
+| 10 | `Minimal.AppServices/<Feature>/V1/<Feature>Dto.cs` (+ optional `<Feature>MappingRegister.cs`) | hand-written DTO record | one `[GenerateDto(typeof(Entity))] public sealed partial record` line; a Mapster `IRegister` only if a response value needs deriving from more than one column |
+| 11 | `Minimal.Api/ApiEndpoints/<Feature>/<Entity>V1Endpoint.cs` | every route a literal `Map*` call | one `group.Map<Entity>Crud(o => …)` call, plus any excluded route mapped literally below it |
+| 12 | `Minimal.App.Tests/Unit/<Feature>/` | entity/validator/spec tests | entity/handler tests |
+| 13 | `Minimal.App.Tests/Integration/<Feature>/V1/` | result-level handler + security tests | same |
+| 14 | `Minimal.App.BDDTests/Features/<Plural>/` | `*.feature` + `Steps/*.cs` | same |
+
+Generated code for `auto` lands in `obj/Generated/DKNet.SlimBus.Generators/` (requests, handlers,
+route registration) and `obj/Generated/DKNet.EfCore.DtoGenerator/` (the DTO's generated members) —
+never committed, never deleted by hand, disappears with the attributes.
+
+## 3. Out-of-folder touchpoints
+
+Deleting the folders above leaves these behind. **Every removal must check all of them** — they are
+the reason a feature delete is a command and not an `rm -rf`.
+
+| Touchpoint | File | When it applies |
+|---|---|---|
+| Schema constant | `Minimal.Domains/Share/DomainSchemas.cs` | if the feature added its own `const string` (the samples instead use literal schema strings — `"manual_sample"`/`"sample"` — directly in their mapper's `ToTable` call) |
+| Broker topology | `Minimal.Infra/Extensions/ServiceBusSetup.cs` | the `azb.Produce<T>`/`azb.Consume<T>` pair, e.g. `ProductCreatedEvent` on `product-tp`/`product-sub` |
+| Feature flag | `Minimal.Share/Options/FeatureOptions.cs` + `FeatureManagement` section in every `appsettings*.json` | if the feature gated itself behind a flag |
+| Auth scopes | the feature's own scopes class (e.g. `ProductScopes`) + its `foreach` registration in `Configs/Auth/AuthConfig.cs` | if the feature registered per-route scope policies |
+| Precondition codes | `Minimal.AppServices/Share/PreconditionCodes.cs` | if a validator added a `precondition.`-prefixed code for this feature |
+| Test-support visibility | `InternalsVisibleTo` in the owning project's `.csproj` (e.g. `Minimal.Api.csproj` grants `Minimal.App.TestSupport` and `Minimal.App.Tests` visibility onto `internal` scope classes) | if the feature's `internal` types need to be visible to test doubles |
+| EF migration | `Minimal.Infra/Migrations/` | see §4 — never hand-delete an applied migration |
+
+Enumerate existing features at any time — no registry file to keep in sync:
+
+```bash
+ls ApiEndpoints/Minimal.Domains/Features/
+```
+
+## 4. Migration rules on removal
+
+The tables outlive the code. Decide by whether the feature's migration has been applied anywhere:
+
+- **Not applied and it is the newest migration** —
+  `dotnet ef migrations remove -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj` (run from
+  `ApiEndpoints/`).
+- **Applied, or newer migrations sit on top of it** — do NOT touch the old migration. Delete the
+  entity and mapper, then
+  `dotnet ef migrations add Drop<Feature> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj`
+  and let EF emit the drop. Rewriting applied history corrupts `__EFMigrationsHistory` for every
+  environment already running it.
+
+When in doubt, take the second branch — it is always correct, merely more verbose.
+
+## 5. Order of operations
+
+**Add** (each step builds green before the next): Domains → Infra → AppServices → Api → tests → BDD
+→ docs. The orchestrator is `/dknet-feature <Feature> <Entity> [mode=manual|auto] [props…]`.
+
+**Remove** (reverse — drop dependents before dependencies, so the build never sees a dangling
+reference): docs → BDD → tests → Api → AppServices → Infra → Domains → touchpoints → migration. The
+orchestrator is `/dknet-feature-remove <Feature>`.
+
+Never remove `ManualSample` or `AutomatedSample` from the template repository itself — they are the
+exemplars every skill and command cites. In a *generated* solution they are the first thing a
+consumer deletes, and `/dknet-feature-remove` is how.

package/skills/dknet-feature-remove/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: dknet-feature-remove
+description: Retire a DKNet vertical-slice business feature end-to-end — deletes its folders across all six projects, cleans the out-of-folder touchpoints, and drops its tables via a new migration.
+metadata:
+  kind: workflow
+  arguments: "<Feature> [--dry-run] e.g. Orders"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash, TodoWrite
+---
+
+Usage: `/dknet-feature-remove <Feature> [--dry-run] e.g. Orders`
+
+You are retiring a complete vertical slice. A feature is addressable by its folder name, but a
+`rm -rf` is **not** a correct removal — schema constants, broker topology, feature flags, docs links,
+and the database tables all live outside the feature folders.
+
+## Inputs
+
+`$ARGUMENTS` — the feature folder name (PascalCase, as it appears under
+`Minimal.Domains/Features/`), plus optional `--dry-run`.
+
+If no feature is named, list the candidates and stop:
+
+```bash
+ls ApiEndpoints/Minimal.Domains/Features/
+```
+
+## Required reading
+
+1. The `dknet-feature-lifecycle` skill — §2 footprint, §3 touchpoints, §4 migration
+   rules, §5 removal order. This command is the executable form of that skill; do not improvise a
+   different order.
+
+## Phase 0 — Confirm and inventory (always, even under `--dry-run`)
+
+1. Resolve the feature: confirm `ApiEndpoints/Minimal.Domains/Features/<Feature>/` exists. If it
+   does not, list the candidates and STOP — do not guess at a near-match.
+2. Inventory every path that will be deleted, using the §2 footprint. Report actual matches only:
+   ```bash
+   find ApiEndpoints -path '*<Feature>*' -not -path '*/obj/*' -not -path '*/bin/*' | sort
+   find docs -path '*<slug>*' | sort
+   ```
+3. Grep for references from **outside** the slice — this is what catches the touchpoints and any
+   coupling the footprint table doesn't predict:
+   ```bash
+   grep -rn '<Feature>\|<Entity>' ApiEndpoints --include=*.cs --include=*.json \
+     -l | grep -v '<Feature>' | sort -u
+   ```
+   Inspect each hit. Anything in a *different* feature's folder is real coupling — surface it and
+   STOP; the user decides whether to break it or keep the feature.
+4. Print the inventory: files to delete (grouped by layer), touchpoints to edit, migration decision
+   (§4 branch), and the exact table names that will be dropped.
+5. **STOP and ask the user to confirm** before deleting anything. Under `--dry-run`, stop here
+   permanently and report.
+
+## Phase 1 — Delete, in dependent-first order
+
+Do NOT reorder. Each step removes only things that nothing later in the list depends on, so an
+intermediate build failure points at real coupling rather than at the ordering.
+
+1. Docs — `docs/features/<slug>/` (or wherever the solution keeps feature docs).
+2. BDD — `ApiEndpoints/Minimal.App.BDDTests/Features/<Plural>/` (both `*.feature` and the
+   generated `*.feature.cs`, plus `Steps/`).
+3. Tests — `Minimal.App.Tests/Unit/<Feature>/` and `Minimal.App.Tests/Integration/<Feature>/`.
+   Also grep `Minimal.App.Tests/Architecture/` — a convention test may assert on this feature by name.
+4. Api — `Minimal.Api/ApiEndpoints/<Feature>/`.
+5. AppServices — `Minimal.AppServices/<Feature>/`.
+6. Infra — `Minimal.Infra/Features/<Feature>/`.
+7. Domains — `Minimal.Domains/Features/<Feature>/`.
+
+## Phase 2 — Out-of-folder touchpoints
+
+Work the §3 table. For each, edit surgically — remove the feature's lines, never the whole file:
+
+1. `Minimal.Domains/Share/DomainSchemas.cs` — drop the feature's `const string`, if it added one.
+   Leave `Migration` and `Profile` alone unless this feature owned one of them.
+2. `Minimal.Infra/Extensions/ServiceBusSetup.cs` — drop the matching `azb.Produce<T>` /
+   `azb.Consume<T>` pair and the now-unused `using`.
+3. `Minimal.Share/Options/FeatureOptions.cs` + every `appsettings*.json` `FeatureManagement` section
+   — drop the flag property and its JSON key together. A key with no property silently no-ops, so
+   an orphan here fails no test; delete both halves or neither.
+4. Docs cross-links — the docs index page and any feature index that linked the slice.
+
+## Phase 3 — Migration
+
+Apply §4 of the lifecycle skill. State which branch you took and why:
+
+- Feature's migration is the newest and unapplied → `cd ApiEndpoints && dotnet ef migrations remove -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj`
+- Otherwise → `cd ApiEndpoints && dotnet ef migrations add Drop<Feature> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj` and verify the generated `Up`
+  contains the expected `DropTable` calls and nothing else.
+
+Read the generated migration before moving on. A drop migration that also touches an unrelated table
+means the model changed underneath you — STOP and report.
+
+## Phase 4 — Verify
+
+1. `dotnet build -c Release` — must be zero warnings (warnings-as-errors).
+2. `dotnet test --settings coverage.runsettings` — all green.
+3. Final residue sweep — must return nothing:
+   ```bash
+   grep -rn '<Feature>\|<Entity>' ApiEndpoints docs --include=*.cs --include=*.json --include=*.md \
+     --include=*.feature | grep -v '/obj/\|/bin/\|Migrations/'
+   ```
+   Hits under `Migrations/` are expected and correct — historical migrations keep the old table
+   names and must not be edited.
+
+## Report
+
+1. Files/folders deleted, grouped by layer.
+2. Touchpoints edited, with the specific lines removed.
+3. Migration branch taken + migration name + tables dropped.
+4. Build + test results.
+5. Anything deliberately left behind, and why (historical migrations, shared types another feature
+   uses).
+6. Suggested commit title. Do not commit unless the user asks.
+
+## Stop conditions
+
+- Feature folder not found → list candidates, STOP.
+- Another feature references this one → report the coupling, STOP.
+- Build or tests fail after deletion and the cause is not an obvious leftover reference → STOP,
+  summarize, ask. Do not start deleting unrelated code to make the build pass.
+- Migration branch is ambiguous (unclear whether it was applied) → take the `add-migration` branch,
+  say so, and continue. That branch is always safe.
+
+## Constraints
+
+- Never hand-delete an applied migration or edit migration history.
+- Never delete `ManualSample` or `AutomatedSample` **in the template repo itself** — every skill and
+  command cites them as exemplars. In a generated consumer solution, removing them is the expected
+  first use of this command.
+- Never widen scope to "cleanup" unrelated code you notice on the way through.