create-flowdular 0.2.3 → 0.2.5

package/agent-template/.ai/blueprints/bug-fix/steps.yaml

@@ -0,0 +1,51 @@
+schemaVersion: 1
+steps:
+  - id: reproduce
+    role: backend-engineer
+    action: Write the failing test with the gate runner (vitest; route.handler(createContext(new Request(...), {})) or the service on the module's tests/support/database.ts provider).
+    inputs:
+      - 'symptom'
+      - 'reproduction'
+    outputs:
+      - 'tests/*.test.ts'
+    gates:
+      - 'tests'
+  - id: locate
+    role: backend-engineer
+    action: Map the symptom to the owning layer with the table in .ai/skills/bug-hunt/SKILL.md; state the root cause as input and state to wrong outcome.
+    inputs:
+      - 'failing test'
+    outputs:
+      - 'root cause'
+  - id: fix
+    role: backend-engineer
+    action: Smallest change in the owning file; no second guard in another layer.
+    inputs:
+      - 'root cause'
+    outputs:
+      - 'owning file'
+    gates:
+      - 'typecheck'
+      - 'tests'
+      - 'format'
+  - id: siblings
+    role: backend-engineer
+    action: grep the same pattern across modules/*/src and either fix or list the siblings.
+    inputs:
+      - 'pattern'
+    outputs:
+      - 'siblings list'
+  - id: land
+    role: orchestrator
+    action: 'Sandbox: eject. Direct path: pnpm verify, pull request with the root cause and the regression test name.'
+    inputs:
+      - 'diff'
+    outputs:
+      - 'pull request'
+    gates:
+      - 'spec-schema'
+      - 'module-schema'
+      - 'dependencies'
+      - 'typecheck'
+      - 'tests'
+      - 'format'

package/agent-template/.ai/blueprints/core-extend/README.md

@@ -0,0 +1,5 @@
+# core-extend
+
+Change a platform package (`packages/**`, `platform/**`, the schemas in `packages/contracts`, or the auth server contract in `modules/auth/src/server/composition.ts`). This runs at the repository root only; a sandbox session cannot reach these paths and hands off with the exact change needed. Procedure and checklists: `.ai/skills/core-extend/SKILL.md`.
+
+Every public surface change names and migrates its consumers in the same change (modules, scaffold, generated composition, reference copies for sandbox sessions, docs, skills). Gates are the repository gates: `pnpm verify` and `pnpm build`. A change to a public boundary gets an ADR in `docs/adr`.

package/agent-template/.ai/blueprints/core-extend/allowed-paths.yaml

@@ -0,0 +1,49 @@
+schemaVersion: 1
+write:
+  - packages/**
+  - platform/octane.config.ts
+  - platform/src/**
+  - platform/scripts/**
+  - modules/auth/src/server/composition.ts
+  - modules/*/module.json
+  - modules/*/spec/module.yaml
+  - modules/*/src/platform.ts
+  - docs/**
+  - .ai/**
+  - .agents/skills/**
+  - .claude/skills/**
+  - AGENTS.md
+  - CLAUDE.md
+  - rulesync.jsonc
+  - package.json
+  - pnpm-workspace.yaml
+deny:
+  - platform/src/generated/**
+  - flowdular.json
+  - infra/**
+  - .github/**
+  - pnpm-lock.yaml (only through pnpm install)
+notes:
+  - modules/** beyond the listed files belong to edit-module; a consumer migration touches only the lines the contract change forces
+  - AGENTS.md, CLAUDE.md, .agents/skills and .claude/skills are written only by pnpm rules:generate
+# Written only by CLI commands, never by hand. The eject and the direct path
+# both run the commands; the files still travel in the same commit.
+cliOwned:
+  - path: flowdular.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/package.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/src/generated/modules.server.ts
+    command: pnpm flowdular module sync --apply
+  - path: platform/src/generated/modules.client.ts
+    command: pnpm flowdular module sync --apply
+  - path: pnpm-lock.yaml
+    command: pnpm install
+  - path: AGENTS.md
+    command: pnpm rules:generate
+  - path: CLAUDE.md
+    command: pnpm rules:generate
+  - path: .agents/skills
+    command: pnpm rules:generate
+  - path: .claude/skills
+    command: pnpm rules:generate

package/agent-template/.ai/blueprints/core-extend/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": "core-extend",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": ["module-executor"],
+	"executorProfiles": ["repo-agent"],
+	"requiredReviewers": ["reviewer", "platform-owner"],
+	"requiresApprovedSpec": false
+}

package/agent-template/.ai/blueprints/core-extend/examples/invalid/input-unknown-package.json

@@ -0,0 +1,5 @@
+{
+	"package": "@flowdular/module-catalog",
+	"change": "server-contract",
+	"brief": "Change a business module through the core blueprint."
+}

package/agent-template/.ai/blueprints/core-extend/examples/invalid/plan-missing-gates.json

@@ -0,0 +1,7 @@
+{
+	"blueprint": "core-extend@1.0.0",
+	"package": "@flowdular/sdk/server",
+	"consumersMigrated": [],
+	"adr": false,
+	"gates": []
+}

package/agent-template/.ai/blueprints/core-extend/examples/valid/input.json

@@ -0,0 +1,6 @@
+{
+	"package": "@flowdular/sdk/modules/auth",
+	"change": "server-contract",
+	"brief": "Add an optional agentTools list to PlatformServerComposition.",
+	"consumers": ["modules/*/src/platform.ts", "packages/cli/src/module-sync.ts"]
+}

