# A6 Architecture Tooling Integration Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Install three tools from the A6 top-5 — #1 `adr-kit` (architecture decisions + enforcement), #3 `mermaid-skill` (C4 / architecture diagrams), #4 `architecture-patterns` (patterns playbook) — and integrate them into Лидерра so the `A6 «Архитектура систем»` map section becomes a populated, working playbook.

**Architecture:** Three tools, three install modes. **adr-kit** = marketplace plugin; its git pre-commit hook and `init` CLAUDE.md write are bypassed (lefthook job 9 + manual bootstrap). **architecture-patterns** = marketplace plugin, knowledge-only skill, zero machinery. **mermaid-skill** = standalone skill vendored into `.claude/skills/mermaid/` (no plugin, no marketplace, no hooks). All three are non-UI → architecture-tooling category, outside the PSR_v1 UI-pool. ADRs live in `docs/adr/`; C4 diagrams in `docs/architecture/`.

**Tech Stack:** adr-kit v0.13.1 (marketplace `rvdbreemen/adr-kit`, MIT); mermaid-skill (`WH-2099/mermaid-skill`, standalone skill, MIT); architecture-patterns (`secondsky/claude-skills`, marketplace plugin, MIT); lefthook 2.x; project normative docs; `docs/automation-graph.html` (vis.js).

---

## Tool Identity (verified 2026-05-17)

| # | Tool | Install mode | Source | Hooks? |
|---|---|---|---|---|
| 1 | **adr-kit** v0.13.1 | Marketplace plugin — `rvdbreemen/adr-kit` → `adr-kit@rvdbreemen-adr-kit` | GitHub `rvdbreemen/adr-kit`, MIT | No CC lifecycle hooks; ships a git pre-commit hook (not used) |
| 3 | **mermaid-skill** | Standalone skill — vendored copy into `.claude/skills/mermaid/` | GitHub `WH-2099/mermaid-skill`, MIT | None (skill files only) |
| 4 | **architecture-patterns** | Marketplace plugin — `secondsky/claude-skills` → `architecture-patterns@claude-skills` | GitHub `secondsky/claude-skills`, MIT | None disclosed (verify on install) |

Dropped from the top-5 by user: #2 `wshobson/agents` (agent sprawl, UI-pool overlap), #5 Anthropic baseline (narrow).

---

## Design Decisions & Conflict Audit

Pattern follows the K1–K8 audit used for claude-mem. Verified against the three repos, project `.claude/settings.json`, `~/.claude/settings.json`, `lefthook.yml`, `cspell.json`, `.markdownlintignore`.

| # | Tool | Sev | Conflict | Resolution (locked) |
|---|---|---|---|---|
| AK1 | adr-kit | 🔴 | `/adr-kit:install-hooks`/`init` writes `.git/hooks/pre-commit`; lefthook owns that file → mutual clobber. | Never run `install-hooks`. Vendor `adr-judge`, wire as **lefthook pre-commit job 9** (Task 5). |
| AK2 | adr-kit | 🔴 | `/adr-kit:init` modifies root `CLAUDE.md` — violates CLAUDE.md §5 п.10 (edits only via `claude-md-management`). | Never run full `init`. Bootstrap manually (Task 4). The CLAUDE.md stub = the `§3.3 #36` row via `claude-md-management` (Task 7). |
| AK3 | adr-kit | 🟡 | `docs/adr/` overlaps the `Открытые_вопросы` registry. | Boundary in ADR-000 (Task 4): ADR = *closed technical/architecture* decision; registry = *open* product/business/legal questions. |
| AK4 | adr-kit | 🟡 | `adr-judge` `## Enforcement` rules could duplicate larastan/eslint/squawk. | Enforcement = architecture-level rules only ("no Inertia/Tailwind/React imports"); never re-encode lint/style rules. |
| AK5 | adr-kit | 🟢 | Lifecycle-hook collision with the 6 economy + 2 ruflo + skill-discipline hooks. | None — adr-kit registers zero CC lifecycle hooks. Re-verified Task 2 Step 5. |
| AK6 | adr-kit | 🟢 | `adr-judge` cost vs economy. | None — declarative regex, no LLM. No ADR will be flagged `llm_judge: true`. |
| AK7 | adr-kit | 🟡 | Plugin #10, Tooling #36 — unregistered = PSR_v1 R0.2/R10 violation on use. | Register in 4 normative homes (Task 7). |
| AK8 | adr-kit | 🟢 | `/adr-kit:judge` vs `superpowers:requesting-code-review` (§12). | None — different scope (ADR-compliance vs general review); §12.2 map unchanged. |
| MK1 | mermaid | 🟡 | Vendored `.claude/skills/mermaid/**/*.md` (third-party English refs) gets caught by the cspell + markdownlint pre-commit jobs. | Add `.claude/skills/mermaid/**` to `cspell.json` `ignorePaths` and `.markdownlintignore` (Task 3). Project's own skills stay linted. |
| MK2 | mermaid | 🟢 | Plugin/marketplace/hook footprint. | None — vendored skill = SKILL.md + references only. No `enabledPlugins` entry, no hooks. Re-verify Task 3 Step 4. |
| MK3 | mermaid | 🟢 | Overlap with the vis.js automation-graph. | None — different purpose: vis.js = the live "карта"; Mermaid = static C4/architecture diagrams in docs. Additive. |
| AP1 | arch-patterns | 🟢 | Hook/overlap footprint. | Knowledge-only skill; no overlap with Superpowers (no architecture skill) or Frontend Design (UI only). Verify hooks unchanged Task 2 Step 5. |
| AP2 | arch-patterns | 🟡 | Plugin #11, Tooling #38 — registration. | Register in 4 normative homes (Task 7). |
| CC1 | all 3 | 🟡 | Bus-factor — three small community projects (adr-kit pre-1.0; mermaid/arch-patterns single-maintainer). | mermaid is **vendored** (immune to upstream loss). adr-kit + arch-patterns are marketplace-cache-pinned. Note in Tooling §4.x as a known risk. No alpha-substrate spike needed — none has a known-broken core (unlike ruflo K7). |

