Add CI validation and project documentation

.github/workflows/validate.yml

@@ -0,0 +1,32 @@
+name: Validate Plugin Structure
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate JSON syntax
+        run: python3 scripts/validate_json.py
+
+      - name: Validate marketplace and plugin structure
+        run: python3 scripts/validate_marketplace.py
+
+      - name: Validate SKILL.md frontmatter
+        run: python3 scripts/validate_skills.py
+
+      - name: Validate hooks.json format
+        run: python3 scripts/validate_hooks.py
+
+      - name: Summary
+        run: |
+          echo ""
+          echo "========================================"
+          echo "  All validations passed!"
+          echo "========================================"

AGENTS.md

@@ -0,0 +1,81 @@
+# Agent Guidelines
+
+Guidelines for LLMs working on this codebase.
+
+## Project Overview
+
+This is a Claude Code plugins marketplace. It contains:
+
+- **Marketplace definition**: `.claude-plugin/marketplace.json`
+- **Plugins**: `plugins/<name>/` directories
+- **Validation scripts**: `scripts/validate_*.py`
+- **CI workflow**: `.github/workflows/validate.yml`
+
+## Key Constraints
+
+### Plugin Structure
+
+1. Each plugin needs `.claude-plugin/plugin.json` with:
+   - `name`, `description`, `version`, `author`
+
+2. Skills are auto-discovered from `skills/*/SKILL.md`
+   - Do NOT add explicit `skills` array to marketplace.json
+   - Each SKILL.md needs frontmatter with `name` and `description`
+
+3. hooks.json format is specific:
+   - Must be object keyed by event name, NOT an array
+   - Use `${CLAUDE_PLUGIN_ROOT}` for paths in commands
+
+### Validation
+
+Always run before committing:
+
+```bash
+./scripts/validate.sh
+```
+
+Or run individual validators:
+
+```bash
+python3 scripts/validate_json.py
+python3 scripts/validate_marketplace.py
+python3 scripts/validate_skills.py
+python3 scripts/validate_hooks.py
+```
+
+### Common Mistakes to Avoid
+
+1. **hooks.json as array**: Must be `{"hooks": {"EventName": [...]}}` not `{"hooks": [...]}`
+2. **Explicit skills array**: Don't add - causes path doubling
+3. **Missing plugin.json**: Each plugin needs `.claude-plugin/plugin.json`
+4. **echo for colors**: Use `printf` with `\e[0;32m` escapes in Makefiles
+
+## Testing Plugin Installation
+
+```bash
+# Add marketplace
+/plugin marketplace add jontsai/claude-plugins
+
+# Install plugin
+/plugin install researcher@jontsai
+
+# Check installation
+/plugin list
+```
+
+## File Locations
+
+| Purpose | Path |
+|---------|------|
+| Marketplace def | `.claude-plugin/marketplace.json` |
+| Plugin metadata | `plugins/<name>/.claude-plugin/plugin.json` |
+| Plugin hooks | `plugins/<name>/hooks/hooks.json` |
+| Skills | `plugins/<name>/skills/<skill>/SKILL.md` |
+| Validation | `scripts/validate_*.py` |
+| CI | `.github/workflows/validate.yml` |
+
+## Commit Guidelines
+
+- Run validation before committing
+- Use clear, descriptive commit messages
+- Squash fixup commits before merging

CLAUDE.md

