feat(brain-spec): Phase 1 design (consumer-universal plugins + context7 activation)
Design doc для brain v1.2 → v1.3 release. Phase 1 после Phase 0 meta-foundation. Scope: 5 plugin'ов из shortlist consumer-universal — code-review, security-guidance, pr-review-toolkit, telegram (target=consumer, registered-only), и context7 (target= user-level+consumer, активен в brain как docs API/SDK lookup). Plus tech-debt close: install-plugins.sh learns --install-target ENUM filter (per routing.md v1.1 §4.1). Out of scope: Liderra deploy (blocked outstanding v1.0), Phase 2 stack-gated, custom skills, Pravila v2 bump. Spec covers: architecture/data-flow (§3), per-file deliverables (§4), 10 conflicts mitigation (§5), per-artifact verification (§6), runtime deps checks (§7), 5 atomic commits sequence + rollback (§8), open risks (§9), self-review (§10). Spec self-review passed: no TBD/TODO/FIXME, only intentional <utc-at-commit-time> and <commit-5-sha> placeholders. Internal consistency §2 ↔ §4 ↔ §8 verified. Cross-refs resolve correctly from docs/superpowers/specs/ base. Next: invoke superpowers:writing-plans для детального plan'а Phase 1B (commits 2-5). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Дмитрий
@@ -0,0 +1,533 @@
|
||||
# Brain v2 Phase 1 — Consumer-Universal Plugins + Context7 Activation (design)
|
||||
|
||||
**Дата:** 12.05.2026
|
||||
**Brain version target:** v1.2 → v1.3
|
||||
**Routing.md target:** v1.1 → v1.2
|
||||
**Связанные документы:**
|
||||
- [docs/brain-plugin-routing.md](../../brain-plugin-routing.md) (v1.1, будет bump v1.2)
|
||||
- [docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md](2026-05-11-brain-plugin-routing-design.md) (предыдущий spec)
|
||||
- [CLAUDE.md](../../../CLAUDE.md) (operational map brain'а)
|
||||
|
||||
---
|
||||
|
||||
## §1. Цель и scope
|
||||
|
||||
Phase 1 — следующий шаг brain v2 после Phase 0 (мета-foundation). Цель: распространить через brain'а в consumer'ы (Liderra и будущие) 5 плагинов категории `consumer-universal` из shortlist'а 17 (см. [memory: project_brain_v2_phase0.md](../../../../../C:/Users/Administrator/.claude/projects/c--------------claude-brain/memory/project_brain_v2_phase0.md)).
|
||||
|
||||
**Что внутри scope:**
|
||||
1. Регистрация 4 plugin'ов в `plugins-manifest.json` (target=consumer, не активируются в brain runtime).
|
||||
2. Активация 1 plugin'а (Context7) на user-level brain'а через `settings-fragment.json` + cache cp.
|
||||
3. Закрытие техдолга `install-plugins.sh` — фильтрация по `target` ENUM (введён в v1.1, но не операционализирован в коде).
|
||||
4. Bump `docs/brain-plugin-routing.md` v1.1 → v1.2 с новыми rows.
|
||||
5. Release brain v1.2 → v1.3 + git tag.
|
||||
|
||||
**Что вне scope:**
|
||||
- Реальный deploy в Liderra (блокирован outstanding'ом v1.0: lychee 33 broken links + Liderra main не запушен). Это Phase 1C / отдельный chat.
|
||||
- Phase 2 stack-gated плагины (figma, vercel, supabase, huggingface, data-engineering) — ждут ответов по стеку.
|
||||
- Кастомные brain skills (skill-creator output) — отдельная инициатива.
|
||||
- Pravila v2 bump — отложен до накопления изменений.
|
||||
|
||||
---
|
||||
|
||||
## §2. 5 артефактов Phase 1
|
||||
|
||||
| # | Plugin | Marketplace | Тип | Author | Target | Active in brain? |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1 | `code-review` | `anthropics/claude-plugins-official` | pure plugin | Anthropic | `consumer` | ✗ |
|
||||
| 2 | `security-guidance` | `anthropics/claude-plugins-official` | plugin + hooks | Anthropic | `consumer` | ✗ |
|
||||
| 3 | `pr-review-toolkit` | `anthropics/claude-plugins-official` | plugin (multi-agent) | Anthropic | `consumer` | ✗ |
|
||||
| 4 | `telegram` | `anthropics/claude-plugins-official` (external_plugins/) | plugin + bundled MCP | community-managed | `consumer` | ✗ |
|
||||
| 5 | `context7` | `anthropics/claude-plugins-official` (external_plugins/) | plugin + bundled MCP | Upstash (community-managed) | `user-level+consumer` | ✓ |
|
||||
|
||||
**Marketplace HEAD SHA для pinning:** `00679aef889efe36bb0389f81d70b6229a2013ee` (commit 2026-05-09 21:40 +0100; тот же SHA, что у plugin-dev и hookify в Phase 0 install).
|
||||
|
||||
### §2.1. Reality check фактических плагинов
|
||||
|
||||
Все 5 верифицированы в локальном marketplace cache (`~/.claude/plugins/marketplaces/claude-plugins-official/`):
|
||||
- Plugin manifests прочитаны: `plugins/code-review/.claude-plugin/plugin.json`, `plugins/security-guidance/.claude-plugin/plugin.json`, `plugins/pr-review-toolkit/.claude-plugin/plugin.json`, `external_plugins/telegram/.claude-plugin/plugin.json`, `external_plugins/context7/.claude-plugin/plugin.json`.
|
||||
- Marketplace entries в `.claude-plugin/marketplace.json` подтверждены (lines 528-538, 572-581, 1455-1465, 1712-1722, 1962-1967 файла marketplace.json — текст `"name": "<plugin>"`).
|
||||
- Bundled MCP в Context7: [external_plugins/context7/.mcp.json](../../../../../C:/Users/Administrator/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/context7/.mcp.json) — `{"context7": {"command": "npx", "args": ["-y", "@upstash/context7-mcp"]}}`.
|
||||
- Bundled MCP в Telegram: [external_plugins/telegram/.mcp.json](../../../../../C:/Users/Administrator/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/.mcp.json) — `{"mcpServers": {"telegram": {"command": "bun", "args": [...]}}}`.
|
||||
|
||||
### §2.2. Categorization rationale
|
||||
|
||||
**Почему Context7 = `user-level+consumer` (активен в brain):**
|
||||
- Brain dev = ежедневное чтение Anthropic SDK / claude-plugins / marketplace specs. Context7 даёт авторитетный structured doc lookup без сёрфинга по GitHub raw url'ам.
|
||||
- Не дублирует существующий tool — нет default'а на «docs API/SDK lookup» в routing.md §3.1; Context7 заполняет новый класс задачи, не overlap'ит.
|
||||
|
||||
**Почему остальные 4 = `consumer-universal` (только в consumer):**
|
||||
- `code-review`: conflict с `superpowers:requesting-code-review` (default routing.md §3.1 line 69). Активация в brain создаст ambiguity «который plugin использовать».
|
||||
- `security-guidance`: conflict с built-in `/security-review` command + bundled `hooks.json` плагина может конфликтовать с brain'овыми 7 economy-hooks.
|
||||
- `pr-review-toolkit`: для brain (1 maintainer, простой PR workflow) overkill. В Liderra (команда) полезен.
|
||||
- `telegram`: brain не имеет need в notifications (локальная работа, нет long-running CI). В Liderra при deploy/CI полезен.
|
||||
|
||||
---
|
||||
|
||||
## §3. Архитектура и data flow
|
||||
|
||||
### §3.1. Unified plugin track (вместо двойного track A/B)
|
||||
|
||||
Все 5 артефактов — **plugin'ы**. Context7 и telegram несут `.mcp.json` внутри plugin'а (bundled MCP), который автоматически регистрируется как MCP-сервер при включении plugin'а в `enabledPlugins`. Никаких отдельных правок `mcp-user.template.json` или `.mcp.json.template` для них **не требуется**.
|
||||
|
||||
**Distribute pipeline (brain → consumer):**
|
||||
|
||||
```
|
||||
brain/user-level-files/plugins-manifest.json
|
||||
│
|
||||
│ scripts/install.sh --target=<consumer> --version=brain-v1.3 --with-plugins=yes
|
||||
│
|
||||
▼
|
||||
scripts/lib/install-plugins.sh --install-target=consumer
|
||||
│
|
||||
│ jq filter: target ∈ {"consumer", "user-level+consumer"}
|
||||
│
|
||||
▼
|
||||
claude plugin install <name>@claude-plugins-official (или JSON fallback)
|
||||
│
|
||||
▼
|
||||
consumer ~/.claude/plugins/cache/claude-plugins-official/<name>/<sha>/
|
||||
consumer ~/.claude/settings.json enabledPlugins.<name>=true (если CLI / manual edit)
|
||||
```
|
||||
|
||||
**Brain runtime pipeline:**
|
||||
|
||||
```
|
||||
brain/user-level-files/plugins-manifest.json → 13 entries (8 existing + 5 new)
|
||||
brain/user-level-files/settings-fragment.json → 9 enabledPlugins (8 existing + context7)
|
||||
│
|
||||
│ scripts/install.sh --target=$HOME/.claude --version=brain-v1.3
|
||||
│
|
||||
▼
|
||||
install.sh detects mode=user; --install-target=user
|
||||
│
|
||||
▼
|
||||
filter target ∈ {"user-level", "user-level+consumer"}
|
||||
│
|
||||
│ 9 plugins pass: 6 existing user-level (claude-md-management, superpowers, skill-creator,
|
||||
│ claude-code-setup, plugin-dev, hookify) + 2 existing user-level+consumer
|
||||
│ (ui-ux-pro-max, frontend-design) + new context7
|
||||
│
|
||||
│ 4 filtered out: code-review, security-guidance, pr-review-toolkit, telegram
|
||||
│
|
||||
▼
|
||||
merge-settings.sh: brain ~/.claude/settings.json enabledPlugins replaced с 9 entries
|
||||
cache cp: ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/ создан
|
||||
```
|
||||
|
||||
### §3.2. Track unified rationale
|
||||
|
||||
Раньше (раннее brainstorming) я различал «Track A — plugins» и «Track B — MCP-серверы через `.mcp templates`». Reality check показал, что Context7 и Telegram — **plugin'ы**, которые **внутри** содержат `.mcp.json`. Claude Code автоматически регистрирует bundled MCP при enabling plugin'а. Это упрощает архитектуру до одного track'а.
|
||||
|
||||
Корректировка: поле `kind: "plugin" | "mcp"` в plugins-manifest **не нужно** — все entries plugin'ы. MCP-only артефакты (например, `magic` 21st.dev в `mcp-user.template.json`) остаются отдельной концепцией для **legacy** случаев, когда есть raw MCP-сервер без plugin wrapper.
|
||||
|
||||
---
|
||||
|
||||
## §4. Изменения по файлам (deliverables)
|
||||
|
||||
### §4.1. `user-level-files/plugins-manifest.json` (+5 entries)
|
||||
|
||||
Сейчас 8 entries в [plugins-manifest.json](../../../user-level-files/plugins-manifest.json). Добавляются 5 новых после `hookify` блока (line 102), перед закрывающим `}`.
|
||||
|
||||
**Template entry для 4 consumer-only (code-review, security-guidance, pr-review-toolkit, telegram):**
|
||||
|
||||
```json
|
||||
"<plugin-name>@claude-plugins-official": [
|
||||
{
|
||||
"scope": "user",
|
||||
"installPath": null,
|
||||
"version": "00679aef889e",
|
||||
"installedAt": null,
|
||||
"lastUpdated": "2026-05-12T00:00:00.000Z",
|
||||
"gitCommitSha": "00679aef889efe36bb0389f81d70b6229a2013ee",
|
||||
"installMethod": "registered-only-not-cached",
|
||||
"target": "consumer",
|
||||
"category": "consumer-universal"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Entry для Context7 (cached + active):**
|
||||
|
||||
```json
|
||||
"context7@claude-plugins-official": [
|
||||
{
|
||||
"scope": "user",
|
||||
"installPath": "C:\\Users\\Administrator\\.claude\\plugins\\cache\\claude-plugins-official\\context7\\00679aef889e",
|
||||
"version": "00679aef889e",
|
||||
"installedAt": "2026-05-12T<utc-at-commit-time>Z",
|
||||
"lastUpdated": "2026-05-12T<utc-at-commit-time>Z",
|
||||
"gitCommitSha": "00679aef889efe36bb0389f81d70b6229a2013ee",
|
||||
"installMethod": "manual-cp-from-marketplace-Path2",
|
||||
"target": "user-level+consumer",
|
||||
"category": "consumer-universal"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Verification после Edit:**
|
||||
- `jq empty user-level-files/plugins-manifest.json` exit 0
|
||||
- `jq '.plugins | length'` == 13
|
||||
- Per-plugin target check (см. §6.1)
|
||||
|
||||
### §4.2. `user-level-files/settings-fragment.json` (+1 ключ)
|
||||
|
||||
Сейчас 8 keys в `enabledPlugins` ([settings-fragment.json:2-11](../../../user-level-files/settings-fragment.json#L2-L11)). Добавляется:
|
||||
|
||||
```json
|
||||
"context7@claude-plugins-official": true
|
||||
```
|
||||
|
||||
**4 consumer-only НЕ добавляются** — они не активируются в brain runtime.
|
||||
|
||||
### §4.3. `scripts/lib/install-plugins.sh` (рефакторинг)
|
||||
|
||||
**Текущее поведение (line 61):**
|
||||
```bash
|
||||
for plugin in $(jq -r '.plugins | keys[]' "$manifest"); do
|
||||
```
|
||||
Берёт все entries без фильтрации.
|
||||
|
||||
**Новое поведение:**
|
||||
|
||||
```bash
|
||||
# New flag parsing (после строки 28)
|
||||
case "$1" in
|
||||
--marketplaces=*) marketplaces="${1#--marketplaces=}" ;;
|
||||
--manifest=*) manifest="${1#--manifest=}" ;;
|
||||
--install-target=*) install_target="${1#--install-target=}" ;;
|
||||
*) log_error "Unknown arg: $1"; exit 1 ;;
|
||||
esac
|
||||
|
||||
# Fallback default (backwards-compat для прямых вызовов из тестов)
|
||||
if [ -z "${install_target:-}" ]; then
|
||||
log_warn "--install-target not specified, defaulting to 'user' (deprecated path)"
|
||||
install_target="user"
|
||||
fi
|
||||
|
||||
# Filter expression
|
||||
case "$install_target" in
|
||||
user)
|
||||
filter='.plugins | to_entries[] | select(.value[0].target == "user-level" or .value[0].target == "user-level+consumer") | .key'
|
||||
;;
|
||||
consumer)
|
||||
filter='.plugins | to_entries[] | select(.value[0].target == "consumer" or .value[0].target == "user-level+consumer") | .key'
|
||||
;;
|
||||
*)
|
||||
log_error "--install-target must be 'user' or 'consumer', got: $install_target"; exit 1 ;;
|
||||
esac
|
||||
|
||||
# Use filter
|
||||
for plugin in $(jq -r "$filter" "$manifest"); do
|
||||
# ... rest unchanged from current line 62-74
|
||||
done
|
||||
```
|
||||
|
||||
**Также корректировка `scripts/install.sh` line 145-150:**
|
||||
|
||||
```bash
|
||||
if [ "$with_plugins" = "yes" ]; then
|
||||
if [ -f "$src/marketplaces.json" ] && [ -f "$src/plugins-manifest.json" ]; then
|
||||
# Map detected $mode (user|project) to --install-target (user|consumer)
|
||||
plugin_target=$([ "$mode" = "user" ] && echo "user" || echo "consumer")
|
||||
bash "$SCRIPT_DIR/lib/install-plugins.sh" \
|
||||
--marketplaces="$src/marketplaces.json" \
|
||||
--manifest="$src/plugins-manifest.json" \
|
||||
--install-target="$plugin_target" || exit 6
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
**Verification после Edit:**
|
||||
- `bash -n scripts/lib/install-plugins.sh scripts/install.sh` exit 0
|
||||
- Regression: `bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2` exit 0
|
||||
- Functional filter test (см. §6.3)
|
||||
|
||||
### §4.4. `docs/brain-plugin-routing.md` (v1.1 → v1.2)
|
||||
|
||||
**Header:**
|
||||
```diff
|
||||
- # Brain Plugin Routing Rules (v1.1)
|
||||
+ # Brain Plugin Routing Rules (v1.2)
|
||||
- **Дата:** 11.05.2026
|
||||
+ **Дата:** 12.05.2026
|
||||
```
|
||||
|
||||
**§2.1 — +1 row Context7 (после строки hookify):**
|
||||
|
||||
```markdown
|
||||
| **context7** | `anthropics/claude-plugins-official` | `consumer-universal` (active in brain via target=user-level+consumer) | docs lookup для API/SDK/marketplaces (Anthropic SDK, claude-plugins, future Vue/Vuetify Liderra); plugin bundles MCP via `npx @upstash/context7-mcp` | каждодневный код-write (не doc-lookup) |
|
||||
```
|
||||
|
||||
**§3.1 — +1 row (после строки «Запутался — какой плагин брать»):**
|
||||
|
||||
```markdown
|
||||
| Документация API/SDK/marketplace (Anthropic SDK, claude-plugins-official, Vue/Vuetify в Liderra) | `context7` MCP (через plugin context7 enabledPlugins) | `WebFetch` если context7 npx down/offline ИЛИ источник вне SDK doc trees (общая статья, blog post) | структурированный version-pinned lookup vs unstructured web scrape |
|
||||
```
|
||||
|
||||
**§3.2 — +1 tie-breaker (после №3 «User написал /skill-name явно»):**
|
||||
|
||||
```markdown
|
||||
4. **Community-managed plugin предложен для активного use** — добавить в `enabledPlugins` только если: (a) Anthropic-маркетплейс с явной верификацией (community-managed tag там есть, но Anthropic git-hosted), ИЛИ (b) user явно проаппрувил риск, ИЛИ (c) plugin изолирован (read-only queries без PII). Иначе оставить `registered-only-not-cached` для consumer-distribute, не активируя в brain.
|
||||
```
|
||||
|
||||
**§4.2 — +5 rows (после строки #18 hookify):**
|
||||
|
||||
```markdown
|
||||
| #1 | `context7` | `consumer-universal` (active in brain user-level via target=user-level+consumer) | installed brain v1.3 (manual-cp-from-marketplace-Path2); **community-managed** (Upstash) + npx runtime dep |
|
||||
| #2 | `code-review` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); Anthropic-authored |
|
||||
| #7 | `security-guidance` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); Anthropic-authored; plugin несёт own hooks.json — потенциальный конфликт с brain economy-hooks при activation |
|
||||
| #10 | `pr-review-toolkit` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); Anthropic-authored |
|
||||
| #12 | `telegram` | `consumer-universal` | registered brain v1.3 (registered-only-not-cached); **community-managed** + bun runtime dep + post-install pairing required |
|
||||
```
|
||||
|
||||
**История версий — +1 entry в начало (между v1.1 и v1.0):**
|
||||
|
||||
```markdown
|
||||
- **v1.2 от 2026-05-12** — Brain v1.3 release: Phase 1 deliverables. Added 5 plugins (#1 context7 active-in-brain, #2 code-review, #7 security-guidance, #10 pr-review-toolkit, #12 telegram — все consumer-universal через target=consumer ИЛИ user-level+consumer). install-plugins.sh learned `--install-target` flag + filter по `target` ENUM (closing tech-debt unmentioned-but-implicit из v1.0). §2.1 +1 row, §3.1 +1 row (docs lookup новый класс задачи), §3.2 +1 tie-breaker (community-managed), §4.2 +5 rows.
|
||||
```
|
||||
|
||||
### §4.5. `.brain-version` (v1.2 → v1.3)
|
||||
|
||||
```diff
|
||||
- v1.2
|
||||
- sha: 276a47f<rest>
|
||||
+ v1.3
|
||||
+ sha: <commit-5-sha-after-atomic-commit>
|
||||
```
|
||||
|
||||
### §4.6. Cache cp Context7 (filesystem side-effect, не git-tracked в brain repo)
|
||||
|
||||
Действие при execution commit 4:
|
||||
|
||||
```bash
|
||||
cp -r ~/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/context7/ \
|
||||
~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/
|
||||
```
|
||||
|
||||
Соответствует pattern'у Phase 0 plugin-dev/hookify cache cp ([plugins-manifest.json:81-89](../../../user-level-files/plugins-manifest.json#L81-L89)).
|
||||
|
||||
---
|
||||
|
||||
## §5. Conflicts и mitigation
|
||||
|
||||
| ID | Конфликт | Mitigation | Where it lives |
|
||||
|---|---|---|---|
|
||||
| **C1** | `code-review` plugin vs `superpowers:requesting-code-review` | Не активировать code-review в brain. Routing.md §3.1 line 69 default остаётся superpowers | settings-fragment.json НЕ содержит ключ |
|
||||
| **C2** | `security-guidance` bundled hooks.json vs brain economy-hooks | Не активировать security-guidance в brain. Built-in `/security-review` команда покрывает need | settings-fragment.json НЕ содержит ключ |
|
||||
| **C3** | `pr-review-toolkit` agents vs `superpowers:requesting-code-review` agents | В brain оба не активны (no conflict). В consumer — задача PSR template'а | вне scope brain routing.md |
|
||||
| **C4** | `telegram` notifications vs brain (нет аналога) | No conflict в brain | — |
|
||||
| **C5** | `context7` MCP vs `WebFetch` для docs | Routing.md §3.1 +1 row: Context7 default for API/SDK; WebFetch fallback | docs/brain-plugin-routing.md v1.2 §3.1 |
|
||||
| **C6** | Context7 npx runtime требование | Pre-install dep check (см. §7); если npx absent — Context7 entry остаётся, но enabledPlugins=false до решения dep | plan execution (Phase 1B) |
|
||||
| **C7** | Telegram bun runtime требование (для consumer) | Pre-distribute dep check для Liderra; bun на Windows — отдельная установка. Spec помечает: telegram опционален для consumer без bun | — (не блокер brain v1.3) |
|
||||
| **C8** | Context7 MCP coexistence c `magic` (21st.dev) MCP в `~/.claude.json:mcpServers` | merge-mcp.sh идемпотентно добавит context7 entry рядом с magic. **Не верифицировано** — verify-checkpoint в plan | plan execution |
|
||||
| **C9** | Community-managed plugin'ы (Context7, telegram) vs brain до v1.2 — только Anthropic-authored | Spec disclaimer + routing.md §3.2 tie-breaker #4 | docs/brain-plugin-routing.md v1.2 §3.2 |
|
||||
| **C10** | install-plugins.sh refactor ломает обратную совместимость (флаг `--install-target`) | Fallback-to-user with warning (см. §4.3) для прямых вызовов | scripts/lib/install-plugins.sh |
|
||||
|
||||
---
|
||||
|
||||
## §6. Verification (как проверять каждый артефакт в Phase 1B)
|
||||
|
||||
### §6.1. Per-file verification
|
||||
|
||||
**A. plugins-manifest.json:**
|
||||
```bash
|
||||
jq empty user-level-files/plugins-manifest.json
|
||||
jq '.plugins | length' user-level-files/plugins-manifest.json # → 13
|
||||
for p in code-review security-guidance pr-review-toolkit telegram context7; do
|
||||
jq -r ".plugins[\"$p@claude-plugins-official\"][0].target" user-level-files/plugins-manifest.json
|
||||
done
|
||||
# Expected: consumer, consumer, consumer, consumer, user-level+consumer
|
||||
```
|
||||
|
||||
**B. settings-fragment.json:**
|
||||
```bash
|
||||
jq empty user-level-files/settings-fragment.json
|
||||
jq '.enabledPlugins | length' user-level-files/settings-fragment.json # → 9
|
||||
jq '.enabledPlugins["context7@claude-plugins-official"]' user-level-files/settings-fragment.json # → true
|
||||
```
|
||||
|
||||
**C. install-plugins.sh:**
|
||||
```bash
|
||||
bash -n scripts/lib/install-plugins.sh scripts/install.sh
|
||||
# Functional dry-run regression
|
||||
bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2 # exit 0
|
||||
# Filter functional test
|
||||
BRAIN_ROOT=$PWD bash scripts/lib/install-plugins.sh \
|
||||
--marketplaces=user-level-files/marketplaces.json \
|
||||
--manifest=user-level-files/plugins-manifest.json \
|
||||
--install-target=user 2>&1 | grep "Installing" # → 9 plugins
|
||||
```
|
||||
|
||||
**D. routing.md:**
|
||||
```bash
|
||||
grep -E "^# Brain Plugin Routing Rules \(v1\.2\)$" docs/brain-plugin-routing.md
|
||||
grep -c "^| **context7**" docs/brain-plugin-routing.md # → 1+ (в §2.1)
|
||||
grep -cE "^\| #(1|2|7|10|12) \|" docs/brain-plugin-routing.md # → ≥5
|
||||
```
|
||||
|
||||
**E. .brain-version:**
|
||||
```bash
|
||||
head -1 .brain-version # → v1.3
|
||||
```
|
||||
|
||||
**F. Context7 cache:**
|
||||
```bash
|
||||
test -d ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e
|
||||
jq empty ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/.claude-plugin/plugin.json
|
||||
jq -r .name ~/.claude/plugins/cache/claude-plugins-official/context7/00679aef889e/.claude-plugin/plugin.json
|
||||
# Expected: context7
|
||||
```
|
||||
|
||||
### §6.2. Runtime smoke test (после install.sh + restart)
|
||||
|
||||
```bash
|
||||
jq '.enabledPlugins["context7@claude-plugins-official"]' ~/.claude/settings.json # → true
|
||||
npx -y @upstash/context7-mcp --help 2>&1 | head -5 # exit 0
|
||||
```
|
||||
|
||||
Manual: открыть новую сессию, проверить что Skill tool / mcpServers видит context7.
|
||||
|
||||
### §6.3. Regression check (existing 8 plugins после install-plugins.sh refactor)
|
||||
|
||||
```bash
|
||||
# До refactor (commit 1 в HEAD)
|
||||
git stash
|
||||
git checkout HEAD~1 -- scripts/lib/install-plugins.sh scripts/install.sh
|
||||
bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2 | tee before.txt
|
||||
|
||||
# После refactor
|
||||
git stash pop
|
||||
bash scripts/install.sh --dry-run --target=$HOME/.claude --version=brain-v1.2 | tee after.txt
|
||||
|
||||
diff before.txt after.txt # diff не должен содержать added/removed plugins из 8 existing
|
||||
```
|
||||
|
||||
### §6.4. Final verification gate
|
||||
|
||||
Перед claim «Phase 1 готов» — обязательно invoke `superpowers:verification-before-completion`. Skill сам проверит:
|
||||
- atomic commits sequence (5 commits) в git log
|
||||
- git tag `brain-v1.3` создан
|
||||
- `.brain-version` соответствует git rev-parse HEAD
|
||||
- verify.sh exit 0
|
||||
- runtime smoke test (Context7 в новой сессии) — verified или явно «не верифицировал X»
|
||||
|
||||
---
|
||||
|
||||
## §7. Runtime dependencies (pre-install checks)
|
||||
|
||||
Phase 1B execution (writing-plans) обязан включить pre-install dep check как отдельный helper. Возможный артефакт `scripts/verify-deps.sh`:
|
||||
|
||||
```bash
|
||||
require_runtime() {
|
||||
local cmd="$1"; local plugin="$2"
|
||||
if ! command -v "$cmd" >/dev/null 2>&1; then
|
||||
log_warn "$plugin requires '$cmd' — not in PATH"
|
||||
return 1
|
||||
fi
|
||||
log_info "$plugin runtime OK: $cmd ($(command -v "$cmd"))"
|
||||
return 0
|
||||
}
|
||||
|
||||
require_runtime npx context7 || log_warn "context7 будет в manifest но enabledPlugins=false"
|
||||
require_runtime bun telegram || log_warn "telegram остаётся registered-only для consumer без bun"
|
||||
```
|
||||
|
||||
Не верифицировал, что `npx` и `bun` присутствуют на машине Дмитрия — это входит в Phase 1B как первый шаг execution.
|
||||
|
||||
---
|
||||
|
||||
## §8. Atomic commits sequence (Phase 1B execution)
|
||||
|
||||
5 коммитов, каждый — один логический change, self-contained, reversible.
|
||||
|
||||
| # | Commit message | Files modified | Verify gate |
|
||||
|---|---|---|---|
|
||||
| 1 | `feat(brain-spec): Phase 1 design (consumer-universal plugins + context7 activation)` | spec doc (this file) | markdown self-review |
|
||||
| 2 | `refactor(brain-install): filter plugins by target ENUM in install-plugins.sh` | scripts/lib/install-plugins.sh, scripts/install.sh | bash -n + regression dry-run |
|
||||
| 3 | `feat(brain-plugins): register 4 consumer-universal plugins (code-review, security-guidance, pr-review-toolkit, telegram)` | plugins-manifest.json (+4) | jq schema + target check |
|
||||
| 4 | `feat(brain-plugins): register and activate context7 user-level+consumer` | plugins-manifest.json (+1), settings-fragment.json (+1), cache cp side-effect | jq + cache dir + runtime smoke |
|
||||
| 5 | `docs(brain-routing): bump v1.1 → v1.2 with Phase 1 entries; chore brain-version v1.2 → v1.3` | docs/brain-plugin-routing.md, .brain-version | grep version + verify.sh |
|
||||
|
||||
После commit 5: `git tag brain-v1.3` (не амендится; следующие итерации — `brain-v1.3.1` per memory project_outstanding_items rule).
|
||||
|
||||
**Push на origin/main:** ТОЛЬКО после явного user-approve, не auto.
|
||||
|
||||
### §8.1. Rollback strategy
|
||||
|
||||
| Что сломалось | Rollback |
|
||||
|---|---|
|
||||
| Spec self-review выявил противоречие (commit 1) | Amend commit 1 (изолирован) |
|
||||
| install-plugins.sh регрессия (commit 2) | `git revert <c2-sha>` — manifest и spec остаются |
|
||||
| 4 entries малформированы (commit 3) | `git revert <c3-sha>` — install-plugins.sh уже умеет filter |
|
||||
| Context7 cache cp fail / npx broken (commit 4) | `git revert <c4-sha>` + `rm -rf ~/.claude/plugins/cache/claude-plugins-official/context7/` |
|
||||
| routing.md mismatch (commit 5) | `git revert <c5-sha>` |
|
||||
|
||||
---
|
||||
|
||||
## §9. Открытые риски
|
||||
|
||||
### §9.1. Технические
|
||||
|
||||
- **C6 npx availability** — не верифицировано на машине Дмитрия. Если npx absent → Context7 в brain runtime не работает; деградация до registered-only.
|
||||
- **C7 bun availability** — не верифицировано для Liderra deploy; не блокер brain v1.3, но блокер Liderra distribute telegram.
|
||||
- **C8 MCP coexistence** — merge-mcp.sh не тестировался на сценарии «magic + context7 одновременно». Verify-checkpoint в plan.
|
||||
- **lychee/markdownlint** — не верифицировано наличие на машине.
|
||||
- **shellcheck** — не верифицировано наличие.
|
||||
|
||||
### §9.2. Документационные
|
||||
|
||||
- Spec self-review (§10) может выявить ambiguity, требующую правки до Phase 1B start'а.
|
||||
- routing.md changes v1.2 могут потребовать обновления `Plugin_stack_rules.template.md` для consumer'ов (PSR template), но это вне scope brain v1.3 — будет в Phase 1C / Liderra integration.
|
||||
|
||||
### §9.3. Risk acknowledgment community-managed
|
||||
|
||||
Phase 1 вводит **первые** community-managed plugin'ы в brain distribute (Context7 — Upstash, telegram — community). До v1.2 brain содержал только Anthropic-authored + 2 marketplace с vetted-репутацией (FD/UPM через `nextlevelbuilder/ui-ux-pro-max-skill`, superpowers через `obra/superpowers`).
|
||||
|
||||
Для **Liderra (152-ФЗ персданные):**
|
||||
- Context7 → шлёт только docs queries (не PII). Acceptable.
|
||||
- Telegram → обмен сообщениями через бота. Перед production-use Liderra — обязательная allowlist policy в `/telegram:access`, явное согласование с заказчиком на data flows.
|
||||
|
||||
---
|
||||
|
||||
## §10. Spec self-review (выполняется автором перед user review)
|
||||
|
||||
**Placeholders scan:**
|
||||
- `<utc-at-commit-time>` в §4.1 (Context7 entry) — будет подставлен в Phase 1B при actual commit. Это placeholder с явной семантикой, не TODO.
|
||||
- `<commit-5-sha-after-atomic-commit>` в §4.5 — то же самое.
|
||||
- `<rest>` в §4.5 (sha plug) — phasing, означает «текущий sha brain-v1.2».
|
||||
- Других TBD / TODO в тексте нет.
|
||||
|
||||
**Internal consistency:**
|
||||
- §2 таблица 5 артефактов согласована с §4.1-§4.5 файловыми изменениями (5 plugins ↔ 5 entries в manifest).
|
||||
- §3.1 архитектурная диаграмма соответствует §4.3 install-plugins.sh filter logic.
|
||||
- §5 C1-C10 не противоречат §6 verification (каждый conflict либо mitigated через config, либо имеет verify-checkpoint).
|
||||
- §8 atomic commits sequence согласован с §4 deliverables (commit N → file group N).
|
||||
|
||||
**Scope check:**
|
||||
- Фокусирован на одну задачу — Phase 1 release с 5 plugins + install-sh fix.
|
||||
- НЕ включает Phase 2 stack-gated, custom skills, Liderra deploy — явно вынесено в out-of-scope §1.
|
||||
- Готов под один writing-plans → executing-plans cycle.
|
||||
|
||||
**Ambiguity check:**
|
||||
- `community-managed` — однозначно определено как «не Anthropic-authored, поддержка третьей стороной» (см. marketplace.json tag).
|
||||
- `target` ENUM — три значения определены в routing.md v1.1 §4.1 (`user-level`, `consumer`, `user-level+consumer`).
|
||||
- `installMethod` — два значения используются (`manual-cp-from-marketplace-Path2`, `registered-only-not-cached`), оба явно описаны.
|
||||
|
||||
**Известные ограничения (не верифицировано):**
|
||||
- npx availability в env Дмитрия
|
||||
- bun availability
|
||||
- shellcheck, markdownlint, lychee availability
|
||||
- Точное поведение Claude Code при enabling plugin'а с bundled `.mcp.json` — auto-register или нужна manual edit `~/.claude/.claude.json`? Documenting как assumption, verify-checkpoint в Phase 1B commit 4.
|
||||
|
||||
---
|
||||
|
||||
## §11. Что после этого spec'а
|
||||
|
||||
1. **User review этого файла** — phase 1A gate.
|
||||
2. После approve → invoke `superpowers:writing-plans` для детального implementation plan'а Phase 1B (5 атомарных коммитов по §8).
|
||||
3. Plan review с пользователем.
|
||||
4. Invoke `superpowers:executing-plans` для выполнения plan'а с verification checkpoints (§6).
|
||||
5. Final invoke `superpowers:verification-before-completion` перед claim «Phase 1 brain v1.3 готов».
|
||||
6. (Опционально, после user-approve) push на origin/main + git tag brain-v1.3.
|
||||
|
||||
**Brain v1.3 release не требует Liderra deploy** — это отдельный Phase 1C (или часть Phase 2 при decision point).
|
||||
Reference in New Issue
Block a user