beadloom 0.1.0__tar.gz

beadloom-0.1.0/.beadloom/_graph/services.yml

@@ -0,0 +1,67 @@
+nodes:
+  - ref_id: beadloom
+    kind: service
+    summary: "Beadloom CLI + MCP server — Context Oracle + Doc Sync Engine"
+    source: src/beadloom/
+    docs:
+      - docs/architecture.md
+      - docs/getting-started.md
+
+  - ref_id: context-oracle
+    kind: domain
+    summary: "Context bundle building via BFS graph traversal"
+    docs:
+      - docs/context-oracle.md
+
+  - ref_id: doc-sync
+    kind: domain
+    summary: "Doc-code synchronization tracking and stale detection"
+    docs:
+      - docs/sync-engine.md
+
+  - ref_id: mcp-server
+    kind: service
+    summary: "MCP stdio server with 5 tools for AI agents"
+    docs:
+      - docs/mcp-server.md
+
+  - ref_id: cli
+    kind: service
+    summary: "Click-based CLI with 11 commands"
+    docs:
+      - docs/cli-reference.md
+
+  - ref_id: graph-format
+    kind: domain
+    summary: "YAML graph format specification and loader"
+    docs:
+      - docs/graph-format.md
+
+edges:
+  - src: context-oracle
+    dst: beadloom
+    kind: part_of
+  - src: doc-sync
+    dst: beadloom
+    kind: part_of
+  - src: mcp-server
+    dst: beadloom
+    kind: part_of
+  - src: cli
+    dst: beadloom
+    kind: part_of
+  - src: graph-format
+    dst: beadloom
+    kind: part_of
+  - src: mcp-server
+    dst: context-oracle
+    kind: uses
+  - src: cli
+    dst: context-oracle
+    kind: uses
+  - src: cli
+    dst: doc-sync
+    kind: uses
+  - src: cli
+    dst: graph-format
+    kind: uses

