unclejobs-ai/second-claude-code/workflow

Resolve runtime paths before file or script operations.

Iron Law

Validate the manual workflow before automating.

Red Flags

• "I'll test the steps after building the full workflow" → STOP, because the Iron Law says validate the manual workflow before automating — run each step individually first.
• "Step 3 can use step 2's output from memory" → STOP, because steps pass data through files, never memory — shared memory between steps does not exist.
• "This 12-step workflow covers everything" → STOP, because the maximum is 10 steps — split oversized workflows into smaller pipelines.
• "Step A references step C which references step A, but it should work" → STOP, because circular dependencies are detected and rejected at create-time — restructure the dependency graph.
• "I'll add the topic variable at runtime" → STOP, because every {{variable}} must resolve before execution starts — unresolved tokens abort the run.

Workflow

Create, save, and run reusable multi-step workflows where each step passes files to the next. Workflows support runtime parameterization so a single definition serves multiple topics and contexts. Treat each workflow run as a skill-attached task that can later be scheduled, resumed, or routed through background infrastructure.

When to Use

• A workflow repeats across sessions
• The job needs 3 or more skill invocations in sequence
• Research, writing, review, and refinement should run as one named process
• The same workflow applies to different topics (use --topic at runtime)

Subcommands

Variables

Workflow definitions use {{placeholder}} syntax for values resolved at runtime.

Pass custom variables with --var key=value. See references/workflow-definition.md for resolution rules, default values, and full definition examples.

Execution Model

1. Load the workflow definition.
2. Resolve variables: merge defaults with runtime flags, inject built-ins. Abort if any {{...}} token remains unresolved.
3. Identify parallel groups: consecutive steps marked parallel: true without cross-references run concurrently.
4. Run sequential steps one at a time as fresh subagents. Pass data through files, never memory.
5. Save run state (including resolved variables) after every step.
6. Resume from saved state if interrupted.

Automation Readiness

• Workflows should be background-ready: every step must be able to run without interactive chat context.
• Prefer stable file outputs over ephemeral chat-only instructions.
• When a workflow is reused often, treat it as the canonical task payload for future automation or companion-daemon scheduling.
• Recurring delivery should be modeled as a daemon job plus workflow variables, not as a free-form cron prompt.
• Use workflow recall to find prior sessions before rebuilding the same chain from scratch.

Presets

Run a named preset with /scc:workflow run <preset>:

Definition

Store workflow definitions at <plugin-data>/workflows/{name}.json. See references/workflow-definition.md for step fields, data flow, and a full worked example.

State

Data directory: Resolve <plugin-data> through the runtime path contract. Before writing state files, verify the directory exists with mkdir -p.

• Active state: <plugin-data>/state/workflow-active.json
• Run log: <plugin-data>/workflows/{name}-run.json
• Daemon jobs: <plugin-data>/daemon/jobs.json
• Background runs: <plugin-data>/daemon/runs/*.json
• Session recall index: <plugin-data>/daemon/recall/index.jsonl

See references/workflow-definition.md for the canonical state schema.

Constraints

• Maximum 10 steps per workflow
• Every step must declare an output
• Step compatibility is validated through input_from and output
• Circular reference detection: At create-time, build a dependency graph from input_from references. If a cycle is detected (A → B → C → A), abort with an error listing the cycle path. This check runs before any execution.
• Every {{variable}} in the definition must resolve at runtime (from flags, defaults, or built-ins)
• Variable names must be alphanumeric plus underscores: [a-zA-Z_][a-zA-Z0-9_]*
• Variable value injection safety: Variable values (from --topic, --var, or defaults) must be treated as positional content strings, never as raw argument fragments. Before interpolation, validate that no variable value matches the flag-injection pattern --[a-zA-Z][-a-zA-Z0-9_]* (two dashes followed by a letter, then optional alphanumeric/dash/underscore characters). If a value contains that pattern, abort the run with: "Variable '{name}' contains a flag-like pattern ('--...'). Pass structured data instead of embedding flags."
• Every skill referenced in a step must be a valid /scc:* command. Validate at create-time and abort with an error listing unknown skills.
• on_fail: retry allows up to 2 retry attempts per step (3 total attempts: 1 original + 2 retries). After the retry limit is exhausted, the step is treated as abort.

Gotchas

• Never assume shared memory between steps.
• Save outputs immediately so later failures do not erase earlier work.
• Split oversized workflows into smaller pipelines rather than exceeding the step limit.
• Always provide --topic when running a workflow that uses {{topic}}.
• Variable resolution happens once at run start. Mid-workflow changes require a new run.
• When resuming, the orchestrator reuses resolved_vars from saved state -- it does not re-resolve from flags.
• Do not create a workflow referencing skills that don't exist.

Subagents

pipeline-orchestrator: { model: sonnet, tools: [Read, Write, Bash], constraint: "resolve variables, execute sequentially, persist state" }
pipeline-step-executor: { model: varies, constraint: "read input file and write output file only" }