swallowkit 1.0.0-beta.9 → 1.0.0

package/dist/core/project/validation.js

@@ -0,0 +1,274 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateProject = validateProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const manifest_1 = require("./manifest");
+const model_parser_1 = require("../scaffold/model-parser");
+function pushViolation(violations, violation) {
+    violations.push(violation);
+}
+function hasScaffoldedEntities(manifest) {
+    return manifest.entities.length > 0;
+}
+function validateRequiredPaths(manifest, violations) {
+    const requiredModules = manifest.modules.filter((module) => ["shared-models", "bff", "functions"].includes(module.kind));
+    for (const module of requiredModules) {
+        if (!module.exists) {
+            pushViolation(violations, {
+                code: "missing-required-module",
+                severity: "error",
+                message: `Required module path is missing: ${module.rootPath}`,
+                location: { path: module.rootPath },
+                suggestedFix: "Initialize or restore the standard SwallowKit project directories before generating code.",
+            });
+        }
+    }
+    if (hasScaffoldedEntities(manifest) && !manifest.artifacts.callFunctionHelperExists) {
+        pushViolation(violations, {
+            code: "missing-call-function-helper",
+            severity: "warning",
+            message: "BFF helper lib/api/call-function.ts is missing.",
+            location: { path: manifest.artifacts.callFunctionHelperPath },
+            suggestedFix: "Run scaffold to regenerate the BFF helper.",
+        });
+    }
+}
+function validateSchemaNaming(entity, violations) {
+    const expectedFileName = `${(0, model_parser_1.toKebabCase)(entity.name)}.ts`;
+    if (!entity.filePath.endsWith(expectedFileName)) {
+        pushViolation(violations, {
+            code: "naming-model-file",
+            severity: "warning",
+            message: `Model file should match the entity name in kebab-case: expected ${expectedFileName}.`,
+            location: { path: entity.filePath, entity: entity.name },
+            suggestedFix: `Rename the model file to ${expectedFileName} to keep generator conventions deterministic.`,
+        });
+    }
+    const camelSchema = `${(0, model_parser_1.toCamelCase)(entity.name)}Schema`;
+    if (entity.schemaName !== entity.name && entity.schemaName !== camelSchema) {
+        pushViolation(violations, {
+            code: "naming-schema-export",
+            severity: "warning",
+            message: `Schema export should be ${entity.name} or ${camelSchema}. Found ${entity.schemaName}.`,
+            location: { path: entity.filePath, entity: entity.name },
+            suggestedFix: "Use either the PascalCase Zod export or the camelCase Schema suffix pattern supported by SwallowKit.",
+        });
+    }
+}
+function validateGeneratedArtifacts(manifest, violations) {
+    for (const route of manifest.routes.filter((candidate) => candidate.kind === "entity")) {
+        if (!route.exists) {
+            pushViolation(violations, {
+                code: route.surface === "bff" ? "missing-bff-route" : "missing-functions-artifact",
+                severity: "warning",
+                message: `${route.surface === "bff" ? "BFF route" : "Functions artifact"} is missing for ${route.entityName}.`,
+                location: {
+                    path: route.filePath,
+                    entity: route.entityName,
+                },
+                suggestedFix: `Run scaffold for ${route.entityName} to regenerate ${route.surface === "bff" ? "API routes" : "Functions code"}.`,
+            });
+        }
+    }
+    if (hasScaffoldedEntities(manifest) &&
+        manifest.backendLanguage !== "typescript" &&
+        manifest.artifacts.openApiSpecs.length === 0) {
+        pushViolation(violations, {
+            code: "missing-openapi-artifacts",
+            severity: "warning",
+            message: `No OpenAPI export or native schema artifacts were found for ${manifest.backendLanguage} backend generation.`,
+            location: { path: "functions/openapi" },
+            suggestedFix: "Run scaffold to regenerate the OpenAPI export and native backend schema artifacts.",
+        });
+    }
+}
+function validateLayeringViolations(projectRoot, violations) {
+    const apiDir = path.join(projectRoot, "app", "api");
+    const modelsDir = path.join(projectRoot, "shared", "models");
+    if (fs.existsSync(apiDir)) {
+        for (const filePath of walkFiles(apiDir, [".ts", ".tsx"])) {
+            const content = fs.readFileSync(filePath, "utf-8");
+            if (content.includes("@azure/cosmos") || content.match(/from\s+['"].*functions\//)) {
+                pushViolation(violations, {
+                    code: "forbidden-bff-dependency",
+                    severity: "error",
+                    message: "BFF files must not depend directly on Azure Cosmos or Functions implementation paths.",
+                    location: { path: path.relative(projectRoot, filePath).replace(/\\/g, "/") },
+                    suggestedFix: "Keep app/api as a pure BFF layer and call the backend through generated helpers instead.",
+                });
+            }
+        }
+    }
+    if (fs.existsSync(modelsDir)) {
+        for (const filePath of walkFiles(modelsDir, [".ts", ".tsx"])) {
+            const content = fs.readFileSync(filePath, "utf-8");
+            if (content.match(/from\s+['"].*(app\/|functions\/|lib\/api\/)/)) {
+                pushViolation(violations, {
+                    code: "forbidden-model-layer-import",
+                    severity: "error",
+                    message: "Shared models must not import from app/, functions/, or lib/api/ layers.",
+                    location: { path: path.relative(projectRoot, filePath).replace(/\\/g, "/") },
+                    suggestedFix: "Keep shared/models framework-agnostic so generators can reuse them across all layers.",
+                });
+            }
+        }
+    }
+}
+function validateManifestDrift(projectRoot, loadedManifest, rebuiltManifest, violations) {
+    const sameEntitySet = JSON.stringify(loadedManifest.entities.map((entity) => entity.name).sort()) ===
+        JSON.stringify(rebuiltManifest.entities.map((entity) => entity.name).sort());
+    const sameRouteSet = JSON.stringify(loadedManifest.routes.map((route) => route.name).sort()) ===
+        JSON.stringify(rebuiltManifest.routes.map((route) => route.name).sort());
+    if (!sameEntitySet || !sameRouteSet) {
+        pushViolation(violations, {
+            code: "manifest-out-of-date",
+            severity: "warning",
+            message: `${manifest_1.SWALLOWKIT_MANIFEST_PATH} is out of date with the current project structure.`,
+            location: { path: manifest_1.SWALLOWKIT_MANIFEST_PATH },
+            suggestedFix: "Run a SwallowKit generator command or refresh the manifest so inspection and validation use current metadata.",
+        });
+    }
+}
+function walkFiles(directory, extensions) {
+    const collected = [];
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            collected.push(...walkFiles(entryPath, extensions));
+            continue;
+        }
+        if (extensions.some((extension) => entry.name.endsWith(extension))) {
+            collected.push(entryPath);
+        }
+    }
+    return collected;
+}
+const VERIFIER_STUB_MARKER = /External token verifier(?: for \S+)? is not configured/;
+/**
+ * external-token スキームの verifier が生成スタブのまま (fail-closed throw のみ) だと
+ * typecheck / verify は通るのに実行時は必ず 401/503 になる。
+ * 「認証は生成されたが動かない」状態を warning として可視化する。
+ */
+function validateExternalTokenVerifierStubs(projectRoot, manifest, violations) {
+    const auth = manifest.auth;
+    const hasExternalToken = auth?.provider === "external-token" ||
+        Object.values(auth?.schemes ?? {}).some((scheme) => scheme.provider === "external-token");
+    if (!hasExternalToken)
+        return;
+    const candidates = [
+        path.join("functions", "src", "auth", "external-token-verifier.ts"),
+        path.join("functions", "Auth", "ExternalTokenVerifier.cs"),
+        path.join("functions", "auth", "external_token_verifier.py"),
+    ];
+    const schemeDirs = [
+        { root: path.join("functions", "src", "auth", "schemes"), file: "verifier.ts" },
+        { root: path.join("functions", "Auth", "Schemes"), file: "ExternalTokenVerifier.cs" },
+        { root: path.join("functions", "auth", "schemes"), file: "verifier.py" },
+    ];
+    for (const { root, file } of schemeDirs) {
+        const absoluteRoot = path.join(projectRoot, root);
+        if (!fs.existsSync(absoluteRoot))
+            continue;
+        for (const entry of fs.readdirSync(absoluteRoot, { withFileTypes: true })) {
+            if (entry.isDirectory())
+                candidates.push(path.join(root, entry.name, file));
+        }
+    }
+    for (const relativePath of candidates) {
+        const absolutePath = path.join(projectRoot, relativePath);
+        if (!fs.existsSync(absolutePath))
+            continue;
+        const content = fs.readFileSync(absolutePath, "utf-8");
+        if (VERIFIER_STUB_MARKER.test(content)) {
+            pushViolation(violations, {
+                code: "auth-verifier-stub",
+                severity: "warning",
+                message: "External token verifier is still the generated stub; it fails closed, so external-token authentication cannot succeed at runtime.",
+                location: { path: relativePath.replace(/\\/g, "/") },
+                suggestedFix: "Implement the verifier against your identity provider. The file is yours to edit (generated-once).",
+            });
+        }
+    }
+}
+async function validateProject(projectRoot = process.cwd()) {
+    const loaded = await (0, manifest_1.loadProjectManifest)(projectRoot);
+    const rebuilt = await (0, manifest_1.buildProjectManifest)(projectRoot);
+    const violations = [];
+    validateRequiredPaths(loaded.manifest, violations);
+    for (const error of loaded.manifest.configValidation.errors) {
+        pushViolation(violations, {
+            code: "config-validation",
+            severity: "error",
+            message: error,
+            location: loaded.manifest.configPath ? { path: loaded.manifest.configPath } : undefined,
+            suggestedFix: "Fix the SwallowKit config so generators and validators have a stable project definition.",
+        });
+    }
+    const namedPolicies = loaded.manifest.auth?.authorization?.policies ?? {};
+    for (const entity of loaded.manifest.entities) {
+        const policy = entity.authPolicy;
+        if (!policy)
+            continue;
+        const references = [policy.policy, typeof policy.read === "string" ? policy.read : undefined, typeof policy.write === "string" ? policy.write : undefined].filter((value) => Boolean(value));
+        for (const name of references) {
+            if (!namedPolicies[name])
+                pushViolation(violations, {
+                    code: "undefined-auth-policy",
+                    severity: "error",
+                    message: `Model '${entity.name}' references undefined authorization policy '${name}'.`,
+                    location: { path: entity.filePath, entity: entity.name },
+                    suggestedFix: `Define auth.authorization.policies.${name} or update the model authPolicy reference.`,
+                });
+        }
+    }
+    for (const entity of loaded.manifest.entities) {
+        validateSchemaNaming(entity, violations);
+    }
+    validateGeneratedArtifacts(loaded.manifest, violations);
+    validateLayeringViolations(projectRoot, violations);
+    validateExternalTokenVerifierStubs(projectRoot, loaded.manifest, violations);
+    if (loaded.source === "file") {
+        validateManifestDrift(projectRoot, loaded.manifest, rebuilt.manifest, violations);
+    }
+    return {
+        manifest: loaded.manifest,
+        manifestSource: loaded.source,
+        diagnostics: [...loaded.diagnostics, ...rebuilt.diagnostics],
+        violations: violations.sort((left, right) => left.code.localeCompare(right.code)),
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/core/project/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/core/project/validation.ts"],"names":[],"mappings":"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"}

package/dist/core/project/workflows.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Workflow Docs & Agent Skills
+ *
+ * 同一のランブック コンテンツから 2 つの表面を生成する:
+ * - `.swallowkit/workflows/*.md` — Coding Agent 非依存の Markdown ランブック
+ *   (AGENTS.md / CLAUDE.md / copilot-instructions.md から参照される)
+ * - `.github/skills/<name>/SKILL.md` — Agent Skills (agentskills.io open standard)。
+ *   GitHub Copilot (VS Code / CLI / cloud agent) 等が name/description で自動発見し、
+ *   タスクに関連するときだけ本文をロードする (progressive disclosure)。
+ */
+export interface WorkflowDoc {
+    /** `.swallowkit/workflows/` 配下のファイル名 */
+    fileName: string;
+    title: string;
+    content: string;
+    /**
+     * Agent Skills のスキル名 (ディレクトリ名と一致必須)。
+     * agentskills.io 仕様: 小文字英数字とハイフンのみ・64 文字以内。
+     * undefined の場合はスキルとして出力しない (README など)。
+     */
+    skillName?: string;
+    /**
+     * Agent Skills の description (最大 1024 文字)。
+     * 「何をするか」と「いつ使うか」の両方を書く。
+     */
+    skillDescription?: string;
+}
+export declare function buildWorkflowDocs(runCmd: string): WorkflowDoc[];
+export declare const WORKFLOWS_DIR: string;
+export declare const SKILLS_DIR: string;
+/** `.swallowkit/workflows/*.md` を書き出し、書き込んだ相対パスを返す。 */
+export declare function writeWorkflowDocs(projectDir: string, runCmd: string): string[];
+/** Agent Skills (agentskills.io) の SKILL.md コンテンツを組み立てる。 */
+export declare function buildAgentSkills(runCmd: string): Array<{
+    skillName: string;
+    content: string;
+}>;
+/**
+ * `.github/skills/<name>/SKILL.md` を書き出し、書き込んだ相対パスを返す。
+ * agentskills.io 仕様: ディレクトリ名は frontmatter の name と一致必須。
+ */
+export declare function writeAgentSkills(projectDir: string, runCmd: string): string[];
+//# sourceMappingURL=workflows.d.ts.map

package/dist/core/project/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../../src/core/project/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CA4N/D;AAED,eAAO,MAAM,aAAa,QAAwC,CAAC;AACnE,eAAO,MAAM,UAAU,QAAiC,CAAC;AAEzD,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAS9E;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAS9F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAS7E"}

package/dist/core/project/workflows.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * Workflow Docs & Agent Skills
+ *
+ * 同一のランブック コンテンツから 2 つの表面を生成する:
+ * - `.swallowkit/workflows/*.md` — Coding Agent 非依存の Markdown ランブック
+ *   (AGENTS.md / CLAUDE.md / copilot-instructions.md から参照される)
+ * - `.github/skills/<name>/SKILL.md` — Agent Skills (agentskills.io open standard)。
+ *   GitHub Copilot (VS Code / CLI / cloud agent) 等が name/description で自動発見し、
+ *   タスクに関連するときだけ本文をロードする (progressive disclosure)。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILLS_DIR = exports.WORKFLOWS_DIR = void 0;
+exports.buildWorkflowDocs = buildWorkflowDocs;
+exports.writeWorkflowDocs = writeWorkflowDocs;
+exports.buildAgentSkills = buildAgentSkills;
+exports.writeAgentSkills = writeAgentSkills;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function buildWorkflowDocs(runCmd) {
+    const addModel = {
+        fileName: "add-model.md",
+        title: "Add a new model (autonomous loop)",
+        skillName: "swallowkit-add-model",
+        skillDescription: "Add a new data model to a SwallowKit project and deterministically derive CRUD Functions, BFF routes, UI pages, and Cosmos DB infra from it using the plan/apply/verify loop. Use when asked to add a model, entity, resource, table, or a new CRUD feature.",
+        content: `# Workflow: Add a new model
+
+Goal: add a data model and derive CRUD/BFF/UI/infra deterministically.
+
+## Responsibility boundary
+
+- **You author freely**: the model schema (\`shared/models/<name>.ts\`) and any business logic.
+- **SwallowKit generates deterministically**: Functions CRUD, BFF routes, UI pages, OpenAPI, Bicep containers.
+- Query the full contract: \`${runCmd} swallowkit machine inspect boundaries\`
+
+## Steps
+
+1. Create the model file (deterministic template):
+   \`${runCmd} swallowkit machine generate model <name> --overwrite never\`
+2. Edit \`shared/models/<name>.ts\` — add domain fields (free-form authoring).
+3. Compute the change plan (writes nothing):
+   \`${runCmd} swallowkit machine plan scaffold <name>\`
+   - \`status: "requires-human"\` → review \`data.conflicts\`; only proceed with \`--approve\` if overwriting is intended.
+4. Apply:
+   \`${runCmd} swallowkit machine apply scaffold --plan <planId>\`
+5. Verify:
+   \`${runCmd} swallowkit machine verify project\`
+   - \`summary.done: false\` → \`${runCmd} swallowkit machine explain failure\` and repair, then re-verify.
+6. If \`dev-seeds/\` exists, update seed JSON for the new model. Seeds are only
+   applied by \`${runCmd} swallowkit dev --seed-env <environment>\` — editing the
+   JSON alone does nothing.
+
+## Terminal states
+
+| status | meaning | next |
+|--------|---------|------|
+| complete | operation finished | continue |
+| in-progress | more work remains (e.g. failing checks) | follow nextActions |
+| blocked | prerequisite missing (e.g. stale plan) | re-plan |
+| requires-human | approval needed | ask the human, or pass --approve when instructed |
+| failed | operation failed | inspect error.details |
+`,
+    };
+    const modifyModel = {
+        fileName: "modify-model.md",
+        title: "Modify an existing model schema",
+        skillName: "swallowkit-modify-model",
+        skillDescription: "Change an existing Zod model schema in a SwallowKit project and re-align every generated artifact (Functions, BFF, UI, infra) via drift inspection and plan/apply regeneration. Use when asked to add/remove/rename model fields, change validation rules, or when inspect drift reports schema-drift.",
+        content: `# Workflow: Modify an existing model
+
+Goal: change a schema and re-align every generated artifact.
+
+## Steps
+
+1. Edit \`shared/models/<name>.ts\` (free-form authoring).
+2. Check what drifted:
+   \`${runCmd} swallowkit machine inspect drift\`
+   - \`schema-drift\` findings list the models whose artifacts are stale.
+3. Plan the regeneration:
+   \`${runCmd} swallowkit machine plan scaffold <name>\`
+   - Conflicts mean generated files were hand-edited after generation. Decide: keep the hand-edit (move the logic to an ai-authored file first) or overwrite with \`--approve\`.
+4. Apply: \`${runCmd} swallowkit machine apply scaffold --plan <planId>\`
+5. Verify: \`${runCmd} swallowkit machine verify project\`
+
+## Guardrail
+
+Never hand-edit managed artifacts to implement schema changes — always change the model
+and regenerate. Hand-edits are detected as drift and block unattended overwrites.
+`,
+    };
+    const addAuth = {
+        fileName: "add-auth.md",
+        title: "Add authentication (plan/apply with config ownership rules)",
+        skillName: "swallowkit-add-auth",
+        skillDescription: "Add authentication (custom-jwt, Azure Static Web Apps built-in, or external-token) to a SwallowKit project via plan/apply auth, including the config ownership rules (never hand-write auth.schemes; hand-edit policies and allowedProviders after apply) and post-apply steps. Use when asked to add login, authentication, authorization, roles, or a named auth scheme.",
+        content: `# Workflow: Add authentication
+
+Goal: introduce an auth scheme deterministically and finish the manual follow-ups.
+
+## Config ownership (critical)
+
+- \`auth.schemes\` is **owned by plan/apply auth. Never hand-write scheme entries** —
+  a pre-written scheme makes planning fail with \`already exists\`.
+- \`auth.authorization.policies\` and \`swa.allowedProviders\` are **hand-edited after
+  apply** (the config is an extension point; this is the expected workflow).
+
+## Steps
+
+1. Check what already exists: \`${runCmd} swallowkit machine inspect capabilities\`
+   (authentication section) and the current \`auth\` block in swallowkit.config.
+2. Plan (writes nothing):
+   \`${runCmd} swallowkit machine plan auth --provider <custom-jwt|swa|external-token> [--scheme <name>] [--allowed-providers github,aad]\`
+3. Apply:
+   \`${runCmd} swallowkit machine apply auth --plan <planId>\`
+4. Follow the returned \`nextActions\`:
+   - Define \`auth.authorization.policies\` referencing the scheme (hand-edit).
+   - swa: confirm \`swa.allowedProviders\` — generated login URLs use the first entry.
+   - external-token: implement the generated verifier stub. It fails closed and
+     **verify passes with the stub**, so a green verify does not mean the auth
+     flow works (a \`auth-verifier-stub\` warning is surfaced while unmodified).
+5. Add \`authPolicy\` to models that need guards, then re-run plan/apply scaffold
+   for them.
+6. Verify: \`${runCmd} swallowkit machine verify project\`
+
+## Scope guardrail
+
+Generated CRUD enforces authentication and roles but does **not** scope rows to
+the caller. Owner-scoped behavior belongs in ai-authored endpoints that derive
+the scoping key from the verified principal, never from the request body.
+`,
+    };
+    const verifyRepair = {
+        fileName: "verify-and-repair.md",
+        title: "Verify and repair loop",
+        skillName: "swallowkit-verify-repair",
+        skillDescription: "Converge a SwallowKit project to a verified state: run structure/drift/typecheck (and build/lint/test) checks, read evidence with explain failure, repair, and repeat. Use after any code or schema change, when verification fails, when the build/lint/tests are broken, or before finishing a task.",
+        content: `# Workflow: Verify and repair
+
+Goal: converge the project to a verified state after any change.
+
+## Loop
+
+1. \`${runCmd} swallowkit machine verify project\`
+   - default checks: structure, drift, typecheck (+ project-specific checks from swallowkit.config \`verify.checks\`)
+   - opt-in heavier checks: \`--checks structure,drift,typecheck,build,lint,test\`
+2. If \`summary.done\` is false:
+   - \`${runCmd} swallowkit machine explain failure\` → evidence (logTail, findings, violations) and suggestedActions per check.
+   - Repair:
+     - \`drift\` failures → follow each finding's \`repairAction\` (usually re-run plan/apply scaffold).
+     - \`structure\` failures → follow \`suggestedFix\` per violation.
+     - \`typecheck\`/\`build\`/\`lint\`/\`test\` failures → fix the code in ai-authored files.
+3. Repeat until \`summary.done: true\`.
+
+## Exit criteria
+
+Stop and ask a human when:
+- the same check fails 3 times in a row with the same evidence, or
+- a repair would require overwriting hand-edited files (\`requires-human\`).
+`,
+    };
+    const provision = {
+        fileName: "provision.md",
+        title: "Provision Azure resources (plan/apply with approval gate)",
+        skillName: "swallowkit-provision",
+        skillDescription: "Provision Azure resources (Static Web Apps, Functions, Cosmos DB) for a SwallowKit project using the two-phase plan/apply flow with a mandatory human approval gate. Use when asked to deploy infrastructure, provision Azure, create resource groups, or run Bicep deployments.",
+        content: `# Workflow: Provision Azure resources
+
+Goal: deploy the Bicep infrastructure with an explicit human approval gate.
+
+## Rules
+
+- Provisioning **always** requires human approval — \`plan provision\` returns
+  \`status: "requires-human"\` and \`requiresApproval: true\` by design.
+- Never pass \`--approve\` to \`apply provision\` unless a human explicitly
+  instructed you to provision in this session.
+- Inspect infra locally first — no \`az\` calls are needed for inspection.
+
+## Steps
+
+1. Inspect the infrastructure definition (pure local Bicep analysis):
+   \`${runCmd} swallowkit machine inspect infra\`
+   - review parameters, modules, outputs, and container wiring warnings.
+2. Compute the provisioning plan (no resources are created):
+   \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region>\`
+   - optional: \`--what-if\` to include an \`az deployment ... what-if\` preview.
+   - the plan lists the exact \`az\` commands that would run.
+3. Present the plan to the human and wait for explicit approval.
+4. Only after approval:
+   \`${runCmd} swallowkit machine apply provision --plan <planId> --approve\`
+5. Verify the deployment outputs and report them.
+
+## Terminal states
+
+\`apply provision\` without \`--approve\` fails with \`approval-required\` —
+this is the guardrail working as intended, not an error to work around.
+`,
+    };
+    const index = {
+        fileName: "README.md",
+        title: "SwallowKit agent workflows",
+        content: `# SwallowKit Agent Workflows
+
+Agent-agnostic runbooks for autonomous development loops. Machine-readable
+interfaces (\`swallowkit machine ...\` / MCP \`swallowkit_*\` tools) return a
+\`status\` terminal state and \`nextActions\`, so agents can chain steps without
+parsing human-oriented output.
+
+These runbooks are also installed as Agent Skills (agentskills.io format)
+under \`.github/skills/\` so skills-aware agents load them automatically.
+
+| Workflow | File | Skill |
+|----------|------|-------|
+| Add a new model | [add-model.md](./add-model.md) | \`swallowkit-add-model\` |
+| Modify an existing model | [modify-model.md](./modify-model.md) | \`swallowkit-modify-model\` |
+| Add authentication | [add-auth.md](./add-auth.md) | \`swallowkit-add-auth\` |
+| Verify and repair | [verify-and-repair.md](./verify-and-repair.md) | \`swallowkit-verify-repair\` |
+| Provision Azure resources | [provision.md](./provision.md) | \`swallowkit-provision\` |
+
+## Responsibility boundary (summary)
+
+- **ai-authored** (write freely): \`shared/models/\`, business logic, custom pages/components, tests.
+- **deterministic** (never hand-edit): artifacts generated by SwallowKit (see \`.swallowkit/artifacts.json\`) and \`.swallowkit/\` metadata. Change models/config and regenerate via plan/apply.
+- **shared** (edit outside markers): \`infra/main.bicep\`, \`functions/function_app.py\`, \`shared/index.ts\`.
+
+Full machine-readable contract: \`${runCmd} swallowkit machine inspect boundaries\`
+`,
+    };
+    return [index, addModel, modifyModel, addAuth, verifyRepair, provision];
+}
+exports.WORKFLOWS_DIR = path.join(".swallowkit", "workflows");
+exports.SKILLS_DIR = path.join(".github", "skills");
+/** `.swallowkit/workflows/*.md` を書き出し、書き込んだ相対パスを返す。 */
+function writeWorkflowDocs(projectDir, runCmd) {
+    const dir = path.join(projectDir, exports.WORKFLOWS_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    const written = [];
+    for (const doc of buildWorkflowDocs(runCmd)) {
+        fs.writeFileSync(path.join(dir, doc.fileName), doc.content, "utf-8");
+        written.push(path.posix.join(".swallowkit", "workflows", doc.fileName));
+    }
+    return written;
+}
+/** Agent Skills (agentskills.io) の SKILL.md コンテンツを組み立てる。 */
+function buildAgentSkills(runCmd) {
+    return buildWorkflowDocs(runCmd)
+        .filter((doc) => Boolean(doc.skillName && doc.skillDescription))
+        .map((doc) => ({
+        skillName: doc.skillName,
+        content: `---\nname: ${doc.skillName}\ndescription: ${doc.skillDescription}\nmetadata:\n  generator: swallowkit\n---\n\n${doc.content}`,
+    }));
+}
+/**
+ * `.github/skills/<name>/SKILL.md` を書き出し、書き込んだ相対パスを返す。
+ * agentskills.io 仕様: ディレクトリ名は frontmatter の name と一致必須。
+ */
+function writeAgentSkills(projectDir, runCmd) {
+    const written = [];
+    for (const skill of buildAgentSkills(runCmd)) {
+        const dir = path.join(projectDir, exports.SKILLS_DIR, skill.skillName);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "SKILL.md"), skill.content, "utf-8");
+        written.push(path.posix.join(".github", "skills", skill.skillName, "SKILL.md"));
+    }
+    return written;
+}
+//# sourceMappingURL=workflows.js.map

package/dist/core/project/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../../src/core/project/workflows.ts"],"names":[],"mappings":"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"}