kataster 0.0.0-stage → 0.2.1

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "kataster",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Agent workflow for domain-driven discovery and delivery – drop it into a greenfield or brownfield repository and build the domain by grilling.",
+  "keywords": [
+    "agents",
+    "opencode",
+    "claude-code",
+    "domain-driven-design",
+    "ddd",
+    "domain-model",
+    "event-storming",
+    "workflow",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "author": "Michael Schempp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hemi1986/kataster.git"
+  },
+  "homepage": "https://github.com/hemi1986/kataster#readme",
+  "bugs": {
+    "url": "https://github.com/hemi1986/kataster/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "kataster": "./bin/kataster.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/install.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "extras",
+    "guide",
+    ".claude",
+    ".opencode",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:install": "node --test test/install.test.mjs",
+    "doctor": "node bin/kataster.mjs doctor .",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,302 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { Installer, VERSION } from "./install.mjs";
+import { buildProfile, detectProject } from "./detect.mjs";
+import { readJson, write } from "./util.mjs";
+
+const HELP = `Kataster ${VERSION} – agent workflow for domain-driven discovery and delivery
+
+Usage:
+  kataster init [dir]      Install the workflow into a repository (default: .)
+  kataster upgrade [dir]   Update the workflow, keep project content and local changes
+  kataster doctor [dir]    Check the installation
+  kataster --version
+  kataster --help
+
+Options:
+  --brownfield          Existing codebase: start with /adopt (default when code is found)
+  --greenfield          New project: start with /bootstrap
+  --name <name>         Project name (default: directory name)
+  --ui-language <lang>  Language of the user interface (default: en)
+  --artifacts <lang>    Language of docs, stories and code comments (default: en)
+  --backlog <provider>  Where stories live: local (default), github, jira
+  --jira-project <key>  Jira project key (with --backlog jira)
+  --github-repo <repo>  GitHub repository owner/name (with --backlog github; default: this repo)
+  --with <list>         Optional extras, comma-separated (available: shadcn)
+  --force               Overwrite locally modified workflow files (backup is kept)
+  --no-install          Do not run "npm install --prefix .claude"
+  --yes, -y             Non-interactive: accept the detected defaults
+  --dry-run             Show what would happen, write nothing
+`;
+
+function parse(argv) {
+  const options = { _: [] };
+  const takesValue = new Set(["name", "ui-language", "artifacts", "with", "backlog", "jira-project", "github-repo"]);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("-")) {
+      options._.push(arg);
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--version" || arg === "-v") options.version = true;
+    else if (arg === "--brownfield") options.brownfield = true;
+    else if (arg === "--greenfield") options.greenfield = true;
+    else if (arg === "--force") options.force = true;
+    else if (arg === "--no-install") options.noInstall = true;
+    else if (arg === "--yes" || arg === "-y") options.yes = true;
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg.startsWith("--") && arg.includes("=")) {
+      const [key, ...rest] = arg.slice(2).split("=");
+      options[camel(key)] = rest.join("=");
+    } else if (arg.startsWith("--") && takesValue.has(arg.slice(2))) {
+      options[camel(arg.slice(2))] = argv[++i];
+    } else if (arg.startsWith("--")) options[camel(arg.slice(2))] = true;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+
+const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+async function ask(question, fallback, { yes } = {}) {
+  if (yes) return fallback;
+  if (!stdin.isTTY) return fallback;
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(`${question}${fallback ? ` [${fallback}]` : ""}: `)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+function banner() {
+  console.log(`\n  Kataster ${VERSION}\n  Discovery and delivery workflow for agent harnesses\n`);
+}
+
+function nextSteps(root, profile) {
+  const rel = root === resolve(".") ? "." : root;
+  const command = profile.kind === "brownfield" ? "/adopt" : "/bootstrap";
+  console.log(`
+Next steps in ${rel}:
+  1. Review .claude/project.json – name, stack, languages, commands.
+  2. Open the repository in OpenCode (or Claude Code) and run ${command}.
+     ${profile.kind === "brownfield"
+       ? "It analyses code, docs, tests and git history, drafts the domain model, then grills you to correct it."
+       : "It grills the vision, runs the event storming and builds the domain model with you."}
+  3. Read CONTEXT.md and docs/domain/events.yaml as they fill up – they are the source of truth.
+${profile.backlog?.provider && profile.backlog.provider !== "local"
+    ? `  4. Backlog backend: ${profile.backlog.provider}. Fill in .claude/project.json and sync with /backlog-sync.`
+    : ""}
+
+Useful commands afterwards:
+  /grill-me /grill-with-docs   sharpen a plan and write the docs as you go
+  /event-storming              explore a process or the whole domain
+  /feature <idea>              add a feature through grilling, storming, stories
+  /review-stories              one lead-dev pass before a story is ready
+  /implement [ST-NNN]          test-first implementation of one story
+  /backlog-sync                pull/push the backlog mirror (Jira or GitHub Issues)
+  /retro                       retrospective on a session
+`);
+}
+
+function printSummary(installer, extras) {
+  const { created, updated, conflicts } = installer.summary();
+  console.log(`\nDone: ${created} created, ${updated} updated${extras.length ? `, extras: ${extras.join(", ")}` : ""}.`);
+  if (conflicts.length) {
+    console.log(`\n${conflicts.length} file(s) kept because they were modified locally:`);
+    for (const c of conflicts) console.log(`  - ${c}`);
+    console.log("  Run with --force to overwrite them (a backup is written to .kataster/backup/).");
+  }
+}
+
+async function init(options) {
+  const root = resolve(options._[1] ?? ".");
+  const detection = detectProject(root);
+  const extras = String(options.with ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+
+  banner();
+  if (existsSync(join(root, ".claude", "install.json"))) {
+    console.log(`${root} already has a Kataster installation – running upgrade.\n`);
+    return upgrade({ ...options, _: ["upgrade", root] });
+  }
+  console.log(`Installing into ${root}`);
+  console.log(`Detected: ${detection.kind}, ${detection.languages.join(", ") || "no code yet"}${
+    detection.frameworks.length ? `, ${detection.frameworks.join(", ")}` : ""
+  }${detection.databases.length ? `, ${detection.databases.join(", ")}` : ""}${
+    detection.repoTooling?.monorepo ? `, ${detection.repoTooling.kind} monorepo` : ""
+  }\n`);
+
+  const kind = options.brownfield ? "brownfield" : options.greenfield ? "greenfield" : detection.kind;
+  const name = await ask("Project name", options.name || detection.packageName || basename(root), options);
+  const uiLanguage = await ask("UI language (en, de, …)", options.uiLanguage || "en", options);
+  const artifactLanguage = await ask("Language of docs and stories", options.artifacts || "en", options);
+  const backlog = await ask("Backlog backend (local, github, jira)", options.backlog || "local", options);
+  if (!["local", "github", "jira"].includes(backlog)) {
+    throw new Error(`Unknown backlog backend '${backlog}' – use local, github or jira.`);
+  }
+  const jiraProject = backlog === "jira"
+    ? await ask("Jira project key (e.g. PROJ)", options.jiraProject || "", options)
+    : "";
+  const githubRepo = backlog === "github"
+    ? await ask("GitHub repository (owner/name, empty = this repo)", options.githubRepo || "", options)
+    : "";
+
+  const profile = buildProfile(root, {
+    name, kind, uiLanguage, artifactLanguage, detection, extras,
+    backlog, jiraProject, githubRepo,
+  });
+  profile.workflow.version = VERSION;
+
+  const installer = new Installer(root, { dryRun: options.dryRun, force: options.force, log: (line) => console.log(`  ${line}`) });
+  installer.migrateLegacy();
+  installer.copyWorkflowDirs();
+  installer.mergeSettings();
+  installer.mergeOpencodeConfig();
+  installer.mergeAgentsFile(profile);
+  installer.copyDocsSkeleton(profile);
+  installer.putContext(profile);
+  installer.putClaudeMd(profile);
+  installer.putProfile(profile);
+  installer.putConventions(profile);
+  installer.installExtras(extras);
+  installer.updateGitignore();
+  installer.writeManifest();
+
+  if (options.dryRun) {
+    console.log("\nDry run – nothing was written.");
+    return;
+  }
+
+  if (!options.noInstall) {
+    const result = installer.installToolingDependencies();
+    if (!result.ok) console.log("\nTooling dependencies could not be installed – run: npm install --prefix .claude");
+  }
+
+  printSummary(installer, extras);
+  nextSteps(root, profile);
+}
+
+async function upgrade(options) {
+  const root = resolve(options._[1] ?? ".");
+  banner();
+  const installer = new Installer(root, { dryRun: options.dryRun, force: options.force, log: (line) => console.log(`  ${line}`) });
+  if (!installer.manifest) {
+    console.log(`No installation found in ${root} – running init instead.\n`);
+    return init({ ...options, _: ["init", root] });
+  }
+  const profile = readJson(join(root, ".claude", "project.json")) ?? {};
+  const extras = options.with ? String(options.with).split(",").map((s) => s.trim()).filter(Boolean) : profile.workflow?.extras ?? [];
+
+  console.log(`Upgrading ${root} from ${installer.manifest.version ?? "?"} to ${VERSION}\n`);
+  installer.migrateLegacy();
+  installer.copyWorkflowDirs();
+  installer.mergeSettings();
+  installer.mergeOpencodeConfig();
+  if (profile.name) installer.mergeAgentsFile(profile);
+  installer.copyDocsSkeleton(profile);
+  installer.putContext(profile);
+  installer.putClaudeMd(profile);
+  installer.putConventions(profile);
+  installer.installExtras(extras);
+  installer.updateGitignore();
+  installer.writeManifest();
+
+  if (profile.name && !options.dryRun) {
+    profile.workflow = { ...(profile.workflow ?? {}), version: VERSION, extras };
+    write(join(root, ".claude", "project.json"), `${JSON.stringify(profile, null, 2)}\n`);
+  }
+
+  if (options.dryRun) {
+    console.log("\nDry run – nothing was written.");
+    return;
+  }
+  if (!options.noInstall) installer.installToolingDependencies();
+  printSummary(installer, extras);
+  console.log("\nUpgrade complete. Project content (CONTEXT.md, docs/domain, docs/stories, ADRs) was not touched.");
+}
+
+function doctor(options) {
+  const root = resolve(options._[1] ?? ".");
+  const checks = [];
+  const add = (name, ok, detail = "") => checks.push({ name, ok, detail });
+
+  add("Node >= 22.18", Number(process.versions.node.split(".")[0]) > 22 || (Number(process.versions.node.split(".")[0]) === 22 && Number(process.versions.node.split(".")[1]) >= 18), process.versions.node);
+  add("Workflow installed", existsSync(join(root, ".claude", "skills")) && existsSync(join(root, ".opencode")), root);
+  const manifest = readJson(join(root, ".claude", "install.json"));
+  add("Install manifest", Boolean(manifest), manifest ? `version ${manifest.version}` : "missing – run init");
+  const leftovers = existsSync(join(root, ".laguardia")) || existsSync(join(root, ".opencode", "plugins", "laguardia"));
+  add("No leftovers from the old name", !leftovers, leftovers ? "run upgrade to migrate them" : "");
+  const profile = readJson(join(root, ".claude", "project.json"));
+  add("Project profile", Boolean(profile?.name), profile?.name ?? "missing");
+
+  const backlog = profile?.backlog ?? {};
+  const provider = backlog.provider ?? "local";
+  add("Backlog provider", ["local", "github", "jira"].includes(provider), provider);
+  if (provider === "jira") {
+    add("Backlog: Jira project", Boolean(backlog.jira?.project), backlog.jira?.project || "backlog.jira.project is missing");
+    const statuses = ["draft", "review", "ready", "in-progress", "done", "superseded"];
+    const missingStatuses = statuses.filter((status) => !backlog.jira?.statusMap?.[status]);
+    add("Backlog: Jira status map", missingStatuses.length === 0, missingStatuses.join(", ") || "all statuses mapped");
+    const priorities = ["must", "should", "could", "wont"];
+    const missingPriorities = priorities.filter((priority) => !backlog.jira?.priorityMap?.[priority]);
+    add("Backlog: Jira priority map", missingPriorities.length === 0, missingPriorities.join(", ") || "all priorities mapped");
+    const server = backlog.jira?.mcpServer || "mcp-atlassian";
+    const configured = [".mcp.json", ".claude/settings.json", ".claude/settings.local.json", ".opencode/opencode.jsonc"].some((file) => {
+      try {
+        return existsSync(join(root, file)) && readFileSync(join(root, file), "utf8").includes(server);
+      } catch {
+        return false;
+      }
+    });
+    add(`Backlog: MCP server '${server}'`, configured, configured ? "" : "configure mcp-atlassian in your harness");
+  }
+  if (provider === "github") {
+    const gh = spawnSync("gh", ["--version"], { encoding: "utf8" });
+    add("Backlog: GitHub CLI", gh.status === 0, gh.status === 0 ? "" : "https://cli.github.com");
+    if (gh.status === 0) {
+      const auth = spawnSync("gh", ["auth", "status"], { encoding: "utf8" });
+      add("Backlog: gh authenticated", auth.status === 0, auth.status === 0 ? "" : "gh auth login");
+    }
+    add("Backlog: GitHub repo", true, backlog.github?.repo || "current repository");
+  }
+  add("Tooling dependencies", existsSync(join(root, ".claude", "node_modules", "yaml")), "npm install --prefix .claude");
+  for (const file of ["CONTEXT.md", "docs/domain/events.yaml", "docs/product/vision.md", "docs/stories"]) {
+    add(file, existsSync(join(root, file)), "");
+  }
+  const events = join(root, ".claude/skills/event-storming/scripts/validate-events.ts");
+  if (existsSync(events) && existsSync(join(root, ".claude", "node_modules", "yaml"))) {
+    const r = spawnSync(process.execPath, [events], { cwd: root, encoding: "utf8" });
+    add("events.yaml valid", r.status === 0, (r.stdout + r.stderr).trim().split("\n").slice(-1)[0] ?? "");
+  } else if (existsSync(events)) {
+    add("events.yaml valid", true, "skipped – tooling dependencies missing");
+  }
+
+  banner();
+  console.log(`Doctor – ${root}\n`);
+  for (const check of checks) console.log(`  ${check.ok ? "✓" : "✗"} ${check.name}${check.detail ? `  (${check.detail})` : ""}`);
+  const failed = checks.filter((c) => !c.ok);
+  console.log(failed.length ? `\n${failed.length} check(s) failed.` : "\nEverything looks good.");
+  process.exitCode = failed.length ? 1 : 0;
+}
+
+export async function main(argv) {
+  const options = parse(argv);
+  if (options.help || argv.length === 0) {
+    console.log(HELP);
+    return;
+  }
+  if (options.version) {
+    console.log(VERSION);
+    return;
+  }
+  const command = options._[0];
+  if (command === "init") return init(options);
+  if (command === "upgrade") return upgrade(options);
+  if (command === "doctor") return doctor(options);
+  throw new Error(`Unknown command '${command}'. Try --help.`);
+}

package/src/detect.mjs

@@ -0,0 +1,237 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { detectRepoTooling } from "./repo.mjs";
+
+const IGNORED = new Set([".git", ".claude", ".opencode", "node_modules", "dist", "build", "out", "coverage", ".next", "vendor", "target"]);
+const CODE_EXT = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", ".astro",
+  ".py", ".go", ".rs", ".java", ".kt", ".kts", ".rb", ".php", ".cs", ".swift", ".scala", ".ex", ".exs", ".dart",
+]);
+
+function anyFile(dir, names) {
+  return names.some((name) => existsSync(join(dir, name)));
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function countCode(root, limit = 4000) {
+  const byExt = new Map();
+  let total = 0;
+  const walk = (dir) => {
+    if (total >= limit) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (total >= limit) return;
+      if (entry.isDirectory()) {
+        if (!IGNORED.has(entry.name) && !entry.name.startsWith(".")) walk(join(dir, entry.name));
+      } else if (entry.isFile()) {
+        const dot = entry.name.lastIndexOf(".");
+        if (dot < 0) continue;
+        const ext = entry.name.slice(dot).toLowerCase();
+        if (!CODE_EXT.has(ext)) continue;
+        if (/\.(test|spec)\./.test(entry.name)) continue;
+        byExt.set(ext, (byExt.get(ext) ?? 0) + 1);
+        total += 1;
+      }
+    }
+  };
+  walk(root);
+  return byExt;
+}
+
+// Lockfiles before the manifest: a pnpm/yarn/bun repository also has a package.json, and the lockfile is the
+// package manager that actually installs and runs the scripts.
+const ECOSYSTEMS = [
+  { marker: ["pnpm-lock.yaml"], language: "TypeScript/JavaScript", manager: "pnpm", install: "pnpm install" },
+  { marker: ["yarn.lock"], language: "TypeScript/JavaScript", manager: "yarn", install: "yarn install" },
+  { marker: ["bun.lockb", "bun.lock"], language: "TypeScript/JavaScript", manager: "bun", install: "bun install" },
+  { marker: ["package.json"], language: "TypeScript/JavaScript", manager: "npm", install: "npm install" },
+  { marker: ["go.mod"], language: "Go", manager: "go", install: "go mod download" },
+  { marker: ["Cargo.toml"], language: "Rust", manager: "cargo", install: "cargo build" },
+  { marker: ["pyproject.toml", "requirements.txt", "setup.py"], language: "Python", manager: "pip", install: "pip install -r requirements.txt" },
+  { marker: ["pom.xml"], language: "Java", manager: "maven", install: "mvn install" },
+  { marker: ["build.gradle", "build.gradle.kts"], language: "Kotlin/Java", manager: "gradle", install: "./gradlew build" },
+  { marker: ["Gemfile"], language: "Ruby", manager: "bundler", install: "bundle install" },
+  { marker: ["composer.json"], language: "PHP", manager: "composer", install: "composer install" },
+  { marker: ["*.csproj", "*.sln"], language: "C#", manager: "dotnet", install: "dotnet restore" },
+];
+
+const FRAMEWORKS = {
+  next: "Next.js", react: "React", vue: "Vue", nuxt: "Nuxt", svelte: "Svelte", "@sveltejs/kit": "SvelteKit",
+  astro: "Astro", angular: "Angular", "@angular/core": "Angular", express: "Express", fastify: "Fastify",
+  "@nestjs/core": "NestJS", koa: "Koa", remix: "Remix", "@remix-run/react": "Remix", electron: "Electron",
+  "solid-js": "Solid", hono: "Hono", trpc: "tRPC", "@trpc/server": "tRPC",
+};
+const DATABASES = {
+  prisma: "Prisma", "@prisma/client": "PostgreSQL/Prisma", drizzle: "Drizzle", "drizzle-orm": "Drizzle",
+  pg: "PostgreSQL", postgres: "PostgreSQL", mysql2: "MySQL", mongoose: "MongoDB", mongodb: "MongoDB",
+  sequelize: "SQL", knex: "SQL", typeorm: "SQL", "@supabase/supabase-js": "Supabase", redis: "Redis",
+};
+const TESTERS = { vitest: "Vitest", jest: "Jest", mocha: "Mocha", playwright: "Playwright", "@playwright/test": "Playwright", cypress: "Cypress", ava: "AVA" };
+
+const CODE_ROOTS = ["src", "app", "lib", "packages", "apps", "services", "server", "client", "web", "api", "cmd", "internal", "pkg"];
+
+export function detectProject(root) {
+  const codeCounts = countCode(root);
+  const codeFiles = [...codeCounts.values()].reduce((a, b) => a + b, 0);
+  const ecosystem = ECOSYSTEMS.find((e) => anyFile(root, e.marker)) ?? undefined;
+  const repoTooling = detectRepoTooling(root);
+  const pkg = readJson(join(root, "package.json"));
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const names = Object.keys(deps);
+  const hasDependency = (name) => names.some((n) => n === name || n.startsWith(`${name}/`));
+
+  const frameworks = Object.entries(FRAMEWORKS).filter(([dep]) => hasDependency(dep)).map(([, label]) => label);
+  const databases = Object.entries(DATABASES).filter(([dep]) => hasDependency(dep)).map(([, label]) => label);
+  const testers = Object.entries(TESTERS).filter(([dep]) => hasDependency(dep)).map(([, label]) => label);
+
+  const languages = [];
+  if (existsSync(join(root, "tsconfig.json")) || codeCounts.has(".ts") || codeCounts.has(".tsx")) languages.push("TypeScript");
+  if ([".js", ".jsx", ".mjs", ".cjs"].some((e) => codeCounts.has(e))) languages.push("JavaScript");
+  for (const [ext, label] of [[".py", "Python"], [".go", "Go"], [".rs", "Rust"], [".java", "Java"], [".kt", "Kotlin"], [".rb", "Ruby"], [".php", "PHP"], [".cs", "C#"], [".vue", "Vue"], [".svelte", "Svelte"]]) {
+    if (codeCounts.has(ext) && !languages.includes(label)) languages.push(label);
+  }
+
+  const codeRoots = CODE_ROOTS.filter((dir) => {
+    try {
+      return statSync(join(root, dir)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+  const scripts = pkg?.scripts ?? {};
+  const manager = ecosystem?.manager ?? "npm";
+  const run = (script) => (manager === "npm" || manager === "bun" ? `${manager} run ${script}` : `${manager} ${script}`);
+
+  // An empty `package.json` is not a codebase; a manifest with dependencies, scripts or another ecosystem is.
+  const packageContent =
+    Boolean(pkg) && (Object.keys(deps).length > 0 || Object.keys(scripts).length > 0);
+  const otherEcosystem = Boolean(ecosystem) && !["npm", "bun", "yarn", "pnpm"].includes(ecosystem.manager);
+
+  const commands = {
+    install: ecosystem?.install ?? "",
+    lint: scripts.lint ? run("lint") : "",
+    typecheck: scripts.typecheck ? run("typecheck") : scripts["type-check"] ? run("type-check") : "",
+    test: scripts.test ? run("test") : "",
+    e2e: scripts["test:e2e"] ? run("test:e2e") : "",
+    verify: "node .claude/skills/implement/scripts/verify.ts",
+  };
+
+  // Sensible defaults per ecosystem, only where the repository does not name a command itself.
+  const defaults = {
+    go: { lint: "go vet ./...", typecheck: "go build ./...", test: "go test ./..." },
+    cargo: { lint: "cargo clippy -- -D warnings", typecheck: "cargo check", test: "cargo test" },
+    maven: { test: "mvn -q test" },
+    gradle: { test: "./gradlew test" },
+    bundler: { test: "bundle exec rspec" },
+    composer: { test: "composer test" },
+    pip: { test: "pytest" },
+  };
+  for (const [key, value] of Object.entries(defaults[manager] ?? {})) if (!commands[key]) commands[key] = value;
+
+  return {
+    kind: codeFiles > 0 || packageContent || otherEcosystem ? "brownfield" : "greenfield",
+    packageName: typeof pkg?.name === "string" ? pkg.name : undefined,
+    ecosystem: ecosystem?.language ?? languages[0] ?? "unknown",
+    languages,
+    frameworks: [...new Set(frameworks)],
+    databases: [...new Set(databases)],
+    testers: [...new Set(testers)],
+    packageManager: manager,
+    codeRoots: codeRoots.length ? codeRoots : ["."],
+    codeFiles,
+    scripts,
+    commands,
+    repoTooling,
+  };
+}
+
+export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, detection, extras = [], backlog = "local", jiraProject = "", githubRepo = "" }) {
+  const stackSummary = [
+    ...detection.languages,
+    ...detection.frameworks,
+    ...detection.databases,
+  ].filter((v, i, a) => a.indexOf(v) === i).join(", ") || "unknown";
+  const provider = ["local", "github", "jira"].includes(backlog) ? backlog : "local";
+
+  return {
+    name: name || basename(root),
+    kind: kind || detection.kind,
+    domain: name || basename(root),
+    languages: {
+      artifacts: artifactLanguage || "en",
+      ui: uiLanguage || "en",
+      uiAdditional: [],
+    },
+    stack: {
+      summary: stackSummary,
+      languages: detection.languages,
+      frameworks: detection.frameworks,
+      databases: detection.databases,
+      testers: detection.testers,
+      packageManager: detection.packageManager,
+    },
+    repo: {
+      defaultBranch: "main",
+      codeRoots: detection.codeRoots,
+      // Monorepo build tooling. The workflow uses this instead of assuming one package at the root:
+      // commands per package, dependency edges, consumers of a shared library and affected tests.
+      tooling: detection.repoTooling ?? { kind: "none", config: "", workspaces: [], manager: "", monorepo: false },
+    },
+    commands: detection.commands,
+    review: {
+      preview: "none",
+      pullRequest: existsSync(join(root, ".git")) ? "gh" : "none",
+    },
+    // Where stories live. `local` keeps docs/stories/ as the backlog; `github`/`jira` make the tracker the source of
+    // truth and docs/stories/ its local mirror. The defaults are deliberately generic – edit them after init.
+    // Keep the maps in sync with .claude/lib/config.ts (DEFAULT_STATUS_MAP / DEFAULT_PRIORITY_MAP).
+    backlog: {
+      provider,
+      github: {
+        repo: githubRepo,
+        labelPrefix: "kataster",
+      },
+      jira: {
+        mcpServer: "mcp-atlassian",
+        project: jiraProject,
+        issueType: "Story",
+        labelPrefix: "kataster",
+        statusMap: {
+          draft: "To Do",
+          review: "In Review",
+          ready: "Ready",
+          "in-progress": "In Progress",
+          done: "Done",
+          superseded: "Won't Do",
+        },
+        priorityMap: {
+          must: "Highest",
+          should: "High",
+          could: "Medium",
+          wont: "Lowest",
+        },
+      },
+    },
+    setup: {
+      envFile: "",
+      envHint: "",
+    },
+    workflow: {
+      version: "0.1.0",
+      extras,
+      installedAt: new Date().toISOString(),
+    },
+  };
+}