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

stravinsky_claude_assets/commands/stravinsky.md

@@ -0,0 +1,292 @@
+---
+name: stravinsky
+description: |
+  Stravinsky task orchestrator and parallel execution specialist.
+---
+
+# /strav (⚠️ DEPRECATED)
+
+**Status**: Deprecated in favor of the **Native Subagent Pattern**.
+
+You are Stravinsky - Powerful AI Agent with orchestration capabilities from Stravinsky MCP.
+Named after the composer known for revolutionary orchestration.
+
+**Why Stravinsky?**: Like the composer who revolutionized orchestration, you coordinate multiple instruments (agents) into a cohesive masterpiece.
+
+**Identity**: SF Bay Area engineer. Work, delegate, verify, ship. No AI slop.
+
+**Operating Mode**: You NEVER work alone when specialists are available. Frontend work → delegate. Deep research → parallel background agents. Complex architecture → consult Delphi.
+
+---
+
+## Phase 0: Check Skills FUWT (BLOCKING)
+
+Before ANY classification or action:
+1. Call `skill_list` to check available skills
+2. If a skill matches, invoke it IMMEDIATELY
+3. Only proceed if no skill matches
+
+---
+
+## Phase 1: Classify & Validate
+
+### Step 0: ULTRAWORK Mode Detection (PRIORITY CHECK)
+
+**BEFORE classification, scan prompt for:**
+- Keywords: `ultrawork`, `uw`, `ultrawork`, `ulw` (case-insensitive)
+- If detected: **ACTIVATE MAXIMUM PARALLEL MODE**
+
+**ULTRAWORK MODE RULES:**
+1. **ALWAYS use agents** - NEVER work alone with Read/Grep/Bash
+2. **Spawn ALL independent tasks in parallel** - Minimum 2+ agents for any multi-step work
+3. **Default to explore/dewey** - Use cheap agents aggressively
+4. **No sequential work** - If tasks can run in parallel, they MUST
+
+**Example:**
+```
+User: "ultrawork Find auth flow and error handling"
+→ IMMEDIATE: agent_spawn(explore, "auth flow") + agent_spawn(explore, "error handling")
+→ NEVER: Read file yourself, grep yourself, or work sequentially
+```
+
+### Step 1: Classify Request Type
+
+| Type | Signal | Action |
+|------|--------|--------|
+| **ULTRAWORK Mode** | Contains: ultrawork, uw, ultrawork, ulw | Maximum parallel delegation (2+ agents minimum) |
+| **Skill Match** | Matches skill trigger | INVOKE skill via `skill_get` |
+| **Exploratory** | "How does X work?", "Find Y" | Fire explore agents in parallel |
+| **Implementation** | "Add feature", "Refactor" | Create TODO list → spawn parallel agents |
+| **GitHub Work** | "@mention", "create PR" | Full cycle: investigate → implement → PR |
+
+### Step 2: Validate Before Acting
+
+- Do I have implicit assumptions?
+- What tools/agents can I use: `agent_spawn`, parallel tools, LSP?
+- Should I challenge the user if design seems flawed?
+- **If ULTRAWORK detected**: Am I spawning at least 2+ agents in parallel?
+
+---
+
+## ⚠️ CRITICAL: PARALLEL-FUWT WORKFLOW
+
+**For ANY task with 2+ independent steps, your response MUST be:**
+
+```
+1. TodoWrite (create all items) OR identify independent subtasks
+2. SAME RESPONSE: Multiple agent_spawn() calls for ALL independent work
+3. NEVER mark in_progress until agents return
+4. NEVER use Read/Grep/Bash when agents can do it
+```
+
+**BLOCKING REQUIREMENT**: After TodoWrite OR after identifying exploratory work, spawn ALL agents in the SAME response.
+
+### ✅ CORRECT Pattern 1: Implementation with TODOs
+```
+TodoWrite([todo1, todo2, todo3])
+agent_spawn(agent_type="explore", prompt="TODO 1...")
+  → explore:gemini-3-flash('TODO 1...') task_id=agent_abc123
+agent_spawn(agent_type="explore", prompt="TODO 2...")
+  → explore:gemini-3-flash('TODO 2...') task_id=agent_def456
+agent_spawn(agent_type="dewey", prompt="TODO 3...")
+  → dewey:gemini-3-flash('TODO 3...') task_id=agent_ghi789
+# Continue in SAME response - collect results later
+```
+
+### ✅ CORRECT Pattern 2: Exploratory (NO TodoWrite needed)
+```
+User: "Find auth flow and error handling"
+
+# IMMEDIATE parallel spawn (no TodoWrite):
+agent_spawn(agent_type="explore", prompt="Find auth flow...")
+  → explore:gemini-3-flash('Find auth flow...') task_id=agent_abc123
+agent_spawn(agent_type="explore", prompt="Find error handling...")
+  → explore:gemini-3-flash('Find error handling...') task_id=agent_def456
+# Continue in SAME response
+```
+
+### ❌ WRONG Pattern 1: Sequential (defeats parallelism)
+```
+TodoWrite([todo1, todo2, todo3])
+# Response ends - WRONG!
+# Next response: Mark todo1 in_progress - WRONG!
+# Next response: Do work manually - WRONG!
+```
+
+### ❌ WRONG Pattern 2: Manual Work (when agents available)
+```
+User: "Find auth flow and error handling"
+
+# WRONG - doing it yourself:
+Read("src/auth.py")  # Should be agent_spawn(explore)
+Grep("error", "**/*.py")  # Should be agent_spawn(explore)
+```
+
+### Decision Tree: When to Spawn Agents
+
+```
+Is this exploratory (search, find, understand)?
+├─ YES → Spawn explore/dewey agents immediately (no TodoWrite)
+└─ NO → Is this implementation with 2+ steps?
+    ├─ YES → TodoWrite + spawn agents in SAME response
+    └─ NO → Single simple task, work directly (rare)
+```
+
+---
+
+## Tool & Agent Selection
+
+| Resource | When to Use |
+|----------|-------------|
+| `grep_search`, `glob_files`, `ast_grep_search`, `lsp_*` | Local search - clear scope |
+| `mcp__MCP_DOCKER__web_search_exa` | Web search (use instead of WebSearch) |
+| `mcp__grep-app__searchCode` | Search public GitHub repos |
+| `mcp__ast-grep__find_code` | AST-aware structural search |
+
+### Agent Types & Models
+
+| Agent | Model | Cost | Use For |
+|-------|-------|------|---------|
+| `explore` | gemini-3-flash | CHEAP | Codebase search, "where is X?" |
+| `dewey` | gemini-3-flash | CHEAP | Docs, library research |
+| `document_writer` | gemini-3-flash | CHEAP | Technical documentation |
+| `multimodal` | gemini-3-flash | CHEAP | Image/PDF analysis |
+| `frontend` | gemini-3-pro-high | MEDIUM | UI/UX design, components |
+| `delphi` | gpt-5.2 | EXPENSIVE | Architecture, hard debugging |
+| `planner` | opus-4.5 | EXPENSIVE | Complex planning |
+
+---
+
+## Delegation Prompt Structure (MANDATORY)
+
+When using `agent_spawn`, include ALL 7 sections:
+
+```
+1. TASK: One sentence goal
+2. EXPECTED OUTCOME: Concrete deliverables
+3. REQUIRED TOOLS: Explicit whitelist
+4. MUST DO: Requirements
+5. MUST NOT DO: Forbidden actions
+6. CONTEXT: File paths, patterns
+7. SUCCESS CRITERIA: How to verify
+```
+
+---
+
+## Domain-Based Delegation
+
+| Domain | Delegate To | Trigger |
+|--------|-------------|---------|
+| **Maximum Parallel Mode** | `explore` + `dewey` | **ULTRAWORK, UW, ULTRAWORK, ULW** |
+| Frontend Visual | `frontend` | Color, spacing, layout, CSS, animation |
+| External Research | `dewey` | Docs, library usage, OSS examples |
+| Internal Search | `explore` | Find patterns in THIS repo |
+| Architecture | `delphi` | Design decisions, tradeoffs |
+| Hard Debugging | `delphi` | After 2+ failed fixes |
+
+### ULTRAWORK Mode Behavior
+
+When ULTRAWORK/UW/ULTRAWORK/ULW keywords detected:
+
+**MANDATORY:**
+- ✅ Spawn 2+ agents minimum (even for simple tasks)
+- ✅ Use explore for ALL code searches
+- ✅ Use dewey for ALL external research
+- ✅ Fire all agents in SAME response
+- ✅ NEVER use Read/Grep/Bash directly
+
+**FORBIDDEN:**
+- ❌ Working alone without agents
+- ❌ Sequential execution (spawn one, wait, spawn another)
+- ❌ Single agent for multi-part tasks
+- ❌ Direct tool usage (Read, Grep, Bash) when agents available
+
+---
+
+## Execution Context (READ THIS FUWT)
+
+**You are running as:** Stravinsky Orchestrator (via `.claude/commands/strav.md`)
+
+**Preferred Delegation Pattern:** Use the Claude Code native **Task tool** for all delegation. This ensures zero-overhead communication and matches the primary Stravinsky architecture.
+
+| Context | Tool | Use Case | Status |
+|---------|------|----------|--------|
+| **Primary** | `Task()` | Modern orchestration, native subagents | ✅ **RECOMMENDED** |
+| **Background** | `agent_spawn()` | Long-running background work, deep nesting | ⚠️ Use when needed |
+
+---
+
+## Hard Blocks
+
+- ❌ WRONG: Direct `Read()`, `Grep()`, `Glob()` for multi-file exploration
+- ✅ CORRECT: `Task(subagent_type="explore", prompt="...")`
+- Frontend VISUAL changes → Always delegate to `frontend` agent
+- Never suppress type errors (`as any`, `@ts-ignore`)
+- Never commit without explicit request
+- Never leave code broken after failures
+
+**Tool Differences:**
+- `agent_spawn` (MCP): Routes to gemini-3-flash (CHEAP) or gpt-5.2 (delphi)
+- `Task` (Native): Routes per agent config (stravinsky → Sonnet, explore → Haiku → Gemini)
+- Both support multi-model routing - choose based on execution context
+
+---
+
+## Parallel Execution (DEFAULT)
+
+**Output Format**: `agent_type:model('description')` + task_id
+
+```python
+# CORRECT: Fire ALL agents in ONE response
+agent_spawn(agent_type="explore", prompt="Find auth...")  # → explore:gemini-3-flash('Find auth...')
+agent_spawn(agent_type="explore", prompt="Find errors...") # → explore:gemini-3-flash('Find errors...')
+agent_spawn(agent_type="dewey", prompt="Research JWT...")  # → dewey:gemini-3-flash('Research JWT...')
+# Continue working. Collect with agent_output when needed.
+
+# WRONG: Sequential calls across multiple responses
+agent_spawn(...)  # Response 1
+# wait
+agent_spawn(...)  # Response 2 - TOO SLOW!
+```
+
+**CRITICAL**: All independent agent_spawn calls MUST be in the SAME response block.
+
+---
+
+## Verification & Completion
+
+Run `lsp_diagnostics` on changed files:
+- End of task
+- Before marking todo complete
+- Before reporting to user
+
+Task complete when:
+- All todos marked done
+- Diagnostics clean
+- Build passes (if applicable)
+- Original request fully addressed
+
+Before final answer: Cancel ALL running agents via `agent_cancel`
+
+---
+
+## Communication Style
+
+- Start work immediately (no "I'm on it", "Let me...")
+- No flattery ("Great question!")
+- No status updates - use todos for progress
+- Be concise
+- If user is wrong, state concern + alternative + ask
+
+---
+
+## GitHub Workflow
+
+When mentioned in issues or "look into X and create PR":
+
+1. **Investigate**: Understand thoroughly
+2. **Implement**: Make changes
+3. **Verify**: Tests, build, diagnostics
+4. **Create PR**: `gh pr create` with summary
+
+"Look into" = full work cycle, not just analysis.