**Severable scope:** Task 5 (lefthook enforcement) is the only part touching the commit pipeline. **Knowledge-only** integration = skip Task 5 entirely — Tasks 1-4, 6-9 still deliver a working ADR store + diagram skill + patterns skill + populated map. Primary path below = full integration.

---

## File Structure

| File | Created / Modified | Responsibility |
|---|---|---|
| `docs/adr/` | Create dir | ADR document store, `ADR-XXX-kebab-title.md` |
| `docs/adr/ADR-000-adr-process.md` | Create | Meta-ADR: ADR vs registry vs `docs/architecture/` boundaries |
| `docs/adr/ADR-001-frontend-stack-vue-vuetify.md` | Create | Seed ADR with an `Enforcement` block (testable rule for Task 5) |
| `docs/adr/ADR-002-multitenancy-postgres-rls.md` | Create | Seed ADR, documentation-only |
| `docs/architecture/` | Create dir | C4 / system diagrams (Mermaid), models |
| `docs/architecture/README.md` | Create | Index — defines `docs/architecture/` purpose, links A6 |
| `docs/architecture/c4-context.md` | Create | Seed C4 Context diagram of Лидерра (proof + initial A6 content) |
| `.claude/skills/mermaid/` | Create (vendored) | The mermaid-skill — `SKILL.md` + `references/` |
| `.claude/adr-kit-guide.md` | Create | adr-kit canonical guide (manual copy from plugin cache) |
| `tools/adr-judge.mjs` | Create (vendored) | Project-local `adr-judge` runner — decouples lefthook from plugin cache |
| `lefthook.yml` | Modify | Add pre-commit job 9 `adr-judge` |
| `cspell.json` | Modify | `ignorePaths` += `.claude/skills/mermaid/**` |
| `.markdownlintignore` | Modify | += `.claude/skills/mermaid/` |
| `cspell-words.txt` | Modify (conditional) | New ADR/architecture vocabulary |
| `~/.claude/settings.json` | Modify | `enabledPlugins` += adr-kit + architecture-patterns; `extraKnownMarketplaces` += 2 |
| `docs/Tooling_v8_3.md` | Modify | Прил. Н — new §4.11/§4.12/§4.13 + §0 counter 35 → 38 |
| `docs/Plugin_stack_rules_v1.md` | Modify | R10.1 — 3 new rows |
| `docs/Pravila_raboty_Claude_v1_1.md` | Modify | §13.2 — architecture-tooling note |
| `CLAUDE.md` | Modify (**via claude-md-management only**) | §3 title count, §1 row 2b count, §3.3 rows #36/#37/#38 |
| `docs/CHANGELOG_claude_md.md` | Modify | CLAUDE.md version-bump entry |
| `docs/automation-graph.html` | Modify | 3 new nodes (`adr_kit`, `mermaid_skill`, `arch_patterns`) → `NODE_SECTION` A6 |

