/stagent-setup

name: stagent-setup
description: "Bootstrap a dev workflow session (for /stagent:start): parse flags, derive a topic from the task description, call setup-workflow.sh, and hand off to the workflow loop skill. Does NOT drive the state machine — that's stagent:stagent's job."

Workflow Setup

Single-purpose skill: **materialize a new `state.md`** for the current Claude Code session by parsing the user's flags, picking a kebab-case topic, and invoking `setup-workflow.sh`. Used by `/stagent:start`; not invoked directly by users.

Boundary

| Responsibility | Who | |---|---| | Parse `--mode` / `--flow` / task description from `$ARGUMENTS` | This skill | | Derive a kebab-case topic from the task | This skill | | Run `setup-workflow.sh` (which writes `state.md`, sets up scratch, registers cloud session) | This skill | | Handle `setup-workflow.sh` exit codes (0 → success, 2 → active conflict, other → error) | This skill | | Read `state.md`, run stage loop, post artifacts, advance state machine | **`stagent:stagent` skill (not this one)** |

By the time this skill returns control, `state.md` exists at the session's run dir. The caller (`commands/start.md`) then invokes `stagent:stagent` to drive the loop.

Plugin path resolution

Every Bash tool call that runs a plugin script starts with the same two lines — session-cached path then filesystem fallback:

P=$(cat ~/.config/stagent/plugin-root 2>/dev/null)
[[ -n $P && -d $P/scripts ]] || P=$(ls -d ~/.claude/plugins/cache/*/stagent/*/ 2>/dev/null | head -1)

Shell vars don't persist across Bash-tool calls — repeat these two lines in every call.

Protocol

Step 0 — Parse flags and announce

P=$(cat ~/.config/stagent/plugin-root 2>/dev/null)
[[ -n $P && -d $P/scripts ]] || P=$(ls -d ~/.claude/plugins/cache/*/stagent/*/ 2>/dev/null | head -1)
eval "$("$P/scripts/parse-workflow-flags.sh" '$ARGUMENTS')" || exit 1
"$P/scripts/print-start-banner.sh" "$MODE" "$WORKFLOW_FLAG" "$WF_TYPE"

Parser exports `MODE` / `WORKFLOW_FLAG` / `WF_TYPE` / `DESCRIPTION`. Relay the banner to the user. If errors were printed, stop and wait for the user to retry with valid flags.

Step 1 — Derive a topic

Pick a short kebab-case slug from `$DESCRIPTION` (e.g. `"add user auth"` → `user-auth`; `"fix login bug"` → `login-bug`). If the description is empty or too vague, ask ONE clarifying question, just enough to name the topic.

Briefly tell the user: `I'll use topic \`<topic>\` for this workflow.`

Step 2 — Call setup-workflow.sh

P=$(cat ~/.config/stagent/plugin-root 2>/dev/null)
[[ -n $P && -d $P/scripts ]] || P=$(ls -d ~/.claude/plugins/cache/*/stagent/*/ 2>/dev/null | head -1)
"$P/scripts/setup-workflow.sh" --topic="<topic>" [--flow="$WORKFLOW_FLAG"] [--mode="$MODE"]

Pass `--flow` only when `$WORKFLOW_FLAG` is non-empty. Pass `--mode` only when the user was explicit (otherwise the script defaults).

Step 3 — Handle the exit code

**Exit 0 — success.** `setup-workflow.sh` already printed the run directory and the initial stage's I/O context. Tell the user **exactly one** line: `Workflow session initialised; stage loop will take over.` Then return control — do not invoke any other skill or script from here. `commands/start.md` Step 2 invokes `stagent:stagent` to start the loop.

**Exit 2 — session already has an active (or interrupted) workflow.** The script prints the existing topic + status. Do NOT offer to archive-and-restart blindly (that silently discards in-progress work). Relay the script's message verbatim and give the user three choices:

• `/stagent:interrupt` — pause the existing workflow (safe, preserves state)
• `/stagent:continue` — resume the existing workflow (treat this new request as the one to discard)
• `/stagent:cancel` — archive or hard-delete the existing run, then retry `/stagent:start` with the new task

Only re-run `setup-workflow.sh --force` if the user **explicitly** asks to discard the existing run in this turn. Default stance: refuse, ask user to choose.

**Exit 1 or other — real error.** Relay the stderr verbatim. Common cases:

• Config validation errors (`❌ stage '<x>': ...`) — workflow.json / stage .md problems. If the user passed `--flow=<their-path>`, that's their config; point at the offending file and stop. If no `--flow` was passed, it's a plugin bug — surface it.
• `session_id is unknown` — SessionStart hook didn't populate the cache. Tell the user to restart their Claude Code session.
• Cloud fetch failure — relay and suggest retry / network check / `--mode=local` escape hatch.

Do NOT auto-fix the user's workflow files. Do NOT proceed. Wait for user confirmation before retrying.

Rules

• This skill **does not drive the stage loop**. It exits after `setup-workflow.sh` succeeds. The loop is `stagent:stagent`'s job.
• This skill **does not call `update-status.sh`**, **does not read stage artifacts**, **does not launch subagents**. Just bootstrap.
• Do NOT invoke any other skill from here. The chain is coordinated at the command-file level (`commands/start.md`).
• When `setup-workflow.sh` returns exit 2, **do not auto-force**. The user's active work must be preserved unless they explicitly say otherwise.