@@ -0,0 +1,26 @@
+# Claude Code Instructions
+
+This file provides guidance for Claude Code when working on this repository.
+
+## Quick Reference
+
+- **[AGENTS.md](./AGENTS.md)** - Technical guidelines for LLMs working on this codebase
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution workflow and standards
+- **[TESTING.md](./TESTING.md)** - How to validate and test plugins
+
+## Before Making Changes
+
+1. Read [AGENTS.md](./AGENTS.md) for structural constraints
+2. Run `./scripts/validate.sh` after changes
+3. Follow patterns in existing plugins
+
+## Key Commands
+
+```bash
+# Validate everything
+./scripts/validate.sh
+
+# Test plugin install
+/plugin marketplace add jontsai/claude-plugins
+/plugin install researcher@jontsai
+```

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to @jontsai Claude Code Plugins
+
+Thank you for your interest in contributing!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork locally
+3. Create a feature branch: `git checkout -b my-feature`
+
+## Development Workflow
+
+### Before Committing
+
+Run the validation script to catch errors early:
+
+```bash
+./scripts/validate.sh
+```
+
+This checks:
+- JSON syntax in all `.json` files
+- Marketplace and plugin structure
+- SKILL.md frontmatter format
+- hooks.json event names
+
+### Plugin Structure
+
+Each plugin must have:
+
+```
+plugins/<plugin-name>/
+├── .claude-plugin/
+│   └── plugin.json          # Required: name, description, version, author
+├── hooks/
+│   └── hooks.json           # Optional: lifecycle hooks
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md         # Required: frontmatter with name, description
+├── scripts/                 # Optional: helper scripts
+├── LICENSE
+├── Makefile                 # Optional: install/uninstall targets
+└── README.md
+```
+
+### SKILL.md Frontmatter
+
+Every SKILL.md must have YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: What the skill does
+---
+```
+
+### hooks.json Format
+
+Hooks must be an object keyed by event name:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/my-hook.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Valid events: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `SubagentStop`, `SessionEnd`, `UserPromptSubmit`, `PermissionRequest`, `PreCompact`, `Notification`
+
+## Submitting Changes
+
+1. Ensure `./scripts/validate.sh` passes
+2. Commit with clear, descriptive messages
+3. Push to your fork
+4. Open a pull request against `main`
+
+## Code Style
+
+- Keep scripts POSIX-compatible where possible
+- Use `printf` instead of `echo` for colored output
+- Prefer readability over cleverness
+
+## Questions?
+
+Open an issue on [GitHub](https://github.com/jontsai/claude-plugins/issues).

README.md

@@ -1,58 +1,53 @@
 # @jontsai Claude Code Plugins
 
-![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugins-blueviolet?style=flat-square)
-![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
-![Plugins](https://img.shields.io/badge/Plugins-1-blue?style=flat-square)
+[![Validate](https://github.com/jontsai/claude-plugins/actions/workflows/validate.yml/badge.svg)](https://github.com/jontsai/claude-plugins/actions/workflows/validate.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 Curated Claude Code plugins for research, productivity, and development workflows.
 
-## Installation
+## Quick Start
 
 ```bash
-# Add this marketplace (one time)
+# Add marketplace (one time)
 /plugin marketplace add jontsai/claude-plugins
 
-# Install a plugin (example)
+# Install a plugin
 /plugin install researcher@jontsai
 ```
 
-**Syntax:**
-```
-/plugin install <plugin-name>@jontsai
-```
-
 ## Available Plugins
 
 | Plugin | Category | Description |
 |--------|----------|-------------|
-| [`researcher`](./plugins/researcher/) | Productivity | Create distinctive HTML one-pagers with curated aesthetics, convert to PDF |
+| [researcher](./plugins/researcher/) | Productivity | Create distinctive HTML/Markdown one-pagers with curated aesthetics, convert to PDF |
 
 ### researcher
 
 Create professional, visually striking research documents that avoid generic "AI slop" aesthetics.
 
-**Features:**
-- 5 curated aesthetic presets (Terminal, Editorial, Corporate, Industrial, Fresh)
-- Cross-platform PDF generation via headless Chromium
-- Print-optimized layouts with micro-interactions
-- Makefile for easy setup
+- **5 aesthetic presets:** Terminal, Editorial, Corporate, Industrial, Fresh
+- **Dual output:** HTML (styled) or Markdown (plaintext)
+- **Cross-platform:** macOS, Linux, Windows (WSL)
+- **PDF generation:** via headless Chromium
 
 ```bash
 /plugin install researcher@jontsai
 ```
 
-## Categories
+## Documentation
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - How to contribute
+- [TESTING.md](./TESTING.md) - Validation and testing
+- [AGENTS.md](./AGENTS.md) - Guidelines for LLMs
+
+## Contributing
 
-| Category | Description |
-|----------|-------------|
-| `productivity` | Tools for research, documentation, and workflow automation |
-| `development` | Developer tools, code generation, and IDE enhancements |
-| `learning` | Educational tools and interactive learning experiences |
+Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
 ## License
 
-MIT License - see individual plugin repositories for details.
+[MIT](LICENSE)
 
-## Author
+---
 
-**Jonathan Tsai** · [GitHub](https://github.com/jontsai) · [Website](https://jontsai.org)
+Created by [Jonathan Tsai](https://github.com/jontsai)