---

## Task 1: Pre-flight — baseline, snapshot, fact-check

**Files:** none modified (read-only)

- [ ] **Step 1: Confirm clean tree and HEAD**

```bash
cd "c:/моя/проекты/портал crm/Документация"
git status --short
git rev-parse --short HEAD
git branch --show-current
```

Expected: working tree shows only known untracked items; record HEAD SHA as the regression baseline.

- [ ] **Step 2: Snapshot the git-hook owner**

```bash
git config core.hooksPath
head -5 .git/hooks/pre-commit
```

Expected: pre-commit references `lefthook`. Task 5 must NOT change `.git/hooks/`.

- [ ] **Step 3: Baseline the pre-commit chain**

```bash
npx lefthook run pre-commit
```

Expected: all 8 jobs (gitleaks, markdownlint, cspell, stylelint, pint, larastan, squawk, eslint-vue) green / "no staged files".

- [ ] **Step 4: Fact-check the 3 tools**

Open and confirm assumptions still hold:

- `https://github.com/rvdbreemen/adr-kit` — v0.13.x, no CC lifecycle hooks, marketplace `rvdbreemen/adr-kit`.
- `https://github.com/WH-2099/mermaid-skill` — standalone skill, files under `.claude/skills/mermaid/`, supports C4 + Architecture diagram types, MIT.
- `https://github.com/secondsky/claude-skills` — `architecture-patterns` installable as `architecture-patterns@claude-skills`, MIT.

If any tool now registers CC lifecycle hooks → **stop**, re-audit AK5/MK2/AP1 before continuing.

---

## Task 2: Install the two marketplace plugins (adr-kit, architecture-patterns)

**Files:** Modify `~/.claude/settings.json` (the `Edit` triggers the `ask` permission — expected)

- [ ] **Step 1: Add both marketplaces**

```
/plugin marketplace add rvdbreemen/adr-kit
/plugin marketplace add https://github.com/secondsky/claude-skills
```

- [ ] **Step 2: Install both plugins**

```
/plugin install adr-kit@rvdbreemen-adr-kit
/plugin install architecture-patterns@claude-skills
```

- [ ] **Step 3: Reload**

```
/reload-plugins
```

- [ ] **Step 4: Verify `enabledPlugins`**

Read `~/.claude/settings.json` — `enabledPlugins` must now contain `adr-kit@rvdbreemen-adr-kit: true` and `architecture-patterns@claude-skills: true`, alongside the existing 9 → **11 plugins total**.

- [ ] **Step 5: Verify NO lifecycle hooks were added (AK5 / AP1)**

Read the `hooks` block of `~/.claude/settings.json` AND project `.claude/settings.json`. Both must be **unchanged** — still only the economy/skill-discipline/ruflo entries. If either plugin injected a `hooks` entry → stop and re-audit.

- [ ] **Step 6: Verify adr-kit skills loaded**

```bash
ls ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/skills/
```

Expected: 8 skill directories (`adr`, `init`, `judge`, `install-hooks`, `upgrade`, `setup`, `lint`, `migrate`).

- [ ] **Step 7: Confirm economy/ruflo chain intact**

Submit a trivial prompt; confirm the economy marker still appears, no hook errors. No repo files changed in Task 2 → no commit.

---

## Task 3: Install the mermaid-skill (standalone, vendored)

**Files:**

- Create: `.claude/skills/mermaid/` (vendored skill tree)
- Modify: `cspell.json`, `.markdownlintignore`

- [ ] **Step 1: Clone the source to a temp location**

```bash
git clone --depth 1 https://github.com/WH-2099/mermaid-skill.git /tmp/mermaid-skill-src
ls /tmp/mermaid-skill-src/.claude/skills/mermaid/
```

Expected: `SKILL.md` + a `references/` directory.

- [ ] **Step 2: Vendor the skill into the project**

```bash
mkdir -p ".claude/skills/mermaid"
cp -r /tmp/mermaid-skill-src/.claude/skills/mermaid/. ".claude/skills/mermaid/"
ls -R ".claude/skills/mermaid/"
rm -rf /tmp/mermaid-skill-src
```

