Подключение существующего проекта

English version: 02-existing-project-adopt.md. Этот файл — русский дубликат; обновляется вместе с 02-existing-project-adopt.md.

Подключение ничего не перестраивает. Binnacle сначала читает уже существующие соглашения, документы и tracker, затем добавляет только недостающее и без вашего «да» ничего не перемещает и не переписывает. Никакого автоматического масштабного переписывания.

Быстрый путь

1. binn audit — находки только на чтение; он ничего не пишет.
2. binn init — тот же один план, что и для нового проекта, с одним подтверждением.
3. /binnacle:roadmap — эпики, предложенные по коду, истории и документам.
4. /binnacle:product — первая Product-сессия.

Команды binn adopt нет: аудит читает, binn init пишет, навык roadmap планирует.

1. Аудит

binn audit [path] читает Git-репозиторий, содержащий путь, по умолчанию рабочий каталог, и печатает находки, текстом или с --json. Он ничего не пишет, не требует ни демона, ни регистрации, не ходит в сеть и не запускает ничего, кроме Git. Пробелы не делают его неуспешным: ненулевой код выхода бывает, только если аудит не смог отработать.

В Claude Code /binnacle:audit [path] запускает его из чата и показывает сначала план миграции, затем пробелы и то, о чём аудит не может судить, по областям, и в конце число ok. Правила — в его спеке, docs/specs/audit-and-adopt/spec.md.

У каждой находки есть код, область, статус (ok, gap или unknown), признак того, закрывает ли её binn init, и причина; у пробела и неизвестного есть ещё рекомендация. Общей оценки нет. Области, в том порядке, в каком он их печатает:

Область	Что она читает
git-and-tracker	репозиторий и его ветку; .binnacle/project.yaml; tracker, который называет remote, и есть ли для него токен; extensions.worktreeconfig, включённый без config.worktree, который бы им пользовался: с ним Antigravity не открывает репозиторий
docs	CONTEXT.md, docs/adr, docs/; roadmap и то, в формате ли он Binnacle; затерявшиеся документы
matt-pocock-layout	соглашения планирования в docs/agents/, каталоги спек и раздел заголовка тикета
scratch	игнорирует ли Git .scratch и нет ли там спеки или тикета в единственном экземпляре
capabilities	выглядят ли настроенными Serena, Graphify и Context7; навыки Binnacle другой версии, чем binn
instructions	AGENTS.md и CLAUDE.md и составляют ли они один набор инструкций
structure	наличие тестов, конфигурации CI и форму проекта
telemetry	сессии Claude Code и Codex для этого репозитория; экспортирует ли каждый найденный harness OpenTelemetry в Binnacle
docker	каждый отслеживаемый Dockerfile, Containerfile или compose-файл и исключены ли .env и .git в .dockerignore рядом с ним или в собственном <Dockerfile>.dockerignore у Dockerfile; проект без них просто не использует контейнеры, и это не пробел
secrets	каждый отслеживаемый текстовый файл, на известные форматы токенов (GitHub, GitLab, AWS, npm, Slack, Anthropic, OpenAI, Google и закрытый ключ PEM); каждое совпадение названо путём, строкой и видом, но не значением; каждый отслеживаемый .env или .env.<суффикс>, кроме .env.example, .env.sample и .env.template; бинарные файлы и файлы больше 1 МиБ пропускаются, и заглушить совпадение нельзя
security	отслеживаемый lockfile для каждого манифеста пакетов, в его каталоге или выше (npm, pnpm, Yarn, Bun, Cargo, Go, Poetry, uv, Pipenv, Bundler, Composer); у проекта без манифеста этой находки нет; конфигурацию Dependabot или Renovate; SECURITY.md в корне, в .github/ или в docs/

Работает ли токен tracker, видно только по сети, поэтому аудит оставляет это неизвестным; binn init читает tracker один раз и говорит. Для каждого недостающего файла Binnacle, например манифеста, roadmap или файла соглашений, аудит рекомендует запустить binn init.

Секрет, найденный аудитом, остаётся в истории Git и после удаления строки: уберите его, перевыпустите ключ и сами решите, переписывать ли историю, если коммит был запушен. Аудит читает только отслеживаемые файлы в их текущем виде; историю проверяет gitleaks.

Затерявшийся документ — это отслеживаемый план, спека, решение, TODO, заметки, backlog, дизайн, RFC, PRD, roadmap или ADR вне мест Binnacle. Аудит только перечисляет их, как docs.stranded; /binnacle:roadmap предлагает, куда поместить каждый.

