agentic

Разворачивает в проекте структуру для работы с агентами: директория agentic/ со skills, agents, hooks, корневой AGENTS.md, симлинки .claude и CLAUDE.md.

Контент лежит в открытой директории; инструменто-специфичные пути — симлинки. Новый агент = ещё один симлинк, файлы не перекладываем.

Установка

npm i -D @rudevich/agentic-flow
npx @rudevich/agentic-flow init

Установка ничего не меняет в вашем package.json — postinstall только печатает, какую команду запустить. Всё создаётся на npx @rudevich/agentic-flow init. Дальше — «Флоу пользователя» ниже.

Из локальной копии или из git, если нужна неопубликованная версия:

npm i -D file:../agentic-flow
npm i -D git+ssh://[email protected]/rudevich/agentic-flow.git

Что создаёт agentic-flow init

project/
├── agentic/
│   ├── skills/   spec, plan, jira, confluence, figma (+ ваши)
│   ├── agents/   reader, part-reader, specificator, planner
│   ├── hooks/
│   ├── tasks/    одна директория на тикет
│   └── settings.json   порог ответа MCP (MAX_MCP_OUTPUT_TOKENS)
├── .claude   -> agentic
├── AGENTS.md
└── CLAUDE.md -> AGENTS.md

Больше ничего: ни .mcp.json, ни файлов с токенами — доступами пакет не распоряжается.

Флоу пользователя

От пустого проекта до первой спецификации.

1. Поставить пакет

npm i -D @rudevich/agentic-flow

2. Развернуть структуру

npx @rudevich/agentic-flow init

Директории, AGENTS.md, симлинки — и сразу скан MCP: что нашлось, разложено по ролям; чего не нашлось, про то напечатана инструкция.

Порядок имеет значение. Связка «сервер → роль → tools: ридера» собирается в момент запуска, а не на лету.

Если в проекте уже есть .claude/ — а он есть почти везде, где работают с Claude Code — симлинк не создаётся: чужую директорию пакет не трогает. Скиллы тогда не видны и /spec не существует. init скажет об этом последним блоком и предложит два выхода: перенести содержимое в agentic/ и перезапустить init, либо оставить .claude и подложить части:

ln -s ../agentic/skills .claude/skills
ln -s ../agentic/agents .claude/agents
ln -s ../agentic/hooks .claude/hooks

3. Описать проект

В AGENTS.md три места под HTML-комментариями ждут вас: Overview, Commands, Conventions. Можно поручить своему агенту — он читает этот же файл.

Блоки под маркерами doc-language и mcp-roles не трогайте: их перегенерирует config.

4. Подключить MCP

Серверы уже были — глобально, в плагине или в проектном .mcp.json. init их нашёл и связал, проверяется двумя строками:

grep '^tools:' agentic/agents/reader.md   # содержит mcp__<server>
sed -n '/mcp-roles/,/^$/p' AGENTS.md            # роли заполнены

Серверов не было — init напечатал, какие имена закрывают какую роль. Подключаете и пересканируете:

claude mcp add --transport http atlassian https://<host>/mcp
npx @rudevich/agentic-flow config

Пропустить config нельзя: без него /spec запустится и остановится — у ридера нет инструмента на роль tracker, а содержимое тикета не выдумывается. Остальные роли не блокируют: источник помечается unavailable, а пробел уезжает в Missing in sources.

Скану видны пять мест: проектный .mcp.json, ~/.claude.json (глобальные и привязанные к проекту), ~/.claude/settings*.json, .mcp.json включённых плагинов и плагины, поставленные десктопным приложением (они лежат вне ~/.claude). Коннектор, живущий где-то ещё, не увидится — роль останется пустой, хотя сервер у вас есть.

Сервер из плагина попадает в таблицу под своим полным идентификатором — plugin:product-management:figma. Найденный сервер ещё не значит авторизованный: OAuth-коннектор надо один раз подтвердить через /mcp в интерактивной сессии, иначе инструменты вернут ошибку доступа.

5. Перезапустить сессию

Скиллы и агенты появились на диске только что — уже открытый Claude Code может их не видеть.

6. Взять задачу

/spec https://company.atlassian.net/browse/PROJ-123

Что происходит дальше — раздел «Флоу задачи».

7. Обновлять пакет

npm i -D @rudevich/agentic-flow@latest && npx @rudevich/agentic-flow init