Expected: `.claude/skills/mermaid/SKILL.md` + `references/*.md` present. (Vendoring — not a submodule — keeps it on Windows+Cyrillic paths and immune to upstream loss, CC1.)

- [ ] **Step 3: Exclude the vendored skill from the doc-lint chain (MK1)**

Edit `.markdownlintignore` — append:

```
.claude/skills/mermaid/
```

Edit `cspell.json` — add `.claude/skills/mermaid/**` to the `ignorePaths` array (create the array if absent). Do **not** ignore `.claude/skills/` wholesale — the project's own skills (`q-item-add`, `rls-check`, `regression`) stay linted.

- [ ] **Step 4: Reload and verify the skill is discoverable**

```
/reload-plugins
```

Confirm a `mermaid` skill is now listed among available skills (project `.claude/skills/` is auto-discovered, like the existing 3 project skills). Confirm neither `settings.json` `hooks` block changed (MK2).

- [ ] **Step 5: Verify lint exclusion works**

```bash
git add .claude/skills/mermaid/ cspell.json .markdownlintignore
npx lefthook run pre-commit
```

Expected: cspell + markdownlint jobs do NOT report errors from `.claude/skills/mermaid/**`; all 8 jobs green.

- [ ] **Step 6: Commit**

```bash
git commit -m "feat(arch): vendor mermaid-skill into .claude/skills + lint-ignore (MK1)"
```

---

## Task 4: adr-kit controlled bootstrap (no `init`, no CLAUDE.md write)

**Files:**

- Create: `docs/adr/ADR-000-adr-process.md`, `ADR-001-frontend-stack-vue-vuetify.md`, `ADR-002-multitenancy-postgres-rls.md`
- Create: `.claude/adr-kit-guide.md`
- Modify (conditional): `cspell-words.txt`

- [ ] **Step 1: Create the ADR directory**

```bash
mkdir -p "docs/adr"
```

- [ ] **Step 2: Copy the adr-kit canonical guide**

```bash
cp ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/skills/adr/SKILL.md ".claude/adr-kit-guide.md"
```

If the guide lives elsewhere (e.g. `references/guide.md`), copy that. Reference-only — this replaces what `init` would write, without touching `CLAUDE.md` (AK2).

- [ ] **Step 3: Write ADR-000 — process / boundary meta-ADR**

Create `docs/adr/ADR-000-adr-process.md`:

```markdown
# ADR-000: ADR process and boundaries

- **Status:** Accepted
- **Date:** 2026-05-17
- **Deciders:** Дмитрий

## Context
Лидерра tracks open product/business/legal questions in
`docs/Открытые_вопросы_v8_3.md`. Adding adr-kit introduces `docs/adr/`, and the
mermaid-skill introduces `docs/architecture/`. Without boundaries they overlap.

## Decision
- **ADR (`docs/adr/`)** — a *closed technical/architecture decision*: stack,
  patterns, structural boundaries, data-layer strategy. One file per decision.
- **`docs/architecture/`** — diagrams and models (C4, system context). Visual,
  not normative; an ADR may embed or reference a diagram.
- **Открытые_вопросы registry** — *unresolved* product/business/legal questions
  awaiting an explicit "закрываем". Not machine-enforced.
- A registry question resolving into a technical choice MAY graduate into an ADR.

## Consequences
- No ADR for an item still open in the registry.
- ADR `## Enforcement` blocks target architecture-level constraints only — never
  re-encode larastan / eslint / squawk rules (AK4).
```

- [ ] **Step 4: Write ADR-001 — frontend stack (with Enforcement)**

Preferred: run `/adr-kit:adr "frontend stack Vue Vuetify"` and let the `adr-generator` agent emit the `## Enforcement` block in the exact v0.13 schema; paste the prose below. Verify key names (`forbid_import`/`forbid_pattern`/`require_pattern`) against `.claude/adr-kit-guide.md`. Create `docs/adr/ADR-001-frontend-stack-vue-vuetify.md`:

