# Sq Run

> Runs a squadron pipeline step by step via the prompt-only executor, driving cf operations, dispatches, reviews, checkpoints and commits. Use when the user asks to run a pipeline such as slice, design or tasks.

- Skill: `ecorkran/sq-run` (Agent Skill)
- Install (CLI): `npx get-skill add ecorkran/sq-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ecorkran/sq-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ecorkran (https://skillmd.com/u/ecorkran)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/ecorkran/sq-run

---


# 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:

1. **Scan** the argument string for known verbosity tokens at the tail end: `-v`, `-vv`, or `--verbose`.
2. **Capture** any matched tokens as `<verbose_flags>` (e.g., `-v` or `-vv`). If none are present, `<verbose_flags>` is an empty string.
3. **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`, empty `chars`, and `yield_time_ms` set to `300000`.
  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:
```bash
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 as `run_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:

```json
{
  "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 FAIL
- `on-fail`: Pause if verdict is FAIL
- `always`: Always pause — **you MUST stop and wait for the user**
- `never`: 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_switch` is present, note the recommended model — like dispatch, this cannot be automated.
- If `emit` includes `clipboard`: pipe the summary to the system clipboard via Bash using a heredoc (try `pbcopy`, then `xclip -selection clipboard`, then `wl-copy` — warn if none available). Confirm the character count to the user.
- If `emit` includes `rotate`: 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:

```bash
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:

```bash
sq run --step-done <run-id>
```

If the step included a review action, include the verdict:

```bash
sq run --step-done <run-id> --verdict <PASS|CONCERNS|FAIL>
```

---

## Get Next Step

After marking a step done, request the next step:

```bash
sq run --prompt-only --next --resume <run-id>
```

Parse the JSON output:
- If it contains `step_name` and `actions`, loop back to the Main Loop.
- If it contains `"status": "completed"`, the pipeline is done — proceed to Completion.

---

## Error Handling

- If `sq run --prompt-only` fails on initialization: show the error and stop.
- If `sq run --step-done` fails: 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-fail` checkpoint: 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.

