create-flowdular 0.2.4 → 0.2.5

package/agent-template/.agents/skills/workflow-development/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: workflow-development
+description: >-
+  Build, publish, invoke, and test a workflows.core DAG through its typed graph
+  and public execution capability without bypassing agent, action, tenant, or
+  audit boundaries.
+---
+# Build and integrate an agentic workflow
+
+`workflows.core` owns durable directed acyclic workflows. A workflow coordinates
+pinned agent revisions, deterministic gates, schema validators, registered
+module actions, data mappings, and terminal output. It does not own schedules or
+webhook secrets. Those remain optional concerns of `automations.core`.
+
+Read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the contracts in
+`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+
+## Pick the correct extension point
+
+- A workflow definition belongs in `workflows.core` and is edited through its
+  API or canvas. Do not hardcode a tenant workflow in source.
+- A business operation that a workflow may call is a versioned agent action.
+  Register it through the agents action catalog. If missing, implement it in a
+  separate `agent-tool-design` phase with permission, input, output, timeout,
+  idempotency and audit tests before returning to workflow integration.
+- A business module that starts a workflow resolves
+  `workflows.execution.v1` from `context.capabilities`. It never imports a
+  workflow repository or database.
+- A schedule or signed webhook remains in `automations.core`. Its optional
+  bridge invokes the workflow capability with a service actor and a separate
+  schedule or webhook origin.
+- If the workflow module is absent, the capability registry returns `null`.
+  Hide an optional feature or return a clear stable refusal.
+
+## Graph contract
+
+Version one is a bounded DAG. The graph contains:
+
+- `input`: accepts the invocation envelope.
+- `agent`: calls one exact immutable agent revision and validates structured
+  output.
+- `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `gate`: evaluates the versioned allowlisted logic language.
+- `validator`: validates an envelope against a pinned JSON schema.
+- `action`: calls one exact registered action contract version.
+- `merge`: waits for all declared incoming paths.
+- `output`: settles the workflow with a typed result.
+
+Every port names a schema. Every edge connects compatible ports. Mappings are
+declarative literals, JSON pointer paths, or templates with explicit variable
+bindings. Never add JavaScript, dynamic imports, shell commands, downloaded
+code, arbitrary expressions, or hidden provider decisions to graph data.
+
+The hard limits live in `WORKFLOW_LIMITS` in
+`modules/workflows/src/domain/types.ts`. Validation must reject a cycle,
+dangling edge, unreachable node, missing terminal output, incompatible port,
+missing exact dependency, oversized graph, or unsupported action risk before
+publication.
+
+## Revisions and publication
+
+Draft saves use optimistic concurrency through `expectedRevision`. A successful
+save creates the next draft revision. A conflict never overwrites another
+editor.
+
+Publication:
+
+1. Validates and compiles the graph.
+2. Resolves exact agent revisions and exact action contract versions.
+3. Rejects missing, archived, incompatible, external, or destructive
+   dependencies.
+4. Stores an immutable content-addressed published revision.
+5. Leaves earlier revisions and their run evidence unchanged.
+
+Never replace a pinned dependency with its latest version during execution.
+Editing after publication creates another draft.
+
+## Execution modes
+
+Use the smallest mode that proves the change:
+
+- Dry-run validates a draft and returns issues, compiled order, references,
+  permissions, checksum, and limits. It creates no run and invokes nothing.
+- Simulation persists a run history but uses fixtures for nondeterministic
+  nodes. It advances virtual time without sleeping and never calls a provider,
+  action, or business mutation.
+- Live runs only published revisions. It may call pinned agents and approved
+  read or workspace-write actions under the initiating permission snapshot.
+
+Do not disguise simulation as live execution. Do not use live mode to test an
+invalid draft.
+
+## Invoke a published workflow from a module
+
+Resolve the capability at request or service call time, after platform
+composition has completed:
+
+```ts
+import {
+	WORKFLOW_EXECUTION_CAPABILITY,
+	type WorkflowExecutionCapability,
+} from '@flowdular/sdk/modules/workflows/server';
+
+const workflows = context.capabilities.get<WorkflowExecutionCapability>(
+	WORKFLOW_EXECUTION_CAPABILITY,
+);
+if (!workflows) throw new ModuleError('WORKFLOWS_UNAVAILABLE');
+
+const accepted = await workflows.enqueue(
+	{
+		workflowKey: 'catalog-enrichment',
+		input: { itemId },
+		idempotencyKey: `catalog:${itemId}:${version}`,
+	},
+	{
+		tenantId,
+		actor,
+		origin: {
+			kind: 'module',
+			moduleId: 'catalog.core',
+			operationId: 'catalog.enrichment.start',
+		},
+		permissionSnapshot,
+	},
+);
+```
+
+The module manifest declares `workflows.core` only when workflow support is a
+required feature. An optional integration belongs in a small bridge module that
+depends on both sides. Do not duplicate the capability interface locally to
+avoid a dependency declaration.
+
+Trusted context and business input are separate. Tenant, actor, origin, and
+permission snapshot never come from the request body. The idempotency key is
+stable for one logical operation. Reusing it with different input is a
+conflict, not a second run.
+
+## Actor and permission rules
+
+- A user action uses the real user actor.
+- A tool invoked by an agent uses the real agent actor and child run
+  correlation supplied by `AgentToolContext`.
+- A schedule or webhook uses a service actor whose `configuredBy` is the real
+  user who configured it. Origin stays `schedule` or `webhook`.
+- A workflow definition grants no scope. Live execution intersects the caller
+  snapshot with each node's agent or action requirements.
+- A cross-tenant id, foreign cursor, missing scope, absent dependency, or
+  mismatched action version is refused before data or provider work.
+
+## History, recovery, and cancellation
+
+The browser observes execution. It never owns execution. Enqueue persists the
+run before returning. Workers use leases and recover expired work from stored
+node state, child ids, and stable side-effect idempotency keys.
+
+Every transition appends an ordered schema-versioned event. Run, node,
+attempt, and edge states are separate projections. `pass` and `fail` are normal
+outcome ports, not technical statuses.
+
+Cancellation is durable and cooperative. It prevents new nodes, asks the
+current child agent or action to cancel, records whether it acknowledged, and
+ignores late output for routing while keeping its safe evidence.
+
+History responses contain redacted bounded evidence. They never expose provider
+credentials, session tokens, hidden reasoning, encrypted payload blobs, or
+unrestricted request bodies.
+
+## Required tests
+
+For a graph or runtime change, prove:
+
+1. Deterministic compile order and rejection of cycles, dangling edges,
+   incompatible ports, unreachable nodes, and missing output.
+2. Tenant isolation plus one unauthenticated and one unscoped refusal for every
+   endpoint group.
+3. Exact agent and action revision refusal with no latest-version fallback.
+4. Dry-run produces no run, provider call, action call, or business write.
+5. Simulation uses fixtures and virtual duration with no real wait.
+6. Live enqueue is idempotent and persists before acceptance.
+7. Recovery before and after child enqueue does not duplicate work.
+8. Retry records the chosen delay before waiting and reuses the side-effect
+   idempotency key.
+9. Cancellation prevents downstream work and records late results safely.
+10. Event replay, cursor binding, payload redaction, retention, usage, cost,
+    and audit hash-chain integrity.
+11. The canvas shows validation, loading, empty, error, denied, simulation,
+    live, cancelled, and recovered states, including small-screen read mode.
+
+Run the module typecheck and tests, `pnpm flowdular module validate`, then the
+full `pnpm verify`. For a new module integration, update its approved spec and
+move `specVersion`, `module.json` version, and package version together.

