workflow-init

name	workflow-init
description	Routing entry point for the Claude Code workflow. Inspects
model	sonnet

IMPORTANT: Interactive session required. Hard-fail in non-interactive contexts (claude -p, /loop, subagents).

Purpose

First step of every workflow session. Routes on GH issue context: Path A (#N + intent:clarified) skips interview; Path B (#N, no label) pre-fills interview; Path C (no #N) runs full interview and auto-creates a tracking issue.

Procedure

Read rules/github-issues.md before WI-2 — on-demand-only, never auto-injected; the meta label, intent:clarified, closes_issues insertion order, and the sub-issue open-state gate all come from it.

Step WI-1 — Resolve <PLANS_DIR>

Canonical: skills/_shared/resolve-plans-dir.md. Substitute the resolved absolute path for every <PLANS_DIR> placeholder below. Subagent prompts must receive literals — they cannot expand $VAR.

Step WI-2 — Driver loop

The driver (bin/workflow/workflow-init-driver) handles WI-3..WI-9: token detection, gh issue view fetch for each N in ISSUES, CLOSED detection, label extraction, meta classification (meta strip / open sub-issue guard), Aggregate WIP check (all N: all_same / all_none / any_other), route decision, and context.md write. The driver writes the checkpoint and <SID>-context.md directly under PLANS_DIR (outside git repos → ENFORCE_WORKTREE does not apply).

Invocation: node "$AGENTS_CONFIG_DIR/bin/workflow/workflow-init-driver" <raw-tokens> 2>/dev/null (<raw-tokens> = issue number tokens like #15 or #15 #22 — not the full user prompt)

On resume (after ask_user): node "$AGENTS_CONFIG_DIR/bin/workflow/workflow-init-driver" --resume <CHECKPOINT> --answer '<token>'

Read all KEY=VALUE output lines. Dispatch on ACTION=:

ACTION	Meaning	What to do
invoke	Next skill ready	Run NEXT_SKILL via Skill tool
done	Driver complete	Proceed to WI-10; follow PATH_DECISION= at WI-12 (Path C still runs WI-10 onward — no jump)
blocked	Unrecoverable	Show REASON= + NEXT_HINT= and stop
ask_user	User decision needed	Percent-decode OPTIONS_DISPLAY= (encoded like QUESTION=), present via AskUserQuestion; re-invoke with --resume <CHECKPOINT> --answer '<token>'
emit_sentinel	Driver requests sentinel	Emit SENTINEL= via separate Bash call

ask_user interruptions and their options:

• ASK_ID=wip_conflict: Issue(s) # are in progress in another session. Driver answers: Continue (recommended) / Abort. On Continue: for each N in ISSUES, driver runs wip-state set <N> (override for other; claim for none; idempotent for same). On Abort: ACTION=blocked REASON=user_aborted.
• ASK_ID=wip_rc2: wip-state set rc=2 for #N. Driver answers: Continue (acknowledge risk — driver treats as none, proceeds) / Abort.
• ASK_ID=wip_error: wip-state check failed (transient auth / session-id resolution failure — check $CLAUDE_ENV_FILE or $CLAUDE_SESSION_ID, rc=non-zero). Driver answers: Continue (treat as none, proceed) / Abort. Advisory: driver logs [wip-state check failed for #N — proceeding as 'none'].
• ASK_ID=closed_reopen_<N>: Issue #N is CLOSED. Driver answers: reopen / remove / abort. Remove is only offered when len(closes_issues) >= 2.
• ASK_ID=meta_select: meta issue has open sub-issues. Driver answers: #<M> (select sub-issue) / abort.
• ASK_ID=fetch_failed_path_c: gh issue view fetch failed. Driver answers: continue (Path C) / abort.

PATH_DECISION= values on ACTION=done:

• A — all N carry intent:clarified (and FORCE_PATH_B is not set from a fresh WIP claim).
• B — any N lacks intent:clarified OR WIP was freshly claimed for all N (FORCE_PATH_B=true). ALL_NONE path: none + for each N in ISSUES, wip-state set <N> (from fresh claim), then set FORCE_PATH_B=1 — even when intent:clarified is present, FORCE_PATH_B routes to B. ISSUES[0] becomes closes_issues[0]; all entries become closes_issues in insertion order. ISSUES[@] are processed symmetrically.
• C — zero issues (ISSUES=()) OR NON_GITHUB=1.
• META — all issues carry meta label and have no open sub-issues.

Step WI-10 — Parallel survey launch (all Paths)

Dispatch the survey-code + survey-history subagents per skills/_shared/subagent-concurrency.md SC-P (independent — distinct artifact paths, neither reads the other's output). For each: prompt session-id=<resolved>, context_path=<PLANS_DIR>/<session-id>-context.md, artifact_path=<PLANS_DIR>/<session-id>-survey-{code|history}.md, instruct to read context_path + follow skills/<survey-code|survey-history>/SKILL.md Procedure, write to artifact_path, do NOT invoke make-outline-plan. Substitute <PLANS_DIR> with the absolute path resolved at WI-1.

Note: the Stop-guard silence during dispatch is automatic (PostToolUse marks the step in_progress). Do not emit NEXT_STEP_PAUSE.

Step WI-11 — Post-check

Apply skills/_shared/survey-artifact-valid.md to each artifact. On invalid: emit <<WORKFLOW_SURVEY_AGENT_FAILED: survey-code>> or <<WORKFLOW_SURVEY_AGENT_FAILED: survey-history>>. Fall through to WI-12 on failure — do NOT abort. clarify-intent handles missing-or-invalid artifacts.

Step WI-12 — Path-specific steps

Path META — meta label issue

WI-8 open sub-issue guard ensures all ISSUES[@] have no open sub-issues before reaching this path.

• PM1. node "$AGENTS_CONFIG_DIR/bin/workflow/set-workflow-type" --session "$SESSION_ID" --type wf-meta --advance --step workflow_init --complete (single Bash call — records workflow_type and completes workflow_init together; no --next since the next action is fixed at PM2).
• PM2. echo "<<WORKFLOW_CLARIFY_INTENT_NOT_NEEDED: meta issue — WF-META type; intent confirmed from issue body>>".
• PM3. Use /issue-create --skip-survey with --verdict bulk-sub-of --parent <meta-N> --manifest <file> to create all planned sub-issues under the meta parent in a single bulk pass.
• PM4. Invoke make-outline-plan. (next-step auto-skips detail and 8 other non-applicable WF-CODE steps after outline completes — make-detail-plan is never invoked in WF-META.)

Path A — intent:clarified

• A1. Write <PLANS_DIR>/<session-id>-intent.md (strip sentinels from body): # Agreed Requirements — <session-id>, then immediately a **Title:** <human-readable one-line title> line (same data contract as clarify-intent CI-4), ## Issues (one - #<N>: <title> line per entry in ISSUES[@], in insertion order, no annotations), ## Background / Motivation, ## Scope / Constraints, ## Accepted Tradeoffs (none — capture at outline stage). Title for each N from WI-4's gh issue view; fetch failure → - #<N>: (title unavailable). Never omit ## Issues or ## Accepted Tradeoffs — latter is detail-planner.md Approved Scope gate. ## Issues is SSOT for closes_issues (canonical parser: hooks/lib/parse-closes-issues.js). ISSUES[0] is the first entry; it becomes closes_issues[0]; this entry becomes closes_issues[0].
• A1a. Record closes_issues into session state: node "$AGENTS_CONFIG_DIR/bin/parse-closes-issues" --session "$SESSION_ID" (separate Bash call; routes through the write-once cache in hooks/workflow-state/session-facts.js).
• A1b. Set session title: node "$AGENTS_CONFIG_DIR/bin/cc-session-title" set-issue "$(pwd)" "<PLANS_DIR>"
• A2. Label + board-card parity for all N. Invoke skills/workflow-init/scripts/path-a-label-and-board.sh with "${REPO_MAP_ARGS[@]}" followed by all entries of ISSUES[@] as positional args; export PLANS_DIR, SESSION_ID, AGENTS_CONFIG_DIR. Adds intent:clarified (--add-label "intent:clarified") to each related entry (fail-closed — on failure writes ABORT marker <PLANS_DIR>/<session-id>-workflow-init-aborted-pathA-multiN-label-failure.md + exit 1). For every issue it runs ensure-board-card.sh (best-effort, warn-and-continue). Both idempotent.
• A3. node "$AGENTS_CONFIG_DIR/bin/workflow/next-step" --advance --step workflow_init --complete (no --next — the next action is fixed at A3a, not next-step's judgment), then, unchanged, as a separate Bash call: .

When --advance is called without --next, no ACTION= block is ever emitted — proceed directly to the next documented step above rather than waiting on next-step's judgment.

Path B — issue exists, no intent:clarified

• B1. Write <PLANS_DIR>/<session-id>-issue-prefill.md with <!-- Issue #<N> seed for clarify-intent. Confirm framing, do not start from scratch. -->, # Issue #<N>: <title>, <body>.
• B2. echo "<<WORKFLOW_MARK_STEP_workflow_init_complete>>" (separate Bash call).
• B3. Invoke clarify-intent with #<N> in args so step 1a auto-detect fires.

Path C — no issue

• C1. echo "<<WORKFLOW_MARK_STEP_workflow_init_complete>>" (separate Bash call).
• C2. Invoke clarify-intent (no pre-fill).

Skip Conditions

Cannot be skipped. For docs-only bypass: echo "<<WORKFLOW_MARK_STEP_workflow_init_complete>>" directly.