Coding agent guide

See package manager commands and troubleshooting for pnpm 11/12 and npm usage.

SwallowKit does not replace a coding agent's development process. It supplies project inspection, deterministic change operations, ownership boundaries, and verification guardrails that compose with requirements, specification, planning, TDD, implementation, and review practices.

For the detailed machine/MCP command and response contract, see AI / MCP integration.

Purpose

Development-process skills decide how the work proceeds. SwallowKit is the authoritative project-specific layer that determines how the current project can be inspected and changed safely and reproducibly.

text

Development process / engineering practices
  e.g. process skills, Spec Kit, GSD, BMAD,
       custom skills, normal agent interaction
                    │
                    │ intent / specification / task
                    ▼
             SwallowKit contract
                    │
        ┌───────────┼────────────┐
        │           │            │
     inspect     plan/apply     verify
        │           │            │
        └───────────┼────────────┘
                    ▼
       deterministic Azure application

SwallowKit owns current-project inspection, deterministic artifact generation, drift detection, structural verification, failure explanation, and infrastructure guardrails. It does not introduce its own requirements, specification, ticketing, or semantic-review framework.

Generated agent integration files

swallowkit init creates a layered integration rather than repeating one large contract for every agent:

File	Role
`AGENTS.md`	Canonical always-on project contract
`CLAUDE.md`	Claude Code adapter that points to `AGENTS.md`
`.github/copilot-instructions.md`	GitHub Copilot adapter that points to `AGENTS.md`
`.github/instructions/*.instructions.md`	Path/layer-specific rules
`.mcp.json`	Project-scoped SwallowKit MCP bootstrap
`.github/skills/*/SKILL.md`	Task-specific Agent Skills
`.swallowkit/workflows/*.md`	Agent-neutral fallback runbooks

The adapters contain enough always-on rules to make SwallowKit visible before an agent has loaded AGENTS.md. Task-specific detail remains in Skills and runbooks so the canonical contract stays operational rather than encyclopedic.

SwallowKit across the development lifecycle

Discovery and requirements clarification

Inspect the current project, relevant entities, routes, infrastructure, and ownership boundaries before asking implementation-detail questions. The agent should answer facts discoverable from the repository or SwallowKit itself and reserve human questions for genuine product and domain decisions.

Specification

Describe user intent, observable behavior, acceptance criteria, and useful test seams. Treat SwallowKit architecture and ownership as implementation constraints. Do not describe each generated layer as a separate manually implemented component.

Planning

Inspect current capabilities whenever support or ownership changes a design decision. Never infer SwallowKit capabilities from model memory: the installed version and project state are authoritative.

Ticket decomposition

Prefer independently valuable and verifiable vertical slices. If one model change deterministically derives schema contracts, Functions, BFF, UI, and infrastructure, keep those generated changes in the same behavioral slice.

text

Add priority support to Todo
  ├─ change the source-of-truth model
  ├─ plan/apply the managed artifacts
  ├─ add custom behavior and tests
  └─ verify the project

Do not create schema, backend, BFF, UI, and infrastructure tickets solely because the generated files occupy horizontal layers.

Implementation

Inspect responsibility boundaries before choosing files. Edit ai-authored locations normally, change deterministic artifacts only through their source of truth and plan/apply, and edit shared files only outside managed markers.

Verification

Run SwallowKit verification after implementation and follow structured failure evidence until the project converges or an explicit human decision is required.

Review

Perform semantic/specification/engineering review after mechanical SwallowKit verification. The two gates answer different questions and neither substitutes for the other.

Inspect before asking or designing

Use only the inspections relevant to the task:

npmpnpm

bash

npx swallowkit machine inspect project
npx swallowkit machine inspect entities
npx swallowkit machine inspect routes
npx swallowkit machine inspect boundaries
npx swallowkit machine inspect drift
npx swallowkit machine inspect infra

bash

