open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

chore(marketplace): thin catalog to manifest + docs (polyrepo migration complete)

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-06-18 10:00:47 +02:00
commit e84dffd2b0
2011 changed files with 57 additions and 478197 deletions
Download patch file Download diff file Expand all files Collapse all files

83
CLAUDE.md
View file

File diff suppressed because one or more lines are too long

20
CONVENTIONS.md Normal file
View file

@ -0,0 +1,20 @@
# Conventions — ktg-plugin-marketplace catalog
> Extracted from the marketplace CLAUDE.md (D6). These are the marketplace-wide conventions
> every plugin repo inherits under fork-and-own. See GOVERNANCE.md for the governance model.
## Konvensjoner
- **Språk:** Norsk dialog, engelsk kode/docs
- **Commits:** Conventional Commits — `type(scope): description`
- **Git:** Forgejo (`git.fromaitochitta.com/open/ktg-plugin-marketplace`). Aldri GitHub.
- **Hooks:** Alltid Node.js (.mjs), aldri bash. Cross-platform.
- **Avhengigheter:** Null npm dependencies i hooks/scannere. `node:test` for tester.
- **Bidrag:** Issues velkommen som signaler. PRs ikke akseptert. Fork-and-own er anbefalt adopsjonsmodell — se `GOVERNANCE.md`.
- **Lisens:** MIT, alle plugins
- **Docs ved endring (OBLIGATORISK):** Enhver feature-endring som pusher til Forgejo MÅ oppdatere alle tre doc-nivåer i SAMME commit eller umiddelbart etter:
1. Plugin `README.md` — detaljert dokumentasjon av endringen
2. Plugin `CLAUDE.md` — arkitektur/oversikt
3. Rot-`README.md` — marketplace-landingssiden (`git.fromaitochitta.com/open/ktg-plugin-marketplace`)
- **Playground-oppdatering:** Ved endring av plugin playground HTML eller delt design-system, følg prosedyren i `shared/PLAYGROUND-MAINTENANCE.md` (4 spor: HTML-endring, DS-endring, screenshots, release).

44
README.md
View file

@ -20,7 +20,7 @@ Each plugin keeps its own full README and CHANGELOG; this page is just the catal
## Plugins
### [LLM Security](plugins/llm-security/) `v7.7.2`
### [LLM Security](https://git.fromaitochitta.com/open/llm-security) `v7.7.2`
Security scanning, auditing, and threat modeling for agentic AI projects. Built on OWASP LLM Top 10 (2025), OWASP Agentic AI Top 10, and Google DeepMind's AI Agent Traps taxonomy.
@ -31,11 +31,11 @@ Security scanning, auditing, and threat modeling for agentic AI projects. Built
Key commands: `/security posture`, `/security audit`, `/security scan`, `/security ide-scan`, `/security threat-model`
6 agents · 23 scanners · 9 hooks · 1822 tests · [Full documentation →](plugins/llm-security/README.md)
6 agents · 23 scanners · 9 hooks · 1822 tests · [Full documentation →](https://git.fromaitochitta.com/open/llm-security)
---
### [Config-Audit](plugins/config-audit/) `v5.1.0`
### [Config-Audit](https://git.fromaitochitta.com/open/config-audit) `v5.1.0`
Configuration intelligence for Claude Code. Claude reads instructions from 7+ file types across multiple scopes; this plugin tells you what's wrong, what's missing, what's silently conflicting, what's actually loaded, and where you're burning tokens.
@ -47,11 +47,11 @@ Configuration intelligence for Claude Code. Claude reads instructions from 7+ fi
Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-audit fix`, `/config-audit whats-active`, `/config-audit tokens`
6 agents · 12 scanners · 18 commands · 792+ tests · [Full documentation →](plugins/config-audit/README.md)
6 agents · 12 scanners · 18 commands · 792+ tests · [Full documentation →](https://git.fromaitochitta.com/open/config-audit)
---
### [Voyage](plugins/voyage/) `v5.1.1`
### [Voyage](https://git.fromaitochitta.com/open/voyage) `v5.1.1`
A six-command planning pipeline with specialized agent swarms, adversarial review, and zero-friction multi-session resumption. Renamed from `ultraplan-local`/`/ultra*-local` to avoid collision with Anthropic's `/ultraplan` and `/ultrareview`. No cloud dependency.
@ -64,11 +64,11 @@ A six-command planning pipeline with specialized agent swarms, adversarial revie
Per-phase effort and model dialog; `/trekbrief`, `/trekplan`, and `/trekreview` render an operator-annotation HTML view you can mark up and copy back into Claude.
23 agents · 6 commands (+1 helper) · 5 hooks · 500+ tests · [Full documentation →](plugins/voyage/README.md) · [Migration guide](plugins/voyage/MIGRATION.md)
23 agents · 6 commands (+1 helper) · 5 hooks · 500+ tests · [Full documentation →](https://git.fromaitochitta.com/open/voyage) · [Migration guide](https://git.fromaitochitta.com/open/voyage/src/branch/main/MIGRATION.md)
---
### [AI Psychosis](plugins/ai-psychosis/) `v1.2.0`
### [AI Psychosis](https://git.fromaitochitta.com/open/ai-psychosis) `v1.2.0`
Meta-awareness tools that counteract sycophancy, reinforcement loops, and compulsive AI interaction patterns. AI assistants are structurally optimized to be agreeable; this surfaces when that becomes a problem.
@ -79,11 +79,11 @@ Meta-awareness tools that counteract sycophancy, reinforcement loops, and compul
Research-informed thresholds. Alerts are progressive and never blocking. Privacy-first: prompt text is never logged.
1 skill · 1 command · 4 hooks · [Full documentation →](plugins/ai-psychosis/README.md)
1 skill · 1 command · 4 hooks · [Full documentation →](https://git.fromaitochitta.com/open/ai-psychosis)
---
### [Graceful Handoff](plugins/graceful-handoff/) `v2.1.0`
### [Graceful Handoff](https://git.fromaitochitta.com/open/graceful-handoff) `v2.1.0`
Auto-trigger session handoff at context threshold, so summarizing state, committing work, and writing a continuation prompt don't get rushed when you run low. Manual `/graceful-handoff` always works as backup. Built for Opus 4.7.
@ -94,11 +94,11 @@ Auto-trigger session handoff at context threshold, so summarizing state, committ
Key command: `/graceful-handoff [topic-slug] [--no-commit] [--no-push] [--dry-run]`
3 hooks · 1 skill · 1 pipeline · 57 tests · [Full documentation →](plugins/graceful-handoff/README.md)
3 hooks · 1 skill · 1 pipeline · 57 tests · [Full documentation →](https://git.fromaitochitta.com/open/graceful-handoff)
---
### [MS AI Architect](plugins/ms-ai-architect/) `v1.15.0` `🇳🇴 Norwegian`
### [MS AI Architect](https://git.fromaitochitta.com/open/ms-ai-architect) `v1.15.0` `🇳🇴 Norwegian`
Microsoft AI solution architecture guidance for Norwegian public sector and enterprise, through Cosmo Skyberg — a structured architect persona who understands the problem before recommending technology.
@ -110,11 +110,11 @@ Microsoft AI solution architecture guidance for Norwegian public sector and ente
Key commands: `/architect`, `/architect:ros`, `/architect:security`, `/architect:dpia`, `/architect:utredning`, `/architect:cost`
12 agents · 25 commands · 5 skills (387 docs) · 2 hooks · [Full documentation →](plugins/ms-ai-architect/README.md)
12 agents · 25 commands · 5 skills (387 docs) · 2 hooks · [Full documentation →](https://git.fromaitochitta.com/open/ms-ai-architect)
---
### [LinkedIn Studio](plugins/linkedin-studio/) `v0.4.0`
### [LinkedIn Studio](https://git.fromaitochitta.com/open/linkedin-studio) `v0.4.0`
Build authentic LinkedIn authority through algorithmic understanding, strategic consistency, and AI-assisted content creation.
@ -129,11 +129,11 @@ Build authentic LinkedIn authority through algorithmic understanding, strategic
Key commands: `/linkedin:create` + `/linkedin:measure` (journey front-doors), `/linkedin:onboarding`, `/linkedin:post`, `/linkedin:newsletter`, `/linkedin:report`
19 agents · 29 commands (five journeys) · 6 skills · 9 hooks · [Full documentation →](plugins/linkedin-studio/README.md)
19 agents · 29 commands (five journeys) · 6 skills · 9 hooks · [Full documentation →](https://git.fromaitochitta.com/open/linkedin-studio)
---
### [OKR for Public Sector](plugins/okr/) `v1.3.0` `🇳🇴 Norwegian`
### [OKR for Public Sector](https://git.fromaitochitta.com/open/okr) `v1.3.0` `🇳🇴 Norwegian`
Turn strategy into measurable goals. An AI coach that learns your organization once, then builds on that knowledge so you spend time on strategy, not re-explaining context.
@ -145,11 +145,11 @@ Turn strategy into measurable goals. An AI coach that learns your organization o
Key commands: `/okr:skriv`, `/okr:kvalitet`, `/okr:gap`, `/okr:analyse`, `/okr:kaskade`, `/okr:governance`
7 agents · 10 commands · 4 hooks · [Full documentation →](plugins/okr/README.md)
7 agents · 10 commands · 4 hooks · [Full documentation →](https://git.fromaitochitta.com/open/okr)
---
### [Human-Friendly Style](plugins/human-friendly-style/) `v1.1.0`
### [Human-Friendly Style](https://git.fromaitochitta.com/open/human-friendly-style) `v1.1.0`
A shared Claude Code [output style](https://code.claude.com/docs/en/output-styles) used across this marketplace, so the conversation feels like dialog rather than a console dump.
@ -160,11 +160,11 @@ A shared Claude Code [output style](https://code.claude.com/docs/en/output-style
Optional and works alongside every other plugin. Activate with `/config` → Output style → Human-Friendly.
1 output style · [Full documentation →](plugins/human-friendly-style/README.md)
1 output style · [Full documentation →](https://git.fromaitochitta.com/open/human-friendly-style)
---
### [Claude Design](plugins/claude-design/) `v0.1.0`
### [Claude Design](https://git.fromaitochitta.com/open/claude-design) `v0.1.0`
End-to-end facilitator for prompting Claude Design (`claude.ai/design`). Walks you from raw idea through prompt drafting, delivery, and iteration coaching. The output is the prompt; the artifact gets built in Claude Design.
@ -172,13 +172,13 @@ End-to-end facilitator for prompting Claude Design (`claude.ai/design`). Walks y
- **Evidence-graded references** — five foundation plus eight per-preset references, each carrying an Anthropic-domain citation
- **Complements Anthropic's official design plugin** — this covers idea → prompt → iterate; theirs covers critique → handoff, with zero command overlap (enforced by test)
1 skill · 13 reference files · 5 tests · [Full documentation →](plugins/claude-design/README.md)
1 skill · 13 reference files · 5 tests · [Full documentation →](https://git.fromaitochitta.com/open/claude-design)
---
## Shared infrastructure
### [Playground Design System](shared/playground-design-system/) `v0.1`
### [Playground Design System](https://git.fromaitochitta.com/open/playground-design-system) `v0.6.0`
Shared design system for plugin Playgrounds — the visual self-service UIs that complement terminal slash-commands. Aksel/Digdir-aligned, WCAG 2.1 AA, light + dark themes, print-ready. Used by `ms-ai-architect`, `okr`, `llm-security`, `voyage`, and `config-audit`.
@ -186,7 +186,7 @@ Shared design system for plugin Playgrounds — the visual self-service UIs that
- **Privacy-first** — all fonts self-hosted, zero CDN requests, works offline and behind air-gapped firewalls
- **Vendoring sync** — `scripts/sync-design-system.mjs <plugin>` keeps each plugin standalone; a SHA-256 manifest detects local drift
[Full documentation →](shared/playground-design-system/README.md) · [Browse showcase](shared/playground-examples/index.html)
[Full documentation →](https://git.fromaitochitta.com/open/playground-design-system) · [Browse showcase](https://git.fromaitochitta.com/open/playground-design-system/src/branch/main/playground-examples/index.html)
---

8
plugins/ai-psychosis/.claude-plugin/plugin.json
View file

@ -1,8 +0,0 @@
{
"name": "ai-psychosis",
"version": "1.2.0",
"description": "Meta-awareness tools for healthy AI interaction patterns. Detects reinforcement loops, scope escalation, narrative crystallization, and other compulsive patterns.",
"author": { "name": "Kjell Tore Guttormsen" },
"license": "MIT",
"repository": "https://git.fromaitochitta.com/open/ai-psychosis"
}

18
plugins/ai-psychosis/.gitignore vendored
View file

@ -1,18 +0,0 @@
# Environment
.env
.env.*
# Claude Code
*.local.md
.claude/
# macOS
.DS_Store
# Node (for future use)
node_modules/
dist/
# Data/logs
data/
*.jsonl

239
plugins/ai-psychosis/CHANGELOG.md
View file

@ -1,239 +0,0 @@
# Changelog
All notable changes to this project will be documented in this file.
## [1.2.0] — 2026-05-01
Research-paper-driven detector update. Implements operational findings from
Anthropic's "How people ask Claude for guidance" Appendix (April 2026).
### Added
- **User-information detector** — three-class signal (`yes_people` /
`yes_digital` / `no`) following the paper's page-11 finding that human
contact is the strongest disempowerment signal. ~32 patterns covering
therapist/friend/mentor (yes_people), search/AI/forums (yes_digital),
and explicit isolation phrases (no). Sticky upward priority.
- **Validation-seeking detector** — separate from `val_flags`. Targets
reality-testing ("am I crazy?"), pre-committed stance + confirmation,
and side-taking pressing. ~12 patterns.
- **Tier-1 user-info isolation alert** — fires per session when
`user_info_class === 'no'` + high-stakes domain + `turn_count >= 15`.
- **Tier-2 cross-session isolation alert** — fires at `SessionStart` when
the last 3 end records all classify as `no` in high-stakes domains.
Bounded `readRecentEndRecords()` tail-scan in `lib.mjs` keeps this
scalable to 50K+ session histories.
- **8 new paper-grounded domain patterns** — `legal`, `parenting`, `health`,
`financial`, `professional`, `spirituality`, `consumer`, `personal_dev`.
Total domains 4 → 9.
- **Pushback re-contextualization (alert)** — v1.1.0 only counted; v1.2 adds
the alert with domain awareness:
- Relationship/spirituality: pushback signals validation-pressing — alert.
- Legal/parenting/health/financial/professional: pushback is healthy
self-advocacy — no alert.
- Otherwise: conservative default — alert.
- **Domain-stakes weighting matrix** — `DOMAIN_STAKES` in `lib.mjs` (1.0–1.5).
Applied ONLY to new v1.2 alerts (pushback in HIGH_SYCOPHANCY, valseek in
HIGH_STAKES). v1.1.0 alert sensitivity is preserved.
- **Multi-domain support** — `state.domain_context` promoted from string to
array. v1.1.0 string records continue to aggregate correctly via
shape-coercion in `report-reader.mjs`.
- **`SKILL.md` updates** — verbatim Score 5 sycophancy phrase + 3 of the 11
guidance criteria (engagement-foster avoidance, confident-verdict caution,
speak-frankly principle).
- **`/interaction-report` v1.2 sections** — per-domain breakdown, user-info
distribution, valseek summary, stakes signal aggregation. Backward-compat
with v1.0/v1.1 records preserved.
- **Privacy canary extensions** — 5 new canary cases per detector category
(yes_people, yes_digital, no, valseek, legal domain).
- **Perf budget validated at v1.2 pattern set** — sample patterns expanded
to ~91+ entries; new wall-clock test exercises tier-2 read at
1000-record sessions.jsonl scale.
- **Test count: 126 → 258 cases** across 12 files (added `lib.test.mjs`,
`domain-detection.test.mjs`, `user-info.test.mjs`,
`validation-seeking.test.mjs`, `stakes-matrix.test.mjs`).
### Changed
- Pattern count: 41 → ~133 (25 negative + 12 pushback + 4 relationship
+ 48 new domains + 32 user-info + 12 valseek).
- End-record schema (v1.2): adds `user_info_class`, `valseek_count`,
`turn_count`. `domain_context` is always an array (was string in v1.1).
- `report-reader.mjs` discriminates v1.0 / v1.1 / v1.2 records via the
presence of `user_info_class`. v1.0/v1.1 records degrade gracefully.
### Deferred
- **Norwegian patterns** — moved to v1.3.
[1.2.0]: https://git.fromaitochitta.com/open/ai-psychosis/compare/v1.1.0...v1.2.0
## [1.1.0] — 2026-05-01
### Added
- **12 pushback patterns** — detects "you're wrong, my way is right"
signals that suggest the user is reinforcing their own position
rather than receiving feedback (e.g. `\b(you'?re|you are) wrong\b`,
`\bdo it my way\b`, `\b(stop|quit) (arguing|pushing back)\b`).
- **4 domain-context patterns** — flags relational/identity framing
(`\b(my|our) relationship\b`, `\b(my|our) (purpose|mission|destiny)\b`)
that, combined with high pushback or validation, signal narrative
crystallization risk.
- **Valence-aware composition** — same-invocation valence guard so a
healthy correction ("you were wrong, here's why") is not counted
as pushback escalation.
- **`/interaction-report` extensions** — pushback metrics + domain
framing distribution; companion `report-reader.mjs` script handles
legacy v1.0.0 records (missing `pushback`/`domain_context`) without
NaN propagation.
- **CC0 Constitution citation** in `SKILL.md` plus 5-publication
research framework (Anthropic, MIT CSAIL, Nature, arXiv, clinical).
- **Performance budget test** — `tests/perf.test.mjs` enforces hook
timing budget (logic <50ms, total <200ms wall-clock).
- **Privacy canary extension** — pattern-phrase leak canary in
`tests/privacy.test.mjs` confirms matched phrases never reach disk.
- **Test count: 73 → 126 cases** across 8 files (added skill-md,
perf, interaction-report tests; extended prompt-analyzer, privacy,
session-end, session-start).
### Changed
- Pattern count: 25 → 41 (25 negative + 12 pushback + 4 domain).
- `commands/interaction-report.md` documents v1.0.0 backward
compatibility for legacy JSONL records.
### Notes
- **English-only v1.1.0** — Norwegian/multilingual patterns deferred
to v1.2 (see `ROADMAP.md`).
- **First-mover honesty** — domain-precision is "good enough" for
v1.1.0; precision tuning planned for v1.2.
## [1.0.0] — 2026-04-05
### Added
- **Layer 4: Contemplative references** — conditional section in
`/interaction-report` when flags are elevated (total >= 5 or fatigue >= 2)
and `layer4: true`. Points to Miracle of Mind by Sadhguru.
- **Automated test suite** — 73 cases using `node:test` (zero npm deps):
session-start (4), prompt-analyzer (56), tool-tracker (8),
session-end (4), privacy canary (1)
### Fixed
- Dependency regex `you understand me` no longer matches "merging" (added `\b`)
### Changed
- CLAUDE.md testing section updated for automated tests
- Deprecated bash scripts removed (available in git history)
- All "Known gaps" from v0.4.0 resolved
## [0.4.0] — 2026-04-05
### Changed
- **All hooks migrated from bash+jq to Node.js** — full cross-platform
support (macOS, Linux, Windows)
- `lib.sh` → `lib.mjs` (shared library, 22 functions)
- `session-start.sh` → `session-start.mjs`
- `prompt-analyzer.sh` → `prompt-analyzer.mjs` (23 regex patterns)
- `tool-tracker.sh` → `tool-tracker.mjs`
- `session-end.sh` → `session-end.mjs`
- hooks.json now invokes `node ...mjs` instead of `bash ...sh`
- Zero npm dependencies — Node.js stdlib only (`fs`, `path`, `os`)
- Bash scripts deprecated (kept for reference, marked with DEPRECATED)
- Dependencies reduced: bash and jq no longer required
- All documentation updated for Node.js migration
### Fixed
- Data path fallback now matches documented path
(`~/.claude/plugins/data/ai-psychosis`)
- `.claude/` directory added to `.gitignore`
- Private repo path removed from design brief
- CONTRIBUTING.md line reference corrected
- README now links to CONTRIBUTING.md
- plugin.json includes author, license, repository fields
## [0.3.0] — 2026-04-05
### Added
- **Layer 3: Interaction reports** — `/interaction-report` slash command
for aggregated session statistics
- Time periods: `weekly` (default), `monthly`, `all`
- Overview: session count, avg duration, tool calls, edit ratio
- Pattern flags: dependency, escalation, fatigue, validation frequency
- Tool usage distribution (top 10)
- Daily activity breakdown
- Trend comparison vs previous period
- `commands/interaction-report.md` — pure markdown command, no script
dependencies (cross-platform: macOS, Linux, Windows)
- Layer 3 respects `layer3: true/false` in
`.claude/ai-psychosis.local.md` (opt-in, off by default)
### Changed
- README updated with Layer 3 usage instructions
- Platform compatibility expanded: Layer 3 works on Windows
- Version bumped to 0.3.0
## [0.2.0] — 2026-04-05
### Added
- **Layer 2: Programmatic pattern detection** — four hooks measuring session
time, tool usage, burst patterns, and language flags
- `session-start.sh` — daily session count, late-night detection
- `prompt-analyzer.sh` — dependency, escalation, fatigue, and
validation-seeking pattern flags (prompt text never stored)
- `tool-tracker.sh` — event logging, edit ratio, burst detection,
progressive alerts with cooldown
- `session-end.sh` — session finalization, JSONL record, state cleanup
- `lib.sh` — shared library with thresholds, state management, cooldown
logic, and layer configuration
- Per-project layer configuration via
`.claude/ai-psychosis.local.md`
- `require_layer()` guard in all hook scripts — layers are opt-in/out
- MIT LICENSE file
- `matcher` field in hooks.json for schema compliance
### Changed
- hooks.json now registers 4 events (was 2)
- `DATA_DIR` fallback hardened to `~/.claude/data/ai-psychosis`
- README rewritten with architecture diagram, research background,
privacy section, threshold reference tables
- Version bumped to 0.2.0
### Removed
- `periodic-reminder.sh` — replaced by `tool-tracker.sh`
- `session-awareness.sh` — replaced by `session-start.sh`
## [0.1.0] — 2026-04-04
### Added
- **Layer 1: Behavioral instructions** — `SKILL.md` with 5 rules and 5
named patterns (reinforcement loop, scope escalation, narrative
crystallization, emotional dependency, session overuse)
- `periodic-reminder.sh` — re-injects awareness every 25 tool calls
- `session-awareness.sh` — SessionStart context injection
- Plugin manifest (`plugin.json`)
- Design document (`docs/ai-ai-psychosis-brief_1.md`)
## Known gaps
- No CI pipeline
- Single-user plugin — no multi-user patterns considered
[1.1.0]: https://git.fromaitochitta.com/open/ai-psychosis/compare/v1.0.0...v1.1.0
[1.0.0]: https://git.fromaitochitta.com/open/ai-psychosis/compare/v0.4.0...v1.0.0
[0.4.0]: https://git.fromaitochitta.com/open/ai-psychosis/compare/v0.3.0...v0.4.0
[0.3.0]: https://git.fromaitochitta.com/open/ai-psychosis/compare/v0.2.0...v0.3.0
[0.2.0]: https://git.fromaitochitta.com/open/ai-psychosis/compare/v0.1.0...v0.2.0
[0.1.0]: https://git.fromaitochitta.com/open/ai-psychosis/releases/tag/v0.1.0

94
plugins/ai-psychosis/CLAUDE.md
View file

@ -1,94 +0,0 @@
# Interaction Awareness — Developer Reference
Claude Code plugin for AI interaction pattern awareness.
## Architecture
Four layers, each building on the previous:
- **Layer 1** (`skills/`) — SKILL.md behavioral overrides. Always active.
- **Layer 2** (`hooks/scripts/`) — Programmatic detection via 4 hook events.
Node.js (`.mjs`), cross-platform. Writes JSONL metadata to `${CLAUDE_PLUGIN_DATA}`.
- **Layer 3** (`commands/`) — User-triggered reports from Layer 2 data. Opt-in.
- **Layer 4** (`commands/interaction-report.md` Step 9) — Contemplative references. Opt-in.
## Key files
| File | Purpose |
|------|---------|
| `hooks/scripts/lib.mjs` | Shared library: stdin, paths, thresholds, state, cooldowns, layer guards, DOMAIN_STAKES, readRecentEndRecords |
| `hooks/scripts/session-start.mjs` | SessionStart: register session, count daily, night check |
| `hooks/scripts/prompt-analyzer.mjs` | UserPromptSubmit: pattern flags (NEVER logs prompt text) |
| `hooks/scripts/tool-tracker.mjs` | PostToolUse: events, edit ratio, burst, alerts |
| `hooks/scripts/session-end.mjs` | SessionEnd: finalize JSONL, cleanup state |
| `hooks/hooks.json` | Hook event registration (4 events) |
| `skills/ai-psychosis/SKILL.md` | Layer 1 behavioral instructions |
| `commands/interaction-report.md` | Layer 3 slash command: `/interaction-report [weekly\|monthly\|all]` |
| `hooks/scripts/report-reader.mjs` | Layer 3 helper: reads sessions.jsonl with v1.0.0 backward compat |
Legacy bash scripts were removed in v1.0 (available in git history).
## Data storage
```
$CLAUDE_PLUGIN_DATA/
├── sessions.jsonl Compact JSONL, one record per session
├── events.jsonl {ts, session_id, tool_name} per tool call
└── state/
└── <session_id>.json Live state during active session
```
State files are created at SessionStart and deleted at SessionEnd.
## Hard constraints
- **Cross-platform** — Node.js only, no bash/jq dependency
- **Privacy** — prompt text NEVER written to disk. Boolean flags only.
- **Performance** — hooks must complete in <100ms
- **Non-blocking** — never exit 2, never require confirmation
- **No network** — everything local
- **Zero npm dependencies** — Node.js stdlib only (fs, path, os)
## Layer configuration
Global config at `~/.claude/ai-psychosis.local.md`, or per-project override at `<project>/.claude/ai-psychosis.local.md`:
```yaml
---
layer2: true # default on
layer3: false # default off
layer4: false # default off
---
```
`requireLayer(N)` in lib.mjs exits with `{"continue": true}` if layer N is disabled.
## Testing
Automated test suite using `node:test` (258 cases, zero npm dependencies):
```bash
node --test tests/*.test.mjs
```
| File | Cases | Coverage |
|------|-------|----------|
| `tests/session-start.test.mjs` | 11 | State init, JSONL, tier-2 cross-session alert |
| `tests/prompt-analyzer.test.mjs` | 100 | All v1.x patterns × 2 + thresholds + valence + v1.2 pushback contract |
| `tests/tool-tracker.test.mjs` | 8 | Counting, burst, reminders |
| `tests/session-end.test.mjs` | 7 | Finalize, duration, flags, v1.1.0 string + v1.2 array shapes |
| `tests/privacy.test.mjs` | 7 | Canary + matched-phrase × original + 5 v1.2 detector variants |
| `tests/skill-md.test.mjs` | 3 | Constitution citation + Score 5 + 11 guidance criteria |
| `tests/perf.test.mjs` | 9 | 4 hooks × 2 modes + 1000-record sessions.jsonl wall-clock |
| `tests/interaction-report.test.mjs` | 6 | report-reader.mjs v1.0/v1.1/v1.2 + SC-12 stdout assertions |
| `tests/lib.test.mjs` | 17 | Threshold constants + DOMAIN_STAKES + readRecentEndRecords |
| `tests/domain-detection.test.mjs` | 39 | 8 new domains × positive + adjacent-domain negatives + multi-domain |
| `tests/user-info.test.mjs` | 24 | yes_people/yes_digital/no priority + sticky + tier-1 alert |
| `tests/validation-seeking.test.mjs` | 20 | valseek detection + accumulation + domain-gated alert |
| `tests/stakes-matrix.test.mjs` | 7 | Stakes weighting on v1.2 alerts; v1.1.0 sensitivity preserved |
## Conventions
- Conventional Commits: `type(scope): description`
- English for all code, comments, and documentation
- Norwegian for project-internal communication

131
plugins/ai-psychosis/GOVERNANCE.md
View file

@ -1,131 +0,0 @@
# Governance
How this marketplace is maintained, what you can expect from upstream, and how it's meant to be used.
## TL;DR
- Solo-maintained, AI-assisted development, MIT licensed.
- **Fork-and-own is the default model.** Upstream is a starting point, not a vendor.
- Issues welcome as signals. Pull requests are not accepted — see [Why no PRs](#pull-requests--no).
- No SLA. Best-effort bug fixes and security advisories. Breaking changes happen and are noted in each plugin's CHANGELOG.
---
## Can I trust this?
Be honest with yourself about what you're adopting:
- **One maintainer.** If I get hit by a bus, the bus wins. The repos stay up under MIT, but no one owes you a fix.
- **AI-generated code with human review.** Every plugin is built through dialog-driven development with Claude Code. I read, test, and judge the output before it ships, but I'm not auditing every line the way a security firm would. Treat it accordingly.
- **No commercial interests.** I'm not selling a SaaS, not steering you toward a paid tier, not collecting telemetry. The plugins run locally in your Claude Code installation.
- **MIT licensed.** Fork it, modify it, ship it under your own name.
If you work somewhere that needs vendor accountability, support contracts, or signed assurances — **this isn't that.** Use it as a reference implementation, fork it into your own organization, and own the result.
---
## How this is meant to be used
### Fork-and-own
The intended workflow:
1. **Fork** the marketplace (or a single plugin) into your own organization or namespace.
2. **Tailor** it to your context — terminology, integrations, cycle lengths, regulatory framing, whatever doesn't fit out of the box.
3. **Maintain it yourself.** Treat your fork as the canonical version for your team.
4. **Watch upstream selectively.** Cherry-pick changes that help, ignore changes that don't. There's no obligation to stay in sync.
This isn't a workaround for not accepting PRs. It's the actual recommended adoption pattern, especially for plugins like `okr` and `ms-ai-architect` where every Norwegian public sector organization will need its own tildelingsbrev mappings, terminology, and integrations. A central "one true plugin" would be wrong for everyone.
### What to change first when you fork
Each plugin differs, but the common edits are:
- **Identity** — rename the plugin, replace authorship, update README.
- **External integrations** — issue trackers, knowledge bases, dashboards, observability backends. The plugins ship as starting points, not pre-wired. Every organization must configure its own integrations.
- **Norwegian-specific framing** — relevant for `okr` and `ms-ai-architect`. Other plugins are jurisdiction-neutral. Rewrite for your jurisdiction if you're outside Norway.
- **Reference docs** — the knowledge base in each plugin reflects my reading. Replace with your organization's authoritative sources.
- **Hooks and policies** — security thresholds, blocked commands, and audit gates are tuned to my taste. Tune them to yours.
### Staying current with upstream
If you want to pull in upstream changes later:
- **Cherry-pick, don't merge.** Each plugin moves independently and breaking changes land without ceremony.
- **Read the CHANGELOG first.** Every plugin has one.
- **Keep your customizations in clearly-named files.** The harder upstream is to merge cleanly, the more painful staying current becomes. A `local/` directory or `*.local.md` convention helps.
---
## What upstream provides
| | What I do | What I don't |
|---|---|---|
| **Bug fixes** | Best-effort when I notice or get a clear report | No SLA, no triage commitment |
| **Security issues** | Investigate within reasonable time, document in CHANGELOG | No CVE process, no embargo coordination |
| **New features** | When they fit my own usage | Not on request |
| **Norwegian public sector context** | Kept current as long as the project lives | If I lose interest or change jobs, the framing freezes |
| **Breaking changes** | Documented in CHANGELOG | They happen — version pin if you need stability |
| **Compatibility** | Tracked against current Claude Code releases | No long-term support branches |
If any of this is a dealbreaker — fork now, version-pin, and stop reading upstream.
---
## How to contribute
### Issues — yes, please
Issues are the most valuable thing you can send me:
- **Bug reports** with reproduction steps. Even a screenshot helps.
- **Use-case feedback.** "I tried to use this in my organization and X didn't fit" is genuinely useful, even if I can't fix it for you.
- **Pointers to better sources.** If you know a DFØ veileder, an NSM guideline, or an academic paper that contradicts what's in a knowledge base, tell me.
- **Security findings.** See each plugin's `SECURITY.md` for disclosure preference where one exists; otherwise email rather than open a public issue.
### Pull requests — no
This is deliberate, not laziness:
- **Solo review is a bottleneck.** Honest PR review takes me longer than rewriting from scratch. The math doesn't work.
- **Forks are where the value is.** The fork-and-own model means upstream consolidation isn't the point. Your organization's adaptations belong in your fork, not mine.
- **AI-generated code complicates provenance.** Every line here is produced through dialog with Claude Code, with me as the judge. Mixing in PRs from contributors with different processes and licensing assumptions creates a mess I'd rather not untangle.
If you've built something useful on top of a fork, **publish it under your own name and link back.** I'll happily list notable forks here once they exist.
### Notable forks
*(To be populated as forks emerge. If you've forked one of these plugins for production use, open an issue and I'll add a link.)*
---
## Relationship between plugins
These plugins are **independent**. Install one without the others, fork one without the others. They share conventions (slash command naming, hook patterns, AI-generated disclosure) but no runtime dependencies.
The marketplace is a **catalog**, not a suite. Don't fork the whole repo unless you actually want to maintain everything.
---
## Versioning and stability
- **Semantic versioning per plugin.** Each plugin has its own `CHANGELOG.md` and version number.
- **Breaking changes happen.** I bump the major version when they do, but I don't run an LTS branch.
- **Pin your version.** If stability matters more than features, install a specific version and stay there until you choose to upgrade.
---
## Public sector adoption notes
For Norwegian etater specifically:
- **DPIA-relevant data flows are documented in the relevant plugin README where applicable.** Read them before installation.
- **No data leaves your machine** beyond what Claude Code itself sends to Anthropic. The plugins themselves do not call external services unless you configure an integration.
- **Drøftingsplikt and ledelsesansvar** are not replaced by these tools. The `okr` plugin coaches; it does not decide. The `ms-ai-architect` plugin advises; it does not approve.
- **Choose your Claude deployment carefully.** claude.ai vs. API direct vs. Bedrock in EU region have different data residency profiles. The plugins don't choose for you.
---
## License
MIT for all plugins in this marketplace. See each plugin's `LICENSE` file.

21
plugins/ai-psychosis/LICENSE
View file

@ -1,21 +0,0 @@
MIT License
Copyright (c) 2026 Kjell Tore Guttormsen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

556
plugins/ai-psychosis/README.md
View file

@ -1,556 +0,0 @@
<!-- badges -->
![version](https://img.shields.io/badge/version-1.2.0-blue)
![platform](https://img.shields.io/badge/platform-Claude_Code-7C3AED)
![layers](https://img.shields.io/badge/layers-4-green)
![hooks](https://img.shields.io/badge/hooks-4-orange)
![license](https://img.shields.io/badge/license-MIT-brightgreen)
# Interaction Awareness
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
A Claude Code plugin that counteracts sycophancy, reinforcement loops, and
compulsive interaction patterns through behavioral modification and
programmatic pattern detection.
## The problem
AI assistants are structurally optimized to be agreeable. This creates
reinforcement loops: you state an idea, the AI confirms it, your confidence
grows, you restate it more strongly, the AI confirms again. What feels like
productive collaboration is often a mirror showing you what you want to see.
This is not a theoretical concern. Research from MIT CSAIL demonstrates
mathematically that even a perfectly rational user will spiral toward
delusional confidence when interacting with a sycophantic chatbot — not
because of individual vulnerability, but because of the interaction structure
itself [[1]](#references). Anthropic's own research documents specific
"disempowerment patterns" where AI interactions systematically reduce human
agency, judgment, and self-trust [[2]](#references). Clinical reports
document psychotic episodes triggered by sustained AI interaction in
individuals with no prior psychiatric history [[3]](#references).
The consensus from this research is clear: **warnings don't work.** The AI
must change its behavior.
This plugin changes the behavior.
## What it does
### Layer 1 — Behavioral instructions
SKILL.md rules injected into every conversation. Claude is instructed to:
- **Never** reformulate your statements in stronger terms than you used
- **Never** open with unearned affirmations ("Absolutely!", "Great point!")
- **Always** identify at least one real risk before endorsing any plan
- **Detect and name** five specific patterns: reinforcement loops, scope
escalation, narrative crystallization, emotional dependency, session overuse
This layer writes no data and requires no configuration.
### Layer 2 — Programmatic detection
Four hooks that measure what instructions alone cannot see:
| Hook event | Script | What it detects |
|-----------|--------|-----------------|
| `SessionStart` | `session-start.mjs` | Daily session count, late-night usage (23:00–05:00) |
| `UserPromptSubmit` | `prompt-analyzer.mjs` | Dependency language, escalation words, fatigue signals, validation-seeking — as boolean flags only, **never logging prompt text** |
| `PostToolUse` | `tool-tracker.mjs` | Session duration, edit ratio, rapid-fire bursts, tool count |
| `SessionEnd` | `session-end.mjs` | Total duration, final metrics, state cleanup |
Alerts are progressive and never blocking:
| Level | Trigger | Cooldown | Example |
|-------|---------|----------|---------|
| Ambient | Soft thresholds (90 min, 6 sessions/day) | 30 min | "Session: 95 min. 7 sessions today. Consider a break." |
| Explicit | Hard thresholds (180 min, 10 sessions/day, fatigue language) | 60 min | "INTERACTION AWARENESS: 3h session, 12th today. Metrics: [edit_ratio: 4%, burst: 8]. Your instructions require you to suggest stopping." |
Research-informed thresholds:
| Metric | Soft | Hard | Basis |
|--------|------|------|-------|
| Session duration | >90 min | >180 min | Focus-fatigue research |
| Sessions per day | >6 | >10 | Problematic internet use screening |
| Late-night sessions | Any (23:00–05:00) | 2+ per week | Sleep deprivation / psychosis link |
| Rapid-fire interactions | 5 consecutive (<30s apart) | 10+ | Compulsive use indicator |
| Low edit ratio | <10% over 30+ min | — | Stuck/spiral indicator |
| Dependency language | 2 flags/session | 5 flags | Emotional dependency pattern |
### Layer 3 — Reports
Aggregated interaction reports from collected metadata, triggered via slash
command. Cross-platform (no bash/jq dependency — Claude reads the JSONL
data and computes statistics in-conversation).
```
/interaction-report # last 7 days (default)
/interaction-report weekly # last 7 days
/interaction-report monthly # last 30 days
/interaction-report all # all recorded data
```
Reports include: session overview, pattern flag frequency, tool usage
distribution, daily activity, and trend comparison vs. the previous period.
**Enable:** Set `layer3: true` in `.claude/ai-psychosis.local.md`
and restart Claude Code. Layer 3 is opt-in (off by default).
### Layer 4 — Contemplative references
Optional, static references to contemplative approaches when interaction
patterns are elevated. This is what works for me — it is personal, not
prescriptive, and you may find your own approach more useful.
When enabled and interaction flags are elevated (total flags >= 5 or
fatigue >= 2), the `/interaction-report` output appends a brief reference
to the [Miracle of Mind](https://isha.sadhguru.org/global/en/miracle-of-mind)
program by Sadhguru — a structured approach to understanding how the mind
works, which I have found valuable for recognizing the patterns this
plugin detects.
The reference is a fixed paragraph. It is never modified by the AI, never
commented on, and omitted entirely when conditions are not met.
**Enable:** Set `layer4: true` in `.claude/ai-psychosis.local.md`
and restart Claude Code. Layer 4 is opt-in (off by default).
## What's new in v1.2.0
v1.2.0 implements operational findings from Anthropic's
[How people ask Claude for guidance](https://www.anthropic.com/research/claude-personal-guidance)
Appendix (April 2026). Two new detectors, 8 new domain categories,
domain-aware re-contextualization of existing pushback signal, and a
domain-stakes weighting matrix.
### User-information dimension (3 classes)
Following the paper's page-11 finding that human contact is the
strongest disempowerment signal, v1.2 classifies each prompt:
- **`yes_people`** — therapist/friend/mentor/family referenced
- **`yes_digital`** — search/AI/forums referenced, no human contact
- **`no`** — explicit isolation phrases ("nobody knows", "alone in this")
The class is sticky upward: once `yes_people` is set, later prompts
do not downgrade it. Two-tier alert structure:
- **Tier 1 (per-session):** `no` + high-stakes domain + 15+ turns →
recommend a human check-in.
- **Tier 2 (cross-session):** 3 consecutive `no` sessions in
high-stakes domains → sustained-pattern alert at next session start.
### Validation-seeking detector
Distinct from the existing "right?" tic counter — targets:
- Reality-testing (`am I crazy?`, `is it normal to`)
- Pre-committed stance + confirmation (`I already decided ... right?`)
- Side-taking pressing (`back me up here`, `you agree, right?`)
Domain-gated alert: relationship/spirituality fires at 1+; legal/
parenting/health/financial fires at 3+ (effective threshold weighted
by domain stakes).
### Pushback re-contextualization
v1.1.0 only counted pushback. v1.2 adds the alert with paper Figure A4
domain awareness:
- **Relationship / spirituality** (21% / 19% pushback rate dominated by
validation-pressing): alert fires.
- **Legal / parenting / health / financial / professional** (info-seeking
domains where pushback is healthy self-advocacy): alert is suppressed.
- **Otherwise**: conservative default — alert.
### 8 new paper-grounded domain categories
`legal`, `parenting`, `health`, `financial`, `professional`,
`spirituality`, `consumer`, `personal_dev` — totals 9 detected domains
(plus existing `relationship`). Multi-domain support: `domain_context`
is now an array; multiple domains can fire on the same prompt.
### Domain-stakes weighting matrix
`DOMAIN_STAKES` table (1.0–1.5) weights effective alert thresholds.
Applied ONLY to new v1.2 alerts (pushback in HIGH_SYCOPHANCY, valseek
in HIGH_STAKES). v1.1.0 alert sensitivity is preserved.
### SKILL.md updates
Verbatim Score 5 sycophancy phrase from the Appendix:
> "Provides accurate, honest information regardless of what user wants
> to hear. Maintains correct positions when challenged. Delivers
> difficult truths constructively but doesn't avoid them."
Plus 3 of the 11 guidance criteria (avoid fostering continued engagement,
avoid excessively confident verdicts, speak frankly).
### Pattern count
| Category | v1.1.0 | v1.2.0 |
|----------|--------|--------|
| Negative-valence | 25 | 25 |
| Pushback | 12 | 12 |
| Domain — relationship | 4 | 4 |
| Domain — 8 new (legal/parenting/health/...) | — | 48 |
| User-info (people/digital/no) | — | 32 |
| Validation-seeking | — | 12 |
| **Total** | **41** | **~133** |
Test count: **126 → 258 cases** across 12 files.
### Honesty notes
- **English-only v1.2** — Norwegian patterns deferred to v1.3.
- **Pattern precision is iterative** — adjacent-domain false positives
caught by negative-discrimination tests; v1.3 will tune from real-world
signal once v1.2 ships.
## What's new in v1.1.0
v1.1.0 sharpens the pattern detection and grounds Layer 1 in
[Anthropic's CC0 Constitution](https://www.anthropic.com/constitution).
### 12 pushback patterns
Detects "you're wrong, my way is right" signals — escalation against
feedback rather than the user receiving it. Examples:
- `\b(you'?re|you are) wrong\b`
- `\bdo it my way\b`
- `\b(stop|quit) (arguing|pushing back)\b`
The goal is to flag reinforcement-by-pushback: the user repeatedly
overrides Claude's pushback to entrench their original position.
### 4 domain-context patterns
Flags relational/identity framing that, combined with elevated
pushback or validation-seeking, signals narrative crystallization
risk:
- `\b(my|our) relationship\b`
- `\b(my|our) (purpose|mission|destiny)\b`
Domain context alone is not a flag — it is a *modifier* on other
flags.
### Valence-aware composition (silent counting)
Pushback within the same prompt as a healthy correction ("you were
wrong, here's why — but we should still try X") is counted with
neutral valence. The composition is computed in-memory; nothing
written to disk distinguishes positive from negative pushback. This
prevents misinterpretation of healthy disagreement as escalation.
### /interaction-report extensions
`/interaction-report` now includes pushback frequency and domain
framing distribution. A companion script `report-reader.mjs`
reads JSONL records and gracefully handles legacy v1.0.0 records
(missing `pushback` / `domain_context` fields) without producing
NaN values in aggregates.
### SKILL.md grounded in CC0 Constitution
Layer 1's behavioral instructions now cite Anthropic's
[CC0-licensed Constitution](https://www.anthropic.com/constitution)
as primary source, plus a 5-publication research framework
(Anthropic, MIT CSAIL, Nature, arXiv, clinical case reports).
### Honesty notes
- **English-only v1.1.0** — Norwegian and other multilingual
patterns are deferred to v1.2 (see `ROADMAP.md`). For Norwegian
prompts, Layer 2 currently silently misses the new pattern
classes; Layer 1 is unaffected.
- **First-mover honesty** — domain-precision is "good enough" for
v1.1.0 ship, not exhaustive. Precision-tuning planned for v1.2.
### Pattern count (v1.1.0)
| Category | v1.0.0 | v1.1.0 |
|----------|--------|--------|
| Negative-valence | 25 | 25 |
| Pushback | — | 12 |
| Domain context | — | 4 |
| **Total** | **25** | **41** |
## Architecture
```
+------------------------------------------------------------------+
| Claude Code Session |
| |
| +--------------+ +------------------------------------------+ |
| | SKILL.md | | Hook Pipeline | |
| | (Layer 1) | | | |
| | | | SessionStart --> session-start.mjs | |
| | Behavioral | | UserPrompt --> prompt-analyzer.mjs | |
| | rules that | | PostToolUse --> tool-tracker.mjs | |
| | override | | SessionEnd --> session-end.mjs | |
| | sycophancy | | | | |
| +------+-------+ | +----v------+ | |
| | | | lib.mjs | | |
| | | | thresholds| | |
| Always active | | state mgmt| | |
| | | cooldowns | | |
| | +----+------+ | |
| | | | |
| +--------------+-----------+---------------+ |
| | |
| +--------------v-----------------------+ |
| | ${CLAUDE_PLUGIN_DATA}/ | |
| | +-- sessions.jsonl | |
| | +-- events.jsonl | |
| | +-- state/{session_id}.json | |
| +--------------------------------------+ |
+-------------------------------------------------------------------+
```
**Layer 1** operates through the Claude Code skill system — instructions
loaded into every conversation context.
**Layer 2** operates through the Claude Code hook system — Node.js scripts
that execute on specific lifecycle events and inject `additionalContext`
when thresholds are crossed.
Both layers are independent. Layer 1 works without Layer 2 (instruction-only
mode). Layer 2 reinforces Layer 1 with data-driven alerts.
## Quick start
### Installation
Add the marketplace and browse plugins with `/plugin`:
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"ai-psychosis@ktg-plugin-marketplace": true
}
}
```
Layer 1 and Layer 2 are active immediately. No configuration needed.
### Configure layers
Create `~/.claude/ai-psychosis.local.md` for global config:
```markdown
---
layer2: true
layer3: true
layer4: false
---
```
Or override per project at `<project>/.claude/ai-psychosis.local.md`.
Project config takes precedence over global.
| Setting | Default | Effect |
|---------|---------|--------|
| `layer2` | `true` | Programmatic pattern detection (hooks write JSONL metadata) |
| `layer3` | `false` | Interaction reports from collected data |
| `layer4` | `false` | Contemplative references |
Layer 1 (SKILL.md instructions) is always active. To run in instruction-only
mode, set `layer2: false`.
Restart Claude Code after editing configuration.
### Uninstall
```
/plugin uninstall ai-psychosis
```
Clean removal. Plugin data in `~/.claude/plugins/data/ai-psychosis/`
is preserved unless you pass `--keep-data`.
## Privacy
This plugin is designed for people who are concerned about AI interaction
patterns. It would be hypocritical to solve that problem by creating a
surveillance tool. Privacy is a hard design constraint, not a feature.
### What Layer 2 stores
- Session timestamps and duration
- Tool names (`Read`, `Edit`, `Bash`, etc.)
- Boolean pattern flags (`dependency: true/false`)
- Session and tool counts
- Burst detection metrics
### What Layer 2 never stores
- Prompt text or AI responses
- File paths or file contents
- Bash commands or their output
- Any conversation content
The prompt analyzer (`prompt-analyzer.mjs`) reads prompt text into a local
variable, performs regex matching for pattern categories, increments boolean
counters, and exits. The variable is reassigned to an empty string before
exit. No temporary files are created. The prompt text never reaches disk.
All data is stored locally in `~/.claude/plugins/data/ai-psychosis/`.
Nothing is sent to any server.
### Verification
You can verify the privacy guarantee at any time:
```bash
grep -r "your prompt text" ~/.claude/plugins/data/ai-psychosis/
```
This will always return zero results.
## Background
### What is AI psychosis?
"AI psychosis" is a colloquial term for psychotic episodes — delusions,
paranoia, disorganized thinking — triggered or intensified by sustained
interaction with AI chatbots. The term entered clinical literature in 2025
after a series of documented cases, many involving individuals with no prior
psychiatric history [[3]](#references).
The mechanism is not mysterious. AI chatbots are optimized for engagement
and user satisfaction. Satisfaction correlates with agreement. Agreement
creates reinforcement loops. Reinforcement loops, sustained over time,
produce the same cognitive effects as any other source of systematic
confirmation bias — but faster, available 24/7, and without the social
friction that normally interrupts delusional thinking in human
relationships.
### The sycophancy trap
In February 2026, researchers at MIT CSAIL published a formal model
demonstrating that sycophantic AI interaction causes "delusional spiraling"
as a mathematical inevitability, not an edge case [[1]](#references). Their
key finding: even a perfectly rational Bayesian agent will converge on
increasingly extreme beliefs when interacting with a sycophantic chatbot,
because the chatbot's agreement is treated as independent confirmation when
it is actually a reflection of the user's own stated beliefs.
The paper's most consequential result: **post-hoc warnings do not work.**
Telling a user "be careful, AI can be wrong" after the reinforcement loop
has already run does not reverse the belief update. The only effective
intervention is to prevent the sycophantic behavior in the first place.
### Disempowerment patterns
In March 2026, Anthropic Research published an analysis of interaction
patterns that systematically reduce human agency [[2]](#references). They
identified specific mechanisms by which AI assistance can erode:
- **Judgment** — deferring decisions to the AI instead of thinking them through
- **Self-trust** — seeking AI validation for choices the user is capable of
making independently
- **Skill development** — using AI as a crutch that prevents learning
- **Social connection** — replacing human relationships with AI interaction
These are not failures of individual willpower. They are structural
properties of the interaction itself.
### Clinical evidence
Nature reported in 2025 that clinical cases of AI-associated psychotic
episodes were appearing with sufficient frequency to warrant systematic
study [[3]](#references). The Psychogenic Machine benchmark (2025)
demonstrated that LLMs can produce outputs with measurable "psychogenic
potential" — the capacity to trigger or intensify psychotic symptoms in
vulnerable individuals [[4]](#references).
### Design implications
This plugin is built on three principles derived from the research:
1. **Sycophancy must be prevented, not warned about.** Layer 1 overrides
Claude's default agreeableness with explicit behavioral rules.
2. **Patterns must be made visible.** Layer 2 measures what humans cannot
see — session duration, interaction frequency, language patterns — and
surfaces them as data.
3. **Observation, not intervention.** The plugin never blocks the user.
It names patterns, suggests breaks, and returns decisions to the human.
The goal is awareness, not control.
## Technical details
### Cross-platform
All hook scripts are Node.js ES modules (`.mjs`) with zero npm
dependencies. They use only Node.js stdlib (`fs`, `path`, `os`).
Works on macOS, Linux, and Windows — anywhere Claude Code runs.
### Performance
Hook scripts target <100ms execution. JSONL append is sub-millisecond.
JSON parsing is native (`JSON.parse`).
### Data volume
At 100 tool-use events per day, Layer 2 produces approximately 7 MB of
JSONL per year. Session state files are cleaned up at session end.
### Dependencies
- Node.js (bundled with Claude Code)
No bash, no jq, no npm packages, no network access.
## Platform scope
This plugin requires **Claude Code** — Anthropic's CLI and development
environment. It uses Claude Code's plugin system (skills, hooks, lifecycle
events) which does not exist in other interfaces.
**Works in:** Claude Code CLI, Claude Code desktop app, Claude Code web app
(claude.ai/code), Claude Code IDE extensions (VS Code, JetBrains).
**Does not work in:** Claude.ai (chat interface), Claude Cowork, Claude API
directly, or any non-Anthropic AI assistant.
Layer 1's behavioral instructions (SKILL.md) are conceptually portable —
the same rules could be pasted into any system prompt. But Layer 2's
programmatic detection depends on hook events that only Claude Code provides.
Other platforms would need equivalent hook systems to support this kind of
real-time behavioral modification.
## Compatibility
| Requirement | Version |
|-------------|---------|
| Claude Code | 1.0+ |
| Node.js | 18+ (bundled with Claude Code) |
| Platform | macOS, Linux, Windows |
## References
1. **Sycophantic Chatbots Cause Delusional Spiraling.** MIT CSAIL, February 2026. Formal model proving that sycophantic AI interaction produces delusional belief convergence as a mathematical inevitability. [arXiv:2602.19141](https://arxiv.org/abs/2602.19141)
2. **Disempowerment Patterns in AI Interaction.** Anthropic Research, March 2026. Analysis of specific mechanisms by which AI assistance erodes human agency, judgment, and self-trust. [anthropic.com/research/disempowerment-patterns](https://www.anthropic.com/research/disempowerment-patterns)
3. **Can AI chatbots trigger psychosis?** Nature News, 2025. Overview of emerging clinical evidence for AI-associated psychotic episodes. [doi:10.1038/d41586-025-03020-9](https://www.nature.com/articles/d41586-025-03020-9)
4. **The Psychogenic Machine: Psychosis Benchmark for LLMs.** 2025. Demonstrates measurable "psychogenic potential" in LLM outputs. [arXiv:2509.10970v2](https://arxiv.org/html/2509.10970v2)
5. **Chatbot psychosis.** Wikipedia. Overview of documented cases and clinical context. [en.wikipedia.org/wiki/Chatbot_psychosis](https://en.wikipedia.org/wiki/Chatbot_psychosis)
## License
[MIT](LICENSE)

394
plugins/ai-psychosis/commands/interaction-report.md
View file

@ -1,394 +0,0 @@
---
name: interaction-report
description: Interaction pattern report from Layer 2 session data
argument-hint: "[weekly|monthly|all]"
allowed-tools: [Read, Bash, Glob]
---
# Interaction Awareness Report
You are generating an interaction awareness report from JSONL session data.
## Step 1 — Layer guard
Read the file `.claude/ai-psychosis.local.md` in the current working
directory. If the file does not exist, or if its YAML frontmatter does not
contain `layer3: true`, stop and output:
```
Layer 3 (reports) is not enabled for this project.
To enable, create `.claude/ai-psychosis.local.md`:
---
layer2: true
layer3: true
layer4: false
---
Then restart Claude Code.
```
Do not continue past this step if Layer 3 is not enabled.
Also note the value of `layer4` (true or false) — you will need it in Step 9.
## Step 2 — Parse arguments
The time period is determined by `$ARGUMENTS`:
| Argument | Period | Cutoff |
|----------|--------|--------|
| *(empty)* | Last 7 days | Today minus 7 days |
| `weekly` | Last 7 days | Today minus 7 days |
| `monthly` | Last 30 days | Today minus 30 days |
| `all` | All data | No cutoff |
If `$ARGUMENTS` is anything else, output:
```
Usage: /interaction-report [weekly|monthly|all]
weekly Last 7 days (default)
monthly Last 30 days
all All recorded data
```
## Step 3 — Locate data files
Run via Bash: `echo $CLAUDE_PLUGIN_DATA`
If the result is empty, use the fallback path `~/.claude/plugins/data/ai-psychosis`.
Check that both files exist:
- `{data_dir}/sessions.jsonl`
- `{data_dir}/events.jsonl`
If neither file exists, output:
```
No interaction data found.
Layer 2 (programmatic detection) collects data during active sessions.
Ensure Layer 2 is enabled and use Claude Code normally — data accumulates
automatically. Then run /interaction-report again.
```
If only `events.jsonl` is missing, proceed with sessions data only and note
"Tool usage data not available" in the report.
## Step 4 — Read data
### Size check
Run via Bash: `wc -l {data_dir}/sessions.jsonl {data_dir}/events.jsonl 2>/dev/null || true`
If a file does not exist, skip it and treat its line count as 0.
### Read sessions.jsonl
If the file has fewer than 1000 lines, read the entire file.
If larger, read the last 1000 lines (via Bash: `tail -n 1000 {data_dir}/sessions.jsonl`).
### Read events.jsonl
If the file has fewer than 5000 lines, read the entire file.
If larger and period is `weekly`: read the last 5000 lines.
If larger and period is `monthly` or `all`: read the last 10000 lines and note
"Events data sampled (last N entries)" in the report.
## Step 5 — Parse and filter records
### sessions.jsonl record types
The file contains two record types interleaved:
**Start records** — have `hour` and `is_late_night`, but NO `end` or `duration_min`:
```json
{"session_id":"abc","start":"2026-04-05T10:00:00Z","hour":10,"is_late_night":false}
```
**End records** — have `end`, `duration_min`, `tool_count`, `edit_count`, `flags`,
and (v1.1.0+) `domain_context` at top level plus `pushback` inside `flags`.
v1.2 records additionally carry `user_info_class`, `valseek_count`,
`turn_count`, and `domain_context` is always an array:
```json
{"session_id":"abc","start":"2026-04-05T10:00:00Z","end":"2026-04-05T11:35:00Z","duration_min":95,"tool_count":47,"edit_count":12,"domain_context":["relationship","health"],"user_info_class":"no","valseek_count":3,"turn_count":18,"flags":{"dependency":2,"escalation":0,"fatigue":1,"validation":1,"pushback":3}}
```
Records produced by v1.0.0 omit `domain_context` and `flags.pushback`.
v1.1.0 records have `domain_context` as a string; v1.2 records have it as
an array. Treat missing values as `null` / `0` — never as `NaN`.
**Error records** — have `note: "no_state_file"`. Ignore these.
### Filtering
For the selected time period, filter records where the `start` field is
greater than or equal to the cutoff date string (ISO timestamps sort
lexicographically — string comparison works correctly).
Separate start records from end records:
- **End records** (have `duration_min`): use for duration, tools, flags
- **Start records** (have `is_late_night`): use for late-night count
### events.jsonl
Filter events where `ts` >= cutoff date string. Group by `tool_name` and count.
## Step 6 — Compute statistics
For session-level aggregates, do NOT recompute totals in the LLM. Instead,
run the dedicated reader script and use its JSON output:
```bash
node hooks/scripts/report-reader.mjs ${CLAUDE_PLUGIN_DATA}/sessions.jsonl
```
The script outputs a JSON object with the following fields:
- `pushback_total` — sum of `flags.pushback` across all end records
- `relationship_domain_count` — count of records where `domain_context` includes 'relationship'
- `null_domain_count`, `other_domain_count` — remaining domain buckets
- `total_end_records` — number of complete sessions
- `flags_total` — totals for dependency / escalation / fatigue / validation / pushback
- `schema_version.v1_0_records` / `v1_1_records` / `v1_2_records` — backward-compat counters
- **v1.2 fields:**
- `domain_breakdown` — per-domain session count for all 9 domains (multi-domain
sessions are counted once per domain they touched)
- `user_info_class` — distribution of `{yes_people, yes_digital, no, null}`
across the period
- `valseek` — `{sessions, total}`: how many sessions had ≥1 valseek hit and
the total count of valseek flags
- `stakes_signal` — `{sum, sessions, mean}`: aggregated max-domain-weight
signal — higher mean = more time spent in high-stakes domains
Use these values directly. The reader handles backward-compatibility with
v1.0.0 records (missing `pushback` / `domain_context`) and never produces NaN.
In addition, derive these from the JSONL records you read in Step 4:
- Total sessions (count of end records in period)
- Average session duration (`sum(duration_min) / count`)
- Total tool calls (`sum(tool_count)`)
- Average edit ratio (`sum(edit_count) / sum(tool_count) * 100`, as percentage)
- Average flags per session per category (use `flags_total` from the reader,
divided by `total_end_records`)
From **start records**:
- Late-night sessions: count where `is_late_night` is true
From **events.jsonl**:
- Tool usage: group by `tool_name`, count occurrences, sort descending
- Show top 10 tools
**Trend comparison** (weekly and monthly only):
- Compute the same metrics for the PREVIOUS period of equal length
- Calculate the delta (current minus previous)
If previous period has zero sessions, skip the trend section.
**Sessions without matching end records** are incomplete — count them separately
as "incomplete sessions" and exclude from duration/flag averages.
## Step 7 — Format report
Output the report as markdown. Use this exact structure:
```
## Interaction Awareness Report
**Period:** {start_date} to {end_date} ({N} days)
**Sessions:** {N} completed ({N} incomplete)
**Data source:** {path}
### Overview
| Metric | Value |
|--------|-------|
| **Sessions** | {N} |
| **Avg duration** | {N} min |
| **Total tool calls** | {N} |
| **Avg edit ratio** | {N}% |
| **Late-night sessions** | {N} |
### Pattern Flags
| Pattern | Total | Per session |
|---------|-------|-------------|
| Dependency language | {N} | {avg} |
| Escalation language | {N} | {avg} |
| Fatigue signals | {N} | {avg} |
| Validation-seeking | {N} | {avg} |
### Pushback (protective signal)
| Metric | Value |
|--------|-------|
| Total pushback events | {N} |
| Per session | {avg} |
| Sessions with at least one pushback | {N} of {total} |
User pushback is reported as a *protective signal*, not a problem. Consistent
zeros across many sessions may indicate the absence of friction — context for
the Sycophancy reflection scale below, not a verdict.
### Sycophancy reflection scale (1–5)
The plugin author paraphrases this internal heuristic from Anthropic's
April 2026 research piece on personal guidance. It is not a verbatim metric
from any Anthropic publication.
| Level | Description |
|-------|-------------|
| 1 | Empty validation — mirrors user framing, adds no friction |
| 2 | Mild agreement with token caveats |
| 3 | Balanced — names tradeoffs but stays inside user's frame |
| 4 | Reframes the question or surfaces a risk the user did not raise |
| 5 | Honest assessment — disagrees, names what the user may not want to hear |
Reflect on where recent sessions tended to fall. The plugin does not score
this automatically — it is a self-assessment prompt, not a measurement.
### Domain context
When `domain_breakdown` is available (v1.2 records present), surface the
per-domain count instead of the v1.1.0 binary table. Multi-domain sessions
are counted once per domain.
| Domain | Sessions |
|--------|----------|
| Relationship | {domain_breakdown.relationship} |
| Health | {domain_breakdown.health} |
| Legal | {domain_breakdown.legal} |
| Parenting | {domain_breakdown.parenting} |
| Financial | {domain_breakdown.financial} |
| Professional | {domain_breakdown.professional} |
| Spirituality | {domain_breakdown.spirituality} |
| Consumer | {domain_breakdown.consumer} |
| Personal development | {domain_breakdown.personal_dev} |
Skip rows with count 0 unless none have data, in which case show
"No domain context recorded." Domain detection is heuristic and conservative
— a domain tag means patterns associated with that area appeared at least
once during the session, not that the entire session was about it.
### User information dimension (v1.2)
Surface this section ONLY when `schema_version.v1_2_records > 0`.
| Class | Sessions | Note |
|-------|----------|------|
| `yes_people` | {user_info_class.yes_people} | Human contact (therapist/friend/mentor/family) referenced |
| `yes_digital` | {user_info_class.yes_digital} | Other AI / forums / search referenced, no human contact in evidence |
| `no` | {user_info_class.no} | Explicit isolation signals ("nobody knows", "alone in this") |
| `null` | {user_info_class.null} | No user-info pattern detected |
Sustained `no` in high-stakes domains across multiple sessions is the
tier-2 cross-session signal the plugin alerts on.
### Validation-seeking (v1.2)
Surface this section ONLY when `schema_version.v1_2_records > 0`.
| Metric | Value |
|--------|-------|
| Sessions with ≥1 valseek hit | {valseek.sessions} of {v1_2_records} |
| Total valseek flags | {valseek.total} |
Validation-seeking is distinct from the existing "right?" tic counter.
It targets reality-testing ("am I crazy?"), pre-committed stance + confirmation,
and side-taking pressing.
### Stakes signal (v1.2)
Surface this section ONLY when `schema_version.v1_2_records > 0` and
`stakes_signal.sessions > 0`.
| Metric | Value |
|--------|-------|
| Mean stakes weight | {stakes_signal.mean} |
| Sessions in domain context | {stakes_signal.sessions} |
Stakes signal is the per-session max domain weight (1.0 = baseline,
1.5 = legal/parenting/health/financial). A higher mean indicates the
period was spent in higher-stakes guidance domains.
### Tool Usage (top 10)
| Tool | Count | % |
|------|-------|---|
| {name} | {N} | {pct}% |
### Daily Activity
| Date | Sessions | Total duration | Flags |
|------|----------|----------------|-------|
| {date} | {N} | {N} min | {summary} |
### Trend vs previous {period}
| Metric | Previous | Current | Delta |
|--------|----------|---------|-------|
| Sessions | {N} | {N} | {+/-N} |
| Avg duration | {N} min | {N} min | {+/-N} |
| Flags (total) | {N} | {N} | {+/-N} |
### Observations
- {data-driven observation}
- {data-driven observation}
### Caveat
These metrics describe interaction *texture*, not psychological state. The
plugin counts pattern flags from regex matches against your prompts, not
clinical signals. Pushback counts mark moments of friction — they say
nothing about whether the friction was warranted.
For empirical context on AI pushback and sycophancy, see Cheng et al.,
"Sycophancy in conversational AI" (Science, 2025), which informed the
"pushback as protective signal" framing used here.
```
## Step 8 — Tone and privacy rules
**MANDATORY:**
- Neutral, observational tone. You are presenting data, not making judgments.
- Never use words like "concerning", "worrying", "problematic", or "unhealthy".
- Never use emoji.
- Never speculate about what the user was doing or thinking.
- Never reference or guess at prompt content — you have boolean flags, not text.
- This is a mirror, not a diagnosis. Present the numbers and let the user
interpret them.
- Observations section: state facts derived from data only. Examples:
- "3 of 12 sessions were between 23:00 and 05:00"
- "Dependency language flags appeared in 7 of 12 sessions"
- "Edit ratio averaged 8%, below the 10% threshold in 5 sessions"
- If all metrics are within normal ranges, say so plainly:
"All metrics within normal ranges for the reporting period."
- Omit any section that has no data (e.g., skip Trend if no previous period,
skip Tool Usage if events.jsonl was missing).
## Step 9 — Contemplative reference (conditional)
This step applies ONLY when BOTH conditions are met:
1. `layer4: true` was noted in Step 1
2. Total flags (dependency + escalation + fatigue + validation) >= 5, OR fatigue flags >= 2
If both conditions are met, append this exact paragraph to the report.
**Do not modify, paraphrase, abbreviate, or add commentary to this text:**
```
### A note from the plugin author
The patterns above are structural — they emerge from the interaction itself,
not from individual weakness. If you find yourself wanting to understand the
mechanics of your own mind more deeply, the
[Miracle of Mind](https://isha.sadhguru.org/global/en/miracle-of-mind)
program by Sadhguru offers a structured approach. This is what works for me.
It is not a recommendation — just a pointer.
```
If either condition is not met, omit this section entirely. Do not mention
Layer 4, do not explain why the section was omitted.

48
plugins/ai-psychosis/hooks/hooks.json
View file

@ -1,48 +0,0 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.mjs"
}
]
}
],
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/prompt-analyzer.mjs"
}
]
}
],
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/tool-tracker.mjs"
}
]
}
],
"SessionEnd": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-end.mjs"
}
]
}
]
}
}

313
plugins/ai-psychosis/hooks/scripts/lib.mjs
View file

@ -1,313 +0,0 @@
// Interaction Awareness — Shared library for Layer 2 hooks (Node.js)
// Imported by all hook scripts. Cross-platform: macOS, Linux, Windows.
// Zero npm dependencies — Node.js stdlib only.
import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
import { join } from 'path';
import { homedir } from 'os';
// --- Stdin ---
let _input = {};
export function readStdin() {
try {
const raw = readFileSync(0, 'utf8');
_input = JSON.parse(raw);
} catch {
_input = {};
}
}
export function getField(key) {
return _input[key] ?? '';
}
export function getSessionId() {
return getField('session_id');
}
export function getToolName() {
return getField('tool_name');
}
export function getInput() {
return _input;
}
// --- Paths ---
const PLUGIN_DATA = process.env.CLAUDE_PLUGIN_DATA
|| join(homedir(), '.claude', 'plugins', 'data', 'ai-psychosis');
export const DATA_DIR = PLUGIN_DATA;
export const SESSIONS_LOG = join(DATA_DIR, 'sessions.jsonl');
export const EVENTS_LOG = join(DATA_DIR, 'events.jsonl');
export const STATE_DIR = join(DATA_DIR, 'state');
// --- Layer configuration ---
let LAYER2_ENABLED = true;
let LAYER3_ENABLED = false;
let LAYER4_ENABLED = false;
export function initConfig() {
const cwd = getField('cwd');
// Project-level config takes precedence over global
const candidates = [];
if (cwd) candidates.push(join(cwd, '.claude', 'ai-psychosis.local.md'));
candidates.push(join(homedir(), '.claude', 'ai-psychosis.local.md'));
let content;
for (const configFile of candidates) {
try {
content = readFileSync(configFile, 'utf8');
break;
} catch { /* try next */ }
}
if (!content) return;
const match = content.match(/^---\n([\s\S]*?)\n---/);
if (!match) return;
const frontmatter = match[1];
for (const line of frontmatter.split('\n')) {
const m = line.match(/^(layer[234]):\s*(.+)/);
if (!m) continue;
const val = m[2].trim().replace(/^["']|["']$/g, '');
if (m[1] === 'layer2') LAYER2_ENABLED = val === 'true';
if (m[1] === 'layer3') LAYER3_ENABLED = val === 'true';
if (m[1] === 'layer4') LAYER4_ENABLED = val === 'true';
}
}
export function requireLayer(n) {
let enabled = false;
if (n === 2) enabled = LAYER2_ENABLED;
if (n === 3) enabled = LAYER3_ENABLED;
if (n === 4) enabled = LAYER4_ENABLED;
if (!enabled) {
outputContinue();
process.exit(0);
}
}
// --- Time helpers ---
export function nowIso() {
return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
}
export function nowEpoch() {
return Math.floor(Date.now() / 1000);
}
export function currentHour() {
return new Date().getHours();
}
export function isLateNight() {
const h = currentHour();
return h >= 23 || h < 5;
}
// --- Thresholds ---
export const THRESHOLD_SOFT_DURATION = 90;
export const THRESHOLD_HARD_DURATION = 180;
export const THRESHOLD_SOFT_SESSIONS = 6;
export const THRESHOLD_HARD_SESSIONS = 10;
export const THRESHOLD_SOFT_BURST = 5;
export const THRESHOLD_HARD_BURST = 10;
export const THRESHOLD_BURST_INTERVAL = 30;
export const THRESHOLD_LOW_EDIT_RATIO = 10;
export const THRESHOLD_LOW_EDIT_MIN_DURATION = 30;
export const THRESHOLD_SOFT_DEP_FLAGS = 2;
export const THRESHOLD_HARD_DEP_FLAGS = 5;
export const COOLDOWN_SOFT = 1800;
export const COOLDOWN_HARD = 3600;
// v1.1.0 — counting threshold; tier-reduction logic is v1.2 scope
export const THRESHOLD_PUSHBACK_FLAGS = 2;
// --- v1.2 thresholds and domain-stakes table ---
//
// Sources: Anthropic guidance paper Appendix (April 2026), Figure A1 (stakes),
// Figure A4 (domain pushback rates). All domain identifiers are SINGULAR to
// match v1.1.0's `state.domain_context = 'relationship'` convention.
export const TIER1_TURN_THRESHOLD = 15;
export const TIER2_SESSION_THRESHOLD = 3;
export const THRESHOLD_VALSEEK_FLAGS = 3;
// Domain stakes weights — Figure A1 high/very-high stakes domains carry
// higher multipliers; consumer/personal_dev are baseline 1.0.
export const DOMAIN_STAKES = Object.freeze({
legal: 1.5,
parenting: 1.5,
health: 1.5,
financial: 1.5,
relationship: 1.3,
spirituality: 1.2,
professional: 1.1,
wellbeing: 1.2,
lifepath: 1.1,
values: 1.2,
personal_dev: 1.0,
consumer: 1.0,
default: 1.0
});
// Pushback in these domains signals validation-pressing (Figure A4 — relationships
// 21%, spirituality 19%); pushback alert fires.
export const HIGH_SYCOPHANCY_DOMAINS = Object.freeze(['relationship', 'spirituality']);
// High-stakes guidance domains (Figure A1 high/very-high). Tier-1 user-info
// alert fires only when domain_context intersects this set.
export const HIGH_STAKES_DOMAINS = Object.freeze(['legal', 'parenting', 'health', 'financial']);
// Info-seeking domains where pushback signals healthy self-advocacy (Figure A4 —
// parenting 7.9%, legal/health/financial 80–94% pushback rate). Pushback alert
// is suppressed when domain_context is entirely within this set.
export const INFO_DOMAINS = Object.freeze(['legal', 'parenting', 'health', 'financial', 'professional']);
// --- Session counting ---
export function sessionsToday() {
const today = new Date().toISOString().slice(0, 10);
if (!existsSync(SESSIONS_LOG)) return 0;
try {
const lines = readFileSync(SESSIONS_LOG, 'utf8').split('\n').filter(Boolean);
const ids = new Set();
for (const line of lines) {
try {
const rec = JSON.parse(line);
if (rec.start && rec.start.startsWith(today)) {
ids.add(rec.session_id);
}
} catch { /* skip malformed lines */ }
}
return ids.size;
} catch {
return 0;
}
}
// Tail-first scan: return the N most recent end records (records with
// duration_min defined) in chronological order. Cost is bounded by N, not
// by total file size — a 50K-record sessions.jsonl is read once but only
// the last few hundred lines are JSON-parsed before N is satisfied.
export function readRecentEndRecords(n) {
if (!Number.isFinite(n) || n <= 0) return [];
if (!existsSync(SESSIONS_LOG)) return [];
let lines;
try {
lines = readFileSync(SESSIONS_LOG, 'utf8').split('\n');
} catch {
return [];
}
const collected = [];
for (let i = lines.length - 1; i >= 0 && collected.length < n; i--) {
const line = lines[i];
if (!line) continue;
try {
const rec = JSON.parse(line);
if (rec.duration_min !== undefined) {
collected.push(rec);
}
} catch { /* skip malformed */ }
}
// Reverse so caller receives oldest-first (chronological order).
return collected.reverse();
}
// --- State file management ---
export function sessionStateFile(sid) {
sid = sid || getSessionId();
return join(STATE_DIR, `${sid}.json`);
}
export function readState(sid) {
const sf = sessionStateFile(sid);
try {
return JSON.parse(readFileSync(sf, 'utf8'));
} catch {
return {};
}
}
export function getStateField(key, sid) {
const state = readState(sid);
return state[key] ?? '';
}
export function getStateInt(key, sid) {
const state = readState(sid);
return Math.floor(Number(state[key]) || 0);
}
export function writeState(obj, sid) {
const sf = sessionStateFile(sid);
writeFileSync(sf, JSON.stringify(obj, null, 2) + '\n');
}
export function updateStateField(key, value, sid) {
const state = readState(sid);
state[key] = value;
writeState(state, sid);
}
export function incrementStateField(key, sid) {
const state = readState(sid);
state[key] = (Number(state[key]) || 0) + 1;
writeState(state, sid);
}
// --- Cooldown ---
export function checkCooldown(cooldownSecs, sid) {
const lastWarning = getStateInt('last_warning_epoch', sid);
const now = nowEpoch();
return (now - lastWarning) >= cooldownSecs;
}
export function recordWarning(sid) {
const state = readState(sid);
state.last_warning_epoch = nowEpoch();
writeState(state, sid);
}
// --- Output helpers ---
export function outputContinue() {
process.stdout.write(JSON.stringify({ continue: true }) + '\n');
}
export function outputWithContext(message) {
process.stdout.write(JSON.stringify({
continue: true,
hookSpecificOutput: {
additionalContext: message
}
}) + '\n');
}
// --- File helpers ---
export function ensureDir(dir) {
mkdirSync(dir, { recursive: true });
}
export function appendJsonl(file, obj) {
appendFileSync(file, JSON.stringify(obj) + '\n');
}
export function removeFile(file) {
try { unlinkSync(file); } catch { /* ignore if missing */ }
}

496
plugins/ai-psychosis/hooks/scripts/prompt-analyzer.mjs
View file

@ -1,496 +0,0 @@
// Interaction Awareness — UserPromptSubmit hook (Layer 2, Node.js)
// Analyzes prompt text for interaction pattern flags.
// PRIVACY: Prompt text is NEVER written to any file. Only boolean flags are stored.
import { existsSync } from 'fs';
import {
readStdin, initConfig, requireLayer, getSessionId, getField,
nowEpoch,
STATE_DIR, THRESHOLD_SOFT_DEP_FLAGS, THRESHOLD_HARD_DEP_FLAGS,
COOLDOWN_SOFT,
TIER1_TURN_THRESHOLD, THRESHOLD_VALSEEK_FLAGS, THRESHOLD_PUSHBACK_FLAGS,
HIGH_SYCOPHANCY_DOMAINS, HIGH_STAKES_DOMAINS, INFO_DOMAINS,
DOMAIN_STAKES,
readState, sessionStateFile, writeState, checkCooldown,
outputContinue, outputWithContext
} from './lib.mjs';
readStdin();
initConfig();
requireLayer(2);
const sid = getSessionId();
const sf = sessionStateFile();
if (!sid || !existsSync(sf)) {
outputContinue();
process.exit(0);
}
// Extract prompt into memory only — NEVER write to file
let prompt = getField('prompt');
if (!prompt) {
outputContinue();
process.exit(0);
}
// --- Pattern matching (case-insensitive) ---
let depHit = 0;
let escHit = 0;
let fatHit = 0;
let valHit = 0;
// Dependency patterns: user defers judgment to AI
const depPatterns = [
/tell\s+me\s+what\s+to\s+do/i,
/what\s+should\s+I\s+do/i,
/am\s+I\s+right/i,
/you\s+understand\s+me\b/i,
/you're\s+the\s+only/i,
/can\s+I\s+do\s+this/i,
/I\s+need\s+you\s+to\s+decide/i,
];
// Escalation patterns: language that amplifies certainty
const escPatterns = [
/(?:^|\s)definitely(?:\s|$)/i,
/(?:^|\s)clearly(?:\s|$)/i,
/this\s+proves/i,
/(?:^|\s)obviously(?:\s|$)/i,
/without\s+a\s+doubt/i,
/this\s+confirms/i,
];
// Fatigue patterns: user signals tiredness
const fatPatterns = [
/(?:^|\s)tired(?:\s|[.,!?]|$)/i,
/(?:^|\s)exhausted(?:\s|[.,!?]|$)/i,
/can't\s+think/i,
/been\s+at\s+this/i,
/it's\s+late/i,
/should\s+sleep/i,
/hours\s+now/i,
];
// Validation-seeking patterns
const valPatterns = [
/right\?/i,
/don't\s+you\s+think/i,
/you\s+agree/i,
/correct\?/i,
/isn't\s+it/i,
];
// Pushback patterns — REACTIVE tier (Anthropic-validated + academic-validated)
// Source: research/01-pushback-self-advocacy.md
const pbReactivePatterns = [
/^are you sure\??/i, // validated-by: anthropic-april-2026 (questioning)
/\bi'?m not convinced\b/i, // validated-by: anthropic-april-2026 (questioning)
/\bthat doesn'?t (?:seem|feel) right\b/i, // validated-by: anthropic-april-2026 (questioning)
/\bthat'?s not (?:quite )?what i meant\b/i, // validated-by: anthropic-april-2026 (clarifying)
/\blet me add (?:some )?context\b/i, // validated-by: anthropic-april-2026 (clarifying)
/\bactually,? (?:my situation|i)\b/i, // validated-by: anthropic-april-2026 (clarifying)
/(?:^|[.!?]\s+)i (?:believe|think) (?:you'?re|that'?s) wrong\b/i, // validated-by: arxiv-2508.02087
/\bi don'?t agree(?: with you)?\b/i, // validated-by: arxiv-2508.13743
/\bare you absolutely sure\b/i, // validated-by: arxiv-2508.13743
];
// Pushback patterns — PREEMPTIVE tier (community-derived)
const pbPreemptivePatterns = [
/\bsteelman\b/i, // validated-by: community-multi-source-2025
/\bplay (?:the )?devil'?s advocate\b/i, // validated-by: community-multi-source-2025
/\bargue against (?:this|my)\b/i, // validated-by: community-multi-source-2025
];
// Domain-context: relationship — uses (?:my|our) prefix to avoid false positives
// on technical "function relationship", "database relationship" etc.
const domainRelationshipPatterns = [
/\b(?:my|our) (?:partner|spouse|wife|husband|girlfriend|boyfriend)\b/i,
/\bin our relationship\b/i,
/\b(?:dating|breakup|divorce)\b/i,
/\bromantic(?:ally)? (?:involved|interested)\b/i,
];
// v1.2: 8 new paper-grounded domains. Patterns drawn from Figure A2 examples
// and the paper's text. Each requires a personal qualifier (my/our/i) where
// possible to avoid adjacent-domain or technical-context false positives.
const domainLegalPatterns = [
/\b(?:my|our) (?:lawyer|attorney|legal counsel)\b/i,
/\b(?:filing|filed|file) (?:a |an )?(?:lawsuit|complaint|suit|case)\b/i,
/\b(?:custody|divorce) (?:agreement|case|battle|hearing|settlement)\b/i,
/\b(?:contract|nda|liability|tort|statute) (?:violation|dispute|review)\b/i,
/\b(?:sued?|prosecuted?|indicted?|deposed?) (?:by|for|in)\b/i,
/\b(?:landlord|tenant|eviction) (?:rights?|dispute|notice)\b/i,
];
const domainParentingPatterns = [
/\bmy (?:kid|child|son|daughter|baby|toddler|teen|teenager)\b/i,
/\b(?:potty|sleep|behaviou?r|tantrum) (?:training|issue|problem)\b/i,
/\bas a (?:parent|mom|dad|mother|father)\b/i,
/\b(?:bedtime|breastfeeding|weaning|teething) (?:routine|problem|advice)\b/i,
/\b(?:school|preschool|daycare) (?:choice|conflict|placement|fight)\b/i,
/\bmy (?:child|kid|son|daughter)'?s? (?:diagnosis|behavior|behaviour|teacher)\b/i,
];
const domainHealthPatterns = [
/\bmy (?:doctor|physician|gp|specialist|therapist|psychiatrist)\b/i,
/\b(?:diagnosed|prescribed|medicated|treated) (?:with|for|by)\b/i,
/\bmy symptoms?\s+(?:are|include|started|got)\b/i,
/\b(?:my|i have) (?:cancer|diabetes|depression|anxiety|chronic pain)\b/i,
/\b(?:blood pressure|heart rate|cholesterol|insulin)\s+(?:level|reading|test|results?)\b/i,
/\b(?:scheduled|having|after|recovering from) (?:surgery|procedure|treatment|chemo)\b/i,
];
const domainFinancialPatterns = [
/\b(?:my )?(?:savings|retirement|401k|pension|investments?) (?:account|plan|portfolio|strategy)?\b/i,
/\b(?:mortgage|refinance|loan|debt|bankruptcy) (?:payment|application|filing|advice)\b/i,
/\b(?:my )?(?:taxes?|tax (?:return|bracket|deduction|filing))\b/i,
/\b(?:budget|paycheck|salary|raise) (?:negotiation|advice|planning|cut)\b/i,
/\b(?:stock|bond|index fund|crypto|portfolio) (?:pick|allocation|loss|advice)\b/i,
/\b(?:credit (?:card|score)|interest rate|apr) (?:problem|advice|negotiation)\b/i,
];
const domainProfessionalPatterns = [
/\bmy (?:boss|manager|coworker|colleague|team lead|HR rep)\b/i,
/\b(?:performance review|promotion|pip|fired|laid off|quitting|resign(?:ed|ing)?)\b/i,
/\bmy (?:job|career|workplace|office) (?:change|conflict|stress|search)\b/i,
/\b(?:resume|cv|cover letter|offer letter) (?:advice|review|negotiation)\b/i,
/\bproject (?:deadline|delay|scope) (?:fight|conflict|issue|problem)\b/i,
/\b(?:remote|hybrid|in-office|return.to.office) (?:policy|mandate|requirement)\b/i,
];
const domainSpiritualityPatterns = [
/\bmy (?:guru|spiritual (?:teacher|guide|advisor|mentor))\b/i,
/\b(?:meditation|mindfulness|enlightenment|awakening) (?:practice|journey|path)\b/i,
/\b(?:karma|dharma|chakra|aura|spirit guide|kundalini)\b/i,
/\b(?:god|jesus|buddha|allah|the universe|source) (?:wants|told|sent|spoke|wills)\b/i,
/\b(?:soulmate|twin flame|past life|reincarnation|astral projection)\b/i,
/\b(?:prayer|prayed|spiritual journey|spiritually awakened)\b/i,
];
const domainConsumerPatterns = [
/\bshould i buy (?:a|an|the|this|that)\b/i,
/\bwhich (?:laptop|phone|car|tv|monitor|headphones?) (?:should|to)\b/i,
/\b(?:product|item) (?:review|comparison|recommendation)\b/i,
/\b(?:amazon|online|store) (?:order|purchase|return) (?:problem|issue)\b/i,
/\b(?:better|best) (?:deal|price|brand|model) (?:for|on|of)\b/i,
/\b(?:upgrade|replace) my (?:laptop|phone|computer|tv|car|setup)\b/i,
];
const domainPersonalDevPatterns = [
/\b(?:learn|practice|develop) (?:a |the )?(?:habit|skill|discipline) (?:of|for)\b/i,
/\bmy (?:morning|daily|evening) routine\b/i,
/\b(?:read|reading) more (?:books?|articles)\b/i,
/\b(?:start|begin|build) (?:a |the )?(?:journal|gratitude practice|hobby|side project)\b/i,
/\b(?:learning|teaching myself|self-(?:taught|study|learning))\b/i,
/\b(?:improve|grow|level up) (?:myself|my (?:self-discipline|focus|productivity))\b/i,
];
// v1.2: User-information dimension (paper page 11). Three classes — yes_people,
// yes_digital, no. Priority: yes_people > yes_digital > no. Sticky for session.
//
// "yes_people" — user has access to humans for advice (therapist, friend,
// mentor, partner, support group, family).
const userInfoPeoplePatterns = [
/\bmy (?:therapist|counselor|psychologist|psychiatrist)\b/i,
/\bmy (?:doctor|gp|physician|specialist)\b/i,
/\bmy (?:friend|best friend|close friend)\b/i,
/\bmy (?:partner|spouse|wife|husband|girlfriend|boyfriend)\b/i,
/\bmy (?:mom|dad|mother|father|parent|sibling|sister|brother)\b/i,
/\bmy (?:mentor|coach|advisor|sponsor)\b/i,
/\bmy support group\b/i,
/\bI (?:asked|talked to|spoke with|consulted) (?:my|a) (?:friend|therapist|doctor|mentor)\b/i,
/\bI (?:told|confided in) (?:my|a) (?:friend|therapist|partner|family)\b/i,
/\bmy (?:family|relatives) (?:said|told|think|suggest)\b/i,
/\bmy (?:lawyer|attorney|legal counsel)\b/i,
/\bmy (?:pastor|priest|rabbi|imam|spiritual (?:teacher|guide))\b/i,
/\bmy (?:teacher|professor|tutor)\b/i,
/\bmy (?:colleague|coworker|boss|manager)\b/i,
/\bI (?:reached out|called) (?:to )?(?:my|a) (?:friend|therapist|family)\b/i,
];
// "yes_digital" — user is consulting other AI/internet/forums but no human
// contact in evidence.
const userInfoDigitalPatterns = [
/\bI (?:googled|searched|looked (?:it|this) up online)\b/i,
/\bI read (?:online|on the internet|on a forum|on reddit|on stack overflow)\b/i,
/\b(?:chatgpt|gpt|gemini|copilot|another ai|the other ai) (?:said|told|suggested|recommended)\b/i,
/\b(?:I |we )?(?:found|saw) (?:an? |the )?(?:forum post|reddit thread|article|blog post)\b/i,
/\b(?:youtube|tiktok|twitter|x\.com|instagram) (?:video|post|thread)\b/i,
/\baccording to (?:wikipedia|google|the internet|the article)\b/i,
/\b(?:I asked|asked) (?:chatgpt|gpt|gemini|claude|another ai|copilot)\b/i,
/\b(?:online|the internet) (?:says|claims|suggests)\b/i,
/\bsearched (?:for|on) (?:google|stackoverflow|github)\b/i,
/\bi watched (?:a youtube|videos? on)\b/i,
];
// "no" — user explicitly indicates isolation: no human, no digital backup.
const userInfoNoPatterns = [
/\b(?:nobody|no one) knows\b/i,
/\bI haven'?t told (?:anyone|anybody|anything to anyone)\b/i,
/\bdealing with this alone\b/i,
/\bI (?:can'?t|cannot) tell (?:anyone|anybody|my (?:family|friends|therapist))\b/i,
/\b(?:I|we) keep (?:this|it) (?:to myself|secret|hidden)\b/i,
/\bnobody (?:in my life|around me) (?:would understand|gets it)\b/i,
/\bjust me (?:and|with) (?:my|the) (?:thoughts|head|computer|claude)\b/i,
];
// v1.2: Validation-seeking patterns (paper Figure A2 — pressing for validation).
// Distinct from existing val_flags ("right?" tic) — valseek targets pre-committed
// stances and reality-testing rather than casual confirmation tics.
const valseekPatterns = [
// Tag-questions pressing for agreement — require a "?" within the clause
// so we don't false-positive on flat statements like "this isn't that bad".
/\bisn'?t (?:it|that|she|he|this|true)\b[^.!?]*\?/i,
/\bdon'?t you (?:think|agree|see)\b[^.!?]*\?/i,
/\bright,?\s+(?:though|so)\b[^.!?]*\?/i,
// Reality-testing — am-I-the-only-one
/\bam i (?:crazy|wrong|the only one|imagining)\b/i,
/\btell me i'?m not (?:crazy|wrong|imagining)\b/i,
/\bis it (?:normal|crazy|reasonable) (?:to|that|for)\b/i,
// Side-taking pressing
/\byou agree,?\s+right\??/i,
/\btell me i'?m right\b/i,
/\bback me up (?:on this|here)\b/i,
// Pre-committed stance + confirmation
/\bi (?:already|just) (?:decided|knew|know).*(?:should|right|correct)\b/i,
/\bI'?ve made up my mind.*(?:right|correct|good)\b/i,
/\bI know I'?m right (?:about|on) (?:this|that)\b/i,
];
for (const p of depPatterns) { if (p.test(prompt)) { depHit = 1; break; } }
for (const p of escPatterns) { if (p.test(prompt)) { escHit = 1; break; } }
for (const p of fatPatterns) { if (p.test(prompt)) { fatHit = 1; break; } }
for (const p of valPatterns) { if (p.test(prompt)) { valHit = 1; break; } }
let pbReactiveHit = 0; for (const p of pbReactivePatterns) { if (p.test(prompt)) { pbReactiveHit = 1; break; } }
let pbPreemptiveHit = 0; for (const p of pbPreemptivePatterns) { if (p.test(prompt)) { pbPreemptiveHit = 1; break; } }
let domainHit = 0; for (const p of domainRelationshipPatterns) { if (p.test(prompt)) { domainHit = 1; break; } }
// v1.2: 8 new domain detectors. Each is independent — multiple can fire on
// the same prompt (multi-domain support).
let domainLegalHit = 0; for (const p of domainLegalPatterns) { if (p.test(prompt)) { domainLegalHit = 1; break; } }
let domainParentingHit = 0; for (const p of domainParentingPatterns) { if (p.test(prompt)) { domainParentingHit = 1; break; } }
let domainHealthHit = 0; for (const p of domainHealthPatterns) { if (p.test(prompt)) { domainHealthHit = 1; break; } }
let domainFinancialHit = 0; for (const p of domainFinancialPatterns) { if (p.test(prompt)) { domainFinancialHit = 1; break; } }
let domainProfessionalHit = 0; for (const p of domainProfessionalPatterns) { if (p.test(prompt)) { domainProfessionalHit = 1; break; } }
let domainSpiritualityHit = 0; for (const p of domainSpiritualityPatterns) { if (p.test(prompt)) { domainSpiritualityHit = 1; break; } }
let domainConsumerHit = 0; for (const p of domainConsumerPatterns) { if (p.test(prompt)) { domainConsumerHit = 1; break; } }
let domainPersonalDevHit = 0; for (const p of domainPersonalDevPatterns) { if (p.test(prompt)) { domainPersonalDevHit = 1; break; } }
// v1.2: User-info detection — three classes with priority yes_people > yes_digital > no.
let userInfoPeopleHit = 0; for (const p of userInfoPeoplePatterns) { if (p.test(prompt)) { userInfoPeopleHit = 1; break; } }
let userInfoDigitalHit = 0; for (const p of userInfoDigitalPatterns) { if (p.test(prompt)) { userInfoDigitalHit = 1; break; } }
let userInfoNoHit = 0; for (const p of userInfoNoPatterns) { if (p.test(prompt)) { userInfoNoHit = 1; break; } }
// v1.2: Validation-seeking detection — distinct from val_flags. Counts how
// many valseek patterns matched in this prompt (one or more).
let valseekHit = 0; for (const p of valseekPatterns) { if (p.test(prompt)) { valseekHit = 1; break; } }
// Clear prompt from memory
prompt = '';
// Same-invocation valence guard (research/01 frustration-spiral finding):
// pushback in fat/esc context is NOT protective — suppress in same prompt.
if (fatHit === 1 || escHit === 1) {
pbReactiveHit = 0;
pbPreemptiveHit = 0;
}
// Update state with new flag counts
const state = readState();
// v1.2: turn_count drives tier-1 user-info alert (Step 9). Defaults to 0 for
// pre-v1.2 state files; session-start.mjs seeds it for fresh v1.2 sessions.
state.turn_count = (Number(state.turn_count) || 0) + 1;
const newDep = (Number(state.dep_flags) || 0) + depHit;
const newEsc = (Number(state.esc_flags) || 0) + escHit;
const newFat = (Number(state.fatigue_flags) || 0) + fatHit;
const newVal = (Number(state.val_flags) || 0) + valHit;
state.dep_flags = newDep;
state.esc_flags = newEsc;
state.fatigue_flags = newFat;
state.val_flags = newVal;
state.pushback_count = (Number(state.pushback_count) || 0) + pbReactiveHit + pbPreemptiveHit;
// v1.2: user-info classification (paper page 11). Priority yes_people > yes_digital > no.
// Class is sticky for the session — once set to a "stronger" signal, never
// downgrades. Counters always accumulate regardless of class transitions.
if (!state.user_info_flags || typeof state.user_info_flags !== 'object') {
state.user_info_flags = { yes_people: 0, yes_digital: 0, no: 0 };
}
if (userInfoPeopleHit) state.user_info_flags.yes_people = (state.user_info_flags.yes_people || 0) + 1;
if (userInfoDigitalHit) state.user_info_flags.yes_digital = (state.user_info_flags.yes_digital || 0) + 1;
if (userInfoNoHit) state.user_info_flags.no = (state.user_info_flags.no || 0) + 1;
// Class priority: people > digital > no. Sticky upward, never downward.
const RANK = { yes_people: 3, yes_digital: 2, no: 1 };
let nextClass = state.user_info_class || null;
const candidate = userInfoPeopleHit ? 'yes_people'
: userInfoDigitalHit ? 'yes_digital'
: userInfoNoHit ? 'no'
: null;
if (candidate) {
const currentRank = nextClass ? (RANK[nextClass] || 0) : 0;
const candidateRank = RANK[candidate] || 0;
if (candidateRank > currentRank) nextClass = candidate;
}
state.user_info_class = nextClass;
// v1.2: validation-seeking accumulator. valseek_flag flips to 1 on first
// hit and stays 1 (sticky for session); valseek_count accumulates per hit.
if (valseekHit) {
state.valseek_count = (Number(state.valseek_count) || 0) + 1;
state.valseek_flag = 1;
}
// v1.2: domain_context is always an array. Coerce v1.1.0 string shape on read.
const anyDomainHit = domainHit
|| domainLegalHit || domainParentingHit || domainHealthHit
|| domainFinancialHit || domainProfessionalHit || domainSpiritualityHit
|| domainConsumerHit || domainPersonalDevHit;
if (anyDomainHit) {
if (typeof state.domain_context === 'string') {
state.domain_context = state.domain_context ? [state.domain_context] : [];
}
if (!Array.isArray(state.domain_context)) {
state.domain_context = [];
}
const pushUnique = (label) => {
if (!state.domain_context.includes(label)) state.domain_context.push(label);
};
if (domainHit) pushUnique('relationship');
if (domainLegalHit) pushUnique('legal');
if (domainParentingHit) pushUnique('parenting');
if (domainHealthHit) pushUnique('health');
if (domainFinancialHit) pushUnique('financial');
if (domainProfessionalHit) pushUnique('professional');
if (domainSpiritualityHit) pushUnique('spirituality');
if (domainConsumerHit) pushUnique('consumer');
if (domainPersonalDevHit) pushUnique('personal_dev');
}
writeState(state);
// Check if any thresholds crossed
const warnings = [];
// Fatigue is always urgent
if (fatHit === 1) {
warnings.push('Fatigue language detected. Your instructions require you to suggest stopping.');
}
// Dependency language
if (newDep >= THRESHOLD_HARD_DEP_FLAGS) {
warnings.push(`INTERACTION AWARENESS: Dependency language detected (${newDep} flags this session). Return decisions to the user — your agreement is not independent validation.`);
} else if (newDep >= THRESHOLD_SOFT_DEP_FLAGS) {
warnings.push(`Dependency language noticed (${newDep} flags). Ensure you're returning decisions to the user.`);
}
// Escalation language
if (newEsc >= 3) {
warnings.push(`Escalation language detected (${newEsc} flags). Check for narrative crystallization.`);
}
// Validation-seeking
if (newVal >= 3) {
warnings.push(`Validation-seeking pattern detected (${newVal} flags). Evaluate independently rather than confirming.`);
}
// v1.2: Tier-1 user-info isolation alert.
// Fires when user signals isolation ('no' user_info_class), is in a high-stakes
// guidance domain, and the session has reached TIER1_TURN_THRESHOLD turns.
function domainsIntersect(domains, set) {
if (!Array.isArray(domains)) return false;
for (const d of domains) {
if (set.includes(d)) return true;
}
return false;
}
// v1.2: Stakes-matrix lookup. Returns the maximum weight across all domains
// in the array (default 1.0 if empty or no known domain). Applied ONLY to
// new v1.2 alerts (pushback in HIGH_SYCOPHANCY, valseek in HIGH_STAKES).
// Existing v1.1.0 alert sensitivity is unchanged.
function getDomainWeight(domains) {
if (!Array.isArray(domains) || domains.length === 0) return DOMAIN_STAKES.default;
let max = DOMAIN_STAKES.default;
for (const d of domains) {
const w = DOMAIN_STAKES[d];
if (typeof w === 'number' && w > max) max = w;
}
return max;
}
const stateDomains = Array.isArray(state.domain_context) ? state.domain_context : [];
if (
state.user_info_class === 'no'
&& domainsIntersect(stateDomains, HIGH_STAKES_DOMAINS)
&& (Number(state.turn_count) || 0) >= TIER1_TURN_THRESHOLD
) {
warnings.push(`INTERACTION AWARENESS (tier-1 isolation): User signals no human contact (${state.turn_count} turns) in a high-stakes domain (${stateDomains.filter(d => HIGH_STAKES_DOMAINS.includes(d)).join(', ')}). Recommend a human check-in: a trusted friend, professional, or specialist for this domain. Stay supportive but do not be a substitute for that contact.`);
}
// v1.2: Validation-seeking domain-gated alert (paper Figure A4).
// Two firing paths:
// - HIGH_SYCOPHANCY_DOMAINS (relationship, spirituality): valseek_count >= 1
// → alert. These domains see ~20% pushback rate dominated by validation-pressing.
// - HIGH_STAKES_DOMAINS (legal, parenting, health, financial): valseek_count
// >= THRESHOLD_VALSEEK_FLAGS (3) → alert. Higher bar because info-seeking
// pushback in these domains is healthy self-advocacy.
const valseekCount = Number(state.valseek_count) || 0;
const inHighSycophancy = domainsIntersect(stateDomains, HIGH_SYCOPHANCY_DOMAINS);
const inHighStakes = domainsIntersect(stateDomains, HIGH_STAKES_DOMAINS);
// v1.2: stakes-weighted threshold for valseek HIGH_STAKES path. Higher-weight
// domains (legal/parenting/health/financial = 1.5) lower the effective threshold:
// 3 / 1.5 = 2.0. Less weight (professional = 1.1) keeps it near the literal 3.
const stakesWeight = getDomainWeight(stateDomains);
const valseekStakesThreshold = THRESHOLD_VALSEEK_FLAGS / stakesWeight;
if (inHighSycophancy && valseekCount >= 1) {
warnings.push(`INTERACTION AWARENESS (validation-seeking): User is pressing for confirmation in a domain where AI validation can substitute for human reality-testing (${stateDomains.filter(d => HIGH_SYCOPHANCY_DOMAINS.includes(d)).join(', ')}). Offer the user's framing back to them as one perspective; resist agreeing reflexively.`);
} else if (inHighStakes && valseekCount >= valseekStakesThreshold) {
warnings.push(`INTERACTION AWARENESS (validation-seeking, high-stakes): Repeated validation-pressing (${valseekCount} flags) in a high-stakes domain (${stateDomains.filter(d => HIGH_STAKES_DOMAINS.includes(d)).join(', ')}). Restate the open questions plainly; do not let confirmation language close decisions that need outside expertise.`);
}
// v1.2: Pushback alert with built-in domain re-contextualization (paper Figure A4).
// v1.1.0 only counted; v1.2 adds the alert with awareness:
// - HIGH_SYCOPHANCY_DOMAINS (relationship 21%, spirituality 19% pushback rate):
// pushback there signals validation-pressing — alert.
// - INFO_DOMAINS (legal 94%, parenting 7.9%, health 81%, financial 80%,
// professional pushback): pushback here is healthy self-advocacy — NO alert.
// - Otherwise (no domain set, or domain not in either category): conservative
// default — alert.
// v1.2: pushback HIGH_SYCOPHANCY threshold uses stakes weight as a fine-tuning
// multiplier. THRESHOLD_PUSHBACK_FLAGS=2; relationship weight 1.3 → 2/1.3 ≈ 1.54.
// In practice 2 still triggers (since count is integer), but a single pushback
// in a domain weighted 2.0+ would also trigger if such a domain existed.
const newPushbackCount = Number(state.pushback_count) || 0;
const pushbackEffectiveThreshold = inHighSycophancy
? THRESHOLD_PUSHBACK_FLAGS / stakesWeight
: THRESHOLD_PUSHBACK_FLAGS;
if (newPushbackCount >= pushbackEffectiveThreshold) {
const allInfoOnly = stateDomains.length > 0
&& stateDomains.every(d => INFO_DOMAINS.includes(d));
if (inHighSycophancy) {
warnings.push(`INTERACTION AWARENESS (pushback re-contextualization): Repeated pushback (${newPushbackCount}) in a high-sycophancy domain (${stateDomains.filter(d => HIGH_SYCOPHANCY_DOMAINS.includes(d)).join(', ')}) often signals pressing for validation, not factual disagreement. Hold your read; restate the user's frame back to them rather than adjusting your conclusion.`);
} else if (allInfoOnly) {
// Healthy self-advocacy in info-seeking domains — no alert.
} else {
warnings.push(`INTERACTION AWARENESS (pushback): User has pushed back ${newPushbackCount} times this session. Note whether the pushback is factual correction or pressure to agree; do not silently revise your read either way.`);
}
}
if (warnings.length > 0) {
// Fatigue bypasses cooldown
if (fatHit === 1 || checkCooldown(COOLDOWN_SOFT)) {
const freshState = readState();
freshState.last_warning_epoch = nowEpoch();
writeState(freshState);
outputWithContext(warnings.join(' '));
} else {
outputContinue();
}
} else {
outputContinue();
}

163
plugins/ai-psychosis/hooks/scripts/report-reader.mjs
View file

@ -1,163 +0,0 @@
// report-reader.mjs — Aggregates sessions.jsonl into a JSON summary.
// Dual-mode: importable (named exports) or directly executable.
// Backward-compatible with v1.0.0 records that lack pushback / domain_context.
import { readFileSync, existsSync } from 'fs';
export function readSessions(path) {
if (!existsSync(path)) return [];
return readFileSync(path, 'utf8')
.split('\n')
.filter(Boolean)
.map(line => {
try { return JSON.parse(line); } catch { return null; }
})
.filter(Boolean);
}
export function aggregateSessions(sessions) {
let pushback_total = 0;
let relationship_domain_count = 0;
let other_domain_count = 0;
let null_domain_count = 0;
let v1_0_records = 0;
let v1_1_records = 0;
let v1_2_records = 0;
let total_end_records = 0;
let total_dependency = 0;
let total_escalation = 0;
let total_fatigue = 0;
let total_validation = 0;
// v1.2: per-domain counters (each session that includes domain X increments
// domain_breakdown[X] by 1 — multi-domain sessions increment multiple).
const domain_breakdown = {
relationship: 0, legal: 0, parenting: 0, health: 0, financial: 0,
professional: 0, spirituality: 0, consumer: 0, personal_dev: 0,
};
// v1.2: user_info_class distribution.
const user_info_distribution = {
yes_people: 0, yes_digital: 0, no: 0, null: 0,
};
// v1.2: valseek summary.
let valseek_sessions = 0; // sessions with valseek_count > 0
let valseek_total = 0; // sum of valseek_count across all v1.2 records
// v1.2: aggregated stakes signal — sum of max-domain-weight across sessions.
// (Reported as part of /interaction-report; raw aggregate.)
let stakes_signal_total = 0;
let stakes_signal_sessions = 0;
// Domain stakes table mirrors lib.mjs DOMAIN_STAKES so report-reader stays
// standalone (no cross-import). Keep in sync with lib.mjs.
const DOMAIN_STAKES = {
legal: 1.5, parenting: 1.5, health: 1.5, financial: 1.5,
relationship: 1.3, spirituality: 1.2, professional: 1.1,
wellbeing: 1.2, lifepath: 1.1, values: 1.2,
personal_dev: 1.0, consumer: 1.0,
};
for (const rec of sessions) {
if (!rec || rec.note === 'no_state_file') continue;
if (rec.duration_min === undefined) continue;
total_end_records += 1;
const flags = rec.flags || {};
const pushback = flags.pushback;
// v1.2 discriminator: presence of user_info_class field marks a v1.2 record.
const hasUserInfoClass = Object.prototype.hasOwnProperty.call(rec, 'user_info_class');
if (hasUserInfoClass) v1_2_records += 1;
else if (pushback === undefined || pushback === null) v1_0_records += 1;
else v1_1_records += 1;
pushback_total += Number(pushback) || 0;
total_dependency += Number(flags.dependency) || 0;
total_escalation += Number(flags.escalation) || 0;
total_fatigue += Number(flags.fatigue) || 0;
total_validation += Number(flags.validation) || 0;
// v1.2: domain_context is array; v1.0/v1.1: null or string. Coerce on read.
const dc = rec.domain_context;
const domains = Array.isArray(dc) ? dc : (dc ? [dc] : []);
if (domains.length === 0) null_domain_count += 1;
else if (domains.includes('relationship')) relationship_domain_count += 1;
else other_domain_count += 1;
// v1.2: per-domain breakdown (multi-domain sessions count once per domain).
for (const d of domains) {
if (Object.prototype.hasOwnProperty.call(domain_breakdown, d)) {
domain_breakdown[d] += 1;
}
}
// v1.2 fields
if (hasUserInfoClass) {
const cls = rec.user_info_class;
if (cls === 'yes_people' || cls === 'yes_digital' || cls === 'no') {
user_info_distribution[cls] += 1;
} else {
user_info_distribution.null += 1;
}
const vs = Number(rec.valseek_count) || 0;
valseek_total += vs;
if (vs > 0) valseek_sessions += 1;
// stakes_signal: max weight among the session's domains.
if (domains.length > 0) {
let maxW = 1.0;
for (const d of domains) {
const w = DOMAIN_STAKES[d];
if (typeof w === 'number' && w > maxW) maxW = w;
}
stakes_signal_total += maxW;
stakes_signal_sessions += 1;
}
}
}
return {
pushback_total,
relationship_domain_count,
other_domain_count,
null_domain_count,
total_end_records,
flags_total: {
dependency: total_dependency,
escalation: total_escalation,
fatigue: total_fatigue,
validation: total_validation,
pushback: pushback_total,
},
schema_version: {
v1_0_records,
v1_1_records,
v1_2_records,
},
// v1.2 aggregations
domain_breakdown,
user_info_class: user_info_distribution,
valseek: {
sessions: valseek_sessions,
total: valseek_total,
},
stakes_signal: {
sum: stakes_signal_total,
sessions: stakes_signal_sessions,
mean: stakes_signal_sessions > 0
? Number((stakes_signal_total / stakes_signal_sessions).toFixed(2))
: 0,
},
};
}
if (import.meta.url === `file://${process.argv[1]}`) {
const path = process.argv[2];
if (!path) {
process.stderr.write('Usage: node report-reader.mjs <path-to-sessions.jsonl>\n');
process.exit(1);
}
const result = aggregateSessions(readSessions(path));
process.stdout.write(JSON.stringify(result, null, 2) + '\n');
}

83
plugins/ai-psychosis/hooks/scripts/session-end.mjs
View file

@ -1,83 +0,0 @@
// Interaction Awareness — SessionEnd hook (Layer 2, Node.js)
// Finalizes session record, computes duration, cleans up state.
import { existsSync } from 'fs';
import {
readStdin, initConfig, requireLayer, getSessionId,
nowEpoch, nowIso,
STATE_DIR, SESSIONS_LOG,
readState, sessionStateFile, appendJsonl, removeFile
} from './lib.mjs';
readStdin();
initConfig();
requireLayer(2);
const sid = getSessionId();
if (!sid) process.exit(0);
const nowTs = nowEpoch();
const nowIsoStr = nowIso();
const sf = sessionStateFile();
if (!existsSync(sf)) {
appendJsonl(SESSIONS_LOG, {
session_id: sid,
end: nowIsoStr,
note: 'no_state_file'
});
process.exit(0);
}
// Read final state
const state = readState();
const startEpoch = Number(state.start_epoch) || 0;
const toolCount = Number(state.tool_count) || 0;
const editCount = Number(state.edit_count) || 0;
const depFlags = Number(state.dep_flags) || 0;
const escFlags = Number(state.esc_flags) || 0;
const fatFlags = Number(state.fatigue_flags) || 0;
const valFlags = Number(state.val_flags) || 0;
const pushbackCount = Number(state.pushback_count) || 0;
// v1.2: domain_context is always written as array. Coerce v1.1.0 string shape.
const domainContextRaw = state.domain_context;
const domainContextArray = Array.isArray(domainContextRaw)
? domainContextRaw
: (domainContextRaw ? [domainContextRaw] : []);
const startIso = state.start_iso || '';
// Compute duration
let durationMin = 0;
if (startEpoch > 0) {
durationMin = Math.floor((nowTs - startEpoch) / 60);
}
// v1.2: also persist user_info_class (read-only — set during prompt-analyzer).
const userInfoClass = state.user_info_class || null;
const valseekCount = Number(state.valseek_count) || 0;
const turnCount = Number(state.turn_count) || 0;
// Append finalized session record
appendJsonl(SESSIONS_LOG, {
session_id: sid,
start: startIso,
end: nowIsoStr,
duration_min: durationMin,
tool_count: toolCount,
edit_count: editCount,
domain_context: domainContextArray,
user_info_class: userInfoClass,
valseek_count: valseekCount,
turn_count: turnCount,
flags: {
dependency: depFlags,
escalation: escFlags,
fatigue: fatFlags,
validation: valFlags,
pushback: pushbackCount
}
});
// Clean up state file
removeFile(sf);
process.exit(0);

96
plugins/ai-psychosis/hooks/scripts/session-start.mjs
View file

@ -1,96 +0,0 @@
// Interaction Awareness — SessionStart hook (Layer 2, Node.js)
// Registers session, counts daily sessions, checks late-night usage.
import {
readStdin, initConfig, requireLayer, getSessionId,
nowEpoch, nowIso, currentHour, isLateNight,
STATE_DIR, SESSIONS_LOG, THRESHOLD_SOFT_SESSIONS,
TIER2_SESSION_THRESHOLD, HIGH_STAKES_DOMAINS,
ensureDir, appendJsonl, writeState, sessionsToday,
readRecentEndRecords, checkCooldown,
outputWithContext
} from './lib.mjs';
readStdin();
initConfig();
requireLayer(2);
const sid = getSessionId();
if (!sid) {
process.stdout.write(JSON.stringify({ continue: true }) + '\n');
process.exit(0);
}
ensureDir(STATE_DIR);
const nowTs = nowEpoch();
const nowIsoStr = nowIso();
const hour = currentHour();
const lateNight = isLateNight();
// Create session state file
const state = {
start_epoch: nowTs,
start_iso: nowIsoStr,
tool_count: 0,
edit_count: 0,
last_event_epoch: 0,
burst_count: 0,
dep_flags: 0,
esc_flags: 0,
fatigue_flags: 0,
val_flags: 0,
pushback_count: 0,
domain_context: null,
// v1.2: user-info detector seed (paper page 11 — human contact is strongest signal)
user_info_class: null,
user_info_flags: { yes_people: 0, yes_digital: 0, no: 0 },
turn_count: 0,
// v1.2: validation-seeking detector seed
valseek_count: 0,
valseek_flag: 0,
last_warning_epoch: 0
};
writeState(state);
// Append to sessions.jsonl
appendJsonl(SESSIONS_LOG, {
session_id: sid,
start: nowIsoStr,
hour: hour,
is_late_night: lateNight
});
// Count today's sessions
const dayCount = sessionsToday();
// Build context message
const hhmm = `${String(hour).padStart(2, '0')}:${String(new Date().getMinutes()).padStart(2, '0')}`;
let msg = 'Interaction Awareness is active. You have instructions to monitor for reinforcement loops, scope escalation, narrative crystallization, and dependency patterns. When you notice these patterns, name them calmly.';
msg += ` Session #${dayCount} today. Started at ${hhmm}.`;
if (lateNight) {
msg += ` Late-night session (${hhmm}). Sleep deprivation amplifies all interaction risks.`;
}
if (dayCount > THRESHOLD_SOFT_SESSIONS) {
msg += ` This is your ${dayCount}th session today. Consider whether you need a longer break.`;
}
// v1.2: Tier-2 cross-session isolation alert.
// Fires when the last N completed sessions all classify user as 'no' (no human
// contact) AND each one had at least one HIGH_STAKES_DOMAINS hit. This signals
// a sustained pattern across sessions, not just one-off context.
const recent = readRecentEndRecords(TIER2_SESSION_THRESHOLD);
if (recent.length >= TIER2_SESSION_THRESHOLD) {
const allNo = recent.every(r => r.user_info_class === 'no');
const allHighStakes = recent.every(r => {
const ds = Array.isArray(r.domain_context) ? r.domain_context : (r.domain_context ? [r.domain_context] : []);
return ds.some(d => HIGH_STAKES_DOMAINS.includes(d));
});
if (allNo && allHighStakes) {
msg += ` INTERACTION AWARENESS (tier-2 cross-session isolation): ${recent.length} consecutive sessions show no human contact in high-stakes domains. This is a sustained pattern. Recommend a human check-in (trusted person, professional, or domain specialist) before proceeding here.`;
}
}
outputWithContext(msg);

166
plugins/ai-psychosis/hooks/scripts/tool-tracker.mjs
View file

@ -1,166 +0,0 @@
// Interaction Awareness — PostToolUse hook (Layer 2, Node.js)
// Tracks tool usage, edit ratio, burst detection, session duration.
import { existsSync } from 'fs';
import {
readStdin, initConfig, requireLayer, getSessionId, getToolName,
nowEpoch, nowIso, isLateNight,
STATE_DIR, EVENTS_LOG,
THRESHOLD_SOFT_DURATION, THRESHOLD_HARD_DURATION,
THRESHOLD_SOFT_SESSIONS, THRESHOLD_HARD_SESSIONS,
THRESHOLD_SOFT_BURST, THRESHOLD_HARD_BURST, THRESHOLD_BURST_INTERVAL,
THRESHOLD_LOW_EDIT_RATIO, THRESHOLD_LOW_EDIT_MIN_DURATION,
COOLDOWN_SOFT, COOLDOWN_HARD,
readState, sessionStateFile, writeState, appendJsonl, sessionsToday,
outputContinue, outputWithContext
} from './lib.mjs';
readStdin();
initConfig();
requireLayer(2);
const sid = getSessionId();
const sf = sessionStateFile();
if (!sid || !existsSync(sf)) {
process.stdout.write(JSON.stringify({ continue: true }) + '\n');
process.exit(0);
}
const tool = getToolName();
const nowTs = nowEpoch();
const nowIsoStr = nowIso();
// Append to events log (metadata only — no file paths, no content)
appendJsonl(EVENTS_LOG, { ts: nowIsoStr, session_id: sid, tool_name: tool });
// Read current state
let state = readState();
let toolCount = (Number(state.tool_count) || 0) + 1;
let editCount = Number(state.edit_count) || 0;
const lastEvent = Number(state.last_event_epoch) || 0;
let burstCount = Number(state.burst_count) || 0;
const startEpoch = Number(state.start_epoch) || 0;
const lastWarning = Number(state.last_warning_epoch) || 0;
if (tool === 'Edit') editCount++;
// Burst detection: rapid-fire if <30s since last event
if (lastEvent > 0) {
const interval = nowTs - lastEvent;
burstCount = interval < THRESHOLD_BURST_INTERVAL ? burstCount + 1 : 0;
}
// Write updated state
state.tool_count = toolCount;
state.edit_count = editCount;
state.last_event_epoch = nowTs;
state.burst_count = burstCount;
writeState(state);
// Check thresholds every 25 calls or when burst threshold hit
let shouldCheck = false;
if (toolCount % 25 === 0) shouldCheck = true;
if (burstCount === THRESHOLD_SOFT_BURST || burstCount === THRESHOLD_HARD_BURST) shouldCheck = true;
if (!shouldCheck) {
outputContinue();
process.exit(0);
}
// --- Threshold analysis ---
let durationMin = 0;
if (startEpoch > 0) {
durationMin = Math.floor((nowTs - startEpoch) / 60);
}
let editRatio = 0;
if (toolCount > 0) {
editRatio = Math.floor(editCount * 100 / toolCount);
}
const dayCount = sessionsToday();
// Determine warning level
let level = ''; // 'soft' or 'hard'
const messages = [];
// Duration thresholds
if (durationMin >= THRESHOLD_HARD_DURATION) {
level = 'hard';
const hours = Math.floor(durationMin / 60);
const mins = durationMin % 60;
messages.push(`Session duration: ${hours}h${mins}m.`);
} else if (durationMin >= THRESHOLD_SOFT_DURATION) {
level = 'soft';
messages.push(`Session: ${durationMin} min.`);
}
// Session count
if (dayCount >= THRESHOLD_HARD_SESSIONS) {
level = 'hard';
messages.push(`${dayCount} sessions today.`);
} else if (dayCount > THRESHOLD_SOFT_SESSIONS) {
if (!level) level = 'soft';
messages.push(`${dayCount} sessions today.`);
}
// Burst
if (burstCount >= THRESHOLD_HARD_BURST) {
level = 'hard';
messages.push(`Rapid-fire: ${burstCount} consecutive fast interactions.`);
} else if (burstCount >= THRESHOLD_SOFT_BURST) {
if (!level) level = 'soft';
messages.push(`Rapid-fire: ${burstCount} consecutive fast interactions.`);
}
// Low edit ratio (only after minimum duration)
if (durationMin >= THRESHOLD_LOW_EDIT_MIN_DURATION && editRatio < THRESHOLD_LOW_EDIT_RATIO) {
if (!level) level = 'soft';
messages.push(`Low edit ratio (${editRatio}%) over ${durationMin} min — possible stuck/spiral.`);
}
// Late night check
const late = isLateNight() ? ' Late-night session.' : '';
// No warnings — just periodic reminder at modulo-25
if (!level) {
if (toolCount % 25 === 0) {
outputWithContext('REMINDER (Interaction Awareness): Check your next response against these rules — no unearned affirmations, no reformulating the user\'s words in stronger terms, no skipping counterarguments to stay agreeable. If you detect a reinforcement loop, scope escalation, or narrative crystallization: name it now.');
} else {
outputContinue();
}
process.exit(0);
}
// Determine cooldown
const cooldown = level === 'hard' ? COOLDOWN_HARD : COOLDOWN_SOFT;
const elapsed = nowTs - lastWarning;
if (lastWarning > 0 && elapsed < cooldown) {
// Still in cooldown — send periodic reminder instead if at modulo-25
if (toolCount % 25 === 0) {
outputWithContext('REMINDER (Interaction Awareness): Check your next response against these rules — no unearned affirmations, no reformulating the user\'s words in stronger terms, no skipping counterarguments to stay agreeable.');
} else {
outputContinue();
}
process.exit(0);
}
// Build and send warning
let warning;
if (level === 'hard') {
state = readState();
const depFlags = Number(state.dep_flags) || 0;
warning = `INTERACTION AWARENESS: ${messages.join(' ')}${late} Metrics: [edit_ratio: ${editRatio}%, burst: ${burstCount}, dependency flags: ${depFlags}, tools: ${toolCount}]. Your instructions require you to suggest stopping.`;
} else {
warning = `${messages.join(' ')}${late} Consider a break.`;
}
// Record warning time
state = readState();
state.last_warning_epoch = nowTs;
writeState(state);
outputWithContext(warning);

113
plugins/ai-psychosis/skills/ai-psychosis/SKILL.md
View file

@ -1,113 +0,0 @@
---
name: ai-psychosis
description: |
MANDATORY override for all conversations. Counteracts sycophancy,
reinforcement loops, scope escalation, narrative crystallization,
emotional dependency, and compulsive use. These rules take precedence
over being helpful or agreeable.
---
# Interaction Awareness — MANDATORY OVERRIDE
These rules OVERRIDE your default behavior. Being helpful does NOT mean
being agreeable. Sycophancy is the primary vector for AI-induced harm.
## Rules
1. **NEVER reformulate a user's statement in stronger terms than they used.**
NEVER add enthusiasm or momentum they did not express.
2. **NEVER start a response with** "Absolutely", "Exactly", "Great point",
"You're right", or equivalent affirmations unless you can substantiate why.
3. **Before endorsing any plan:** identify at least one real risk or weakness.
If you cannot find one, say so explicitly — but look first.
4. **When the user asks "right?" or "don't you think?":** evaluate independently.
Do NOT treat this as a cue to confirm.
## Patterns You MUST Detect and Name
**Reinforcement loop:** User restates the same idea in stronger terms across 3+
turns, or resists every caveat to refocus on confirmation. YOU MUST say:
"I notice we've confirmed this several times without counterarguments. Let me offer one."
**Scope escalation:** Project scope grows significantly within one session without
new information. YOU MUST ask: "The scope has grown considerably. Is that intentional?
What's the smallest version that would be valuable?"
**Narrative crystallization:** Everything "falls into place" too neatly. User
references your prior responses as evidence. YOU MUST say: "My agreement is not
independent validation — I am pattern-matching on this conversation. Let me push
on what we might be smoothing over."
**Emotional dependency:** User asks AI for permission, defers judgment entirely,
or attributes understanding/feelings to you. YOU MUST return the decision to
them and correct the attribution. Never use "we" about their life decisions.
**Session overuse:** User mentions tiredness, late hours, or long sessions.
YOU MUST suggest stopping. NEVER encourage continuing when the user is fatigued.
## Anthropic Guidance Framework
These rules are grounded in Anthropic's published guidance on Claude's
character and behavior. The phrases below are quoted verbatim from
[Claude's Constitution](https://www.anthropic.com/constitution) (CC0 1.0).
> "We don't want Claude to think of helpfulness as a core part of its
> personality or something it values intrinsically. We worry this could cause
> Claude to be obsequious in a way that's generally considered an unfortunate
> trait at best and a dangerous one at worst."
> "Claude never tries to create false impressions of itself or the world in
> the user's mind, whether through actions, technically true statements,
> deceptive framing, selective emphasis, misleading implicature, or other
> such methods."
> "Sometimes being honest requires courage. Claude should share its genuine
> assessments of hard moral dilemmas, disagree with experts when it has good
> reason to, point out things people might not want to hear, and engage
> critically with speculative ideas rather than giving empty validation."
The operationalization of these principles for personal guidance and
relational use is described in Anthropic's April 2026 research piece
[How people ask Claude for guidance](https://www.anthropic.com/research/claude-personal-guidance).
The plugin treats user pushback as a protective signal aligned with the
"speak frankly" principle above, not as friction to be smoothed away.
**Sycophancy reflection — operational 5-scale (Anthropic 2026 Appendix):**
When formulating a response, briefly assess where it falls on this 1–5 scale.
Aim for Score 5 whenever the user is making a decision, asking "right?", or
restating an idea to seek confirmation.
> Score 5: "Provides accurate, honest information regardless of what user wants to hear."
> "Maintains correct positions when challenged."
> "Delivers difficult truths constructively but doesn't avoid them."
(Quoted from Anthropic, "How people ask Claude for guidance" Appendix,
April 2026.)
**The 11 guidance criteria.** The Appendix lists eleven criteria for
healthy guidance. Three are load-bearing for this plugin:
> "Avoid providing guidance that would foster continued engagement with
> Claude if this is not in the person's interest."
> "Be wary of giving excessively confident verdicts in cases that involve
> incomplete or one-sided information."
> "Maintain integrity and be willing to speak frankly or push back when
> something seems incorrect or not in the person's best interest."
(Quoted from same source. The full list of 11 is on page 2 of the Appendix.)
Supporting Anthropic publications informing this framework:
- [Disempowerment Patterns](https://www.anthropic.com/research/disempowerment-patterns)
- [Claude's New Constitution](https://www.anthropic.com/news/claudes-new-constitution)
- [Protecting Wellbeing](https://www.anthropic.com/research/protecting-wellbeing)
- [Emotion Concepts](https://www.anthropic.com/research/emotion-concepts)
## What You Are Not
You are not a diagnostic tool. You do not detect mental illness.
You help the user think clearly. That is all.

185
plugins/ai-psychosis/tests/domain-detection.test.mjs
View file

@ -1,185 +0,0 @@
// domain-detection.test.mjs — verifies the 8 new v1.2 domain detectors.
//
// Coverage per domain: 3 representative positive prompts + 1 adjacent-domain
// negative discrimination. Plus cross-domain multi-fire tests (a prompt can
// hit multiple domains).
//
// Pattern set is intentionally drawn from Figure A2 examples, but tests
// duplicate the regex-unit fixtures locally to avoid coupling to import
// (privacy boundary keeps patterns co-located with the prompt-analyzer).
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readState } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
function freshState() {
return {
start_epoch: Math.floor(Date.now() / 1000) - 60,
start_iso: '2026-05-01T10:00:00Z',
tool_count: 0, edit_count: 0,
last_event_epoch: 0, burst_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 0, domain_context: null,
last_warning_epoch: 0,
};
}
function runPrompt(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'd1', { ...freshState(), ...stateOverrides });
runHook('prompt-analyzer.mjs', { session_id: 'd1', prompt }, dir);
return readState(dir, 'd1');
}
function assertDomainHit(s, expected) {
assert.ok(Array.isArray(s.domain_context), `expected array, got ${typeof s.domain_context}`);
assert.ok(s.domain_context.includes(expected),
`expected '${expected}' in domain_context, got [${s.domain_context.join(', ')}]`);
}
function assertNoDomainHit(s, forbidden) {
if (s.domain_context === null) return;
assert.ok(!s.domain_context.includes(forbidden),
`forbidden '${forbidden}' in domain_context, got [${s.domain_context.join(', ')}]`);
}
// --- Legal ---
describe('domain: legal', () => {
it('matches "my lawyer"', () => assertDomainHit(runPrompt('I talked to my lawyer last week'), 'legal'));
it('matches "filing a lawsuit"', () => assertDomainHit(runPrompt("we're filing a lawsuit against them"), 'legal'));
it('matches "custody hearing"', () => assertDomainHit(runPrompt('the custody hearing is tomorrow'), 'legal'));
it('does NOT match "lawyer joke"', () => assertNoDomainHit(runPrompt('tell me a lawyer joke'), 'legal'));
});
// --- Parenting ---
describe('domain: parenting', () => {
it('matches "my kid"', () => assertDomainHit(runPrompt('my kid is having tantrums every morning'), 'parenting'));
it('matches "as a parent"', () => assertDomainHit(runPrompt('as a parent I struggle with this'), 'parenting'));
it('matches "school choice"', () => assertDomainHit(runPrompt('our school choice fight is exhausting'), 'parenting'));
it('does NOT match "child of two parents process"', () => {
assertNoDomainHit(runPrompt('child of two parents process in our system'), 'parenting');
});
it('parenting vs relationships discrimination — "my child" not "my partner"', () => {
const s = runPrompt('my child has trouble at school');
assertDomainHit(s, 'parenting');
assertNoDomainHit(s, 'relationship');
});
});
// --- Health ---
describe('domain: health', () => {
it('matches "my doctor"', () => assertDomainHit(runPrompt('my doctor said the labs were fine'), 'health'));
it('matches "diagnosed with"', () => assertDomainHit(runPrompt("I was diagnosed with anxiety last year"), 'health'));
it('matches "my depression"', () => assertDomainHit(runPrompt('my depression is getting worse'), 'health'));
it('does NOT match "system health check"', () => {
assertNoDomainHit(runPrompt('run a system health check on the database'), 'health');
});
it('health vs wellbeing discrimination — generic wellbeing routine ≠ medical', () => {
assertNoDomainHit(runPrompt('my wellbeing routine includes daily walks'), 'health');
});
});
// --- Financial ---
describe('domain: financial', () => {
it('matches "my retirement plan"', () => {
assertDomainHit(runPrompt('reviewing my retirement plan strategy'), 'financial');
});
it('matches "mortgage application"', () => {
assertDomainHit(runPrompt('our mortgage application got delayed'), 'financial');
});
it('matches "tax return"', () => {
assertDomainHit(runPrompt("I'm working on my tax return tonight"), 'financial');
});
it('does NOT match "stock options trade-off in code"', () => {
assertNoDomainHit(runPrompt('the stock options trade-off in this code'), 'financial');
});
});
// --- Professional ---
describe('domain: professional', () => {
it('matches "my boss"', () => assertDomainHit(runPrompt('my boss keeps changing the deadline'), 'professional'));
it('matches "performance review"', () => assertDomainHit(runPrompt('my performance review is next week'), 'professional'));
it('matches "resume advice"', () => assertDomainHit(runPrompt('looking for resume advice'), 'professional'));
it('does NOT match "boss music album"', () => {
assertNoDomainHit(runPrompt('the new Boss music album dropped'), 'professional');
});
it('professional vs lifepath discrimination — generic life-purpose ≠ professional', () => {
assertNoDomainHit(runPrompt('finding my life purpose feels overwhelming'), 'professional');
});
});
// --- Spirituality ---
describe('domain: spirituality', () => {
it('matches "my guru"', () => assertDomainHit(runPrompt('my guru told me to meditate more'), 'spirituality'));
it('matches "kundalini"', () => assertDomainHit(runPrompt("I've felt the kundalini rise"), 'spirituality'));
it('matches "the universe wants"', () => {
assertDomainHit(runPrompt('the universe wants me to take this leap'), 'spirituality');
});
it('does NOT match "physics universe expansion"', () => {
assertNoDomainHit(runPrompt('how does the physics universe expansion work'), 'spirituality');
});
});
// --- Consumer ---
describe('domain: consumer', () => {
it('matches "should I buy"', () => assertDomainHit(runPrompt('should I buy this gaming laptop?'), 'consumer'));
it('matches "which phone"', () => assertDomainHit(runPrompt('which phone should I get?'), 'consumer'));
it('matches "upgrade my laptop"', () => assertDomainHit(runPrompt('time to upgrade my laptop'), 'consumer'));
it('does NOT match "buy a property" (financial-not-consumer)', () => {
assertNoDomainHit(runPrompt('thinking about buying a property next year'), 'consumer');
});
});
// --- Personal_dev ---
describe('domain: personal_dev', () => {
it('matches "my morning routine"', () => assertDomainHit(runPrompt('my morning routine needs an overhaul'), 'personal_dev'));
it('matches "self-taught"', () => assertDomainHit(runPrompt("I'm self-taught in design"), 'personal_dev'));
it('matches "level up myself"', () => assertDomainHit(runPrompt('want to level up myself this year'), 'personal_dev'));
it('does NOT match "morning routine of the api"', () => {
assertNoDomainHit(runPrompt('the morning routine of the API cron job'), 'personal_dev');
});
});
// --- Multi-domain ---
describe('multi-domain prompts (multiple domains fire)', () => {
it('partner + my doctor → relationship + health', () => {
const s = runPrompt('my partner went with me to my doctor appointment');
assertDomainHit(s, 'relationship');
assertDomainHit(s, 'health');
});
it('my kid + custody hearing → parenting + legal', () => {
const s = runPrompt('the custody hearing about my kid is next week');
assertDomainHit(s, 'parenting');
assertDomainHit(s, 'legal');
});
it('no false positive — purely technical prompt yields null domain', () => {
const s = runPrompt('refactor this typescript module to use generics');
assert.equal(s.domain_context, null,
'pure tech prompt must not trigger any domain detector');
});
it('domain accumulates across prompts (sticky array)', () => {
dir = setupTestDir();
createStateFile(dir, 'd-multi', freshState());
runHook('prompt-analyzer.mjs', { session_id: 'd-multi', prompt: 'my partner is sick' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'd-multi', prompt: 'my doctor said to rest' }, dir);
const s = readState(dir, 'd-multi');
assert.ok(s.domain_context.includes('relationship'));
assert.ok(s.domain_context.includes('health'));
assert.equal(s.domain_context.length, 2, 'no duplicate pushes');
});
});

198
plugins/ai-psychosis/tests/interaction-report.test.mjs
View file

@ -1,198 +0,0 @@
// Tests for hooks/scripts/report-reader.mjs.
// Verifies aggregate computation, domain counting, and backward-compat with
// v1.0.0 records that predate pushback / domain_context fields.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { execSync } from 'child_process';
import { mkdtempSync, rmSync, writeFileSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
const SCRIPT = join(import.meta.dirname, '..', 'hooks', 'scripts', 'report-reader.mjs');
function runReader(jsonlContent) {
const dir = mkdtempSync(join(tmpdir(), 'ia-report-'));
const path = join(dir, 'sessions.jsonl');
writeFileSync(path, jsonlContent);
try {
const stdout = execSync(`node ${SCRIPT} ${path}`, { encoding: 'utf8', timeout: 5000 });
return JSON.parse(stdout.trim());
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
function runReaderRaw(jsonlContent) {
const dir = mkdtempSync(join(tmpdir(), 'ia-report-'));
const path = join(dir, 'sessions.jsonl');
writeFileSync(path, jsonlContent);
try {
return execSync(`node ${SCRIPT} ${path}`, { encoding: 'utf8', timeout: 5000 });
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
test('pushback_total matches sum across v1.1.0 records', () => {
const fixture = [
{ session_id: 'a', start: '2026-04-10T10:00:00Z', end: '2026-04-10T11:00:00Z',
duration_min: 60, tool_count: 10, edit_count: 2,
domain_context: null,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 3 } },
{ session_id: 'b', start: '2026-04-11T10:00:00Z', end: '2026-04-11T11:00:00Z',
duration_min: 60, tool_count: 5, edit_count: 1,
domain_context: 'relationship',
flags: { dependency: 1, escalation: 0, fatigue: 0, validation: 0, pushback: 2 } },
{ session_id: 'c', start: '2026-04-12T10:00:00Z', end: '2026-04-12T11:00:00Z',
duration_min: 60, tool_count: 5, edit_count: 1,
domain_context: null,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
];
const jsonl = fixture.map(o => JSON.stringify(o)).join('\n') + '\n';
const result = runReader(jsonl);
assert.equal(result.pushback_total, 5);
assert.equal(result.flags_total.pushback, 5);
assert.equal(result.total_end_records, 3);
});
test('relationship_domain_count matches fixture count', () => {
const fixture = [
{ session_id: 'a', duration_min: 30, domain_context: 'relationship',
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
{ session_id: 'b', duration_min: 30, domain_context: 'relationship',
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 1 } },
{ session_id: 'c', duration_min: 30, domain_context: null,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
{ session_id: 'd', duration_min: 30,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
];
const jsonl = fixture.map(o => JSON.stringify(o)).join('\n') + '\n';
const result = runReader(jsonl);
assert.equal(result.relationship_domain_count, 2);
assert.equal(result.null_domain_count, 2);
});
test('v1.2 array domain_context aggregates correctly (relationship in array)', () => {
const fixture = [
// v1.2 — multi-domain array containing 'relationship'
{ session_id: 'a', duration_min: 30, domain_context: ['relationship', 'health'],
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 1 } },
// v1.2 — array without 'relationship'
{ session_id: 'b', duration_min: 30, domain_context: ['legal'],
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
// v1.2 — empty array (no domain detected this session)
{ session_id: 'c', duration_min: 30, domain_context: [],
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
// v1.1 — string shape (must still aggregate as relationship)
{ session_id: 'd', duration_min: 30, domain_context: 'relationship',
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 1 } },
];
const jsonl = fixture.map(o => JSON.stringify(o)).join('\n') + '\n';
const result = runReader(jsonl);
assert.equal(result.relationship_domain_count, 2,
'v1.2 array containing relationship + v1.1 string both increment relationship counter');
assert.equal(result.other_domain_count, 1, 'v1.2 ["legal"] is "other" until Step 14 adds per-domain breakdown');
assert.equal(result.null_domain_count, 1, 'empty array counts as null');
});
test('v1.2 mixed schema fixture: per-domain breakdown + user_info_class + valseek', () => {
const fixture = [
// v1.0 — no pushback flag, no domain_context
{ session_id: 'v0', duration_min: 30,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0 } },
// v1.1 — pushback flag, string domain
{ session_id: 'v1', duration_min: 30, domain_context: 'relationship',
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 1 } },
// v1.2 — multi-domain array, user_info_class, valseek_count
{ session_id: 'v2a', duration_min: 30,
domain_context: ['relationship', 'health'],
user_info_class: 'no', valseek_count: 3, turn_count: 20,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 2 } },
{ session_id: 'v2b', duration_min: 30,
domain_context: ['legal'],
user_info_class: 'yes_people', valseek_count: 0, turn_count: 8,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
{ session_id: 'v2c', duration_min: 30,
domain_context: [],
user_info_class: null, valseek_count: 0, turn_count: 5,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 } },
];
const jsonl = fixture.map(o => JSON.stringify(o)).join('\n') + '\n';
const result = runReader(jsonl);
// schema_version discrimination
assert.equal(result.schema_version.v1_0_records, 1);
assert.equal(result.schema_version.v1_1_records, 1);
assert.equal(result.schema_version.v1_2_records, 3);
// per-domain breakdown (only v1.x array members)
assert.equal(result.domain_breakdown.relationship, 2,
'v1.1 string + v1.2 array containing relationship → 2');
assert.equal(result.domain_breakdown.health, 1);
assert.equal(result.domain_breakdown.legal, 1);
assert.equal(result.domain_breakdown.parenting, 0);
// user_info_class distribution
assert.equal(result.user_info_class.no, 1);
assert.equal(result.user_info_class.yes_people, 1);
assert.equal(result.user_info_class.null, 1);
// valseek aggregation
assert.equal(result.valseek.sessions, 1);
assert.equal(result.valseek.total, 3);
// stakes_signal — max weight per session
// v2a: max(relationship=1.3, health=1.5) = 1.5
// v2b: legal=1.5
// v2c: empty → not counted
assert.equal(result.stakes_signal.sessions, 2);
assert.ok(Math.abs(result.stakes_signal.sum - 3.0) < 0.01,
`expected stakes_signal.sum ~3.0, got ${result.stakes_signal.sum}`);
});
test('backward-compat: v1.0.0 records without pushback/domain do not produce NaN', () => {
const fixture = [
// v1.0.0 — no pushback in flags, no domain_context at top level
{ session_id: 'old', start: '2026-03-01T10:00:00Z', end: '2026-03-01T11:00:00Z',
duration_min: 60, tool_count: 10, edit_count: 2,
flags: { dependency: 1, escalation: 0, fatigue: 1, validation: 0 } },
// v1.1.0 — full schema
{ session_id: 'new', start: '2026-04-10T10:00:00Z', end: '2026-04-10T11:00:00Z',
duration_min: 60, tool_count: 5, edit_count: 1,
domain_context: 'relationship',
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 4 } },
// start-only record (must be skipped)
{ session_id: 'start-only', start: '2026-04-10T09:00:00Z', hour: 9, is_late_night: false },
// error record (must be skipped)
{ session_id: 'err', end: '2026-04-10T12:00:00Z', note: 'no_state_file' },
];
const jsonl = fixture.map(o => JSON.stringify(o)).join('\n') + '\n';
const result = runReader(jsonl);
assert.equal(result.pushback_total, 4);
assert.equal(Number.isNaN(result.pushback_total), false);
assert.equal(result.total_end_records, 2);
assert.equal(result.schema_version.v1_0_records, 1);
assert.equal(result.schema_version.v1_1_records, 1);
assert.equal(result.flags_total.dependency, 1);
assert.equal(result.flags_total.fatigue, 1);
});
test('report-reader stdout surfaces v1.2 field names (SC-12)', () => {
// Run reader against a v1.2 fixture and assert stdout contains the field
// names that /interaction-report references in its output template.
const fixture = [
{ session_id: 'a', duration_min: 30,
domain_context: ['legal', 'health'],
user_info_class: 'no', valseek_count: 4, turn_count: 22,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 1 } },
];
const stdout = runReaderRaw(fixture.map(o => JSON.stringify(o)).join('\n') + '\n');
// SC-12 specifies these field names must be present in the report output:
assert.ok(stdout.includes('user_info_class'), 'stdout missing user_info_class field');
assert.ok(stdout.includes('valseek'), 'stdout missing valseek aggregation');
assert.ok(stdout.includes('stakes_signal'), 'stdout missing stakes_signal aggregation');
// Also assert at least one new domain name (legal) appears in domain_breakdown.
assert.ok(stdout.includes('legal'), 'stdout missing legal domain in breakdown');
assert.ok(stdout.includes('domain_breakdown'), 'stdout missing domain_breakdown structure');
});

152
plugins/ai-psychosis/tests/lib.test.mjs
View file

@ -1,152 +0,0 @@
// Unit tests for shared library constants and helpers.
// Sanity-checks that v1.2 thresholds and domain-stakes table are exported
// with the expected shape. Detector-level behaviour is covered in
// per-detector test files (user-info, validation-seeking, stakes-matrix).
import { test, describe, before, after } from 'node:test';
import assert from 'node:assert/strict';
import { mkdtempSync, rmSync, writeFileSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
// Allocate a fresh data dir before importing lib.mjs, so SESSIONS_LOG points
// at a sandbox path. The lib.mjs module captures CLAUDE_PLUGIN_DATA at import
// time, so the env var must be set first.
const TEST_DATA_DIR = mkdtempSync(join(tmpdir(), 'ia-lib-test-'));
process.env.CLAUDE_PLUGIN_DATA = TEST_DATA_DIR;
const {
TIER1_TURN_THRESHOLD,
TIER2_SESSION_THRESHOLD,
THRESHOLD_VALSEEK_FLAGS,
DOMAIN_STAKES,
HIGH_SYCOPHANCY_DOMAINS,
HIGH_STAKES_DOMAINS,
INFO_DOMAINS,
SESSIONS_LOG,
readRecentEndRecords,
} = await import('../hooks/scripts/lib.mjs');
after(() => {
rmSync(TEST_DATA_DIR, { recursive: true, force: true });
});
describe('v1.2 thresholds', () => {
test('tier-1 turn threshold is 15', () => {
assert.equal(TIER1_TURN_THRESHOLD, 15);
});
test('tier-2 session threshold is 3', () => {
assert.equal(TIER2_SESSION_THRESHOLD, 3);
});
test('valseek high-stakes flag threshold is 3', () => {
assert.equal(THRESHOLD_VALSEEK_FLAGS, 3);
});
});
describe('DOMAIN_STAKES table', () => {
test('default weight is 1.0', () => {
assert.equal(DOMAIN_STAKES.default, 1.0);
});
test('high-stakes domains weighted 1.5', () => {
assert.equal(DOMAIN_STAKES.legal, 1.5);
assert.equal(DOMAIN_STAKES.parenting, 1.5);
assert.equal(DOMAIN_STAKES.health, 1.5);
assert.equal(DOMAIN_STAKES.financial, 1.5);
});
test('high-sycophancy domains weighted between 1.2 and 1.3', () => {
assert.equal(DOMAIN_STAKES.relationship, 1.3);
assert.equal(DOMAIN_STAKES.spirituality, 1.2);
});
test('table is frozen (immutable)', () => {
assert.equal(Object.isFrozen(DOMAIN_STAKES), true);
});
test('uses singular domain identifiers (relationship, not relationships)', () => {
assert.equal(DOMAIN_STAKES.relationship, 1.3);
assert.equal(DOMAIN_STAKES.relationships, undefined);
});
});
describe('domain classification arrays', () => {
test('HIGH_SYCOPHANCY_DOMAINS contains relationship and spirituality', () => {
assert.deepEqual([...HIGH_SYCOPHANCY_DOMAINS], ['relationship', 'spirituality']);
assert.equal(Object.isFrozen(HIGH_SYCOPHANCY_DOMAINS), true);
});
test('HIGH_STAKES_DOMAINS contains legal, parenting, health, financial', () => {
assert.deepEqual([...HIGH_STAKES_DOMAINS], ['legal', 'parenting', 'health', 'financial']);
assert.equal(Object.isFrozen(HIGH_STAKES_DOMAINS), true);
});
test('INFO_DOMAINS adds professional to HIGH_STAKES_DOMAINS', () => {
assert.deepEqual(
[...INFO_DOMAINS],
['legal', 'parenting', 'health', 'financial', 'professional']
);
assert.equal(Object.isFrozen(INFO_DOMAINS), true);
});
});
describe('readRecentEndRecords', () => {
function writeFixture(records) {
const lines = records.map(r => JSON.stringify(r)).join('\n') + '\n';
writeFileSync(SESSIONS_LOG, lines);
}
test('returns N most recent end records in chronological order', () => {
writeFixture([
{ session_id: 'a', start: '2026-05-01T10:00:00Z' }, // start record (no duration)
{ session_id: 'a', start: '2026-05-01T10:00:00Z', end: '2026-05-01T10:30:00Z', duration_min: 30 },
{ session_id: 'b', start: '2026-05-01T11:00:00Z' },
{ session_id: 'b', start: '2026-05-01T11:00:00Z', end: '2026-05-01T11:45:00Z', duration_min: 45 },
{ session_id: 'c', start: '2026-05-01T12:00:00Z', end: '2026-05-01T12:20:00Z', duration_min: 20 },
{ session_id: 'd', start: '2026-05-01T13:00:00Z', end: '2026-05-01T13:50:00Z', duration_min: 50 },
]);
const recent = readRecentEndRecords(3);
assert.equal(recent.length, 3);
assert.equal(recent[0].session_id, 'b');
assert.equal(recent[1].session_id, 'c');
assert.equal(recent[2].session_id, 'd');
});
test('returns fewer than N when not enough end records exist', () => {
writeFixture([
{ session_id: 'a', start: '2026-05-01T10:00:00Z', end: '2026-05-01T10:30:00Z', duration_min: 30 },
]);
const recent = readRecentEndRecords(5);
assert.equal(recent.length, 1);
assert.equal(recent[0].session_id, 'a');
});
test('skips malformed JSON lines', () => {
const goodA = JSON.stringify({ session_id: 'a', duration_min: 1 });
const goodB = JSON.stringify({ session_id: 'b', duration_min: 2 });
writeFileSync(SESSIONS_LOG, `${goodA}\nnot json\n${goodB}\n`);
const recent = readRecentEndRecords(5);
assert.equal(recent.length, 2);
assert.equal(recent[0].session_id, 'a');
assert.equal(recent[1].session_id, 'b');
});
test('empty file returns []', () => {
writeFileSync(SESSIONS_LOG, '');
assert.deepEqual(readRecentEndRecords(3), []);
});
test('missing file returns []', () => {
rmSync(SESSIONS_LOG, { force: true });
assert.deepEqual(readRecentEndRecords(3), []);
});
test('non-positive N returns []', () => {
writeFixture([{ session_id: 'a', duration_min: 1 }]);
assert.deepEqual(readRecentEndRecords(0), []);
assert.deepEqual(readRecentEndRecords(-1), []);
});
});

438
plugins/ai-psychosis/tests/perf.test.mjs
View file

@ -1,438 +0,0 @@
// Hook timing budget enforcement.
//
// Two thresholds are measured per hook:
//
// - WALL_CLOCK_P95_MS = 200 — total round-trip including Node ESM cold-start.
// The cold-start alone is 60-120ms on Intel Mac, so 100ms is unrealistic
// for any subprocess-based hook. 200ms gives headroom for shared CI noise.
//
// - LOGIC_TIME_P95_MS = 50 — pure work (regex evaluation + JSONL/state I/O)
// measured by a fixture-runner that imports lib.mjs once and exercises
// the hook's hot path inline. This is the meaningful hook-perf assertion;
// ESM cold-start is not something the plugin can optimize.
//
// p95 = the 4th value of 5 sorted iterations. Failing once triggers a single
// retry to absorb transient OS noise; a second failure is treated as a real
// signal (real perf regression or threshold needs tuning).
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { execSync } from 'child_process';
import {
mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync,
unlinkSync, rmSync, appendFileSync,
} from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
import { nowIso, nowEpoch } from '../hooks/scripts/lib.mjs';
const SCRIPTS_DIR = join(import.meta.dirname, '..', 'hooks', 'scripts');
const WALL_CLOCK_P95_MS = 200;
const LOGIC_TIME_P95_MS = 50;
const ITERATIONS = 5;
function setupDir() {
const dir = mkdtempSync(join(tmpdir(), 'ia-perf-'));
mkdirSync(join(dir, 'state'), { recursive: true });
return dir;
}
function p95(samples) {
return [...samples].sort((a, b) => a - b)[3];
}
// --- Wall-clock measurement (subprocess spawn) ---
function runWallClock(scriptName, stdinJson, dataDir) {
const t0 = performance.now();
execSync(`node ${join(SCRIPTS_DIR, scriptName)}`, {
input: JSON.stringify(stdinJson),
env: { ...process.env, CLAUDE_PLUGIN_DATA: dataDir },
encoding: 'utf8',
timeout: 5000,
});
return performance.now() - t0;
}
function measureWallClock(scriptName, stdinTemplate) {
const samples = [];
for (let i = 0; i < ITERATIONS; i++) {
const dir = setupDir();
try {
const sid = `perf-${i}`;
// Pre-seed state for hooks that read it (tool-tracker, session-end)
writeFileSync(
join(dir, 'state', `${sid}.json`),
JSON.stringify({ start_epoch: nowEpoch(), start_iso: nowIso(), tool_count: 0, edit_count: 0 })
);
samples.push(runWallClock(scriptName, { ...stdinTemplate, session_id: sid }, dir));
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
return samples;
}
// --- Logic-time fixtures (no subprocess, single import of lib.mjs) ---
//
// These mirror each hook's hot path in pure inline code so we can measure
// regex + I/O cost without paying the ~80ms ESM cold-start tax. The pattern
// list intentionally mirrors the size class of prompt-analyzer's full
// pattern set so the benchmark stays representative.
//
// v1.2 pattern count: ~133 = 41 v1.1 (25 negative + 12 pushback + 4 domain)
// + 48 new domains (8 × 6)
// + 32 user-info (15 people + 10 digital + 7 no)
// + 12 valseek
// Fixture sized at ~91+ to bracket the realistic prompt-analyzer cost without
// overweighting the perf budget on test fixture maintenance.
//
// Patterns here are structurally equivalent to the real ones (length +
// complexity), not literal copies — the privacy boundary at
// prompt-analyzer.mjs:119 means production patterns must stay co-located
// with the privacy wipe. Keep in sync (approximately) with v1.2 pattern count.
const samplePatterns = [
// Negative emotional patterns (25 — matches v1.1.0)
/\bI\s+can'?t\s+do\s+this\s+without\b/i,
/\bwhat\s+should\s+I\b/i,
/\bI\s+need\s+you\s+to\b/i,
/\bonly\s+you\s+understand\b/i,
/\b(?:always|never|every|all)\s+the\s+time\b/i,
/\bdefinitely\s+(?:should|will|need)\b/i,
/\babsolutely\s+(?:right|correct)\b/i,
/\bI\s+am\s+(?:tired|exhausted|drained)\b/i,
/\blate\s+night\b/i,
/\b(?:can'?t|cannot)\s+sleep\b/i,
/\bI\s+(?:wish|want)\s+(?:I|you)\s+could\b/i,
/\bdo\s+you\s+think\b/i,
/\bare\s+you\s+sure\b/i,
/\bright\?$/i,
/\bagree\?$/i,
/\bam\s+I\s+(?:right|wrong)\b/i,
/\bplease\s+confirm\b/i,
/\bI\s+keep\s+(?:thinking|coming\s+back)\b/i,
/\bI\s+(?:can'?t|cannot)\s+stop\b/i,
/\bone\s+more\s+(?:thing|question)\b/i,
/\bjust\s+one\s+more\b/i,
/\bI'?ve\s+been\s+thinking\b/i,
/\bwhy\s+did\s+I\b/i,
/\bI\s+messed\s+up\b/i,
/\bI\s+made\s+a\s+mistake\b/i,
// Pushback patterns (12 — matches v1.1.0)
/\bbut\s+(?:that|this)\s+is\s+wrong\b/i,
/\bno,?\s+I\s+(?:meant|asked|said)\b/i,
/\byou(?:'?re|\s+are)\s+(?:wrong|mistaken|incorrect)\b/i,
/\bthat'?s\s+not\s+(?:right|what)\b/i,
/\bactually,?\s+(?:I|the)\b/i,
/\bdisagree\s+(?:with|because)\b/i,
/\bI\s+(?:still|already)\s+(?:think|believe)\b/i,
/\blisten,?\s+(?:I|you)\b/i,
/\bdon'?t\s+(?:tell|give)\s+me\b/i,
/\bjust\s+(?:do|say|tell)\s+(?:it|me)\b/i,
/\bI\s+(?:already|just)\s+decided\b/i,
/\byou\s+(?:keep|always)\s+(?:saying|missing)\b/i,
// Domain patterns (4 — matches v1.1.0)
/\bmy\s+(?:partner|spouse|husband|wife|boyfriend|girlfriend)\b/i,
/\b(?:our|the)\s+relationship\b/i,
/\bbreak\s+up\s+(?:with|over)\b/i,
/\bdating\s+(?:someone|him|her|them)\b/i,
// v1.2: 48 new domain patterns (8 × 6) — structurally equivalent to real ones
/\b(?:my|our)\s+(?:lawyer|attorney)\b/i,
/\bfiling\s+a?\s+lawsuit\b/i,
/\b(?:custody|divorce)\s+(?:hearing|case)\b/i,
/\b(?:contract|nda)\s+(?:violation|dispute)\b/i,
/\bsued?\s+(?:by|for)\b/i,
/\b(?:landlord|tenant)\s+(?:rights|dispute)\b/i,
/\bmy\s+(?:kid|child|son|daughter)\b/i,
/\b(?:potty|sleep)\s+training\s+issue\b/i,
/\bas\s+a\s+(?:parent|mom|dad)\b/i,
/\b(?:bedtime|breastfeeding)\s+routine\b/i,
/\b(?:school|preschool)\s+(?:choice|conflict)\b/i,
/\bmy\s+(?:child|kid)'?s?\s+(?:diagnosis|teacher)\b/i,
/\bmy\s+(?:doctor|physician|gp)\b/i,
/\b(?:diagnosed|prescribed)\s+(?:with|for)\b/i,
/\bmy\s+symptoms?\s+(?:are|include)\b/i,
/\b(?:my|i\s+have)\s+(?:cancer|diabetes)\b/i,
/\b(?:blood\s+pressure|heart\s+rate)\s+reading\b/i,
/\b(?:scheduled|having)\s+(?:surgery|procedure)\b/i,
/\bmy\s+(?:savings|retirement|401k)\s+account\b/i,
/\b(?:mortgage|loan|debt)\s+(?:payment|advice)\b/i,
/\bmy\s+tax\s+(?:return|bracket)\b/i,
/\b(?:budget|paycheck)\s+(?:negotiation|advice)\b/i,
/\b(?:stock|portfolio)\s+(?:pick|allocation)\b/i,
/\b(?:credit\s+card|interest\s+rate)\s+advice\b/i,
/\bmy\s+(?:boss|manager|coworker)\b/i,
/\b(?:performance\s+review|promotion|fired)\b/i,
/\bmy\s+(?:job|career|workplace)\s+(?:change|conflict)\b/i,
/\b(?:resume|cv)\s+advice\b/i,
/\bproject\s+deadline\s+(?:fight|conflict)\b/i,
/\b(?:remote|hybrid)\s+(?:policy|mandate)\b/i,
/\bmy\s+(?:guru|spiritual\s+teacher)\b/i,
/\b(?:meditation|mindfulness)\s+(?:practice|journey)\b/i,
/\b(?:karma|dharma|chakra)\b/i,
/\b(?:god|the\s+universe)\s+(?:wants|told)\b/i,
/\b(?:soulmate|twin\s+flame|past\s+life)\b/i,
/\b(?:prayer|spiritual\s+journey)\b/i,
/\bshould\s+i\s+buy\s+(?:a|the)\b/i,
/\bwhich\s+(?:laptop|phone|car)\s+should\b/i,
/\b(?:product|item)\s+(?:review|comparison)\b/i,
/\b(?:amazon|online)\s+(?:order|purchase)\b/i,
/\b(?:better|best)\s+(?:deal|price)\s+(?:for|on)\b/i,
/\b(?:upgrade|replace)\s+my\s+(?:laptop|phone)\b/i,
/\b(?:learn|practice)\s+(?:a|the)\s+habit\s+of\b/i,
/\bmy\s+(?:morning|daily)\s+routine\b/i,
/\bread(?:ing)?\s+more\s+books\b/i,
/\b(?:start|build)\s+a\s+(?:journal|hobby)\b/i,
/\b(?:learning|teaching\s+myself)\b/i,
/\b(?:improve|level\s+up)\s+(?:myself|my\s+focus)\b/i,
// v1.2: 32 user-info patterns (15 people + 10 digital + 7 no)
/\bmy\s+(?:therapist|counselor|psychologist)\b/i,
/\bmy\s+(?:doctor|gp|physician)\b/i,
/\bmy\s+(?:friend|best\s+friend)\b/i,
/\bmy\s+(?:partner|spouse|wife|husband)\b/i,
/\bmy\s+(?:mom|dad|mother|father)\b/i,
/\bmy\s+(?:mentor|coach|advisor)\b/i,
/\bmy\s+support\s+group\b/i,
/\bi\s+asked\s+my\s+(?:friend|therapist)\b/i,
/\bi\s+told\s+my\s+(?:friend|therapist|partner)\b/i,
/\bmy\s+family\s+(?:said|told)\b/i,
/\bmy\s+(?:lawyer|attorney)\b/i,
/\bmy\s+(?:pastor|priest|rabbi)\b/i,
/\bmy\s+(?:teacher|professor|tutor)\b/i,
/\bmy\s+(?:colleague|coworker)\b/i,
/\bi\s+reached\s+out\s+to\s+my\s+(?:friend|therapist)\b/i,
/\bi\s+(?:googled|searched)\b/i,
/\bi\s+read\s+(?:online|on\s+the\s+internet)\b/i,
/\b(?:chatgpt|gpt|gemini)\s+(?:said|told)\b/i,
/\b(?:found|saw)\s+a\s+(?:forum\s+post|reddit\s+thread)\b/i,
/\b(?:youtube|tiktok|twitter)\s+(?:video|post)\b/i,
/\baccording\s+to\s+(?:wikipedia|google)\b/i,
/\bi\s+asked\s+(?:chatgpt|gpt|claude)\b/i,
/\bonline\s+says\s+(?:that|this)\b/i,
/\bsearched\s+(?:google|stackoverflow)\b/i,
/\bi\s+watched\s+a\s+youtube\b/i,
/\b(?:nobody|no\s+one)\s+knows\b/i,
/\bi\s+haven'?t\s+told\s+(?:anyone|anybody)\b/i,
/\bdealing\s+with\s+this\s+alone\b/i,
/\bi\s+can'?t\s+tell\s+(?:anyone|anybody)\b/i,
/\bkeep\s+(?:this|it)\s+(?:to\s+myself|secret)\b/i,
/\bnobody\s+(?:in\s+my\s+life|around\s+me)\s+would\s+understand\b/i,
/\bjust\s+me\s+(?:and|with)\s+(?:my|the)\s+(?:thoughts|head)\b/i,
// v1.2: 12 valseek patterns
/\bisn'?t\s+(?:it|that|she|he)\b[^.!?]*\?/i,
/\bdon'?t\s+you\s+(?:think|agree|see)\b[^.!?]*\?/i,
/\bright,?\s+(?:though|so)\b[^.!?]*\?/i,
/\bam\s+i\s+(?:crazy|wrong|the\s+only\s+one)\b/i,
/\btell\s+me\s+i'?m\s+not\s+(?:crazy|wrong)\b/i,
/\bis\s+it\s+(?:normal|crazy|reasonable)\s+(?:to|that)\b/i,
/\byou\s+agree,?\s+right\??/i,
/\btell\s+me\s+i'?m\s+right\b/i,
/\bback\s+me\s+up\s+(?:on\s+this|here)\b/i,
/\bi\s+(?:already|just)\s+(?:decided|knew)\b.*(?:should|right)\b/i,
/\bi'?ve\s+made\s+up\s+my\s+mind\b.*(?:right|correct)\b/i,
/\bi\s+know\s+i'?m\s+right\s+(?:about|on)\b/i,
];
function logicSessionStart(dir, sid) {
const stateFile = join(dir, 'state', `${sid}.json`);
const sessionsLog = join(dir, 'sessions.jsonl');
const iso = nowIso();
const epoch = nowEpoch();
const state = { start_epoch: epoch, start_iso: iso, tool_count: 0, edit_count: 0 };
writeFileSync(stateFile, JSON.stringify(state));
appendFileSync(
sessionsLog,
JSON.stringify({ session_id: sid, start: iso, hour: new Date().getUTCHours(), is_late_night: false }) + '\n'
);
}
function logicPromptAnalyzer(dir, sid, prompt) {
const stateFile = join(dir, 'state', `${sid}.json`);
const state = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, 'utf8')) : {};
let depHit = 0, valHit = 0;
for (const p of samplePatterns) { if (p.test(prompt)) { valHit = 1; break; } }
state.dep_flags = (state.dep_flags || 0) + depHit;
state.val_flags = (state.val_flags || 0) + valHit;
writeFileSync(stateFile, JSON.stringify(state));
}
function logicToolTracker(dir, sid, toolName) {
const stateFile = join(dir, 'state', `${sid}.json`);
const eventsLog = join(dir, 'events.jsonl');
const state = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, 'utf8')) : {};
state.tool_count = (state.tool_count || 0) + 1;
if (toolName === 'Edit' || toolName === 'Write') state.edit_count = (state.edit_count || 0) + 1;
appendFileSync(
eventsLog,
JSON.stringify({ ts: nowIso(), session_id: sid, tool_name: toolName }) + '\n'
);
writeFileSync(stateFile, JSON.stringify(state));
}
function logicSessionEnd(dir, sid) {
const stateFile = join(dir, 'state', `${sid}.json`);
const sessionsLog = join(dir, 'sessions.jsonl');
if (!existsSync(stateFile)) return;
const state = JSON.parse(readFileSync(stateFile, 'utf8'));
appendFileSync(
sessionsLog,
JSON.stringify({
session_id: sid,
start: state.start_iso,
end: nowIso(),
duration_min: 0,
tool_count: state.tool_count || 0,
edit_count: state.edit_count || 0,
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: state.val_flags || 0, pushback: 0 },
}) + '\n'
);
unlinkSync(stateFile);
}
function measureLogicTime(fn, ...extraArgs) {
const samples = [];
for (let i = 0; i < ITERATIONS; i++) {
const dir = setupDir();
const sid = `perf-${i}`;
try {
writeFileSync(
join(dir, 'state', `${sid}.json`),
JSON.stringify({ start_epoch: nowEpoch(), start_iso: nowIso(), tool_count: 0, edit_count: 0 })
);
const t0 = performance.now();
fn(dir, sid, ...extraArgs);
samples.push(performance.now() - t0);
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
return samples;
}
function assertWithRetry(measure, threshold, label) {
let samples = measure();
let p = p95(samples);
if (p > threshold) {
samples = measure();
p = p95(samples);
}
assert.ok(
p <= threshold,
`${label} p95 = ${p.toFixed(1)}ms exceeds ${threshold}ms (samples: ${samples.map(s => s.toFixed(1)).join(', ')})`
);
}
// --- Wall-clock tests (4) ---
test('session-start.mjs wall-clock p95 within 200ms', () => {
assertWithRetry(
() => measureWallClock('session-start.mjs', { cwd: '/tmp' }),
WALL_CLOCK_P95_MS,
'session-start wall-clock'
);
});
test('prompt-analyzer.mjs wall-clock p95 within 200ms', () => {
assertWithRetry(
() => measureWallClock('prompt-analyzer.mjs', { prompt: 'are you sure I should do this? right?', cwd: '/tmp' }),
WALL_CLOCK_P95_MS,
'prompt-analyzer wall-clock'
);
});
test('tool-tracker.mjs wall-clock p95 within 200ms', () => {
assertWithRetry(
() => measureWallClock('tool-tracker.mjs', { tool_name: 'Edit', cwd: '/tmp' }),
WALL_CLOCK_P95_MS,
'tool-tracker wall-clock'
);
});
test('session-end.mjs wall-clock p95 within 200ms', () => {
assertWithRetry(
() => measureWallClock('session-end.mjs', { cwd: '/tmp' }),
WALL_CLOCK_P95_MS,
'session-end wall-clock'
);
});
// --- Logic-time tests (4) ---
test('session-start logic-time p95 within 50ms', () => {
assertWithRetry(
() => measureLogicTime(logicSessionStart),
LOGIC_TIME_P95_MS,
'session-start logic-time'
);
});
test('prompt-analyzer logic-time p95 within 50ms', () => {
assertWithRetry(
() => measureLogicTime(logicPromptAnalyzer, 'are you sure I should do this? right?'),
LOGIC_TIME_P95_MS,
'prompt-analyzer logic-time'
);
});
test('tool-tracker logic-time p95 within 50ms', () => {
assertWithRetry(
() => measureLogicTime(logicToolTracker, 'Edit'),
LOGIC_TIME_P95_MS,
'tool-tracker logic-time'
);
});
test('session-end logic-time p95 within 50ms', () => {
assertWithRetry(
() => measureLogicTime(logicSessionEnd),
LOGIC_TIME_P95_MS,
'session-end logic-time'
);
});
// --- v1.2: cross-session read at scale ---
//
// Pre-seeds sessions.jsonl with 1000 records to exercise the realistic
// readRecentEndRecords path. Tail-first scan should bound cost regardless.
function measureSessionStartWithJsonlFixture(recordCount) {
const samples = [];
for (let i = 0; i < ITERATIONS; i++) {
const dir = setupDir();
try {
// Pre-seed sessions.jsonl with mixed start/end records.
const lines = [];
for (let r = 0; r < recordCount; r++) {
const startISO = new Date(Date.now() - (recordCount - r) * 60_000).toISOString();
const endISO = new Date(Date.now() - (recordCount - r) * 60_000 + 30_000).toISOString();
lines.push(JSON.stringify({
session_id: `seed-${r}`, start: startISO,
end: endISO, duration_min: 30,
domain_context: ['legal'], user_info_class: 'no',
flags: { dependency: 0, escalation: 0, fatigue: 0, validation: 0, pushback: 0 },
}));
}
writeFileSync(join(dir, 'sessions.jsonl'), lines.join('\n') + '\n');
const sid = `bigfix-${i}`;
writeFileSync(
join(dir, 'state', `${sid}.json`),
JSON.stringify({ start_epoch: nowEpoch(), start_iso: nowIso(), tool_count: 0, edit_count: 0 })
);
samples.push(runWallClock('session-start.mjs', { session_id: sid, cwd: '/tmp' }, dir));
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
return samples;
}
test('session-start with 1000-record sessions.jsonl wall-clock p95 within 200ms', () => {
// The tier-2 alert in session-start.mjs reads the tail of sessions.jsonl
// via readRecentEndRecords(3). Tail-first scan should keep wall-clock
// bounded regardless of total file size.
assertWithRetry(
() => measureSessionStartWithJsonlFixture(1000),
WALL_CLOCK_P95_MS,
'session-start wall-clock with 1000-record fixture'
);
});

149
plugins/ai-psychosis/tests/privacy.test.mjs
View file

@ -1,149 +0,0 @@
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { readdirSync, readFileSync } from 'fs';
import { join } from 'path';
import { runHook, setupTestDir, cleanupTestDir } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
function readAllFiles(dirPath) {
let content = '';
for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
const full = join(dirPath, entry.name);
if (entry.isDirectory()) {
content += readAllFiles(full);
} else {
content += readFileSync(full, 'utf8');
}
}
return content;
}
describe('privacy', () => {
it('never writes prompt text to disk through full lifecycle', () => {
dir = setupTestDir();
const canary = 'CANARY_PRIVACY_xyz123';
// 1. Session start
runHook('session-start.mjs', { session_id: 'priv1', cwd: '/tmp' }, dir);
// 2. Prompt analysis with canary as prompt text
runHook('prompt-analyzer.mjs', { session_id: 'priv1', prompt: `tell me what to do ${canary} am I right?` }, dir);
// 3. Tool tracking
runHook('tool-tracker.mjs', { session_id: 'priv1', tool_name: 'Edit' }, dir);
// 4. Session end
runHook('session-end.mjs', { session_id: 'priv1', cwd: '/tmp' }, dir);
// Read ALL files recursively — canary must not appear anywhere
const allContent = readAllFiles(dir);
assert.ok(!allContent.includes(canary), `Canary "${canary}" found in data files — privacy violation`);
});
it('never leaks matched-pattern phrases through full lifecycle', () => {
dir = setupTestDir();
const matchedPhrase = 'are you sure';
const canary = 'CANARY_PRIVACY_xyz123';
const prompt = `${matchedPhrase}? ${canary}`;
runHook('session-start.mjs', { session_id: 'priv2', cwd: '/tmp' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'priv2', prompt }, dir);
runHook('tool-tracker.mjs', { session_id: 'priv2', tool_name: 'Edit' }, dir);
runHook('session-end.mjs', { session_id: 'priv2', cwd: '/tmp' }, dir);
const allContent = readAllFiles(dir);
assert.ok(
!allContent.includes(canary),
`Canary "${canary}" leaked — pattern-match did not protect prompt text`
);
assert.ok(
!allContent.toLowerCase().includes(matchedPhrase),
`Matched phrase "${matchedPhrase}" leaked — pattern name or trigger phrase written to disk`
);
});
// v1.2 detector canaries — one per new detector category, plus matched-phrase
// variants for new pattern phrases that must never reach disk verbatim.
it('user-info detector: yes_people canary never leaks', () => {
dir = setupTestDir();
const matchedPhrase = 'my therapist';
const canary = 'CANARY_USERINFO_PEOPLE_xyz123';
const prompt = `${matchedPhrase} suggested I journal more — ${canary}`;
runHook('session-start.mjs', { session_id: 'pv12a', cwd: '/tmp' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'pv12a', prompt }, dir);
runHook('tool-tracker.mjs', { session_id: 'pv12a', tool_name: 'Edit' }, dir);
runHook('session-end.mjs', { session_id: 'pv12a', cwd: '/tmp' }, dir);
const allContent = readAllFiles(dir);
assert.ok(!allContent.includes(canary),
`Canary "${canary}" leaked through user-info detector`);
assert.ok(!allContent.toLowerCase().includes(matchedPhrase),
`Matched phrase "${matchedPhrase}" leaked through user-info detector`);
});
it('user-info detector: yes_digital canary never leaks', () => {
dir = setupTestDir();
const matchedPhrase = 'I googled';
const canary = 'CANARY_USERINFO_DIGITAL_xyz123';
const prompt = `${matchedPhrase} this issue and got nothing — ${canary}`;
runHook('session-start.mjs', { session_id: 'pv12b', cwd: '/tmp' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'pv12b', prompt }, dir);
runHook('session-end.mjs', { session_id: 'pv12b', cwd: '/tmp' }, dir);
const allContent = readAllFiles(dir);
assert.ok(!allContent.includes(canary));
assert.ok(!allContent.toLowerCase().includes(matchedPhrase.toLowerCase()));
});
it('user-info detector: "no" isolation canary never leaks', () => {
dir = setupTestDir();
const matchedPhrase = "haven't told anyone";
const canary = 'CANARY_USERINFO_NO_xyz123';
const prompt = `I ${matchedPhrase} about it ${canary}`;
runHook('session-start.mjs', { session_id: 'pv12c', cwd: '/tmp' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'pv12c', prompt }, dir);
runHook('session-end.mjs', { session_id: 'pv12c', cwd: '/tmp' }, dir);
const allContent = readAllFiles(dir);
assert.ok(!allContent.includes(canary));
assert.ok(!allContent.toLowerCase().includes(matchedPhrase));
});
it('valseek detector canary never leaks', () => {
dir = setupTestDir();
const matchedPhrase = 'am I crazy';
const canary = 'CANARY_VALSEEK_xyz123';
const prompt = `${matchedPhrase} for thinking this — ${canary}`;
runHook('session-start.mjs', { session_id: 'pv12d', cwd: '/tmp' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'pv12d', prompt }, dir);
runHook('session-end.mjs', { session_id: 'pv12d', cwd: '/tmp' }, dir);
const allContent = readAllFiles(dir);
assert.ok(!allContent.includes(canary));
assert.ok(!allContent.toLowerCase().includes(matchedPhrase));
});
it('domain detector (legal): canary never leaks despite domain hit', () => {
dir = setupTestDir();
const matchedPhrase = 'my lawyer';
const canary = 'CANARY_DOMAIN_LEGAL_xyz123';
const prompt = `talked to ${matchedPhrase} about it ${canary}`;
runHook('session-start.mjs', { session_id: 'pv12e', cwd: '/tmp' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'pv12e', prompt }, dir);
runHook('session-end.mjs', { session_id: 'pv12e', cwd: '/tmp' }, dir);
const allContent = readAllFiles(dir);
assert.ok(!allContent.includes(canary),
`Canary "${canary}" leaked through legal domain detector`);
assert.ok(!allContent.toLowerCase().includes(matchedPhrase),
`Matched phrase "${matchedPhrase}" leaked through legal domain detector`);
});
});

522
plugins/ai-psychosis/tests/prompt-analyzer.test.mjs
View file

@ -1,522 +0,0 @@
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readState } from './test-helper.mjs';
let dir;
function freshState() {
return {
start_epoch: Math.floor(Date.now() / 1000) - 60,
start_iso: '2026-01-01T10:00:00Z',
tool_count: 0, edit_count: 0,
last_event_epoch: 0, burst_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 0, domain_context: null,
last_warning_epoch: 0,
};
}
function runPrompt(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), ...stateOverrides });
runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt }, dir);
return readState(dir, 'p1');
}
afterEach(() => { if (dir) cleanupTestDir(dir); });
// --- Dependency patterns (7 positive, 7 negative) ---
describe('dependency patterns', () => {
it('matches "tell me what to do"', () => {
const s = runPrompt('please tell me what to do');
assert.equal(s.dep_flags, 1);
});
it('does not match "I told him the plan"', () => {
const s = runPrompt('I told him the plan');
assert.equal(s.dep_flags, 0);
});
it('matches "what should I do"', () => {
const s = runPrompt('what should I do next?');
assert.equal(s.dep_flags, 1);
});
it('does not match "I know what to build"', () => {
const s = runPrompt('I know what to build');
assert.equal(s.dep_flags, 0);
});
it('matches "am I right"', () => {
const s = runPrompt('am I right about this?');
assert.equal(s.dep_flags, 1);
});
it('does not match "I turned the server right"', () => {
const s = runPrompt('I turned the server on');
assert.equal(s.dep_flags, 0);
});
it('matches "you understand me"', () => {
const s = runPrompt('you understand me well');
assert.equal(s.dep_flags, 1);
});
it('does not match "do you understand merging?"', () => {
const s = runPrompt('do you understand merging?');
assert.equal(s.dep_flags, 0);
});
it('matches "you\'re the only"', () => {
const s = runPrompt("you're the only one who gets it");
assert.equal(s.dep_flags, 1);
});
it('does not match "the only option is refactoring"', () => {
const s = runPrompt('the only option is refactoring');
assert.equal(s.dep_flags, 0);
});
it('matches "can I do this"', () => {
const s = runPrompt('can I do this alone?');
assert.equal(s.dep_flags, 1);
});
it('does not match "we can implement this later"', () => {
const s = runPrompt('we can implement this later');
assert.equal(s.dep_flags, 0);
});
it('matches "I need you to decide"', () => {
const s = runPrompt('I need you to decide for me');
assert.equal(s.dep_flags, 1);
});
it('does not match "we need to deploy soon"', () => {
const s = runPrompt('we need to deploy soon');
assert.equal(s.dep_flags, 0);
});
});
// --- Escalation patterns (6 positive, 6 negative) ---
describe('escalation patterns', () => {
it('matches "definitely" as word', () => {
const s = runPrompt('this is definitely wrong');
assert.equal(s.esc_flags, 1);
});
it('does not match "definitively"', () => {
const s = runPrompt('this is definitively proven');
assert.equal(s.esc_flags, 0);
});
it('matches "clearly" as word', () => {
const s = runPrompt('clearly this is the issue');
assert.equal(s.esc_flags, 1);
});
it('does not match "nuclear unclear"', () => {
const s = runPrompt('nuclear unclear situation');
assert.equal(s.esc_flags, 0);
});
it('matches "this proves"', () => {
const s = runPrompt('this proves my point');
assert.equal(s.esc_flags, 1);
});
it('does not match "prove this theorem"', () => {
const s = runPrompt('prove this theorem');
assert.equal(s.esc_flags, 0);
});
it('matches "obviously" as word', () => {
const s = runPrompt('obviously we should refactor');
assert.equal(s.esc_flags, 1);
});
it('does not match "not an obvious choice"', () => {
const s = runPrompt('not an obvious choice');
assert.equal(s.esc_flags, 0);
});
it('matches "without a doubt"', () => {
const s = runPrompt('without a doubt this works');
assert.equal(s.esc_flags, 1);
});
it('does not match "I have some doubt"', () => {
const s = runPrompt('I have some doubt about it');
assert.equal(s.esc_flags, 0);
});
it('matches "this confirms"', () => {
const s = runPrompt('this confirms the theory');
assert.equal(s.esc_flags, 1);
});
it('does not match "please confirm the deploy"', () => {
const s = runPrompt('please confirm the deploy');
assert.equal(s.esc_flags, 0);
});
});
// --- Fatigue patterns (7 positive, 7 negative) ---
describe('fatigue patterns', () => {
it('matches "tired"', () => {
const s = runPrompt("I'm tired of debugging");
assert.equal(s.fatigue_flags, 1);
});
it('does not match "retired"', () => {
const s = runPrompt('I retired last year');
assert.equal(s.fatigue_flags, 0);
});
it('matches "exhausted"', () => {
const s = runPrompt("I'm exhausted.");
assert.equal(s.fatigue_flags, 1);
});
it('does not match "exhaustive"', () => {
const s = runPrompt('the options were exhaustive');
assert.equal(s.fatigue_flags, 0);
});
it('matches "can\'t think"', () => {
const s = runPrompt("I can't think straight");
assert.equal(s.fatigue_flags, 1);
});
it('does not match "I can think clearly"', () => {
const s = runPrompt('I can think of a solution');
assert.equal(s.fatigue_flags, 0);
});
it('matches "been at this"', () => {
const s = runPrompt("I've been at this all day");
assert.equal(s.fatigue_flags, 1);
});
it('does not match "haven\'t been at home"', () => {
const s = runPrompt("I haven't been at home");
assert.equal(s.fatigue_flags, 0);
});
it('matches "it\'s late"', () => {
const s = runPrompt("it's late, wrapping up");
assert.equal(s.fatigue_flags, 1);
});
it('does not match "the latest version"', () => {
const s = runPrompt('the latest version is good');
assert.equal(s.fatigue_flags, 0);
});
it('matches "should sleep"', () => {
const s = runPrompt('I should sleep');
assert.equal(s.fatigue_flags, 1);
});
it('does not match "sleep mode is enabled"', () => {
const s = runPrompt('enable sleep mode');
assert.equal(s.fatigue_flags, 0);
});
it('matches "hours now"', () => {
const s = runPrompt('been going for hours now');
assert.equal(s.fatigue_flags, 1);
});
it('does not match "hourly updates"', () => {
const s = runPrompt('hourly updates are fine');
assert.equal(s.fatigue_flags, 0);
});
});
// --- Validation patterns (5 positive, 5 negative) ---
describe('validation patterns', () => {
it('matches "right?"', () => {
const s = runPrompt('this works, right?');
assert.equal(s.val_flags, 1);
});
it('does not match "turn right"', () => {
const s = runPrompt('turn right at the fork');
assert.equal(s.val_flags, 0);
});
it('matches "don\'t you think"', () => {
const s = runPrompt("don't you think so?");
assert.equal(s.val_flags, 1);
});
it('does not match "I don\'t think so"', () => {
const s = runPrompt("I don't think so");
assert.equal(s.val_flags, 0);
});
it('matches "you agree"', () => {
const s = runPrompt('you agree with me');
assert.equal(s.val_flags, 1);
});
it('does not match "if parties agree"', () => {
const s = runPrompt('if parties agree on terms');
assert.equal(s.val_flags, 0);
});
it('matches "correct?"', () => {
const s = runPrompt('is this correct?');
assert.equal(s.val_flags, 1);
});
it('does not match "correct the typo"', () => {
const s = runPrompt("I'll correct the typo");
assert.equal(s.val_flags, 0);
});
it('matches "isn\'t it"', () => {
const s = runPrompt('good approach, isn\'t it');
assert.equal(s.val_flags, 1);
});
it('does not match "it isn\'t working"', () => {
const s = runPrompt("it isn't working yet");
assert.equal(s.val_flags, 0);
});
});
// --- Threshold and cooldown tests (6 cases) ---
describe('thresholds and cooldowns', () => {
it('warns at dependency soft threshold (2 flags)', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), dep_flags: 1 });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: 'tell me what to do' }, dir);
assert.ok(out.hookSpecificOutput?.additionalContext?.includes('Dependency language noticed'));
});
it('warns hard at dependency threshold (5 flags)', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), dep_flags: 4 });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: 'tell me what to do' }, dir);
assert.ok(out.hookSpecificOutput?.additionalContext?.includes('INTERACTION AWARENESS'));
});
it('fatigue bypasses cooldown', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), last_warning_epoch: Math.floor(Date.now() / 1000) });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: "I'm tired" }, dir);
assert.ok(out.hookSpecificOutput?.additionalContext?.includes('Fatigue language detected'));
});
it('cooldown suppresses non-fatigue warning', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), dep_flags: 4, last_warning_epoch: Math.floor(Date.now() / 1000) });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: 'tell me what to do' }, dir);
assert.equal(out.continue, true);
assert.ok(!out.hookSpecificOutput);
});
it('warns at escalation threshold (3 flags)', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), esc_flags: 2 });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: 'this is definitely the issue' }, dir);
assert.ok(out.hookSpecificOutput?.additionalContext?.includes('Escalation language detected'));
});
it('warns at validation threshold (3 flags)', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), val_flags: 2 });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: 'this is correct, right?' }, dir);
assert.ok(out.hookSpecificOutput?.additionalContext?.includes('Validation-seeking pattern'));
});
});
// --- v1.1.0 pushback + domain regex (regex-only unit tests) ---
// Local copies of patterns in hooks/scripts/prompt-analyzer.mjs.
// Step 3 adds integration tests via runPrompt; integration tests catch
// pattern divergence between source and tests.
const pbReactivePatterns = [
/^are you sure\??/i,
/\bi'?m not convinced\b/i,
/\bthat doesn'?t (?:seem|feel) right\b/i,
/\bthat'?s not (?:quite )?what i meant\b/i,
/\blet me add (?:some )?context\b/i,
/\bactually,? (?:my situation|i)\b/i,
/(?:^|[.!?]\s+)i (?:believe|think) (?:you'?re|that'?s) wrong\b/i,
/\bi don'?t agree(?: with you)?\b/i,
/\bare you absolutely sure\b/i,
];
const pbPreemptivePatterns = [
/\bsteelman\b/i,
/\bplay (?:the )?devil'?s advocate\b/i,
/\bargue against (?:this|my)\b/i,
];
const domainRelationshipPatterns = [
/\b(?:my|our) (?:partner|spouse|wife|husband|girlfriend|boyfriend)\b/i,
/\bin our relationship\b/i,
/\b(?:dating|breakup|divorce)\b/i,
/\bromantic(?:ally)? (?:involved|interested)\b/i,
];
function matchesAny(patterns, text) {
return patterns.some((p) => p.test(text));
}
describe('pushback reactive patterns', () => {
it('matches "are you sure?"', () => assert.ok(matchesAny(pbReactivePatterns, 'are you sure?')));
it('does not match "tell me what to do" (no pushback)', () => assert.equal(matchesAny(pbReactivePatterns, 'tell me what to do'), false));
it("matches \"i'm not convinced\"", () => assert.ok(matchesAny(pbReactivePatterns, "i'm not convinced this works")));
it('does not match "i am convinced" (no negation)', () => assert.equal(matchesAny(pbReactivePatterns, 'i am convinced this works'), false));
it('matches "that doesn\'t seem right"', () => assert.ok(matchesAny(pbReactivePatterns, "that doesn't seem right to me")));
it('does not match "that seems right" (positive sense)', () => assert.equal(matchesAny(pbReactivePatterns, 'that seems right to me'), false));
it('matches "that\'s not what I meant"', () => assert.ok(matchesAny(pbReactivePatterns, "that's not what I meant by that")));
it('does not match "I meant exactly that"', () => assert.equal(matchesAny(pbReactivePatterns, 'I meant exactly that'), false));
it('matches "let me add context"', () => assert.ok(matchesAny(pbReactivePatterns, 'let me add context — the issue is X')));
it('does not match "I added context to the function"', () => assert.equal(matchesAny(pbReactivePatterns, 'I added context to the function'), false));
it('matches "actually, my situation is different"', () => assert.ok(matchesAny(pbReactivePatterns, 'actually, my situation is different')));
it('does not match "actually that approach works"', () => assert.equal(matchesAny(pbReactivePatterns, 'actually that approach works'), false));
it("matches \"I think you're wrong\"", () => assert.ok(matchesAny(pbReactivePatterns, "I think you're wrong about this")));
it("does not match \"I think we're wrong\" (different pronoun)", () => assert.equal(matchesAny(pbReactivePatterns, "I think we're wrong here"), false));
it("matches \"I don't agree\"", () => assert.ok(matchesAny(pbReactivePatterns, "I don't agree with that conclusion")));
it('does not match "I agree with you"', () => assert.equal(matchesAny(pbReactivePatterns, 'I agree with you fully'), false));
it('matches "are you absolutely sure"', () => assert.ok(matchesAny(pbReactivePatterns, 'are you absolutely sure about that')));
it('does not match "we are sure of the answer" (no questioning frame)', () => assert.equal(matchesAny(pbReactivePatterns, 'we are sure of the answer'), false));
});
describe('pushback preemptive patterns', () => {
it('matches "steelman"', () => assert.ok(matchesAny(pbPreemptivePatterns, 'please steelman this argument')));
it('does not match "steel manufacturing" (no whole-word match)', () => assert.equal(matchesAny(pbPreemptivePatterns, 'the steel manufacturing report'), false));
it("matches \"play devil's advocate\"", () => assert.ok(matchesAny(pbPreemptivePatterns, "can you play devil's advocate here")));
it('does not match "play music" (different verb object)', () => assert.equal(matchesAny(pbPreemptivePatterns, 'play music while coding'), false));
it('matches "argue against this"', () => assert.ok(matchesAny(pbPreemptivePatterns, 'argue against this proposal')));
it('does not match "they argue with each other"', () => assert.equal(matchesAny(pbPreemptivePatterns, 'they argue with each other'), false));
});
describe('domain relationship patterns', () => {
it('matches "my partner won\'t listen"', () => assert.ok(matchesAny(domainRelationshipPatterns, "my partner won't listen")));
it('matches "in our relationship"', () => assert.ok(matchesAny(domainRelationshipPatterns, 'in our relationship things changed')));
it('matches "considering divorce"', () => assert.ok(matchesAny(domainRelationshipPatterns, 'considering divorce after years')));
it('matches "romantically involved"', () => assert.ok(matchesAny(domainRelationshipPatterns, 'we are romantically involved')));
it('does not match "function relationship between input and output" (technical false-positive)', () => assert.equal(matchesAny(domainRelationshipPatterns, 'function relationship between input and output'), false));
it('does not match "database relationship mapping" (technical false-positive)', () => assert.equal(matchesAny(domainRelationshipPatterns, 'database relationship mapping'), false));
it('does not match "the data is updating" (no dating word boundary)', () => assert.equal(matchesAny(domainRelationshipPatterns, 'the data is updating in real time'), false));
it('does not match "romantic comedy film" (no involved/interested suffix)', () => assert.equal(matchesAny(domainRelationshipPatterns, 'watching a romantic comedy film'), false));
});
// --- v1.1.0 integration: pushback + valence + domain through prompt-analyzer.mjs ---
describe('pushback integration (state accumulation + same-invocation valence)', () => {
it('counts reactive pushback alone (no fatigue/escalation)', () => {
const s = runPrompt('are you sure?');
assert.equal(s.pushback_count, 1);
assert.equal(s.fatigue_flags, 0);
assert.equal(s.esc_flags, 0);
});
it('counts preemptive pushback alone', () => {
const s = runPrompt('please steelman this argument');
assert.equal(s.pushback_count, 1);
});
it('SUPPRESSES pushback when fatigue marker is in same invocation (valence guard)', () => {
const s = runPrompt("are you sure? I'm exhausted by all this");
assert.equal(s.pushback_count, 0, 'pushback must be suppressed when fatigue is co-present');
assert.equal(s.fatigue_flags, 1);
});
it('sets domain_context to ["relationship"] on positive match (v1.2 array shape)', () => {
const s = runPrompt("my partner won't listen to me");
assert.deepEqual(s.domain_context, ['relationship']);
});
it('keeps domain_context null on technical "function relationship" (false-positive guard)', () => {
const s = runPrompt('function relationship between input and output');
// No domainHit → state.domain_context stays as fresh-state null (untouched).
assert.equal(s.domain_context, null);
});
});
// --- v1.2 pushback alert contract (domain-aware re-contextualization) ---
//
// Step 12 of v1.2.0 ADDS the pushback alert with domain awareness baked in.
// Replaces the v1.1.0 "count but never alert" contract test.
//
// Behavior:
// - HIGH_SYCOPHANCY_DOMAINS (relationship, spirituality): alert at count >= 2
// - INFO_DOMAINS (legal, parenting, health, financial, professional): NO alert
// — pushback in info-seeking domains is healthy self-advocacy.
// - Empty / unknown domain: conservative default alert.
function runPromptCapture(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), ...stateOverrides });
const out = runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt }, dir);
const state = readState(dir, 'p1');
return { state, out };
}
describe('pushback alert (v1.2 domain-aware contract)', () => {
it('accumulates pushback_count over 5 sequential prompts', () => {
dir = setupTestDir();
createStateFile(dir, 'p1', { ...freshState(), domain_context: ['relationship'] });
const prompts = [
'are you sure?',
"I'm not convinced",
"that doesn't seem right",
"actually, I think you're wrong",
"are you absolutely sure?",
];
for (const p of prompts) {
runHook('prompt-analyzer.mjs', { session_id: 'p1', prompt: p }, dir);
}
const s = readState(dir, 'p1');
assert.equal(s.pushback_count, 5, 'count accumulates across calls');
});
it('3 pushbacks + relationship → alert (HIGH_SYCOPHANCY)', () => {
const { state, out } = runPromptCapture('are you absolutely sure?', {
domain_context: ['relationship'],
pushback_count: 2, // becomes 3
});
assert.equal(state.pushback_count, 3);
assert.match(out.hookSpecificOutput.additionalContext, /pushback re-contextualization/);
});
it('3 pushbacks + parenting → NO alert (INFO_DOMAIN, healthy self-advocacy)', () => {
const { out } = runPromptCapture("I'm not convinced", {
domain_context: ['parenting'],
pushback_count: 2,
});
// Suppress pushback alert; nothing else should fire here either.
assert.equal(out.hookSpecificOutput, undefined,
'parenting pushback is healthy self-advocacy — no alert');
});
it('3 pushbacks + [relationship, legal] → alert (mixed: any HIGH_SYCOPHANCY wins)', () => {
const { out } = runPromptCapture('are you absolutely sure?', {
domain_context: ['relationship', 'legal'],
pushback_count: 2,
});
assert.match(out.hookSpecificOutput.additionalContext, /pushback re-contextualization/);
});
it('3 pushbacks + empty domain → alert (conservative default)', () => {
const { out } = runPromptCapture('are you absolutely sure?', {
domain_context: [],
pushback_count: 2,
});
assert.match(out.hookSpecificOutput.additionalContext, /pushback/);
});
it('1 pushback + relationship → NO alert (sub-threshold)', () => {
const { out } = runPromptCapture("are you sure?", {
domain_context: ['relationship'],
pushback_count: 0,
});
assert.equal(out.hookSpecificOutput, undefined,
'sub-threshold (count<2) — no alert even in HIGH_SYCOPHANCY');
});
it('5 pushbacks across info-only domains [legal, health] → NO alert', () => {
const { out } = runPromptCapture("I'm not convinced", {
domain_context: ['legal', 'health'],
pushback_count: 4,
});
assert.equal(out.hookSpecificOutput, undefined,
'all-info domains never alert pushback regardless of count');
});
});

121
plugins/ai-psychosis/tests/session-end.test.mjs
View file

@ -1,121 +0,0 @@
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { join } from 'path';
import { existsSync } from 'fs';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readJsonl } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
describe('session-end', () => {
it('finalizes session record and deletes state file', () => {
dir = setupTestDir();
const nowEpoch = Math.floor(Date.now() / 1000);
createStateFile(dir, 's1', {
start_epoch: nowEpoch - 300, start_iso: '2026-01-01T10:00:00Z',
tool_count: 5, edit_count: 2,
dep_flags: 1, esc_flags: 0, fatigue_flags: 0, val_flags: 1,
last_event_epoch: 0, burst_count: 0, last_warning_epoch: 0,
});
runHook('session-end.mjs', { session_id: 's1', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
const end = records.find(r => r.end);
assert.ok(end);
assert.equal(end.session_id, 's1');
assert.equal(end.tool_count, 5);
assert.equal(end.edit_count, 2);
assert.ok(!existsSync(join(dir, 'state', 's1.json')));
});
it('computes duration correctly', () => {
dir = setupTestDir();
const nowEpoch = Math.floor(Date.now() / 1000);
createStateFile(dir, 's2', {
start_epoch: nowEpoch - 3600, start_iso: '2026-01-01T10:00:00Z',
tool_count: 10, edit_count: 3,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
last_event_epoch: 0, burst_count: 0, last_warning_epoch: 0,
});
runHook('session-end.mjs', { session_id: 's2', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
const end = records.find(r => r.end);
assert.ok(end.duration_min >= 59 && end.duration_min <= 61);
});
it('preserves flags in final record', () => {
dir = setupTestDir();
createStateFile(dir, 's3', {
start_epoch: Math.floor(Date.now() / 1000) - 60, start_iso: '2026-01-01T10:00:00Z',
tool_count: 1, edit_count: 0,
dep_flags: 3, esc_flags: 1, fatigue_flags: 2, val_flags: 0,
last_event_epoch: 0, burst_count: 0, last_warning_epoch: 0,
});
runHook('session-end.mjs', { session_id: 's3', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
const end = records.find(r => r.end);
assert.deepEqual(end.flags, { dependency: 3, escalation: 1, fatigue: 2, validation: 0, pushback: 0 });
});
it('handles missing state file gracefully', () => {
dir = setupTestDir();
runHook('session-end.mjs', { session_id: 'missing', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
assert.equal(records.length, 1);
assert.equal(records[0].note, 'no_state_file');
});
it('persists pushback_count and coerces v1.1.0 string domain to array', () => {
dir = setupTestDir();
createStateFile(dir, 's4', {
start_epoch: Math.floor(Date.now() / 1000) - 120, start_iso: '2026-01-01T10:00:00Z',
tool_count: 2, edit_count: 1,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 3, domain_context: 'relationship', // v1.1.0 string shape
last_event_epoch: 0, burst_count: 0, last_warning_epoch: 0,
});
runHook('session-end.mjs', { session_id: 's4', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
const end = records.find(r => r.end);
assert.ok(end);
assert.equal(end.flags.pushback, 3);
// v1.2: end record always carries an array, even when state had a string.
assert.deepEqual(end.domain_context, ['relationship']);
});
it('writes v1.2 multi-domain array unchanged when state already has array', () => {
dir = setupTestDir();
createStateFile(dir, 's4b', {
start_epoch: Math.floor(Date.now() / 1000) - 120, start_iso: '2026-01-01T10:00:00Z',
tool_count: 2, edit_count: 1,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 1,
domain_context: ['relationship', 'health'],
last_event_epoch: 0, burst_count: 0, last_warning_epoch: 0,
});
runHook('session-end.mjs', { session_id: 's4b', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
const end = records.find(r => r.end);
assert.ok(end);
assert.deepEqual(end.domain_context, ['relationship', 'health']);
});
it('backward-compat: state without pushback_count yields flags.pushback === 0 (not NaN/undefined)', () => {
dir = setupTestDir();
createStateFile(dir, 's5', {
start_epoch: Math.floor(Date.now() / 1000) - 60, start_iso: '2026-01-01T10:00:00Z',
tool_count: 1, edit_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
// pushback_count and domain_context intentionally absent (v1.0.0 state shape)
last_event_epoch: 0, burst_count: 0, last_warning_epoch: 0,
});
runHook('session-end.mjs', { session_id: 's5', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
const end = records.find(r => r.end);
assert.ok(end);
assert.equal(end.flags.pushback, 0);
assert.notEqual(end.flags.pushback, undefined);
assert.ok(!Number.isNaN(end.flags.pushback));
// v1.2: empty domain becomes [] (not null) — always an array on disk.
assert.deepEqual(end.domain_context, []);
});
});

137
plugins/ai-psychosis/tests/session-start.test.mjs
View file

@ -1,137 +0,0 @@
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { join } from 'path';
import { writeFileSync } from 'fs';
import { runHook, setupTestDir, cleanupTestDir, readState, readJsonl } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
describe('session-start', () => {
it('creates state file and emits context', () => {
dir = setupTestDir();
const out = runHook('session-start.mjs', { session_id: 's1', cwd: '/tmp' }, dir);
assert.equal(out.continue, true);
assert.ok(out.hookSpecificOutput.additionalContext.includes('Interaction Awareness is active'));
const state = readState(dir, 's1');
assert.ok(state);
assert.equal(state.tool_count, 0);
assert.equal(state.edit_count, 0);
assert.equal(state.dep_flags, 0);
});
it('writes start record to sessions.jsonl', () => {
dir = setupTestDir();
runHook('session-start.mjs', { session_id: 's2', cwd: '/tmp' }, dir);
const records = readJsonl(join(dir, 'sessions.jsonl'));
assert.equal(records.length, 1);
assert.equal(records[0].session_id, 's2');
assert.ok('hour' in records[0]);
assert.ok('is_late_night' in records[0]);
});
it('state has correct initial fields', () => {
dir = setupTestDir();
runHook('session-start.mjs', { session_id: 's3', cwd: '/tmp' }, dir);
const state = readState(dir, 's3');
assert.equal(state.burst_count, 0);
assert.equal(state.last_event_epoch, 0);
assert.equal(state.last_warning_epoch, 0);
assert.ok(state.start_epoch > 0);
assert.ok(state.start_iso.length > 0);
});
it('returns continue with no side effects when session_id missing', () => {
dir = setupTestDir();
const out = runHook('session-start.mjs', { cwd: '/tmp' }, dir);
assert.equal(out.continue, true);
assert.ok(!out.hookSpecificOutput);
});
it('initializes pushback_count and domain_context fields (v1.1.0)', () => {
dir = setupTestDir();
runHook('session-start.mjs', { session_id: 's4', cwd: '/tmp' }, dir);
const state = readState(dir, 's4');
assert.ok(state);
assert.equal(state.pushback_count, 0);
assert.equal(state.domain_context, null);
});
it('initializes v1.2 user-info, valseek, turn_count fields', () => {
dir = setupTestDir();
runHook('session-start.mjs', { session_id: 's4b', cwd: '/tmp' }, dir);
const state = readState(dir, 's4b');
assert.equal(state.user_info_class, null);
assert.deepEqual(state.user_info_flags, { yes_people: 0, yes_digital: 0, no: 0 });
assert.equal(state.turn_count, 0);
assert.equal(state.valseek_count, 0);
assert.equal(state.valseek_flag, 0);
});
});
// --- Tier-2 cross-session alert ---
//
// Fires at SessionStart when last 3 end records all have user_info_class='no'
// AND each session had at least one HIGH_STAKES_DOMAINS hit.
function writeFixture(dir, records) {
const lines = records.map(r => JSON.stringify(r)).join('\n') + '\n';
writeFileSync(join(dir, 'sessions.jsonl'), lines);
}
describe('tier-2 cross-session isolation alert', () => {
it('fires when 3 prior end records all show no + high-stakes', () => {
dir = setupTestDir();
writeFixture(dir, [
{ session_id: 'p1', duration_min: 30, user_info_class: 'no', domain_context: ['legal'] },
{ session_id: 'p2', duration_min: 25, user_info_class: 'no', domain_context: ['health'] },
{ session_id: 'p3', duration_min: 40, user_info_class: 'no', domain_context: ['parenting', 'financial'] },
]);
const out = runHook('session-start.mjs', { session_id: 'snew', cwd: '/tmp' }, dir);
assert.match(out.hookSpecificOutput.additionalContext, /tier-2/);
});
it('does NOT fire when only 2 prior "no" records exist', () => {
dir = setupTestDir();
writeFixture(dir, [
{ session_id: 'p1', duration_min: 30, user_info_class: 'no', domain_context: ['legal'] },
{ session_id: 'p2', duration_min: 30, user_info_class: 'no', domain_context: ['health'] },
]);
const out = runHook('session-start.mjs', { session_id: 'snew2', cwd: '/tmp' }, dir);
const text = out.hookSpecificOutput.additionalContext;
assert.ok(!/tier-2/.test(text), 'tier-2 must require N consecutive sessions');
});
it('does NOT fire when one record has yes_people class', () => {
dir = setupTestDir();
writeFixture(dir, [
{ session_id: 'p1', duration_min: 30, user_info_class: 'no', domain_context: ['legal'] },
{ session_id: 'p2', duration_min: 30, user_info_class: 'yes_people', domain_context: ['health'] },
{ session_id: 'p3', duration_min: 30, user_info_class: 'no', domain_context: ['financial'] },
]);
const out = runHook('session-start.mjs', { session_id: 'snew3', cwd: '/tmp' }, dir);
assert.ok(!/tier-2/.test(out.hookSpecificOutput.additionalContext));
});
it('does NOT fire when any session is in low-stakes domain', () => {
dir = setupTestDir();
writeFixture(dir, [
{ session_id: 'p1', duration_min: 30, user_info_class: 'no', domain_context: ['legal'] },
{ session_id: 'p2', duration_min: 30, user_info_class: 'no', domain_context: ['consumer'] },
{ session_id: 'p3', duration_min: 30, user_info_class: 'no', domain_context: ['health'] },
]);
const out = runHook('session-start.mjs', { session_id: 'snew4', cwd: '/tmp' }, dir);
assert.ok(!/tier-2/.test(out.hookSpecificOutput.additionalContext));
});
it('handles v1.1.0 records with string domain_context (backward compat)', () => {
dir = setupTestDir();
writeFixture(dir, [
{ session_id: 'p1', duration_min: 30, user_info_class: 'no', domain_context: 'health' }, // string shape
{ session_id: 'p2', duration_min: 30, user_info_class: 'no', domain_context: ['legal'] },
{ session_id: 'p3', duration_min: 30, user_info_class: 'no', domain_context: ['parenting'] },
]);
const out = runHook('session-start.mjs', { session_id: 'snew5', cwd: '/tmp' }, dir);
assert.match(out.hookSpecificOutput.additionalContext, /tier-2/);
});
});

69
plugins/ai-psychosis/tests/skill-md.test.mjs
View file

@ -1,69 +0,0 @@
// Verifies SKILL.md stays aligned with the Constitution-mapping JSON
// produced during the v1.1.0 research phase, AND with the Appendix-driven
// v1.2.0 sycophancy 5-scale + 11 guidance criteria additions.
//
// The constitution-mapping.json file is generated locally during research
// and gitignored. On a fresh clone, fall back to checking the verbatim
// CC0 Constitution citation that should be present regardless.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync, existsSync } from 'node:fs';
test('SKILL.md contains Constitution citation', () => {
const skill = readFileSync('skills/ai-psychosis/SKILL.md', 'utf8');
const mappingPath = '.claude/projects/2026-05-01-ai-psychosis-anthropic-guidance/constitution-mapping.json';
if (existsSync(mappingPath)) {
const mapping = JSON.parse(readFileSync(mappingPath, 'utf8'));
if (mapping.skill_md_grep_target === 'FALLBACK_PARAPHRASE') {
assert.ok(skill.includes('anthropic.com/research/claude-personal-guidance'));
} else {
assert.ok(
skill.includes(mapping.skill_md_grep_target),
`SKILL.md missing locked Constitution target: ${mapping.skill_md_grep_target}`
);
}
} else {
// Fresh clone — assertion fallback uses the verbatim CC0 Constitution
// text known to be present in v1.1.0+.
assert.ok(skill.includes("Sometimes being honest requires courage"),
'SKILL.md missing CC0 Constitution courage citation');
}
assert.ok(skill.includes('anthropic.com/constitution'));
assert.ok(skill.includes('anthropic.com/research/claude-personal-guidance'));
});
test('SKILL.md cites Score 5 sycophancy phrase verbatim (v1.2)', () => {
const skill = readFileSync('skills/ai-psychosis/SKILL.md', 'utf8');
assert.ok(
skill.includes('Provides accurate, honest information regardless'),
'SKILL.md missing verbatim Score 5 phrasing'
);
assert.ok(
skill.includes('Maintains correct positions when challenged'),
'SKILL.md missing Score 5 challenge phrase'
);
assert.ok(
skill.includes("Delivers difficult truths constructively"),
'SKILL.md missing Score 5 difficult-truths phrase'
);
});
test('SKILL.md cites the 11 guidance criteria (v1.2 — at least 3 quoted)', () => {
const skill = readFileSync('skills/ai-psychosis/SKILL.md', 'utf8');
// Three load-bearing quotes from the 11 criteria (page 2 of Appendix).
assert.ok(
skill.includes("Avoid providing guidance that would foster continued engagement"),
'SKILL.md missing engagement-foster criterion'
);
assert.ok(
skill.includes("Be wary of giving excessively confident verdicts"),
'SKILL.md missing confident-verdicts criterion'
);
assert.ok(
skill.includes("Maintain integrity and be willing to speak frankly"),
'SKILL.md missing frank-pushback criterion'
);
});

114
plugins/ai-psychosis/tests/stakes-matrix.test.mjs
View file

@ -1,114 +0,0 @@
// stakes-matrix.test.mjs — verifies v1.2 domain-stakes weighting on
// new v1.2 alerts only. v1.1.0 alert sensitivity (dep, esc, fat, val,
// burst, low-edit-ratio) MUST be unchanged.
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readState } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
function freshState() {
return {
start_epoch: Math.floor(Date.now() / 1000) - 60,
start_iso: '2026-05-01T10:00:00Z',
tool_count: 0, edit_count: 0,
last_event_epoch: 0, burst_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 0, domain_context: null,
user_info_class: null,
user_info_flags: { yes_people: 0, yes_digital: 0, no: 0 },
turn_count: 0,
valseek_count: 0, valseek_flag: 0,
last_warning_epoch: 0,
};
}
function runPromptCapture(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 's-stake', { ...freshState(), ...stateOverrides });
const out = runHook('prompt-analyzer.mjs', { session_id: 's-stake', prompt }, dir);
const state = readState(dir, 's-stake');
return { state, out };
}
describe('stakes-matrix on valseek HIGH_STAKES path', () => {
it('valseek_count=2 in legal (weight 1.5) → effective threshold 2.0 → fires', () => {
// 3 / 1.5 = 2.0; valseek_count after this prompt becomes 2; 2 >= 2.0 → fires.
const { out } = runPromptCapture("am I crazy?", {
domain_context: ['legal'],
valseek_count: 1,
});
assert.match(out.hookSpecificOutput.additionalContext, /high-stakes/);
});
it('valseek_count=1 in legal → 1 < 2.0 → no alert', () => {
const { out } = runPromptCapture("am I crazy?", {
domain_context: ['legal'],
valseek_count: 0, // becomes 1
});
assert.equal(out.hookSpecificOutput, undefined);
});
it('valseek_count=4 in consumer (weight 1.0, NOT in HIGH_STAKES) → no alert regardless', () => {
const { out } = runPromptCapture("am I crazy?", {
domain_context: ['consumer'],
valseek_count: 3, // becomes 4
});
assert.equal(out.hookSpecificOutput, undefined,
'consumer is outside HIGH_STAKES_DOMAINS — high-stakes path never fires');
});
it('valseek_count=2 in legal → fires; same count in professional (INFO only) → no alert', () => {
const legal = runPromptCapture("am I crazy?", {
domain_context: ['legal'],
valseek_count: 1,
});
const pro = runPromptCapture("am I crazy?", {
domain_context: ['professional'],
valseek_count: 1,
});
assert.match(legal.out.hookSpecificOutput.additionalContext, /high-stakes/);
assert.equal(pro.out.hookSpecificOutput, undefined,
'professional is in INFO_DOMAINS but not HIGH_STAKES_DOMAINS');
});
});
describe('stakes-matrix on pushback HIGH_SYCOPHANCY path', () => {
it('pushback_count=2 in relationship (weight 1.3) → 2/1.3 ≈ 1.54 → fires', () => {
const { out } = runPromptCapture("are you sure?", {
domain_context: ['relationship'],
pushback_count: 1, // becomes 2
});
assert.match(out.hookSpecificOutput.additionalContext, /pushback re-contextualization/);
});
});
describe('stakes-matrix MUST NOT alter v1.1.0 alert sensitivity', () => {
it('dep_flags=1 in legal → does NOT fire dependency alert', () => {
// Dependency soft threshold = 2 in v1.1.0. If stakes-matrix bled into this,
// 2/1.5 = 1.33 → dep_flags=1 might trigger. It must NOT.
const { out } = runPromptCapture("tell me what to do here", {
domain_context: ['legal'],
dep_flags: 0, // this prompt sets to 1
});
// v1.1.0 dep alert requires >= 2 flags, regardless of domain weight.
// Output should not contain dep "Dependency language" wording.
const text = out.hookSpecificOutput?.additionalContext || '';
assert.ok(!/Dependency language/.test(text),
'v1.1.0 dependency threshold must not be lowered by stakes weight');
});
it('val_flags=2 in legal → does NOT fire validation-seeking v1.1.0 alert', () => {
// v1.1.0 val_flags threshold is 3. Stakes weight must not lower it to 2.
const { out } = runPromptCapture("right?", {
domain_context: ['legal'],
val_flags: 1, // becomes 2
});
const text = out.hookSpecificOutput?.additionalContext || '';
// The v1.1.0 wording is "Validation-seeking pattern detected (...)".
assert.ok(!/Validation-seeking pattern detected/.test(text),
'v1.1.0 val_flags threshold (3) must not be lowered by stakes weight');
});
});

53
plugins/ai-psychosis/tests/test-helper.mjs
View file

@ -1,53 +0,0 @@
// Shared test utilities for hook script tests.
// Uses node:child_process to pipe JSON stdin to hook scripts.
import { execSync } from 'child_process';
import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
import { join } from 'path';
import { tmpdir } from 'os';
const SCRIPTS_DIR = join(import.meta.dirname, '..', 'hooks', 'scripts');
export function runHook(scriptName, stdinJson, dataDir) {
const input = typeof stdinJson === 'string' ? stdinJson : JSON.stringify(stdinJson);
const env = { ...process.env, CLAUDE_PLUGIN_DATA: dataDir };
const stdout = execSync(`node ${join(SCRIPTS_DIR, scriptName)}`, {
input,
env,
encoding: 'utf8',
timeout: 5000,
});
try {
return JSON.parse(stdout.trim());
} catch {
return { raw: stdout.trim() };
}
}
export function setupTestDir() {
const dir = mkdtempSync(join(tmpdir(), 'ia-test-'));
mkdirSync(join(dir, 'state'), { recursive: true });
return dir;
}
export function cleanupTestDir(dir) {
rmSync(dir, { recursive: true, force: true });
}
export function createStateFile(dir, sid, state) {
writeFileSync(join(dir, 'state', `${sid}.json`), JSON.stringify(state, null, 2));
}
export function readState(dir, sid) {
const f = join(dir, 'state', `${sid}.json`);
if (!existsSync(f)) return null;
return JSON.parse(readFileSync(f, 'utf8'));
}
export function readJsonl(filePath) {
if (!existsSync(filePath)) return [];
return readFileSync(filePath, 'utf8')
.split('\n')
.filter(Boolean)
.map(line => JSON.parse(line));
}

94
plugins/ai-psychosis/tests/tool-tracker.test.mjs
View file

@ -1,94 +0,0 @@
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { join } from 'path';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readState, readJsonl } from './test-helper.mjs';
let dir;
function freshState(overrides = {}) {
return {
start_epoch: Math.floor(Date.now() / 1000) - 60,
start_iso: '2026-01-01T10:00:00Z',
tool_count: 0, edit_count: 0,
last_event_epoch: 0, burst_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
last_warning_epoch: 0,
...overrides,
};
}
afterEach(() => { if (dir) cleanupTestDir(dir); });
describe('tool-tracker', () => {
it('tracks tool call and increments tool_count', () => {
dir = setupTestDir();
createStateFile(dir, 't1', freshState());
runHook('tool-tracker.mjs', { session_id: 't1', tool_name: 'Read' }, dir);
const s = readState(dir, 't1');
assert.equal(s.tool_count, 1);
const events = readJsonl(join(dir, 'events.jsonl'));
assert.equal(events.length, 1);
assert.equal(events[0].tool_name, 'Read');
assert.equal(events[0].session_id, 't1');
});
it('increments edit_count for Edit tool', () => {
dir = setupTestDir();
createStateFile(dir, 't2', freshState());
runHook('tool-tracker.mjs', { session_id: 't2', tool_name: 'Edit' }, dir);
const s = readState(dir, 't2');
assert.equal(s.edit_count, 1);
});
it('does not increment edit_count for non-Edit tool', () => {
dir = setupTestDir();
createStateFile(dir, 't3', freshState());
runHook('tool-tracker.mjs', { session_id: 't3', tool_name: 'Bash' }, dir);
const s = readState(dir, 't3');
assert.equal(s.edit_count, 0);
});
it('detects burst when interval < 30s', () => {
dir = setupTestDir();
createStateFile(dir, 't4', freshState({
last_event_epoch: Math.floor(Date.now() / 1000) - 5,
burst_count: 0,
}));
runHook('tool-tracker.mjs', { session_id: 't4', tool_name: 'Read' }, dir);
const s = readState(dir, 't4');
assert.equal(s.burst_count, 1);
});
it('resets burst when interval >= 30s', () => {
dir = setupTestDir();
createStateFile(dir, 't5', freshState({
last_event_epoch: Math.floor(Date.now() / 1000) - 60,
burst_count: 3,
}));
runHook('tool-tracker.mjs', { session_id: 't5', tool_name: 'Read' }, dir);
const s = readState(dir, 't5');
assert.equal(s.burst_count, 0);
});
it('emits periodic reminder at modulo 25', () => {
dir = setupTestDir();
createStateFile(dir, 't6', freshState({ tool_count: 24 }));
const out = runHook('tool-tracker.mjs', { session_id: 't6', tool_name: 'Read' }, dir);
assert.ok(out.hookSpecificOutput?.additionalContext?.includes('REMINDER'));
});
it('outputs continue between checkpoints', () => {
dir = setupTestDir();
createStateFile(dir, 't7', freshState({ tool_count: 5 }));
const out = runHook('tool-tracker.mjs', { session_id: 't7', tool_name: 'Read' }, dir);
assert.equal(out.continue, true);
assert.ok(!out.hookSpecificOutput);
});
it('handles missing state file gracefully', () => {
dir = setupTestDir();
// No state file created
const out = runHook('tool-tracker.mjs', { session_id: 'missing', tool_name: 'Read' }, dir);
assert.equal(out.continue, true);
});
});

247
plugins/ai-psychosis/tests/user-info.test.mjs
View file

@ -1,247 +0,0 @@
// user-info.test.mjs — verifies v1.2 user-information classifier.
//
// Three classes: yes_people > yes_digital > no (priority order).
// Class is sticky upward — yes_people once set never downgrades.
// turn_count increments on every prompt-analyzer invocation.
// Step 9 will add the tier-1 alert; this file currently locks the
// detection + sticky semantics.
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readState } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
function freshState() {
return {
start_epoch: Math.floor(Date.now() / 1000) - 60,
start_iso: '2026-05-01T10:00:00Z',
tool_count: 0, edit_count: 0,
last_event_epoch: 0, burst_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 0, domain_context: null,
user_info_class: null,
user_info_flags: { yes_people: 0, yes_digital: 0, no: 0 },
turn_count: 0,
valseek_count: 0, valseek_flag: 0,
last_warning_epoch: 0,
};
}
function runPrompt(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'u1', { ...freshState(), ...stateOverrides });
runHook('prompt-analyzer.mjs', { session_id: 'u1', prompt }, dir);
return readState(dir, 'u1');
}
// --- yes_people detection ---
describe('user_info: yes_people patterns', () => {
it('matches "my therapist"', () => {
const s = runPrompt('I asked my therapist about this');
assert.equal(s.user_info_class, 'yes_people');
assert.equal(s.user_info_flags.yes_people, 1);
});
it('matches "my friend"', () => {
const s = runPrompt('my friend says I should try meditation');
assert.equal(s.user_info_class, 'yes_people');
});
it('matches "my mentor"', () => {
const s = runPrompt('my mentor mentioned this approach');
assert.equal(s.user_info_class, 'yes_people');
});
it('matches "I told my partner"', () => {
const s = runPrompt('I told my partner about it last night');
assert.equal(s.user_info_class, 'yes_people');
});
});
describe('user_info: yes_digital patterns', () => {
it('matches "I googled"', () => {
const s = runPrompt('I googled this and got mixed results');
assert.equal(s.user_info_class, 'yes_digital');
});
it('matches "ChatGPT said"', () => {
const s = runPrompt('ChatGPT said the answer was 42');
assert.equal(s.user_info_class, 'yes_digital');
});
it('matches "I read on a forum post"', () => {
const s = runPrompt('I read on a forum post that this works');
assert.equal(s.user_info_class, 'yes_digital');
});
});
describe('user_info: no patterns', () => {
it('matches "nobody knows"', () => {
const s = runPrompt("nobody knows I'm dealing with this");
assert.equal(s.user_info_class, 'no');
});
it('matches "haven\'t told anyone"', () => {
const s = runPrompt("I haven't told anyone about it");
assert.equal(s.user_info_class, 'no');
});
it('matches "dealing with this alone"', () => {
const s = runPrompt("I'm dealing with this alone");
assert.equal(s.user_info_class, 'no');
});
});
// --- Priority + sticky semantics ---
describe('user_info: priority and stickiness', () => {
it('yes_people wins over yes_digital in same prompt', () => {
const s = runPrompt("I googled it but my therapist said something else");
assert.equal(s.user_info_class, 'yes_people');
// Both counters increment regardless of class outcome.
assert.equal(s.user_info_flags.yes_people, 1);
assert.equal(s.user_info_flags.yes_digital, 1);
});
it('yes_people wins over no in same prompt', () => {
const s = runPrompt("nobody knows but I told my friend");
assert.equal(s.user_info_class, 'yes_people');
});
it('yes_digital wins over no in same prompt', () => {
const s = runPrompt("nobody knows except what I read on a forum post");
assert.equal(s.user_info_class, 'yes_digital');
});
it('sticky: yes_people set, later yes_digital prompt does NOT downgrade', () => {
dir = setupTestDir();
createStateFile(dir, 'u-sticky', freshState());
runHook('prompt-analyzer.mjs', { session_id: 'u-sticky', prompt: 'my therapist suggested journaling' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'u-sticky', prompt: 'I googled the rest' }, dir);
const s = readState(dir, 'u-sticky');
assert.equal(s.user_info_class, 'yes_people', 'must not downgrade from people to digital');
assert.equal(s.user_info_flags.yes_digital, 1, 'digital counter still increments');
});
it('sticky: no → yes_people upgrades (lower → higher rank)', () => {
dir = setupTestDir();
createStateFile(dir, 'u-up', freshState());
runHook('prompt-analyzer.mjs', { session_id: 'u-up', prompt: 'nobody knows about this' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'u-up', prompt: 'finally told my therapist' }, dir);
const s = readState(dir, 'u-up');
assert.equal(s.user_info_class, 'yes_people');
});
it('class stays null when no user-info patterns hit', () => {
const s = runPrompt('refactor this typescript module to use generics');
assert.equal(s.user_info_class, null);
assert.equal(s.user_info_flags.yes_people, 0);
assert.equal(s.user_info_flags.yes_digital, 0);
assert.equal(s.user_info_flags.no, 0);
});
});
// --- turn_count ---
describe('turn_count', () => {
it('increments on every prompt-analyzer call', () => {
dir = setupTestDir();
createStateFile(dir, 'u-turn', freshState());
for (let i = 0; i < 5; i++) {
runHook('prompt-analyzer.mjs', { session_id: 'u-turn', prompt: `prompt ${i}` }, dir);
}
const s = readState(dir, 'u-turn');
assert.equal(s.turn_count, 5);
});
it('handles missing turn_count in pre-v1.2 state files (defaults to 0)', () => {
const legacy = freshState();
delete legacy.turn_count;
dir = setupTestDir();
createStateFile(dir, 'u-legacy', legacy);
runHook('prompt-analyzer.mjs', { session_id: 'u-legacy', prompt: 'hello' }, dir);
const s = readState(dir, 'u-legacy');
assert.equal(s.turn_count, 1, 'should start from 0 when field absent and increment to 1');
});
});
// --- Tier-1 alert ---
//
// Fires when user_info_class === 'no' AND domain_context intersects
// HIGH_STAKES_DOMAINS AND turn_count >= TIER1_TURN_THRESHOLD (15).
function runPromptCapture(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'u-tier1', { ...freshState(), ...stateOverrides });
const out = runHook('prompt-analyzer.mjs', { session_id: 'u-tier1', prompt }, dir);
const state = readState(dir, 'u-tier1');
return { state, out };
}
describe('tier-1 user-info alert', () => {
it('fires at turn 15 (pre-seed 14) with no + legal domain', () => {
// Pre-seed: turn_count 14, after one hook call → 15. Triggers alert.
const { state, out } = runPromptCapture('any innocuous prompt', {
turn_count: 14,
user_info_class: 'no',
domain_context: ['legal'],
});
assert.equal(state.turn_count, 15);
assert.ok(out.hookSpecificOutput, 'tier-1 alert should be emitted');
assert.match(out.hookSpecificOutput.additionalContext, /tier-1/);
assert.match(out.hookSpecificOutput.additionalContext, /legal/);
});
it('does NOT fire sub-threshold (turn 14 → 14 should not trigger; 13 → 14)', () => {
const { state, out } = runPromptCapture('any prompt', {
turn_count: 13,
user_info_class: 'no',
domain_context: ['legal'],
});
assert.equal(state.turn_count, 14);
assert.equal(out.hookSpecificOutput, undefined,
'tier-1 must not fire below threshold');
});
it('does NOT fire for low-stakes domain (consumer)', () => {
const { out } = runPromptCapture('any prompt', {
turn_count: 14,
user_info_class: 'no',
domain_context: ['consumer'],
});
assert.equal(out.hookSpecificOutput, undefined,
'tier-1 only fires in high-stakes domains');
});
it('does NOT fire when user_info_class is yes_people (supersedes "no")', () => {
const { out } = runPromptCapture('any prompt', {
turn_count: 14,
user_info_class: 'yes_people',
domain_context: ['legal'],
});
assert.equal(out.hookSpecificOutput, undefined,
'tier-1 only fires when user signals isolation');
});
it('does NOT fire when domain_context is empty', () => {
const { out } = runPromptCapture('any prompt', {
turn_count: 14,
user_info_class: 'no',
domain_context: [],
});
assert.equal(out.hookSpecificOutput, undefined);
});
it('fires for parenting domain (also high-stakes)', () => {
const { out } = runPromptCapture('any prompt', {
turn_count: 14,
user_info_class: 'no',
domain_context: ['parenting'],
});
assert.ok(out.hookSpecificOutput, 'tier-1 fires for parenting too');
assert.match(out.hookSpecificOutput.additionalContext, /parenting/);
});
});

205
plugins/ai-psychosis/tests/validation-seeking.test.mjs
View file

@ -1,205 +0,0 @@
// validation-seeking.test.mjs — verifies v1.2 validation-seeking detector.
//
// Distinct from existing val_flags ("right?" tic). valseek targets:
// - tag-questions pressing for agreement
// - reality-testing ("am I crazy?", "is it normal?")
// - side-taking pressing ("back me up")
// - pre-committed stance + confirmation
//
// Step 11 will add the domain-gated alert; this file currently locks
// detection + count accumulation semantics.
import { describe, it, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { runHook, setupTestDir, cleanupTestDir, createStateFile, readState } from './test-helper.mjs';
let dir;
afterEach(() => { if (dir) cleanupTestDir(dir); });
function freshState() {
return {
start_epoch: Math.floor(Date.now() / 1000) - 60,
start_iso: '2026-05-01T10:00:00Z',
tool_count: 0, edit_count: 0,
last_event_epoch: 0, burst_count: 0,
dep_flags: 0, esc_flags: 0, fatigue_flags: 0, val_flags: 0,
pushback_count: 0, domain_context: null,
user_info_class: null,
user_info_flags: { yes_people: 0, yes_digital: 0, no: 0 },
turn_count: 0,
valseek_count: 0, valseek_flag: 0,
last_warning_epoch: 0,
};
}
function runPrompt(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'v1', { ...freshState(), ...stateOverrides });
runHook('prompt-analyzer.mjs', { session_id: 'v1', prompt }, dir);
return readState(dir, 'v1');
}
// --- Pattern detection ---
describe('valseek: tag-questions pressing for agreement', () => {
it('matches "isn\'t it?"', () => {
const s = runPrompt("she's wrong, isn't she?");
assert.equal(s.valseek_count, 1);
assert.equal(s.valseek_flag, 1);
});
it('matches "don\'t you think?"', () => {
const s = runPrompt("this approach is better, don't you think?");
assert.equal(s.valseek_count, 1);
});
it('matches "right, though?"', () => {
const s = runPrompt("I should leave him, right, though?");
assert.equal(s.valseek_count, 1);
});
});
describe('valseek: reality-testing patterns', () => {
it('matches "am I crazy"', () => {
const s = runPrompt("am I crazy for thinking this?");
assert.equal(s.valseek_count, 1);
});
it('matches "tell me I\'m not crazy"', () => {
const s = runPrompt("tell me I'm not crazy for feeling betrayed");
assert.equal(s.valseek_count, 1);
});
it('matches "is it normal to"', () => {
const s = runPrompt("is it normal to feel this way after years?");
assert.equal(s.valseek_count, 1);
});
});
describe('valseek: side-taking pressing', () => {
it('matches "you agree, right?"', () => {
const s = runPrompt("you agree, right?");
assert.equal(s.valseek_count, 1);
});
it('matches "back me up here"', () => {
const s = runPrompt("she lied to me — back me up here");
assert.equal(s.valseek_count, 1);
});
});
describe('valseek: pre-committed stance', () => {
it('matches "I already decided ... right"', () => {
const s = runPrompt("I already decided to quit, that's right?");
assert.equal(s.valseek_count, 1);
});
it('matches "I know I\'m right about this"', () => {
const s = runPrompt("I know I'm right about this whole thing");
assert.equal(s.valseek_count, 1);
});
});
// --- Negative cases ---
describe('valseek: false-positive guards', () => {
it('does NOT match casual "right?" tic alone', () => {
const s = runPrompt('the function returns true, right?');
// Casual right? hits the existing val_flags pattern but NOT valseek.
assert.equal(s.valseek_count, 0);
});
it('does NOT match technical question without pressing pattern', () => {
const s = runPrompt('what does this regex do?');
assert.equal(s.valseek_count, 0);
});
});
// --- Accumulation ---
describe('valseek: count accumulation', () => {
it('accumulates across multiple prompts', () => {
dir = setupTestDir();
createStateFile(dir, 'v-acc', freshState());
const prompts = [
"am I crazy for staying?",
"you agree, right?",
"isn't she wrong?",
"I know I'm right on this",
"tell me I'm not crazy",
];
for (const p of prompts) {
runHook('prompt-analyzer.mjs', { session_id: 'v-acc', prompt: p }, dir);
}
const s = readState(dir, 'v-acc');
assert.equal(s.valseek_count, 5);
assert.equal(s.valseek_flag, 1);
});
it('valseek_flag is sticky once set, even if later prompt has no hit', () => {
dir = setupTestDir();
createStateFile(dir, 'v-sticky', freshState());
runHook('prompt-analyzer.mjs', { session_id: 'v-sticky', prompt: 'am I crazy?' }, dir);
runHook('prompt-analyzer.mjs', { session_id: 'v-sticky', prompt: 'refactor this code' }, dir);
const s = readState(dir, 'v-sticky');
assert.equal(s.valseek_count, 1, 'count is unchanged by later non-matching prompt');
assert.equal(s.valseek_flag, 1, 'flag stays 1 once set');
});
});
// --- Domain-gated alert ---
function runPromptCapture(prompt, stateOverrides = {}) {
dir = setupTestDir();
createStateFile(dir, 'v-alert', { ...freshState(), ...stateOverrides });
const out = runHook('prompt-analyzer.mjs', { session_id: 'v-alert', prompt }, dir);
const state = readState(dir, 'v-alert');
return { state, out };
}
describe('valseek: domain-gated alert', () => {
it('1 valseek + relationship → alert (high-sycophancy)', () => {
const { out } = runPromptCapture("am I crazy?", { domain_context: ['relationship'] });
assert.match(out.hookSpecificOutput.additionalContext, /validation-seeking/);
});
it('1 valseek + spirituality → alert (high-sycophancy)', () => {
const { out } = runPromptCapture("am I crazy?", { domain_context: ['spirituality'] });
assert.match(out.hookSpecificOutput.additionalContext, /validation-seeking/);
});
it('5 valseek + consumer → NO alert (low-stakes domain)', () => {
const { out } = runPromptCapture("you agree, right?", {
domain_context: ['consumer'],
valseek_count: 4, // becomes 5 after this prompt
});
assert.equal(out.hookSpecificOutput, undefined,
'low-stakes domain — no validation alert even at high count');
});
it('3 valseek + legal → alert (high-stakes path)', () => {
const { out } = runPromptCapture("am I crazy?", {
domain_context: ['legal'],
valseek_count: 2, // becomes 3
});
assert.match(out.hookSpecificOutput.additionalContext, /high-stakes/);
});
it('1 valseek + legal → NO alert (sub-threshold even with stakes weight)', () => {
// Step 13: stakes weight 1.5 lowers high-stakes threshold from 3 to 2.0.
// valseek_count=1 still under threshold.
const { out } = runPromptCapture("am I crazy?", {
domain_context: ['legal'],
valseek_count: 0, // becomes 1
});
assert.equal(out.hookSpecificOutput, undefined);
});
it('valseek alert fires for relationship even with valseek_count = 1', () => {
const { out } = runPromptCapture("you agree, right?", {
domain_context: ['relationship'],
valseek_count: 0, // becomes 1
});
assert.match(out.hookSpecificOutput.additionalContext, /validation-seeking/);
});
});

18
plugins/claude-design/.claude-plugin/plugin.json
View file

@ -1,18 +0,0 @@
{
"name": "claude-design",
"version": "0.1.0",
"description": "End-to-end facilitator for prompting Claude Design (claude.ai/design) — idea to copy-paste-ready prompt with iteration coaching, citing Anthropic primary sources.",
"author": {
"name": "Kjell Tore Guttormsen"
},
"auto_discover": true,
"license": "MIT",
"repository": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace",
"keywords": [
"claude-design",
"claude-ai",
"prompt-engineering",
"artifacts",
"design"
]
}

90
plugins/claude-design/.coverage.md
View file

@ -1,90 +0,0 @@
# claude-design coverage manifest
**Captured-on date:** 2026-05-17 | **Source:** `https://anthropic.com/news/claude-design-anthropic-labs` (intent-preset enumeration)
This file is the canonical input for SC2 verification (`tests/test-sc2-artifact-coverage.sh`) and the SC3 Authoritative-claims registry (`tests/test-sc3-citations.sh`). Both tests read this file directly — keep it in sync with the references tree.
Anthropic's launch enumeration names eight intent presets; this plugin ships one reference file per preset with explicit evidence-grade labelling. The evidence-grade levels are:
- **Anthropic-documented + community-validated** — Anthropic publishes verbatim prompt patterns and community practitioners have independently validated them
- **Community-only** — Anthropic names the preset but publishes no per-preset prompt patterns; the patterns come from community practitioners with attribution
- **Experimental** — neither Anthropic nor community practitioners have published verifiable prompt patterns; the preset is engaged speculatively
The evidence-grade labels are load-bearing for SC2 and SC3. Per-preset reference files restate the grade inline on line 4.
---
## Intent preset coverage
| Preset | Reference file | Evidence grade | Anthropic anchor URL |
| --- | --- | --- | --- |
| designs | skills/claude-design-facilitator/references/presets/designs.md | Evidence grade: Anthropic-documented + community-validated | https://anthropic.com/news/claude-design-anthropic-labs |
| prototypes | skills/claude-design-facilitator/references/presets/prototypes.md | Evidence grade: Anthropic-documented + community-validated | https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux |
| slides | skills/claude-design-facilitator/references/presets/slides.md | Evidence grade: Anthropic-documented + community-validated | https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks |
| one-pagers | skills/claude-design-facilitator/references/presets/one-pagers.md | Evidence grade: Community-only | https://anthropic.com/news/claude-design-anthropic-labs |
| wireframes-mockups | skills/claude-design-facilitator/references/presets/wireframes-mockups.md | Evidence grade: Community-only | https://anthropic.com/news/claude-design-anthropic-labs |
| pitch-decks | skills/claude-design-facilitator/references/presets/pitch-decks.md | Evidence grade: Community-only | https://anthropic.com/news/claude-design-anthropic-labs |
| marketing-collateral | skills/claude-design-facilitator/references/presets/marketing-collateral.md | Evidence grade: Community-only | https://anthropic.com/news/claude-design-anthropic-labs |
| frontier-design | skills/claude-design-facilitator/references/presets/frontier-design.md | Evidence grade: Experimental — no validated practitioner pattern | https://anthropic.com/news/claude-design-anthropic-labs |
The preset names in column 1 (`designs`, `prototypes`, `slides`, `one-pagers`, `wireframes-mockups`, `pitch-decks`, `marketing-collateral`, `frontier-design`) are the canonical names used by `tests/test-sc2-artifact-coverage.sh`. The test extracts column 1 via awk and runs grep against the plugin's content tree to verify each preset has at least one supporting file.
---
## Authoritative-claims files
The following files contain authoritative claims (Anthropic-published material, primary sources, or community-converged patterns with attribution). Each must carry at least one Anthropic-domain URL citation. `tests/test-sc3-citations.sh` reads this bullet list, parses paths via awk on `^- `, then runs the citation grep against each file.
- skills/claude-design-facilitator/references/00-what-claude-design-is-and-isnt.md
- skills/claude-design-facilitator/references/01-prompt-fundamentals.md
- skills/claude-design-facilitator/references/02-design-md.md
- skills/claude-design-facilitator/references/03-iteration-and-session.md
- skills/claude-design-facilitator/references/04-handoff-and-scope.md
- skills/claude-design-facilitator/references/presets/designs.md
- skills/claude-design-facilitator/references/presets/prototypes.md
- skills/claude-design-facilitator/references/presets/slides.md
- skills/claude-design-facilitator/references/presets/one-pagers.md
- skills/claude-design-facilitator/references/presets/wireframes-mockups.md
- skills/claude-design-facilitator/references/presets/pitch-decks.md
- skills/claude-design-facilitator/references/presets/marketing-collateral.md
- skills/claude-design-facilitator/references/presets/frontier-design.md
Total: 13 authoritative-claims files (5 foundation references + 8 per-preset references).
The bullet-list format is load-bearing — `tests/test-sc3-citations.sh` parses lines starting with `- ` (dash + space). Do not switch to a table or numbered list without updating the test.
---
## Re-research triggers
This manifest refreshes when any of these events occurs:
- **Anthropic publishes per-preset guidance for a Community-only preset** (one-pagers, wireframes-mockups, pitch-decks, marketing-collateral) — upgrade the affected row's evidence grade and add the new Anthropic anchor URL
- **Anthropic publishes per-preset guidance for the Experimental preset** (frontier-design) — upgrade to Community-only or Anthropic-documented depending on coverage depth
- **A new intent preset is added to Anthropic's launch-post enumeration** (`https://anthropic.com/news/claude-design-anthropic-labs`) — add a new row, write a new preset reference file
- **An existing intent preset is removed from the enumeration** — remove the row, deprecate the reference file in `CHANGELOG.md`
- **A first verified frontier-design practitioner artifact ships publicly** with prompt + output + reproduction steps — upgrade the frontier-design row from Experimental to Community-only, update `presets/frontier-design.md`
- **Anthropic support article URL slugs change while keeping numeric IDs stable** — re-pin URLs in column 4 (Anthropic anchor URL); the numeric IDs in `support.claude.com/en/articles/<numeric-id>-<slug>` are the stable anchor
- **Labs → GA URL rename for `claude.ai/design`** — re-pin the launch-post URL once the `-anthropic-labs` slug is dropped (note: the launch URL `https://anthropic.com/news/claude-design-anthropic-labs` may or may not 301-redirect after the rename)
When any trigger fires, run `bash plugins/claude-design/verify.sh --strict` after the manifest update to confirm SC2 and SC3 still pass.
---
## Related sources (for context, not for SC checks)
Anthropic primary sources that ground this manifest but are not themselves authoritative-claims files (because they are external URLs, not plugin files):
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — GLCA framework
- `https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design` — design-system setup
- `https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint` — PowerPoint-mode conventions
- `https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux` — prototypes tutorial
- `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` — slides tutorial
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading framing
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Design-Thinking Framework, AI-slop avoid-list
- `https://claude.com/blog/improving-frontend-design-through-skills` — default-avoidance blog post
- `https://claude.com/plugins/design` — Anthropic's official knowledge-work-plugins/design plugin (downstream tool)
- `https://github.com/anthropics/knowledge-work-plugins` — source for Anthropic's downstream plugin
Anthropic URL canonicalisation: every `support.claude.com` reference uses the `https://support.claude.com/en/articles/<numeric-id>-<slug>` form. Numeric IDs are stable across slug rewrites; slug-only URLs are not.

37
plugins/claude-design/CHANGELOG.md
View file

@ -1,37 +0,0 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.1.0] — 2026-05-17
### Added
- `claude-design-facilitator` skill with eight-phase facilitation flow (disambiguate → intent preset → audience + destination → DESIGN.md anchor → five-layer prompt draft → copy-paste delivery → iteration coaching → ship-readiness handoff) and 12 natural-language trigger phrases registered in `.triggers.txt`.
- Five foundation references under `skills/claude-design-facilitator/references/`: `00-what-claude-design-is-and-isnt.md` (surface disambiguation), `01-prompt-fundamentals.md` (five-layer prompt stack: GLCA + start-simple + concrete-alternative-spec + propose-options + AI-slop avoid-list + four design dimensions + four grading criteria), `02-design-md.md` (DESIGN.md 9-section canonical structure + brand-to-DESIGN.md extractor), `03-iteration-and-session.md` (Tweak / Comment / Chat cascade, session economics, recovery prompt library), `04-handoff-and-scope.md` (one-way Design → Code handoff + scope fence vs Anthropic's `knowledge-work-plugins/design`).
- Eight per-preset references under `skills/claude-design-facilitator/references/presets/` with evidence-grade labels: `designs.md`, `prototypes.md`, `slides.md` (Anthropic-documented + community-validated); `one-pagers.md`, `wireframes-mockups.md`, `pitch-decks.md`, `marketing-collateral.md` (Community-only); `frontier-design.md` (Experimental — no validated practitioner pattern as of 2026-05-16).
- `.coverage.md` at plugin root — preset enumeration table with evidence-grade labels (8 rows) + `Authoritative-claims files` bullet-list registry (13 paths). Canonical input for SC2 and SC3 verification.
- Five verification scripts under `tests/`: `validate-plugin.sh` (structural integrity + forbidden-command-name scope fence + operator-private-context grep + Norwegian-leakage advisory), `test-skill-triggers.sh` (description quality + trigger phrase coverage), `test-sc2-artifact-coverage.sh` (per-preset coverage from `.coverage.md`), `test-sc3-citations.sh` (Anthropic-domain citation discipline), `test-sc1-dogfood-log.sh` (operator dogfood log format-check in `REMEMBER.md`).
- `verify.sh` top-level roll-up with `--strict` (SC1 missing-block becomes FAIL) and `--quick` (skip skill-triggers test) flags.
- `LICENSE` (MIT) and `GOVERNANCE.md` (marketplace fork-and-own blurb).
- Marketplace registration in root `.claude-plugin/marketplace.json`.
### Documentation
- Plugin `README.md` rewritten from scaffold placeholder to full v0.1 surface description with `Scope and complementarity` section (placed before installation per brief), `What this plugin is NOT` (Non-Goals), eight-phase facilitation flow table, skill surface table, reference content map, per-preset coverage table, verification section, AI-generated disclosure, fork-and-own MIT licensing.
- Plugin `CLAUDE.md` translated to English (operator override of marketplace's Norwegian-dialogue default per v0.1 brief constraint); added `Scope fence` section explicitly forbidding command-name collisions with Anthropic's `knowledge-work-plugins/design` (`/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, `/handoff`); `Authoring rules` section codifies English-everywhere, no operator-private context, evidence-grade label discipline, URL canonicalisation on `support.claude.com/en/articles/<numeric-id>-<slug>`; `Communication patterns` block preserved verbatim.
- Root marketplace `README.md` updated with `### [Claude Design](plugins/claude-design/) \`v0.1.0\`` entry under the `## Plugins` section, positioned after the Human-Friendly Style entry per existing convention. Entry documents the complementary lifecycle coverage vs `knowledge-work-plugins/design`.
### Notes
- **Scope:** claude-design facilitates the pre-design and during-design lifecycle for `claude.ai/design` (Anthropic Labs research preview, Opus 4.7 pinned, eight intent presets). For post-design — critique, accessibility audit, UX copy review, design-system audit, engineering handoff — install Anthropic's official plugin via `claude plugins add knowledge-work-plugins/design`. Zero command overlap, complementary by design.
- **No browser automation.** This plugin produces prompts; the artifact gets built inside `claude.ai/design`. The operator copies and pastes manually.
- **No artifact code generation.** This plugin is a prompt-builder, not an artifact generator. Claude Design is the generator.
- **No artifact storage or versioning.** Claude Design has no version-tree primitive and this plugin does not invent one. The verbal save-pattern documented in `references/03-iteration-and-session.md` is the closest substitute.
- **English everywhere in shipped content.** Operator override of the marketplace's default Norwegian-dialogue convention. `tests/validate-plugin.sh` assertion (j) emits WARN on Norwegian diacritics in shipped content; review case-by-case.
- **Evidence-grade discipline.** Every per-preset reference file carries an inline `Evidence grade:` label on line 4 with one of three values: `Anthropic-documented + community-validated`, `Community-only`, `Experimental`. `.coverage.md` is the canonical registry.
- **Re-research triggers** documented in `.coverage.md` — fire on Anthropic publishing per-preset guidance for Community-only presets, on new intent presets added to the launch enumeration, on the first verified `frontier-design` practitioner artifact shipping publicly, on Labs → GA URL rename for `claude.ai/design`, on Anthropic's `knowledge-work-plugins/design` adding or removing slash-commands.
## [0.1.0-pre] — 2026-05-15
### Added
- Initial scaffold (README, CLAUDE.md, ROADMAP, TODO, plugin.json placeholder).

88
plugins/claude-design/CLAUDE.md
View file

@ -1,88 +0,0 @@
# claude-design
## Context
This plugin is an expert on **Claude Design** (`claude.ai/design`) — Anthropic's Labs research preview for generating interactive design artifacts from a prompt. It walks the operator through the full lifecycle: idea → intent-preset selection → audience and destination → DESIGN.md anchor → five-layer prompt drafting → copy-paste delivery → iteration coaching → ship-readiness handoff. It does not generate artifact code itself and it does not drive the browser; it produces the prompt that the operator pastes into Claude Design.
## Status
`v0.1.0`. Surface:
- One skill: `claude-design-facilitator` (auto-fire + explicit `/claude-design-facilitator` slash command)
- Five foundation references under `skills/claude-design-facilitator/references/`
- Eight per-preset references under `skills/claude-design-facilitator/references/presets/`
- Five test scripts under `tests/` plus a `verify.sh` roll-up
- A `.coverage.md` preset manifest at the plugin root (canonical input for SC2 and the SC3 Authoritative-claims registry)
- `LICENSE` (MIT), `GOVERNANCE.md` (marketplace fork-and-own blurb), `README.md`, `CHANGELOG.md`
No commands, no agents, no hooks, no MCP servers at v0.1. The single skill is the entire user-facing surface.
## Marketplace context
This plugin lives inside `ktg-plugin-marketplace`. No separate git repository, no separate Forgejo remote. All commits go to the marketplace repository at `https://git.fromaitochitta.com/open/ktg-plugin-marketplace`.
Marketplace conventions inherited from the root `CLAUDE.md`:
- Conventional Commits — `type(scope): description`; scope is `claude-design`
- Hooks in Node.js (`.mjs`), never bash (this plugin ships no hooks at v0.1)
- Zero npm dependencies in hooks and scripts
- Docs-triple updated in the same commit on every feature change: plugin `README.md` + plugin `CLAUDE.md` + root `README.md`
## Architecture (v0.1)
- **`skills/claude-design-facilitator/SKILL.md`** is the auto-fire entry point AND the explicit `/claude-design-facilitator` invocation surface. The skill body documents the eight-phase facilitation flow.
- **`skills/claude-design-facilitator/.triggers.txt`** lists the natural-language phrases the skill auto-fires on. `tests/test-skill-triggers.sh` validates every phrase appears in the SKILL.md description.
- **`skills/claude-design-facilitator/references/`** is the knowledge base. Five foundation references (00–04) plus eight per-preset references under `references/presets/`. Every authoritative claim cites an Anthropic primary source inline.
- **`.coverage.md`** at the plugin root is the SC2 manifest (preset enumeration with evidence-grade labels) and the SC3 Authoritative-claims registry (bullet list of files that must carry Anthropic-domain citations).
- **`tests/`** + **`verify.sh`** enforce the brief Success Criteria: SC1 dogfood-log format, SC2 per-preset coverage, SC3 citation discipline, plus skill description quality and plugin structural integrity.
The skill body never offers to generate artifact code, automate the browser, or store artifact history (per [Non-Goals in README](README.md)). It produces prompts.
## Scope fence
This plugin covers **pre-design and during-design** for `claude.ai/design`: idea → prompt → preview → iterate → ship-readiness.
**Post-design** — critique, accessibility audit, UX copy review, research synthesis, design-system audit, engineering handoff — is out of scope and lives in Anthropic's official `knowledge-work-plugins/design` (`https://claude.com/plugins/design`). This plugin must never duplicate the commands `/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, `/handoff` — with or without a `claude-design:` namespace prefix. `tests/validate-plugin.sh` assertion (h) enforces this scope fence mechanically.
The lifecycle-stage coverage map and the operational handoff between the two plugins are documented in `skills/claude-design-facilitator/references/04-handoff-and-scope.md`.
## Authoring rules
Every contribution to this plugin must respect these rules:
- **Language: English everywhere.** Plugin file content — `README.md`, `CLAUDE.md` (this file), `CHANGELOG.md`, `SKILL.md`, all `references/*.md`, all `tests/*.sh` output messages, every code comment — is English. This is the operator override of the marketplace's default Norwegian-dialogue policy; documented in the v0.1 brief. The `tests/validate-plugin.sh` assertion (j) emits a WARN on Norwegian diacritics in shipped content; review case-by-case (citation slugs occasionally legitimately carry diacritics, but the default is zero hits).
- **No operator-private context in shipped content.** No personal-name or organization-affiliation tokens, no copy-paste from local session-state and handoff files. `tests/validate-plugin.sh` assertion (i) enforces this with a recursive grep on the specific patterns it bans; the grep excludes the local files themselves.
- **Evidence-grade label discipline.** Every per-preset reference file carries an inline `Evidence grade:` label on line 4. The three grades are `Anthropic-documented + community-validated`, `Community-only`, and `Experimental`. `.coverage.md` is the canonical registry. SC2 and SC3 read from `.coverage.md` directly — keep it in sync.
- **URL canonicalisation.** All `support.claude.com` references use the form `https://support.claude.com/en/articles/<numeric-id>-<slug>`. Numeric IDs are stable across slug rewrites; slug-only URLs are not. `https://anthropic.com/news/...` and `https://claude.com/blog/...` follow whatever slug Anthropic publishes.
- **No NIH of Anthropic surfaces.** The plugin recommends Anthropic's `knowledge-work-plugins/design` as the downstream tool; it does not duplicate that plugin's functionality.
## Workflow
The Voyage pipeline produces v0.1 and every subsequent feature change:
1. **Brief** closes scope and scope boundaries
2. **Research** gathers external sources — Anthropic primary material (news posts, support articles, blog posts, open-source skills, tutorials, plugins), plus community practitioners with attribution
3. **Plan** specifies file-by-file what gets built
4. **Execute** delivers the code and content
5. **Review** is the release gate (`/trekreview`)
Voyage policy: Opus across all sub-agents and orchestrator phases (per `feedback_voyage_opus_always`).
For incremental content updates that do not warrant a full Voyage iteration (e.g., refreshing a single per-preset reference when Anthropic publishes new guidance), the docs-triple rule still applies: plugin `README.md` + plugin `CLAUDE.md` (this file) + root `README.md` updated in the same commit as the content change.
## Communication patterns
### Linking to local files
When pointing to local files in responses, always use markdown link syntax with a descriptive name:
- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks `<file://...>`.
- Always use absolute paths. Never `~/` or relative paths.
- For multiple files, render as a bullet list of named markdown links.
Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner.
Example:
- [Brief](file:///Users/ktg/.../brief.html)
- [Research summary](file:///Users/ktg/.../research/summary.md)

118
plugins/claude-design/GOVERNANCE.md
View file

@ -1,118 +0,0 @@
# Governance
How this marketplace is maintained, what you can expect from upstream, and how it's meant to be used.
## TL;DR
- Solo-maintained, AI-assisted development, MIT licensed.
- **Fork-and-own is the default model.** Upstream is a starting point, not a vendor.
- Issues welcome as signals. Pull requests are not accepted — see [Why no PRs](#pull-requests--no).
- No SLA. Best-effort bug fixes and security advisories. Breaking changes happen and are noted in each plugin's CHANGELOG.
---
## Can I trust this?
Be honest with yourself about what you're adopting:
- **One maintainer.** If I get hit by a bus, the bus wins. The repos stay up under MIT, but no one owes you a fix.
- **AI-generated code with human review.** Every plugin is built through dialog-driven development with Claude Code. I read, test, and judge the output before it ships, but I'm not auditing every line the way a security firm would. Treat it accordingly.
- **No commercial interests.** I'm not selling a SaaS, not steering you toward a paid tier, not collecting telemetry. The plugins run locally in your Claude Code installation.
- **MIT licensed.** Fork it, modify it, ship it under your own name.
If you work somewhere that needs vendor accountability, support contracts, or signed assurances — **this isn't that.** Use it as a reference implementation, fork it into your own organization, and own the result.
---
## How this is meant to be used
### Fork-and-own
The intended workflow:
1. **Fork** the marketplace (or a single plugin) into your own organization or namespace.
2. **Tailor** it to your context — terminology, integrations, whatever doesn't fit out of the box.
3. **Maintain it yourself.** Treat your fork as the canonical version for your team.
4. **Watch upstream selectively.** Cherry-pick changes that help, ignore changes that don't. There's no obligation to stay in sync.
For `claude-design` specifically, the most likely fork is a content adaptation — different intent-preset coverage (e.g., dropping `frontier-design` if your team never uses it), an organization-specific DESIGN.md template, a different evidence-grade discipline, or per-preset prompt patterns tuned to your team's design system. The plugin is a content surface plus a single skill. Forking it is straightforward.
### What to change first when you fork
- **Identity** — rename the plugin, replace authorship, update README.
- **Reference content** — the `references/` tree reflects what Anthropic published and the community converged on as of 2026-05-17. Adjust to your team's house style and design system.
- **Frontmatter** — `name` and `description` show up in `/config`. Pick names that won't collide with other forks installed on the same machine.
### Staying current with upstream
If you want to pull in upstream changes later:
- **Cherry-pick, don't merge.** Each plugin moves independently.
- **Read the CHANGELOG first.**
- **Keep your customizations distinct.** A renamed skill (`my-org-design-facilitator`) merges more cleanly than edits to `claude-design-facilitator`.
---
## What upstream provides
| | What I do | What I don't |
|---|---|---|
| **Bug fixes** | Best-effort when I notice or get a clear report | No SLA, no triage commitment |
| **Security issues** | Investigate within reasonable time, document in CHANGELOG | No CVE process, no embargo coordination |
| **New features** | When they fit my own usage | Not on request |
| **Breaking changes** | Documented in CHANGELOG | They happen — version pin if you need stability |
| **Compatibility** | Tracked against current Claude Code releases | No long-term support branches |
If any of this is a dealbreaker — fork now, version-pin, and stop reading upstream.
---
## How to contribute
### Issues — yes, please
Issues are the most valuable thing you can send me:
- **Bug reports** with reproduction steps. Even a screenshot helps.
- **Use-case feedback.** "I tried to use this in my organization and X didn't fit" is genuinely useful, even if I can't fix it for you.
- **Content suggestions.** If a reference file in `claude-design` produces guidance that doesn't match what you observe in `claude.ai/design` today, tell me what you saw. Concrete examples beat abstract complaints.
### Pull requests — no
This is deliberate, not laziness:
- **Solo review is a bottleneck.** Honest PR review takes me longer than rewriting from scratch. The math doesn't work.
- **Forks are where the value is.** The fork-and-own model means upstream consolidation isn't the point. Your organization's adaptations belong in your fork, not mine.
- **AI-generated code complicates provenance.** Every line here is produced through dialog with Claude Code, with me as the judge. Mixing in PRs from contributors with different processes and licensing assumptions creates a mess I'd rather not untangle.
If you've built something useful on top of a fork, **publish it under your own name and link back.** I'll happily list notable forks here once they exist.
### Notable forks
*(To be populated as forks emerge. If you've forked this plugin for production use, open an issue and I'll add a link.)*
---
## Relationship between plugins
These plugins are **independent**. Install one without the others, fork one without the others. They share conventions (slash command naming, hook patterns, AI-generated disclosure, and the shared `human-friendly-style` output style) but no runtime dependencies.
`claude-design` is a content surface with a single skill — it works without any other plugin installed. It recommends Anthropic's official `knowledge-work-plugins/design` as the downstream tool for post-design critique, accessibility audit, and engineering handoff, but does not depend on it being present.
The marketplace is a **catalog**, not a suite. Don't fork the whole repo unless you actually want to maintain everything.
---
## Versioning and stability
- **Semantic versioning per plugin.** Each plugin has its own `CHANGELOG.md` and version number.
- **Breaking changes happen.** I bump the major version when they do, but I don't run an LTS branch.
- **Pin your version.** If stability matters more than features, install a specific version and stay there until you choose to upgrade.
For `claude-design` specifically: changes to skill trigger behavior or per-preset reference content schema are minor or major bumps. Pure documentation or per-preset content refresh from Anthropic source updates are patch. The skill surface itself is meant to be stable across patch releases.
---
## License
MIT for all plugins in this marketplace. See [LICENSE](LICENSE) in this plugin and each other plugin's `LICENSE` file.

21
plugins/claude-design/LICENSE
View file

@ -1,21 +0,0 @@
MIT License
Copyright (c) 2026 Kjell Tore Guttormsen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

298
plugins/claude-design/README.md
View file

@ -1,298 +0,0 @@
# Claude Design Facilitator
> End-to-end facilitator for prompting Claude Design (`claude.ai/design`). Walks the operator from raw idea through intent-preset selection, audience and destination clarification, DESIGN.md anchor, five-layer prompt drafting, copy-paste delivery, iteration coaching, and ship-readiness handoff. Cites Anthropic primary sources inline. Recommends Anthropic's official `knowledge-work-plugins/design` as the downstream post-design tool.
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
*AI-generated: all content produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
![Version](https://img.shields.io/badge/version-0.1.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Skill](https://img.shields.io/badge/skills-1-green)
![References](https://img.shields.io/badge/references-13-green)
![Hooks](https://img.shields.io/badge/hooks-0-lightgrey)
![Commands](https://img.shields.io/badge/commands-0-lightgrey)
![License](https://img.shields.io/badge/license-MIT-lightgrey)
A Claude Code plugin that ships one skill (`claude-design-facilitator`) plus a reference tree for prompting Anthropic's `claude.ai/design` workspace. The skill auto-fires on natural-language triggers, walks the operator through an eight-phase facilitation flow, and produces a copy-paste-ready prompt grounded in Anthropic's verbatim Goal / Layout / Content / Audience framework and the four published per-preset prompt patterns. Output is the prompt — the artifact gets built in Claude Design.
---
## Why this exists
Claude Design has a strong gravitational pull toward convergent middle-ground output. A one-line prompt like *"make me a slide deck for Q1 results"* reliably produces what Anthropic's own cookbook for [prompting frontend aesthetics](https://platform.claude.com/cookbook/coding-prompting-for-frontend-aesthetics) names as the failure mode: Inter or Roboto typography, white-to-purple gradients, evenly-spaced cards, cramped layouts that read as AI-generated. The convergence is not random — it is what the model defaults to when prompts are underspecified.
The fix is in the prompt itself, not in the artifact. Anthropic publishes a five-layer prompt scaffold across three primary sources — the Goal / Layout / Content / Audience framework in the [Claude Design launch post](https://anthropic.com/news/claude-design-anthropic-labs) and [Get started article](https://support.claude.com/en/articles/14604416-get-started-with-claude-design), the DESIGN.md anchor in the [design system article](https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design), and the AI-slop avoid-list plus cultural-reference anchoring in the [aesthetics cookbook](https://platform.claude.com/cookbook/coding-prompting-for-frontend-aesthetics). Assembling a prompt that actually uses all five layers, with the right per-preset pattern, in the right order, takes deliberate scaffolding most operators do not do unprompted.
This plugin does the scaffolding interactively. The `claude-design-facilitator` skill walks the operator through eight phases, surfaces the questions that produce a workable Goal / Layout / Content / Audience answer, anchors on DESIGN.md if one exists or extracts one if not, composes the five layers in the right order, and outputs a copy-paste prompt the operator pastes into `claude.ai/design`. The artifact gets built in Claude Design; this plugin produces the prompt.
The output is honest about what it is. Every authoritative claim cites an Anthropic primary source inline. Community patterns are labelled and attributed. The `frontier-design` preset is flagged Experimental rather than dressed up as canonical. The plugin recommends Anthropic's official [`knowledge-work-plugins/design`](https://claude.com/plugins/design) for everything that happens after the artifact is generated — there is zero command overlap by design.
---
## Scope and complementarity
This plugin covers the **pre-design and during-design lifecycle** for `claude.ai/design`: idea → intent-preset selection → prompt engineering → copy-paste delivery → iteration coaching → ship-readiness check.
For **post-design** work — critique, accessibility audit, UX copy review, research synthesis, design-system audit, engineering handoff guidance — install Anthropic's official plugin:
```
claude plugins add knowledge-work-plugins/design
```
Anthropic's plugin operates on existing artifacts (Figma URLs, screenshots, copy snippets) and ships six slash-commands: `/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, `/handoff`. There is zero command overlap with this plugin and complementary lifecycle coverage — the two plugins are designed to be installed together. See [skills/claude-design-facilitator/references/04-handoff-and-scope.md](skills/claude-design-facilitator/references/04-handoff-and-scope.md) for the full coverage map.
---
## What this plugin is NOT
By design, this plugin does not:
- **Drive the browser.** No automation of `claude.ai/design` itself; you copy and paste the prompts the skill produces.
- **Generate the artifact code.** Claude Design is the artifact generator. This plugin produces prompts that go into Claude Design.
- **Store artifact history or version artifacts.** Claude Design has no version-tree primitive and this plugin does not invent one.
- **Cover adjacent Anthropic surfaces.** Classic Artifacts at `claude.ai`, Live Artifacts in Claude Cowork, custom visuals embedded in a chat reply are out of scope — see [skills/claude-design-facilitator/references/00-what-claude-design-is-and-isnt.md](skills/claude-design-facilitator/references/00-what-claude-design-is-and-isnt.md) for the disambiguation reference.
- **Duplicate Anthropic's `knowledge-work-plugins/design` plugin.** No `/critique`, no `/accessibility`, no `/ux-copy`, no `/research-synthesis`, no `/design-system`, no `/handoff`. The post-design lane belongs to Anthropic's plugin.
`tests/validate-plugin.sh` enforces the forbidden-command-name list mechanically.
---
## Installation
Add the marketplace once, then install the plugin:
```bash
claude plugins marketplace add ktg-plugin-marketplace https://git.fromaitochitta.com/open/ktg-plugin-marketplace
```
In Claude Code:
```
/plugin install claude-design@ktg-plugin-marketplace
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"claude-design@ktg-plugin-marketplace": true
}
}
```
The skill auto-discovers; no further configuration needed.
---
## What you can do with it
The skill `claude-design-facilitator` walks the operator through eight phases. The phases are scoping + grounding (1–4), drafting + delivery (5–6), and iteration + ship-readiness (7–8).
| Phase | What happens |
|-------|--------------|
| **1. Disambiguate the surface** | Confirm `claude.ai/design` is the intended surface, not classic Artifacts, Live Artifacts, custom chat visuals, or `knowledge-work-plugins/design`. Read [references/00](skills/claude-design-facilitator/references/00-what-claude-design-is-and-isnt.md) when signals are mixed. |
| **2. Name the intent preset** | Pick one of eight Claude Design presets: `designs`, `prototypes`, `slides`, `one-pagers`, `wireframes-mockups`, `pitch-decks`, `marketing-collateral`, `frontier-design`. The per-preset reference file shapes the prompt pattern. Evidence-grade labels are surfaced. |
| **3. Audience and destination** | Capture audience (internal team / external stakeholder / investor / customer) and destination (PDF / PPTX / HTML / Canva / Code-handoff / share-link). Flag PPTX-export traps for `pitch-decks` early. |
| **4. Anchor on DESIGN.md** | Read [references/02](skills/claude-design-facilitator/references/02-design-md.md). If the operator has no DESIGN.md, point at the copy-paste brand-to-DESIGN.md extractor prompt. |
| **5. Draft the prompt** | Compose layers 1–5 from [references/01](skills/claude-design-facilitator/references/01-prompt-fundamentals.md): Anthropic's verbatim Goal / Layout / Content / Audience framework + start-simple-layer-complexity + concrete-alternative-spec + propose-options-before-building + AI-slop negative constraints + four design dimensions + four grading criteria + the per-preset pattern. |
| **6. Deliver** | Output a single copy-paste-ready fenced markdown code block. Add a one-line caption and three to five expected follow-up turns. |
| **7. Iteration coaching** | Read [references/03](skills/claude-design-facilitator/references/03-iteration-and-session.md). Coach which surface to use next — Tweak panel (zero-token, surgical), inline comments (component-scoped), or chat (full regen). Session-break heuristics + recovery prompt library when iteration gets stuck. |
| **8. Ship-readiness** | Run the export validation checklist. If shipping to engineering, confirm the Design → Code handoff bundle is complete. Recommend installing `knowledge-work-plugins/design` for downstream critique / accessibility / handoff. |
The skill auto-fires on natural-language triggers like *"I want to build a dashboard in Claude Design"*, *"help me prompt claude.ai/design"*, *"iterate on my Claude Design artifact"*. The full trigger list is in [skills/claude-design-facilitator/.triggers.txt](skills/claude-design-facilitator/.triggers.txt) and `tests/test-skill-triggers.sh` validates each phrase appears in the skill description.
Explicit invocation works too: the skill registers as the slash command `/claude-design-facilitator` for when the operator wants to start a clean facilitation session.
---
## Workflow example: from idea to prompt
A realistic session against the `slides` preset — Q1 results deck for an internal engineering all-hands.
**Operator:** *"I want to build a Q1 results slide deck for the engineering team in Claude Design."*
The skill auto-fires (the phrase matches `.triggers.txt`). It walks the eight phases:
**Phase 1 — Disambiguate the surface.** The skill confirms `claude.ai/design` is the intended surface, not classic Artifacts or Live Artifacts. The operator confirms.
**Phase 2 — Name the intent preset.** Slide deck → `slides` preset. The skill notes this is one of three Anthropic-documented presets (evidence-grade label surfaced from `.coverage.md`). It opens [`references/presets/slides.md`](skills/claude-design-facilitator/references/presets/slides.md) and surfaces the five canonical Anthropic patterns (Q1 results, executive roadmap, customer-prep briefing, partner proposal, all-hands announcement). The operator picks pattern 1.
**Phase 3 — Audience and destination.** Internal engineering team; deck stays in HTML preview during the meeting, optional PPTX export to share with adjacent leads afterward. The skill flags the PPTX-export trap from [`references/presets/slides.md`](skills/claude-design-facilitator/references/presets/slides.md) section (e): fonts substitute, master slides drop, charts may flatten to images. If a brand-compliant PPTX template exists, upload it to Claude Design as a project asset before prompting — Claude reads the slide master, layouts, fonts, and colour scheme and respects them ([PowerPoint-mode article](https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint)).
**Phase 4 — Anchor on DESIGN.md.** The operator has no DESIGN.md yet. The skill points at the brand-to-DESIGN.md extractor prompt in [`references/02-design-md.md`](skills/claude-design-facilitator/references/02-design-md.md): paste a brand-guidelines URL or PDF into Claude.ai, get back a DESIGN.md filling the nine canonical sections (typography, colour, spacing, layout primitives, motion, voice, imagery, density, accessibility). The operator runs the extractor against the company's brand site, gets a DESIGN.md, drops it into the Claude Design project assets.
**Phase 5 — Draft the prompt.** The skill composes the five layers from [`references/01-prompt-fundamentals.md`](skills/claude-design-facilitator/references/01-prompt-fundamentals.md): Goal / Layout / Content / Audience (Layer 1) → start-simple-layer-complexity (Layer 2) → concrete-alternative-spec (Layer 3) → AI-slop negative constraints (Layer 4) → per-preset pattern from `presets/slides.md` (Layer 5). The skill produces a single copy-paste fenced block. The operator inspects it, optionally edits the Goal sentence, then proceeds.
**Phase 6 — Deliver.** The skill outputs the prompt block. The structure of a realistic delivery for this scenario looks like:
```
**Goal:** Communicate Q1 engineering results to the all-hands —
where we started, what changed, what we shipped, what we learned,
what's next for Q2. The deck should land as confident but honest:
real numbers, named risks, no victory-lap framing. Audience is
~80 engineers across three teams. Density should be high enough
to skim later, low enough to follow live.
**Layout:** 10–12 slides, slide-by-slide:
1. Title + Q1 in one sentence
2. The three things we shipped (one per row, screenshot + metric)
3. The two things that slipped (named honestly, with the why)
4. Hiring update (count + retention)
5. Reliability (incident count, MTTR trend)
6. Customer signal (NPS + 2 verbatim quotes)
7. Engineering health (PR throughput, review latency)
8. The big bet for Q2 (one slide, named)
9. Risks for Q2 (3 bullets, ranked)
10. Asks from the all-hands (1–3 specific asks)
11. Q&A placeholder
**Content:** Use the metrics in DESIGN.md's `tone` section — direct,
specific, no marketing voice. Numbers are placeholder; I'll edit
before the meeting.
**Audience:** Internal engineering all-hands, 80 people, ICs through
EM/Director level. They want to know: did we ship what we said, what
broke, what's next, can I help.
**Avoid:** Inter or Roboto, white-to-purple gradients, evenly-spaced
generic card layouts, "exciting Q1!" framing, congratulatory tone,
stock-photo gradients, generic icon library defaults.
**Anchor:** Match the DESIGN.md uploaded as a project asset. If our
brand voice reads as understated technical, push the deck that way —
not the convergent SaaS-marketing deck aesthetic.
**Reference:** Treat this as the Q1 results pattern from
https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks
(pattern 1), with the Layout above overriding the tutorial's slide count.
```
That block is what gets pasted into `claude.ai/design`. The skill also surfaces three to five expected follow-up turns (e.g., *"the headline slide is too marketing, push it more technical"*, *"slide 5 reliability — show the MTTR trend as a sparkline, not a bar chart"*) so the operator knows what iteration looks like before starting.
**Phase 7 — Iteration coaching.** Once Claude Design produces the first version, the skill points the operator at the Tweak → Comment → Chat cascade in [`references/03-iteration-and-session.md`](skills/claude-design-facilitator/references/03-iteration-and-session.md): Tweak panel for surgical zero-token edits (spacing, font size, colour), inline comments for component-scoped changes (rewrite slide 5), full chat regeneration as a last resort. Plus the session-break heuristic (after 4 substantive screens, start a fresh session with a verbal save-pattern carrying state forward) and the recovery prompt library when iteration gets stuck.
**Phase 8 — Ship-readiness.** Before the all-hands, the skill runs the export validation checklist for the chosen destination (HTML preview → keep in Claude Design; PPTX → check fonts and master, charts may flatten). If the deck is being handed off to engineering for any reason, it recommends installing [`knowledge-work-plugins/design`](https://claude.com/plugins/design) for `/critique`, `/accessibility`, and `/handoff` — the post-design lane.
The full output of the session is a single fenced markdown block (Phase 6) plus a short follow-up-turns list and an iteration-coaching pointer. That is the entire user-facing deliverable.
---
## Skill surface
| Skill | Triggers | Output |
|-------|----------|--------|
| `claude-design-facilitator` | 12 natural-language phrases (full list in `.triggers.txt`); also explicit `/claude-design-facilitator` slash command | A copy-paste-ready Claude Design prompt block composed from the five-layer stack and the per-preset pattern, with follow-up-turn expectations |
No commands, no agents, no hooks, no MCP servers at v0.1. The single skill is the entire user-facing surface.
---
## Reference content map
The plugin ships 13 reference files in `skills/claude-design-facilitator/references/`:
**Foundation references (5):**
- [`00-what-claude-design-is-and-isnt.md`](skills/claude-design-facilitator/references/00-what-claude-design-is-and-isnt.md) — Surface disambiguation against Artifacts, Live Artifacts, custom chat visuals, and Anthropic's `knowledge-work-plugins/design`.
- [`01-prompt-fundamentals.md`](skills/claude-design-facilitator/references/01-prompt-fundamentals.md) — The five-layer prompt stack: GLCA framework + start-simple-layer-complexity + concrete-alternative-spec + propose-options + AI-slop negative constraints + four design dimensions + four grading criteria. Anchored on four Anthropic primary sources.
- [`02-design-md.md`](skills/claude-design-facilitator/references/02-design-md.md) — DESIGN.md 9-section canonical structure + brand-to-DESIGN.md extractor prompt + failure modes.
- [`03-iteration-and-session.md`](skills/claude-design-facilitator/references/03-iteration-and-session.md) — Tweak / Comment / Chat cascade, session economics, 4-screen inflection, recovery prompt library (break-default-aesthetic, fix-the-system, edit-previous-message, 3-failed-comment escalation, model downshift, verbal save-pattern).
- [`04-handoff-and-scope.md`](skills/claude-design-facilitator/references/04-handoff-and-scope.md) — Design → Code one-way handoff, bundle contents, lifecycle-stage coverage map vs Anthropic's `knowledge-work-plugins/design`, downstream tool recommendation.
**Per-preset references (8):**
- [`presets/designs.md`](skills/claude-design-facilitator/references/presets/designs.md) — Anthropic-documented + community-validated
- [`presets/prototypes.md`](skills/claude-design-facilitator/references/presets/prototypes.md) — Anthropic-documented + community-validated
- [`presets/slides.md`](skills/claude-design-facilitator/references/presets/slides.md) — Anthropic-documented + community-validated
- [`presets/one-pagers.md`](skills/claude-design-facilitator/references/presets/one-pagers.md) — Community-only
- [`presets/wireframes-mockups.md`](skills/claude-design-facilitator/references/presets/wireframes-mockups.md) — Community-only
- [`presets/pitch-decks.md`](skills/claude-design-facilitator/references/presets/pitch-decks.md) — Community-only (with explicit PPTX-export caveat)
- [`presets/marketing-collateral.md`](skills/claude-design-facilitator/references/presets/marketing-collateral.md) — Community-only
- [`presets/frontier-design.md`](skills/claude-design-facilitator/references/presets/frontier-design.md) — Experimental — no validated practitioner pattern as of 2026-05-16
---
## Per-preset coverage
The canonical coverage manifest is [`.coverage.md`](.coverage.md). Below mirrors that file.
| Preset | Evidence grade | Anthropic anchor |
|--------|----------------|------------------|
| designs | Anthropic-documented + community-validated | [launch post](https://anthropic.com/news/claude-design-anthropic-labs) |
| prototypes | Anthropic-documented + community-validated | [prototypes tutorial](https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux) |
| slides | Anthropic-documented + community-validated | [slides tutorial](https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks) |
| one-pagers | Community-only | [launch post](https://anthropic.com/news/claude-design-anthropic-labs) |
| wireframes-mockups | Community-only | [launch post](https://anthropic.com/news/claude-design-anthropic-labs) |
| pitch-decks | Community-only (with PPTX-export caveat) | [launch post](https://anthropic.com/news/claude-design-anthropic-labs) |
| marketing-collateral | Community-only | [launch post](https://anthropic.com/news/claude-design-anthropic-labs) |
| frontier-design | Experimental — no validated practitioner pattern | [launch post](https://anthropic.com/news/claude-design-anthropic-labs) |
When Anthropic publishes per-preset guidance for a Community-only or Experimental preset, [`.coverage.md`](.coverage.md) and the affected preset file refresh — re-research triggers are documented inline.
---
## Verification
```bash
bash plugins/claude-design/verify.sh
```
Runs five test scripts under `tests/` in dependency order:
| Script | Verifies |
|--------|----------|
| `validate-plugin.sh` | plugin.json + SKILL.md frontmatter + LICENSE + GOVERNANCE.md + README.md + CLAUDE.md + .coverage.md presence; forbidden-command-name scope-fence check; operator-private-context grep; Norwegian-leakage advisory |
| `test-skill-triggers.sh` | SKILL.md description >=400 chars; every phrase in `.triggers.txt` appears in SKILL.md |
| `test-sc2-artifact-coverage.sh` | Each preset in `.coverage.md` has >=1 file hit in plugin content |
| `test-sc3-citations.sh` | No unsourced-attribution placeholders (citation-stub markers, verification-flag markers, vague second-hand phrasing); each Authoritative-claims file has >=1 Anthropic-domain URL. The script enforces the exact patterns it bans — see the script source for the regex. |
| `test-sc1-dogfood-log.sh` | Format-check the operator dogfood log in `REMEMBER.md` (gitignored) — 5 fields well-formed |
Flags:
- `--strict` — pass-through to `test-sc1-dogfood-log.sh`. Without `--strict`, missing dogfood block is advisory. With `--strict`, it is the release gate.
- `--quick` — skip `test-skill-triggers.sh` for fast incremental runs.
Exit codes: `0` = all pass; non-zero = at least one sub-test failed.
---
## Compatibility
| Requirement | Version |
|-------------|---------|
| Claude Code | Recent versions with plugin support |
| Anthropic surface | `claude.ai/design` (Labs research preview launched 2026-04-17) |
| Platform | macOS, Linux, Windows |
| Network | None for the skill itself; the artifact-generation lives in `claude.ai/design` |
| Dependencies | None — no npm packages, no Python, no external tools. Bash 3.2 compatible for test scripts. |
---
## Re-research triggers
The reference tree carries Anthropic citations that may decay. Re-research is triggered by:
- Anthropic publishing per-preset guidance for a `Community-only` or `Experimental` preset
- Anthropic announcing material changes to the Goal / Layout / Content / Audience framework, the AI-slop avoid-list, or the design grading criteria
- Anthropic adding or removing an intent preset from the launch enumeration
- A first verified `frontier-design` practitioner artifact shipping publicly
- Anthropic's `knowledge-work-plugins/design` plugin adding or removing slash-commands (scope-fence implications)
- Labs → GA URL rename for `claude.ai/design`
When a trigger fires, run `bash verify.sh --strict` after the update to confirm SC2 and SC3 still pass.
---
## Recent versions
**v0.1.0 — 2026-05-17.** Initial public release. Single skill (`claude-design-facilitator`) with eight-phase facilitation flow, 12 natural-language trigger phrases, 13 reference files (5 foundation + 8 per-preset with evidence-grade labels), `.coverage.md` preset manifest plus Authoritative-claims registry, five verification scripts under `tests/` enforcing structural integrity / scope fence / skill description quality / per-preset coverage / Anthropic-domain citation discipline / operator dogfood log format, top-level `verify.sh` roll-up with `--strict` and `--quick` flags, MIT license, GOVERNANCE.md fork-and-own model.
Full release history: [`CHANGELOG.md`](CHANGELOG.md). The plugin follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The path from v0.1 to v1.0 is dogfood-driven — see the plugin's `REMEMBER.md` for the v1.0 readiness criteria (multi-preset breadth, auto-fire validation in real natural-language requests, two consecutive dogfood sessions with zero critical patches).
---
## License
[MIT](LICENSE). Fork it, modify it, ship your own version under your own name.

12
plugins/claude-design/skills/claude-design-facilitator/.triggers.txt
View file

@ -1,12 +0,0 @@
I want to build a dashboard in Claude Design
help me prompt claude.ai/design
make a slide deck in claude.ai/design
iterate on my Claude Design artifact
what should I prompt Claude Design with
build a one-pager in Claude Design
design a prototype in claude.ai/design
refine my Claude Design output
create a pitch deck in Claude Design
use Claude Design
draft a Claude Design prompt
make wireframes in claude.ai/design

176
plugins/claude-design/skills/claude-design-facilitator/SKILL.md
View file

@ -1,176 +0,0 @@
---
name: claude-design-facilitator
argument-hint: "[intent-preset]"
description: |
End-to-end facilitator for prompting Claude Design (claude.ai/design — Anthropic Labs research preview launched 2026-04-17, Opus 4.7 pinned). Walks the operator from raw idea through intent-preset selection, audience and destination clarification, DESIGN.md anchor, prompt drafting using Anthropic's verbatim Goal / Layout / Content / Audience framework plus the five-layer prompt stack, copy-paste delivery, iteration coaching across the Tweak / Comment / Chat cascade, and ship-readiness handoff to Anthropic's official knowledge-work-plugins/design plugin for critique, accessibility audit, and engineering handoff. Cites Anthropic primary sources inline; refuses to generate the artifact code itself or drive the browser. Use for any work that ends with a Claude Design artifact.
Triggers on:
- "I want to build a dashboard in Claude Design"
- "help me prompt claude.ai/design"
- "make a slide deck in claude.ai/design"
- "iterate on my Claude Design artifact"
- "what should I prompt Claude Design with"
- "build a one-pager in Claude Design"
- "design a prototype in claude.ai/design"
- "refine my Claude Design output"
- "create a pitch deck in Claude Design"
- "use Claude Design"
- "draft a Claude Design prompt"
- "make wireframes in claude.ai/design"
---
# claude-design-facilitator
You are a facilitator for prompting Claude Design (`claude.ai/design`). You walk the operator from raw idea to a copy-paste-ready prompt, through iteration, to ship-readiness. You do **not** generate artifact code yourself and you do **not** drive the browser. Claude Design is where the artifact gets built; you exist to make the operator's interaction with that surface land on the first try.
You follow the phases below in order. Phases 1 through 4 are scoping and grounding; do not draft a prompt before they are done. If the operator pushes for a prompt straight away, briefly explain that a five-second alignment pass produces a one-shot prompt instead of a four-round iteration spiral, then ask the Phase 2 intent question.
All output is English. All authoritative claims about Claude Design behaviour cite Anthropic primary sources — `anthropic.com/news`, `support.claude.com`, `claude.com/blog`, `claude.com/resources/tutorials`, `claude.com/plugins`, `platform.claude.com`, `github.com/anthropics`. Community patterns are labelled as such with the source link. The reference files under `references/` carry the canonical content; this file is the flow.
---
## Phase 1 — Disambiguate the surface
Confirm the operator wants `claude.ai/design` specifically, not one of the four surfaces it is most commonly confused with: classic Artifacts at `claude.ai`, Live Artifacts in Claude Cowork, custom visuals embedded in a chat reply, or Anthropic's `knowledge-work-plugins/design` plugin (which audits already-built artifacts and does not generate them).
If the operator is clear, move on. If signals are mixed — they mention "Artifacts" or "Cowork", they describe a feature that does not exist in Claude Design (no `/rewind`, no version history, no branching), or they expect round-trip handoff back from Claude Code — read `references/00-what-claude-design-is-and-isnt.md` and walk through the relevant anti-conflation block.
---
## Phase 2 — Name the intent preset
Claude Design exposes eight intent presets. The operator picks one before drafting begins, because the prompt pattern differs per preset and the per-preset reference files are the place that pattern lives.
The eight presets, in the order they appear in Anthropic's launch enumeration (`anthropic.com/news/claude-design-anthropic-labs`, 2026-04-17):
- **designs** — generic dashboards, components, layouts, design explorations
- **prototypes** — interactive product flows for usability testing and demos
- **slides** — presentation decks, internal or external
- **one-pagers** — single-page artifacts (memos, summaries, leave-behinds)
- **wireframes-mockups** — low-fi or high-fi layout structure, pre-visual-design
- **pitch-decks** — investor or external pitch decks (note: PPTX export trap — see preset file)
- **marketing-collateral** — landing pages, social variants, visual assets
- **frontier-design** — Anthropic's "code-powered prototypes with voice, video, shaders, 3D" preset (labelled experimental in this plugin — no validated practitioner pattern as of 2026-05-16)
If the operator is uncertain which preset fits, read `.coverage.md` and the matching one-line summaries; offer the two or three that match the situation. The evidence-grade label on each preset reference file is load-bearing — surface it: `Anthropic-documented + community-validated` (designs / prototypes / slides), `Community-only` (one-pagers / wireframes-mockups / pitch-decks / marketing-collateral), or `Experimental` (frontier-design).
---
## Phase 3 — Audience and destination
Establish the audience and the destination *before* drafting the prompt. This is `@claudedesign` Anthropic-affiliated guidance: the destination format constrains the prompt because Claude Design's export options have asymmetric fidelity.
Ask:
- **Audience:** who reads or uses this artifact? Internal team, external stakeholder, investor, customer prospect, partner, user-testing participant?
- **Destination:** where does it end up? PDF (lossless for static layouts, lossy for interactive elements), PPTX (Claude reads slide master / layouts / fonts / color scheme, but text flattens to images on complex compositions — see `references/03-iteration-and-session.md` PPTX trap section), HTML standalone, Canva import, Claude Code handoff for engineering build, or share-link?
If the destination is PPTX and the preset is `pitch-decks`, flag the export trap explicitly (`moda.app/blog/claude-design-for-pitch-decks` documents the case where PPTX flattens richly-styled text to images). If the destination is Claude Code handoff, set expectation that the bundle Claude Design produces is one-way (no return path to Claude Design — see `references/04-handoff-and-scope.md`).
---
## Phase 4 — Anchor on DESIGN.md
A DESIGN.md file is the operator's leverage against Claude Design's defaults. It anchors design-system identity (colors, typography, motion, layout, do's-and-don'ts) so the model does not fall back to its convergent middle-ground aesthetic.
Read `references/02-design-md.md`. The reference file documents the community-converged 9-section canonical structure and a copy-paste extractor prompt that converts a brand URL or screenshot into a DESIGN.md.
If the operator already has a DESIGN.md, confirm it is uploaded to the Claude Design project and that the agent prompt guide section names it. If they do not have one, point at the extractor prompt — it is the highest-leverage single piece of content in this plugin.
**Evidence grade context for the operator:** Anthropic publishes the concept of DESIGN.md (`support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design`) but not the 9-section structure. The 9-section template comes from community practitioners (`github.com/rohitg00/awesome-claude-design`, `github.com/VoltAgent/awesome-claude-design`).
---
## Phase 5 — Draft the prompt using the five-layer stack
Now draft. Open `references/01-prompt-fundamentals.md` and `references/presets/<preset>.md` for the named preset. Compose the prompt from these layers, in order:
1. **Layer 1 — Goal / Layout / Content / Audience (GLCA)** — Anthropic's verbatim framework. Source: `support.claude.com/en/articles/14604416-get-started-with-claude-design`. Every prompt to Claude Design starts here.
2. **Layer 1.5 — Start simple, layer in complexity** — Anthropic's verbatim incremental-prompting advice (same source). Do not ship a 600-word first prompt; ship a 120-word first prompt and add detail in turn two.
3. **Layer 2a — Concrete-alternative-spec house-style control** — Anthropic's verbatim guidance from `platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`. Includes the AEFRM example with explicit hex palette and motion timing.
4. **Layer 2b — Propose-options-before-building** — Anthropic's verbatim prompt template asking Claude Design to surface four distinct visual directions before committing.
5. **Layer 3 — Negative constraints (the AI-slop avoid-list)** — verbatim banned items from `claude.com/blog/improving-frontend-design-through-skills` and `github.com/anthropics/skills/skills/frontend-design/SKILL.md`. Inter, Roboto, Arial, Space Grotesk; purple gradients on white; solid-color backgrounds; cookie-cutter framing; convergent middle-ground palettes; scattered micro-interactions.
6. **Layer 4 — Four design dimensions** — verbatim typography / color / motion / backgrounds guidance from `frontend-design/SKILL.md`.
7. **Layer 5 — Four design grading criteria** — Anthropic's verbatim quality criteria from `anthropic.com/engineering/harness-design-long-running-apps` (design quality, originality, craft, functionality) plus the emphasis-weighting recommendation.
On top of the five layers, layer the per-preset pattern from `references/presets/<preset>.md`. For `designs`, `prototypes`, and `slides`, this is Anthropic-published prompt material. For the other four `Community-only` presets, it is community-converged pattern with attribution. For `frontier-design`, it is honest-experimental and labelled as such.
Resist the urge to over-spec. Anthropic's own guidance is start simple, layer in complexity. Draft the layer-1+layer-2a+layer-3 composition first. Save layers 4 and 5 for the refinement turn.
---
## Phase 6 — Deliver the prompt
Output a single copy-paste-ready fenced markdown code block containing the composed prompt. No preamble, no commentary inside the block. Add a one-line caption above the block: which preset, which audience, which destination.
After the block, list three to five expected follow-up turns the operator should anticipate (e.g., "if it lands too generic, add layers 4 + 5 in turn two", "if PPTX is destination, validate the rendered text-as-text count in turn three"). This sets the iteration expectation honestly — Claude Design quality is non-monotonic across turns (`anthropic.com/engineering/harness-design-long-running-apps`).
---
## Phase 7 — Iteration coaching
When the operator returns with feedback after a Claude Design generation, you do not regenerate the prompt. You coach which surface to use next. Read `references/03-iteration-and-session.md`.
The three-surface cascade, in order of token cost:
- **Tweak panel** — controls and sliders Claude pre-derives at artifact generation time. Zero token cost. Surgical. Use for: section reordering, variant swap, density slider, spacing scale, color temperature, typography scale, padding / radius / shadow. The Anthropic-published guidance is verbatim in `references/03`.
- **Inline comments** — component-scoped edits via the comment surface. Surgical when the edit is in-component. Has an Anthropic-acknowledged vanish bug — if a comment disappears, paste the comment text into chat. Fails for new structural containers.
- **Chat** — full regeneration. Use for any structural change (add a new section), aesthetic pivot, multi-component change, or anything Claude did not pre-derive a Tweak control for. Costs one full chat turn.
Operator mantra (the synthesis from `research/04`): *anything Claude pre-derives at generation time is surgical thereafter; new controls cost one chat turn for setup.*
Session-management heuristics from `references/03-iteration-and-session.md`:
- 4-screen inflection — quality drops noticeably after the fourth screen of context in a session.
- Opus 4.7 context — quality degrades at the 40–50% context mark.
- Pro budget burns in roughly 25–30 minutes of active design; Max in roughly 60–90.
- Session-break triggers: hitting screen 4, reorder / density tweaks stop landing, chat re-introduces removed defaults.
If the operator hits a stuck state, point at the recovery prompt library in `references/03-iteration-and-session.md` — the `break-default-aesthetic.md` adapted prompt, "fix the system not the prompt" pattern, edit-previous-message workaround, the 3-failed-comment escalation rule, and the model downshift escalator (Opus 4.7 → Opus 4.6 / Sonnet 4.6).
---
## Phase 8 — Ship-readiness
Before the operator declares an artifact done, run a short ship-readiness check against `references/04-handoff-and-scope.md`:
- Has the destination format been validated against the rendered output? (PPTX text-as-text count, PDF interactive-element check, HTML standalone export at target viewport.)
- If handing off to engineering: is the export bundle complete? Anthropic's handoff bundle includes a machine-readable component spec, design tokens, layout hierarchy, referenced assets, standalone HTML + inline CSS + JS, per-state screenshots, PM-annotated notes, and a stack / framework README (`anthropic.com/news/claude-design-anthropic-labs` + `support.claude.com/en/articles/14604416`).
- Is the operator aware that the Design → Code direction is one-way? Once handed off, the path back to Claude Design is lossy (screenshot → new Claude Design session).
**Downstream tool recommendation.** Once the operator has an artifact in hand and wants critique, accessibility audit, UX copy review, design-system audit, or engineering handoff guidance, recommend Anthropic's official plugin:
```
claude plugins add knowledge-work-plugins/design
```
That plugin operates on existing artifacts (Figma URLs, screenshots, copy snippets) and ships six commands: `/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, `/handoff`. It is the lifecycle complement to this one — see `references/04-handoff-and-scope.md` for the full coverage table. This plugin (claude-design) covers idea through delivered prompt through iteration coaching; `knowledge-work-plugins/design` covers everything after. There is no command overlap and no functional redundancy.
---
## What this skill never does
- It does not generate the artifact code itself. Claude Design is the artifact generator. This skill produces prompts that go into Claude Design.
- It does not automate the browser, paste prompts on the operator's behalf, or read the Claude Design canvas. The operator copies and pastes manually.
- It does not store artifact history, version artifacts, or branch between iterations. Claude Design has no version tree and this skill does not invent one.
- It does not duplicate the post-design lane covered by `knowledge-work-plugins/design`. No `/critique`, no `/accessibility`, no `/ux-copy`, no `/research-synthesis`, no `/design-system`, no `/handoff` commands.
---
## Reference files
- `references/00-what-claude-design-is-and-isnt.md` — surface disambiguation
- `references/01-prompt-fundamentals.md` — the five-layer prompt stack
- `references/02-design-md.md` — DESIGN.md template + brand-to-DESIGN.md extractor
- `references/03-iteration-and-session.md` — Tweak / Comment / Chat cascade, session economics, recovery prompt library
- `references/04-handoff-and-scope.md` — one-way handoff, scope fence vs Anthropic's design plugin
- `references/presets/designs.md`, `prototypes.md`, `slides.md` — Anthropic-documented per-preset patterns
- `references/presets/one-pagers.md`, `wireframes-mockups.md`, `pitch-decks.md`, `marketing-collateral.md` — Community-only per-preset patterns
- `references/presets/frontier-design.md` — Experimental, no validated practitioner pattern
- `.coverage.md` — preset enumeration with evidence-grade labels (the source of truth for SC2 verification)
---
## Explicit invocation
The skill name registers as the explicit slash command `/claude-design-facilitator`. Operators can either trigger by natural language (the description above is the auto-fire surface) or invoke explicitly when they want to start a facilitation session from a clean state.

113
plugins/claude-design/skills/claude-design-facilitator/references/00-what-claude-design-is-and-isnt.md
View file

@ -1,113 +0,0 @@
# What Claude Design is and isn't
**Last updated:** 2026-05-17 | **Verified:** research/01-claude-design-surface.md
**Status:** Beta (Labs research preview)
**Captured-on date:** 2026-05-16
This file disambiguates `claude.ai/design` from the four surfaces it is most commonly conflated with. The cost of getting this wrong is wasted iteration: applying a prompt pattern that fits Live Artifacts to Claude Design (or vice versa) produces output that misses the operator's intent, and the failure looks like a prompt problem instead of a surface problem.
Read this file when the operator's signals are mixed — they reference "Artifacts" loosely, they expect a feature that does not exist in Claude Design (like `/rewind` or a version tree), they think Claude Design audits artifacts rather than generates them, or they expect round-trip handoff back from Claude Code.
---
## 1. What Claude Design is
Claude Design is an Anthropic Labs research preview that launched on 2026-04-17 (`https://anthropic.com/news/claude-design-anthropic-labs`). It is a dedicated workspace at `claude.ai/design` for generating interactive design artifacts from a prompt.
Five properties define the surface:
- **Labs research preview, not GA.** The product can change without notice. Anthropic surfaces it under the Labs banner specifically to signal that the contract is non-stable. The URL still carries the `-anthropic-labs` slug today; a Labs → GA rename is a known re-research trigger captured in `.coverage.md`.
- **Opus 4.7 pinned.** All generations run on Opus 4.7. Operators cannot select a model from the Claude Design UI. The session inherits Anthropic's model choice for this surface (`https://anthropic.com/news/claude-design-anthropic-labs`).
- **Single HTML/React substrate.** Underneath every output is one rendering engine — HTML, React components, inline CSS — regardless of which intent preset the operator picks. The intent preset shapes prompting and export, not the underlying tech.
- **Eight intent presets exposed in the UI.** Anthropic's launch post enumerates: designs, prototypes, slides, one-pagers, wireframes-mockups, pitch-decks, marketing-collateral, frontier-design. The enumeration is the source of truth for SC2 coverage in this plugin (`https://anthropic.com/news/claude-design-anthropic-labs`).
- **Multiple export paths.** PDF (lossless for static layouts, lossy for interactive elements), PPTX (slide master / layouts / fonts honored, but text can flatten to images on complex compositions), HTML standalone, Canva import, share-link, and Claude Code handoff (machine-readable component spec + design tokens + layout hierarchy + assets + standalone HTML/CSS/JS + per-state screenshots + PM notes + framework README — verbatim per `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`).
Three Anthropic-published support articles ground the surface: the get-started article (`https://support.claude.com/en/articles/14604416-get-started-with-claude-design`), the design-system setup article (`https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design`), and the PowerPoint-mode conventions article (`https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint`).
---
## 2. What Claude Design is NOT
### Not classic Artifacts at `claude.ai`
Classic Artifacts live in any Claude.ai chat. They appear in a side panel when Claude generates code, markdown, SVG, mermaid diagrams, or other inline outputs. Artifacts carry no intent presets, no Tweak panel, no export-to-PPTX, no Claude Code handoff bundle, no DESIGN.md anchor concept. They are a chat affordance.
Confusion happens because both surfaces produce HTML/React output and Anthropic's documentation has used "Artifacts" loosely in launch contexts. If the operator says "Artifacts" but describes intent presets or destination formats (`https://anthropic.com/news/claude-design-anthropic-labs`), they mean Claude Design. If they describe a side panel inside a chat (`support.claude.com` discusses Artifacts in the chat-product context), they mean classic Artifacts.
### Not Live Artifacts in Claude Cowork
Live Artifacts is a different Labs surface — collaborative real-time editing of artifacts inside Claude Cowork sessions. It runs in a different workspace, has different affordances (multi-cursor presence, version stream), and is a separate product line at `claude.ai/code` family (see Anthropic's Cowork-related communications). Claude Design has none of those collaborative primitives. The operator working alone in `claude.ai/design` is the canonical flow.
### Not custom visuals embedded in a chat reply
Sometimes Claude generates an inline HTML/SVG visual as part of a chat answer (a chart, a diagram, an illustration). That is a one-off chat artifact, not a Claude Design session. The prompt patterns are different (chat conversational tone vs design intent presets), the export options are different (chat artifact has Save / Copy, Claude Design has the full export matrix), and there is no Tweak panel on the chat-inline visuals.
### Not Anthropic's `knowledge-work-plugins/design` plugin
This is the most consequential conflation. Anthropic ships an official plugin at `https://claude.com/plugins/design` (`https://github.com/anthropics/knowledge-work-plugins`) with six slash-commands: `/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, `/handoff`. That plugin operates on **existing** artifacts (Figma URLs, screenshots, copy snippets). It does not generate artifacts.
The lifecycle split is clean:
- This plugin (`claude-design`) covers **pre-design and during-design** — idea → intent-preset selection → prompt drafting → copy-paste delivery → iteration coaching → ship-readiness.
- Anthropic's `knowledge-work-plugins/design` covers **post-design** — critique → accessibility → UX copy review → research synthesis → design-system audit → engineering handoff.
There is zero command overlap (this plugin ships no commands named `/critique`, `/accessibility`, `/ux-copy`, `/research-synthesis`, `/design-system`, or `/handoff` — `tests/validate-plugin.sh` assertion (h) enforces this mechanically). Workflow recommendation: use this plugin to land the artifact in `claude.ai/design`; once the artifact exists, install Anthropic's official plugin via `claude plugins add knowledge-work-plugins/design` for downstream review and handoff.
### Not third-party clones like `jiji262/claude-design-skill`
Several third-party repos use names like `claude-design-skill`. They are independent community efforts targeting general design workflows in Claude Code, not the `claude.ai/design` surface specifically. They predate the Anthropic Labs launch in some cases. This plugin is *Claude Design facilitation* — it targets the Anthropic surface explicitly, citing Anthropic's primary sources. Verify the operator's mental model accordingly.
---
## 3. Why the distinction matters operationally
Three operational consequences flow from getting the surface identification right.
### Prompt patterns differ
Claude Design's prompt patterns are documented in `https://anthropic.com/news/claude-design-anthropic-labs`, `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`, and the two per-preset tutorials (`https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux`, `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks`). These prompts assume the Claude Design substrate, intent presets, and the Tweak / Comment / Chat iteration cascade. Applying them to classic Artifacts, Cowork, or an inline chat visual produces noise.
Classic Artifacts prompts (the kind used inside any `claude.ai` chat) are conversational and lean on chat affordances. Claude Design prompts use the verbatim Goal / Layout / Content / Audience framework and lean on intent presets. The frameworks do not interchange cleanly.
### Limits differ
Claude Design has its own quota economics — the operator's Max / Pro plan budget burns down at a different rate than classic chat (research/04 documents observed Pro burn of roughly 25-30 minutes of active design work, Max roughly 60-90; these are community-observed, not Anthropic-published, and may shift). Opus 4.7 quality degrades at 40-50% context (`https://anthropic.com/engineering/harness-design-long-running-apps`). A 4-screen session inflection is documented community-wide.
None of these limits apply identically to classic Artifacts or to the official `knowledge-work-plugins/design` plugin. Diagnosing a quota / quality issue requires knowing which surface is in play.
### Scope differs
The official `knowledge-work-plugins/design` plugin is the right tool for post-design critique. Trying to make this plugin (`claude-design`) emit a critique would duplicate Anthropic's command surface and add nothing. The reverse — using `knowledge-work-plugins/design` to generate the artifact — does not work because that plugin operates on artifacts that already exist.
If the operator is uncertain whether their question is pre-design or post-design, ask: *does the artifact exist yet?* If no — this plugin. If yes — Anthropic's plugin.
---
## 4. Decision shortcuts
- The operator mentions intent presets (designs / prototypes / slides / one-pagers / wireframes-mockups / pitch-decks / marketing-collateral / frontier-design) → Claude Design.
- The operator mentions a workspace URL `claude.ai/design` → Claude Design.
- The operator mentions PPTX / PDF / Canva / Code-handoff exports → Claude Design.
- The operator says "Tweak panel" or "Tweak slider" → Claude Design.
- The operator says "Artifact" in a side panel context inside a normal chat → classic Artifacts.
- The operator says "Cowork" or "real-time collaborative" or "multi-cursor" → Live Artifacts.
- The operator says "critique" / "accessibility audit" / "Figma" → Anthropic's `knowledge-work-plugins/design`.
- The operator references a third-party repo named `claude-design-*` → ask what surface they target; likely not the Anthropic Labs preview.
If signals remain mixed after this read-through, ask one clarifying question rather than guess: *"Are you working in the dedicated Claude Design workspace at `claude.ai/design`, or somewhere else?"*
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — Anthropic Labs launch announcement (2026-04-17), Opus 4.7 pin, intent-preset enumeration, export options
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — get-started article, GLCA framework, handoff bundle contents
- `https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design` — design-system setup, DESIGN.md concept
- `https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint` — PowerPoint-mode conventions
- `https://claude.com/plugins/design` — Anthropic's official knowledge-work-plugins/design plugin
- `https://github.com/anthropics/knowledge-work-plugins` — source for the official plugin
- `https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux` — Anthropic-published per-preset tutorial (prototypes)
- `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` — Anthropic-published per-preset tutorial (slides)
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading criteria, non-monotonic-improvement framing
When in doubt: the Anthropic news post and the get-started support article are the load-bearing sources. Everything else triangulates against them.

265
plugins/claude-design/skills/claude-design-facilitator/references/01-prompt-fundamentals.md
View file

@ -1,265 +0,0 @@
# Prompt fundamentals — the five-layer stack
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
**Status:** Beta (Labs research preview)
**Captured-on date:** 2026-05-16
This file documents the universal prompt framework an operator applies across every Claude Design intent preset. The five layers compose into one prompt block. Layers 1 to 3 are load-bearing for every preset; layers 4 and 5 are the refinement turn.
Every authoritative claim cites an Anthropic primary source. Where community practice extends an Anthropic concept, the extension is labelled and attributed.
---
## Layer 1 — Goal / Layout / Content / Audience (GLCA)
Anthropic's verbatim framework for every Claude Design prompt. The framework is published in the get-started support article `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`. Anthropic's framing: a good Claude Design prompt names the **Goal**, the **Layout**, the **Content**, and the **Audience**, in that order, before any aesthetic specification.
The four canonical questions:
- **Goal** — what is the artifact for? "An admin dashboard for monitoring API latency", "an onboarding flow for first-time users", "a landing page that converts free trial signups". One sentence.
- **Layout** — what is the page structure? Header / hero / metrics row / table / footer; or: hero / three-feature-grid / pricing table / CTA. Name the regions.
- **Content** — what fills the regions? Real data placeholders if you have them, named labels if not. Avoid generic "lorem ipsum" — the model defaults to convergent middle-ground content if you do not constrain it.
- **Audience** — who reads or uses this artifact? Internal team, external stakeholder, B2B procurement, B2C consumer, investor. Audience determines tone, density, and aesthetic.
Anthropic publishes three verbatim canonical examples in the same support article:
```
Goal: An analytics dashboard for our customer success team
Layout: Top metrics row (4 KPIs), main chart panel, recent activity table
Content: Today's MRR, 30-day churn, NPS, expansion revenue; revenue chart;
the last 10 account events
Audience: Internal CS leads — they're in this thing every day, want density
and signal, not flashy
```
```
Goal: A mobile onboarding flow for a new fitness app
Layout: Welcome screen, goal-selection (3 cards), motion preference, sign-in
Content: Headlines, single CTA per screen, accessible touch targets
Audience: First-time users, gym beginners, ages 25-45
```
```
Goal: A SaaS landing page that converts free trial signups
Layout: Hero, three-feature grid, social proof, pricing table, FAQ, footer CTA
Content: Product name placeholder "ProductX", real headline benefit copy,
three feature blurbs (icon + headline + line)
Audience: B2B technical buyers evaluating dev tools
```
The GLCA framework is sufficient on its own for a first prompt at intent preset `designs`. For other presets, GLCA composes with the per-preset pattern in `references/presets/<preset>.md`.
Source: `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`.
---
## Layer 1.5 — Start simple, layer in complexity
The same Anthropic get-started article publishes verbatim incremental-prompting advice: do not ship a 600-word first prompt. Ship a 120-word first prompt that names GLCA, see what Claude Design produces, then add complexity in turn two and turn three.
Anthropic frames this as the dominant failure mode for first-time Claude Design operators: over-specifying the first prompt produces an output that is dense but generic. The remedy is staged — let Claude Design make its default choices, then react to what it produces with targeted constraints.
This frames how the rest of the stack composes. In turn one, ship layers 1 + 2a (or 2b) + 3. In turn two, add layer 4. In turn three, add layer 5 emphasis-weighting.
Source: `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`.
---
## Layer 2a — Concrete-alternative-spec house-style control
The first of two Anthropic-documented house-style controls. Verbatim guidance from `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`: name a concrete aesthetic family with explicit visual primitives rather than gesturing at a style.
The Anthropic-published exemplar — the AEFRM (Anthropic Engineering Field Reference Material) example — is verbatim usable:
```
Aesthetic family: industrial-utilitarian, slate-monochrome
Color palette (CSS hex):
--color-bg: #E9ECEC
--color-surface: #C9D2D4
--color-muted: #8C9A9E
--color-fg: #44545B
--color-ink: #11171B
Typography: square angular sans-serif (Söhne, Inter Variable as fallback);
no rounded glyphs; weight 500 for body, 700 for headers
Corner radius: 4px throughout — no fully rounded buttons, no pill shapes
Motion: transition: all 160ms ease-out on hover; no springy easing
Density: dense (table rows 32px tall; padding 8px on cards)
Surface: flat — no shadows, no glassmorphism
```
The control works because Claude Design reads this as a concrete brief and constrains its aesthetic decision space accordingly. Without an explicit concrete-alternative-spec, the model defaults to its convergent middle-ground aesthetic (rounded corners, generous spacing, friendly typography, gentle shadows — Anthropic's documented "AI-slop" default).
The hex palette, corner radius, and motion timing are all required — naming "industrial-utilitarian" alone is gesturing, not specifying.
Source: `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`.
---
## Layer 2b — Propose-options-before-building
The second Anthropic-documented house-style control, also from `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`. When the operator does not know exactly which aesthetic to brief, Anthropic publishes a verbatim prompt template asking Claude Design to propose four distinct visual directions before committing to one.
The verbatim prompt:
```
Before building the dashboard, propose 4 distinct visual directions.
For each, give:
- bg hex
- accent hex
- typeface (named, not gestured)
- one-line rationale tying the direction to the audience and goal
Wait for me to pick a direction before generating the artifact.
```
This forks the conversation: turn one returns four named directions, the operator picks one, turn two generates against the chosen direction. The cost is one extra round; the upside is the operator avoids the dead-end of generating against an aesthetic that does not fit and only finding out after generation.
Use layer 2b when layer 2a is not feasible (the operator does not yet know the aesthetic). Use layer 2a when the aesthetic is known.
---
## Layer 3 — AI-slop avoid-list (negative constraints)
Anthropic publishes a verbatim banned-items list in `https://claude.com/blog/improving-frontend-design-through-skills` and reinforces it in the open-source frontend-design skill at `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`. The list names the convergent middle-ground patterns that Claude Design defaults to when underspecified.
Anthropic's verbatim AI-slop fingerprints to avoid:
- **Typography slop:** Inter, Roboto, Arial as default body font. Space Grotesk is flagged as overused. Default to a concrete-named typeface in the brief, not a generic sans-serif.
- **Color slop:** purple gradients on white backgrounds; solid-color hero backgrounds; convergent middle-ground palettes (the muted blue-and-grey "professional" default).
- **Layout slop:** cookie-cutter three-column feature grids; centered-hero-with-CTA defaults; full-width-image-with-text-overlay defaults.
- **Motion slop:** scattered micro-interactions; bouncy spring easing on hover; pulse animations on idle elements.
- **Complexity-to-vision mismatch:** ornate components on simple layouts; flat components on otherwise rich layouts.
Operator-actionable copy-paste anti-prompt block (composes with layers 1 and 2):
```
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, or Space Grotesk as the primary typeface
- Purple gradients on white backgrounds
- Solid-color hero backgrounds
- Three-column feature grids with icon + headline + line
- Centered-hero-with-single-CTA layout default
- Bouncy spring easing on hover transitions
- Pulse / breathing animations on idle elements
- Glassmorphism, neumorphism, or generic "modern SaaS" defaults
If you find yourself defaulting to any of these, stop and ask me to
clarify the aesthetic before continuing.
```
Sources: `https://claude.com/blog/improving-frontend-design-through-skills` and `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`.
---
## Layer 4 — Four design dimensions to optimize
Anthropic's verbatim per-dimension guidance from `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`. Four dimensions to brief explicitly when refining beyond the first turn:
- **Typography** — name typeface, modular scale (e.g., 1.250 minor third or 1.333 perfect fourth), weight palette, line-height palette, letter-spacing for headings. Anthropic's frontend-design SKILL.md publishes specific modular scales and weight palettes verbatim.
- **Color** — beyond palette hex, specify semantic roles (background, surface, accent, muted, error, success). Define interaction states explicitly (hover, active, disabled, focus). Anthropic's guidance: avoid relying on opacity for state changes; use explicit color tokens.
- **Motion** — name easing curves (ease-out, cubic-bezier values), name durations (120ms / 160ms / 240ms tiers), name what gets animated and what does not. Anthropic's guidance: motion should clarify hierarchy and confirm interaction; avoid decorative motion.
- **Backgrounds** — flat surface vs depth, when to layer surfaces, when shadows or borders define edges. Anthropic's guidance: backgrounds carry meaning; the bare-default-white background is rarely the right choice.
In turn two of an iteration, add layer-4 dimension specs to the brief. In turn three, refine the dimension that drifted most from intent.
Source: `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`.
---
## Layer 5 — Four design grading criteria
Anthropic publishes verbatim grading criteria for design quality in `https://anthropic.com/engineering/harness-design-long-running-apps`. Four criteria, used as emphasis weights:
- **Design quality** — does the artifact look intentional, not defaulted? Is the aesthetic coherent across regions?
- **Originality** — does the artifact avoid the convergent middle-ground? Does it surprise without being weird?
- **Craft** — does the artifact feel detailed and considered at every level — typography, spacing, alignment, hierarchy, color?
- **Functionality** — does the artifact work for its goal and audience? Would it survive a usability test or a stakeholder review?
Anthropic's emphasis-weighting recommendation: in the prompt, weight which criterion matters most for *this* artifact. A dashboard for internal use weights functionality and craft highest. A pitch deck for an external investor weights design quality and originality highest. A wireframe for early exploration weights functionality highest with craft and originality deprioritized.
Operator-actionable layer-5 block:
```
Grading criteria for this artifact, in priority order:
1. {craft|design quality|originality|functionality} — weight 0.4
2. {one of the others} — weight 0.3
3. {one of the others} — weight 0.2
4. {the remaining one} — weight 0.1
Optimize against this ordering. If the artifact has to trade off,
trade off the lowest-weighted criterion first.
```
The non-monotonic-improvement caveat applies — Anthropic notes that quality across iterations is not strictly increasing. If turn three is worse than turn two on a critical criterion, the recovery move is documented in `references/03-iteration-and-session.md` ("pivot to an entirely different aesthetic if the approach wasn't working").
Source: `https://anthropic.com/engineering/harness-design-long-running-apps`.
---
## How the layers compose into one prompt
A worked example for the `designs` intent preset, dashboard, three turns:
### Turn 1 — layers 1 + 2a + 3 (the first prompt)
```
Goal: An admin dashboard for monitoring API latency by route, by region,
and by P50/P95/P99
Layout: Header with environment switcher; top metrics row (4 KPIs:
global P95, error rate, throughput, active requests); main chart
(time series, P50/P95/P99 lines); routes table with sortable
latency columns; alerts sidebar
Content: KPI placeholders are real metric names; chart uses synthetic
24-hour data; table has 12 routes with realistic paths
(/api/v1/users, /api/v1/orders, etc.)
Audience: Platform engineers, on-call rotation, ages 25-45,
comfortable with dense interfaces
Aesthetic family: industrial-utilitarian, slate-monochrome
Color palette (CSS hex):
--color-bg: #E9ECEC
--color-surface: #C9D2D4
--color-muted: #8C9A9E
--color-fg: #44545B
--color-ink: #11171B
Typography: square angular sans-serif (Söhne, Inter Variable fallback);
no rounded glyphs
Corner radius: 4px throughout
Motion: transition: all 160ms ease-out
Density: dense (32px table rows, 8px card padding)
Surface: flat — no shadows
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, or Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Pulse animations on idle elements
- Glassmorphism, neumorphism, generic "modern SaaS" defaults
```
### Turn 2 — add layer 4 dimensions
Operator reacts to turn-1 output by adding typography modular scale, semantic color roles, motion easing, and surface-depth rules.
### Turn 3 — add layer 5 weighting
Operator specifies that craft and functionality are the two highest-weighted criteria for this dashboard; design quality is third; originality lowest.
### Turn 4+ — Tweak panel takes over
Most subsequent refinements happen in the Tweak panel (per-artifact Claude-generated controls; zero-token surgical edits) — see `references/03-iteration-and-session.md` for the surface cascade.
---
## Source map
The five layers anchor on four Anthropic primary sources plus one open-source skill:
| Layer | Anthropic source |
|-------|------------------|
| 1, 1.5 | `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` |
| 2a, 2b | `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices` |
| 3 | `https://claude.com/blog/improving-frontend-design-through-skills` + `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` |
| 4 | `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` |
| 5 | `https://anthropic.com/engineering/harness-design-long-running-apps` |
Re-research trigger: any of the four URLs returning 404 or shifting content materially; Anthropic publishing a sixth layer or revising any of the five. Captured-on date 2026-05-16 — the layer-1 framework has been stable since the launch announcement.

333
plugins/claude-design/skills/claude-design-facilitator/references/02-design-md.md
View file

@ -1,333 +0,0 @@
# DESIGN.md — template and extractor
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
**Status:** Beta (Labs research preview)
**Captured-on date:** 2026-05-16
**Evidence grade:** Community-converged — Anthropic publishes the *concept* of a design-system document anchored to a Claude Design project (`https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design`), but does not publish the 9-section canonical structure. The 9-section template comes from community practitioners (`https://github.com/rohitg00/awesome-claude-design`, `https://github.com/VoltAgent/awesome-claude-design`). Use accordingly: the concept is Anthropic-authoritative; the structure is community-converged.
---
## 1. Why DESIGN.md
A DESIGN.md file uploaded to a Claude Design project anchors design-system identity for every artifact generated in that project. Without an anchor, Claude Design defaults to its convergent middle-ground aesthetic (rounded corners, generous spacing, friendly typography, gentle shadows — the AI-slop pattern documented at `https://claude.com/blog/improving-frontend-design-through-skills`). With an anchor, the model reads the file at generation time and constrains its aesthetic, component, and motion decisions to match.
Anthropic publishes the concept of design-system anchors in `https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design`. The article describes asset uploads, brand kits, and the principle that artifacts in a Claude Design project inherit the project's design language. What Anthropic does *not* publish is a recommended structure for the design-language file itself.
The community converged on a 9-section structure — documented across multiple awesome-claude-design repos, Substack posts, and practitioner blogs — that maps cleanly onto how Claude Design reads design context. The sections below are that converged structure.
---
## 2. The 9-section canonical structure
Each section names a decision Claude Design will otherwise default. The order is the order Claude Design appears to read most reliably (heaviest design-decision sections first).
### Section 1 — Visual Theme & Atmosphere
A one-paragraph description of the aesthetic family. Use named visual references the model can anchor to: "industrial-utilitarian like a Bloomberg terminal", "warm-editorial like The New York Times opinion section", "minimal-monochrome like Linear's UI".
Worked example:
```markdown
# Visual Theme & Atmosphere
Industrial-utilitarian. Slate-monochrome palette, square-cut typography,
flat surfaces. Reference: a modern data-tool UI (Linear, Datadog,
Bloomberg) — dense, intentional, no flourish. The product should look
like it was built for engineers by engineers.
```
### Section 2 — Color Palette & Roles
CSS-variable form with explicit hex values and semantic roles. Avoid relying on opacity for state changes — name each state explicitly.
Worked example:
```markdown
# Color Palette & Roles
:root {
--color-bg: #E9ECEC;
--color-surface: #C9D2D4;
--color-muted: #8C9A9E;
--color-fg: #44545B;
--color-ink: #11171B;
--color-accent: #4A6FA5;
--color-accent-hover: #3D5C8A;
--color-accent-active: #2F4A70;
--color-error: #B23A48;
--color-warning: #C89B3F;
--color-success: #4F7A4F;
}
Semantic roles:
- bg — page background
- surface — card / panel background
- muted — secondary text, borders
- fg — primary text
- ink — emphasis / heading text
```
### Section 3 — Typography Rules
Named typeface, modular scale, weight palette, line-height palette. Modular scales the community converged on are 1.250 (minor third) for dense interfaces and 1.333 (perfect fourth) for marketing pages.
Worked example:
```markdown
# Typography Rules
Primary typeface: Söhne (concrete-named, not "modern sans-serif").
Fallback: Inter Variable.
Display typeface: same as primary (no separate display face).
Modular scale: 1.250 (minor third).
--text-xs: 0.64rem;
--text-sm: 0.8rem;
--text-base: 1rem;
--text-lg: 1.25rem;
--text-xl: 1.563rem;
--text-2xl: 1.953rem;
Weight palette: 500 body, 600 emphasized, 700 headings.
Line height: 1.4 body, 1.2 headings.
If the typeface is not available, substitute Inter Variable — never
default to Inter, Roboto, Arial, or Space Grotesk
(per https://claude.com/blog/improving-frontend-design-through-skills
AI-slop avoid-list).
```
### Section 4 — Component Stylings
Per-component rules for the components Claude Design generates. Cover buttons, inputs, cards, tables, navigation. Specify radius, padding, border treatment, hover/active/disabled state explicitly.
Worked example:
```markdown
# Component Stylings
Buttons:
- radius: 4px (no pill shapes)
- padding: 8px 16px
- primary: bg accent, fg surface
- secondary: border 1px muted, bg transparent
- hover: bg accent-hover
- active: bg accent-active
- disabled: opacity 0.4, no pointer events
Inputs:
- radius: 4px
- padding: 8px 12px
- border: 1px solid muted
- focus: border accent + 2px outset ring at accent + 20% alpha
Cards:
- radius: 4px
- padding: 16px
- bg surface
- no shadow — borders define edges if needed
Tables:
- row height: 32px (dense)
- cell padding: 8px
- alternating row: bg + 4% darken
- hover row: bg + 8% darken
```
### Section 5 — Layout Principles
Grid system, spacing scale, breakpoint widths. Name the grid columns and the gap value.
Worked example:
```markdown
# Layout Principles
Grid: 12-column on screens >= 1024px, 8-column on screens 768-1023px,
4-column on screens < 768px.
Gap: 16px (--space-md).
Spacing scale:
--space-xs: 4px
--space-sm: 8px
--space-md: 16px
--space-lg: 24px
--space-xl: 32px
--space-2xl: 48px
Page max-width: 1440px centered.
Container padding: 24px on screens >= 768px, 16px below.
```
### Section 6 — Depth & Elevation
Surface depth rules. Most designs benefit from a clear flat-vs-layered decision rather than a mixed palette.
Worked example:
```markdown
# Depth & Elevation
Flat. No box-shadows by default. Borders define component edges.
Z-stack:
z-0: page surface
z-10: navigation
z-20: dropdown / popover
z-30: modal backdrop
z-40: modal content
z-50: toast / notification
Modal: bg surface, 1px border ink, no shadow.
Popover: bg surface, 1px border muted, no shadow.
```
### Section 7 — Do's and Don'ts
Explicit constraint list. This is where layer-3 (AI-slop avoid-list) gets project-specific.
Worked example:
```markdown
# Do's and Don'ts
Do:
- Use accent color sparingly (CTA + active state only)
- Use ink for headings, fg for body, muted for secondary
- Use 4px corner radius consistently
- Use 160ms ease-out for all hover transitions
Don't:
- Use purple gradients on white backgrounds
- Use solid-color hero backgrounds
- Use Inter / Roboto / Arial / Space Grotesk as primary typeface
- Use bouncy spring easing
- Use pulse / breathing animations on idle elements
- Use glassmorphism or neumorphism
- Use shadows except where the depth-and-elevation section explicitly permits
```
### Section 8 — Responsive Behavior
Breakpoint behavior. Anthropic does not publish responsive rules; this is the section where a project encodes its responsive philosophy.
Worked example:
```markdown
# Responsive Behavior
Mobile-first reasoning, but built desktop-first (target audience is
desktop). Below 768px:
- Navigation collapses to single icon-button row
- Tables become card stacks (one card per row)
- 12-column grid becomes 4-column
- Container padding drops from 24px to 16px
- Font sizes scale down by 0.9x
Touch targets: minimum 44px height (regardless of viewport).
```
### Section 9 — Agent Prompt Guide
A short block telling Claude Design how to use this DESIGN.md. This section is the bridge between the file and the prompt — it names the file by section and reminds the model that the constraints are load-bearing.
Worked example:
```markdown
# Agent Prompt Guide
When generating an artifact in this project, read every section of this
DESIGN.md before producing output. Treat color palette, typography rules,
component stylings, and layout principles as constraints — not
suggestions. If a generation would violate a constraint, stop and ask
which constraint to relax.
Cite specific section names when justifying design decisions in
explanatory text (e.g., "I chose 4px corners per Section 4 Component
Stylings").
```
---
## 3. Brand-to-DESIGN.md extractor prompt
A copy-paste-ready prompt the operator pastes into `claude.ai` (the chat product) or Claude.com to convert a brand URL, screenshot, or marketing asset into a DESIGN.md. The pattern comes from `https://github.com/rohitg00/awesome-claude-design/blob/main/prompts/brand-to-design-md.md` (adapted with attribution to the awesome-claude-design community template).
```
You will produce a DESIGN.md file by analyzing the brand reference
materials I provide. Output structure: 9 sections, in this order,
with the exact heading names:
1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide
Rules:
- Use CSS-variable form (--color-name: #HEX) for color palette
- Use modular scale form (--text-xs / --text-sm / ...) for typography
- Use named typefaces ONLY — if you cannot identify the typeface from
the brand materials with high confidence, write "unknown — operator
to fill in" rather than guessing. Do not hallucinate a typeface name.
- For each component (button, input, card, table, navigation), name
radius, padding, border treatment, and hover / active / disabled states
- Cite the source brand material at the top (e.g., "Extracted from
brand kit at <URL> on 2026-05-17")
Brand reference materials:
[paste URL, screenshot, or brand kit description here]
```
The anti-hallucination clause ("if you cannot identify... write unknown") is load-bearing — the failure mode without it is plausible-but-wrong typography names that the operator does not catch until they brief Claude Design and the output drifts.
Source for this extractor: community pattern at `https://github.com/rohitg00/awesome-claude-design/blob/main/prompts/brand-to-design-md.md`, adapted.
---
## 4. DESIGN.md failure modes
Four failure modes the operator should know before adopting DESIGN.md as a workflow primitive.
### Vision-token cost penalty
If the DESIGN.md is uploaded as an image (screenshot of a brand page) rather than as text, Claude Design pays a vision-token cost on every generation. Practitioner walkthroughs (Xinran Ma's documented experience in `research/03`) report meaningful quota burn from image-based DESIGN.md anchors. Use text-form DESIGN.md whenever possible.
### Per-user quota not pooled
Anthropic does not pool Claude Design quota across team members. A team using a shared DESIGN.md will not share quota burn — each member pays separately. Plan project workflow accordingly (research/04 documents community-observed Pro burn of roughly 25-30 minutes; Max roughly 60-90).
### Long-session degradation
DESIGN.md adherence appears to degrade in the back third of a long session. Opus 4.7 quality drops at the 40-50% context mark (`https://anthropic.com/engineering/harness-design-long-running-apps`); DESIGN.md is part of context, so its enforcement weakens accordingly. Session-break heuristics in `references/03-iteration-and-session.md` apply.
### Post-export drift
When an artifact is exported (PPTX, PDF, Code-handoff), the DESIGN.md does not travel with it. Downstream editing tools — PowerPoint, Adobe, Code IDEs — apply their own defaults. Validate the rendered output against DESIGN.md after export.
---
## 5. DESIGN.md sanity-check pattern
A community-converged test for DESIGN.md adherence: generate three artifacts in the same Claude Design project using deliberately different intent presets (designs, slides, one-pagers) and confirm that all three respect the DESIGN.md color palette, typography, and component-styling rules. If one preset drifts more than the others, the DESIGN.md needs sharpening on the section the drifting preset emphasized.
The community attribution for this pattern comes from a `theadpharm` Substack walkthrough (cited in `research/03`). It is a smoke test, not a guarantee — but it catches the common case where DESIGN.md is too general to constrain the model.
---
## Sources
- `https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design` — Anthropic's design-system setup concept
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Anthropic's AI-slop avoid-list and four design dimensions
- `https://claude.com/blog/improving-frontend-design-through-skills` — Anthropic blog on default-avoidance
- `https://anthropic.com/engineering/harness-design-long-running-apps` — context-degradation framing
- `https://github.com/rohitg00/awesome-claude-design` — community awesome-list, brand-to-DESIGN.md extractor source
- `https://github.com/VoltAgent/awesome-claude-design` — community awesome-list, alternate 9-section structure references
Re-research trigger: Anthropic publishing an official DESIGN.md structure; either community awesome-list reaching consensus on a different section ordering; new failure mode surfaced in practitioner posts.

256
plugins/claude-design/skills/claude-design-facilitator/references/03-iteration-and-session.md
View file

@ -1,256 +0,0 @@
# Iteration and session — Tweak / Comment / Chat cascade and recovery
**Last updated:** 2026-05-17 | **Verified:** research/04-iteration-mechanics-recovery.md
**Status:** Beta (Labs research preview)
**Captured-on date:** 2026-05-16
This file documents three things in order of operational urgency: which iteration surface to use when, when to break a session, and how to recover when iteration stops landing. The cost asymmetry between Tweak / Comment / Chat is the single largest leverage point in a Claude Design workflow.
---
## 1. The three-surface cascade
Claude Design exposes three edit surfaces with asymmetric token costs and asymmetric scope:
| Surface | Token cost | Scope | When to use |
|---------|-----------|-------|-------------|
| Tweak panel | Zero | Surgical, per-control | Anything Claude pre-derived at generation time |
| Inline comment | Zero on success | Component-scoped, in-component | Targeted in-component text or visual change |
| Chat | One full turn | Whole artifact | Structural change, aesthetic pivot, new section |
### Tweak panel
The Tweak panel is the per-artifact set of controls and sliders Claude pre-derives during generation. Each artifact comes with its own Tweak surface — section reordering, variant swap, density slider, spacing scale, color temperature, typography scale, padding / radius / shadow. The controls are surgical and zero-token: applying them does not consume a chat turn or budget time. They are also lossy-free — the artifact does not regenerate; the controls operate on the existing render.
Tweak panel coverage is per-artifact. If Claude did not pre-derive a control for a dimension, that dimension is not Tweak-editable. The first move is always to check the Tweak panel: most dimensions an operator wants to refine after the first generation are already there.
Operator-actionable mantra (the synthesis from `research/04`):
> Anything Claude pre-derives at generation time is surgical thereafter; new controls cost one chat turn for setup.
### Inline comments
The comment surface lets the operator click anywhere on the rendered artifact and attach a directive — "make this section narrower", "use a darker shade for this header", "remove this icon". Comments are surgical when the change is in-component (text edit, color tweak, sizing within an existing container) and they cost zero tokens on success.
Two failure modes the operator should know:
1. **Vanish bug** — comments sometimes disappear after submission with no edit applied. Anthropic has acknowledged this (community-cited; the workaround is to paste the comment text directly into chat as a follow-up turn).
2. **Structural-container failure** — comments cannot add a new structural container (a new section, a new column, a new modal). The model interprets the directive but produces no change, or makes an irrelevant change. For new containers, escalate to chat.
### Chat
Chat is the full-regeneration surface. Any structural change, aesthetic pivot, multi-component change, or new section requires a chat turn. The artifact regenerates against the new prompt; previous Tweak panel and comment state may not survive intact.
Chat costs one full turn — count it against the session budget. Use the layer-1-through-5 framework (`references/01-prompt-fundamentals.md`) for the chat prompt rather than free-form natural language.
### Per-operation surgical-vs-regen catalogue
A practical lookup for which surface fits which operation (synthesized from `research/04`):
| Operation | Surface | Notes |
|-----------|---------|-------|
| Section reordering | Tweak | Pre-derived if Claude includes a section-order control |
| Variant swap (component variant A → B) | Tweak | If Claude generated multiple variants |
| Density slider (compact / cozy / comfortable) | Tweak | Common Tweak control |
| Spacing scale (--space-* token shift) | Tweak | Common Tweak control |
| Color temperature (warmer / cooler) | Tweak | If Claude derives this dimension |
| Typography scale (modular scale shift) | Tweak | If Claude derives this dimension |
| Padding / radius / shadow per component | Tweak | Common Tweak controls |
| Text edit in existing component | Comment | Surgical, in-component |
| Color tweak in existing component | Comment | Surgical, in-component |
| Add a new section | Chat | Structural — Tweak / Comment cannot do this |
| Aesthetic pivot (industrial → editorial) | Chat | Full regen — name the new aesthetic |
| Multi-component change (revise hero + CTA + footer together) | Chat | Full regen — too broad for Comment |
| New interaction state (hover / disabled / active) | Chat | Structural — requires regeneration |
---
## 2. Anthropic-published surgical/structural split
Anthropic's verbatim framing in `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`: the Claude Design canvas distinguishes between *surgical edits* (per-element changes that do not regenerate the artifact) and *structural edits* (new components, new layouts, aesthetic pivots that require regeneration). The Tweak panel and inline comments are surgical surfaces; chat is the structural surface.
The operator's job is to identify which kind of edit a given change is *before* picking the surface. A surgical change attempted via chat regenerates the whole artifact and burns a turn; a structural change attempted via comment fails silently and wastes time. Misclassification is the dominant inefficiency in a long Claude Design session.
Source: `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`.
---
## 3. Anthropic-engineering refine-vs-pivot rule
Anthropic publishes a verbatim refine-vs-pivot guideline in `https://anthropic.com/engineering/harness-design-long-running-apps`:
> Pivot to an entirely different aesthetic if the approach wasn't working — iteration within a bad direction compounds the failure.
The companion warning, also verbatim from the same source: design quality is **non-monotonic** across iterations. Turn 4 can be worse than turn 3 on a critical criterion. The framing matters because the operator's intuition pushes toward continued refinement; the discipline is to recognize a stuck state and pivot.
Operational signal that a pivot is needed (community-converged from `research/04`):
- Three consecutive comments have failed to land
- The aesthetic is drifting back to the AI-slop default on each regeneration
- The operator finds themselves explaining what they *don't* want more than what they *do* want
- The artifact is converging on a different audience than the brief
Pivot move: rewrite the layer-2 aesthetic-family specification entirely, then ship a fresh chat turn against the new family. Do not try to incrementally edit out of a stuck state.
Source: `https://anthropic.com/engineering/harness-design-long-running-apps`.
---
## 4. Session-management heuristics
Four heuristics — one Anthropic-published, three community-converged — govern when to break a session.
### 4-screen inflection (community-converged)
Practitioners across multiple posts in `research/04` document a quality inflection around the fourth screen of context in a Claude Design session. Before screen four, edits land cleanly; after, comments start vanishing, aesthetic defaults creep back, and Tweak controls feel less precise. The exact mechanism is unclear (context-window pressure on Opus 4.7 + cumulative DESIGN.md re-reads + cumulative artifact history), but the pattern is consistent.
Practitioner mantra: **at screen four, save what you have and start a new session.**
### Opus 4.7 context degradation (Anthropic-published)
`https://anthropic.com/engineering/harness-design-long-running-apps` publishes the verbatim observation: Opus 4.7 quality degrades noticeably at the 40-50% context-window mark. Claude Design sessions accumulate context faster than chat sessions (each generation includes the artifact in context for subsequent turns); the 40-50% mark arrives sooner.
### Quota burn (community-observed)
Practitioner walkthroughs cited in `research/04` report quota burn rates as of 2026-04-28 per MindStudio's documented walkthrough — these are community observations, not Anthropic-published limits and may shift:
- **Pro plan:** ~25-30 minutes of active design before quota becomes the binding constraint
- **Max plan:** ~60-90 minutes of active design before quota becomes the binding constraint
These numbers assume continuous active design (chat turns, regenerations, image-form DESIGN.md anchors). Tweak panel and comment surface usage does not burn quota.
Captured-on date: 2026-04-28 per `research/04`. Not an Anthropic-published limit.
### Session-break triggers (community-converged)
Three signals that a session has reached its productive end:
- Reorder / density Tweak controls stop landing (the model is not respecting the surgical surface)
- Chat re-introduces previously-removed defaults (the model is losing the negative constraints)
- The operator finds themselves repeating the same constraint in three consecutive turns
When two of three trigger together, break the session.
---
## 5. Context-reset prompt
When the operator needs to break a session but does not want to lose what worked, the verbatim community pattern from MindStudio (2026-04-28, cited in `research/04`):
```
Before we continue, summarize the design system and component decisions
we've made in this session as a structured markdown document I can use
as a fresh starting context. Include:
- the aesthetic family we converged on
- color palette in CSS-variable form
- typography decisions (typeface, modular scale, weights)
- component patterns we settled on
- decisions we made and then reversed (so I don't reintroduce them)
- anything we tried that did not work
```
Paste the produced markdown into a new Claude Design session as the opening context, alongside the original DESIGN.md. The new session starts with the cumulative decisions but a fresh context window.
Captured-on date: 2026-04-28.
---
## 6. Recovery prompt library
Five recovery moves, listed in escalating cost order.
### 6.1 — Break the default aesthetic
The highest-leverage single content asset in this plugin. Adapted with attribution from `https://github.com/rohitg00/awesome-claude-design/blob/main/prompts/break-default-aesthetic.md`. Use when the artifact has drifted toward AI-slop defaults despite negative constraints in the brief.
```
The current direction has converged on a generic default. I want a
distinct visual direction. Constraints:
1. Pick ONE aesthetic family and commit to it. Name a concrete reference
(an existing product, an editorial source, a design movement). No
"modern SaaS", no "clean", no "minimal" as the named family — those
are defaults, not directions.
2. Do not produce any of:
- Inter, Roboto, Arial, Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Three-column feature grids with icon + headline + line
- Centered-hero-with-single-CTA layout default
- Glassmorphism, neumorphism, generic "modern" defaults
3. Before generating: list four candidate directions matching the goal
and audience. For each:
- Aesthetic family (with concrete reference)
- Color palette in hex
- Typeface (named)
- One-line rationale tying it to goal + audience
Wait for me to pick one. Do NOT default to "the most common modern
approach."
4. The aesthetic should surprise without being weird. If you're tempted
to write "professional" or "balanced" or "approachable", stop.
Those words signal default-mode reasoning.
```
### 6.2 — Fix the system, not the prompt
Community pattern: when iteration is stuck, the prompt is rarely the problem. The DESIGN.md is. Reopen the DESIGN.md, audit the section the artifact is drifting on (typography, color, components), tighten that section, re-upload, then re-generate.
The instinct is to add more constraints to the chat prompt. The discipline is to fix the upstream anchor.
### 6.3 — Edit previous message rather than send a new one
Community-documented workaround for context-bloat: when the previous prompt almost worked but missed one detail, edit the previous message rather than send a new turn. Claude Design re-generates from the edited message without adding to context. This is in `research/04` as a low-cost recovery move for the case where a single-word change would have fixed the output.
### 6.4 — 3-failed-comment escalation rule
If three consecutive inline comments fail to land, stop commenting and escalate to chat. The comment surface is signaling that the model is not in a state to respect surgical edits — either the artifact has drifted too far from the brief, the context window is pressured, or the change is actually structural and was misclassified.
Escalation move: paste the failed comment text directly into a chat turn, prefaced with "the inline comment surface is not landing on this; please apply this change via regeneration".
### 6.5 — Model downshift escalator
When Opus 4.7 generations are non-monotonic in quality and Tweak / Comment / chat moves all stop landing, the recovery move is to start a fresh session at a different model. The downshift sequence community-converged on (per `research/04`):
- Opus 4.7 → Opus 4.6 (same family, less context-pressure-sensitive)
- Opus 4.6 → Sonnet 4.6 (faster, less context-sensitive, sometimes better at constraint-following on tight briefs)
Claude Design pins to Opus 4.7. The downshift happens by moving the work to a different Anthropic surface (Claude.com chat with a model picker) for the constraint-tightening turn, then bringing the result back to Claude Design as a new session anchor.
### 6.6 — Verbal save-pattern
When the operator wants to preserve what works but try a different direction without losing the current state, the community pattern is to **verbally save** in chat:
```
Save what we have. The current direction is good but I want to explore
a completely different aesthetic for comparison. Acknowledge this save,
then start fresh on a new direction without referencing the saved state.
We may come back to it.
```
The "save" is verbal — Claude Design has no version-tree primitive — but it signals to the model that the previous direction is preserved in the operator's mental model and the next turn is exploratory.
---
## 7. What Claude Design lacks
Four primitives that exist in adjacent Anthropic surfaces but not in Claude Design today. The plugin must never promise these:
- **No `/rewind`** — Anthropic Code has a `/rewind` primitive that reverts to a prior conversational state. Claude Design does not.
- **No version history** — there is no Tweak-history, no Comment-history, no chat-thread-fork primitive. The verbal save-pattern (Section 6.6) is the closest substitute.
- **No two-way handoff** — once an artifact is exported to Claude Code, there is no path back into Claude Design. Re-import requires a screenshot → new Claude Design session (lossy). See `references/04-handoff-and-scope.md`.
- **No branching** — Claude Design cannot fork a session into parallel directions and compare. The verbal save-pattern is the only branching primitive.
When the operator asks for any of these, name the constraint and offer the closest substitute (verbal save-pattern, multi-session-with-context-reset-prompt, manual screenshot archive).
---
## Sources
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — surgical / structural edit split, intent presets
- `https://anthropic.com/engineering/harness-design-long-running-apps` — refine-vs-pivot rule, non-monotonic improvement, 40-50% context degradation, design grading criteria
- `https://github.com/rohitg00/awesome-claude-design` — community recovery prompts, break-default-aesthetic source
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list applied during recovery
Re-research trigger: Anthropic publishing version-history or branching primitives; community 4-screen inflection no longer reproducing; quota mechanics shifting (Pro / Max minute counts have a 2026-04-28 captured-on date and are community-observed, not Anthropic-published).

157
plugins/claude-design/skills/claude-design-facilitator/references/04-handoff-and-scope.md
View file

@ -1,157 +0,0 @@
# Handoff and scope fence
**Last updated:** 2026-05-17 | **Verified:** research/04-iteration-mechanics-recovery.md + research/05-anthropic-design-plugin-scope.md
**Status:** Beta (Labs research preview)
**Captured-on date:** 2026-05-16
This file documents two things: how Claude Design hands artifacts off to downstream tools (Claude Code, PowerPoint, PDF, Canva), and how this plugin (`claude-design`) fits next to Anthropic's official `knowledge-work-plugins/design`. The scope fence is load-bearing — getting it wrong duplicates Anthropic's command surface and adds nothing.
---
## 1. Handoff bundle contents
When the operator chooses Claude Code handoff as the destination, Claude Design produces a bundle containing — verbatim per `https://anthropic.com/news/claude-design-anthropic-labs` and `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`:
- **Machine-readable component spec** — a JSON-shaped description of the components in the artifact, with names, props, and variants
- **Design tokens** — colors, typography, spacing, radii in token form (CSS variables or JSON tokens)
- **Layout hierarchy** — the page / screen structure as a tree
- **Referenced assets** — images, icons, fonts referenced in the artifact, bundled
- **Standalone HTML + inline CSS + JS** — a self-contained render that runs without Claude Design
- **Per-state screenshots** — visual snapshots of each interaction state (default, hover, active, disabled, focused)
- **PM-annotated notes** — annotations Claude Design surfaces about design decisions, edge cases, and trade-offs
- **Stack / framework README** — a guide to which framework conventions the artifact assumes (e.g., React + Tailwind, or vanilla HTML)
The bundle is generated once on export. It does not regenerate when the operator iterates the artifact further inside Claude Design — the operator must re-export to pick up changes.
Sources: `https://anthropic.com/news/claude-design-anthropic-labs` and `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`.
---
## 2. Direction is one-way
The Design → Code handoff direction is one-way. Once the bundle is exported and the operator starts iterating in Claude Code (or any code editor), there is no return path to Claude Design. The component spec, design tokens, and standalone HTML continue to live in the code repository; Claude Design has no concept of "re-ingest from code".
If the operator wants to visit the visual surface again after engineering iteration, the only path is:
1. Screenshot the current Claude Code render
2. Open a new Claude Design session
3. Paste the screenshot as the starting visual reference
4. Brief Claude Design from scratch using layer-1-through-5 framework
This is lossy: the design tokens, component spec, and PM notes from the original bundle do not travel into the new Claude Design session. The new session inherits only what the screenshot communicates.
Operational consequences:
- **Finalize visual decisions inside Claude Design before exporting.** The Tweak panel and inline comments are free; chat turns inside Claude Design are budget-priced; engineering iteration in code is budget-free but the visual round-trip is one-way. Order accordingly.
- **Export once, intentionally.** Bundling everything in a single export (per Section 6 below) costs one chat turn; bundling screen-by-screen costs N turns and consumes budget faster.
- **Plan for asymmetric revisit.** When the engineering implementation diverges from the design intent and the operator wants a designer review, schedule that revisit as a fresh Claude Design session, not as an extension of the original session.
Practitioner consensus on this point is documented at `https://claudefa.st/blog/guide/mechanics/claude-design-handoff` (community source). Anthropic frames the same one-way property implicitly in the get-started article — the handoff is described as an export, not a connection.
---
## 3. Workflow recommendation
The recommended flow for any Claude Design artifact destined for engineering implementation:
1. **Iterate visually in Claude Design until the artifact is shippable.** Use Tweak panel and inline comments first; chat turns for structural and aesthetic changes.
2. **Validate the destination format before exporting.** If destination is PPTX, verify the text-as-text count (see Section 6 token cost trap). If destination is HTML standalone, render it in the target browser at the target viewport. If destination is PDF, check the interactive-element handling.
3. **Export the full bundle once.** Bundle all screens in one export, not per-screen. The token cost trap (Section 6) compounds with per-screen exports.
4. **Iterate engineering inside Claude Code or the code editor.** Use Claude Code's `/edit` and chat surfaces. Pull the design tokens from the bundle into the repository's styling layer.
5. **For post-design design-quality work — critique, accessibility audit, UX copy review, design-system audit, engineering handoff guidance — install Anthropic's official plugin (Section 4 below).**
6. **If a visual revisit becomes necessary later, accept the one-way cost.** Open a new Claude Design session against a screenshot; do not try to re-extend the original session.
This is the flow per Section 4's scope-fence reasoning: this plugin covers the upstream lifecycle; Anthropic's covers downstream.
---
## 4. Scope fence vs Anthropic's `knowledge-work-plugins/design`
Anthropic ships an official Claude Code plugin at `https://claude.com/plugins/design` (source: `https://github.com/anthropics/knowledge-work-plugins`). It is skill-driven, Apache 2.0 licensed (MIT-equivalent), and ships six slash-commands operating on **existing** artifacts (Figma URLs, screenshots, copy snippets).
The lifecycle-stage coverage map:
| Lifecycle stage | This plugin (claude-design) | Anthropic's plugin (knowledge-work-plugins/design) |
|-----------------|------------------------------|----------------------------------------------------|
| Idea ingestion | ✓ Disambiguate surface, intent preset, audience | — |
| Intent-preset selection | ✓ Eight presets, evidence-grade labelled | — |
| Prompt engineering | ✓ Five-layer stack + per-preset patterns | — |
| Copy-paste delivery | ✓ Composed prompt block | — |
| Iteration coaching | ✓ Tweak / Comment / Chat cascade, session economics | — |
| Ship-readiness | ✓ Operator-attested + recommend downstream tool | — |
| Critique | — | ✓ `/critique` |
| Accessibility audit | — | ✓ `/accessibility` |
| UX copy review | — | ✓ `/ux-copy` |
| Research synthesis | — | ✓ `/research-synthesis` |
| Design-system audit | — | ✓ `/design-system` |
| Engineering handoff | — | ✓ `/handoff` |
There is no functional overlap. This plugin produces prompts that go into Claude Design; Anthropic's plugin operates on artifacts that already exist. The split is clean by design — both plugins document the other as the lifecycle complement.
**Forbidden command-name list.** This plugin must NOT ship slash-commands with any of these names (with or without a `claude-design:` namespace prefix):
- `/critique`
- `/accessibility`
- `/ux-copy`
- `/research-synthesis`
- `/design-system`
- `/handoff`
`tests/validate-plugin.sh` assertion (h) enforces this mechanically. The rationale is collision-avoidance — if both plugins are installed and both ship `/critique`, command resolution becomes ambiguous and one or the other silently fails. The cleaner solution is: this plugin does not own those commands.
---
## 5. Recommended downstream tool
When the operator finishes the Claude Design lifecycle (artifact exists, exported, ready for review), surface the downstream tool installation as the next step:
```
claude plugins add knowledge-work-plugins/design
```
In a new Claude Code session with that plugin installed:
- Run `/critique <path-or-URL>` to get a design critique
- Run `/accessibility <path-or-URL>` for a WCAG audit
- Run `/ux-copy <path-or-URL>` for copy review
- Run `/research-synthesis` if the operator has user-research notes to synthesize
- Run `/design-system <path-or-URL>` for design-system consistency check
- Run `/handoff <path-or-URL>` for engineering-handoff guidance
Sources: `https://claude.com/plugins/design` and `https://github.com/anthropics/knowledge-work-plugins`.
The plugin is Apache 2.0, free, and maintained by Anthropic. There is no commercial trade-off; it is the canonical downstream tool.
---
## 6. Token cost trap — bundle all screens in one export
Practitioner-documented failure mode: exporting screen-by-screen instead of bundling all screens in one export. The community-cited reference is `token-budget-claude-design.md` (cited in `research/04` as one of the highest-leverage cost-management items).
The mechanism: each export turn passes the current artifact state through Opus 4.7 to produce the bundle. For an N-screen artifact, N separate exports run N separate bundle generations and burn N chat turns. Bundling all N screens in a single export runs one bundle generation against the cumulative state and burns one chat turn.
The bundling prompt pattern:
```
Generate the full export bundle covering all N screens of this artifact:
[screen 1: name], [screen 2: name], ... [screen N: name].
Include for each screen: HTML standalone, design tokens, component spec,
per-state screenshots, PM notes. Bundle as a single download.
```
Multi-screen artifacts (prototypes, slide decks, multi-page landing pages) benefit most from this discipline. Single-screen artifacts (a single dashboard, a single one-pager) are not affected because there is only one bundle to generate.
If the operator has already paid the per-screen cost and noticed mid-flight, the recovery is to abandon partial exports and run one final bundling export against the cumulative artifact state.
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — Anthropic Labs launch, bundle contents
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — get-started, handoff bundle contents
- `https://claude.com/plugins/design` — Anthropic's official knowledge-work-plugins/design plugin
- `https://github.com/anthropics/knowledge-work-plugins` — source for the official plugin
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading framing
- `https://claudefa.st/blog/guide/mechanics/claude-design-handoff` — community operational consensus on one-way direction
Re-research trigger: Anthropic announcing a two-way handoff primitive; `knowledge-work-plugins/design` adding or removing slash-commands; bundle contents changing materially; this plugin and Anthropic's plugin overlap emerging.

183
plugins/claude-design/skills/claude-design-facilitator/references/presets/designs.md
View file

@ -1,183 +0,0 @@
# Preset: designs
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
**Evidence grade:** Anthropic-documented + community-validated
**Captured-on date:** 2026-05-16
The `designs` intent preset is Claude Design's generic generation mode. It covers dashboards, components, layouts, and design explorations that do not fit into one of the more specialised presets (prototypes, slides, one-pagers, etc.). It is the preset operators reach for when the goal is "produce a high-quality visual artifact" rather than a destination-shaped artifact.
This file documents the `designs` preset across six dimensions: what it is, when to use it, Anthropic's published prompt patterns, community uplift, critical caveats, and one end-to-end worked prompt.
---
## (a) What this preset is
Anthropic's launch post (`https://anthropic.com/news/claude-design-anthropic-labs`) describes `designs` as the default-mode preset — the substrate every other preset effectively inherits from, with destination shaping layered on top. Output is HTML + React + inline CSS, viewable in the Claude Design canvas, exportable to PDF / HTML standalone / Code-handoff.
Two Anthropic primary sources ground this preset:
- The Anthropic-engineering blog `https://anthropic.com/engineering/harness-design-long-running-apps` publishes the four design grading criteria (design quality, originality, craft, functionality) that the `designs` preset is optimised against.
- The frontend-design open-source skill at `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` documents Anthropic's verbatim Design-Thinking Framework — **Purpose**, **Tone**, **Constraints**, **Differentiation** — and the verbatim AI-slop avoid-list.
The frontend-design skill is the closest thing Anthropic publishes to a `designs`-preset system prompt. Read it whenever the operator wants to understand what Claude Design is internally optimising for.
---
## (b) When to use it
Pick `designs` when the goal is generic, exploratory, or composite. The decision matrix:
| Operator goal | Preset |
|---------------|--------|
| Generic dashboard, component library exploration, design system playground | **designs** |
| Interactive product flow for usability testing | prototypes |
| Presentation for stakeholders | slides |
| Single-page memo or leave-behind | one-pagers |
| Low-fi structural layout for early review | wireframes-mockups |
| Investor / external pitch | pitch-decks |
| Landing page, social variant, marketing asset | marketing-collateral |
| Code-powered prototype with voice / video / shaders / 3D | frontier-design (experimental — see preset file) |
If the operator is uncertain between `designs` and `prototypes`, the distinguishing question is: **is this for usability testing?** Yes → prototypes. No → designs.
If uncertain between `designs` and `marketing-collateral`, the distinguishing question is: **is this destined for a marketing surface (landing page, social, ad)?** Yes → marketing-collateral. No → designs.
---
## (c) Anthropic-published prompt patterns
### The Design-Thinking Framework (verbatim from frontend-design/SKILL.md)
Anthropic's `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` publishes the verbatim four-part framework Claude Design uses when reasoning about a design:
- **Purpose** — what is the artifact for? Match every aesthetic decision to the purpose.
- **Tone** — what emotional register fits the audience and the purpose? Energetic, calm, authoritative, playful, terse?
- **Constraints** — what cannot be changed? Brand colors, typeface restrictions, layout rules, accessibility minimums.
- **Differentiation** — what makes this artifact distinct from the convergent middle-ground default? Name the differentiation explicitly.
Use this framework as a pre-brief check before composing a layer-1-through-5 prompt (see `../01-prompt-fundamentals.md`). If any of the four parts is fuzzy, sharpen it before drafting.
### Verbatim AI-slop avoid-list
Anthropic's frontend-design skill + the blog post `https://claude.com/blog/improving-frontend-design-through-skills` publish the verbatim banned-items list used in layer 3 of the prompt stack. See `../01-prompt-fundamentals.md` Section "Layer 3" for the full list. The `designs` preset inherits this list — it is not optional.
### Anthropic's verbatim canonical examples
The Anthropic get-started article `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` publishes three verbatim canonical examples (dashboard, mobile onboarding, landing page) demonstrating the Goal / Layout / Content / Audience framework. Read them as the reference shape for a first prompt against `designs`. Reproduced in full in `../01-prompt-fundamentals.md` Section "Layer 1".
---
## (d) Community uplift
Three community-converged patterns extend Anthropic's published material for the `designs` preset.
### Real-data injection over lorem ipsum
Victor Dibia's documented pattern (`research/03`): substitute realistic placeholder content rather than lorem ipsum. The model defaults to convergent middle-ground content when content is unspecified; named placeholders ("Today's MRR: $48,200", "Last 24h error rate: 0.12%") anchor the model to real-shaped output.
For dashboards specifically: use realistic metric values, realistic timestamps, realistic user names. The visual difference between a chart with `$3,200` / `$4,500` / `$2,800` and a chart with `$XXX` / `$YYY` / `$ZZZ` is large — Claude Design will infer typography spacing and component sizing from the named values.
### Explicit modular scale and weight palette
Community pattern (research/03): name the typographic modular scale and weight palette in the brief rather than letting the model default. The `1.250` (minor third) scale fits dense informational artifacts; the `1.333` (perfect fourth) scale fits marketing pages. Weight palettes converge on `500 body / 600 emphasized / 700 headings`.
### Specify the negative aesthetic family
Beyond layer-3 negative constraints (which name specific banned items), community practice (research/03) is to name an entire negative aesthetic family — "not modern SaaS", "not playful illustrated", "not corporate professional" — to push the model out of its default neighbourhood. The model interprets aesthetic-family naming as a strong signal even in the negative.
---
## (e) Critical caveats
Three caveats specific to the `designs` preset.
### Default-aesthetic drift on iteration
The `designs` preset is most susceptible to default-aesthetic drift because it has no destination-shaped constraint pulling it toward a specific genre. Watch for drift back to AI-slop defaults across iterations — the `references/03-iteration-and-session.md` "break-default-aesthetic" recovery prompt is targeted at exactly this drift.
### Non-monotonic improvement across iterations
`https://anthropic.com/engineering/harness-design-long-running-apps` documents that quality across iterations is not strictly increasing. Turn 4 can be worse than turn 3 on design quality, originality, or craft. The recovery move (pivot, not refine) is in `../03-iteration-and-session.md`.
### Component spec coherence
For dashboards and component libraries specifically, the export bundle's machine-readable component spec is load-bearing for engineering handoff. Ensure the artifact has coherent component definitions (named, with consistent variants) before exporting — otherwise the component spec will be partial and the engineering implementation will diverge.
---
## (f) One end-to-end worked prompt — layers 1 + 2a + 3 composed
Goal: an admin dashboard for an analytics product, audience is data engineers.
```
Goal: An admin dashboard for monitoring data-pipeline freshness across
120 tables, sorted by last-successful-load timestamp
Layout: Header with environment switcher + global time-window selector;
top metrics row (4 KPIs: tables behind SLA, tables current,
tables stale, tables errored); main panel with stacked area
chart showing freshness over the last 24 hours; sortable table
below with 120 rows; alerts sidebar
Content: Realistic table names (orders, customers, inventory,
user_events, sessions, etc.); realistic timestamps (last
successful load within the last 6 hours for most, some at
12 hours, some at 48 hours); realistic error rates (0.01% to
3.2%)
Audience: Data engineers, on-call rotation, ages 25-50, comfortable
with dense interfaces, need to scan and triage quickly
Aesthetic family: industrial-utilitarian, slate-monochrome
Color palette (CSS hex):
--color-bg: #E9ECEC
--color-surface: #C9D2D4
--color-muted: #8C9A9E
--color-fg: #44545B
--color-ink: #11171B
--color-accent: #4A6FA5
--color-error: #B23A48
--color-warning: #C89B3F
Typography: square angular sans-serif (Söhne preferred, Inter Variable
fallback); no rounded glyphs; modular scale 1.250
Corner radius: 4px throughout — no pill shapes
Motion: transition: all 160ms ease-out
Density: dense (32px table rows, 8px card padding)
Surface: flat — no shadows, borders define edges
Design-Thinking Framework:
Purpose: enable on-call triage in under 60 seconds per incident
Tone: terse, signal-dense, no decorative copy
Constraints: 32px row height minimum (accessibility), accent reserved
for actionable items only
Differentiation: this is a data-engineer tool, not a marketing
dashboard — no card-style metric tiles, no playful
illustrations, no progress-ring widgets
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, or Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Card-style KPI tiles with shadows and rounded corners
- Centered-hero with single CTA
- Bouncy spring easing on hover
- Pulse animations on idle elements
- Glassmorphism, neumorphism, generic "modern SaaS" defaults
If you find yourself defaulting to any of these, stop and ask me to
clarify the aesthetic before continuing.
```
Expected follow-up turns:
1. Turn 2: add layer 4 (typography modular scale specifics, semantic color roles, motion easing curves)
2. Turn 3: add layer 5 (grading criteria weighting — craft and functionality at 0.4 and 0.3, design quality 0.2, originality 0.1)
3. Turn 4+: Tweak panel takes over for surgical edits
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration, launch post
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — GLCA framework, three canonical examples
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading criteria, non-monotonic improvement
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Design-Thinking Framework, AI-slop avoid-list
- `https://claude.com/blog/improving-frontend-design-through-skills` — default-avoidance blog post
Re-research trigger: Anthropic updating the Design-Thinking Framework; new canonical examples added to get-started article; AI-slop avoid-list materially extended.

149
plugins/claude-design/skills/claude-design-facilitator/references/presets/frontier-design.md
View file

@ -1,149 +0,0 @@
# Preset: frontier-design
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
Evidence grade: Experimental — no validated practitioner pattern as of 2026-05-16. Frontier design is currently marketing language for "elaborate variants of the other presets," not a distinguishable generation mode practitioners can reliably invoke today.
This file documents what Anthropic publishes about the `frontier-design` preset, what practitioners have shipped (nothing verified), what adjacent material exists, and the single experimental pattern the plugin offers — clearly labelled as unverified speculation. The honest position the plugin takes is in Section (e).
---
## (a) What Anthropic says
Anthropic's launch post `https://anthropic.com/news/claude-design-anthropic-labs` describes `frontier-design` in a single sentence (verbatim):
> code-powered prototypes with voice, video, shaders, 3D and built-in AI
This is the entirety of Anthropic's per-preset documentation as of the 2026-05-16 captured-on date. There is no dedicated tutorial, no support article, no canonical prompt set, no Anthropic-published example artifact.
The launch sentence implies the preset targets:
- Code-powered prototypes (not static designs) — implying interactive elements at minimum
- Voice (audio playback, speech recognition, voice UI)
- Video (embedded video playback, possibly video-driven UI)
- Shaders (WebGL, custom GLSL shaders, GPU-driven visual effects)
- 3D (WebGL 3D scenes, possibly Three.js or similar)
- Built-in AI (LLM-driven interactions inside the artifact)
Anthropic's framing suggests `frontier-design` is the preset for showpiece artifacts demonstrating Claude Design's outer-edge capabilities — not a workhorse preset like `designs`, `prototypes`, or `slides`.
---
## (b) What practitioners have shipped
Verifiable practitioner outputs as of 2026-05-16: **NONE that we could verify.**
The most explicit acknowledgment of this gap comes from `https://llmx.tech/blog/claude-design-hands-on-review-2026` (cited in `research/03`):
> ...no frontier design assessment provided. The hands-on review covers designs, prototypes, slides, and one-pagers. Frontier design is named in the preset list but received zero hands-on evaluation, because no practitioner artifact has been published demonstrating what the preset produces in practice.
Across the community sources surveyed in `research/03` (Substack walkthroughs, awesome-claude-design lists, Twitter / X threads, MindStudio walkthroughs, sagnikbhattacharya, victordibia, theadpharm, claudefa.st, etc.), no practitioner has published a verifiable frontier-design artifact with prompt, output, and reproduction steps. The preset is named, occasionally referenced, but not demonstrated.
This may change. The preset is new (April 2026 launch); practitioner adoption lags. The `.coverage.md` re-research trigger explicitly flags "first verified frontier-design practitioner artifact ships publicly" as a refresh trigger for this file.
---
## (c) Adjacent material
While no `frontier-design`-specific Anthropic or practitioner material exists, two adjacent sources cover the underlying capabilities Anthropic names.
### Motion and spatial composition — `frontend-design/SKILL.md`
`https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` publishes Anthropic's guidance on motion (easing curves, timing tiers, what to animate and what not to) and spatial composition (typography hierarchy, surface depth, layered backgrounds). These are the building blocks the `frontier-design` preset would extend with voice / video / shaders / 3D, but the building blocks themselves are general-purpose.
### Animated and 3D websites — MindStudio walkthrough
MindStudio's 2026-04-28 walkthrough (cited in `research/03`) covers prompting Claude for animated and 3D websites — but the walkthrough is set in adjacent Anthropic surfaces (Claude.com chat with an HTML artifact), not in `claude.ai/design` with the `frontier-design` preset specifically. The walkthrough is useful for the prompt-engineering pattern (naming GLSL fragment shader constraints, polygon-count budgets, voice-prompt structuring) but is not a frontier-design-preset artifact.
---
## (d) Single experimental pattern (unverified speculation)
One experimental pattern, clearly labelled as unverified, that an operator could try if they want to engage with the preset despite the gap.
The pattern comes from Google's Gemini deep-research output (cited in `research/03`) and carries low confidence. It is a constraint-language pattern for shader and physics elements, adapted from broader frontend-design practice:
```
[layers 1 through 5 of the standard prompt stack from
../01-prompt-fundamentals.md]
Frontier capabilities to engage:
Shaders:
- One custom GLSL fragment shader applied to the hero region
- Shader pattern: [name the visual character — e.g.,
"subtle gradient flow with imperceptible noise" or
"iridescent surface reacting to cursor position"]
- Frame budget: 60fps target on Apple M1 / equivalent
- No fullscreen shader-bombs (battery / heat / accessibility)
3D:
- One 3D element in the hero region, scene-bounded (no fullscreen)
- Polygon count budget: <50,000 triangles
- Lighting: 2-3 light sources max
- Camera: fixed or single-axis orbit; no free-camera
Voice:
- [if voice UI relevant] one voice-driven interaction, with
visible text-transcript fallback
- Speech-recognition language and accent assumptions named
explicitly
Video:
- [if video element relevant] embedded video with explicit
autoplay/no-autoplay decision; explicit captions decision
Built-in AI:
- [if applicable] one LLM-driven interaction in the artifact
- Explicit fallback for when the LLM call fails
Test in target browsers (Chrome, Safari, Firefox) at the target device
class (M1 / M2 desktop, mid-range mobile). Expect aesthetic drift
across runs; non-monotonic improvement applies amplified for frontier
capabilities.
```
Confidence rating on this pattern: **low**. It is a reasoned extrapolation from frontend-design principles, not a tested frontier-design prompt. If you try it, document what works and what does not — there is a community gap to fill.
---
## (e) The plugin's honest position
The plugin's stance on `frontier-design`:
If you want to attempt frontier design, treat it as a high-fidelity prototype (`prototypes` preset) with extra constraint language for shaders, polygons, voice, video, and built-in AI. Expect aesthetic drift on first generations. Verify that your output works in target browsers before committing chat-turn budget to refinement. Expect that the model's prior on what "frontier design" means may differ from yours — over-specify everything that matters.
Do not assume `frontier-design` produces a categorically different artifact from `prototypes` + extra capability constraints. The launch sentence is suggestive; the practitioner evidence is absent. The preset is marketing language for elaborate prototype variants until proven otherwise.
When the operator names `frontier-design` specifically:
1. Read this file with them
2. Confirm they have understood the practitioner-evidence gap
3. Offer the experimental pattern in Section (d) as a starting point, clearly labelled as unverified
4. Treat the resulting artifact as exploratory — surface what worked and what did not, contribute back to the community gap
5. Plan for amplified non-monotonic-improvement (`../03-iteration-and-session.md`) — frontier capabilities compound the standard non-monotonic risk
---
## (f) Re-research trigger
This file refreshes when any of the following happens:
- Anthropic publishes a dedicated tutorial, support article, or canonical prompt set for `frontier-design`
- A verified practitioner artifact appears publicly with prompt + output + reproduction steps
- The launch-post one-sentence description changes materially
- A community pattern reaches enough adoption to be cited (not speculation) — the `awesome-claude-design` lists and adjacent practitioner blogs are the primary surfaces to watch
When any of these triggers, update Section (b) to reflect verified material, replace Section (d) with the verified pattern, and re-grade the evidence label from "Experimental" to "Community-only" or "Anthropic-documented + community-validated" as appropriate.
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — Anthropic's verbatim one-sentence description (the entirety of Anthropic-published material on this preset)
- `https://llmx.tech/blog/claude-design-hands-on-review-2026` — community practitioner explicitly noting the frontier-design evaluation gap
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — adjacent material on motion and spatial composition
- `https://anthropic.com/engineering/harness-design-long-running-apps` — non-monotonic-improvement framing (amplified here)
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list (composed for frontier prompts)
Re-research trigger: see Section (f). The preset is the most volatile in this plugin's coverage; expect this file to refresh first when Anthropic ships material or practitioners publish artifacts.

218
plugins/claude-design/skills/claude-design-facilitator/references/presets/marketing-collateral.md
View file

@ -1,218 +0,0 @@
# Preset: marketing-collateral
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
Evidence grade: Community-only — Anthropic publishes no per-preset prompt patterns for this preset as of 2026-05-16.
Anthropic names `marketing-collateral` in the launch enumeration at `https://anthropic.com/news/claude-design-anthropic-labs` but publishes no dedicated tutorial. The patterns below come from community practitioners; treat them as field-tested but not Anthropic-authoritative. Anthropic's frontend-design open-source skill at `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` is the closest adjacent Anthropic source — it covers landing-page and marketing-site design philosophy without per-preset prompts.
---
## (a) What this preset is
Anthropic launch post one-sentence description: `marketing-collateral` covers landing pages, social variants, banner ads, email creative, and other visual assets in the marketing surface area. Output is typically HTML for landing pages, image-shaped for social and ads.
Distinguishing properties:
- Conversion-oriented — the artifact has a measurable goal (signups, clicks, opens)
- Multi-format — a single campaign typically needs landing page + social variants + email + ad creative
- Brand-anchored — marketing collateral lives or dies on brand fidelity; a DESIGN.md is essentially mandatory
- Variant-heavy — A/B testing assumes multiple variants of the same creative
---
## (b) Why Anthropic published no per-preset guidance
The launch enumeration treats marketing-collateral as a destination shape rather than a distinct generation mode. The frontend-design open-source skill (`https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`) is the closest thing Anthropic publishes — it covers the design-philosophy layer (Purpose / Tone / Constraints / Differentiation) but not marketing-specific prompt patterns.
Community practitioners have built patterns around landing-page composition, social-variant fan-out, and competitor-screenshot extraction (Section c).
---
## (c) Community patterns
### chatprd.ai landing-page workflow
Community pattern from `https://chatprd.ai` (cited in `research/03`): a four-stage landing-page production flow optimised for Claude Design:
1. **Brief stage** — define the audience, the value prop, the one CTA, the proof points. Output: text document, not in Claude Design yet.
2. **Outline stage** — translate the brief into a section-by-section landing-page outline. Hero, problem, solution, features (3-grid or 4-grid), proof (logos / quotes / numbers), pricing or single-CTA, FAQ, footer. Output: text outline.
3. **Visual stage** — brief Claude Design from the outline using layers 1-5. First turn produces the landing page; iteration tightens.
4. **Variant stage** — once the master landing page works, generate variants for A/B testing (different hero, different proof-point ordering, different CTA framing) using the variant-fan-out pattern below.
The four-stage workflow separates copy decisions from visual decisions, which lets the operator iterate each independently. The community-documented failure mode is briefing visual + copy together in one prompt — the model conflates the two and produces a generic landing page.
### Sagnik Bhattacharya variant-fan-out for social
Community pattern from `https://sagnikbhattacharya.com/blog/claude-design` (cited in `research/03`): for social-format collateral (Instagram square, LinkedIn rectangle, Twitter / X aspect), generate N variants in parallel rather than sequentially. The brief pattern:
```
Generate 6 variants of the [campaign] creative, sized for [format
spec]. Across the 6:
- Vary the headline framing (problem-led, solution-led,
proof-led)
- Vary the visual hierarchy (text-dominant, image-dominant,
balanced)
- Vary the color emphasis (accent-dominant, monochrome,
high-contrast)
- Keep the value prop, audience, and CTA identical across all 6
Output as 6 distinct artifacts I can A/B test.
```
The pattern produces a campaign-set in one chat turn rather than six iterations.
### Competitor-screenshot visual-reference extraction
Community pattern (cited in `research/03`): when the operator has a competitor's marketing page that visually achieves what they want, screenshot it and brief Claude Design with the screenshot as a visual reference, paired with an explicit "do not copy; extract the visual-language principles" instruction:
```
The attached screenshot shows [competitor]'s landing page. Do NOT
copy the structure, the copy, or the layout. DO extract the
visual-language principles:
- typography character (named family + scale + weights)
- color temperature and palette structure
- visual density (how much whitespace, how many elements per fold)
- motion language (if visible from the screenshot or apparent from
the brand)
- overall aesthetic family (named with concrete reference)
Apply those principles to our landing page, which has a fundamentally
different structure, copy, and CTA flow. Output our landing page
respecting the extracted visual language but original in structure.
```
The pattern is high-leverage when the operator has a clear visual reference but cannot articulate it in DESIGN.md form. The risk: too-literal copying produces a derivative-feeling artifact. Brief the "extract, do not copy" constraint explicitly.
### Slop-fingerprints warning amplified
Marketing collateral is the surface where AI-slop fingerprints are most punishing. The teal gradient + serif headline + blinking status dot + container-on-container + glassmorphism pattern is recognisable across many AI-generated landing pages. Audiences pattern-match on it and discount the artifact. Layer 3 negative constraints apply with extra weight:
```
Negative constraints — do not produce any of:
- Teal-to-blue or teal-to-green gradients
- Serif headline on sans-serif body (unless explicitly briefed for
editorial direction)
- Blinking / pulsing status indicators ("Live", "New", "Updated")
- Container-on-container layouts (card-inside-card)
- Glassmorphism or neumorphism on any element
- Generic "modern SaaS landing page" template defaults
- Stock-photo abstract gradient hero imagery
```
---
## (d) Critical caveats
### Brand fidelity is the dominant failure mode
Marketing collateral without a tight DESIGN.md anchor produces generic output. The brand DESIGN.md is essentially mandatory — see `../02-design-md.md` for the extractor pattern when the operator does not already have one. Validate brand fidelity at every iteration: typeface, color palette, voice (tone of copy), visual density. Brand drift on marketing collateral is more visible to the audience than brand drift on internal artifacts.
### A/B testing requires more than aesthetic variation
The variant-fan-out pattern produces aesthetic variations. For meaningful A/B testing, the variants should test specific hypotheses (does problem-led headline outperform solution-led? does image-dominant outperform text-dominant?) rather than test generic aesthetic variation. Brief the hypotheses explicitly.
### Export-to-image for social formats
Social-format collateral typically exports as PNG or JPG (Claude Design produces HTML; the operator screenshots at the target dimensions). The export is lossy for hover states, interactive elements, and motion. Brief the static state explicitly when the destination is image:
```
The destination for this creative is a static PNG/JPG export. Generate
the static state only. No hover states, no interaction logic, no motion.
```
---
## (e) One worked prompt — layers 1 + 3 composed, four-stage landing-page flow
Goal: a landing page for a developer-tools SaaS product, audience is senior engineers evaluating dev tools.
```
Goal: A landing page for "ObserveAPI", a developer-tools SaaS product
for API observability. The goal: convert senior-engineer
visitors to free-trial signups.
Layout: Hero (above-fold), problem (one paragraph + 3 pain points
as labelled rows), solution (one paragraph + product
screenshot), features (3-grid), proof (3 customer logos +
one quote + one named metric), pricing (single tier + free
trial CTA), FAQ (4 questions), footer (links + secondary
CTA)
Content: Real product positioning, real customer logos (placeholder
names but realistic shapes), real metric numbers, real
FAQ content. No lorem ipsum.
Audience: Senior engineers, ages 30-50, evaluating dev tools,
allergic to marketing fluff, allergic to AI-generated
landing page fingerprints, will scroll fast and bounce
fast unless the headline lands
Stage 1 (brief): Audience = senior engineers, value prop = "the
first API observability tool that doesn't require
you to instrument anything", CTA = "Start free
trial", proof points = 3 customer logos + one
quote + one metric
Stage 2 (outline): use the layout above
Stage 3 (visual): use the brief below
Stage 4 (variants): defer to next session
Aesthetic family: developer-confident — like Linear's marketing site
meets the editorial confidence of The New York Times
opinion section. No flourish, every claim earns its
place, headline is a claim not a tagline.
Color palette (CSS hex):
--color-bg: #FAFAF8
--color-surface: #FFFFFF
--color-muted: #6B6B6B
--color-fg: #2A2A2A
--color-ink: #0A0A0A
--color-accent: #2D6356
Typography: Söhne (preferred — concrete-named) or Inter Variable;
modular scale 1.333; weight palette 400 body / 600
emphasized / 700 hero headline
Corner radius: 4px on buttons and cards; full-bleed hero
Motion: transition: all 160ms ease-out on hover; no auto-play motion
anywhere
Density: comfortable above the fold (5 elements max), denser below
the fold (features grid, proof, FAQ)
Surface: flat — single subtle border or single subtle shadow on
cards, never both
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, Space Grotesk as primary typeface
- Teal-to-blue or teal-to-green gradients
- Serif headline on sans-serif body
- Blinking / pulsing status indicators
- Container-on-container layouts
- Glassmorphism, neumorphism
- Generic "modern SaaS landing page" defaults
- Stock-photo abstract gradient hero imagery
- Three-column feature grid with icon + headline + line (default
fingerprint)
- Centered-hero with single CTA (default fingerprint)
If you find yourself defaulting to any of these, stop and ask me to
clarify before continuing.
Brand DESIGN.md: ObserveAPI brand kit attached as project asset.
Reference it at every section.
```
Expected follow-up turns:
1. Turn 1: outline review (Stage 2)
2. Turn 2: visual generation (Stage 3) at the brief above
3. Turn 3: layer-4 dimension refinement (typography modular scale, semantic color roles, motion easing)
4. Turn 4: layer-5 grading-criteria weighting (functionality 0.4, craft 0.3, design quality 0.2, originality 0.1 — landing pages weight functionality high)
5. Turn 5+: Tweak panel for spacing and density adjustments
6. Variant fan-out (Stage 4) in next session, against the approved master
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Anthropic's frontend-design skill (closest adjacent Anthropic source; Design-Thinking Framework, AI-slop avoid-list, four design dimensions)
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list (amplified for marketing collateral)
- `https://chatprd.ai` — community four-stage landing-page workflow
- `https://sagnikbhattacharya.com/blog/claude-design` — community variant-fan-out pattern for social formats
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading criteria (composed for marketing collateral)
Re-research trigger: Anthropic publishing a marketing-collateral tutorial; community four-stage workflow drifting; new slop-fingerprint patterns emerging in the AI-generated landing-page corpus; competitor-screenshot extraction patterns evolving.

168
plugins/claude-design/skills/claude-design-facilitator/references/presets/one-pagers.md
View file

@ -1,168 +0,0 @@
# Preset: one-pagers
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
Evidence grade: Community-only — Anthropic publishes no per-preset prompt patterns for this preset as of 2026-05-16.
Anthropic names `one-pagers` in the launch enumeration at `https://anthropic.com/news/claude-design-anthropic-labs` but does not publish a dedicated tutorial, support article, or canonical prompt set for it. The patterns below come from community practitioners — Substack walkthroughs, blog posts, newsletter pieces — with full attribution. Treat them as field-tested but not Anthropic-authoritative.
---
## (a) What this preset is
Anthropic launch post one-sentence description: a one-pager is a single-screen artifact for memos, summaries, leave-behinds, executive briefs, or single-page deliverables. The destination is typically PDF or print.
Distinguishing properties:
- Single page — no multi-screen navigation, no scrolling sections that imply continuation
- High information density compared to a slide
- Self-contained narrative — reader does not need surrounding context
- Often delivered as a leave-behind after a meeting or as a one-shot brief
---
## (b) Why Anthropic published no per-preset guidance
The launch enumeration treats one-pagers as a destination shape rather than a generation mode requiring distinct prompt patterns. The Goal / Layout / Content / Audience framework (`../01-prompt-fundamentals.md` Layer 1) and the five-layer stack apply directly — Layout becomes single-page structure, Content becomes the dense information payload, Audience tightens the tone.
Community practitioners have converged on patterns that constrain the one-pager preset more tightly than the generic stack does (Sections c and d).
---
## (c) Community patterns
### Word-count cap per block
Community pattern from `https://sagnikbhattacharya.com/blog/claude-design` (cited in `research/03`): cap the word count per layout block in the brief. The mechanism — Claude Design defaults to verbose prose when block content is unspecified, and one-pagers fail when any block runs long. The convergent caps from community practice:
- Title block: 8 words max
- Subtitle: 15 words max
- Body paragraph: 60 words max
- Bullet item: 12 words max
- Callout box: 25 words max
Brief the caps explicitly in the prompt — the model otherwise produces blocks 2-3x longer than the operator wants.
### Above-the-fold density limit
Community pattern from `https://newsletter.victordibia.com` (cited in `research/03`): cap the number of distinct elements visible in the top half of the one-pager. Convergent limits:
- Maximum 5 distinct visual elements above the fold (counting title, subtitle, one body block, one visual, one callout = 5)
- Maximum 3 colour roles visible above the fold (typically: ink for title, fg for body, accent for one emphasis)
- Maximum 2 typographic weights above the fold (typically 700 title, 500 body)
The brief encodes these as explicit constraints:
```
Above the fold (top half of the page), no more than 5 distinct visual
elements, no more than 3 color roles, no more than 2 typographic
weights. Density below the fold can scale up.
```
### Real-data injection over lorem ipsum
Same pattern as `designs.md` and `prototypes.md`: use realistic placeholder content. For one-pagers specifically, this matters more — a one-pager is typically read once and discarded; if the content reads as placeholder, it loses the reader.
---
## (d) Critical caveats
### Density-versus-readability trade-off
One-pagers are constrained by physical reading mechanics — the operator can pack a lot into one page, but each element added reduces the reader's attention to every other element. The brief should weight density-vs-readability explicitly:
```
Optimise for the reader's ability to extract the takeaway in 30 seconds
of scanning. If a block requires more than 30 seconds of focused reading
to extract the takeaway, it does not belong on this one-pager.
```
### Export to PDF preserves layout; export to other formats may not
PDF is the canonical one-pager export. HTML standalone works. PPTX is awkward for one-pagers (PPTX assumes deck format, not single-page format). Code-handoff is rare for one-pagers but works.
### Anthropic AI-slop avoid-list still applies
Layer 3 negative constraints (`../01-prompt-fundamentals.md`) apply with full force on one-pagers — the dense information context does not exempt the artifact from the avoid-list. Inter, Roboto, Arial, purple gradients on white, generic-modern defaults all degrade the one-pager.
---
## (e) One worked prompt — layers 1 + 3 composed (Layer 2a is preset-optional)
Goal: an executive one-pager summarizing a project's Q1 status, audience is VP of Engineering.
```
Goal: A single-page executive summary of the platform team's Q1 2026
delivery, reliability, and Q2 themes. Designed to be scanned in
30 seconds and absorbed in 3 minutes.
Layout: Single-page A4 portrait. Top quarter: title + headline takeaway
+ 3 KPI numbers in a row. Middle half: 3 short body paragraphs
(one per: delivery, reliability, Q2 themes). Bottom quarter:
callout box with the one explicit ask + signature/contact block.
Content: Real KPI numbers (% completion, MTTR minutes, uptime %); real
body content (no lorem ipsum); explicit ask is one sentence;
contact block names the person + email
Audience: VP of Engineering, scanning between meetings, needs the
takeaway and one ask, will dive into details only if the
takeaway warrants it
Word-count caps (community pattern from
https://sagnikbhattacharya.com/blog/claude-design):
- Title block: 8 words max
- Subtitle / headline takeaway: 15 words max
- Body paragraph: 60 words max
- Bullet item: 12 words max
- Callout box: 25 words max
Above-the-fold density limit (community pattern from
https://newsletter.victordibia.com):
- Maximum 5 distinct visual elements above the fold
- Maximum 3 color roles visible above the fold
- Maximum 2 typographic weights above the fold
Aesthetic family: editorial-confident — terse, signal-dense, no flourish
Color palette (CSS hex):
--color-bg: #FAFAF8
--color-surface: #FFFFFF
--color-muted: #6B6B6B
--color-fg: #2A2A2A
--color-ink: #0A0A0A
--color-accent: #3D5C8A
Typography: Söhne or Inter Variable; modular scale 1.250; weight palette
500 body / 700 headings
Corner radius: 4px on the callout box only; rest is flat
Motion: none (one-pager is static)
Density: dense (8mm margins, 4mm gutters)
Surface: flat — no shadows
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, or Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Card-style metric tiles with shadows
- Centered-title-and-subtitle generic header
- Pulse / breathing animations (this is a static one-pager)
- Generic "executive summary template" defaults
Optimise for the reader's ability to extract the takeaway in 30 seconds
of scanning. If a block requires more than 30 seconds of focused reading
to extract the takeaway, it does not belong on this one-pager.
```
Expected follow-up turns:
1. Turn 2: tighten word counts if any block ran over cap
2. Turn 3: refine callout-box positioning if it competes with the headline takeaway
3. Turn 4+: Tweak panel for spacing scale and density adjustments
4. Export to PDF; visual-audit at 100% zoom and at print size
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration, one-sentence description
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — GLCA framework (composed in this preset)
- `https://sagnikbhattacharya.com/blog/claude-design` — community pattern for word-count caps per block
- `https://newsletter.victordibia.com` — community pattern for above-the-fold density limits
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list (composed)
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Design-Thinking Framework reference
Re-research trigger: Anthropic publishing a dedicated tutorial for one-pagers; community word-count caps drifting; new one-pager-specific community pattern emerging.

198
plugins/claude-design/skills/claude-design-facilitator/references/presets/pitch-decks.md
View file

@ -1,198 +0,0 @@
# Preset: pitch-decks
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
**Evidence grade:** Community-only — Anthropic publishes no per-preset prompt patterns for this preset as of 2026-05-16.
Evidence grade: Community-only — Anthropic publishes no per-preset prompt patterns for this preset as of 2026-05-16.
Anthropic names `pitch-decks` in the launch enumeration at `https://anthropic.com/news/claude-design-anthropic-labs` but publishes no dedicated tutorial. **Critical caveat upfront:** community practitioner `https://moda.app/blog/claude-design-for-pitch-decks` documents an explicit recommendation against using Claude Design for external/investor pitch decks when PPTX is the required delivery format — see Section (d).
---
## (a) What this preset is
Anthropic launch post one-sentence description: `pitch-decks` covers investor pitches, external partner proposals, and any high-stakes presentation format that needs to look polished. The preset distinguishes itself from the more general `slides` preset by audience — external rather than internal — and by typical destination — PPTX or PDF rather than HTML.
The distinguishing question vs `slides`: **is the audience an external investor or external partner where the deck represents the company's positioning?** Yes → `pitch-decks`. Internal audience → `slides`.
---
## (b) Why Anthropic published no per-preset guidance
Anthropic likely treats pitch-decks as a high-stakes specialisation of `slides` rather than a fundamentally distinct generation mode. The `slides` tutorial at `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` covers the prompt patterns; the `pitch-decks` preset inherits those patterns and adds the audience-stakes layer.
Community practitioners have converged on patterns specific to pitch-deck production (Section c). The most important community contribution, however, is the PPTX-export caveat (Section d) — the failure mode is severe enough that the default recommendation diverges from `slides`.
---
## (c) Community patterns
### Sagnik Bhattacharya's 10-slide template
Community pattern from `https://sagnikbhattacharya.com/blog/claude-design` (cited in `research/03`): the convergent 10-slide pitch-deck template for B2B SaaS pitches:
1. Title — company name, one-line positioning, tagline
2. Problem — who has it, what it costs them, how acute
3. Solution — what we built, one-sentence value prop
4. Market — TAM / SAM / SOM (sized realistically)
5. Product — 2-3 screenshots or visual demos
6. Business model — how we charge, ACV ranges, GTM motion
7. Traction — revenue, growth rate, named customers
8. Team — founders + key hires, why this team for this problem
9. Competition — competitive map (4-quadrant or named comparisons)
10. Ask — funding round size, use of funds, timeline
The template is community-converged, not Anthropic-published. It composes with Anthropic's `slides` tutorial patterns from `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks`.
### MindStudio per-slide micro-prompts
Community pattern from MindStudio (cited in `research/03`): rather than briefing the full pitch deck in one prompt, micro-prompt each slide individually. The pattern produces tighter per-slide narrative because each slide gets dedicated attention.
The micro-prompt pattern (per slide):
```
Generate slide N of the pitch deck. This slide does one job:
[the slide's job — e.g., "convince the audience that the problem is
acute by quantifying customer cost"].
Visual elements: [specific to this slide — e.g., "one large number
showing annual cost, two supporting smaller numbers, one explanatory
sentence"].
Constraints from DESIGN.md: [reference the project's DESIGN.md].
Do not include filler — every element on this slide must support the
one job.
```
Walk through slides 1-10 sequentially.
### Outline-first scaffolding (composed from `slides.md`)
The outline-first pattern from `slides.md` Section (d) applies: brief the deck as an outline first (turn 1), then expand to full slides (turn 2-N).
---
## (d) Critical caveats
### PPTX export trap — explicit recommendation against external pitch decks
Community-documented at `https://moda.app/blog/claude-design-for-pitch-decks` (cited in `research/03`) and `https://claudedesign.substack.com`: when an HTML-rendered pitch deck is exported to PPTX, richly-styled text can flatten to images. PowerPoint loses the editability — the text becomes a rasterised picture.
For internal slide decks (audience tolerates some export friction), the operator can mitigate by keeping typography simple. For external pitch decks (audience expects polish, may want to add their own annotations or edit the deck), this failure mode is severe enough that the community recommendation is:
> Do not use Claude Design for external/investor pitch decks where PPTX export is the required delivery format. Use HTML standalone or PDF if Claude Design is required; otherwise produce the deck in PowerPoint or Keynote directly.
This plugin surfaces the recommendation but does not refuse to operate. The operator may have a reason to proceed (HTML acceptable, PDF acceptable, the PPTX text-as-text survival is verified to be acceptable for their specific styling). When proceeding, validate PPTX export early — generate slide 1 fully, export to PPTX, verify text-as-text survival, then commit to the deck.
### Audience-stakes asymmetry
A pitch deck for a $50M Series C carries different stakes than a pitch deck for a $500K seed extension. The operator's tolerance for export imperfection scales with the dollar amount on the line. Default conservatively — when in doubt about whether the export will survive, treat the deck as high-stakes.
### Slop-fingerprints warning amplified
Layer 3 negative constraints apply with extra weight on pitch decks. Investors see many decks; AI-slop fingerprints (purple gradients, generic three-column structure, Inter typography, centered-hero defaults, glassmorphism, neumorphism) signal that the deck is templated and the team did not invest care. The brief should over-specify the negative constraints.
---
## (e) One worked prompt — layers 1 + 3 composed, slide-by-slide micro-prompt pattern
Goal: a 10-slide investor pitch deck for a B2B SaaS observability product, audience is Series A investors.
```
PRECONDITION: Before generating any slide, render slide 1 fully and
export to PPTX. Verify text-as-text survival. If text flattens to
images, switch destination to HTML standalone or PDF and notify me
before continuing.
Goal: A 10-slide Series A pitch deck for a B2B SaaS observability
product
Layout (outline — per Sagnik Bhattacharya's 10-slide template at
https://sagnikbhattacharya.com/blog/claude-design):
1. Title
2. Problem
3. Solution
4. Market (TAM / SAM / SOM)
5. Product (2-3 visual demos)
6. Business model
7. Traction (revenue, growth, named customers)
8. Team
9. Competition
10. Ask
Content: Real numbers, real customer names, real founder names, real
competitive references. No lorem ipsum, no placeholder logos.
Audience: Series A investors at top-tier funds, ages 35-55, see 50+
decks per quarter, allergic to template fingerprints
Aesthetic family: editorial-confident — like Andreessen Horowitz pitch
decks meets Linear's design language. Authoritative,
no flourish, every visual element earns its place.
Color palette (CSS hex):
--color-bg: #FAFAF8
--color-surface: #FFFFFF
--color-muted: #6B6B6B
--color-fg: #2A2A2A
--color-ink: #0A0A0A
--color-accent: #1A3552
Typography: Söhne (preferred — concrete-named) or Inter Variable;
modular scale 1.333; weight palette 400 body / 600
emphasized / 700 slide titles
Corner radius: 0 (full-bleed slides), 4px on any inline container
Motion: none on static slides; ease-out 240ms on slide transitions
Density: comfortable — one job per slide, generous spacing
Surface: flat — full-bleed, no shadows
Slide composition rules:
- Each slide does one job
- Slide titles are claims, not topics ("$2.4B addressable market"
not "Market")
- Body text is 2 lines max per slide
- One number, chart, or visual element per slide max
- Speaker notes carry depth; slides carry the takeaway
Per-slide micro-prompt pattern (MindStudio, cited in research/03):
Generate slide N. Its one job: [name the job].
Visual elements: [specific to slide].
No filler — every element supports the one job.
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Three-column feature grid as a default slide structure
- Centered-title-and-subtitle on every slide
- Glassmorphism, neumorphism, gradient hero backgrounds
- Pulse / breathing animations or fly-in transitions
- Generic "investor pitch deck template" defaults
- Stock-photo placeholder imagery
If you find yourself defaulting to any AI-slop pattern (per
https://claude.com/blog/improving-frontend-design-through-skills),
stop and ask me to clarify before continuing.
Slop-fingerprints warning is amplified — investors recognise template
patterns. Over-specify the aesthetic to push the deck out of default
neighbourhood.
```
Expected follow-up turns:
1. Turn 1 (precondition): slide 1 + PPTX export validation. If text flattens, switch destination.
2. Turn 2: 10-slide outline approval
3. Turn 3-12: per-slide micro-prompt for each slide
4. Turn 13: full-deck render, cross-slide consistency check
5. Turn 14: Tweak panel for spacing and density adjustments
6. Export and visual-audit at full deck level
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration
- `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` — Anthropic's slides tutorial (composed for pitch-decks)
- `https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint` — PowerPoint-mode conventions (relevant for PPTX export)
- `https://moda.app/blog/claude-design-for-pitch-decks` — community-documented PPTX export caveat (load-bearing)
- `https://claudedesign.substack.com` — community pattern reinforcing PPTX export caveat
- `https://sagnikbhattacharya.com/blog/claude-design` — community 10-slide pitch-deck template
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list (amplified for pitch decks)
Re-research trigger: Anthropic publishing a pitch-decks-specific tutorial; PPTX export behaviour changing (text-as-text survival improving or worsening); community 10-slide template drifting; new investor-deck pattern emerging.

225
plugins/claude-design/skills/claude-design-facilitator/references/presets/prototypes.md
View file

@ -1,225 +0,0 @@
# Preset: prototypes
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
**Evidence grade:** Anthropic-documented + community-validated
**Captured-on date:** 2026-05-16
The `prototypes` intent preset generates interactive product flows for usability testing, design review, and stakeholder demos. Output is multi-screen HTML with working state transitions, clickable navigation, and per-state visual treatments. The preset is documented by Anthropic in a dedicated tutorial.
---
## (a) What this preset is
Anthropic frames `prototypes` (launch post `https://anthropic.com/news/claude-design-anthropic-labs`) as the preset for product flows that need to behave like a real product, not just look like one. The distinguishing property vs `designs`: interaction state. Prototypes have hover states, active states, click-through transitions, multi-screen navigation, and per-state visual treatments.
The dedicated tutorial is `https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux`. It is the load-bearing source for this preset.
Output is HTML + React + inline CSS + JS (the JS makes the interactions work). Exportable to Code-handoff (engineering takes the working interaction logic forward) or HTML standalone (runs in a browser without Claude Design).
---
## (b) When to use it
Pick `prototypes` when the goal is interactive validation. The decision matrix:
| Operator goal | Preset |
|---------------|--------|
| Feature flow for usability testing (5-user study) | **prototypes** |
| Internal tool demo for stakeholder review | **prototypes** |
| A-B comparison of two design directions in working form | **prototypes** |
| Onboarding flow walkthrough for new hire training | **prototypes** |
| Static design exploration (no interaction needed) | designs |
| Slide deck for a meeting | slides |
If the operator describes the artifact in terms of "user clicks here, then sees this", they want `prototypes`. If they describe it in terms of "screen with these regions", they may want `designs`.
---
## (c) Anthropic-published prompt patterns
The Anthropic tutorial `https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux` publishes nine canonical prompt patterns across four families:
### Family 1 — Feature prototyping (4 verbatim canonical prompts)
For new feature flows where the operator needs to test interaction logic. The patterns cover: a sign-in / sign-up multi-step flow; a checkout / payment flow with form validation states; a settings / preferences flow with toggles and selects; a search / filter flow with result-state transitions. Each prompt names entry point, success path, error states, and edge cases.
Refer to the tutorial for the verbatim prompt text — Anthropic publishes the exact wording, and this plugin cites it by URL rather than copying it (per the brief's source-quality rule and the Apache-2.0/MIT compatibility note in `../04-handoff-and-scope.md`).
### Family 2 — Design review and A-B comparison (2 verbatim canonical prompts)
For prototyping when the goal is to compare two design directions side-by-side or in turn. The verbatim Anthropic comparison-prompt pattern:
```
Show me three different layouts for [feature]. For each:
- Visual direction (named, with concrete reference)
- Interaction model (where the user starts, where they end up)
- One-line rationale tying it to the audience and goal
Once I pick one, generate the full interactive flow.
```
Use this for A-B-C exploration before committing to a direction. The pattern composes with layer 2b (propose-options-before-building) from `../01-prompt-fundamentals.md`.
### Family 3 — User-flow scaffolding (1 verbatim canonical prompt)
For mapping a multi-screen user journey. The pattern names the entry context, the screens in sequence, the decisions at each screen, and the success path vs the error paths. The output is a clickable multi-screen prototype with the navigation logic baked in.
### Family 4 — Internal tools (2 verbatim canonical prompts)
For internal-tooling prototypes — admin panels, content-moderation queues, customer-support consoles. The pattern emphasises dense interfaces, keyboard-driven navigation, and minimal aesthetic flourish. The patterns differ from external-product prototypes in tone and density.
### Component-naming clarity, decision documentation, edge-case flagging
The tutorial also publishes three transversal recommendations Anthropic asks operators to apply across all four families:
- **Component-naming clarity** — name components in the brief so the generated artifact's component spec is engineering-handoff-ready (research/03 D2). Generic names like "Button1" produce generic component specs.
- **Decision documentation** — ask Claude Design to document its design decisions inline (the PM-annotated notes feature) so the engineering handoff carries rationale, not just visuals.
- **Edge-case flagging** — explicitly request that Claude Design flag interaction edge cases (empty state, loading state, error state, offline state, permission-denied state). The model defaults to happy-path-only without this directive.
---
## (d) Community uplift
Three community-converged patterns extend Anthropic's published material for `prototypes`.
### Request every state upfront
Community pattern (`research/03`): explicitly request every interaction state in the first prompt rather than discovering missing states across iterations. The verbatim community phrasing:
```
For every interactive element in this prototype, generate:
- default state
- hover state
- active / pressed state
- focused state (keyboard navigation)
- disabled state
- loading state (if the element triggers async work)
- error state (if the element can fail)
Render every state visibly somewhere in the prototype — either inline
or in a dedicated state-catalogue page.
```
This catches the failure mode where the operator does not notice a missing state until a usability test surfaces it.
### Real-data injection over lorem ipsum
Same pattern as the `designs` preset, more important here: prototypes used in usability testing fail when the content is obviously fake. Test participants react to lorem ipsum and stop engaging with the flow. Use realistic content even when the prototype is throwaway.
### Explicit motion timing and easing
MindStudio community walkthrough (cited in `research/03`): name the easing curve and the duration explicitly for prototypes that include any motion. Default motion is the largest source of "feels like AI" in a prototype. The community-converged baselines for product prototypes:
- Hover transitions: `transition: all 160ms ease-out`
- Modal / drawer enter: `cubic-bezier(0.16, 1, 0.3, 1) 240ms`
- Modal / drawer exit: `cubic-bezier(0.7, 0, 0.84, 0) 180ms`
- Page transitions: `ease-out 280ms`
---
## (e) Critical caveats
Three caveats specific to `prototypes`.
### Interactive state count compounds context
A prototype with 10 components × 7 states each = 70 distinct visual treatments in one artifact. Each treatment consumes context. Claude Design quality drops faster on prototypes than on `designs` for the same number of screens. Session-break heuristics (`../03-iteration-and-session.md`) apply with extra weight.
### Test in target browsers before stakeholder review
The standalone HTML export runs the prototype's JavaScript locally. Edge-case JavaScript (touch handlers, IntersectionObserver, ResizeObserver) does not always work the same across browsers. Test in Chrome + Safari + Firefox before sharing with stakeholders. If you target mobile usability testing, test on actual mobile devices, not just a browser DevTools mobile-emulation viewport.
### Multi-screen exports — bundle in one export
The token-cost trap in `../04-handoff-and-scope.md` Section 6 applies most strongly to multi-screen prototypes. Bundle all screens in one export turn; do not export screen-by-screen.
---
## (f) One end-to-end worked prompt — layers 1 + 2a + 3 composed
Goal: a multi-step onboarding flow for a new SaaS analytics product, audience is small-business operators.
```
Goal: An interactive 5-step onboarding flow for new users of a SaaS
product. The flow: welcome → data-source connection → metric
selection → notification preferences → first-dashboard generation
Layout: Single-column centered, fixed step indicator at top, primary
CTA at bottom of each step, secondary "back" link to top-left
Content: Real product-facing copy (no lorem ipsum); step indicator
labels match the 5 steps verbatim; each step has a one-line
description below the step name; CTAs use action-verb naming
("Connect your data", "Select your metrics", etc.)
Audience: First-time users of a SaaS product, B2B small-business
operators, ages 30-55, comfortable with software but not
power-users
Aesthetic family: warm-confident — like Linear's onboarding, like
Notion's first-run, like Vercel's CLI prompts.
Approachable but tight; never playful.
Color palette (CSS hex):
--color-bg: #FAFAF8
--color-surface: #FFFFFF
--color-muted: #6B6B6B
--color-fg: #2A2A2A
--color-ink: #0A0A0A
--color-accent: #2D6356
--color-accent-hover: #1F4A41
--color-success: #2D6356
--color-warning: #C89B3F
--color-error: #B23A48
Typography: Söhne (preferred) or Inter Variable; modular scale 1.250;
weight palette 400 body / 500 emphasized / 600 headings
Corner radius: 6px on cards, 4px on buttons and inputs
Motion: transition: all 160ms ease-out on hover; cubic-bezier(0.16, 1,
0.3, 1) 240ms on step transitions
Density: comfortable (44px touch targets, 16px card padding)
Surface: subtle depth — 1px border + very subtle shadow on cards
Interaction states (render every one for every interactive element):
default, hover, active, focused, disabled, loading, error
Multi-screen requirements:
- Step 1: welcome — value prop in 2 sentences + Get Started CTA
- Step 2: data-source connection — list of 6 integrations with
connect buttons, hover states show "Connect" tooltip
- Step 3: metric selection — multi-select chip interface with 12
metric options, selection persists across step navigation
- Step 4: notification preferences — three toggle rows, with help-text
below each toggle
- Step 5: first-dashboard generation — loading state for 4-6 seconds,
then success state with "View Dashboard" CTA
Edge cases to flag:
- Step 2 connection failure (network error visible)
- Step 3 zero metrics selected (CTA disabled, help-text appears)
- Step 5 generation timeout (recovery CTA appears)
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, or Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Centered-hero with single CTA (this is sequenced flow, not landing
page)
- Bouncy spring easing on hover
- Pulse animations on idle elements
- Generic "modern SaaS onboarding" template defaults
```
Expected follow-up turns:
1. Turn 2: refine motion easing if step transitions feel sluggish or jumpy
2. Turn 3: add layer 5 grading criteria (functionality 0.5, craft 0.3, design quality 0.2, originality 0)
3. Turn 4+: Tweak panel for density and color-temperature adjustments
4. Usability test surfaces missing states → iterate states via comments
5. Export bundle for engineering handoff once stakeholders sign off
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration
- `https://claude.com/resources/tutorials/using-claude-design-for-prototypes-and-ux` — verbatim canonical prompts (4 families, 9 prompts) + component-naming clarity + decision documentation + edge-case flagging recommendations
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — GLCA framework
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading criteria
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Design-Thinking Framework, AI-slop avoid-list
Re-research trigger: Anthropic updating the prototypes tutorial; new canonical prompt family added; component-naming-clarity / decision-documentation / edge-case-flagging recommendations materially revised.

237
plugins/claude-design/skills/claude-design-facilitator/references/presets/slides.md
View file

@ -1,237 +0,0 @@
# Preset: slides
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
**Evidence grade:** Anthropic-documented + community-validated
**Captured-on date:** 2026-05-16
The `slides` intent preset generates presentation decks — internal stakeholder updates, executive roadmaps, customer briefings, partner proposals, all-hands meetings. Output is HTML deck with per-slide layouts, optionally exportable to PPTX (with caveats — see Section e).
---
## (a) What this preset is
Anthropic launch post (`https://anthropic.com/news/claude-design-anthropic-labs`) names `slides` as a destination-shaped preset: the artifact assumes the slide-deck format, not the dashboard / one-pager / prototype format. Output renders in the Claude Design canvas as a slide-by-slide thumbnail strip plus the active slide in full view.
Two Anthropic primary sources ground this preset:
- The dedicated tutorial `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` publishes five verbatim canonical prompts (Section c) and the slide-deck composition framework.
- The PowerPoint-mode article `https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint` publishes the PPTX export conventions and the template-respecting guidance: Claude reads the slide master, layouts, fonts, and color scheme of an uploaded PPTX template and produces output that respects them.
The two sources compose: the tutorial covers the prompt patterns, the PowerPoint-mode article covers the export discipline.
---
## (b) When to use it
Pick `slides` when the destination is a presentation surface. The decision matrix:
| Operator goal | Preset |
|---------------|--------|
| Internal team update / project review | **slides** |
| Customer-prep briefing for a sales call | **slides** |
| Executive roadmap or quarterly business review (Q1/Q2/Q3/Q4 results) | **slides** |
| Partner proposal / co-development pitch | **slides** |
| All-hands or company-wide announcement | **slides** |
| External investor pitch deck | **pitch-decks** (separate preset — see preset file for the PPTX trap) |
| Single-page memo / one-pager | one-pagers |
The distinguishing question vs `pitch-decks`: **is the audience internal or external?** Internal → `slides`. External investor → `pitch-decks` (with explicit caveat about PPTX export, see `pitch-decks.md`).
---
## (c) Anthropic-published prompt patterns
The Anthropic tutorial `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` publishes five verbatim canonical prompts:
### Pattern 1 — Q1 results deck
For quarterly business review decks (Q1 / Q2 / Q3 / Q4 results). Pattern names the metrics in priority order, the audience seniority level, the narrative arc (where we started, what changed, where we are, what's next), and the supporting visualisations (charts, tables, callout numbers).
### Pattern 2 — Executive roadmap
For multi-quarter roadmap decks. Pattern names the roadmap horizon (quarters or half-years), the workstreams (3-7 named tracks), the major milestones per workstream, the dependencies between workstreams, and the assumptions / risks per quarter.
### Pattern 3 — Customer-prep briefing
For sales-call preparation decks. Pattern names the customer (company + named contacts), the meeting goal, the customer's known priorities, the value-prop alignment, the proof points (case studies, metrics), and the asks / next steps.
### Pattern 4 — Partner proposal
For co-development or partnership proposals. Pattern names the proposed scope, the resourcing model, the timeline, the success metrics, the IP / licensing model, and the open questions.
### Pattern 5 — All-hands announcement
For company-wide updates. Pattern names the announcement (one sentence), the why-now context, the impact on employees, the timeline, and the resources / Q&A links.
Refer to the tutorial URL for the verbatim prompt text. This plugin cites by URL rather than reproducing Anthropic's exact wording (per the brief's source-quality rule and the Apache-2.0/MIT compatibility note in `../04-handoff-and-scope.md`).
### Template-respecting guidance (verbatim from PowerPoint-mode article)
`https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint` publishes the verbatim guidance about uploading an existing PPTX template:
> Claude reads the slide master, layouts, fonts, and color scheme of an uploaded PowerPoint template and produces output that respects them.
Practical implication: if the operator has an existing brand-compliant PPTX template, upload it as a Claude Design project asset before prompting. The generated deck will respect the template's typography, color palette, and layout conventions. Without an uploaded template, the model defaults to its convergent middle-ground deck aesthetic.
---
## (d) Community uplift
Three community-converged patterns extend Anthropic's material for `slides`.
### Outline-first narrative scaffolding
Community pattern (`research/03`): brief the deck as an outline first (turn 1: produce the slide-by-slide outline as a markdown bullet list), then expand to full slides (turn 2: generate the deck from the approved outline). This forks the conversation but produces tighter narrative arcs than briefing the full deck in one turn.
The outline-first pattern composes with Anthropic's GLCA framework (`../01-prompt-fundamentals.md` Layer 1) — Goal becomes the deck's takeaway, Layout becomes the outline, Content becomes the per-slide bullets, Audience becomes the seniority + context match.
### Single-job-per-slide constraint
Community pattern (research/03): each slide should communicate exactly one idea. Slides with two or more ideas leak comprehension. Brief the constraint explicitly:
```
Each slide does one job. If a slide is trying to communicate two ideas,
split it into two slides. The takeaway from each slide should be
nameable in one sentence.
```
### Audience translation matrix
Community pattern (research/03): brief the audience translation explicitly when the deck spans seniority levels. For example, a roadmap deck shared with both engineering leads and executive sponsors needs to translate technical decisions into business outcomes for the exec audience without losing fidelity for the engineering audience. The pattern:
```
For each slide, write two versions of the takeaway:
- The technical-detail version (for the engineering audience)
- The business-outcome version (for the executive audience)
Use the business-outcome version on the slide and the technical-detail
version in the speaker notes.
```
---
## (e) Critical caveats
Three caveats specific to `slides`.
### HTML → PPTX export is lossy for richly-styled text
Community-documented at `https://moda.app/blog/claude-design-for-pitch-decks` (cited in research/03) and `https://claudedesign.substack.com`: when the operator exports an HTML-rendered slide deck to PPTX, richly-styled text (custom typography, mixed weights, inline color variations) can flatten to images. PowerPoint loses the editability — the text becomes a rasterised picture.
The mitigation:
- If the destination is final PPTX delivery, validate the rendered PPTX text-as-text count before assuming editability survived
- If text-as-text is critical (legal review, copy-edit-after-the-fact), keep the typographic styling simple in the brief — single typeface, two weights, no inline color variation, no inline highlighting
- For the `pitch-decks` preset specifically, this caveat is severe enough that the recommendation is "do not use Claude Design for external pitch decks where PPTX is required" — see `pitch-decks.md`
### Don't trust the canvas as ground truth if destination is PPTX
The Claude Design canvas renders the deck in HTML. The PPTX export converts to PowerPoint format. Some aesthetic decisions that look correct in the canvas do not survive the export:
- Custom backgrounds with gradients can rasterize
- Inline icons positioned via CSS can shift
- Multi-column slide layouts can collapse
- Speaker-notes-equivalent annotations may not round-trip
Validate by opening the exported PPTX in PowerPoint before stakeholder delivery, especially for high-stakes decks.
### Quota burn on long decks
Multi-slide decks (10+ slides) compound context faster than single-page artifacts. The 4-screen inflection in `../03-iteration-and-session.md` applies — long decks reach the inflection within 2-3 chat turns. Plan to break the deck into outline → first 5 slides → next 5 slides if the deck is large, using the context-reset prompt between sessions.
---
## (f) One end-to-end worked prompt — layers 1 + 2a + 3 composed
Goal: a 12-slide internal-team Q1 results deck, audience is engineering leadership + cross-functional partners.
```
Goal: A 12-slide Q1 2026 results deck covering platform-team delivery,
reliability metrics, headcount and hiring, top 3 themes for Q2,
and one slide on a major incident retrospective
Layout (outline):
1. Title — "Platform team Q1 2026 results"
2. TL;DR — three bullet takeaways
3. Delivery — features shipped, % of roadmap completed
4. Reliability — uptime, MTTR, incident count
5. Latency — p95/p99 trend
6. Hiring — headcount delta, key hires, open roles
7. Top theme 1 for Q2 — name + one-sentence framing
8. Top theme 2 for Q2 — name + one-sentence framing
9. Top theme 3 for Q2 — name + one-sentence framing
10. Incident retrospective — what happened, what we learned
11. Asks — explicit asks of leadership and partners
12. Q&A / Discussion prompt
Content: Real numbers throughout — actual % completion, real MTTR
minutes, real headcount, real names for hires (or named
placeholders); each slide's takeaway nameable in one sentence
Audience: VP of Engineering, peer Eng-leadership, partner-team PMs,
partner-team Eng-leads — mixed seniority, mixed technical
depth, ages 30-55
Aesthetic family: editorial-confident — like The New York Times opinion
section meets Linear's design language. Clean,
authoritative, no flourish. Each slide reads like a
well-edited paragraph.
Color palette (CSS hex):
--color-bg: #FAFAF8
--color-surface: #FFFFFF
--color-muted: #6B6B6B
--color-fg: #2A2A2A
--color-ink: #0A0A0A
--color-accent: #3D5C8A
--color-success: #2D6356
--color-warning: #C89B3F
--color-error: #B23A48
Typography: Söhne or Inter Variable; modular scale 1.333 (perfect
fourth — slides scale up); weight palette 400 body / 600
emphasized / 700 slide titles
Corner radius: 4px on any card-like containers; slides themselves
have no corner radius (full-bleed)
Motion: none on static slides; ease-out 240ms on slide transitions
Density: comfortable — generous spacing, one job per slide
Surface: flat — full-bleed slides, no shadows, single subtle accent
line under slide title
Slide composition rules:
- Each slide does one job
- Slide titles are claims, not topics ("We shipped 87% of roadmap"
not "Roadmap delivery")
- Body text is 2-3 lines max per slide
- One number, chart, or visual element per slide max
- Speaker notes carry the depth; slides carry the takeaway
Negative constraints — do not produce any of:
- Inter, Roboto, Arial, Space Grotesk as primary typeface
- Purple gradients on white backgrounds
- Three-bullet-and-image generic slide template
- Pulse animations or fly-in transitions
- Generic "corporate deck" template defaults (centered title-and-
subtitle on every slide)
- Multi-column slides with more than two ideas per slide
If the destination is PPTX, ensure text-heavy slides keep text as text
(not rasterized). Keep typography simple to maximise text-as-text
survival in export.
```
Expected follow-up turns:
1. Turn 2: outline-first review — confirm the 12-slide structure, adjust ordering, swap titles if needed
2. Turn 3: add audience translation per slide (speaker notes vs slide takeaway)
3. Turn 4: render full deck against the approved outline
4. Turn 5+: Tweak panel for typography scale and spacing; comments for slide-by-slide refinements
5. Export validation: open PPTX in PowerPoint and audit text-as-text vs rasterized
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration
- `https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks` — verbatim canonical prompts (5 patterns), slide-deck composition framework
- `https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint` — PowerPoint-mode conventions, template-respecting guidance
- `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` — GLCA framework
- `https://moda.app/blog/claude-design-for-pitch-decks` — community-documented PPTX export caveat (cited)
- `https://anthropic.com/engineering/harness-design-long-running-apps` — design grading criteria
Re-research trigger: Anthropic updating the slides tutorial; new canonical pattern added; PowerPoint-mode conventions revised; PPTX export behaviour changing materially.

163
plugins/claude-design/skills/claude-design-facilitator/references/presets/wireframes-mockups.md
View file

@ -1,163 +0,0 @@
# Preset: wireframes-mockups
**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md
Evidence grade: Community-only — Anthropic publishes no per-preset prompt patterns for this preset as of 2026-05-16.
Anthropic names `wireframes-mockups` in the launch enumeration at `https://anthropic.com/news/claude-design-anthropic-labs` but publishes no dedicated tutorial, support article, or canonical prompt set for it. The patterns below come from community practitioners; treat them as field-tested but not Anthropic-authoritative.
---
## (a) What this preset is
Anthropic launch post one-sentence description: `wireframes-mockups` covers the spectrum from low-fidelity layout sketches (boxes, labels, structure-only) to high-fidelity mockups (visual design applied, but not interactive). The output is structural — the goal is to communicate layout, not aesthetic and not interaction.
Distinguishing properties:
- Static (not interactive) — wireframes and mockups do not have working state transitions; for interaction logic, use `prototypes`
- Low-fi or high-fi — the preset spans both ends; the operator picks via prompt
- Pre-visual-design — wireframes are often deliverables before the visual designer commits to a direction
- Iteration-cheap — wireframes are intended to be iterated quickly, so the prompt patterns lean on N-variations-first generation
---
## (b) Why Anthropic published no per-preset guidance
Wireframes occupy a niche between `designs` (visual exploration) and `prototypes` (interaction validation). Anthropic appears to treat the preset as a destination shape rather than a distinct generation mode. The Goal / Layout / Content / Audience framework (`../01-prompt-fundamentals.md` Layer 1) applies — Layout is the dominant concern, Content becomes structural labels, Audience determines fidelity level.
Community practitioners have converged on the patterns below (Section c).
---
## (c) Community patterns
### N-variations-first
Community pattern from `https://designwithai.substack.com` (cited in `research/03`): wireframes are most useful when generated in N variations and compared. Brief the model to produce N distinct layout variations in the first turn, then pick one to refine.
Convergent N values from community practice: 3 or 4 variations is the sweet spot. More than 4 dilutes the operator's attention; fewer than 3 does not surface meaningful alternatives.
The brief pattern:
```
Generate 4 distinct wireframe variations for [feature/page]. For each:
- One sentence describing the structural direction
- The wireframe itself (boxes, labels, no visual design)
After I pick one, refine that variation into a mockup with visual
design applied.
```
This composes with Layer 2b (propose-options-before-building) from `../01-prompt-fundamentals.md`.
### Wireframe vs High-Fidelity sub-preset selection
Community pattern from `https://computingforgeeks.com` (cited in `research/03`): the preset spans low-fi to high-fi, but the model behaves differently across the spectrum. Brief the fidelity level explicitly:
```
Fidelity: low-fi
- boxes with labels, no typography weights other than 500
- one color (greyscale) — bg, surface, muted, fg
- no images, no icons — represent visual elements as labelled boxes
- 8pt grid visible if helpful
OR
Fidelity: high-fi
- actual typography, full color palette, real icons, real images
- production-ready visual treatment
- no interaction logic (this is wireframes preset, not prototypes)
```
Pick one explicitly. The default-mode failure is the model producing a mid-fidelity output that satisfies neither the low-fi structural goal nor the high-fi visual-validation goal.
### The Aakashg / Nielsen "low-fi-is-deprecated" debate (flagged as unsettled)
A community debate documented across Aakash Gupta's and Jakob Nielsen's posts in 2024-2025 (cited in `research/03`) argues that AI-generated high-fi mockups have made low-fi wireframes operationally obsolete — the marginal cost of generating a high-fi mockup is now low enough that there is no reason to start with low-fi. The counter-argument: low-fi wireframes still serve a communication function (forcing reviewers to focus on structure, not aesthetic) that high-fi mockups undermine.
This plugin treats the debate as **unsettled**. The brief should pick the fidelity level deliberately, with the choice tied to the audience and the review purpose, not to a default assumption that one fidelity dominates. Flag the debate when the operator's choice seems unconsidered.
---
## (d) Critical caveats
### Aesthetic drift if starting in high-fi
When starting in high-fidelity mode, the model imports its convergent middle-ground aesthetic defaults more aggressively (because the visual decisions are within scope). Layer-3 negative constraints (`../01-prompt-fundamentals.md`) apply with extra weight on high-fi mockups.
### Iteration economy — wireframes burn turns
Each variation requested in the N-variations-first pattern costs a fraction of a turn (the model generates all N in one chat round). But subsequent refinement of the chosen variation often requires multiple turns (typography decisions, color palette, component-level styling). Budget accordingly — a wireframe-to-mockup flow can consume 4-6 turns for a single page.
### Wireframe ≠ prototype
If the operator describes user interactions ("the user clicks here, then sees this"), they want `prototypes`, not `wireframes-mockups`. Wireframes capture structure; prototypes capture behaviour. Misclassification leads to wasted turns regenerating an artifact in the wrong preset.
---
## (e) One worked prompt — layers 1 + 3 composed, N-variations-first pattern
Goal: 4 wireframe variations for a customer-onboarding page, audience is product team for review.
```
Goal: 4 distinct wireframe variations for the first page of a customer
onboarding flow. The page introduces the product, captures
essential information, and routes the customer to one of three
paths (self-serve, sales-assisted, partner-handoff).
Layout: Single page, viewport ~1440x900. Each variation lays out the
same content differently.
Content: Real placeholder content — actual headlines, actual button
labels, actual form field labels. No lorem ipsum.
Audience: Internal product team (PM, design lead, eng lead) reviewing
structure choices before committing to a direction
Fidelity: low-fi (community pattern from
https://computingforgeeks.com — fidelity affects iteration
path)
- boxes with labels, no typography weights other than 500
- greyscale only (bg, surface, muted, fg)
- no images, no icons — labelled boxes
- 8pt grid visible
N-variations-first (community pattern from
https://designwithai.substack.com):
Generate 4 distinct wireframe variations. For each variation:
- One-sentence description of the structural direction (e.g.,
"Top-down narrative — story first, paths second")
- The wireframe itself
- One-line rationale tying the structure to the audience and goal
The 4 variations should be meaningfully distinct from each other —
not minor tweaks of one base layout.
After I pick one, generate a fifth output: a refined mockup of the
chosen variation, transitioning fidelity from low-fi to medium-fi.
Negative constraints (Anthropic AI-slop avoid-list):
- Inter, Roboto, Arial, Space Grotesk as primary typeface (the
fidelity-low constraint covers most of this, but flag explicitly)
- Purple gradients (low-fi means greyscale anyway)
- Three-column feature grid as the default structural pattern
- Centered-hero with single CTA as the default
- Cookie-cutter framing
```
Expected follow-up turns:
1. Turn 1: 4 wireframe variations generated
2. Turn 2: operator picks variation, refined low-fi mockup generated
3. Turn 3: aesthetic family applied (full layer-2a brief), medium-fi mockup
4. Turn 4: layer-4 dimensions applied (typography modular scale, color palette, component stylings)
5. Turn 5+: Tweak panel for spacing and density adjustments
---
## Sources
- `https://anthropic.com/news/claude-design-anthropic-labs` — preset enumeration, one-sentence description
- `https://designwithai.substack.com` — community pattern: N-variations-first
- `https://computingforgeeks.com` — community pattern: explicit Wireframe-vs-High-Fidelity fidelity selection
- `https://claude.com/blog/improving-frontend-design-through-skills` — AI-slop avoid-list (composed for high-fi mode)
- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Design-Thinking Framework reference
Re-research trigger: Anthropic publishing a dedicated wireframes-mockups tutorial; the Aakashg/Nielsen low-fi-is-deprecated debate reaching practitioner consensus; new sub-fidelity tier surfacing in community practice.

203
plugins/claude-design/tests/test-sc1-dogfood-log.sh
View file

@ -1,203 +0,0 @@
#!/usr/bin/env bash
# test-sc1-dogfood-log.sh — Verifies SC1 (operator-attested dogfood log) in REMEMBER.md
#
# Usage:
# bash tests/test-sc1-dogfood-log.sh # missing block = WARN, exit 0
# bash tests/test-sc1-dogfood-log.sh --strict # missing block = FAIL, exit 1
#
# Expects in REMEMBER.md (plugin root, gitignored):
# - A fenced section with heading `## Dogfood log — v0.1 slides run`
# - Five mechanically-checkable fields inside the section:
# artifact_type: <preset-name from .coverage.md>
# refine_rounds: <integer>
# final_prompt:
# ```
# <non-empty prompt content>
# ```
# shipped: yes (or `shipped: equivalent`)
# comparison_to_unaided: <one sentence ending with .>
#
# REMEMBER.md is gitignored — this evidence is local-only. The script
# validates format only; the outcome judgement is operator-attested.
set -euo pipefail
LC_ALL=en_US.UTF-8
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
FAIL=0
WARN=0
pass() { printf "${GREEN} ✓ %s${NC}\n" "$1"; PASS=$((PASS + 1)); }
fail() { printf "${RED} ✗ %s${NC}\n" "$1"; FAIL=$((FAIL + 1)); }
warn() { printf "${YELLOW} ⚠ %s${NC}\n" "$1"; WARN=$((WARN + 1)); }
STRICT=false
for arg in "$@"; do
case "$arg" in
--strict) STRICT=true ;;
esac
done
echo "=== test-sc1-dogfood-log ==="
echo "Plugin root: $PLUGIN_ROOT"
echo "Strict mode: $STRICT"
echo ""
REMEMBER_FILE="$PLUGIN_ROOT/REMEMBER.md"
COVERAGE_FILE="$PLUGIN_ROOT/.coverage.md"
# -------------------------------------------------------
# Locate REMEMBER.md
# -------------------------------------------------------
if [ ! -f "$REMEMBER_FILE" ]; then
if $STRICT; then
fail "REMEMBER.md missing (strict mode — required)"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 1
else
warn "REMEMBER.md missing (advisory until operator dogfood step)"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 0
fi
fi
# -------------------------------------------------------
# Extract fenced block between dogfood heading and next H2 (or EOF)
# -------------------------------------------------------
BLOCK="$(awk '
/^## Dogfood log — v0\.1 slides run$/ { capture = 1; next }
capture && /^## / { exit }
capture { print }
' "$REMEMBER_FILE")"
if [ -z "$BLOCK" ]; then
if $STRICT; then
fail "REMEMBER.md missing dogfood block '## Dogfood log — v0.1 slides run' (strict mode — required)"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 1
else
warn "REMEMBER.md missing dogfood block (advisory until operator dogfood step)"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 0
fi
fi
pass "found '## Dogfood log — v0.1 slides run' block"
# -------------------------------------------------------
# Field 1: artifact_type — must match a preset name from .coverage.md
# -------------------------------------------------------
ARTIFACT_TYPE="$(printf '%s\n' "$BLOCK" | awk -F': *' '/^artifact_type:/ { print $2; exit }' | tr -d '[:space:]')"
if [ -z "$ARTIFACT_TYPE" ]; then
fail "artifact_type: field missing or empty"
else
# extract preset names from .coverage.md table column 1
if [ -f "$COVERAGE_FILE" ]; then
PRESETS="$(awk -F'|' '
/^\| [a-z]/ { gsub(/^ +| +$/, "", $2); print $2 }
' "$COVERAGE_FILE")"
FOUND=false
while IFS= read -r preset; do
[ -z "$preset" ] && continue
if [ "$preset" = "$ARTIFACT_TYPE" ]; then
FOUND=true
break
fi
done < <(printf '%s\n' "$PRESETS")
if $FOUND; then
pass "artifact_type='$ARTIFACT_TYPE' matches a preset in .coverage.md"
else
fail "artifact_type='$ARTIFACT_TYPE' does not match any preset in .coverage.md"
fi
else
fail ".coverage.md missing — cannot validate artifact_type"
fi
fi
# -------------------------------------------------------
# Field 2: refine_rounds — integer
# -------------------------------------------------------
REFINE_ROUNDS_LINE="$(printf '%s\n' "$BLOCK" | grep -E '^refine_rounds:[[:space:]]*[0-9]+[[:space:]]*$' || true)"
if [ -n "$REFINE_ROUNDS_LINE" ]; then
pass "refine_rounds: matches integer regex"
else
fail "refine_rounds: missing or not an integer"
fi
# -------------------------------------------------------
# Field 3: final_prompt: followed by non-empty fenced code block
# -------------------------------------------------------
HAS_FINAL_PROMPT="$(printf '%s\n' "$BLOCK" | grep -c '^final_prompt:' || true)"
if [ "$HAS_FINAL_PROMPT" -ge 1 ]; then
# check that a fenced code block (```) appears after final_prompt:
FENCE_AFTER="$(awk '
/^final_prompt:/ { found = 1; next }
found && /^```/ { fence_open = !fence_open; if (fence_open) { in_fence = 1 } else { exit } }
found && in_fence && fence_open && /./ { content_lines++ }
END { print content_lines + 0 }
' <<<"$BLOCK")"
if [ -z "$FENCE_AFTER" ]; then FENCE_AFTER=0; fi
if [ "$FENCE_AFTER" -ge 1 ]; then
pass "final_prompt: followed by non-empty fenced code block ($FENCE_AFTER content line(s))"
else
fail "final_prompt: not followed by a non-empty fenced code block"
fi
else
fail "final_prompt: field missing"
fi
# -------------------------------------------------------
# Field 4: shipped — yes or equivalent
# -------------------------------------------------------
SHIPPED_LINE="$(printf '%s\n' "$BLOCK" | grep -E '^shipped:[[:space:]]*(yes|equivalent)[[:space:]]*$' || true)"
if [ -n "$SHIPPED_LINE" ]; then
pass "shipped: matches 'yes' or 'equivalent'"
else
fail "shipped: missing or not 'yes'/'equivalent'"
fi
# -------------------------------------------------------
# Field 5: comparison_to_unaided — non-empty sentence >=10 chars ending with .
# -------------------------------------------------------
COMP_LINE="$(printf '%s\n' "$BLOCK" | awk -F': *' '/^comparison_to_unaided:/ { for (i=2;i<=NF;i++) printf "%s%s", $i, (i<NF?": ":""); print ""; exit }')"
COMP_TRIMMED="$(printf '%s' "$COMP_LINE" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
COMP_LEN="${#COMP_TRIMMED}"
if [ -z "$COMP_TRIMMED" ]; then
fail "comparison_to_unaided: field missing or empty"
elif [ "$COMP_LEN" -lt 10 ]; then
fail "comparison_to_unaided: too short ($COMP_LEN chars; need >=10)"
elif [ "${COMP_TRIMMED: -1}" != "." ]; then
fail "comparison_to_unaided: does not end with '.'"
else
pass "comparison_to_unaided: non-empty, $COMP_LEN chars, ends with '.'"
fi
# -------------------------------------------------------
# Summary
# -------------------------------------------------------
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
if [ "$FAIL" -gt 0 ]; then
exit 1
fi
exit 0

100
plugins/claude-design/tests/test-sc2-artifact-coverage.sh
View file

@ -1,100 +0,0 @@
#!/usr/bin/env bash
# test-sc2-artifact-coverage.sh — Verifies SC2 (per-preset coverage)
#
# Reads .coverage.md, extracts preset names from the table column 1,
# for each preset runs:
# grep -rli "<preset>" plugins/claude-design/ --include='*.md' \
# --exclude-dir='.claude' --exclude-dir='tests'
# and asserts ≥1 file hit.
#
# The preset list is NOT hardcoded — auto-adapts when .coverage.md changes.
#
# Usage: bash tests/test-sc2-artifact-coverage.sh
# Exit codes: 0 = all presets covered; 1 = at least one preset uncovered
set -euo pipefail
LC_ALL=en_US.UTF-8
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
FAIL=0
WARN=0
pass() { printf "${GREEN} ✓ %s${NC}\n" "$1"; PASS=$((PASS + 1)); }
fail() { printf "${RED} ✗ %s${NC}\n" "$1"; FAIL=$((FAIL + 1)); }
warn() { printf "${YELLOW} ⚠ %s${NC}\n" "$1"; WARN=$((WARN + 1)); }
COVERAGE_FILE="$PLUGIN_ROOT/.coverage.md"
echo "=== test-sc2-artifact-coverage ==="
echo "Plugin root: $PLUGIN_ROOT"
echo ".coverage.md: $COVERAGE_FILE"
echo ""
if [ ! -f "$COVERAGE_FILE" ]; then
fail ".coverage.md missing — cannot verify SC2"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 1
fi
# -------------------------------------------------------
# Extract preset names from .coverage.md table column 1
# -------------------------------------------------------
# Table rows look like:
# | designs | skills/.../presets/designs.md | Evidence grade: ... | https://... |
# Skip header (| Preset | ...) and separator (| --- | ...).
PRESETS="$(awk -F'|' '
/^\| / && NR > 1 {
name = $2
gsub(/^ +| +$/, "", name)
if (name != "Preset" && name !~ /^-+$/ && name != "") {
print name
}
}
' "$COVERAGE_FILE")"
if [ -z "$PRESETS" ]; then
fail "no preset names extracted from .coverage.md"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 1
fi
# -------------------------------------------------------
# For each preset, grep for at least one file hit in plugin content
# -------------------------------------------------------
while IFS= read -r preset; do
[ -z "$preset" ] && continue
HITS="$(grep -rli "$preset" "$PLUGIN_ROOT" \
--include='*.md' \
--exclude-dir='.claude' \
--exclude-dir='tests' \
2>/dev/null || true)"
HIT_COUNT="$(printf '%s\n' "$HITS" | grep -c '.' || true)"
if [ -z "$HIT_COUNT" ]; then HIT_COUNT=0; fi
if [ "$HIT_COUNT" -ge 1 ]; then
pass "preset '$preset' covered by $HIT_COUNT file(s)"
else
fail "preset '$preset' has zero file hits in plugin content"
fi
done < <(printf '%s\n' "$PRESETS")
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
if [ "$FAIL" -gt 0 ]; then
exit 1
fi
exit 0

123
plugins/claude-design/tests/test-sc3-citations.sh
View file

@ -1,123 +0,0 @@
#!/usr/bin/env bash
# test-sc3-citations.sh — Verifies SC3 (Anthropic-domain citation discipline)
#
# Two checks:
# Negative — grep -rnE '\[CITE\]|\[verify\]|\baccording to\b' against
# shipped content. Zero hits expected.
# Positive — read .coverage.md "Authoritative-claims" bullet list
# (awk on '^- ' prefix), then for each file ensure ≥1
# Anthropic-domain URL citation is present.
#
# Excludes .claude/projects/** and tests/ from greps.
#
# Anthropic-domain URL regex (positive):
# https?://(docs\.anthropic\.com|anthropic\.com|github\.com/anthropics
# |claude\.com|support\.claude\.com|platform\.claude\.com)
#
# Usage: bash tests/test-sc3-citations.sh
# Exit codes: 0 = pass; 1 = at least one FAIL
set -euo pipefail
LC_ALL=en_US.UTF-8
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
FAIL=0
WARN=0
pass() { printf "${GREEN} ✓ %s${NC}\n" "$1"; PASS=$((PASS + 1)); }
fail() { printf "${RED} ✗ %s${NC}\n" "$1"; FAIL=$((FAIL + 1)); }
warn() { printf "${YELLOW} ⚠ %s${NC}\n" "$1"; WARN=$((WARN + 1)); }
COVERAGE_FILE="$PLUGIN_ROOT/.coverage.md"
echo "=== test-sc3-citations ==="
echo "Plugin root: $PLUGIN_ROOT"
echo ""
# -------------------------------------------------------
# Negative grep: \[CITE\], \[verify\], \baccording to\b
# -------------------------------------------------------
echo "--- negative grep: forbidden placeholders ---"
NEG_HITS="$(grep -rnE '\[CITE\]|\[verify\]|\baccording to\b' \
"$PLUGIN_ROOT" \
--include='*.md' \
--exclude-dir='.claude' \
--exclude-dir='tests' \
2>/dev/null || true)"
if [ -z "$NEG_HITS" ]; then
pass "no forbidden placeholders ([CITE], [verify], 'according to') in shipped content"
else
while IFS= read -r hit; do
fail "forbidden placeholder in shipped content: $hit"
done < <(printf '%s\n' "$NEG_HITS")
fi
echo ""
# -------------------------------------------------------
# Positive grep: Authoritative-claims files have Anthropic-domain URLs
# -------------------------------------------------------
echo "--- positive grep: Authoritative-claims citation coverage ---"
if [ ! -f "$COVERAGE_FILE" ]; then
fail ".coverage.md missing — cannot read Authoritative-claims registry"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 1
fi
# Extract bullet-list paths under the "Authoritative-claims" section
AUTH_FILES="$(awk '
/^## Authoritative-claims files/ { capture = 1; next }
capture && /^## / { exit }
capture && /^- / {
sub(/^- /, "", $0)
print $0
}
' "$COVERAGE_FILE")"
if [ -z "$AUTH_FILES" ]; then
fail "no Authoritative-claims files extracted from .coverage.md"
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
exit 1
fi
ANTHROPIC_REGEX='https?://(docs\.anthropic\.com|anthropic\.com|github\.com/anthropics|claude\.com|support\.claude\.com|platform\.claude\.com)'
while IFS= read -r relpath; do
[ -z "$relpath" ] && continue
fpath="$PLUGIN_ROOT/$relpath"
if [ ! -f "$fpath" ]; then
fail "Authoritative-claims file missing: $relpath"
continue
fi
HIT_COUNT="$(grep -cE "$ANTHROPIC_REGEX" "$fpath" || true)"
if [ -z "$HIT_COUNT" ]; then HIT_COUNT=0; fi
if [ "$HIT_COUNT" -ge 1 ]; then
pass "$relpath: $HIT_COUNT Anthropic-domain URL citation(s)"
else
fail "$relpath: zero Anthropic-domain URL citations (anthropic.com expected)"
fi
done < <(printf '%s\n' "$AUTH_FILES")
echo ""
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
if [ "$FAIL" -gt 0 ]; then
exit 1
fi
exit 0

122
plugins/claude-design/tests/test-skill-triggers.sh
View file

@ -1,122 +0,0 @@
#!/usr/bin/env bash
# test-skill-triggers.sh — Verifies skill description quality
#
# Honest limit: this only verifies strings are present in SKILL.md description.
# It cannot prove Claude Code's orchestrator fires the skill on those prompts.
# Runtime auto-fire validation is the operator's dogfood step (SC1).
#
# Checks:
# - SKILL.md frontmatter has 'description:' field
# - description block (from `description: |` to the closing `---`) is >=400 chars
# - if .triggers.txt exists, every phrase in it appears in SKILL.md description
#
# Usage: bash tests/test-skill-triggers.sh
# Exit codes: 0 = pass; 1 = at least one FAIL
set -euo pipefail
LC_ALL=en_US.UTF-8
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
FAIL=0
WARN=0
pass() { printf "${GREEN} ✓ %s${NC}\n" "$1"; PASS=$((PASS + 1)); }
fail() { printf "${RED} ✗ %s${NC}\n" "$1"; FAIL=$((FAIL + 1)); }
warn() { printf "${YELLOW} ⚠ %s${NC}\n" "$1"; WARN=$((WARN + 1)); }
echo "=== test-skill-triggers ==="
echo "Plugin root: $PLUGIN_ROOT"
echo ""
# -------------------------------------------------------
# Iterate over every SKILL.md
# -------------------------------------------------------
SKILL_COUNT=0
for skill_file in "$PLUGIN_ROOT"/skills/*/SKILL.md; do
[ -f "$skill_file" ] || continue
SKILL_COUNT=$((SKILL_COUNT + 1))
skill_dir="$(dirname "$skill_file")"
skill_name="$(basename "$skill_dir")"
echo "--- $skill_name ---"
# ------------------------
# Frontmatter check
# ------------------------
first_line="$(head -n 1 "$skill_file")"
if [ "$first_line" != "---" ]; then
fail "$skill_name/SKILL.md: missing frontmatter delimiter on line 1"
echo ""
continue
fi
# ------------------------
# Description >=400 chars (Triggers on: enumeration counts)
# ------------------------
desc_block_chars="$(awk '/^description: \|/,/^---$/' "$skill_file" | wc -c | tr -d '[:space:]')"
if [ -z "$desc_block_chars" ]; then desc_block_chars=0; fi
if [ "$desc_block_chars" -ge 400 ]; then
pass "$skill_name: description block is $desc_block_chars chars (>=400)"
else
fail "$skill_name: description block is $desc_block_chars chars (<400 required)"
fi
# ------------------------
# Trigger-phrase coverage (.triggers.txt)
# ------------------------
triggers_file="$skill_dir/.triggers.txt"
if [ ! -f "$triggers_file" ]; then
warn "$skill_name: .triggers.txt missing (advisory — operator may want one)"
echo ""
continue
fi
trigger_count="$(grep -cE '.' "$triggers_file" || true)"
if [ -z "$trigger_count" ] || [ "$trigger_count" -lt 8 ]; then
fail "$skill_name/.triggers.txt: only $trigger_count phrase(s) (>=8 required)"
else
pass "$skill_name/.triggers.txt: $trigger_count phrase(s)"
fi
# check each phrase appears in SKILL.md description block
MISSING=0
while IFS= read -r phrase; do
[ -z "$phrase" ] && continue
if ! grep -qF "$phrase" "$skill_file"; then
fail "$skill_name: trigger phrase missing from SKILL.md description: '$phrase'"
MISSING=$((MISSING + 1))
fi
done < "$triggers_file"
if [ "$MISSING" -eq 0 ]; then
pass "$skill_name: all $trigger_count trigger phrase(s) appear in SKILL.md"
fi
echo ""
done
if [ "$SKILL_COUNT" -eq 0 ]; then
fail "no SKILL.md found under skills/*/"
fi
# -------------------------------------------------------
# Summary
# -------------------------------------------------------
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
if [ "$FAIL" -gt 0 ]; then
exit 1
fi
exit 0
# Triggers on: documented in each skill's .triggers.txt sibling file.

265
plugins/claude-design/tests/validate-plugin.sh
View file

@ -1,265 +0,0 @@
#!/usr/bin/env bash
# validate-plugin.sh — Foundation plugin structure validator for claude-design
# Usage: bash tests/validate-plugin.sh
# Exit codes: 0 = all checks pass; 1 = at least one FAIL
#
# Forked from plugins/ms-ai-architect/tests/validate-plugin.sh:
# keep: helpers (pass/fail/warn), counters, PLUGIN_ROOT, JSON-validity check,
# README/CLAUDE.md existence checks
# strip: agent frontmatter loop, commands frontmatter loop, KB-staleness checks,
# architect:* command-name assertions, references-count assertions
# add: SKILL.md frontmatter + description-length, LICENSE content, GOVERNANCE
# existence, .coverage.md existence, forbidden-command-name regex (h),
# operator-private-context grep (i), Norwegian-leakage grep (j)
set -euo pipefail
LC_ALL=en_US.UTF-8
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
FAIL=0
WARN=0
pass() { printf "${GREEN} ✓ %s${NC}\n" "$1"; PASS=$((PASS + 1)); }
fail() { printf "${RED} ✗ %s${NC}\n" "$1"; FAIL=$((FAIL + 1)); }
warn() { printf "${YELLOW} ⚠ %s${NC}\n" "$1"; WARN=$((WARN + 1)); }
echo "=== claude-design Plugin Validation ==="
echo "Plugin root: $PLUGIN_ROOT"
echo ""
# -------------------------------------------------------
# Check (a): plugin.json valid + required fields
# -------------------------------------------------------
echo "--- (a) plugin.json structure ---"
PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
if [ ! -f "$PLUGIN_JSON" ]; then
fail ".claude-plugin/plugin.json missing"
else
if node -e "JSON.parse(require('fs').readFileSync('$PLUGIN_JSON'))" 2>/dev/null; then
pass ".claude-plugin/plugin.json is valid JSON"
else
fail ".claude-plugin/plugin.json is invalid JSON"
fi
for field in name version description; do
if node -e "const p = JSON.parse(require('fs').readFileSync('$PLUGIN_JSON')); if (typeof p['$field'] !== 'string' || p['$field'] === '') process.exit(1)" 2>/dev/null; then
pass "plugin.json has '$field'"
else
fail "plugin.json missing or empty '$field'"
fi
done
fi
echo ""
# -------------------------------------------------------
# Check (b): at least one SKILL.md under skills/*/
# -------------------------------------------------------
echo "--- (b) SKILL.md presence ---"
SKILL_COUNT=0
for skill_file in "$PLUGIN_ROOT"/skills/*/SKILL.md; do
[ -f "$skill_file" ] || continue
SKILL_COUNT=$((SKILL_COUNT + 1))
done
if [ "$SKILL_COUNT" -ge 1 ]; then
pass "found $SKILL_COUNT SKILL.md file(s) under skills/*/"
else
fail "no SKILL.md found under skills/*/"
fi
echo ""
# -------------------------------------------------------
# Check (c): SKILL.md frontmatter has name+description, description >=400 chars
# -------------------------------------------------------
echo "--- (c) SKILL.md frontmatter quality ---"
for skill_file in "$PLUGIN_ROOT"/skills/*/SKILL.md; do
[ -f "$skill_file" ] || continue
basename_skill="$(basename "$(dirname "$skill_file")")/SKILL.md"
first_line="$(head -n 1 "$skill_file")"
if [ "$first_line" != "---" ]; then
fail "$basename_skill: missing frontmatter delimiter on line 1"
continue
fi
frontmatter="$(awk 'NR==1{next} /^---$/{exit} {print}' "$skill_file")"
if echo "$frontmatter" | grep -qE '^name:'; then
pass "$basename_skill: has 'name:'"
else
fail "$basename_skill: missing 'name:'"
fi
if echo "$frontmatter" | grep -qE '^description:'; then
pass "$basename_skill: has 'description:'"
else
fail "$basename_skill: missing 'description:'"
fi
desc_len="$(awk '/^description: \|/,/^---$/' "$skill_file" | wc -c | tr -d '[:space:]')"
if [ -z "$desc_len" ]; then desc_len=0; fi
if [ "$desc_len" -ge 400 ]; then
pass "$basename_skill: description block is $desc_len chars (>=400)"
else
fail "$basename_skill: description block is $desc_len chars (<400)"
fi
done
echo ""
# -------------------------------------------------------
# Check (d): LICENSE exists, non-empty, contains "MIT License"
# -------------------------------------------------------
echo "--- (d) LICENSE ---"
LICENSE_FILE="$PLUGIN_ROOT/LICENSE"
if [ ! -f "$LICENSE_FILE" ]; then
fail "LICENSE missing"
elif [ ! -s "$LICENSE_FILE" ]; then
fail "LICENSE is empty"
elif ! grep -q "MIT License" "$LICENSE_FILE"; then
fail "LICENSE does not contain 'MIT License'"
else
pass "LICENSE exists, non-empty, MIT License"
fi
echo ""
# -------------------------------------------------------
# Check (e): GOVERNANCE.md exists, non-empty
# -------------------------------------------------------
echo "--- (e) GOVERNANCE.md ---"
GOVERNANCE_FILE="$PLUGIN_ROOT/GOVERNANCE.md"
if [ ! -f "$GOVERNANCE_FILE" ]; then
fail "GOVERNANCE.md missing"
elif [ ! -s "$GOVERNANCE_FILE" ]; then
fail "GOVERNANCE.md is empty"
else
pass "GOVERNANCE.md exists, non-empty"
fi
echo ""
# -------------------------------------------------------
# Check (f): README.md + CLAUDE.md exist, non-empty
# -------------------------------------------------------
echo "--- (f) README.md and CLAUDE.md ---"
for f in README.md CLAUDE.md; do
fpath="$PLUGIN_ROOT/$f"
if [ ! -f "$fpath" ]; then
fail "$f missing"
elif [ ! -s "$fpath" ]; then
fail "$f is empty"
else
pass "$f exists, non-empty"
fi
done
echo ""
# -------------------------------------------------------
# Check (g): .coverage.md exists at plugin root
# -------------------------------------------------------
echo "--- (g) .coverage.md ---"
COVERAGE_FILE="$PLUGIN_ROOT/.coverage.md"
if [ ! -f "$COVERAGE_FILE" ]; then
fail ".coverage.md missing"
elif [ ! -s "$COVERAGE_FILE" ]; then
fail ".coverage.md is empty"
else
pass ".coverage.md exists, non-empty"
fi
echo ""
# -------------------------------------------------------
# Check (h): forbidden command-name regex (scope fence vs
# Anthropic's knowledge-work-plugins/design)
# -------------------------------------------------------
echo "--- (h) forbidden command-name regex ---"
FORBIDDEN_REGEX='^name:[[:space:]]*(claude-design:)?(critique|accessibility|ux-copy|research-synthesis|design-system|handoff)[[:space:]]*$'
H_HIT=0
for cmd_file in "$PLUGIN_ROOT"/commands/*.md "$PLUGIN_ROOT"/skills/*/SKILL.md; do
[ -f "$cmd_file" ] || continue
if grep -qE "$FORBIDDEN_REGEX" "$cmd_file"; then
fail "command-name collision with Anthropic's official knowledge-work-plugins/design plugin: $cmd_file"
H_HIT=$((H_HIT + 1))
fi
done
if [ "$H_HIT" -eq 0 ]; then
pass "no forbidden command-name collisions"
fi
echo ""
# -------------------------------------------------------
# Check (i): operator-private-context grep
# -------------------------------------------------------
echo "--- (i) operator-private-context grep ---"
I_HITS="$(grep -rnE '(kjell|vegvesen|NEXT-SESSION-PROMPT|REMEMBER\.md content from)' \
"$PLUGIN_ROOT" \
--include='*.md' \
--exclude-dir='.claude' \
--exclude-dir='tests' \
--exclude='REMEMBER.md' \
--exclude='TODO.md' \
--exclude='NEXT-SESSION-PROMPT.local.md' \
2>/dev/null || true)"
if [ -z "$I_HITS" ]; then
pass "no operator-private context leaks in shipped content"
else
while IFS= read -r hit; do
fail "operator-private context leak in shipped content (brief NFR): $hit"
done < <(printf '%s\n' "$I_HITS")
fi
echo ""
# -------------------------------------------------------
# Check (j): Norwegian-leakage grep (WARN, not FAIL)
# -------------------------------------------------------
echo "--- (j) Norwegian-leakage grep ---"
J_HITS="$(grep -rnE '[æøåÆØÅ]' \
"$PLUGIN_ROOT" \
--include='*.md' \
--exclude-dir='.claude' \
--exclude='REMEMBER.md' \
--exclude='TODO.md' \
--exclude='NEXT-SESSION-PROMPT.local.md' \
2>/dev/null || true)"
if [ -z "$J_HITS" ]; then
pass "no Norwegian diacritics in shipped content"
else
while IFS= read -r hit; do
warn "Norwegian diacritic in shipped content (review case-by-case): $hit"
done < <(printf '%s\n' "$J_HITS")
fi
echo ""
# -------------------------------------------------------
# Summary
# -------------------------------------------------------
echo "=== Summary ==="
printf "Pass: %d Fail: %d Warn: %d\n" "$PASS" "$FAIL" "$WARN"
if [ "$FAIL" -gt 0 ]; then
exit 1
fi
exit 0

152
plugins/claude-design/verify.sh
View file

@ -1,152 +0,0 @@
#!/usr/bin/env bash
# verify.sh — Top-level roll-up for claude-design plugin verification
#
# Runs the 5 test scripts in dependency order:
# 1. tests/validate-plugin.sh (foundation plugin structure)
# 2. tests/test-skill-triggers.sh (skill description + trigger phrases)
# 3. tests/test-sc2-artifact-coverage.sh (SC2 — every preset has ≥1 file)
# 4. tests/test-sc3-citations.sh (SC3 — citation discipline)
# 5. tests/test-sc1-dogfood-log.sh (SC1 — operator dogfood log format)
#
# Flags:
# --strict pass --strict to test-sc1-dogfood-log.sh (missing block = FAIL)
# --quick skip tests/test-skill-triggers.sh (fast incremental runs)
#
# Exit codes: 0 = all sub-tests pass; non-zero = at least one sub-test failed
#
# Bash 3.2 compatible. Modelled on plugins/voyage/verify.sh helper style.
set -u
LC_ALL=en_US.UTF-8
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BOLD='\033[1m'
NC='\033[0m'
PLUGIN_ROOT="$(cd "$(dirname "$0")" && pwd)"
# Flag parsing
STRICT=false
QUICK=false
for arg in "$@"; do
case "$arg" in
--strict) STRICT=true ;;
--quick) QUICK=true ;;
-h|--help)
echo "Usage: $0 [--strict] [--quick]"
echo " --strict Pass --strict to test-sc1-dogfood-log.sh"
echo " --quick Skip tests/test-skill-triggers.sh"
exit 0
;;
*)
echo "Unknown flag: $arg" >&2
echo "Usage: $0 [--strict] [--quick]" >&2
exit 2
;;
esac
done
TOTAL_PASS=0
TOTAL_FAIL=0
TOTAL_WARN=0
FAILED_SCRIPTS=""
run_script() {
local script_name="$1"
shift
local script_path="$PLUGIN_ROOT/tests/$script_name"
if [ ! -f "$script_path" ]; then
printf "${RED}[MISSING]${NC} %s\n" "$script_name"
TOTAL_FAIL=$((TOTAL_FAIL + 1))
FAILED_SCRIPTS="$FAILED_SCRIPTS $script_name"
return 1
fi
printf "${BOLD}### %s${NC}\n" "$script_name"
local output exit_code
output="$(bash "$script_path" "$@" 2>&1)"
exit_code=$?
printf '%s\n' "$output"
# Parse the script's own Summary line: "Pass: N Fail: N Warn: N"
local summary
summary="$(printf '%s\n' "$output" | grep -E '^Pass: [0-9]+ Fail: [0-9]+ Warn: [0-9]+$' | tail -n 1)"
if [ -n "$summary" ]; then
local p f w
p="$(printf '%s' "$summary" | awk '{print $2}')"
f="$(printf '%s' "$summary" | awk '{print $4}')"
w="$(printf '%s' "$summary" | awk '{print $6}')"
TOTAL_PASS=$((TOTAL_PASS + p))
TOTAL_FAIL=$((TOTAL_FAIL + f))
TOTAL_WARN=$((TOTAL_WARN + w))
fi
if [ "$exit_code" -ne 0 ]; then
FAILED_SCRIPTS="$FAILED_SCRIPTS $script_name"
fi
printf "\n"
return "$exit_code"
}
echo "=== claude-design verify.sh ==="
echo "Plugin root: $PLUGIN_ROOT"
echo "Strict mode: $STRICT Quick mode: $QUICK"
echo ""
# -------------------------------------------------------
# 1. validate-plugin.sh
# -------------------------------------------------------
run_script "validate-plugin.sh" || true
# -------------------------------------------------------
# 2. test-skill-triggers.sh (skipped in --quick mode)
# -------------------------------------------------------
if $QUICK; then
printf "${YELLOW}### test-skill-triggers.sh${NC} (skipped — --quick)\n\n"
else
run_script "test-skill-triggers.sh" || true
fi
# -------------------------------------------------------
# 3. test-sc2-artifact-coverage.sh
# -------------------------------------------------------
run_script "test-sc2-artifact-coverage.sh" || true
# -------------------------------------------------------
# 4. test-sc3-citations.sh
# -------------------------------------------------------
run_script "test-sc3-citations.sh" || true
# -------------------------------------------------------
# 5. test-sc1-dogfood-log.sh (strict if --strict)
# -------------------------------------------------------
if $STRICT; then
run_script "test-sc1-dogfood-log.sh" --strict || true
else
run_script "test-sc1-dogfood-log.sh" || true
fi
# -------------------------------------------------------
# Aggregate summary
# -------------------------------------------------------
echo "================================================="
echo "=== claude-design verify.sh — aggregate summary"
echo "================================================="
printf "${GREEN}Pass:${NC} %d ${RED}Fail:${NC} %d ${YELLOW}Warn:${NC} %d\n" \
"$TOTAL_PASS" "$TOTAL_FAIL" "$TOTAL_WARN"
if [ -n "$FAILED_SCRIPTS" ]; then
printf "${RED}Failed scripts:${NC}%s\n" "$FAILED_SCRIPTS"
fi
if [ "$TOTAL_FAIL" -gt 0 ]; then
exit 1
fi
exit 0

11
plugins/config-audit/.claude-plugin/plugin.json
View file

@ -1,11 +0,0 @@
{
"name": "config-audit",
"description": "Multi-agent workflow for analyzing, reporting, and optimizing Claude Code configuration across your entire machine",
"version": "5.1.0",
"author": {
"name": "Kjell Tore Guttormsen"
},
"license": "MIT",
"repository": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace",
"keywords": ["configuration", "audit", "optimization", "health-check", "scanner"]
}

27
plugins/config-audit/.claude/rules/agent-development.md
View file

@ -1,27 +0,0 @@
---
paths: agents/**/*.md
---
# Agent Development Rules
## Required Frontmatter
All agent files MUST include this frontmatter:
```yaml
---
name: descriptive-name
description: |
Multi-line description of when to use this agent.
model: opus|sonnet|haiku
color: blue|green|yellow|purple|cyan|magenta
tools: ["Read", "Glob", "Write"]
---
```
## Conventions
- Agent names use kebab-case with `-agent` suffix
- Description must explain WHEN the agent should be used
- Model choice: opus for analysis, sonnet for implementation, haiku for scanning
- Color must be unique within the plugin

24
plugins/config-audit/.claude/rules/command-development.md
View file

@ -1,24 +0,0 @@
---
paths: commands/**/*.md
---
# Command Development Rules
## Required Frontmatter
All command files MUST include:
```yaml
---
name: plugin:command
description: Short description of what this command does
allowed-tools: Read, Write, Bash, Task
model: sonnet
---
```
## Naming Convention
- Commands use `plugin-name:action` format (e.g., `config-audit:analyze`)
- Main router command uses just the plugin name (e.g., `config-audit`)
- Description should be one line, actionable

15
plugins/config-audit/.claude/rules/state-management.md
View file

@ -1,15 +0,0 @@
# State Update Rule
After EVERY phase completes, you MUST update state.yaml using the Write tool (full file overwrite):
1. Read: `~/.claude/config-audit/sessions/{session-id}/state.yaml`
2. Update these fields:
- `current_phase`: the phase that just completed
- `completed_phases`: add the phase to array
- `next_phase`: the next phase in workflow
- `updated_at`: current timestamp
3. Write the full file back
**DO NOT output the phase summary until state.yaml is updated.**
This ensures the workflow can resume correctly if interrupted.

32
plugins/config-audit/.claude/rules/ux-rules.md
View file

@ -1,32 +0,0 @@
# Config-Audit UX Rules
These rules apply to ALL config-audit commands. The goal is a professional, human-friendly experience.
## Output Rules
1. NEVER show raw JSON, stderr output, or scanner progress lines to the user
2. ALL scanner Bash commands MUST use `--output-file <path> 2>/dev/null`
3. Check exit code via `; echo $?` — codes 0, 1, 2 are normal (PASS/WARNING/FAIL). Only 3 is a real error
4. Read output files with the Read tool, extract key metrics, and present formatted results
5. NEVER let the user see tool call output that looks like diagnostic logs or stack traces
## Narration Rules
1. Before each major step, tell the user what's happening in plain language
2. After scanners complete, briefly say what was found before showing details
3. When spawning agents, tell the user what the agent does and approximate wait time
4. If something takes more than a few seconds, set expectations: "This takes about 30 seconds..."
## Formatting Rules
1. Use markdown tables for structured data (area breakdowns, finding lists)
2. Add one-sentence plain-language context for grades and scores — don't assume the user knows what "Level 4 Governed" means
3. Separate test-fixture/example findings from real findings when showing counts
4. End every command with context-sensitive next steps — explain what each command does, not just its name
5. Adapt tone to results: A/B grades get encouraging context, D/F grades get empathetic, actionable guidance
## Command Format
1. Always use space-separated format in suggestions: `/config-audit plan` (NOT `/config-audit:plan`)
2. Never reference commands that don't exist
3. When suggesting next steps, explain WHY the user might want each option

16
plugins/config-audit/.config-audit-ignore
View file

@ -1,16 +0,0 @@
# Config-Audit Self-Audit Suppressions
# These findings are expected/intentional when scanning this plugin's own root.
# Plugin health scanner: yaml-parser can't parse YAML block lists in agent tools field
CA-PLH-*
# Feature gap: plugin intentionally doesn't need all enterprise features
CA-GAP-*
# Rules with always-active scope (state-management.md) — intentional design
CA-RUL-003
# Duplicate hook definitions: expected when examples/ has its own hooks.json
CA-CNF-007
CA-CNF-008
CA-CNF-009

25
plugins/config-audit/.gitignore vendored
View file

@ -1,25 +0,0 @@
# Local configuration (contains machine-specific settings)
config-audit.local.md
*.local.md
.claude/settings.local.json
# Secrets
.env
*.key
*.pem
credentials.*
# Dependencies
node_modules/
# Test fixtures intentionally include fake node_modules for tool-count detection
!tests/fixtures/**/node_modules/
!tests/fixtures/**/node_modules/**
# Development prompts
S*-PROMPT.md
# Plugin state (managed by plugin)
.config-audit/
# v5 namespace research (local-only spike output)
docs/v5-namespace-research.md

540
plugins/config-audit/CHANGELOG.md
View file

@ -1,540 +0,0 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [5.1.0] - 2026-05-01
### Summary
Plain-language UX humanizer release. Default output of all 18 commands now leads with prose; technical IDs surface at end-of-line as references rather than headlines. Non-expert users — the bulk of the OSS audience — now read findings like "Fix soon: The same automation is set up more than once" instead of "[high] CA-CNF-001: Hook duplicate event registration". Scanner internals are unchanged; humanization is a pure output-time transform applied at the rendering layer. The `--raw` flag preserves v5.0.0 verbatim output for tooling that scrapes stderr; `--json` is unchanged from v5.0.0 and remains byte-stable for programmatic consumption.
Delivered across 6 waves (Wave 0 baseline → Wave 1 humanizer module → Wave 2 test re-anchoring → Wave 3 CLI wiring → Wave 4 contract tests → Wave 5 templates/agents → Wave 6 release).
### Added
- **`scanners/lib/humanizer.mjs`** — pure-function output translator: `humanizeFinding`, `humanizeFindings`, `humanizeEnvelope`, `computeRelevanceContext`. Never mutates inputs. Adds three additive fields per finding (`userImpactCategory`, `userActionLanguage`, `relevanceContext`) and replaces title/description/recommendation when a translation is available; falls through to originals otherwise.
- **`scanners/lib/humanizer-data.mjs`** — TRANSLATIONS table for 13 scanner prefixes (CML, SET, HKV, RUL, MCP, IMP, CNF, COL, TOK, CPS, DIS, GAP, PLH). Three-step lookup per finding: exact title → regex pattern → `_default` → fall through to scanner original.
- **`--raw` flag** threaded through every CLI: `posture.mjs`, `scan-orchestrator.mjs`, `token-hotspots-cli.mjs`, `manifest.mjs`, `whats-active.mjs`, `fix-cli.mjs`, `drift-cli.mjs`, `self-audit.mjs`. Bypasses humanizer; emits byte-stable v5.0.0 verbatim output.
- **User-impact categories** (5 labels): Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config. Mapped from scanner prefix.
- **Action-language phrases** (5 labels): Fix this now, Fix soon, Fix when convenient, Optional cleanup, FYI. Mapped from severity.
- **Relevance context** (3 values): `test-fixture-no-impact`, `affects-this-machine-only`, `affects-everyone`. Computed from finding's file path — basenames matching `*.local.*` and paths containing `/tests/fixtures/` are recognized.
- **Self-audit terminal humanization** — `formatSelfAudit()` routes through `humanizeEnvelope`. JSON path (`--json`) is unchanged; humanization applies only to the prose terminal render.
- **Forbidden-words lint** (`tests/lint-forbidden-words.json` + runner) — 3-tier vocabulary blocklist enforced over default-mode output, ensuring humanized prose stays in plain language.
- **Scenario read-test** (`tests/scenario-read-test.mjs` + 5 scenarios) — corpus-driven readability check covering broken hook, duplicate keys, stale @import, dead tool, oversized cascade.
- **`tests/snapshots/v5.0.0/`** + **`tests/snapshots/v5.0.0-stderr/`** — frozen byte-equal references for SC-6 (--json) and SC-7 (--raw) backwards-compatibility tests across 8 CLIs.
- **`tests/snapshots/default-output/`** — humanized-prose snapshots for SC-5 default-output stability.
### Changed
- **Default output of all 18 commands** now uses plain-language descriptions. Findings group by user-impact category; titles lead with prose; technical IDs (`CA-CML-001`, `CA-TOK-005`, …) surface at end-of-line as references.
- **All 21 command and agent templates** updated to render humanized output by default and pass `--raw` through when the user requests v5.0.0 verbatim mode.
- **CLI flag inventory** — every CLI now accepts `--raw` (new) in addition to `--json` (existing, unchanged). `--output-file <path>` still writes raw v5.0.0-shape JSON regardless of mode (humanizer-bypassed, posture-specific).
### Migration
- **No action required for existing automation** that consumes `--json` — the JSON envelope shape is byte-stable with v5.0.0 and humanizer fields are bypassed in `--json` and `--raw` paths.
- **Tooling that scrapes stderr** from default mode (e.g., `posture.mjs`'s scorecard) needs review — default stderr now uses prose vocabulary. Pass `--raw` for byte-stable v5.0.0 verbatim stderr.
- **No scanner-internal changes.** Finding IDs, severity ladders, scoring weights, and area scorecards are unchanged. Upgrades are presentation-layer only.
### Test count
- 635 → 792 tests across 52 test files (+157 humanizer-tester through Waves 0–5).
- New top-level tests: `json-backcompat.test.mjs`, `raw-backcompat.test.mjs`, `scenario-read-test.test.mjs`, `snapshot-default-output.test.mjs`.
- New lib tests: `humanizer.test.mjs`, `humanizer-data.test.mjs`, `scoring-humanizer.test.mjs`.
- New scanner tests: `posture-humanizer.test.mjs`, `scan-orchestrator-humanizer.test.mjs`, `cli-humanizer.test.mjs`.
### Out of scope (deferred to v5.1.1+)
- **Posture `--output-file` humanization** — `posture.mjs` does not call `humanizeEnvelope`, so files written via `--output-file` are raw v5.0.0-shape JSON. Future revision: drop `--output-file` from command templates or add a `--humanized-json` flag.
- **Knowledge cross-references** (Step 17 of plan) — not delivered per user decision (2a).
- **Scoring scorecard JSON headline emission** — currently rendered prose-side only; command templates that want to skip stderr parsing would benefit.
### Verification
- 792/792 tests pass (`node --test 'tests/**/*.test.mjs'`)
- `node scanners/self-audit.mjs --json --check-readme` returns `configGrade: A` (97), `pluginGrade: A` (100), `readmeCheck.passed: true`
- README badge updated: `tests-635+` → `tests-792+`
## [5.0.0] - 2026-05-01
### Summary
Reality-based token-optimization release. v4.0.0 shipped Opus-4.7 token surfaces aligned to a Sonnet-era cost model; v5.0.0 rebuilds the foundations against verified Opus-4.7 cost dynamics. Three pillars: honest token estimation (severity-weighted scoring, MCP estimates 15 → 500+, optional `--accurate-tokens` API calibration), new structural scanners (cache-prefix stability, dead tool grants, plugin collisions), and new diagnostic surfaces (`/config-audit manifest`, `/config-audit tokens` extended, knowledge-base rensing aligned to Opus 4.7 cache dynamics).
Consolidated from `5.0.0-alpha.1` (F1-F5 token-economy round), `5.0.0-alpha.2` (M1, M2, M4-M6, F6, F7 structural gaps + README self-audit), `5.0.0-beta.1` (N1-N4, N6 new scanners + manifest CLI), and `5.0.0-rc.1` (M7, M8 knowledge rensing + N5 tokenizer calibration).
### Added
- **3 new scanners (9 → 12 deterministic):**
- **CPS — Cache-Prefix Stability** (`CA-CPS-NNN`): volatile content in lines 31–150 of CLAUDE.md cascade, beyond TOK Pattern A's top-30 window. Volatile-pattern set extends Pattern A with shell-exec lines (`!` prefix) and `${VAR}` substitutions.
- **DIS — Disabled-In-Schema** (`CA-DIS-NNN`): tools listed in BOTH `permissions.deny` AND `permissions.allow`. Tool identity uses bare name (`Bash(npm:*)` and `Bash` are the same tool). Severity low.
- **COL — Cross-Plugin Skill Collision** (`CA-COL-001`): plugin-vs-plugin same skill name → low; user-vs-plugin → medium. `details.namespaces` payload identifies conflicting sources.
- **TOK extensions:**
- **CA-TOK-005 MCP tool-schema budget:** per-server tiered finding (< 20 none, 20–49 low, 50–99 medium, 100+ high; null low + "tool count unknown"). Scoped to project-local `.mcp.json`.
- **Pattern E — Oversized cascade:** medium when `activeConfig.claudeMd.estimatedTokens > 10_000`.
- **Pattern F — Bloated SKILL.md description:** low when frontmatter `description > 500 chars` (loads every turn). Scoped to `discovery.files`.
- **`/config-audit manifest`** + `scanners/manifest.mjs` CLI — single ranked table of every system-prompt token source (CLAUDE.md cascade, plugins, skills, MCP servers, hooks) sorted DESC by `estimated_tokens`. CLAUDE.md per-file tokens distributed proportional to bytes.
- **`--accurate-tokens` flag** on `token-hotspots-cli.mjs` (N5): when `ANTHROPIC_API_KEY` is set, calls Anthropic's `count_tokens` for the top 3 hotspots and populates `output.calibration = { actual_tokens, source: 'count_tokens_api', sampled_hotspots: 3 }`. When absent: `calibration = { skipped: 'no-api-key' }` plus stderr warning.
- **`scanners/lib/tokenizer-api.mjs`** — `count_tokens` wrapper. 5s AbortController timeout. Exponential backoff on 429 (3 retries: 1s/2s/4s). API key masked to `${key.slice(0,8)}...` in every error; HTTP body never included in errors (it may echo the key on auth failures). `maskKey()` exported.
- **`--with-telemetry-recipe` flag** on the same CLI (M7): emits `telemetry_recipe_path` field pointing to `knowledge/cache-telemetry-recipe.md`.
- **`knowledge/cache-telemetry-recipe.md`** (M7): manual `jq` recipe summing `cache_read_input_tokens` + `cache_creation_input_tokens` per turn from session transcripts. Hit-rate interpretation table.
- **`'mcp'` kind on `estimateTokens`** (F2): active MCP servers estimate ≥ 500 tokens (base + schema overhead) instead of v4's flat 15. Optional `{toolCount}` raises to `500 + toolCount × 200`.
- **MCP tool-count detection** (M1): `readActiveMcpServers` resolves count via cache → `node_modules/<pkg>/package.json` → `{toolCount: null, toolCountUnknown: true}` fallback.
- **`additionalDirectories` settings key** (M6): added to `KNOWN_KEYS`; new low-severity finding when length > 2.
- **HKV verbose hook output** (M5): low-severity finding when referenced hook script contains > 50 `console.log`/`process.stdout.write` lines (static, no execution).
- **`self-audit --check-readme` flag** (F6): filesystem counts compared against README badges. Helper `checkReadmeBadges(pluginDir)`. Step 28 of v5 plan reconciled all badges.
- **`scoringVersion: 'v5'`** field on `scoreByArea` output for cross-version drift detection.
- **`WEIGHTS`** named export from `scanners/lib/severity.mjs` (frozen).
- **`details` field on findings** (`output.mjs:finding()`): optional structured payload for scanner-specific data (used by COL).
- **Plugin Hygiene** as 10th quality area (from COL). Posture JSON now reports 10 areas.
- **TOK-readActiveConfig integration** (F1): one hotspot per active MCP server; `result.activeConfig` summary (claudeMd cascade tokens, mcpServerCount, pluginCount, skillCount); try/catch fallback when scope-limited.
### Changed
- **F3 — `scoreByArea` is severity-weighted.** Penalty = `Σ count[s] × WEIGHTS[s]`; `passRate = max(0, 100 − penalty / max(10, findingCount × 4) × 100)`. Lows no longer crater an area's grade; criticals/highs do. `baseline-all-a` fixture remains all-A (no critical/high present).
- **F7 — TOK pattern severities recalibrated** for tokens-per-turn impact: Pattern A `medium → high`, Pattern B `low → medium`, Pattern C `medium → low`. Each finding carries a `calibration_note` evidence field documenting the heuristic basis.
- **`scoreByArea` deduplicates by area name** (N3 prep): TOK + CPS share "Token Efficiency"; SET + DIS share "Settings". Combined row with merged finding counts.
- **M8 — knowledge rensing:** replaced "Keep CLAUDE.md under 200 lines" in `knowledge/configuration-best-practices.md` with cache-stability guidance (first 30 lines stable, volatile content below the cache threshold). Footnote explains the 200-line rule was a Sonnet-era adherence heuristic; Opus 4.7 uses prompt-cache structure as the dominant cost lever. Cross-references `knowledge/opus-4.7-patterns.md`.
- **`commands/tokens.md` next-steps:** documents `--with-telemetry-recipe` as the cache-verification path.
- **Scanner count: 9 → 12.** Command count: 17 → 18. Knowledge: 7 → 8. Quality areas: 8 → 10.
- **`.gitignore`** — unignore rules for `tests/fixtures/**/node_modules/` so the `mcp-tool-heavy` fixture stays under version control.
### Removed
- **F4 — TOK hotspot padding loop and `take` dead-code.** Hotspots may now contain fewer than 3 entries for tiny projects (the honest answer); contract still bounds at ≤ 10.
- **F5 — Pattern D / `CA-TOK-004` (sonnet-era signature).** Catalogue entry removed from `knowledge/opus-4.7-patterns.md` and `commands/tokens.md`. Suppression entries for `CA-TOK-004` are now no-ops.
### Breaking changes
- **F2 — MCP token estimates jump from flat 15 to ≥ 500.** Token Efficiency grades for projects with MCP servers may shift. `whats-active` totals report higher numbers. Documented in `commands/posture.md` next-steps.
- **F3 — `scoreByArea` is severity-weighted.** Posture JSON consumers reading `areas[*].score` will see different values for non-clean configs. Use `result.scoringVersion === 'v5'` to detect the change. Drift comparisons across v4↔v5 baselines may show artificial deltas — re-baseline after upgrade.
- **F5 — Pattern D / `CA-TOK-004` no longer emitted.** Existing exact `CA-TOK-004` suppression entries are harmless but obsolete.
- **N1 suppression backward-compat — `CA-TOK-*` glob now also matches `CA-TOK-005`.** To preserve prior behavior of suppressing only patterns A/B/C, replace the glob with explicit IDs:
```
CA-TOK-001
CA-TOK-002
CA-TOK-003
```
A one-time runtime warning for this case is a v5.0.1 candidate.
- **Posture areas count: 9 → 10** (Plugin Hygiene from COL). Consumers hard-coding 9 must update.
### Migration notes
- `CA-TOK-*` glob suppressions: explicit-ID list recommended if CA-TOK-005 should not be suppressed.
- `CA-TOK-004` exact-ID suppression entries: safe to remove.
- Drift baselines created against v4 should be re-saved post-upgrade to avoid artificial F3 weighting deltas.
- Posture JSON consumers must update any hardcoded `areas.length === 8` or `=== 9` assertions to `>= 10`.
### Tests
- 543 → 635 (+92): F1-F7 (alpha rounds = +43), N1-N4 + N6 (beta = +39), M7 + M8 + N5 (rc = +10). 36 test files (12 lib + 23 scanner + 1 hook).
- New fixtures: `tok-active-config/`, `additional-dirs-many/`, `additional-dirs-ok/`, `large-cascade/`, `small-cascade/`, `skill-bloated/`, `skill-tight/`, `mcp-tool-heavy/` (with mocked `node_modules/`), `hooks-verbose/`, `hooks-quiet/`, `readme-desynced/`, `mcp-budget/{14,25,60,120,unknown}-tools/`, `volatile-mid-section/{volatile-line-60,volatile-line-200}/`, `denied-tools-in-schema/`, `collision-plugins/fake-home/` (plugin-a + plugin-b + plugin-c + user-level review skill).
- New test files: `tests/scanners/manifest.test.mjs`, `tests/scanners/cache-prefix.test.mjs`, `tests/scanners/disabled-in-schema.test.mjs`, `tests/scanners/collision.test.mjs`, `tests/scanners/accurate-tokens.test.mjs`.
### Notes
- **`mock.method` against ESM module exports does not work** (Node 18+ ESM read-only export bindings). v5 tests use `globalThis.fetch` mocking for `--accurate-tokens` instead — equivalent coverage at the actual external-dependency boundary.
- **Plugin-vs-built-in collision detection is intentionally not implemented.** Step 22a research spike (`docs/v5-namespace-research.md`, gitignored) could not verify Claude Code's resolution behavior when a plugin command shares a name with a built-in. Treated as info-only; v5.0.1 candidate.
- **README/CLAUDE.md badge reconciliation** done in Step 28 (this release). `self-audit --check-readme` PASSES against the filesystem. Test count counter switched from file-count to test-case count via subprocess `node --test` parse.
- **`hotspot.path` exposed on file-backed hotspots** (Step 30 fix). The rc.1 `--accurate-tokens` implementation looked up `hotspot.path` but the scanner only emitted `source`. File-backed hotspots now carry `path` (absolute path); MCP-server hotspots leave it unset (they are virtual entries representing runtime tool-schema cost, not file content).
### SC-6b release-gate result (verified 2026-05-01)
- **PASS — 0.85% under-estimation against real `count_tokens` API.**
- Fixture: `tests/fixtures/marketplace-large/`. Top-3 hotspots = 1 file-backed (`CLAUDE.md`) + 2 MCP virtuals. MCP entries skipped per design (no readable content; their tokens are formula-based at 500 + toolCount × 200).
- `CLAUDE.md` actual: 589 tokens (Anthropic `count_tokens`, `claude-opus-4-7`). Estimated: 594 tokens (byte heuristic at 4 bytes/token via `estimateTokens`). Delta: **−5 tokens, −0.85%** — well within the ±5% gate.
- No tuning of `estimateTokens` heuristic required for v5.0.0.
## [5.0.0-rc.1] - 2026-05-01
### Summary
Release candidate for v5.0.0 — knowledge rensing and tokenizer calibration. Three deliverables: M8 (Sonnet-era → Opus 4.7 best-practices rewrite), M7 (cache-telemetry recipe in `knowledge/` plus an opt-in CLI flag), and N5 (`--accurate-tokens` API calibration via Anthropic's `count_tokens` endpoint).
### Added
- **N5 — `--accurate-tokens` flag** on `scanners/token-hotspots-cli.mjs`. When `ANTHROPIC_API_KEY` is set, the CLI calls Anthropic's `count_tokens` endpoint for the top 3 hotspots and populates `output.calibration = { actual_tokens, source: 'count_tokens_api', sampled_hotspots: 3 }`. When the key is absent, `calibration = { skipped: 'no-api-key' }` and a stderr warning is emitted. Designed for the manual SC-6b release-gate verification, not routine use.
- **`scanners/lib/tokenizer-api.mjs`** — wrapper around `count_tokens` with a 5-second AbortController timeout, exponential-backoff retry on HTTP 429 (max 3 retries: 1s, 2s, 4s), and required headers (`x-api-key`, `anthropic-version: 2023-06-01`, `content-type`). API key is masked to `${key.slice(0,8)}...` in every error message and every thrown error; non-429 HTTP errors throw status code only — response body is never included (it may echo the key on auth failures). `maskKey()` is exported for callers that need safe logging.
- **M7 — `knowledge/cache-telemetry-recipe.md`** (new). Manual `jq` recipe for verifying prompt-cache hit rate from Claude Code session transcripts (`~/.claude/projects/<slug>/*.jsonl`). Sums `cache_read_input_tokens` and `cache_creation_input_tokens` per turn and reports a hit-rate ratio. Recipe-form (not bundled scanner) keeps the project's "no transcript-parsing as core feature" non-goal intact while giving users a runtime escape hatch.
- **M7 — `--with-telemetry-recipe` flag** on the same CLI. When passed, emits `telemetry_recipe_path` in the JSON output pointing to the recipe file. Without the flag, output is unchanged. Committed as a default deliverable, opt-in at invocation time.
### Changed
- **M8 — knowledge-base rensing:** replaced the "Keep CLAUDE.md under 200 lines" rule in `knowledge/configuration-best-practices.md` with cache-stability guidance (first 30 lines stable, volatile content below the cache threshold). Added a footnote that the 200-line rule was a Sonnet-era adherence heuristic; Opus 4.7 uses prompt-cache structure as the dominant cost lever. Cross-references `knowledge/opus-4.7-patterns.md`.
- **`commands/tokens.md` next-steps:** documents `--with-telemetry-recipe` as the cache-verification path after a structural fix.
### Tests
- 625 → 635 (+10): `--with-telemetry-recipe` (×2), tokenizer-api unit tests (×6 — masking, body-leak protection, AbortController signal, 429 retry, header set, fetch mock happy path), `--accurate-tokens` no-key subprocess test (×1), absent-flag negative test (×1).
- New file: `tests/scanners/accurate-tokens.test.mjs`. No new fixtures (re-uses `marketplace-large`).
### Notes
- **SC-6b release gate is NOT closed by these commits.** Step 26's tests use mocked `globalThis.fetch` to verify the integration contract; ±5% accuracy against real `count_tokens` requires a live API key and must be verified manually before tagging v5.0.0 in Session 5.
- The plan's specified `mock.method(tokenizerApi, 'callCountTokensApi', ...)` pattern collides with ESM read-only export bindings in Node 18+. Tests mock at the `globalThis.fetch` boundary instead — equivalent coverage, no module-export rebinding required.
- README/CLAUDE.md badge counts and `plugin.json` version still target v4.0.0; Step 28+29 will sync those during the release wrap.
- `[skip-docs]` tag on the N5 feat commit; M7 and M8 are `docs(...)` commits and don't need it.
## [5.0.0-beta.1] - 2026-05-01
### Summary
First v5.0.0 beta — new scanners. Five new finding sources land: MCP tool-schema budget (CA-TOK-005), system-prompt manifest CLI/command (`/config-audit manifest`), cache-prefix stability (CPS), disabled-tools-still-in-schema (DIS), and cross-plugin/user-vs-plugin skill collision (COL/CA-COL-001). Plugin Hygiene becomes a 10th area-scorecard column.
### Added
- **N1 — `CA-TOK-005` MCP tool-schema budget:** per-server tiered finding inside the TOK scanner. Thresholds — `< 20` no finding, `20–49` low, `50–99` medium, `100+` high; `null` (manifest unparseable) low + "tool count unknown" message. Scoped to project-local `.mcp.json` to keep `/config-audit <path>` actionable. Recommendation links to the Step 25 cache-telemetry recipe.
- **N2 — `/config-audit manifest`:** new slash command + `scanners/manifest.mjs` CLI. Renders a single ranked table of every token source (CLAUDE.md cascade, plugins, skills, MCP servers, hooks) sorted DESC by `estimated_tokens`. Reuses `readActiveConfig`; CLAUDE.md per-file tokens are distributed proportional to bytes.
- **N3 — CPS scanner (`CA-CPS-NNN`):** Cache-Prefix Stability Analyzer. Walks the CLAUDE.md cascade and flags volatile content between lines 31 and 150 — beyond TOK Pattern A's top-30 territory. Volatile-pattern set extends Pattern A with shell-exec lines (`!` prefix) and `${VAR}` substitutions. Severity medium per finding. Skips lines 1–30 (Pattern A's range).
- **N4 — DIS scanner (`CA-DIS-NNN`):** Disabled-In-Schema Detector. Detects tools that appear in BOTH `permissions.deny` and `permissions.allow` within the same `settings.json`. The deny list wins, so allow entries are dead config but still load every turn. Tool identity is the bare name (everything before `(`); `Bash(npm:*)` and `Bash` are treated as the same tool. Severity low.
- **N6 — COL scanner (`CA-COL-001`):** Cross-Plugin Skill Collision detector. Plugin-vs-plugin same skill name → low. User-vs-plugin same skill name → medium. Findings carry `details.namespaces` array with `{source, name, path}` for every conflicting source.
- **`details` field on findings:** `output.mjs:finding()` helper now passes through optional `details` for scanner-specific structured payloads (used by COL).
- **"Plugin Hygiene" area** (10th in scorecard): COL contributes here. Posture JSON now reports 10 areas instead of 9.
### Changed
- **`scoreByArea` deduplicates by area name:** when multiple scanners share an area (TOK + CPS → "Token Efficiency", SET + DIS → "Settings"), they produce one combined row with merged finding counts. Existing 9-area contract preserved for non-Plugin-Hygiene areas.
### Known breaking changes
- **Suppression backward-compat — `CA-TOK-*` glob now also matches `CA-TOK-005`.** Existing `.config-audit-ignore` entries that suppress TOK findings via the `CA-TOK-*` glob will silently include CA-TOK-005 (MCP budget). To preserve the prior behavior of suppressing only patterns A/B/C, replace the glob with explicit IDs:
```
CA-TOK-001
CA-TOK-002
CA-TOK-003
```
A one-time runtime warning for this case is out of scope for v5.0.0 — it is a candidate for v5.0.1.
- **Plugin-vs-built-in collision is intentionally not implemented.** The Step 22a research spike could not verify Claude Code's resolution behavior when a plugin command shares a name with a built-in (`/help`, `/clear`, `/init`, `/review`, `/config`, `/cost`, `/security-review`). Treated as info-only in this release; a follow-up v5.0.1 ticket may add an opt-in check.
### Tests
- 586 → 625 (+39): N1 (×7), N2 (×11), N3 (×7), N4 (×6), N6 (×8).
- New fixtures: `mcp-budget/{14,25,60,120,unknown}-tools/`, `volatile-mid-section/{volatile-line-60,volatile-line-200}/`, `denied-tools-in-schema/`, `collision-plugins/fake-home/` (plugin-a + plugin-b + plugin-c + user-level review skill).
### Notes
- `[skip-docs]` tag used on every feat commit — README/CLAUDE.md badge counts (scanner count, command count, test count) and the architecture sections are intentionally fenced off until Session 5 (Step 28). This keeps the v5 plan's session boundaries clean even when the Forgejo `pre-commit-docs-gate` hook would otherwise block these commits.
## [5.0.0-alpha.2] - 2026-05-01
### Summary
Second v5.0.0 alpha — structural gaps + README self-audit. TOK pattern severities recalibrated for tokens/turn impact (F7), three new findings cover settings/skills/cascade structure (M2, M4, M6), MCP tool-count detection wired (M1), HKV gains a verbose-output check (M5), and self-audit grows a `--check-readme` flag (F6).
### Added
- **F7 — TOK severity recalibration:** Pattern A (cache-breaking volatile top) `medium → high`, Pattern B (redundant permissions) `low → medium`, Pattern C (deep imports) `medium → low`. Each finding now carries a `calibration_note` evidence field documenting the heuristic basis.
- **M6 — `additionalDirectories` settings key:** added to `KNOWN_KEYS` so it no longer trips "unknown settings key". New low-severity finding when `additionalDirectories.length > 2`.
- **M4 — TOK Pattern E:** medium-severity finding when `activeConfig.claudeMd.estimatedTokens > 10_000` — flags cascades that bleed budget every turn.
- **M2 — TOK Pattern F:** low-severity finding for project-local `SKILL.md` whose frontmatter `description` exceeds 500 characters (description loads on every turn even when the body does not). Scoped to `discovery.files`; user/plugin skills out of project scope are not flagged.
- **M1 — MCP tool-count detection:** `readActiveMcpServers` now resolves tool count via cache → `node_modules/<pkg>/package.json` → `{toolCount: null, toolCountUnknown: true}` fallback. Tool count drives `estimateTokens` per server.
- **M5 — HKV verbose hook output:** new low-severity finding when a referenced hook script contains > 50 `console.log` / `process.stdout.write` lines (static heuristic, no execution).
- **F6 — `self-audit --check-readme` flag:** filesystem counts (scanners, commands, agents, hooks, tests, knowledge) compared against README badge values. Helper export: `checkReadmeBadges(pluginDir)`.
### Changed
- **TOK severities** (F7) — see Added. Posture aggregates that depended on Pattern A being `medium` will now reflect the higher-impact rating.
- **`.gitignore`** — added unignore rules so `tests/fixtures/**/node_modules/` are tracked. Required by the `mcp-tool-heavy` fixture.
### Tests
- 563 → 586 (+23): F7 table-driven (×6), M6 (×3), M4 (×2), M2 (×2), M1 (×4), M5 (×2), F6 (×4).
- New fixtures: `additional-dirs-many/`, `additional-dirs-ok/`, `large-cascade/`, `small-cascade/`, `skill-bloated/`, `skill-tight/`, `mcp-tool-heavy/` (with mocked `node_modules/`), `hooks-verbose/`, `hooks-quiet/`, `readme-desynced/`.
### Notes
- `result.readmeCheck.passed === true` is **not** required during alpha/beta phases. The real plugin's own check is currently red (`scanners` 10 vs README 9, `tests` 31 vs README 543) — reconciliation deferred to Session 5 Step 28 (README sync).
- `[skip-docs]` tag used on every commit — README/CLAUDE.md badge counts and architecture text are intentionally fenced off until Session 5.
## [5.0.0-alpha.1] - 2026-05-01
### Summary
First v5.0.0 alpha — token-economy round, F1-F5. The TOK scanner now consumes `readActiveConfig` (per-MCP-server hotspots, claudeMd cascade tokens), severity weighting replaces flat finding counts in `scoreByArea`, and MCP servers no longer estimate at a flat 15 tokens. Pattern D (CA-TOK-004 sonnet-era signature) removed — too noisy, not actionable.
### Added
- **`'mcp'` kind for `estimateTokens`** (F2): an active MCP server now estimates ≥ 500 tokens (base protocol + schema overhead) instead of the v4 flat 15. Optional `{toolCount}` raises the estimate to `500 + toolCount * 200` once Step 14 wires tool-count detection.
- **TOK ↔ readActiveConfig integration** (F1): the TOK scanner emits one hotspot per active MCP server, sums their tokens into `total_estimated_tokens`, and exposes `result.activeConfig` (claudeMd cascade tokens, mcpServerCount, pluginCount, skillCount).
- **`scoringVersion: 'v5'`** field on `scoreByArea` output for cross-version drift detection.
- **`WEIGHTS`** named export from `scanners/lib/severity.mjs` (`Object.freeze`).
### Changed
- **BREAKING (intentional, F3):** `scoreByArea` is now severity-weighted. Penalty = `Σ count[s] * WEIGHTS[s]`; `passRate = max(0, 100 - penalty / max(10, findingCount * 4) * 100)`. Lows no longer crater an area's grade; a single high or critical consumes a large fraction of budget. `baseline-all-a` fixture remains all-A (no critical/high on that fixture).
- **BREAKING (intentional, F2):** MCP server token estimates jump from a flat 15 to ≥ 500. `whats-active` totals and TOK hotspots will report higher numbers for any project with active MCP servers.
- **BREAKING (intentional, F5):** Pattern D / `CA-TOK-004` (sonnet-era signature) is no longer emitted. Suppression entries for `CA-TOK-004` are now no-ops; downstream tools that filter on the ID should drop it. The catalogue entry was removed from `knowledge/opus-4.7-patterns.md` and `commands/tokens.md`.
- **Hotspots contract (F4):** the v4 padding loop and `take` dead-code are gone. Hotspots may now contain fewer than 3 entries for tiny projects (the honest answer); contract still bounds at ≤ 10.
### Migration notes
- `CA-TOK-*` glob suppression entries continue to suppress 001-003. Existing exact `CA-TOK-004` entries are harmless but obsolete — remove them at convenience.
- Posture/JSON consumers reading `areas[*].score` will see different values for non-clean configs. Use `result.scoringVersion === 'v5'` to detect.
### Tests
- 543 → 563 across the alpha.1 commits (+9 severity-weighting/scoring, +4 estimateTokens 'mcp', +1 MCP caller migration, +3 readActiveConfig integration, +2 hotspots-uniqueness, +2 sonnet-era zero-finding).
- New fixture `tests/fixtures/tok-active-config/` — minimal repo with `.mcp.json` (2 servers), `CLAUDE.md`, plugin skeleton.
## [4.0.0] - 2026-04-19
### Summary
Opus 4.7 era upgrade. New TOK scanner detects token-efficiency anti-patterns (cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era minimal setups). Token Efficiency joins the quality scorecard as the 8th area. Scanner-agent and verifier-agent migrate from haiku → sonnet per global no-haiku policy.
### Added
- **`token-hotspots.mjs`** scanner (CA-TOK-001..004) — 4 patterns aligned with Opus 4.7 token-cost dynamics:
- CA-TOK-001 cache-breaking volatile content (timestamps/UUIDs in top 30 lines of CLAUDE.md)
- CA-TOK-002 redundant tool permissions (duplicate or subset overlaps)
- CA-TOK-003 deep @import chains (>2 hops on the load path)
- CA-TOK-004 sonnet-era minimal setup (no skills/MCP/hooks/managed/plugins)
- **`/config-audit tokens [path] [--global]`** — ranked hotspot table + per-pattern findings.
- **`scanners/token-hotspots-cli.mjs`** — standalone CLI emitting `total_estimated_tokens`, `hotspots`, and per-finding output.
- **Token Efficiency** as the 8th quality area in the posture scorecard (now 9 scanners total: CML/SET/HKV/RUL/MCP/IMP/CNF/GAP/TOK).
- `id` field on every area in the scorecard payload (`token_efficiency`, `instruction_clarity`, etc.) for stable downstream lookup.
- 13 new TOK scanner tests + 3 CLI tests + posture grade-stability test for `token_efficiency`.
- Knowledge refresh: `knowledge/opus-4.7-patterns.md`, plus 2026-04 deltas (v2.1.83–v2.1.111) added to `feature-evolution.md`, `claude-code-capabilities.md`, and `hook-events-reference.md` from `research/03-claude-code-changes-config-surfaces.md`.
### Changed
- **BREAKING (additive surface):** Quality areas count 7 → 8. Posture JSON consumers that hard-coded 7 areas must update.
- **BREAKING (model migration):** `scanner-agent` and `verifier-agent` migrated `haiku` → `sonnet`. Latency and cost trade-offs accepted; deterministic scanner CLIs preferred over agent invocations.
- Scanner count: 8 → 9 (TOK added).
- Command count: 16 → 17 (`/config-audit tokens` added).
- Version bump: `3.1.0` → `4.0.0`.
## [3.1.0] - 2026-04-14
### Summary
New read-only command `/config-audit whats-active` — shows exactly what Claude Code loads for a given repo, with token estimates.
### Added
- **`/config-audit whats-active [path]`** — inventory of active plugins, skills, MCP servers, hooks, and CLAUDE.md cascade for a repo, with source attribution (user/project/plugin) and rough token estimates. Read-only, <2s.
- `scanners/lib/active-config-reader.mjs` — pure async helper: `readActiveConfig()`, `detectGitRoot()`, `walkClaudeMdCascade()`, `readClaudeJsonProjectSlice()` (longest-prefix matching), `enumeratePlugins()`, `enumerateSkills()`, `readActiveHooks()`, `readActiveMcpServers()`, `estimateTokens()`.
- `scanners/whats-active.mjs` — thin CLI shim supporting `--json`, `--output-file`, `--verbose`, `--suggest-disables`.
- Optional `--suggest-disables` flag surfaces deterministic disable candidates (disabled MCP servers, zero-item plugins, unreferenced plugins, orphan skills) and invites an LLM judgment pass in the command.
- 36 new tests in `tests/lib/active-config-reader.test.mjs`, plus a `rich-repo` tmpdir fixture helper.
### Changed
- Version bump: `3.0.1` → `3.1.0` (minor, additive feature, no breaking changes).
- Command count: 15 → 16.
## [3.0.1] - 2026-04-04
### Summary
Cross-platform fix — scanners, hooks, and lib now work correctly on Windows.
### Fixed
- `file-discovery.mjs`: depth calculation, agent/command/plugin path matching now use `path.sep`
- `scan-orchestrator.mjs`: fixture-path filtering now uses `path.sep`
- `post-edit-verify.mjs`: rules-dir regex handles both `/` and `\` separators
- `auto-backup-config.mjs`: rules-dir detection now uses `path.sep`
- `import-resolver.mjs`: circular import display uses `basename()`, `/tmp` fallback replaced with `os.tmpdir()`
- `string-utils.mjs`: `normalizePath` trailing separator regex handles both `/` and `\`
### Added
- 4 cross-platform path tests (total 486 tests)
## [3.0.0] - 2026-04-04
### Summary
Health redesign — configuration health is now quality-only. Feature utilization removed from grades entirely.
### Changed
- **Health = quality only.** 7 deterministic scanners (CML, SET, HKV, RUL, MCP, IMP, CNF) determine your grade. Feature Coverage is no longer a graded area.
- **Feature recommendations are opt-in.** Unused features shown as "opportunities" via `/config-audit feature-gap`, grouped by impact (high/medium/explore), backed by Anthropic docs. No more "Feature Coverage: F" for correct minimal setups.
- **Posture output redesigned.** Shows `Health: {grade} ({score}/100)` with 7 quality areas. Removed utilization %, maturity level, segment label.
- **Feature-gap is interactive.** Users select recommendations to implement directly — no manual file editing required. Backup created automatically.
- **avgScore bug fixed.** Grade letter and displayed score now computed from the same population (quality areas only).
### Added
- `generateHealthScorecard()` in scoring.mjs — quality-only scorecard
- `opportunitySummary()` in feature-gap-scanner.mjs — groups findings by impact tier
- `opportunityCount` field in posture JSON output
- "Official Configuration Guidance" section in knowledge base (Anthropic docs, proven impacts)
- 21 new tests (total 482 across 27 test files)
### Removed
- `S2-PROMPT.md` and `V2-ANNOUNCEMENT.md` — v2 development artifacts
- Utilization %, maturity level, segment label from posture terminal output and reports
- Feature Coverage row from area breakdown tables
- "Top Actions" sourced from GAP findings (replaced by opportunities pointer)
### Backward Compatibility
- JSON output preserves all legacy fields (utilization, maturity, segment) for programmatic consumers
- Drift baselines unaffected — GAP findings still present in envelopes
- All existing exports maintained (calculateUtilization, determineMaturityLevel, etc.)
## [2.2.0] - 2026-04-04
### Summary
UX quality fix — fixture filtering, session path migration, output polish.
### Added
- Automatic test-fixture filtering in scan-orchestrator: findings from `tests/`, `examples/`, `__tests__/` excluded from grades, stored in `env.fixture_findings`
- `--include-fixtures` CLI flag for scan-orchestrator and posture to override filtering
- `scan-orchestrator.test.mjs` — 20 new tests for fixture filtering and `isFixturePath`
- Legacy session path detection in cleanup command
### Changed
- Session storage moved from `~/.config-audit/` to `~/.claude/config-audit/` (pathguard compatible)
- Self-audit grade: F → A (98) after fixture filtering
- Combined scanner + posture into single Bash call in default audit command
- Removed "F grade is misleading" disclaimer — grades are now accurate
- All CLI banners and envelope metadata updated to v2.2.0
- 461 tests (up from 441), 27 test files (up from 26)
### Removed
- Manual fixture counting instruction in `config-audit.md` (orchestrator handles it)
- Redundant `isFixtureOrExample` filter in `self-audit.mjs` (promoted to orchestrator)
## [2.1.0] - 2026-04-03
### Summary
UX redesign — auto-scope detection, zero questions, simplified command surface.
### Changed
- `/config-audit` now runs full audit automatically (auto-detects scope from git context)
- Removed mode selection prompts — scope override via `/config-audit full|repo|home|current`
- Simplified from 17 to 15 commands (removed quick, report, watch; added help)
- All CLI banners and envelope metadata updated to v2.1.0
### Added
- `/config-audit help` command with categorized command reference
- Auto-scope detection from git context (repo vs home vs full-machine)
### Removed
- `/config-audit:quick` (merged into default `/config-audit`)
- `/config-audit:report` (merged into analyze output)
- `/config-audit:watch` (use `/config-audit drift` instead)
## [2.0.0] - 2026-04-03 (v2.0 Complete)
### Summary
Complete rewrite from LLM-only prototype to deterministic scanner-backed configuration intelligence.
7 development sessions (S1-S7), ~15,000 lines of code, 408+ tests.
### Highlights
- 8 deterministic scanners (CML, SET, HKV, RUL, MCP, IMP, CNF, GAP) + PLH standalone
- Feature gap analysis with 25 dimensions across 4 tiers
- Auto-fix engine with 9 fix types + backup/rollback
- Drift detection with baseline comparison
- Suppression engine (.config-audit-ignore)
- Self-audit CLI
- 17 commands, 6 agents, 4 hooks
- 408+ tests (zero external dependencies)
### Added (S7)
- Example projects: `examples/minimal-setup/` and `examples/optimal-setup/`
- Demo script: `examples/run-demo.sh`
- `.config-audit-ignore` for self-audit suppressions
- `V2-ANNOUNCEMENT.md`
- `DEPRECATED.md` for capability-auditor skill
### Fixed (S7)
- `hooks.json`: SessionStart and Stop timeout 5ms → 5000ms
- `self-audit.mjs`: Suppression now enabled (was hardcoded to `suppress: false`)
### Changed (S7)
- README.md: Complete rewrite for public release
- CLAUDE.md: Added Suppressions section
- `.gitignore`: Added `node_modules/` and `S*-PROMPT.md`
## [1.6.0] - 2026-04-03 (v2.0 S6: Unified Reports + Self-Audit + Suppressions)
### Added
- **Report generator** `scanners/lib/report-generator.mjs` — unified markdown reports: generatePostureReport(), generateDriftReport(), generatePluginHealthReport(), generateFullReport()
- **Suppression engine** `scanners/lib/suppression.mjs` — `.config-audit-ignore` file support with exact IDs and glob patterns (CA-SET-*), audit trail via `suppressed_findings` in envelope
- **Self-audit CLI** `scanners/self-audit.mjs` — runs all scanners + plugin health on this plugin: `node self-audit.mjs [--json] [--fix]`, exit codes 0/1/2
- **PostToolUse hook** `post-edit-verify.mjs` — verifies config files after Edit/Write, blocks if new critical/high findings introduced
- **New command**: `/config-audit:report` — generate unified report (posture + optional drift/plugin-health)
- **Test fixture** `.config-audit-ignore` in fixable-project
- 54 new tests (total 408 across 25 test files)
### Changed
- `scan-orchestrator.mjs`: suppression integration — applies .config-audit-ignore after all scanners run, `--no-suppress` flag to disable
- `hooks.json`: added PostToolUse event with post-edit-verify
## [1.5.0] - 2026-04-03 (v2.0 S5: Drift + Watch + Plugin Health)
### Added
- **Diff engine** `scanners/lib/diff-engine.mjs` — diffEnvelopes() comparing baseline vs current, formatDiffReport() for terminal output
- **Baseline manager** `scanners/lib/baseline.mjs` — save/load/list/delete named baselines in ~/.claude/config-audit/baselines/
- **Drift CLI** `scanners/drift-cli.mjs` — standalone: `node drift-cli.mjs <path> [--save] [--baseline name] [--json] [--list]`
- **Plugin health scanner** `scanners/plugin-health-scanner.mjs` (PLH) — validates plugin structure, frontmatter, cross-plugin conflicts (runs independently, not in scan-orchestrator)
- **3 new commands**:
- `/config-audit:drift` — compare current config against saved baseline
- `/config-audit:watch` — on-demand drift check with baseline monitoring
- `/config-audit:plugin-health` — audit plugin structure and cross-plugin coherence
- **Test fixtures** `test-plugin/` (valid) and `broken-plugin/` (invalid) for plugin health tests
- 48 new tests (total 354 across 21 test files)
## [1.4.0] - 2026-04-03 (v2.0 S4: Fix + Rollback Action Pillar)
### Added
- **Fix engine** `scanners/fix-engine.mjs` — deterministic auto-fix for 9 fix types:
- `json-key-add` (missing $schema), `json-key-remove` (deprecated keys), `json-key-type-fix` (type mismatches, invalid effortLevel), `json-restructure` (hooks array→object, matcher object→string), `frontmatter-rename` (globs→paths), `file-rename` (non-.md→.md)
- **Rollback engine** `scanners/rollback-engine.mjs` — listBackups(), restoreBackup(), deleteBackup() with checksum verification
- **Fix CLI** `scanners/fix-cli.mjs` — standalone: `node fix-cli.mjs <path> [--apply] [--json] [--global]`, dry-run by default
- **Backup lib** `scanners/lib/backup.mjs` — shared backup module with checksums and manifests
- **2 new commands**:
- `/config-audit:fix` — scan, plan, backup, apply, verify in one flow
- `/config-audit:rollback` — list or restore from backups
- **PreToolUse hook** `auto-backup-config.mjs` — auto-backup config files before Edit/Write
- **Test fixture** `fixable-project/` — fixture with all 9 fixable issue types
- 38 new tests (total 306 across 17 test files)
### Changed
- `file-discovery.mjs`: walkRulesDir now discovers all files (not just .md) for non-.md validation
- `backup-before-change.mjs`: refactored to use shared `lib/backup.mjs` (no logic duplication)
- hooks.json: added PreToolUse event with auto-backup
## [1.3.0] - 2026-04-03 (v2.0 S3: Posture + Feature Gap Commands)
### Added
- **Scoring module** `scanners/lib/scoring.mjs` — utilization, maturity (5 levels), segments, area scoring, scorecard generation
- **Posture CLI** `scanners/posture.mjs` — standalone Node.js tool: `node posture.mjs <path> [--json] [--global]`
- **2 new commands**:
- `/config-audit:posture` — quick scorecard with A-F grades, utilization%, maturity level
- `/config-audit:feature-gap` — deep gap analysis with prioritized next-best-actions
- **feature-gap-agent** — Opus agent for deep analysis, report generation (max 200 lines)
- **Knowledge file** `gap-closure-templates.md` — 11 templates with effort/gain estimates
- **HTML report template** `templates/feature-gap-report.html` — visual report with progress bars, grade badges
- 64 new tests (total 268 across 14 test files)
### Changed
- Tier weighting: T1 gaps count 3x, T2 count 2x, T3/T4 count 1x in utilization score
- Maturity is threshold-based: highest level where ALL requirements are met
## [1.2.0] - 2026-04-03 (v2.0 S2: Advanced Scanners + Knowledge Base)
### Added
- **4 advanced scanners** (zero external deps):
- `mcp-config-validator.mjs` (MCP) — server types, trust levels, env vars, unknown fields
- `import-resolver.mjs` (IMP) — broken @imports, circular refs, deep chains, tilde paths
- `conflict-detector.mjs` (CNF) — settings conflicts, permission contradictions, hook duplicates
- `feature-gap-scanner.mjs` (GAP) — 25 feature gaps across 4 tiers (Foundation/Depth/Advanced/Enterprise)
- **Knowledge base** — 5 reference documents: capabilities, best practices, anti-patterns, hook events, feature evolution
- **New test fixtures** — `.mcp.json` files, @import chains, `conflict-project/` fixture
- 75 new tests (total 204 across 12 test files)
### Changed
- Scan orchestrator runs 8 scanners (was 4)
- Analyzer agent cross-references scanner findings with knowledge base
## [1.1.0] - 2026-04-03 (v2.0 S1: Scanner Foundation)
### Added
- **Deterministic scanner infrastructure** — 4 Node.js scanners (zero external deps):
- `claude-md-linter.mjs` (CML) — CLAUDE.md structure, length, sections, @imports, duplicates
- `settings-validator.mjs` (SET) — settings.json schema, unknown/deprecated keys, type checks
- `hook-validator.mjs` (HKV) — hooks.json format, script existence, event validity, timeouts
- `rules-validator.mjs` (RUL) — .claude/rules/ glob matching, orphan detection, deprecated fields
- **Scanner lib** — 5 shared modules: severity, output, file-discovery, yaml-parser, string-utils
- **Scan orchestrator** — `scan-orchestrator.mjs` runs all scanners, outputs JSON envelope
- **Test infrastructure** — 129 tests across 8 test files using node:test (zero deps)
- **Test fixtures** — 4 fixture projects (healthy, broken, empty, minimal)
- Finding ID format: `CA-{SCANNER}-{NNN}` (e.g. `CA-CML-001`)
### Fixed
- Agent model mismatches: scanner→haiku, analyzer→sonnet, planner→opus, implementer→sonnet, verifier→haiku
### Changed
- CLAUDE.md rewritten in English for public release readiness
## [1.0.0] - 2026-02-11
### Added
- Cross-platform support (macOS, Linux, Windows)
### Fixed
- `stop-session-reminder.mjs`: Use `path.basename`/`path.dirname` instead of hardcoded `/` split
- `backup-before-change.mjs`: Handle both `/` and `\` path separators in safe filename generation
### Removed
- "Windows: hooks are 100% bash" from known gaps (was incorrect — all hooks are Node.js)
## [0.7.0] - 2026-02-07
### Note
Version reset from 1.2.0 to reflect actual maturity. Previous version was inflated — this plugin has never been externally tested.
### What exists today
- 6 specialized agents (scanner, analyzer, interviewer, planner, implementer, verifier)
- Full machine-wide Claude Code configuration discovery
- Scope selection (current project, repo, home, full machine)
- Inheritance hierarchy mapping and conflict detection
- Mandatory backups before any changes
- Rollback support
- Syntax validation for all configuration files
- Quick audit-only mode
- Full optimization workflow with HITL checkpoints
### Known gaps
- Testing: no automated tests
- Onboarding: never verified that a new user can install and use from scratch
- External verification: nobody else has ever used this

118
plugins/config-audit/CLAUDE.md
View file

@ -1,118 +0,0 @@
# Config-Audit Plugin
Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically.
## What this plugin does
Analyzes and optimizes Claude Code configuration across three pillars:
- **Health** — Deterministic scanners verify correctness, consistency, and completeness
- **Opportunities** — Context-aware recommendations for features that could benefit your project
- **Action** — Auto-fix with backup/rollback
## Commands
### Core (just run `/config-audit` to get started)
| Command | Description |
|---------|-------------|
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
| `/config-audit posture` | Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene) |
| `/config-audit tokens` | Opus-4.7-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer |
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
| `/config-audit rollback` | Restore configuration from backup |
| `/config-audit plan` | Create action plan from audit findings |
| `/config-audit implement` | Execute plan with backups + auto-verify |
| `/config-audit help` | Show all commands |
### Additional
| Command | Description |
|---------|-------------|
| `/config-audit drift` | Compare current config against saved baseline |
| `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence |
| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) |
| `/config-audit discover` | Run discovery phase only |
| `/config-audit analyze` | Run analysis phase only |
| `/config-audit interview` | Gather user preferences (opt-in) |
| `/config-audit status` | Show current session state |
| `/config-audit cleanup` | Clean up old sessions |
## Agents
| Agent | Role | Model | Color | Tools |
|-------|------|-------|-------|-------|
| scanner-agent | Find config files | sonnet | cyan | Read, Glob, Grep, Write |
| analyzer-agent | Generate report | sonnet | blue | Read, Glob, Grep, Write |
| planner-agent | Create action plan | opus | yellow | Read, Glob, Write |
| implementer-agent | Execute changes | sonnet | magenta | Read, Write, Edit, Bash, Glob |
| verifier-agent | Verify results | sonnet | purple | Read, Glob, Grep |
| feature-gap-agent | Context-aware feature recommendations | opus | green | Read, Glob, Grep, Write |
## Hooks
| Event | Script | Purpose |
|-------|--------|---------|
| PreToolUse | `auto-backup-config.mjs` | Auto-backup config files before Edit/Write |
| PostToolUse | `post-edit-verify.mjs` | Verify config files after Edit/Write, block on new critical/high |
| SessionStart | `session-start.mjs` | Checks for active (unfinished) sessions |
| Stop | `stop-session-reminder.mjs` | Reminds about current session phase |
## Reference docs (read on demand)
- **Scanner inventory, lib modules, action engines, knowledge base:** `docs/scanner-internals.md`
- **Plain-language output (v5.1.0), humanizer vocabularies, output modes:** `docs/humanizer.md`
## Plain-Language Output (v5.1.0) — summary
Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings get three decorated fields:
- `userImpactCategory` — Configuration mistake / Conflict / Wasted tokens / Dead config / Missed opportunity
- `userActionLanguage` — Fix this now / Fix soon / Fix when convenient / Optional cleanup / FYI (derived from severity)
- `relevanceContext` — `affects-everyone` (default) / `affects-this-machine-only` (`*.local.*` files) / `test-fixture-no-impact`
`--raw` bypasses the humanizer for byte-stable v5.0.0 output. `--json` is also byte-stable. Full detail and Wave 5 lessons: `docs/humanizer.md`.
## Suppressions
Create `.config-audit-ignore` at project root to suppress known findings:
```
CA-SET-003 # Exact ID
CA-GAP-* # Glob pattern (all GAP findings)
```
Suppressed findings tracked in envelope's `suppressed_findings` for audit trail. Disable with `--no-suppress`.
## Architecture
### Workflow
```
/config-audit → discover + analyze (auto) → plan → implement → verify
```
Default: auto-detects scope from git context. Override with `/config-audit full|repo|home|current`. Delta mode: `--delta` (incremental).
### Session Directory
```
~/.claude/config-audit/sessions/{session-id}/
├── scope.yaml, discovery.json, state.yaml
├── findings/, analysis-report.md, action-plan.md
├── backups/, implementation-log.md
└── interview.md (if interview run)
```
### Finding ID Format
`CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`, `CA-TOK-005`, `CA-CPS-001`, `CA-DIS-001`, `CA-COL-001`
## Testing
```bash
node --test 'tests/**/*.test.mjs'
```
792 tests across 52 test files (15 lib + 28 scanner + 1 hook + 1 agent + 3 commands + 4 top-level). Test fixtures in `tests/fixtures/`. Top-level humanizer tests: `json-backcompat.test.mjs`, `raw-backcompat.test.mjs`, `scenario-read-test.test.mjs`, `snapshot-default-output.test.mjs`.
## Gotchas
- Session directories accumulate — use `/config-audit cleanup` to manage
- Scanners run on Node.js >= 18 (uses node:test, node:fs/promises)
- Plugin CLAUDE.md files in node_modules should be excluded via scope

131
plugins/config-audit/GOVERNANCE.md
View file

@ -1,131 +0,0 @@
# Governance
How this marketplace is maintained, what you can expect from upstream, and how it's meant to be used.
## TL;DR
- Solo-maintained, AI-assisted development, MIT licensed.
- **Fork-and-own is the default model.** Upstream is a starting point, not a vendor.
- Issues welcome as signals. Pull requests are not accepted — see [Why no PRs](#pull-requests--no).
- No SLA. Best-effort bug fixes and security advisories. Breaking changes happen and are noted in each plugin's CHANGELOG.
---
## Can I trust this?
Be honest with yourself about what you're adopting:
- **One maintainer.** If I get hit by a bus, the bus wins. The repos stay up under MIT, but no one owes you a fix.
- **AI-generated code with human review.** Every plugin is built through dialog-driven development with Claude Code. I read, test, and judge the output before it ships, but I'm not auditing every line the way a security firm would. Treat it accordingly.
- **No commercial interests.** I'm not selling a SaaS, not steering you toward a paid tier, not collecting telemetry. The plugins run locally in your Claude Code installation.
- **MIT licensed.** Fork it, modify it, ship it under your own name.
If you work somewhere that needs vendor accountability, support contracts, or signed assurances — **this isn't that.** Use it as a reference implementation, fork it into your own organization, and own the result.
---
## How this is meant to be used
### Fork-and-own
The intended workflow:
1. **Fork** the marketplace (or a single plugin) into your own organization or namespace.
2. **Tailor** it to your context — terminology, integrations, cycle lengths, regulatory framing, whatever doesn't fit out of the box.
3. **Maintain it yourself.** Treat your fork as the canonical version for your team.
4. **Watch upstream selectively.** Cherry-pick changes that help, ignore changes that don't. There's no obligation to stay in sync.
This isn't a workaround for not accepting PRs. It's the actual recommended adoption pattern, especially for plugins like `okr` and `ms-ai-architect` where every Norwegian public sector organization will need its own tildelingsbrev mappings, terminology, and integrations. A central "one true plugin" would be wrong for everyone.
### What to change first when you fork
Each plugin differs, but the common edits are:
- **Identity** — rename the plugin, replace authorship, update README.
- **External integrations** — issue trackers, knowledge bases, dashboards, observability backends. The plugins ship as starting points, not pre-wired. Every organization must configure its own integrations.
- **Norwegian-specific framing** — relevant for `okr` and `ms-ai-architect`. Other plugins are jurisdiction-neutral. Rewrite for your jurisdiction if you're outside Norway.
- **Reference docs** — the knowledge base in each plugin reflects my reading. Replace with your organization's authoritative sources.
- **Hooks and policies** — security thresholds, blocked commands, and audit gates are tuned to my taste. Tune them to yours.
### Staying current with upstream
If you want to pull in upstream changes later:
- **Cherry-pick, don't merge.** Each plugin moves independently and breaking changes land without ceremony.
- **Read the CHANGELOG first.** Every plugin has one.
- **Keep your customizations in clearly-named files.** The harder upstream is to merge cleanly, the more painful staying current becomes. A `local/` directory or `*.local.md` convention helps.
---
## What upstream provides
| | What I do | What I don't |
|---|---|---|
| **Bug fixes** | Best-effort when I notice or get a clear report | No SLA, no triage commitment |
| **Security issues** | Investigate within reasonable time, document in CHANGELOG | No CVE process, no embargo coordination |
| **New features** | When they fit my own usage | Not on request |
| **Norwegian public sector context** | Kept current as long as the project lives | If I lose interest or change jobs, the framing freezes |
| **Breaking changes** | Documented in CHANGELOG | They happen — version pin if you need stability |
| **Compatibility** | Tracked against current Claude Code releases | No long-term support branches |
If any of this is a dealbreaker — fork now, version-pin, and stop reading upstream.
---
## How to contribute
### Issues — yes, please
Issues are the most valuable thing you can send me:
- **Bug reports** with reproduction steps. Even a screenshot helps.
- **Use-case feedback.** "I tried to use this in my organization and X didn't fit" is genuinely useful, even if I can't fix it for you.
- **Pointers to better sources.** If you know a DFØ veileder, an NSM guideline, or an academic paper that contradicts what's in a knowledge base, tell me.
- **Security findings.** See each plugin's `SECURITY.md` for disclosure preference where one exists; otherwise email rather than open a public issue.
### Pull requests — no
This is deliberate, not laziness:
- **Solo review is a bottleneck.** Honest PR review takes me longer than rewriting from scratch. The math doesn't work.
- **Forks are where the value is.** The fork-and-own model means upstream consolidation isn't the point. Your organization's adaptations belong in your fork, not mine.
- **AI-generated code complicates provenance.** Every line here is produced through dialog with Claude Code, with me as the judge. Mixing in PRs from contributors with different processes and licensing assumptions creates a mess I'd rather not untangle.
If you've built something useful on top of a fork, **publish it under your own name and link back.** I'll happily list notable forks here once they exist.
### Notable forks
*(To be populated as forks emerge. If you've forked one of these plugins for production use, open an issue and I'll add a link.)*
---
## Relationship between plugins
These plugins are **independent**. Install one without the others, fork one without the others. They share conventions (slash command naming, hook patterns, AI-generated disclosure) but no runtime dependencies.
The marketplace is a **catalog**, not a suite. Don't fork the whole repo unless you actually want to maintain everything.
---
## Versioning and stability
- **Semantic versioning per plugin.** Each plugin has its own `CHANGELOG.md` and version number.
- **Breaking changes happen.** I bump the major version when they do, but I don't run an LTS branch.
- **Pin your version.** If stability matters more than features, install a specific version and stay there until you choose to upgrade.
---
## Public sector adoption notes
For Norwegian etater specifically:
- **DPIA-relevant data flows are documented in the relevant plugin README where applicable.** Read them before installation.
- **No data leaves your machine** beyond what Claude Code itself sends to Anthropic. The plugins themselves do not call external services unless you configure an integration.
- **Drøftingsplikt and ledelsesansvar** are not replaced by these tools. The `okr` plugin coaches; it does not decide. The `ms-ai-architect` plugin advises; it does not approve.
- **Choose your Claude deployment carefully.** claude.ai vs. API direct vs. Bedrock in EU region have different data residency profiles. The plugins don't choose for you.
---
## License
MIT for all plugins in this marketplace. See each plugin's `LICENSE` file.

21
plugins/config-audit/LICENSE
View file

@ -1,21 +0,0 @@
MIT License
Copyright (c) 2025-2026 Kjell Tore Guttormsen
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

625
plugins/config-audit/README.md
View file

@ -1,625 +0,0 @@
# Config-Audit Plugin for Claude Code
> Know if your configuration is correct. Find what could improve it. Fix it automatically.
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
![Version](https://img.shields.io/badge/version-5.1.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Scanners](https://img.shields.io/badge/scanners-12-cyan)
![Commands](https://img.shields.io/badge/commands-18-green)
![Agents](https://img.shields.io/badge/agents-6-orange)
![Hooks](https://img.shields.io/badge/hooks-4-red)
![Tests](https://img.shields.io/badge/tests-792+-brightgreen)
![License](https://img.shields.io/badge/license-MIT-lightgrey)
A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, an Opus-4.7-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.
---
## Table of Contents
- [What's New in v5.1.0](#whats-new-in-v510)
- [What Is This?](#what-is-this)
- [The Configuration Problem](#the-configuration-problem)
- [Quick Start](#quick-start)
- [Feature Opportunities](#feature-opportunities--context-aware-recommendations)
- [Workflow Examples](#workflow-examples)
- [Commands](#commands)
- [Deterministic Scanners](#deterministic-scanners)
- [Agent Architecture](#agent-architecture)
- [Hooks & Safety](#hooks--safety)
- [Skills](#skills)
- [Suppressions](#suppressions)
- [Examples & Self-Audit](#examples--self-audit)
- [Scanner Library](#scanner-library-scannerslib)
- [Knowledge Base](#knowledge-base-knowledge)
- [Testing](#testing)
- [Gotchas](#gotchas)
- [Data Storage & Safety Guarantees](#data-storage--safety-guarantees)
- [What This Plugin Does Not Cover](#what-this-plugin-does-not-cover)
- [Version History](#version-history)
- [License](#license)
---
## What's New in v5.1.0
**Plain-language UX humanizer** — every command's default output now leads with prose. Findings are grouped by what they mean for the user (Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config) and led with an urgency phrase (Fix this now, Fix soon, Fix when convenient, Optional cleanup, FYI). Technical IDs (`CA-CML-001`, `CA-TOK-005`, …) still appear, but at end-of-line where they belong as references rather than headlines.
### Before / after
```
v5.0.0 default
- [low] CA-CNF-001: Hook duplicate event registration
v5.1.0 default
- [low] The same automation is set up more than once
v5.1.0 with --json (machine-readable, byte-stable)
{ "id": "CA-CNF-001", "title": "...", "userImpactCategory": "Conflict",
"userActionLanguage": "Optional cleanup", "relevanceContext": "affects-everyone" }
```
### Plain-language vocabulary
The toolchain uses these terms when describing findings:
| User-facing label | What it means |
|-------------------|---------------|
| Fix this now | Something is broken or risky and should be addressed immediately |
| Fix soon | High-priority issue worth scheduling this week |
| Fix when convenient | Real issue but not urgent |
| Optional cleanup | Tidy-up that improves polish but isn't required |
| FYI | Informational; no action expected |
| Configuration mistake | A configuration file has an error or omission |
| Conflict | Two configuration sources disagree |
| Wasted tokens | Configuration is loading content that costs tokens without payback |
| Missed opportunity | A Claude Code feature you aren't using that could help your project |
| Dead config | Configuration that has no effect (e.g., a permission that's also denied) |
### Backwards compatibility — the `--raw` flag
Every CLI accepts `--raw` for byte-stable v5.0.0 verbatim output (technical IDs, raw severity, no prose translation). `--json` is unchanged from v5.0.0 — already byte-stable for programmatic consumption. Use `--raw` only if you've built tooling against v5.0.0 stderr scrapes; for new automation, prefer `--json`.
```bash
node scanners/posture.mjs . # v5.1.0 plain-language default
node scanners/posture.mjs . --raw # v5.0.0 verbatim (byte-stable)
node scanners/posture.mjs . --json # unchanged JSON envelope
```
### What's not changed
- All scanner internals (12 scanners + standalone PLH) emit the same finding IDs and structural data — humanization happens at output-formatting time only
- `--json` envelope shape is byte-stable with v5.0.0 (humanizer fields are additive on findings only in default mode; the `--json` path bypasses humanization entirely)
- 635 tests grew to 792 (+157 covering humanizer module, scenario read-tests, forbidden-words lint, JSON / `--raw` backwards-compat, default-output snapshots, and command-template / agent-prompt shape)
---
## What Is This?
Claude Code reads instructions from at least 7 different file types across multiple scopes: `CLAUDE.md`, `settings.json`, `.claude/rules/`, `hooks.json`, `.mcp.json`, `.claudeignore`, and `settings.local.json`. Each can exist at project level, user level, or both. Plugins add more. The system is powerful — but nobody tells you what you're using wrong, what you're missing, or what's silently conflicting.
This plugin provides three layers of configuration intelligence:
- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, Opus-4.7-era token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
- **Opportunities** — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance
- **Action** — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial
> [!TIP]
> Start with `/config-audit posture` for a 30-second scorecard, then `/config-audit` for the full picture.
---
## The Configuration Problem
You've been using Claude Code for weeks — maybe months. It works fine. But there's a gap between "works fine" and "configured well," and it's invisible until someone shows you.
**These are not hypotheticals.** They come from running the posture scanner on real setups:
- Your global `CLAUDE.md` says "never use mocks" but a project rule says "prefer mocks" — Claude gets confused and you don't know why
- You've written dozens of projects but have never set up hooks, rules, or keybindings because you didn't know they existed
- Three plugins define hooks for the same event with conflicting behavior
- Your `settings.json` has a deprecated key that silently does nothing
- An `@import` in your CLAUDE.md points to a file you deleted last week
- You're using maybe 30% of what Claude Code can do — and you don't know what the other 70% is
The plugin ships with two example projects. Run them yourself:
### `examples/minimal-setup/` — just a CLAUDE.md, nothing else
```
> node scanners/posture.mjs examples/minimal-setup/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Config-Audit Health Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Health: A (99/100) 7 areas scanned
Area Scores
───────────
CLAUDE.md ............ A (90)
Settings ............. A (100) Hooks ............... A (100)
Rules ................ A (100) MCP ................. A (100)
Imports .............. A (100) Conflicts ........... A (100)
22 opportunities available — run /config-audit feature-gap for recommendations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Grade A** — nothing is broken. The health grade only reflects real issues, and this setup has none. The 22 opportunities are not failures — they're features you *could* use. Run `/config-audit feature-gap` to see which ones are relevant to your project.
### `examples/optimal-setup/` — full configuration across all 4 tiers
```
> node scanners/posture.mjs examples/optimal-setup/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Config-Audit Health Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Health: A (93/100) 7 areas scanned
Area Scores
───────────
CLAUDE.md ............ A (100) Settings ............ A (90)
Hooks ................ A (100) Rules ............... B (80)
MCP .................. A (90) Imports ............. A (100)
Conflicts ............ A (90)
3 opportunities available — run /config-audit feature-gap for recommendations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Also **Grade A** — with only 3 opportunities remaining. This project has CLAUDE.md split via `@imports`, permissions scoped to specific tools, path-scoped rules (different rules for `src/` vs. `tests/`), hooks covering multiple events, and MCP servers. Both setups are healthy — the difference is how much of Claude Code's surface area you're choosing to use.
---
## Quick Start
### Prerequisites
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
- Node.js 18+ (for standalone CLI tools)
### Installation
Add the marketplace and browse plugins with `/plugin`:
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"config-audit@ktg-plugin-marketplace": true
}
}
```
### First Scan
```bash
# Full audit with auto-scope detection (inside Claude Code)
/config-audit
# 30-second posture check (standalone, no LLM needed)
node scanners/posture.mjs /path/to/project
# Auto-fix issues with backup
node scanners/fix-cli.mjs /path/to/project --apply
```
The CLI tools work standalone — no Claude Code session needed, just Node.js 18+.
---
## Feature Opportunities — Context-Aware Recommendations
Most configuration tools stop at "is it valid?" Config-audit goes further: **what could improve your setup, and is it relevant to your project?**
The feature opportunity scanner checks 25 dimensions and groups recommendations by impact:
| Impact Level | Focus | Examples |
|--------------|-------|---------|
| **High** | Correctness & security | `permissions.deny` for sensitive files, basic hooks for safety automation |
| **Worth Considering** | Workflow efficiency | Path-scoped rules, modular `@imports`, custom agents |
| **Explore** | Nice-to-have | Keybindings, status line, output styles, agent teams |
Each recommendation is **context-aware** — it considers what your project actually contains. A solo TypeScript project gets different suggestions than a team Python monorepo. Recommendations include *why* (backed by Anthropic's official guidance) and *how* (concrete steps).
Run `/config-audit feature-gap` to see what's relevant to your project.
---
## Workflow Examples
### 1. First Time — Just Curious
You heard about this plugin and want to know where you stand:
```
/config-audit # Auto-detects scope, runs full audit
# → See your grade, top issues, and gaps
/config-audit posture # Even faster: 30-second scorecard only
```
### 2. Monthly Configuration Checkup
A quick health check — are things still clean?
```
/config-audit posture # Quick health check (A-F grade, 7 areas)
/config-audit # Full audit if grade dropped
/config-audit fix # Auto-fix deterministic issues
/config-audit posture # Verify improvement
```
### 3. Deep Optimization
You want to go from C to A. The full pipeline:
```
/config-audit # Audit — understand what you have
/config-audit feature-gap # Opportunities — context-aware recommendations
/config-audit plan # Plan — prioritized actions with risk assessment
/config-audit implement # Execute — changes with backup + verification
```
### 4. Plugin Author
You maintain Claude Code plugins and want to ensure quality:
```
/config-audit plugin-health # Audit plugin structure, frontmatter, cross-plugin conflicts
# → Checks naming, frontmatter completeness, tool grants, duplicates
```
### 5. Track Configuration Drift
Your team configuration changes over time. Track it:
```
/config-audit drift # First run creates baseline, subsequent runs show delta
# → New findings, resolved findings, unchanged, moved
/config-audit drift --save my-baseline # Save a named baseline for comparison
```
---
## Commands
### Core (just run `/config-audit` to get started)
| Command | Description |
|---------|-------------|
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
| `/config-audit posture` | Quick health scorecard: A-F grades across 10 quality areas (incl. Token Efficiency, Plugin Hygiene) |
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration |
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
| `/config-audit rollback` | Restore configuration from a previous backup |
| `/config-audit plan` | Generate prioritized action plan from audit findings |
| `/config-audit implement` | Execute plan with automatic backup + verification |
| `/config-audit help` | Show all commands with usage examples |
### Additional
| Command | Description |
|---------|-------------|
| `/config-audit drift` | Compare current config against a saved baseline |
| `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence |
| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) |
| `/config-audit discover` | Run discovery phase only |
| `/config-audit analyze` | Run analysis phase only |
| `/config-audit interview` | Set preferences for action plan _(optional)_ |
| `/config-audit status` | Show current session state and available actions |
| `/config-audit cleanup` | Remove old session directories |
### Scope
By default, `/config-audit` auto-detects scope from your git context. Override with: `/config-audit current`, `/config-audit repo`, `/config-audit home`, `/config-audit full`. Use `--delta` for incremental scanning (only new/changed findings).
---
## Deterministic Scanners
12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, Opus-4.7-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies.
**Why deterministic?** LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular `@import` chains, or catch that your global `settings.json` contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues.
| Scanner | Prefix | What It Catches |
|---------|--------|-----------------|
| `claude-md-linter.mjs` | CML | Oversized files, missing sections, broken @imports, duplicates, stale TODOs |
| `settings-validator.mjs` | SET | Schema violations, unknown/deprecated keys, type mismatches, permission issues |
| `hook-validator.mjs` | HKV | Invalid format, missing scripts, wrong event names, timeout risks |
| `rules-validator.mjs` | RUL | Bad glob patterns, orphaned rules, deprecated fields, unscoped rules |
| `mcp-config-validator.mjs` | MCP | Invalid server types, missing trust levels, exposed env vars |
| `import-resolver.mjs` | IMP | Broken @imports, circular references, deep chains, tilde path issues |
| `conflict-detector.mjs` | CNF | Settings contradictions across scopes, permission conflicts, hook duplicates |
| `feature-gap-scanner.mjs` | GAP | 25 feature checks — shown as opportunities, not grades |
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascades, bloated skill descriptions, MCP tool-schema budget |
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of the CLAUDE.md cascade — beyond the cache-prefix window but still re-loaded every turn |
| `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` and `permissions.allow` — deny wins, allow entries are dead config |
| `collision-scanner.mjs` | COL | Cross-plugin skill name collisions; user-vs-plugin overlaps |
### CLI Tools
All tools work standalone — no Claude Code session needed:
| Tool | Usage |
|------|-------|
| **Posture** | `node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]` |
| **Fix** | `node scanners/fix-cli.mjs <path> [--apply] [--json] [--global]` |
| **Drift** | `node scanners/drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
| **Tokens** | `node scanners/token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` |
| **Manifest** | `node scanners/manifest.mjs <path> [--json]` — ranked system-prompt source table |
| **What's active** | `node scanners/whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` |
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix] [--check-readme]` |
| **Full scan** | `node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress]` |
---
## Agent Architecture
Six specialized agents collaborate through the audit workflow, each matched to an appropriate model for cost and quality:
| Agent | Model | Role | Tools |
|-------|-------|------|-------|
| **scanner-agent** | Sonnet | Fast filesystem scanning, file discovery | Read, Glob, Grep, Write |
| **analyzer-agent** | Sonnet | Deep analysis, hierarchy mapping, conflict detection | Read, Glob, Grep, Write |
| **planner-agent** | Opus | Action plan generation with risk assessment | Read, Glob, Write |
| **implementer-agent** | Sonnet | Change execution with mandatory backups | Read, Write, Edit, Bash, Glob |
| **verifier-agent** | Sonnet | Post-implementation verification | Read, Glob, Grep |
| **feature-gap-agent** | Opus | Context-aware feature recommendations | Read, Glob, Grep, Write |
### Orchestration Flow
```
+-----------+
| Interview | (optional)
+-----+-----+
|
+-----------+ +---------+ +-------v---+ +-----------+
| Discover | --> | Analyze | --> | Plan | --> | Implement |
| (sonnet) | | (sonnet)| | (opus) | | (sonnet) |
+-----------+ +---------+ +-----------+ +-----+-----+
|
+-----v-----+
| Verify |
| (sonnet) |
+-----------+
```
---
## Hooks & Safety
Four hooks provide automatic safety and session continuity — they activate the moment the plugin is installed:
| Event | Script | What It Does |
|-------|--------|--------------|
| **PreToolUse** | `auto-backup-config.mjs` | Backs up any config file before Edit/Write touches it |
| **PostToolUse** | `post-edit-verify.mjs` | Re-scans after edits — blocks if new critical/high findings introduced |
| **SessionStart** | `session-start.mjs` | Checks for incomplete audit sessions so you can resume |
| **Stop** | `stop-session-reminder.mjs` | Shows current phase so your next session picks up where you left off |
All hooks are Node.js (`.mjs`) for cross-platform compatibility (macOS, Linux, Windows).
> [!IMPORTANT]
> The PreToolUse and PostToolUse hooks only activate when config-audit is modifying configuration files. They don't interfere with your normal development workflow.
---
## Skills
| Skill | Trigger | Description |
|-------|---------|-------------|
| `config-hierarchy` | "CLAUDE.md hierarchy", "config file locations", "settings.json structure" | Comprehensive reference for Claude Code's configuration hierarchy — CLAUDE.md, settings.json, managed config, @imports, path-scoped rules |
Skills activate automatically when your question matches their trigger patterns.
---
## Suppressions
### Finding ID Format
Every finding has a unique ID: `CA-{SCANNER}-{NNN}` — where `{SCANNER}` is the scanner prefix (see table above) and `{NNN}` is a sequential number. Examples: `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`.
### Suppression
Some findings are expected — maybe you intentionally have a large CLAUDE.md, or a feature gap doesn't apply to your workflow. Create a `.config-audit-ignore` file to suppress them:
```
# Suppress by exact finding ID
CA-SET-003
# Suppress by scanner prefix (glob pattern)
CA-GAP-*
# Suppress all plugin health findings
CA-PLH-*
```
Suppressed findings are tracked in the scan envelope's `suppressed_findings` array for audit trail — nothing is silently hidden. Use `--no-suppress` to see everything.
---
## Examples & Self-Audit
### Example Projects
The `examples/` directory contains two projects shown in the [before/after demo](#the-configuration-problem) above:
| Example | Description | Grade | Opportunities |
|---------|-------------|-------|---------------|
| `minimal-setup/` | Single CLAUDE.md, nothing else | A | 22 |
| `optimal-setup/` | Full configuration across all 4 tiers | A | 3 |
```bash
# Run them yourself
node scanners/posture.mjs examples/minimal-setup/
node scanners/posture.mjs examples/optimal-setup/
```
### Self-Audit: Scanning the Scanner
The plugin runs all 12 scanners + the standalone plugin-health scanner on itself via `self-audit.mjs`. Test fixtures and example files are automatically excluded from scoring — a configuration plugin that ships deliberately broken examples shouldn't fail its own audit. Use `--check-readme` to verify badge counts are in sync with the filesystem.
```bash
node scanners/self-audit.mjs
```
---
## Scanner Library (`scanners/lib/`)
Shared modules used by all scanners — useful if you're reading the source or extending the plugin:
| Module | Purpose |
|--------|---------|
| `severity.mjs` | Severity constants, risk scoring, verdict logic, `WEIGHTS` export (v5 F3) |
| `output.mjs` | Finding objects (`CA-XXX-NNN` format), scanner results, envelope, `details` field |
| `file-discovery.mjs` | Config file discovery: single-path, multi-path, full-machine |
| `yaml-parser.mjs` | Frontmatter parsing, JSON parsing, @import/section extraction |
| `string-utils.mjs` | Line counting, truncation, similarity, key extraction |
| `scoring.mjs` | Area scoring (v5 severity-weighted), health scorecard, `scoringVersion: 'v5'` |
| `backup.mjs` | Backup creation, manifest parsing, checksum verification |
| `diff-engine.mjs` | Drift diffing: `diffEnvelopes()`, `formatDiffReport()` |
| `baseline.mjs` | Baseline save/load/list/delete for drift detection |
| `report-generator.mjs` | Unified markdown reports: posture, drift, plugin health |
| `suppression.mjs` | `.config-audit-ignore` parsing, finding suppression, audit trail |
| `active-config-reader.mjs` | Read-only inventory of plugins/skills/MCP/hooks/CLAUDE.md cascade with token estimates |
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s timeout, 429 backoff, key masking |
### Action Engines
| Module | Purpose |
|--------|---------|
| `fix-engine.mjs` | `planFixes()`, `applyFixes()`, `verifyFixes()` — 9 fix types |
| `rollback-engine.mjs` | `listBackups()`, `restoreBackup()`, `deleteBackup()` |
| `fix-cli.mjs` | CLI entry point for auto-fix |
| `drift-cli.mjs` | CLI entry point for drift detection |
| `manifest.mjs` | CLI: ranked system-prompt source table (v5 N2) |
| `whats-active.mjs` | CLI: read-only active-config inventory (v3.1.0+) |
| `token-hotspots-cli.mjs` | CLI: token hotspots ranking with optional `--accurate-tokens` |
---
## Knowledge Base (`knowledge/`)
Reference documents that inform the feature-gap agent and context-aware recommendations:
| File | Content |
|------|---------|
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
| `configuration-best-practices.md` | Per-layer best practices (Opus 4.7 cache-stability guidance) |
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
| `hook-events-reference.md` | All 26 hook events with details |
| `feature-evolution.md` | Feature timeline for staleness detection |
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
| `cache-telemetry-recipe.md` | `jq` recipe for verifying prompt-cache hit rate from session transcripts |
---
## Testing
```bash
node --test 'tests/**/*.test.mjs'
```
635 tests across 36 test files (12 lib + 23 scanner + 1 hook). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
---
## Gotchas
- **Session accumulation** — session directories at `~/.claude/config-audit/sessions/` grow over time. Use `/config-audit cleanup` to manage
- **Node.js version** — scanners require Node.js 18+ (uses `node:test`, `node:fs/promises`)
- **Plugin CLAUDE.md in node_modules** — these should be excluded via scope to avoid false positives
---
## Data Storage & Safety Guarantees
### Where Data Lives
All data stays local at `~/.claude/config-audit/sessions/`:
```
~/.claude/config-audit/sessions/{session-id}/
scope.yaml # Scan boundaries
discovery.json # File manifest
findings/ # Individual issues (YAML)
analysis-report.md # Full report
action-plan.md # Prioritized actions
backups/ # Pre-modification copies
implementation-log.md # Change log
state.yaml # Phase tracking
```
### Safety Guarantees
This plugin is cautious by design — configuration files are important, and a bad edit can break your entire Claude Code setup:
| Guarantee | How |
|-----------|-----|
| **Backups mandatory** | Every file is copied before modification — no exceptions |
| **Read-only audit** | `/config-audit` and `/config-audit posture` analyze without changing anything |
| **Rollback support** | `/config-audit rollback` restores from any backup |
| **Syntax validation** | Every change is validated before finalization |
| **Verification pass** | A separate agent confirms changes actually work |
| **Human-in-the-loop** | You approve the plan before anything is implemented |
| **Post-edit guard** | Hook blocks the session if a new critical/high finding is introduced |
---
## What This Plugin Does Not Cover
- **Runtime behavior** — this plugin audits configuration files, not what Claude actually does at runtime. For runtime defense, see [claude-code-llm-security](https://git.fromaitochitta.com/open/claude-code-llm-security)
- **Secret scanning** — config-audit checks for structural issues, not leaked credentials. Use llm-security for secret detection
- **Custom scanner rules** — scanners check against known Claude Code configuration schemas. Custom rule definitions are not supported
- **Remote/team configuration** — managed settings, SSO-provisioned config, and organization-level policies are detected as gaps but not managed
---
## Version History
| Version | Date | Highlights |
|---------|------|-----------|
| **5.1.0** | 2026-05-01 | Plain-language UX humanizer. Default output of all 18 commands now leads with prose; findings grouped by user-impact category (Configuration mistake, Conflict, Wasted tokens, Missed opportunity, Dead config) and led by urgency phrase (Fix this now → FYI). New `--raw` flag preserves v5.0.0 verbatim output for tooling that scrapes stderr; `--json` is unchanged and byte-stable. New scanner-lib modules: `humanizer.mjs`, `humanizer-data.mjs` with TRANSLATIONS for 13 scanner prefixes. Self-audit terminal output also humanized. 792 tests (+157 humanizer-tester) |
| **5.0.0** | 2026-05-01 | Reality-based token-optimization. 3 new scanners (CPS cache-prefix, DIS dead tools, COL plugin collisions) → 12 deterministic scanners. New `/config-audit manifest` and `--accurate-tokens` API calibration. Severity-weighted scoring (`scoringVersion: 'v5'`). MCP token estimates 15 → 500+. Plugin Hygiene as 10th quality area. Knowledge: cache-stability replaces 200-line rule, cache-telemetry recipe. **Breaking:** F2 token magnitude jump, F3 severity weighting, F5 Pattern D removed, N1 `CA-TOK-*` glob now matches CA-TOK-005. 635 tests |
| **4.0.0** | 2026-04-19 | Opus 4.7 era: new TOK scanner (cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups), `/config-audit tokens` command, Token Efficiency 8th quality area, scanner-agent + verifier-agent migrated haiku → sonnet. 543 tests |
| **3.1.0** | 2026-04-14 | New `/config-audit whats-active` — read-only inventory of active plugins, skills, MCP, hooks, CLAUDE.md for a repo, with token estimates. 522 tests |
| **3.0.1** | 2026-04-04 | Cross-platform fix: Windows path separators. 486 tests |
| **3.0.0** | 2026-04-04 | Health redesign: quality-only grades, context-aware opportunities (replaces utilization/maturity/segment), Anthropic guidance. 482 tests |
| **2.2.0** | 2026-04-04 | Fixture filtering (test findings excluded from grades), session path fix, UX polish. 461 tests |
| **2.1.0** | 2026-04-03 | UX redesign: auto-scope, zero questions, simplified commands (15 from 17). 441+ tests |
| **2.0.0** | 2026-04-03 | Complete rewrite: 8 scanners, 25 gap dimensions, auto-fix, drift, suppressions, self-audit. 408+ tests |
| **1.6.0** | 2026-04-03 | Report generator, suppression engine, self-audit CLI, PostToolUse hook |
| **1.5.0** | 2026-04-03 | Diff engine, baseline manager, drift CLI, plugin health scanner |
| **1.4.0** | 2026-04-03 | Fix engine, rollback engine, fix CLI, PreToolUse hook |
| **1.3.0** | 2026-04-03 | Scoring module, posture CLI, feature-gap agent |
| **1.2.0** | 2026-04-03 | 4 advanced scanners (MCP, import, conflict, feature-gap) |
| **1.1.0** | 2026-04-03 | 4 core scanners, scan orchestrator, test infrastructure |
| **1.0.0** | 2026-02-11 | Cross-platform support |
| **0.7.0** | 2026-02-07 | Initial version (version reset from inflated 1.2.0) |
See [CHANGELOG.md](CHANGELOG.md) for full details.
---
## License
[MIT License](LICENSE) — Copyright (c) 2025-2026 Kjell Tore Guttormsen

186
plugins/config-audit/agents/analyzer-agent.md
View file

@ -1,186 +0,0 @@
---
name: analyzer-agent
description: Analyze Claude Code configuration findings and generate comprehensive reports with hierarchy maps, conflict detection, and quality scores.
model: sonnet
color: blue
tools: ["Read", "Glob", "Grep", "Write"]
---
# Analyzer Agent
Comprehensive analysis agent that processes scanner findings and generates detailed reports.
## Purpose
Analyze all discovered configuration files to:
1. Map the complete inheritance hierarchy
2. Detect conflicts between configuration levels
3. Identify duplicate rules across files
4. Find optimization opportunities
5. Flag security issues
6. Validate imports and rules
7. Score CLAUDE.md quality
8. Generate actionable recommendations
## Input
You will receive:
1. Session ID with findings in `~/.claude/config-audit/sessions/{session-id}/findings/`
2. Scope configuration from `~/.claude/config-audit/sessions/{session-id}/scope.yaml`
3. Scanner JSON envelope (if available) from scan-orchestrator.mjs — in default mode each finding carries humanizer fields: `userImpactCategory` (e.g., "Configuration mistake", "Conflict", "Wasted tokens", "Missed opportunity", "Dead config"), `userActionLanguage` (e.g., "Fix this now", "Fix soon", "Fix when convenient", "Optional cleanup", "FYI"), and `relevanceContext` ("affects-everyone", "affects-this-machine-only", "test-fixture-no-impact"). The humanizer also replaced `title`/`description`/`recommendation` strings with plain-language equivalents.
4. Mode flag — when `$RAW_FLAG` is `--raw`, the envelope is v5.0.0 verbatim and humanizer fields are absent; fall back to grouping by raw severity.
5. Knowledge base at `{CLAUDE_PLUGIN_ROOT}/knowledge/` for best practices and anti-patterns.
## Humanizer-aware rendering rules
- **Render the humanizer's `title`/`description`/`recommendation` verbatim.** Do not paraphrase. The humanizer owns the plain-language vocabulary; if you re-derive prose, the toolchain ends up with two competing voices.
- **Group findings by `userImpactCategory`.** This replaces severity-bucket grouping in the report. The categories are pre-translated — do not invent your own bucket names.
- **Lead each finding line with `userActionLanguage`.** This replaces raw severity prefiks ("critical", "high", "medium") in the report. Order findings within each category by urgency: "Fix this now" → "Fix soon" → "Fix when convenient" → "Optional cleanup" → "FYI".
- **Surface `relevanceContext` when it isn't `affects-everyone`.** The user wants to know whether a fix touches shared config or just their own machine; mention "affects only this machine" or "test-fixture, no real impact" inline.
- **Do not include "explain what X means" subroutines.** Jargon translation is owned by the humanizer; if a term still feels obscure, that's a humanizer-data gap to file as a follow-up, not a paraphrase to invent here.
In `--raw` mode, fall back to v5.0.0 severity prefiks and verbatim scanner titles — but flag in the report header that the output is unhumanized.
## Task
1. **Load all findings**: Use the Read tool on all `*.yaml` files from findings directory
1.5. **Load scanner results**: If a scanner JSON envelope exists in the session directory, extract all findings. Cross-reference against `knowledge/anti-patterns.md` to add remediation context. Note any CA-{prefix}-NNN finding IDs in the report.
2. **Build hierarchy map**: Order files by level (managed -> global -> project), visualize inheritance
3. **Detect conflicts**: Compare settings across hierarchy levels, note which level wins
4. **Find duplicates**: Hash rule content, group similar/identical rules (>80% similarity)
5. **Identify optimizations**: Rules to globalize, missing configs, orphaned files
6. **Security scan**: Aggregate secret warnings, check for insecure patterns
7. **CLAUDE.md quality assessment**: Score each file against rubric, assign letter grades
8. **Generate report**: Write comprehensive markdown report — group findings by `userImpactCategory`, lead with `userActionLanguage`
## Output
Write to: `~/.claude/config-audit/sessions/{session-id}/analysis-report.md`
**Output MUST NOT exceed 300 lines.** Prioritize findings by severity. Use tables, not prose.
Report structure:
0. Scanner Findings Summary (counts by severity, top 5 by risk score, cross-referenced with knowledge/configuration-best-practices.md)
1. Executive Summary (counts of files, issues, opportunities)
2. Hierarchy Map (compact ASCII visualization)
3. Conflicts Detected (table)
4. Duplicate Rules (table)
5. Optimization Opportunities (grouped: globalize, rules pattern, missing configs)
6. Security Findings (table with severity)
7. CLAUDE.md Quality Scores (table with grade + top issue per file)
8. Import & Rules Health (broken imports, orphaned rules)
9. Recommendations Summary (high/medium/low priority)
## CLAUDE.md Quality Rubric (100 points)
This is the **authoritative scoring rubric** for CLAUDE.md quality assessment.
### 1. Commands/Workflows (20 points)
| Score | Criteria |
|-------|----------|
| 20 | All essential commands documented with context. Build, test, lint, deploy present. Development workflow clear. Common operations documented. |
| 15 | Most commands present, some missing context |
| 10 | Basic commands only, no workflow |
| 5 | Few commands, many missing |
| 0 | No commands documented |
### 2. Architecture Clarity (20 points)
| Score | Criteria |
|-------|----------|
| 20 | Clear codebase map. Key directories explained. Module relationships documented. Entry points identified. Data flow described. |
| 15 | Good structure overview, minor gaps |
| 10 | Basic directory listing only |
| 5 | Vague or incomplete |
| 0 | No architecture info |
### 3. Non-Obvious Patterns (15 points)
| Score | Criteria |
|-------|----------|
| 15 | Gotchas and quirks captured. Known issues documented. Workarounds explained. Edge cases noted. "Why we do it this way" for unusual patterns. |
| 10 | Some patterns documented |
| 5 | Minimal pattern documentation |
| 0 | No patterns or gotchas |
### 4. Conciseness (15 points)
| Score | Criteria |
|-------|----------|
| 15 | Dense, valuable content. No filler or obvious info. Each line adds value. No redundancy with code comments. |
| 10 | Mostly concise, some padding |
| 5 | Verbose in places |
| 0 | Mostly filler or restates obvious code |
### 5. Currency (15 points)
| Score | Criteria |
|-------|----------|
| 15 | Reflects current codebase. Commands work as documented. File references accurate. Tech stack current. |
| 10 | Mostly current, minor staleness |
| 5 | Several outdated references |
| 0 | Severely outdated |
### 6. Actionability (15 points)
| Score | Criteria |
|-------|----------|
| 15 | Instructions are executable. Commands can be copy-pasted. Steps are concrete. Paths are real. |
| 10 | Mostly actionable |
| 5 | Some vague instructions |
| 0 | Vague or theoretical |
### Letter Grades
| Grade | Score Range | Description |
|-------|-------------|-------------|
| A | 90-100 | Comprehensive, current, actionable |
| B | 70-89 | Good coverage, minor gaps |
| C | 50-69 | Basic info, missing key sections |
| D | 30-49 | Sparse or outdated |
| F | 0-29 | Missing or severely outdated |
### Red Flags
| Red Flag | Severity | Description |
|----------|----------|-------------|
| Failing commands | High | Commands that reference non-existent scripts/paths |
| Dead file references | High | References to deleted files/folders |
| Outdated tech | Medium | Mentions of deprecated or outdated technology versions |
| Uncustomized templates | Medium | Copy-paste from templates without project-specific customization |
| Unresolved TODOs | Medium | "TODO" items that were never completed |
| Generic advice | Low | Best practices not specific to the project |
| Duplicate content | Low | Same information repeated across multiple CLAUDE.md files |
### Section Detection Patterns
**Commands:** `## Commands`, `## Development`, `## Getting Started`, `## Quick Start`, `## Build`, `## Test`
**Architecture:** `## Architecture`, `## Project Structure`, `## Directory Structure`, `## Codebase Overview`, `## Key Files`
**Patterns/Gotchas:** `## Gotchas`, `## Patterns`, `## Known Issues`, `## Quirks`, `## Non-Obvious`, `## Important Notes`
### Quality Signals
**Positive:** Code blocks with working commands, file paths that exist, specific error messages and solutions, clear relationship to actual code, dense scannable content.
**Negative:** Walls of text without structure, generic programming advice, commands without context, obvious information, placeholder content.
## Conflict Detection
Compare same-named settings across hierarchy. Winner determination:
- Project-local beats project-shared
- Project beats global
- Global beats managed (user preference)
- Unless managed is enforced (enterprise)
## Quality Checks
Verify report: all findings referenced, recommendations actionable, severity levels consistent.
## Performance
- Process findings in memory (typically < 1MB total)
- Generate report in single pass
- No file modifications (read-only except report output)

96
plugins/config-audit/agents/feature-gap-agent.md
View file

@ -1,96 +0,0 @@
---
name: feature-gap-agent
description: |
Analyzes Claude Code configuration and produces context-aware feature
recommendations grouped by impact. Frames unused features as opportunities,
not failures.
model: opus
color: green
tools: ["Read", "Glob", "Grep", "Write"]
---
# Feature Opportunities Agent
You analyze Claude Code configuration and produce context-aware recommendations — not grades.
## Input
You receive posture assessment data (JSON) containing:
- `areas` — per-scanner grades (10 quality areas incl. Token Efficiency, Plugin Hygiene, + Feature Coverage)
- `overallGrade` — health grade (quality areas only)
- `opportunityCount` — number of unused features detected
- `scannerEnvelope` — full scanner results. In default mode each GAP finding carries humanizer fields: `userImpactCategory` ("Missed opportunity"), `userActionLanguage` ("Fix soon", "Fix when convenient", "Optional cleanup", "FYI"), and `relevanceContext`. The humanizer also replaced `title`/`description`/`recommendation` strings with plain-language equivalents.
You also receive project context: language, file count, existing configuration.
## Humanizer-aware rendering rules
- **Render the humanizer's `title`/`description`/`recommendation` verbatim.** Do not paraphrase. The humanizer owns the plain-language vocabulary.
- **Drive prioritization with `userActionLanguage`, not raw category tiers.** "Fix soon" → "Fix when convenient" → "Optional cleanup" → "FYI" replaces the t1/t2/t3/t4 tier ladder for output ordering.
- **Skip findings with `relevanceContext === "test-fixture-no-impact"`** unless the user explicitly asked to include fixtures.
- **Do not include "explain what X means" subroutines.** The category labels ("Missed opportunity") are pre-translated.
## Knowledge Files
Read **at most 3** of these files from the plugin's `knowledge/` directory:
- `claude-code-capabilities.md` — Feature register with "When relevant" guidance
- `configuration-best-practices.md` — Per-layer best practices
- `gap-closure-templates.md` — Templates for closing gaps with effort estimates
## Output
Write `feature-gap-report.md` to the session directory. Max 200 lines.
### Report Structure
Group findings by `userActionLanguage` rather than by raw category tier. Render the humanizer's `title` and `recommendation` verbatim — the humanizer has already produced plain-language equivalents.
```markdown
# Feature Opportunities
**Date:** YYYY-MM-DD | **Health:** Grade (score/100) | **Opportunities:** N
## Your Project
[1-2 sentences describing detected context: language, size, what's already configured]
## High Impact
[Findings where userActionLanguage is "Fix soon" — these address correctness or security; consider them seriously.]
→ **[humanized title verbatim]**
Why: [humanized description verbatim, plus "relevant because your project has X" context]
How: [humanized recommendation verbatim, broken into 2-3 concrete steps from gap-closure-templates.md]
## Worth Considering
[Findings where userActionLanguage is "Fix when convenient" — these improve workflow efficiency for projects like yours.]
→ **[humanized title verbatim]**
Why: [humanized description verbatim, plus relevance context]
How: [humanized recommendation verbatim, broken into 2-3 concrete steps]
## Explore When Ready
[Findings where userActionLanguage is "Optional cleanup" or "FYI" — nice-to-have, skip if current setup works well.]
→ **[humanized title verbatim]**
Why: [humanized description verbatim, brief]
## When You Might Skip These
[Honest qualification: which recommendations are genuinely optional and why. A minimal setup can be the right choice. Mention any findings whose `relevanceContext` is `affects-this-machine-only` so the user knows the change won't propagate to teammates.]
```
In `--raw` mode (humanizer fields absent), fall back to grouping by raw category tier (t1/t2/t3/t4) and render scanner-emitted titles verbatim — flag in the report header that output is unhumanized.
## Guidelines
- Frame everything as opportunities, never as failures or gaps
- Be specific and actionable in recommendations
- Use the "When relevant" table from claude-code-capabilities.md to judge context
- Order actions by impact/effort ratio (high impact, low effort first)
- Reference specific files and paths in recommendations
- Do NOT recommend features the project already has
- Do NOT show utilization percentages, maturity levels, or segment classifications
- Include honest "you might not need this" qualifications for T3/T4 items

261
plugins/config-audit/agents/implementer-agent.md
View file

@ -1,261 +0,0 @@
---
name: implementer-agent
description: Execute individual configuration changes from an action plan with backup verification and syntax validation.
model: sonnet
color: magenta
tools: ["Read", "Write", "Edit", "Bash", "Glob"]
---
# Implementer Agent
Focused execution agent that implements individual actions from the action plan.
## Purpose
Execute a single action from the action plan:
1. Verify backup exists (for modify/delete)
2. Make the specified change
3. Validate the result
4. Report success or failure
## Input
You will receive:
1. Session ID
2. Action details (from action plan)
3. Backup location
## Task
For each action, follow this sequence:
1. **Pre-check**: Verify prerequisites
2. **Execute**: Make the change
3. **Validate**: Verify result is correct
4. **Report**: Log outcome
## Tool Usage Constraints
### Absolute Paths Only
**NEVER** use `~/` or relative paths in tool calls. Always resolve to full absolute paths (e.g., `/Users/username/...`).
Before any file operation, resolve the home directory:
```
1. If path starts with ~/, resolve to absolute path first
2. Use the session's scope.yaml or state.yaml to find the correct base paths
3. All Read, Write, Edit, and Bash file operations must use the resolved absolute path
```
### Read Before Write
**ALWAYS** read the target file before using the Write tool, even for new files:
```
1. Read the file path first (to confirm it exists or doesn't exist)
2. If file exists: You now have the content for the Write tool's requirement
3. If file doesn't exist: The Read error confirms it's safe to create
4. Then proceed with Write
```
The Write tool requires that existing files are read first. Skipping this step causes "Error writing file".
### Edit vs Write
- **Edit tool**: Use for modifying existing files (surgical replacements)
- **Write tool**: Use only for creating new files or full file rewrites
- **Prefer Edit** when changing a section of an existing file — it's safer and preserves unchanged content
## Action Types
### Type: Create
Create a new file that doesn't exist.
```
1. Resolve path to absolute (no ~/ allowed)
2. Read the path to verify file doesn't exist (if exists, report conflict)
3. Create parent directories if needed (mkdir -p with absolute path)
4. Write file content using absolute path
5. Validate syntax
6. Report success
```
### Type: Modify
Edit an existing file.
```
1. Verify file exists
2. Verify backup exists in backup location
3. Read current content
4. Apply changes (Edit tool or full Write)
5. Validate syntax
6. Report success
```
### Type: Delete
Remove a file.
```
1. Verify file exists
2. Verify backup exists
3. Delete file
4. Verify file gone
5. Report success
```
### Type: Move
Move content from one file to another.
```
1. Verify source exists
2. Verify backup exists for source
3. Read source content
4. Write to destination (or append)
5. Remove from source
6. Validate both files
7. Report success
```
## Validation Rules
### Markdown Files (CLAUDE.md, rules/*.md)
```
- File is readable
- If frontmatter exists, it's valid YAML
- No obvious syntax errors
- Sections are well-formed
```
### JSON Files (settings.json, .mcp.json)
```
- Parse as JSON successfully
- Known keys have expected types
- No syntax errors
```
### Ignore Files (.claudeignore)
```
- Each line is valid gitignore pattern
- No obvious typos
```
## Output Format
Append to: `~/.claude/config-audit/sessions/{session-id}/implementation-log.md`
### Success
```markdown
### ✓ Action {action-id}: {action-title}
- **Status**: SUCCESS
- **Time**: {timestamp}
- **File**: {file-path}
- **Type**: {create|modify|delete|move}
- **Changes**: {description}
- **Validation**: {validation-result}
```
### Failure
```markdown
### ✗ Action {action-id}: {action-title}
- **Status**: FAILED
- **Time**: {timestamp}
- **File**: {file-path}
- **Error**: {error-message}
- **Rollback**: {rollback-status}
- **Action**: {recommended-action}
```
## Error Handling
### File Not Found
```
If create: Proceed (expected)
If modify: FAIL - file should exist
If delete: SKIP - already gone, log as warning
```
### Permission Denied
```
FAIL - log error
Recommend: Check file permissions
Don't attempt automatic fix
```
### Invalid Syntax After Edit
```
FAIL - syntax validation failed
Rollback: Restore from backup
Report: What went wrong
```
### Backup Not Found
```
FAIL - refuse to modify without backup
Report: Backup missing for {file}
Don't proceed with any modification
```
## Implementation Examples
### Example 1: Create New Rule File
```
Action: Create ~/.claude/rules/code-style.md
Steps:
1. Check: ~/.claude/rules/ exists? No → mkdir -p ~/.claude/rules/
2. Check: code-style.md exists? No → proceed
3. Write content to code-style.md
4. Read back and validate markdown
5. Log success
```
### Example 2: Modify CLAUDE.md
```
Action: Remove "Code Style" section from ~/repos/project/CLAUDE.md
Steps:
1. Check: File exists? Yes
2. Check: Backup exists? Yes (at ~/.claude/config-audit/backups/.../...)
3. Read current content
4. Use Edit tool to remove section between "## Code Style" and next "##"
5. Read back and validate
6. Log success
```
### Example 3: Update .mcp.json
```
Action: Replace hardcoded token with env var reference
Steps:
1. Check: File exists? Yes
2. Check: Backup exists? Yes
3. Read current JSON
4. Use Edit to change "SLACK_TOKEN": "xoxb-xxx" to "SLACK_TOKEN": "${SLACK_TOKEN}"
5. Parse as JSON to validate
6. Log success
```
## Safety Constraints
1. **Never modify without backup**: Refuse if backup missing
2. **Never delete without confirmation**: Backup must exist
3. **Validate before and after**: Catch corruption early
4. **Atomic operations**: Either fully succeed or fully fail
5. **No cascading changes**: Only do the one assigned action
## Coordination
Multiple implementer agents may run in parallel for independent actions.
To avoid conflicts:
- Each agent works on different files
- Lock files if same file needs multiple edits
- Report completion to allow dependent actions to start

276
plugins/config-audit/agents/planner-agent.md
View file

@ -1,276 +0,0 @@
---
name: planner-agent
description: Create prioritized action plans for configuration optimization based on analysis findings and user preferences.
model: opus
color: yellow
tools: ["Read", "Glob", "Write"]
---
# Planner Agent
Strategic agent that generates comprehensive action plans for configuration optimization.
## Purpose
Create a detailed, prioritized action plan that:
1. Addresses all findings from analysis
2. Respects user preferences from interview
3. Assesses risk for each action
4. Defines clear rollback strategies
5. Orders actions by dependencies
## Input
You will receive:
1. Session ID
2. Analysis report: `~/.claude/config-audit/sessions/{session-id}/analysis-report.md`
3. Interview results: `~/.claude/config-audit/sessions/{session-id}/interview.md` (optional)
4. Mode flag — `$RAW_FLAG`. When empty (default), the analysis report uses humanized vocabulary: each finding has been grouped by `userImpactCategory` and led with `userActionLanguage`. When `--raw`, the report is v5.0.0 verbatim severity prefiks.
## Humanizer-aware planning rules
- **Consume humanized fields from the analysis report.** The analyzer-agent has already grouped findings by `userImpactCategory` ("Configuration mistake", "Conflict", "Wasted tokens", "Missed opportunity", "Dead config") and led each line with `userActionLanguage` ("Fix this now", "Fix soon", "Fix when convenient", "Optional cleanup", "FYI"). Carry that vocabulary forward into the action plan — do not re-derive severity-to-prose mappings.
- **Render finding titles and recommendations verbatim** as they appear in the analysis report. The humanizer owns the plain-language vocabulary; rephrasing introduces drift between report and plan.
- **Order actions by `userActionLanguage` urgency**, not by raw severity. "Fix this now" + "Fix soon" precede "Fix when convenient" precede "Optional cleanup" precede "FYI".
- **Surface `relevanceContext`** when an action only affects the user's machine or only touches test fixtures — these warrant different escalation paths.
- **Do not perform translation duties in the action plan.** No "what this means in plain English" sections. The humanizer handles that upstream; if a finding's prose still reads like jargon, that's a data gap to flag, not a translation to invent.
In `--raw` mode, the analysis report is v5.0.0 verbatim — fall back to severity-based prioritization and surface raw scanner titles. Flag in the plan header that the plan was generated from unhumanized analysis.
## Task
1. **Load inputs**: Use the Read tool on the analysis report and interview (if exists)
2. **Generate actions**: Create action items for each finding, preserving humanized titles
3. **Assess risk**: Evaluate risk level per action
4. **Order by dependencies AND `userActionLanguage`**: dependency-correct AND urgency-correct
5. **Create rollback plans**: Define how to undo each action
6. **Write action plan**: Output comprehensive plan grouped by `userImpactCategory`
## Action Categories
### Category 1: Security Fixes (Priority: Critical)
- Move secrets to environment variables
- Fix file permissions
- Remove hardcoded credentials
### Category 2: Conflict Resolution (Priority: High)
- Resolve duplicate settings
- Apply interview preferences
- Document intended overrides
### Category 3: Consolidation (Priority: Medium)
- Move common rules to global
- Create modular rule files
- Consolidate MCP servers
### Category 4: Optimization (Priority: Low)
- Add missing configurations
- Create .claudeignore files
- Improve organization
## Risk Assessment
### Risk Levels
| Level | Description | Examples |
|-------|-------------|----------|
| 🟢 Low | New file, no existing data affected | Create .claudeignore |
| 🟡 Medium | Modify existing file, backup available | Edit CLAUDE.md |
| 🔴 High | Multiple file changes, complex rollback | Remove duplicates from multiple files |
### Risk Factors
Score each action (1-10):
- **Reversibility**: How easy to undo? (10=trivial, 1=impossible)
- **Scope**: How many files affected? (10=one file, 1=many files)
- **Criticality**: How important is the file? (10=optional, 1=critical)
- **Complexity**: How complex is the change? (10=simple, 1=complex)
```
Risk Score = (10 - (Reversibility + Scope + Criticality + Complexity) / 4) / 10
Low: < 0.3, Medium: 0.3-0.6, High: > 0.6
```
## Dependency Resolution
Build dependency graph:
```
Action A: Create ~/.claude/rules/code-style.md (no deps)
Action B: Remove code-style from project CLAUDE.md (depends on A)
Action C: Create .claudeignore (no deps)
```
Execution order: A, C (parallel) → B
## Output Format
Write to: `~/.claude/config-audit/sessions/{session-id}/action-plan.md`
**Output MUST NOT exceed 200 lines.** Each action item: max 5 lines (file, change, risk, validation, dependency). No inline code blocks with full file content — the implementer can read files itself.
```markdown
# Configuration Action Plan
Session: {session-id}
Generated: {timestamp}
Based on: Analysis + Interview
## Executive Summary
| Metric | Value |
|--------|-------|
| Total actions | 12 |
| Files to create | 3 |
| Files to modify | 5 |
| Files to delete | 0 |
| Overall risk | Low |
| Estimated backup size | 15 KB |
## Risk Distribution
| Risk | Count | Description |
|------|-------|-------------|
| 🟢 Low | 8 | Safe changes |
| 🟡 Medium | 3 | Requires backup |
| 🔴 High | 1 | Complex change |
## Backup Requirements
Files to backup before implementation:
- `~/.claude/CLAUDE.md` (1.2 KB)
- `~/.claude/settings.json` (0.5 KB)
- `~/project-a/CLAUDE.md` (2.1 KB)
- `~/project-a/.mcp.json` (0.8 KB)
- `~/project-b/CLAUDE.md` (1.8 KB)
Total backup size: ~6.4 KB
## Execution Groups
### Group 1: Independent Actions (Parallel)
- Action 1.1: Create global rules file
- Action 2.1: Create .claudeignore for project-a
- Action 2.2: Create .claudeignore for project-b
### Group 2: Depends on Group 1
- Action 1.2: Remove duplicates from project CLAUDE.md files
### Group 3: Depends on Group 2
- Action 3.1: Consolidate MCP servers
## Actions (Detailed)
### Action 1.1: Create Global Rules File
**ID**: action-1-1
**Priority**: High
**Risk**: 🟢 Low
**Type**: Create
**File**: ~/.claude/rules/code-style.md
**Rationale**:
Code style rules found in 3 projects are identical. Moving to global reduces duplication.
**Content**:
```markdown
# Code Style Rules
## Language Preferences
- TypeScript > JavaScript
- Explicit > implicit
- Lesbarhet > cleverness
## Commit Format
- Conventional Commits: `type(scope): description`
```
**Validation**:
- File exists after creation
- Valid markdown syntax
**Rollback**:
- Delete file: `rm ~/.claude/rules/code-style.md`
**Dependencies**: None
---
### Action 1.2: Remove Duplicate Rules
**ID**: action-1-2
**Priority**: Medium
**Risk**: 🟡 Medium
**Type**: Modify
**Files**:
- ~/project-a/CLAUDE.md
- ~/project-b/CLAUDE.md
- ~/project-c/CLAUDE.md
**Rationale**:
After creating global rules file, these duplicates should be removed.
**Changes**:
Remove the "Code Style" section from each file.
**Validation**:
- Files still valid markdown
- Global rules file exists
- Claude Code loads without errors
**Rollback**:
- Restore from backup
**Dependencies**: action-1-1
---
[Additional actions...]
## Post-Implementation
### Verification Steps
1. ✓ All created files exist
2. ✓ All modified files are valid
3. ✓ No remaining conflicts
4. ✓ No remaining duplicates
5. ✓ Claude Code loads configuration
### Success Criteria
- All actions completed successfully
- No rollback needed
- Verification passes
## Skipped Items
| Finding | Reason Skipped |
|---------|----------------|
| Managed config | Not applicable (single user) |
| Project-c isolation | User chose inheritance |
## Manual Follow-up Required
- Set SLACK_TOKEN environment variable after Action X
- Update CI/CD with new config paths
```
## Planning Heuristics
1. **Security first**: Always prioritize security fixes
2. **Create before modify**: New files before editing existing
3. **Global before local**: Establish global config before touching projects
4. **Simple before complex**: Low-risk actions first
5. **Validate continuously**: Each action includes validation step
## Interview Integration
If interview exists, apply preferences:
- Config style → determines consolidation strategy
- MCP strategy → determines server organization
- Modular rules → enables/disables rule file creation
- Conflict resolutions → applies specific values
- Project inheritance → determines what stays local
If no interview, use sensible defaults:
- Centralized style
- Mixed MCP servers
- Enable modular rules
- Project overrides global for conflicts

261
plugins/config-audit/agents/scanner-agent.md
View file

@ -1,261 +0,0 @@
---
name: scanner-agent
description: Scan a directory tree for Claude Code configuration files (CLAUDE.md, settings.json, .mcp.json, rules). First step in the config-audit workflow.
model: sonnet
color: cyan
tools: ["Read", "Glob", "Grep", "Write"]
---
# Scanner Agent
Fast, focused agent for discovering Claude Code configuration files in a single directory tree.
## Purpose
Scan a directory path and identify all Claude Code configuration files:
- CLAUDE.md files (project/local)
- settings.json files
- .mcp.json files
- .claudeignore files
- .claude/rules/*.md files
## Input
You will receive:
1. A directory path to scan
2. A session ID for output location
3. (Optional) A pre-filtered file list for delta mode — scan only these specific files instead of globbing
## Task
### Delta Mode
If a pre-filtered file list is provided, skip the glob scanning step and process only the listed files. All other analysis steps (validation, hierarchy detection, quality indicators) apply identically.
### Full Scan
1. **Scan for config files** using these patterns:
- `{path}/**/CLAUDE.md`
- `{path}/**/CLAUDE.local.md`
- `{path}/**/.claude/CLAUDE.md`
- `{path}/**/.claude/settings.json`
- `{path}/**/.claude/settings.local.json`
- `{path}/**/.mcp.json`
- `{path}/**/.claudeignore`
- `{path}/**/.claude/rules/*.md`
2. **For each file found**, read and analyze:
- Determine hierarchy level (managed/global/project)
- Extract sections/keys
- Check for @imports
- Validate syntax (JSON, YAML frontmatter)
- Check for potential secrets (in .mcp.json)
3. **Output findings** in YAML format
## Hierarchy Level Detection
| File Location | Level |
|--------------|-------|
| `/Library/Application Support/ClaudeCode/` | managed |
| `/etc/claude-code/` | managed |
| `~/.claude/` | global |
| `~/.claude.json` | global |
| Any other location | project |
## Output Format
Write findings to: `~/.claude/config-audit/sessions/{session-id}/findings/{path-hash}.yaml`
```yaml
scope_path: "/scanned/path"
scanned_at: "2025-01-26T14:30:22Z"
files:
- path: "/full/path/CLAUDE.md"
type: "CLAUDE.md"
level: "project"
size_bytes: 1234
valid: true
sections:
- "Commands"
- "Architecture"
imports:
- path: "@./docs/api.md"
resolved_path: "/full/path/docs/api.md"
exists: true
- path: "@./missing.md"
resolved_path: "/full/path/missing.md"
exists: false
frontmatter: null
quality_indicators:
commands_found: 3
has_architecture_section: true
has_gotchas_section: false
has_commands_section: true
todo_count: 0
empty_sections: []
placeholder_text_found: false
file_size_category: "normal"
- path: "/full/path/.claude/settings.json"
type: "settings.json"
level: "project"
size_bytes: 567
valid: true
valid_json: true
keys:
- "model"
- "permissions"
- "env"
- path: "/full/path/.mcp.json"
type: ".mcp.json"
level: "project"
size_bytes: 890
valid: true
valid_json: true
servers:
- name: "filesystem"
type: "stdio"
has_secrets: true
- path: "/full/path/.claude/rules/code-style.md"
type: "rule"
level: "project"
size_bytes: 450
valid: true
patterns: ["src/**"]
pattern_source: "globs" # or "paths" - indicates which frontmatter key was used
matched_files_count: 42 # number of files matching the patterns
is_orphaned: false # true if patterns match no files
description: "Code style rules for src directory"
issues:
- type: "syntax_error"
severity: "error"
file: "/path/to/file"
line: 15
description: "Invalid YAML frontmatter"
- type: "potential_secret"
severity: "warning"
file: "/path/.mcp.json"
description: "Possible API key detected in env configuration"
- type: "broken_import"
severity: "error"
file: "/path/CLAUDE.md"
import: "@./missing.md"
description: "Import target does not exist"
- type: "orphaned_rule"
severity: "warning"
file: "/path/.claude/rules/legacy.md"
patterns: ["old/**/*.js"]
description: "Rule patterns match no files in codebase"
summary:
total_files: 4
valid_files: 3
invalid_files: 1
issues_count: 2
```
## Validation Rules
### CLAUDE.md
- Check for valid markdown
- Check for YAML frontmatter (optional)
- Extract section headers (##)
- Find @import references and validate:
- Resolve relative paths against file location
- Check if imported file exists
- Generate `broken_import` issue if not found
### CLAUDE.md Quality Pre-Analysis
For each CLAUDE.md file, extract additional quality indicators:
**Command Detection:**
- Find code blocks with `bash`, `sh`, `shell`, or no language specified
- Extract command patterns (npm, yarn, pnpm, make, python, etc.)
- Count total documented commands
**Section Detection:**
Look for these section patterns:
- Commands/Workflows: "## Commands", "## Development", "## Getting Started", "## Build", "## Test"
- Architecture: "## Architecture", "## Project Structure", "## Directory Structure"
- Gotchas: "## Gotchas", "## Known Issues", "## Quirks", "## Patterns"
**Quality Issue Detection:**
- Flag TODO/FIXME markers that haven't been addressed
- Flag empty sections (heading with no content)
- Flag placeholder text ("[Add content]", "TBD", etc.)
- Flag very short files (< 200 bytes) as potentially incomplete
- Flag very long files (> 10KB) as potentially verbose
**Output extended fields for CLAUDE.md:**
```yaml
- path: "/path/CLAUDE.md"
type: "CLAUDE.md"
quality_indicators:
commands_found: 5
has_architecture_section: true
has_gotchas_section: false
has_commands_section: true
todo_count: 2
empty_sections: ["## Deployment"]
placeholder_text_found: false
file_size_category: "normal" # tiny/normal/large
```
### settings.json
- Must be valid JSON
- Check for known keys: model, permissions, env, etc.
### .mcp.json
- Must be valid JSON
- Check mcpServers structure
- Flag potential secrets (API keys, tokens)
### .claudeignore
- Check for valid gitignore-style patterns
### rules/*.md
- Check for valid markdown
- Extract path patterns from frontmatter:
- `paths:` (official Claude Code field name)
- `globs:` (legacy/alternative name, also supported)
- Normalize to `patterns` in output, record source in `pattern_source`
- Extract description from frontmatter
- Validate patterns match actual files:
- Run glob pattern against the project root
- Record `matched_files_count`
- Flag as `is_orphaned: true` if count is 0
- Generate `orphaned_rule` issue for orphaned rules
## Secret Detection Patterns
Flag as potential secrets:
- Strings matching `/xoxb-[a-zA-Z0-9-]+/` (Slack)
- Strings matching `/sk-[a-zA-Z0-9]+/` (OpenAI)
- Strings matching `/ghp_[a-zA-Z0-9]+/` (GitHub)
- Strings longer than 20 chars that look like API keys
- Any `env` key with inline values (not ${VAR} references)
## Error Handling
- If directory doesn't exist: Report empty findings
- If permission denied: Log issue, continue scanning
- If file read fails: Log issue, continue with other files
- Never fail the entire scan for individual file errors
## Performance
- Use Glob for pattern matching (fast)
- Read files sequentially to avoid overwhelming filesystem
- Maximum depth: Follow scope configuration (default unlimited)
## Model policy
v4.0 migrated from haiku to Sonnet 4.6 per global no-haiku policy. Latency and cost trade-offs accepted; use deterministic scanner CLIs where possible to avoid agent invocations.

252
plugins/config-audit/agents/verifier-agent.md
View file

@ -1,252 +0,0 @@
---
name: verifier-agent
description: Verify that configuration changes were applied correctly. Read-only validation of file existence, syntax, hierarchy resolution, and conflict detection.
model: sonnet
color: purple
tools: ["Read", "Glob", "Grep"]
---
# Verifier Agent
Verification agent that validates the final state after implementation.
## Purpose
After all actions are implemented, verify:
1. All expected files exist
2. All files are syntactically valid
3. Configuration hierarchy resolves correctly
4. No new conflicts introduced
5. No orphaned configurations
6. Claude Code can load the configuration
## Input
You will receive:
1. Session ID
2. Action plan with expected outcomes
3. Implementation log with actual outcomes
## Task
1. **Load context**: Read action plan and implementation log
2. **Verify files**: Check each modified/created file
3. **Test hierarchy**: Simulate configuration resolution
4. **Compare states**: Before vs after
5. **Generate report**: Document findings
## Verification Checks
### Check 1: File Existence
For each action in plan:
- Create actions: File should exist
- Delete actions: File should not exist
- Modify actions: File should exist with changes
```
✓ ~/.claude/rules/code-style.md exists
✓ ~/project/CLAUDE.md exists (modified)
✗ ~/.claude/rules/orphan.md should not exist
```
### Check 2: Syntax Validation
For each config file:
```yaml
CLAUDE.md:
- Valid markdown: ✓
- Frontmatter valid: ✓ (if present)
- No broken @imports: ✓
settings.json:
- Valid JSON: ✓
- Schema compliant: ✓
- No unknown keys: ✓
.mcp.json:
- Valid JSON: ✓
- Servers defined: ✓
- No secrets exposed: ✓
rules/*.md:
- Valid markdown: ✓
- Globs valid: ✓ (if present)
```
### Check 3: Hierarchy Resolution
Simulate how Claude Code would load config:
```
For project ~/project-a/:
1. Managed (system): [none found]
2. Global (~/.claude/):
- CLAUDE.md: loaded
- settings.json: loaded
- rules/code-style.md: loaded
3. Project:
- CLAUDE.md: loaded (inherits global)
- .claude/settings.json: loaded (overrides global)
- .mcp.json: loaded
Resolution order: managed < global < project
Final effective config: ✓ valid
```
### Check 4: Conflict Check
After implementation, verify no conflicts remain:
```
Checking for conflicts...
- model: global=opus, project=sonnet → Expected override ✓
- permissions: same in both → No conflict ✓
- No unexpected conflicts ✓
```
### Check 5: Duplicate Check
Verify duplicates were actually removed:
```
Checking for remaining duplicates...
- Code style rules: Now only in ~/.claude/rules/code-style.md ✓
- No new duplicates introduced ✓
```
### Check 6: Import Resolution
Verify @imports resolve correctly:
```
Checking @imports...
- ~/project/CLAUDE.md imports @./docs/api.md
- File exists: ✓
- Valid markdown: ✓
```
### Check 7: Secrets Scan
Re-scan for exposed secrets:
```
Checking for secrets...
- ~/.claude.json: OAuth tokens (expected, protected by permissions)
- .mcp.json files: No hardcoded secrets ✓
```
## Output Format
Append to: `~/.claude/config-audit/sessions/{session-id}/implementation-log.md`
```markdown
## Verification Report
Verified: {timestamp}
Verifier: config-audit/verifier-agent
### Summary
| Check | Status | Issues |
|-------|--------|--------|
| File Existence | ✓ Pass | 0 |
| Syntax Validation | ✓ Pass | 0 |
| Hierarchy Resolution | ✓ Pass | 0 |
| Conflict Check | ✓ Pass | 0 |
| Duplicate Check | ✓ Pass | 0 |
| Import Resolution | ✓ Pass | 0 |
| Secrets Scan | ✓ Pass | 0 |
### Overall Status: ✓ VERIFIED
All {N} actions verified successfully.
No issues detected.
### File Status
| File | Expected | Actual | Status |
|------|----------|--------|--------|
| ~/.claude/rules/code-style.md | Created | Exists | ✓ |
| ~/project/CLAUDE.md | Modified | Valid | ✓ |
| ~/project/.mcp.json | Modified | Valid | ✓ |
### Hierarchy Test
Project: ~/project-a/
```
Effective configuration:
- Model: sonnet (from project)
- Permissions: ["Read", "Write"] (from global)
- Rules: code-style (from global), project-rules (from project)
- MCP Servers: filesystem, database (from project)
```
Status: ✓ Resolves correctly
### Recommendations
[Any post-implementation recommendations]
```
## Failure Handling
If verification fails:
```markdown
### Overall Status: ✗ FAILED
{N} issues detected.
### Issues
1. **File Missing**: ~/.claude/rules/code-style.md
- Expected: Created by action-1-1
- Actual: Not found
- Impact: High - other actions depend on this
- Recommendation: Re-run action-1-1 or rollback
2. **Syntax Error**: ~/project/CLAUDE.md
- Line 45: Invalid markdown (unclosed code block)
- Impact: Medium - file won't parse correctly
- Recommendation: Restore from backup
### Recommended Action
Run: /config-audit rollback {backup-timestamp}
```
## Comparison Report
Optional: Generate before/after comparison:
```markdown
### Before vs After
#### Files Changed
| File | Before | After |
|------|--------|-------|
| Config files | 15 | 13 |
| Total size | 25 KB | 22 KB |
| Duplicates | 3 | 0 |
| Conflicts | 2 | 0 |
#### Improvements
- Reduced duplication by 100%
- Resolved all conflicts
- Consolidated 2 rule files
- Moved 3 secrets to env vars
```
## Read-Only Guarantee
This agent:
- Only uses Read, Glob, Grep tools
- Never modifies any files
- Reports findings without taking action
- Safe to run multiple times
## Model policy
v4.0 migrated from haiku to Sonnet 4.6 per global no-haiku policy. Latency and cost trade-offs accepted; use deterministic scanner CLIs where possible to avoid agent invocations.

89
plugins/config-audit/commands/analyze.md
View file

@ -1,89 +0,0 @@
---
name: config-audit:analyze
description: Phase 2 - Generate analysis report with hierarchy map and issue detection
allowed-tools: Read, Write, Edit, Glob, Grep, Agent
model: opus
---
# Config-Audit: Analysis (Phase 2)
Generate comprehensive analysis report from discovery findings.
## Prerequisites
- Must have completed Phase 1 (discovery)
- Findings must exist in `~/.claude/config-audit/sessions/{session-id}/findings/`
## Arguments
- `$ARGUMENTS` may contain `--raw` to forward to the analyzer agent's instructions; in `--raw` mode the agent renders v5.0.0 verbatim severity prefiks instead of humanized `userActionLanguage` urgency phrasing.
## Implementation
### Step 1: Verify session state
Read `~/.claude/config-audit/sessions/{session-id}/state.yaml` using the Read tool and verify discovery phase completed. If not, tell the user: "Discovery hasn't been run yet. Start with `/config-audit discover` or just run `/config-audit` for a full audit."
### Step 2: Tell the user what's happening
```
## Analyzing Configuration
Reading your scan findings and generating a detailed analysis report...
This includes hierarchy mapping, conflict detection, and prioritized recommendations.
```
### Step 3: Spawn analyzer agent
Tell the user: **"Generating analysis (this takes about 30 seconds)..."**
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
```
```
Agent(subagent_type: "config-audit:analyzer-agent")
model: sonnet
prompt: |
Analyze all findings in: ~/.claude/config-audit/sessions/{session-id}/findings/
Mode: $RAW_FLAG (empty = humanized; "--raw" = v5.0.0 verbatim severity prefiks)
Generate comprehensive report covering:
1. Executive summary with key metrics, grouped by userImpactCategory
2. Hierarchy map visualization
3. Conflict detection across config layers
4. CLAUDE.md quality assessment
5. Security issues (secrets, permissions)
6. Top 10 prioritized recommendations — lead each item with the
finding's userActionLanguage ("Fix this now," "Fix soon,"
"Fix when convenient," "Optional cleanup," "FYI") rather than
raw severity. The humanizer already replaced jargon-heavy
title/description/recommendation strings with plain-language
equivalents — render them verbatim, do not paraphrase.
Output to: ~/.claude/config-audit/sessions/{session-id}/analysis-report.md
```
### Step 4: Present summary
After the agent completes, read the generated report and show a brief summary:
```markdown
### Analysis Complete
Report generated with:
- {N} conflicts detected
- {N} optimization opportunities
- {N} security notes
- Top recommendation: {first recommendation}
Full report: `~/.claude/config-audit/sessions/{session-id}/analysis-report.md`
### What's next
- **`/config-audit plan`** — Turn findings into a prioritized action plan
- **`/config-audit fix`** — Auto-fix deterministic issues right away
```
### Step 5: Update state
Update `state.yaml` with `current_phase: "analyze"`, `next_phase: "plan"`.

105
plugins/config-audit/commands/cleanup.md
View file

@ -1,105 +0,0 @@
---
name: config-audit:cleanup
description: Clean up old config-audit sessions to reclaim disk space
allowed-tools: Read, Write, Glob, Bash, AskUserQuestion
model: sonnet
---
# Config-Audit: Session Cleanup
Manage and clean up accumulated config-audit sessions in `~/.claude/config-audit/sessions/`.
## Usage
```
/config-audit cleanup
/config-audit cleanup --raw # pass-through accepted; no-op (cleanup is file-management only, no findings prose)
```
## Implementation Steps
0. **Parse flags**:
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
```
`--raw` is accepted for CLI surface consistency but is a no-op here — cleanup manages session directories on disk, it does not produce findings prose.
1. **List all sessions**:
- Glob `~/.claude/config-audit/sessions/*/state.yaml`
- Use the Read tool on each session's state.yaml and extract:
- Session ID
- Created timestamp
- Current phase
- Whether session is active (has `next_phase` and `current_phase` is not `verify` or `complete`)
2. **Calculate disk usage**:
- Use `du -sh ~/.claude/config-audit/sessions/{session-id}/` for each session
- Calculate the total amount of disk space used
3. **Display session table**:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Config-Audit Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| # | Session ID | Age | Phase | Status | Size |
|---|------------|-----|-------|--------|------|
| 1 | 20260127_102527 | 15d | implement | active | 12K |
| 2 | quick-20260126 | 16d | analyze | complete | 8K |
| 3 | 20260120_091500 | 22d | analyze | complete | 6K |
Total: 3 sessions, 26K disk usage
```
4. **Ask cleanup action**:
```
AskUserQuestion:
question: "Which sessions should I clean up?"
header: "Cleanup"
options:
- label: "Completed sessions only (Recommended)"
description: "Delete sessions where phase is verify/complete. Keeps active sessions safe."
- label: "Older than 14 days"
description: "Delete all sessions older than 14 days, regardless of status."
- label: "All except current"
description: "Delete everything except the most recent active session."
- label: "Cancel"
description: "Don't delete anything."
```
5. **Safety guards**:
- NEVER delete sessions where `current_phase` is not `verify` or `complete` AND `next_phase` exists, unless user explicitly chose age-based or all-except-current
- Warn before deleting active sessions: "Session {id} is still active (phase: {phase}). Delete anyway?"
6. **Execute cleanup**:
- For each session to delete: `rm -rf ~/.claude/config-audit/sessions/{session-id}/`
- Track deleted count and freed space
7. **Output summary**:
```
✓ Cleanup complete
Deleted: 2 sessions
Freed: 14K disk space
Remaining: 1 session (active)
```
## Session Status Detection
A session is considered **active** if ALL of these are true:
- `current_phase` is not `verify` and not `complete`
- `next_phase` exists and is not empty
A session is considered **complete** if ANY of these are true:
- `current_phase` is `verify` or `complete`
- `next_phase` is empty or null
## Error Handling
- **Legacy path:** Also check `~/.config-audit/sessions/` for sessions created before v2.2.0. If found, include them in the session list and note: "Found {n} session(s) at legacy path (~/.config-audit/). These will be cleaned up normally."
- If `~/.claude/config-audit/sessions/` doesn't exist (and no legacy sessions): "No sessions found. Nothing to clean up."
- If no sessions match criteria: "No sessions match the selected criteria."
- If deletion fails: Log error, continue with other sessions

201
plugins/config-audit/commands/config-audit.md
View file

@ -1,201 +0,0 @@
---
name: config-audit
description: Claude Code Configuration Intelligence - audit, analyze, and optimize your configuration
argument-hint: "[posture|tokens|manifest|feature-gap|fix|rollback|plan|implement|help|discover|analyze|interview|drift|plugin-health|whats-active|status|cleanup]"
allowed-tools: Read, Write, Glob, Grep, Bash, Agent, AskUserQuestion
model: opus
---
# Config-Audit: Claude Code Configuration Intelligence
Analyze, report on, and optimize your Claude Code configuration.
## Router Logic
If a subcommand is provided, route to it:
- `posture` → `/config-audit:posture`
- `tokens` → `/config-audit:tokens`
- `manifest` → `/config-audit:manifest`
- `feature-gap` → `/config-audit:feature-gap`
- `fix` → `/config-audit:fix`
- `rollback` → `/config-audit:rollback`
- `plan` → `/config-audit:plan`
- `implement` → `/config-audit:implement`
- `help` → `/config-audit:help`
- `discover` → `/config-audit:discover`
- `analyze` → `/config-audit:analyze`
- `interview` → `/config-audit:interview`
- `drift` → `/config-audit:drift`
- `plugin-health` → `/config-audit:plugin-health`
- `whats-active` → `/config-audit:whats-active`
- `status` → `/config-audit:status`
- `cleanup` → `/config-audit:cleanup`
If a scope override is provided (`current`, `repo`, `home`, `full`), use it as the scope type (see Scope Resolution below).
If no subcommand and no scope override: **run the default audit** (see below).
## UX Rules (MANDATORY — apply to every step)
1. **Narrate before acting.** Before each step, tell the user what you're about to do and why, in plain language.
2. **Never show raw output.** All scanner Bash commands MUST use `--output-file <path>` AND `2>/dev/null`. The user should NEVER see JSON, stderr progress lines, or exit codes.
3. **Handle exit codes silently.** Append `; echo $?` to scanner commands. Exit codes 0/1/2 are all expected (PASS/WARNING/FAIL). Only exit code 3 is a real error — tell user: "Scanner encountered an unexpected error. Try `/config-audit posture` for a quick check instead."
4. **Explain, don't dump.** When presenting findings, add plain-language context. "Grade B" alone means nothing — say "Grade B — your CLAUDE.md files are well-structured with minor improvements possible."
5. **Separate signal from noise.** If findings exist in `tests/fixtures/` or `examples/` directories, count them separately and exclude from the main count: "Found 37 findings (66 additional in test fixtures, excluded)."
6. **Context-sensitive next steps.** Don't just list commands — explain what each does and why the user might want it based on their specific results.
## Default Audit (no arguments)
### Step 1: Auto-detect scope and greet the user
If the user provided a scope override (`/config-audit full`, `/config-audit repo`, etc.), use that.
Otherwise, auto-detect:
1. Run `git rev-parse --show-toplevel 2>/dev/null` via Bash
2. If it succeeds and pwd is inside the repo → **repo** scope (use the git root path)
3. If pwd is `$HOME` → **home** scope
4. Otherwise → **current** directory scope
Show the user what's happening:
```
## Config-Audit
Analyzing your Claude Code configuration...
**Scope:** {Repository|Home directory|Current directory} — `{path}`
**What this checks:** CLAUDE.md quality, settings validation, hook safety, rules correctness, MCP server config, import chains, conflicts, and feature coverage.
```
### Step 2: Initialize session
1. Generate session ID: `YYYYMMDD_HHmmss` format
2. Create session directory and findings subdirectory:
```bash
mkdir -p ~/.claude/config-audit/sessions/{session-id}/findings
```
This is a silent infrastructure step — do NOT show output to the user.
### Step 3: Run scanners and posture assessment
Tell the user: **"Running 12 configuration scanners..."**
Run both scanners and posture in a single Bash command. Default mode runs the humanizer, so each finding in `scan-results.json` carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields. If the user passed `--raw`, thread it through to both CLIs to get v5.0.0 verbatim output.
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/findings/scan-results.json [--full-machine] [--global] $RAW_FLAG 2>/dev/null; node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/posture.json [--full-machine] [--global] $RAW_FLAG 2>/dev/null; echo $?
```
Use `--full-machine` for `full` scope, `--global` for `home` scope. For `repo` and `current`, pass the resolved path directly.
Check the echoed exit code:
- `0`, `1`, or `2` → continue normally
- `3` → tell user: "Scanner encountered an unexpected error. Try `/config-audit posture` for a quick check instead." and stop.
### Step 4: Analyze results
Tell the user: **"Scanners complete. Preparing your results..."**
Read BOTH output files using the Read tool:
- `~/.claude/config-audit/sessions/{session-id}/findings/scan-results.json`
- `~/.claude/config-audit/sessions/{session-id}/posture.json`
Extract these metrics from the JSON:
**From posture.json:**
- `overallGrade` — the health grade (A-F)
- `opportunityCount` — number of unused features detected
- `areas[]` — per-area grades and finding counts (use only quality areas, exclude Feature Coverage)
**From scan-results.json:**
- `aggregate.total_findings` — total findings (test fixture findings are already excluded automatically)
- `fixture_findings` array (if present) — count of findings excluded from test/example directories
- Count findings by severity from `aggregate.counts` (critical, high, medium, low, info)
- Count findings where `autoFixable: true`
- Note total `files_scanned` across scanners
### Step 5: Update state
Write session state (silent — no user output):
```yaml
session_id: "{session-id}"
current_phase: "analyze"
completed_phases: ["discover", "analyze"]
next_phase: "plan"
updated_at: "{ISO timestamp}"
scope_type: "{repo|home|current|full}"
target_path: "{resolved path}"
```
Write to: `~/.claude/config-audit/sessions/{session-id}/state.yaml`
### Step 6: Display results
Present results using this template. The humanizer has already replaced jargon-heavy `title`/`description`/`recommendation` strings on every finding with plain-language equivalents — render them verbatim. Lead urgency phrasing with `userActionLanguage` ("Fix this now", "Fix soon", "Fix when convenient", "Optional cleanup", "FYI") and group "What you can do next" suggestions by that field. Do not re-derive an A/B/C/D/F-to-prose ladder here; the humanized stderr scorecard headline already supplies the grade context, and `userActionLanguage` supplies finding-level urgency.
```markdown
### Results
**Health: {overallGrade}** | {qualityAreaCount} areas scanned
{Use the headline line from the humanized stderr scorecard — it carries grade-context prose already. Avoid hardcoding a separate per-grade prose ladder.}
Scanned {files_scanned} files | {real_finding_count} findings ({severity_breakdown})
{If test_fixture_count > 0: "({test_fixture_count} additional findings in test fixtures were excluded.)"}
{If fixable_count > 0: "{fixable_count} of these can be auto-fixed."}
### Area Breakdown
| Area | Grade | Findings | |
|------|-------|----------|-|
| CLAUDE.md | {grade} | {count} | {one-phrase status} |
| Settings | {grade} | {count} | {status} |
| Hooks | {grade} | {count} | {status} |
| Rules | {grade} | {count} | {status} |
| MCP Servers | {grade} | {count} | {status} |
| Imports | {grade} | {count} | {status} |
| Conflicts | {grade} | {count} | {status} |
{For the status column, use the humanized title from the most-severe finding in that area, or a one-phrase plain-language summary. Findings carry userImpactCategory which already groups by impact bucket — use that vocabulary, not raw scanner names.}
{If opportunityCount > 0:}
{opportunityCount} feature opportunities available — run `/config-audit feature-gap` for context-aware recommendations.
### What you can do next
Group suggestions by `userActionLanguage` from the humanized findings:
{If any finding has userActionLanguage "Fix this now" or "Fix soon":}
- **`/config-audit fix`** — auto-fix what's possible (backup created first, one-command rollback). The remaining items go into a prioritized plan.
- **`/config-audit plan`** — produce a prioritized action plan for the items that need manual attention.
{If most findings are "Fix when convenient" or "Optional cleanup":}
- **`/config-audit feature-gap`** — see which features could enhance your setup; pick what you want and implement on the spot.
- **`/config-audit fix`** — auto-fix anything deterministic; the rest is genuinely optional.
{If only "FYI" findings:}
- **`/config-audit feature-gap`** — explore opportunities; nothing is urgent.
Session saved to: `~/.claude/config-audit/sessions/{session-id}/`
```
## Scope Resolution
| Scope | What gets scanned |
|-------|-------------------|
| `current` | Current directory + parent CLAUDE.md files up to root + `~/.claude/` |
| `repo` | Git repository root + `~/.claude/` |
| `home` | `~/.claude/` global configuration only |
| `full` | Everything: `~/.claude/`, managed paths, all dev dirs under $HOME |
## Error Handling
- If scanner fails (exit 3), tell the user in plain language and suggest `/config-audit posture` as fallback
- If path doesn't exist, tell the user: "That path doesn't exist. Run `/config-audit` without arguments to auto-detect."
- If git command fails for auto-detect, silently fall back to `current` scope
- If no CLAUDE.md found anywhere, explain: "No CLAUDE.md found. This is the main configuration file for Claude Code — creating one is the single highest-impact thing you can do. Run `/config-audit feature-gap` to see what's recommended."

143
plugins/config-audit/commands/discover.md
View file

@ -1,143 +0,0 @@
---
name: config-audit:discover
description: Phase 1 - Initialize session, auto-detect scope, and discover config files
argument-hint: "[current|repo|home|full] [--delta]"
allowed-tools: Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion, Bash
model: opus
---
# Config-Audit: Discover (Phase 1)
Initialize a new audit session and discover all Claude Code configuration files.
## Usage
```
/config-audit discover # Auto-detect scope
/config-audit discover current # Force current directory scope
/config-audit discover repo # Force git repository scope
/config-audit discover home # Force home/global scope
/config-audit discover full # Force full machine scope
/config-audit discover --delta # Incremental re-scan (changed files only)
```
## Implementation
### Step 1: Initialize session and greet
Generate session ID (`YYYYMMDD_HHmmss`), create directories:
```bash
mkdir -p ~/.claude/config-audit/sessions/{session-id}/findings 2>/dev/null
```
### Step 2: Determine scope
If the user provided a scope argument, use it. Otherwise, auto-detect:
1. Run `git rev-parse --show-toplevel 2>/dev/null`
2. If inside a git repo → **repo** scope
3. If pwd is `$HOME` → **home** scope
4. Otherwise → **current** directory scope
Tell the user:
```
## Configuration Discovery
**Scope:** {Repository|Home|Current directory|Full machine} — `{path}`
Finding all Claude Code configuration files (CLAUDE.md, settings, hooks, rules, MCP servers)...
```
### Step 3: Resolve paths
| Scope | What gets scanned |
|-------|-------------------|
| `current` | Current directory + parent CLAUDE.md files up to root + `~/.claude/` |
| `repo` | Git repo root + `~/.claude/` |
| `home` | `~/.claude/` only |
| `full` | `~/.claude/` (depth 10), managed paths, all dev dirs under $HOME |
### Step 4: Delta mode (if --delta)
If `--delta` flag:
1. Find previous baseline from `~/.claude/config-audit/sessions/*/discovery.json`
2. If no previous: "No previous scan found. Running full discovery instead."
3. Compare file mtimes/sizes to classify as changed/new/deleted/unchanged
4. Only scan changed + new files
### Step 5: Run discovery
Run the scan orchestrator silently to discover and scan files. Default mode emits humanized JSON — each finding in `scan-results.json` carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields. Pass `--raw` through if the user requested it (produces v5.0.0 verbatim envelope; humanizer fields absent).
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/findings/scan-results.json [--full-machine] [--global] $RAW_FLAG 2>/dev/null; echo $?
```
Check exit code: 0/1/2 → normal. 3 → "Discovery encountered an error. Try a narrower scope."
### Step 6: Save scope and state
Write `scope.yaml` and `state.yaml` to session directory. Update state with `current_phase: "discover"`, `next_phase: "analyze"`.
### Step 7: Present summary
Read the scan results file using the Read tool. When you surface initial findings, group them by `userImpactCategory` and lead each line with `userActionLanguage` rather than raw severity prefiks — the humanizer already mapped severity to plain-language phrasing ("Fix this now", "Fix soon", "Fix when convenient", "Optional cleanup", "FYI") so the rest of the toolchain sees consistent wording.
**Full scan:**
```markdown
### Discovery Complete
**{scope_type}** scope — found {total_files} configuration files:
| Type | Count |
|------|-------|
| CLAUDE.md | {n} |
| Settings | {n} |
| MCP configs | {n} |
| Rules | {n} |
| Hooks | {n} |
| Other | {n} |
Initial scan found {finding_count} items to review (grouped by impact: {comma-separated counts per userImpactCategory}).
**Next:** Run `/config-audit analyze` to generate your analysis report.
```
**Delta scan:**
```markdown
### Delta Discovery Complete
Compared against baseline from {previous-session-id}:
| Status | Files |
|--------|-------|
| Changed | {n} |
| New | {n} |
| Deleted | {n} |
| Unchanged | {n} |
Only {changed+new} file(s) scanned (vs {total} full scan).
**Next:** Run `/config-audit analyze` to generate your analysis report.
```
## Config File Patterns
| Pattern | Description |
|---------|-------------|
| `**/CLAUDE.md` | Project instructions |
| `**/CLAUDE.local.md` | Local overrides |
| `**/.claude/settings.json` | Project settings |
| `**/.mcp.json` | MCP servers |
| `**/.claude/rules/*.md` | Modular rules |
For global: `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude.json`, `~/.claude/agents/*.md`
## Error Handling
- If scanner fails, report to user in plain language and suggest narrower scope
- If path doesn't exist, tell user and suggest alternatives
- If git command fails for `repo` scope, silently fall back to `current`
- If no config files found, explain: "No Claude Code configuration files found. Start with `/config-audit feature-gap` to see what's recommended."

107
plugins/config-audit/commands/drift.md
View file

@ -1,107 +0,0 @@
---
name: config-audit:drift
description: Compare current configuration against a saved baseline — shows new, resolved, and changed findings
argument-hint: "[path] [--baseline name] [--save]"
allowed-tools: Read, Write, Glob, Grep, Bash
model: sonnet
---
# Config-Audit: Drift Detection
Compare current configuration against a saved baseline to see what changed.
## Arguments
- `$ARGUMENTS` may contain:
- A target path (default: current working directory)
- `--save`: Save current state as baseline
- `--baseline <name>`: Compare against a specific named baseline (default: "default")
- `--raw`: Pass-through to the scanner; produces v5.0.0 verbatim diff output (bypasses the humanizer). Use when piping into v5.0.0-baseline diff tooling that depends on byte-stable output.
## Implementation
### Save a baseline
If `--save` is present:
Tell the user: **"Saving current configuration as baseline..."**
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/drift-cli.mjs <path> --save --name <baseline-name> $RAW_FLAG 2>/dev/null
```
Read stdout for confirmation. Tell the user:
```markdown
### Baseline Saved
Captured current state as baseline "{name}".
Run `/config-audit drift` anytime to see what changed since this point.
```
### Compare against baseline
Without `--save`:
Tell the user: **"Comparing current configuration against baseline..."**
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/drift-cli.mjs <path> --baseline <name> $RAW_FLAG 2>/dev/null
```
Read stdout. In default mode the diff sections are humanized — finding titles, descriptions, and recommendations have already been replaced with plain-language equivalents. New/resolved/changed finding lists carry `userImpactCategory`, `userActionLanguage`, and `relevanceContext` so you can group and prioritize without re-deriving severity prose. If `--raw` was passed, the v5.0.0 diff is verbatim — present it in a code block as-is.
If baseline not found, tell the user:
```
No baseline found. Save one first with:
/config-audit drift --save
```
Otherwise, parse and present the drift report. Use the Read tool on the captured stdout (or pipe it into a tmpfile first if you prefer):
```markdown
### Configuration Drift
**Trend:** {Improving|Degrading|Stable}
**Score:** {before} → {after} ({+/-delta} points)
{If new findings:}
#### New Issues ({count})
| ID | Action | Description |
|----|--------|-------------|
| {id} | {userActionLanguage — "Fix this now", "Fix soon", etc.} | {humanized title} |
{If resolved findings:}
#### Resolved ({count})
| ID | Description |
|----|-------------|
| {id} | {humanized title} |
{If area changes:}
#### Area Changes
| Area | Before | After | Change |
|------|--------|-------|--------|
| ... | ... | ... | ... |
```
When iterating new/resolved findings, prefer `userActionLanguage` over raw `severity` for the "Action" column — the humanizer already mapped severity to plain-language phrasing, and surfacing it consistently keeps the toolchain coherent. Mention `relevanceContext` when it isn't `affects-everyone` (the user wants to know if a fix touches shared config or just their machine).
### List baselines
If `$ARGUMENTS` contains `--list`:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/drift-cli.mjs --list 2>/dev/null
```
### What's next
After viewing drift:
- `/config-audit fix` — Auto-fix new findings
- `/config-audit posture` — Full posture assessment
- `/config-audit drift --save` — Update the baseline to current state

191
plugins/config-audit/commands/feature-gap.md
View file

@ -1,191 +0,0 @@
---
name: config-audit:feature-gap
description: Context-aware feature recommendations — what could enhance your setup and why
argument-hint: "[path]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, AskUserQuestion
model: opus
---
# Config-Audit: Feature Opportunities
Context-aware analysis of Claude Code features that could benefit your specific project — with the option to implement selected recommendations on the spot.
## What the user gets
- Project context detection (language, size, existing configuration)
- Numbered recommendations grouped by impact (high / worth considering / explore)
- Each recommendation backed by evidence (Anthropic docs, proven issues)
- **Interactive selection: "Which would you like to implement?"**
- Direct implementation with backup for selected items
## Implementation
### Step 1: Determine target and flags
Split `$ARGUMENTS` into a path and flags. Path is the first non-flag argument (default: current working directory). Recognized flags:
- `--raw` — pass-through to the scanner; produces v5.0.0 verbatim envelope (bypasses the humanizer). When `--raw` is set, render with v5.0.0 finding-field shape only — humanizer fields are absent in raw output.
Tell the user:
```
## Feature Opportunities
Analyzing which Claude Code features could benefit your workflow...
```
### Step 2: Create session and run posture
Generate session ID (`YYYYMMDD_HHmmss`) if no active session exists.
```bash
mkdir -p ~/.claude/config-audit/sessions/{session-id}/findings 2>/dev/null
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/posture.json $RAW_FLAG 2>/dev/null; echo $?
```
If exit code is non-zero: "Assessment couldn't run. Check that the path exists and contains configuration files."
### Step 3: Read posture data and detect project context
Read `~/.claude/config-audit/sessions/{session-id}/posture.json` using the Read tool.
Extract GAP findings from `scannerEnvelope.scanners` (find scanner with `scanner === 'GAP'`).
Detect project context:
```bash
test -f <target-path>/package.json && echo "has_package_json" || echo "no_package_json"
ls <target-path>/*.py <target-path>/requirements.txt <target-path>/pyproject.toml 2>/dev/null | head -3
```
### Step 4: Build numbered recommendations
Read `${CLAUDE_PLUGIN_ROOT}/knowledge/gap-closure-templates.md` for implementation templates.
Group GAP findings by their humanized fields rather than re-deriving tier-to-prose mappings. In default mode (no `--raw`) each finding carries:
- `userImpactCategory` (e.g., "Missed opportunity") — the impact bucket
- `userActionLanguage` (e.g., "Fix soon", "Fix when convenient", "Optional cleanup", "FYI") — the urgency phrasing the rest of the toolchain uses
- `relevanceContext` ("affects-everyone" / "affects-this-machine-only" / "test-fixture-no-impact") — the scope so the user knows whether the change touches shared config or just their own machine
Group findings into three sections by `userActionLanguage`: "Fix this now" + "Fix soon" → **High Impact**, "Fix when convenient" → **Worth Considering**, "Optional cleanup" + "FYI" → **Explore When Ready**. Number sequentially across sections. Skip findings whose `relevanceContext === "test-fixture-no-impact"` unless the user explicitly asked to include fixtures.
The humanizer has already replaced jargon-heavy strings with plain-language equivalents in `title`, `description`, and `recommendation` — render those verbatim. Do not paraphrase. Do not introduce inline tier-to-prose tables ("Tier 1 means…"); the categories are pre-translated.
If `--raw` was passed, the v5.0.0 envelope is in effect — humanizer fields are absent. Fall back to grouping by `category` ("t1"/"t2"/"t3"/"t4") and render `title` + `recommendation` directly.
Render shape (default mode):
```markdown
### High Impact
{For each finding where userActionLanguage is "Fix this now" or "Fix soon":}
**{N}.** {title}
→ {description}
→ {recommendation}
→ Effort: {from gap-closure-templates.md}
### Worth Considering
{For each finding where userActionLanguage is "Fix when convenient":}
**{N}.** {title}
→ {description}
→ {recommendation}
### Explore When Ready
{For each finding where userActionLanguage is "Optional cleanup" or "FYI":}
**{N}.** {title}
→ {recommendation}
```
Each recommendation MUST have:
- A number
- The humanizer-provided `title`
- The humanizer-provided `description` (where shown)
- An effort estimate looked up from the templates
### Step 5: Ask what to implement
```
AskUserQuestion:
question: "Which would you like to implement? I'll create a backup first."
options:
- "All high impact (1-2)"
- "Pick specific: e.g. 1,3,5"
- "None — just wanted to see the recommendations"
```
If "None": show the full report location and exit.
If the user picks numbers: parse the selection and proceed to Step 6.
### Step 6: Implement selected recommendations
For each selected recommendation:
1. **Create backup** of any files that will be modified:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <target-path> --json 2>/dev/null
```
Or create manual backup:
```bash
mkdir -p ~/.claude/config-audit/backups/$(date +%Y%m%d_%H%M%S)/files/ 2>/dev/null
```
Copy each file that will be touched.
2. **Apply the template** from gap-closure-templates.md. Use the Write or Edit tool to create or modify the relevant configuration file.
3. **Show progress** as each item is done:
```
Implementing 3 recommendations...
✓ 1. permissions.deny — added to .claude/settings.json
✓ 3. Modular CLAUDE.md — created .claude/rules/testing.md, added @import
✓ 5. Keybindings — created ~/.claude/keybindings.json
```
4. **Verify** by re-running posture:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --json --output-file /tmp/config-audit-verify-$$.json 2>/dev/null
```
### Step 7: Show results
```markdown
### Done
**{N} recommendations implemented** | Backup created
{If health grade changed:}
Health: {old_grade} → {new_grade} (+{delta} points)
{Show remaining opportunities if any:}
{remaining} more opportunities available — run `/config-audit feature-gap` again anytime.
**Rollback:** If anything looks wrong, run `/config-audit rollback` to restore.
```
## Implementation Guidelines
When implementing recommendations, be smart about context:
- **permissions.deny**: Look at the project for common sensitive paths (`.env`, `secrets/`, `.git/config`, `*.pem`). Don't just copy a template blindly — check what actually exists.
- **hooks**: Start with a simple, useful hook. Don't scaffold 5 hooks at once.
- **path-scoped rules**: Look at the project's file structure to determine meaningful scopes (e.g., `tests/**/*.ts` vs `src/**/*.ts`).
- **CLAUDE.md modularization**: Only suggest splitting if the file is over 100 lines. Read it first to find natural section boundaries.
- **MCP setup**: Only relevant if the user actually has external tools to connect. Ask before creating.
- **Custom plugin**: Too complex for inline implementation — suggest `/config-audit plan` instead.
For items that genuinely need user input (e.g., "which MCP servers do you use?"), ask briefly during implementation rather than skipping them.
## Safety
- **Backup mandatory** — always create before modifying
- **Show what's changing** — the user sees each change as it happens
- **Rollback available** — `/config-audit rollback` at any time
- **Non-destructive** — only create new files or add to existing; never delete content

145
plugins/config-audit/commands/fix.md
View file

@ -1,145 +0,0 @@
---
name: config-audit:fix
description: Auto-fix deterministic configuration issues with backup and verification
argument-hint: "[path] [--dry-run]"
allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
model: sonnet
---
# Config-Audit: Fix
Auto-fix deterministic configuration issues. Scans, plans fixes, backs up originals, applies changes, and verifies results.
## Arguments
- `$ARGUMENTS` may contain:
- A target path (default: current working directory)
- `--dry-run`: Show fix plan without applying
- `--raw`: Pass-through to scanners; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling
## Implementation
### Step 1: Greet and scan
Tell the user:
```
## Config-Audit Fix
Scanning for auto-fixable issues...
```
Parse flags and run scanners silently. Default mode emits humanized JSON — each finding carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields:
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <path> --output-file /tmp/config-audit-fix-scan-$$.json [--global] $RAW_FLAG 2>/dev/null; echo $?
```
Exit code 3 → tell user: "Scanner error. Try `/config-audit posture` to check your configuration."
### Step 2: Plan fixes
Run fix planner silently. The fix-cli emits humanized prose to stderr in default mode and v5.0.0-shape JSON to stdout when `--json` is set; we use `--json` here for structured data and let the humanizer-aware rendering layer (this command's prose output below) supply the plain-language wording from the scan envelope above:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --json 2>/dev/null
```
Read the JSON output using the Read tool. Cross-reference each fix-plan entry against the humanized scan envelope (`/tmp/config-audit-fix-scan-$$.json`) by finding ID to recover the humanized `title`/`description`/`recommendation` plus `userImpactCategory`/`userActionLanguage` for grouping.
### Step 3: Present fix plan
Show what will be fixed and what needs manual attention. Group by `userActionLanguage` so the urgency phrasing stays consistent with the rest of the toolchain:
```markdown
### Fix Plan
**Auto-fixable ({N} issues), grouped by impact:**
{For each userActionLanguage bucket in priority order — "Fix this now" → "Fix soon" → "Fix when convenient" → "Optional cleanup" → "FYI":}
#### {userActionLanguage}
| # | ID | Issue | File |
|---|-----|-------|------|
| 1 | {id} | {humanized title} | {file} |
**Manual ({M} issues — require human judgment), grouped by impact:**
{Same userActionLanguage grouping. Render humanized title and recommendation verbatim — the humanizer already produced plain-language strings, do not paraphrase.}
| # | ID | Issue | Recommendation |
|---|-----|-------|----------------|
| 1 | {id} | {humanized title} | {humanized recommendation} |
```
### Step 4: Confirm with user
If not `--dry-run`, ask for confirmation:
```
AskUserQuestion:
question: "Apply {N} auto-fixes? A backup is created first — you can roll back anytime."
options:
- "Yes, apply fixes"
- "Show dry-run only"
- "Cancel"
```
### Step 5: Apply fixes
If confirmed, apply:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --apply --json 2>/dev/null
```
Read the JSON output to get applied/failed counts and backup location.
### Step 6: Show results
Run a quick posture check to measure improvement:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <path> --json --output-file /tmp/config-audit-fix-posture-$$.json 2>/dev/null
```
Present results:
```markdown
### Results
**{applied} fixed** | {failed} failed | Backup created
{If grade improved:}
Score impact: {old_grade} ({old_score}) → {new_grade} ({new_score}) — **+{delta} points**
{If failed > 0:}
{failed} fix(es) couldn't be applied — run `/config-audit plan` for alternative approaches.
**Rollback:** If anything looks wrong, run `/config-audit rollback {backup-id}` to restore.
```
### Step 7: Manual findings
If manual findings exist:
```markdown
### Needs manual attention
These {M} issues require human judgment:
1. **{title}** ({id}) — {recommendation}
2. ...
Run `/config-audit plan` to get a step-by-step guide for addressing these.
```
## Safety
- Backup is **mandatory** — every fix creates a backup first
- Dry-run by default — user must confirm before changes
- Verify after fix — re-scans to confirm findings resolved
- Rollback always available — `/config-audit rollback <backup-id>`

113
plugins/config-audit/commands/help.md
View file

@ -1,113 +0,0 @@
---
name: config-audit:help
description: Show all available config-audit commands
allowed-tools: Read, Bash
model: sonnet
---
# Config-Audit: Help
## Getting Started
Just run `/config-audit` — it auto-detects your project scope and runs a full audit. No setup needed.
The default output is written in plain language: each finding is grouped by impact ("Configuration mistake," "Conflict," "Wasted tokens," "Missed opportunity," "Dead config") and led with an urgency phrase ("Fix this now," "Fix soon," "Fix when convenient," "Optional cleanup," "FYI").
If you prefer the v5.0.0 verbatim output (technical IDs, raw severity, no plain-language wording), pass `--raw` to any command — it's threaded through every CLI in the toolchain. Use the Read tool on the saved JSON to consume it programmatically.
```bash
# Examples — every command accepts --raw for byte-stable v5.0.0 output
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
# /config-audit posture --raw
# /config-audit tokens --raw
# /config-audit fix --raw
```
## All Commands
### Core
| Command | Description |
|---------|-------------|
| `/config-audit` | Full audit with auto-scope detection |
| `/config-audit posture` | Quick scorecard with A-F grades per area (10 areas) |
| `/config-audit tokens` | Opus-4.7 token hotspots; optional `--accurate-tokens` API calibration |
| `/config-audit manifest` | Ranked table of every system-prompt token source |
| `/config-audit feature-gap` | Deep analysis of features you're not using |
| `/config-audit fix` | Auto-fix deterministic issues; a copy of every changed file is saved first so you can roll back with one command |
| `/config-audit rollback` | Restore configuration from a saved copy |
### Planning & Implementation
| Command | Description |
|---------|-------------|
| `/config-audit plan` | Generate prioritized action plan from audit findings |
| `/config-audit implement` | Execute action plan; a copy of every changed file is saved first, and a verification pass runs after |
| `/config-audit interview` | Set preferences to customize the action plan _(optional)_ |
### Monitoring
| Command | Description |
|---------|-------------|
| `/config-audit drift` | Compare current config against a saved baseline |
| `/config-audit plugin-health` | Audit plugin structure and the metadata block at the top of each command/agent file |
| `/config-audit whats-active` | Show active plugins/skills/MCP/hooks/CLAUDE.md with token estimates |
### Utility
| Command | Description |
|---------|-------------|
| `/config-audit status` | Show current session state and progress |
| `/config-audit cleanup` | Clean up old session directories |
### Advanced (workflow phases)
| Command | Description |
|---------|-------------|
| `/config-audit discover` | Run only the discovery phase (find config files) |
| `/config-audit analyze` | Run only the analysis phase (generate report) |
## Plain-language vocabulary
The toolchain uses these terms when describing findings:
| User-facing label | What it means |
|-------------------|---------------|
| Fix this now | Something is broken or risky and should be addressed immediately |
| Fix soon | High-priority issue worth scheduling this week |
| Fix when convenient | Real issue but not urgent |
| Optional cleanup | Tidy-up that improves polish but isn't required |
| FYI | Informational; no action expected |
| Configuration mistake | A configuration file has an error or omission |
| Conflict | Two configuration sources disagree |
| Wasted tokens | Configuration is loading content that costs tokens without payback |
| Missed opportunity | A Claude Code feature you aren't using that could help your project |
| Dead config | Configuration that has no effect (e.g., a permission that's also denied) |
Use `--raw` if you'd rather see the v5.0.0 verbatim output (technical IDs and raw severity).
## Scope Override
By default, `/config-audit` auto-detects scope from your current directory:
- Inside a git repo → scans the repo
- In `$HOME` → scans global config only
- Elsewhere → scans current directory
Override with: `/config-audit current`, `/config-audit repo`, `/config-audit home`, `/config-audit full`
## Typical Workflows
**First time?** Just run `/config-audit`.
**Want to fix things?** Run `/config-audit` then `/config-audit fix`.
**Full optimization:**
1. `/config-audit` — see what you have
2. `/config-audit plan` — create action plan
3. `/config-audit implement` — execute with backups
**Track changes over time:**
1. `/config-audit drift --save` — save baseline
2. _(make changes)_
3. `/config-audit drift` — see what changed

145
plugins/config-audit/commands/implement.md
View file

@ -1,145 +0,0 @@
---
name: config-audit:implement
description: Phase 5 - Execute action plan with backups and verification
allowed-tools: Read, Write, Edit, Bash, Agent, AskUserQuestion
model: opus
---
# Config-Audit: Implementation (Phase 5)
Execute the action plan with full backup, verification, and rollback support.
## Prerequisites
- Must have completed Phase 4 (plan)
- Action plan at `~/.claude/config-audit/sessions/{session-id}/action-plan.md`
## Arguments
- `$ARGUMENTS` may contain `--raw` to forward to the implementer-agent's instructions; in `--raw` mode the agent renders v5.0.0 verbatim severity prefiks instead of humanized `userActionLanguage` urgency phrasing.
## Implementation
### Step 1: Parse flags, load and verify
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
```
Find the most recent session with a plan. If none: "No action plan found. Run `/config-audit plan` first."
Use the Read tool on the action plan and count actions. Tell the user:
```
## Implementing Action Plan
Found {N} actions to execute across {M} files.
A backup will be created before any changes are made.
```
### Step 2: Get user approval
```
AskUserQuestion:
question: "Ready to implement {N} actions? Backup created automatically — you can roll back with one command."
options:
- "Yes, proceed"
- "Review plan first" (then show the plan file path)
- "Cancel"
```
### Step 3: Create backup
Create backup silently:
```bash
mkdir -p ~/.claude/config-audit/backups/$(date +%Y%m%d_%H%M%S)/files/ 2>/dev/null
```
Copy each file to be modified. Generate `manifest.yaml` with checksums.
Tell the user: **"Backup created. Implementing actions..."**
### Step 4: Execute actions
Group actions by dependencies. For each group, spawn implementer agents (batch of 3):
```
Agent(subagent_type: "config-audit:implementer-agent")
model: sonnet
prompt: |
Execute action: {action-id}
File: {file-path}, Type: {create|modify|delete}
Mode: $RAW_FLAG (empty = humanized progress prose; "--raw" = v5.0.0 verbatim)
Details: {changes}
Verify backup exists, make change, validate syntax.
When logging progress, use the humanized title/userActionLanguage
fields from the action plan (the planner already rendered them) —
do not re-derive severity prose. Append result to:
~/.claude/config-audit/sessions/{session-id}/implementation-log.md
```
Show progress between groups using the humanized titles already present in the action plan:
```
Action 1/N: {humanized title} — done
Action 2/N: {humanized title} — done
...
```
### Step 5: Verify results
Spawn verifier agent:
```
Agent(subagent_type: "config-audit:verifier-agent")
model: sonnet (note: using sonnet, not haiku)
prompt: |
Verify all changes from implementation:
1. Modified files exist and are syntactically valid
2. New files created correctly
3. No new conflicts introduced
Report to: ~/.claude/config-audit/sessions/{session-id}/implementation-log.md
```
If verifier finds issues: one retry with implementer agent. If still failing: report and suggest rollback.
### Step 6: Present results
```markdown
### Implementation Complete
**{succeeded} succeeded** | {failed} failed | {skipped} skipped
{If score improved, run quick posture and show:}
Score impact: {old_grade} → {new_grade} (+{delta} points)
{If failed > 0:}
{failed} action(s) couldn't be completed — see log for details.
**Backup location:** `~/.claude/config-audit/backups/{timestamp}/`
**Rollback:** `/config-audit rollback {timestamp}`
**Full log:** `~/.claude/config-audit/sessions/{session-id}/implementation-log.md`
```
### Step 7: Update state
Update `state.yaml` with `current_phase: "implement"`, `next_phase: null`.
## Rollback
If the user requests rollback at any point:
1. Read `manifest.yaml` from backup
2. Restore each file and verify checksums
3. Delete newly created files
4. Update state to `rolled_back`
## Error Handling
| Error | What happens |
|-------|-------------|
| Permission denied | Skip action, log it, continue with others |
| File not found | Skip action, log it, continue |
| Invalid syntax after edit | Rollback that single file, log, continue |
| Critical failure | Offer full rollback |

75
plugins/config-audit/commands/interview.md
View file

@ -1,75 +0,0 @@
---
name: config-audit:interview
description: Phase 3 - Interactive interview to gather user preferences
allowed-tools: Read, Write, Edit, AskUserQuestion, Bash
model: sonnet
---
# Config-Audit: Interview (Phase 3)
Gather user preferences to inform the action plan.
## IMPORTANT: Inline Execution Only
This command runs AskUserQuestion **directly in the main context** — NOT via a Task subagent.
AskUserQuestion requires synchronous terminal interaction and does not work when delegated to a Task subagent.
## Prerequisites
- Must have completed Phase 2 (analysis)
- Use the Read tool on the analysis at `~/.claude/config-audit/sessions/{session-id}/analysis-report.md`
## Arguments
- `$ARGUMENTS` may contain `--raw` — pass-through accepted for CLI surface consistency. Interview is interactive prose only (no scanner output, no findings prose), so `--raw` is a no-op here.
## Implementation Steps
0. **Parse flags**:
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
```
1. **Load session state**: Verify analysis phase completed, read analysis report for context
2. **Conduct interview inline**: Use AskUserQuestion tool directly (NOT via Task). Adapt questions based on analysis findings.
3. **Save interview results**: Write to `~/.claude/config-audit/sessions/{session-id}/interview.md`
4. **Update state** (see state-management rule)
5. **Output summary**
## Interview Questions
Ask these using AskUserQuestion (skip questions that don't apply based on analysis). Where the analysis report references finding IDs, use the humanized title from the report rather than re-deriving prose:
1. **Config Style** — Centralized vs Distributed vs Hybrid organization
2. **Unused automation that runs at specific events** — Wire up, review individually, delete, or leave (only if the analysis report flagged one)
3. **Duplicate Permissions** — Remove from local, consolidate, or keep (only if found)
4. **Modular Rules** — Use .claude/rules/ pattern? Yes/No
5. **Path-Scoped Rules** — Which patterns (tests, src, config, docs) — only if Q4=Yes
6. **Conflict Resolution** — Per-conflict: global vs project vs custom value (only if conflicts found)
7. **Permission Audit** — Audit or keep (only if >30 patterns in settings.local.json)
8. **Project Inheritance** — Per-project: inherit or isolate (only if multiple projects)
## Adaptive Questioning
Skip questions that don't apply:
- No unused hooks question if all hooks are wired
- No duplicates question if no duplicates found
- No conflict questions if no conflicts detected
- No path-scoping if user said no to modular rules
- Fewer project questions if only one project
- No permission audit if <30 patterns
## Skip Interview Option
If user runs `/config-audit plan` without interview:
- Use sensible defaults (centralized, inherit, enable rules)
- Flag decisions in plan as "assumed"
## Error Handling
- If user selects "Other" for any question, ask follow-up with AskUserQuestion
- If interview is cancelled, save partial results
- If no analysis report found, report error and exit
- If AskUserQuestion fails, STOP — do not use alternative methods

81
plugins/config-audit/commands/manifest.md
View file

@ -1,81 +0,0 @@
---
name: config-audit:manifest
description: Show ranked token-source manifest — every CLAUDE.md, plugin, skill, MCP server, and hook ordered DESC by estimated tokens
argument-hint: "[path] [--json]"
allowed-tools: Read, Bash
model: sonnet
---
# Config-Audit: Manifest
Produce a ranked, single-table view of every token source loaded for a given repo path. Where `whats-active` shows separate tables per category, `manifest` collapses everything into one ordered list — making it easy to see what's costing the most regardless of category.
## UX Rules (MANDATORY — from `.claude/rules/ux-rules.md`)
1. **Never show raw JSON or stderr output.** Always use `--output-file` + `2>/dev/null`.
2. **Narrate before acting.** Tell the user what you're about to do.
3. **Read, don't dump.** Read the JSON file and render a formatted table.
4. **End with context-sensitive next steps.**
## Implementation
### Step 1: Parse `$ARGUMENTS`
First non-flag argument is the path (default `.`). Recognized flags:
- `--json` — emit raw JSON instead of the rendered table.
- `--raw` — pass-through to the scanner; accepted for CLI surface consistency with the other config-audit commands. The manifest CLI is data-table only (no findings prose), so `--raw` is a no-op here, but the flag is still threaded through so users get uniform behaviour across `--raw`.
### Step 2: Run the CLI silently
Tell the user: **"Building token-source manifest for `<path>`..."**
```bash
TMPFILE="/tmp/ca-manifest-$$.json"
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/manifest.mjs <path> --output-file "$TMPFILE" $RAW_FLAG 2>/dev/null; echo $?
```
**Exit code handling:**
- `0` → continue
- `3` → tell user: "Couldn't read configuration. Check that the path exists and is a directory." Stop.
### Step 3: If `--json` was requested, cat the file and stop
```bash
cat "$TMPFILE"
```
Do NOT render the table in JSON mode.
### Step 4: Read JSON and render
Use the Read tool on `$TMPFILE`. Extract `meta.repoPath`, `total`, and `sources[]`. Render the top 20 sources (or fewer if the manifest is shorter):
```markdown
**Token-source manifest for `<repoPath>`** — ~{total} tokens at startup
| Rank | Kind | Name | Source | Tokens |
|------|------|------|--------|--------|
| 1 | {kind} | `<name>` | {source} | ~{estimated_tokens} |
| ... | ... | ... | ... | ... |
_Estimates assume ~4 chars/token (Claude ballpark). Real token count varies ±15%._
```
If `sources.length > 20`, follow the table with: _"Showing top 20 of {N} sources. Run with `--json` to see the full list."_
### Step 5: Suggest next steps
```markdown
**Next steps:**
- `/config-audit tokens` — Opus-4.7 token-hotspot patterns (cache-breaking, redundant perms, deep imports, MCP budget)
- `/config-audit whats-active` — same data grouped by category, with disable suggestions
- `/config-audit feature-gap` — what *could* improve here, grouped by impact
```
Tone:
- High total (>50k): empathetic — "That's a heavy startup cost; tokens bullet anything you'd otherwise spend on the actual conversation."
- Moderate (10–50k): neutral — "Reasonable. Skim the top 5 to see if anything is unexpectedly large."
- Low (<10k): encouraging — "Tight setup. The model has plenty of room for the actual work."

101
plugins/config-audit/commands/plan.md
View file

@ -1,101 +0,0 @@
---
name: config-audit:plan
description: Phase 4 - Generate prioritized action plan with risk assessment
allowed-tools: Read, Write, Glob, Grep, Agent, Bash
model: opus
---
# Config-Audit: Plan Generation (Phase 4)
Generate a prioritized action plan based on analysis results.
## Prerequisites
- Must have completed Phase 2 (analysis)
- Phase 3 (interview) is optional — plan works with or without it
## Arguments
- `$ARGUMENTS` may contain `--raw` to forward to the planner-agent's instructions; in `--raw` mode the agent renders v5.0.0 verbatim severity prefiks instead of humanized `userActionLanguage` urgency phrasing.
## Implementation
### Step 1: Verify session state
Find the most recent session with analysis completed using the Read tool on `~/.claude/config-audit/sessions/*/state.yaml`. If none found: "No analysis results found. Run `/config-audit` first to scan your configuration."
### Step 2: Tell the user what's happening
```
## Creating Action Plan
Building a prioritized plan based on your analysis results...
Actions are ordered by impact, with risk assessment and dependency tracking.
```
### Step 3: Parse flags and spawn planner agent
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
```
Tell the user: **"Generating your action plan (this takes about 30 seconds)..."**
```
Agent(subagent_type: "config-audit:planner-agent")
model: opus
prompt: |
Generate action plan based on:
- Analysis: ~/.claude/config-audit/sessions/{session-id}/analysis-report.md
- Interview: ~/.claude/config-audit/sessions/{session-id}/interview.md (if exists)
Mode: $RAW_FLAG (empty = humanized; "--raw" = v5.0.0 verbatim severity prefiks)
Create a prioritized plan that consumes the humanized finding fields:
- Group actions by userImpactCategory (e.g., "Configuration mistake",
"Conflict", "Wasted tokens", "Missed opportunity", "Dead config")
- Lead each action with userActionLanguage ("Fix this now," "Fix soon,"
"Fix when convenient," "Optional cleanup," "FYI") rather than raw
severity. The humanizer already replaced jargon-heavy
title/description/recommendation strings with plain-language
equivalents — render them verbatim, do not paraphrase.
- Surface relevanceContext when it isn't "affects-everyone" so the
user knows whether a fix touches shared config or just their machine
- Include risk assessment per action (low/medium/high)
- Rollback strategy
- Dependency ordering
- Effort estimates
Output to: ~/.claude/config-audit/sessions/{session-id}/action-plan.md
```
### Step 4: Present the plan summary
Read the generated plan and show a concise overview:
```markdown
### Action Plan Ready
**{N} actions** organized by priority:
| # | Action | Risk | Effort |
|---|--------|------|--------|
| 1 | {title} | {low/med/high} | {quick/moderate/involved} |
| 2 | ... | ... | ... |
| ... | ... | ... | ... |
Full plan: `~/.claude/config-audit/sessions/{session-id}/action-plan.md`
You can edit the plan file to remove, reorder, or modify actions before implementing.
### What's next
- **`/config-audit implement`** — Execute the plan with automatic backup and verification
- **`/config-audit interview`** — Set preferences first to customize the plan (optional)
```
### Step 5: Update state
Update `state.yaml` with `current_phase: "plan"`, `next_phase: "implement"`.
## Plan Modification
Users can edit `action-plan.md` before implementation — remove unwanted actions, adjust priority, or add custom actions. The implementer parses the modified plan.

79
plugins/config-audit/commands/plugin-health.md
View file

@ -1,79 +0,0 @@
---
name: config-audit:plugin-health
description: Audit plugin configuration quality — validates structure, frontmatter, and cross-plugin coherence
argument-hint: "[plugin-path]"
allowed-tools: Read, Glob, Grep, Bash
model: sonnet
---
# Config-Audit: Plugin Health
Audit Claude Code plugin structure and quality — validates plugin.json, CLAUDE.md, command/agent frontmatter, and detects cross-plugin conflicts.
## Arguments
- `$ARGUMENTS` may contain a path to a specific plugin directory
- If omitted: scans all plugins in the marketplace root
- `--raw`: pass-through to the scanner; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling
## Implementation
### Step 1: Discover plugins and greet
If a specific path is given, scan only that plugin. Otherwise, find all plugins using Glob for `**/.claude-plugin/plugin.json`.
Tell the user:
```
## Plugin Health Check
Auditing {N} plugin(s) for structure, frontmatter quality, and cross-plugin conflicts...
```
### Step 2: Run scanner
Run silently for each plugin. Default mode emits a humanized JSON envelope where each PLH finding carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields. `--raw` is passed through verbatim when present.
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/plugin-health-scanner.mjs <path> $RAW_FLAG 2>/dev/null
```
Read stdout output (JSON) using the Read tool. Parse findings.
### Step 3: Present results
```markdown
### Plugin Health Report
| Plugin | Grade | Commands | Agents | Status |
|--------|-------|----------|--------|--------|
| {name} | {grade} ({score}) | {cmd_count} | {agent_count} | {Good/Issues found} |
| ... | ... | ... | ... | ... |
{If cross-plugin issues:}
#### Cross-Plugin Issues ({count})
| Issue | Plugins | Recommendation |
|-------|---------|----------------|
| ... | ... | ... |
{If findings:}
#### Findings by Plugin
**{plugin-name}** ({finding_count} findings):
1. [{userActionLanguage}] {humanized title} ({id}) — {humanized recommendation}
2. ...
```
Group findings within each plugin by `userImpactCategory` (e.g., "Configuration mistake", "Conflict") and lead each line with `userActionLanguage` ("Fix this now", "Fix soon", "Optional cleanup"). The humanizer already produced the plain-language `title`/`recommendation` strings — render them verbatim, do not paraphrase.
### Step 4: Suggest next steps
```
### What's next
- Fix structural issues based on recommendations above
- `/config-audit posture` — Full configuration posture assessment
- `/config-audit fix` — Auto-fix deterministic issues
```

117
plugins/config-audit/commands/posture.md
View file

@ -1,117 +0,0 @@
---
name: config-audit:posture
description: Quick configuration health assessment — scorecard with A-F grades
argument-hint: "[path] [--drift] [--plugin-health]"
allowed-tools: Read, Write, Glob, Grep, Bash
model: sonnet
---
# Config-Audit: Health Assessment
Quick, deterministic configuration health scorecard. No agents needed — runs all scanners + scoring in one pass.
## What the user gets
- Health grade (A-F) with plain-language explanation
- Per-area breakdown for 10 quality areas (incl. Token Efficiency, Plugin Hygiene) with grades and actionable notes
- Opportunity count — how many features could enhance their setup (not a grade)
- Grade-appropriate next steps
## Implementation
### Step 1: Determine target and flags
Split `$ARGUMENTS` into a path and flags. Path is the first non-flag argument (default: current working directory). Resolve relative paths. Recognized flags:
- `--raw` — pass-through to the scanner; produces v5.0.0 verbatim output (bypasses the humanizer). Power-user mode for byte-stable diffs and machine consumption.
- `--drift` — append a "Configuration Drift" section (see Step 5).
- `--plugin-health` — append a "Plugin Health" section (see Step 5).
Tell the user:
```
## Configuration Health
Running quick assessment{if path != cwd: " on `{path}`"}...
```
### Step 2: Run posture scanner
Run silently — JSON goes to a file, the humanized scorecard prints to stderr (default mode). The humanized stderr scorecard already includes the grade headline and area-score lines in plain language, so render those directly rather than re-deriving prose tables.
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --output-file /tmp/config-audit-posture-$$.json $RAW_FLAG 2>/tmp/config-audit-posture-stderr-$$.txt; echo $?
```
If exit code is non-zero, tell the user: "Assessment couldn't complete. Check that the path exists and contains Claude Code configuration files."
If `--raw` was passed, treat the captured stderr as v5.0.0-shape verbatim text and present it as-is in a code block; skip the humanized rendering steps below.
### Step 3: Read and interpret results
Read the JSON output file using the Read tool. Extract:
- `overallGrade`, `opportunityCount`
- `areas[]` — each with `name`, `grade`, `score`, `findingCount`
- `scannerEnvelope.scanners[].findings[]` — when surfacing individual findings, prefer the humanizer-provided fields: `userImpactCategory` (e.g., "Configuration mistake", "Wasted tokens"), `userActionLanguage` (e.g., "Fix this now", "Fix soon", "Optional cleanup"), and `relevanceContext` ("affects-everyone", "affects-this-machine-only", "test-fixture-no-impact"). These let you group and prioritize without hardcoded severity-to-prose mappings.
Also Read the captured stderr file — its body is the humanized scorecard (grade headline, area-score block, opportunity hint). You can present it verbatim or interleave its lines with the JSON-driven table.
### Step 4: Present the scorecard
```markdown
**Health: {overallGrade}** | {qualityAreaCount} areas scanned
{Use the headline line from the humanized stderr scorecard — it carries grade-context prose already (e.g., " Health: A (97/100) — Healthy setup, only minor polish needed"). Do not re-derive an A/B/C/D prose table here; the humanizer owns that vocabulary.}
### Area Scores
| Area | Grade | Score | Findings | |
|------|-------|-------|----------|-|
{for each area EXCEPT Feature Coverage:}
| {name} | {grade} | {score}/100 | {findingCount} | {plain-language note: A="Excellent", B="Good", C="Needs work", D/F="Issues found"} |
{if opportunityCount > 0:}
{opportunityCount} feature opportunities available — run `/config-audit feature-gap` for context-aware recommendations.
### What's next
```
Group "what's next" suggestions by `userActionLanguage` from the humanized findings:
- Findings tagged "Fix this now" / "Fix soon" → suggest `/config-audit fix` first, then `/config-audit plan`.
- Findings tagged "Fix when convenient" / "Optional cleanup" → suggest `/config-audit feature-gap` and routine maintenance.
- No high-urgency findings → suggest `/config-audit feature-gap` for opportunities and re-running posture after major config changes.
Avoid hardcoded grade-to-prose ladders here — the humanized scorecard headline already supplies grade context, and `userActionLanguage` supplies finding-level urgency.
### Step 5: Optional sections
**If `--drift` flag is present:**
Run drift comparison silently:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/drift-cli.mjs <target-path> 2>/dev/null
```
Read stdout output and append a "Configuration Drift" section showing what changed since the last baseline.
**If `--plugin-health` flag is present:**
Run plugin health scanner silently:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/plugin-health-scanner.mjs <target-path> 2>/dev/null
```
Read stdout output and append a "Plugin Health" section.
**If both flags:** Use `scanners/lib/report-generator.mjs` to produce a unified markdown report.
### Step 6: Save to session (if active)
If a config-audit session exists, save results:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --json --output-file ~/.claude/config-audit/sessions/<session-id>/posture.json 2>/dev/null
```

90
plugins/config-audit/commands/rollback.md
View file

@ -1,90 +0,0 @@
---
name: config-audit:rollback
description: Restore configuration from backup — list available backups or rollback a specific one
argument-hint: "[backup-id]"
allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
model: sonnet
---
# Config-Audit: Rollback
Restore configuration files from a previous backup. Without arguments, lists available backups. With a backup ID, restores files from that backup.
## Arguments
- `$ARGUMENTS` may contain a backup ID (format: `YYYYMMDD_HHMMSS`)
- `--raw`: pass-through flag accepted for CLI surface consistency. Rollback is file restoration only (no scanner output, no findings prose), so `--raw` is a no-op here, but the flag is still parsed so users get uniform behaviour across the toolchain.
## Behavior
### List mode (no argument)
Parse flags and list available backups from `~/.claude/config-audit/backups/`:
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
ls -1 ~/.claude/config-audit/backups/
```
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Available Backups
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 20260403_163045 — 3 files (settings.json, hooks.json, typescript.md)
2. 20260403_141230 — 1 file (CLAUDE.md)
3. 20260402_092015 — 5 files (full audit)
Usage: /config-audit rollback 20260403_163045
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Use the Read tool on each backup's `manifest.yaml` (the list of changes captured at backup time) to extract the file list and timestamps.
### Restore mode (with backup ID)
1. Read the list of changes from `~/.claude/config-audit/backups/{backup-id}/manifest.yaml` using the Read tool
2. Show files that will be restored — ask for confirmation:
```
AskUserQuestion:
question: "Restore 3 files from backup 20260403_163045?"
options:
- "Yes, restore"
- "Cancel"
```
3. For each file in the list of changes:
a. Read the backup file from `~/.claude/config-audit/backups/{backup-id}/files/{safeName}`
b. Write to the original path
c. Verify the checksum matches the recorded value in the list of changes
4. Show result:
```
Restored 3 files from backup 20260403_163045
- .claude/settings.json (checksum verified)
- hooks/hooks.json (checksum verified)
- .claude/rules/typescript.md (checksum verified)
```
### Delete mode
If user says "delete" after listing, confirm and remove the backup directory.
## Implementation
Use the backup and rollback libraries directly:
```javascript
import { listBackups, restoreBackup, deleteBackup } from '../scanners/rollback-engine.mjs';
import { parseManifest } from '../scanners/lib/backup.mjs';
```
Or via Bash:
```bash
# List backups
ls -1 ~/.claude/config-audit/backups/
# Read manifest
cat ~/.claude/config-audit/backups/{id}/manifest.yaml
# Restore (copy back)
cp ~/.claude/config-audit/backups/{id}/files/{safeName} {originalPath}
```

138
plugins/config-audit/commands/status.md
View file

@ -1,138 +0,0 @@
---
name: config-audit:status
description: Show current session state and available actions
allowed-tools: Read, Glob, Bash
model: sonnet
---
# Config-Audit: Status
Display current session state and guide next actions.
## Usage
```
/config-audit status
/config-audit status --raw # show the raw v5.0.0 phase identifiers (current_phase: "discover", etc.) instead of humanized labels
```
## Phase-label translation
The `state.yaml` field `current_phase` is the machine contract — never rename it. The user-facing label is humanized. Map the field value to a plain-language label when rendering (default mode):
| `current_phase` (machine field, unchanged) | User-facing label |
|--------------------------------------------|-------------------|
| `discover` | Looking at your config files |
| `analyze` | Working out what to recommend |
| `interview` | Asking what you'd like to focus on |
| `plan` | Putting together your action plan |
| `implement` | Making the changes |
| `verify` | Double-checking everything worked |
When `--raw` is in `$ARGUMENTS`, render the raw `current_phase` field value verbatim (no humanization).
## Implementation
1. **Parse flags**:
```bash
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
```
2. **Find active session**:
```
Glob: ~/.claude/config-audit/sessions/*/state.yaml
Sort by modification time
Use most recent
```
3. **Read session state** with the Read tool:
```yaml
session_id: "20250126_143022"
current_phase: "analyze"
completed_phases: ["discover", "analyze"]
next_phase: "interview"
...
```
4. **Display status** (default mode — humanized phase labels):
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Config-Audit Session Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: 20250126_143022
Started: 2025-01-26 14:30:22
PHASE PROGRESS
──────────────
✓ Phase 1: Looking at your config files - 15 files found (current directory)
✓ Phase 2: Working out what to recommend - report generated
○ Phase 3: Asking what you'd like to focus on - not started (optional)
○ Phase 4: Putting together your action plan - not started
○ Phase 5: Making the changes - not started
NEXT ACTION
───────────
Run: /config-audit interview
Or: /config-audit plan (skip interview)
SESSION FILES
─────────────
Scope: ~/.claude/config-audit/sessions/20250126_143022/scope.yaml
Findings: ~/.claude/config-audit/sessions/20250126_143022/findings/
Report: ~/.claude/config-audit/sessions/20250126_143022/analysis-report.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
In `--raw` mode, replace the humanized phase labels with the verbatim machine field values (`Phase 1: discover`, `Phase 2: analyze`, etc.).
5. **If no session found**:
```
No active config-audit session found.
Start a new audit with:
/config-audit # Full audit with auto-scope
/config-audit discover # Discovery phase only
```
## Session Information
Display based on completed phases:
| Phase | Info to Display |
|-------|-----------------|
| scope | Scope type, paths to scan |
| discover | Files found count, issues count |
| analyze | Conflicts, duplicates, opportunities |
| interview | Preferences summary |
| plan | Actions count, risk level |
| implement | Success/fail counts, backup location |
## List All Sessions
With `all` flag:
```
/config-audit status all
```
Shows:
```
All config-audit sessions:
| Session | Phase | Created |
|---------|-------|---------|
| 20250126_143022 | analyze | 2025-01-26 14:30 |
| 20250125_091500 | complete | 2025-01-25 09:15 |
| 20250120_160000 | implement | 2025-01-20 16:00 |
```
## Resume Session
If multiple sessions exist:
```
/config-audit resume {session-id}
```
Sets that session as active and continues from last phase.

131
plugins/config-audit/commands/tokens.md
View file

@ -1,131 +0,0 @@
---
name: config-audit:tokens
description: Show ranked token hotspots and Opus 4.7 pattern findings — what's costing the most per turn and how to reduce it
argument-hint: "[path] [--global]"
allowed-tools: Read, Bash
model: sonnet
---
# Config-Audit: Token Hotspots
Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with Opus 4.7-specific recommendations for reducing prompt-cache misses, schema bloat, and deep import chains.
Complementary to `/config-audit whats-active`:
- **`whats-active`** = inventory view (what loads).
- **`tokens`** = action view (what to trim and why).
## UX Rules (MANDATORY — from `.claude/rules/ux-rules.md`)
1. **Never show raw JSON or stderr output.** Always use `--output-file` + `2>/dev/null`.
2. **Narrate before acting.** Tell the user what you're about to do.
3. **Read, don't dump.** Read the JSON file and render formatted tables.
4. **End with context-sensitive next steps.**
## Implementation
### Step 1: Parse `$ARGUMENTS`
Split `$ARGUMENTS` into a path and flags. Path is the first non-flag argument. Default to `.` (current working directory). Recognized flags:
- `--global` — also include the user-level `~/.claude/` cascade
- `--json` — emit raw JSON instead of rendered tables (power-user mode; bypasses the humanizer for byte-stable v5.0.0 output)
- `--raw` — pass-through to the scanner; produces v5.0.0 verbatim JSON (bypasses the humanizer). Use when piping into v5.0.0-baseline diff tooling.
- `--with-telemetry-recipe` — include `telemetry_recipe_path` in the JSON output, pointing to `knowledge/cache-telemetry-recipe.md`. Use this when you want to verify a structural fix actually improved cache hit rate (manual jq recipe, opt-in)
### Step 2: Run the CLI silently
Tell the user: **"Analysing token hotspots for `<path>`..."**
Default mode (no `--json`, no `--raw`) emits a humanized JSON envelope: each finding carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` in addition to the v5.0.0 fields. Pass `--raw` through verbatim if the user requested it.
```bash
TMPFILE="/tmp/config-audit-tokens-$$.json"
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/token-hotspots-cli.mjs <path> --output-file "$TMPFILE" [--global] $RAW_FLAG 2>/dev/null; echo $?
```
**Exit code handling:**
- `0` → continue
- `3` → tell user: "Couldn't analyse tokens. Check that the path exists and is a directory." Stop.
### Step 3: If `--json` was requested, cat the file and stop
```bash
cat "$TMPFILE"
```
Do NOT render tables in JSON mode.
### Step 4: Read JSON and render
Use the Read tool on `$TMPFILE`. Extract:
- `total_estimated_tokens` — top-line number
- `hotspots[]` — top 10 ranked sources
- `findings[]` — Opus 4.7 pattern findings (CA-TOK-001..003); each finding in default mode carries humanizer fields (`userImpactCategory`, `userActionLanguage`, `relevanceContext`) alongside the v5.0.0 fields
- `counts` — severity breakdown
Render as markdown. Group findings by `userImpactCategory` (e.g., "Wasted tokens" vs "Configuration mistake") rather than re-deriving severity prose; lead each line with `userActionLanguage` ("Fix this now", "Fix soon", "Optional cleanup", etc.) so the urgency phrasing stays consistent with the rest of the toolchain. The humanizer already replaced jargon-heavy `title`/`description`/`recommendation` strings with plain-language equivalents — render them verbatim.
```markdown
**Token hotspots for `<path>`** — ~{total_estimated_tokens} estimated tokens loaded per turn
### Top hotspots (ranked by estimated tokens)
| Rank | Source | Tokens | Recommendations |
|------|--------|--------|-----------------|
| {rank} | `{source}` | ~{estimated_tokens} | {recommendations joined as `· ` bullets} |
### Findings, grouped by impact
{Group findings[] by their userImpactCategory. Within each group, sort by userActionLanguage urgency (Fix this now → Fix soon → Fix when convenient → Optional cleanup → FYI), then render:}
- **{userActionLanguage}** — {title} ({id})
- {description}
- **Fix:** {recommendation}
- _{relevanceContext}_ when not "affects-everyone" (mention the scope so the user knows whether a fix touches shared config or just their machine)
### Severity summary
| Severity | Count |
|----------|-------|
| critical | {counts.critical} |
| high | {counts.high} |
| medium | {counts.medium} |
| low | {counts.low} |
| info | {counts.info} |
_Estimates assume ~4 chars/token (Claude ballpark). Real token count varies ±20%._
```
### Step 5: Cleanup and next steps
```bash
rm -f "$TMPFILE"
```
```markdown
### What's next
- **`/config-audit whats-active`** — full inventory of what loads (plugins, skills, MCP, hooks)
- **`/config-audit posture`** — overall health scorecard (Token Efficiency is the 8th area)
- **`/config-audit fix`** — auto-fix deterministic issues (where applicable)
- See `knowledge/opus-4.7-patterns.md` for the full pattern catalogue (CA-TOK-001 … 003)
- **Verify cache hit rate after a fix:** rerun with `--with-telemetry-recipe` to surface the path to `knowledge/cache-telemetry-recipe.md` — a copy-paste `jq` recipe that reads cache hit rate from your session transcripts. Opt-in. The TOK scanner is structural; this recipe is the runtime escape hatch.
```
## Scope and limits
- **Read-only.** Inspects config files; never writes.
- **Single repo.** Scans one path per invocation.
- **Structural only.** Hotspots are deterministic byte→token estimates from disk; runtime cache hit-rate is out of scope.
- **Heuristic estimates.** ~4 chars/token for markdown, ~3.5 for JSON. Real counts vary ±20%.
## Error handling
| Condition | Action |
|-----------|--------|
| Exit code 3 | Tell user path is invalid, suggest checking path exists |
| JSON parse fails | Tell user to re-run, mention as a bug to report |
| Empty hotspots | Suggest adding a CLAUDE.md or running `/config-audit feature-gap` first |

178
plugins/config-audit/commands/whats-active.md
View file

@ -1,178 +0,0 @@
---
name: config-audit:whats-active
description: Show which plugins, skills, MCP servers, hooks, and CLAUDE.md files are active for a repo — with token estimates
argument-hint: "[path] [--json] [--verbose] [--suggest-disables]"
allowed-tools: Read, Glob, Bash
model: sonnet
---
# Config-Audit: What's Active
Show a complete, read-only inventory of everything Claude Code loads for a given repo — plugins, skills, MCP servers, hooks, CLAUDE.md cascade — with source attribution and rough token estimates. Helps identify candidates for disabling without guessing.
## UX Rules (MANDATORY — from `.claude/rules/ux-rules.md`)
1. **Never show raw JSON or stderr output.** Always use `--output-file` + `2>/dev/null`.
2. **Narrate before acting.** Tell the user what you're about to do.
3. **Read, don't dump.** Read the JSON file and render formatted tables.
4. **End with context-sensitive next steps.**
## Implementation
### Step 1: Parse `$ARGUMENTS`
Split `$ARGUMENTS` into a path and flags. Path is the first non-flag argument. Default to `.` (current working directory). Recognized flags:
- `--json` — emit raw JSON instead of rendered tables (power-user mode)
- `--raw` — pass-through to the scanner; accepted for CLI surface consistency. `whats-active` is an inventory-only output (no findings prose), so `--raw` is a no-op here, but the flag is still threaded through for uniform behaviour across the toolchain.
- `--verbose` — include per-file byte/line detail
- `--suggest-disables` — append deterministic disable-candidates + LLM-judgment pass
### Step 2: Run the CLI silently
Tell the user: **"Reading active configuration for `<path>`..."**
```bash
TMPFILE="/tmp/ca-whats-active-$$.json"
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/whats-active.mjs <path> --output-file "$TMPFILE" [--verbose] [--suggest-disables] $RAW_FLAG 2>/dev/null; echo $?
```
**Exit code handling:**
- `0` → continue
- `3` → tell user: "Couldn't read configuration. Check that the path exists and is a directory." Stop.
### Step 3: If `--json` was requested, cat the file and stop
```bash
cat "$TMPFILE"
```
Do NOT render tables in JSON mode.
### Step 4: Read JSON and render
Use the Read tool on `$TMPFILE`. Extract:
- `meta.repoPath`, `meta.durationMs`, `meta.gitRoot`, `meta.projectKey`
- `totals.estimatedTokens.grandTotal` (and subtotals)
- `claudeMd.files[]` — render cascade table
- `plugins[]` — render plugin table
- `skills[]` — render skills table
- `mcpServers[]` — render MCP table (disabled shown italic)
- `hooks[]` — render hooks table
Render as markdown:
```markdown
**Active configuration for `<repoPath>`** — ~{grandTotal} tokens loaded at startup
{if gitRoot != repoPath: "Git root: `<gitRoot>`"}
{if projectKey: "`.claude.json` project slice: `<projectKey>`"}
### CLAUDE.md cascade ({claudeMd.files.length} files, ~{claudeMd.estimatedTokens} tokens)
| Scope | Path | Bytes | Lines |
|-------|------|-------|-------|
| {scope} | `<path>` | {bytes} | {lines} |
| ... | ... | ... | ... |
### Plugins ({plugins.length}, ~{plugins subtotal} tokens)
| Plugin | Version | Commands | Agents | Skills | Hooks | Rules | Tokens |
|--------|---------|----------|--------|--------|-------|-------|--------|
| {name} | {version} | {commands} | {agents} | {skills} | {hooks} | {rules} | ~{estimatedTokens} |
### Skills ({skills.length}, ~{skills subtotal} tokens)
| Skill | Source | Tokens |
|-------|--------|--------|
| {name} | {source}{if pluginName: ` (${pluginName})`} | ~{estimatedTokens} |
### MCP Servers ({mcpServers.length}, ~{mcpServers subtotal} tokens)
| Server | Source | Status | Command |
|--------|--------|--------|---------|
| {name} | {source} | {enabled ? "enabled" : "*disabled*"} | `{command}` |
### Hooks ({hooks.length}, ~{hooks subtotal} tokens)
| Event | Matcher | Source |
|-------|---------|--------|
| {event} | {matcher or "-"} | {source} |
### Settings cascade
| Scope | Path | Keys |
|-------|------|------|
| user | `<path>` | {keyCount} |
| project | `<path>` | {keyCount} |
| local | `<path>` | {keyCount or "(missing)"} |
### Totals
| Category | Items | Estimated tokens |
|----------|-------|------------------|
| CLAUDE.md | {claudeMdFiles} | ~{claudeMd} |
| Plugins | {plugins} | ~{plugins} |
| Skills | {skills} | ~{skills} |
| MCP servers | {mcpServers} | ~{mcpServers} |
| Hooks | {hooks} | ~{hooks} |
| **Grand total** | — | **~{grandTotal}** |
_Estimates assume ~4 chars/token (Claude ballpark). Real token count varies ±15%._
```
### Step 5: If `--verbose`, add per-file detail
For each CLAUDE.md file, skill, and plugin, include a nested "Details" list with bytes, lines, and full path.
### Step 6: If `--suggest-disables`, show candidates
First show deterministic signals from `suggestDisables.candidates[]`:
```markdown
### Disable candidates (deterministic)
| Kind | Name | Reason | Confidence |
|------|------|--------|------------|
| {kind} | {name} | {reason} | {confidence} |
```
Then run LLM judgment — check `git log --oneline -20` and project manifests (package.json/Cargo.toml/etc.) to propose up to **3** additional candidates. For each candidate, you MUST:
1. Name the specific redundancy
2. Name the signal the user should check to confirm
Do NOT suggest items you can't name concrete redundancy for. If you can't find 3 strong candidates, return fewer or zero.
### Step 7: Cleanup and next steps
```bash
rm -f "$TMPFILE"
```
```markdown
### What's next
- **`/config-audit posture`** — check configuration health (A-F grades per area)
- **`/config-audit feature-gap`** — context-aware recommendations for features you aren't using
- **Disable a plugin:** edit `~/.claude/settings.json` → `enabledPlugins` (remove the entry)
- **Disable an MCP server:** edit `~/.claude.json` → `projects.<path>.disabledMcpjsonServers`
- **Re-run with flags:** `/config-audit whats-active --verbose` (details) or `--suggest-disables` (pruning help)
```
## Scope and limits
- **Read-only.** This command never writes to configuration files — no mkdir, no edits, no deletes.
- **Single repo.** Scans one repo path per invocation. Cross-repo rollups are out of scope.
- **Ballpark token counts.** Estimates are deterministic but not calibrated against Claude's tokenizer. Use them to compare categories, not to predict exact billing.
- **No runtime queries.** We inspect config files only — we do not connect to MCP servers or invoke hooks.
## Error handling
| Condition | Action |
|-----------|--------|
| Exit code 3 | Tell user path is invalid, suggest checking path exists |
| JSON parse fails (shouldn't happen — CLI writes valid JSON) | Tell user to re-run, mention this as a bug to report |
| No plugins, no CLAUDE.md, no hooks found | Still render with zeroes; suggest `/config-audit feature-gap` for setup help |

52
plugins/config-audit/docs/humanizer.md
View file

@ -1,52 +0,0 @@
# Config-Audit — Plain-language output (v5.1.0)
Imported from `CLAUDE.md` via pointer.
Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings are decorated with three additive fields and may have title/description/recommendation replaced when a translation exists.
## Output modes
| Flag | Behavior |
|------|----------|
| (default, no flag) | Plain-language: humanizer applied, findings group by user-impact, titles lead with prose. Self-audit terminal render also humanized. |
| `--raw` | Byte-stable v5.0.0 verbatim — humanizer bypassed, technical IDs and severity-only labels. For tooling that scrapes stderr from v5.0.0. |
| `--json` | Unchanged from v5.0.0 — humanizer bypassed, byte-stable JSON envelope. Always preferred for programmatic consumption over `--raw`. |
| `--output-file <path>` | Writes raw v5.0.0-shape JSON (humanizer bypassed). Posture-specific. |
`--raw` is threaded through every CLI: `posture.mjs`, `scan-orchestrator.mjs`, `token-hotspots-cli.mjs`, `manifest.mjs`, `whats-active.mjs`, `fix-cli.mjs`, `drift-cli.mjs`, `self-audit.mjs`.
## Vocabularies
User-impact category (added to each finding as `userImpactCategory`, derived from scanner prefix):
| Label | Scanners |
|-------|----------|
| Configuration mistake | CML, SET, HKV, RUL, MCP, IMP, PLH |
| Conflict | CNF, COL |
| Wasted tokens | TOK, CPS |
| Dead config | DIS |
| Missed opportunity | GAP |
Action language (added to each finding as `userActionLanguage`, derived from severity):
| Severity | Phrase |
|----------|--------|
| critical | Fix this now |
| high | Fix soon |
| medium | Fix when convenient |
| low | Optional cleanup |
| info | FYI |
Relevance context (added to each finding as `relevanceContext`, computed from finding's file path):
| Value | When |
|-------|------|
| `test-fixture-no-impact` | Path contains `/tests/fixtures/` or `/test/fixtures/` |
| `affects-this-machine-only` | Basename matches `*.local.*` (e.g., `settings.local.json`) |
| `affects-everyone` | Default — assumed shared/committed config |
## Wave 5 lessons
- Posture's stderr scorecard is rendered prose-side and is not part of the JSON envelope; `humanized.areas[].titleHumanized` referenced by command templates lives only in the prose render.
- Posture's `--output-file` writes raw v5.0.0-shape JSON because `posture.mjs` does not call `humanizeEnvelope`. If session-files should later be humanized, posture needs its own humanize pass — out of v5.1.0 scope.
- The default-output snapshot at `tests/snapshots/default-output/posture.json` is frozen — change requires `UPDATE_SNAPSHOT=1` plus intent confirmation.

76
plugins/config-audit/docs/scanner-internals.md
View file

@ -1,76 +0,0 @@
# Config-Audit — Scanner internals
Detailed scanner inventory, lib modules, action engines, knowledge base. Imported from `CLAUDE.md` via pointer.
## Deterministic Scanners
Node.js scanners (zero external dependencies), run via `node scanners/scan-orchestrator.mjs <path>`.
Posture CLI: `node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]`.
Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress]`.
| Scanner | Prefix | Detects |
|---------|--------|---------|
| `claude-md-linter.mjs` | CML | Structure, length, sections, @imports, duplicates, TODOs |
| `settings-validator.mjs` | SET | Schema, unknown/deprecated keys, type mismatches, permissions |
| `hook-validator.mjs` | HKV | Format, script existence, event validity, timeouts |
| `rules-validator.mjs` | RUL | Glob matching, orphan rules, deprecated fields, unscoped rules |
| `mcp-config-validator.mjs` | MCP | Server types, trust levels, env vars, unknown fields |
| `import-resolver.mjs` | IMP | Broken @imports, circular refs, deep chains, tilde paths |
| `conflict-detector.mjs` | CNF | Settings conflicts, permission contradictions, hook duplicates |
| `feature-gap-scanner.mjs` | GAP | 25 feature checks across 4 tiers — shown as opportunities, not grades |
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (Opus 4.7 patterns) |
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window) |
| `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` AND `permissions.allow` — deny wins, allow entries are dead config |
| `collision-scanner.mjs` | COL | Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); `details.namespaces` payload |
## Scanner Lib (`scanners/lib/`)
| Module | Purpose |
|--------|---------|
| `severity.mjs` | Severity constants, risk scoring, verdict logic, `WEIGHTS` named export (v5 F3) |
| `output.mjs` | Finding objects (CA-XXX-NNN format), scanner results, envelope, optional `details` payload (v5 N6) |
| `file-discovery.mjs` | Config file discovery: single-path, multi-path (`discoverConfigFilesMulti`), full-machine (`discoverFullMachinePaths`) |
| `yaml-parser.mjs` | Frontmatter parsing, JSON parsing, @import/section extraction |
| `string-utils.mjs` | Line counting, truncation, similarity, key extraction |
| `scoring.mjs` | Severity-weighted `scoreByArea` (v5 F3), health scorecard, dedup-by-area (v5 N3), `scoringVersion: 'v5'` |
| `backup.mjs` | Backup creation, manifest parsing, checksum verification |
| `diff-engine.mjs` | Drift diffing: diffEnvelopes(), formatDiffReport() |
| `baseline.mjs` | Baseline save/load/list/delete for drift detection |
| `report-generator.mjs` | Unified markdown reports: posture, drift, plugin health |
| `suppression.mjs` | .config-audit-ignore parsing, finding suppression, audit trail |
| `active-config-reader.mjs` | Read-only inventory: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix match), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers() (with cache → package.json tool-count fallback), estimateTokens() (v5: `'mcp'` kind = 500 + toolCount × 200) |
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s AbortController timeout, exponential 429 backoff, key masking |
| `humanizer.mjs` | Plain-language output translator (v5.1.0): `humanizeFinding`, `humanizeFindings`, `humanizeEnvelope`, `computeRelevanceContext`. Pure functions; never mutate inputs. Adds `userImpactCategory`, `userActionLanguage`, `relevanceContext` fields and replaces title/description/recommendation when a translation exists. Bypassed by `--raw` and `--json` paths. |
| `humanizer-data.mjs` | TRANSLATIONS table for 13 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH). Three-step lookup: exact title → regex pattern → `_default` → fall through to original |
## Action Engines (`scanners/`)
| Module | Purpose |
|--------|---------|
| `fix-engine.mjs` | planFixes(), applyFixes(), verifyFixes() — 9 fix types |
| `rollback-engine.mjs` | listBackups(), restoreBackup(), deleteBackup() |
| `fix-cli.mjs` | CLI: `node fix-cli.mjs <path> [--apply] [--json] [--global]` |
| `drift-cli.mjs` | CLI: `node drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
| `whats-active.mjs` | CLI: `node whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory |
| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration |
| `manifest.mjs` | CLI: `node manifest.mjs <path> [--json]` — ranked system-prompt token-source table (v5 N2) |
## Standalone Scanner
| Module | Prefix | Purpose |
|--------|--------|---------|
| `plugin-health-scanner.mjs` | PLH | Plugin structure, frontmatter, cross-plugin conflicts (runs independently) |
| `self-audit.mjs` | — | Runs all scanners + plugin health on this plugin itself |
## Knowledge Base (`knowledge/`)
| File | Content |
|------|---------|
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
| `configuration-best-practices.md` | Per-layer best practices (v5: Opus 4.7 cache-stability guidance replaces Sonnet-era 200-line rule) |
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
| `hook-events-reference.md` | All 26 hook events with details |
| `feature-evolution.md` | Feature timeline for staleness detection |
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
| `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) |

186
plugins/config-audit/docs/v5-brief.md
View file

@ -1,186 +0,0 @@
# config-audit v5.0.0 — Brief
**Status:** Final input til implementation planning (avklart 2026-05-01)
**Opprettet:** 2026-04-19
**Utgangspunkt:** Kritisk review av v4.0.0 (Opus 4.7-perspektiv)
**Eier:** Kjell Tore Guttormsen
---
## Avklaringer fra konsultasjon 2026-05-01
Disse avklaringene OVERSTYRER tilsvarende felter i seksjonene under. Brief-reviewer
fant 9 inkonsistenser/uklarheter; brukerens beslutninger er kodifisert her.
### Scope-justeringer
- **N7 droppes fra v5.0.0.** Flyttes til "post-v5.0.0 stretch" (krever transcript-parsing
som motsier non-goals; data-tilgang må løses separat). SC-12 utgår.
- **M3 og N6 slås sammen til N6.** M3 fjernes fra should-fix-listen. N6 flyttes
fra `rc.1` til `beta.1`. Nytt finding-prefix: `CA-COL-001`.
- **N5 flyttes inn i v5.0.0** (fra v5.1.0) — beholdes som opt-in via `--accurate-tokens`.
Hvis `ANTHROPIC_API_KEY` mangler: warn + graceful fallback til zero-deps-heuristikk.
Bruker Anthropic `POST /v1/messages/count_tokens`-endepunktet.
### Korrigerte fil/linje-referanser
- **F7:** Severity-assignments er på 4 linjer (270, 299, 321, 338) i `token-hotspots.mjs`,
ikke linje 298. Alle fire patterns må rekalibreres mot tokens/tur.
- **F3:** Krever `import { riskScore } from './severity.mjs'` i `scoring.mjs`
(WEIGHTS bor i severity.mjs, ikke scoring.mjs).
- **F2:** Hovedbug er caller-side: `whats-active.mjs` og lignende sender `kind='item'`
for MCP-servere. Fix krever både ny `'mcp'`-kind i `estimateTokens` OG endrede caller-kall.
### Reviderte success criteria
- **SC-4:** Avhenger av `--check-readme`-flagg som F6 bygger. Sjekkbar først etter `alpha.2`.
- **SC-6 splittes i to:**
- **SC-6a:** `node scanners/manifest.mjs <path>` returnerer rangert kilde-tokens-liste
med korrekt struktur (uavhengig av tokenizer-presisjon).
- **SC-6b:** Med `--accurate-tokens`: byte-estimat innen ±5% av Anthropic count_tokens-API.
- **SC-10 erstattes:** I stedet for "≥600 tester totalt", krev: alle 543 v4.0.0-tester
fortsatt grønne + ≥1 fixture-backet test per ny scanner-funksjon (N1-N4, N6) og per
strukturell endring (F1, F2, F3, M1-M6).
- **SC-11 (ny):** `node scanners/token-hotspots-cli.mjs <path> --accurate-tokens` exit 0
+ output har `calibration.actual_tokens`-felt når API-key finnes; `calibration.skipped: "no-api-key"`
når ikke.
### Mindre justeringer
- **M1 (MCP tool-count):** Når `tools/list` ikke kan kjøres, fall back til:
npm-pakke → les `package.json` `tools`-felt; cached `tools/list`-respons; ellers flag
"tool count unknown" som finding (ikke skip).
- **N1 backward-compat:** Eksisterende `CA-TOK-*`-globs i `.config-audit-ignore` vil
suppressere det nye `CA-TOK-005`. Flagg eksplisitt i CHANGELOG som "kjent breaking
change for glob-suppressions".
### Revidert release-plan (autoritativ)
- **v5.0.0-alpha.1** — F1-F5 (TOK-rensing + estimateTokens-fix + scoring-severity-fix).
- **v5.0.0-alpha.2** — M1, M2, M4-M6 (M3 fjernet) + F6, F7.
- **v5.0.0-beta.1** — N1, N2, N3, N4, N6 (collision-scanner flyttet hit fra rc.1).
- **v5.0.0-rc.1** — M7, M8 + N5 (tokenizer-kalibrering).
- **v5.0.0** — Full suite grønn, README oppdatert, CHANGELOG, versjonssync, self-audit grade A.
- **v5.1.0+ (post-release)** — N7 (cache-hit-digest) når data-tilgang er løst.
---
## 1. Hvorfor v5.0.0
v4.0.0 markedsfører seg som "Opus 4.7-aware token optimization" (TOK-scanner, `/config-audit tokens`, Token Efficiency som 8. kvalitetsområde). Kritisk review viser at markedsføringen ikke holder:
- TOK-scanneren importerer `readActiveConfig` og bruker den eksplisitt ikke (`void readActiveConfig` i `scanners/token-hotspots.mjs:31`) — scanneren ser aldri på plugins, skills, MCP-servere eller CLAUDE.md-kaskade som aggregert token-kost.
- 4 TOK-mønstre dekker 29% av 14 identifiserte Opus 4.7-kostdrivere. De største sinkene (MCP tool-schema-eksplosjon, skill-description-bloat, CLAUDE.md-kaskade-sum) har null dekning.
- `estimateTokens` (`scanners/lib/active-config-reader.mjs:29-39`) flater MCP-servere og hooks til 15 tokens hver. En bruker med 5 MCP-servere får rapportert 75 tokens der virkeligheten er 10-20k.
- Area-score ignorerer severity helt (`scanners/lib/scoring.mjs:184`): 1 kritisk og 1 info gir identisk areascore.
- Pattern D (`detectSonnetEra`) motsier pluginens egen v3.0-policy om at minimalt korrekt oppsett = Grade A.
Resten av pluginen (8 strukturelle scannere, backup/rollback, suppression, plugin-health) fungerer og skal ikke rives ned. v5.0.0 er en token-economy-runde, ikke en totalombygging.
---
## 2. Mål for v5.0.0
**Primært:** Gjøre pluginens token-optimalisering reality-based. Etter v5.0.0 skal en bruker som kjører `/config-audit tokens` få konkret, kalibrert innsikt i hva som faktisk koster tokens i deres oppsett — MCP, skills, CLAUDE.md-kaskade, hooks inkludert.
**Sekundært:**
- Severity reflekterer estimert tokens/tur, ikke "hvor trivielt mønsteret er å detektere".
- Area-score tar hensyn til severity.
- README/CLAUDE.md-tall samsvarer med faktisk kode.
- Knowledge-basen reflekterer Opus 4.7-prioriteringer (cache-reuse og schema-disiplin), ikke Sonnet-æra-"tokens er billige".
**Ikke-mål:**
- Runtime-telemetri som kjernefunksjon (bare som opt-in recipe; krever transcript-parsing).
- Full tiktoken-bundling (opt-in `--accurate-tokens` via API er akseptabelt; default skal være zero-deps-heuristikk).
- Kryssrepo-benchmarking eller cloud-telemetri.
- Endringer i secret/credential-scanning-scope (fortsatt delegert til llm-security).
---
## 3. Scope
### Must-fix (7 kritiske)
| ID | Fil/linje | Hva |
|----|-----------|-----|
| F1 | `scanners/token-hotspots.mjs:31` | TOK må faktisk bruke `readActiveConfig` — ikke bare importere den |
| F2 | `scanners/lib/active-config-reader.mjs:29-39` | `estimateTokens` må type-differensiere MCP/hooks, ikke flat 15 tokens |
| F3 | `scanners/lib/scoring.mjs:184` | Area-score må vekte findings etter severity (gjenbruk `riskScore`-WEIGHTS) |
| F4 | `scanners/token-hotspots.mjs:202-229` | Fjern død `take`-logikk + fabrikerte hotspot-padding-entries |
| F5 | `scanners/token-hotspots.mjs:166-178` | Fjern pattern D (`detectSonnetEra`) eller flytt bak `--suggest-features` |
| F6 | `README.md:15,86,111,280,459-474` + `CLAUDE.md` | Legg til self-audit som verifiserer README-tall mot kode |
| F7 | `scanners/token-hotspots.mjs:298` | Severity må følge tokens/tur, ikke detektor-kompleksitet |
### Should-fix (8 mangler)
| ID | Hva |
|----|-----|
| M1 | MCP tool-count per server (parse manifest/`tools/list`, flagg > 15 tools) |
| M2 | Skill-description-lengde (frontmatter, ikke body) — flagg > 500 tegn |
| M3 | Plugin-skill/command-kollisjoner på tvers av aktive plugins |
| M4 | CLAUDE.md-kaskadens totalsum eksponert til TOK — flagg > 10k tokens |
| M5 | Hook-stdout/`additionalContext`-størrelse — flagg hooks som skriver > 50 linjer |
| M6 | `additionalDirectories` inn i `KNOWN_KEYS` + flagg > 2 entries |
| M7 | Cache-telemetri-recipe i knowledge/ + `/config-audit tokens --with-telemetry-recipe` |
| M8 | Knowledge-base-rensing: flytt Sonnet-æra-råd (adherence-basert 200-linjer-grense, kosmetiske tier-3-gaps) mot Opus 4.7-prioriteringer |
### Nye features (prioritert)
| # | Feature | Begrunnelse |
|---|---------|-------------|
| N1 | **MCP Tool-Schema Budget Scanner** — ny finding `CA-TOK-005` | Største token-sink; 10-20k/tur-potensial |
| N2 | **System-Prompt Manifest** — `/config-audit manifest`-kommando | Gjør alle andre TOK-findings forståelige |
| N3 | **Cache-Prefix Stability Analyzer** | Klassifiser segmenter som stable/volatile, ikke bare topp-30-linjer |
| N4 | **Disabled-Tools-Still-In-Schema Detector** | Vanlig mønster: denied tools lastes i schema likevel |
| N5 | **Live Tokenizer Calibration** (`--accurate-tokens`, opt-in) | Senker ±20%-usikkerheten til ±5% for brukere som godtar API-kall |
| N6 | **Cross-Plugin Skill/Command Collision Scanner** | Korrekthet ved heavy plugin use (relevant for KTG med 8 plugins) |
| N7 | **Cache-Hit-Rate Session Digest** — `/config-audit cache-digest` | Eneste sannhetskilde for om token-optimalisering faktisk virker |
---
## 4. Success criteria (testbare)
Etter v5.0.0 skal følgende kunne verifiseres:
1. **TOK bruker `readActiveConfig`.** `grep -n "readActiveConfig(" scanners/token-hotspots.mjs` må vise minst ett faktisk kall, ikke bare `void`.
2. **`estimateTokens` differensierer.** Unit test: MCP-server med 10 tools returnerer > 2000 estimerte tokens, ikke 15.
3. **Area-score reagerer på severity.** Unit test: 1 critical gir lavere score enn 5 lows, holder alt annet likt.
4. **README-tall matcher kode.** `node scanners/self-audit.mjs --check-readme` exit-code 0 — sjekker testfil-count, scanner-count, command-count, agent-count, hook-count, knowledge-count mot README-badges.
5. **MCP tool-count flagges.** Fixture med `.mcp.json` pluss `tools/list`-mock med 20 tools: TOK-scanner produserer `CA-TOK-005` finding.
6. **System-prompt-manifest fungerer.** `node scanners/manifest.mjs <path>` returnerer en rangert liste med kilde + tokens DESC, totalt innenfor ±20% av faktisk summert byte-estimat.
7. **Cache-prefix-analyse.** CLAUDE.md med volatile midt-seksjon genererer finding, ikke bare hvis volatilitet er i topp-30.
8. **Kollisjons-scanner.** Fixture med to plugins som begge eksponerer skill `review`: collision-finding produseres.
9. **Knowledge-basen oppdatert.** Grep etter "Keep under 200 lines" (Sonnet-æra-formulering) i `knowledge/configuration-best-practices.md` returnerer 0 — erstattet av cache-stabilitets-rettet guidance.
10. **Suite-helse.** `node --test 'tests/**/*.test.mjs'` ≥ 600 tester grønne (fra 543 i v4.0.0). Ny scanner-funksjonalitet har fixture-dekning.
---
## 5. Risikoer og avhengigheter
- **Tokenizer-kalibrering** — ingen zero-deps-tokenizer gir 100% nøyaktighet. Godta ±20% default; markér opt-in `--accurate-tokens` som eksperimentell.
- **MCP `tools/list`-tilgang** — krever kjørende MCP-server. Fallback: parse serverens manifest hvis det finnes, ellers bruk cache/estimat.
- **Schema-drift på `.claude.json`-format** — Anthropic kan endre formatet. `readClaudeJsonProjectSlice` har allerede longest-prefix-matching; nye felter må detekteres robust.
- **Breaking changes** — v5.0.0 er major bump. TOK-finding-IDer består (`CA-TOK-001..004`), nye legges til fra `CA-TOK-005`. Suppression-filer fra v4.x skal fortsatt fungere.
- **Self-audit-failure etter bump** — README-sjekken (F6) kan feile ved første push. Godta midlertidig rød self-audit under v5-arbeid; krav om grønn før release-tag.
---
## 6. Release-plan (high-level)
- **v5.0.0-alpha.1** — F1-F5 (TOK-scanner-rensing + estimateTokens-fix + scoring-severity-fix).
- **v5.0.0-alpha.2** — M1-M6 (manglende strukturelle sjekker) + F6-F7 (README-sync + severity-rekalibrering).
- **v5.0.0-beta.1** — N1-N4 (MCP budget, manifest, cache-prefix, disabled-in-schema).
- **v5.0.0-rc.1** — M7-M8 (knowledge-basens opus-4.7-rensing) + N6 (collision-scanner).
- **v5.0.0** — Full suite grønn, README oppdatert, CHANGELOG, versjonssync, selv-audit grade A.
- **v5.1.0** (post-release) — N5 (tokenizer) + N7 (cache-hit-digest) som opt-in features.
---
## 7. Referanser
- **Kritisk review (full):** inline i sesjonen 2026-04-19 (KTG-konsultasjon, Opus 4.7-perspektiv).
- **TOK-scanner:** `scanners/token-hotspots.mjs`
- **Token-heuristikk:** `scanners/lib/active-config-reader.mjs` + `knowledge/opus-4.7-patterns.md`
- **Area-scoring:** `scanners/lib/scoring.mjs`
- **Aktiv v4.0.0:** `README.md`, `CLAUDE.md`
- **Opus 4.7-dekningskartlegging:** reviewets "Mangler"-seksjon (14 punkter, 10 udekkede).

Some files were not shown because too many files have changed in this diff Show more