workflow-management

name	workflow-management
description	Create, configure, and manage Syntropic137 workflow templates (phase definitions, agent config, YAML schema, $ARGUMENTS substitution, input declarations, and design patterns like RIPER-5)

Workflow Management: Syntropic137

When you need to build a new automated workflow, or understand why an existing one behaves unexpectedly, start here. Workflows are the core unit of work: YAML-defined multi-phase agent pipelines that run in isolated Docker workspaces.

NEVER hardcode task descriptions or repository names into phase prompts. Use $ARGUMENTS for the task and {{repository}} in the URL so the same template works for any repo and any task.

When to Use This Skill

Use this when you are: designing a new workflow template, debugging unexpected phase behavior, choosing the right design pattern (RIPER-5 vs lighter options), or understanding the input/output wiring between phases.

Not needed when you just want to run an existing workflow; use the execution-control skill instead. Not needed when you want to list or inspect already-registered workflows; use /syn-workflow for that.

Phases Are Claude Code Sessions

Each workflow phase is a full Claude CLI invocation. That means phase prompts can invoke any slash command (/syn-*, /commit, /review, etc.) and any installed skill directly by name. When designing a phase prompt, consult the Claude Code commands and skills references to know what's available:

• Commands: https://code.claude.com/docs/en/commands.md
• Skills: https://code.claude.com/docs/en/skills.md

Write phase prompts the same way you'd write instructions to Claude Code in a terminal session.

The Core Model: Templates vs Executions

A workflow template is a reusable definition (like a class). A workflow execution is a running instance (like an object). One template can have many concurrent executions with different tasks, repos, and inputs.

Templates define phases: each phase is one Claude CLI invocation in its own workspace. Phases run sequentially by default; outputs from phase N feed into phase N+1 via {{phase-id}} substitution.

Phase workspaces are ephemeral. Each phase starts in a fresh Docker container: no git branches, staged files, commits, or file changes from a prior phase carry over. The only thing that crosses a phase boundary is the artifact output. If a phase needs to do git work (commit, push, gh pr create), it must do so in the same phase that made the changes. If a later phase needs those changes, either collapse the phases or have the earlier phase output a patch/diff artifact that the later phase applies.

Designing a Workflow: 4 Phases

1. Choose the right pattern

Pick based on complexity:

Pattern	Phases	Use When
RIPER-5	5	Feature development, complex bug fixes: full Research→Innovate→Plan→Execute→Review loop
Research→Analyze→Synthesize	3	Investigation work, architectural questions
Parallel Analysis	2	Broad codebase surveys: frontend/backend/infra simultaneously
Human-in-the-Loop	3+	Any workflow requiring approval before execution

RIPER-5 is the recommended default for implementation work. It has a HUMAN_IN_LOOP gate at the Plan phase: the agent pauses and waits for your approval before writing any code.

2. Define your input declarations

Every input the workflow needs must be declared in input_declarations. This drives the CLI flags, the dashboard UI, and the {{variable}} substitution in prompts:

input_declarations:
  - name: task
    description: "What to implement or fix"
    required: true
  - name: repository
    description: "owner/repo"
    required: false
    default: "syntropic137/syntropic137"

task maps to $ARGUMENTS and the --task flag. Named inputs map to {{name}} in prompts and --input name=value on the CLI.

3. Wire phases with substitution

Each phase's prompt_template can reference:

• $ARGUMENTS: the task description
• {{variable}}: a declared input value
• {{phase-id}}: the output artifact from a previous phase

Phase outputs chain forward automatically. Keep the substitution chain explicit: if phase 3 needs phase 1's output, reference {{phase-1-id}} directly rather than relying on phase 2 to pass it through.

4. Right-size the model per phase

Use cheaper models for read-only, exploratory phases; use more capable models where reasoning depth matters:

• haiku: reading files, formatting output, simple classification
• sonnet: most phases, balanced cost/capability
• opus: complex implementation, architecture decisions, deep analysis

A well-designed RIPER-5 workflow might use sonnet for Research, opus for Innovate and Plan, opus for Execute, sonnet for Review.

Creating a Workflow

Validate first, then register:

syn workflow validate ./my-workflow.yaml
syn workflow create --type implementation --repo owner/repo --description "..."

Or load from the source repo: just seed-workflows loads all YAML files from workflows/examples/.

See workflow-management skill for full YAML schema reference including allowed_tools, timeout_seconds, execution_type: PARALLEL, and API-based creation.

Common Mistakes

Phases referencing wrong substitution keys. If phase 3 uses {{phase_2}} but phase 2's phase_id is analyze, the substitution silently fails. Always match {{phase-id}} exactly to the phase_id field.

Every phase using opus. Costs scale fast with opus. Audit your model assignments whenever a workflow runs expensive.

Missing input_declarations for inputs used in prompts. If {{repository}} appears in a prompt but isn't declared, it won't be substituted. Validate the workflow before registering.

Splitting git operations across phases. If phase 1 commits code and phase 2 tries to push or open a PR, phase 2 will start with a clean workspace and find nothing to push. All git operations, including commit, push, and gh pr create, must happen in the same phase that wrote the changes. If the workflow design requires separating research/implementation from the git step, have the implementation phase output a patch artifact and have the git phase apply it in a fresh clone.

Skipping HUMAN_IN_LOOP on destructive workflows. Any workflow that writes, commits, or deploys should pause for human review. Automation without oversight is how you get force-pushed to main at 2am.

Escalation Point

If a workflow design isn't working as expected after two attempts (phases not receiving outputs, models ignoring injected context), stop and inspect the execution detail before redesigning. Run syn control status <exec-id> and check each phase's artifact_id. The artifact content will tell you exactly what was passed forward.

Integration

Design here, run with execution-control, then monitor with observability. Install community workflows via the marketplace skill instead of building from scratch.

CLI Quick Reference

syn workflow list
syn workflow show <id>
syn workflow validate ./my-workflow.yaml
syn workflow run <id> --task "Implement retry logic"
syn workflow run <id> --task "Fix auth bug" --input repository=owner/repo
syn workflow delete <id>