pnpm exec swallowkit machine inspect project
pnpm exec swallowkit machine inspect entities
pnpm exec swallowkit machine inspect routes
pnpm exec swallowkit machine inspect boundaries
pnpm exec swallowkit machine inspect drift
pnpm exec swallowkit machine inspect infra

Prefer equivalent swallowkit_* MCP tools when available. Use the machine interface as the agent-facing fallback.

This policy avoids questions such as how generated CRUD layers are wired, whether a managed route may be edited, or whether an infrastructure operation exists when current inspection can answer them. It does not suppress questions about ambiguous product behavior, business rules, or risk choices.

Responsibility boundary

machine inspect boundaries (or swallowkit_inspect_boundaries) is the machine-readable authority for the current project:

Zone	Editing policy	Typical examples
`ai-authored`	Edit directly	source-of-truth models, custom logic, custom UI, tests
`deterministic`	Never hand-edit; change source/config and plan/apply	generated CRUD, BFF, UI, schema, and infra artifacts
`shared`	Edit only outside managed markers	aggregate or infrastructure files with SwallowKit sections

The examples are not a substitute for inspection. Ownership can vary by backend, feature, and SwallowKit version.

Planning and ticketing

A specification should lead with desired behavior rather than generated-file mechanics. A plan can record SwallowKit constraints and the expected plan/apply/verify loop without turning deterministic output into independent manual work.

Ticket boundaries should be vertical or tracer-bullet slices that can be implemented and verified independently. Horizontal tickets are appropriate only when they represent genuinely independent value or risk, not merely separate generated directories.

Implementation workflow

The standard agent workflow is:

text

inspect → plan → evaluate conflicts/approval → apply → verify

Prefer MCP tools when the runtime exposes them. Otherwise use structured machine operations, for example:

npmpnpm

bash

npx swallowkit machine inspect drift
npx swallowkit machine plan scaffold todo
npx swallowkit machine apply scaffold --plan <planId>
npx swallowkit machine verify project

bash

pnpm exec swallowkit machine inspect drift
pnpm exec swallowkit machine plan scaffold todo
pnpm exec swallowkit machine apply scaffold --plan <planId>
pnpm exec swallowkit machine verify project

Use swallowkit-add-model, swallowkit-modify-model, and swallowkit-verify-repair when the runtime supports Agent Skills. Otherwise read the corresponding .swallowkit/workflows/ runbook. These task-level capabilities are designed to be invoked from a larger implementation process.

Example request for your agent

Describe the behavior you want rather than asking for separate edits to each generated file.

Add priority to Todo. Read this project's AGENTS.md and relevant Skill/workflow, and keep its selected package manager. Inspect ownership and drift before editing. After changing the model, create a scaffold Plan, inspect its changes and conflicts, then Apply it. Run verify and tests for the priority behavior. If a decision is needed, such as overwriting hand edits, show the affected diff and options.

A Plan here is a change plan returned by SwallowKit. It is separate from an agent's written task plan or Plan mode: it contains planned operations, conflicts, and a planId. Planning does not change generated targets, but saves the plan under .swallowkit/state/plans/. Pass the reviewed plan's planId to Apply.

A stale-plan response means files fingerprinted during planning have changed. Inspect the current diff, create a new Plan, and review it again. --approve does not make a stale Plan valid. For requires-human, obtain the requested decision before continuing. Ordinary changes without conflicts do not need an additional blanket approval step.

When drift is reported

Drift is a mismatch between models, generation records, current files, or project metadata. Read each finding's kind, severity, and repairAction from machine inspect drift, together with the editing policy from machine inspect boundaries. A finding does not automatically mean every affected file should be overwritten.

Finding	What the agent should check
`schema-drift`	Confirm the model change is intentional, then Plan and Apply scaffold for the affected model.
`artifact-modified`	Review the post-generation diff and ownership. Changes in user-editable areas can be expected; preserve needed customizations.
`artifact-missing`	Check whether deletion was intentional and regenerate artifacts that are still needed.
`generator-drift`	Compare the generating and running SwallowKit versions; review regeneration changes when adopting an update.
`manifest-drift`	Investigate the mismatch between the actual project structure and its records, then follow the supplied `repairAction`.