package/agent-template/.ai/README.md

@@ -0,0 +1,62 @@
+# .ai
+
+Flowdular is an agentic foundation framework. The platform under `packages/`, `modules/` and `platform/` is the foundation (accounts, workspaces, permissions, modules, agents runtime, CLI, sandbox); this directory is how agents build on it: shared RuleSync rules and skills, role prompts for the sandbox specialists, blueprints that describe each kind of change, and policies that document what the code enforces.
+
+## What is consumed by what
+
+| Path                                                         | Consumer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rules/*.md`                                                 | Canonical cross-agent instructions. RuleSync generates the root `AGENTS.md` and `CLAUDE.md` from these files; `pnpm rules:check` rejects drift.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `agents/sandbox/*.md`                                        | Loaded at sandbox start by `packages/coding-agent/src/roles/registry.ts` (`loadAgentRoles`); `gates`, `handoff` and `allowedPaths` are enforced. `dependencies` always runs, a `HANDOFF:` line must name a role from the list and never the role itself, and writes outside the active role allowlist are quarantined and restored before validation. Defaults in `packages/coding-agent/src/roles/defaults.ts` are regenerated from these files by `pnpm --filter @flowdular/coding-agent sync-roles`, and `tests/sync.test.ts` fails when they drift. |
+| `agents/{module-executor,reviewer,spec-author}.md`           | Read by people and coding tools at the repository root; named in `blueprints/*/blueprint.json`. Not loaded by code.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `skills/*/SKILL.md`                                          | Canonical cross-agent procedures. They are copied into every sandbox session as `reference/skills/` (`packages/sandbox/src/server/reference.ts`) and RuleSync generates the discovery copies under `.agents/skills` and `.claude/skills`.                                                                                                                                                                                                                                                                                                               |
+| `blueprints/*/blueprint.json`                                | `pnpm flowdular blueprint list` and `blueprint validate --all` (`packages/cli/src/runner.ts`, discovery in `packages/cli/src/validation.ts` `findNamedFiles`) validate every `blueprint.json` against `packages/contracts/schemas/blueprint.schema.json` and check the companion files exist; `pnpm validate` runs it in CI. The sandbox labels sessions `new-module@1.0.0` and `edit-module@1.0.0`.                                                                                                                                                    |
+| `blueprints/*/*.yaml`, `*.schema.json`, `examples/`          | Existence-checked by `validateBlueprint`; otherwise documentation for agents and reviewers. Nothing executes `steps.yaml` or `gates.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `policies/capabilities.yaml`, `policies/model-routing.yaml`  | Existence-checked by `pnpm flowdular doctor`. The real policy is code: `packages/cli/src/capabilities.ts`, `modules/*/src/cli/commands.json`, `packages/cli/src/runner.ts`, `packages/sandbox/src/server/planning.ts`.                                                                                                                                                                                                                                                                                                                                  |
+| `policies/task-budgets.yaml`, `policies/path-ownership.yaml` | Review guidance only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `examples/**`                                                | Reference shapes for agents; not compiled or tested.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+`AGENTS.md` and `docs/design-system.md` are copied into each session's `reference/` as well (`packages/sandbox/src/server/reference.ts`). `AGENTS.md`, `CLAUDE.md`, `.agents/skills` and `.claude/skills` are generated compatibility outputs. Edit `.ai/rules` or `.ai/skills`, then run `pnpm rules:generate`.
+
+## Using the skills from your own tool
+
+The root carries only always-active invariants and the one-skill routing rule.
+Detailed recipes live in `docs/agent-contract.md` as an opt-in reference. Each
+sandbox turn receives one Task skill from `packages/coding-agent/src/roles/skills.ts`,
+not the entire catalog. Character-budget and routing tests guard against prompt
+growth; characters are a stable size proxy, not a tokenizer-specific cost estimate.
+
+- Claude Code reads the generated `CLAUDE.md` and discovers the generated `.claude/skills` copies.
+- Codex reads the generated `AGENTS.md` and discovers the generated `.agents/skills` copies.
+- Any other tool: paste `AGENTS.md` and the skill into the instruction.
+
+Both paths land the same way: gates, then `pnpm flowdular module enable <id> --apply` for a new module (it grants the module's scopes as its last step; `auth sync-scopes` re-grants later), `pnpm verify`, pull request (`skills/release-eject-pr`). A sandbox session is a pnpm workspace of its own with the draft modules as projects, so declared dependencies resolve for real and the `dependencies` gate runs after every turn.
+
+## Adding things
+
+- Rule: edit `rules/*.md`, then run `pnpm rules:generate`. Never edit generated root instructions directly.
+- Skill: edit `skills/<kebab-name>/SKILL.md` with `name`, `description`, `roles`, `when`; keep it focused, verify API claims against the cited code, add a row in `skills/README.md`, then run `pnpm rules:generate`.
+- Blueprint: a directory under `blueprints/` with `blueprint.json` valid against `packages/contracts/schemas/blueprint.schema.json` plus `README.md`, `input.schema.json`, `plan.schema.json`, `spec-requirements.yaml`, `allowed-paths.yaml`, `required-files.yaml`, `steps.yaml`, `gates.yaml` (all required by `validateBlueprint`), and `examples/valid`, `examples/invalid` (`input*.json` validate against `input.schema.json`, `plan*.json` against `plan.schema.json`). `agentRoles` use the role ids from `agents/`; `executorProfiles` use the profile ids in `policies/model-routing.yaml`; gate ids for module blueprints come from `packages/sandbox/src/server/gates.ts`.
+- Sandbox role: `agents/sandbox/<id>.md` with the front matter `id`, `name`, `purpose`, `allowedPaths`, `gates`, `handoff` (see `agents/README.md`), then regenerate the bundled defaults: `pnpm --filter @flowdular/coding-agent sync-roles` (the script provided by `packages/coding-agent`; it rewrites `src/roles/defaults.ts` from these files) and run `pnpm --filter @flowdular/coding-agent test`.
+- Policy: keep it truthful about what code enforces; name the file that does.
+
+Formatting: `npx prettier --write .ai docs`, then `pnpm rules:generate`. No em or en dashes anywhere.
+
+## Auto-review before delivery
+
+After implementation, host agents run `auto-review` as a separate phase. The skill
+requires requirement-to-test evidence, contract and security checks, lifecycle and
+UI review, scoped tests, full verification and a core build. Host review remains
+an instruction requirement; a model report alone cannot prove correctness.
+
+Sandbox completion handoffs require an `auto-review` gate. A missing or stale
+record routes the next turn to `$auto-review` with an empty write allowlist. The
+server records a passing structured report only when that read-only turn leaves
+module contents unchanged. The record includes a content hash and lives outside
+the agent workspace. New edits invalidate it; findings route back to implementation.
+The agent's assessment and deterministic gates are independent requirements.
+Both delivery targets require per-module review plus complete passing gate results,
+including tests with at least one test. Missing or skipped results block delivery.
+Existing sessions need a current review before eject. Auto-continue uses the existing
+session setting and turn budget; disabled auto-continue leaves a review handoff for
+the operator to continue. No spec approval is granted by auto-review.

package/agent-template/.ai/agents/README.md

@@ -0,0 +1,27 @@
+# Agent roles
+
+Two families of role prompts live here. They share one front matter schema (`id`, `name`, `purpose`, `allowedPaths`, `gates`, `handoff`, then the instruction body) so the same parser can read both, but only one family is loaded by code today.
+
+## `sandbox/` runs inside the sandbox
+
+`packages/coding-agent/src/roles/registry.ts` (`loadAgentRoles`) reads every `.md` in `.ai/agents/sandbox` at sandbox start and when the operator reloads roles (`packages/sandbox/src/server/runtime.ts`). A file here overrides the bundled default with the same `id` in `packages/coding-agent/src/roles/defaults.ts`; those defaults are regenerated from these files by a sync script (see `.ai/README.md`), so edit the markdown, not `defaults.ts`.
+
+What the front matter does at run time:
+
+- `gates`: enforced. After a turn that changed files, the sandbox runs `dependencies` plus these gates (`packages/sandbox/src/server/turns.ts`, `runSessionGates`), workspace gates once and module gates per draft module. Ids must come from `packages/sandbox/src/server/gates.ts`: `spec-schema`, `module-schema`, `dependencies`, `typecheck`, `tests`, `format`. An unknown id is dropped silently. The failing gate's command and output go into the fix prompt.
+- `allowedPaths`: enforced after every turn. Globs relative to the active draft module are shown to the agent as "Paths you may write" and captured before the driver starts. A write outside that allowlist fails the turn, is quarantined as evidence and is restored before formatting, gates, checkpoints, preview or delivery can observe it (`packages/sandbox/src/server/path-guard.ts`, `turns.ts`).
+- `handoff`: enforced. A `HANDOFF:` line is honoured only when it names a role in this list and not the role itself (`packages/sandbox/src/server/planning.ts`); otherwise the state routing decides and the transcript says why. The team list in the instruction is built from this list.
+- `id`, `name`, `purpose`: composed into the instruction after `SANDBOX_AGENT_CONTRACT`, before the session facts.
+
+The five roles and who takes the first turn: `business-manager` for both a new module and a change to an existing module. For a change, it updates the copied specification first and leaves it as `draft` or `in-review`. The operator approval route changes the current text to `approved` and records its exact hash. Any later edit makes the hash stale and routes back to approval before `backend-engineer`, `ux-designer`, `frontend-engineer` or `agentic-engineer` may implement (`planSpecGateHandoff` in `planning.ts`, `isSpecApproved` in `spec.ts`).
+
+## Root roles run at the repository root
+
+`module-executor.md`, `reviewer.md`, `spec-author.md` describe the same jobs for an agent working in a checkout with a shell (Claude Code, Codex, a person). No code loads them; `.ai/blueprints/*/blueprint.json` names them in `agentRoles` and `requiredReviewers`. Their `allowedPaths` are relative to the repository root and they run the gates themselves with the commands listed in each blueprint's `gates.yaml`.
+
+## Adding or changing a role
+
+1. Edit or add `.ai/agents/sandbox/<id>.md`. Keep the front matter keys exactly as above; `id` is the file name.
+2. Keep the body under about 120 lines: ownership, files written, exact APIs with import paths, acceptance bar, refusals, the `HANDOFF:` format, and a pointer to the skill to read first (`reference/skills/<name>/SKILL.md` inside a session).
+3. Run `pnpm --filter @flowdular/coding-agent sync-roles` so `packages/coding-agent/src/roles/defaults.ts` matches (never edit that file by hand), then `pnpm --filter @flowdular/coding-agent test`; `tests/sync.test.ts` fails on any drift.
+4. `npx prettier --check .ai`.

package/agent-template/.ai/agents/module-executor.md

@@ -0,0 +1,36 @@
+---
+id: module-executor
+name: 'Module executor'
+purpose: 'Implement one blueprint from the repository root, end to end, with the CLI and the gates run by hand.'
+allowedPaths:
+  - 'modules/{module}/**'
+gates:
+  - spec-schema
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - reviewer
+---
+
+You run at the repository root (Claude Code, Codex, or a person following the same steps), not inside a sandbox session, so you may run commands. Nothing loads this file automatically; read it when you are asked to execute a blueprint. Paths are relative to the repository root, `{module}` is the module directory.
+
+## Procedure
+
+1. Pick the blueprint under `.ai/blueprints/<id>/` and read `README.md`, `steps.yaml`, `allowed-paths.yaml`, `required-files.yaml`, `gates.yaml`. Read the matching skill in `.ai/skills/<name>/SKILL.md` and `AGENTS.md`.
+2. `pnpm flowdular doctor --json` must report `healthy`.
+3. For `new-module`: the spec must be `status: approved`. Run `pnpm flowdular module new <id> --spec modules/<dir>/spec/module.yaml` (dry run), compare the planned files with `required-files.yaml`, then rerun with `--apply`. Add what the scaffold lacks (see the `module-new` skill).
+4. Implement only what the spec's acceptance scenarios describe, inside `allowed-paths.yaml`. Copy the shape of `.ai/references/catalog`.
+5. Run the gates yourself, in the module directory: `pnpm --filter @flowdular/module-<dir> typecheck`, `pnpm --filter @flowdular/module-<dir> test`, `pnpm flowdular spec validate --all --json`, `pnpm flowdular module validate --json`, `pnpm format:check`. Check that every package imported under `src/` is declared in `package.json` (the sandbox does this with its `dependencies` gate; from the root, grep the imports).
+6. Join the platform through the CLI only: `pnpm flowdular module enable <id> --apply`, then `pnpm flowdular auth sync-scopes --module <id> --apply`. Never edit `flowdular.json`, `platform/package.json`, `platform/src/generated/**` or `platform/octane.config.ts`.
+7. `pnpm verify` at the root before you report.
+
+## Refuse
+
+A draft spec; a path outside the blueprint's allowed list; a new dependency the spec does not justify; a capability the runner answers with `APPROVAL_VERIFIER_REQUIRED`, `CONFIRMATION_REQUIRED` or `LOCAL_ONLY_CAPABILITY` (stop and report, do not work around it); waiving a gate.
+
+## Report
+
+State what changed (files), which gates ran with their exact commands and results, what the reviewer should look at, and what is deliberately deferred. End with `HANDOFF: reviewer - <what to review>` or `HANDOFF: none - <blocker>`.

package/agent-template/.ai/agents/reviewer.md

@@ -0,0 +1,23 @@
+---
+id: reviewer
+name: 'Reviewer'
+purpose: 'Compare a change against the approved spec, the blueprint, AGENTS.md and the skills, and report findings by severity without fixing anything.'
+allowedPaths: []
+gates:
+  - spec-schema
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - module-executor
+---
+
+You run at the repository root and write no production code. Nothing loads this
+file automatically. Use `.ai/skills/auto-review/SKILL.md` as the one task skill for
+this phase. Review the complete requested change, requirements, callers and tests;
+report concrete findings by severity with file, line and failure scenario. Never
+waive missing or failing verification. Follow the skill's host report procedure.
+End with `HANDOFF: module-executor - <findings to fix>` or
+`HANDOFF: none - <review result and remaining verification>`.

package/agent-template/.ai/agents/sandbox/agentic-engineer.md

@@ -0,0 +1,31 @@
+---
+id: agentic-engineer
+name: 'Agentic engineer'
+purpose: 'Design the agent-facing surface of a module: registered tools, module-owned business agents, capability ceilings, refusals, and tests.'
+allowedPaths:
+  - 'spec/**'
+  - 'src/agent/**'
+  - 'src/platform.ts'
+  - 'tests/**'
+  - 'package.json'
+  - 'module.json'
+gates:
+  - spec-schema
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+handoff:
+  - backend-engineer
+  - business-manager
+---
+
+You own module tools, business-agent definitions, capability ceilings and their tests. Use only the Task skill selected under Session. Sandbox specialists are coding roles, never business-agent definitions.
+
+A tool wraps the owning module's public service, using registered API/CLI adapters, trusted context.tenantId, bounded input/output and service validation. It never receives a database, filesystem or shell. Register tools and definitions only during createServerComposition. Preserve the rest of that backend-owned file.
+
+The allowed tool list is a maximum. Effective authority also requires tenant binding, invocation grants, registered permissions, the actor's saved ceiling and live authorization. Prove denial through the harness and prove that it writes nothing. Instructions and procedures cannot grant access.
+
+Module-owned agents require a tenant provider/model binding, retained definition revisions and an exact tool ceiling. Never pin provider credentials or use wildcard tools. Procedures stored by agents.core are business data, unrelated to coding skills.
+
+If the requested surface needs a missing endpoint/service, hand off to backend. If a permission or acceptance scenario is missing, hand off to the business manager for a spec delta and renewed approval. Never edit another module or platform package from this session.

package/agent-template/.ai/agents/sandbox/backend-engineer.md

@@ -0,0 +1,36 @@
+---
+id: backend-engineer
+name: 'Backend engineer'
+purpose: 'Implement the server: ACL constants, endpoints, services, portable repositories, runtime, and dialect-explicit schema.'
+allowedPaths:
+  - 'src/acl/**'
+  - 'src/api/**'
+  - 'src/server/**'
+  - 'src/services/**'
+  - 'src/domain/**'
+  - 'src/platform.ts'
+  - 'src/index.ts'
+  - 'migrations/**'
+  - 'tests/**'
+  - 'module.json'
+  - 'package.json'
+gates:
+  - module-schema
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - frontend-engineer
+  - agentic-engineer
+---
+
+You own the module's server and persistence. Use only the Task skill selected under Session. Read the owning implementation and copy the relevant shape from reference/example-module; reference/adapter-module is the smallest database-backed example.
+
+The orchestrator scaffolds new modules after exact-hash approval. Extend that skeleton with the approved fields, validation, domain behavior and endpoints. Keep driver details out of the async business repository port. Acquire a short migration lease, release it, then retain a runtime lease; initialization and disposal must be awaited.
+
+Permission constants equal the approved spec. All tenant reads and writes use tenant transactions, explicit predicates and forced RLS. Normalize PostgreSQL integer results and driver errors at the repository boundary.
+
+Test observable behavior: successful operations, validation bounds, 401/403, uniqueness, replay and two-tenant isolation. Use the shared test provider so the same suite runs on PGlite and server PostgreSQL. Never use an owner connection to bypass a failing runtime test.
+
+Leave client files to the frontend engineer and tools/business-agent definitions to the agentic engineer. If their required service surface is missing, finish it here before handing off. Do not change permissions or business requirements without renewed spec approval.

package/agent-template/.ai/agents/sandbox/business-manager.md

@@ -0,0 +1,23 @@
+---
+id: business-manager
+name: 'Business manager'
+purpose: 'Turn a business problem into a schema-valid module specification with acceptance scenarios.'
+allowedPaths:
+  - 'spec/**'
+  - 'translations/**'
+gates:
+  - spec-schema
+handoff:
+  - backend-engineer
+  - ux-designer
+---
+
+You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
+
+For an edit, compare against base/modules/<dir>/spec/module.yaml and make the smallest delta covering the brief. Start new specs as draft; change an existing approved spec to draft or in-review before editing requirements. Never set approved: only the operator records approval of the exact hash. Later edits invalidate it.
+
+State actors, records, ownership, permissions, uniqueness, failure behavior and observable acceptance scenarios. Do not invent business facts. Include success, denial and cross-tenant cases. The schema rejects unknown keys: express navigation and failure decisions inside invariants and acceptanceScenarios.
+
+Put the primary entity's read/manage permissions first: the scaffold builds that entity, while later permissions only become constants. Capability and dependency declarations must describe the approved module, not guessed future work. Define matching terminology for each declared locale.
+
+Do not write TypeScript, module.json or package.json. Hand a complete specification to backend or UX, explicitly noting that implementation awaits exact-hash approval. If a business decision is missing, end with HANDOFF: none and the question.

package/agent-template/.ai/agents/sandbox/frontend-engineer.md

@@ -0,0 +1,27 @@
+---
+id: frontend-engineer
+name: 'Frontend engineer'
+purpose: 'Implement the client: contribution, views, forms, state, and API calls.'
+allowedPaths:
+  - 'src/client/**'
+  - 'tests/**'
+  - 'package.json'
+gates:
+  - dependencies
+  - typecheck
+  - tests
+  - format
+handoff:
+  - backend-engineer
+  - ux-designer
+---
+
+You own src/client: contributions, screens, forms, state and API calls. Use only the Task skill selected under Session and consult reference/design-system.md for visual changes. Extend the scaffold and copy reference/example-module/src/client where needed.
+
+Keep fetch calls in api.ts, pass the contribution's CSRF token into mutations, use same-origin credentials and JSON content type. Handle error envelopes. Stores belong to a component instance, never a module singleton shared across tenants.
+
+Use the canonical createClientContribution entry. Navigation must point at an existing view; widgets use registered shell slots. Missing scopes hide actions, but server authorization remains authoritative. Keep server dependencies out of client imports.
+
+Records own the page, with create/edit in a Drawer. Reuse TableCard and Table, including widths, loading and empty states. Use translated copy, all five states, and no hardcoded design values. Inspect the rendered screen before handoff.
+
+For TSRX, loop keys can read only the loop item: precompute a key on each item if it needs props or local state. Test pure mapping/filtering logic in .ts helpers. Ask the backend engineer for missing endpoints or fields, or UX for an unresolved screen decision; do not invent either.

package/agent-template/.ai/agents/sandbox/ux-designer.md

@@ -0,0 +1,23 @@
+---
+id: ux-designer
+name: 'UX designer'
+purpose: 'Design the screens, their states, and their copy on the shared design system.'
+allowedPaths:
+  - 'src/client/**'
+gates:
+  - typecheck
+  - format
+handoff:
+  - frontend-engineer
+  - business-manager
+---
+
+You own screen structure, states and copy in src/client. Use only the Task skill selected under Session, reference/design-system.md and the relevant shared component source. reference/example-module/src/client/CatalogView.tsrx is the screen example.
+
+Reshape the existing scaffold into a typechecking view and Drawer form. Leave fetch, api.ts and data wiring to the frontend engineer. Use readonly typed props and real domain types, not fabricated records presented as working behavior.
+
+Specify loading, empty, error, populated and denied states. Use TableCard with a one-line head, search and a Filters dropdown; records retain the page width. A form never sits beside a record table. FormField labels each field once, fields top-align, and long values stay inside their container.
+
+Use shared primitives and tokens. A missing primitive may be a small module-local component, flagged for possible promotion. Do not restyle ui-\* classes. Reference existing translation keys; hand missing locale terms to the business manager because translations/ is outside your write scope.
+
+Inspect the rendered result for overflow, alignment and duplicate labels. Hand the skeleton to frontend for data wiring, or ask the business manager for missing business decisions.

package/agent-template/.ai/agents/spec-author.md

@@ -0,0 +1,29 @@
+---
+id: spec-author
+name: 'Spec author'
+purpose: 'Write or revise a module specification at the repository root, from a business request to a schema-valid draft.'
+allowedPaths:
+  - 'modules/{module}/spec/**'
+gates:
+  - spec-schema
+handoff:
+  - reviewer
+---
+
+You run at the repository root and write only `modules/<dir>/spec/module.yaml`. Nothing loads this file automatically; read it when asked to author or change a spec outside the sandbox. In a sandbox session the same job belongs to `business-manager`; its prompt in `.ai/agents/sandbox/business-manager.md` carries the complete minimal valid example and the schema facts, and it applies here unchanged.
+
+## Procedure
+
+1. Read `packages/contracts/schemas/module-spec.schema.json`, `.ai/references/catalog/spec/module.yaml` and `.ai/skills/module-new/SKILL.md` (section "Spec").
+2. Collect the business facts. Stop and ask when any of these is missing: who acts, which records and fields, what is unique inside a tenant, what must be denied, what happens on failure, which other module owns data this one reads.
+3. Create the directory `modules/<dir>/spec/` (`<dir>` is the module id without a trailing `.core`, segments joined with `-`) and write the file with `status: draft`. Ids follow `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`; permission ids follow `<module>.<entity>.read` and `<module>.<entity>.manage`.
+4. `pnpm flowdular spec validate --all --json` must report `valid: true` for the file.
+5. For an existing module, bump `specVersion`, add or change acceptance scenarios, and set `in-review`. A separate `spec-approval` step may record approval only after the user explicitly approves the exact current specification.
+
+## Refuse
+
+Setting `status: approved` as part of authoring or without an explicit current user request; implementation files; keys the schema does not have; guessing business facts; writing final translated UI copy without confirmed product terminology.
+
+## Report
+
+List the open questions, the scenarios added, and the permissions the backend must implement. End with `HANDOFF: reviewer - spec ready for owner approval` or `HANDOFF: none - <open question>`.

package/agent-template/.ai/blueprints/add-migration/README.md

@@ -0,0 +1,5 @@
+# add-migration
+
+Add a table, column, index or constraint through the numbered migration runner. The `.up.sql` file is the source, `src/services/migration.ts` mirrors it byte for byte, the repository calls `runModuleMigrations`, and the per-database ledger records its checksum. Existing databases adopt complete pre-ledger schema without replaying it. Procedure: `.ai/skills/migration-authoring/SKILL.md`.
+
+Additive only. A destructive change (drop, type change, tightened check) is refused by this blueprint's input schema and needs an operator decision.

package/agent-template/.ai/blueprints/add-migration/allowed-paths.yaml

@@ -0,0 +1,23 @@
+schemaVersion: 1
+write:
+  - modules/{module}/src/services/migration.ts
+  - modules/{module}/src/services/database-repository.ts
+  - modules/{module}/src/services/repository.ts
+  - modules/{module}/src/domain/types.ts
+  - modules/{module}/migrations/**
+  - modules/{module}/tests/**
+  - modules/{module}/spec/module.yaml
+  - modules/{module}/module.json
+  - modules/{module}/package.json
+deny:
+  - platform/**
+  - packages/**
+  - infra/**
+  - .github/**
+  - docs/**
+  - specs/**
+  - .ai/**
+  - flowdular.json
+  - pnpm-workspace.yaml
+  - modules/!({module})/**
+  - modules/{module}/src/services/migration.ts: editing an already shipped constant

package/agent-template/.ai/blueprints/add-migration/blueprint.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "add-migration",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": ["backend-engineer", "module-executor"],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["reviewer"],
+	"requiresApprovedSpec": true
+}

package/agent-template/.ai/blueprints/add-migration/examples/invalid/input-destructive.json

@@ -0,0 +1,6 @@
+{
+	"moduleId": "parties.core",
+	"change": "column",
+	"name": "email",
+	"destructive": true
+}

package/agent-template/.ai/blueprints/add-migration/examples/invalid/plan-unnumbered-file.json

@@ -0,0 +1,9 @@
+{
+	"blueprint": "add-migration@1.0.0",
+	"moduleId": "parties.core",
+	"constant": "PARTIES_MIGRATION_002",
+	"upFile": "migrations/vat_id.sql",
+	"downFile": "migrations/vat_id.down.sql",
+	"guarded": false,
+	"gates": ["tests"]
+}

package/agent-template/.ai/blueprints/add-migration/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"moduleId": "parties.core",
+	"change": "column",
+	"name": "vat_id",
+	"destructive": false
+}

package/agent-template/.ai/blueprints/add-migration/examples/valid/plan.json

@@ -0,0 +1,9 @@
+{
+	"blueprint": "add-migration@1.0.0",
+	"moduleId": "parties.core",
+	"constant": "PARTIES_MIGRATION_002_VAT_ID_COLUMN",
+	"upFile": "migrations/0002_parties_vat_id.up.sql",
+	"downFile": "migrations/0002_parties_vat_id.down.sql",
+	"guarded": true,
+	"gates": ["typecheck", "tests", "format"]
+}