factory/skills/setup-tasks/README.md

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 — 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 detects a missing or non-canonical .tasks/ and delegates here via its Prerequisites section.
• 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.

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

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

See also

• using-tasks — runtime policy for working with .tasks/.
• 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.