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

---
name: using-tasks
version: 1.1.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. **Pre-close coverage check.** Before setting 🟢:
   - List acceptance criteria from the per-task `<slug>.md` (or the STATUS block if no per-task file).
   - For each criterion, locate evidence: a test name in the diff, a smoke-test artefact, a manual-checklist tick in the per-task file, or a design-doc reference.
   - Missing evidence on any criterion → flag to user and ask "закрывать или подождать coverage'а?". Never silently close.
   - If acceptance criteria are policy / docs-only and have no testable shape, an explicit user "ok, closed by inspection" is required (record this in the close-note).
2. Resolve or drop all open questions.
3. Set status to 🟢 in STATUS.md.
4. Append final summary line to Decisions log.
5. Remind user to delete the branch after merge.

### Post-commit task closure prompt

After any implementation commit (`feat:` / `fix:` / similar), prompt the user once:

> Эта работа закрывает таску `<slug>`?

Slug candidates, in priority: (a) commit message scope, (b) current branch name, (c) the most recent `Where I stopped` field that mentions a now-shipped artefact. If user says yes → run the pre-close coverage check from "### Task completion". If no → silent.

Skip on `chore:` / `meta:` / `docs:` / `style:` commits — they rarely close work.

This exists because shipped code can sit while the task block stays ⚪ ready (e.g. `extend-project-discipline-brainstorm-workspaces` lived as ⚪ for a day after `215afdd` shipped Rule 5). The prompt forces a one-line decision while the work is fresh.

### Recommendations / "what's next" trigger

When the user asks «что дальше», «срочные», «куда копаем», «status», «what next», or session-start lands on a project — recommend in this order:

1. **Local cwd-project board** ranked 🔴 → 🟡 → ⚪. Group by status, summarize one line each. Cite slugs.
2. **One footnote line** if cross-project state is relevant: `Cross-project: N 🔴 active in other repos (см. mcp__projects-meta__tasks_aggregate).` Only when N>0 and there is no active 🔴 in the current cwd. Never bury local recommendations under it.

Cross-project urgents are *information*, not the driver of "what to do here". The user chose this cwd; that's the implicit scope.

If the user explicitly asks "across all projects" / "по всем проектам" / "cross-project status" — flip the order: cross-project first, local as footnote.

Pair: `using-projects-meta` declares local-first for **reads**; this rule extends local-first to the **recommendation phase**.

---

## 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.
- **Never close a task without a coverage check** — see "### Task completion" step 1. Acceptance criteria with no evidence → ask, don't auto-close.
- **Local-first recommendations** — cwd-project board comes first; cross-project urgents are at most one footnote line.