@stella-studio/ck 1.0.0

package/.claude/skills/copywriting/scripts/extract-writing-styles.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""
+Extract Writing Styles from assets/writing-styles/ directory.
+
+Supports multiple file types:
+- Text: .md, .txt
+- Documents: .pdf, .docx, .xlsx, .pptx (via document_converter.py)
+- Media: .jpg, .jpeg, .png, .webp, .mp4, .mov (via gemini_batch_process.py)
+
+Usage:
+    python extract-writing-styles.py --list         # List available style files
+    python extract-writing-styles.py --style <name> # Extract specific style
+    python extract-writing-styles.py --all          # Extract all styles
+    python extract-writing-styles.py --all --json   # Output as JSON
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# File type categories
+TEXT_FORMATS = {'.md', '.txt'}
+DOC_FORMATS = {'.pdf', '.docx', '.xlsx', '.pptx'}
+IMAGE_FORMATS = {'.jpg', '.jpeg', '.png', '.webp', '.heic'}
+VIDEO_FORMATS = {'.mp4', '.mov', '.avi', '.mkv'}
+ALL_FORMATS = TEXT_FORMATS | DOC_FORMATS | IMAGE_FORMATS | VIDEO_FORMATS
+
+
+def find_project_root(start_dir: Path) -> Path:
+    """Find project root by looking for .claude directory."""
+    for parent in [start_dir] + list(start_dir.parents):
+        if (parent / '.claude').exists():
+            return parent
+    return start_dir
+
+
+PROJECT_ROOT = find_project_root(Path(__file__).parent)
+STYLES_DIR = PROJECT_ROOT / 'assets' / 'writing-styles'
+AI_MULTIMODAL_SCRIPTS = PROJECT_ROOT / '.claude' / 'skills' / 'ai-multimodal' / 'scripts'
+
+
+def get_style_files() -> Dict[str, Any]:
+    """List all style files in the writing-styles directory."""
+    if not STYLES_DIR.exists():
+        return {'error': f'Directory not found: {STYLES_DIR}', 'files': []}
+
+    files = []
+    for f in STYLES_DIR.iterdir():
+        if f.is_file() and f.suffix.lower() in ALL_FORMATS:
+            files.append({
+                'name': f.stem,
+                'path': str(f),
+                'type': get_file_type(f),
+                'size': f.stat().st_size
+            })
+
+    return {'files': sorted(files, key=lambda x: x['name']), 'directory': str(STYLES_DIR)}
+
+
+def get_file_type(file_path: Path) -> str:
+    """Categorize file by type."""
+    ext = file_path.suffix.lower()
+    if ext in TEXT_FORMATS:
+        return 'text'
+    if ext in DOC_FORMATS:
+        return 'document'
+    if ext in IMAGE_FORMATS:
+        return 'image'
+    if ext in VIDEO_FORMATS:
+        return 'video'
+    return 'unknown'
+
+
+def extract_text_content(file_path: Path) -> str:
+    """Extract content from text files (.md, .txt)."""
+    try:
+        return file_path.read_text(encoding='utf-8')
+    except Exception as e:
+        return f'Error reading file: {e}'
+
+
+def extract_document_content(file_path: Path, verbose: bool = False) -> str:
+    """Extract content from documents using document_converter.py."""
+    converter = AI_MULTIMODAL_SCRIPTS / 'document_converter.py'
+    if not converter.exists():
+        return f'Error: document_converter.py not found at {converter}'
+
+    output_file = STYLES_DIR / f'.temp_{file_path.stem}_extraction.md'
+
+    try:
+        cmd = [
+            sys.executable, str(converter),
+            '--input', str(file_path),
+            '--output', str(output_file),
+            '--prompt', '''Extract the writing style characteristics from this document.
+Identify: tone, vocabulary, sentence structure, rhetorical devices, formatting patterns.
+Output as structured markdown with clear sections.'''
+        ]
+        if verbose:
+            cmd.append('--verbose')
+
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+
+        if output_file.exists():
+            content = output_file.read_text(encoding='utf-8')
+            output_file.unlink()  # Clean up temp file
+            return content
+        else:
+            return f'Conversion failed: {result.stderr}'
+
+    except subprocess.TimeoutExpired:
+        return 'Error: Document conversion timed out'
+    except Exception as e:
+        return f'Error: {e}'
+
+
+def extract_media_content(file_path: Path, verbose: bool = False) -> str:
+    """Extract writing style from media using gemini_batch_process.py."""
+    processor = AI_MULTIMODAL_SCRIPTS / 'gemini_batch_process.py'
+    if not processor.exists():
+        return f'Error: gemini_batch_process.py not found at {processor}'
+
+    try:
+        prompt = '''Analyze this content and identify any writing style characteristics visible.
+Look for: text overlays, captions, typography choices, messaging tone, branding voice.
+Describe the writing style in terms of: tone, vocabulary level, sentence structure, key phrases.
+Output as structured analysis.'''
+
+        cmd = [
+            sys.executable, str(processor),
+            '--files', str(file_path),
+            '--task', 'analyze',
+            '--prompt', prompt
+        ]
+
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        return result.stdout if result.stdout else result.stderr
+
+    except subprocess.TimeoutExpired:
+        return 'Error: Media analysis timed out'
+    except Exception as e:
+        return f'Error: {e}'
+
+
+def extract_style_content(file_path: Path, verbose: bool = False) -> Dict[str, Any]:
+    """Extract writing style content from any supported file type."""
+    if not file_path.exists():
+        return {'error': f'File not found: {file_path}'}
+
+    file_type = get_file_type(file_path)
+
+    if file_type == 'text':
+        content = extract_text_content(file_path)
+    elif file_type == 'document':
+        content = extract_document_content(file_path, verbose)
+    elif file_type in ('image', 'video'):
+        content = extract_media_content(file_path, verbose)
+    else:
+        return {'error': f'Unsupported file type: {file_path.suffix}'}
+
+    # Parse the content for style information
+    result = {
+        'file': str(file_path),
+        'type': file_type,
+        'title': '',
+        'sections': [],
+        'styles': [],
+        'rawContent': content
+    }
+
+    # Extract title from first H1
+    title_match = re.search(r'^#\s+(.+)$', content, re.MULTILINE)
+    if title_match:
+        result['title'] = title_match.group(1).strip()
+
+    # Extract sections (H2 headers)
+    for i, match in enumerate(re.finditer(r'^##\s+(.+)$', content, re.MULTILINE)):
+        result['sections'].append({
+            'title': match.group(1).strip(),
+            'lineNumber': content[:match.start()].count('\n') + 1
+        })
+
+    # Extract style entries from tables
+    table_pattern = r'\|.*?\|.*?\|.*?\|'
+    for match in re.finditer(table_pattern, content, re.MULTILINE):
+        row = match.group(0)
+        if '---' not in row and 'Style' not in row:
+            cols = [c.strip() for c in row.split('|') if c.strip()]
+            if len(cols) >= 2:
+                result['styles'].append({
+                    'name': re.sub(r'\*+', '', cols[0]),
+                    'keywords': cols[1] if len(cols) > 1 else '',
+                    'description': ' | '.join(cols[2:]) if len(cols) > 2 else ''
+                })
+
+    return result
+
+
+def format_output(data: Dict[str, Any], as_json: bool = False) -> str:
+    """Format output for display."""
+    if as_json:
+        return json.dumps(data, indent=2, ensure_ascii=False)
+
+    if 'error' in data:
+        return f"Error: {data['error']}"
+
+    output = []
+
+    if 'files' in data:
+        # List mode
+        output.append('# Available Writing Styles\n')
+        output.append(f"Directory: {data['directory']}\n")
+
+        if not data['files']:
+            output.append('\nNo style files found. Add files to assets/writing-styles/')
+        else:
+            output.append('\n| Style | Type | Size |')
+            output.append('|---|---|---|')
+            for f in data['files']:
+                size_kb = f['size'] / 1024
+                output.append(f"| {f['name']} | {f['type']} | {size_kb:.1f}KB |")
+
+    elif 'title' in data:
+        # Single style extraction
+        if data.get('title'):
+            output.append(f"# {data['title']}\n")
+
+        output.append(f"**File Type:** {data.get('type', 'unknown')}\n")
+
+        if data.get('styles'):
+            output.append(f"\n## Extracted Styles ({len(data['styles'])})\n")
+            for s in data['styles'][:30]:  # Limit to 30 styles
+                output.append(f"### {s['name']}")
+                output.append(f"**Keywords:** {s['keywords']}\n")
+
+        if data.get('sections'):
+            output.append('\n## Sections\n')
+            for s in data['sections']:
+                output.append(f"- {s['title']} (line {s['lineNumber']})")
+
+    return '\n'.join(output)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Extract writing styles from assets/writing-styles/ directory',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Supported formats:
+  Text:      .md, .txt
+  Documents: .pdf, .docx, .xlsx, .pptx (requires GEMINI_API_KEY)
+  Images:    .jpg, .jpeg, .png, .webp (requires GEMINI_API_KEY)
+  Videos:    .mp4, .mov (requires GEMINI_API_KEY)
+
+Examples:
+  python extract-writing-styles.py --list
+  python extract-writing-styles.py --style default
+  python extract-writing-styles.py --all --json
+        '''
+    )
+
+    parser.add_argument('--list', action='store_true', help='List available style files')
+    parser.add_argument('--style', type=str, help='Extract specific style by name')
+    parser.add_argument('--all', action='store_true', help='Extract all styles')
+    parser.add_argument('--json', action='store_true', help='Output as JSON')
+    parser.add_argument('--verbose', '-v', action='store_true', help='Verbose output')
+
+    args = parser.parse_args()
+
+    if args.list or (not args.style and not args.all):
+        result = get_style_files()
+    elif args.style:
+        # Find the file with matching name
+        style_files = get_style_files()
+        if 'error' in style_files:
+            result = style_files
+        else:
+            matching = [f for f in style_files['files'] if f['name'] == args.style]
+            if matching:
+                result = extract_style_content(Path(matching[0]['path']), args.verbose)
+            else:
+                result = {'error': f"Style '{args.style}' not found"}
+    elif args.all:
+        style_files = get_style_files()
+        if 'error' in style_files:
+            result = style_files
+        else:
+            result = {
+                'title': 'All Writing Styles',
+                'files': []
+            }
+            for f in style_files['files']:
+                extracted = extract_style_content(Path(f['path']), args.verbose)
+                result['files'].append({'name': f['name'], **extracted})
+    else:
+        result = get_style_files()
+
+    print(format_output(result, args.json))
+
+
+if __name__ == '__main__':
+    main()

package/.claude/skills/copywriting/templates/copy-brief.md

@@ -0,0 +1,49 @@
+# Copy Brief Template
+
+## Project Info
+
+| Field | Value |
+|-------|-------|
+| Project | |
+| Deliverable | |
+| Due Date | |
+| Writer | |
+
+## Audience
+
+**Who:**
+**Pain points:**
+**Goals:**
+**Awareness level:** (Unaware / Problem-aware / Solution-aware / Product-aware)
+
+## Copy Details
+
+**Type:** (headline / email / landing page / ad / social)
+**Tone:** (professional / casual / urgent / playful)
+**Length:**
+**Primary CTA:**
+
+## Key Messages
+
+1.
+2.
+3.
+
+## Proof Points
+
+-
+-
+
+## Constraints
+
+- Must include:
+- Must avoid:
+- Brand voice notes:
+
+## Formula to Use
+
+[ ] AIDA  [ ] PAS  [ ] BAB  [ ] 4Ps  [ ] FAB
+
+## Success Metrics
+
+-

package/.claude/skills/databases/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: databases
+description: Design schemas, write queries for MongoDB and PostgreSQL. Use for database design, SQL/NoSQL queries, aggregation pipelines, indexes, migrations, replication, performance optimization, psql CLI.
+license: MIT
+---
+
+# Databases Skill
+
+Unified guide for working with MongoDB (document-oriented) and PostgreSQL (relational) databases. Choose the right database for your use case and master both systems.
+
+## When to Use This Skill
+
+Use when:
+- Designing database schemas and data models
+- Writing queries (SQL or MongoDB query language)
+- Building aggregation pipelines or complex joins
+- Optimizing indexes and query performance
+- Implementing database migrations
+- Setting up replication, sharding, or clustering
+- Configuring backups and disaster recovery
+- Managing database users and permissions
+- Analyzing slow queries and performance issues
+- Administering production database deployments
+
+## Reference Navigation
+
+### Database Design
+- **[db-design.md](references/db-design.md)** - Activate when user requests: Database/table design for transactional (OLTP), analytics (OLAP), create or extend schema, design fact/dimension tables, analyze/review CSV/JSON/SQL files to create tables, or need advice on data storage structure.
+
+### MongoDB References
+- **[mongodb-crud.md](references/mongodb-crud.md)** - CRUD operations, query operators, atomic updates
+- **[mongodb-aggregation.md](references/mongodb-aggregation.md)** - Aggregation pipeline, stages, operators, patterns
+- **[mongodb-indexing.md](references/mongodb-indexing.md)** - Index types, compound indexes, performance optimization
+- **[mongodb-atlas.md](references/mongodb-atlas.md)** - Atlas cloud setup, clusters, monitoring, search
+
+### PostgreSQL References
+- **[postgresql-queries.md](references/postgresql-queries.md)** - SELECT, JOINs, subqueries, CTEs, window functions
+- **[postgresql-psql-cli.md](references/postgresql-psql-cli.md)** - psql commands, meta-commands, scripting
+- **[postgresql-performance.md](references/postgresql-performance.md)** - EXPLAIN, query optimization, vacuum, indexes
+- **[postgresql-administration.md](references/postgresql-administration.md)** - User management, backups, replication, maintenance
+
+## Python Utilities
+
+Database utility scripts in `scripts/`:
+- **db_migrate.py** - Generate and apply migrations for both databases (MongoDB and PostgreSQL)
+- **db_backup.py** - Backup and restore MongoDB and PostgreSQL
+- **db_performance_check.py** - Analyze slow queries and recommend indexes
+
+```bash
+# Generate migration
+python scripts/db_migrate.py --db mongodb --generate "add_user_index"
+
+# Run backup
+python scripts/db_backup.py --db postgres --output /backups/
+
+# Check performance
+python scripts/db_performance_check.py --db mongodb --threshold 100ms
+```
+
+## Best Practices
+
+**MongoDB:**
+- Use embedded documents for 1-to-few relationships
+- Reference documents for 1-to-many or many-to-many
+- Index frequently queried fields
+- Use aggregation pipeline for complex transformations
+- Enable authentication and TLS in production
+- Use Atlas for managed hosting
+
+**PostgreSQL:**
+- Normalize schema to 3NF, denormalize for performance
+- Use foreign keys for referential integrity
+- Index foreign keys and frequently filtered columns
+- Use EXPLAIN ANALYZE to optimize queries
+- Regular VACUUM and ANALYZE maintenance
+- Connection pooling (pgBouncer) for web apps
+
+## Resources
+
+- MongoDB: https://www.mongodb.com/docs/
+- PostgreSQL: https://www.postgresql.org/docs/
+- MongoDB University: https://learn.mongodb.com/
+- PostgreSQL Tutorial: https://www.postgresqltutorial.com/

package/.claude/skills/databases/analytics.md

@@ -0,0 +1,198 @@
+# Analytics (OLAP) Rules
+
+> **Note:** Core naming conventions, workflow, and checklist are in `SKILL.md` or `db-design.md` (always loaded).
+
+Guidelines for designing schemas for statistics and reporting tables.
+
+---
+
+## General Principles
+
+- **Separate** from transactional tables - don't mix analytics logic into business tables
+- When heavy analytics queries/aggregations repeat → create separate tables
+- Use **Star Schema**: Fact tables at center, Dimension tables around
+
+---
+
+## Design Process
+
+### 1. Analyze Statistics Requirements
+
+Ask user to clarify:
+- **Analysis dimensions**: by date, by customer, by product, by channel, by region?
+- **Granularity**: per order, per item, per day, per month?
+- **Metrics**: order_count, revenue, margin, conversion_rate, avg_order_value?
+
+### 2. Define Fact Granularity
+
+**Important**: What does 1 row in fact table represent?
+
+| Fact Table | Granularity | Use case |
+|------------|-------------|----------|
+| `fact_orders` | 1 row = 1 order | Statistics by order |
+| `fact_order_items` | 1 row = 1 order item | Statistics by product |
+| `fact_daily_sales` | 1 row = 1 day + store | Daily summary |
+
+### 3. Identify Required Dimensions
+
+Create separate dim table when:
+- Reused in multiple places
+- Has many descriptive attributes
+- Subject to slow changes (Slowly Changing Dimension)
+
+---
+
+## Fact Tables
+
+### Fact table structure
+
+```sql
+CREATE TABLE fact_orders (
+    fact_id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    -- Dimension keys
+    date_key INT NOT NULL,              -- FK to dim_date
+    customer_key BIGINT NOT NULL,       -- FK to dim_customer
+    store_key INT,
+    channel_key INT,
+    -- Degenerate dimensions (no separate dim needed)
+    order_id BIGINT NOT NULL,
+    order_number VARCHAR(50),
+    -- Measures
+    item_count INT NOT NULL,
+    gross_amount DECIMAL(18,2) NOT NULL,
+    discount_amount DECIMAL(18,2) DEFAULT 0,
+    net_amount DECIMAL(18,2) NOT NULL,
+
+    INDEX idx_fact_orders_date (date_key),
+    INDEX idx_fact_orders_customer (customer_key),
+    INDEX idx_fact_orders_date_store (date_key, store_key)
+);
+```
+
+---
+
+## Dimension Tables
+
+### dim_date (required for every analytics schema)
+
+```sql
+CREATE TABLE dim_date (
+    date_key INT PRIMARY KEY,           -- Format: YYYYMMDD (20241215)
+    full_date DATE NOT NULL,
+    year INT NOT NULL,
+    quarter INT NOT NULL,               -- 1-4
+    month INT NOT NULL,                 -- 1-12
+    month_name VARCHAR(20),             -- 'January', 'February'
+    week_of_year INT NOT NULL,
+    day_of_month INT NOT NULL,
+    day_of_week INT NOT NULL,           -- 1=Monday, 7=Sunday
+    day_name VARCHAR(20),
+    is_weekend BOOLEAN NOT NULL,
+    is_holiday BOOLEAN DEFAULT FALSE,
+
+    UNIQUE (full_date)
+);
+-- Pre-populate for multiple years (2020-2030)
+```
+
+### dim_customer
+
+```sql
+CREATE TABLE dim_customer (
+    customer_key BIGINT PRIMARY KEY AUTO_INCREMENT,  -- Surrogate key
+    customer_id BIGINT NOT NULL,                     -- Natural key from users
+    customer_name VARCHAR(255),
+    email VARCHAR(255),
+    segment VARCHAR(50),                -- 'VIP', 'Regular', 'New'
+    city VARCHAR(100),
+    region VARCHAR(100),
+    first_order_date DATE,
+    -- SCD Type 2 columns (if history needed)
+    effective_from DATE NOT NULL,
+    effective_to DATE,
+    is_current BOOLEAN DEFAULT TRUE,
+
+    INDEX idx_dim_customer_id (customer_id),
+    INDEX idx_dim_customer_current (is_current, customer_id)
+);
+```
+
+---
+
+## Summary Tables (Pre-aggregated)
+
+When pre-aggregation needed for dashboard performance:
+
+```sql
+CREATE TABLE summary_daily_sales (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    date_key INT NOT NULL,
+    store_key INT,
+    channel_key INT,
+    -- Pre-aggregated measures
+    order_count INT NOT NULL,
+    item_count INT NOT NULL,
+    gross_revenue DECIMAL(18,2) NOT NULL,
+    net_revenue DECIMAL(18,2) NOT NULL,
+    unique_customers INT NOT NULL,
+    avg_order_value DECIMAL(18,2),
+
+    UNIQUE (date_key, store_key, channel_key),
+    INDEX idx_summary_date (date_key)
+);
+```
+
+---
+
+## Slowly Changing Dimensions (SCD)
+
+### Type 1 - Overwrite
+Overwrite old value, no history kept:
+```sql
+UPDATE dim_customer SET segment = 'VIP' WHERE customer_id = 123;
+```
+
+### Type 2 - Add new row (Recommended when history needed)
+```sql
+-- 1. Close old row
+UPDATE dim_customer
+SET effective_to = CURRENT_DATE - 1, is_current = FALSE
+WHERE customer_id = 123 AND is_current = TRUE;
+
+-- 2. Add new row
+INSERT INTO dim_customer (customer_id, segment, effective_from, is_current)
+VALUES (123, 'VIP', CURRENT_DATE, TRUE);
+```
+
+---
+
+## Indexing for Analytics
+
+### Fact tables
+- Index FKs to dimensions: `date_key`, `customer_key`, `product_key`
+- Composite index based on query patterns: `INDEX (date_key, store_key)`
+
+### Dimension tables
+- PK: surrogate key
+- Index natural key: `customer_id`, `product_id`
+- Index for SCD: `(is_current, customer_id)`
+
+---
+
+## Naming Convention
+
+- Fact tables: `fact_*` or `fct_*`
+- Dimension tables: `dim_*`
+- Summary tables: `summary_*` or `agg_*`
+
+---
+
+## Checklist
+
+- [ ] Granularity defined for each fact table
+- [ ] dim_date exists or created (pre-populate multiple years)
+- [ ] Surrogate keys for dimensions
+- [ ] Index FKs in fact tables
+- [ ] SCD strategy for changing dimensions (Type 1 or Type 2)
+- [ ] Naming: `fact_*`, `dim_*`, `summary_*`
+- [ ] Refresh strategy: see [incremental-etl.md](incremental-etl.md)