stravinsky 0.2.52__py3-none-any.whl → 0.4.18__py3-none-any.whl

mcp_bridge/config/skills_manifest.json

@@ -0,0 +1,128 @@
+{
+  "schema_version": "1.0.0",
+  "manifest_version": "0.3.9",
+  "description": "Stravinsky skills for Claude Code command integration",
+  "generated_date": "2026-01-08T23:53:08.837988Z",
+  "skills": {
+    "commit.md": {
+      "file_path": "commit.md",
+      "description": "Git Master - Intelligent atomic commit orchestration",
+      "checksum": "f09aee4cc46e",
+      "lines_of_code": 531,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "delphi.md": {
+      "file_path": "delphi.md",
+      "description": "Strategic advisor for architecture and debugging",
+      "checksum": "46ce352164a5",
+      "lines_of_code": 5,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "dewey.md": {
+      "file_path": "dewey.md",
+      "description": "Research librarian for documentation and examples",
+      "checksum": "de4e41fc0e08",
+      "lines_of_code": 54,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "index.md": {
+      "file_path": "str/index.md",
+      "description": "Index project for semantic search",
+      "checksum": "a37c570b70a5",
+      "lines_of_code": 199,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "publish.md": {
+      "file_path": "publish.md",
+      "description": "Publish to PyPI with version bump",
+      "checksum": "9e6ed392ebc4",
+      "lines_of_code": 66,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "review.md": {
+      "file_path": "review.md",
+      "description": "Code review recent changes",
+      "checksum": "47274e796826",
+      "lines_of_code": 67,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "search.md": {
+      "file_path": "str/search.md",
+      "description": "Stravinsky skill",
+      "checksum": "eb092d567333",
+      "lines_of_code": 205,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "start_filewatch.md": {
+      "file_path": "str/start_filewatch.md",
+      "description": "Stravinsky skill",
+      "checksum": "23ca1f6a1999",
+      "lines_of_code": 136,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "stats.md": {
+      "file_path": "str/stats.md",
+      "description": "Stravinsky skill",
+      "checksum": "017f4fc6d099",
+      "lines_of_code": 71,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "stop_filewatch.md": {
+      "file_path": "str/stop_filewatch.md",
+      "description": "Stravinsky skill",
+      "checksum": "dbe92100d0ba",
+      "lines_of_code": 89,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "cancel-loop.md": {
+      "file_path": "strav/cancel-loop.md",
+      "description": "Cancel active continuation loop",
+      "checksum": "d811ea8bb0e9",
+      "lines_of_code": 128,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "loop.md": {
+      "file_path": "strav/loop.md",
+      "description": "Continuation loop for iterative execution",
+      "checksum": "defc1ae0aae4",
+      "lines_of_code": 193,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "strav.md": {
+      "file_path": "strav.md",
+      "description": "Stravinsky Orchestrator - Parallel agent execution",
+      "checksum": "9c9969cf8c09",
+      "lines_of_code": 216,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "verify.md": {
+      "file_path": "verify.md",
+      "description": "Post-implementation verification",
+      "checksum": "87894579d5ec",
+      "lines_of_code": 60,
+      "updatable": true,
+      "priority": "medium"
+    },
+    "version.md": {
+      "file_path": "version.md",
+      "description": "Stravinsky skill",
+      "checksum": "1cf41d5d28da",
+      "lines_of_code": 5,
+      "updatable": true,
+      "priority": "medium"
+    }
+  }
+}

mcp_bridge/hooks/HOOKS_SETTINGS.json

@@ -0,0 +1,175 @@
+{
+  "description": "Stravinsky MCP Hooks Configuration - Copy this to .claude/settings.json",
+  "installation_note": "These hooks are bundled with the stravinsky PyPI package. Hook paths should point to the installed package location or .claude/hooks/ if copied locally.",
+  
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/notification_hook.py",
+            "description": "Agent spawn notification messages"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/subagent_stop.py",
+            "description": "Agent completion handling and validation"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/pre_compact.py",
+            "description": "Context preservation before compaction"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read,Search,Grep,Bash,Edit,MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/stravinsky_mode.py",
+            "description": "Hard blocking of direct tools in stravinsky mode"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/parallel_execution.py",
+            "description": "Pre-emptive parallel execution enforcement"
+          },
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/context.py",
+            "description": "Auto-inject project context (CLAUDE.md, README.md)"
+          },
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/todo_continuation.py",
+            "description": "Remind about incomplete todos"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/truncator.py",
+            "description": "Truncate long tool responses"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__stravinsky__*,mcp__grep-app__*,Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/tool_messaging.py",
+            "description": "User-friendly MCP tool messaging"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit,MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/edit_recovery.py",
+            "description": "Recovery guidance for failed Edit operations"
+          }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/todo_delegation.py",
+            "description": "Parallel execution enforcer after TodoWrite"
+          }
+        ]
+      }
+    ]
+  },
+  
+  "usage_instructions": {
+    "installation": [
+      "1. Copy this file to .claude/settings.json in your project root",
+      "2. Ensure hook scripts are available at .claude/hooks/ (copy from package or use symlink)",
+      "3. Restart Claude Code or run /reload"
+    ],
+    "hook_paths": {
+      "local_copy": "Copy hooks to .claude/hooks/ and use relative paths (as shown above)",
+      "package_install": "Use absolute paths to installed package: python -c 'import mcp_bridge; print(mcp_bridge.__path__[0])'/hooks/",
+      "development": "For development, symlink: ln -s /path/to/stravinsky/mcp_bridge/hooks .claude/hooks"
+    },
+    "customization": [
+      "Disable individual hooks by removing them from the hooks array",
+      "Adjust matchers to change which tools trigger hooks",
+      "Add custom hooks by creating new Python scripts"
+    ]
+  },
+  
+  "hook_overview": {
+    "execution_control": {
+      "parallel_execution.py": "Detects implementation tasks and injects parallel execution instructions before response generation. Activates stravinsky mode on /stravinsky invocation.",
+      "stravinsky_mode.py": "Blocks native file tools (Read, Grep, Bash, Edit) when stravinsky mode is active, forcing Task delegation.",
+      "todo_delegation.py": "Hard blocks response completion after TodoWrite if 2+ pending items exist without spawning Task agents."
+    },
+    "context_management": {
+      "context.py": "Auto-injects CLAUDE.md, README.md, or AGENTS.md content into prompts for project-specific context.",
+      "todo_continuation.py": "Reminds about incomplete in_progress or pending todos before starting new work.",
+      "pre_compact.py": "Preserves critical context patterns (ARCHITECTURE, DESIGN DECISION, etc.) before compaction."
+    },
+    "tool_enhancement": {
+      "tool_messaging.py": "Outputs user-friendly messages about which agent/tool was used (e.g., 'delphi:gpt-5.2-medium(\"Analyzing architecture\")').",
+      "edit_recovery.py": "Detects Edit tool failures and suggests recovery actions (re-read file, verify exact match).",
+      "truncator.py": "Truncates tool responses longer than 30k characters to prevent token overflow."
+    },
+    "agent_lifecycle": {
+      "notification_hook.py": "Outputs spawn messages for agent delegation (e.g., 'spawned explore:gemini-3-flash(\"Find auth code\")').",
+      "subagent_stop.py": "Handles subagent completion, validates output, and can block if critical agents fail."
+    }
+  },
+  
+  "exit_code_reference": {
+    "0": "Success - Allow continuation",
+    "1": "Warning - Show message but continue",
+    "2": "Block - Hard failure (prevents tool execution in PreToolUse, or signals error in PostToolUse)"
+  },
+  
+  "state_files": {
+    "~/.stravinsky_mode": "Marker file indicating stravinsky orchestrator mode is active (enables hard blocking)",
+    "~/.claude/state/compaction.jsonl": "Audit log of context compaction events with preserved items",
+    ".claude/todo_state.json": "Cached todo state for continuation enforcement"
+  },
+  
+  "version": "0.2.63",
+  "package": "stravinsky",
+  "documentation": "https://github.com/GratefulDave/stravinsky"
+}

mcp_bridge/hooks/README.md

@@ -0,0 +1,215 @@
+# Stravinsky Hooks for Claude Code
+
+This directory contains 11 production-ready hooks that integrate with Claude Code to enforce parallel execution, stravinsky mode, and advanced workflow patterns.
+
+## Quick Start
+
+### Option 1: Copy to Local Project
+
+```bash
+# In your Claude Code project root
+mkdir -p .claude/hooks
+cp -r $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks/*.py .claude/hooks/
+cp $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks/HOOKS_SETTINGS.json .claude/settings.json
+```
+
+### Option 2: Symlink (Development)
+
+```bash
+# In your Claude Code project root
+mkdir -p .claude
+ln -s $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks .claude/hooks
+cp .claude/hooks/HOOKS_SETTINGS.json .claude/settings.json
+```
+
+## Hook Files (11 Total)
+
+### Core Execution (3)
+1. **parallel_execution.py** - UserPromptSubmit hook
+   - Detects implementation tasks and injects parallel execution instructions
+   - Activates stravinsky mode when `/stravinsky` is invoked
+   - Creates `~/.stravinsky_mode` marker file for hard blocking
+
+2. **stravinsky_mode.py** - PreToolUse hook
+   - Blocks Read, Grep, Bash, Edit, MultiEdit when stravinsky mode is active
+   - Forces delegation via Task tool instead
+   - Exit code 2 = hard block
+
+3. **todo_delegation.py** - PostToolUse hook (after TodoWrite)
+   - Enforces parallel Task spawning when 2+ pending todos exist
+   - Blocks continuation without Task delegation in stravinsky mode
+   - Exit code 2 = hard block if stravinsky mode active
+
+### Context Management (3)
+4. **context.py** - UserPromptSubmit hook
+   - Auto-injects CLAUDE.md, README.md, or AGENTS.md content
+   - Prepends project context to every prompt
+   - Reduces need for explicit context requests
+
+5. **todo_continuation.py** - UserPromptSubmit hook
+   - Reminds about in_progress and pending todos
+   - Prevents starting new work when existing todos are incomplete
+   - Uses `.claude/todo_state.json` cache
+
+6. **pre_compact.py** - PreCompact hook
+   - Preserves critical context before compaction (ARCHITECTURE, DESIGN DECISION, etc.)
+   - Logs compaction events to `~/.claude/state/compaction.jsonl`
+   - Maintains stravinsky mode state across compactions
+
+### Tool Enhancement (3)
+7. **tool_messaging.py** - PostToolUse hook
+   - User-friendly messages for MCP tools and Task delegations
+   - Format: `🎯 delphi:gpt-5.2-medium('Strategic analysis')`
+   - Works with mcp__stravinsky__* and mcp__grep-app__* tools
+
+8. **edit_recovery.py** - PostToolUse hook (after Edit/MultiEdit)
+   - Detects Edit failures (oldString not found, multiple matches, etc.)
+   - Suggests recovery: re-read file, verify exact match
+   - Appends recovery guidance to error messages
+
+9. **truncator.py** - PostToolUse hook (all tools)
+   - Truncates responses longer than 30k characters
+   - Prevents token overflow and context bloat
+   - Adds truncation markers for transparency
+
+### Agent Lifecycle (2)
+10. **notification_hook.py** - Notification hook
+    - Outputs spawn messages for agent delegations
+    - Format: `spawned explore:gemini-3-flash('Find auth code')`
+    - Maps agents to their display models
+
+11. **subagent_stop.py** - SubagentStop hook
+    - Handles subagent completion events
+    - Validates output and detects failures
+    - Can block completion for critical agents (delphi, code-reviewer, debugger)
+
+## Configuration
+
+The `HOOKS_SETTINGS.json` file contains the complete hook configuration for `.claude/settings.json`. It includes:
+
+- Hook type mappings (UserPromptSubmit, PreToolUse, PostToolUse, etc.)
+- Tool matchers (which tools trigger which hooks)
+- Command paths (python3 .claude/hooks/hookname.py)
+- Descriptions for each hook
+
+## Hook Types & Exit Codes
+
+### Hook Types
+- **UserPromptSubmit**: Before response generation (can modify prompt)
+- **PreToolUse**: Before tool execution (can block with exit 2)
+- **PostToolUse**: After tool execution (can modify response)
+- **Notification**: On notification events
+- **SubagentStop**: When subagent completes
+- **PreCompact**: Before context compaction
+
+### Exit Codes
+- `0` - Success (allow continuation)
+- `1` - Warning (show message but continue)
+- `2` - Block/Error (prevents tool in PreToolUse, signals failure in PostToolUse)
+
+## State Files
+
+Hooks use these state files:
+
+| File | Purpose |
+|------|---------|
+| `~/.stravinsky_mode` | Marker for stravinsky orchestrator mode (enables hard blocking) |
+| `~/.claude/state/compaction.jsonl` | Audit log of context compaction events |
+| `.claude/todo_state.json` | Cached todo state for continuation enforcement |
+
+## Testing Hooks
+
+Test individual hooks with JSON input:
+
+```bash
+# Test parallel_execution
+echo '{"prompt": "implement feature X"}' | python3 parallel_execution.py
+
+# Test stravinsky_mode (should block)
+touch ~/.stravinsky_mode
+echo '{"toolName": "Read", "params": {}}' | python3 stravinsky_mode.py
+echo $?  # Should be 2
+
+# Test todo_delegation
+echo '{"tool_name": "TodoWrite", "tool_input": {"todos": [{"status": "pending"}, {"status": "pending"}]}}' | python3 todo_delegation.py
+```
+
+## Customization
+
+To disable a hook:
+1. Open `.claude/settings.json`
+2. Find the hook in the hooks array
+3. Remove or comment out the hook object
+
+To modify a hook:
+1. Copy the hook file to your project's `.claude/hooks/`
+2. Edit as needed
+3. Update the command path in `.claude/settings.json`
+
+## Environment Variables
+
+Hooks receive these from Claude Code:
+- `CLAUDE_CWD` - Current working directory
+- `CLAUDE_TOOL_NAME` - Tool being invoked
+- `CLAUDE_SESSION_ID` - Active session ID
+
+## Workflow
+
+### Stravinsky Mode Flow
+1. User invokes `/stravinsky`
+2. `parallel_execution.py` detects it and creates `~/.stravinsky_mode`
+3. `stravinsky_mode.py` now blocks Read/Grep/Bash/Edit tools
+4. Claude must use Task tool for delegation
+5. `todo_delegation.py` enforces parallel Task spawning for 2+ pending todos
+
+### Normal Flow (No Stravinsky Mode)
+1. User submits prompt
+2. `context.py` injects CLAUDE.md content
+3. `todo_continuation.py` reminds about incomplete todos
+4. `parallel_execution.py` adds parallel execution guidance if implementation task
+5. Claude generates response
+6. `tool_messaging.py` outputs friendly tool messages
+7. `truncator.py` truncates long responses
+
+## Troubleshooting
+
+### Hooks Not Firing
+- Check `.claude/settings.json` exists with hook configuration
+- Verify hook scripts are executable: `chmod +x .claude/hooks/*.py`
+- Check hook paths are correct (relative to project root)
+- Restart Claude Code: `/reload`
+
+### Stravinsky Mode Stuck Active
+- Remove marker file: `rm ~/.stravinsky_mode`
+- Check for orphaned mode files: `ls -la ~/ | grep stravinsky`
+
+### Hooks Causing Errors
+- Test hooks individually (see Testing section above)
+- Check Python version: `python3 --version` (requires 3.8+)
+- Review hook stderr output in Claude Code logs
+- Disable problematic hooks temporarily
+
+## Integration with Stravinsky MCP
+
+These hooks are designed to work seamlessly with the Stravinsky MCP server:
+
+- `tool_messaging.py` recognizes `mcp__stravinsky__*` tools
+- `parallel_execution.py` works with `agent_spawn` MCP tool
+- `stravinsky_mode.py` forces use of MCP Task delegation
+- All hooks respect the parallel execution philosophy
+
+## Version
+
+Version: 0.2.61
+Package: stravinsky
+Repository: https://github.com/GratefulDave/stravinsky
+
+## License
+
+MIT License - See package LICENSE file
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/GratefulDave/stravinsky/issues
+- Documentation: See CLAUDE.md in package root