/lightweight-task-workflow

Lightweight Task Workflow

Task list + session state for multi-session work.

What It Does

Maintains three files in .claude/:

• tasks.md - numbered checklist
• requirements.md - implementation specs, verification steps
• session.md - current task, progress, context

Claude follows a strict state machine and prefixes every message with the current state (e.g., 🔵 STATE: WORKING).

Setup

Say "create a plan" and Claude will:

1. Ask you to describe your tasks
2. Ask about requirements, testing standards, and verification steps
3. Create .claude/tasks.md (checklist)
4. Create .claude/requirements.md (specs + verification)
5. Create .claude/session.md (current state)

Then say "continue" to start working.

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)      │
           └──────────────────┘

Note: To ensure Claude uses the skill, you may want to @-mention it. Claude may deviate from the workflow based on hard-coded plan mode instructions, so it may be more compliant by exiting plan mode.

Files

tasks.md:

- [ ] Task 1: Extract UserService
- [x] Task 2: Add tests
- [ ] Task 3: Update documentation

requirements.md:

## Global Guidelines
- No breaking changes to public APIs
- Add logging for error cases
- Follow existing code style

## Verification & Definition of Done
- npm test - all tests pass
- npm run lint - no errors
- npm run build - successful

## Task 1: Extract UserService
- Move user methods from AppService to new UserService
- Maintain backward compatibility
- Update dependency injection

## Task 2: Add tests
- Cover happy path and error cases
- Include null/undefined edge cases
- Mock external dependencies

session.md:

**Current Task:** Task 3

## What's Done
- Extracted UserService (commit abc123)
- Added tests (commit def456)

## Next Steps
1. Update documentation

## Context
- Using npm for package management
- Found edge case: user.email can be null