@rt-tools/agent-kit 0.3.0 → 0.4.0

package/assets/templates/gate-map.sh

@@ -1,37 +1,45 @@
 #!/usr/bin/env bash
-# Карта «что правится — какое правило» этого дерева. Её читает хук гейта правил.
+# Надстройка карты гейта: то, чего нет у других деревьев мастерской.
 #
-# Живёт в проекте, а не в пакете: имена каталогов, расширения и команды поставки у каждого
-# дерева свои. Пакет везёт механизм, проект — карту.
+# Скопировать в `.claude/rt-kit/gate-map.sh` и дописать своё. Файл необязателен: без него
+# действует умолчание пакета — `.claude/rt-kit/defaults/gate-map.sh`, где уже разобраны тесты,
+# компоненты, стили, барели, манифесты, документы и команды поставки.
 #
-# Функция печатает ИМЯ ПРАВИЛА или молчит. Молчание — «правила на это нет», и гейт пропускает.
+# Заводить эту надстройку стоит ровно тогда, когда у дерева есть род файлов, которого нет у
+# остальных: витрина, свой генератор, чужая раскладка каталогов.
 #
-# Порядок веток решает: первое совпадение выигрывает, поэтому частное идёт раньше общего.
-# Файл спеки — не файл компонента, и обе ветки обязаны стоять до общей ветки расширения.
+# Функция печатает ИМЯ ПРАВИЛА или молчит. Имён может быть несколько, по одному в строке.
+# Порядок веток решает: первое совпадение выигрывает, поэтому частное идёт раньше общего — и
+# своё частное обязано стоять ДО вызова умолчания, иначе общая ветка расширения его перехватит.
 
 skill_for() {
     kind="$1"
     target="$2"
+    written="$3"
 
     case "$kind" in
         edit)
             case "$target" in
-                # Файлы самого агента правятся без правила: правило на них — это оно само.
-                */.claude/*)                        return 0 ;;
-                *.spec.ts)                          printf '%s' '<правило про тесты>' ;;
-                *.component.ts|*.component.html)    printf '%s' '<правило про компонент>' ;;
-                *.scss)                             printf '%s' '<правило про оформление>' ;;
-                */index.ts)                         printf '%s' '<правило про раскладку либ>' ;;
-                *.ts)                               printf '%s' '<правило про код>' ;;
-                *.md)                               printf '%s' '<правило про тексты>' ;;
+                # Пример: у витрины своё правило, пакет такого не везёт.
+                # *.stories.ts | *.mdx) printf '%s\n' '<правило витрины>' ; return 0 ;;
+
+                # Пример: домен, который правится по своему правилу.
+                # */libs/<домен>/*) printf '%s\n' '<правило домена>' ; return 0 ;;
+                *) ;;
             esac
             ;;
         bash)
             case "$target" in
-                *git\ commit*|*git\ push*|*gh\ pr\ create*) printf '%s' '<правило про поставку>' ;;
+                # Пример: своя команда развёртывания.
+                # *<команда>*) printf '%s\n' '<правило>' ; return 0 ;;
+                *) ;;
             esac
             ;;
     esac
 
+    # Всё, что дерево не назвало своим, разбирает умолчание пакета. Проверка на объявленность
+    # нужна ровно в одном промежутке: пакет обновлён, а `sync` в этом дереве ещё не прогнан.
+    command -v skill_for_default >/dev/null 2>&1 && skill_for_default "$kind" "$target" "$written"
+
     return 0
 }

package/assets/templates/implementation.md

@@ -1,14 +1,20 @@
-# <имя-правила> — как это устроено здесь
+# <имя-правила> — что здесь своё
 