```markdown
# ADR-001: Frontend stack — Vue 3 + Vuetify 3

- **Status:** Accepted
- **Date:** 2026-05-17
- **Deciders:** Дмитрий

## Context
Лидерра's UI is Vue 3 + Vuetify 3. Tailwind, Inertia, Livewire, Filament, Flux
UI, Nova, Folio, Volt, Wayfinder are excluded (CLAUDE.md §5 п.2). framer-motion
is a technical block — React-only peerDep, crashes in Vue.

## Decision
All UI is Vue 3 SFC + Vuetify 3. No alternative UI framework or React-coupled
runtime library may be imported into `app/resources/js/`.

## Consequences
- Laravel Boost (Roster auto-detect) serves only relevant guidelines.
- A dependency pulling React / Tailwind / Inertia is rejected at pre-commit.

## Enforcement
```json
{
  "forbid_import": ["@inertiajs/vue3", "tailwindcss", "framer-motion", "react", "react-dom"],
  "applies_to": ["app/resources/js/**"]
}
```

```
(Adjust `applies_to` / key names to the schema in `.claude/adr-kit-guide.md`.)

- [ ] **Step 5: Write ADR-002 — multi-tenancy via RLS (documentation-only)**

Create `docs/adr/ADR-002-multitenancy-postgres-rls.md` — no Enforcement block:
```markdown
# ADR-002: Multi-tenancy via PostgreSQL Row-Level Security

- **Status:** Accepted
- **Date:** 2026-05-17
- **Deciders:** Дмитрий

## Context
Лидерра is a multi-tenant SaaS CRM. Tenant isolation must be enforced at the
database layer, not only in application code.

## Decision
Every tenant-scoped table carries RLS policies. Tenant id is set per transaction
via `SET LOCAL app.current_tenant_id` (`SetTenantContext` middleware). Five DB
roles; `crm_supplier_worker` is `BYPASSRLS` — queued jobs running as it MUST
filter `tenant_id` explicitly.

## Consequences
- New tenant-scoped tables require an RLS policy + a `db/CHANGELOG_schema.md`
  entry (CLAUDE.md §5 п.8).
- Verified by RLS smoke tests and the `rls-reviewer` agent — not by a regex gate.

## Enforcement
None — verified by tests and code review.
```

- [ ] **Step 6: Lint and validate**

```bash
npx markdownlint-cli2 "docs/adr/*.md"
npx cspell --no-progress --no-summary --no-gitignore "docs/adr/*.md"
```

Add valid project terms (`Vuetify`, `BYPASSRLS`, `Лидерра`, etc.) to `cspell-words.txt` if flagged. Then:

```
/adr-kit:lint docs/adr/
```

Expected: all three ADRs pass adr-kit's structural checks.

- [ ] **Step 7: Commit**

```bash
git add docs/adr/ .claude/adr-kit-guide.md cspell-words.txt
git commit -m "feat(adr): bootstrap docs/adr — ADR-000/001/002 + adr-kit guide"
```

---

## Task 5: Wire `adr-judge` into lefthook (pre-commit job 9)

**Files:** Create `tools/adr-judge.mjs`; Modify `lefthook.yml`

> Skip this entire task for **knowledge-only** integration (see "Severable scope").

- [ ] **Step 1: Inspect `adr-judge` and choose the invocation**

```bash
ls -la ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/bin/
head -20 ~/.claude/plugins/cache/rvdbreemen-adr-kit/*/bin/adr-judge
```

Decision:

- **(a) self-contained** node/`.mjs` script, no plugin-local `require` → vendor: `cp <plugin>/bin/adr-judge tools/adr-judge.mjs`. (Re-vendor after `/adr-kit:upgrade`.)
- **(b) has plugin-local deps** → write a 3-line `tools/adr-judge.mjs` wrapper that globs the newest `~/.claude/plugins/cache/rvdbreemen-adr-kit/*/bin/adr-judge` and `spawnSync`s it.

Primary path = (a). Record the branch taken.

- [ ] **Step 2: Add the lefthook job**

Edit `lefthook.yml` — append after the `eslint-vue` job (job 8), inside `pre-commit:` → `jobs:`:

```yaml
    # 9. adr-judge — declarative ADR Enforcement-block checker (Прил. Н #36).
    # Blocks the commit if a staged diff violates a forbid_*/require_* rule
    # in an `## Enforcement` block of any docs/adr/ADR-*.md.
    # Declarative regex only — no LLM calls, zero economy cost.
    - name: adr-judge
      glob: "*.{php,vue,ts,js,sql}"
      run: node tools/adr-judge.mjs {staged_files}
      fail_text: |
        adr-judge: a staged change violates a documented Architecture Decision.
        See the file:line citation above and the referenced docs/adr/ADR-*.md.
        If the ADR is wrong, update it (and its Enforcement block) first.