Именно i … @latest, а не npm update: update не выходит за диапазон из package.json, а для нулевой мажорной версии ^0.1.5 означает >=0.1.5 <0.2.0 — до 0.2.0 он не дойдёт и ничего об этом не скажет.

init умеет доводить до новой версии то, что писал сам. По каждому файлу он сравнивает содержимое с хешем из манифеста:

| Файл | Что будет | | --- | --- | | не трогали | updated — перезапишется новой версией | | правили, новой версии нет | skip (your version), молча | | правили, и версия новее | предупреждение, файл не тронут | | удалили | вернётся | | пакет его больше не поставляет, не трогали | removed — вместе с опустевшей директорией | | пакет его больше не поставляет, правили | предупреждение, файл не тронут |

Правки не теряются никогда. Если хотите новую версию вместо своей — удалите файл и запустите init.

Последние две строки — про переименованные и снятые с поставки скиллы. Без них старый SKILL.md остался бы в проекте навсегда, и Claude Code грузил бы его рядом с тем, который пришёл на замену.

В конце init печатает, с какой версии на какую вы переехали, и просит перезапустить сессию: скиллы и агенты читаются при её старте, поэтому до перезапуска обновлённые файлы ничего не меняют.

Флоу задачи

/spec https://company.atlassian.net/browse/PROJ-123
#   → requirements.md + sources/, стоп
#   человек читает, задаёт вопросы аналитику и дизайнеру
/plan PROJ-123
#   → subtasks.md: подзадачи по 2–8 часов, каждая привязана к требованию
#     и с приоритетом — меньше число раньше, одинаковое можно параллельно
/design PROJ-123
#   → design/: макеты по ссылкам из requirements.md, когда они понадобятся

Повторный /spec по тому же тикету перечитывает задачу с нуля: удаляет requirements.md, subtasks.md и sources/ и читает всё заново. Ничего не сливается, поэтому вопрос, на который аналитик ответил правкой в Confluence, просто перестаёт задаваться. Папку design/ он не трогает.

Вызов /plan — и есть сигнал, что спецификацию приняли: пока это делает человек. Незакрытые Open questions не блокируют, но планировщик их покажет и спросит, декомпозировать ли всё равно.

На входе полный URL тикета — ничего настраивать не нужно, адрес сайта агент берёт из самой ссылки. Дальше он идёт только по ссылкам, которые нашёл: адреса не собирает и страницы по названию не ищет.

По сабагенту на ссылку

Каждую страницу забирает свой сабагент reader — один на ссылку, все сразу. Наружу он отдаёт строк двадцать: куда положил снимок, какие факты нашёл (каждый с якорем вроде §2.1) и какие ссылки на странице. Сама страница остаётся внутри сабагента.

Это и делает возможным тикет с четырьмя конфлюенсами и двумя макетами. Без этого один только сырой ответ MCP забил бы контекст раньше, чем будет написано первое требование.

Лимит — пять ссылок на источник за круг. Всё сверх попадает в Sources строкой not read (over the limit) и в Missing in sources. Тикет-помойка даёт короткую спецификацию, а не захлебнувшийся прогон.

Большая страница

Одна страница тоже может не влезть в ридера: сырой ответ MCP плюс снимок, который ридер сам пишет, — это примерно два размера страницы.

init кладёт порог в agentic/settings.json:

{ "env": { "MAX_MCP_OUTPUT_TOKENS": "4000" } }

Ответ MCP больше порога Claude Code не кладёт в контекст: сохраняет в файл и отдаёт путь. По тому, как пришёл ответ, ридер и узнаёт вес страницы — второго запроса не нужно:

| Что ответил MCP | Стратегия | Что делает ридер | | --- | --- | --- | | страницу целиком | inline | как обычно | | «сохранено в файл», одна часть | whole file | читает файл сам, одним Read с limit | | «сохранено в файл», частей больше | parts | по сабагенту part-reader на часть, по 3 за раз |

Часть — ~12 КБ или 150 строк, частей не больше восьми. Каждая пишется в свой <slug>.part-N.md, а <slug>.md становится оглавлением. Что не влезло в восемь частей, попадает в Sources как partial и в Missing in sources. В дайджесте ридера строка strategy: показывает, какой путь он выбрал.

Порог и размер части рассчитаны на окно ~32k. Окно больше — поднимите MAX_MCP_OUTPUT_TOKENS и числа в agentic/agents/reader.md (после правки init перестанет обновлять этот файл).

