@shanyucoder/flowgrid 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+<!-- flowgrid-catalog -->
+**[Danh mục tài liệu](CATALOG.md)**
+<!-- /flowgrid-catalog -->
+
+# FlowGrid
+
+**FlowGrid** là nền tảng **CLI + harness** dành cho team phát triển phần mềm khi làm việc với **agent AI** (Cursor, Claude Code, Gemini/Antigravity, Codex, OpenCode, Hermes, Kiro, Kilo Code, … — chọn ở bước `flowgrid init`).
+
+- **Workflow cho team** — các phase phát triển theo quy chuẩn: **design**; phát triển **code + test**; **wire**.
+- **Quản lý artifact** — quy trình và SSOT trên disk cho dự án phần mềm:
+  - **Spec / requirement** (docs-hub — SSOT):
+    - user story, bundle spec;
+    - thiết kế UI, action;
+    - QA: open question;
+    - artifact khác: technical debt, technical derived, call external service, …
+  - **Document testcase** (tests-docs):
+    - testcase, test suite;
+    - scenario test.
+- **Toolkit T-shaped** — hỗ trợ member mở rộng lane khi làm việc với AI:
+  - **Dev** — skill dev chuyên sâu, kèm chút kỹ năng BA: nhờ AI phân tích / grill → spec đạt khoảng **70–80%** so với BA thông thường.
+  - **BA** — phân tích, tạo requirement spec: nhờ AI code **prototype** theo yêu cầu, **không** cần nhờ dev.
+  - **QA / Test** — skill manual test: nhờ AI sinh automation **E2E**; dev review bổ sung lỗ hổng còn thiếu theo document testcase.
+
+FlowGrid **không** thay IDE hay model. Nó gắn **quy trình**, **định dạng artifact** và **lệnh kiểm định** vào repo để agent và member đi **cùng một lane**, **từng bước một**.
+
+## Tổng quan
+
+- **CLI (`flowgrid`)** — cài tool; `init` theo loại dự án; chạy audit, gate, codegen; `doctor`; sync harness.
+- **Harness (skills + MCP)** — sau `init`, agent gọi slash command (vd. `/spec`, `/testcase`) theo `SKILL.md` đã sync; MCP server `flowgrid` nối engine docs / test / codegen với workspace.
+- **Script audit** — kiểm tra **lượng** trên artifact (schema, field bắt buộc, trace testcase ↔ bundle) bằng Node thuần; output JSON `gaps[]`; bổ trợ grill **chất** của member và agent.
+- **Workflow theo phase phát triển** — bám vòng đời thực tế **một tính năng**:
+  - **Phân tích** — yêu cầu, phạm vi, kiến trúc (overview, module, luồng nghiệp vụ).
+  - **Đặc tả** — bundle, user story, API contract trên **docs-hub**.
+  - **Prototype UI** — feedback sớm, thống nhất hành vi trước code production.
+  - **Backend** — spec API; sinh / xử lý service theo adapter stack (NestJS, FastAPI, …).
+  - **Tests-docs** — scenario, ma trận `TC-*.yaml`; gate trước khi coi testcase **đóng**.
+  - **E2E automation** — sinh Playwright từ testcase; regression trên **e2e-root** (repo FE); giảm **IT thủ công** lặp trước release.
+  - **Wire** — ghép FE với API thật; audit đối chiếu tests-docs ↔ spec E2E.
+- **Skill ↔ vai trò member (T-shaped)** — mỗi phase gắn skill và vai trò gợi ý; AI **hỗ trợ đúng việc, đúng người** — **không** gom cả repo một lần:
+  - **Lead / BA** — phạm vi, kiến trúc, grill nghiệp vụ (`/overview`, `/grill-bqa`, …).
+  - **Dev FE** — prototype, wire, unit / E2E lane code.
+  - **Dev BE** — contract, implementation API, align FE–BE (`audit fe-be`).
+  - **QA** — testcase trên **tests-docs**, grill testcase, theo dõi coverage E2E.
+  - **Member** — vẫn **review, grill, chốt**; agent chuẩn hóa YAML/Markdown, gợi ý patch, chạy codegen — **không** tự quyết thay product owner.
+- **Ba loại artifact trên disk** — có thể nhiều repo, nối bằng env:
+  - **docs-hub** — `*.bundle.yaml`, IR, kiến trúc & function (`FLOWGRID_DOCS_ROOT`).
+  - **tests-docs** — `cases/**`, `TC-*.yaml`, scenario (`FLOWGRID_TESTS_DOC`, `--tests-docs`).
+  - **Code** — FE / BE / fullstack; test tự động trên **e2e-root** (`--e2e-root`), tách khỏi hub testcase.
+
+## Phase · vai trò · skill
+
+| Phase (tóm tắt) | Vai trò thường gặp | Hỗ trợ FlowGrid (ví dụ) |
+| --- | --- | --- |
+| Phân tích & phạm vi | Lead / BA | `/overview`, `/architecture`, `/module` |
+| Đặc tả chức năng | BA / Dev | `/spec`, `/grill-bqa`, `flowgrid audit spec` |
+| Prototype UI | Dev FE | `/prototype`, portal/codegen adapters |
+| Backend & contract | Dev BE | `/api-spec`, `/api`, `audit api`, `audit fe-be` |
+| Testcase (tests-docs) | QA / Dev | `/testcase`, `/scenario`, `cases:gate` |
+| E2E automation | QA / Dev | `testcase:gen`, Playwright trên **e2e-root** |
+| Tích hợp & kiểm tra trước release | Dev FE + QA | `/wire`, `flowgrid audit e2e` |
+
+`flowgrid audit *` và `cases:gate` dùng ở các mốc trên để phát hiện lệch artifact trước khi sang phase kế tiếp.
+
+---
+
+## Cài đặt
+
+**Yêu cầu:** Node.js **≥ 22**.
+
+### 1. Cài FlowGrid CLI
+
+**Khuyến nghị — pnpm global từ npm** (cùng một lệnh trên **Linux**, **macOS**, **WSL** và **Windows PowerShell** / Terminal):
+
+```text
+pnpm add -g @shanyucoder/flowgrid
+```
+
+(Gõ trong bash, zsh, **PowerShell**, CMD hoặc Windows Terminal — cùng một lệnh. Tarball npm đã có `dist/` — **không** cần `--allow-build`.)
+
+**Chưa có bản trên npm** (hoặc cần bản Git cụ thể):
+
+```text
+pnpm add -g github:ShanYuCoder/flowgrid --allow-build=@shanyucoder/flowgrid
+```
+
+pnpm 10+ cần `--allow-build` khi cài **từ GitHub** (build TypeScript lúc cài).
+
+| Môi trường | PATH sau `pnpm add -g` |
+| --- | --- |
+| **Linux / macOS** | Chạy `pnpm setup` nếu shell báo thiếu bin; thường là `~/.local/share/pnpm`. |
+| **WSL** | Giống Linux — dùng Node/pnpm **trong WSL**, không trộn với Node cài trên Windows host trừ khi cố ý. |
+| **Windows (PowerShell, CMD, Windows Terminal)** | Chạy **`pnpm setup`** một lần (ghi PATH user), **đóng và mở lại** terminal; kiểm tra: `where.exe flowgrid` hoặc `flowgrid --version`. |
+
+**WSL / Git Bash** có thể dùng lệnh pnpm ở trên; **không** bắt buộc `install.sh` nếu đã cài global qua pnpm.
+
+**npx (không cài global):**
+
+```text
+npx -p @shanyucoder/flowgrid flowgrid init
+```
+
+Thay `init` bằng `doctor`, `harness sync`, … GitHub: `npx -p github:ShanYuCoder/flowgrid flowgrid init`.
+
+**npm (global):**
+
+```text
+npm install -g @shanyucoder/flowgrid
+```
+
+Cài từ Git: `npm install -g github:ShanYuCoder/flowgrid` (npm 11+: có thể cần `npm install-scripts approve @shanyucoder/flowgrid`).
+
+**Dev dependency trong repo dự án:**
+
+```text
+pnpm add -D @shanyucoder/flowgrid
+pnpm exec flowgrid doctor
+```
+
+Từ Git: `pnpm add -D github:ShanYuCoder/flowgrid --allow-build=@shanyucoder/flowgrid`.
+
+Đội toolkit publish npm: [PUBLISH-NPM.md](PUBLISH-NPM.md) (root, không build VitePress).
+
+**Phát triển toolkit (clone repo):**
+
+Linux / macOS / WSL:
+
+```bash
+git clone https://github.com/ShanYuCoder/flowgrid.git && cd flowgrid
+pnpm install && sh install-local.sh
+```
+
+Windows (PowerShell):
+
+```powershell
+git clone https://github.com/ShanYuCoder/flowgrid.git; cd flowgrid
+pnpm install; pnpm link --global
+```
+
+**Tùy chọn — script bash** (Linux / macOS / WSL / Git Bash — clone + `~/.local/bin`, **không** thay pnpm global):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ShanYuCoder/flowgrid/main/install.sh | bash
+```
+
+**Cập nhật** (npm hoặc GitHub — không cần gỡ cài lại):
+
+```text
+flowgrid update
+```
+
+Tự nhận cách cài (pnpm global, npm global, `install.sh`, hoặc clone dev) và chạy lệnh phù hợp. Ghim ref: `FLOWGRID_REF=v0.1.0 flowgrid update`. Xem trước: `flowgrid update --check`.
+
+**Gỡ:** `pnpm remove -g @shanyucoder/flowgrid` (mọi OS) · hoặc `npm uninstall -g @shanyucoder/flowgrid` · script bash: `bash install.sh --uninstall`.
+
+### 2. Khởi tạo repo (`flowgrid init`)
+
+```bash
+cd your-project
+flowgrid init
+```
+
+| Bước | Câu hỏi init | Ý nghĩa / gợi ý nhập |
+| --- | --- | --- |
+| **1** | **Select Agents/Skills to integrate** | Agent IDE/CLI (Cursor, Claude, …). Copy **skills** + **MCP** (`flowgrid`) vào thư mục agent. Có thể bỏ trống, sync sau: `flowgrid harness sync`. |
+| **2** | **Select project type** | **Document** — docs-hub. **Frontend** / **Backend** / **Fullstack** — code (+ pointer docs/tests). **Test** — tests-docs. |
+| **3** | **Base Architecture Profile** | **Standard** (Nuxt4, Next.js, NestJS, FastAPI, …) hoặc **Custom** (+ **Golden Sample** tùy chọn). |
+| **4** | **Frontend / Backend technology** | Adapter codegen (`nuxt4`, `nextjs`, `nestjs`, `fastapi`, …). Fullstack: FE + BE (mặc định Nest). |
+| **5** | **Docs-hub location** (FE / BE / Fullstack) | **This repository** — scaffold `docs/` (integration/hook surfaces trên repo BE). **Other** — path pointer → `FLOWGRID_DOCS_ROOT`. **Document**: cwd = hub. |
+| **6** | **Tests-docs location** (FE / BE / Fullstack) | **This repository** — scaffold `tests/` (+ `/test-api`, `testcase:gen:api` cho hook). **Other** — path pointer → `FLOWGRID_TESTS_DOC`. **Test**: cwd = hub. |
+| **7** | **Languages** (chỉ **Document**) | **Đa ngôn ngữ global** dự án (i18n toàn hệ thống, không phải bản dịch từng file docs): vd. `vi,en,ja` + locale mặc định; một ngôn ngữ thì nhập một. |
+| **8** | **Installation Plan** + **Proceed?** | Xem lại và xác nhận. |
+| **9** | *(sau confirm)* | `.flowgrid/`, scaffold, harness, MCP, `artifactgraph/`. |
+| **10** | **Optional toolkits** | Tuỳ chọn **Codegraph**. |
+
+Sau init: **`.flowgrid/config.json`**; dùng slash skill (vd. `/spec`) trong agent đã chọn.
+
+```mermaid
+flowchart LR
+  A[Chọn agents] --> B[Project type]
+  B --> C[Base profile]
+  C --> D[Stack FE/BE]
+  D --> E[Docs root]
+  E --> F[Tests root]
+  F --> G[Xác nhận plan]
+  G --> H[.flowgrid + MCP + skills]
+```
+
+Wizard tương tác: chạy `flowgrid init` trên repo dự án. Bảng bước, `flowgrid doctor` / `harness sync`: [docs/references/cli-and-commands.md](docs/references/cli-and-commands.md) (Audit & Harness · MCP).
+
+### 3. Kiểm tra
+
+```bash
+flowgrid doctor
+```

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/IntegrationContext.cs

@@ -0,0 +1,56 @@
+namespace IntegrationGen;
+
+internal sealed class IntegrationContext
+{
+    public required string Module { get; init; }
+    public required string ModulePascal { get; init; }
+    public required string EntityPascal { get; init; }
+    public required string EntitySnake { get; init; }
+    public required string Profile { get; init; }
+    public required string ApiPath { get; init; }
+    public required string ApiMethod { get; init; }
+    public required string Action { get; init; }
+    public required string ActionPascal { get; init; }
+    public required string FeatureId { get; init; }
+
+    public static IntegrationContext FromSpec(Dictionary<string, object?> spec)
+    {
+        var feature = YamlMap.GetDict(spec, "feature");
+        var codegen = YamlMap.GetDict(spec, "codegen");
+        var module = YamlMap.GetString(codegen, "module", "mes");
+        var entity = YamlMap.GetString(codegen, "entity", "Entity");
+        var profile = YamlMap.GetString(codegen, "profile", "adapter");
+        var endpoints = YamlMap.AsList(YamlMap.GetDict(spec, "api").GetValueOrDefault("endpoints")) ?? [];
+        var endpoint = endpoints.Count > 0 && YamlMap.AsDict(endpoints[0]) is { } value
+            ? value
+            : new Dictionary<string, object?>();
+        var action = YamlMap.GetString(endpoint, "action", "get");
+        return new IntegrationContext
+        {
+            Module = module,
+            ModulePascal = NameUtil.ToPascal(module),
+            EntityPascal = NameUtil.ToPascal(entity),
+            EntitySnake = NameUtil.ToSnake(entity),
+            Profile = profile,
+            ApiPath = YamlMap.GetString(endpoint, "path", "/plants/{plant_id}/downtime"),
+            ApiMethod = YamlMap.GetString(endpoint, "method", "GET"),
+            Action = action,
+            ActionPascal = action == "getDowntime" ? "GetDowntime" : NameUtil.ToPascal(action),
+            FeatureId = YamlMap.GetString(feature, "id", NameUtil.ToSnake(entity)),
+        };
+    }
+
+    public object ToTemplateModel() => new
+    {
+        module = Module,
+        module_pascal = ModulePascal,
+        entity_pascal = EntityPascal,
+        entity_snake = EntitySnake,
+        profile = Profile,
+        api_path = ApiPath,
+        api_method = ApiMethod,
+        action = Action,
+        action_pascal = ActionPascal,
+        feature_id = FeatureId,
+    };
+}

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/IntegrationGen.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>IntegrationGen</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Scriban" Version="7.2.5" />
+    <PackageReference Include="YamlDotNet" Version="16.3.0" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="Templates\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+</Project>

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/NameUtil.cs

@@ -0,0 +1,18 @@
+using System.Text.RegularExpressions;
+
+namespace IntegrationGen;
+
+internal static class NameUtil
+{
+    public static string ToPascal(string value)
+    {
+        var parts = Regex.Split(value, @"[-_\s]+").Where(part => part.Length > 0);
+        return string.Concat(parts.Select(part => char.ToUpper(part[0]) + part[1..]));
+    }
+
+    public static string ToSnake(string value)
+    {
+        var snake = Regex.Replace(value, @"([a-z])([A-Z])", "$1_$2");
+        return Regex.Replace(snake, @"[\s\-]+", "_").ToLowerInvariant();
+    }
+}

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/Program.cs

@@ -0,0 +1,265 @@
+using System.Text.Json;
+using IntegrationGen;
+using Scriban;
+using Scriban.Runtime;
+
+static string ProjectRoot()
+{
+    var configured = Environment.GetEnvironmentVariable("FLOWGRID_PROJECT_ROOT");
+    var root = Path.GetFullPath(string.IsNullOrWhiteSpace(configured) ? Directory.GetCurrentDirectory() : configured);
+    if (!Directory.Exists(root))
+        throw new DirectoryNotFoundException($"FLOWGRID_PROJECT_ROOT not found: {root}");
+    return root;
+}
+
+static string UnderRoot(string root, string path, string label)
+{
+    var full = Path.GetFullPath(path, root);
+    var relative = Path.GetRelativePath(root, full);
+    if (relative == ".." || relative.StartsWith($"..{Path.DirectorySeparatorChar}") || Path.IsPathRooted(relative))
+        throw new InvalidOperationException($"{label} must be inside FLOWGRID_PROJECT_ROOT: {full}");
+    return full;
+}
+
+static (Dictionary<string, object?> spec, string specPath, string featureDir) ReadSpec(string root, string specArg)
+{
+    var specPath = UnderRoot(root, specArg, "spec");
+    var spec = YamlMap.Load(specPath);
+    var parent = Path.GetFileName(Path.GetDirectoryName(specPath)!);
+    var featureDir = parent is "ir" or "integration"
+        ? Path.GetDirectoryName(Path.GetDirectoryName(specPath))!
+        : Path.GetDirectoryName(specPath)!;
+    return (spec, specPath, featureDir);
+}
+
+static string RenderTemplate(string name, object model)
+{
+    var templatePath = Path.Combine(AppContext.BaseDirectory, "Templates", name);
+    var template = Template.Parse(File.ReadAllText(templatePath), templatePath);
+    var script = new ScriptObject();
+    script.Import(model, renamer: member => member.Name);
+    var context = new TemplateContext();
+    context.PushGlobal(script);
+    return template.Render(context).TrimEnd() + Environment.NewLine;
+}
+
+static List<(string RelativePath, string Template)> BuildPlan(IntegrationContext context)
+{
+    var module = context.ModulePascal;
+    var entity = context.EntityPascal;
+    return
+    [
+        ($"src/Integration.Application/Generated/{module}/I{entity}Service.gen.cs", "application_service.cs.scriban"),
+        ($"src/Integration.Infrastructure/Generated/{module}/Mock{entity}Repository.gen.cs", "infrastructure_mock.cs.scriban"),
+        ($"src/Integration.Presenters/Generated/{module}/{entity}Presenter.gen.cs", "presenter.cs.scriban"),
+        ($"tests/Integration.Api.Tests/Generated/{entity}ServiceTests.gen.cs", "service_test.cs.scriban"),
+    ];
+}
+
+static void MergeI18nFlat(object? i18nObj, string localesDir, bool dryRun)
+{
+    if (i18nObj is not Dictionary<string, object?> i18nDict) return;
+    
+    var dataByLang = new Dictionary<string, Dictionary<string, string>>();
+    foreach (var kvp in i18nDict)
+    {
+        var key = kvp.Key;
+        if (kvp.Value is not Dictionary<string, object?> translations) continue;
+        
+        foreach (var trans in translations)
+        {
+            var lang = trans.Key;
+            var val = trans.Value?.ToString();
+            if (val == null) continue;
+            
+            if (!dataByLang.ContainsKey(lang)) dataByLang[lang] = new Dictionary<string, string>();
+            dataByLang[lang][key] = val;
+        }
+    }
+    
+    foreach (var langPair in dataByLang)
+    {
+        var lang = langPair.Key;
+        var newKeys = langPair.Value;
+        var localePath = Path.Combine(localesDir, $"{lang}.json");
+        var currentData = new Dictionary<string, string>();
+        if (File.Exists(localePath))
+        {
+            try
+            {
+                var existing = JsonSerializer.Deserialize<Dictionary<string, string>>(File.ReadAllText(localePath));
+                if (existing != null) currentData = existing;
+            }
+            catch { }
+        }
+        
+        foreach (var kv in newKeys) currentData[kv.Key] = kv.Value;
+        
+        if (!dryRun)
+        {
+            Directory.CreateDirectory(localesDir);
+            File.WriteAllText(localePath, JsonSerializer.Serialize(currentData, new JsonSerializerOptions { WriteIndented = true }) + "\n");
+        }
+        
+        Console.WriteLine($"  {(dryRun ? "[dry] " : "write")}: locales/{lang}.json (+{newKeys.Count} keys)");
+    }
+}
+
+static int Registry(string root)
+{
+    Console.WriteLine(File.ReadAllText(Path.Combine(root, "registries", "dotnet-integration.codegen.registry.json")));
+    return 0;
+}
+
+static int Run(string root, string command, string specArg, bool force)
+{
+    var dryRun = command == "dry";
+    var (spec, specPath, featureDir) = ReadSpec(root, specArg);
+    var context = IntegrationContext.FromSpec(spec);
+    var model = context.ToTemplateModel();
+    var written = new List<string>();
+    Console.WriteLine($"integration-gen: entity={context.EntityPascal} module={context.ModulePascal}");
+    Console.WriteLine($"  spec: {specPath}");
+
+    foreach (var (relative, template) in BuildPlan(context))
+    {
+        var destination = UnderRoot(root, relative, "output");
+        if (File.Exists(destination) && !force)
+        {
+            Console.WriteLine($"  skip: {relative} (exists)");
+            continue;
+        }
+        var content = RenderTemplate(template, model);
+        if (dryRun) Console.WriteLine($"  [dry]: {relative}");
+        else
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(destination)!);
+            File.WriteAllText(destination, content);
+            Console.WriteLine($"  write: {relative}");
+        }
+        written.Add(relative);
+    }
+
+    if (!dryRun)
+    {
+        var generatedDir = UnderRoot(root, Path.Combine(featureDir, "generated"), "generated metadata");
+        Directory.CreateDirectory(generatedDir);
+        var manifestPath = Path.Combine(generatedDir, "integration.manifest.json");
+        File.WriteAllText(manifestPath, JsonSerializer.Serialize(new
+        {
+            generatedAt = DateTime.UtcNow.ToString("o"),
+            spec = Path.GetRelativePath(root, specPath).Replace('\\', '/'),
+            profile = context.Profile,
+            files = written,
+        }, new JsonSerializerOptions { WriteIndented = true }));
+        var handoff = new ScriptObject();
+        handoff.Import(model, renamer: member => member.Name);
+        handoff["spec_path"] = specPath;
+        handoff["files"] = written;
+        var handoffContext = new TemplateContext();
+        handoffContext.PushGlobal(handoff);
+        var handoffTemplate = Template.Parse(File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Templates", "handoff.md.scriban")));
+        File.WriteAllText(Path.Combine(generatedDir, "INTEGRATION-HANDOFF.md"), handoffTemplate.Render(handoffContext));
+        Console.WriteLine($"  manifest: {manifestPath}");
+    }
+
+    if (spec.TryGetValue("i18n", out var i18nData))
+    {
+        MergeI18nFlat(i18nData, Path.Combine(root, "locales"), dryRun);
+    }
+
+    return 0;
+}
+
+static List<string> ResolveSpecPaths(string root, string? specArg, string? idArg)
+{
+    if (specArg is not null) return [specArg];
+    if (idArg is null) throw new InvalidOperationException("Either --spec or --id must be provided");
+
+    var dir = new DirectoryInfo(AppContext.BaseDirectory);
+    while (dir != null && dir.Name != "adapters")
+    {
+        dir = dir.Parent;
+    }
+    if (dir == null) throw new Exception("Could not locate adapters directory");
+    var scriptPath = Path.Combine(dir.FullName, "shared", "resolve-cli.mjs");
+
+    var process = new System.Diagnostics.Process
+    {
+        StartInfo = new System.Diagnostics.ProcessStartInfo
+        {
+            FileName = "node",
+            Arguments = $"\"{scriptPath}\" \"{root}\" \"{idArg}\" api-codegen",
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true
+        }
+    };
+    process.Start();
+    var output = process.StandardOutput.ReadToEnd();
+    process.WaitForExit();
+    if (process.ExitCode != 0)
+    {
+        throw new Exception($"Failed to resolve ID {idArg}: {process.StandardError.ReadToEnd()}");
+    }
+    using var doc = JsonDocument.Parse(output);
+    var rootObj = doc.RootElement;
+    if (!rootObj.GetProperty("success").GetBoolean())
+    {
+        throw new Exception($"Failed to resolve ID {idArg}: {rootObj.GetProperty("error").GetString()}");
+    }
+    
+    var paths = rootObj.GetProperty("paths").EnumerateArray().Select(x => x.GetString()!).ToList();
+    var notes = rootObj.GetProperty("notes").EnumerateArray().Select(x => x.GetString()!).ToList();
+    var kind = rootObj.GetProperty("kind").GetString();
+
+    foreach (var note in notes) Console.WriteLine($"  note: {note}");
+    if (paths.Count == 0) throw new Exception($"--id {idArg}: no codegen specs");
+    Console.WriteLine($"integration-gen: --id {idArg} -> {paths.Count} spec(s) ({kind})");
+    return paths;
+}
+
+if (args.Length == 0)
+{
+    Console.Error.WriteLine("Usage: IntegrationGen registry | dry --spec <path> | write --spec <path> [--force]");
+    return 1;
+}
+
+try
+{
+    var root = ProjectRoot();
+    var force = args.Contains("--force");
+    var specIndex = Array.IndexOf(args, "--spec");
+    var specPath = specIndex >= 0 && specIndex + 1 < args.Length ? args[specIndex + 1] : null;
+    var idIndex = Array.IndexOf(args, "--id");
+    var idArg = idIndex >= 0 && idIndex + 1 < args.Length ? args[idIndex + 1] : null;
+    
+    if (args[0] == "registry") return Registry(root);
+    if (args[0] == "dry" || args[0] == "write")
+    {
+        var paths = ResolveSpecPaths(root, specPath, idArg);
+        if (paths.Count > 1) Console.WriteLine($"integration-gen: {paths.Count} spec(s) to process");
+        var failed = 0;
+        foreach (var path in paths)
+        {
+            try
+            {
+                Run(root, args[0], path, force);
+                if (paths.Count > 1) Console.WriteLine("");
+            }
+            catch (Exception e)
+            {
+                failed++;
+                Console.Error.WriteLine($"integration-gen: FAIL {path}: {e.Message}");
+            }
+        }
+        return failed > 0 ? 1 : 0;
+    }
+    return 1;
+}
+catch (Exception error)
+{
+    Console.Error.WriteLine($"IntegrationGen: {error.Message}");
+    return 1;
+}

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/Templates/application_service.cs.scriban

@@ -0,0 +1,27 @@
+// Auto-generated by integration-gen
+using Integration.Domain.{{ module_pascal }};
+
+namespace Integration.Application.Generated.{{ module_pascal }};
+
+public interface I{{ entity_pascal }}Service
+{
+    Task<{{ entity_pascal }}> {{ action_pascal }}Async(int plantId, CancellationToken cancellationToken = default);
+}
+
+public sealed class {{ entity_pascal }}Service : I{{ entity_pascal }}Service
+{
+    private readonly I{{ entity_pascal }}Repository _repository;
+
+    public {{ entity_pascal }}Service(I{{ entity_pascal }}Repository repository)
+    {
+        _repository = repository;
+    }
+
+    public Task<{{ entity_pascal }}> {{ action_pascal }}Async(int plantId, CancellationToken cancellationToken = default)
+        => _repository.GetAsync(plantId, cancellationToken);
+}
+
+public interface I{{ entity_pascal }}Repository
+{
+    Task<{{ entity_pascal }}> GetAsync(int plantId, CancellationToken cancellationToken = default);
+}

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/Templates/handoff.md.scriban

@@ -0,0 +1,15 @@
+# Integration gen — HANDOFF
+
+Spec: `{{ spec_path }}`
+
+Entity: **{{ entity_pascal }}** · module: **{{ module_pascal }}** · API: `{{ api_method }} {{ api_path }}`
+
+## Generated files
+
+{{ for f in files }}- `{{ f }}`
+{{ end }}
+
+## Manual follow-up
+
+- Register DI in `WebAppFactory` / `Program`
+- Validate the pilot-specific `mes-downtime` integration behavior

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/Templates/infrastructure_mock.cs.scriban

@@ -0,0 +1,20 @@
+// Auto-generated by integration-gen
+using Integration.Application.Generated.{{ module_pascal }};
+using Integration.Domain.{{ module_pascal }};
+
+namespace Integration.Infrastructure.Generated.{{ module_pascal }};
+
+public sealed class Mock{{ entity_pascal }}Repository : I{{ entity_pascal }}Repository
+{
+    public Task<{{ entity_pascal }}> GetAsync(int plantId, CancellationToken cancellationToken = default)
+    {
+        return Task.FromResult(new {{ entity_pascal }}
+        {
+            PlantId = plantId,
+            Items =
+            [
+                new DowntimeRecord { MachineId = "M-GEN-001", Minutes = 5, Reason = "integration-gen-stub" },
+            ],
+        });
+    }
+}

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/Templates/presenter.cs.scriban

@@ -0,0 +1,41 @@
+// Auto-generated by integration-gen
+using System.Text.Json.Serialization;
+using Integration.Domain.{{ module_pascal }};
+
+namespace Integration.Presenters.Generated.{{ module_pascal }};
+
+public sealed class {{ entity_pascal }}Contract
+{
+    [JsonPropertyName("plant_id")]
+    public int PlantId { get; init; }
+
+    [JsonPropertyName("items")]
+    public IReadOnlyList<DowntimeItemContract> Items { get; init; } = Array.Empty<DowntimeItemContract>();
+}
+
+public sealed class DowntimeItemContract
+{
+    [JsonPropertyName("machine_id")]
+    public string MachineId { get; init; } = string.Empty;
+
+    [JsonPropertyName("minutes")]
+    public int Minutes { get; init; }
+
+    [JsonPropertyName("reason")]
+    public string Reason { get; init; } = string.Empty;
+}
+
+public static class {{ entity_pascal }}Presenter
+{
+    public static {{ entity_pascal }}Contract ToContract({{ entity_pascal }} source)
+        => new()
+        {
+            PlantId = source.PlantId,
+            Items = source.Items.Select(item => new DowntimeItemContract
+            {
+                MachineId = item.MachineId,
+                Minutes = item.Minutes,
+                Reason = item.Reason,
+            }).ToList(),
+        };
+}

package/adapters/dotnet-integration/codegen/runners/IntegrationGen/Templates/service_test.cs.scriban

@@ -0,0 +1,17 @@
+// Auto-generated by integration-gen
+using Integration.Application.Generated.{{ module_pascal }};
+using Integration.Infrastructure.Generated.{{ module_pascal }};
+
+namespace Integration.Api.Tests.Generated;
+
+public class {{ entity_pascal }}ServiceGenTests
+{
+    [Fact]
+    public async Task Service_returns_gen_stub()
+    {
+        var service = new {{ entity_pascal }}Service(new Mock{{ entity_pascal }}Repository());
+        var result = await service.{{ action_pascal }}Async(1);
+        Assert.Equal(1, result.PlantId);
+        Assert.Contains(result.Items, item => item.Reason == "integration-gen-stub");
+    }
+}