dsh-department 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0
4
+ - **Обсуждение задачи**: `discussion.md` (цели, не-цели, пользователи, ограничения, риски, вопросы, решения).
5
+ - **Гейт утверждения**: ТЗ нельзя утвердить при открытых вопросах; концепция — без двух вариантов.
6
+ - **ТЗ и концепция в любом порядке**, запуск проекта только после утверждения обоих.
7
+ - **Стадия release**: `dept_handover` собирает `delivery/` (RUN.md, MANUAL-QA.md, CHANGELOG.md, RELEASE.md + копии документов), без неё `done` недоступен.
8
+ - **Встроенный пиксель-редактор**: трафарет, сохранение в проект, передача художнику.
9
+ - **«Отдел вкл/выкл»** и **«+ Задача»** в панели.
10
+ - Ужесточены переходы: из ревью нельзя проскочить без утверждения человеком.
11
+
12
+
13
+ ## 0.1.3
14
+ - Полный английский README (главная страница GitHub и npm), русский — README.ru.md.
15
+ - Скриншоты панели, офиса, паузы и персонажей в README.
16
+ - GitHub Actions: CI, авто-создание релиза и публикация в npm по тегу (Trusted Publishing).
17
+ - Убраны временные спрайт-инструменты из репозитория.
18
+
19
+
20
+ ## 0.1.2
21
+ - Исправлено: русские переводы новых ключей (в т.ч. имя офиса в сайдбаре — «ИИ-отдел»).
22
+ - Проверка паритета словарей ru/en (226/226).
23
+
24
+
25
+ ## 0.1.1
26
+ - Полная локализация интерфейса ru/en: карточка задачи, вкладки, стадии, события,
27
+ аудит, документы, роли, бюджет, офис, схема проекта, графики, формы.
28
+ - Переключатель языка EN/RU в шапке доски, выбор сохраняется.
29
+ - `dept_start release=true` — шаблон подготовки к релизу.
30
+ - GitHub Actions CI, docs/PUBLISHING.md.
31
+
32
+
3
33
  ## 0.1.0
4
34
 
5
35
  - Первый публичный релиз: доска задач, карточка задачи, офис, гейты, git, бюджет, роли.
package/README.md CHANGED
@@ -1,256 +1,297 @@
1
- # dsh-department — ИИ-отдел разработки для DeepSeek Harness
1
+ # dsh-department — AI development department for DeepSeek Harness
2
2
 
3
- Плагин превращает DeepSeek Harness в **отдел разработки**: задача проходит анализ →
4
- концепцию → ТЗ → план → этапы, а внутри этапа — реализацию, тесты, независимое ревью и
5
- коммит с тегом. Человек утверждает только концепцию и ТЗ, остальное отдел решает сам
6
- по политике автономии.
3
+ **English** · [Русский](README.ru.md)
7
4
 