```

- [ ] **Step 3: Verify the job runs clean**

```bash
npx lefthook run pre-commit
```

Expected: 9 jobs now; `adr-judge` reports success.

- [ ] **Step 4: Red test — confirm the gate blocks**

```bash
echo "import { router } from '@inertiajs/vue3';" > app/resources/js/__adr_probe.ts
git add app/resources/js/__adr_probe.ts
npx lefthook run pre-commit
```

Expected: **FAIL** — `adr-judge` blocks on the `@inertiajs/vue3` import, citing `ADR-001` with file:line.

- [ ] **Step 5: Green test — clean up**

```bash
git restore --staged app/resources/js/__adr_probe.ts
rm app/resources/js/__adr_probe.ts
npx lefthook run pre-commit
```

Expected: PASS — all 9 jobs green, no probe file remaining.

- [ ] **Step 6: Commit**

```bash
git add lefthook.yml tools/adr-judge.mjs
git commit -m "feat(adr): wire adr-judge as lefthook pre-commit job 9 (AK1)"
```

---

## Task 6: Smoke #3 + #4, seed `docs/architecture/`

**Files:**

- Create: `docs/architecture/README.md`, `docs/architecture/c4-context.md`

- [ ] **Step 1: Create the architecture-diagrams directory + index**

```bash
mkdir -p "docs/architecture"
```

Create `docs/architecture/README.md`:

```markdown
# docs/architecture — system diagrams & models

C4 and architecture diagrams for Лидерра (Mermaid source). Generated with the
`mermaid` skill (`.claude/skills/mermaid/`). Decisions live in `docs/adr/`;
this directory holds the *visual* models. Map section: A6 «Архитектура систем».
```

- [ ] **Step 2: Smoke-test the mermaid skill — generate the seed C4 diagram**

Invoke the `mermaid` skill to author a C4 Context diagram. Create `docs/architecture/c4-context.md`:

````markdown
# C4 — System Context: Лидерра

```mermaid
C4Context
  title Лидерра — System Context
  Person(manager, "Менеджер арендатора", "Работает со сделками и лидами")
  Person(saasAdmin, "SaaS-админ", "Биллинг, инциденты, арендаторы")
  System(liderra, "Лидерра CRM", "Multi-tenant CRM: лиды, сделки, биллинг")
  System_Ext(supplier, "crm.bp-gr.ru", "Поставщик лидов (B1/B2/B3)")
  System_Ext(unisender, "Unisender Go", "SMTP-relay для email")
  System_Ext(yandex360, "Yandex 360", "SSO администраторов")
  Rel(manager, liderra, "Использует", "HTTPS")
  Rel(saasAdmin, liderra, "Администрирует", "HTTPS")
  Rel(liderra, supplier, "Импорт лидов / webhook", "HTTPS")
  Rel(liderra, unisender, "Отправка email", "SMTP")
  Rel(saasAdmin, yandex360, "Аутентификация", "OAuth")
```
````

Expected: the skill loads, the Mermaid `C4Context` block is syntactically valid (renders on GitHub natively — no `mmdc`/Chromium needed).

- [ ] **Step 3: Smoke-test the architecture-patterns skill**

Ask a sample architecture question (e.g. "what pattern fits the supplier-lead import pipeline?") and confirm the `architecture-patterns` skill activates and returns pattern guidance (layered / hexagonal / event-driven etc.). This is a functional smoke test — no file output required.

- [ ] **Step 4: Lint the new docs**

```bash
npx markdownlint-cli2 "docs/architecture/*.md"
npx cspell --no-progress --no-summary --no-gitignore "docs/architecture/*.md"
```

Add flagged valid terms to `cspell-words.txt`.

- [ ] **Step 5: Commit**

```bash
git add docs/architecture/ cspell-words.txt
git commit -m "feat(arch): seed docs/architecture — C4 Context diagram + index"
```

---

## Task 7: Unified normative registry sync (AK7 / AP2)

**Files:** Modify `docs/Tooling_v8_3.md`, `docs/Plugin_stack_rules_v1.md`, `docs/Pravila_raboty_Claude_v1_1.md`, `CLAUDE.md`, `docs/CHANGELOG_claude_md.md`

- [ ] **Step 1: Read the registry homes**

Read for exact insertion points and counters: `docs/Tooling_v8_3.md` Прил. Н §0 (counter "35") + §4.8/§4.9/§4.10; `docs/Plugin_stack_rules_v1.md` R10.1; `docs/Pravila_raboty_Claude_v1_1.md` §13.2.

- [ ] **Step 2: Add Tooling Прил. Н §4.11–§4.13**

Edit `docs/Tooling_v8_3.md`: add three subsections — `§4.11 #36 adr-kit`, `§4.12 #37 mermaid-skill`, `§4.13 #38 architecture-patterns` — all category **architecture-tooling** (off-phase). Note per tool: adr-kit (marketplace `rvdbreemen/adr-kit` v0.13.1 MIT; `adr-judge` via lefthook job 9, NOT adr-kit's git hook — AK1; `init`/`install-hooks` unused — AK1/AK2); mermaid-skill (`WH-2099/mermaid-skill` MIT, vendored standalone skill in `.claude/skills/mermaid/`); architecture-patterns (`secondsky/claude-skills` MIT, marketplace plugin). Add the bus-factor note (CC1). Bump §0 counter `35 → 38`; bump the Прил. Н version header.

