Dev Workflow Lite

dev-workflow-lite - Skill Chain Workflow

Type: Multi-Skill Orchestrated Workflow Pattern: State Machine + Skill Routing States: {{ states|length }} phases

Core Concept

This skill chains together multiple sub-skills into a coherent workflow. Each state represents a phase of work; the skill automatically routes to the next state based on completion, user decisions, or conditional logic.

Decision Core

State Management

State file: <workflow-area>/.dev-workflow-lite.yaml (auto-generated per task)

Required fields:

state: explore          # Current state ID
started_at: 2026-06-13 # Timestamp
completed_states: []   # History of finished states
variables: {}          # Persisted across states

Optional phase fields (per-state):

verify_result: "pass"  # For verify states
archived: false        # For archive states

Phase Auto-Detection

On each invocation:

1. Read state file (if exists)
2. Determine current state from state field
3. Route to corresponding sub-skill
4. Sub-skill completes → update state → transition to next

Preset Detection (if defined)

{% if preset_detection %} The following preset shortcuts are available:

{% for preset in preset_detection %}

• {{ preset.if }} → routes to {{ preset.then }} {% endfor %}

If preset conditions are met, the workflow skips to the designated state variant. {% else %} No preset shortcuts defined. Full workflow always used. {% endif %}

Decision Points (Blocking)

When reaching a state with decision_point, must use AskUserQuestion and wait for explicit user choice before proceeding.

{% for state in states %} {% if state.decision_point %} {{ state.name }} ({{ state.id }}):

• Question: "{{ state.decision_point.question }}"
• Options: {{ state.decision_point.options }} {% endif %} {% endfor %}

Critical: Do NOT proceed without user confirmation at decision points.

Phase Reference

{% for state in states %}

{{ loop.index }}. {{ state.name }} ({{ state.id }})

Sub-skill: {{ state.skill }}

{% if state.next is mapping %} Transition Logic: {% for cond in state.next %}

• Condition: {{ cond.condition }} → Next: {{ cond.state }} {% endfor %} {% else %} Next State: {{ state.next }} {% endif %}

{% if state.end %} Terminal: This state completes the workflow. {% endif %}

{% endfor %}

Error Handling Quick Reference

Workflow Transition Rules

Automatic transitions (happen after successful sub-skill completion): {% for state in states %} {% if not state.end and state.next is not mapping %}

• {{ state.id }} → {{ state.next }} (on success) {% endif %} {% endfor %}

Conditional transitions (require checking variables): {% for state in states %} {% if state.next is mapping %} {% for cond in state.next %}

• {{ state.id }}: {{ cond.condition }} → {{ cond.state }} {% endfor %} {% endif %} {% endfor %}

Files & Structure

workdir/
├── .dev-workflow-lite.yaml         # State file (auto-created)
├── (sub-skill outputs)     # Varies by sub-skill
└── README.md               # Optional documentation

Best Practices

1. Always persist state - After each phase, write to state file
2. Re-read state before decisions - Keep context fresh
3. Log all errors - Track failures to avoid repetition
4. Ask for confirmation at decision points - Never assume
5. Mark state as complete before transition - Use Edit on state file

🔒 Reliability for Long-Running Workflows

Complex skill chains can span many tool calls and long time periods. To prevent context loss, drift, and failure, follow these patterns inspired by /plan (Manus):

1. State File is Single Source of Truth

• Never rely on memory - All progress, decisions, and variables go in .dev-workflow-lite.yaml
• Append-only updates - Never delete history, only add new state
• Immutable logs - Once written, state entries are never modified (except for current_state)

2. Recitation Pattern (Pre-Decision)

Before any major decision or tool call:

1. Read .dev-workflow-lite.yaml (refresh current state)
2. Read SKILL.md (refresh workflow definition)
3. Check goal alignment (am I on the right phase?)
4. Then proceed

Why: After ~50 tool calls, the original goal gets buried. Re-reading brings it back to the attention window.

3. Periodic Re-Planning Check

If this workflow is expected to run > 100 tool calls:

• Break into sub-workflows: Use nested skill chains (one chain calls another)
• Or switch to multi-agent mode: Delegate portions to sub-agents with their own context
• Or use /session-catchup: After long breaks, run recovery script

4. Error Recovery Protocol

When an error occurs:

Step 1: Log to state file
  variables:
    last_error: "<error message>"
    last_error_at: "<timestamp>"
    last_error_attempt: <count>

Step 2: Tell the user immediately
  "Error: <message>. Attempt N. Fixing by <approach>."

Step 3: Try different approach (NEVER repeat same failing action)

Step 4: If 3 failures → escalate to user
  "I've tried: A, B, C. All failed. How would you like to proceed?"

5. Context Drift Prevention (CLAUDE.md Compliance)

This skill chain must adhere to:

• Rule: All file writes go through PreToolUse scope guard
• Rule: Never modify state file concurrently (use Edit with atomic updates)
• Rule: No assumptions about phase — always read state, don't guess
• Rule: Decision points require AskUserQuestion, no text-only prompts

6. The 5-Question Reboot Test

Anytime context might be stale (after /clear, long pause), verify:

If can't answer → run recovery script before proceeding.

Integration with Other Skills

• /plan: Use plan skill to design the workflow before generating
• /skill-creator: Create custom sub-skills referenced in this chain
• /session-catchup: Recover state after context reset

Generated by: skill-chain-generator Template version: 1.0 Generated at: {{ now() }}