# using-tasks

Runtime policy for keeping 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.

`using-tasks` governs *usage* of an existing `.tasks/`. Initial creation and
migration to canon are owned by [`setup-tasks`](../setup-tasks/).

> Renamed from `task-status-wiki` at v1.0.0.

## When it triggers

- User is switching between tasks, resuming a paused task, starting a new
  one, or asks "where were we" / "what's the status".
- User says: "use task management system", "pause", "switch to X",
  "update status".
- Any context-switching or multi-task coordination question in a code
  project.
- If `.tasks/` is missing or non-canonical, this skill delegates to
  [`setup-tasks`](../setup-tasks/) before doing anything else.

## 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

---
```

Status legend:

| Emoji | State | Notes |
|---|---|---|
| 🔴 | Active | Currently worked on. **Only one at a time.** |
| 🟡 | Paused | In progress, resumable. |
| ⚪ | Ready | Defined, not started. |
| 🟢 | Done | Kept until merged. |
| 🔵 | Blocked | Waiting on external input. |

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

Sections, in order: **Goal** (one paragraph — what this achieves and why),
**Key files** (`path/to/file.ts:42` style — specific lines when relevant),
**Decisions log** (reverse-chronological, append-only — past entries are
immutable), **Open questions**, **Completed steps**, **Notes** (temporary
hypotheses, links).

## Operations

### Session start

1. Check `.tasks/STATUS.md`. If missing → invoke
   [`setup-tasks`](../setup-tasks/) and stop 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 `_Updated` is more than 3 days old, flag it and ask the user to
   confirm current state.

### Session end / pause / switch

1. Update `STATUS.md`: set the current task to 🟡, refresh "Where I stopped"
   and "Next action".
2. Append non-obvious decisions to `<task-slug>.md` Decisions log.
3. Move finished items to "Completed steps".
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`.

### Task switch

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

### New task

1. Ask: slug, goal, known key files, branch.
2. Create `<task-slug>.md` with Goal and Key files populated.
3. Add a ⚪ block to `STATUS.md`.
4. Create / checkout the branch if missing.

### Task completion

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

## Rules

- **Never lose "Where I stopped".** Most critical field. If unclear, ask
  before ending the 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`.

## Install

From the repo root:

```bash
bash scripts/install.sh using-tasks
```

Works on Windows under git-bash, Linux, macOS.

## See also

- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` creation and
  canon migration.
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-tasks` for
  new projects.