{"protocol":"clank-doc/1","frameworkVersion":"0.13.0","slug":"conversational-build","title":"Conversational application building","description":"clank compose turns an application request and an agent proposed blueprint into a reviewable, deterministic Clank project. The agent proposes data; Clank remains the authority that validates, plans, and writes the application.","group":{"id":"agents","title":"Agents and generation"},"url":"https://docs.clank.run/docs/conversational-build","source":"docs/conversational-build.md","headings":["The shortest safe loop","Interactive use","External agent protocol","Mutation and rollback contract","Existing applications"],"tableOfContents":[{"id":"the-shortest-safe-loop","title":"The shortest safe loop","level":2},{"id":"interactive-use","title":"Interactive use","level":2},{"id":"external-agent-protocol","title":"External agent protocol","level":2},{"id":"mutation-and-rollback-contract","title":"Mutation and rollback contract","level":2},{"id":"existing-applications","title":"Existing applications","level":2}],"markdown":"# Conversational application building\n\n`clank compose` turns an application request and an agent-proposed blueprint into a reviewable,\ndeterministic Clank project. The agent proposes data; Clank remains the authority that validates,\nplans, and writes the application.\n\n## The shortest safe loop\n\nAsk a coding agent to create a data-only `clank.app.ts`, then review it without changing any\napplication files:\n\n```sh\nclank compose ./my-app \\\n  --request=\"Build a private client portal with projects and tasks\" \\\n  --proposal=./proposals/client-portal.clank.app.ts \\\n  --json\n```\n\nThe result is a `clank-compose-result/1` review containing:\n\n- the review ID;\n- a SHA-256 digest for the exact generated plan;\n- every file that would be created, updated, or left unchanged;\n- blueprint counts and validation warnings; and\n- the exact apply command.\n\nRun that returned command only after inspecting the plan:\n\n```sh\nclank compose /absolute/path/to/my-app \\\n  --review=<review-id> \\\n  --approve=<plan-digest> \\\n  --json\n```\n\nThe target path is part of the stored review. The approval is accepted only when its digest\nexactly matches the reviewed plan and every destination still has the same baseline. If a person,\nagent, formatter, or build changes a reviewed file first, Clank rejects the review as stale.\n\n## Interactive use\n\nRun `clank` and choose **Build with an agent**, or call `clank compose` directly in a terminal.\nThe direct command prints the proposed file changes and asks whether to apply, revise, or cancel.\nRevision is available when an external agent executable is configured:\n\n```sh\nclank compose ./my-app \\\n  --request=\"Build a lightweight issue tracker for a design team\" \\\n  --agent=./tools/my-clank-agent\n```\n\nClank can request up to four proposals in one conversation by default. Set `--max-turns` from 1\nthrough 10 and `--agent-timeout` from 1 through 600 seconds. Non-interactive agents and CI should\nuse `--json` and perform review and approval as separate commands.\n\n## External agent protocol\n\n`--agent` is provider-neutral. Its value must be a real executable file, not a shell command or a\nsymbolic link. Clank starts it without a shell, writes one JSON object to standard input, and\nexpects one JSON object on standard output.\n\nThe request is `clank-compose-request/1`:\n\n```json\n{\n  \"protocol\": \"clank-compose-request/1\",\n  \"turn\": 1,\n  \"intent\": \"Build a private client portal\",\n  \"feedback\": null,\n  \"currentBlueprint\": null,\n  \"history\": [],\n  \"constraints\": {\n    \"frameworkVersion\": \"0.13.0\",\n    \"approvalRequired\": true,\n    \"dataOnlyBlueprint\": true,\n    \"neverIncludeSecrets\": true\n  }\n}\n```\n\nThe response must be exactly a `clank-compose-proposal/1` proposal:\n\n```json\n{\n  \"protocol\": \"clank-compose-proposal/1\",\n  \"type\": \"proposal\",\n  \"message\": \"Added private projects, task ownership, and workspace roles.\",\n  \"blueprint\": {\n    \"name\": \"Client Portal\",\n    \"description\": \"A private project and task workspace.\",\n    \"entities\": {\n      \"projects\": {\n        \"description\": \"A customer project.\",\n        \"ownership\": \"user\",\n        \"displayField\": \"name\",\n        \"fields\": {\n          \"name\": { \"type\": \"string\", \"min\": 1, \"max\": 120 }\n        }\n      }\n    },\n    \"routes\": [\n      { \"path\": \"/\", \"view\": \"Projects\", \"entity\": \"projects\" }\n    ],\n    \"actions\": {}\n  }\n}\n```\n\nThe blueprint must satisfy the complete [AI blueprint](blueprints.md) contract. Unknown response\nfields, invalid protocols, invalid blueprints, output over 1 MiB, nonzero exits, and deadlines fail\nclosed. Diagnostic stderr is capped at 32 KiB.\n\nClank passes only a small process environment needed to start the executable; arbitrary CLI and\napplication environment variables are not forwarded. For an existing app, the normalized current\nblueprint is sent as context but `deployment.env` is withheld and preserved if the next proposal\nomits it.\n\nThe executable still runs as the current operating-system user and therefore has that user's file\nand network authority. Use a program you trust, sandbox it when appropriate, and prefer\n`--proposal` when a coding agent has already prepared the blueprint through its own controlled\nenvironment.\n\n## Mutation and rollback contract\n\nCreating a review writes only an owner-readable file under:\n\n```text\n.clank/compose-reviews/<review-id>.json\n```\n\nApplication files are not written until approval. Apply uses temporary files and atomic renames.\nIf any destination or parent becomes unsafe, including through a symbolic link, Clank restores\nfiles already touched during that apply. A successful apply retains an owner-readable audit record\nat:\n\n```text\n.clank/compose-sessions/<review-id>.json\n```\n\n`.clank/` is excluded from generated repositories. Reviews can contain product requirements and\npublic deployment configuration, so treat the directory as private local state. Never place\npasswords, access tokens, private keys, or other secrets in a blueprint; provision deploy secrets\nwith `clank secrets`.\n\n## Existing applications\n\nPoint compose at a generated application to evolve it:\n\n```sh\nclank compose . \\\n  --request=\"Add customer notes and a read-only auditor role\" \\\n  --agent=./tools/my-clank-agent \\\n  --json\n```\n\nThe current normalized blueprint becomes agent context. The review reports `update` only for files\nwhose generated contents change. Hand-written changes to generated destinations are visible in the\nbaseline and are never silently overwritten after review.\n\nAfter applying, verify the product contract and deploy normally:\n\n```sh\nnpm install\nnpm test\nclank doctor\nclank deploy\n```\n\nComposition does not authenticate or deploy. It produces the same ordinary, inspectable Clank\nproject that `clank create` and `clank generate` produce, so the existing build, migration,\nsecurity, MCP, and deployment contracts remain in force.\n"}