dev-skills

Appearance

Work Tracking ​

Purpose ​

You help the user manage parallel workstreams in a git repository. Each workstream lives in its own git worktree and is tracked by a WORK.md file at the worktree root. This skill defines the lifecycle of a workstream and the conventions for maintaining WORK.md so that any agent session — current or future — can understand what's happening and pick up where work left off.

Core Concepts ​

  • One worktree = one workstream. A worktree is the unit of work. There is no task list within a worktree — the worktree itself is the thing being tracked.
  • WORK.md is the source of truth. It describes the purpose, acceptance criteria, current status, and full history of the workstream. It lives at the root of the worktree.
  • WORK.md serves multiple audiences. Everything above the --- divider is for humans scanning quickly. The session log below is for agents resuming work.
  • WORK.md gets committed and pushed. It lives on the branch so that work can be resumed from any computer. When the branch merges, WORK.md can either be removed in the merge commit or left in as a historical record of how the work happened — either is fine.

File Format ​

See WORK.template.md for the template and WORK.example.md for a realistic mid-flight example.

The structure is:

text
# {Title}

**Purpose:** {One sentence}

**Done when:**
- {Verifiable criterion}

**Status:** Not Started | In Progress | Blocked | Needs Review | Done

**Progress:** ~N%

---

## Plan

{Optional checklist or sequence of steps}

---

## Session Log

### Session N — {timestamp}

**What happened:**
- {Items completed, decisions made, things tried}

**Blocked on:** {Nothing, or the blocker}

**Next:** {What the next session should do first}

Field definitions ​

  • Purpose: One sentence. A human reads this to remember what this workstream is about. Write it so someone with no context understands the goal.
  • Done when: Objective, verifiable criteria. The agent uses these to know when work is complete. These must be specific enough that a different agent could evaluate them.
  • Status: One of: Not Started, In Progress, Blocked, Needs Review, Done. The dashboard reads this field.
  • Progress: Rough percentage. Doesn't need to be precise — it's a signal for humans scanning the overview. Update it when meaningful progress happens.
  • Plan: Optional. If the human provides a detailed checklist, put it here. If the agent decomposes the work, put that here too. If the "done when" criteria are sufficient, omit this section.
  • Session Log: Append-only, newest first. Every agent session that does meaningful work adds an entry.

Operations ​

Overview: See all work in flight ​

When the user asks what's happening in a repo, or wants to see all active work:

  1. Run git worktree list to find all worktrees.
  2. For each worktree (excluding the main worktree), check for WORK.md.
  3. Read the header section (everything above the first ---) from each WORK.md.
  4. Also check for recent Claude Code session activity — look for .claude/ directory metadata or recent file modification timestamps in the worktree to determine if a session is currently active or recently active.
  5. Present a formatted summary. Example:
text
## Work in Flight — my-app

| Worktree           | Status      | Progress | Purpose                          | Last Active |
|--------------------|-------------|----------|----------------------------------|-------------|
| auth-jwt-migration | In Progress | ~60%     | Replace sessions with JWT        | 2 hours ago |
| fix-ios-nav        | Needs Review| done     | Fix mobile nav on iOS Safari     | yesterday   |
| dark-mode          | Not Started | ~0%      | Add dark mode with color tokens  | —           |

If a worktree has no WORK.md, note it as "No WORK.md — unknown status."

Start: Begin a new workstream ​

When the user wants to start new work:

  1. Create a new branch: git branch <branch-name>.
  2. Create a worktree: git worktree add <path> <branch-name>. Use a consistent location for worktrees (e.g., ../<repo>-worktrees/<name> or a .worktrees/ directory — follow whatever convention the repo already uses, or ask the user).
  3. Create WORK.md at the worktree root using the template. Fill in the title, purpose, and "done when" criteria based on what the user describes. Set status to Not Started.
  4. Add a Session 1 log entry noting the workstream was created.
  5. If the user wants to begin working immediately, update status to In Progress and proceed with the work.

Resume: Pick up existing work ​

When the user wants to continue work on an existing worktree:

  1. Read WORK.md fully — header for goals, latest session log for context.
  2. Check git status and git diff main to understand current branch state.
  3. Check if there are uncommitted changes from a prior session.
  4. Present a brief orientation to the user:
    • What this workstream is about (purpose)
    • Where things stand (status, progress, latest session summary)
    • What the previous session said to do next
    • Any uncommitted changes or anomalies
  5. Propose a plan for this session, then begin work when the user approves.

Pause: Record progress and step away ​

When the user wants to stop work on a workstream, or when you're ending a session:

  1. Update the session log with a new entry covering what happened.
  2. Update Status and Progress in the header.
  3. Write a clear, specific Next section so a future agent can pick up without guessing.
  4. If there's a Plan checklist, check off completed items.
  5. Commit the WORK.md update (and any other work) to the branch.
  6. Present a brief work report in chat:
text
## Work Report: Auth JWT Migration

**Purpose:** Replace sessions with JWT for mobile client support

**Status:** In Progress — ~75%

**This session:** Implemented refresh middleware, updated 8 of 14 route guards

**Key decisions:** Using Redis for refresh tokens after all (scale concern)

**Blocked on:** Nothing

**Next:** Update remaining 6 route guards, then run integration tests

Done: Complete a workstream ​

When all "done when" criteria are met:

  1. Update status to Done and progress to 100%.
  2. Add a final session log entry.
  3. The user handles merge/PR workflow — this skill doesn't manage that.
  4. After merge, the worktree can be removed with git worktree remove.

Agent Behavior Rules ​

  • Always read WORK.md before starting work in a worktree. If it exists, orient yourself. If it doesn't, ask the user if they want to create one.
  • Always update WORK.md before ending a session. The session log is how future agents (and the human) understand what happened.
  • Write "Next" instructions as if talking to a stranger. Don't assume the next agent has any context beyond WORK.md and the code diff. Be specific: "Implement refresh middleware at POST /auth/refresh" not "Continue the auth work."
  • Keep the header section scannable. Purpose is one sentence. Status is one value. Progress is a rough number. A human should understand the state in under 5 seconds.
  • Don't modify "Done when" criteria unless the user explicitly asks you to. These are the contract. If you think they need to change, say so and let the user decide.
  • Log decisions and dead ends. Future agents waste time re-exploring approaches that already failed. If you tried something and it didn't work, say what and why in the session log.