@diottodev/runic 1.0.0 → 1.1.0

package/engineering/skills/command-guide/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: "command-guide"
+description: >
+  Claude Code Command Selection Guide - Automatically recommend and select the right
+  commands, agents, and skills in Claude Code.
+  Use when: (1) user is unsure which command or tool to use, (2) needs to decide which
+  agent/skill best fits the current task, (3) querying usage scenarios for /plan, /tdd,
+  /compact, /loop and other commands, (4) understanding when to invoke planner,
+  code-reviewer, build-error-resolver and other agents, (5) needs command cheat sheet
+  or decision flowchart.
+  Triggers: "which command to use", "which agent", "command selection", "how to use /plan",
+  "when to use /compact", "agent selection guide", "command cheat sheet", "skill recommendation".
+---
+
+# Claude Code Command Selection Guide
+
+This skill helps you choose the most appropriate command, agent, or skill for different scenarios.
+
+## Quick Decision Flowchart
+
+```mermaid
+graph TD
+    A[User Request] --> B{Request Type?}
+    B -->|New Feature| C[/plan]
+    B -->|Bug Fix| D[/tdd or build-error-resolver]
+    B -->|Code Review| E[/code-review or code-reviewer agent]
+    B -->|Testing| F[/e2e or tdd-guide agent]
+    B -->|Context Too Long| G[/compact]
+    B -->|Documentation| H[/docs or docs-lookup agent]
+    B -->|Looping Task| I[/loop]
+    B -->|Security Review| J[security-reviewer agent]
+
+    C --> K[planner agent]
+    D --> L{Build Failed?}
+    L -->|Yes| M[build-error-resolver]
+    L -->|No| N[tdd-guide]
+    E --> O[code-reviewer]
+    F --> P[e2e-runner]
+```
+
+## 1. Built-in Slash Commands
+
+### Session Management Commands
+
+| Command | Use Case | Example |
+|---------|----------|---------|
+| `/compact` | Context too long (>150K tokens), slow response, task phase transition | `/compact` or auto-trigger |
+| `/clear` | Start fresh conversation, clear history | `/clear` |
+| `/loop` | Periodic task execution, automated looping work | `/loop 5m check build status` |
+| `/help` | View help, learn commands | `/help` |
+| `/fast` | Need faster response (Opus 4.6 only) | `/fast` |
+| `/model` | Switch model | `/model sonnet` |
+
+### Development Workflow Commands
+
+| Command | Use Case | Activation Timing |
+|---------|----------|-------------------|
+| `/plan` | Start new feature, architecture refactor, complex tasks | **Enter Plan Mode** |
+| `/tdd` | Write tests, TDD development workflow | When test guidance needed |
+| `/e2e` | E2E testing, critical user flow verification | When browser testing needed |
+| `/code-review` | Code quality review | After writing code |
+| `/build-fix` | Build failure, type errors | When build fails |
+| `/learn` | Extract patterns from session, learning | Before session ends |
+| `/skill-create` | Create new skill from git history | When repeating patterns found |
+
+### Documentation & Query Commands
+
+| Command | Use Case | Example |
+|---------|----------|---------|
+| `/docs` | Update project documentation | `/docs` |
+| `/update-codemaps` | Update code maps | `/update-codemaps` |
+| `/remember` | Save memory to memory system | `/remember user prefers concise output` |
+| `/tasks` | View task list | `/tasks` |
+
+---
+
+## 2. Agents Selection
+
+### Development Workflow Agents
+
+| Agent | Trigger Condition | Purpose |
+|-------|-------------------|---------|
+| `planner` | Complex feature request, architectural decision | Create implementation plan |
+| `architect` | System design, tech stack selection | Architecture analysis and decisions |
+| `tdd-guide` | New feature, bug fix | TDD workflow guidance |
+| `code-reviewer` | **Invoke immediately after writing code** | Code quality review |
+| `security-reviewer` | Handling auth, API, sensitive data | Security vulnerability detection |
+
+### Problem Solving Agents
+
+| Agent | Trigger Condition | Purpose |
+|-------|-------------------|---------|
+| `build-error-resolver` | **Invoke immediately when build fails** | Fix build/type errors |
+| `e2e-runner` | Critical user flows, before PR | E2E test execution |
+| `refactor-cleaner` | Code maintenance, dead code cleanup | Dead code detection and cleanup |
+| `doc-updater` | Update docs, codemaps | Documentation sync |
+
+### Research & Exploration Agents
+
+| Agent | Trigger Condition | Purpose |
+|-------|-------------------|---------|
+| `Explore` | Codebase exploration, file finding | Quick codebase exploration |
+| `general-purpose` | Complex multi-step tasks | General task handling |
+| `docs-lookup` | Query library/framework docs | Get latest API documentation |
+
+---
+
+## 3. Skills Selection
+
+### Workflow Skills
+
+| Skill | Trigger Timing | Purpose |
+|-------|----------------|---------|
+| `tdd-workflow` | Developing new feature/fixing bug | Complete TDD workflow guidance |
+| `verification-loop` | After feature completion, before PR | Comprehensive verification (build/test/lint/security) |
+| `strategic-compact` | Long session, context pressure | Guide when to manually `/compact` |
+
+### Architecture & Pattern Skills
+
+| Skill | Trigger Timing | Purpose |
+|-------|----------------|---------|
+| `frontend-patterns` | Frontend development | React/Next.js/Vue best practices |
+| `backend-patterns` | Backend development | API/service architecture patterns |
+| `api-design` | API design | RESTful/API design standards |
+| `mcp-server-patterns` | MCP server development | MCP configuration and patterns |
+
+### Testing Skills
+
+| Skill | Trigger Timing | Purpose |
+|-------|----------------|---------|
+| `e2e-testing` | E2E testing needs | Playwright test generation |
+| `security-review` | Security review needs | OWASP Top 10 detection |
+
+### Research Skills
+
+| Skill | Trigger Timing | Purpose |
+|-------|----------------|---------|
+| `deep-research` | Need deep research | Multi-round search and research |
+| `exa-search` | Need web search | Web content search |
+| `documentation-lookup` | Query library docs | Context7 documentation query |
+
+---
+
+## 4. Scenario Decision Matrix
+
+### By Task Phase
+
+| Phase | Recommended Tool Combination | Reason |
+|-------|------------------------------|--------|
+| **Requirements Analysis** | `planner` + `Explore` | Plan first, explore later |
+| **Architecture Design** | `architect` + `api-design` skill | Professional architecture guidance |
+| **Pre-Development** | `tdd-guide` + `tdd-workflow` skill | Test first |
+| **During Development** | Direct edit + quick iteration | Stay in flow |
+| **Post-Development** | `code-reviewer` + `verification-loop` | Quality gate |
+| **Testing Phase** | `e2e-runner` + `e2e-testing` skill | Complete test coverage |
+| **Before PR** | `security-reviewer` + `verification-loop` | Final verification |
+| **Build Failure** | `build-error-resolver` | Focused fix |
+
+### By Problem Type
+
+| Problem | Invoke Immediately | Note |
+|---------|--------------------|------|
+| Build failure | `build-error-resolver` | Minimal changes, quick fix |
+| Type error | `build-error-resolver` | TypeScript specialist |
+| Bug fix | `tdd-guide` | Write test then fix |
+| Security vulnerability | `security-reviewer` | OWASP detection |
+| Poor code quality | `code-reviewer` | Immediate review |
+| Missing documentation | `doc-updater` | Auto update |
+| Dead code | `refactor-cleaner` | Safe cleanup |
+
+### By Development Type
+
+| Development Type | Skills Combination |
+|------------------|--------------------|
+| Frontend feature | `frontend-patterns` + `tdd-workflow` |
+| Backend API | `backend-patterns` + `api-design` + `tdd-workflow` |
+| MCP server | `mcp-server-patterns` + `tdd-workflow` |
+| Database | `database-reviewer` agent |
+| Security feature | `security-reviewer` + `security-review` skill |
+
+---
+
+## 5. Parallel Execution Strategy
+
+### Parallelizable Scenarios
+
+Recommended: Launch multiple independent tasks simultaneously
+
+Scenario: Preparing PR after code completion
+- Agent 1: code-reviewer (code quality)
+- Agent 2: security-reviewer (security review)
+- Agent 3: e2e-runner (E2E tests)
+
+Scenario: Large refactor analysis
+- Agent 1: architect (architecture analysis)
+- Agent 2: Explore (code exploration)
+- Agent 3: refactor-cleaner (dead code detection)
+
+### Sequential Execution Required
+
+Cannot parallelize: Dependencies exist
+
+Scenario: Fixing build error
+- Sequence: build-error-resolver -> test verification -> code-reviewer
+
+Scenario: New feature development
+- Sequence: planner -> tdd-guide (write tests) -> implementation -> code-reviewer
+
+---
+
+## 6. Auto-Trigger Rules
+
+### Invoke Without User Request
+
+| Situation | Auto Action |
+|-----------|-------------|
+| Code written/modified | **Immediately invoke** `code-reviewer` |
+| Build fails | **Immediately invoke** `build-error-resolver` |
+| Complex feature request | **Immediately invoke** `planner` |
+| Handling auth/sensitive data | **Immediately invoke** `security-reviewer` |
+| New feature/bug fix | **Immediately invoke** `tdd-guide` |
+| Architectural decision | **Immediately invoke** `architect` |
+
+---
+
+## 7. Context Management Timing
+
+| Indicator | Trigger `/compact` |
+|-----------|-------------------|
+| Token > 150K | Immediately compact |
+| Slow response | Suggest compact |
+| Task phase switch | Compact at boundary |
+| Major milestone completed | Compact then continue |
+| Debugging ends -> new task | Clear debug traces |
+
+**Best Practices**:
+- Compact after research, before implementation (preserve plan)
+- Compact after milestone completion (clear intermediate state)
+- Don't compact mid-implementation (lose variables/paths)
+
+---
+
+## 8. Command Cheat Sheet
+
+```
+Development Workflow:
+/plan        -> Enter planning mode (complex tasks)
+/tdd         -> TDD workflow
+/e2e         -> E2E testing
+/code-review -> Code review
+/build-fix   -> Fix build
+
+Session Management:
+/compact     -> Compact context
+/clear       -> Clear session
+/loop        -> Looping task
+/fast        -> Fast mode
+
+Documentation & Memory:
+/docs        -> Update docs
+/remember    -> Save memory
+/tasks       -> View tasks
+
+Help:
+/help        -> View all commands
+```
+
+---
+
+## 9. Usage Examples
+
+### Example 1: New Feature Development
+
+User: Add user authentication feature
+
+Workflow:
+1. /plan -> planner agent creates plan
+2. tdd-guide -> write tests
+3. Implementation -> edit code
+4. code-reviewer -> code review
+5. security-reviewer -> security review (auth sensitive)
+6. e2e-runner -> E2E tests
+7. /compact -> compact after milestone completion
+
+### Example 2: Build Failure
+
+User: npm run build failed
+
+Workflow:
+1. build-error-resolver -> analyze error, minimal fix
+2. Verify build success
+3. code-reviewer -> check fix quality
+
+### Example 3: Code Refactoring
+
+User: Refactor authentication module
+
+Workflow:
+1. architect -> architecture analysis
+2. planner -> implementation plan
+3. refactor-cleaner -> dead code detection
+4. tdd-guide -> ensure test coverage
+5. Implementation -> refactor code
+6. verification-loop -> comprehensive verification
+
+---
+
+**Core Principles**:
+1. **Plan first, implement later** - Use `/plan` for complex tasks
+2. **Test first** - Use `tdd-guide` for new features
+3. **Review immediately after coding** - Use `code-reviewer` when code complete
+4. **Fix build immediately when failed** - Use `build-error-resolver`
+5. **Review sensitive code** - Use `security-reviewer` for auth/API
+6. **Verify comprehensively before PR** - Use `verification-loop`

