Step 1: Initialize Work Directory (If Needed)

Before checking for active work, ensure agent-work directory exists:

if [ ! -d "agent-work" ]; then echo "Initializing work directory..." cp -r .claude/skills/work-tracking/scaffold agent-work echo "Work directory initialized from scaffold" fi

What this does:

• Checks if agent-work/ directory exists

• If not, copies the scaffold structure from .claude/skills/work-tracking/scaffold/

• Creates the necessary bin/ and completed/ subdirectories

• Sets up the work tracking system ready for use

Step 2: Check for Active Work

ALWAYS do this first before creating new work.

ls agent-work/*.md 2>/dev/null

If there's an active work file:

• Show it to the user

• Ask: "There's an active work file: [filename]. Would you like to:

• Continue with this work

• Complete it first

• Create new work file"

• Wait for user response before proceeding

If no active work file, proceed to Step 3.

Step 3: Create Work File (MANDATORY)

You MUST run this script BEFORE writing ANY code.

./agent-work/bin/work-create.sh <task_name>

Task Naming Rules

Use descriptive, snake_case names:

• ✅ improve_pdf_generation

• ✅ add_watermark_support

• ✅ fix_date_parsing_bug

• ✅ implement_resume_validator

• ❌ new_feature

• ❌ stuff

• ❌ update

What the script does:

• Generates UTC timestamp automatically

• Creates agent-work/{timestamp}_{task_name}.md

• Populates it with the template

Example output:

Created work file: agent-work/20251230164521_improve_pdf_generation.md

Step 4: Populate Work File

Immediately after creation, populate the work file with:

• Context - What problem is being solved, why it's needed

• Value Proposition - What the feature achieves, business value

• Alternatives Considered - Other approaches considered with trade-offs

• Todos - Specific, actionable tasks with [ ] checkboxes

• Acceptance Criteria - How to verify the work is complete

• Notes - Any additional information

See EXAMPLES.md for complete, real-world examples of properly filled work files.

Step 5: Implement Work (Update Todos Progressively)

⚠️ CRITICAL: Update the work file after EACH todo, not after all todos.

Wrong Approach (DO NOT DO THIS):

1. Complete all 5 todos
2. Update work file once with all 5 checked

Correct Approach (DO THIS):

1. Complete Todo 1
2. Update work file: [ ] Task 1 → [x] Task 1
3. Complete Todo 2
4. Update work file: [ ] Task 2 → [x] Task 2
5. And so on...

Why This Matters:

• If AI crashes, progress isn't lost

• Maintains accurate progress tracking

• Allows resumption from any point

• User can see real-time progress

How to Update:

Use the Edit tool to change [ ] to [x] for completed todos:

Edit: agent-work/{timestamp}_{task_name}.md Old: - [ ] Update PDF generator to verify text layer New: - [x] Update PDF generator to verify text layer

Step 6: Complete Work

When ALL todos are checked as [x], complete the work:

./agent-work/bin/work-complete.sh <name>

Examples:

./agent-work/bin/work-complete.sh improve_pdf_generation ./agent-work/bin/work-complete.sh 20251230164521_improve_pdf_generation

What the script does:

• Updates status to completed ({completion_timestamp})

• Moves file to agent-work/completed/ directory

Example output:

Completed and moved: agent-work/completed/20251230164521_improve_pdf_generation.md

Work File Locations

• Active work: agent-work/{timestamp}_{task_name}.md

• Completed work: agent-work/completed/{timestamp}_{task_name}.md

Enforcement Checklist

First time in project:

• Initialized agent-work directory from scaffold

Before writing ANY code, verify:

• Checked for active work files

• Created work file using work-create.sh

• Populated Context, Value Proposition, Alternatives, Todos, Acceptance Criteria

• Work file exists in agent-work/ directory

While implementing:

• Update work file after EACH todo completion

• Use Edit tool to change [ ] to [x]

• Never batch todo updates

After completing all todos:

• Verify ALL todos are marked [x]

• Run work-complete.sh to move file to completed/

Common Mistakes to Avoid

❌ Starting to code before creating work file ✅ Always create work file first

❌ Updating all todos at once after completing all work ✅ Update each todo immediately after completion

❌ Not checking for active work files ✅ Always check first: ls agent-work/*.md

❌ Using vague task names like "update" or "fix" ✅ Use descriptive names like "fix_date_parsing_bug"

❌ Forgetting to complete work file when done ✅ Run work-complete.sh to move to completed/

Summary

MANDATORY SEQUENCE:

• First time only: Initialize agent-work directory from scaffold (Step 1)

• Check for active work: ls agent-work/*.md (Step 2)

• Create work file: ./agent-work/bin/work-create.sh <task_name> (Step 3)

• Populate work file with context, todos, etc. (Step 4)

• Implement EACH todo + update work file immediately after EACH (Step 5)

• Complete work: ./agent-work/bin/work-complete.sh <name> (Step 6)

NO CODE WITHOUT A WORK FILE. NO EXCEPTIONS.

For complete examples of work files, see EXAMPLES.md .