sq run
Run a squadron pipeline via the prompt-only executor.
Input parsing
Parse what the user typed after $sq-run using this three-step procedure:
- Scan the argument string for known verbosity tokens at the tail end:
-v,-vv, or--verbose. - Capture any matched tokens as
<verbose_flags>(e.g.,-vor-vv). If none are present,<verbose_flags>is an empty string. - Remove the matched tokens from the argument string. The remaining text is split: the first word becomes
<pipeline>, the rest becomes<target>.
If the pipeline name is missing after stripping verbosity tokens, show the usage below and stop.
Usage:
$sq-run <pipeline> [target] [-v|-vv] — run a pipeline (e.g., $sq-run P456 152 -v)
Waiting on the command
The sq commands this skill runs can take several minutes, print their own progress, and
finish on their own. Waiting costs nothing; checking on them does, because every check is a
full model turn.
- Run each command once. Never start it again because it seems slow.
- If the command is still running when the tool returns and you are given a session ID, wait
on that session with
write_stdin, emptychars, andyield_time_msset to300000. Repeat exactly that until the command exits. - Between waits, do nothing else: no status checks, no reading files, no commentary.
If Codex blocks the command
If Codex rejects or blocks the sq command for sandbox or approval reasons — an approval
request that cannot be granted, a sandbox denial, or a network error such as "host
unreachable" from a command that needs a provider or GitHub — tell the user plainly that
this is Codex's sandbox, not the model provider and not squadron's configuration. Tell
them to run sq install-commands --ide codex from a terminal: it writes the Codex rules file
(~/.codex/rules/squadron.rules) that lets these sq commands run.
The "Codex sandbox approval rule" section of squadron's README has the details. Do not
suggest changing provider settings, API keys, or squadron config for this failure.
Step 0: Validate and Initialize
Run:
sq run <pipeline> <target> <verbose_flags> --prompt-only
This initializes the pipeline run and outputs the first step's instructions as JSON. Capture:
- The
run_id(printed to stderr asrun_id=<value>) - The JSON step instructions (printed to stdout)
If the command fails (invalid pipeline, missing params), show the error and stop.
Main Loop
Parse the JSON output. The structure is:
{
"run_id": "...",
"step_name": "...",
"step_type": "...",
"step_index": 0,
"total_steps": 6,
"actions": [
{
"action_type": "cf-op|dispatch|review|checkpoint|commit|summary|devlog",
"instruction": "Human-readable description",
"command": "shell command to run (if applicable)",
"model": "model alias (if applicable)",
"model_switch": "/model alias (if applicable)",
"template": "template name (if applicable)",
"trigger": "checkpoint trigger (if applicable)",
"resolved_instructions": "resolved instructions (if applicable)"
}
]
}
For each action in the step's actions list, execute based on action_type:
cf-op
Run the command field via Bash. Example: cf set phase 4, cf build.
dispatch
If the command field is present:
Write the assembled context prompt to a temp file via Bash (mktemp).
Replace {tmp_path} in the command field with the temp file path.
Run the command via Bash. Capture stdout as the dispatch response.
Remove the temp file after capture (rm -f <path>).
Else:
This is in-session work — you perform the task described in instruction.
If model_switch is present (e.g., /model opus), note the recommended model for the user. Model switching cannot be automated — only the user can issue /model commands. State which model is recommended so the user can switch if desired.
review
Run the command field via Bash. Example: sq review slice 152 --model glm52 -v.
Capture the output. The review will produce a verdict (PASS, CONCERNS, FAIL) and persist the review file automatically.
checkpoint
Evaluate based on the trigger field and the previous review's verdict:
on-concerns: Pause if verdict is CONCERNS or FAILon-fail: Pause if verdict is FAILalways: Always pause — you MUST stop and wait for the usernever: Skip (continue automatically)
IMPORTANT: When a checkpoint triggers, you MUST stop all pipeline work immediately. Do not continue to the next action or step. Present the review findings to the user and explicitly ask:
"Checkpoint triggered ({trigger}). Verdict: {verdict}. Continue or abort?"
Wait for the user's response before proceeding. This is not optional.
commit
Run the command field via Bash. Example: git add -A && git commit -m 'phase-4: ...'.
summary
Generate a summary of the current session following the resolved_instructions.
- If
model_switchis present, note the recommended model — like dispatch, this cannot be automated. - If
emitincludesclipboard: pipe the summary to the system clipboard via Bash using a heredoc (trypbcopy, thenxclip -selection clipboard, thenwl-copy— warn if none available). Confirm the character count to the user. - If
emitincludesrotate: note to the user that session rotation cannot be automated in prompt-only mode. Suggest they start a new Claude Code session and paste in the summary to seed context if needed.
Always write the summary to the conventional file path via Bash, regardless of emit contents:
SUMM_DIR=~/.config/squadron/runs/summaries
PIPELINE_NAME=<pipeline name from step JSON>
PROJECT_NAME=$(cf status --json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('project','unknown'))" 2>/dev/null || echo "unknown")
mkdir -p "$SUMM_DIR"
cat << '__SQ_END__' > "$SUMM_DIR/${PROJECT_NAME}-${PIPELINE_NAME}.md"
SUMMARY_TEXT
__SQ_END__
Replace PIPELINE_NAME with the step_name or pipeline identifier from the run JSON, and SUMMARY_TEXT with the generated summary. This file enables $sq-summary --restore to seed context in a new session without a run-id.
Do not attempt to start a new session — present the summary as text only.
devlog
Execute the work described in instruction — write a DEVLOG entry capturing the pipeline run state.
After Each Step
After completing all actions in a step, mark it done:
sq run --step-done <run-id>
If the step included a review action, include the verdict:
sq run --step-done <run-id> --verdict <PASS|CONCERNS|FAIL>
Get Next Step
After marking a step done, request the next step:
sq run --prompt-only --next --resume <run-id>
Parse the JSON output:
- If it contains
step_nameandactions, loop back to the Main Loop. - If it contains
"status": "completed", the pipeline is done — proceed to Completion.
Error Handling
- If
sq run --prompt-onlyfails on initialization: show the error and stop. - If
sq run --step-donefails: show the error but don't lose progress. The run state is preserved and can be resumed. - If a checkpoint pauses execution: present findings to the user. On abort, the run can be resumed later with
sq run --prompt-only --next --resume <run-id>. - If a review verdict is FAIL with an
on-failcheckpoint: stop and present findings. Do not silently continue.
Completion
When the pipeline returns "status": "completed", provide a brief summary:
- Steps completed and their verdicts
- Artifacts created (design files, task files, review files)
- Commits made during the pipeline
- Any unresolved concerns or deferred items
Run sq run --status <run-id> for a final state summary if needed.