-Имена этого дерева при правиле `SKILL.md` рядом. Отдельный файл потому, что правило говорит
-приёмом и переносится между репозиториями целиком, а всё, что ниже, верно только здесь и
-устаревает при каждом переименовании.
+Имена и привязки этого дерева при правиле `SKILL.md` рядом.
+
+Правило говорит приёмом и называет пути, общие для деревьев мастерской, — их переписывать
+здесь не надо. Сюда идёт только то, чего пакет знать не может: как названы вещи именно в этом
+репозитории, и в каком его файле каждая статья правила исполняется.
 
 Пока в файле стоит `<!-- заполняет проект -->`, правило считается неразвёрнутым: `agent-kit
-sync --check` отказывает, а агент читает указание, которому здесь нечего назвать.
+sync --check` отказывает, а агент читает указание, у которого здесь нет адресата.
 
 ## Как это называется здесь
 
+Только то, что расходится с правилом: ключ задач, адрес борды, префикс компонентов, имя
+владеющей сущности, валюта хранения, набор областей коммита. Строку, которая просто повторяет
+правило, сюда не переносят — она устареет отдельно от него.
+
 | В правиле         | Здесь                                       |
 | ----------------- | ------------------------------------------- |
 | <понятие правила> | <имя в этом коде> <!-- заполняет проект --> |
@@ -21,9 +27,9 @@ sync --check` отказывает, а агент читает указание,
 
 ## Где исполняются статьи
 
-Первая колонка — статья дословно, как она написана в разделе «Что здесь действует» правила
-(жирная часть пункта). Статья без строки и строка без статьи — расхождение: правило обещает
-то, чего в дереве нет, либо в дереве стоит то, о чём правило молчит.
+Первая колонка — статья дословно, как она написана в разделе «Как закон применяется здесь»
+(жирная часть пункта). Статья без строки и строка без статьи — расхождение: правило обещает то,
+чего в дереве нет, либо в дереве стоит то, о чём правило молчит.
 
 | Статья            | Где исполняется                             |
 | ----------------- | ------------------------------------------- |

package/assets/templates/pattern.md

@@ -8,7 +8,7 @@ description: Паттерн правила <имя-правила>. Брать <
 # <Что собирается>
 
 Паттерн правила `<имя-правила>`. Что при этом должно быть верно — закон
-`{{lawsDir}}/<закон>.md`.
+`docs/constitution/<закон>.md`.
 
 ## Когда брать
 

package/assets/templates/project.sh

@@ -1,41 +1,54 @@
 #!/usr/bin/env bash
-# Профиль этого дерева: что здесь чем зовётся и какими командами проверяется.
+# Надстройка профиля дерева: команды, стенды и пары «правка — документ» этого репозитория.
 #
-# Живёт в проекте, а не в пакете: механизм у сторожевых хуков общий, а команды, порты и пары
-# «правка — её документ» у каждого дерева свои. Пакет везёт хуки, проект — этот файл.
+# Скопировать в `.claude/rt-kit/project.sh` и дописать своё. Файл необязателен: без него
+# действует умолчание пакета — `.claude/rt-kit/defaults/project.sh`, где запускатель выбирается
+# по локфайлу, а линтеры, форма имени ветки и образцы переизобретения уже названы.
 #
-# Каждая функция вправе промолчать. Молчание значит «правила на это нет», и хук пропускает:
-# пустой профиль оставляет хуки безвредными, а не отбивающими наугад.
+# Каждая функция вправе промолчать. Молчание значит «правила на это нет», и хук пропускает.
+# Объявленная здесь функция замещает умолчание ЦЕЛИКОМ — чтобы дописать, а не заменить, зовите
+# из неё то же имя с суффиксом `_default`.
 
 # Где подняты приложения. Идёт в текст отказа, когда кто-то поднимает второй экземпляр.
+# Умолчание молчит: чужой порт назвать хуже, чем не назвать никакого.
 RT_STANDS='<приложение> http://localhost:<порт>, <приложение> http://localhost:<порт>'
 
+# Адрес боевого хранилища. Любая запись по нему отбивается совсем, и опт-аут не действует.
+RT_PROD_DSN='<хост боевого хранилища>'
+
+# Пути, у которых якорь для сквозных тестов не требуется.
+RT_QA_SKIP_RE='<выражение путей>'
+
 # Команды, которые обязаны пройти перед пушем. По одной на строку; первая упавшая отбивает пуш.
 rt_push_checks() {
-    cat <<'EOF'
-<команда линтера кода>
-<команда линтера стилей>
-<команда тестов>
-EOF
+    rt_push_checks_default
+    # printf '%s\n' '<своя проверка>'
 }
 