beadloom-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,274 @@
+# CLAUDE.md — Ядро мультиагентной разработки
+
+> **Версия:** 3.0 (Optimized)
+> **Интеграция:** steveyegge/beads CLI
+> **Skills:** `/epic-init`, `/dev`, `/review`, `/test`, `/coordinator`, `/templates`, `/checkpoint`
+
+---
+
+## 0. КРИТИЧЕСКИЕ ПРАВИЛА
+
+> **ЧИТАТЬ ПЕРВЫМ. ВЫПОЛНЯТЬ ВСЕГДА.**
+
+### ПЕРЕД любой работой
+
+```bash
+# 1. Проверить доступные задачи
+bd ready
+
+# 2. Взять задачу
+bd update <bead-id> --status in_progress --claim
+
+# 3. Прочитать контекст
+# .claude/development/docs/features/{ISSUE-KEY}/CONTEXT.md
+# .claude/development/docs/features/{ISSUE-KEY}/ACTIVE.md
+
+# 4. Подтвердить пользователю понимание состояния
+```
+
+### ВО ВРЕМЯ работы
+
+```bash
+# Checkpoint каждые 30 мин или 5 шагов
+bd comments add <bead-id> "CHECKPOINT: [что сделано]"
+
+# Обновлять ACTIVE.md после каждого значимого действия
+```
+
+### ПРИ ЗАВЕРШЕНИИ bead
+
+```bash
+# 1. Тесты проходят
+uv run pytest
+
+# 2. Финальный checkpoint
+bd comments add <bead-id> "ЗАВЕРШЕНО: [результаты]"
+
+# 3. Закрыть bead
+bd close <bead-id>
+```
+
+---
+
+## 0.1 Проект: Beadloom
+
+- **Стек:** Python 3.10+, SQLite (WAL), Click + Rich (CLI), tree-sitter, MCP (stdio)
+- **Дистрибуция:** PyPI (`uv tool install beadloom`)
+- **Тесты:** pytest + pytest-cov (≥80% покрытие)
+- **Линтер/форматтер:** ruff (lint + format)
+- **Типизация:** mypy --strict
+- **Документация проекта:** `.claude/development/PRD.md`, `.claude/development/RFC.md`
+- **Фазы:** 0-Onboarding → 1-Context Oracle → 2-MCP → 3-Doc Sync → 4-Polish
+
+---
+
+## 1. Skills — Динамическая загрузка
+
+| Ситуация | Команда | Описание |
+|----------|---------|----------|
+| Новый эпик/фича | `/epic-init` | Сетап, стандарты, согласование |
+| Разработка кода | `/dev` | TDD, паттерны, workflow |
+| Code review | `/review` | Чеклисты качества |
+| Написание тестов | `/test` | AAA pattern, покрытие |
+| Параллельная работа | `/coordinator` | Распределение, синхронизация |
+| Нужны шаблоны | `/templates` | PRD, RFC, CONTEXT, PLAN |
+| Создать checkpoint | `/checkpoint` | Формат, правила |
+
+**Правило:** Вызывай skill когда нужна детальная инструкция.
+
+---
+
+## 2. Beads CLI — Essentials
+
+```bash
+# Доступные задачи (без блокеров)
+bd ready
+
+# Все задачи
+bd list
+
+# Детали + история
+bd show <id>
+bd comments <id>
+
+# Взять задачу
+bd update <id> --status in_progress --claim
+
+# Добавить checkpoint (НЕ перетирает описание)
+bd comments add <id> "текст checkpoint"
+
+# Закрыть задачу
+bd close <id>
+
+# Граф зависимостей
+bd graph --all
+
+# Добавить зависимость
+bd dep add <id> <depends-on-id>
+```
+
+**ВАЖНО:**
+- `bd comments add` — для checkpoints (сохраняет историю)
+- `bd update --append-notes` — для заметок
+- НИКОГДА не работай над задачей без `--claim`
+- ВСЕГДА закрывай через `bd close`
+
+---
+
+## 3. Файловая память (защита от автокомпакта)
+
+```
+.claude/development/docs/features/{ISSUE-KEY}/
+├── CONTEXT.md   ← ЯДРО: состояние, решения, стандарты
+├── ACTIVE.md    ← ФОКУС: текущая работа, прогресс
+├── RFC.md       ← АРХИТЕКТУРА: техническое решение
+├── PLAN.md      ← DAG: beads и зависимости
+└── PRD.md       ← ТРЕБОВАНИЯ: бизнес-цели
+```
+
+| Приоритет | Файл | Когда читать |
+|-----------|------|--------------|
+| **P0** | CONTEXT.md | Всегда в начале |
+| **P0** | ACTIVE.md | Всегда в начале |
+| **P1** | beads comments | При возобновлении работы |
+
+**Правило:** НИКОГДА не полагаться на "память" из чата. Читать файлы!
+
+---
+
+## 4. Роли агентов
+
+| Роль | Skill | Когда использовать |
+|------|-------|-------------------|
+| **Разработчик** | `/dev` | Реализация beads |
+| **Ревьювер** | `/review` | Проверка качества |
+| **Тестировщик** | `/test` | Написание тестов |
+| **Координатор** | `/coordinator` | Мультиагентная работа |
+
+### Один агент
+Используй `/dev` для разработки, `/checkpoint` для сохранения прогресса.
+
+### Мультиагентный режим
+Координатор использует `/coordinator` для распределения.
+Субагенты используют соответствующие роли.
+
+---
+
+## 5. DAG и приоритеты
+
+| Приоритет | Описание | Правило |
+|-----------|----------|---------|
+| **P0** | Critical, блокирует другие | Выполнять первым |
+| **P1** | High, важно | После P0 |
+| **P2** | Medium, улучшения | Когда есть время |
+| **P3** | Low, nice-to-have | В последнюю очередь |
+
+**Правила:**
+- Брать только из `bd ready`
+- НЕ брать bead с невыполненными зависимостями
+- НЕ брать P2/P3 пока есть P0/P1
+
+---
+
+## 6. Git
+
+```
+Формат коммитов:
+[{ISSUE-KEY}] <type>: <описание на русском>
+
+Типы: feat, fix, refactor, docs, test, chore
+
+Пример:
+[MCP-001] feat: добавлен health endpoint
+```
+
+---
+
+## 7. Антипаттерны (НИКОГДА)
+
+### Планирование
+- Начинать без согласованного плана
+- Брать bead с незавершёнными зависимостями
+- Менять DAG без уведомления пользователя
+
+### Работа
+- Начинать без чтения CONTEXT.md
+- Полагаться на память чата
+- Работать над несколькими beads одновременно
+- Игнорировать checkpoints
+
+### Завершение
+- Завершать bead без `bd comments add`
+- Завершать без `bd close`
+- Коммитить с падающими тестами
+
+### Код
+- Использовать `Any` / `# type: ignore` без причины
+- Оставлять `print()` / `breakpoint()`
+- Писать код без теста (нарушение TDD)
+- Голый `except:` без указания типа исключения
+- `import *`
+- Мутабельные аргументы по умолчанию (`def f(x=[]):`)
+
+---
+
+## 8. Quick Reference
+
+### Старт сессии
+```bash
+bd ready
+bd update <id> --status in_progress --claim
+# Читать CONTEXT.md, ACTIVE.md
+# Подтвердить пользователю
+```
+
+### Во время работы
+```bash
+# Каждые 30 мин
+bd comments add <id> "CHECKPOINT: ..."
+# Обновить ACTIVE.md
+```
+
+### Завершение bead
+```bash
+uv run pytest
+bd comments add <id> "ЗАВЕРШЕНО: ..."
+bd close <id>
+bd ready  # что разблокировалось?
+```
+
+### Новый эпик
+```
+/epic-init
+```
+
+### Нужны шаблоны
+```
+/templates
+```
+
+---
+
+## 9. Чеклист агента
+
+### При старте
+- [ ] `bd ready` → выбрал задачу
+- [ ] `bd update <id> --status in_progress --claim`
+- [ ] Прочитал CONTEXT.md и ACTIVE.md
+- [ ] Подтвердил понимание пользователю
+
+### Во время работы
+- [ ] Обновляю ACTIVE.md
+- [ ] Checkpoint в beads каждые 30 мин
+- [ ] Следую TDD (если код)
+
+### При завершении
+- [ ] Тесты проходят
+- [ ] `bd comments add` — финальный checkpoint
+- [ ] `bd close <id>`
+- [ ] ACTIVE.md очищен
+
+---
+
+> **Нужна детальная инструкция?** Вызови соответствующий skill:
+> `/epic-init` | `/dev` | `/review` | `/test` | `/coordinator` | `/templates` | `/checkpoint`

