claude-skills/skills/using-tasks/SKILL.md

---
name: using-tasks
version: 1.0.0
description: >
  Policy skill for working with an existing `.tasks/` board (per-task files + STATUS.md).
  Use whenever the user is switching between tasks, resuming a paused task, starting a new
  task, asking "where were we", says "use task management system", "pause", "switch to X",
  "what's the status", "update status", or wants to track progress across parallel workstreams.
  Trigger on any context-switching or multi-task coordination question in a code project.
  If `.tasks/` is missing or non-canonical (no per-task `<task-slug>.md` files, no emoji
  status legend in STATUS.md), delegate to `setup-tasks` first — it has its own confirmation
  gate. Renamed from `task-status-wiki` at v1.0.0.
---

# using-tasks

> Policy for maintaining compressed working context across parallel tasks in a monorepo.
> The agent reads and updates `.tasks/` so every session starts oriented and every switch
> costs seconds, not minutes. This skill governs *usage* of an existing `.tasks/` — initial
> creation and migration to canon are owned by `setup-tasks`.

## Prerequisites

This skill assumes the project has a canonical `.tasks/` layout:

- `.tasks/STATUS.md` — the board, with per-task blocks using emoji status (🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked).
- `.tasks/<task-slug>.md` — one deep-context file per active or paused task.

If `.tasks/` is **missing**, or `STATUS.md` exists but is non-canonical (e.g. flat sections like "## Done" / "## In Progress" without the emoji + per-task block format, or no per-task files exist alongside STATUS.md) — invoke `setup-tasks` first. It detects greenfield vs migrate, has its own confirmation gate, and creates / migrates the structure. Only after `setup-tasks` finishes should this skill operate on `.tasks/`.

## Structure

```
<monorepo-root>/
  .tasks/
    STATUS.md          ← board: one block per task, sorted by priority
    <task-slug>.md     ← deep context per task, one file each
```

Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved.

---

## STATUS.md format

```markdown
# Task Board
_Updated: YYYY-MM-DD_

## 🔴 [task-slug] — short description
**Status:** active | paused | blocked | done
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name

---
```

**Emoji convention:**
- 🔴 Active — currently worked on (only one at a time)
- 🟡 Paused — in progress, resumable
- ⚪ Ready — not started, fully defined
- 🟢 Done — completed, kept until merged
- 🔵 Blocked — waiting on external input

---

## Per-task file format (`<task-slug>.md`)

```markdown
# <task-slug>

## Goal
One paragraph. What this achieves and why it matters in the monorepo.

## Key files
- `path/to/file.ts` — role in this task
- `path/to/other.ts:42` — specific line if relevant

## Decisions log
Reverse-chronological. Append only — never rewrite past entries.
- YYYY-MM-DD: Why X was chosen over Y
- YYYY-MM-DD: Constraint Z discovered, approach adjusted

## Open questions
- [ ] unresolved design or dependency questions

## Completed steps
- [x] steps finished this or previous sessions

## Notes
Temporary hypotheses, links, names of people to consult.
```

---

## Agent operations

### Session start
1. Check if `.tasks/STATUS.md` exists. If not → invoke `setup-tasks` and stop here until it returns.
2. Read `STATUS.md`.
3. If user names a task, read its `<task-slug>.md`.
4. Confirm in one sentence: "We're in the middle of X, next step is Y."
5. Ask if the plan is still correct before doing anything.
6. If STATUS.md `_Updated` date is >3 days ago, flag it and ask user to confirm current state.

### Session end / pause / switch
1. Update `STATUS.md`: set current task to 🟡, update "Where I stopped" and "Next action".
2. Append to `<task-slug>.md` Decisions log any non-obvious choices made this session.
3. Move finished items to "Completed steps".
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`

### Task switch
1. Perform session-end operations for the current task.
2. Read the target `<task-slug>.md`.
3. Set it to 🔴 in STATUS.md (demote previous active to 🟡).
4. Confirm orientation before starting work.

### New task creation
1. Ask: task name (slug), goal, known key files, branch name.
2. Create `<task-slug>.md` with Goal and Key files populated.
3. Add ⚪ block to `STATUS.md`.
4. Create and checkout branch if it doesn't exist.

### Task completion
1. Resolve or drop all open questions.
2. Set status to 🟢 in STATUS.md.
3. Append final summary line to Decisions log.
4. Remind user to delete the branch after merge.

---

## Rules

- **Never lose "Where I stopped"** — most critical field. If unclear, ask before ending session.
- **One sentence per STATUS.md field** — compress, don't write prose.
- **Key files must be specific** — not "auth module" but `packages/auth/src/useAuth.ts:87`.
- **Decisions log is append-only** — past entries are immutable.
- **Commit after every session end** — git log is the history of thinking.
- **Always confirm orientation at session start** — state understanding before acting.
- **One active task at a time** — only one 🔴 in STATUS.md.