swallowkit 1.0.0-beta.57 → 1.0.0-beta.58

package/src/core/project/agent-instructions.ts

@@ -0,0 +1,167 @@
+import * as fs from "fs";
+import * as path from "path";
+import { BackendLanguage } from "../../types";
+import { PackageManager } from "../../utils/package-manager";
+
+export interface AgentInstructionContext {
+  projectName: string;
+  backendLanguage: BackendLanguage;
+  packageManager: PackageManager;
+}
+
+export interface AgentInstructionDocuments {
+  agentsMd: string;
+  claudeMd: string;
+  copilotInstructions: string;
+  pathSpecificInstructions: Record<string, string>;
+}
+
+export const AGENT_TEMPLATE_FILES = {
+  agentsMd: "AGENTS.md",
+  claudeMd: "CLAUDE.md",
+  copilotInstructions: "copilot-instructions.md",
+  sharedModelsInstructions: "shared-models.instructions.md",
+  bffRoutesInstructions: "bff-routes.instructions.md",
+  azureFunctionsInstructions: "azure-functions.instructions.md",
+} as const;
+
+const BACKEND_LANGUAGE_LABELS: Record<BackendLanguage, string> = {
+  typescript: "TypeScript",
+  csharp: "C#",
+  python: "Python",
+};
+
+function getTemplatePath(fileName: string): string {
+  const candidates = [
+    path.join(__dirname, "agent-templates", fileName),
+    path.join(__dirname, "../../../src/core/project/agent-templates", fileName),
+  ];
+  const templatePath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!templatePath) {
+    throw new Error(`Agent instruction template not found: ${fileName}`);
+  }
+  return templatePath;
+}
+
+export function readAgentInstructionTemplate(fileName: string): string {
+  return fs.readFileSync(getTemplatePath(fileName), "utf-8").replace(/\r\n/g, "\n");
+}
+
+function getFunctionsStructureLine(backendLanguage: BackendLanguage): string {
+  if (backendLanguage === "typescript") {
+    return "│   └── src/               # HTTP trigger handlers with Cosmos DB bindings";
+  }
+  if (backendLanguage === "csharp") {
+    return "│   ├── Crud/              # C# HTTP trigger handlers\n│   └── generated/         # Native-generated C# schema assets";
+  }
+  return "│   ├── blueprints/        # Python HTTP trigger handlers\n│   └── generated/         # Native-generated Python schema assets";
+}
+
+function getBackendRules(backendLanguage: BackendLanguage): string {
+  if (backendLanguage === "typescript") {
+    return [
+      "- All backend business logic and data access live in `functions/src/`.",
+      "- Prefer Azure Functions Cosmos DB input/output bindings for reads and writes.",
+      "- Use the Cosmos DB SDK directly only where bindings do not support the operation, such as deletes.",
+      "- Validate data against the shared Zod schemas before persistence.",
+    ].join("\n");
+  }
+  return [
+    "- All backend business logic and data access live in `functions/`.",
+    `- SwallowKit derives OpenAPI and native ${BACKEND_LANGUAGE_LABELS[backendLanguage]} schema assets from the Zod source of truth.`,
+    "- Keep custom business logic in ai-authored locations identified by the current boundary contract.",
+  ].join("\n");
+}
+
+function interpolateTemplate(template: string, context: AgentInstructionContext): string {
+  const runCmd = context.packageManager === "pnpm" ? "pnpm" : "npx";
+  const replacements: Record<string, string> = {
+    projectName: context.projectName,
+    backendLanguageLabel: BACKEND_LANGUAGE_LABELS[context.backendLanguage],
+    functionsStructureLine: getFunctionsStructureLine(context.backendLanguage),
+    backendRules: getBackendRules(context.backendLanguage),
+    pm: context.packageManager,
+    runCmd,
+  };
+
+  const result = template.replace(/\{\{([A-Za-z]+)\}\}/g, (placeholder, key: string) => {
+    const replacement = replacements[key];
+    if (replacement === undefined) {
+      throw new Error(`Unknown Agent instruction placeholder: ${placeholder}`);
+    }
+    return replacement;
+  });
+
+  if (/\{\{[^}]+\}\}/.test(result)) {
+    throw new Error("Unresolved Agent instruction template placeholder");
+  }
+  return result;
+}
+
+function buildTemplate(fileName: string, context: AgentInstructionContext): string {
+  return interpolateTemplate(readAgentInstructionTemplate(fileName), context);
+}
+
+export function buildAgentsMd(context: AgentInstructionContext): string {
+  return buildTemplate(AGENT_TEMPLATE_FILES.agentsMd, context);
+}
+
+export function buildClaudeMd(context: AgentInstructionContext): string {
+  return buildTemplate(AGENT_TEMPLATE_FILES.claudeMd, context);
+}
+
+export function buildCopilotInstructions(context: AgentInstructionContext): string {
+  return buildTemplate(AGENT_TEMPLATE_FILES.copilotInstructions, context);
+}
+
+export function buildPathSpecificInstructions(
+  context: AgentInstructionContext
+): Record<string, string> {
+  return {
+    [AGENT_TEMPLATE_FILES.sharedModelsInstructions]: buildTemplate(
+      AGENT_TEMPLATE_FILES.sharedModelsInstructions,
+      context
+    ),
+    [AGENT_TEMPLATE_FILES.bffRoutesInstructions]: buildTemplate(
+      AGENT_TEMPLATE_FILES.bffRoutesInstructions,
+      context
+    ),
+    [AGENT_TEMPLATE_FILES.azureFunctionsInstructions]: buildTemplate(
+      AGENT_TEMPLATE_FILES.azureFunctionsInstructions,
+      context
+    ),
+  };
+}
+
+export function buildAgentInstructionDocuments(
+  context: AgentInstructionContext
+): AgentInstructionDocuments {
+  return {
+    agentsMd: buildAgentsMd(context),
+    claudeMd: buildClaudeMd(context),
+    copilotInstructions: buildCopilotInstructions(context),
+    pathSpecificInstructions: buildPathSpecificInstructions(context),
+  };
+}
+
+export function writeAgentInstructionFiles(
+  projectDir: string,
+  context: AgentInstructionContext
+): AgentInstructionDocuments {
+  const documents = buildAgentInstructionDocuments(context);
+  fs.writeFileSync(path.join(projectDir, "AGENTS.md"), documents.agentsMd, "utf-8");
+  fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), documents.claudeMd, "utf-8");
+
+  const githubDir = path.join(projectDir, ".github");
+  const instructionsDir = path.join(githubDir, "instructions");
+  fs.mkdirSync(instructionsDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(githubDir, "copilot-instructions.md"),
+    documents.copilotInstructions,
+    "utf-8"
+  );
+  for (const [fileName, content] of Object.entries(documents.pathSpecificInstructions)) {
+    fs.writeFileSync(path.join(instructionsDir, fileName), content, "utf-8");
+  }
+  return documents;
+}