Текст начинается с того, что делать, на вашем языке: по-русски, когда LC_ALL, а если она не задана, то LANG, начинается с ru, иначе по-английски. Сначала одна строка итогов, затем план перехода, затем пробелы и неизвестное по областям, у каждой находки — причина и рекомендация, и в конце находки ok, по строке на каждую. Кодов находок в тексте нет; их несёт --json, а причины и рекомендации в нём английские при любой локали.

План перехода раскладывает находки не в статусе ok по пронумерованным шагам; каждый шаг называет свои области и что сделать. В --json у каждого шага есть заголовок, коды его находок и что сделать.

1. Всё, что закрывает binn init: манифест, docs/ и заготовка roadmap, файлы соглашений Matt Pocock и раздел заголовка тикета, первый AGENTS.md, инструменты, которые он ставит, навыки Binnacle и экспорт телеметрии.
2. Секреты: все находки области secrets.
3. Дальше по шагу на область, в порядке таблицы: сначала пробелы, потом неизвестное.

Для области, где делать нечего, шага нет; если все находки в статусе ok, план говорит, что делать нечего. План — только совет: аудит ничего из него не выполняет. --json отдаёт его как plan, { "steps", "summary" }, рядом с root и findings, а поле init у каждой находки говорит, закрывает ли её binn init.

2. Настроить через binn init

binn init показывает один план и спрашивает один раз, как для нового проекта; из чата то же делает /binnacle:init (Из чата). В существующем проекте он добавляет только недостающее:

• Корректный манифест остаётся как есть. Манифест с проблемами называется и остаётся вам на исправление, и до тех пор проект не регистрируется.
• Язык документации предлагается по корневому README.md: русский, если кириллических букв вне блоков кода и встроенного кода больше, чем латинских, иначе английский. Новый манифест записывает ваш ответ как knowledge.language. Существующий манифест без него читается как английский, поэтому, если ваш ответ не английский, init печатает строку, которую нужно в него добавить, и ничего не пишет. Файлы, которые создаёт план, — заготовка роадмапа, файлы соглашений, раздел заголовка тикета и блок Agent skills — пишутся на языке документации, а слова, которые читает Binnacle, остаются английскими.
• Существующий roadmap никогда не переписывается. Не соответствующий формату Binnacle называется в Summary, а binn audit говорит, чего в нём не хватает.
• В существующий docs/agents/issue-tracker.md добавляется только недостающий раздел заголовка тикета. Блок Agent skills, уже имеющийся в AGENTS.md или CLAUDE.md, не трогается.
• Существующий JSON-файл никогда не переписывается: вместо этого печатается запись, которую нужно добавить.
• Инструмент, который уже есть в PATH или объявлен false в capabilities, не трогается.

План, пункт за пунктом

Что может содержать план, в его порядке. Большинство пунктов появляется, только когда чего-то не хватает; регистрация, пока демон запущен, и три набора навыков из пункта 5 планируются при каждом запуске. Запись вне репозитория говорит об этом в своём заголовке.

