Type of Change

• 🔌 New plugin submission

Description

Summary:
Adds prettier-markdown-hook, a productivity plugin that automatically formats markdown files with prettier when Claude stops responding. The hook runs asynchronously in the background, ensuring consistent markdown formatting without interrupting workflow.

Motivation:

• Eliminate manual prettier formatting for markdown files
• Maintain consistent formatting across all Claude Code workspaces
• Enable organization/path-based exclusions for mixed-repo environments
• Provide configurable automation with zero-config defaults

Related Issues:
N/A (new plugin submission)

Security

• Related alerts: None
• Impact assessment: None

Plugin Details

Plugin Name: prettier-markdown-hook
Category: productivity
Version: 1.0.0
Keywords: prettier, markdown, formatting, automation, hook, stop, git, conventional-commits

Components Included:

• Hooks (1 - Stop hook)
• Scripts (1 - format-markdown.sh)
• Commands
• Agents
• MCP servers

Dependencies:

• prettier (2.0+) - Markdown formatter
• jq (1.6+) - JSON config parser
• git (1.8.5+) - Version control

Checklist

For All PRs

• I have read the CONTRIBUTING.md guidelines
• My code follows the project's style and conventions
• I have performed a self-review of my code
• I have commented my code where necessary
• My changes generate no new warnings or errors
• Documentation has been updated (comprehensive README.md)
• CodeQL passes; no new code scanning alerts (will be verified by CI)
• No high/critical Dependabot alerts introduced

For Plugin Submissions/Updates

• Plugin has valid .claude-plugin/plugin.json with all required fields
• plugin.json validated with jq empty plugin.json
• README.md is comprehensive with installation, usage, and examples
• LICENSE file is included (MIT)
• All shell scripts are executable (chmod +x scripts/*.sh)
• No hardcoded secrets, API keys, or credentials
• Marketplace.json has been updated with plugin entry (via sync-marketplace)
• Plugin tested locally with test marketplace installation
• Commands include YAML frontmatter (N/A - no commands)
• Agents include YAML frontmatter (N/A - no agents)
• Hooks use ${CLAUDE_PLUGIN_ROOT} for portable paths
• All JSON files are valid (jq empty *.json)

Testing Evidence

Test Environment:

• OS: macOS 14.6 (Darwin 24.6.0)
• Claude Code Version: Latest
• Node Version: 22.17.0

Test Commands Run:

# Local marketplace installation
mkdir -p ~/test-marketplace-prettier/.claude-plugin
cat > ~/test-marketplace-prettier/.claude-plugin/marketplace.json << 'EOFTEST'
{
  "name": "test-prettier",
  "owner": {"name": "Terry Li", "email": "[email protected]"},
  "plugins": [{
    "name": "prettier-markdown-hook",
    "source": "/tmp/prettier-marketplace-plugin-test/prettier-markdown-hook",
    "version": "1.0.0",
    "category": "productivity"
  }]
}
EOFTEST

# Validation
./scripts/validate-all-plugins.sh plugins/productivity/prettier-markdown-hook/
node scripts/sync-marketplace.cjs
jq empty .claude-plugin/marketplace.json
jq empty .claude-plugin/marketplace.extended.json

Test Results:

• ✅ All validation checks passed (JSON, permissions, structure, security)
• ✅ Marketplace sync successful (marketplace.json auto-generated)
• ✅ Script permissions verified (rwxr-xr-x on format-markdown.sh)
• ✅ Security scan clean (no secrets, no dangerous commands)
• ✅ JSON syntax valid for all .json files
• ✅ Hook configuration uses proper path variables (${CLAUDE_PLUGIN_ROOT})

Edge Cases Tested:

• Works with minimal configuration (zero-config default)
• Handles errors gracefully (missing dependencies → log + exit)
• Works across different platforms (macOS tested, Linux/Git Bash compatible)
• Performance is acceptable (async background processing, <10ms hook exit)
• Security considerations addressed (no hardcoded secrets, env var support)

Breaking Changes

• No

Screenshots / Recordings

N/A (hook runs in background, outputs to log file)

Log File Location: ~/.local/state/prettier-hook/prettier-hook.log

Performance Impact

• No performance impact (async fire-and-forget execution, <10ms hook exit time)

Security Considerations

Automated Security Scans

• No hardcoded secrets (API keys, passwords, tokens)
• No AWS keys, private keys, or credentials detected
• No destructive commands (rm -rf /, data deletion)
• No eval() or command injection risks
• No suspicious curl/wget to IP addresses
• No base64 obfuscation detected
• All URLs use HTTPS (N/A - no external URLs)
• No URL shorteners (N/A - no URLs)

Manual Security Review

• Prompt Injection Protection: No hidden instructions in markdown files
• Data Privacy: No data exfiltration (all processing local)
• Permission Audit: Requires git, prettier, jq (standard dev tools)
• Clear Intent: README clearly explains hook behavior
• Input Validation: Config file validated with jq
• Error Handling: All errors logged, no sensitive data in logs
• Dependencies: All dependencies are standard OSS tools

Testing

• Tested in isolated environment before submission
• No unexpected side effects observed
• Graceful error handling for edge cases (missing deps, invalid config)
• Works as documented in README

Rollback Plan

Plugin can be removed via:

/plugin uninstall prettier-markdown-hook

Hook is isolated (Stop event only), no system-wide changes.

Additional Notes

Architecture Decision:

• Plugin based on personal automation (v2.0.0) refactored for marketplace distribution
• Follows hooks-only architecture (no commands/agents complexity)
• Source of truth: format-markdown.sh (single-file deployment)
• Cross-platform compatible (macOS, Linux, Windows Git Bash)

References:

• ADR-0003: Prettier Marketplace Plugin Creation
• Plan: docs/plan/0003-prettier-marketplace-plugin-creation/plan.yaml
• Source automation: v2.0.0 (from claude-config v8.0.0 release)
• Test commit: da0c186

Configuration Example:

{
  "excludeOrgs": ["Eon-Labs", "CompanyOrg"],
  "excludePaths": ["docs/archive", "legacy"],
  "logDir": null
}

Features:

1. Zero-config defaults (works immediately after installation)
2. JSON-based configuration with jq parser
3. Organization exclusions (skip specific GitHub orgs)
4. Path exclusions (skip specific directories/patterns)
5. AI commit messages (opt-in via environment variable)
6. XDG-compliant paths (~/.local/state/prettier-hook)
7. Fire-and-forget async execution
8. Comprehensive error logging

By submitting this PR, I confirm:

• I have the right to submit this code under the project's license (MIT)
• I understand my contributions will be publicly available
• I agree to the project's Code of Conduct