workflows.config.json

One file. One required key (name). Everything else has a default. Set it when the default is wrong.

Lives at .ai/workflows.config.json. Missing file means defaults. Missing keys, same. The only required key is name.

{
  "$schema": "https://raw.githubusercontent.com/1aGh/maude/main/plugins/flow/.claude-plugin/config.schema.json",
  "name": "my-app",
  "language": "en",
  "theme": "agnostic",
  "platforms": ["web-desktop"]
}

Set keys from the CLI or by hand:

maude config set platforms '["web-desktop","web-mobile"]'
maude config set motion.complex 1200
maude config get integrations.tracker.provider

Sections

name (required)

{ "name": "my-app" }

Resolves the <project> placeholder in commands and file paths. .ai/<project>-prd.md becomes .ai/my-app-prd.md.

language / theme

{ "language": "en", "theme": "agnostic" }

• language. ISO 639-1 (en, cs, etc). Cosmetic. Only signals preferred tone in plans and reviews.
• theme. dark | light | agnostic. Drives theme-first contrast checks in the a11y skill.

paths

{
  "paths": {
    "prd": ".ai/my-app-prd.md",
    "designSystem": ".ai/my-app-design-system.md",
    "codebaseMap": ".ai/context/codebase-map.md"
  }
}

Override only if your project's canonical files differ from the defaults.

platforms

{ "platforms": ["web-desktop", "web-mobile", "ios-phone"] }

Drives the /flow:scenario matrix and responsive-rules density mapping. Valid values: web-desktop, web-mobile, ios-phone, ios-tablet, android-phone, android-tablet, macos, windows, linux.

stack

Auto-detected by /flow:init and refreshed by /flow:setup-codebase-map. Used for routing decisions. Which test runner, whether to gate on workspace builds.

{
  "stack": {
    "language": "typescript",
    "framework": "next.js",
    "packageManager": "pnpm",
    "buildTool": "turbo",
    "monorepo": true,
    "ci": "github-actions",
    "tests": "vitest",
    "css": "tailwind",
    "router": "next-app"
  }
}

Use unknown when detection fails. Never invent.

conventions

{
  "conventions": {
    "branchingModel": "github-flow",
    "commits": "conventional",
    "prohibited": ["lodash", "moment"]
  }
}

• branchingModel. Drives /flow:done's push and PR behavior. Enum: github-flow, trunk-based, gitflow, release-branch, other.
• commits. conventional, gitmoji, free-form. /flow:done formats commits to match.
• prohibited. Packages, libs, or APIs the project rejects. Flow commands flag accidental introduction.

boundaries

Integration boundaries the project crosses. The debugging-rules and testing-rules skills treat these as no-mock zones and demand real evidence at the seam.

{
  "boundaries": {
    "realtime": ["websocket"],
    "video": [],
    "api": ["openai", "stripe"],
    "db": ["postgres", "redis"],
    "auth": ["clerk"],
    "telemetry": ["posthog"],
    "payments": ["stripe"]
  }
}

motion

Hard ceilings in milliseconds. motion-rules enforces these.

{
  "motion": {
    "micro": 300,
    "page": 500,
    "complex": 1000,
    "customPulses": { "liveIndicator": 1500 }
  }
}

customPulses are exempt from the page/complex caps. They're loops, not transitions.

responsive

{
  "responsive": {
    "approach": "mobile-first",
    "densityMap": {
      "web-desktop": "command-center",
      "web-mobile": "palm-friendly",
      "ios-phone": "palm-friendly"
    },
    "breakpoints": { "sm": 480, "md": 768, "lg": 1024, "xl": 1280, "2xl": 1536 }
  }
}

densityMap values: command-center, sideline-tool, palm-friendly, cozy, compact, or custom string.

ux

{
  "ux": {
    "responseTargetMs": 100,
    "bilingual": ["cs", "en"]
  }
}

responseTargetMs is a user-perceived ceiling for primary interactions. bilingual is an ISO 639-1 array. Empty means monolingual.

skills

Per-skill toggles. Each enforcement skill respects its own enabled flag (default true).

{
  "skills": {
    "motionRules": { "enabled": true },
    "responsiveRules": { "enabled": true },
    "a11yRules": { "enabled": true },
    "testingRules": { "enabled": true },
    "debuggingRules": { "enabled": true }
  }
}

integrations

Lightweight pointers to external services. Generic commands read provider and decide whether to offer integration actions; project-specific shape (list IDs, custom fields, etc.) lives in defaults.

{
  "integrations": {
    "tracker": {
      "provider": "linear",
      "mcp": "mcp__linear",
      "defaults": { "teamId": "ENG", "projectId": "phase-2" }
    },
    "analytics": { "provider": "posthog" },
    "ci": { "provider": "vercel" },
    "design": { "provider": "figma", "mcp": "mcp__figma" },
    "changelog": {
      "provider": "changesets",
      "scope": "@acme/web",
      "releaseGuide": ".ai/release-guide.md"
    }
  }
}

integrations.changelog

The release-note tooling. Used by /flow:validate and /flow:done for soft warnings about missing release notes, by /flow:release-changelog to author entries, and by /flow:release to walk the project-owned release runbook.

Currently only the changesets provider has a full implementation; git-cliff / conventional / custom / none are accepted but treated as no-op until their providers land.

The release runbook (releaseGuide) is plain Markdown. H2 sections become steps, bash blocks become candidate commands (run only after user confirmation). Scaffolded with a provider-appropriate stub during /flow:init.

Validation

The full JSON Schema lives at plugins/flow/.claude-plugin/config.schema.json. Reference it via $schema for editor autocomplete + diagnostics.