package/src/core/project/agent-templates/AGENTS.md

@@ -0,0 +1,442 @@
+# AGENTS.md
+
+This project was generated by **SwallowKit**.
+
+SwallowKit is part of this project's architecture and development workflow.
+Treat it as a standing constraint during discovery, requirements clarification,
+specification, planning, ticket decomposition, implementation, verification,
+and review — not only during code generation.
+
+## How SwallowKit Fits Into the Development Process
+
+SwallowKit does **not** own the overall software development process.
+
+If the user or another Agent Skill or framework defines a process for
+requirements discovery, specification, planning, ticketing, TDD,
+implementation, or review, continue to follow that process.
+
+Use SwallowKit as the authoritative project-specific layer for:
+
+- inspecting the current project
+- understanding entities, routes, infrastructure, and responsibility boundaries
+- determining which artifacts may be edited directly
+- performing deterministic generation through plan/apply
+- detecting drift
+- verifying the resulting project
+- enforcing human approval gates for sensitive operations
+
+External development-process skills and SwallowKit are intended to compose.
+
+A process skill decides **how to proceed**.
+SwallowKit determines **how this SwallowKit project can be changed safely and reproducibly**.
+
+## Do Not Assume SwallowKit Capabilities From Memory
+
+SwallowKit evolves over time.
+
+Do not rely on model knowledge or assumptions about what SwallowKit can or
+cannot generate.
+
+When a SwallowKit capability, project structure, or ownership boundary affects
+a design decision, inspect the current project and the currently available
+SwallowKit interfaces before deciding.
+
+Prefer the `swallowkit_*` MCP tools when available.
+
+If MCP is unavailable, use the machine interface:
+
+```bash
+{{runCmd}} swallowkit machine ...
+```
+
+The machine interface is the fallback Agent-facing interface and returns
+structured `status` / `nextActions` suitable for autonomous workflows.
+
+## Inspect Before Asking or Designing
+
+When a task may affect SwallowKit-managed application structure, inspect the
+project before asking the human questions or committing to an implementation
+design.
+
+Use only the inspections relevant to the task. Typical inspections include:
+
+```bash
+{{runCmd}} swallowkit machine inspect project
+{{runCmd}} swallowkit machine inspect entities
+{{runCmd}} swallowkit machine inspect routes
+{{runCmd}} swallowkit machine inspect boundaries
+{{runCmd}} swallowkit machine inspect drift
+{{runCmd}} swallowkit machine inspect infra
+```
+
+Use the equivalent `swallowkit_*` MCP tools when available.
+
+Questions that can be answered from the repository or SwallowKit inspection
+should be answered by the agent instead of being delegated to the human.
+
+Examples:
+
+- Do not ask how generated CRUD layers should be wired if SwallowKit already
+  defines and generates them.
+- Do not propose editing a generated file until responsibility boundaries have
+  been checked.
+- Do not assume an infrastructure capability is unavailable before inspecting
+  the current SwallowKit project and available operations.
+
+## Specification and Planning Guidance
+
+When producing or refining a specification:
+
+- describe user-visible behavior and domain intent
+- define acceptance criteria and important test seams
+- treat SwallowKit's architecture and responsibility boundaries as
+  implementation constraints
+- avoid prematurely describing generated artifacts as manually implemented
+  components
+- do not duplicate work that SwallowKit can deterministically derive from its
+  source of truth
+
+For example, if adding a model field causes SwallowKit to regenerate backend,
+BFF, UI, and infrastructure artifacts, the specification should primarily
+describe the desired end-to-end behavior and the SwallowKit constraint.
+
+It should not imply that every generated layer is an independent manual
+implementation decision.
+
+If whether SwallowKit supports the desired behavior affects the specification,
+inspect the current capabilities before finalizing the spec.
+
+## Ticket Decomposition Guidance
+
+Prefer independently verifiable **vertical slices** of user or system behavior.
+
+Do not split work into horizontal tickets such as:
+
+- schema ticket
+- backend ticket
+- BFF ticket
+- UI ticket
+- infrastructure ticket
+
+merely because those artifacts exist in separate layers.
+
+When SwallowKit deterministically produces those layers, keep them inside the
+same vertical slice whenever they represent one end-to-end behavior.
+
+Example:
+
+```text
+Add priority support to Todo
+  ├─ update the source-of-truth model
+  ├─ use SwallowKit plan/apply to realign managed artifacts
+  ├─ add any required ai-authored business logic
+  ├─ add/update tests
+  └─ verify the project
+```
+
+Ticket boundaries should reflect independently valuable and verifiable
+behavior, not SwallowKit's generated file structure.
+
+## Responsibility Boundary
+
+Before making file-level implementation decisions, inspect the current
+machine-readable boundary contract:
+
+```bash
+{{runCmd}} swallowkit machine inspect boundaries
+```
+
+Treat its current result as authoritative.
+
+The general ownership model is:
+
+### ai-authored
+
+The agent may edit these directly.
+
+Typical examples include:
+
+- source-of-truth models
+- custom business logic
+- custom pages/components
+- tests
+
+### deterministic
+
+Do not hand-edit these artifacts.
+
+They are generated and owned by SwallowKit. Change the appropriate source of
+truth or configuration, then use SwallowKit plan/apply to regenerate them.
+
+Managed artifacts are tracked by SwallowKit metadata such as
+`.swallowkit/artifacts.json`.
+
+### shared
+
+Edit only outside SwallowKit-managed markers.
+
+Always inspect the current boundary contract instead of relying solely on the
+examples in this document.
+
+## Deterministic Changes: Plan → Apply → Verify
+
+For autonomous or agent-driven generation, prefer the SwallowKit two-phase
+workflow.
+
+```text
+inspect
+   ↓
+plan
+   ↓
+evaluate conflicts / approval requirements
+   ↓
+apply
+   ↓
+verify
+```
+
+Example:
+
+```bash
+{{runCmd}} swallowkit machine plan scaffold <model>
+{{runCmd}} swallowkit machine apply scaffold --plan <planId>
+{{runCmd}} swallowkit machine verify project
+```
+
+Do not bypass plan/apply by manually editing deterministic artifacts.
+
+If a plan reports conflicts, determine whether existing hand-written behavior
+must be moved to an ai-authored location or whether overwrite approval is
+required.
+
+Never invent or implicitly grant human approval.
+
+## Model Changes
+
+For an existing model change, the normal pattern is:
+
+```text
+edit source-of-truth model
+        ↓
+inspect drift
+        ↓
+plan scaffold
+        ↓
+resolve conflicts / approvals if any
+        ↓
+apply
+        ↓
+verify
+```
+
+Use the `swallowkit-modify-model` Agent Skill when available.
+
+Otherwise read and follow the equivalent runbook under
+`.swallowkit/workflows/`.
+
+Never repair schema drift by directly patching SwallowKit-managed artifacts.
+
+## New Models / CRUD Features
+
+Use the `swallowkit-add-model` Agent Skill when available.
+
+Otherwise follow the equivalent runbook under `.swallowkit/workflows/`.
+
+The agent may author domain-specific schema fields and custom behavior, but
+SwallowKit should generate framework-owned CRUD artifacts.
+
+Do not manually recreate boilerplate that SwallowKit owns.
+
+## Verification Is a Completion Gate
+
+Before treating an agent-driven implementation as complete, run SwallowKit
+verification:
+
+```bash
+{{runCmd}} swallowkit machine verify project
+```
+
+or the equivalent MCP operation.
+
+Verification covers SwallowKit structural correctness, drift, type correctness,
+and configured project checks.
+
+When verification fails, use the structured failure explanation:
+
+```bash
+{{runCmd}} swallowkit machine explain failure
+```
+
+or its MCP equivalent, then repair the appropriate source and verify again.
+
+Use the `swallowkit-verify-repair` Agent Skill or runbook when applicable.
+
+SwallowKit verification answers:
+
+> Is the SwallowKit project mechanically and structurally valid?
+
+A semantic code review answers different questions:
+
+> Is this implementation well designed?
+> Does it satisfy the specification and user intent?
+
+Therefore, perform SwallowKit verification before treating semantic code review
+as the final quality gate.
+
+## Human Approval Gates
+
+A machine operation may return terminal states such as:
+
+- `complete`
+- `in-progress`
+- `blocked`
+- `requires-human`
+- `failed`
+
+Follow `nextActions`.
+
+When the status is `requires-human`, stop and request the required human
+decision.
+
+Do not reinterpret `requires-human` as an error to work around.
+
+Azure provisioning is a human-approved operation.
+
+Use the `swallowkit-provision` Agent Skill or runbook and never bypass its
+approval gate. A broad request to deploy does not itself grant the explicit
+approval required by that workflow.
+
+## SwallowKit Agent Skills and Runbooks
+
+SwallowKit installs task-specific Agent Skills under:
+
+```text
+.github/skills/
+```
+
+Current workflows include:
+
+- `swallowkit-add-model`
+- `swallowkit-modify-model`
+- `swallowkit-verify-repair`
+- `swallowkit-provision`
+
+Equivalent agent-agnostic runbooks are available under:
+
+```text
+.swallowkit/workflows/
+```
+
+If the runtime supports Agent Skills, use the relevant Skill when the task
+matches. If it does not, read the corresponding runbook.
+
+These task-specific instructions supplement this `AGENTS.md`; they do not
+replace the always-on project contract.
+
+## Architecture
+
+This is a full-stack application deployed on Azure with a TypeScript
+frontend/BFF and an Azure Functions backend in {{backendLanguageLabel}}.
+
+```text
+Frontend (React / Next.js App Router)
+  ↓
+BFF (Next.js API Routes)
+  ↓
+Azure Functions
+  ↓
+Azure Cosmos DB
+```
+
+### Core architecture rules
+
+1. Next.js API routes are a BFF/proxy layer. Do not place application business
+   logic or direct database access there.
+2. Zod schemas under `shared/models/` are the application model source of truth.
+3. Do not duplicate model definitions across layers.
+4. Azure Functions own backend business logic and data access.
+5. SwallowKit-generated artifacts must be changed through their source of truth
+   and deterministic generation workflow, not by hand.
+6. Infrastructure is managed as code with Bicep. Respect SwallowKit ownership
+   markers and boundaries.
+7. Production access to Azure resources must follow the generated security
+   architecture; do not introduce hard-coded credentials or connection strings.
+
+### Backend-specific rules
+
+{{backendRules}}
+
+The backend owns `id`, `createdAt`, and `updatedAt`; never trust client-sent
+values for these fields.
+
+## Project Structure
+
+```text
+{{projectName}}/
+├── app/                    # Next.js App Router
+│   ├── api/                # BFF routes
+│   └── {model}/            # generated/custom UI
+├── functions/              # Azure Functions backend
+{{functionsStructureLine}}
+├── shared/
+│   ├── models/             # Zod source-of-truth models
+│   └── index.ts
+├── lib/
+│   └── api/
+├── components/
+├── infra/                  # Bicep infrastructure
+├── .swallowkit/            # SwallowKit project metadata and runbooks
+├── .github/skills/         # SwallowKit Agent Skills
+├── .mcp.json               # project-scoped SwallowKit MCP bootstrap
+└── AGENTS.md
+```
+
+Inspect the current project rather than assuming every project has exactly the
+same generated structure.
+
+## Naming and Model Conventions
+
+- Model schema files use `shared/models/{kebab-case}.ts`.
+- The Zod schema constant and inferred TypeScript type use the same PascalCase
+  name: `export const Todo = z.object(...); export type Todo = z.infer<typeof Todo>`.
+- Re-export models from `shared/index.ts`.
+- Mark backend-managed fields as optional in source-of-truth schemas.
+- Cosmos DB containers use PascalCase plural names and default to `/id` as the
+  partition key unless the model declares another key.
+
+## Everyday Commands
+
+```bash
+{{pm}} install
+{{runCmd}} swallowkit dev
+{{pm}} run build
+{{pm}} run lint
+{{runCmd}} swallowkit machine verify project
+```
+
+Always invoke SwallowKit using the package-runner convention generated for this
+project. Do not arbitrarily mix package-manager invocation styles.
+
+## Final Rules
+
+Do not:
+
+- rely on remembered SwallowKit capabilities when current inspection can answer
+  the question
+- hand-edit deterministic SwallowKit-managed artifacts
+- bypass plan/apply safety checks
+- bypass human approval gates
+- duplicate model definitions across generated layers
+- move backend business logic into the BFF
+- decompose one end-to-end SwallowKit-generated feature into artificial
+  horizontal tickets solely because multiple generated layers exist
+- consider an implementation complete before SwallowKit verification succeeds
+
+Do:
+
+- inspect before making SwallowKit-dependent design assumptions
+- preserve external development-process workflows
+- use SwallowKit as the deterministic execution and verification layer
+- keep specifications focused on intent and observable behavior
+- prefer vertical, independently verifiable slices
+- verify before final semantic review

