claude-skills/skills/task-status-wiki/SKILL.md

---
name: task-status-wiki
version: 1.0.0
description: >
  Manage a persistent task status wiki inside a monorepo using the .tasks/ folder pattern.
  Use this skill whenever the user is switching between tasks, resuming a paused task,
  starting a new task, asking "where were we", or wanting to track progress across multiple
  parallel workstreams. Also use when the user says "pause", "switch to X", "what's the status",
  "update status", or "initialize task tracking". Trigger even if the user doesn't explicitly
  mention the wiki — any context-switching or multi-task coordination question in a code project
  is a signal to use this skill.
---

# Task Status Wiki

A pattern for maintaining compressed working context across parallel tasks in a monorepo.
The agent reads and updates a small wiki in `.tasks/` so that every session starts oriented
and every switch costs seconds, not minutes.

## 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 → run **Initialization** below.
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.

---

## Initialization (first time in a project)

Run when `.tasks/` doesn't exist yet.

1. Confirm understanding in one sentence.
2. Ask: "What tasks are currently in flight? Give me each name and a one-line description."
3. For each task: ask for branch, current status, and where work stopped last.
4. Create `.tasks/STATUS.md` with all tasks filled in.
5. Create `<task-slug>.md` for each active or paused task.
6. Commit: `git add .tasks/ && git commit -m "chore: init task status wiki"`
7. Print path to STATUS.md and confirm it's ready.

**Do not invent task details — ask for what is unknown.**

---

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