claude-workflow-v2 CLAUDE.md

Claude Code Development Guidelines

Team-maintained workflow document. Update frequently with new learnings.

Quick Reference

• Plugin validation: claude plugin validate
• Test locally: claude --plugin-dir ./
• Formatting: Prettier for MD/JSON, Black for Python

Development Workflow

Making Changes

1. Before editing any file:

   • Run claude plugin validate to ensure current state is valid
   • Check existing patterns in similar files

2. When adding agents (agents/*.md):

   • Copy structure from agents/orchestrator.md as template
   • Include "PROACTIVELY" in description for auto-triggering
   • Specify tools, model (opus/sonnet/haiku), and skills
   • Test trigger keywords work as expected

3. When adding skills (skills/*/SKILL.md):

   • Keep under 500 lines for optimal context usage
   • Include trigger keywords in description
   • Make content language-agnostic where possible

4. When adding hooks (hooks/*):

   • Register in hooks/hooks.json
   • Use ${CLAUDE_PLUGIN_ROOT} for paths
   • Exit codes: 0 = allow, 2 = block with message
   • Test with both success and failure cases

5. After all changes:

   • Run claude plugin validate
   • Test the specific feature with Claude Code

Code Conventions

Markdown Files

• Use YAML frontmatter for metadata
• Consistent heading hierarchy (# > ## > ###)
• Code blocks with language specifiers

Python Hooks

• Use #!/usr/bin/env python3 shebang
• Read input from stdin as JSON
• Handle all exceptions silently (don't block operations)
• Use subprocess.run with timeout

JSON Files

• 2-space indentation
• No trailing commas
• Validate syntax before committing

Git Workflow

Commit Messages

Follow Conventional Commits:

feat: add new agent for X
fix: correct hook exit code handling
docs: update README with new feature
chore: bump version to X.Y.Z

Branching

• main is always deployable
• Feature branches: feature/description
• Bug fixes: fix/description