# setup-tasks

One-time skill that creates or migrates a project's `.tasks/` board to the
canonical layout — `STATUS.md` (the board, with emoji status legend) plus
per-task `<task-slug>.md` files for each active or paused task. The runtime
policy for working *with* the board lives in
[`using-tasks`](../using-tasks/) — `setup-tasks` is the only place that
creates the structure.

## When it triggers

- User says: "set up tasks", "init tasks", "create task tracking",
  "migrate tasks to canon", "tasks broken", or the Russian equivalents
  ("настрой таски", "инициализируй таски").
- [`using-tasks`](../using-tasks/) detects a missing or non-canonical
  `.tasks/` and delegates here via its Prerequisites section.
- [`project-bootstrap`](../project-bootstrap/) Step 4 delegates here when
  initializing a new project.

## Modes

`setup-tasks` picks one of three modes after a discovery scan:

| Mode | Trigger | Action |
|---|---|---|
| **greenfield** | No `.tasks/` exists | Write `.tasks/STATUS.md` from the canonical template. No per-task files yet — they're created on demand. |
| **noop** | `.tasks/STATUS.md` already canon (emoji status legend + at least one per-task file) | Report and exit. |
| **migrate** | `.tasks/STATUS.md` is flat (plain `## Done` / `## In Progress` / `## Backlog`, no emoji legend, no per-task files) | Back up, then drive an interactive migration — one task at a time, asking the user for the canonical fields. |

A "placeholder" STATUS.md (just the bootstrap default with no real tasks) is
treated as `greenfield` — no migration needed.

## What canon means

```
.tasks/
├── STATUS.md          ← board, with emoji status legend + one block per task
└── <task-slug>.md     ← per-task deep context (one file per active/paused task)
```

Status legend: 🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked.

`STATUS.md` block format (one per task):

```
## 🔴 [task-slug] — short description
**Status:** active
**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
```

Per-task file sections: Goal, Key files, Decisions log, Open questions,
Completed steps, Notes.

## Hard rules

- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause
  for explicit confirmation. A trigger phrase grants permission to inspect,
  not to write.
- **Never auto-parse a flat STATUS.md.** Old layouts vary; agent heuristics
  mangle real work. Migration is interactive — the agent asks the user for
  each task's canonical fields.
- **Never invent task slugs / branches / "where you stopped" values.** The
  whole point is *real* preserved context, not hallucinated context.
- **No empty per-task files at greenfield.** Wait until the user adds a
  real task.
- **Never edit the `.bak` file.** It's the rollback artifact.

## Procedure (high-level)

1. **Phase 0** — environment sanity (project root).
2. **Phase 1** — discovery (greenfield / noop / migrate).
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
4. **Phase 3** — backup (migrate only) → `STATUS.md.bak-YYYYMMDD-HHMMSS`.
5. **Phase 4a/4b** — greenfield create or interactive migrate.
6. **Phase 5** — verify (canon `STATUS.md`, per-task files for active/paused
   only, no required content lost).
7. **Phase 6** — final report; if invoked from `project-bootstrap`, return
   silently.

Full procedure with templates and the migration script lives in
[`SKILL.md`](SKILL.md).

## Rollback

- Greenfield: `rm -rf .tasks/`.
- Migrate: `mv .tasks/STATUS.md.bak-<ts> .tasks/STATUS.md` plus `rm` for any
  newly created per-task files; `git reset HEAD .tasks/`.

## Install

From the repo root:

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

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

## See also

- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
  here for new projects.
- Source pattern: `.wiki/raw/setup-task-status-wiki.md` in this repo —
  extended documentation, decisions log format, agent operations.