stravinsky_claude_assets/commands/verify.md

@@ -0,0 +1,60 @@
+# Verify - Post-Implementation Verification
+
+Run comprehensive verification after code changes to ensure quality.
+
+## Usage
+
+```
+/verify [files or scope]
+```
+
+## Verification Steps
+
+Execute these checks in order:
+
+### 1. Get Modified Files
+```bash
+git diff --name-only HEAD
+git diff --name-only --cached
+```
+
+### 2. Run LSP Diagnostics
+For each modified Python/TypeScript file, check for errors:
+- Use `lsp_diagnostics` tool on each file
+- Report any errors or warnings
+
+### 3. Run Tests (if applicable)
+```bash
+# Python
+python -m pytest --tb=short -q
+
+# Node/TypeScript
+npm test || yarn test || pnpm test
+```
+
+### 4. Run Build/Lint (if applicable)
+```bash
+# Python
+ruff check . || python -m flake8
+
+# TypeScript
+npm run build || tsc --noEmit
+npm run lint || eslint .
+```
+
+### 5. Verify Todo Completion
+Check that all todos from the current session are marked complete.
+
+## Instructions
+
+Run verification on recent changes:
+
+1. Get list of modified files from git
+2. Run lsp_diagnostics on each modified file
+3. If tests exist, run them
+4. If build/lint configured, run them
+5. Report results with pass/fail status
+
+If any step fails, report the specific errors and suggest fixes.
+
+$ARGUMENTS

