AI-assisted development
How Claude Code, Cursor, Copilot, and Windsurf edit a Tale project — the rules file each editor reads and the schema reference Tale generates under `.tale/reference/`.
3 min read
Tale projects are JSON — agents, workflows, integrations, branding — and JSON edits well in AI editors when the editor knows the schema. The CLI emits two things for that: a rules file each editor reads at the project root (CLAUDE.md for Claude Code, .cursor/rules/tale.mdc for Cursor, .github/copilot-instructions.md for Copilot, .windsurfrules for Windsurf), and a read-only schema mirror under .tale/reference/ the rules file points the editor at.
Read this when you want to edit a Tale project in an AI editor without hand-typing JSON. Come back when the editor invents fields or wires the wrong agent shape — the answer is almost always that the schema under .tale/reference/ is stale.
A worked setup
Initialise a project — the CLI writes the rules file and the schema mirror in the same step:
tale init my-org
cd my-org
ls -a
# .cursor/ .github/ .tale/ .windsurfrules
# CLAUDE.md agents/ workflows/ integrations/ branding/CLAUDE.md (also installed as the Cursor .mdc, the Copilot .md, and the Windsurf rules file) tells the editor where to look before editing a config:
Before creating or editing any config, read the relevant schemas and implementation code in
.tale/reference/to understand the valid structure, fields, and constraints. Use existing config files in the project as examples.
The directive matters because every editor under load skips schema reads unless told otherwise. The rules file is the contract; the schema mirror is the ground truth.
What lives where
| Path | What it is |
|---|---|
agents/ | One JSON file per agent — instructions, knowledge, tools, model. |
workflows/ | Workflow JSON configs, grouped by category subdirectory. |
integrations/<slug>/config.json | Integration manifest — operations, auth method, allowed hosts. |
integrations/<slug>/connector.ts | Optional TypeScript connector for REST shapes the manifest can't cover. |
branding/branding.json | Org branding — colours, logos, email senders. |
.tale/reference/ | Read-only schema mirror; regenerated by tale init and tale upgrade. |
The reference tree is bytes-identical to the schemas the platform validates against at deploy time. Treat it as canonical: when a field name in a hand-written config disagrees with the reference, the reference wins.
Working with the editor
The rules file names three rules each editor enforces while editing:
- Agents bind, delegate, attach. An agent can simultaneously bind integrations (
integrationBindings), delegate to other agents (delegates), and attach workflows (workflows). Read existing configs before introducing a new binding. - Workflows use integration operations. A workflow step references integration operations declared in
integrations/<slug>/config.json. Editing a step against an operation that does not exist will fail validation. - Naming is enforced. Agent filenames match
[a-z0-9][a-z0-9_-]*\.json. Workflow step slugs match[a-z0-9][a-z0-9_-]*. Integration directories are lowercase alphanumeric with hyphens or underscores.
When the editor proposes a change, ask it to cite the file in .tale/reference/ it relied on. If it cannot, regenerate the mirror with tale upgrade and try again.
Where this fits
AI-assisted development is the editing path; deployment is the publishing path. Once a config passes editor validation, tale deploy reconciles it against the platform — the same schema check, this time as a gate. For features the editor cannot reach (the in-product builder, the visual workflow editor), the Platform tab is the canonical surface; the AI-editor path here is for projects that prefer config-as-code.