Iron Law

Validate the manual workflow before automating.

Red Flags

• "I can write tests later" → STOP. Write them now.
• "This change is too small to review" → STOP. Small bugs become P0 incidents.
• "I don't need to check previous cycle insights" → STOP. You will repeat the same mistake.
• "This is good enough" → STOP. Check the checklist.
• "No time to follow every step" → STOP. Skipped steps cost 3x more later.

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

Command	Purpose	Output
create	define a workflow	Confirmation with definition summary and variable list
run	execute a saved workflow (accepts --topic, --output_dir, --background, and custom --var flags)	Foreground progress or a queued background-run receipt with run ID
schedule	persist a recurring daemon job for a saved workflow	Job summary with schedule, status, and next-run metadata
runs	inspect recent background runs for a workflow	Table: run ID, trigger, status, created/updated timestamps
recall	search prior session recall summaries linked to workflows	Ranked recall hits with topic, workflow name, tags, and handoff path
list	show saved workflows	Table: name, step count, preset flag, last run date. Include all presets.
show	inspect a workflow (resolves variables if --topic provided)	Full definition with resolved variables
delete	remove a workflow	Confirmation with name of deleted workflow

Variables

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

Variable	Source	Default
{{topic}}	--topic "X" flag at runtime	required if present in definition
{{date}}	auto-generated	YYYY-MM-DD of run start
{{output_dir}}	--output_dir "path" flag	current working directory
{{run_id}}	auto-generated	{workflow_name}-{timestamp}

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 /second-claude-code:workflow run <preset>:

Preset	Steps	Use For
autopilot	research -> analyze -> write(--skip-research --skip-review) -> review -> refine	End-to-end content production
quick-draft	research -> write	Fast first draft
quality-gate	review -> refine	Post-hoc quality check on existing content

Definition

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

State

Data directory: ${CLAUDE_PLUGIN_DATA} is set by the plugin system. If unavailable, fall back to .data/ relative to the plugin root. Before writing state files, verify the directory exists with mkdir -p.

• Active state: ${CLAUDE_PLUGIN_DATA}/state/workflow-active.json
• Run log: ${CLAUDE_PLUGIN_DATA}/workflows/{name}-run.json
• Daemon jobs: ${CLAUDE_PLUGIN_DATA}/daemon/jobs.json
• Background runs: ${CLAUDE_PLUGIN_DATA}/daemon/runs/*.json
• Session recall index: ${CLAUDE_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 /second-claude-code:* 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

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