git:20260114.28781d4 to git:20260116.b506f92

- # MAP Framework Development Instructions

-

- ## Critical: Template Synchronization

-

- **ВАЖНО**: После изменения любых файлов в `.claude/agents/` или `.claude/commands/`, ВСЕГДА синхронизируй их в `src/mapify_cli/templates/`!

-

- ### Почему это критично?

-

- Когда пользователи запускают `mapify init`, они получают шаблоны из `src/mapify_cli/templates/`, а НЕ из `.claude/`. Если забыть синхронизировать:

- - Новые пользователи получают УСТАРЕВШИЕ шаблоны

- - Улучшения НЕ доступны через `mapify init`

- - Создаётся расхождение между dev и production шаблонами

-

- ### Процесс синхронизации

-

- После ЛЮБОГО изменения файлов в `.claude/agents/` или `.claude/commands/`:

-

- ```bash

- # 1. Проверь что изменилось

- git status .claude/agents/ .claude/commands/

-

- # 2. Синхронизируй агентов

- cp .claude/agents/task-decomposer.md src/mapify_cli/templates/agents/

- cp .claude/agents/actor.md src/mapify_cli/templates/agents/

- cp .claude/agents/monitor.md src/mapify_cli/templates/agents/

- cp .claude/agents/predictor.md src/mapify_cli/templates/agents/

- cp .claude/agents/evaluator.md src/mapify_cli/templates/agents/

- cp .claude/agents/reflector.md src/mapify_cli/templates/agents/

- cp .claude/agents/curator.md src/mapify_cli/templates/agents/

- cp .claude/agents/documentation-reviewer.md src/mapify_cli/templates/agents/

- cp .claude/agents/research-agent.md src/mapify_cli/templates/agents/

- cp .claude/agents/synthesizer.md src/mapify_cli/templates/agents/

-

- # 3. Синхронизируй команды

- cp .claude/commands/map-efficient.md src/mapify_cli/templates/commands/

- cp .claude/commands/map-debug.md src/mapify_cli/templates/commands/

- cp .claude/commands/map-fast.md src/mapify_cli/templates/commands/

- cp .claude/commands/map-learn.md src/mapify_cli/templates/commands/

- cp .claude/commands/map-release.md src/mapify_cli/templates/commands/

- cp .claude/commands/map-review.md src/mapify_cli/templates/commands/

-

- # 4. Проверь что файлы скопировались

- git status src/mapify_cli/templates/

-

- # 5. Закоммить вместе с остальными изменениями

- git add src/mapify_cli/templates/

- ```

-

- ### Автоматическая проверка

-

- Проверка синхронизации через pytest (запускается в CI):

-

- ```bash

- # Запуск тестов синхронизации

- pytest tests/test_template_sync.py -v

-

- # Тесты проверяют:

- # - Все файлы из .claude/agents/ существуют в templates/

- # - Нет orphaned файлов в templates/ без source

- # - Контент файлов идентичен

- # - Frontmatter не ссылается на удалённые файлы

- ```

-

- ## MAP Workflow Enforcement

-

- При работе с MAP Framework slash commands (`/map-efficient`, `/map-debug`, `/map-fast`):

-

- ### Обязательная последовательность агентов

-

- Для КАЖДОГО subtask:

-

- ```

- 1. Actor (implement)

- 2. Monitor (validate) → If invalid: return to Actor with feedback

- 3. Predictor (analyze impact) ← условно, для high-risk subtasks

- 4. Apply changes

- ```

-

- ### Learning is OPTIONAL via /map-learn

-

- Reflector и Curator теперь вызываются ТОЛЬКО через отдельную команду `/map-learn`:

-

- ✅ **НОВЫЙ ПОДХОД**:

- - Workflows (map-efficient, map-debug, map-fast) НЕ включают автоматический learning

- - После завершения workflow предлагай пользователю: "Если хотите сохранить паттерны — запустите `/map-learn`"

- - `/map-learn` вызывает Reflector → Curator → mem0 storage

-

- ❌ **Не добавляй learning в workflows**:

- - Не вызывай Reflector/Curator автоматически в map-efficient, map-debug

- - Не делай работу Reflector/Curator самостоятельно

-

- ### Когда рекомендовать /map-learn

-

- Предлагай `/map-learn` если:

- - Были найдены новые паттерны решения

- - Debugging выявил нестандартные проблемы

- - Несколько итераций Actor→Monitor (>3)

-

- ## Pattern Storage Rules

-

- **CRITICAL: How to Store Patterns (v4.0+)**

-

- ✅ **CORRECT WAY (via Curator agent)**:

- 1. Call `Task(subagent_type="curator", ...)`

- 2. Curator calls `mcp__mem0__map_add_pattern` for new patterns

- 3. Curator calls `mcp__mem0__map_archive_pattern` for deprecated patterns

-

- ❌ **NEVER DO THIS**:

- - ❌ Directly calling mem0 tools without Curator review

- - ❌ Manually creating patterns without deduplication check

-

- **Why**:

- - Curator validates quality, checks duplicates via tiered search

- - Fingerprint-based deduplication prevents duplicates

- - Tiered storage (branch/project/org) keeps patterns organized

-

- ## Template Variable Protection

-

- **НИКОГДА не удаляй** template variables из agent files:

- - `{{language}}`

- - `{{#if existing_patterns}}...{{/if}}`

- - `{{feedback}}`

- - `{{code}}`

- - и т.д.

-

- Эти переменные критичны для orchestration. Git hook `.claude/hooks/pre-commit.sh` проверяет их наличие.

-

- ## Documentation Updates

-

- При изменении функциональности обновляй:

- 1. **USAGE.md** - примеры использования, best practices

- 2. **README.md** - quick reference

- 3. **ARCHITECTURE.md** - технические детали (если меняется архитектура)

-

- ## Testing

-

- Перед коммитом:

-

- ```bash

- # Запусти все тесты

- pytest

-

- # Проверь новую функциональность вручную

- mapify --help

- mapify validate graph tests/fixtures/valid_graph.json

- ```

-

- ## Commit Messages

- Используй conventional commits:

- ```

- feat: add new feature

- fix: bug fix

- docs: documentation update

- refactor: code refactoring

- test: add tests

- chore: maintenance

- ```

- Для больших изменений добавляй детальное описание в body коммита.