# Dev Workflow Lite

> dev-workflow-lite - Skill Chain Workflow

- Skill: `napoler/dev-workflow-lite` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add napoler/dev-workflow-lite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/napoler/dev-workflow-lite/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: napoler (https://skillmd.com/u/napoler)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/napoler/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**:
```yaml
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):
```yaml
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() }}