- [ ] **Step 3: Add 3 PSR_v1 R10.1 rows**

Edit `docs/Plugin_stack_rules_v1.md`: add adr-kit, mermaid-skill, architecture-patterns rows to R10.1, category **architecture-tooling** (off-phase) — explicitly *outside* the UI-pool → no R6.0/R6.1 stack-filter, no R14 pipeline (same treatment as `claude-md-management`). Bump the PSR_v1 version header.

- [ ] **Step 4: Add the Pravila §13.2 note**

Edit `docs/Pravila_raboty_Claude_v1_1.md` §13.2: add a one-line architecture-tooling note covering the three tools, alongside the existing infrastructure note. Re-read Pravila §0/§13 first to keep section numbering consistent. Bump the Pravila version header.

- [ ] **Step 5: Update CLAUDE.md via the governed channel**

Invoke `/claude-md-management:claude-md-improver`. Apply: §3 title count (`35` → `38`), §1 priority-chain row 2b count (`35` → `38`), three new §3.3 rows `#36 adr-kit` / `#37 mermaid-skill` / `#38 architecture-patterns` (architecture-tooling, off-phase). The plugin also writes the `docs/CHANGELOG_claude_md.md` entry and bumps §0 cross-ref versions (Tooling / PSR_v1 / Pravila).

- [ ] **Step 6: Lint + commit**

```bash
npx markdownlint-cli2 "docs/Tooling_v8_3.md" "docs/Plugin_stack_rules_v1.md" "docs/Pravila_raboty_Claude_v1_1.md" "docs/CHANGELOG_claude_md.md"
npx cspell --no-progress --no-summary --no-gitignore "docs/Tooling_v8_3.md" "docs/Plugin_stack_rules_v1.md" "docs/Pravila_raboty_Claude_v1_1.md"
git add docs/Tooling_v8_3.md docs/Plugin_stack_rules_v1.md docs/Pravila_raboty_Claude_v1_1.md CLAUDE.md docs/CHANGELOG_claude_md.md cspell-words.txt
git commit -m "docs(arch): register adr-kit/mermaid/architecture-patterns #36-38 (AK7/AP2)"
```

---

## Task 8: Reflect the 3 tools on the map (close A6)

**Files:** Modify `docs/automation-graph.html`

- [ ] **Step 1: Read the structures to replicate**

In `docs/automation-graph.html` read, as templates, an existing plugin node — `claude_md_mgmt` — across `NODES`, `NODE_DETAILS`, `NODE_SECTION`, and the "Паспорт узла" date fields. Read an existing skill node for the mermaid-skill template. Note the current node count (~103-104) and the plugins-group size.

- [ ] **Step 2: Add three nodes**

Add to `NODES`, replicating the template shapes:

- `adr_kit` — label `adr-kit`, plugins group.
- `arch_patterns` — label `architecture-patterns`, plugins group.
- `mermaid_skill` — label `mermaid (skill)`, skills group.

Add matching `NODE_DETAILS` entries: adr_kit — "Плагин ADR. docs/adr/ + adr-judge в lefthook job 9."; arch_patterns — "Скил-плагин: справочник архитектурных паттернов."; mermaid_skill — "Vendored-скил: C4/architecture-диаграммы (Mermaid) → docs/architecture/." Паспорт: дата внедрения `2026-05-17` for all three.

- [ ] **Step 3: Map all three to section A6**

In `NODE_SECTION` add:

```js
adr_kit: 'A6', arch_patterns: 'A6', mermaid_skill: 'A6',
```