package/agent-template/.ai/blueprints/core-extend/examples/valid/plan.json

@@ -0,0 +1,10 @@
+{
+	"blueprint": "core-extend@1.0.0",
+	"package": "@flowdular/sdk/modules/auth",
+	"consumersMigrated": [
+		"modules/agents/src/platform.ts",
+		"packages/cli/src/module-sync.ts"
+	],
+	"adr": true,
+	"gates": ["pnpm verify", "pnpm build"]
+}

package/agent-template/.ai/blueprints/core-extend/gates.yaml

@@ -0,0 +1,16 @@
+schemaVersion: 1
+# Repository gates. Nothing executes this file; CI runs the same commands
+# (.github/workflows/ci.yml).
+gates:
+  - id: verify
+    command: pnpm verify
+    required: true
+  - id: build
+    command: pnpm build
+    required: true
+  - id: platform-typecheck
+    command: pnpm --filter @flowdular/platform typecheck
+    required: true
+  - id: audit
+    command: pnpm audit --prod --audit-level high
+    required: false

package/agent-template/.ai/blueprints/core-extend/input.schema.json

@@ -0,0 +1,54 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["package", "change", "brief"],
+	"properties": {
+		"package": {
+			"type": "string",
+			"enum": [
+				"@flowdular/sdk/contracts",
+				"@flowdular/sdk/kernel",
+				"@flowdular/sdk/server",
+				"@flowdular/sdk/client",
+				"@flowdular/sdk/ui",
+				"@flowdular/cli",
+				"@flowdular/sdk/cli-protocol",
+				"@flowdular/sandbox",
+				"@flowdular/coding-agent",
+				"@flowdular/sdk/harness",
+				"@flowdular/sdk/ai-provider",
+				"@flowdular/sdk/dev-console",
+				"@flowdular/platform",
+				"@flowdular/sdk/modules/auth"
+			]
+		},
+		"change": {
+			"type": "string",
+			"enum": [
+				"schema",
+				"server-contract",
+				"client-contract",
+				"ui-primitive",
+				"cli",
+				"sandbox",
+				"coding-agent",
+				"kernel",
+				"composition"
+			]
+		},
+		"brief": {
+			"type": "string",
+			"minLength": 8,
+			"maxLength": 20000
+		},
+		"consumers": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/agent-template/.ai/blueprints/core-extend/plan.schema.json

@@ -0,0 +1,39 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["blueprint", "package", "consumersMigrated", "adr", "gates"],
+	"properties": {
+		"blueprint": {
+			"const": "core-extend@1.0.0"
+		},
+		"package": {
+			"type": "string",
+			"pattern": "^@flowdular/[a-z-]+$"
+		},
+		"consumersMigrated": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			},
+			"uniqueItems": true
+		},
+		"adr": {
+			"type": "boolean"
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"pnpm verify",
+					"pnpm build",
+					"pnpm --filter @flowdular/platform typecheck"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}

package/agent-template/.ai/blueprints/core-extend/required-files.yaml

