← back to ClawCoder

docs/superpowers/specs/2026-03-23-clawcoder-profiles-analyzer-design.md

1378 lines

# ClawCoder — Profile System + CLAUDE.md Analyzer Design Spec

**Date**: 2026-03-23
**Status**: Draft
**Approach**: B (Profile + Analyzer + Marketplace)

---

## 1. Executive Summary

ClawCoder is a cross-platform app that helps users generate, analyze, and maintain high-quality CLAUDE.md configurations. This spec covers two core features:

1. **Profile System** — 15 profiles (5 age groups x 3 skill levels) that pre-configure the entire app experience: UI, templates, skill bundles, MCP servers, hooks, and learning paths.
2. **CLAUDE.md Analyzer** — Upload an existing CLAUDE.md, get scored against 12 best-practice criteria, see pros/cons/suggestions, select suggestions to apply, and mass-update records.

---

## 2. Profile System Architecture

### 2.1 Profile Matrix: 5 Age Groups x 3 Skill Levels

Each profile is a JSON configuration object that controls:
- `ui` — font size, motion preference, contrast, touch target size, layout density
- `template` — CLAUDE.md template variant, verbosity level, safety strictness
- `skills` — pre-selected skill bundles from marketplace
- `mcpServers` — recommended MCP servers (trust-gated)
- `hooks` — default hook configurations
- `subagents` — recommended subagent bundles
- `learningPath` — ordered list of video/doc resources
- `onboarding` — question flow customization (pace, language level, examples)

### 2.2 The 15 Profiles

---

#### Profile 1: Teen Beginner (age 13-17, skill: beginner)

**Slug**: `teen-beginner`
**Persona**: First-time coder, learning programming in school or self-taught. Needs encouragement, safety rails, and simple language.

**UI Configuration**:
```json
{
  "fontSize": 16,
  "fontScale": 1.0,
  "motionLevel": "normal",
  "contrast": "standard",
  "touchTargetMin": 44,
  "layoutDensity": "comfortable",
  "theme": "light"
}
```

**CLAUDE.md Template**: `starter-safe`
- Verbosity: high (explain every step)
- Safety: maximum (no destructive commands, no secret handling, ask before any file change)
- Style: encouraging, uses simple terms
- Target lines: 40-60

**Template Content**:
```markdown
# CLAUDE.md — My Project

## How to help me
- Explain what you're doing in simple steps.
- If something might break, warn me first and ask permission.
- Show me what changed after each step.
- If I seem confused, offer a simpler explanation.

## Safety rules
- Never delete files without asking.
- Never run commands that could break things.
- If you're not sure about something, ask me first.
- Keep my passwords and private info safe — never put them in code files.

## My project
- Name: {{project_name}}
- What it does: {{project_description}}
- Language: {{language}}

## Commands
- Run it: {{run_cmd}}
- Test it: {{test_cmd}}
```

**Skill Bundle**:
- `senior-explain` (simple language explanations)
- `git-commit-helper` (safe commit guidance)

**MCP Servers**:
- `filesystem` (read-only, project dir only)
- `memory` (knowledge graph for learning)

**Hooks**:
```json
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "echo 'Checking for dangerous commands...' && echo $TOOL_INPUT | grep -qE 'rm -rf|sudo|chmod 777|format|mkfs' && exit 2 || exit 0"
    }]
  }]
}
```