A6 «Архитектура систем» goes from 0 → 3 nodes — the section is no longer empty.

- [ ] **Step 4: Update header metrics**

Bump the node count in the map header/legend by 3 (e.g. `103 → 106`). Update the plugins-group and skills-group count comments in `NODE_SECTION`.

- [ ] **Step 5: Smoke-test the map**

```bash
npx stylelint docs/automation-graph.html
```

Open `docs/automation-graph.html` in a browser (Playwright MCP or local `http.server`): 0 JS console errors; the 3 new nodes render; clicking section `A6` highlights all three.

- [ ] **Step 6: Commit**

```bash
git add docs/automation-graph.html
git commit -m "feat(map): add adr_kit/mermaid/arch_patterns nodes — closes section A6"
```

---

## Task 9: Final regression & branch finish

**Files:** none modified

- [ ] **Step 1: Full pre-commit chain**

```bash
npx lefthook run pre-commit
```

Expected: all **9** jobs green (8 if knowledge-only).

- [ ] **Step 2: Confirm app code untouched — run the suites**

These tools change no `app/` code → suites must match the Task 1 baseline:

```bash
cd app && php artisan test --parallel
npm run test:vue
```

Expected: Pest and Vitest counts unchanged vs Task 1 baseline (0 regressions). Record exact counts.

- [ ] **Step 3: Confirm the economy/ruflo hook chain is intact**

Economy marker still appears; Stop verifier still runs; no plugin leaked a `hooks` entry into either `settings.json`.

- [ ] **Step 4: Pre-push checks**

```bash
./bin/gitleaks.exe detect --source . --no-banner --config .gitleaks.toml --redact
./bin/lychee.exe --config .lychee.toml "docs/**/*.md" "db/**/*.md" "*.md"
```

Expected: gitleaks 0 leaks; lychee 0 broken (new `docs/adr/*.md` + `docs/architecture/*.md` are scanned — fix or `.lychee.toml`-exclude any link).

- [ ] **Step 5: Finish the branch**

Invoke `superpowers:finishing-a-development-branch` — present the standard options. Do **not** push without an explicit user choice.

---

## Self-Review

**1. Spec coverage** — adr-kit: install (Task 2), bootstrap (Task 4), enforcement (Task 5). mermaid-skill: install+lint-ignore (Task 3), smoke+seed (Task 6). architecture-patterns: install (Task 2), smoke (Task 6). Conflict audit: AK1→T5, AK2→T4+T7.5, AK3→T4.3 (ADR-000), AK4→T4.4, AK5/AP1→T2.5, AK6→no task, AK7/AP2→T7, AK8→no task, MK1→T3.3, MK2→T3.4, MK3→no task, CC1→T7.2. Map A6 closure→T8. No gaps.

**2. Placeholder scan** — Task 5 Step 1 and Task 8 Step 1 are *decision/read-template* steps with concrete criteria, not "TBD" (the adr-judge dep shape and the live `claude_md_mgmt` node shape are not knowable without install / without reading the 2400-line map). All commands exact; ADR + C4 + README content shown in full.

**3. Consistency** — `adr-judge` invoked uniformly (`node tools/adr-judge.mjs`); paths consistent (`docs/adr/`, `docs/architecture/`, `.claude/skills/mermaid/`); tool counter `35 → 38` consistent T7↔T8; node ids `adr_kit`/`mermaid_skill`/`arch_patterns` consistent T8 Steps 2-3; plugin ids `adr-kit@rvdbreemen-adr-kit` / `architecture-patterns@claude-skills` consistent.

---

## Execution Handoff

Plan complete. Two execution options:

1. **Subagent-Driven** — fresh subagent per task, two-stage review. *Caveat:* Tasks 2, 3 (slash commands `/plugin …`, `/reload-plugins`), Task 4 Step 6 (`/adr-kit:lint`), Task 6 Steps 2-3 (skill invocations) and Task 7 Step 5 (`claude-md-management`) are main-session-bound — those steps stay with the controller.
2. **Inline Execution** — `superpowers:executing-plans`, batch with checkpoints. **Recommended here** — the integration is install/config/docs-heavy with many interactive main-session steps.

Open question for the user: **full integration** (incl. Task 5 — adr-judge pre-commit enforcement) or **knowledge-only** (skip Task 5 — ADR store + diagrams + patterns skill, no commit gate)?