@@ -0,0 +1,36 @@
+schemaVersion: 1
+required: []
+byChange:
+  schema:
+    - packages/contracts/schemas/<name>.schema.json
+    - packages/contracts/src/index.ts
+    - packages/cli/src/module-scaffold.ts
+    - packages/cli/tests/module-scaffold.test.ts
+  server-contract:
+    - modules/auth/src/server/composition.ts
+    - packages/cli/src/module-sync.ts (when the generated composition changes)
+    - modules/*/src/platform.ts (when the new member is required)
+  client-contract:
+    - packages/client/src/contributions.ts
+    - packages/client/src/index.ts
+    - packages/client/src/ApplicationShell.tsrx
+    - modules/*/src/client/index.ts (when ModuleClientContext changes)
+  ui-primitive:
+    - packages/ui/src/components/<Name>.tsrx
+    - packages/ui/src/index.ts
+    - packages/ui/src/styles/components.css
+    - docs/design-system.md
+  cli:
+    - packages/cli/src/runner.ts
+    - packages/cli/src/capabilities.ts (core capability)
+    - packages/cli/tests/*.test.ts
+    - .ai/policies/capabilities.yaml
+  sandbox:
+    - packages/sandbox/src/server/gates.ts (gate ids match .ai/agents/sandbox/*.md)
+    - packages/sandbox/src/server/reference.ts (what sessions can read)
+  coding-agent:
+    - packages/coding-agent/src/roles/contract.ts
+    - packages/coding-agent/src/roles/defaults.ts (regenerated from .ai/agents/sandbox, never hand-edited)
+  composition:
+    - platform/octane.config.ts
+    - platform/src/App.tsrx

package/agent-template/.ai/blueprints/core-extend/spec-requirements.yaml

@@ -0,0 +1,17 @@
+schemaVersion: 1
+# Core changes have no module spec. A public boundary change records an ADR.
+status:
+  allowed: []
+adr:
+  requiredWhen:
+    - a type exported from packages/server, packages/client, packages/contracts, packages/ui or @flowdular/module-auth/server changes shape
+    - a JSON schema in packages/contracts/schemas gains or loses a key
+    - a gate id, role front matter key, or CLI command group changes
+  location: docs/adr/NNNN-<slug>.md
+schemas:
+  whenChanged:
+    - update packages/contracts/src/index.ts types
+    - update packages/cli/src/module-scaffold.ts and its test
+    - update every modules/*/module.json or spec/module.yaml affected
+    - update .ai/blueprints/*/required-files.yaml and spec-requirements.yaml
+    - update .ai/agents/sandbox/business-manager.md when spec keys change

package/agent-template/.ai/blueprints/core-extend/steps.yaml

@@ -0,0 +1,54 @@
+schemaVersion: 1
+steps:
+  - id: map
+    role: module-executor
+    action: Read the owning package end to end and list every consumer (grep the export name across modules/, platform/, packages/). Read .ai/skills/core-extend/SKILL.md.
+    inputs:
+      - 'brief'
+    outputs:
+      - 'consumer list'
+  - id: contract
+    role: module-executor
+    action: Change the type or schema first, optional members before required ones; write the ADR when a public boundary changes.
+    inputs:
+      - 'consumer list'
+    outputs:
+      - 'packages/**'
+      - 'docs/adr/NNNN-*.md'
+  - id: consumers
+    role: module-executor
+    action: Migrate every consumer in the same change, including the scaffold, the generated composition generator, reference copies, docs/design-system.md and the skills that describe the surface.
+    inputs:
+      - 'consumer list'
+    outputs:
+      - 'modules/*/src/platform.ts'
+      - 'packages/cli/src/module-scaffold.ts'
+      - 'packages/cli/src/module-sync.ts'
+      - '.ai/skills/**'
+  - id: regenerate
+    role: module-executor
+    action: Run pnpm flowdular module sync --apply when the generated composition shape changed. Run pnpm rules:generate when .ai/rules or .ai/skills changed. Never hand-edit generated files.
+    inputs:
+      - 'packages/cli/src/module-sync.ts'
+    outputs:
+      - 'platform/src/generated/modules.server.ts'
+      - 'platform/src/generated/modules.client.ts'
+      - 'AGENTS.md'
+      - 'CLAUDE.md'
+      - '.agents/skills/**'
+      - '.claude/skills/**'
+  - id: verify
+    role: module-executor
+    action: pnpm verify, then pnpm build; pnpm --filter @flowdular/platform typecheck while iterating.
+    inputs:
+      - 'working tree'
+    outputs:
+      - 'gate evidence'
+  - id: review
+    role: reviewer
+    action: Dependency direction respected, consumers migrated, dead code not extended, ADR present when required.
+    inputs:
+      - 'diff'
+      - 'gate evidence'
+    outputs:
+      - 'review report'