package/src/core/project/agent-templates/CLAUDE.md

@@ -0,0 +1,28 @@
+# CLAUDE.md
+
+This is a **SwallowKit** project.
+
+Before discovery, requirements clarification, specification, planning, ticket
+decomposition, implementation, verification, or review, read and follow the
+root `AGENTS.md`.
+
+SwallowKit must be considered before implementation, not only when generating
+code.
+
+Always-on rules:
+
+- Inspect the current project and SwallowKit capabilities before making
+  SwallowKit-dependent assumptions or asking questions the repository can answer.
+- Prefer `swallowkit_*` MCP tools.
+- Fall back to `{{runCmd}} swallowkit machine ...` when MCP is unavailable.
+- Inspect responsibility boundaries before editing framework-related files.
+- Never hand-edit deterministic SwallowKit-managed artifacts.
+- Use plan/apply for deterministic generation.
+- Respect all `requires-human` states and provisioning approval gates.
+- Run SwallowKit verification before considering implementation complete.
+
+Task-specific SwallowKit Agent Skills are available under `.github/skills/`.
+Equivalent agent-agnostic runbooks are available under
+`.swallowkit/workflows/`.
+
+The root `AGENTS.md` is the canonical project contract.

package/src/core/project/agent-templates/azure-functions.instructions.md

