| 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 \` 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.