package/agent-template/.ai/blueprints/edit-module/README.md

@@ -0,0 +1,9 @@
+# edit-module
+
+Change an existing module. The sandbox labels these sessions `edit-module@1.0.0` (`packages/sandbox/src/server/routes.ts`) and copies the module into the session with a pristine `base/` copy for the diff; the same blueprint applies when a person or a coding tool follows `.ai/skills/module-update/SKILL.md` at the repository root.
+
+`requiresApprovedSpec` is true. The copied specification describes the old module, so `business-manager` takes the first sandbox turn and writes the smallest delta needed for the request: a `specVersion` bump plus changed acceptance scenarios, invariants, permissions or ownership rules. The sandbox then shows that delta to the operator. Approval records a SHA-256 hash of the exact specification after the approval route changes its status to `approved`. An agent-written status line has no authority. Editing the specification or requesting changes clears the gate because its content no longer matches the recorded hash. Only then does the selected implementer start (`packages/sandbox/src/server/spec.ts`, `planning.ts`, `sessions.ts`).
+
+Landing: eject runs the gates per module, copies added and changed files, removes the files the session deleted, runs `pnpm install`, `auth sync-scopes`, and a platform typecheck, and stops at the first failed step; `module enable` does not run for an existing module. A session may carry several modules. Direct path: `pnpm verify` and a pull request.
+
+When the approved delta adds an agent tool or a module-owned business agent, `agentic-engineer` follows `agent-tool-design` or `business-agent-design`. Business agent definitions live in module source, register through `context.agentDefinitions`, and keep provider, model, and reduced enabled tools in the tenant binding.

package/agent-template/.ai/blueprints/edit-module/allowed-paths.yaml

