Skip to content

CLAUDE.md

Latest commit

 

History

History
57 lines (52 loc) · 2.97 KB

CLAUDE.md

File metadata and controls

57 lines (52 loc) · 2.97 KB

CLAUDE.md — synodic-kit

What This Is

Claude Code plugin toolkit providing hooks, skills, and slash commands used across all synodic-studio projects. Installed as a --plugin-dir to extend Claude Code sessions with safety guardrails, formatters, and development workflows.

Tech Stack

  • Language: Python 3.13+
  • Platform: Claude Code plugin system (hooks + skills + commands)
  • Testing: pytest
  • No build step — loaded directly by Claude Code at runtime

Build & Test

cd ~/Developer/synodic-kit
python3 -m pytest tests/ -v

Project Structure

hooks/
  pre_tool_use.py        # Force-push block, git safety, calendar guard, rm warnings
  post_tool_use.py       # Post-action validation
  notification.py        # Telegram/Discord notifications
  stop.py                # Session stop handler
  subagent_stop.py       # Subagent stop handler
  pre_compact.py         # Pre-compaction handler
  session_start.py       # Session initialization
  session_end.py         # Session cleanup, reporting
  user_prompt_submit.py  # User input preprocessing
  hook_utils.py          # Shared hook utilities
  hooks.json             # Hook registration config
  formatters/            # Auto-formatters (Swift, Python, JSON, TypeScript)
  session/               # Session tracking (branch management, change handler, SQLite logger)
  shared/                # Shared modules (git utils, hook_utils, telegram, discord)
commands/                # Slash commands (markdown files)
  open.md                # /open — reopen last relevant file(s) from conversation
skills/                  # Domain skills (SKILL.md + references)
  apple-platform-dev/    # iOS/macOS development patterns
  swift-quality/         # SwiftUI code quality rules (symlink)
  self-healing-errors/   # Error handling for LLM automation
  apple-release/         # Fastlane/notarize release automation
  testflight-ship/       # TestFlight upload + tester invitation
  cobalt-sync/           # Obsidian vault headless sync
  openscad/              # OpenSCAD scripted 3D modeling (headless render loop)
tests/
  test_pre_tool_use.py   # Pre-tool-use hook tests
  test_post_tool_use.py  # Post-tool-use hook tests

Key Conventions

  • All hooks are Python — no bash business logic
  • hooks.json registers all lifecycle hooks using ${CLAUDE_PLUGIN_ROOT} variable
  • Git safety: pre_tool_use blocks force-pushes to any branch. develop is the standard working branch — direct commits to it are normal. main, master, production, and release are protected by convention (not hook-enforced): never commit directly to them.
  • Formatters run automatically on file writes (Swift via swiftformat, Python via ruff, JSON, TypeScript)
  • Session tracking logs edits to SQLite for disaster recovery and pattern analysis
  • Commands are markdown files — Claude reads them as instructions when a slash command is invoked
  • Skills are reference docs — SKILL.md files loaded on demand for domain-specific guidance