-# Какой документ обязан ехать тем же коммитом, что и этот файл. Печатает путь или молчит.
+# Какой документ обязан ехать тем же коммитом, что и этот файл. Печатает образец пути или молчит.
 rt_docs_pair_for() {
     case "$1" in
-        */<каталог правил>/*)   printf '%s' '<зеркало правила>' ;;
-        *.proto)                printf '%s' '<спек задетого домена>' ;;
+        # <свой путь>) printf '%s' '<образец пути документа>' ; return 0 ;;
+        *) ;;
     esac
+
+    rt_docs_pair_for_default "$1"
 }
 
 # Чем линтуется этот файл сразу после правки. Печатает команду или молчит.
 rt_lint_for() {
-    case "$1" in
-        *.scss)  printf '%s' '<команда линтера стилей> "$1"' ;;
-        *.ts)    printf '%s' '<команда линтера кода> "$1"' ;;
-    esac
+    rt_lint_for_default "$1"
 }
 
-# Имя ветки, с которой разрешено открывать PR: номер задачи в имени. Успех — годится.
+# Имя ветки, с которой разрешено открывать заявку на слияние. Успех — годится.
 rt_task_branch_ok() {
-    printf '%s' "$1" | grep -qE '<выражение имени ветки>'
+    rt_task_branch_ok_default "$1"
+}
+
+# Что в этом дереве считается переизобретением. По строке «образец<таб>чем заменить».
+rt_reinvented_in() {
+    rt_reinvented_in_default "$1"
+    # case "$1" in
+    #     *.ts) printf '%s\t%s\n' '<образец>' '<чем заменить>' ;;
+    # esac
 }

package/assets/templates/rule.md

@@ -7,7 +7,7 @@ description: Правило под закон «<Название закона>
 
 # <О чём закон> — каким приёмом
 
-Правило под закон `{{lawsDir}}/<закон>.md`. Закон говорит, что должно быть верно; здесь — каким
+Правило под закон `docs/constitution/<закон>.md`. Закон говорит, что должно быть верно; здесь — каким
 приёмом это делается. Чем это названо в этом дереве и где лежит — `implementation.md` рядом:
 правило переносится между репозиториями, имена — нет.
 

package/assets/variants.json

@@ -0,0 +1,20 @@
+{
+  "host": {
+    "question": "Где лежит репозиторий и очередь работ?",
+    "title": "хостинг репозитория",
+    "options": [
+      {
+        "value": "github",
+        "title": "GitHub — gh, issues, Projects"
+      },
+      {
+        "value": "gitlab",
+        "title": "GitLab — glab, issues, Boards"
+      },
+      {
+        "value": "azure",
+        "title": "Azure DevOps — az repos, work items, Boards"
+      }
+    ]
+  }
+}

package/assets/workflows/feature.js

@@ -0,0 +1,134 @@
+export const meta = {
+    name: 'feature',
+    description: 'План от PM, реализация по шагам, веер проверок QA и приёмка по исходному запросу',
+    whenToUse: 'Крупная правка, которая заденет несколько слоёв: контракт, хранилище, приложения, переводы',
+    phases: [
+        { title: 'План', detail: 'PM разбивает задачу на шаги с признаками готовности' },
+        { title: 'Реализация', detail: 'по шагу за раз — рабочее дерево одно на всех' },
+        { title: 'Проверка', detail: 'QA веером: тесты, сборка, браузер, состязательный разбор' },
+        { title: 'Приёмка', detail: 'PM сверяет сделанное с исходным запросом' },
+    ],
+};
+
+// Задача приходит строкой в args; без неё сценарий бессмыслен.
+const task = typeof args === 'string' ? args : (args?.task ?? '');
+if (!task) {
+    throw new Error('Нужна задача: передай её строкой в args');
+}
+
+const PLAN = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['steps', 'risks', 'acceptance'],
+    properties: {
+        steps: {
+            type: 'array',
+            maxItems: 6,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['title', 'scope', 'done'],
+                properties: {
+                    title: { type: 'string' },
+                    scope: { type: 'string', description: 'что входит и что НЕ входит' },
+                    done: { type: 'string', description: 'проверяемый признак готовности' },
+                },
+            },
+        },
+        risks: { type: 'array', items: { type: 'string' } },
+        acceptance: { type: 'array', items: { type: 'string' }, description: 'критерии приёмки по исходному запросу' },
+    },
+};
+
+const FINDINGS = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['findings', 'checked'],
+    properties: {
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['what', 'where', 'evidence', 'severity'],
+                properties: {
+                    what: { type: 'string' },
+                    where: { type: 'string' },
+                    evidence: { type: 'string', description: 'вывод команды или замер, а не пересказ' },
+                    severity: { type: 'string', enum: ['blocker', 'major', 'minor'] },
+                    preExisting: { type: 'boolean' },
+                },
+            },
+        },
+        checked: { type: 'array', items: { type: 'string' } },
+    },
+};
+
+phase('План');
+const plan = await agent(
+    `Задача от пользователя:\n\n${task}\n\nРазбери её и верни план. Шагов не больше шести; ` +
+        `каждый — самостоятельная правка с проверяемым признаком готовности.`,
+    { agentType: 'project-manager', label: 'план', schema: PLAN }
+);
+log(`План: ${plan.steps.length} шаг(ов), рисков ${plan.risks.length}`);
+
+// Шаги идут по очереди, а не веером: рабочее дерево одно, и параллельные
+// правки одних и тех же файлов затирали бы друг друга.
+phase('Реализация');
+const done = [];
+for (const [index, step] of plan.steps.entries()) {
+    const result = await agent(
+        `Задача целиком: ${task}\n\nТвой шаг ${index + 1} из ${plan.steps.length}: ${step.title}\n` +
+            `Границы: ${step.scope}\nПризнак готовности: ${step.done}\n\n` +
+            `Уже сделано на предыдущих шагах:\n${done.join('\n') || '— ничего'}\n\n` +
+            `Соблюдай правила дерева из CLAUDE.md и .claude/skills. Перед правкой файла загрузи ` +
+            `подходящее правило через инструмент Skill — иначе гейт правил заблокирует правку. ` +
+            `Никаких git-команд. Верни коротко: какие файлы изменил и чем подтверждается признак готовности.`,
+        { label: `шаг ${index + 1}: ${step.title}`, phase: 'Реализация' }
+    );
+    done.push(`${step.title}: ${result ?? 'шаг не выполнен'}`);
+}
+
+// Здесь барьер оправдан: приёмке нужны все находки разом, а измерения
+// независимы и честно параллелятся.
+phase('Проверка');
+const LENSES = [
+    { key: 'тесты', prompt: 'Прогони юнит-тесты и e2e по затронутому. Отдели новые падения от доэтапных.' },
+    { key: 'сборка', prompt: 'Прогони сборки затронутых приложений и линтеры. Доэтапные ошибки помечай как доэтапные.' },
+    {
+        key: 'браузер',
+        prompt: 'Проверь результат в браузере замерами: вычисленные стили, геометрия, контраст. Серверы разработки уже подняты — свой не поднимай.',
+    },
+    {
+        key: 'разбор',
+        prompt: 'Состязательно разбери правку: граничные значения, вторая локаль, тёмная тема, узкий экран, отвалившийся сервер, отдача страницы сервером.',
+    },
+];
+const reports = (
+    await parallel(
+        LENSES.map(
+            (lens) => () =>
+                agent(`Задача, которую выполняли: ${task}\n\nЧто сделано:\n${done.join('\n')}\n\n${lens.prompt}`, {
+                    agentType: 'qa-engineer',
+                    label: `qa: ${lens.key}`,
+                    phase: 'Проверка',
+                    schema: FINDINGS,
+                })
+        )
+    )
+).filter(Boolean);
+
+const findings = reports.flatMap((report) => report.findings);
+const blockers = findings.filter((finding) => finding.severity === 'blocker' && !finding.preExisting);
+log(`Находок ${findings.length}, из них блокеров ${blockers.length}`);
+
+phase('Приёмка');
+const verdict = await agent(
+    `Исходный запрос пользователя:\n\n${task}\n\nКритерии приёмки:\n${plan.acceptance.join('\n')}\n\n` +
+        `Что сделано:\n${done.join('\n')}\n\nНаходки проверяющих:\n${JSON.stringify(findings, null, 1)}\n\n` +
+        `Вынеси вердикт: что принято, что нет и почему. Отдельно назови, что из исходного запроса ` +
+        `осталось незакрытым или тихо сузилось.`,
+    { agentType: 'project-manager', label: 'приёмка', phase: 'Приёмка' }
+);
+
+return { plan, done, findings, blockers, verdict };

package/assets/workflows/plan.js

@@ -0,0 +1,150 @@
+export const meta = {
+    name: 'plan',
+    description: 'После разбора с владельцем: нужна ли работа, договорённость о продукте, её состязательный разбор и замысел реализации',
+    whenToUse: 'Разбор просьбы владельца закрыт, папка задачи заведена, код ещё не пишется',
+    phases: [
+        { title: 'Нужность', detail: 'что даёт работа и что из неё выкидывается' },
+        { title: 'Договорённость', detail: 'спек фичи в proposed/ по разбору' },
+        { title: 'Критика', detail: 'что в договорённости недосказано' },
+        { title: 'Замысел', detail: 'этапы с признаками готовности и разбивка на задачи' },
+    ],
+};
+
+// Папка задачи приходит в args; без неё конвейеру нечего читать. Разбор просьбы владельца
+// лежит в ней и остаётся единственным источником: пересказывать его в промпте значит терять
+// слова владельца, ради которых он и записан.
+const dir = typeof args === 'string' ? args : (args?.dir ?? '');
+if (!dir) {
+    throw new Error('Нужна папка задачи: передай её строкой в args, например docs/tasks/<ветка>');
+}
+
+const grill = `${dir}/grill.md`;
+
+const WORTH = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['verdict', 'gives', 'drop'],
+    properties: {
+        verdict: { type: 'string', enum: ['делать', 'делать урезанно', 'отложить'] },
+        gives: { type: 'string', description: 'что владелец получит' },
+        drop: { type: 'array', items: { type: 'string' }, description: 'что выкидывается без потери цели' },
+        risks: { type: 'array', items: { type: 'string' } },
+    },
+};
+
+const DRAFT = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['path', 'rules', 'gaps'],
+    properties: {
+        path: { type: 'string', description: 'заведённая директория в docs/specs/*/proposed/' },
+        rules: { type: 'array', items: { type: 'string' }, description: 'правила по одной строке' },
+        gaps: { type: 'array', items: { type: 'string' }, description: 'пробелы, которые не закрыть без владельца' },
+    },
+};
+
+const FINDINGS = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['findings'],
+    properties: {
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['what', 'where', 'cost'],
+                properties: {
+                    what: { type: 'string', description: 'что недосказано' },
+                    where: { type: 'string', description: 'файл и правило дословно' },
+                    cost: { type: 'string', description: 'чем обернётся в коде' },
+                },
+            },
+        },
+    },
+};
+
+const PLAN = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['tasks', 'steps', 'acceptance'],
+    properties: {
+        tasks: {
+            type: 'array',
+            description: 'на сколько задач делится работа; одна — обычный случай',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['title', 'slug', 'why'],
+                properties: {
+                    title: { type: 'string' },
+                    slug: { type: 'string' },
+                    why: { type: 'string', description: 'почему это откатывается отдельно' },
+                },
+            },
+        },
+        steps: {
+            type: 'array',
+            maxItems: 8,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['title', 'scope', 'done'],
+                properties: {
+                    title: { type: 'string' },
+                    scope: { type: 'string', description: 'что входит и что НЕ входит' },
+                    done: { type: 'string', description: 'проверяемый признак готовности' },
+                },
+            },
+        },
+        acceptance: { type: 'array', items: { type: 'string' } },
+    },
+};
+
+phase('Нужность');
+const worth = await agent(
+    `Разбор просьбы владельца — \`${grill}\`. Прочитай его целиком.\n\n` +
+        `Скажи, что эта работа даёт владельцу, что из неё выкидывается без потери цели и почему её ` +
+        `стоит делать сейчас, а не через полгода. Отвергнутое называй с причиной.`,
+    { agentType: 'business-analyst', label: 'нужность', schema: WORTH }
+);
+log(`Нужность: ${worth.verdict}; выкидывается пунктов ${worth.drop.length}`);
+
+if (worth.verdict === 'отложить') {
+    log('Работа не начинается: решение относится владельцу.');
+    return { worth, stopped: 'аналитик предложил отложить — решение за владельцем' };
+}
+
+phase('Договорённость');
+const draft = await agent(
+    `Разбор просьбы владельца — \`${grill}\`. Прочитай его целиком и напиши по нему договорённость ` +
+        `о продукте: \`docs/specs/<домен>/proposed/<фича>/\`.\n\n` +
+        `Из работы выкинуто: ${worth.drop.join('; ') || '— ничего'}.\n\n` +
+        `Пробелы, которые не закрываются разбором, не додумывай — верни их списком.`,
+    { agentType: 'spec-writer', label: 'договорённость', schema: DRAFT }
+);
+log(`Договорённость: ${draft.path}, правил ${draft.rules.length}, пробелов ${draft.gaps.length}`);
+
+phase('Критика');
+const critique = await agent(
+    `Договорённость — \`${draft.path}\`, разбор просьбы владельца — \`${grill}\`.\n\n` +
+        `Состязательно разбери договорённость: что недосказано, где два прочтения, какие случаи ` +
+        `не названы. Ничего не правь.`,
+    { agentType: 'spec-critic', label: 'критика', schema: FINDINGS }
+);
+log(`Критика: находок ${critique.findings.length}`);
+
+phase('Замысел');
+const plan = await agent(
+    `Разбор просьбы владельца — \`${grill}\`, договорённость — \`${draft.path}\`.\n\n` +
+        `Находки состязательного разбора:\n${critique.findings.map((f) => `- ${f.what} (${f.where})`).join('\n') || '— нет'}\n\n` +
+        `Собери замысел реализации: этапы с границами и проверяемым признаком готовности у каждого. ` +
+        `Отдельно скажи, на сколько задач делится работа: делится то, что придётся откатывать порознь, ` +
+        `а не то, что просто объёмно. Одна задача — обычный случай.`,
+    { agentType: 'project-manager', label: 'замысел', schema: PLAN }
+);
+log(`Замысел: задач ${plan.tasks.length}, этапов ${plan.steps.length}`);
+
+// Ничего не записывается на диск отсюда: замысел и пробелы уходят владельцу, а `plan.md`
+// пишет главный агент — вопросы к владельцу задаёт только он.
+return { worth, draft, critique: critique.findings, plan };

package/bin/agent-kit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-kit.d.ts","sourceRoot":"","sources":["../../../projects/agent-kit/src/bin/agent-kit.ts"],"names":[],"mappings":";AAaA,OAAO,EAA8B,iBAAiB,EAAc,MAAM,oBAAoB,CAAC;AAwF/F,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsB9E"}
+{"version":3,"file":"agent-kit.d.ts","sourceRoot":"","sources":["../../../projects/agent-kit/src/bin/agent-kit.ts"],"names":[],"mappings":";AAaA,OAAO,EAAqC,iBAAiB,EAAc,MAAM,oBAAoB,CAAC;AAoKtG,wBAAsB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqC9E"}