@@ -0,0 +1,27 @@
+schemaVersion: 1
+write:
+  - modules/{module}/**
+deny:
+  - platform/**
+  - packages/**
+  - infra/**
+  - .github/**
+  - docs/**
+  - specs/**
+  - .ai/**
+  - flowdular.json
+  - pnpm-workspace.yaml
+  - modules/!({module})/**
+# Written only by CLI commands, never by hand. The eject and the direct path
+# both run the commands; the files still travel in the same commit.
+cliOwned:
+  - path: flowdular.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/package.json
+    command: pnpm flowdular module enable <id> --apply
+  - path: platform/src/generated/modules.server.ts
+    command: pnpm flowdular module sync --apply
+  - path: platform/src/generated/modules.client.ts
+    command: pnpm flowdular module sync --apply
+  - path: pnpm-lock.yaml
+    command: pnpm install

package/agent-template/.ai/blueprints/edit-module/blueprint.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "../../../packages/contracts/schemas/blueprint.schema.json",
+	"schemaVersion": 1,
+	"architecture": "0.2.0",
+	"owner": "platform-architecture",
+	"status": "approved",
+	"id": "edit-module",
+	"version": "1.0.0",
+	"risk": "workspace-write",
+	"agentRoles": [
+		"backend-engineer",
+		"frontend-engineer",
+		"ux-designer",
+		"business-manager",
+		"agentic-engineer"
+	],
+	"executorProfiles": ["sandbox-specialist", "repo-agent"],
+	"requiredReviewers": ["reviewer"],
+	"requiresApprovedSpec": true
+}

package/agent-template/.ai/blueprints/edit-module/examples/invalid/input-unknown-change.json

@@ -0,0 +1,5 @@
+{
+	"moduleId": "parties.core",
+	"change": "rewrite",
+	"brief": "Rewrite the module in another framework."
+}

package/agent-template/.ai/blueprints/edit-module/examples/invalid/plan-touches-platform.json

@@ -0,0 +1,15 @@
+{
+	"blueprint": "edit-module@1.0.0",
+	"moduleId": "parties.core",
+	"change": "endpoint",
+	"touchList": ["platform/octane.config.ts"],
+	"specVersionBump": "minor",
+	"gates": [
+		"spec-schema",
+		"module-schema",
+		"dependencies",
+		"typecheck",
+		"tests",
+		"format"
+	]
+}

package/agent-template/.ai/blueprints/edit-module/examples/valid/input.json

@@ -0,0 +1,5 @@
+{
+	"moduleId": "parties.core",
+	"change": "column",
+	"brief": "Add a vat_id column to parties with a list filter."
+}

package/agent-template/.ai/blueprints/edit-module/examples/valid/plan.json

@@ -0,0 +1,25 @@
+{
+	"blueprint": "edit-module@1.0.0",
+	"moduleId": "parties.core",
+	"change": "column",
+	"touchList": [
+		"modules/parties/src/services/migration.ts",
+		"modules/parties/src/services/database-repository.ts",
+		"modules/parties/migrations/0002_parties_vat_id.up.sql",
+		"modules/parties/migrations/0002_parties_vat_id.down.sql",
+		"modules/parties/src/domain/types.ts",
+		"modules/parties/src/api/endpoints.ts",
+		"modules/parties/src/client/PartyForm.tsrx",
+		"modules/parties/tests/module.test.ts",
+		"modules/parties/spec/module.yaml"
+	],
+	"specVersionBump": "minor",
+	"gates": [
+		"spec-schema",
+		"module-schema",
+		"dependencies",
+		"typecheck",
+		"tests",
+		"format"
+	]
+}

package/agent-template/.ai/blueprints/edit-module/gates.yaml

@@ -0,0 +1,30 @@
+schemaVersion: 1
+# Ids equal GateId in packages/sandbox/src/server/gates.ts. The sandbox runs the
+# gates a role lists in its front matter after every turn that changed files;
+# from the repository root run the command column yourself. Nothing executes
+# this file; it documents the contract.
+gates:
+  - id: spec-schema
+    command: pnpm flowdular spec validate --all --json
+    sandbox: pnpm flowdular spec validate --all --json --root <session workspace>
+    required: true
+  - id: module-schema
+    command: pnpm flowdular module validate --json
+    sandbox: pnpm flowdular module validate --json --root <session workspace>
+    required: true
+  - id: dependencies
+    command: 'grep the imports under src/** and compare with package.json dependencies (no CLI command yet)'
+    sandbox: checkDeclaredDependencies(modulePath) in packages/sandbox/src/server/dependencies.ts, run after every turn that changed files, plus a pnpm install when a package.json changed
+    required: true
+  - id: typecheck
+    command: pnpm --filter @flowdular/module-{module} typecheck
+    sandbox: node_modules/.bin/tsrx-tsc --noEmit -p tsconfig.json (cwd module)
+    required: true
+  - id: tests
+    command: pnpm --filter @flowdular/module-{module} test
+    sandbox: node_modules/.bin/vitest run --passWithNoTests (cwd module; zero tests still pass)
+    required: true
+  - id: format
+    command: pnpm format:check
+    sandbox: prettier --check . (cwd module)
+    required: true

package/agent-template/.ai/blueprints/edit-module/input.schema.json

@@ -0,0 +1,31 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["moduleId", "change", "brief"],
+	"properties": {
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"change": {
+			"type": "string",
+			"enum": [
+				"endpoint",
+				"table",
+				"column",
+				"screen",
+				"widget",
+				"permission",
+				"setting",
+				"cross-module-read",
+				"fix"
+			]
+		},
+		"brief": {
+			"type": "string",
+			"minLength": 8,
+			"maxLength": 20000
+		}
+	}
+}

package/agent-template/.ai/blueprints/edit-module/plan.schema.json

@@ -0,0 +1,65 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"blueprint",
+		"moduleId",
+		"change",
+		"touchList",
+		"specVersionBump",
+		"gates"
+	],
+	"properties": {
+		"blueprint": {
+			"const": "edit-module@1.0.0"
+		},
+		"moduleId": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+		},
+		"change": {
+			"type": "string",
+			"enum": [
+				"endpoint",
+				"table",
+				"column",
+				"screen",
+				"widget",
+				"permission",
+				"setting",
+				"cross-module-read",
+				"fix"
+			]
+		},
+		"touchList": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"pattern": "^modules/[a-z0-9-]+/"
+			},
+			"uniqueItems": true
+		},
+		"specVersionBump": {
+			"type": "string",
+			"enum": ["patch", "minor"]
+		},
+		"gates": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"enum": [
+					"spec-schema",
+					"module-schema",
+					"dependencies",
+					"typecheck",
+					"tests",
+					"format"
+				]
+			},
+			"uniqueItems": true
+		}
+	}
+}