docs(rules): Add commit-style and naming-conventions rules

- Add rules/commit-style.md: Conventional commits format guide
- Add rules/naming-conventions.md: Component naming patterns
- Update docs/PLAN.md with strategic enhancement roadmap
- Bump plugin to v1.3.0, now with 4 rules

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-mods",
-  "version": "1.2.0",
-  "description": "Custom commands, skills, and agents for Claude Code - session continuity, 23 expert agents, 30 skills, modern CLI tools",
+  "version": "1.3.0",
+  "description": "Custom commands, skills, and agents for Claude Code - session continuity, 23 expert agents, 30 skills, 4 rules, modern CLI tools",
   "author": "0xDarkMatter",
   "repository": "https://github.com/0xDarkMatter/claude-mods",
   "license": "MIT",
@@ -86,6 +86,8 @@
     ],
     "rules": [
       "rules/cli-tools.md",
+      "rules/commit-style.md",
+      "rules/naming-conventions.md",
       "rules/thinking.md"
     ],
     "output-styles": [

docs/PLAN.md

@@ -1,108 +1,172 @@
-# Project Plan: claude-mods
+# Claude-Mods: Project Plan & Roadmap
 
 **Goal**: A centralized repository of custom Claude Code commands, agents, and skills that enhance Claude Code's native capabilities with persistent session state, specialized expert agents, and streamlined workflows.
 
 **Created**: 2025-11-27
-**Last Updated**: 2025-11-27
-**Status**: In Progress
-
-## Context
-
-Claude Code is powerful but has gaps:
-- TodoWrite state doesn't persist between sessions (by design)
-- Plan Mode thinking is lost when sessions end
-- No built-in specialized expert agents for specific tech stacks
-- No easy way to share custom configurations across machines
-
-This project bridges those gaps with git-trackable, shareable extensions.
-
-## Approach
-
-Build modular, composable tools that:
-1. Integrate seamlessly with native Claude Code features
-2. Persist important state to git-trackable files
-3. Provide specialized expertise via custom agents
-4. Work across machines via git sync
-
-## Implementation Steps
-
-### Completed
-- [x] Session continuity commands (`/plan --save`, `/plan --load`)
-  - Completed: 2025-11-27
-  - Persists TodoWrite state to `.claude/session-cache.json`
-  - Human-readable progress in `.claude/claude-progress.md`
-
-- [x] Plan persistence command (`/plan`)
-  - Completed: 2025-11-27
-  - Captures Plan Mode state to `docs/PLAN.md`
-  - Auto-captures internal state on every invocation
-
-- [x] Development workflow commands
-  - `/review` - Code review with configurable depth
-  - `/test` - Test generation with framework detection
-  - `/explain` - Deep code explanation
-
-- [x] Agent genesis system (`/agent-genesis`)
-  - Completed: 2025-11-27
-  - Generates expert agent prompts from templates
-
-- [x] Expert agents collection
-  - TypeScript, React, Vue, Cypress
-  - Python, JavaScript, SQL, Postgres
-  - Laravel, Payload CMS, Astro
-  - AWS Fargate, Cloudflare Workers
-  - And more...
-
-- [x] Installation scripts
-  - `install.sh` for Unix/macOS
-  - `install.ps1` for Windows
-
-### In Progress
-- [ ] Documentation and examples
-  - Started: 2025-11-27
-  - Need usage examples for each command
-  - Need agent selection guide
-
-### Pending
-- [ ] More expert agents
-  - Next.js expert
-  - Docker/Kubernetes expert
-  - GraphQL expert
-  - Testing frameworks (Jest, Vitest, Playwright)
-
-- [ ] Enhanced `/plan` features
-  - Automatic progress tracking from git commits
-  - Integration with GitHub Issues
-  - Milestone tracking
-
-- [ ] Skill expansions
-  - Code statistics skill
-  - Dependency analysis skill
-  - Security audit skill
-
-- [ ] Cross-project sync
-  - Settings sync across machines
-  - Team sharing capabilities
+**Last Updated**: 2025-12-22
+**Status**: Active Development
 
-## Open Questions
+---
+
+## Current Inventory
+
+| Component | Count | Notes |
+|-----------|-------|-------|
+| Agents | 23 | Domain experts (Python, Go, Rust, React, etc.) |
+| Skills | 30 | Pattern libraries (Python deep, others emerging) |
+| Commands | 11 | Workflow automation |
+| Rules | 4 | CLI tools, thinking, commit style, naming |
+| Output Styles | 1 | Vesper personality |
+| Hooks | 0 | Config examples only |
+
+---
+
+## Completed Milestones
+
+### Core Infrastructure
+- [x] Session continuity (`/plan --save`, `/plan --load`)
+- [x] Plan persistence to `docs/PLAN.md`
+- [x] Agent genesis system (`/spawn`)
+- [x] Installation scripts (Unix + Windows)
+
+### Expert Agents (23)
+- [x] Languages: Python, TypeScript, JavaScript, Go, Rust, SQL, Bash
+- [x] Frontend: React, Vue, Astro
+- [x] Backend: Laravel, PayloadCMS, CraftCMS
+- [x] Infrastructure: AWS Fargate, Cloudflare, Wrangler
+- [x] Testing: Cypress, Playwright
+- [x] Databases: PostgreSQL, SQL patterns
+- [x] Specialized: Claude-architect, Project-organizer
+
+### Skills (30)
+- [x] Python patterns (8): async, cli, database, env, fastapi, observability, pytest, typing
+- [x] Claude Code internals: debug, headless, hooks, templates
+- [x] Workflows: git, data-processing, structural-search, task-runner
+- [x] Patterns: REST, SQL, security, testing, tailwind
+
+### Commands (11)
+- [x] Planning: `/plan`, `/sync`, `/atomise`
+- [x] Development: `/review`, `/testgen`, `/explain`
+- [x] Multi-model: `/conclave`, `/spawn`
+- [x] Utilities: `/pulse`, `/setperms`, `/archive`
+
+### Documentation
+- [x] ARCHITECTURE.md - Extension system guide with authority levels
+- [x] README.md - Project overview and usage
+- [x] AGENTS.md - Quick reference
+
+---
+
+## Enhancement Roadmap
+
+### Tier 1: High Impact, Low Effort
+
+#### Output Style Variations
+
+| Style | Personality | Best For |
+|-------|-------------|----------|
+| **Vesper** | Sophisticated British wit | General work (exists) |
+| **Spartan** | Minimal, bullet-points only | Quick tasks |
+| **Mentor** | Patient, educational | Learning, onboarding |
+| **Executive** | High-level summaries | Non-technical stakeholders |
+
+#### Rules Expansion
+
+| Rule | Purpose | Status |
+|------|---------|--------|
+| `cli-tools.md` | Modern CLI preferences | Done |
+| `thinking.md` | Extended thinking triggers | Done |
+| `commit-style.md` | Conventional commits format | Done |
+| `naming-conventions.md` | Component naming patterns | Done |
+| `code-review.md` | Review checklist | Future |
+| `testing-philosophy.md` | Coverage expectations | Future |
+
+#### Hook Implementations
+
+| Hook | Purpose |
+|------|---------|
+| `pre-commit-lint.sh` | Run linter before committing |
+| `post-edit-format.sh` | Auto-format after edits |
+| `dangerous-cmd-warn.sh` | Confirm destructive commands |
+
+### Tier 2: High Impact, Medium Effort
+
+#### Agent Gaps
 
-- [ ] Should agents auto-update from a central registry?
-- [ ] How to handle agent versioning?
-- [ ] Should there be a "recommended agents" list per project type?
+| Agent | Why It Matters |
+|-------|----------------|
+| `docker-expert` | Containerisation is ubiquitous |
+| `github-actions-expert` | CI/CD complexity |
+| `nextjs-expert` | App Router specifics |
+| `testing-architect` | Strategy decisions |
+| `api-design-expert` | OpenAPI, versioning |
 
-## Success Criteria
+#### Command Gaps
 
-- [ ] All commands documented with examples
-- [ ] Installation tested on Windows, macOS, Linux
-- [ ] At least 20 expert agents covering major tech stacks
-- [ ] Session continuity works reliably across sessions
-- [ ] Community contributions via PRs
+| Command | Purpose |
+|---------|---------|
+| `/debug` | Systematic debugging workflow |
+| `/migrate` | Framework/version upgrades |
+| `/refactor` | Safe refactoring |
+| `/secure` | Security audit checklist |
 
-## Notes
+#### Skill Parity
 
-- Based on patterns from Anthropic's "Building Effective Agents" article
-- TodoWrite non-persistence is intentional (confirmed via claude-code-guide)
-- Plan Mode also doesn't persist (this project fixes that)
+Languages needing Python-level depth:
+- `typescript-patterns/`
+- `go-patterns/`
+- `rust-patterns/`
+
+### Tier 3: Strategic Expansions
+
+- **Template System**: Project scaffolding via `/scaffold`
+- **MCP Server Catalog**: Curated high-value servers
+- **Feedback System**: Track tool effectiveness
+
+---
+
+## Priority Matrix
+
+```
+                    IMPACT
+                    High         Low
+            +-----------+-----------+
+       Low  | Output    | Templates |
+            | Styles    |           |
+    EFFORT  | Rules     | MCP       |
+            | Hooks     | Catalog   |
+            +-----------+-----------+
+       High | Agent     | Analytics |
+            | Gaps      |           |
+            | Commands  | Lang      |
+            |           | Parity    |
+            +-----------+-----------+
+```
 
 ---
-*Plan managed by `/plan` command. Last captured: 2025-11-27*
+
+## Immediate Next Steps
+
+- [x] Create `rules/commit-style.md`
+- [x] Create `rules/naming-conventions.md`
+- [ ] Create Spartan output style
+- [ ] Add docker-expert agent
+- [ ] Implement `/debug` command
+
+---
+
+## Open Questions
+
+- Should agents auto-update from a central registry?
+- How to handle agent versioning?
+- Should there be a "recommended agents" list per project type?
+
+---
+
+## Guiding Principle
+
+> The best enhancements solve problems you've already felt. Follow the pain.
+
+---
+
+*Plan managed by `/plan` command. Last updated: 2025-12-22*

rules/commit-style.md

@@ -0,0 +1,115 @@
+# Commit Style Guide
+
+Conventional Commits format for all commits in this project.
+
+## Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+## Types
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `feat` | New feature or capability | `feat: Add docker-expert agent` |
+| `fix` | Bug fix | `fix: Correct skill routing in python-expert` |
+| `docs` | Documentation only | `docs: Update ARCHITECTURE.md` |
+| `refactor` | Code change (neither fix nor feat) | `refactor: Streamline agent frontmatter` |
+| `chore` | Maintenance, dependencies, config | `chore: Bump plugin version to 1.3.0` |
+| `style` | Formatting, whitespace (no logic) | `style: Fix markdown table alignment` |
+| `test` | Adding or updating tests | `test: Add skill functional tests` |
+| `perf` | Performance improvement | `perf: Optimize skill loading` |
+
+## Scopes (Optional)
+
+| Scope | Applies To |
+|-------|------------|
+| `agents` | Files in `/agents` |
+| `skills` | Files in `/skills` |
+| `commands` | Files in `/commands` |
+| `rules` | Files in `/rules` |
+| `hooks` | Hook implementations |
+| `docs` | Documentation files |
+| `plugin` | Plugin configuration |
+
+## Rules
+
+1. **Subject line**: Max 72 characters, imperative mood ("Add" not "Added")
+2. **No period** at end of subject line
+3. **Scope is optional** but recommended for component-specific changes
+4. **Body**: Wrap at 72 characters, explain "what" and "why"
+5. **Breaking changes**: Add `BREAKING CHANGE:` in footer
+
+## Examples
+
+### Simple Feature
+
+```
+feat(agents): Add docker-expert agent
+```
+
+### Bug Fix with Context
+
+```
+fix(skills): Correct dependency resolution in python-async-patterns
+
+The depends-on field was not being parsed correctly when multiple
+dependencies were specified. Now handles arrays properly.
+```
+
+### Breaking Change
+
+```
+refactor(commands): Rename /delegate to /conclave
+
+BREAKING CHANGE: /delegate command no longer exists. Use /conclave.
+```
+
+### Documentation Update
+
+```
+docs: Add authority levels to ARCHITECTURE.md
+```
+
+### Multi-component Change
+
+```
+feat: Add Go/Rust agents, enhance setperms with AI CLIs
+
+- Add go-expert and rust-expert agents
+- Add AI CLI tools (gemini, claude, codex) to setperms
+- Add git safety rules to cli-tools
+```
+
+## Anti-patterns
+
+```
+BAD:  "Updated stuff"           - Vague, no type
+BAD:  "feat: added new agent."  - Past tense, trailing period
+BAD:  "FEAT: Add agent"         - Uppercase type
+BAD:  "feat(agents): Add the new docker expert agent for containerization"
+      - Too long (> 72 chars)
+
+GOOD: "feat(agents): Add docker-expert agent"
+```
+
+## Claude Code Integration
+
+When committing via Claude Code, these patterns apply:
+
+1. Analyze staged changes to determine appropriate type
+2. Infer scope from modified directories
+3. Generate concise, imperative subject line
+4. Add body for non-trivial changes explaining rationale
+5. Append standard footer:
+
+```
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <model> <noreply@anthropic.com>
+```

rules/naming-conventions.md

@@ -0,0 +1,195 @@
+# Naming Conventions
+
+Consistent naming patterns for all claude-mods components.
+
+## General Principles
+
+1. **kebab-case** for all file and directory names
+2. **Lowercase** always (no PascalCase, camelCase, or UPPERCASE)
+3. **Descriptive** but concise
+4. **No abbreviations** unless universally understood (API, CLI, SQL)
+
+## Component Patterns
+
+### Agents (`/agents`)
+
+```
+{domain}-expert.md
+```
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Language | `python-expert.md` | Programming languages |
+| Framework | `laravel-expert.md` | Frameworks |
+| Tool | `docker-expert.md` | Specific tools |
+| Domain | `aws-fargate-ecs-expert.md` | Compound domains |
+| Specialized | `playwright-roulette-expert.md` | Project-specific |
+
+**Frontmatter:**
+
+```yaml
+---
+name: python-expert          # Match filename (without .md)
+description: <one line>      # Concise capability summary
+model: sonnet|opus|haiku     # Recommended model
+---
+```
+
+### Skills (`/skills`)
+
+```
+{topic}-patterns/skill.md    # Pattern collections
+{tool-name}/skill.md         # Tool-specific knowledge
+```
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Language patterns | `python-async-patterns/` | Domain + "patterns" |
+| Tool knowledge | `sqlite-ops/` | Tool + operation |
+| Workflow | `git-workflow/` | Activity-focused |
+| Framework | `tailwind-patterns/` | Framework + "patterns" |
+
+**Frontmatter:**
+
+```yaml
+---
+name: python-async-patterns  # Match directory name
+description: "<trigger phrases>"
+compatibility: "<version requirements>"
+allowed-tools: "<tool list>"
+depends-on: [<skill-names>]
+related-skills: [<skill-names>]
+---
+```
+
+### Commands (`/commands`)
+
+```
+{action}.md
+```
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Single verb | `review.md` | Preferred |
+| Compound | `testgen.md` | Concatenate, no hyphens |
+| Conceptual | `atomise.md` | Abstract operations |
+
+**Frontmatter:**
+
+```yaml
+---
+description: "<one line summary with trigger phrases>"
+---
+```
+
+### Rules (`/rules`)
+
+```
+{topic}.md
+```
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Tool guidance | `cli-tools.md` | Tool + purpose |
+| Workflow | `commit-style.md` | Activity + aspect |
+| Philosophy | `thinking.md` | Conceptual guidance |
+
+**No frontmatter required** - plain markdown injected into context.
+
+### Output Styles (`/output-styles`)
+
+```
+{personality}.md
+```
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Character | `vesper.md` | Named personality |
+| Descriptor | `spartan.md` | Style type |
+| Role | `mentor.md` | Persona type |
+
+**Frontmatter:**
+
+```yaml
+---
+keep-coding-instructions: true|false
+---
+```
+
+### Hooks (`/hooks`)
+
+```
+{trigger}-{action}.sh
+```
+
+| Pattern | Example | Notes |
+|---------|---------|-------|
+| Pre-action | `pre-commit-lint.sh` | Before operation |
+| Post-action | `post-edit-format.sh` | After operation |
+| Warning | `dangerous-cmd-warn.sh` | Guardrails |
+
+## Variable Naming
+
+### Shell Scripts
+
+```bash
+# Constants: UPPER_SNAKE_CASE
+readonly PROJECT_ROOT="/path/to/root"
+readonly MAX_RETRIES=3
+
+# Variables: lower_snake_case
+local file_count=0
+local current_branch=""
+
+# Functions: lower_snake_case (verbs)
+check_prerequisites() { ... }
+run_tests() { ... }
+```
+
+### YAML Frontmatter
+
+```yaml
+# Keys: kebab-case
+name: skill-name
+depends-on: [other-skill]
+allowed-tools: "Read Write"
+
+# NOT these:
+dependsOn: [bad]      # camelCase wrong
+depends_on: [bad]     # snake_case wrong
+```
+
+### Markdown
+
+- Headers: Title Case (`## Decision Frameworks`)
+- Tables: Title Case headers, sentence case content
+- Code blocks: Language-appropriate conventions
+
+## Anti-patterns
+
+```
+BAD:  Python-Expert.md       - PascalCase
+BAD:  python_expert.md       - snake_case
+BAD:  pythonExpert.md        - camelCase
+GOOD: python-expert.md       - kebab-case
+
+BAD:  skills/PythonPatterns/ - PascalCase directory
+GOOD: skills/python-patterns/
+
+BAD:  commands/TestGen.md    - PascalCase
+GOOD: commands/testgen.md    - Concatenated lowercase
+
+BAD:  VESPER.md              - UPPERCASE
+GOOD: vesper.md              - lowercase
+```
+
+## Quick Reference
+
+| Component | Pattern | Example |
+|-----------|---------|---------|
+| Agent | `{domain}-expert.md` | `docker-expert.md` |
+| Skill | `{topic}-patterns/skill.md` | `python-async-patterns/skill.md` |
+| Command | `{action}.md` | `review.md` |
+| Rule | `{topic}.md` | `commit-style.md` |
+| Output Style | `{personality}.md` | `vesper.md` |
+| Hook | `{trigger}-{action}.sh` | `pre-commit-lint.sh` |