MCP defaults to latest, while normal CLI commands use the project's pinned version. If versions differ, inspect the current capabilities of each interface instead of assuming they are identical. Use the same project and version of the interface for Plan and Apply. See the package manager guide for configuring the MCP version.

After repair, run machine verify project; use machine explain failure to inspect evidence for failures. Resolving drift does not by itself prove the requested feature behavior or a successful Azure deployment. Check those through their own tests and execution results.

Verification versus semantic review

SwallowKit verification asks:

Is the project mechanically and structurally correct, free from managed artifact drift, and passing its configured checks?

Semantic review asks:

Is the design right? Is the behavior right? Does it satisfy the specification and user intent?

Use this order:

text

implementation → SwallowKit verify → semantic code review

When verification fails, use machine explain failure or its MCP equivalent, repair the correct source, and verify again.

Human approval

Machine operations return terminal states and nextActions. A requires-human state is a deliberate stop, not an error to route around. The agent must request the stated decision and must never invent approval.

Azure provisioning always uses the swallowkit-provision Skill/runbook and its explicit approval gate. Even a broad request to complete deployment does not implicitly grant the approval expected after the plan is presented.

Composing with external development processes

Any process framework can provide discovery, specification, ticketing, TDD, implementation orchestration, or semantic review while invoking SwallowKit for current-project facts and deterministic operations. This applies equally to custom Skills, Spec Kit, GSD, BMAD, and ordinary Codex, Claude Code, or GitHub Copilot conversations.

Example: Matt Pocock Skills

The following is a recommended composition example, not a compatibility guarantee or dependency:

text

grill-with-docs
    ├─ inspect project/entities/routes/boundaries as relevant
    ├─ answer repository/SwallowKit-answerable questions autonomously
    └─ ask the human only for genuine product/domain decisions
    ↓
to-spec
    ├─ describe intent and observable behavior
    ├─ include SwallowKit architecture/ownership as constraints
    └─ avoid treating generated layers as independent manual implementation
    ↓
to-tickets
    ├─ keep vertical / tracer-bullet slices
    └─ generated schema/API/BFF/UI/infra work stays inside the slice
    ↓
implement
    ├─ inspect boundaries
    ├─ ai-authored → normal implementation/TDD
    ├─ deterministic → SwallowKit plan/apply
    ├─ shared → edit outside managed markers
    └─ SwallowKit verify
    ↓
code-review
    └─ semantic / spec / engineering review after mechanical verification

SwallowKit supports Matt Pocock Skills through composition, not through a hard dependency. SwallowKit does not install, vendor, fork, or rewrite those Skills.

Complete generated agent documents

The following are the complete English templates used by swallowkit init, not abridged excerpts. , , , , , and are expanded for the selected project. The docs import the canonical templates directly, so generator wording and these published originals share one source.

Generated AGENTS.md

