Restructure deliverable from 4 to 6 chapters:
- §2 (new): score table promoted from technical annex to top of doc for
immediate visual proof of impact (tested with local-business clients —
converts "what did I pay for?" doubt within 30 seconds).
- §4 (new): NAP table promoted from §7 annex so client reads identity
values (name, address, phone, hours, categories, short description)
BEFORE attacking §5 todo list. Prevents 10-different-description drift
across external platforms that degrades Google's NAP-consistency signal.
- §5 (todo) and §6 (tech details) renumbered; §7/§8 annexes still optional.
Pandoc bumped to gfm+gfm_auto_identifiers so internal anchor links like
[§4](nap) resolve in the rendered HTML/PDF.
Co-Authored-By: Claude <noreply@anthropic.com>
Two distinct render bugs producing overlapping text on multi-page PDFs:
1. Bare-URL duplication. The print stylesheet injects `(href)` after every
external link via `a[href^="http"]::after`. When pandoc/marked
auto-links a bare URL or renders `[X](X)`, the visible text already
equals the href, so the pseudo-element produces "URL (URL)" and the
trailing duplicate wraps onto the next line, colliding with the
following block (e.g. "https://pagespeed.web.dev/ (https://...)" then
"• Ouvrir, taper l'URL...").
Fix: post-process the body HTML in handover-to-pdf.sh; tag every
`<a href="X">X</a>` (text == href, ignoring trailing slash + case)
with `class="bare-url"`, and exclude `a.bare-url::after` from the
URL-injection rule. Named links still get `(URL)` for print legibility.
Belt-and-braces: add `white-space: nowrap` and `break-inside: avoid`
on the remaining `::after` so future long URLs cannot wrap across
page boundaries either.
2. List item splitting across page boundary. `li` had only
`orphans/widows: 3` and no `break-inside`, so a long item could put
its bullet on page N and its text on page N+1, overlapping unrelated
content. Heading-to-first-block adjacency was also unprotected, so
"heading at bottom of page A / intro paragraph or first bullet at top
of page B" could produce visual overlap during reflow.
Fix: add `li { page-break-inside: avoid; break-inside: avoid; }` and
`h{1..4} + p|ul|ol { break-before: avoid; }` so list items stay
intact and intros stay glued to their heading.
Verified end-to-end: rendered sample md with bare URL + named link +
heading-followed-by-list straddling a page break; pdftotext shows each
URL once, no orphaned bullets, no `::after` warning from weasyprint.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three bugs surfaced on the LIVRAISON.pdf test render:
1. **MD→HTML conversion** — host had no pandoc, no python-markdown, fell
back to `npx marked < "$src"`. marked CLI 16.x ignores stdin and
dumps its own cli.js source. Resulting PDF body = marked's binary
source (`#!/usr/bin/env node`, `Marked CLI`, copyright). Fix:
`npx --yes marked --gfm -i "$src"` (file path via -i, not stdin).
2. **Cover background** — original cream `#F5F0EB` + 8mm green stripe
was washed out. Iterated to white-pure bg with subtle radial
sage/forest tints, black-deep title, green-forest accents
(eyebrow, meta labels, footer, border). Solid green-dark tried
first then rejected (too heavy for long client-facing doc).
3. **Default logo** — SVG `logo-horizontal.svg` rendered cream-toned,
blended into bg. Switched LOGO_URL default to
`https://zenquality.fr/assets/logo-horizontal-1024.png`.
Also added test-artifact gitignore rules for LIVRAISON.* / HANDOVER.*
project-local renders.
Verified: regenerated LIVRAISON.pdf → 164 KB, 19 pages, full content
rendered, white cover with black title + green-forest accents +
visible PNG logo.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
End-to-end pipeline that hardens the project, commits, pauses for
deploy, validates the live site, then generates a non-technical client
deliverable (LIVRAISON.md / HANDOVER.md):
1. /seo (SEO+GEO) and /harden run in parallel with auto-fix loops
until each scores >=17/20.
2. /commit-change + push if changes were made.
3. Pause to tell the user what to deploy and wait for confirmation.
4. /validate against the live site.
5. Per-audit gate >=17/20 — stop and analyze if any below.
6. Write client doc with before/after score table + owner-maintenance
checklist.
Reads git history + .claude/memory/ registries for context. For
local-business projects, appends a manual NAP-consistency platform
checklist (Google Business, Pages Jaunes, Yelp, Facebook, Instagram,
TikTok, Apple Maps, Bing Places, TripAdvisor). Optional build/deploy
chapter on prompt.
Adds skills/client-handover/SKILL.md (slash-command entrypoint),
skills/client-handover/checklists/seo-geo-manual.md (NAP checklist),
agents/client-handover-writer.md (orchestrator agent).
Co-Authored-By: Claude <noreply@anthropic.com>
Pattern: toggle scripts for tools with separate install + symlink steps
must check 3 states (disabled-dir, enabled-dir, source-only), not 2.
Source-only branch creates symlink in place rather than failing. Error
messages name the path checked, not just the abstract tool name, so
callers can diagnose install vs symlink state without rereading the
script. Symmetric pairs (enable/disable) must both cover the same
lifecycle states — missing state in one half = silent dead end.
Co-Authored-By: Claude <noreply@anthropic.com>
`enable <tool>` for npx/external skills (darwin-skill, find-skills,
emil-design-eng) only handled two states: symlink in skills-disabled/
(move) and symlink in skills/ (already enabled). Missed the state
right after `make plugin` where the source dir exists at
~/.agents/skills/<tool> but no symlink has been created yet — first
run errored "not installed — run: make plugin" misleadingly.
Add a third branch: when the resolved source dir exists, create the
symlink in place. Resolve source path per tool (skills-external for
emil-design-eng, ~/.agents/skills for darwin-skill/find-skills). Error
message now names the path checked so the caller can verify install
vs symlink state without rereading the script.
Co-Authored-By: Claude <noreply@anthropic.com>
Auto-discover what the project actually has instead of a fixed doc list:
root files (incl. DEPLOY.md, SECURITY.md, ARCHITECTURE.md, ROADMAP.md),
docs/**, and .claude/{tasks,audits,memory}/.
Detect stack (Node/Python/Rust/Go/Ruby/PHP/Dart/.NET) and deploy
complexity (NONE/TRIVIAL/NON_TRIVIAL) to drive doc-needs:
- Propose DEPLOY.md only when non-trivial (Docker, fly.toml, k8s,
multi-stage CI).
- Propose inlining/removing DEPLOY.md when deploy is trivial.
- Enforce README presence with typical GitHub layout.
Add CREATE/REMOVE proposal categories to the validation gate. Update
auto-mode to map deploy artifacts to DEPLOY.md and decisions.md
architectural changes back to CLAUDE.md/README.
Sync skills/doc/SKILL.md description + triggers to match.
Co-Authored-By: Claude <noreply@anthropic.com>
Disable ui-ux-pro-max (off-profile for current work) and enable
pr-review-toolkit so /review and the toolkit subagents are available.
Co-Authored-By: Claude <noreply@anthropic.com>
Matcher was Glob|Grep — those tool inputs have no `command` field, so
the hint never fired. Switch to Bash matcher and gate on the actual
command substring (grep, rg, ripgrep, find, fd, ack, ag) so the
graphify hint only injects when Claude is about to scan raw files.
Co-Authored-By: Claude <noreply@anthropic.com>
Tell Claude to read graphify-out/GRAPH_REPORT.md before answering
architecture questions, prefer graphify query/path/explain over grep
for cross-module questions, and run graphify update . after code edits.
Co-Authored-By: Claude <noreply@anthropic.com>
- GitHub URL clone support (single + multi-repo merge)
- uv tool detection ahead of pipx shebang
- Optional Kimi K2.6 backend via MOONSHOT_API_KEY
- Discrete confidence rubric (0.55/0.65/0.75/0.85/0.95) replaces continuous range
- Aggregated community view for graphs >5000 nodes
- Manifest persistence after --update so next run diffs against current state
- Video file support, rationale-as-attribute (not separate node)
Co-Authored-By: Claude <noreply@anthropic.com>
Append BDR-009 entry + Index update in decisions.md, plus 2026-05-05
heading in journal.md covering the 4-commit batch.
Catches Index up to BDR-008 (was missing 007/008 entries despite
already-written sections).
Co-Authored-By: Claude <noreply@anthropic.com>
/caveman:compress writes a human-readable backup as <file>.original.md
before overwriting. Backups are recoverable via git history (the
pre-compression state lives in the previous commit), so committing
them duplicates content and bloats the repo.
Globbing on *.original.md catches all compressed registries plus
CLAUDE.original.md.
Co-Authored-By: Claude <noreply@anthropic.com>
Add "Format — registries ALWAYS caveman" rule alongside existing
English-only rule. All writes to .claude/memory/*.md (decisions,
learnings, blockers, journal, evals) must drop articles/filler/hedging
while preserving technical terms, IDs, dates, and code blocks exact.
Rationale: registries load every session start — caveman cuts ~40%
input tokens with zero loss of substance. Applies to direct writes and
skill-driven CAPITALIZE steps (close, ship-feature, feat, bugfix,
hotfix, commit-change). Existing entries: compress on demand via
/caveman:compress <file>.
Self-applied: CLAUDE.md prose itself compressed in same pass.
Co-Authored-By: Claude <noreply@anthropic.com>
Toggle example-skills@anthropic-agent-skills off — not used in active
profiles, reduces session-start skill enumeration.
Co-Authored-By: Claude <noreply@anthropic.com>
- BDR-007: Skill profiles partition gstack by usage (v1, skill-only).
Decision to ship lib/profile.sh + symlink-based toggle for skills,
with plugin/MCP entries advisory in v1. Rationale: the existing
toggle-external.sh enable|disable gstack is too coarse — it
disables checkpoint/ship/learn alongside design skills. Profiles
hide the irrelevant skills without uninstalling the gstack repo.
Alternatives rejected: forking SKILL.md to strip the gstack
preamble (re-fork on every upgrade — preamble already degrades
gracefully via `|| true`); per-skill toggle via claude plugin
enable/disable (gstack skills are not marketplace plugins);
removing symlinks (lossy if user has local edits).
- BDR-008: Profile system v2 — extend to plugins + MCPs + CLIs.
Reverses the "advisory only" stance from BDR-007 alternative #4.
User feedback: pure-skill toggling left ui-ux-pro-max/magic always
loaded regardless of profile, so passive token cost didn't drop
enough on profile switch. Solution: real claude plugin enable/
disable for an explicit MANAGED_PLUGINS allowlist (3 entries) +
PROTECTED_PLUGINS denylist for always-on (caveman, security-
guidance, superpowers). MCP magic delegated to toggle-external.sh.
Other MCPs stay advisory because each needs specific config. Adds
4 new profiles: web, seo, web-full, backend.
- Journal: 2026-05-04 entry summarizing the v1 ship, then a follow-up
block for the v2 extension (new profiles, plugin auto-toggle, tie-
breaker for `current`).
- TODO.md: marked done — v1 (Skill profiles) section and v2 (Profile
system v2 — extension plugins/MCPs/CLIs) section, both with their
full subtask lists.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ship lib/profile.sh + 9 profiles in lib/profiles/. A profile is a
plain-text file listing items + types (gstack | personal | external |
plugin@<marketplace> | mcp | cli). `profile set <name>` enables the
listed items and disables the rest:
- gstack/personal/external skills: symlink toggle skills/ ↔
skills-disabled/ (gstack__<name> prefix to avoid collisions; no
prefix for personal/external).
- plugins typed `plugin@<marketplace>`: actually toggled via
`claude plugin enable|disable <name>@<marketplace>`. Allowlist:
MANAGED_PLUGINS = ui-ux-pro-max, plugin-dev, pr-review-toolkit.
Denylist: PROTECTED_PLUGINS = caveman, security-guidance,
superpowers (always-on, never disabled even if absent from a
profile).
- mcp magic: delegated to lib/toggle-external.sh which already
handles the MAGIC_API_KEY env lookup. Other MCPs stay advisory.
- cli (rtk, gsd, ctx7, graphify): status-only, never auto-installed.
Profiles shipped:
web public website work — frontend + content + light dev
seo SEO + GEO + W3C audit (search/AI indexability + a11y)
web-full production website end-to-end (web ∪ seo ∪ qa-only/canary)
backend backend / API / system dev — no design, no SEO
design visual QA, design systems, mockups, polish
dev daily code work — features, fixes, refactor, ship
qa site testing, perf, canary, validation
audit comprehensive audit — security + SEO + perf + health
minimal strip all gstack skills (quiet session)
Commands:
profile list / show <name> / current / apply <name> / set <name> /
reset / diff <a> <b>
`current` heuristic returns "full" when nothing is disabled, otherwise
picks the profile with the highest available-ratio (counts both
"enabled" and "installed" — the latter for CLIs). Tiebreaker: larger
profile total wins, so web-full beats web at a 100% tie.
`reset` re-enables every gstack skill but does NOT touch plugins —
the user re-enables a managed plugin manually or via `apply <profile>`.
This is documented in the trailing info line.
Integration:
- skills/profile/SKILL.md — `/profile` slash command, lists profiles,
documents the per-type mechanism, points at lib/profile.sh.
- agents/plugin-advisor.md — DETECT phase calls `profile current`,
OUTPUT adds a PROFILE line, and TOGGLING EXTERNAL TOOLS gains a
"Skill profiles" section with a signal → profile recommendation
table.
- lib/toggle-external.sh — header pointer to profile.sh for fine-
grained activation (toggle-external still owns whole-gstack and
magic-MCP toggles).
- Makefile — `make profile cmd="set <name>"`, profile-list,
profile-current, profile-reset.
Tested end-to-end: `set web` enables ui-ux-pro-max + magic; `set seo`
disables ui-ux-pro-max; `set minimal` disables ui-ux-pro-max but
spares always-on plugins; `reset` restores all 64 skills; shellcheck
clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- BDR-006: Caveman as 4th always-on plugin (output compression, sym
with rtk's input compression). Full install rationale, alternatives
rejected, caveats around path normalization + gitignore.
- LRN-005: claude plugin install does NOT enable — explicit
claude plugin enable required for ALWAYS-ON plugins. Pattern: read
enabledPlugins, never hardcode plugin names in status displays.
- LRN-006: caveman-shrink (and any MCP middleware proxy) needs an
upstream wrapper. Bare registration fails health checks. Pattern:
register under derived names (proxy-upstream), don't auto-register.
- Journal: 2026-05-03 entry summarizing the session.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two interlocked bugs masking each other:
1. install-plugins.sh installed but never enabled marketplace plugins.
`claude plugin install` only writes to ~/.claude/plugins/cache; without
a separate `claude plugin enable` the plugin sits dormant in the
user's enabledPlugins map. security-guidance and superpowers shipped
as ALWAYS-ON in CLAUDE.md/README/installer banner but in practice
landed disabled on every fresh install.
2. session-start.sh hardcoded the literal "security-guidance rtk
superpowers" in the ✅ ON row, so the misleading banner agreed with
the misleading documentation. The bug stayed invisible.
Fixes:
- install-plugins.sh now calls enable_plugin (added in the caveman
commit) for security-guidance and superpowers immediately after
install. Idempotent: skips if already in enabledPlugins.
- session-start.sh builds the ALWAYS-ON row dynamically from RTK
binary detection + plugin_enabled() lookups against
settings.json. Plugins that are not enabled are omitted, so the
banner reflects reality. Wider strings split across two lines like
the toggle row.
- settings.json: ship security-guidance and superpowers in
enabledPlugins so this user's machine matches the contract until
install-plugins.sh runs again.
Out of scope (separate bug, not addressed here): the marketplace-aware
detect_security_guidance / detect_plugin_dev cache scans miss plugins
nested under cache/<marketplace>/<plugin>/<version>/. They aren't on
the always-on path so the symptom is hidden — left for a follow-up.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wires JuliusBrussee/caveman into the always-on tier alongside
security-guidance and superpowers. Caveman compresses Claude's output
tokens (~75%) by speaking like a caveman while keeping technical
substance. Three layers:
1. Plugin (caveman@caveman, marketplace JuliusBrussee/caveman)
— adds /caveman, /caveman-commit, /caveman-review, /caveman-stats,
/caveman-help, /cavecrew, /compress + 3 cavecrew agents +
SessionStart/UserPromptSubmit hooks from the plugin path.
2. Standalone hooks (statusline + stats badge) deployed by
caveman's own hooks/install.sh into ~/.claude/hooks/. Paths in
settings.json normalized to ~/.claude/hooks/... so this user's
home dir doesn't leak across machines.
3. caveman-shrink MCP proxy — NOT auto-registered. The bare proxy
fails health checks because it requires an upstream MCP server
to wrap. install-plugins.sh STEP 5.5 prints a snippet showing how
to register a wrapped entry (e.g. caveman-shrink-fs) when the user
decides which upstream to compress.
New helper enable_plugin() for explicit always-on activation —
'claude plugin install' only copies into cache, doesn't write
enabledPlugins. Idempotent via Python json check.
doctor.sh adds detect_caveman / detect_caveman_hooks / detect_caveman_shrink
checks plus a 300t passive-cost adder. update-all.sh refreshes hook
files via the upstream installer's --force mode.
.gitignore covers caveman runtime files materialized into hooks/
because ~/.claude/hooks is symlinked to this repo.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
doctor.sh exited at the gstack-skills-count step on machines where
~/.claude/skills/gstack does not contain a skills/ subdirectory (e.g.
when the gstack submodule layout puts skills directly at root). Under
set -o pipefail, find's non-zero exit propagated through wc | tr,
killing the script before it reached the prerequisites/plugins/budget
sections.
Wrap the find in a brace group with `|| true` so the pipe stays
zero-exit and downstream sections run.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
BDR-005: motion as default animation library; plugin-advisor stays
read-only (orchestrators own install).
LRN-004: framer-motion was rebranded `motion` in Nov 2024 — single
package for React/Svelte/vanilla, separate `motion-v` for Vue. React
Native still needs react-native-reanimated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