8
- ## Возможности
5
+ ![CI](https://github.com/Vldimirus/dsh-department/actions/workflows/ci.yml/badge.svg)
6
+ ![npm](https://img.shields.io/npm/v/dsh-department.svg)
7
+ ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
9
8
 
10
- - **Доска задач** по всем проектам: стадия, прогресс, гейты, последнее событие.
11
- - **Карточка задачи** на вкладках: обзор, документы, вопросы, аудит, события, git;
12
- кнопки утверждения, ответы на вопросы, поправки к ТЗ.
13
- - **Офис отдела**: кто работает, за каким столом, что делает; клик — проект, задача,
14
- файлы и история действий.
15
- - **Схема проекта**: файлы и связи импортов по группам (папкам), drill-down до файла.
16
- - **Бюджет**: расход токенов по сессиям, стоимость по ценам за 1M, лимит задачи.
17
- - **Отчётность**: `dept_report` — этап, гейты, кто чем занят, открытые вопросы.
18
- - **Вопросы к человеку** (`dept_ask` / `dept_answer`) — отдел не останавливается.
19
- - **Поправки ТЗ** (`dept_amend`): с подписью человека или автономно (с лимитом).
20
- - **Повторы по циклу** «данные → анализ → план → изменения → тесты»; повтор без анализа
21
- блокируется, повторяющийся провал переводит этап в `blocked`.
22
- - **Git**: коммит этапа, тег, push ветки и тегов; коммит заблокирован без свежих гейтов.
9
+ The plugin turns DeepSeek Harness into a **development department**: a task goes through
10
+ analysis → concept → specification → plan → stages, and inside each stage — implementation,
11
+ tests, independent review and a tagged commit. The human approves only the concept and the
12
+ specification; everything else the department decides itself under the autonomy policy.
23
13
 
24
- ## Установка
14
+ ## Screenshots
25
15
 
26
- Плагин ставится в профиль DSH как локальный (`link:`) или из репозитория:
16
+ | Department panel (EN) | Office: working |
17
+ |---|---|
18
+ | ![Panel](docs/screenshots/panel-en.png) | ![Office](docs/screenshots/office.png) |
19
+
20
+ | Paused: everyone in the lounge | 16 characters |
21
+ |---|---|
22
+ | ![Paused](docs/screenshots/office-paused.png) | ![Characters](docs/screenshots/characters.png) |
23
+
24
+ ## Features
25
+
26
+ - **Task board** across projects: stage, progress, gates, last event.
27
+ - **Task card** with tabs: overview, documents, questions, audit, events, corrections,
28
+ roles, budget, git; approval buttons, answers, amendments.
29
+ - **Department office**: who is working, at which desk, what they do; click — project,
30
+ task, files and action history.
31
+ - **Project blueprint**: files and import edges grouped by folders, drill-down to a file.
32
+ - **Budget**: token usage per session, cost by price per 1M, task limit.
33
+ - **Reporting**: `dept_report` — stage, gates, who is busy, open questions.
34
+ - **Questions to the human** (`dept_ask` / `dept_answer`) — the department does not stop.
35
+ - **Spec amendments** (`dept_amend`): human-signed or autonomous (with a limit).
36
+ - **Retries** by the loop data → analysis → plan → changes → tests; retry without analysis
37
+ is blocked; a repeated failure moves the stage to `blocked`.
38
+ - **Git**: stage commit, tag, push branch and tags; commit is blocked without fresh gates.
39
+
40
+ ## Install
41
+
42
+ The plugin is installed into a DSH profile as a local (`link:`) package or from the registry:
27
43
 
28
44
  ```bash
29
45
  dsh plugin add link:/path/to/dsh-department
46
+ # or from npm:
47
+ dsh plugin add dsh-department
30
48
  ```
31
49
 
32
- Затем включите bundle `dsh-department` в менеджере плагинов и перезагрузите вкладку.
33
- В сайдбаре появится «ИИ-отдел», в основном окне — доска, офис и схема.
50
+ Then enable the `dsh-department` bundle in the plugin manager and reload the tab.
51
+ The sidebar shows “Department”, the main window shows the board, office and blueprint.
34
52
 
35
- ## Инструменты модели
53
+ ## Model tools
36
54
 
37
- | Инструмент | Назначение |
55
+ | Tool | Purpose |
38
56
  |---|---|
39
- | `dept_start` | создать задачу: состояние, ветка, task.md |
40
- | `dept_status` | состояние задачи и сводка |
41
- | `dept_stage` | переход стадии (кроме утверждений) |
42
- | `dept_approve` | утверждение концепции/ТЗ человеком |
43
- | `dept_gate` | гейт тестов (exit code) или ревью (PASS/FAIL) |
44
- | `dept_verify` | аудит: состояние ↔ артефакты ↔ git |
45
- | `dept_commit` | коммит этапа, тег, push |
46
- | `dept_amend` | поправка к документу (подпись человека или `autonomous`) |
47
- | `dept_ask` | вопрос человеку без остановки работы |
48
- | `dept_answer` | ответ человека на вопрос |
49
- | `dept_report` | отчёт о состоянии отдела |
50
- | `dept_health` | «жив ли отдел»: работает / стоит / ждёт человека / готов к коммиту |
51
- | `dept_modules` | план модулей и владение файлами для параллельной работы |
52
- | `dept_art` | нарисовать пиксельный спрайт и сохранить PNG |
53
- | `dept_pixelize` | PNG/JPEG → пиксельная сетка + палитра + спрайт (для перерисовки по референсу) |
54
- | `dept_compose` | собрать большое PNG из маленьких спрайтов (холст, фон, слои) |
55
- | `dept_roles` | роли и модели (researcher, designer, artist, senior-coder, supervisor, beta-tester, ...) |
56
- | `dept_bug` | баг-репорт бета-тестера (шаги, ожидаемое/фактическое, критичность) |
57
- | `dept_browse` | браузер: открыть localhost/file, клики, ввод, скриншот в evidence |
58
- | `dept_gui` | нативная программа: команда, env, таймаут, вывод, скриншот через хук/команду |
57
+ | `dept_start` | create a task: state, branch, task.md |
58
+ | `dept_status` | task state and summary |
59
+ | `dept_stage` | stage transition (except approvals) |
60
+ | `dept_approve` | human approval of concept/spec |
61
+ | `dept_gate` | tests gate (exit code) or review gate (PASS/FAIL) |
62
+ | `dept_verify` | audit: state ↔ artifacts ↔ git |
63
+ | `dept_commit` | stage commit, tag, push |
64
+ | `dept_amend` | document amendment (human-signed or `autonomous`) |
65
+ | `dept_ask` | question to the human without stopping work |
66
+ | `dept_answer` | human answer to a question |
67
+ | `dept_report` | department status report |
68
+ | `dept_health` | “is the department alive”: working / idle / waiting for human / ready to commit |
69
+ | `dept_modules` | module plan and file ownership for parallel work |
70
+ | `dept_art` | draw a pixel sprite and save a PNG |
71
+ | `dept_pixelize` | PNG/JPEG → pixel grid + palette + sprite (for redrawing from a reference) |
72
+ | `dept_compose` | compose a large PNG from small sprites (canvas, background, layers) |
73
+ | `dept_roles` | roles and models (researcher, designer, artist, senior-coder, supervisor, beta-tester, ...) |
74
+ | `dept_bug` | beta-tester bug report (steps, expected/actual, severity) |
75
+ | `dept_browse` | browser: open localhost/file, clicks, typing, screenshot into evidence |
76
+ | `dept_gui` | native app: command, env, timeout, output, screenshot via hook/command |
59
77
 
60
78
  ## HTTP API
61
79
 
62
- | Маршрут | Метод | Назначение |
80
+ | Route | Method | Purpose |
63
81
  |---|---|---|
64
- | `/api/department/tasks` | GET | задачи по проектам |
65
- | `/api/department/task?root=&taskId=` | GET | карточка задачи |
66
- | `/api/department/activity` | GET | живая активность агентов |
67
- | `/api/department/approve` | POST | утвердить документ |
68
- | `/api/department/answer` | POST | ответить на вопрос |
69
- | `/api/department/amend` | POST | подписать поправку |
70
- | `/api/department/budget?root=&taskId=` | GET/POST | бюджет и цены |
71
- | `/api/department/blueprint?root=` | GET | схема проекта |
72
- | `/api/department/asset?name=` | GET | ассеты офиса |
73
-
74
- ## Правила процесса
75
-
76
- 1. Этапы: `analysis → concept → concept_review → spec → spec_review → executing → done`.
77
- 2. Утверждения — только человеком (`dept_approve`), стадия двигается только через них.
78
- 3. Каждый этап закрывается коммитом с тегом `stage-N`; тег пушится вместе с веткой.
79
- 4. Гейты сбрасываются после коммита: pass предыдущего этапа не переезжает.
80
- 5. Провал тестов пишет `stages/NN/failure.md`; повтор запрещён, пока не заполнены
81
- «Анализ» и «План».
82
- 6. Автономные поправки — не более 5 на задачу, дальше эскалация человеку.
83
-
84
- ## Совместная работа над концепцией и ТЗ
85
-
86
- - Каждый специалист пишет свой раздел через `dept_section` (дизайнер — стиль,
87
- художник — что рисуем, исследователь — данные и статистика, тестер — стратегия
88
- проверки, архитектор — решения, аналитик — требования).
89
- - Спорные решения архитектор оформляет как идеи (`dept_ideas`): 2–3 варианта.
90
- - Специалисты рецензируют идеи (`dept_critique`): `approve`/`reject` и severity.
91
- Жёсткое отклонение (`high`) убивает идею; два одобрения без жёсткой критики
92
- принимают её. Отклонённую идею в работу не берут — архитектор предлагает новую.
93
- - Исследователь может собирать статистику и факты в интернете.
94
-
95
- ## Автономность (цель вместо таймера)
96
-
97
- - Руководитель создаёт цель: «довести задачу до done по plan.md» и не закрывает её
98
- до конца. DSH сам гоняет раунды — таймер не нужен.
99
- - Каждый раунд: `dept_health` → если `stalled`, найти причину и позвать специалиста:
100
- данные — researcher, визуал — designer, картинки — artist, конфликт — supervisor,
101
- архитектура — architect, сборочные правки — senior-coder.
102
- - `waiting_human` не останавливает: решение принимает команда, записка ждёт человека.
103
- - Защита от пустых раундов: если 2–3 раунда нет новых событий — зафиксировать
104
- `blocked` и служебную записку, а не крутиться.
105
- - Когда задача done — перейти к следующей; когда закрыты все — вечеринка (баннер в офисе).
106
-
107
- ## Автономность
108
-
109
- - Руководитель вызывает `dept_health` после каждого шага и не останавливается:
110
- `stalled` → следующий шаг плана, `waiting_human` → решает тактически сам,
111
- `ready_to_commit` → проверка и коммит.
112
- - Для длинных задач создаётся цель (goal), чтобы раунды шли без участия человека.
113
- - `supervisor` анализирует застой и решает так, как решил бы заказчик.
114
- - `researcher` ищет в интернете, `designer` подбирает визуал, `artist` рисует через `dept_art`.
115
- - Параллельная работа: `dept_modules` раздаёт файлы модулям, кодеры не пересекаются,
116
- `senior-coder` собирает и назначает доработки.
117
-
118
- ## Тестирование
119
-
120
- - **Тестер** — автоматические проверки: тесты, инварианты, exit code. Это гейт этапа.
121
- - **Бета-тестер** — играет/работает как пользователь: проходит сценарии, ловит
122
- непонятные места, сломанные потоки, визуальные баги; пишет баг-репорт через
123
- `dept_bug` (шаги, ожидаемое/фактическое, критичность, доказательство).
124
- Для игры/интерфейса использует `dept_browse`: открывает страницу, кликает,
125
- вводит и прикладывает скриншот к багрепорту.
126
- - Перед релизом руководитель запускает бета-тест и разбирает баги: критичные —
127
- в работу, остальные — в backlog.
128
-
129
- ### Нативные приложения (C++/Qt)
130
-
131
- - `dept_gui` запускает программу с аргументами/env и таймаутом, перехватывает вывод.
132
- - Скриншот: либо приложение само сохраняет кадр по флагу (`--screenshot file.png`,
133
- `QWidget::grab()` / `QQuickWindow::grabWindow()`), либо внешняя команда
134
- (`import -window root shot.png` под Xvfb).
135
- - Рекомендуемый путь для Qt: тестовый хук `--scenario`/`--selftest`, который проходит
136
- сценарий и сохраняет скриншоты; тогда бета-тест детерминирован и работает в CI.
137
- - Интерактивная GUI-автоматизация (клики мышью) требует Xvfb/xdotool; в текущем
138
- окружении их нет, поэтому ставка на хуки приложения и Qt Test.
139
-
140
- ## Подготовка к релизу (штатная фаза)
141
-
142
- Офис делает не только продукт, но и его выпуск. Релиз — не разовая просьба, а фаза после `done`:
143
-
144
- - `dept_start release=true` — бриф задачи получает шаблон `templates/release.md`
145
- (пакет, документация пользователя, QA-чек-лист, changelog, версия, тег, передача);
146
- - артефакт: `release/<продукт>-<версия>/` + архив `.zip`;
147
- - документация: `README.md` (запуск, управление), `MANUAL-QA.md` (ручное тестирование),
148
- `CHANGELOG.md`, известные ограничения;
149
- - проверка: тесты проекта, `dept_verify`, бета-тест по чек-листу (`dept_bug`);
150
- - фиксация: `dept_commit` с тегом `v<версия>`, тег в remote;
151
- - отчёт: где забрать, как запустить, что проверять руками.
152
-
153
- Критерий приёмки релиза: человек забирает артефакт и запускает без подсказок;
154
- документация отвечает на «как запустить», «что умеет», «что ограничено».
155
-
156
- ## Библиотека документов и журнал событий
157
-
158
- - Вкладка «Документы» — как почта: слева список документов (поиск по названию,
159
- фильтр по типу, сортировка по дате), справа содержимое.
160
- - Типы: служебная записка, отчёт этапа, ревью, баг-репорт, раздел специалиста,
161
- план переработки, ТЗ, концепция, план, бэклог.
162
- - Вкладка «События» — список слева, подробности выбранного события справа.
163
- - Markdown в документах отображается как разметка: заголовки, списки, таблицы,
164
- inline-код и блоки кода с подсветкой (JS/TS/C++/Python-ключевые слова).
165
- - Служебные записки, ждущие решения, помечены «ТРЕБУЕТ РЕШЕНИЯ» и подняты наверх
166
- списка; на доске у задачи бейдж «✍ N», в офисе — жёлтый маркер над руководителем,
167
- в шапке карточки — счётчик записок.
168
-
169
- ## Цели (goal)
170
-
171
- - Перед `update_goal` всегда вызывай `get_goal` и используй актуальную ревизию.
172
- - Ошибка `stale goal ref` значит, что ревизия уже сменилась: перечитай `get_goal`
173
- и повтори один раз с новой ревизией — не угадывай.
174
- - Пауза отдела не ставит цель на паузу: цель живёт отдельно (это DSH).
175
-
176
- ## Пауза и возобновление
177
-
178
- - `dept_pause` (или кнопка в карточке) — задача встаёт на паузу: гейты, коммит,
179
- правки блокируются, токены не тратятся, состояние остаётся на диске.
180
- - Сторож не будит задачу на паузе.
181
- - `paused=false` (подпись человека) — работа продолжается с того же места,
182
- в том числе после выключения/включения сервера.
183
- - В офисе пауза видна: баннер «отдел на паузе» и руководитель сидит в комнате отдыха.
184
-
185
- ## Сторож входящих данных
186
-
187
- - Каждые 5 минут плагин проверяет задачи отделов: новые корректировки (`new`),
188
- ответы на вопросы (`answered`), замечания к запискам (`changes_requested`).
189
- - Если появились новые данные — собирает пакет и будит руководителя (`followup`),
190
- один раз на каждый новый элемент; повторно то же самое не присылает.
191
- - Руководитель занят — сторож подождёт следующей проверки.
192
- - **Антизалипание**: если задача активна (не paused/done/blocked), агент простаивает,
193
- а последнее событие старше 15 минут — сторож будит руководителя подсказкой
194
- (dept_verify/commit или следующий шаг). Не чаще одного раза в 30 минут на задачу.
195
-
196
- ## Корректировки
197
-
198
- - Вкладка «Корректировка» — письмо руководителю: к чему относится (концепция/ТЗ/план/
199
- код/данные/интерфейс), тема и текст. Сохраняется в истории корректировок.
200
- - `dept_correction` — руководитель видит список, берёт в работу (`in_progress`),
201
- собирает специалистов на анализ и закрывает (`done`) с итогом.
202
- - По корректировкам дорабатываются концепция, ТЗ и план (`dept_amend`, `dept_section`).
203
-
204
- ## Вопросы и служебные записки
205
-
206
- Вопрос к человеку не останавливает работу:
207
-
208
- 1. `dept_ask` — вопрос записан, отдел продолжает.
209
- 2. `dept_propose` — супервайзер предлагает варианты решения.
210
- 3. `dept_critique` — специалисты критикуют; принятое решение фиксируется.
211
- 4. `dept_memo` — служебная записка: вопрос, варианты, критика, решение команды
212
- (файл `docs/department/<task>/memos/<question>.md`).
213
- 5. `dept_review` — человек утверждает (`approve`) или пишет замечания (`changes`).
214
- 6. `dept_rework` — архитектор готовит план переработки по замечаниям
82
+ | `/api/department/tasks` | GET | tasks across projects |
83
+ | `/api/department/task?root=&taskId=` | GET | task card |
84
+ | `/api/department/activity` | GET | live agent activity |
85
+ | `/api/department/approve` | POST | approve a document |
86
+ | `/api/department/answer` | POST | answer a question |
87
+ | `/api/department/amend` | POST | sign an amendment |
88
+ | `/api/department/budget?root=&taskId=` | GET/POST | budget and prices |
89
+ | `/api/department/blueprint?root=` | GET | project blueprint |
90
+ | `/api/department/asset?name=` | GET | office assets |
91
+
92
+ ## Process rules
93
+
94
+ 1. Stages: `analysis (discussion) → spec → spec_review → concept → concept_review → executing → release → done`.
95
+ `release` is production preparation: `dept_handover` builds `delivery/` with RUN.md,
96
+ MANUAL-QA.md, CHANGELOG.md and copies of the key documents; `done` is blocked without it.
97
+ 2. First comes the **task discussion**: the department asks questions and gathers requirements.
98
+ Then **spec and concept in any order** (iteratively): start from the spec (`spec.md`) or from
99
+ the concept (`concept.md`) with the architect's options; after the first document is approved
100
+ the department moves to the other and refines it. Approvals are human-only (`dept_approve`);
101
+ the project starts (`executing`) only when **both** are approved.
102
+ 3. The first execution step is the **plan** (`plan.md`), then stage-by-stage work.
103
+ The three key documents — **spec, concept, plan** — are always current: changes go through
104
+ `dept_amend`/`dept_section`; the Documents tab pins them at the top.
105
+ 4. Each stage is closed by a commit tagged `stage-N`; the tag is pushed with the branch.
106
+ 5. Gates reset after a commit: a previous stage's pass does not carry over.
107
+ 6. A test failure writes `stages/NN/failure.md`; retry is forbidden until “Analysis” and
108
+ “Plan” are filled in.
109
+ 7. Autonomous amendments — at most 5 per task, then escalate to the human.
110
+
111
+ ## Working together on concept and spec
112
+
113
+ - Each specialist writes their section via `dept_section` (designer — style, artist — what
114
+ to draw, researcher — data and statistics, tester — verification strategy, architect —
115
+ decisions, analyst — requirements).
116
+ - The architect frames contested decisions as ideas (`dept_ideas`): 2–3 options.
117
+ - Specialists review ideas (`dept_critique`): `approve`/`reject` and severity. A hard reject
118
+ (`high`) kills the idea; two approvals without hard criticism accept it. A rejected idea is
119
+ not taken into work — the architect proposes a new one.
120
+ - The researcher can collect statistics and facts on the internet.
121
+
122
+ ## Autonomy (goal instead of a timer)
123
+
124
+ - The manager creates a goal: “bring the task to done by plan.md” and does not close it until
125
+ the end. DSH drives the rounds itself — no timer needed.
126
+ - Each round: `dept_health` → if `stalled`, find the cause and call a specialist:
127
+ data — researcher, visuals — designer, images — artist, conflict — supervisor,
128
+ architecture — architect, integration fixes — senior-coder.
129
+ - `waiting_human` does not stop the work: the team decides, the memo waits for the human.
130
+ - Protection from empty rounds: if 2–3 rounds bring no new events — record `blocked` and a
131
+ memo instead of spinning.
132
+ - When a task is done — move to the next one; when all are closed — a party (office banner).
133
+
134
+ ## Autonomy
135
+
136
+ - The manager calls `dept_health` after every step and does not stop:
137
+ `stalled` → next plan step, `waiting_human` → decides tactically itself,
138
+ `ready_to_commit` → verify and commit.
139
+ - For long tasks a goal is created so rounds run without human involvement.
140
+ - `supervisor` analyses stagnation and decides as a customer would.
141
+ - `researcher` searches the web, `designer` picks visuals, `artist` draws via `dept_art`.
142
+ - Parallel work: `dept_modules` assigns files to modules, coders do not overlap,
143
+ `senior-coder` assembles and assigns follow-ups.
144
+
145
+ ## Testing
146
+
147
+ - **Tester** — automated checks: tests, invariants, exit code. This is the stage gate.
148
+ - **Beta-tester** — plays/works as a user: walks scenarios, catches confusing places,
149
+ broken flows, visual bugs; files a bug report via `dept_bug` (steps, expected/actual,
150
+ severity, evidence). For games/UI it uses `dept_browse`: opens the page, clicks, types and
151
+ attaches a screenshot to the report.
152
+ - Before a release the manager runs a beta test and triages bugs: critical — into work,
153
+ the rest — into the backlog.
154
+
155
+ ### Native applications (C++/Qt)
156
+
157
+ - `dept_gui` runs a program with arguments/env and a timeout, captures the output.
158
+ - Screenshot: either the app saves a frame itself by flag (`--screenshot file.png`,
159
+ `QWidget::grab()` / `QQuickWindow::grabWindow()`), or an external command
160
+ (`import -window root shot.png` under Xvfb).
161
+ - Recommended for Qt: a test hook `--scenario`/`--selftest` that walks a scenario and saves
162
+ screenshots; then the beta test is deterministic and works in CI.
163
+ - Interactive GUI automation (mouse clicks) needs Xvfb/xdotool; the current environment does
164
+ not have them, so the bet is on application hooks and Qt Test.
165
+
166
+ ## Release preparation (a standard phase)
167
+
168
+ The office does not only build the product but also ships it. A release is not a one-off
169
+ request but a phase after `done`:
170
+
171
+ - `dept_start release=true` — the task brief gets the `templates/release.md` template
172
+ (package, user documentation, QA checklist, changelog, version, tag, handover);
173
+ - artifact: `release/<product>-<version>/` + `.zip`;
174
+ - documentation: `README.md` (run, controls), `MANUAL-QA.md` (manual testing),
175
+ `CHANGELOG.md`, known limitations;
176
+ - verification: project tests, `dept_verify`, beta test by the checklist (`dept_bug`);
177
+ - commit: `dept_commit` with tag `v<version>`, tag pushed to remote;
178
+ - report: where to get it, how to run, what to check by hand.
179
+
180
+ Release acceptance criterion: the human takes the artifact and runs it without hints; the
181
+ documentation answers “how to run”, “what it can do”, “what is limited”.
182
+
183
+ ## Document library and event log
184
+
185
+ - The “Documents” tab is like mail: on the left a list of documents (search by title, filter
186
+ by type, sort by date), on the right the content.
187
+ - Types: memo, stage report, review, bug report, specialist section, rework plan, spec,
188
+ concept, plan, backlog.
189
+ - The “Events” tab — list on the left, details of the selected event on the right.
190
+ - Markdown in documents is rendered as markup: headings, lists, tables, inline code and code
191
+ blocks with highlighting (JS/TS/C++/Python keywords).
192
+ - Memos waiting for a decision are marked “REQUIRES DECISION” and raised to the top of the
193
+ list; the board shows a “✍ N” badge on the task, the office shows a yellow marker above the
194
+ manager, the card header shows the memo count.
195
+
196
+ ## Goals
197
+
198
+ - Before `update_goal` always call `get_goal` and use the current revision.
199
+ - A `stale goal ref` error means the revision has already changed: re-read `get_goal` and
200
+ retry once with the new revision — do not guess.
201
+ - Pausing the department does not pause the goal: the goal lives separately (that is DSH).
202
+
203
+ ## Pause and resume
204
+
205
+ - `dept_pause` (or the button in the card) — the task is paused: gates, commit and amendments
206
+ are blocked, no tokens are spent, the state stays on disk.
207
+ - The watchdog does not wake a paused task.
208
+ - `paused=false` (human signature) — work continues from the same place, including after a
209
+ server shutdown/startup.
210
+ - The office shows the pause: a “department paused” banner and the manager sits in the lounge.
211
+
212
+ ## Multilingual UI
213
+
214
+ The panel interface is **Russian and English**:
215
+
216
+ - an **EN/RU** button in the board header; the choice is remembered (`localStorage['dept-lang']`);
217
+ - by default — the browser language, falling back to Russian;
218
+ - translated: navigation, task card, tabs, stages, events, audit, document types, roles,
219
+ budget, office, project blueprint, charts.
220
+ - **Document content** is written by agents in the task language — it is not UI strings; the
221
+ documentation language is set in the brief (`lang` in task.md) or in the prompt.
222
+
223
+ Dictionary: `LOCALES` in `client.js` (ru/en), `dot.case` keys, `{n}` interpolation.
224
+ Roadmap — `docs/I18N.md`.
225
+
226
+ ## Incoming-data watchdog
227
+
228
+ - Every 5 minutes the plugin checks department tasks: new corrections (`new`), answers to
229
+ questions (`answered`), remarks on memos (`changes_requested`).
230
+ - If new data appears, it collects a package and wakes the manager (`followup`), once per new
231
+ item; it does not resend the same thing.
232
+ - If the manager is busy, the watchdog waits for the next check.
233
+ - **Anti-stall**: if the task is active (not paused/done/blocked), the agent is idle, and the
234
+ last event is older than 15 minutes — the watchdog wakes the manager with a hint
235
+ (dept_verify/commit or the next step). At most once per 30 minutes per task.
236
+
237
+ ## Corrections
238
+
239
+ - The “Corrections” tab is a letter to the manager: what it relates to (concept/spec/plan/
240
+ code/data/interface), subject and text. It is stored in the correction history.
241
+ - `dept_correction` — the manager sees the list, takes it into work (`in_progress`), gathers
242
+ specialists for analysis and closes it (`done`) with a summary.
243
+ - Corrections are used to update the concept, spec and plan (`dept_amend`, `dept_section`).
244
+
245
+ ## Questions and memos
246
+
247
+ A question to the human does not stop the work:
248
+
249
+ 1. `dept_ask` — the question is recorded, the department continues.
250
+ 2. `dept_propose` — the supervisor proposes solution options.
251
+ 3. `dept_critique` — specialists critique; the accepted decision is recorded.
252
+ 4. `dept_memo` — a memo: question, options, criticism, team decision
253
+ (file `docs/department/<task>/memos/<question>.md`).
254
+ 5. `dept_review` — the human approves (`approve`) or writes remarks (`changes`).
255
+ 6. `dept_rework` — the architect prepares a rework plan from the remarks
215
256
  (`docs/department/<task>/rework/<question>.md`).
216
257
 
217
- ## Мультипроект
258
+ ## Multi-project
218
259
 
219
- - Вкладка «Проекты» — агрегаты по корням: задачи, стадии, бюджет, последнее событие.
220
- - Каждый корень — отдельный отдел: задачи создаются через `dept_start root=...`,
221
- доска показывает все проекты, фильтр — по проекту.
222
- - Для параллельной работы внутри проекта: `dept_modules` (владение файлами) +
223
- `dept_worktree` (изолированные каталоги на модуль), слияние — сеньор-кодер.
224
- - Лимит одновременных кодеров — `maxInstances` у роли.
260
+ - The “Projects” tab — aggregates by root: tasks, stages, budget, last event.
261
+ - Each root is a separate department: tasks are created via `dept_start root=...`, the board
262
+ shows all projects, filtering by project.
263
+ - For parallel work inside a project: `dept_modules` (file ownership) + `dept_worktree`
264
+ (isolated directories per module), merging — senior-coder.
265
+ - The limit of concurrent coders is the role's `maxInstances`.
225
266
 
226
- ## Художник и референсы
267
+ ## Artist and references
227
268
 
228
- - `dept_art` рисует по сетке символов: вход — `rows` (символ = пиксель) и `palette`
229
- (символ → #rrggbb), выход — PNG (RGBA), масштаб 1–16.
230
- - `dept_pixelize` берёт PNG/JPEG/WebP, уменьшает до сетки (4–96), квантует в палитру
231
- (2–64 цвета или заданную), сохраняет PNG и возвращает `rows` + `palette` —
232
- художник правит пиксели вручную, чтобы получить похожий, но свой спрайт.
233
- - Референс — для стиля (палитра, пропорции), не для копирования чужой графики.
269
+ - `dept_art` draws on a character grid: input — `rows` (character = pixel) and `palette`
270
+ (character → #rrggbb), output — PNG (RGBA), scale 1–16.
271
+ - `dept_pixelize` takes PNG/JPEG/WebP, downsizes to a grid (4–96), quantizes to a palette
272
+ (2–64 colors or a given one), saves a PNG and returns `rows` + `palette` — the artist edits
273
+ pixels by hand to get a similar but own sprite.
274
+ - A reference is for style (palette, proportions), not for copying someone else's graphics.
234
275
 
235
- ### Художник работает не спеша
276
+ ### The artist works slowly
236
277
 
237
- - Скорость не критерий: качество важнее. Художник рисует по частям:
238
- референс/палитра → базовые формы → детали → проверка → композиция.
239
- - Каждый шаг — отдельный файл-чекпоинт (`assets/...png`), его можно пересмотреть.
240
- - Большая картинка не рисуется одним куском: маленькие спрайты + `dept_compose`.
241
- - Роль: `reasoning: high`, до 6 попыток; руководитель дробит задачу на элементы,
242
- а не даёт художнику «нарисуй всё».
278
+ - Speed is not a criterion: quality matters more. The artist draws in parts:
279
+ reference/palette → base shapes → details → check → composition.
280
+ - Each step is a separate checkpoint file (`assets/...png`) that can be reviewed.
281
+ - A large picture is not drawn in one piece: small sprites + `dept_compose`.
282
+ - Role: `reasoning: high`, up to 6 attempts; the manager splits the task into elements
283
+ instead of telling the artist “draw everything”.
243
284
 
244
- ## Ограничения
285
+ ## Limitations
245
286
 
246
- - Офис и схема — визуализация по данным сессий; арт простой.
247
- - Blueprint строит только статические импорты (JS/TS/C/C++/Python).
248
- - У каждой роли лимит одновременных экземпляров (`maxInstances`), у кодера по умолчанию 2:
249
- руководитель не может запускать больше кодеров, чем указано.
250
- - Роли можно включать/выключать (кроме manager/coder/tester); `beta-tester`
251
- по умолчанию выключен — запуск приложений и поток скриншотов дороги по ресурсам.
252
- - Бюджет считает usage, который отдают адаптеры модели; цены задаются вручную.
287
+ - The office and the blueprint are visualizations of session data; the art is simple.
288
+ - The blueprint builds only static imports (JS/TS/C/C++/Python).
289
+ - Each role has a limit of concurrent instances (`maxInstances`), the coder defaults to 2:
290
+ the manager cannot run more coders than allowed.
291
+ - Roles can be enabled/disabled (except manager/coder/tester); `beta-tester` is disabled by
292
+ default — launching apps and screenshot streams is resource-heavy.
293
+ - The budget counts the usage reported by model adapters; prices are set manually.
253
294
 
254
- ## Лицензия
295
+ ## License
255
296
 
256
- MIT. Ассеты офиса (папка `assets/`) — собственные и/или CC0; сторонние паки не входят.
297
+ MIT. Office assets (`assets/`) are original and/or CC0; third-party packs are not included.