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

Scenario	Handling
Sub-skill unavailable	Stop and prompt user to install/enable
State file missing	Initialize with first state
Invalid state ID	Fall back to first state, log error
Transition loop detected	Break loop, ask user to continue
Preset upgrade condition met	If user confirms, transition to appropriate state
Decision timeout	Re-ask question, preserve context

---

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:

Question	Where to Find Answer
Current phase?	.yaml state file → state field
Goal?	SKILL.md → Goal section
Completed steps?	.yaml → completed_states
Pending steps?	SKILL.md → Phase reference
Last decision?	.yaml → variables.last_user_decision

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() }}