Был свой agentic/settings.json — init его не трогает, а печатает warning со строкой, которую нужно добавить.

Не решено: если MCP-сервер отдаёт страницу JSON-ом, где всё тело — одна строка, резать по строкам нечего. Такая страница вернётся written: none с причиной lines too long to read. Лечится сервером, который умеет отдавать markdown.

Источники — отдельные скиллы

Читает не один монолит: spec только маршрутизирует, а каждый вид ссылки знает свой скилл — jira (тикет), confluence (аналитика), figma (макет). Поэтому ветку можно выключить:

/spec <ticket-url> --no-figma        # в макет не ходим
/spec <ticket-url> --no-confluence   # аналитика — описание тикета

Глубина фиксирована: тикет → аналитика → макет. Ссылки внутри макета не разворачиваются, один URL не читается дважды, нераспознанная ссылка не открывается — уезжает в Open questions.

Непрочитанный источник виден строкой в Sources: skipped (--no-figma), links only, unavailable — no docs server или «ссылки не было». Нет сервера для роли — прогон не падает: пишется то, что прочиталось, пробел уезжает в Missing in sources. Падаем только если недоступен трекер — тогда специфицировать нечего.

Макеты — отдельной командой

В ## Source скилла figma стоит fetch | no, поэтому /spec макеты не открывает. Найденные ссылки он складывает в раздел ## Design файла requirements.md — с пометкой, где каждая нашлась. В Sources строка links only, в Missing in sources — то, что макет мог бы ответить.

Читает макеты своя команда, когда они понадобятся:

/design PROJ-123      # → agentic/tasks/PROJ-123/design/checkout.md

/design берёт ссылки из ## Design, отдаёт их сабагенту designer, а тот пишет по файлу на макет. Это заготовка: сам способ вычитки ещё будем дорабатывать.

У ридера при этом нет инструментов Figma — их схемы не занимают его контекст. Инструменты Figma есть только у designer. init не просит подключать сервер для роли design, а в таблице ролей стоит — (links only).

Хотите читать макеты прямо в /spec — поменяйте поле и пересоберите:

# agentic/skills/figma/SKILL.md:   | fetch | no |   →   | fetch | yes |
npx @rudevich/agentic-flow config

После этой правки скилл считается вашим, и init перестанет его обновлять. Поле fetch есть у любого источника: no — ссылки только перечисляются.

Свой источник

Список источников не зашит: источник — это скилл с секцией ## Source. По ней spec маршрутизирует ссылки, а agentic-flow собирает таблицу ролей и allowlist ридера.

agentic-flow source add notion --role docs --matches notion.so,notion.site

## Source

| Field | Value |
| --- | --- |
| role | docs |
| matches | notion.so, notion.site |
| writes | sources/analytics |
| server | notion |
| auth | token |
| links | follow |

Роль — любая строка: заводите research или metrics, строка в таблице MCP roles появится сама. server — имена, по которым источник узнаёт свой сервер среди подключённых. auth: none — подключается не токеном (как Figma), и в инструкции будет отдельная пометка. links: stop — ссылки внутри не разворачиваются. Флаг --no-notion появляется сам, править spec не нужно.

Скилл написан руками — agentic-flow config подхватит его. Свои скиллы reset не удаляет: в манифест они не попадают.

Ни спецификатор, ни планировщик не пишут код — у них нет Edit и Bash. Каждое требование в requirements.md несёт ссылку на источник; чего в источниках нет — уезжает в Open questions и Missing in sources, а не додумывается. Каждая подзадача в subtasks.md ссылается на требования и укладывается в 2–8 часов работы миддла; что не привязалось или не делится — попадает в Gaps. В каждом файле задачи стоит полная ссылка на тикет.

Нет ссылки на аналитику? Спецификатор останавливается, не записав requirements.md, и спрашивает: считать ли описание тикета аналитикой. При согласии описание кладётся в sources/analytics/ дословно, а в Sources остаётся пометка, что это решение человека. С --no-confluence вопрос не задаётся — решение уже принято флагом, и в Sources стоит skipped by --no-confluence.

Доступы

init ничего не спрашивает. Он смотрит, что уже подключено (четыре места перечислены в шаге 4 выше), и раскладывает найденное по ролям:

[agentic] found MCP servers:
    plugin:product-management:atlassian  (plugin)  -> tracker, docs