beadloom-0.1.0/.claude/commands/checkpoint.md

@@ -0,0 +1,182 @@
+# /checkpoint — Создание чекпоинта
+
+> **Вызывать:** каждые 30 мин, после 5 шагов, при завершении bead
+> **Цель:** защита от автокомпакта, сохранение прогресса
+
+---
+
+## Когда создавать checkpoint
+
+| Триггер | Обязательность |
+|---------|----------------|
+| Завершён bead | **ОБЯЗАТЕЛЬНО** |
+| Выполнено 5+ шагов | ОБЯЗАТЕЛЬНО |
+| Прошло 30+ минут | ОБЯЗАТЕЛЬНО |
+| Перед переключением задачи | ОБЯЗАТЕЛЬНО |
+| Принято архитектурное решение | Рекомендуется |
+| Обнаружена проблема | Рекомендуется |
+
+---
+
+## Checkpoint в beads (основной способ)
+
+```bash
+bd comments add <bead-id> "$(cat <<'EOF'
+═══ CHECKPOINT: YYYY-MM-DD HH:MM ═══
+
+ВЫПОЛНЕНО:
+- Шаг 1
+- Шаг 2
+- Шаг 3
+
+РЕШЕНИЯ:
+- Решение X: причина Y
+
+ИЗМЕНЁННЫЕ ФАЙЛЫ:
+- src/path/file1.py — что изменено
+- src/path/file2.py — что изменено
+
+СЛЕДУЮЩИЕ ШАГИ:
+1. Шаг A
+2. Шаг B
+
+БЛОКЕРЫ: [нет | описание]
+EOF
+)"
+```
+
+---
+
+## Checkpoint при завершении bead
+
+```bash
+bd comments add <bead-id> "$(cat <<'EOF'
+═══ BEAD ЗАВЕРШЁН: YYYY-MM-DD HH:MM ═══
+
+ЧТО СДЕЛАНО:
+- Пункт 1
+- Пункт 2
+- Пункт 3
+
+РЕШЕНИЯ В ПРОЦЕССЕ:
+- Решение X: причина Y
+- Решение Z: причина W
+
+ИЗВЕСТНЫЕ ОГРАНИЧЕНИЯ/TODO:
+- TODO 1
+- Ограничение 1
+
+ТЕСТЫ:
+- Unit: XX passed
+- Integration: XX passed
+- Покрытие: XX%
+
+ФАЙЛЫ:
+- src/new-file.py — новый модуль
+- src/updated.py — обновлён
+EOF
+)"
+
+# Затем закрыть
+bd close <bead-id>
+```
+
+---
+
+## Обновление ACTIVE.md
+
+Параллельно с beads checkpoint, обновить ACTIVE.md:
+
+```markdown
+## Заметки по ходу работы
+
+### [HH:MM] CHECKPOINT
+**Выполнено:**
+- Шаг 1
+- Шаг 2
+
+**Решения:**
+- Решение X
+
+**Следующие шаги:**
+1. Шаг A
+2. Шаг B
+```
+
+---
+
+## Checkpoint в чат (для пользователя)
+
+```
+═══════════════════════════════════════════════════════
+CHECKPOINT: {ISSUE-KEY} | BEAD-XX | YYYY-MM-DD HH:MM
+═══════════════════════════════════════════════════════
+
+## Состояние
+- Фаза: Development
+- Bead: BEAD-XX (In Progress)
+
+## Выполнено
+1. [действие 1]
+2. [действие 2]
+
+## Ключевые решения
+- [решение]: [причина]
+
+## Изменённые файлы
+- `path/to/file.py` — [что]
+
+## Следующие шаги
+1. [шаг 1]
+2. [шаг 2]
+
+## Команда для продолжения
+"Продолжи работу над {ISSUE-KEY}"
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## Защита от автокомпакта
+
+**Проблема:** При длительной работе Claude сжимает ранний контекст.
+
+**Решение:** Вся критическая информация в файлах:
+
+| Информация | Где хранится |
+|------------|--------------|
+| Текущее состояние | CONTEXT.md |
+| План и прогресс | ACTIVE.md |
+| Детали работы | `bd comments <bead-id>` |
+| Архитектура | RFC.md |
+| DAG | PLAN.md + beads |
+
+**Правило:** Никогда не полагаться на "память" из чата. Всегда читать файлы при возобновлении работы.
+
+---
+
+## Восстановление после автокомпакта
+
+Если контекст был сжат:
+
+```bash
+# 1. Прочитать состояние из beads
+bd show <bead-id>
+bd comments <bead-id>
+
+# 2. Прочитать файлы
+# - CONTEXT.md
+# - ACTIVE.md
+
+# 3. Продолжить с последнего checkpoint
+```
+
+---
+
+## Чеклист checkpoint
+
+- [ ] Добавлен comment в beads: `bd comments add`
+- [ ] ACTIVE.md обновлён (заметки, прогресс)
+- [ ] CONTEXT.md обновлён (если были решения)
+- [ ] Пользователь информирован (checkpoint в чат)