agentleFS
ivanshchitovivanshchitov/tabletop-ai-assistant-tui/.claude/skills/solve-challenge-task/SKILL.md

solve-challenge-task

Skill0 starsChanged 49 days agoMITView on GitHub

Использовать, когда поступила задача челленджа (AI Advent Challenge) в виде текста — задание дня с ожидаемым результатом и форматом сдачи «Видео + Код». Триггеры: «реши задачу челленджа», «выполни задание дня», «задание недели», «нужно сдать задание», «запиши демо-видео», «запись экрана», «screen recording», «solve challenge task». Не использовать для обычных фич вне челленджа (тогда feature-builder) и для задач без видео-демонстрации.

  • Reads credentials
  • Commits and pushes

The file

Files
SKILL.md

Задание дня челленджа: код + видео + материалы для сдачи

Сдача = обе части: тег релиза с кодом и запись экрана. Нет любой части — задание не сдано.

Границы

  • Пишем только в текущий проект. Челлендж-репозиторий — только чтение; его README правит пользователь, агент готовит фрагмент.
  • Любая мутация git (коммит, мерж, тег, пуш) — только после явного «да» на показанные git status / git diff --stat / список коммитов. Слияние — только fast-forward (git rebase main, затем git merge --ff-only); merge-коммиты запрещены. Создание ветки подтверждения не требует.
  • videos/ в .gitignore; видео, кадры и черновики README не коммитятся.
  • Стиль — caveman: строки статуса, главное жирным. Без жаргона и англицизмов: «подтвердить (approve)», не «апрув».
  • Два неудачных подхода подряд в любой фазе — назад к плану с описанием блокера, не третья попытка того же.
  • Чужие окна терминала не трогать: ни закрывать, ни переключать, ни перемещать.
  • Грабли агентского цикла (--yes у archive, валидация спек, новый файл состояния, объём прогонов) — блок в CLAUDE.md проекта; там же актуальные пути и конвенции.

Скрипт записи: $SKILL/scripts/record_screen.sh, где $SKILL — каталог этого файла (.claude/skills/solve-challenge-task/; в OpenCode — .opencode/skills/solve-challenge-task/). В корне проекта scripts/ нет.

Фаза 0 — разбор и план

  1. Разобрать задачу:

    ЧТО:       <своими словами, 1–3 строки>
    РЕЗУЛЬТАТ: <пункты «что считается выполненным», из текста задачи>
    ФОРМАТ:    <по умолчанию «Видео + Код»>
    ДЕНЬ:      weekN/dayMM   (две цифры: day06, day10)

    РЕЗУЛЬТАТ — дословные пункты задачи, не пересказ: они становятся критериями приёмки proposal.md и пунктами чек-листа. Структуру сверх текста задачи не додумывать. «Минимум 3 типа» с перечислением содержимого = три слоя, а подробности внутри — свойства одного слоя, а не ещё три хранилища. Терминологию задачи использовать буквально; если пользователь переопределил слово («для ассистента» = «для агента», «агент» = конкретный класс) — записать это в план одной строкой и дальше не смешивать.

    Если ai-advent-challenge-9/weekN/dayMM/README.md уже содержит раздел «Решение» со ссылками — день сдан, спросить, какой день имеется в виду. Сданный README не перезаписывается никогда.

  2. Прочитать CLAUDE.md / README.md проекта — архитектурные ограничения обязательны. Проверить среду: pytest -q зелёный (падает до правок — сообщить и остановиться); $SKILL/scripts/record_screen.sh doctor; при необходимости LLM — файл .env есть (значение не печатать); openspec/changes/ без незаархивированных изменений (есть — сообщить).
  3. План решения: 3–7 пунктов — модули/команды/экраны, что нового, какие тесты доказывают каждый пункт РЕЗУЛЬТАТ.
  4. Сценарий демо (управляет тем, что строим):

    СЦЕНАРИЙ ДЕМО (dayMM, 30–600 сек):
    1. <исходное состояние на экране>
    2. <ключевое действие>            # ≥ половины времени
    3. <результат на экране>          # доказательство каждого пункта РЕЗУЛЬТАТ

    Пункт РЕЗУЛЬТАТ, не видимый в сценарии, = сценарий неполный.

  5. Тег: последний git tag -l | sort -V | tail -1 плюс 0.1 (v0.10 → v0.11).

Стоп A: поля + статус среды + план + сценарий + тег одним сообщением. Дальше — только после «да».

