datasqrl/datasqrl-plugin/start

Build or deploy

This skill answers two kinds of request Decide which kind the request is, read that section only, and stop where it stops.

Building DataSQRL runs a containerized agent that writes into the working tree and leaves its work uncommitted, for the user to commit. Deploying writes nothing locally: the DataSQRL Cloud API deploys a commit that GitHub already has. The user's own commit and push sits between the two, so no request is both, and neither section continues into the other on its own.

A request that adds or edits a project file is a building event even when it says "deployment", such as a production environment config or a new deploy target (see Building with DataSQRL). A request that tells to deploy a project in DataSQRL Cloud, or a commit to ship, i.e. asks for nothing to be written in the project, can be considered deploying (see Deploying to DataSQRL Cloud](#deploying-to-datasqrl-cloud)).

Building with DataSQRL

A containerized code agent builds DataSQRL projects. It holds the SQRL compiler, the DataSQRL skill library, a test runner and reviewing judges. This section sets up the environment, routes to a lane, invokes the agent, and reports what the agent returns.

A request to resolve a GitHub issue — the user gives its URL or number, or points at an issue the DataSQRL Cloud assistant filed — goes to the `resolve-issue` skill instead of the steps below. It locates the project from the issue, writes the issue as requirements, and picks the lane the fix needs.

There are two lanes, and this section takes them in order:

File ownership

The containerized agent writes every file of the DataSQRL project: .sqrl scripts, *-package.json configs, GraphQL schemas and operations, connector configs, test files and snapshots and a web UI (SPA, admin panel, dashboard, charts) over the project's GraphQL API. Agent will construct the directories and create layout itself for a green-field project while it complies with the existing tree if there is a project.

In Lane B only: adr/requirements_<ts>.md file is created via the requirements skill. In Lane A the container persists the request string itself. The resolve-issue skill writes that file from the issue in either lane.

Step 1 — Setup (both lanes A&B, before routing)

1a. Make sure the right agent image is here

The agent comes as two editions: the open-source edition, which anyone can pull, and the pro edition, which DataSQRL gives access to with a token. `reference/agent-setup.md` explains how datasqrl-agent.sh picks it.

Run this once, at the start, without prompting:

CODEAGENT="${CLAUDE_PLUGIN_ROOT}/scripts/datasqrl-agent.sh"
[ -f "$CODEAGENT" ] || CODEAGENT=datasqrl-agent.sh   # fall back to PATH
 
bash "$CODEAGENT" --image-exists

It prints one line naming the selected image and its edition, then:

• `is present · edition: … · version: …`: tell the user in one line which edition and version this build uses, and continue to 1b.
• `is missing`: ask the user which edition they want, with what each needs, from the table in `reference/agent-setup.md`: the open-source edition needs nothing; pro needs either the token DataSQRL gave them, set as DATASQRL_PRO_TOKEN in their shell profile followed by a restart of their coding agent, or their own GitHub account with pro access and a one-time docker login ghcr.io. Mention the edition the line named as the one currently selected. Once the user has answered and done what their edition needs, run that edition's pull command from the table.

When the user mentions pro access while the open-source edition is in use, give them the same two pro routes; after the pro pull, every later command selects pro by itself.

If it fails

datasqrl-agent.sh prints the cause and the fix. Relay its message, then apply the matching step.

Leave the token in the user's hands: they set it in their own shell. A token pasted into this conversation would land in your transcript.

1b. Locate the project

Run these two commands in the directory the user wants to build in:

git rev-parse --show-toplevel   # the repository root
git rev-parse --show-prefix     # this project's path inside the repo (empty at the root)

Their output determines the layout completely. An empty --show-prefix means the project is the repository. A non-empty one means the project is a subdirectory, and sibling projects may exist alongside it. Route from that output.

If a repository is found

Report it in one line:

Building <prefix> in the git repository <toplevel>. Ask user if that is not the repo he/she meant.

If no repository is found

A run requires a git repository. Creating one changes the user's filesystem, so ask:

There is no git repository here. Shall I run git init in <absolute path of cwd>?

The current directory is the default. Offer the parent instead when the user names a sibling project or shared data catalog this project must read (live in the same repository) and gives no path.

Mounts

The repository is bind-mounted, so the agent's writes land in the user's real files. The invocation directory is the only writable mount; the rest of the repository (sibling projects or shared data catalog) is mounted read-only for reference. Invoke from the project directory.

1c. Settle the run choices

A run takes three choices: the harness, the model provider and the model. Settle them once per conversation, before the first run, and remember them for the rest of this conversation; nothing writes them to disk. Read `reference/agent-setup.md` whenever needed or the user asks about editions, providers, models, variables or AWS, when a check below reports a problem, and when a run fails to start because of a missing variable or an AWS login.

For the run choices, take the source that applies:

1. The user named them in this conversation: use those.
2. An earlier run in this project: when .datasqrl_agent_results.json exists, ask in one line whether to reuse the harness, provider and model of its last run.
3. Otherwise, ask once. Run bash "$CODEAGENT" --show-options and tell the user the default: the anthropic provider, with its default models for planning and implementation. Name the providers it marks ready, say that any provider in the list works once its variables are set, and ask which they want.

The user makes each choice: the provider, the model and, for Amazon Bedrock, the AWS profile. Present the options neutrally, without promoting any provider, model or agent.

Then check the choices:

bash "$CODEAGENT" --check-config [--provider <id>] [--model <model>] [--harness <name>]

• For Amazon Bedrock, put AWS_PROFILE=<name> in front of bash once the user has named the profile, here and on every run command.
• Status READY: continue to Step 2.
• Status NOT READY: follow the table in `reference/agent-setup.md`, then run the check again. Ask the user to set every key in their own shell, and keep the values out of this conversation.

Step 2 — Route

Lane A — patch

Lane A applies a change the request already determines: the agent applies it, updates the tests and documentation it affects, runs the tests and repairs what it breaks. A change that needs designing, refactoring or a major update belongs in Lane B.

Choose Lane A when all three hold:

• the project already exists
• the request fully determines the minor change
• it touches a handful of existing files at most

Typical examples for Lane A (patch work):

• adjusting a time window or watermark,
• renaming a field,
• changing a setting on an existing connector,
• adding a test case, or reconciling tests and docs after the user hand-edited a .sqrl file.

Lane B — full workflow

Any one of these selects Lane B:

• there are no .sqrl files yet
• a new sub-project or environment configuration
• substantial new logic
• the user supplied payloads, a spec, a ticket, or acceptance criteria — that material has to be carried into a plan verbatim
• the request leaves anything open that you would otherwise decide on the user's behalf
• user asked for a plan
• user requested to write a requirement file

A single Lane B signal, then select Lane B. Route without asking when the signals are clear; when the decision needs the user, ask in one line and state your default.

Step 3, Lane A — Patch

Use the patch skill. That is the entire lane.

Pass the user's request as a single quoted string, including any context they gave. The agent implements, compiles and tests directly, and iterates one time if necessary.

When the run finishes, report the result and stop — see After any agent run.

Step 3, Lane B — Full workflow

Stages 2 and 4 belong to the user. Each is a stop: wait for their reply before continuing. Stages 3 and 5 each start a detached run, hand the user the commands to follow it, and start a background --wait that tells you when the run ends

How each stage ends

Every stage ends with a question you need answered, or an offer to run the next stage.

The offer invites the user to read the file; advance to the next stage on their reply. Report a failed run and end the turn.

1. Requirements, and 2. their review

Use the `requirements` skill, unless the user already has a requirements document. Planning converts every gap in the requirements into a recorded assumption, so run this stage for a simple-sounding request too.