claude-skills/.wiki/raw/setup-task-status-wiki.md

# task-status-wiki

> An idea file for LLM agents. Copy-paste this into your agent (Claude Code, Cursor, Windsurf, etc.)
> and it will set up a task status tracking system in your monorepo.
> The agent builds the specifics in collaboration with you.

---

## The Problem

When working on multiple large tasks in parallel inside a monorepo, context is lost on every
switch. You have to re-explain: what was being done, why, what the current blocker is,
which files matter. This is expensive and error-prone.

## The Pattern

Maintain a small wiki inside the repo — a folder of plain markdown files — that an LLM agent
actively reads and updates as you work. The files store *compressed working context*, not
prose notes. When you switch tasks, you give the agent the relevant file and it is immediately
oriented without re-explanation.

This follows the same principle as Karpathy's llm-wiki: knowledge should *accumulate* across
sessions, not be re-derived from scratch each time.

---

## Structure to Create

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

Place `.tasks/` at the monorepo root. Commit it to git — decision history is valuable,
and diffs show how thinking evolved.

### Solo vs. team

**Solo:** local commits are enough. No need to push `.tasks/` — history is preserved locally,
remote repo stays clean.

**Team or multiple agents:** push `.tasks/` to remote. It becomes the shared source of truth.
Without it, each agent or person works from their own stale snapshot and statuses diverge.
Add a `**Owner:**` field to each STATUS.md block so it's clear who (or which agent) holds
the task at any moment.

---

## STATUS.md — the board

This is the first file you open when returning to work. One block per active task.
The agent updates it at the end of every session, or when asked.

### Format

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

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

---

## 🟡 [task-slug] — short description
...
```

### Status emoji convention
- 🔴 Active — currently being worked on (only one at a time)
- 🟡 Paused — in progress, can be resumed
- ⚪ Ready — not started, fully defined
- 🟢 Done — completed, kept for reference until merged
- 🔵 Blocked — waiting on external input

---

## Per-Task File — `<task-slug>.md`

Created when a task starts. The agent maintains it throughout. This is the *compiled*
context — not raw notes, but synthesized understanding that would take too long to
re-derive from scratch.

### Format

```markdown
# <task-slug>

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

## Key files
List of files central to this task, with one-line notes on their role.
- `path/to/file.ts` — what it does and why it matters here
- `path/to/other.ts:42` — specific line if relevant

## Decisions log
Reverse-chronological. The agent appends here when a non-obvious decision is made.
- YYYY-MM-DD: Why we chose X over Y
- YYYY-MM-DD: Discovered constraint Z, adjusted approach

## Open questions
- [ ] unresolved questions that block or affect design
- [ ] questions to discuss with teammates

## Completed steps
- [x] steps that are done (agent moves items here from open questions or session notes)

## Notes
Anything that doesn't fit above: temporary hypotheses, links to external context,
names of people to ask.
```

---

## Agent Operations

These are the operations the agent performs. The agent should do them autonomously
without being asked each time.

### On session start
1. If in team mode: `git pull` to sync `.tasks/` before reading anything
2. Read `STATUS.md`
3. If the user names a task, read its `<task-slug>.md`
4. Confirm current state 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

### On session end (or when user says "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 completed steps to "Completed steps"
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`
5. If in team mode: `git push`

### On task switch
1. Perform session-end operations for the current task
2. Ask which task to switch to
3. Read the target `<task-slug>.md`
4. Set it to 🔴 in STATUS.md
5. Confirm orientation before starting work

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

### On task completion
1. Move all open questions to resolved or drop them
2. Set status to 🟢 in STATUS.md
3. Add a "Completed" line in Decisions log with final summary
4. Remind user to delete the branch after merge

---

## Initialization Prompt (run once per project)

When the user pastes this file into the agent for the first time, the agent should:

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

The agent must not invent task details — it asks for what it doesn't know.

---

## Rules for the Agent

- **Never lose "Where I stopped"** — this is the most important field. If unclear, ask before ending session.
- **One sentence per field** — STATUS.md fields are not prose. Compress.
- **Key files must be specific** — not "auth module" but `packages/auth/src/useAuth.ts:87`.
- **Decisions log is append-only** — never rewrite past entries, only add.
- **Commit after every session end** — the git log is the history of thinking.
- **Always confirm orientation** — at session start, state what you understand before acting.
- **If STATUS.md is stale** (last update > 3 days ago), flag it and ask the user to confirm current state.
- **Team mode:** always `git pull` before reading, always `git push` after committing. One 🔴 per owner — two people must not hold the same task active simultaneously. Use the `Owner:` field to make this visible.

---

## Why This Works

The key insight from Karpathy's pattern: an LLM should not re-derive context on every session.
It should read accumulated, compiled knowledge — the same way a compiler produces an artifact
you don't recompute every time.

The `.tasks/` wiki is that artifact for engineering work. Each task file is a *compiled*
representation of: what was learned, what was decided, what remains. The agent's job is
to keep it accurate and compressed — not verbose, not a log dump, but the minimum a future
session needs to be immediately productive.

The STATUS.md board adds fast navigation: glance at it, pick a task, load its file.
Two reads and you're back in context.