factory/skills/setup-tasks/SKILL.md

name, version, description

name	version	description
setup-tasks	1.0.0	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. Use when the user says "set up tasks", "init tasks", "настрой таски", "инициализируй таски", "create task tracking", "migrate tasks to canon", "tasks broken", or whenever `using-tasks` detects a missing or non-canonical `.tasks/`. Two modes — greenfield (no `.tasks/`) and migrate (existing flat STATUS.md without per-task files). Confirmation gate before writing. Cross-platform.

setup-tasks

Creates or migrates a .tasks/ board to canon. The canonical layout is enforced by using-tasks and described in .wiki/raw/setup-task-status-wiki.md (the original idea file from which this skill is derived). This skill is the only place that creates the board structure.

When to use

• User explicitly asks: set up / init / migrate / create tasks.
• using-tasks runs and detects a missing or non-canonical .tasks/ — its Prerequisites delegate here.
• project-bootstrap Step 4 delegates here when initializing a new project.

Out of scope

• Editing existing task content during normal work (that's using-tasks).
• Anything outside .tasks/.

Hard rule: don't auto-mutate

The procedure mutates .tasks/. Pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan). A trigger phrase is permission to inspect, not to write.

Procedure

Phase 0 — Environment sanity

• Confirm current working directory is a project root (preferably with .git/; otherwise it's still OK to bootstrap, just note it).
• Tasks paths are POSIX-style (.tasks/...) on every OS.

Phase 1 — Discovery

Inspect .tasks/:

• No .tasks/ → mode = greenfield.
• .tasks/STATUS.md exists with canonical signals — has emoji status (🔴 / 🟡 / ⚪ / 🟢 / 🔵) AND at least one per-task .tasks/<slug>.md exists for any active/paused entry → mode = noop.
• .tasks/STATUS.md exists but flat — no emoji legend, no per-task files, just plain ## Done / ## In Progress / ## Backlog sections (or similar) → mode = migrate.

Report findings:

Mode:        greenfield | noop | migrate
STATUS.md:   exists | missing
Per-task files: <count>
Format:      canon | flat | mixed

Phase 2 — Plan + confirm

Show the plan in one block.

Greenfield:

Will create .tasks/STATUS.md with the canonical board template.
Per-task files will be created on demand by using-tasks when actual tasks are added.

Migrate:

Will:
  • back up existing STATUS.md → STATUS.md.bak-<ts>
  • for each task entry I can identify in the old STATUS.md, ask you for:
      - task-slug (kebab-case, latin)
      - current status (active / paused / ready / done / blocked)
      - branch
      - where you stopped (one sentence)
      - next action (one sentence)
    then write `.tasks/<slug>.md` and a canonical STATUS.md block.
  • leave the .bak file as a fallback reference.

If existing STATUS.md is purely a placeholder (just the bootstrap-default comment block, no real tasks), treat as greenfield — no migration needed, just overwrite with the template.

Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.

Phase 3 — Backup (migrate only)

TS=$(date +%Y%m%d-%H%M%S)
cp .tasks/STATUS.md ".tasks/STATUS.md.bak-$TS"

Phase 4a — Greenfield create

Write .tasks/STATUS.md:

# Task Board
_Updated: <today>_

<!--
  Add one block per task, sorted by priority. Use the emoji status legend below.
  Per-task deep context lives in .tasks/<task-slug>.md (created on demand by using-tasks).

  Block format:

    ## 🔴 [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

    ---

  Status legend:
    🔴 Active     — only one at a time
    🟡 Paused     — in progress, resumable
    ⚪ Ready      — defined, not started
    🟢 Done       — kept until merged
    🔵 Blocked    — waiting on external input
-->

No per-task files at greenfield — they're created when actual tasks are added.

Phase 4b — Migrate

In migrate mode, do not try to auto-parse the old flat STATUS.md. The old layout is too varied — agent-driven heuristics will mangle real work. Instead, drive the migration interactively:

1. Show the user the old STATUS.md content (or a summary).
2. Ask: "Which of these are real, in-flight tasks you want to keep?" Get a list.
3. For each task, ask the four canonical fields (slug, status, branch, where-stopped, next-action). The skill never invents these.
4. Build a fresh canonical .tasks/STATUS.md from those answers.
5. Create .tasks/<task-slug>.md for each active or paused task using the per-task template (Goal, Key files, Decisions log, Open questions, Completed steps, Notes).
6. Leave the .bak-<ts> file in place — historical record.

Per-task template:

# <task-slug>

## Goal
One paragraph. What this achieves and why it matters.

## Key files
- `path/to/file.ts` — role in this task

## Decisions log
- <today>: migrated from flat STATUS.md via setup-tasks@<version>

## Open questions
- [ ] (fill in)

## Completed steps
- [x] (fill in)

## Notes

Phase 5 — Verify

After writes:

• .tasks/STATUS.md exists and has the emoji status legend (or template comment block in greenfield).
• For migrate: each task referenced in STATUS.md has its <task-slug>.md file (active and paused only).
• No required content was lost (the .bak file is the safety net).

If verification fails → restore from .bak-<ts> and report.

Phase 6 — Report

Print final state:

✅ Tasks board ready at .tasks/.
   Mode: greenfield | migrate
   STATUS.md: <created | rewritten + .bak-<ts>>
   Per-task files: <count>

Next steps for the user:
  • Add or edit task entries in .tasks/STATUS.md
  • Read using-tasks SKILL.md if unfamiliar with the workflow

If invoked from project-bootstrap, return control silently.

Rollback

1. rm -rf .tasks/ (greenfield rollback)
   or
   mv .tasks/STATUS.md.bak-<ts> .tasks/STATUS.md (migrate rollback) and rm .tasks/<task-slug>.md for any newly created per-task files.
2. git reset HEAD .tasks/ if a git repo.
3. Tell user what failed.

Common mistakes

• Auto-parsing existing flat STATUS.md. Don't. The format varies, real work is at stake — drive migration through the user, one task at a time.
• Inventing task slugs / branches / "where you stopped" values. Never. Ask the user. The whole point of .tasks/ is real preserved context, not hallucinated context.
• Skipping confirmation on greenfield. Yes, even greenfield needs the gate — the user might be running this in the wrong directory.
• Creating per-task files at bootstrap. Don't pre-generate empty <slug>.md files in greenfield mode — wait until the user adds actual tasks.
• Editing the .bak file. It's the rollback artifact; leave it alone.

Cross-platform notes

The procedure is platform-agnostic. Wiki-style paths (.tasks/...) work the same on Windows / Linux / macOS. The only platform-conditional command is the timestamp generator (date +%Y%m%d-%H%M%S in bash; equivalent in PowerShell), and our scripts use bash via git-bash on Windows.

Source

The canonical pattern (extended documentation, decisions log format, agent operations) lives in this repo at .wiki/raw/setup-task-status-wiki.md. Refer to it when designing project-specific extensions.