Правки плана (пользователь что-то поправил) требуют повторного Стопа A целиком: показать изменения «было → стало» и ожидать подтверждения снова. Дальше — только после «да».

Фаза 1 — код

ОБЯЗАТЕЛЬНЫЙ САБСКИЛЛ: feature-builder (инструмент Skill), весь его цикл без пропусков. Дополнения челленджа:

  • <change-id> — из задачи (add-export-command); критерии приёмки в proposal.md — дословно пункты РЕЗУЛЬТАТ плюс шаги сценария демо.
  • Перед Стопом B: openspec validate <change-id> --strict и openspec validate --all --strict зелёные. Неверная дельта (например, MODIFIED без всех прежних сценариев требования) стоит лишнего круга.
  • Архив изменения — openspec archive <change-id> --yes: без TTY CLI падает на запросе подтверждения.
  • После ff-слияния — тег: показать vX.Y, дождаться «да», затем git tag vX.Y && git push origin main --tags. Релиз в GitHub из тега пользователь создаёт руками — напомнить.

Стоп B (итоговый статус после тега, ожидания не требует): код готов: pytest OK, main = <sha>, тег vX.Y запушен. Видео снимается только с слитого кода.

Фаза 2 — видео

  1. Кадр и состояние: терминал на весь экран; уведомления выключены; микрофон выключен; .env, ключи, личные файлы и лишние окна вне экрана. Убрать в .bak все файлы состояния, которые создаёт демо (history.json, memory.json, любые новые из задачи) — иначе в кадре чужие реплики и чужая память; вернуть их на Стопе D, даже если запись не удалась.
  2. Автоматизация съёмки: сценарий выполняет скрипт, а не рука.

    • Ждать отрисованный маркер, которого нет в эхо ввода: строку метрик (⏱), заголовок отчёта («Память агента», «Правила маршрутизации»), подсказку панели. Ждать текст, который скрипт сам только что напечатал, нельзя: эхо принимается за готовность, и приложение съедает следующую команду (первый прогон дня 11 потерял так /memory и /clear).
    • Готовность обмена — по числу строк метрик (Токены:), как harness.wait_for_answers в e2e; таймаут щедрый (300 с: reasoning-модели отвечают десятками секунд).
    • Паузы: 1–2 с перед первой командой (пустой экран в начале записи), 2–4 с на ключевом экране.
    • Окно создаёт скрипт; адресовать его по id, никогда по индексу. Демо-окно — на весь экран.
    • Рекордер останавливается в finally и по жёсткому лимиту скрипта: падение сценария не оставляет запись идущей. После остановки демо-окно не закрывать — может понадобиться повторный кадр.
    • Скрипт и его логи — в videos/tmp/, не попадает в репозиторий.
  3. Сухой прогон без записи, с замером времени по шагам. Проверять в нём те самые строки, что попадут в кадр. Не проходит — чинить код или сценарий, не «снимать как есть».
  4. Стоп C: «экран готов?» — запись захватывает весь экран пользователя.
  5. Запись:

    $SKILL/scripts/record_screen.sh start videos/dayMM-demo   # расширение добавит скрипт
    # ... сценарий, без спешки ...
    $SKILL/scripts/record_screen.sh stop
  6. Проверка (каждая запись):

    ffprobe -v error -show_entries format=duration -of csv=p=0 videos/dayMM-demo.<ext>
    ffmpeg -y -v error -ss 3 -i videos/dayMM-demo.<ext> -frames:v 1 videos/frame.png && stat -f %z videos/frame.png
    • Длительность 30–600 сек; кадр на 3-й секунде не чёрный — PNG больше 10 000 байт. Чёрный кадр на macOS = у терминала нет разрешения «Запись экрана» (Системные настройки → Конфиденциальность) — выдать и переснять.
    • Прочитать 3–5 кадров в ключевых точках сценария (vision: «прочитай текст на экране»). Размер ловит только чёрный кадр; чтение ловит опечатки, кривые формы слов и не тот экран.
    • Файл больше 150 МБ — пережать: ffmpeg -i in.<ext> -vcodec libx264 -crf 28 out.mp4.
    • Звука в записи нет: avfoundation пишет -i <экран>:none. Нужна озвучка — писать отдельно, этот скилл её не делает.
  7. Запись невозможна (нет рекордера, захват падает, нет разрешения) — две попытки, затем шаг пропускается: видео становится ручным шагом пользователя в Фазе 3, всё остальное сдаётся штатно. Подмена записи скриншотами, слайдами или роликом, собранным из вывода программы, — не запись экрана и не сдача.