# 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
{{runCmd}} swallowkit machine inspect capabilities
```

`inspect capabilities` answers "what can SwallowKit do" (supported model
declarations with exact formats, the correct auth-introduction workflow, what
generated CRUD does and does not guarantee, how seeds are applied). Use it
instead of guessing or grepping SwallowKit internals.

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.

Additional model-change facts:

- The shared package is consumed through its built `dist/`. `verify project`
  rebuilds it automatically before typecheck; when typechecking manually,
  build the shared package first (stale `dist/` shows up as
  "no exported member" errors).
- Seed JSON under `dev-seeds/` is only applied by
  `{{runCmd}} swallowkit dev --seed-env <environment>`; editing the files
  alone does nothing.

## 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.

## Authentication

Authentication is a **plan/apply operation**, not a free-form config edit.
Ownership of `swallowkit.config` is split:

- `auth.schemes` — owned by SwallowKit. **Always start with
  `{{runCmd}} swallowkit machine plan auth --provider <p> [--scheme <name>]`.
  Never hand-write `auth.schemes` entries**; apply auth appends them, and a
  hand-written scheme makes the plan fail with "already exists".
- `auth.authorization.policies` and `swa.allowedProviders` — hand-edited
  **after** apply (the config is an extension point; this edit is expected).
  `swa.allowedProviders` can also be set at plan time with
  `--allowed-providers github,aad`.

After `apply auth`, follow the returned `nextActions`:

1. Define `auth.authorization.policies` referencing the new scheme.
2. For `swa`: confirm `swa.allowedProviders`; generated login URLs use it.
3. For `external-token`: implement the generated verifier stub. It fails
   closed, and **verify passes with the stub in place** — a green verify does
   not mean external-token auth works end-to-end (`verify project` surfaces a
   `auth-verifier-stub` warning while the stub is unmodified).
4. Re-run plan/apply scaffold for models that need auth guards, then verify.

Use the `swallowkit-add-auth` Agent Skill or the
`.swallowkit/workflows/add-auth.md` runbook when available.

### Generated CRUD scope

Generated CRUD endpoints enforce the model's `authPolicy`
(authentication + roles) — **they do NOT scope data to the authenticated
user**. Any caller passing the policy can read or write any document. For
multi-user data where users may only touch their own records, add ai-authored
custom endpoints that derive the scoping key (e.g. `learnerId`) from the
verified principal — never from the request body — and restrict the generated
write endpoints to admin roles.

## 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-add-auth`
- `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`.
- `id` is a required `z.string()`; only `createdAt` / `updatedAt` are optional
  backend-managed fields.
- Models may declare `partitionKey`, `authPolicy`, `displayName`, and
  `connectorConfig` as exported constants. Exact formats:
  `{{runCmd}} swallowkit machine inspect capabilities` (modelDeclarations).
- Cosmos DB containers use PascalCase plural names and default to `/id` as the
  partition key unless the model declares another key, e.g.
  `export const partitionKey = '/learnerId';` (the field must exist in the
  schema).

## 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

Use `{{pm}}`, the package manager selected for this project. Do not introduce another package manager or lockfile. Use `{{runCmd}} swallowkit` for the project-local CLI. The MCP launcher intentionally resolves `latest` independently.

Generated CLAUDE.md

# 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.
- Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
  in swallowkit.config (policies and `swa.allowedProviders` are hand-edited
  after apply).
- 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.

Generated .github/copilot-instructions.md

# 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.
- Add auth schemes only via plan/apply auth; never hand-write `auth.schemes`
  in swallowkit.config (policies and `swa.allowedProviders` are hand-edited
  after apply).
- 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/`.

Coding agent guide ​

Purpose ​

Generated agent integration files ​

SwallowKit across the development lifecycle ​

Discovery and requirements clarification ​

Specification ​

Planning ​

Ticket decomposition ​

Implementation ​

Verification ​

Review ​

Inspect before asking or designing ​

Responsibility boundary ​

Planning and ticketing ​

Implementation workflow ​

Example request for your agent ​

When drift is reported ​

Verification versus semantic review ​

Human approval ​

Composing with external development processes ​

Example: Matt Pocock Skills ​

Complete generated agent documents ​

Generated AGENTS.md ​

Generated CLAUDE.md ​

Generated .github/copilot-instructions.md ​

Coding agent guide

Purpose

Generated agent integration files

SwallowKit across the development lifecycle

Discovery and requirements clarification

Specification

Planning

Ticket decomposition

Implementation

Verification

Review

Inspect before asking or designing

Responsibility boundary

Planning and ticketing

Implementation workflow

Example request for your agent

When drift is reported

Verification versus semantic review

Human approval

Composing with external development processes

Example: Matt Pocock Skills

Complete generated agent documents

Generated AGENTS.md

Generated CLAUDE.md

Generated .github/copilot-instructions.md