diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 00d014d..ef6d408 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -91,8 +91,8 @@ }, { "name": "claude-config-maintainer", - "version": "1.1.0", - "description": "CLAUDE.md optimization and maintenance for Claude Code projects", + "version": "1.2.0", + "description": "CLAUDE.md and settings.local.json optimization for Claude Code projects", "source": "./plugins/claude-config-maintainer", "author": { "name": "Leo Miranda", diff --git a/CHANGELOG.md b/CHANGELOG.md index 664b496..6030702 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +#### claude-config-maintainer v1.2.0 - Settings Audit Feature + +New commands for auditing and optimizing `settings.local.json` permission configurations: + +- **`/config-audit-settings`** — Audit `settings.local.json` permissions with 100-point scoring across redundancy, coverage, safety alignment, and profile fit +- **`/config-optimize-settings`** — Apply permission optimizations with dry-run, named profiles (`conservative`, `reviewed`, `autonomous`), and consolidation modes +- **`/config-permissions-map`** — Generate Mermaid diagram of review layer coverage and permission gaps +- **`skills/settings-optimization.md`** — Comprehensive skill for permission pattern analysis, consolidation rules, review-layer-aware recommendations, and named profiles + +**Key Features:** +- Settings Efficiency Score (100 points) alongside existing CLAUDE.md score +- Review layer verification — agent reads `hooks/hooks.json` from installed plugins before recommending auto-allow patterns +- Three named profiles: `conservative` (prompts for most writes), `reviewed` (for projects with ≥2 review layers), `autonomous` (sandboxed environments) +- Pattern consolidation detection: duplicates, subsets, merge candidates, stale entries, conflicts + #### Projman Hardening Sprint Targeted improvements to safety gates, command structure, lifecycle tracking, and cross-plugin contracts. diff --git a/docs/COMMANDS-CHEATSHEET.md b/docs/COMMANDS-CHEATSHEET.md index 1f0e4a3..4a892f1 100644 --- a/docs/COMMANDS-CHEATSHEET.md +++ b/docs/COMMANDS-CHEATSHEET.md @@ -54,6 +54,9 @@ Quick reference for all commands in the Leo Claude Marketplace. | **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project | | **claude-config-maintainer** | `/config-diff` | | X | Track CLAUDE.md changes over time with behavioral impact | | **claude-config-maintainer** | `/config-lint` | | X | Lint CLAUDE.md for anti-patterns and best practices | +| **claude-config-maintainer** | `/config-audit-settings` | | X | Audit settings.local.json permissions (100-point score) | +| **claude-config-maintainer** | `/config-optimize-settings` | | X | Optimize permissions (profiles, consolidation, dry-run) | +| **claude-config-maintainer** | `/config-permissions-map` | | X | Visual review layer + permission coverage map | | **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server | | **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites | | **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) | diff --git a/plugins/claude-config-maintainer/.claude-plugin/plugin.json b/plugins/claude-config-maintainer/.claude-plugin/plugin.json index 1365710..47899a2 100644 --- a/plugins/claude-config-maintainer/.claude-plugin/plugin.json +++ b/plugins/claude-config-maintainer/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "claude-config-maintainer", - "version": "1.0.0", - "description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects", + "version": "1.2.0", + "description": "Maintains and optimizes CLAUDE.md and settings.local.json configuration files for Claude Code projects", "author": { "name": "Leo Miranda", "email": "leobmiranda@gmail.com" @@ -14,7 +14,9 @@ "configuration", "optimization", "claude-md", - "developer-tools" + "developer-tools", + "settings", + "permissions" ], "commands": ["./commands/"] } diff --git a/plugins/claude-config-maintainer/agents/maintainer.md b/plugins/claude-config-maintainer/agents/maintainer.md index 71ddfa9..d07470e 100644 --- a/plugins/claude-config-maintainer/agents/maintainer.md +++ b/plugins/claude-config-maintainer/agents/maintainer.md @@ -114,7 +114,54 @@ Report plugin coverage percentage and offer to add missing integrations: - Display the integration content that would be added - Ask user for confirmation before modifying CLAUDE.md -### 2. Optimize CLAUDE.md Structure +### 2. Audit Settings Files + +When auditing settings files, perform: + +#### A. Permission Analysis + +Read `.claude/settings.local.json` (primary) and check `.claude/settings.json` and `~/.claude.json` project entries (secondary). + +Evaluate using `skills/settings-optimization.md`: + +**Redundancy:** +- Duplicate entries in allow/deny arrays +- Subset patterns covered by broader patterns +- Patterns that could be merged + +**Coverage:** +- Common safe tools missing from allow list +- MCP server tools not covered +- Directory scopes with no matching permission + +**Safety Alignment:** +- Deny rules cover secrets and destructive commands +- Allow rules don't bypass active review layers +- No overly broad patterns without justification + +**Profile Fit:** +- Compare against recommended profile for the project's review architecture +- Identify specific additions/removals to reach target profile + +#### B. Review Layer Verification + +Before recommending auto-allow patterns, verify active review layers: + +1. Read `plugins/*/hooks/hooks.json` for each installed plugin +2. Map hook types (PreToolUse, PostToolUse) to tool matchers (Write, Edit, Bash) +3. Confirm plugins are listed in `.claude-plugin/marketplace.json` +4. Only recommend auto-allow for scopes covered by ≥2 verified review layers + +#### C. Settings Efficiency Score (100 points) + +| Category | Points | +|----------|--------| +| Redundancy | 25 | +| Coverage | 25 | +| Safety Alignment | 25 | +| Profile Fit | 25 | + +### 3. Optimize CLAUDE.md Structure **Recommended Structure:** @@ -149,7 +196,7 @@ Common issues and solutions. - Use headers that scan easily - Include examples where they add clarity -### 3. Apply Best Practices +### 4. Apply Best Practices **DO:** - Use clear, direct language @@ -166,7 +213,7 @@ Common issues and solutions. - Add generic advice that applies to all projects - Use emojis unless project requires them -### 4. Generate Improvement Reports +### 5. Generate Improvement Reports After analyzing a CLAUDE.md, provide: @@ -202,7 +249,7 @@ Suggested Actions: Would you like me to implement these improvements? ``` -### 5. Insert Plugin Integrations +### 6. Insert Plugin Integrations When adding plugin integration content to CLAUDE.md: @@ -237,7 +284,7 @@ Add this integration to CLAUDE.md? - Allow users to skip specific plugins they don't want documented - Preserve existing CLAUDE.md structure and content -### 6. Create New CLAUDE.md Files +### 7. Create New CLAUDE.md Files When creating a new CLAUDE.md: diff --git a/plugins/claude-config-maintainer/claude-md-integration.md b/plugins/claude-config-maintainer/claude-md-integration.md index 2e2b979..9d97593 100644 --- a/plugins/claude-config-maintainer/claude-md-integration.md +++ b/plugins/claude-config-maintainer/claude-md-integration.md @@ -1,6 +1,6 @@ ## CLAUDE.md Maintenance (claude-config-maintainer) -This project uses the **claude-config-maintainer** plugin to analyze and optimize CLAUDE.md configuration files. +This project uses the **claude-config-maintainer** plugin to analyze and optimize CLAUDE.md and settings.local.json configuration files. ### Available Commands @@ -9,8 +9,13 @@ This project uses the **claude-config-maintainer** plugin to analyze and optimiz | `/config-analyze` | Analyze CLAUDE.md for optimization opportunities with 100-point scoring | | `/config-optimize` | Automatically optimize CLAUDE.md structure and content | | `/config-init` | Initialize a new CLAUDE.md file for a project | +| `/config-diff` | Track CLAUDE.md changes over time with behavioral impact analysis | +| `/config-lint` | Lint CLAUDE.md for anti-patterns and best practices (31 rules) | +| `/config-audit-settings` | Audit settings.local.json permissions with 100-point scoring | +| `/config-optimize-settings` | Optimize permission patterns and apply named profiles | +| `/config-permissions-map` | Visual map of review layers and permission coverage | -### Scoring System +### CLAUDE.md Scoring System The analysis uses a 100-point scoring system across four categories: @@ -21,10 +26,31 @@ The analysis uses a 100-point scoring system across four categories: | Completeness | 25 | Overview, quick start, critical rules, workflows | | Conciseness | 25 | Efficiency, no repetition, appropriate length | +### Settings Scoring System + +The settings audit uses a 100-point scoring system across four categories: + +| Category | Points | What It Measures | +|----------|--------|------------------| +| Redundancy | 25 | No duplicates, no subset patterns, efficient rules | +| Coverage | 25 | Common tools allowed, MCP servers covered | +| Safety Alignment | 25 | Deny rules for secrets/destructive ops, review layers verified | +| Profile Fit | 25 | Alignment with recommended profile for review layer count | + +### Permission Profiles + +| Profile | Use Case | +|---------|----------| +| `conservative` | New users, minimal auto-allow, prompts for most writes | +| `reviewed` | Projects with 2+ review layers (code-sentinel, doc-guardian, PR review) | +| `autonomous` | Trusted CI/sandboxed environments only | + ### Usage Guidelines - Run `/config-analyze` periodically to assess CLAUDE.md quality +- Run `/config-audit-settings` to check permission efficiency - Target a score of **70+/100** for effective Claude Code operation - Address HIGH priority issues first when optimizing - Use `/config-init` when setting up new projects to start with best practices +- Use `/config-permissions-map` to visualize review layer coverage - Re-analyze after making changes to verify improvements diff --git a/plugins/claude-config-maintainer/commands/config-audit-settings.md b/plugins/claude-config-maintainer/commands/config-audit-settings.md new file mode 100644 index 0000000..346249a --- /dev/null +++ b/plugins/claude-config-maintainer/commands/config-audit-settings.md @@ -0,0 +1,204 @@ +--- +name: config-audit-settings +description: Audit settings.local.json for permission optimization opportunities +--- + +# /config-audit-settings + +Audit Claude Code `settings.local.json` permissions with 100-point scoring across redundancy, coverage, safety alignment, and profile fit. + +## Skills to Load + +Before executing, load: +- `skills/visual-header.md` +- `skills/settings-optimization.md` + +## Visual Output + +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Settings Audit | ++-----------------------------------------------------------------+ +``` + +## Usage + +``` +/config-audit-settings # Full audit with recommendations +/config-audit-settings --diagram # Include Mermaid diagram of review layer coverage +``` + +## Workflow + +### Step 1: Locate Settings Files + +Search in order: +1. `.claude/settings.local.json` (primary target) +2. `.claude/settings.json` (shared config) +3. `~/.claude.json` project entry (legacy) + +Report which format is in use. + +### Step 2: Parse Permission Arrays + +Extract and analyze: +- `permissions.allow` array +- `permissions.deny` array +- `permissions.ask` array (if present) +- Legacy `allowedTools` array (if legacy format) + +### Step 3: Run Pattern Consolidation Analysis + +Using `settings-optimization.md` Section 3, detect: + +| Check | Description | +|-------|-------------| +| Duplicates | Exact same pattern appearing multiple times | +| Subsets | Narrower patterns covered by broader ones | +| Merge candidates | 4+ similar patterns that could be consolidated | +| Overly broad | Unscoped tool permissions (e.g., `Bash` without pattern) | +| Stale entries | Patterns referencing non-existent paths | +| Conflicts | Same pattern in both allow and deny | + +### Step 4: Detect Active Marketplace Hooks + +Read `plugins/*/hooks/hooks.json` files: + +```bash +# Check each plugin's hooks +plugins/code-sentinel/hooks/hooks.json # PreToolUse security +plugins/doc-guardian/hooks/hooks.json # PostToolUse drift detection +plugins/project-hygiene/hooks/hooks.json # PostToolUse cleanup +plugins/data-platform/hooks/hooks.json # PostToolUse schema diff +plugins/contract-validator/hooks/hooks.json # Plugin validation +``` + +Parse each to identify: +- Hook event type (PreToolUse, PostToolUse) +- Tool matchers (Write, Edit, MultiEdit, Bash) +- Whether hook is command type (reliable) or prompt type (unreliable) + +### Step 5: Map Review Layers to Directory Scopes + +For each directory scope in `settings-optimization.md` Section 4: +1. Count how many review layers are verified active +2. Determine if auto-allow is justified (≥2 layers required) +3. Note any scopes that lack coverage + +### Step 6: Compare Against Recommended Profile + +Based on review layer count: +- 0-1 layers: Recommend `conservative` profile +- 2+ layers: Recommend `reviewed` profile +- CI/sandboxed: May recommend `autonomous` profile + +Calculate profile fit percentage. + +### Step 7: Generate Scored Report + +Calculate scores using `settings-optimization.md` Section 6. + +## Output Format + +``` +Settings Efficiency Score: XX/100 + Redundancy: XX/25 + Coverage: XX/25 + Safety Alignment: XX/25 + Profile Fit: XX/25 + +Current Profile: [closest match or "custom"] +Recommended Profile: [target based on review layers] + +Issues Found: + 🔴 CRITICAL: [description] + 🟠 HIGH: [description] + 🟡 MEDIUM: [description] + 🔵 LOW: [description] + +Active Review Layers Detected: + ✓ code-sentinel (PreToolUse: Write|Edit|MultiEdit) + ✓ doc-guardian (PostToolUse: Write|Edit|MultiEdit) + ✓ project-hygiene (PostToolUse: Write|Edit) + ✗ data-platform schema-diff (not detected) + +Recommendations: + 1. [specific action with pattern] + 2. [specific action with pattern] + ... + +Follow-Up Actions: + 1. Run /config-optimize-settings to apply recommendations + 2. Run /config-optimize-settings --dry-run to preview first + 3. Run /config-optimize-settings --profile=reviewed to apply profile +``` + +## Diagram Output (--diagram flag) + +When `--diagram` is specified, generate a Mermaid flowchart showing: + +**Before generating:** Read `/mnt/skills/user/mermaid-diagrams/SKILL.md` for diagram requirements. + +**Diagram structure:** +- Left column: File operation types (Write, Edit, Bash) +- Middle: Review layers that intercept each operation +- Right column: Current permission status (auto-allowed, prompted, denied) + +**Color coding:** +- PreToolUse hooks: Blue +- PostToolUse hooks: Green +- Sprint Approval: Amber +- PR Review: Purple + +Example structure: +```mermaid +flowchart LR + subgraph Operations + W[Write] + E[Edit] + B[Bash] + end + + subgraph Review Layers + CS[code-sentinel] + DG[doc-guardian] + PR[pr-review] + end + + subgraph Permission + A[Auto-allowed] + P[Prompted] + D[Denied] + end + + W --> CS + W --> DG + E --> CS + E --> DG + CS --> A + DG --> A + B --> P + + classDef preHook fill:#e3f2fd + classDef postHook fill:#e8f5e9 + classDef prReview fill:#f3e5f5 + class CS preHook + class DG postHook + class PR prReview +``` + +## Issue Severity Levels + +| Severity | Icon | Examples | +|----------|------|----------| +| CRITICAL | 🔴 | Unscoped `Bash` in allow, missing deny for secrets | +| HIGH | 🟠 | Overly broad patterns, missing MCP coverage | +| MEDIUM | 🟡 | Subset redundancy, merge candidates | +| LOW | 🔵 | Exact duplicates, minor optimizations | + +## DO NOT + +- Modify any files (this is audit only) +- Recommend `autonomous` profile unless explicitly sandboxed environment +- Recommend auto-allow for scopes with <2 verified review layers +- Skip hook verification before making recommendations diff --git a/plugins/claude-config-maintainer/commands/config-optimize-settings.md b/plugins/claude-config-maintainer/commands/config-optimize-settings.md new file mode 100644 index 0000000..b8ccd7e --- /dev/null +++ b/plugins/claude-config-maintainer/commands/config-optimize-settings.md @@ -0,0 +1,243 @@ +--- +name: config-optimize-settings +description: Optimize settings.local.json permissions based on audit recommendations +--- + +# /config-optimize-settings + +Optimize Claude Code `settings.local.json` permission patterns and apply named profiles. + +## Skills to Load + +Before executing, load: +- `skills/visual-header.md` +- `skills/settings-optimization.md` +- `skills/pre-change-protocol.md` + +## Visual Output + +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Settings Optimization | ++-----------------------------------------------------------------+ +``` + +## Usage + +``` +/config-optimize-settings # Apply audit recommendations +/config-optimize-settings --dry-run # Preview only, no changes +/config-optimize-settings --profile=reviewed # Apply named profile +/config-optimize-settings --consolidate-only # Only merge/dedupe, no new rules +``` + +## Options + +| Option | Description | +|--------|-------------| +| `--dry-run` | Preview changes without applying | +| `--profile=NAME` | Apply named profile (`conservative`, `reviewed`, `autonomous`) | +| `--consolidate-only` | Only deduplicate and merge patterns, don't add new rules | +| `--no-backup` | Skip backup (not recommended) | + +## Workflow + +### Step 1: Run Audit Analysis + +Execute the same analysis as `/config-audit-settings`: +1. Locate settings file +2. Parse permission arrays +3. Detect issues (duplicates, subsets, merge candidates, etc.) +4. Verify active review layers +5. Calculate current score + +### Step 2: Generate Optimization Plan + +Based on audit results, create a change plan: + +**For `--consolidate-only`:** +- Remove exact duplicates +- Remove subset patterns covered by broader patterns +- Merge similar patterns (4+ threshold) +- Remove stale patterns for non-existent paths +- Remove conflicting allow entries that are already denied + +**For `--profile=NAME`:** +- Calculate diff between current permissions and target profile +- Show additions and removals +- Preserve any custom deny rules not in profile + +**For default (full optimization):** +- Apply all consolidation changes +- Add recommended patterns based on verified review layers +- Suggest profile alignment if appropriate + +### Step 3: Show Before/After Preview + +**MANDATORY:** Always show preview before applying changes. + +``` +Current Settings: + allow: [12 patterns] + deny: [4 patterns] + +Proposed Changes: + + REMOVE from allow (redundant): + - Write(plugins/projman/*) [covered by Write(plugins/**)] + - Write(plugins/git-flow/*) [covered by Write(plugins/**)] + - Bash(git status) [covered by Bash(git *)] + + ADD to allow (recommended): + + Bash(npm *) [2 review layers active] + + Bash(pytest *) [2 review layers active] + + ADD to deny (security): + + Bash(curl * | bash*) [missing safety rule] + +After Optimization: + allow: [10 patterns] + deny: [5 patterns] + +Score Impact: 67/100 → 85/100 (+18 points) +``` + +### Step 4: Request User Approval + +Ask for confirmation before proceeding: + +``` +Apply these changes to .claude/settings.local.json? + [1] Yes, apply changes + [2] No, cancel + [3] Apply partial (select which changes) +``` + +### Step 5: Create Backup + +**Before any write operation:** + +```bash +# Backup location +.claude/backups/settings.local.json.{YYYYMMDD-HHMMSS} +``` + +Create the `.claude/backups/` directory if it doesn't exist. + +### Step 6: Apply Changes + +Write the optimized `settings.local.json` file. + +### Step 7: Verify + +Re-read the file and re-calculate the score to confirm improvement. + +``` +Optimization Complete! + +Backup saved: .claude/backups/settings.local.json.20260202-143022 + +Settings Efficiency Score: 85/100 (+18 from 67) + Redundancy: 25/25 (+8) + Coverage: 22/25 (+5) + Safety Alignment: 23/25 (+3) + Profile Fit: 15/25 (+2) + +Changes applied: + - Removed 3 redundant patterns + - Added 2 recommended patterns + - Added 1 safety deny rule +``` + +## Profile Application + +When using `--profile=NAME`: + +### `conservative` +``` +Switching to conservative profile... + +This profile: + - Allows: Read, Glob, Grep, LS, basic Bash commands + - Allows: Write/Edit only for docs/ + - Denies: .env*, secrets/, rm -rf, sudo + +All other Write/Edit operations will prompt for approval. +``` + +### `reviewed` +``` +Switching to reviewed profile... + +Prerequisites verified: + ✓ code-sentinel hook active (PreToolUse) + ✓ doc-guardian hook active (PostToolUse) + ✓ 2+ review layers detected + +This profile: + - Allows: All file operations (Edit, Write, MultiEdit) + - Allows: Scoped Bash commands (git, npm, python, etc.) + - Denies: .env*, secrets/, rm -rf, sudo, curl|bash +``` + +### `autonomous` +``` +⚠️ WARNING: Autonomous profile requested + +This profile allows unscoped Bash execution. +Only use in fully sandboxed environments (CI, containers). + +Confirm this is a sandboxed environment? + [1] Yes, this is sandboxed - apply autonomous profile + [2] No, cancel +``` + +## Safety Rules + +1. **ALWAYS backup before writing** (unless `--no-backup`) +2. **NEVER remove deny rules without explicit confirmation** +3. **NEVER add unscoped `Bash` to allow** — always use scoped patterns +4. **Preview is MANDATORY** before applying changes +5. **Verify review layers** before recommending broad permissions + +## Output Format + +### Dry Run Output + +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Settings Optimization | ++-----------------------------------------------------------------+ + +DRY RUN - No changes will be made + +[... preview content ...] + +To apply these changes, run: + /config-optimize-settings +``` + +### Applied Output + +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Settings Optimization | ++-----------------------------------------------------------------+ + +Optimization Applied Successfully + +Backup: .claude/backups/settings.local.json.20260202-143022 + +[... summary of changes ...] + +Score: 67/100 → 85/100 +``` + +## DO NOT + +- Apply changes without showing preview +- Remove deny rules silently +- Add unscoped `Bash` permission +- Skip backup without explicit `--no-backup` flag +- Apply `autonomous` profile without sandbox confirmation +- Recommend broad permissions without verifying review layers diff --git a/plugins/claude-config-maintainer/commands/config-permissions-map.md b/plugins/claude-config-maintainer/commands/config-permissions-map.md new file mode 100644 index 0000000..782a5e7 --- /dev/null +++ b/plugins/claude-config-maintainer/commands/config-permissions-map.md @@ -0,0 +1,256 @@ +--- +name: config-permissions-map +description: Generate visual map of review layers and permission coverage +--- + +# /config-permissions-map + +Generate a Mermaid diagram showing the relationship between file operations, review layers, and permission status. + +## Skills to Load + +Before executing, load: +- `skills/visual-header.md` +- `skills/settings-optimization.md` + +Also read: `/mnt/skills/user/mermaid-diagrams/SKILL.md` (for diagram requirements) + +## Visual Output + +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Permissions Map | ++-----------------------------------------------------------------+ +``` + +## Usage + +``` +/config-permissions-map # Generate and display diagram +/config-permissions-map --save # Save diagram to .mermaid file +``` + +## Workflow + +### Step 1: Detect Active Hooks + +Read all plugin hooks from the marketplace: + +``` +plugins/code-sentinel/hooks/hooks.json +plugins/doc-guardian/hooks/hooks.json +plugins/project-hygiene/hooks/hooks.json +plugins/data-platform/hooks/hooks.json +plugins/contract-validator/hooks/hooks.json +plugins/cmdb-assistant/hooks/hooks.json +``` + +For each hook, extract: +- Event type (PreToolUse, PostToolUse, SessionStart, etc.) +- Tool matchers (Write, Edit, MultiEdit, Bash patterns) +- Hook command/script + +### Step 2: Map Hooks to File Scopes + +Create a mapping of which review layers cover which operations: + +| Operation | PreToolUse Hooks | PostToolUse Hooks | Other Gates | +|-----------|------------------|-------------------|-------------| +| Write | code-sentinel | doc-guardian, project-hygiene | PR review | +| Edit | code-sentinel | doc-guardian, project-hygiene | PR review | +| MultiEdit | code-sentinel | doc-guardian | PR review | +| Bash(git *) | git-flow | — | — | + +### Step 3: Read Current Permissions + +Load `.claude/settings.local.json` and parse: +- `allow` array → auto-allowed operations +- `deny` array → blocked operations +- `ask` array → always-prompted operations + +### Step 4: Generate Mermaid Flowchart + +**Diagram requirements (from mermaid-diagrams skill):** +- Use `classDef` for styling +- Maximum 3 colors (blue, green, amber/purple) +- Semantic arrow labels +- Left-to-right flow + +**Structure:** + +```mermaid +flowchart LR + subgraph ops[File Operations] + direction TB + W[Write] + E[Edit] + ME[MultiEdit] + BG[Bash git] + BN[Bash npm] + BO[Bash other] + end + + subgraph pre[PreToolUse Hooks] + direction TB + CS[code-sentinel
Security Scan] + GF[git-flow
Branch Check] + end + + subgraph post[PostToolUse Hooks] + direction TB + DG[doc-guardian
Drift Detection] + PH[project-hygiene
Cleanup] + DP[data-platform
Schema Diff] + end + + subgraph perm[Permission Status] + direction TB + AA[Auto-Allowed] + PR[Prompted] + DN[Denied] + end + + W -->|intercepted| CS + W -->|tracked| DG + E -->|intercepted| CS + E -->|tracked| DG + BG -->|checked| GF + + CS -->|passed| AA + DG -->|logged| AA + GF -->|valid| AA + BO -->|no hook| PR + + classDef preHook fill:#e3f2fd,stroke:#1976d2 + classDef postHook fill:#e8f5e9,stroke:#388e3c + classDef sprint fill:#fff3e0,stroke:#f57c00 + classDef prReview fill:#f3e5f5,stroke:#7b1fa2 + classDef allowed fill:#c8e6c9,stroke:#2e7d32 + classDef prompted fill:#fff9c4,stroke:#f9a825 + classDef denied fill:#ffcdd2,stroke:#c62828 + + class CS,GF preHook + class DG,PH,DP postHook + class AA allowed + class PR prompted + class DN denied +``` + +### Step 5: Generate Coverage Summary Table + +``` +Review Layer Coverage Summary +============================= + +| Directory Scope | Layers | Status | Recommendation | +|--------------------------|--------|-----------------|----------------| +| plugins/*/commands/*.md | 3 | ✓ Auto-allowed | — | +| plugins/*/skills/*.md | 2 | ✓ Auto-allowed | — | +| mcp-servers/**/*.py | 3 | ✓ Auto-allowed | — | +| docs/** | 2 | ✓ Auto-allowed | — | +| scripts/*.sh | 2 | ⚠ Prompted | Consider auto-allow | +| .env* | 0 | ✗ Denied | Correct - secrets | +| Root directory | 1 | ⚠ Prompted | Keep prompted | + +Legend: + ✓ = Covered by ≥2 review layers, auto-allowed + ⚠ = Fewer than 2 layers or not allowed + ✗ = Explicitly denied +``` + +### Step 6: Identify Gaps + +Report any gaps in coverage: + +``` +Coverage Gaps Detected: + 1. Bash(npm *) — not in allow list, but npm operations are common + → 2 review layers active, could be auto-allowed + + 2. mcp__data-platform__* — MCP server configured but tools not allowed + → Add to allow list to avoid prompts + + 3. scripts/*.sh — 2 review layers but still prompted + → Consider adding Write(scripts/**) to allow +``` + +### Step 7: Output Diagram + +Display the Mermaid diagram inline. + +If `--save` flag is used: +- Save to `.claude/permissions-map.mermaid` +- Report the file path + +## Output Format + +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Permissions Map | ++-----------------------------------------------------------------+ + +Review Layer Status +=================== + +PreToolUse Hooks (intercept before operation): + ✓ code-sentinel — Write, Edit, MultiEdit + ✓ git-flow — Bash(git checkout *), Bash(git commit *) + +PostToolUse Hooks (track after operation): + ✓ doc-guardian — Write, Edit, MultiEdit + ✓ project-hygiene — Write, Edit + ✗ data-platform — not detected + +Other Review Gates: + ✓ Sprint Approval (projman milestone workflow) + ✓ PR Review (pr-review multi-agent) + +Permissions Flow Diagram +======================== + +```mermaid +[diagram here] +``` + +Coverage Summary +================ + +[table here] + +Gaps & Recommendations +====================== + +[gaps list here] +``` + +## File Output (--save flag) + +When `--save` is specified: + +``` +Diagram saved to: .claude/permissions-map.mermaid + +To view: + - Open in VS Code with Mermaid extension + - Paste into https://mermaid.live + - Include in documentation with ```mermaid code fence +``` + +## Color Scheme + +| Element | Color | Hex | +|---------|-------|-----| +| PreToolUse hooks | Blue | #e3f2fd | +| PostToolUse hooks | Green | #e8f5e9 | +| Sprint/Planning gates | Amber | #fff3e0 | +| PR Review | Purple | #f3e5f5 | +| Auto-allowed | Light green | #c8e6c9 | +| Prompted | Light yellow | #fff9c4 | +| Denied | Light red | #ffcdd2 | + +## DO NOT + +- Generate diagrams without reading the mermaid-diagrams skill +- Use more than 3 primary colors in the diagram +- Skip the coverage summary table +- Fail to identify coverage gaps diff --git a/plugins/claude-config-maintainer/skills/settings-optimization.md b/plugins/claude-config-maintainer/skills/settings-optimization.md new file mode 100644 index 0000000..41144ee --- /dev/null +++ b/plugins/claude-config-maintainer/skills/settings-optimization.md @@ -0,0 +1,377 @@ +# Settings Optimization Skill + +This skill provides comprehensive knowledge for auditing and optimizing Claude Code `settings.local.json` permission configurations. + +--- + +## Section 1: Settings File Locations & Format + +Claude Code uses two configuration formats for permissions: + +### Newer Format (Recommended) + +**Primary target:** `.claude/settings.local.json` (project-local, gitignored) + +**Secondary locations:** +- `.claude/settings.json` (shared, committed) +- `~/.claude.json` (legacy global config) + +```json +{ + "permissions": { + "allow": ["Edit", "Write(plugins/**)", "Bash(git *)"], + "deny": ["Read(.env*)", "Bash(rm *)"], + "ask": ["Bash(pip install *)"] + } +} +``` + +**Field meanings:** +- `allow`: Operations auto-approved without prompting +- `deny`: Operations blocked entirely +- `ask`: Operations that always prompt (overrides allow) + +### Legacy Format + +Found in `~/.claude.json` with per-project entries: + +```json +{ + "projects": { + "/path/to/project": { + "allowedTools": ["Read", "Write", "Bash(git *)"] + } + } +} +``` + +**Detection strategy:** +1. Check `.claude/settings.local.json` first (primary) +2. Check `.claude/settings.json` (shared) +3. Check `~/.claude.json` for project entry (legacy) +4. Report which format is in use + +--- + +## Section 2: Permission Rule Syntax Reference + +| Pattern | Meaning | +|---------|---------| +| `Tool` or `Tool(*)` | Allow all uses of that tool | +| `Bash(npm run build)` | Exact command match | +| `Bash(npm run test *)` | Prefix match (space+asterisk = word boundary) | +| `Bash(npm*)` | Prefix match without word boundary | +| `Write(plugins/**)` | Glob — all files recursively under `plugins/` | +| `Write(plugins/projman/*)` | Glob — direct children only | +| `Read(.env*)` | Pattern matching `.env`, `.env.local`, etc. | +| `mcp__gitea__*` | All tools from the gitea MCP server | +| `mcp__netbox__list_*` | Specific MCP tool pattern | +| `WebFetch(domain:github.com)` | Domain-restricted web fetch | + +### Important Nuances + +**Word boundary matching:** +- `Bash(ls *)` (with space) matches `ls -la` but NOT `lsof` +- `Bash(ls*)` (no space) matches both `ls -la` AND `lsof` + +**Precedence rules:** +- `deny` rules take precedence over `allow` rules +- `ask` rules override both (always prompts even if allowed) +- More specific patterns do NOT override broader patterns + +**Command operators:** +- Piped commands (`cmd1 | cmd2`) may not match individual command rules (known Claude Code limitation) +- Shell operators (`&&`, `||`) — Claude Code is aware of these and won't let prefix rules bypass them +- Commands with redirects (`>`, `>>`, `<`) are evaluated as complete strings + +--- + +## Section 3: Pattern Consolidation Rules + +The audit detects these optimization opportunities: + +| Issue | Example | Recommendation | +|-------|---------|----------------| +| **Exact duplicates** | `Write(plugins/**)` listed twice | Remove duplicate | +| **Subset redundancy** | `Write(plugins/projman/*)` when `Write(plugins/**)` exists | Remove the narrower pattern — already covered | +| **Merge candidates** | `Write(plugins/projman/*)`, `Write(plugins/git-flow/*)`, `Write(plugins/pr-review/*)` ... (4+ similar patterns) | Merge to `Write(plugins/**)` | +| **Overly broad** | `Bash` (no specifier = allows ALL bash) | Flag as security concern, suggest scoped patterns | +| **Stale patterns** | `Write(plugins/old-plugin/**)` for a plugin that no longer exists | Remove stale entry | +| **Missing MCP permissions** | MCP servers in `.mcp.json` but no `mcp__servername__*` in allow | Suggest adding if server is trusted | +| **Conflicting rules** | Same pattern in both `allow` and `deny` | Flag conflict — deny wins, but allow is dead weight | + +### Consolidation Algorithm + +1. **Deduplicate:** Remove exact duplicates from each array +2. **Subset elimination:** For each pattern, check if a broader pattern exists + - `Write(plugins/projman/*)` is subset of `Write(plugins/**)` + - `Bash(git status)` is subset of `Bash(git *)` +3. **Merge detection:** If 4+ patterns share a common prefix, suggest merge + - Threshold: 4 patterns minimum before suggesting consolidation +4. **Stale detection:** Cross-reference file patterns against actual filesystem +5. **Conflict detection:** Check for patterns appearing in multiple arrays + +--- + +## Section 4: Review-Layer-Aware Recommendations + +This is the key section. Map upstream review processes to directory scopes: + +| Directory Scope | Active Review Layers | Auto-Allow Recommendation | +|----------------|---------------------|---------------------------| +| `plugins/*/commands/*.md` | Sprint approval, PR review, doc-guardian PostToolUse | `Write(plugins/*/commands/**)` — 3 layers cover this | +| `plugins/*/skills/*.md` | Sprint approval, PR review | `Write(plugins/*/skills/**)` — 2 layers | +| `plugins/*/agents/*.md` | Sprint approval, PR review, contract-validator | `Write(plugins/*/agents/**)` — 3 layers | +| `mcp-servers/*/mcp_server/*.py` | Code-sentinel PreToolUse, sprint approval, PR review | `Write(mcp-servers/**)` + `Edit(mcp-servers/**)` — sentinel catches secrets | +| `docs/*.md` | Doc-guardian PostToolUse, PR review | `Write(docs/**)` + `Edit(docs/**)` | +| `.claude-plugin/*.json` | validate-marketplace.sh, PR review | `Write(.claude-plugin/**)` | +| `scripts/*.sh` | Code-sentinel, PR review | `Write(scripts/**)` — with caution flag | +| `CLAUDE.md`, `CHANGELOG.md`, `README.md` | Doc-guardian, PR review | `Write(CLAUDE.md)`, `Write(CHANGELOG.md)`, `Write(README.md)` | + +### Critical Rule: Hook Verification + +**Before recommending auto-allow for a scope, the agent MUST verify the hook is actually configured.** + +Read the relevant `plugins/*/hooks/hooks.json` file: +- If code-sentinel's hook is missing or disabled, do NOT recommend auto-allowing `mcp-servers/**` writes +- If doc-guardian's hook is missing, do NOT recommend auto-allowing `docs/**` without caution +- Count the number of verified review layers before making recommendations + +**Minimum threshold:** Recommend auto-allow only for scopes covered by ≥2 verified review layers. + +--- + +## Section 5: Permission Profiles + +Three named profiles for different project contexts: + +### `conservative` (Default for New Users) + +Minimal permissions, prompts for most write operations: + +```json +{ + "permissions": { + "allow": [ + "Read", + "Glob", + "Grep", + "LS", + "Write(docs/**)", + "Edit(docs/**)", + "Bash(git status *)", + "Bash(git diff *)", + "Bash(git log *)", + "Bash(cat *)", + "Bash(ls *)", + "Bash(head *)", + "Bash(tail *)", + "Bash(wc *)", + "Bash(grep *)" + ], + "deny": [ + "Read(.env*)", + "Read(./secrets/**)", + "Bash(rm -rf *)", + "Bash(sudo *)" + ] + } +} +``` + +### `reviewed` (Projects with ≥2 Upstream Review Layers) + +This is the target profile for projects using the marketplace's multi-layer review architecture: + +```json +{ + "permissions": { + "allow": [ + "Read", + "Glob", + "Grep", + "LS", + "Edit", + "Write", + "MultiEdit", + "Bash(git *)", + "Bash(python *)", + "Bash(pip install *)", + "Bash(cd *)", + "Bash(cat *)", + "Bash(ls *)", + "Bash(head *)", + "Bash(tail *)", + "Bash(wc *)", + "Bash(grep *)", + "Bash(find *)", + "Bash(mkdir *)", + "Bash(cp *)", + "Bash(mv *)", + "Bash(touch *)", + "Bash(chmod *)", + "Bash(source *)", + "Bash(echo *)", + "Bash(sed *)", + "Bash(awk *)", + "Bash(sort *)", + "Bash(uniq *)", + "Bash(diff *)", + "Bash(jq *)", + "Bash(npm *)", + "Bash(npx *)", + "Bash(node *)", + "Bash(pytest *)", + "Bash(python -m *)", + "Bash(./scripts/*)", + "WebFetch", + "WebSearch" + ], + "deny": [ + "Read(.env*)", + "Read(./secrets/**)", + "Bash(rm -rf *)", + "Bash(sudo *)", + "Bash(curl * | bash*)", + "Bash(wget * | bash*)" + ] + } +} +``` + +### `autonomous` (Trusted CI/Sandboxed Environments Only) + +Maximum permissions for automated environments: + +```json +{ + "permissions": { + "allow": [ + "Read", + "Glob", + "Grep", + "LS", + "Edit", + "Write", + "MultiEdit", + "Bash", + "WebFetch", + "WebSearch" + ], + "deny": [ + "Read(.env*)", + "Read(./secrets/**)", + "Bash(rm -rf /)", + "Bash(sudo *)" + ] + } +} +``` + +**Warning:** The `autonomous` profile allows unscoped `Bash` — only use in fully sandboxed environments. + +--- + +## Section 6: Scoring Criteria (Settings Efficiency Score — 100 points) + +| Category | Points | What It Measures | +|----------|--------|------------------| +| **Redundancy** | 25 | No duplicates, no subset patterns, merged where possible | +| **Coverage** | 25 | Common tools allowed, MCP servers covered, no unnecessary gaps | +| **Safety Alignment** | 25 | Deny rules cover secrets, destructive commands; review layers verified | +| **Profile Fit** | 25 | How close to recommended profile for the project's review layer count | + +### Scoring Breakdown + +**Redundancy (25 points):** +- 25: No duplicates, no subsets, patterns are consolidated +- 20: 1-2 minor redundancies +- 15: 3-5 redundancies or 1 merge candidate group +- 10: 6+ redundancies or 2+ merge candidate groups +- 5: Significant redundancy (10+ issues) +- 0: Severe redundancy (20+ issues) + +**Coverage (25 points):** +- 25: All common tools allowed, MCP servers covered +- 20: Missing 1-2 common tool patterns +- 15: Missing 3-5 patterns or 1 MCP server +- 10: Missing 6+ patterns or 2+ MCP servers +- 5: Significant gaps causing frequent prompts +- 0: Minimal coverage (prompts on most operations) + +**Safety Alignment (25 points):** +- 25: Deny rules cover secrets + destructive ops, review layers verified +- 20: Minor gaps (e.g., missing one secret pattern) +- 15: Overly broad allow without review layer coverage +- 10: Missing deny rules for secrets or destructive commands +- 5: Unsafe patterns without review layer justification +- 0: Security concerns (e.g., unscoped `Bash` without review layers) + +**Profile Fit (25 points):** +- 25: Matches recommended profile exactly +- 20: Within 90% of recommended profile +- 15: Within 80% of recommended profile +- 10: Within 70% of recommended profile +- 5: Significant deviation from recommended profile +- 0: No alignment with any named profile + +### Score Interpretation + +| Score Range | Status | Meaning | +|-------------|--------|---------| +| 90-100 | Optimized | Minimal prompt interruptions, safety maintained | +| 70-89 | Good | Minor consolidation opportunities | +| 50-69 | Needs Work | Significant redundancy or missing permissions | +| Below 50 | Poor | Likely getting constant approval prompts unnecessarily | + +--- + +## Section 7: Hook Detection Method + +To verify which review layers are active, read these files: + +| File | Hook Type | Tool Matcher | Purpose | +|------|-----------|--------------|---------| +| `plugins/code-sentinel/hooks/hooks.json` | PreToolUse | Write\|Edit\|MultiEdit | Blocks hardcoded secrets | +| `plugins/doc-guardian/hooks/hooks.json` | PostToolUse | Write\|Edit\|MultiEdit | Tracks documentation drift | +| `plugins/project-hygiene/hooks/hooks.json` | PostToolUse | Write\|Edit | Cleanup tracking | +| `plugins/data-platform/hooks/hooks.json` | PostToolUse | Edit\|Write | Schema diff detection | +| `plugins/cmdb-assistant/hooks/hooks.json` | PreToolUse | (if exists) | Input validation | + +### Verification Process + +1. **Read each hooks.json file** +2. **Parse the JSON to find hook configurations** +3. **Check the `type` field** — must be `"command"` (not `"prompt"`) +4. **Check the `event` field** — maps to when hook runs +5. **Check the `tools` array** — which operations are intercepted +6. **Verify plugin is in marketplace** — check `.claude-plugin/marketplace.json` + +### Example Hook Structure + +```json +{ + "hooks": [ + { + "event": "PreToolUse", + "type": "command", + "command": "./hooks/security-check.sh", + "tools": ["Write", "Edit", "MultiEdit"] + } + ] +} +``` + +### Review Layer Count + +Count verified review layers for each scope: + +| Layer | Verification | +|-------|-------------| +| Sprint approval | Check if projman plugin is installed (milestone workflow) | +| PR review | Check if pr-review plugin is installed | +| code-sentinel PreToolUse | hooks.json exists with PreToolUse on Write/Edit | +| doc-guardian PostToolUse | hooks.json exists with PostToolUse on Write/Edit | +| contract-validator | Plugin installed + hooks present | + +**Recommendation threshold:** Only recommend auto-allow for scopes with ≥2 verified layers. diff --git a/plugins/claude-config-maintainer/skills/visual-header.md b/plugins/claude-config-maintainer/skills/visual-header.md index 5c4e21a..e691c09 100644 --- a/plugins/claude-config-maintainer/skills/visual-header.md +++ b/plugins/claude-config-maintainer/skills/visual-header.md @@ -47,6 +47,27 @@ This skill defines the standard visual header for claude-config-maintainer comma +-----------------------------------------------------------------+ ``` +### /config-audit-settings +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Settings Audit | ++-----------------------------------------------------------------+ +``` + +### /config-optimize-settings +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Settings Optimization | ++-----------------------------------------------------------------+ +``` + +### /config-permissions-map +``` ++-----------------------------------------------------------------+ +| CONFIG-MAINTAINER - Permissions Map | ++-----------------------------------------------------------------+ +``` + ## Usage Display the header at the start of command execution, before any analysis or output.