claude-skills/skills/using-tasks

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.

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

# 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 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 scripts/install.sh using-tasks

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

See also

• setup-tasks — companion, owns .tasks/ creation and canon migration.
• project-bootstrap — invokes setup-tasks for new projects.