package/engineering/skills/database-designer/README.md

@@ -0,0 +1,388 @@
+# Database Designer - POWERFUL Tier Skill
+
+A comprehensive database design and analysis toolkit that provides expert-level schema analysis, index optimization, and migration generation capabilities for modern database systems.
+
+## Features
+
+### 🔍 Schema Analyzer
+- **Normalization Analysis**: Automated detection of 1NF through BCNF violations
+- **Data Type Optimization**: Identifies antipatterns and inappropriate types
+- **Constraint Analysis**: Finds missing foreign keys, unique constraints, and checks
+- **ERD Generation**: Creates Mermaid diagrams from DDL or JSON schema
+- **Naming Convention Validation**: Ensures consistent naming patterns
+
+### ⚡ Index Optimizer  
+- **Missing Index Detection**: Identifies indexes needed for query patterns
+- **Composite Index Design**: Optimizes column ordering for maximum efficiency
+- **Redundancy Analysis**: Finds duplicate and overlapping indexes
+- **Performance Modeling**: Estimates selectivity and query performance impact
+- **Covering Index Recommendations**: Eliminates table lookups
+
+### 🚀 Migration Generator
+- **Zero-Downtime Migrations**: Implements expand-contract patterns
+- **Schema Evolution**: Handles column changes, table renames, constraint updates
+- **Data Migration Scripts**: Automated data transformation and validation
+- **Rollback Planning**: Complete reversal capabilities for all changes
+- **Execution Orchestration**: Dependency-aware migration ordering
+
+## Quick Start
+
+### Prerequisites
+- Python 3.7+ (no external dependencies required)
+- Database schema in SQL DDL format or JSON
+- Query patterns (for index optimization)
+
+### Installation
+```bash
+# Clone or download the database-designer skill
+cd engineering/database-designer/
+
+# Make scripts executable
+chmod +x *.py
+```
+
+## Usage Examples
+
+### Schema Analysis
+
+**Analyze SQL DDL file:**
+```bash
+python schema_analyzer.py --input assets/sample_schema.sql --output-format text
+```
+
+**Generate ERD diagram:**
+```bash
+python schema_analyzer.py --input assets/sample_schema.sql --generate-erd --output analysis.txt
+```
+
+**JSON schema analysis:**
+```bash
+python schema_analyzer.py --input assets/sample_schema.json --output-format json --output results.json
+```
+
+### Index Optimization
+
+**Basic index analysis:**
+```bash
+python index_optimizer.py --schema assets/sample_schema.json --queries assets/sample_query_patterns.json
+```
+
+**High-priority recommendations only:**
+```bash
+python index_optimizer.py --schema assets/sample_schema.json --queries assets/sample_query_patterns.json --min-priority 2
+```
+
+**JSON output with existing index analysis:**
+```bash
+python index_optimizer.py --schema assets/sample_schema.json --queries assets/sample_query_patterns.json --format json --analyze-existing
+```
+
+### Migration Generation
+
+**Generate migration between schemas:**
+```bash
+python migration_generator.py --current assets/current_schema.json --target assets/target_schema.json
+```
+
+**Zero-downtime migration:**
+```bash
+python migration_generator.py --current current.json --target target.json --zero-downtime --format sql
+```
+
+**Include validation queries:**
+```bash
+python migration_generator.py --current current.json --target target.json --include-validations --output migration_plan.txt
+```
+
+## Tool Documentation
+
+### Schema Analyzer
+
+**Input Formats:**
+- SQL DDL files (.sql)
+- JSON schema definitions (.json)
+
+**Key Capabilities:**
+- Detects 1NF violations (non-atomic values, repeating groups)
+- Identifies 2NF issues (partial dependencies in composite keys)
+- Finds 3NF problems (transitive dependencies)
+- Checks BCNF compliance (determinant key requirements)
+- Validates data types (VARCHAR(255) antipattern, inappropriate types)
+- Missing constraints (NOT NULL, UNIQUE, CHECK, foreign keys)
+- Naming convention adherence
+
+**Sample Command:**
+```bash
+python schema_analyzer.py \
+  --input sample_schema.sql \
+  --generate-erd \
+  --output-format text \
+  --output analysis.txt
+```
+
+**Output:**
+- Comprehensive text or JSON analysis report
+- Mermaid ERD diagram
+- Prioritized recommendations
+- SQL statements for improvements
+
+### Index Optimizer
+
+**Input Requirements:**
+- Schema definition (JSON format)
+- Query patterns with frequency and selectivity data
+
+**Analysis Features:**
+- Selectivity estimation based on column patterns
+- Composite index column ordering optimization  
+- Covering index recommendations for SELECT queries
+- Foreign key index validation
+- Redundancy detection (duplicates, overlaps, unused indexes)
+- Performance impact modeling
+
+**Sample Command:**
+```bash
+python index_optimizer.py \
+  --schema schema.json \
+  --queries query_patterns.json \
+  --format text \
+  --min-priority 3 \
+  --output recommendations.txt
+```
+
+**Output:**
+- Prioritized index recommendations
+- CREATE INDEX statements
+- Drop statements for redundant indexes
+- Performance impact analysis
+- Storage size estimates
+
+### Migration Generator
+
+**Input Requirements:**
+- Current schema (JSON format)
+- Target schema (JSON format)
+
+**Migration Strategies:**
+- Standard migrations with ALTER statements
+- Zero-downtime expand-contract patterns
+- Data migration and transformation scripts
+- Constraint management (add/drop in correct order)
+- Index management with timing estimates
+
+**Sample Command:**
+```bash
+python migration_generator.py \
+  --current current_schema.json \
+  --target target_schema.json \
+  --zero-downtime \
+  --include-validations \
+  --format text
+```
+
+**Output:**
+- Step-by-step migration plan
+- Forward and rollback SQL statements
+- Risk assessment for each step
+- Validation queries
+- Execution time estimates
+
+## File Structure
+
+```
+database-designer/
+├── README.md                          # This file
+├── SKILL.md                          # Comprehensive database design guide
+├── schema_analyzer.py                # Schema analysis tool
+├── index_optimizer.py                # Index optimization tool  
+├── migration_generator.py            # Migration generation tool
+├── references/                       # Reference documentation
+│   ├── normalization_guide.md        # Normalization principles and patterns
+│   ├── index_strategy_patterns.md    # Index design and optimization guide
+│   └── database_selection_decision_tree.md # Database technology selection
+├── assets/                           # Sample files and test data
+│   ├── sample_schema.sql            # Sample DDL with various issues
+│   ├── sample_schema.json           # JSON schema definition
+│   └── sample_query_patterns.json   # Query patterns for index analysis
+└── expected_outputs/                 # Example tool outputs
+    ├── schema_analysis_sample.txt   # Sample schema analysis report
+    ├── index_optimization_sample.txt # Sample index recommendations
+    └── migration_sample.txt         # Sample migration plan
+```
+
+## JSON Schema Format
+
+The tools use a standardized JSON format for schema definitions:
+
+```json
+{
+  "tables": {
+    "table_name": {
+      "columns": {
+        "column_name": {
+          "type": "VARCHAR(255)",
+          "nullable": true,
+          "unique": false,
+          "foreign_key": "other_table.column",
+          "default": "default_value",
+          "cardinality_estimate": 1000
+        }
+      },
+      "primary_key": ["id"],
+      "unique_constraints": [["email"], ["username"]],
+      "check_constraints": {
+        "chk_positive_price": "price > 0"
+      },
+      "indexes": [
+        {
+          "name": "idx_table_column",
+          "columns": ["column_name"],
+          "unique": false,
+          "partial_condition": "status = 'active'"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Query Patterns Format
+
+For index optimization, provide query patterns in this format:
+
+```json
+{
+  "queries": [
+    {
+      "id": "user_lookup",
+      "type": "SELECT",
+      "table": "users",
+      "where_conditions": [
+        {
+          "column": "email",
+          "operator": "=",
+          "selectivity": 0.95
+        }
+      ],
+      "join_conditions": [
+        {
+          "local_column": "user_id",
+          "foreign_table": "orders",
+          "foreign_column": "id",
+          "join_type": "INNER"
+        }
+      ],
+      "order_by": [
+        {"column": "created_at", "direction": "DESC"}
+      ],
+      "frequency": 1000,
+      "avg_execution_time_ms": 5.2
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### Schema Analysis
+1. **Start with DDL**: Use actual CREATE TABLE statements when possible
+2. **Include Constraints**: Capture all existing constraints and indexes
+3. **Consider History**: Some denormalization may be intentional for performance
+4. **Validate Results**: Review recommendations against business requirements
+
+### Index Optimization  
+1. **Real Query Patterns**: Use actual application queries, not theoretical ones
+2. **Include Frequency**: Query frequency is crucial for prioritization
+3. **Monitor Performance**: Validate recommendations with actual performance testing
+4. **Gradual Implementation**: Add indexes incrementally and monitor impact
+
+### Migration Planning
+1. **Test Migrations**: Always test on non-production environments first
+2. **Backup First**: Ensure complete backups before running migrations
+3. **Monitor Progress**: Watch for locks and performance impacts during execution
+4. **Rollback Ready**: Have rollback procedures tested and ready
+
+## Advanced Usage
+
+### Custom Selectivity Estimation
+The index optimizer uses pattern-based selectivity estimation. You can improve accuracy by providing cardinality estimates in your schema JSON:
+
+```json
+{
+  "columns": {
+    "status": {
+      "type": "VARCHAR(20)",
+      "cardinality_estimate": 5  # Only 5 distinct values
+    }
+  }
+}
+```
+
+### Zero-Downtime Migration Strategy
+For production systems, use the zero-downtime flag to generate expand-contract migrations:
+
+1. **Expand Phase**: Add new columns/tables without constraints
+2. **Dual Write**: Application writes to both old and new structures  
+3. **Backfill**: Populate new structures with existing data
+4. **Contract Phase**: Remove old structures after validation
+
+### Integration with CI/CD
+Integrate these tools into your deployment pipeline:
+
+```bash
+# Schema validation in CI
+python schema_analyzer.py --input schema.sql --output-format json | \
+  jq '.constraint_analysis.total_issues' | \
+  test $(cat) -eq 0 || exit 1
+
+# Generate migrations automatically
+python migration_generator.py \
+  --current prod_schema.json \
+  --target new_schema.json \
+  --zero-downtime \
+  --output migration.sql
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"No tables found in input file"**
+- Ensure SQL DDL uses standard CREATE TABLE syntax
+- Check for syntax errors in DDL
+- Verify file encoding (UTF-8 recommended)
+
+**"Invalid JSON schema"**  
+- Validate JSON syntax with a JSON validator
+- Ensure all required fields are present
+- Check that foreign key references use "table.column" format
+
+**"Analysis shows no issues but problems exist"**
+- Tools use heuristic analysis - review recommendations carefully
+- Some design decisions may be intentional (denormalization for performance)
+- Consider domain-specific requirements not captured by general rules
+
+### Performance Tips
+
+**Large Schemas:**
+- Use `--output-format json` for machine processing
+- Consider analyzing subsets of tables for very large schemas
+- Provide cardinality estimates for better index recommendations
+
+**Complex Queries:**
+- Include actual execution times in query patterns
+- Provide realistic frequency estimates
+- Consider seasonal or usage pattern variations
+
+## Contributing
+
+This is a self-contained skill with no external dependencies. To extend functionality:
+
+1. Follow the existing code patterns
+2. Maintain Python standard library only requirement
+3. Add comprehensive test cases for new features
+4. Update documentation and examples
+
+## License
+
+This database designer skill is part of the claude-skills collection and follows the same licensing terms.