anvil-dev-framework 0.1.7 → 0.1.9

package/project/hooks/utils/tts/openai_tts.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "openai",
+#     "openai[voice_helpers]",
+#     "python-dotenv",
+# ]
+# ///
+
+import os
+import sys
+import asyncio
+from dotenv import load_dotenv
+
+
+async def main():
+    """
+    OpenAI TTS Script
+
+    Uses OpenAI's latest TTS model for high-quality text-to-speech.
+    Accepts optional text prompt as command-line argument.
+
+    Usage:
+    - ./openai_tts.py                    # Uses default text
+    - ./openai_tts.py "Your custom text" # Uses provided text
+
+    Features:
+    - OpenAI gpt-4o-mini-tts model (latest)
+    - Nova voice (engaging and warm)
+    - Streaming audio with instructions support
+    - Live audio playback via LocalAudioPlayer
+    """
+
+    # Load environment variables
+    load_dotenv()
+
+    # Get API key from environment
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        print("❌ Error: OPENAI_API_KEY not found in environment variables")
+        print("Please add your OpenAI API key to .env file:")
+        print("OPENAI_API_KEY=your_api_key_here")
+        sys.exit(1)
+
+    try:
+        from openai import AsyncOpenAI
+        from openai.helpers import LocalAudioPlayer
+
+        # Initialize OpenAI client
+        openai = AsyncOpenAI(api_key=api_key)
+
+        print("🎙️  OpenAI TTS")
+        print("=" * 20)
+
+        # Get text from command line argument or use default
+        if len(sys.argv) > 1:
+            text = " ".join(sys.argv[1:])  # Join all arguments as text
+        else:
+            text = "Today is a wonderful day to build something people love!"
+
+        print(f"🎯 Text: {text}")
+        print("🔊 Generating and streaming...")
+
+        try:
+            # Generate and stream audio using OpenAI TTS
+            async with openai.audio.speech.with_streaming_response.create(
+                model="gpt-4o-mini-tts",
+                voice="nova",
+                input=text,
+                instructions="Speak in a cheerful, positive yet professional tone.",
+                response_format="mp3",
+            ) as response:
+                await LocalAudioPlayer().play(response)
+
+            print("✅ Playback complete!")
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+
+    except ImportError:
+        print("❌ Error: Required package not installed")
+        print("This script uses UV to auto-install dependencies.")
+        print("Make sure UV is installed: https://docs.astral.sh/uv/")
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Unexpected error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/project/hooks/utils/tts/pyttsx3_tts.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "pyttsx3",
+# ]
+# ///
+
+import sys
+import random
+
+def main():
+    """
+    pyttsx3 TTS Script
+
+    Uses pyttsx3 for offline text-to-speech synthesis.
+    Accepts optional text prompt as command-line argument.
+
+    Usage:
+    - ./pyttsx3_tts.py                    # Uses default text
+    - ./pyttsx3_tts.py "Your custom text" # Uses provided text
+
+    Features:
+    - Offline TTS (no API key required)
+    - Cross-platform compatibility
+    - Configurable voice settings
+    - Immediate audio playback
+    """
+
+    try:
+        import pyttsx3
+
+        # Initialize TTS engine
+        engine = pyttsx3.init()
+
+        # Configure engine settings
+        engine.setProperty('rate', 180)    # Speech rate (words per minute)
+        engine.setProperty('volume', 0.8)  # Volume (0.0 to 1.0)
+
+        print("🎙️  pyttsx3 TTS")
+        print("=" * 15)
+
+        # Get text from command line argument or use default
+        if len(sys.argv) > 1:
+            text = " ".join(sys.argv[1:])  # Join all arguments as text
+        else:
+            # Default completion messages
+            completion_messages = [
+                "Work complete!",
+                "All done!",
+                "Task finished!",
+                "Job complete!",
+                "Ready for next task!"
+            ]
+            text = random.choice(completion_messages)
+
+        print(f"🎯 Text: {text}")
+        print("🔊 Speaking...")
+
+        # Speak the text
+        engine.say(text)
+        engine.runAndWait()
+
+        print("✅ Playback complete!")
+
+    except ImportError:
+        print("❌ Error: pyttsx3 package not installed")
+        print("This script uses UV to auto-install dependencies.")
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/project/linear.yaml.template