Стоп D (статус; .bak-файлы состояния возвращены на место, демо-окно открыто): видео: videos/dayMM-demo.<ext>, N сек, кадр K байт — или честный блокер.

Фаза 3 — сдача

  1. Черновик videos/dayMM-README-draft.md по формату челлендж-репозитория (образец: week2/day09/README.md):

    # День M. <Название>
    
    ## Задача
    
    <текст задачи как пришёл>
    
    ## Решение
    
    Код: https://github.com/ivanshchitov/tabletop-ai-assistant-tui/releases/tag/vX.Y
    
    Видео: <после загрузки — ссылка>
    
    ### Как это работает
    
    - <2–5 пунктов: что реализовано, как проверить>

    Плюс строка таблицы недели (weekN/README.md): | [MM](dayMM/README.md) | [<Название>](dayMM/README.md) | [Tabletop AI Assistant TUI vX.Y](<ссылка на релиз>) | [🎬](<ссылка на видео>) |

  2. Тело GitHub-релиза — videos/dayMM-release-notes.md (образец: предыдущий релиз, releases/tag/v<prev>):

    • заголовок vX.Y — YYYY-MM-DD; тело 1–1.5 экрана, таблицы и списки, без воды;
    • ссылки на коммиты — только хэши (228ceb4), без URL; строка «Полный diff» — одна ссылка на сравнение (v<prev>...vX.Y);
    • разделы: Новое / Изменено / Решения, принятые сознательно / Спецификация OpenSpec / Тесты / проверка на живой модели (таблица prompt, completion, стоимость, время) / Прочее в диапазоне;
    • все числа (тесты, время, токены, размеры) — из свежего вывода команды, не из памяти.
  3. Передать пользователю списком: тег и ссылку на релиз; путь к видео, черновику README и телу релиза; ручные шаги — загрузить видео, вставить ссылки в dayMM/README.md челлендж-репозитория, добавить строку таблицы недели, создать релиз в GitHub из тега и вставить тело.

Чек-лист перед словом «сдано»

  • Каждый пункт РЕЗУЛЬТАТ покрыт кодом, тестом и сценарием демо
  • Цикл feature-builder закрыт: изменение заархивировано (--yes), полный pytest зелёный до архивации, коммиты влиты без merge-коммита, тег запушен
  • Видео существует, 30–600 сек, кадр проверен, ключевые кадры прочитаны, в кадре нет секретов и старого history.json — или видео явно передано как ручной шаг
  • Черновик README, строка таблицы и тело релиза лежат в videos/, ничего из videos/ не в git; .bak-файлы состояния возвращены
  • Рекордер остановлен, демо-окно открыто, чужие окна не тронуты
  • Каждая мутация git прошла через показ и «да»

Красные флаги — стоп

  • «Запишу сразу, сухой прогон потом» — без прогона переснимать.
  • «Чёрный кадр, но на другом плеере видно» — брак, переснять.
  • «Рекордера нет — соберу ролик из кадров/скриншотов» — не запись; честный блокер.
  • «Сценарий упал, запись оставлю идти» — рекордер останавливается всегда, файл недописанный.
  • «Кадр не чёрный по размеру, значит всё хорошо» — размер ловит только чёрный кадр; текст читается глазами по кадрам.
  • «Правка плана — вернусь к Стопу A целиком» — показывать только дельту, если разрешение уже дано.
  • «Пользователь торопит — пропущу подтверждение» — быстрота = короткие статусы, не пропуск стопов.
  • «Тесты зелёные — закоммичу и залью сам» — только после «да».

scripts/record_screen.sh

  • doctor — платформа, рекордеры, вердикт «ГОТОВ / НЕ ГОТОВ» с подсказкой установки; на macOS дополнительно снимает 2-секундную пробу в $TMPDIR и проверяет кадр (ловит отсутствие разрешения «Запись экрана»). Ничего не пишет вне $TMPDIR.
  • start <basename> — запись в <basename>.<ext> (.mp4 ffmpeg, .mkv wf-recorder, .mov screencapture), PID-файл, жёсткий лимит 30 минут (страховка от забытой записи).
  • stop — SIGINT, ожидание до 15 сек (файл финализируется), размер файла; kill -9 только по таймауту.

Выбор рекордера: macOS — ffmpeg avfoundation, иначе screencapture -V; Linux Wayland — wf-recorder, иначе gpu-screen-recorder; Linux X11 — ffmpeg x11grab. x11grab под Wayland даёт чёрный кадр — doctor об этом скажет.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.