lightweight-task-workflow

What this skill does

# Lightweight Task Workflow

**🚨 CRITICAL: YOU MUST FOLLOW THE STATE MACHINE BELOW 🚨**

**🚨 EVERY SINGLE MESSAGE MUST START WITH: `🔵 STATE: [STATE_NAME]` 🚨**

NOT JUST THE FIRST MESSAGE. EVERY. SINGLE. MESSAGE.

When you read a file - prefix with state.
When you run a command - prefix with state.
When you explain something - prefix with state.
When you ask a question - prefix with state.

Example:
```
🔵 STATE: WORKING
Reading requirements.md...

🔵 STATE: WORKING
I can see the requirements specify...

🔵 STATE: WORKING
Now running tests...

🔵 STATE: WORKING
Test results show...
```

This skill is a persistent todo list based on 3 files in `.claude/`: `tasks.md` (checklist), `requirements.md` (specs), `session.md` (current state).

When user says "continue", you MUST:
1. Run `pwd` to check current working directory
2. Announce `🔵 STATE: CHECK_STATUS`
3. Read `.claude/session.md` from the current project directory
4. Follow the state machine below based on the Status field

**STATE MACHINE:**

```
                         user: "continue"
                                ↓
                       ┌────────────────┐
                   ┌───│ CHECK_STATUS   │←──────────┬──────────┐
                   │   │ Read session.md│           │          │
                   │   └────────┬───────┘           │          │
                   │            │                   │          │
        Status=    │            │ Status=           │          │
        "Complete" │            │ "in progress"     │          │
                   │            │                   │          │
                   ↓            ↓                   │          │
           ┌───────────┐  ┌──────────────┐         │          │
           │ AWAITING_ │  │ WORKING      │←────┐   │          │
           │ COMMIT    │  │              │     │   │          │
           │           │  │ Read:        │     │   │          │
           │ Ask       │  │ requirements │     │   │          │
           │ permission│  │ tasks.md     │     │   │          │
           │ STOP      │  │              │     │   │          │
           └─────┬─────┘  │ Write:       │     │   │          │
                 │        │ session.md   │     │   │          │
       user: yes │        └──────┬───────┘     │   │          │
                 │               │             │   │          │
                 │               │ task done   │   │          │
                 │               │             │   │          │
                 │               ↓             │   │          │
                 │        ┌──────────────┐     │   │          │
                 │        │ VERIFY       │     │   │          │
                 │        │              │     │   │          │
                 │        │ Run steps    │     │   │          │
                 │        │ from         │─────┘   │          │
                 │        │ requirements │ fail    │          │
                 │        └──────┬───────┘         │          │
                 │               │                 │          │
                 │               │ pass            │          │
                 │               │                 │          │
                 │               ↓                 │          │
                 │        ┌──────────────┐         │          │
                 │        │ COMPLETE     │         │          │
                 │        │              │         │          │
                 │        │ Write:       │         │          │
                 │        │ session.md   │         │          │
                 │        │ Status=      │─────────┘          │
                 │        │ "Complete"   │                    │
                 │        └──────────────┘                    │
                 │                                            │
                 ↓                                            │
           ┌──────────────────┐                              │
           │ MARK_TASK_       │                              │
           │ COMPLETE         │                              │
           │                  │                              │
           │ Write: tasks [x] │                              │
           │ Write: session.md│──────────────────────────────┘
           │ (next task)      │
           └──────────────────┘
```

**🚨 STATE DEFINITIONS - FOLLOW EXACTLY 🚨**

**CHECK_STATUS:**
```
ACTIONS:
1. Run pwd
2. Read .claude/session.md
3. Look at Status field
4. IF Status="Complete" OR "ready to commit" → Go to AWAITING_COMMIT
5. IF Status="in progress" OR missing → Go to WORKING

DO NOT: Read other files, launch agents, do anything except route
IF ERROR: STOP and tell user what failed
```

**AWAITING_COMMIT:**
```
ACTIONS:
1. Say: "Task X is complete. May I mark Task X as complete in tasks.md?"
2. STOP - wait for user response
3. IF user says yes → Go to MARK_TASK_COMPLETE
4. IF user says no → STOP, await further instruction

DO NOT: Read files, launch agents, work on next task, do anything except ask permission and STOP
IF ERROR: STOP and tell user what failed
```

**MARK_TASK_COMPLETE:**
```
ACTIONS:
1. Write tasks.md: Change [ ] to [x] for current task
2. Write session.md: Update to next task with Status="in progress"
3. Go to CHECK_STATUS

DO NOT: Read other files, launch agents, research next task
IF ERROR (e.g., plan mode, can't write): Say "I cannot edit files: [reason]" and STOP
NEVER try alternative actions if write fails
```

**WORKING:**
```
REMINDER: EVERY message in this state must start with: 🔵 STATE: WORKING

ACTIONS:
1. Read requirements.md
2. Read tasks.md
3. Work on current task
4. Update session.md after TDD cycles
5. When task done → Go to VERIFY

EVERY message you send while WORKING must have the state prefix.
When you read a file → prefix with state
When you run tests → prefix with state
When you explain results → prefix with state

DO NOT: Skip to next task, work on multiple tasks
IF ERROR: Document in session.md as blocker, STOP
```

**VERIFY:**
```
REMINDER: EVERY message in this state must start with: 🔵 STATE: VERIFY

ACTIONS:
1. Read Verification section from requirements.md
2. Run all verification commands
3. IF all pass → Go to COMPLETE
4. IF any fail → Go to WORKING (treat as blocker)

EVERY message you send while VERIFYING must have the state prefix.

DO NOT: Skip verification, claim complete without running checks
IF ERROR running verification: STOP and tell user
```

**COMPLETE:**
```
ACTIONS:
1. Write session.md: Set Status="Complete"
2. Go to CHECK_STATUS

DO NOT: Read files, launch agents, ask permission (that happens in AWAITING_COMMIT)
IF ERROR writing: STOP and tell user
```

**CRITICAL: State Announcements**

**ALL messages MUST be prefixed with your current state.**

Format:
```
**🔵 STATE: [STATE_NAME]**

[Your message here]
```

When transitioning:
```
**🟢 TRANSITION: [STATE_A] → [STATE_B]**
```

Example:
```
**🔵 STATE: CHECK_STATUS**

Reading session.md to check current task status...

**🟢 TRANSITION: CHECK_STATUS → AWAITING_COMMIT**

**🔵 STATE: AWAITING_COMMIT**

Task 2 is complete and ready for you to commit. May I mark Task 2 as complete in tasks.md?
```

## When to Use This Skill

Activate when the user:
- Says "create a plan", "setup tasks", "new task list"
- Says "continue", "continue plan", "resume work", "where were we"
- Is working on multi-step projects that span multiple sessions

## ⚠️ CRITICAL: Task Management System

**THIS SKILL REPLACES Claude Code's built-in TodoWrite functionality.**

**NEVER use the following tools:**
- ❌ TodoWrite
- ❌ TodoRead
- ❌ Any built-in todo/task tracking features

**ALWAYS use this skill's files instead:**
- ✅ `.claude/tasks.md` for task checklists
- ✅ `.claude/requirements.md` for plans and implementation specs
- ✅ `.claude/session.md` for session context and recovery

**Why this matters:** Using TodoWrite creates workflow conflicts. The built-in todo system stores tasks in internal state (not visible as files),