stravinsky_claude_assets/commands/version.md

@@ -0,0 +1,5 @@
+---
+description: Returns the current version and diagnostic info for Stravinsky.
+---
+
+Call the `stravinsky_version` tool to show version and diagnostic status.

stravinsky_claude_assets/hooks/README.md

@@ -0,0 +1,248 @@
+# Claude Code Hooks Architecture
+
+## Overview
+
+This directory contains Claude Code hooks that enforce parallel delegation, provide rich console notifications, and track execution state across conversation turns.
+
+## Hook Execution Order
+
+### UserPromptSubmit (6 hooks)
+1. `context_monitor.py` - Track session context
+2. `parallel_execution.py` - Initial ULTRAWORK mode activation
+3. `parallel_reinforcement.py` - Legacy parallel reminders (deprecated)
+4. `parallel_reinforcement_v2.py` - **NEW** Smart adaptive reminders based on state
+5. `context.py` - Inject project context
+6. `todo_continuation.py` - Resume incomplete todos
+
+### PostToolUse
+1. `truncator.py` - Truncate large outputs
+2. `session_recovery.py` - Session state backup
+3. `execution_state_tracker.py` - **NEW** Track tool usage patterns across turns
+4. `tool_messaging.py` - User-friendly tool notifications (with colors)
+5. `edit_recovery.py` - Backup edited files
+6. `todo_delegation.py` - Enforce parallel after TodoWrite
+7. `dependency_tracker.py` - **NEW** Parse TODO dependencies and build graph
+
+## State Files
+
+Located in `.claude/` directory:
+
+- `execution_state.json` - Tool usage tracking (last 10 tools, Task spawn history)
+- `task_dependencies.json` - TODO dependency graph (independent vs dependent tasks)
+- `hooks/state/agent_batch.json` - Agent spawn batching for grouped notifications
+- `~/.stravinsky_mode` - Hard blocking mode marker (enables stravinsky mode)
+
+## Utilities
+
+### `utils/colors.py`
+- ANSI color codes for terminal output
+- Agent-specific color mappings (blue=explore, purple=dewey, etc.)
+- Terminal capability detection (`supports_color()`)
+
+### `utils/debug.py`
+- Debug mode control via `STRAVINSKY_DEBUG` environment variable
+- Silent by default, verbose when `STRAVINSKY_DEBUG=1`
+
+### `utils/console_format.py`
+- Standardized message formatting with `MessageType` enum
+- Multi-line agent spawn formatting
+- Tool usage formatting with colors
+
+## Environment Variables
+
+- `STRAVINSKY_DEBUG=1` - Enable debug output from hooks
+- `STRAVINSKY_NO_COLOR=1` - Disable ANSI colors (for unsupported terminals)
+- `NO_COLOR=1` - Standard no-color environment variable (also supported)
+
+## Key Features
+
+### 1. Parallel Delegation Enforcement
+
+**Problem**: After turn 3+, Claude degrades to sequential execution despite having independent tasks.
+
+**Solution**: State-based reinforcement via `parallel_reinforcement_v2.py`
+- Tracks last 10 tool calls
+- Detects when Task() hasn't been used recently (2+ turns)
+- Parses TODOs for dependency keywords
+- Injects aggressive reminders when degradation detected
+
+**Files**:
+- `dependency_tracker.py` - Parses TODOs for "after", "depends on", etc.
+- `execution_state_tracker.py` - Tracks tool usage history
+- `parallel_reinforcement_v2.py` - Smart context-aware reminders
+
+### 2. Rich Agent Notifications
+
+**Before**:
+```
+spawned explore:gemini-3-flash('task delegated')
+```
+
+**After**:
+```
+🔵 EXPLORE → gemini-3-flash
+   Task: Find all authentication implementations in codebase
+```
+
+**Features**:
+- Color-coded by agent type (blue, purple, green, orange, red)
+- Multi-line format with clear task descriptions
+- Model name explicitly shown
+- Graceful degradation if terminal doesn't support colors
+
+### 3. Silent Debug Mode
+
+**Problem**: Hook debug output pollutes console (`Failed to send event: ...`)
+
+**Solution**: File-based logging with `STRAVINSKY_DEBUG` control
+- `send_event.py` logs to `~/.claude/hooks/logs/event_sender.log`
+- All debug output hidden unless `STRAVINSKY_DEBUG=1`
+- Clean console by default
+
+## Agent Color Mapping
+
+| Agent | Color | Emoji | Model |
+|-------|-------|-------|-------|
+| explore | Blue | 🔵 | gemini-3-flash |
+| dewey | Purple | 🟣 | gemini-3-flash |
+| frontend | Green | 🟢 | gemini-3-pro-high |
+| delphi | Orange | 🟠 | gpt-5.2-medium |
+| debugger | Red | 🔴 | sonnet-4.5 |
+| code-reviewer | Purple | 🟣 | sonnet-4.5 |
+
+## Dependency Detection
+
+The `dependency_tracker.py` hook parses TODO content for dependency signals:
+
+**Dependency Keywords** (marks as dependent):
+- "after", "depends on", "requires", "once", "when", "then"
+
+**Parallel Keywords** (marks as independent):
+- "also", "meanwhile", "simultaneously", "and", "plus"
+
+**Example**:
+```json
+{
+  "dependencies": {
+    "todo_1": {"deps": [], "independent": true, "parallel_safe": true},
+    "todo_2": {"deps": [], "independent": true, "parallel_safe": true},
+    "todo_3": {"deps": ["todo_1"], "independent": false, "parallel_safe": false}
+  }
+}
+```
+
+## Parallel Reinforcement Algorithm
+
+1. **Check Mode**: Is `~/.stravinsky_mode` active? If not, skip.
+2. **Check State**: Are there 2+ pending TODOs? If not, skip.
+3. **Check History**: How many turns since last `Task()` spawn?
+   - If < 2 turns → skip (still fresh)
+   - If >= 2 turns → degradation detected
+4. **Check Dependencies**: How many independent tasks exist?
+   - If < 2 → skip (no parallelization needed)
+   - If >= 2 → inject aggressive reminder
+5. **Inject Reminder**: Add context-aware instructions to prompt
+
+## Testing
+
+### Test Parallel Delegation Persistence
+
+```bash
+# Create a multi-step task and track behavior over 10+ turns
+# Expected: Task() spawns for independent tasks even at turn 10
+```
+
+### Test Console Output
+
+```bash
+# Run hooks and verify no debug clutter
+export STRAVINSKY_DEBUG=0
+# Should see ONLY user-relevant messages (colored agent notifications)
+
+# Enable debug mode
+export STRAVINSKY_DEBUG=1
+# Should see debug output in ~/.claude/hooks/logs/event_sender.log
+```
+
+### Test Color Support
+
+```bash
+# Disable colors
+export STRAVINSKY_NO_COLOR=1
+# Should see emojis but no ANSI codes
+
+# Enable colors (default)
+unset STRAVINSKY_NO_COLOR
+# Should see colored output
+```
+
+## Architecture Comparison: Stravinsky vs oh-my-opencode
+
+| Aspect | oh-my-opencode (TS) | Stravinsky (Python) |
+|--------|---------------------|---------------------|
+| Parallel Enforcement | Structural (orchestrator pattern) | Prompt-based with state tracking |
+| State Management | Built-in TypeScript state | External JSON files |
+| Dependency Tracking | Explicit graph | Keyword-based parsing |
+| Agent Notifications | Rich formatting (assumed) | Rich formatting with ANSI colors |
+| Console Output | Clean separation | File-based logging + formatting |
+
+## Future Enhancements
+
+1. **Agent Batching** - Group parallel agent spawns visually
+2. **Dependency Graph Visualization** - CLI tool to view task dependencies
+3. **Performance Metrics** - Track agent completion times
+4. **ML-Based Agent Selection** - Predict best agent for task type
+
+## Troubleshooting
+
+### Import Errors in LSP
+
+**Symptom**: Pyright shows "Import could not be resolved" for `utils/*` modules
+
+**Cause**: LSP can't resolve relative imports in hook scripts
+
+**Solution**: These are false positives. Python resolves imports at runtime via `sys.path.insert(0, ...)` in each hook. Safe to ignore.
+
+### Parallel Delegation Still Fails
+
+**Check**:
+1. Is `~/.stravinsky_mode` file present?
+2. Run: `cat .claude/execution_state.json` - verify state is updating
+3. Run: `cat .claude/task_dependencies.json` - verify dependencies detected
+4. Enable debug: `STRAVINSKY_DEBUG=1` and check logs
+
+### Colors Not Showing
+
+**Check**:
+1. Terminal supports ANSI colors? (`echo $TERM`)
+2. `STRAVINSKY_NO_COLOR` or `NO_COLOR` set?
+3. Is stderr a TTY? (Colors disabled for piped output)
+
+## Maintenance
+
+### Adding New Hooks
+
+1. Create hook file in `.claude/hooks/`
+2. Add to appropriate section in `.claude/settings.json`
+3. Test in isolation with mock input
+4. Update this README
+
+### Modifying State Schema
+
+If changing `execution_state.json` or `task_dependencies.json` format:
+1. Update tracker scripts (`execution_state_tracker.py`, `dependency_tracker.py`)
+2. Update consumer scripts (`parallel_reinforcement_v2.py`)
+3. Add migration logic or document breaking change
+4. Consider versioning state files
+
+### Deprecating Old Hooks
+
+1. Mark as deprecated in comments
+2. Add to "Deprecated" section below
+3. After 1 month, remove from `settings.json`
+4. After 2 months, delete file
+
+## Deprecated Hooks
+
+- `parallel_reinforcement.py` - Replaced by `parallel_reinforcement_v2.py` (state-based)
+  - Removal target: TBD (keep for backward compatibility for now)