1. Манифест, для репозитория без него: id проекта, tracker из remote (GitHub, GitLab или локальные тикеты в docs/specs), пути к знаниям, workflow, найденные или устанавливаемые инструменты в capabilities, окно импорта и язык документации в knowledge.language.
2. Регистрация в запущенном демоне. При остановленном демоне init вместо этого называет binn daemon start и binn project register.
3. MCP-сервер binnacle в проектном файле каждого найденного harness: .mcp.json для Claude Code, .codex/config.toml для Codex, opencode.json для opencode, .vscode/mcp.json для VS Code. Файл, где binnacle уже назван, не трогается.
4. Плагин binnacle в Claude Code на уровне пользователя, из этого пакета Binnacle, если Claude Code его ещё не перечисляет и проект не даёт свой.
5. Навыки Binnacle, Matt Pocock Skills и Ponytail — в каждый harness, который находит CLI skills, на уровне пользователя, через npx skills, если найден хоть один harness. Затем каждый набор удаляется из Claude Code, где он есть как плагин, и из каждого --skip-harness <id>. Без npx команды печатаются.
6. Соглашения планирования, которые читают навыки планирования, чтобы никакой навык настройки не запускался перед ними: docs/agents/issue-tracker.md для найденного tracker, с заголовком тикета, Epic brief и спорными пунктами; triage-labels.md; domain.md. Затем блок Agent skills, который на них ссылается, в AGENTS.md или в CLAUDE.md, если есть только он.
7. Раскладка: каталог задач, который читает локальный tracker, и заготовка <knowledge.docs>/roadmap.md в формате Binnacle, чьё Next action — /binnacle:roadmap.
8. Инструменты: Matt Pocock Skills и Ponytail как плагины Claude Code на уровне пользователя, если Claude Code их ещё не перечисляет; Serena и Graphify через uv tool install; ast-grep через npm. Без uv init называет команду, которая его ставит, и оставляет Serena и Graphify вне плана; без npm — Context7 и ast-grep.
9. MCP-серверы инструментов: Serena, Context7 и Graphify регистрируются в каждом найденном harness через его собственный CLI и никогда в репозитории. Graphify обслуживает один проект, поэтому попадает в локальный scope Claude Code, а для остальных его запись печатается.
10. Экспорт OpenTelemetry Claude Code, Codex и Gemini CLI, направленный на адрес демона в их пользовательских настройках (ниже).
11. graphify-out/ в .gitignore, если Graphify найден или устанавливается, а Git его ещё не игнорирует.
12. Хранилище Obsidian, в которое демон проецирует Project Brain, в ~/.binnacle/settings.json, если Obsidian перечисляет ровно одно хранилище, а никакое ещё не задано. Если хранилищ нет или их несколько, init называет найденные и говорит, как задать путь.
13. Первый граф Graphify и его отчёт, только по коду, без API-ключа и без модели: graphify extract . --code-only --allow-dedup-shrink, затем graphify cluster-only . --no-label. Неудача попадает в Summary, а демон построит их позже.
14. Автозапуск, после «да» на его вопрос: binn daemon autostart on.

Уже зарегистрированные MCP-серверы

Сервер, уже зарегистрированный в harness в любом scope, который читает аудит, остаётся как есть. Исключение — Serena в пользовательском файле Codex с контекстом Claude Code: план регистрирует её заново с контекстом Codex. Там, где у harness нет команды для добавления сервера, как у opencode, или его CLI нет в PATH, init печатает запись, которую нужно добавить самому.

Экспорт OpenTelemetry

Экспорт идёт как JSON поверх HTTP, с выключенным логированием промптов, в пользовательских настройках каждого harness:

Harness	Где
Claude Code	env в его настройках
Codex	таблица [otel] в ~/.codex/config.toml
Gemini CLI	блок telemetry в ~/.gemini/settings.json

Уже настроенный экспорт, в Binnacle или куда-то ещё, не трогается и называется. Найденный harness, который не умеет экспортировать, например opencode, называется в Summary с причиной. binn audit сообщает для каждого найденного harness, экспортирует ли он в Binnacle.

3. Roadmap по коду

Запустите /binnacle:roadmap. Демон ему не нужен, а вход для существующего проекта он выбирает, когда Git отслеживает исходный код или в истории есть коммиты помимо коммитов binn init; /binnacle:roadmap existing выбирает его в любом случае.

1. Он читает README, файлы инструкций, видение, документы, спеки со строками Status: их тикетов, git log и код, а также один раз binn audit --json.
2. Он предлагает эпики в порядке зависимостей, каждый со статусом done, in progress или not started, с тем, что этот статус показывает, и строкой объёма. Эпик, который описывает существующая спека, ссылается на неё и берёт статус из её тикетов.
3. Для каждого затерявшегося документа он предлагает одно место: спеку, ADR, CONTEXT.md, product inbox, roadmap или «устарел». Устаревший документ остаётся на месте, если вы не скажете его удалить.
4. Roadmap не в формате Binnacle предлагается переписать в этот формат с сохранением содержимого.
5. Он показывает каждое изменение и коммит и ждёт. По вашему «да» он пишет и перемещает, проверяет, что docs.roadmap в аудите — ok, и коммитит только то, что записал. Он никогда не пушит.

Next action, которое он записывает, грилит первый не завершённый эпик. При повторном запуске он предлагает дополнения и перестановки среди не начатых эпиков, никогда не меняет эпик done и никогда не удаляет строку со ссылкой на спеку. Затем /binnacle:product начинает первую Product-сессию.

Историческая telemetry

Окно импорта, о котором спрашивает binn init, — это сколько истории сессий harness импортирует демон, telemetry.import.window_days в манифесте. Сессия, которую нельзя точно привязать к задаче, сохраняется как сессия проекта, без привязки, и не угадывается.