**Learning Path**:
1. [Sabrina's Ultimate Claude Code Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners) (90 min, beginner-friendly)
2. [Claude Code Official Docs — Best Practices](https://code.claude.com/docs/en/best-practices)

**Subagents**: None (too complex for this level)

---

#### Profile 2: Teen Intermediate (age 13-17, skill: intermediate)

**Slug**: `teen-intermediate`
**Persona**: Coding student with project experience. Comfortable with Git, wants to level up with skills and automation.

**UI Configuration**:
```json
{
  "fontSize": 15,
  "fontScale": 1.0,
  "motionLevel": "normal",
  "contrast": "standard",
  "touchTargetMin": 44,
  "layoutDensity": "comfortable",
  "theme": "light"
}
```

**CLAUDE.md Template**: `student-project`
- Verbosity: medium (explain key decisions)
- Safety: high (guard destructive ops, but allow standard dev workflow)
- Style: clear, educational
- Target lines: 60-80

**Template Content**:
```markdown
# CLAUDE.md — {{project_name}}

## Working style
- Explain key decisions briefly.
- Run tests after changes.
- Use small, focused commits.
- If a change could break existing features, flag it.

## Safety
- Don't modify .env or credential files.
- Don't run destructive commands without asking.
- Prefer safe exploration (read first, then suggest changes).

## Project
- Name: {{project_name}}
- Stack: {{stack}}
- Description: {{project_description}}

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Lint: {{lint_cmd}}

## Code style
- {{indent_style}}
- {{naming_convention}}
```

**Skill Bundle**:
- `git-commit-helper`
- `update-claude-md` (self-improving instructions)
- `webapp-testing` (if web project)

**MCP Servers**:
- `filesystem` (project directory)
- `github` (learn collaboration)
- `context7` (prevent hallucinated APIs)

**Hooks**:
```json
{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "echo 'File changed — consider running tests'"
    }]
  }]
}
```

**Learning Path**:
1. [Sabrina's Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners)
2. [CLAUDE.md Best Practices — Builder.io](https://www.builder.io/blog/claude-md-guide)
3. [Skills vs Commands vs Subagents](https://www.youngleaders.tech/p/claude-skills-commands-subagents-plugins)

**Subagents**:
- `code-reviewer` (Haiku, read-only, reviews before commit)

---

#### Profile 3: Teen Expert (age 13-17, skill: expert)

**Slug**: `teen-expert`
**Persona**: Advanced young developer. Competitive programming, open source contributor, or building real apps. Wants full power.

**UI Configuration**:
```json
{
  "fontSize": 14,
  "fontScale": 1.0,
  "motionLevel": "full",
  "contrast": "standard",
  "touchTargetMin": 44,
  "layoutDensity": "compact",
  "theme": "dark"
}
```

**CLAUDE.md Template**: `power-user`
- Verbosity: low (just do it, explain only if asked)
- Safety: standard (guard secrets, allow normal dev ops)
- Style: concise, technical
- Target lines: 50-70

**Template Content**:
```markdown
# CLAUDE.md

## Rules
- Keep changes minimal and focused.
- Run {{test_cmd}} after behavior changes.
- Commit with descriptive messages.
- Don't touch .env, credentials, or CI config without asking.

## Stack
- {{stack}}
- {{framework_details}}

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Build: {{build_cmd}}
- Lint: {{lint_cmd}}

## Architecture
@docs/ARCHITECTURE.md

## Style
- {{indent_style}}
- {{naming_convention}}
- {{import_style}}
```

**Skill Bundle**:
- `update-claude-md`
- `git-commit-helper`
- `compound-engineering` (plan-work-review-compound loop)

**MCP Servers**:
- `filesystem`, `github`, `context7`
- `21st-dev-magic` (UI generation)
- `brave-search` (web research)

**Hooks**:
```json
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "echo $TOOL_INPUT | grep -qE 'rm -rf /|sudo rm|format|mkfs' && exit 2 || exit 0"
    }]
  }],
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "npx prettier --write $TOOL_INPUT_PATH 2>/dev/null; exit 0"
    }]
  }]
}
```

**Learning Path**:
1. [Agent Skills with Anthropic — DeepLearning.AI](https://learn.deeplearning.ai/courses/agent-skills-with-anthropic)
2. [Frontend Masters Pro AI Setup](https://frontendmasters.com/courses/pro-ai/)
3. [FlorianBruniaux Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)

**Subagents**:
- `code-reviewer` (Sonnet, comprehensive review)
- `test-engineer` (write tests before implementation)

---

#### Profile 4: Young Adult Beginner (age 18-30, skill: beginner)

**Slug**: `young-adult-beginner`
**Persona**: Career starter, bootcamp grad, or hobbyist. May know one language/framework. Needs clear guidance without condescension.

**UI Configuration**:
```json
{
  "fontSize": 16,
  "fontScale": 1.0,
  "motionLevel": "normal",
  "contrast": "standard",
  "touchTargetMin": 44,
  "layoutDensity": "comfortable",
  "theme": "light"
}
```

**CLAUDE.md Template**: `guided-starter`
- Verbosity: high (explain reasoning, show alternatives)
- Safety: high
- Style: supportive, practical
- Target lines: 50-70

**Template Content**:
```markdown
# CLAUDE.md — {{project_name}}

## How we work
- Explain your reasoning for each change.
- If there are multiple approaches, briefly mention the tradeoff.
- After finishing, summarize what changed and how to undo it.
- Ask one clear question if you're unsure, rather than guessing.

## Safety
- Don't edit .env, secrets, or config files unless I say so.
- Don't run destructive commands (rm -rf, drop tables, force push).
- Prefer read-only exploration first.

## Project
- Name: {{project_name}}
- What it does: {{project_description}}
- Stack: {{stack}}

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}

## Style
- {{indent_style}}
- {{naming_convention}}
```

**Skill Bundle**:
- `senior-explain` (clear explanations)
- `git-commit-helper`
- `update-claude-md`

**MCP Servers**:
- `filesystem` (project dir, read-only initially)
- `context7` (prevent hallucinated APIs)
- `memory` (persistent learning)

**Hooks**: Same destructive-command guard as teen-beginner

**Learning Path**:
1. [Sabrina's 90-min Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners)
2. [Official Best Practices](https://code.claude.com/docs/en/best-practices)
3. [CLAUDE.md Guide — Builder.io](https://www.builder.io/blog/claude-md-guide)

**Subagents**: None initially

---

#### Profile 5: Young Adult Intermediate (age 18-30, skill: intermediate)

**Slug**: `young-adult-intermediate`
**Persona**: Working developer (1-5 years). Uses Git daily, knows at least one framework well. Wants to optimize workflow.

**UI Configuration**:
```json
{
  "fontSize": 15,
  "fontScale": 1.0,
  "motionLevel": "normal",
  "contrast": "standard",
  "touchTargetMin": 44,
  "layoutDensity": "comfortable",
  "theme": "auto"
}
```

**CLAUDE.md Template**: `working-dev`
- Verbosity: medium
- Safety: standard
- Style: professional, practical
- Target lines: 60-90

**Template Content**:
```markdown
# CLAUDE.md

## Workflow
- Make small, reviewable changes.
- Create or update tests when behavior changes.
- Keep changes within the requested scope.
- Follow existing patterns in the codebase.

## Safety
- Don't modify secrets, credentials, or CI/CD config without asking.
- Don't force push or reset hard.
- Validate changes work before reporting success.

## Project
- Stack: {{stack}}
- Architecture: @docs/ARCHITECTURE.md

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Unit tests: {{unit_test_cmd}}
- E2E tests: {{e2e_test_cmd}}
- Lint: {{lint_cmd}}
- Format: {{format_cmd}}

## Code style
Follow .claude/rules/code-style.md
```

**Rules (.claude/rules/)**:
- `code-style.md` — indent, TypeScript strict, naming conventions
- `testing.md` — test requirements, coverage expectations
- `security.md` — no secrets in logs, validate external input

**Skill Bundle**:
- `update-claude-md`
- `compound-engineering`
- `git-commit-helper`
- `simplify` (code review for quality)

**MCP Servers**:
- `filesystem`, `github`, `context7`
- `playwright` (testing)
- `brave-search`

**Hooks**:
```json
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{ "type": "command", "command": "echo $TOOL_INPUT | grep -qE 'rm -rf /|--force|--hard|DROP TABLE|TRUNCATE' && exit 2 || exit 0" }]
  }],
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{ "type": "command", "command": "npx prettier --write $TOOL_INPUT_PATH 2>/dev/null; exit 0" }]
  }]
}
```

**Learning Path**:
1. [Frontend Masters Pro AI Setup](https://frontendmasters.com/courses/pro-ai/)
2. [Agent Skills — DeepLearning.AI](https://learn.deeplearning.ai/courses/agent-skills-with-anthropic)
3. [Blake Crosley's Production Hooks](https://blakecrosley.com/blog/claude-code-hooks-tutorial)
4. [ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase)

**Subagents**:
- `code-reviewer` (Sonnet)
- `test-engineer` (write test plans)

---

#### Profile 6: Young Adult Expert (age 18-30, skill: expert)

**Slug**: `young-adult-expert`
**Persona**: Senior dev or tech lead (3-8 years). Builds architectures, mentors juniors, deploys to production. Wants full control and automation.

**UI Configuration**:
```json
{
  "fontSize": 14,
  "fontScale": 1.0,
  "motionLevel": "full",
  "contrast": "standard",
  "touchTargetMin": 40,
  "layoutDensity": "compact",
  "theme": "dark"
}
```

**CLAUDE.md Template**: `full-control`
- Verbosity: low (terse, no trailing summaries)
- Safety: targeted (protect specific paths, allow everything else)
- Style: direct, technical
- Target lines: 40-60 (with heavy modular imports)

**Template Content**:
```markdown
# CLAUDE.md

## Rules
- Follow .claude/rules/*.md
- Use skills for repeatable workflows.
- Hooks enforce non-negotiable steps.

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Build: {{build_cmd}}
- Deploy: {{deploy_cmd}}

## Architecture
@docs/ARCHITECTURE.md

## API conventions
@docs/API_CONVENTIONS.md

## Protected paths
- {{protected_paths}}
- Never change: {{immutable_files}}
```

**Rules (.claude/rules/)**:
- `code-style.md`, `testing.md`, `security.md`
- `deployment.md` — deploy procedures, rollback steps
- `api-conventions.md` — endpoint patterns, versioning

**Skill Bundle**:
- `compound-engineering`
- `update-claude-md`
- `simplify`
- `prd` (product requirements documents)
- `build-feature` (autonomous task loop)

**MCP Servers**:
- `filesystem`, `github`, `context7`, `brave-search`
- `21st-dev-magic` (UI generation)
- `playwright` (testing)
- `postgres-mcp` (database)
- `notion` (project management)
- `firecrawl` (web scraping)

**Hooks**:
```json
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{ "type": "command", "command": "echo $TOOL_INPUT | grep -qE 'rm -rf /|format|mkfs' && exit 2 || exit 0" }]
  }],
  "PostToolUse": [
    { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npx prettier --write $TOOL_INPUT_PATH 2>/dev/null; exit 0" }] },
    { "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo $TOOL_INPUT | grep -q 'test' && echo 'Tests executed' || exit 0" }] }
  ],
  "Stop": [{
    "matcher": "",
    "hooks": [{ "type": "command", "command": "echo 'Session ended — consider updating CLAUDE.md'" }]
  }]
}
```

**Learning Path**:
1. [Agent Skills — DeepLearning.AI](https://learn.deeplearning.ai/courses/agent-skills-with-anthropic)
2. [MCP: Build Rich-Context AI Apps](https://learn.deeplearning.ai/courses/mcp-build-rich-context-ai-apps-with-anthropic)
3. [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) (self-improving agent pattern)
4. [Code w/ Claude Conference](https://anthropic.com/events/code-with-claude-2025)

**Subagents**:
- `code-reviewer` (Sonnet, comprehensive)
- `architect-reviewer` (SOLID, layering)
- `security-auditor` (OWASP, auth)
- `test-engineer` (TDD workflow)
- `performance-engineer` (profiling, optimization)

---

#### Profile 7: Professional Beginner (age 31-50, skill: beginner)

**Slug**: `professional-beginner`
**Persona**: Career switcher, product manager learning to code, or domain expert new to dev tools. Values clarity over speed.

**UI Configuration**:
```json
{
  "fontSize": 17,
  "fontScale": 1.05,
  "motionLevel": "reduced",
  "contrast": "enhanced",
  "touchTargetMin": 48,
  "layoutDensity": "comfortable",
  "theme": "light"
}
```

**CLAUDE.md Template**: `clear-guidance`
- Verbosity: high (explain reasoning, give context)
- Safety: maximum
- Style: professional, patient
- Target lines: 50-70

**Template Content**:
```markdown
# CLAUDE.md — {{project_name}}

## How to help me
- Use clear, jargon-free language when possible.
- Explain technical terms when you first use them.
- Walk me through each step before doing it.
- After each change, tell me: what changed, why, and how to undo it.
- If I make a mistake, help me fix it without judgment.

## Safety (very important)
- Never delete or overwrite files without my explicit permission.
- Never run commands that could damage my computer or data.
- Don't access my email, messages, or personal files.
- Keep all passwords and sensitive data out of code files.
- If you're unsure about something, always ask first.

## My project
- Name: {{project_name}}
- What it does: {{project_description}}
- Language: {{language}}

## Commands (copy and paste these exactly)
- To start: {{run_cmd}}
- To test: {{test_cmd}}
```

**Skill Bundle**:
- `senior-explain` (accessible language)
- `git-commit-helper`

**MCP Servers**:
- `filesystem` (project dir, read-only)
- `memory` (track learning progress)

**Hooks**: Maximum destructive-command blocking

**Learning Path**:
1. [Sabrina's 90-min Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners) (no coding required)
2. [Official Best Practices](https://code.claude.com/docs/en/best-practices)

**Subagents**: None

---

#### Profile 8: Professional Intermediate (age 31-50, skill: intermediate)

**Slug**: `professional-intermediate`
**Persona**: Team lead, engineering manager, or experienced IC. Manages projects, reviews PRs, cares about team standards.

**UI Configuration**:
```json
{
  "fontSize": 16,
  "fontScale": 1.0,
  "motionLevel": "normal",
  "contrast": "standard",
  "touchTargetMin": 44,
  "layoutDensity": "comfortable",
  "theme": "auto"
}
```

**CLAUDE.md Template**: `team-lead`
- Verbosity: medium
- Safety: standard with team protections
- Style: structured, process-oriented
- Target lines: 70-100 (with .claude/rules/)

**Template Content**:
```markdown
# CLAUDE.md

## Team workflow
- Follow .claude/rules/ for code style, testing, and security standards.
- All changes should be reviewable — small commits, clear messages.
- Update tests when behavior changes.
- Don't modify shared config, CI/CD, or infrastructure without approval.

## Project
- Stack: {{stack}}
- Team size: {{team_size}}
- Architecture: @docs/ARCHITECTURE.md

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Lint: {{lint_cmd}}
- Build: {{build_cmd}}

## Review standards
- @docs/REVIEW_CHECKLIST.md

## Protected paths
- .github/workflows/ — CI/CD changes need team review
- {{protected_paths}}
```

**Rules (.claude/rules/)**:
- `code-style.md`, `testing.md`, `security.md`
- `review-standards.md` — PR review checklist

**Skill Bundle**:
- `compound-engineering`
- `update-claude-md`
- `simplify`
- `prd` (requirements docs)
- `code-review` (automated reviews)

**MCP Servers**:
- `filesystem`, `github`, `context7`
- `notion` (project management)
- `slack` (team communication)
- `brave-search`

**Hooks**: Auto-format + destructive guard + post-edit test reminder

**Learning Path**:
1. [Frontend Masters Pro AI Setup](https://frontendmasters.com/courses/pro-ai/)
2. [Agent Skills — DeepLearning.AI](https://learn.deeplearning.ai/courses/agent-skills-with-anthropic)
3. [ChrisWiles Showcase (integration patterns)](https://github.com/ChrisWiles/claude-code-showcase)
4. [DataCamp Hooks Tutorial](https://www.datacamp.com/tutorial/claude-code-hooks)

**Subagents**:
- `code-reviewer` (Sonnet)
- `architect-reviewer`
- `test-engineer`

---

#### Profile 9: Professional Expert (age 31-50, skill: expert)

**Slug**: `professional-expert`
**Persona**: Staff/principal engineer, CTO, or architect. Designs systems, enforces policy, manages infrastructure. Wants full automation and compliance.

**UI Configuration**:
```json
{
  "fontSize": 14,
  "fontScale": 1.0,
  "motionLevel": "full",
  "contrast": "standard",
  "touchTargetMin": 40,
  "layoutDensity": "compact",
  "theme": "dark"
}
```

**CLAUDE.md Template**: `enterprise-architect`
- Verbosity: minimal (just do it)
- Safety: policy-driven (hooks enforce rules, not instructions)
- Style: terse, technical, standards-referenced
- Target lines: 30-50 (heavy modular imports + hooks do enforcement)

**Template Content**:
```markdown
# CLAUDE.md

## Principles
- Hooks enforce all non-negotiable rules (see .claude/settings.json).
- .claude/rules/ contains all standards — no duplication here.
- Skills handle repeatable workflows.
- Subagents handle domain-specific reviews.

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Build: {{build_cmd}}
- Deploy: {{deploy_cmd}}
- Infra: {{infra_cmd}}

## Architecture
@docs/ARCHITECTURE.md

## Private overlays (local only)
@~/.claude/private/{{project_slug}}/PREFERENCES.md
```

**Rules (.claude/rules/)**:
- `code-style.md`, `testing.md`, `security.md`, `deployment.md`, `api-conventions.md`
- `compliance.md` — regulatory requirements
- `incident-response.md` — runbook references

**Skill Bundle**:
- `compound-engineering`, `build-feature`, `simplify`, `prd`
- `update-claude-md` (self-improving)
- `refactor-agent` (code health)

**MCP Servers**: Full suite — filesystem, github, context7, playwright, postgres, firecrawl, notion, slack, brave-search, 21st-dev-magic, datadog, e2b, perplexity

**Hooks**: Full lifecycle — PreToolUse (security gate), PostToolUse (format + test), Stop (session summary), SessionStart (load context), PreCompact (save critical state)

**Learning Path**:
1. [MCP: Build Rich-Context AI Apps](https://learn.deeplearning.ai/courses/mcp-build-rich-context-ai-apps-with-anthropic)
2. [Code w/ Claude Conference](https://anthropic.com/events/code-with-claude-2025)
3. [alirezarezvani Self-Improving Agent](https://github.com/alirezarezvani/claude-skills)
4. [disler/hooks-mastery (all 13 events)](https://github.com/disler/claude-code-hooks-mastery)

**Subagents**: Full fleet — code-reviewer, architect-reviewer, security-auditor, test-engineer, performance-engineer, debugger, deployment-engineer

---

#### Profile 10: Pre-Senior Beginner (age 51-65, skill: beginner)

**Slug**: `pre-senior-beginner`
**Persona**: Late-career professional exploring tech, or non-technical executive wanting to understand AI tools. Larger text, explicit undo instructions, patient pace.

**UI Configuration**:
```json
{
  "fontSize": 18,
  "fontScale": 1.1,
  "motionLevel": "reduced",
  "contrast": "enhanced",
  "touchTargetMin": 48,
  "layoutDensity": "spacious",
  "theme": "light"
}
```

**CLAUDE.md Template**: `gentle-start`
- Verbosity: maximum (every step explained, every action confirmed)
- Safety: maximum
- Style: warm, patient, jargon-free
- Target lines: 40-55

**Template Content**:
```markdown
# CLAUDE.md — {{project_name}}

## How to work with me
- Use plain, everyday language.
- Explain each step before doing it.
- Wait for my OK before making changes.
- After each change, tell me exactly what happened.
- Always tell me how to undo what you just did.
- One thing at a time — don't rush.

## Important safety rules
- Never delete my files without asking.
- Never run anything that could damage my computer.
- Keep all my private information safe.
- If you're not sure, ask me first — it's always OK to ask.

## My project
- Name: {{project_name}}
- What it does: {{project_description}}

## How to run things
- Start: {{run_cmd}}
- Test: {{test_cmd}}
```

**Skill Bundle**:
- `senior-explain` (accessible language)

**MCP Servers**:
- `filesystem` (read-only, single directory)
- `memory` (remember preferences)

**Hooks**: Maximum protection — block all destructive commands, block sudo, block unrecognized commands

**Learning Path**:
1. [Sabrina's 90-min Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners)
2. [Official Best Practices](https://code.claude.com/docs/en/best-practices)

**Subagents**: None

---

#### Profile 11: Pre-Senior Intermediate (age 51-65, skill: intermediate)

**Slug**: `pre-senior-intermediate`
**Persona**: Experienced professional with tech skills — IT manager, analyst, or self-taught developer. Comfortable with tools but prefers structured workflows.

**UI Configuration**:
```json
{
  "fontSize": 17,
  "fontScale": 1.05,
  "motionLevel": "reduced",
  "contrast": "enhanced",
  "touchTargetMin": 48,
  "layoutDensity": "comfortable",
  "theme": "light"
}
```

**CLAUDE.md Template**: `structured-workflow`
- Verbosity: medium-high (explain decisions, checklist approach)
- Safety: high
- Style: organized, step-by-step
- Target lines: 60-80

**Template Content**:
```markdown
# CLAUDE.md — {{project_name}}

## Workflow preferences
- Work through tasks as a checklist — one step at a time.
- Confirm with me before making significant changes.
- Provide clear summaries after completing each task.
- If something goes wrong, explain what happened and how to fix it.

## Safety
- Don't modify configuration files without asking.
- Don't run destructive operations.
- Keep credentials and sensitive data secure.

## Project
- Name: {{project_name}}
- Stack: {{stack}}
- Description: {{project_description}}

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Build: {{build_cmd}}

## Documentation
@docs/ARCHITECTURE.md
```

**Skill Bundle**:
- `update-claude-md`
- `git-commit-helper`
- `simplify`
- `excel-analysis` (familiar tool)
- `email-composer`

**MCP Servers**:
- `filesystem`, `github`, `context7`
- `notion` (organized project management)
- `memory`

**Hooks**: Destructive guard + post-edit notification

**Learning Path**:
1. [Frontend Masters Pro AI Setup](https://frontendmasters.com/courses/pro-ai/)
2. [CLAUDE.md Best Practices — Builder.io](https://www.builder.io/blog/claude-md-guide)
3. [DataCamp Hooks Tutorial](https://www.datacamp.com/tutorial/claude-code-hooks)

**Subagents**:
- `code-reviewer` (Haiku, lightweight)

---

#### Profile 12: Pre-Senior Expert (age 51-65, skill: expert)

**Slug**: `pre-senior-expert`
**Persona**: Veteran technologist or domain expert. Deep knowledge in their field, strong opinions about tools. Wants privacy-first, full control, enterprise-grade.

**UI Configuration**:
```json
{
  "fontSize": 16,
  "fontScale": 1.0,
  "motionLevel": "reduced",
  "contrast": "enhanced",
  "touchTargetMin": 44,
  "layoutDensity": "comfortable",
  "theme": "auto"
}
```

**CLAUDE.md Template**: `veteran-expert`
- Same as `enterprise-architect` but with enhanced contrast, slightly higher verbosity
- Safety: policy-driven
- Target lines: 40-60

**Skill Bundle**: Same as professional-expert
**MCP Servers**: Full suite with privacy emphasis (local servers preferred over remote)
**Hooks**: Full lifecycle
**Subagents**: Full fleet

**Learning Path**:
1. [MCP: Build Rich-Context AI Apps](https://learn.deeplearning.ai/courses/mcp-build-rich-context-ai-apps-with-anthropic)
2. [alirezarezvani Self-Improving Agent](https://github.com/alirezarezvani/claude-skills)
3. [Code w/ Claude Conference](https://anthropic.com/events/code-with-claude-2025)

---

#### Profile 13: Senior Beginner (age 65+, skill: beginner)

**Slug**: `senior-beginner`
**Persona**: Retired or semi-retired adult exploring technology. May have limited computer experience. Needs the most accessible, patient, safe experience possible.

**UI Configuration**:
```json
{
  "fontSize": 20,
  "fontScale": 1.2,
  "motionLevel": "minimal",
  "contrast": "high",
  "touchTargetMin": 56,
  "layoutDensity": "spacious",
  "theme": "light",
  "reducedMotion": true,
  "hapticFeedback": true
}
```

**CLAUDE.md Template**: `senior-safe`
- Verbosity: maximum (every single step, confirm before and after)
- Safety: maximum (most restrictive hooks, read-only by default)
- Style: warm, encouraging, never condescending, extremely simple
- Target lines: 30-40

**Template Content**:
```markdown
# CLAUDE.md

## How to help me
- Use simple, everyday words.
- Do one small thing at a time.
- Always ask before changing anything.
- After each step, tell me what happened in plain language.
- Show me how to undo anything you do.
- Be patient — I'm learning.

## Safety (most important)
- Never change or delete my files without asking first.
- Never run anything that could harm my computer.
- Keep everything safe and private.
- When in doubt, always ask me.

## My project
- Name: {{project_name}}
- What it does: {{project_description}}
```

**Skill Bundle**:
- `senior-explain` (maximum accessibility)

**MCP Servers**:
- `memory` (remember preferences across sessions)
- `filesystem` (read-only, single project directory)

**Hooks**: Maximum protection — deny all potentially destructive operations

**Learning Path**:
1. [Sabrina's 90-min Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners) (start here)

**Subagents**: None

---

#### Profile 14: Senior Intermediate (age 65+, skill: intermediate)

**Slug**: `senior-intermediate`
**Persona**: Experienced older adult who has used computers extensively — retired IT professional, lifelong hobbyist programmer, or technical writer. Comfortable with tools but values clarity and safety.

**UI Configuration**:
```json
{
  "fontSize": 18,
  "fontScale": 1.15,
  "motionLevel": "reduced",
  "contrast": "high",
  "touchTargetMin": 52,
  "layoutDensity": "spacious",
  "theme": "light",
  "reducedMotion": true
}
```

**CLAUDE.md Template**: `confident-senior`
- Verbosity: medium (explain key decisions, skip obvious stuff)
- Safety: high
- Style: respectful, organized
- Target lines: 50-70

**Template Content**:
```markdown
# CLAUDE.md — {{project_name}}

## Working style
- Explain your reasoning for non-obvious decisions.
- Work methodically — complete one task before starting the next.
- Run tests after making changes.
- Provide a summary with undo steps when done.

## Safety
- Don't modify system files, credentials, or backups.
- Don't run destructive commands without explicit permission.
- Prefer safe, reversible operations.

## Project
- Name: {{project_name}}
- Stack: {{stack}}
- Description: {{project_description}}

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
```

**Skill Bundle**:
- `update-claude-md`
- `git-commit-helper`
- `senior-explain`
- `simplify`

**MCP Servers**:
- `filesystem`, `github` (read-focused), `context7`, `memory`

**Hooks**: Destructive guard + post-change notification

**Learning Path**:
1. [Sabrina's Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners)
2. [CLAUDE.md Guide — Builder.io](https://www.builder.io/blog/claude-md-guide)
3. [Skills vs Commands vs Subagents](https://www.youngleaders.tech/p/claude-skills-commands-subagents-plugins)

**Subagents**:
- `code-reviewer` (Haiku, lightweight)

---

#### Profile 15: Senior Expert (age 65+, skill: expert)

**Slug**: `senior-expert`
**Persona**: Retired senior engineer, professor, or domain expert with deep technical knowledge. Values privacy, control, and efficiency. Has strong preferences and wants the system to respect them.

**UI Configuration**:
```json
{
  "fontSize": 17,
  "fontScale": 1.1,
  "motionLevel": "reduced",
  "contrast": "enhanced",
  "touchTargetMin": 48,
  "layoutDensity": "comfortable",
  "theme": "auto",
  "reducedMotion": true
}
```

**CLAUDE.md Template**: `veteran-privacy`
- Same capability as `enterprise-architect` with privacy-first defaults
- Enhanced contrast and larger text
- Local-only MCP servers preferred
- Private vault enabled by default

**Template Content**:
```markdown
# CLAUDE.md

## Principles
- Hooks enforce all critical rules.
- .claude/rules/ contains standards.
- Skills handle repeatable workflows.
- Privacy is non-negotiable — keep data local.

## Commands
- Install: {{install_cmd}}
- Dev: {{dev_cmd}}
- Test: {{test_cmd}}
- Build: {{build_cmd}}

## Architecture
@docs/ARCHITECTURE.md

## Private overlays
@~/.claude/private/{{project_slug}}/PREFERENCES.md
@~/.claude/private/{{project_slug}}/SECRETS_HANDLING.md
```

**Skill Bundle**: Same as professional-expert
**MCP Servers**: Full suite, preference for local over remote
**Hooks**: Full lifecycle
**Subagents**: Full fleet

**Learning Path**:
1. [MCP Course — DeepLearning.AI](https://learn.deeplearning.ai/courses/mcp-build-rich-context-ai-apps-with-anthropic)
2. [Agent Skills — DeepLearning.AI](https://learn.deeplearning.ai/courses/agent-skills-with-anthropic)
3. [Code w/ Claude Conference](https://anthropic.com/events/code-with-claude-2025)

---

## 3. CLAUDE.md Analyzer

### 3.1 Upload Interface

Users can:
- **Drag and drop** a CLAUDE.md file
- **Paste** content directly
- **Connect** to a Git repo and pull CLAUDE.md + .claude/ directory
- **Import** from URL (GitHub raw file URL)

### 3.2 Analysis Engine — 12 Scoring Criteria

| # | Criterion | Weight | Pass Condition |
|---|-----------|--------|---------------|
| 1 | **Line count** | 15% | <200 lines (CLAUDE.md), <80 lines (project-level) |
| 2 | **Structure** | 10% | Has clear markdown headers, organized sections |
| 3 | **Specificity** | 12% | Contains concrete commands (not "run tests" but actual command) |
| 4 | **Safety rules** | 12% | Has explicit safety/protection section |
| 5 | **Build commands** | 8% | Has install, dev, test, lint commands defined |
| 6 | **Code style** | 5% | Defines or delegates to linter/rules file |
| 7 | **Modular imports** | 10% | Uses @imports or .claude/rules/ (not monolithic) |
| 8 | **No secrets** | 10% | No API keys, passwords, tokens in plaintext |
| 9 | **No bloat** | 8% | No contradictory rules, no redundant sections |
| 10 | **Skills/subagents** | 3% | References or recommends appropriate skills |
| 11 | **Hook enforcement** | 3% | Critical rules enforced via hooks (not just instructions) |
| 12 | **MCP configuration** | 4% | MCP servers configured and scoped appropriately |

### 3.3 Report Output

**Score**: Letter grade (A+ through F) + percentage + radar chart

**Sections**:
- **Pros** (green) — What's working well, with specific line references
- **Cons** (red) — Issues found, with severity (critical/warning/info)
- **Suggestions** (blue) — Actionable improvements, each with:
  - Description of what to change
  - Before/after preview
  - One-click "Apply" button
  - Checkbox for batch selection

### 3.4 Select & Apply Workflow

1. User reviews suggestions
2. Checks boxes next to desired suggestions (or "Select All")
3. Clicks "Preview Changes" → sees unified diff
4. Clicks "Apply" → changes are applied to the CLAUDE.md
5. Can download result or push to Git

### 3.5 Mass Record Update

For users managing multiple files (.claude/rules/, skills, hooks):

1. **Table view** — all records listed with columns: file, type, status, last modified, score
2. **Multi-select** — checkboxes on each row
3. **Bulk actions bar** appears when items selected:
   - "Analyze Selected" — run analyzer on all
   - "Apply All Suggestions" — auto-apply passing suggestions
   - "Update Template" — switch to a different profile template
   - "Export Bundle" — download as .zip
   - "Delete Selected" — with confirmation

### 3.6 Integration with Profile System

When a user uploads their CLAUDE.md:
1. Analyzer detects their current "profile level" from the content
2. Suggests a matching ClawCoder profile
3. Shows gap analysis: "Your config is closest to `young-adult-intermediate` but is missing: hooks, modular rules, MCP config"
4. Offers one-click upgrade to the full profile bundle

---

## 4. Data Model (PostgreSQL)

### Profile table
```sql
CREATE TABLE profiles (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug TEXT UNIQUE NOT NULL,
  age_group TEXT NOT NULL CHECK (age_group IN ('teen', 'young_adult', 'professional', 'pre_senior', 'senior')),
  skill_level TEXT NOT NULL CHECK (skill_level IN ('beginner', 'intermediate', 'expert')),
  display_name TEXT NOT NULL,
  persona_description TEXT,
  ui_config JSONB NOT NULL,
  template_slug TEXT NOT NULL,
  skill_bundle JSONB NOT NULL DEFAULT '[]',
  mcp_servers JSONB NOT NULL DEFAULT '[]',
  hooks_config JSONB NOT NULL DEFAULT '{}',
  subagents JSONB NOT NULL DEFAULT '[]',
  learning_path JSONB NOT NULL DEFAULT '[]',
  onboarding_config JSONB NOT NULL DEFAULT '{}',
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

### Analysis results table
```sql
CREATE TABLE analyses (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  input_content TEXT NOT NULL,
  input_source TEXT, -- 'upload', 'paste', 'git', 'url'
  overall_score NUMERIC(5,2),
  letter_grade TEXT,
  criteria_scores JSONB NOT NULL, -- {criterion: {score, max, findings[]}}
  pros JSONB NOT NULL DEFAULT '[]',
  cons JSONB NOT NULL DEFAULT '[]',
  suggestions JSONB NOT NULL DEFAULT '[]',
  detected_profile_slug TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

### Applied suggestions table
```sql
CREATE TABLE applied_suggestions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  analysis_id UUID REFERENCES analyses(id),
  suggestion_index INT NOT NULL,
  applied_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  result_content TEXT -- the output after applying
);
```

---

## 5. Marketplace Integration

### Skill Discovery by Profile

Each profile has a `skill_bundle` that references real marketplace skills. The app queries:
1. [SkillHub](https://skillhub.club) (34,800+ skills) via `npx @skill-hub/cli`
2. [OpenClaw/ClawHub](https://github.com/VoltAgent/awesome-openclaw-skills) (5,211 curated) via `clawhub install`
3. [Anthropic Official](https://github.com/anthropics/claude-plugins-official) via `/plugin install`
4. [vercel-labs/skills](https://github.com/vercel-labs/skills) via `npx skills add` (cross-agent)

### Trust Gating

Before any skill/MCP/plugin is recommended:
1. Check against blocklist (mcp-remote CVE, postmark-mcp, etc.)
2. Verify source repo exists and is maintained
3. Check star count / download count
4. Flag if it fetches untrusted content (prompt injection risk)
5. Require explicit user approval before installation

---

## 6. Technology Stack

- **Frontend**: Next.js 15 (App Router) + Tailwind CSS + Framer Motion
- **Backend**: Next.js API routes + PostgreSQL
- **Auth**: NextAuth.js
- **State**: Zustand (client) + PostgreSQL (server)
- **Deployment**: Vercel or self-hosted (this server)
- **Package**: npm distribution for CLI companion

---

## 7. Ecosystem References

### Skills & Agents
- [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — 30.2k stars, master directory
- [vercel-labs/skills](https://github.com/vercel-labs/skills) — Cross-agent installation CLI
- [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) — 205 skills, self-improving agent
- [anthropics/skills](https://github.com/anthropics/skills) — Official Anthropic reference
- [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) — 127+ subagents
- [0xfurai/claude-code-subagents](https://github.com/0xfurai/claude-code-subagents) — 100+ production subagents
- [ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase) — Full integration example
- [disler/claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery) — All 13 hook events

### MCP Servers
- [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — 82.9k stars, 1200+ servers
- [Official MCP Registry](https://registry.modelcontextprotocol.io/)
- [Context7](https://github.com/upstash/context7) — #1 most installed
- [21st.dev Magic](https://github.com/21st-dev/magic-mcp) — UI generation, 4.4k stars
- [Playwright MCP](https://github.com/microsoft/playwright-mcp) — Microsoft, browser automation
- [Firecrawl MCP](https://github.com/firecrawl/firecrawl-mcp-server) — Web scraping

### Learning Resources
- [Agent Skills — DeepLearning.AI](https://learn.deeplearning.ai/courses/agent-skills-with-anthropic)
- [MCP Course — DeepLearning.AI](https://learn.deeplearning.ai/courses/mcp-build-rich-context-ai-apps-with-anthropic)
- [Frontend Masters Pro AI](https://frontendmasters.com/courses/pro-ai/)
- [Sabrina's 90-min Tutorial](https://www.sabrina.dev/p/claude-code-full-course-for-beginners)
- [Anthropic Skilljar Training](https://anthropic.skilljar.com/introduction-to-agent-skills)
- [agentskills.io Specification](https://agentskills.io/specification)

### Marketplaces
- [SkillHub](https://skillhub.club) — 34,800+ skills
- [OpenClaw](https://openclawskill.ai) — 13,729 skills
- [PulseMCP](https://www.pulsemcp.com) — 12,370+ MCP servers
- [FastMCP](https://fastmcp.me) — 19,922+ MCP servers

### Security References
- [AgentSeal MCP Security Findings](https://agentseal.org/blog/mcp-server-security-findings) — 66% of servers had issues
- [mcp-remote CVE-2025-6514](https://snyk.io/blog/malicious-mcp-server-on-npm-postmark-mcp-harvests-emails/) — CVSS 9.6
- [Prompt Injection via MCP — Simon Willison](https://simonwillison.net/2025/Apr/9/mcp-prompt-injection/)