@@ -0,0 +1,22 @@
+---
+applyTo: "functions/**"
+---
+
+# Azure Functions — Backend Rules
+
+The root `AGENTS.md` is the canonical contract. Azure Functions own application
+business logic and data access, but generated handlers and contracts may be
+deterministic. Inspect boundaries before choosing an edit location.
+
+- Put custom behavior only in an ai-authored location reported by the current
+  boundary contract.
+- Never directly edit deterministic handlers or generated schema assets.
+- Keep backend contracts aligned with `shared/models/` through MCP-first
+  plan/apply, using the machine interface as fallback.
+- Auto-generate `id`, `createdAt`, and `updatedAt` on the backend. Never trust
+  client-sent values for these fields.
+- Container names use PascalCase plural form and default to `/id` as the
+  partition key unless the source-of-truth model says otherwise.
+- Respect `requires-human` and run SwallowKit verification after changes.
+
+Backend language: {{backendLanguageLabel}}.

package/src/core/project/agent-templates/bff-routes.instructions.md

@@ -0,0 +1,18 @@
+---
+applyTo: "app/api/**"
+---
+
+# BFF API Routes — Rules
+
+The root `AGENTS.md` is the canonical contract. Inspect the current
+responsibility boundary before editing files in this layer.
+
+- `app/api/` is a BFF/proxy layer. Never place business logic, database access,
+  or direct Cosmos DB calls here.
+- Use `callFunction()` from `@/lib/api/call-function` to forward requests to
+  Azure Functions.
+- Input/output validation may use schemas imported from `@{{projectName}}/shared`.
+- Never directly edit a route reported as deterministic. Change its source of
+  truth and use MCP-first plan/apply, with the machine interface as fallback.
+- Edit shared artifacts only outside managed markers.
+- Respect `requires-human` and run SwallowKit verification after changes.

package/src/core/project/agent-templates/copilot-instructions.md

@@ -0,0 +1,24 @@
+# Copilot Instructions
+
+This is a **SwallowKit** project.
+
+Read and follow the root `AGENTS.md` as the canonical project contract.
+
+SwallowKit applies during discovery, requirements clarification, specification,
+planning, ticket decomposition, implementation, verification, and review — not
+only during code generation.
+
+Key rules:
+
+- Inspect current SwallowKit capabilities instead of assuming them.
+- Answer repository- and SwallowKit-inspectable questions before asking the human.
+- Prefer `swallowkit_*` MCP tools when available.
+- Otherwise use `{{runCmd}} swallowkit machine ...`.
+- Inspect responsibility boundaries before editing framework-related files.
+- Never hand-edit deterministic SwallowKit-managed artifacts.
+- Use plan/apply for deterministic generation.
+- Respect `requires-human` states and other human approval gates.
+- Run SwallowKit verification before completion.
+
+Task-specific SwallowKit Agent Skills live under `.github/skills/`.
+Agent-agnostic equivalents live under `.swallowkit/workflows/`.