docs(plan): A6 architecture-tooling integration plan (executed)
The 9-task plan for the adr-kit / mermaid-skill / architecture-patterns integration. Committed alongside the work it produced (commits b15a94a..93ac262). cspell-words.txt: +inertiajs +Sev (plan-file vocabulary). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Дмитрий
@@ -1318,4 +1318,6 @@ MMM
|
||||
Nygard
|
||||
DDD
|
||||
mmdc
|
||||
inertiajs
|
||||
Sev
|
||||
вендоренный
|
||||
|
||||
@@ -0,0 +1,659 @@
|
||||
# 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)?
|
||||
Reference in New Issue
Block a user