Чего не нашлось — про то печатается инструкция:

[agentic] no MCP server for: docs
[agentic] connect one, then run `npx @rudevich/agentic-flow config`:
[agentic]   claude mcp add --transport http <name> https://<host>/mcp
[agentic]   or add it to .mcp.json in this project, or authorise a connector with /mcp
[agentic] which server names fill which role, from the skills' ## Source blocks:
[agentic]   docs  <- confluence, atlassian   agentic/skills/confluence/SKILL.md

Про источник с fetch | no (по умолчанию это figma) подсказки нет: его никто не читает, и сервер ему не нужен.

Подключили сервер — agentic-flow config пересобирает таблицу ролей и tools: ридера. Токены пакет не спрашивает, не хранит и не пишет: где им лежать, решает ваш MCP-клиент.

Роли вместо имён серверов

Скиллы называются по сервисам, но инструмент берут по роли: tracker (тикет), docs (аналитика), design (макет) плюс всё, что вы завели, — имён серверов агенты не знают. Сопоставление живёт в AGENTS.md под маркером <!-- agentic:mcp-roles -->, а строка tools: у ридера генерируется из найденных имён. Поэтому одинаково работают и jira + confluence, и один atlassian на обе роли, и plugin:product-management:atlassian.

Какое имя сервера к какой роли относится, говорит поле server в ## Source — поэтому atlassian на две роли и plugin:product-management:atlassian работают без правок в коде. Поменялось окружение — agentic-flow config пересоберёт и таблицу ролей, и allowlist.

Figma токеном не подключается (нужна, только если включить fetch | yes). Варианты: Dev Mode MCP в десктопном приложении Figma или OAuth-коннектор через /mcp — об этом и говорит auth: none в её объявлении. Как только сервер появится, agentic-flow config подхватит его в роль design.

Язык документов

По умолчанию агенты пишут документы на языке запроса. Английский — флагом:

npx @rudevich/agentic-flow init --lang english
agentic-flow config --lang english     # поменять потом

Выбор живёт одной строкой в AGENTS.md под маркером <!-- agentic:doc-language -->. Уже сделанный выбор init не трогает: строка меняется только когда передан --lang.

Начать сначала

agentic-flow reset --dry-run   # что будет удалено
agentic-flow reset             # снимает scaffold, спрашивает подтверждение
agentic-flow reset --all       # плюс agentic/ целиком, включая ваш контент
agentic-flow reset --secrets   # плюс .env.agentic, если вы его завели сами
agentic-flow reset --force     # удаляет и изменённое после init

Удаляется только то, что записано в agentic/.agentic-manifest.json. Ваши скиллы и задачи не трогаются, изменённые файлы сохраняются, директории сносятся только пустыми, а в грязном git-дереве команда отказывается работать без --force.

Идемпотентно: создаётся только недостающее. Существующие AGENTS.md, CLAUDE.md, .claude не перезаписываются — предупреждение + что сделать руками.

Опции init

| Опция | Что делает | | --- | --- | | --dry-run | печатает план, на диск не пишет | | --force | пересоздаёт симлинк с неверным target; реальные файлы не трогает | | --lang | english или request — язык генерируемых документов |

Симлинки и git

• Коммитятся как режим 120000, работают на macOS и Linux.
• Клон на Windows без core.symlinks=true → обычные текстовые файлы.
• Windows: .claude создаётся как junction (без прав администратора). Если симлинк CLAUDE.md создать нельзя — копия AGENTS.md + предупреждение.
• Не добавляйте .claude в .gitignore. init предупредит, если найдёт.
• .claude уже существует как реальная директория или файл — init её не трогает и печатает, что делать. Пока это не решено, Claude Code не видит ни скиллов, ни агентов.

Цвет

Вывод раскрашивается, когда его читает человек. NO_COLOR=1, TERM=dumb и любой пайп выключают цвет; FORCE_COLOR=1 включает принудительно.

Требования

Node 24 или новее, зависимостей нет.

Более старые версии не поддерживаются: CLI проверяет версию сам и отказывается работать, потому что engines в package.json заставляет npm только предупредить, а npx не смотрит и туда.

[agentic] needs Node 24 or newer — this is 20.11.1

Если вы на более старой версии — nvm install 24 && nvm use 24, либо оставайтесь на @rudevich/[email protected]: та версия работала на Node >= 18.