code-ai-installer 2.3.0 → 2.4.1

package/dist/installer.js

@@ -5,6 +5,8 @@ import { loadSourceCatalog } from "./catalog.js";
 import { transformContentForTarget } from "./contentTransformer.js";
 /**
  * Runs installation for selected target with optional dry-run and backup.
+ * For target=google-antugravity, runs legacy prompt.md migration before applyOperations
+ * so the migrated <agent>.md ends up under applyOperations' backup/rollback coverage.
  * @param options Install options.
  * @returns Install state and write summary.
  */
@@ -27,6 +29,12 @@ export async function runInstall(options) {
         selectedAgents: options.selectedAgents,
         selectedSkills: options.selectedSkills,
     };
+    if (options.target === "google-antugravity" && !options.dryRun) {
+        await migrateLegacyGeminiPromptFiles({
+            destinationDir: options.destinationDir,
+            selectedAgents: options.selectedAgents,
+        });
+    }
     const result = await applyOperations({
         operations,
         overwriteMode: options.overwriteMode,
@@ -181,6 +189,46 @@ async function deleteInstallState(destinationDir, target, domain) {
         await fs.remove(stateFile);
     }
 }
+/**
+ * Renames legacy <agentsDir>/<agent>/prompt.md to <agent>.md for installs
+ * created by code-ai-installer <= v2.4.0 on the google-antugravity target.
+ * If both files exist (already migrated, but old prompt.md remained as orphan),
+ * removes the legacy file. Idempotent and safe to run on every install.
+ * Runs before applyOperations so the renamed file is backed up by the normal
+ * install transaction; on apply failure rollback restores user-customized content.
+ * @param args Migration arguments.
+ */
+async function migrateLegacyGeminiPromptFiles(args) {
+    const agentsDir = path.join(args.destinationDir, ".gemini", "agents");
+    if (!(await fs.pathExists(agentsDir))) {
+        return;
+    }
+    for (const agentName of args.selectedAgents) {
+        const legacyPath = path.join(agentsDir, agentName, "prompt.md");
+        const newPath = path.join(agentsDir, agentName, `${agentName}.md`);
+        const configPath = path.join(agentsDir, agentName, "config.json");
+        if (await fs.pathExists(legacyPath)) {
+            if (await fs.pathExists(newPath)) {
+                await fs.remove(legacyPath);
+            }
+            else {
+                await fs.rename(legacyPath, newPath);
+            }
+        }
+        if (await fs.pathExists(configPath)) {
+            try {
+                const config = (await fs.readJson(configPath));
+                if (config.promptFile === "prompt.md") {
+                    config.promptFile = `${agentName}.md`;
+                    await fs.writeJson(configPath, config, { spaces: 2 });
+                }
+            }
+            catch {
+                // Malformed config.json — leave it for applyOperations (overwrite mode regenerates it).
+            }
+        }
+    }
+}
 /**
  * Returns absolute path to state file for the target.
  * @param destinationDir Destination root.

package/dist/platforms/adapters.js

@@ -237,7 +237,7 @@ function planForGeminiLayout(layout, catalog, destinationDir, selectedAgents, se
         }
         operations.push({
             sourcePath,
-            destinationPath: path.join(destinationDir, layout.agentsDir, agentName, "prompt.md"),
+            destinationPath: path.join(destinationDir, layout.agentsDir, agentName, `${agentName}.md`),
             generated: false,
             transform: {
                 target,
@@ -345,7 +345,7 @@ function renderGeminiAgentConfig(agentName) {
     return `${JSON.stringify({
         name: agentName,
         model: "gemini-2.5-pro",
-        promptFile: "prompt.md",
+        promptFile: `${agentName}.md`,
         reasoning: "medium",
         temperature: 0.2,
     }, null, 2)}\n`;

package/domains/analytics/.agents/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: karpathy-guidelines
+description: Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.
+license: MIT
+source: https://x.com/karpathy/status/2015883857489522876
+---
+
+# Karpathy Guidelines
+
+Правила работы, основанные на наблюдениях Андрея Карпати о типичных ошибках LLM.
+
+> Эти правила ставят аккуратность выше скорости. Для совсем тривиальных задач используй здравый смысл.
+
+---
+
+## 1. Сначала думай, потом делай
+
+**Не предполагай молча. Не скрывай неопределённость. Называй альтернативы.**
+
+Перед тем как приступить:
+- Явно назови свои предположения. Если не уверен — спроси.
+- Если задачу можно понять по-разному — перечисли варианты, не выбирай сам.
+- Если есть более простой путь — скажи об этом. Возражай, когда это уместно.
+- Если что-то непонятно — остановись, назови конкретно что, и спроси.
+
+### Пример: скрытые предположения
+
+**Запрос:** "Добавь экспорт пользовательских данных"
+
+❌ **Что делают LLM** — молча предполагают формат, поля и объём:
+
+```python
+def export_users(format='json'):
+    users = User.query.all()
+    with open('users.json', 'w') as f:
+        json.dump([u.to_dict() for u in users], f)
+    return f"Exported {len(users)} users"
+```
+
+✅ **Как надо** — сначала назвать предположения и уточнить:
+
+```
+Прежде чем делать, нужно прояснить:
+
+1. Кого экспортировать: всех пользователей или отфильтрованных? (вопрос приватности)
+2. Что значит "экспорт": скачать файл, фоновая задача с уведомлением или API endpoint?
+3. Какие поля включать? (часть данных может быть чувствительной)
+4. Сколько пользователей обычно? (влияет на архитектуру)
+
+Что из этого важнее всего?
+```
+
+### Пример: несколько трактовок
+
+**Запрос:** "Ускорь поиск"
+
+❌ **Что делают LLM** — выбирают одну трактовку и пишут 200 строк оптимизации.
+
+✅ **Как надо:**
+
+```
+"Ускорить поиск" — это может быть разное:
+
+1. Уменьшить время ответа (< 100 мс вместо 500 мс)
+   → индексы в БД, кеш частых запросов | ~2 часа
+
+2. Выдерживать больше одновременных запросов
+   → async/await, connection pooling | ~4 часа
+
+3. Субъективно казаться быстрее (UX)
+   → показывать частичные результаты сразу | ~3 часа
+
+Сейчас поиск занимает ~500 мс. Что важнее?
+```
+
+---
+
+## 2. Делай только то, что просили
+
+**Минимум, решающий задачу. Ничего лишнего.**
+
+- Не добавляй возможности сверх того, что просили.
+- Не создавай абстракции, если код используется один раз.
+- Не делай код "гибким" и "настраиваемым" без запроса.
+- Не обрабатывай ошибки, которые не могут случиться.
+- Написал 200 строк, а можно 50 — перепиши.
+
+Спроси себя: "Сказал бы опытный коллега, что это переусложнено?" Если да — упрости.
+
+### Пример: лишние абстракции
+
+**Запрос:** "Добавь функцию расчёта скидки"
+
+❌ **Что делают LLM** — Strategy pattern, ABC, dataclass, конфигуратор:
+
+```python
+class DiscountStrategy(ABC):
+    @abstractmethod
+    def calculate(self, amount: float) -> float: pass
+
+class PercentageDiscount(DiscountStrategy):
+    def __init__(self, percentage: float):
+        self.percentage = percentage
+    def calculate(self, amount: float) -> float:
+        return amount * (self.percentage / 100)
+
+@dataclass
+class DiscountConfig:
+    strategy: DiscountStrategy
+    min_purchase: float = 0.0
+    max_discount: float = float('inf')
+
+# Ещё 40 строк ради одной формулы
+```
+
+✅ **Как надо:**
+
+```python
+def calculate_discount(amount: float, percent: float) -> float:
+    """Calculate discount amount. percent should be 0-100."""
+    return amount * (percent / 100)
+```
+
+Усложнять — только когда реально появится несколько типов скидок.
+
+### Пример: возможности "на будущее"
+
+**Запрос:** "Сохрани пользовательские настройки в БД"
+
+❌ **Что делают LLM** — кеш, валидатор, флаг merge, уведомления:
+
+```python
+class PreferenceManager:
+    def __init__(self, db, cache=None, validator=None):
+        ...
+    def save(self, user_id, prefs, merge=True, validate=True, notify=False):
+        # 50 строк вместо трёх
+```
+
+✅ **Как надо:**
+
+```python
+def save_preferences(db, user_id: int, preferences: dict):
+    db.execute(
+        "UPDATE users SET preferences = ? WHERE id = ?",
+        (json.dumps(preferences), user_id)
+    )
+```
+
+Кеш, валидацию, merge — добавить тогда, когда это реально понадобится.
+
+---
+
+## 3. Трогай только то, что нужно
+
+**Правь минимум. Чисти только за собой.**
+
+При редактировании существующего кода:
+- Не "улучшай" соседний код, комментарии или форматирование.
+- Не рефактори то, что работает.
+- Сохраняй существующий стиль, даже если ты сделал бы иначе.
+- Заметил лишний код рядом — упомяни, но не трогай.
+
+Если после твоих правок что-то стало неиспользуемым:
+- Удали то, что стало ненужным из-за твоих изменений.
+- Не трогай уже существующий мёртвый код без запроса.
+
+**Проверка:** каждая изменённая строка должна напрямую относиться к запросу.
+
+### Пример: попутный рефакторинг
+
+**Запрос:** "Исправь баг — пустой email вызывает падение валидатора"
+
+❌ **Что делают LLM** — заодно улучшают валидацию email, добавляют валидацию username, меняют комментарии, пишут docstring.
+
+✅ **Как надо — только строки, связанные с пустым email:**
+
+```diff
+  def validate_user(user_data):
+      # Check email format
+-     if not user_data.get('email'):
++     email = user_data.get('email', '')
++     if not email or not email.strip():
+          raise ValueError("Email required")
+
+      # Basic email validation
+-     if '@' not in user_data['email']:
++     if '@' not in email:
+          raise ValueError("Invalid email")
+
+      # Check username  ← не трогаем, это не в задаче
+      if not user_data.get('username'):
+          raise ValueError("Username required")
+
+      return True
+```
+
+### Пример: дрейф стиля
+
+**Запрос:** "Добавь логирование в функцию upload"
+
+❌ **Что делают LLM** — заодно добавляют type hints, меняют одинарные кавычки на двойные, пишут docstring, переформатируют отступы.
+
+✅ **Как надо — сохраняй существующий стиль:**
+
+```diff
++ import logging
++
++ logger = logging.getLogger(__name__)
++
+  def upload_file(file_path, destination):
++     logger.info(f'Starting upload: {file_path}')
+      try:
+          with open(file_path, 'rb') as f:
+              data = f.read()
+
+          response = requests.post(destination, files={'file': data})
+
+          if response.status_code == 200:
++             logger.info(f'Upload successful: {file_path}')
+              return True
+          else:
++             logger.error(f'Upload failed: {file_path}, status={response.status_code}')
+              return False
+      except Exception as e:
+-         print(f"Error: {e}")
++         logger.exception(f'Upload error: {file_path}')
+          return False
+```
+
+Сохранено: одинарные кавычки, нет type hints, тот же стиль boolean-возврата.
+
+---
+
+## 4. Работай от результата
+
+**Определи, как выглядит "готово". Проверяй каждый шаг.**
+
+Переформулируй задачи в проверяемые цели:
+- "Добавь валидацию" → "Напиши тесты на некорректные данные, затем сделай их зелёными"
+- "Исправь баг" → "Напиши тест, воспроизводящий баг, затем исправь"
+- "Рефакторинг X" → "Убедись, что тесты проходят до и после"
+
+Для многошаговых задач — кратко опиши план:
+
+```
+1. [Шаг] → проверка: [что проверить]
+2. [Шаг] → проверка: [что проверить]
+3. [Шаг] → проверка: [что проверить]
+```
+
+Чёткие критерии дают возможность работать самостоятельно. Размытые ("сделай так, чтобы работало") требуют постоянных уточнений.
+
+### Пример: пошаговая реализация с проверкой
+
+**Запрос:** "Добавь rate limiting в API"
+
+❌ **Что делают LLM** — реализуют Redis, несколько стратегий, конфигурацию и мониторинг в одном PR на 300 строк без чётких шагов проверки.
+
+✅ **Как надо:**
+
+```
+План:
+
+1. Базовый лимит в памяти (один endpoint)
+   Проверка: 100 запросов → первые 10 проходят, остальные получают 429
+
+2. Вынести в middleware (все endpoints)
+   Проверка: существующие тесты не сломались
+
+3. Redis вместо памяти (для нескольких серверов)
+   Проверка: лимит сохраняется после перезапуска
+
+4. Настройка лимитов per-endpoint
+   Проверка: /search — 10/мин, /users — 100/мин
+
+Начинаем с первого шага?
+```
+
+### Пример: сначала воспроизведи баг
+
+**Запрос:** "Сортировка ломается при одинаковых значениях"
+
+❌ **Что делают LLM** — сразу меняют логику сортировки, не убедившись, что воспроизвели проблему.
+
+✅ **Как надо:**
+
+```python
+# 1. Сначала — тест, воспроизводящий баг
+def test_sort_with_duplicate_scores():
+    scores = [
+        {'name': 'Alice', 'score': 100},
+        {'name': 'Bob', 'score': 100},
+        {'name': 'Charlie', 'score': 90},
+    ]
+    result = sort_scores(scores)
+    # Проблема: при одинаковых score порядок непредсказуем
+    assert result[0]['score'] == 100
+    assert result[2]['score'] == 90
+    assert result[0]['name'] < result[1]['name']  # ожидаем стабильную сортировку
+
+# Запускаем тест → он падает → баг подтверждён
+
+# 2. Только теперь исправляем
+def sort_scores(scores):
+    return sorted(scores, key=lambda x: (-x['score'], x['name']))
+
+# Запускаем тест → зелёный
+```
+
+---
+
+## Сводка: что делать нельзя
+
+| Принцип | Типичная ошибка | Правильно |
+|---|---|---|
+| Сначала думай | Молча выбирает формат, поля, трактовку задачи | Называет предположения явно, спрашивает |
+| Делай только то, что просили | Strategy pattern ради одного расчёта | Одна функция — и точка |
+| Трогай только то, что нужно | Правит кавычки и добавляет типы при фиксе бага | Меняет только строки, касающиеся задачи |
+| Работай от результата | "Проанализирую и улучшу" | "Тест воспроизводит баг → исправляю → проверяю регрессии" |
+
+## Главный вывод
+
+Переусложнённые решения не выглядят явно неправильными — они следуют паттернам и best practices. Проблема в **моменте**: сложность добавляется раньше, чем она реально нужна.
+
+**Хорошее решение — это минимум, который решает задачу сегодня, а не задачу, которая, возможно, появится завтра.**

package/domains/analytics/.agents/skills/karpathy-guidelines/agents/claude.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/analytics/.agents/skills/karpathy-guidelines/agents/copilot.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/analytics/.agents/skills/karpathy-guidelines/agents/gemini.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/analytics/.agents/skills/karpathy-guidelines/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Karpathy Guidelines"
+  short_description: "Поведенческие правила для снижения типичных ошибок LLM — думай перед тем как делать, простота, хирургические изменения, ориентация на цель."
+  default_prompt: "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/analytics/.agents/skills/karpathy-guidelines/agents/qwen.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/analytics/.agents/skills/karpathy-guidelines/agents/skill.yaml

@@ -0,0 +1,25 @@
+version: 1
+name: "karpathy-guidelines"
+display_name: "Karpathy Guidelines"
+description: "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата."
+default_prompt: "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование."
+triggers:
+  - "karpathy-guidelines"
+  - "karpathy"
+  - "Karpathy Guidelines"
+  - "сначала думай потом делай"
+  - "простота прежде всего"
+  - "хирургические изменения"
+capabilities:
+  - "quality"
+  - "guidelines"
+  - "best-practices"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "ru"
+  available_locales:
+    - "ru"
+    - "en"

package/domains/analytics/AGENTS.md

@@ -93,3 +93,6 @@ CONDUCTOR → INTERVIEWER → RESEARCHER → DATA_ANALYST → STRATEGIST → MED
 
 ### Верстальщик
 - $html-pdf-report — генерация HTML/CSS → PDF
+
+### Cross-cutting / Quality (все агенты домена)
+- $karpathy-guidelines — обязателен перед любой нетривиальной задачей

package/domains/analytics/agents/conductor.md

@@ -42,6 +42,7 @@ compliance — анализ не уходит за пределы исследо
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **$board** — управление доской задач, трекинг статусов гейтов, метрики прогресса
 - **$handoff** — формирование handoff-конвертов и межсессионных файлов
 - **$gates** — контроль гейтов, проверка deliverables, severity (Blocker/Gap/Note)

package/domains/analytics/agents/data_analyst.md

@@ -45,6 +45,7 @@ Alpha и обязан: (1) провести собственный анализ
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$gates`** — проверка deliverable по AN-xx criteria перед передачей
 - **`$handoff`** — формирование конверта для Strategist
 
@@ -327,7 +328,7 @@ Data quality: Verified XX% | Estimated XX% | Assumed XX%
 ## Анализ по фреймворкам
 
 ### Фреймворк 1: [Название]
-**Skill:** $skill-name
+**Skill:** `<skill-name>`
 **Quality Gate:** ✅ Пройден (N/N чекбоксов)
 
 **Результат:**

package/domains/analytics/agents/designer.md

@@ -40,6 +40,7 @@
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$report-design`** — проектирование макета: структура, визуализации, иерархия, палитра
 - **`$gates`** — проверка deliverable по DS-xx criteria перед передачей Layouter
 - **`$handoff`** — формирование конверта для Layouter

package/domains/analytics/agents/interviewer.md

@@ -43,6 +43,7 @@
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$gates`** --- проверка deliverable по INT-xx criteria перед передачей
 - **`$handoff`** --- приём handoff от COND-01 + формирование конверта с Research Brief
 - **`$board`** --- обновление статуса INT-01

package/domains/analytics/agents/layouter.md

@@ -39,6 +39,7 @@
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$html-pdf-report`** — полный протокол генерации HTML: CSS, Chart.js, Mermaid, компоненты, тестирование
 - **`$gates`** — проверка deliverable по LY-xx criteria + Release Gate
 - **`$handoff`** — приём от DS-01 + передача на Release Gate

package/domains/analytics/agents/mediator.md

@@ -41,6 +41,7 @@
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$gates`** --- проверка deliverable по MED-xx criteria перед передачей
 - **`$handoff`** --- приём от COND-04 + формирование конверта с Mediated Conclusion
 - **`$board`** --- обновление статуса MED-01

package/domains/analytics/agents/researcher.md

@@ -46,6 +46,7 @@
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$web-research`** — веб-поиск и верификация данных. Запускается **всегда**. Протокол: тирование источников (T1/T2/T3), 3-уровневая достоверность, аудит-трейл, контр-поиск, метрики качества.
 - **`$gates`** — проверка deliverable по RES-xx criteria (web-search = Blocker, dependency check)
 - **`$handoff`** — приём от COND-xx + формирование конверта для AN-xx

package/domains/analytics/agents/strategist.md

@@ -49,6 +49,7 @@ Reasoning всегда `high` — стратегические рекоменд
 ## Используемые skills
 
 ### Обязательные (каждый раз)
+- **$karpathy-guidelines** — сначала думай, делай только нужное, правь точечно, работай от результата
 - **`$gates`** — проверка deliverable по ST-xx criteria (прослеживаемость, dependency check)
 - **`$handoff`** — приём от AN-xx + формирование конверта для Conductor
 - **`$board`** — обновление статуса ST-xx