@@ -0,0 +1,23 @@
+# Linear Integration Configuration
+#
+# This file maps your local project to a Linear team/project.
+# Commands like /orient, /sprint, /tasks will use this to filter issues.
+#
+# Run `/linear-setup` to configure interactively, or edit manually.
+
+# Required: Linear team key (e.g., "AMP", "ANV", "ENG")
+# Find this in Linear: Settings → Teams → [Team] → Key
+team_key: ""
+
+# Optional: Specific Linear project within the team
+# Leave empty to see all team issues
+project_name: ""
+
+# Auto-generated: Issue prefix for this team (usually same as team_key)
+issue_prefix: ""
+
+# Auto-generated: Team UUID (set by /linear-setup)
+team_id: ""
+
+# Auto-generated: Project UUID (set by /linear-setup)
+project_id: ""

package/project/product.md.template

@@ -0,0 +1,238 @@
+# Product Definition
+
+> What we're building, why, and for whom.
+
+---
+
+## Quick Start (Answer These First)
+
+Fill in these essential questions to get started. Expand into the detailed sections below as your project matures.
+
+### What does this project do in one sentence?
+> [Your answer here]
+
+### Who are the primary users and what problem do they have?
+> [Your answer here]
+
+### What technologies are you using and why?
+> [Your answer here]
+
+### What are you working on RIGHT NOW?
+> [Your answer here]
+
+### What comes after the current focus? What's explicitly out of scope?
+> [Your answer here]
+
+### How do you know if this project is successful?
+> [Your answer here]
+
+---
+
+## Detailed Sections
+
+*Expand into these sections as needed. Not all sections are required initially.*
+
+---
+
+## Mission
+
+### One-Line Mission
+[A single sentence describing what this product does and why it matters]
+
+### Elevator Pitch
+[Product name] is a [category] that helps [target user] to [primary benefit] by [key differentiator]. Unlike [alternatives], we [unique value].
+
+### Why This Matters
+[2-3 sentences on the problem being solved and why it's worth solving]
+
+---
+
+## Core Value Propositions
+
+### 1. [Value Prop 1 Name]
+**What**: [Brief description]
+**Why it matters**: [Benefit to user]
+**How we deliver**: [Key feature/approach]
+
+### 2. [Value Prop 2 Name]
+**What**: [Brief description]
+**Why it matters**: [Benefit to user]
+**How we deliver**: [Key feature/approach]
+
+### 3. [Value Prop 3 Name]
+**What**: [Brief description]
+**Why it matters**: [Benefit to user]
+**How we deliver**: [Key feature/approach]
+
+---
+
+## Target Users
+
+### Primary Persona: [Name]
+- **Who**: [Demographics, role]
+- **Goals**: [What they want to achieve]
+- **Pain Points**: [Current frustrations]
+- **Why Us**: [Why our solution fits]
+
+### Secondary Persona: [Name]
+- **Who**: [Demographics, role]
+- **Goals**: [What they want to achieve]
+- **Pain Points**: [Current frustrations]
+- **Why Us**: [Why our solution fits]
+
+### Anti-Personas (Who We're NOT For)
+- [Description of users we explicitly don't target]
+- [Description of users we explicitly don't target]
+
+---
+
+## Product Principles
+
+These guide all product decisions:
+
+1. **[Principle 1]**: [Explanation]
+2. **[Principle 2]**: [Explanation]
+3. **[Principle 3]**: [Explanation]
+4. **[Principle 4]**: [Explanation]
+5. **[Principle 5]**: [Explanation]
+
+---
+
+## Tech Stack Rationale
+
+### Why [Framework]
+- [Reason 1]
+- [Reason 2]
+- [Trade-off acknowledged]
+
+### Why [Database]
+- [Reason 1]
+- [Reason 2]
+- [Trade-off acknowledged]
+
+### Why [Hosting]
+- [Reason 1]
+- [Reason 2]
+- [Trade-off acknowledged]
+
+### What We Explicitly Avoided
+- **[Technology]**: [Why we didn't choose it]
+- **[Technology]**: [Why we didn't choose it]
+
+---
+
+## Current Roadmap
+
+### Now (Current Sprint)
+| Priority | Feature | Status |
+|----------|---------|--------|
+| P0 | [Feature] | In Progress |
+| P1 | [Feature] | Todo |
+
+### Next (Next Sprint)
+| Priority | Feature | Dependencies |
+|----------|---------|--------------|
+| P1 | [Feature] | [Current feature] |
+| P2 | [Feature] | None |
+
+### Later (Backlog)
+| Priority | Feature | Notes |
+|----------|---------|-------|
+| P2 | [Feature] | [Context] |
+| P3 | [Feature] | [Context] |
+
+### Not Doing (Explicitly Rejected)
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why not] |
+| [Feature] | [Why not] |
+
+---
+
+## Success Metrics
+
+### North Star Metric
+**[Metric Name]**: [Definition]
+**Target**: [Specific target]
+**Why This Metric**: [Explanation]
+
+### Leading Indicators
+| Metric | Target | Frequency |
+|--------|--------|-----------|
+| [Metric] | [Target] | Daily |
+| [Metric] | [Target] | Weekly |
+
+### Lagging Indicators
+| Metric | Target | Frequency |
+|--------|--------|-----------|
+| [Metric] | [Target] | Monthly |
+| [Metric] | [Target] | Quarterly |
+
+### What We Don't Optimize For
+- [Metric we explicitly deprioritize and why]
+- [Metric we explicitly deprioritize and why]
+
+---
+
+## Competitive Landscape
+
+### Direct Competitors
+| Competitor | Strength | Weakness | Our Differentiation |
+|------------|----------|----------|---------------------|
+| [Name] | [Strength] | [Weakness] | [How we're different] |
+| [Name] | [Strength] | [Weakness] | [How we're different] |
+
+### Indirect Competitors / Alternatives
+| Alternative | When Users Choose It | Our Response |
+|-------------|---------------------|--------------|
+| [Name] | [Scenario] | [Our counter] |
+| [Name] | [Scenario] | [Our counter] |
+
+---
+
+## Constraints
+
+### Technical Constraints
+- [Constraint and why]
+- [Constraint and why]
+
+### Business Constraints
+- [Constraint and why]
+- [Constraint and why]
+
+### Design Constraints
+- [Constraint and why]
+- [Constraint and why]
+
+---
+
+## Open Questions
+
+Questions we haven't resolved yet:
+
+1. **[Question]**
+   - Context: [Why this matters]
+   - Options: [A, B, C]
+   - Deadline: [When we need to decide]
+
+2. **[Question]**
+   - Context: [Why this matters]
+   - Options: [A, B, C]
+   - Deadline: [When we need to decide]
+
+---
+
+## Decision Log
+
+Major product decisions and their rationale:
+
+### [Date]: [Decision]
+- **Context**: [Why this came up]
+- **Options Considered**: [A, B, C]
+- **Decision**: [What we chose]
+- **Rationale**: [Why]
+- **Trade-offs Accepted**: [What we gave up]
+
+---
+
+*Update this document as the product evolves. This is the single source of truth for what we're building and why.*

package/project/retros/README.md

@@ -0,0 +1,126 @@
+# Retrospectives
+
+> Learn from what happened. Keep it simple.
+
+---
+
+## Philosophy
+
+**Write retros that you'll actually write.**
+
+Complex formats create friction → retros don't get written → learning doesn't happen.
+
+Simple format: Narrative first, structure optional.
+
+---
+
+## When to Write Retros
+
+- After completing a significant feature
+- After a bug that took >1 hour to diagnose
+- After discovering unexpected complexity
+- After any "I wish I had known..." moment
+- Weekly (even if brief)
+
+## When NOT to Write Retros
+
+- After trivial changes
+- When there's nothing to learn
+- When it would be pure ceremony
+
+---
+
+## Format: Narrative First
+
+```markdown
+# [Issue ID]: [Brief descriptive title]
+
+**Outcome:** success | partial | failed
+**Date:** YYYY-MM-DD
+
+## What Happened
+[Narrative: What did you try? What worked? What didn't? Why?]
+
+## Key Learning
+[One concrete thing you learned]
+
+## For Next Time
+[One specific thing to do differently]
+```
+
+That's it. Three sections, narrative style.
+
+---
+
+## Example Retro
+
+```markdown
+# ENG-42: Password Reset Token Generation
+
+**Outcome:** success
+**Date:** 2025-12-17
+
+## What Happened
+Started by copying the email verification token pattern, but password 
+reset has different requirements - tokens need to be single-use and 
+expire faster. Spent 30 minutes debugging why tokens weren't invalidating
+before realizing the existing pattern didn't include the `used_at` column.
+
+Ended up creating a separate table rather than retrofitting the existing one.
+This was the right call - cleaner separation of concerns.
+
+## Key Learning
+Don't assume similar-sounding features can share infrastructure. 
+Check the actual requirements before copying patterns.
+
+## For Next Time
+When copying patterns, make a checklist of requirements for the new 
+use case FIRST, then evaluate if the existing pattern meets them.
+```
+
+---
+
+## File Organization
+
+```
+.claude/retros/
+├── README.md
+├── 2025-12/
+│   ├── ENG-42-password-reset.md
+│   └── ENG-45-oauth-integration.md
+└── 2025-11/
+    └── ...
+```
+
+- Organize by month (reduces clutter)
+- Name files: `[ISSUE-ID]-[slug].md`
+- Archive older months when >20 files
+
+---
+
+## What NOT to Include
+
+❌ **YAML frontmatter with 10+ fields** — Creates friction
+❌ **Structured sections for everything** — Makes it feel like a form  
+❌ **Metrics and scores** — Over-engineering
+❌ **Multi-level categorization** — Analysis paralysis
+
+---
+
+## Synthesis: /insights
+
+Individual retros capture learnings. The `/insights` command synthesizes patterns:
+
+- Run weekly (or when starting similar work)
+- Identifies patterns across retros (2+ occurrences)
+- Outputs actionable recommendations
+
+See: `~/.claude/commands/insights.md`
+
+---
+
+## Success Metric
+
+**Retros get written.**
+
+If you're not writing retros, the format is too complex. Simplify until you do.

package/project/rules/README.md

@@ -0,0 +1,90 @@
+# Claude Rules
+
+> Modular rule files that Claude loads automatically alongside CLAUDE.md.
+
+---
+
+## Purpose
+
+The `.claude/rules/` directory provides a location for supplementary rules that:
+- Apply to specific contexts (security, testing, API design)
+- Can be injected into sub-agents via hooks
+- Keep CLAUDE.md focused on project-level guidance
+
+---
+
+## How It Works
+
+1. **Automatic loading**: Claude reads markdown files in this directory
+2. **Hook injection**: SubagentStart hook can inject specific rules based on agent type
+3. **Modular organization**: Each file focuses on one domain
+
+---
+
+## Suggested Files
+
+| File | Purpose |
+|------|---------|
+| `security.md` | Security requirements and checklists |
+| `testing.md` | Testing standards and coverage requirements |
+| `api-design.md` | API conventions and standards |
+| `code-style.md` | Style guidelines beyond linter rules |
+
+---
+
+## Example: security.md
+
+```markdown
+# Security Rules
+
+## Input Validation
+- All user input must be validated
+- Use parameterized queries for SQL
+- Encode output to prevent XSS
+
+## Authentication
+- Passwords must use bcrypt/argon2
+- Session tokens must be cryptographically random
+- Enforce token expiration
+
+## Authorization
+- Implement role-based access control
+- Check permissions on every API endpoint
+- Prevent privilege escalation
+```
+
+---
+
+## Integration with Sub-Agents
+
+Rules can be injected into sub-agents using the SubagentStart hook:
+
+```python
+# In subagent_start.py
+context_map = {
+    "security-code-reviewer": ".claude/rules/security.md",
+    "cross-layer-debugger": ".claude/rules/debugging.md",
+}
+```
+
+See `.claude/hooks/subagent_start.py` for implementation details.
+
+---
+
+## Best Practices
+
+### Do:
+- Keep rules focused and actionable
+- Use checklists for review processes
+- Reference industry standards (OWASP, CWE)
+- Update rules as project evolves
+
+### Don't:
+- Duplicate content from CLAUDE.md
+- Create rules for one-time guidance
+- Make rules too long (keep under 200 lines)
+- Include code examples unless necessary
+
+---
+
+*Introduced in Claude Code 2.0.64*