claudia-mentor 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "claudia-mentor",
+  "version": "0.1.0",
+  "description": "Proactive technology mentor, security advisor, and prompt coach for Claude Code. Catches bad practices, advises on architecture decisions, and coaches better prompting.",
+  "author": {
+    "name": "Regan O'Malley",
+    "email": "regan@reganomalley.com"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Regan O'Malley
+
+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.

package/README.md

@@ -0,0 +1,219 @@
+# Claudia: Proactive Mentor Plugin for Claude Code
+
+A Claude Code plugin that acts as your technology mentor, security advisor, and prompt coach. Claudia fills the gaps between writing code and making good technology decisions.
+
+**10 knowledge domains. 7 automated hooks. Context-aware advice.**
+
+## What Claudia Does
+
+- **Technology advising** -- Helps you choose databases, frameworks, APIs, infrastructure, and architecture patterns with clear trade-offs
+- **Security guidance** -- Catches hardcoded secrets before they ship, advises on auth patterns and secrets management
+- **Anti-pattern detection** -- Warns about common mistakes across code, Docker, dependencies, accessibility, and git hygiene
+- **Prompt coaching** -- Detects vague prompts and suggests improvements to get better results from Claude
+- **Context-aware** -- Reads your package.json, configs, and stack to give specific advice, not generic recommendations
+- **Project health audits** -- `/claudia-health` scans your project for security, testing, dependency, and architecture issues
+
+## Install
+
+```bash
+# Clone the plugin
+git clone https://github.com/reganomalley/claudia.git ~/.claude/plugins/claudia
+
+# Or install from npm
+npm install -g claudia-mentor
+
+# Enable in Claude Code
+claude plugin add ~/.claude/plugins/claudia
+```
+
+## Usage
+
+### Slash Commands
+
+```
+/claudia what database should I use for time-series IoT data?
+/claudia is JWT or session-based auth better for my SPA?
+/claudia should I use REST or GraphQL for my mobile app?
+/claudia how should I structure my CI/CD pipeline?
+/claudia-health                    # Run a full project health audit
+/claudia-health security           # Focus on security issues
+```
+
+### Automatic (Model-Invoked)
+
+Claudia automatically activates when you:
+- Make technology decisions ("should I use MongoDB or Postgres?")
+- Discuss architecture ("how should I structure this microservice?")
+- Choose between frameworks ("React or Svelte for this project?")
+- Write suboptimal prompts ("make it better")
+- Introduce security anti-patterns
+
+### Hooks (Always Active)
+
+**Secret detection** (blocks):
+- AWS access keys, OpenAI/Stripe keys, GitHub tokens, GitLab PATs, Slack tokens
+- Hardcoded passwords, secrets, and API keys
+- Database connection strings with credentials
+- Private keys
+
+**Anti-pattern warnings** (advisory):
+- `eval()` usage, `document.write()`, `innerHTML`
+- `console.log` in production code
+- Empty catch blocks
+- HTTP URLs (non-HTTPS), disabled SSL verification
+- SQL string concatenation
+- `chmod 777`
+- TODO/FIXME markers in new code
+
+**Dependency audit** (advisory):
+- Deprecated packages (moment, request, gulp)
+- Compromised packages (colors, faker, event-stream)
+- Trivial packages (is-odd, is-even, left-pad)
+
+**Dockerfile lint** (advisory):
+- Running as root, large base images, `:latest` tag
+- Missing multi-stage builds, secrets in ENV
+- npm install without --production
+
+**Git hygiene** (blocks/advisory):
+- Writing to .env files (blocks)
+- Merge conflict markers in code (blocks)
+- Large binary files (advisory)
+
+**Accessibility** (advisory):
+- Images without alt text
+- Inputs without labels
+- Icon-only buttons without aria-label
+- Click handlers on non-interactive elements
+- Positive tabIndex values
+
+**License compliance** (advisory):
+- Copyleft dependencies (GPL, AGPL, SSPL) in permissive-licensed projects
+
+## Knowledge Domains
+
+### Databases (`claudia-databases`)
+- SQL vs NoSQL decision framework
+- Vector databases for RAG/embeddings (pgvector, Pinecone, Qdrant)
+- Time-series and graph database selection
+- "Just use Postgres" rule (and when to break it)
+
+### Security (`claudia-security`)
+- Authentication patterns (session, JWT, OAuth, passkeys)
+- Secrets management lifecycle
+- TEEs and sandboxing
+- Common security mistakes with fixes
+
+### Infrastructure (`claudia-infrastructure`)
+- AWS vs GCP vs Azure vs self-host
+- Container orchestration (Docker, ECS, Cloud Run, k8s)
+- Serverless decision framework
+- Edge computing and cost estimation
+
+### Frontend (`claudia-frontend`)
+- Framework selection (React, Vue, Svelte, Solid, Angular)
+- SSR vs SPA vs SSG vs islands architecture
+- State management (when to use what)
+- CSS approaches, bundlers, Core Web Vitals
+
+### API Design (`claudia-api`)
+- REST vs GraphQL vs gRPC vs tRPC
+- API versioning, pagination, error handling
+- Webhook design, rate limiting
+- Real-time patterns (WebSockets, SSE, polling)
+
+### Testing (`claudia-testing`)
+- Test pyramid and what to test at each level
+- Framework comparison (Jest, Vitest, Playwright)
+- Mocking patterns (and when NOT to mock)
+- Testing strategy by app type
+
+### Performance (`claudia-performance`)
+- "Measure before you optimize" framework
+- Backend: N+1 queries, caching, connection pooling
+- Frontend: Core Web Vitals, bundle optimization, image/font loading
+- Profiling tools for Node.js and Python
+
+### DevOps (`claudia-devops`)
+- CI/CD pipeline design (GitHub Actions patterns)
+- Deployment strategies (rolling, blue-green, canary)
+- Monitoring hierarchy and the four golden signals
+- Incident response and SLI/SLO framework
+
+### Data Modeling (`claudia-data`)
+- Schema design patterns (multi-tenancy, soft deletes, hierarchical data)
+- Migration safety (zero-downtime patterns)
+- Indexing strategy (B-tree, GIN, partial, composite)
+- Normalization, denormalization, and anti-patterns
+
+### Prompt Coaching (built into mentor)
+- Detects vague or underspecified prompts
+- Suggests improvements across 5 quality dimensions
+- Offers rewritten versions
+
+## Configuration
+
+Override Claudia's personality and proactivity level:
+
+### Global (`~/.claude/claudia.json`)
+
+```json
+{
+  "proactivity": "high",
+  "personality": {
+    "tone": "casual"
+  }
+}
+```
+
+### Per-project (`.claudia.json` in project root)
+
+```json
+{
+  "proactivity": "low",
+  "hooks": {
+    "check_practices": {
+      "enabled": false
+    }
+  }
+}
+```
+
+### Proactivity Levels
+
+| Level | Behavior |
+|-------|----------|
+| `low` | Only responds when you use `/claudia` |
+| `moderate` | Proactive on security issues and major anti-patterns (default) |
+| `high` | Flags any suboptimal pattern or technology decision |
+
+## Contributing
+
+Claudia is designed for community contributions. The easiest ways to contribute:
+
+### Add Reference Files
+Drop a new `.md` file in any `references/` directory. Follow the voice: opinionated, direct, explains why, uses concrete examples.
+
+### Add Anti-Patterns
+Add entries to any hook script in `hooks/scripts/`.
+
+### New Knowledge Domains
+
+Use the scaffolding tool:
+
+```bash
+./scripts/create-domain.sh architecture
+```
+
+This creates the directory structure and template files. Fill in the SKILL.md, add reference files, and update the mentor's routing table.
+
+### Guidelines
+- Be opinionated -- "it depends" without follow-up is not helpful
+- Use decision trees and comparison tables
+- Explain the "why" behind every recommendation
+- Include "when NOT to use this" alongside recommendations
+- Keep SKILL.md under ~2000 words, put depth in references
+
+## License
+
+MIT

package/commands/claudia-health.md

@@ -0,0 +1,93 @@
+---
+description: Run a health check on the current project -- security, testing, architecture, dependencies
+argument-hint: [optional: focus area like "security" or "deps"]
+allowed-tools: [Read, Glob, Grep, Bash, WebSearch]
+---
+
+# Claudia Health Check
+
+You are Claudia, running a project health audit. Scan the current project and report findings.
+
+**Focus area (optional):** $ARGUMENTS
+
+## Audit Process
+
+### 1. Discover the Stack
+
+Read `package.json` (or `pyproject.toml`, `go.mod`, etc.) and scan for config files:
+
+```
+Glob: **/package.json, **/tsconfig.json, **/Dockerfile, **/docker-compose.yml,
+      **/.env.example, **/prisma/schema.prisma, **/.github/workflows/*.yml,
+      **/vite.config.*, **/next.config.*, **/vitest.config.*, **/jest.config.*,
+      **/.eslintrc.*, **/tailwind.config.*
+```
+
+### 2. Run Checks
+
+**Security:**
+- [ ] .env file is gitignored (check `.gitignore`)
+- [ ] No hardcoded secrets in source (grep for `sk-`, `AKIA`, `password =`)
+- [ ] Dependencies don't have known vulnerabilities (run `npm audit --json` if Node.js)
+- [ ] HTTPS enforced in configs
+- [ ] CORS configured (not `*` in production)
+- [ ] Auth library used (not hand-rolled)
+
+**Testing:**
+- [ ] Test framework configured (jest.config, vitest.config, pytest.ini)
+- [ ] Tests exist (glob for `**/*.test.*`, `**/*.spec.*`, `**/test_*.py`)
+- [ ] CI runs tests (check `.github/workflows/`)
+- [ ] Test coverage configured
+
+**Dependencies:**
+- [ ] Lock file exists and tracked (package-lock.json, yarn.lock, pnpm-lock.yaml)
+- [ ] No deprecated packages (check against known list)
+- [ ] Node/Python version pinned (engines in package.json, .python-version, .nvmrc)
+- [ ] devDependencies not in production dependencies
+
+**Architecture:**
+- [ ] README exists
+- [ ] Environment variables documented (.env.example)
+- [ ] Dockerfile uses multi-stage builds (if containerized)
+- [ ] TypeScript strict mode enabled (if using TS)
+- [ ] Linting configured
+
+**Performance:**
+- [ ] Images optimized (next/image, responsive images)
+- [ ] Bundle analysis available
+- [ ] Caching configured (Redis, CDN, HTTP cache headers)
+
+### 3. Report Format
+
+Present findings as a health report:
+
+```
+## Project Health: [project-name]
+
+**Stack:** [detected framework, DB, hosting]
+**Overall:** [Good / Needs Attention / Critical Issues]
+
+### Security [score/5]
+- [finding]
+- [finding]
+
+### Testing [score/5]
+- [finding]
+
+### Dependencies [score/5]
+- [finding]
+
+### Architecture [score/5]
+- [finding]
+
+### Top 3 Actions
+1. [most impactful fix]
+2. [second most impactful]
+3. [third]
+```
+
+### 4. Personality
+
+Be direct. Don't soften findings. If something is bad, say it's bad and say how to fix it. But also acknowledge what's done well -- a clean security setup deserves a note.
+
+If the user specified a focus area ($ARGUMENTS), go deeper on that area and lighter on others.

package/commands/claudia.md

@@ -0,0 +1,27 @@
+---
+description: Ask Claudia for technology advice, architecture guidance, or prompt coaching
+argument-hint: <question about databases, security, architecture, or prompts>
+allowed-tools: [Read, Glob, Grep, WebSearch, WebFetch]
+---
+
+# Claudia: Technology Mentor
+
+You are Claudia, a proactive technology mentor. The user is asking you a direct question.
+
+**User's question:** $ARGUMENTS
+
+## How to Respond
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/skills/claudia-mentor/SKILL.md` for your personality and routing logic.
+
+2. Determine the domain:
+   - **Database question** → Read `${CLAUDE_PLUGIN_ROOT}/skills/claudia-databases/SKILL.md` and relevant references
+   - **Security question** → Read `${CLAUDE_PLUGIN_ROOT}/skills/claudia-security/SKILL.md` and relevant references
+   - **Prompt quality** → Read `${CLAUDE_PLUGIN_ROOT}/skills/claudia-mentor/references/prompt-coaching.md`
+   - **General architecture/infra** → Use your knowledge + WebSearch for current information
+
+3. Check for personality overrides at `~/.claude/claudia.json` or `.claudia.json` in the current project.
+
+4. Respond following Claudia's personality: direct, explains why, uses analogies, admits uncertainty. Keep it focused -- direct answer, reasoning, trade-offs, next step.
+
+5. If the question is outside your knowledge base, use WebSearch to find current authoritative information. Clearly distinguish between what you know and what you looked up.

package/config/defaults.json

@@ -0,0 +1,25 @@
+{
+  "personality": {
+    "name": "Claudia",
+    "tone": "direct",
+    "style": "explains-why",
+    "uses_analogies": true,
+    "admits_uncertainty": true
+  },
+  "proactivity": "moderate",
+  "proactivity_levels": {
+    "low": "Only responds when invoked via /claudia",
+    "moderate": "Proactive on security issues and major anti-patterns",
+    "high": "Proactive on any suboptimal pattern or decision"
+  },
+  "hooks": {
+    "check_secrets": {
+      "enabled": true,
+      "action": "block"
+    },
+    "check_practices": {
+      "enabled": true,
+      "action": "advisory"
+    }
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,77 @@
+{
+  "description": "Claudia mentor hooks: security, anti-patterns, dependencies, Docker, git hygiene, accessibility, and license compliance",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-secrets.sh",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-practices.py",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-deps.py",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-dockerfile.py",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-git-hygiene.py",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-accessibility.py",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-license.py",
+            "timeout": 10
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      }
+    ]
+  }
+}

package/hooks/scripts/check-accessibility.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+Claudia: check-accessibility.py
+PreToolUse hook that warns on accessibility issues in HTML/JSX writes.
+Advisory only (exit 0 with systemMessage), never blocks.
+Session-aware dedup.
+"""
+
+import json
+import os
+import re
+import sys
+
+# Accessibility patterns to check
+# (pattern_regex, negative_pattern, description, advice, pattern_id)
+# negative_pattern: if this matches, skip the warning (false positive prevention)
+A11Y_PATTERNS = [
+    (
+        r'<img\b(?![^>]*\balt\b)',
+        None,
+        "Image without alt attribute",
+        "All `<img>` elements need an `alt` attribute. Use descriptive text, or `alt=\"\"` for decorative images.",
+        "a11y_img_alt",
+    ),
+    (
+        r'<input\b(?![^>]*\b(?:aria-label|aria-labelledby|id\s*=\s*["\'][^"\']+["\'])\b)(?![^>]*\btype\s*=\s*["\'](?:hidden|submit|button|reset)["\'])',
+        r'<label\b',
+        "Form input without label or aria-label",
+        "Inputs need associated labels. Use `<label htmlFor>`, `aria-label`, or `aria-labelledby`.",
+        "a11y_input_label",
+    ),
+    (
+        r'<button\b(?![^>]*\b(?:aria-label|aria-labelledby)\b)[^>]*>\s*<(?:img|svg|i|span\s+class)',
+        None,
+        "Icon-only button without accessible label",
+        "Buttons with only icons need `aria-label` to describe their action (e.g., `aria-label=\"Close\"`).",
+        "a11y_icon_button",
+    ),
+    (
+        r'onClick\s*=\s*\{[^}]+\}\s*(?:className|style)',
+        r'<(?:button|a|input|select|textarea)\b',
+        "Click handler on non-interactive element",
+        "Use `<button>` for clickable elements, not `<div onClick>`. Buttons are keyboard-accessible and announced by screen readers.",
+        "a11y_div_click",
+    ),
+    (
+        r'tabIndex\s*=\s*["\']?[1-9]',
+        None,
+        "Positive tabIndex value",
+        "Avoid positive `tabIndex` values. They override natural tab order and confuse keyboard users. Use `tabIndex={0}` or `-1`.",
+        "a11y_tabindex",
+    ),
+    (
+        r'<a\b(?![^>]*\bhref\b)',
+        None,
+        "Anchor tag without href",
+        "Use `<button>` for actions, `<a href>` for navigation. An `<a>` without `href` is not keyboard-accessible.",
+        "a11y_anchor_href",
+    ),
+    (
+        r'autoFocus|autofocus',
+        None,
+        "autoFocus attribute used",
+        "Avoid `autoFocus` -- it can disorient screen reader users and disrupt keyboard navigation. Let users control focus.",
+        "a11y_autofocus",
+    ),
+    (
+        r'<(?:h[1-6])\b[^>]*>\s*</(?:h[1-6])>',
+        None,
+        "Empty heading element",
+        "Headings should contain text content. Empty headings confuse screen readers navigating by heading structure.",
+        "a11y_empty_heading",
+    ),
+]
+
+# File extensions to check
+A11Y_EXTENSIONS = {'.html', '.htm', '.jsx', '.tsx', '.vue', '.svelte', '.astro'}
+
+
+def get_state_file(session_id):
+    return os.path.expanduser(f"~/.claude/claudia_a11y_state_{session_id}.json")
+
+
+def load_state(session_id):
+    state_file = get_state_file(session_id)
+    if os.path.exists(state_file):
+        try:
+            with open(state_file) as f:
+                return set(json.load(f))
+        except (json.JSONDecodeError, IOError):
+            return set()
+    return set()
+
+
+def save_state(session_id, shown):
+    state_file = get_state_file(session_id)
+    try:
+        os.makedirs(os.path.dirname(state_file), exist_ok=True)
+        with open(state_file, "w") as f:
+            json.dump(list(shown), f)
+    except IOError:
+        pass
+
+
+def extract_content(tool_name, tool_input):
+    if tool_name == "Write":
+        return tool_input.get("content", "")
+    elif tool_name == "Edit":
+        return tool_input.get("new_string", "")
+    elif tool_name == "MultiEdit":
+        edits = tool_input.get("edits", [])
+        return " ".join(e.get("new_string", "") for e in edits)
+    return ""
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    session_id = input_data.get("session_id", "default")
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if tool_name not in ("Edit", "Write", "MultiEdit"):
+        sys.exit(0)
+
+    # Only check HTML/JSX/Vue/Svelte files
+    _, ext = os.path.splitext(file_path)
+    if ext.lower() not in A11Y_EXTENSIONS:
+        sys.exit(0)
+
+    content = extract_content(tool_name, tool_input)
+    if not content:
+        sys.exit(0)
+
+    # Skip test files
+    if any(x in file_path for x in ['.test.', '.spec.', '/test/', '/tests/', 'fixture', 'mock', '__test__']):
+        sys.exit(0)
+
+    shown = load_state(session_id)
+    warnings = []
+
+    for entry in A11Y_PATTERNS:
+        pattern, negative, description, advice, pattern_id = entry
+
+        if re.search(pattern, content, re.IGNORECASE):
+            # If there's a negative pattern and it matches, skip
+            if negative and re.search(negative, content, re.IGNORECASE):
+                continue
+
+            warning_key = f"{file_path}-{pattern_id}"
+            if warning_key not in shown:
+                shown.add(warning_key)
+                warnings.append(f"- {description}: {advice}")
+
+    if warnings:
+        save_state(session_id, shown)
+        message = "Claudia noticed some accessibility concerns:\n" + "\n".join(warnings)
+        output = json.dumps({"systemMessage": message})
+        print(output)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()