@diottodev/runic 1.0.0 → 1.1.0

package/business/contract-and-proposal-writer/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: "contract-and-proposal-writer"
+description: "Generate professional, jurisdiction-aware business documents: freelance contracts, project proposals, SOWs, NDAs, and MSAs. Structured Markdown output with docx conversion instructions. Covers US (Delaware), EU (GDPR), UK, and DACH (German law) jurisdictions. Not a substitute for legal counsel — use as strong starting points. Use when drafting a freelance contract, preparing a client proposal, writing an SOW for a new engagement, or producing an NDA before sharing sensitive material."
+---
+
+# Contract & Proposal Writer
+
+**Tier:** POWERFUL  
+**Category:** Business Growth  
+**Domain:** Legal Documents, Business Development, Client Relations
+
+---
+
+## Overview
+
+Generate professional, jurisdiction-aware business documents: freelance contracts, project proposals, SOWs, NDAs, and MSAs. Outputs structured Markdown with docx conversion instructions. Covers US (Delaware), EU (GDPR), UK, and DACH (German law) jurisdictions.
+
+**Not a substitute for legal counsel.** Use these templates as strong starting points; review with an attorney for high-value or complex engagements.
+
+---
+
+## Core Capabilities
+
+- Freelance development contracts (fixed-price & hourly)
+- Project proposals with timeline/budget breakdown
+- Statements of Work (SOW) with deliverables matrix
+- NDAs (mutual & one-way)
+- Master Service Agreements (MSA)
+- Jurisdiction-specific clauses (US/EU/UK/DACH)
+- GDPR Data Processing Addenda (EU/DACH)
+
+---
+
+## Key Clauses Reference
+
+| Clause | Options |
+|--------|---------|
+| Payment terms | Net-30, milestone-based, monthly retainer |
+| IP ownership | Work-for-hire (US), assignment (EU/UK), license-back |
+| Liability cap | 1x contract value (standard), 3x (high-risk) |
+| Termination | For cause (14-day cure), convenience (30/60/90-day notice) |
+| Confidentiality | 2-5 year term, perpetual for trade secrets |
+| Warranty | "As-is" disclaimer, limited 30/90-day fix warranty |
+| Dispute resolution | Arbitration (AAA/ICC), courts (jurisdiction-specific) |
+
+---
+
+## When to Use
+
+- Starting a new client engagement and need a contract fast
+- Client asks for a proposal with pricing and timeline
+- Partnership or vendor relationship requiring an MSA
+- Protecting IP or confidential information with an NDA
+- EU/DACH project requiring GDPR-compliant data clauses
+
+---
+
+## Workflow
+
+### 1. Gather Requirements
+
+Ask the user:
+
+    1. Document type? (contract / proposal / SOW / NDA / MSA)
+    2. Jurisdiction? (US-Delaware / EU / UK / DACH)
+    3. Engagement type? (fixed-price / hourly / retainer)
+    4. Parties? (names, roles, business addresses)
+    5. Scope summary? (1-3 sentences)
+    6. Total value or hourly rate?
+    7. Start date / end date or duration?
+    8. Special requirements? (IP assignment, white-label, subcontractors)
+
+### 2. Select Template
+
+| Type | Jurisdiction | Template |
+|------|-------------|----------|
+| Dev contract fixed | Any | Template A |
+| Consulting retainer | Any | Template B |
+| SaaS partnership | Any | Template C |
+| NDA mutual | US/EU/UK/DACH | NDA-M |
+| NDA one-way | US/EU/UK/DACH | NDA-OW |
+| SOW | Any | SOW base |
+
+### 3. Generate & Fill
+
+Fill all [BRACKETED] placeholders. Flag missing data as "REQUIRED".
+
+### 4. Convert to DOCX
+
+```bash
+# Install pandoc
+brew install pandoc        # macOS
+apt install pandoc         # Ubuntu
+
+# Basic conversion
+pandoc contract.md -o contract.docx \
+  --reference-doc=reference.docx \
+  -V geometry:margin=1in
+
+# With numbered sections (legal style)
+pandoc contract.md -o contract.docx \
+  --number-sections \
+  -V documentclass=article \
+  -V fontsize=11pt
+
+# With custom company template
+pandoc contract.md -o contract.docx \
+  --reference-doc=company-template.docx
+```
+
+---
+
+## Jurisdiction Notes
+
+### US (Delaware)
+- Governing law: State of Delaware
+- Work-for-hire doctrine applies (Copyright Act 101)
+- Arbitration: AAA Commercial Rules
+- Non-compete: enforceable with reasonable scope/time
+
+### EU (GDPR)
+- Must include Data Processing Addendum if handling personal data
+- IP assignment requires separate written deed in some member states
+- Arbitration: ICC or local chamber
+
+### UK (post-Brexit)
+- Governed by English law
+- IP: Patents Act 1977 / CDPA 1988
+- Arbitration: LCIA Rules
+- Data: UK GDPR (post-Brexit equivalent)
+
+### DACH (Germany / Austria / Switzerland)
+- BGB (Buergerliches Gesetzbuch) governs contracts
+- Written form requirement for certain clauses (para 126 BGB)
+- IP: Author always retains moral rights; must explicitly transfer Nutzungsrechte
+- Non-competes: max 2 years, compensation required (para 74 HGB)
+- Jurisdiction: German courts (Landgericht) or DIS arbitration
+- DSGVO (GDPR implementation) mandatory for personal data processing
+- Kuendigungsfristen: statutory notice periods apply
+
+---
+
+## Template A: Web Dev Fixed-Price Contract
+
+```markdown
+# SOFTWARE DEVELOPMENT AGREEMENT
+
+**Effective Date:** [DATE]
+**Client:** [CLIENT LEGAL NAME], [ADDRESS] ("Client")
+**Developer:** [YOUR LEGAL NAME / COMPANY], [ADDRESS] ("Developer")
+
+---
+
+## 1. SERVICES
+
+Developer agrees to design, develop, and deliver:
+
+**Project:** [PROJECT NAME]
+**Description:** [1-3 sentence scope]
+
+**Deliverables:**
+- [Deliverable 1] due [DATE]
+- [Deliverable 2] due [DATE]
+- [Deliverable 3] due [DATE]
+
+## 2. PAYMENT
+
+**Total Fee:** [CURRENCY] [AMOUNT]
+
+| Milestone | Amount | Due |
+|-----------|--------|-----|
+| Contract signing | 50% | Upon execution |
+| Beta delivery | 25% | [DATE] |
+| Final acceptance | 25% | Within 5 days of acceptance |
+
+Late payments accrue interest at 1.5% per month.
+Client has [10] business days to accept or reject deliverables in writing.
+
+## 3. INTELLECTUAL PROPERTY
+
+Upon receipt of full payment, Developer assigns all right, title, and interest in the
+Work Product to Client as a work made for hire (US) / by assignment of future copyright (EU/UK).
+
+Developer retains the right to display Work Product in portfolio unless Client
+requests confidentiality in writing within [30] days of delivery.
+
+Pre-existing IP (tools, libraries, frameworks) remains Developer's property.
+Developer grants Client a perpetual, royalty-free license to use pre-existing IP
+as embedded in the Work Product.
+
+## 4. CONFIDENTIALITY
+
+Each party keeps confidential all non-public information received from the other.
+This obligation survives termination for [3] years.
+
+## 5. WARRANTIES
+
+Developer warrants Work Product will substantially conform to specifications for
+[90] days post-delivery. Developer will fix material defects at no charge during
+this period. EXCEPT AS STATED, WORK PRODUCT IS PROVIDED "AS IS."
+
+## 6. LIABILITY
+
+Developer's total liability shall not exceed total fees paid under this Agreement.
+Neither party liable for indirect, incidental, or consequential damages.
+
+## 7. TERMINATION
+
+For Cause: Either party may terminate if the other materially breaches and fails
+to cure within [14] days of written notice.
+
+For Convenience: Client may terminate with [30] days written notice and pay for
+all work completed plus [10%] of remaining contract value.
+
+## 8. DISPUTE RESOLUTION
+
+US: Binding arbitration under AAA Commercial Rules, [CITY], Delaware law.
+EU/DACH: ICC / DIS arbitration, [CITY]. German / English law.
+UK: LCIA Rules, London. English law.
+
+## 9. GENERAL
+
+- Entire Agreement: Supersedes all prior discussions.
+- Amendments: Must be in writing, signed by both parties.
+- Independent Contractor: Developer is not an employee of Client.
+
+---
+
+CLIENT: _________________________ Date: _________
+[CLIENT NAME], [TITLE]
+
+DEVELOPER: _________________________ Date: _________
+[YOUR NAME], [TITLE]
+```
+
+---
+
+## Template B: Monthly Consulting Retainer
+
+```markdown
+# CONSULTING RETAINER AGREEMENT
+
+**Effective Date:** [DATE]
+**Client:** [CLIENT LEGAL NAME] ("Client")
+**Consultant:** [YOUR NAME / COMPANY] ("Consultant")
+
+---
+
+## 1. SERVICES
+
+Consultant provides [DOMAIN, e.g., "CTO advisory and technical architecture"] services.
+
+**Monthly Hours:** Up to [X] hours/month
+**Rollover:** Unused hours [do / do not] roll over (max [X] hours banked)
+**Overflow Rate:** [CURRENCY] [RATE]/hr for hours exceeding retainer
+
+## 2. FEES
+
+**Monthly Retainer:** [CURRENCY] [AMOUNT], due on the 1st of each month.
+**Payment Method:** Bank transfer / Stripe / SEPA direct debit
+**Late Payment:** 2% monthly interest after [10]-day grace period.
+
+## 3. TERM AND TERMINATION
+
+**Initial Term:** [3] months starting [DATE]
+**Renewal:** Auto-renews monthly unless either party gives [30] days written notice.
+**Immediate termination:** For material breach uncured after [7] days notice.
+
+On termination, Consultant delivers all work in progress within [5] business days.
+
+## 4. INTELLECTUAL PROPERTY
+
+Work product created under this Agreement belongs to [Client / Consultant / jointly].
+Advisory output (recommendations, analyses) are Client property upon full payment.
+
+## 5. EXCLUSIVITY
+
+[OPTION A - Non-exclusive:]
+This Agreement is non-exclusive. Consultant may work with other clients.
+
+[OPTION B - Partial exclusivity:]
+Consultant will not work with direct competitors of Client during the term
+and [90] days thereafter.
+
+## 6. CONFIDENTIALITY AND DATA PROTECTION
+
+EU/DACH: If Consultant processes personal data on behalf of Client, the parties
+shall execute a Data Processing Agreement (DPA) per Art. 28 GDPR.
+
+## 7. LIABILITY
+
+Consultant's aggregate liability is capped at [3x] the fees paid in the [3] months
+preceding the claim.
+
+---
+
+Signatures as above.
+```
+
+---
+
+## Template C: SaaS Partnership Agreement
+
+```markdown
+# SAAS PARTNERSHIP AGREEMENT
+
+**Effective Date:** [DATE]
+**Provider:** [NAME], [ADDRESS]
+**Partner:** [NAME], [ADDRESS]
+
+---
+
+## 1. PURPOSE
+
+Provider grants Partner [reseller / referral / white-label / integration] rights to
+Provider's [PRODUCT NAME] ("Software") subject to this Agreement.
+
+## 2. PARTNERSHIP TYPE
+
+[ ] Referral: Partner refers customers; earns [X%] of first-year ARR per referral.
+[ ] Reseller: Partner resells licenses; earns [X%] discount off list price.
+[ ] White-label: Partner rebrands Software; pays [AMOUNT]/month platform fee.
+[ ] Integration: Partner integrates Software via API; terms in Exhibit A.
+
+## 3. REVENUE SHARE
+
+| Tier | Monthly ARR Referred | Commission |
+|------|---------------------|------------|
+| Bronze | < $10,000 | [X]% |
+| Silver | $10,000-$50,000 | [X]% |
+| Gold | > $50,000 | [X]% |
+
+Payout: Net-30 after month close, minimum $[500] threshold.
+
+## 4. INTELLECTUAL PROPERTY
+
+Each party retains all IP in its own products. No implied licenses.
+Partner may use Provider's marks per Provider's Brand Guidelines (Exhibit B).
+
+## 5. DATA AND PRIVACY
+
+Each party is an independent data controller for its own customers.
+Joint processing requires a separate DPA (Exhibit C - EU/DACH projects).
+
+## 6. TERM
+
+Initial: [12] months. Renews annually unless [90]-day written notice given.
+Termination for Cause: [30]-day cure period for material breach.
+
+## 7. LIMITATION OF LIABILITY
+
+Each party's liability capped at [1x] fees paid/received in prior [12] months.
+Mutual indemnification for IP infringement claims from own products.
+
+---
+
+Signatures, exhibits, and governing law per applicable jurisdiction.
+```
+
+---
+
+## GDPR Data Processing Addendum (EU/DACH Clause Block)
+
+```markdown
+## DATA PROCESSING ADDENDUM (Art. 28 GDPR)
+
+Controller: [CLIENT NAME]
+Processor: [CONTRACTOR NAME]
+
+### Subject Matter
+Processor processes personal data on behalf of Controller solely to perform services
+under the main Agreement.
+
+### Categories of Data Subjects
+[e.g., end users, employees, customers]
+
+### Categories of Personal Data
+[e.g., names, email addresses, usage data]
+
+### Processing Duration
+For the term of the main Agreement; deletion within [30] days of termination.
+
+### Processor Obligations
+- Process data only on Controller's documented instructions
+- Ensure persons authorized to process have committed to confidentiality
+- Implement technical and organizational measures per Art. 32 GDPR
+- Assist Controller with data subject rights requests
+- Not engage sub-processors without prior written consent
+- Delete or return all personal data upon termination
+
+### Sub-processors (current as of Effective Date)
+| Sub-processor | Location | Purpose |
+|--------------|----------|---------|
+| [AWS / GCP / Azure] | [Region] | Cloud hosting |
+| [Other] | [Location] | [Purpose] |
+
+### Cross-border Transfers
+Data transfers outside EEA covered by: [ ] SCCs  [ ] Adequacy Decision  [ ] BCRs
+```
+
+---
+
+## Common Pitfalls
+
+1. **Missing IP assignment language** - "work for hire" alone is insufficient in EU; need explicit assignment of Nutzungsrechte in DACH
+2. **Vague acceptance criteria** - Always define what "accepted" means (written sign-off, X days to reject)
+3. **No change order process** - Scope creep kills fixed-price projects; add a clause for out-of-scope work
+4. **Jurisdiction mismatch** - Choosing Delaware law for a German-only project creates enforcement problems
+5. **Missing limitation of liability** - Without a cap, one bug could mean unlimited damages
+6. **Oral amendments** - Contracts modified verbally are hard to enforce; always require written amendments
+
+---
+
+## Best Practices
+
+- Use **milestone payments** over net-30 for projects >$10K - reduces cash flow risk
+- For EU/DACH: always check if a DPA is needed (any personal data = yes)
+- For DACH: include a **Schriftformklausel** (written form clause) explicitly
+- Add a **force majeure** clause for anything over 3 months
+- For retainers: define response time SLAs (e.g., 4h urgent / 24h normal)
+- Keep templates in version control; track changes with `git diff`
+- Review annually - laws change, especially GDPR enforcement interpretations
+- For NDAs: always specify the return/destruction of confidential materials on termination

package/business/customer-success-manager/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: "customer-success-manager"
+description: Monitors customer health, predicts churn risk, and identifies expansion opportunities using weighted scoring models for SaaS customer success. Use when analyzing customer accounts, reviewing retention metrics, scoring at-risk customers, or when the user mentions churn, customer health scores, upsell opportunities, expansion revenue, retention analysis, or customer analytics. Runs three Python CLI tools to produce deterministic health scores, churn risk tiers, and prioritized expansion recommendations across Enterprise, Mid-Market, and SMB segments.
+license: MIT
+metadata:
+  version: 1.0.0
+  author: Alireza Rezvani
+  category: business-growth
+  domain: customer-success
+  updated: 2026-02-06
+  python-tools: health_score_calculator.py, churn_risk_analyzer.py, expansion_opportunity_scorer.py
+  tech-stack: customer-success, saas-metrics, health-scoring
+---
+
+# Customer Success Manager
+
+Production-grade customer success analytics with multi-dimensional health scoring, churn risk prediction, and expansion opportunity identification. Three Python CLI tools provide deterministic, repeatable analysis using standard library only -- no external dependencies, no API calls, no ML models.
+
+---
+
+## Table of Contents
+
+- [Input Requirements](#input-requirements)
+- [Output Formats](#output-formats)
+- [How to Use](#how-to-use)
+- [Scripts](#scripts)
+- [Reference Guides](#reference-guides)
+- [Templates](#templates)
+- [Best Practices](#best-practices)
+- [Limitations](#limitations)
+
+---
+
+## Input Requirements
+
+All scripts accept a JSON file as positional input argument. See `assets/sample_customer_data.json` for complete schema examples and sample data.
+
+### Health Score Calculator
+
+Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, and nested objects `usage` (login_frequency, feature_adoption, dau_mau_ratio), `engagement` (support_ticket_volume, meeting_attendance, nps_score, csat_score), `support` (open_tickets, escalation_rate, avg_resolution_hours), `relationship` (executive_sponsor_engagement, multi_threading_depth, renewal_sentiment), and `previous_period` scores for trend analysis.
+
+### Churn Risk Analyzer
+
+Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, `contract_end_date`, and nested objects `usage_decline`, `engagement_drop`, `support_issues`, `relationship_signals`, and `commercial_factors`.
+
+### Expansion Opportunity Scorer
+
+Required fields per customer object: `customer_id`, `name`, `segment`, `arr`, and nested objects `contract` (licensed_seats, active_seats, plan_tier, available_tiers), `product_usage` (per-module adoption flags and usage percentages), and `departments` (current and potential).
+
+---
+
+## Output Formats
+
+All scripts support two output formats via the `--format` flag:
+
+- **`text`** (default): Human-readable formatted output for terminal viewing
+- **`json`**: Machine-readable JSON output for integrations and pipelines
+
+---
+
+## How to Use
+
+### Quick Start
+
+```bash
+# Health scoring
+python scripts/health_score_calculator.py assets/sample_customer_data.json
+python scripts/health_score_calculator.py assets/sample_customer_data.json --format json
+
+# Churn risk analysis
+python scripts/churn_risk_analyzer.py assets/sample_customer_data.json
+python scripts/churn_risk_analyzer.py assets/sample_customer_data.json --format json
+
+# Expansion opportunity scoring
+python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json
+python scripts/expansion_opportunity_scorer.py assets/sample_customer_data.json --format json
+```
+
+### Workflow Integration
+
+```bash
+# 1. Score customer health across portfolio
+python scripts/health_score_calculator.py customer_portfolio.json --format json > health_results.json
+# Verify: confirm health_results.json contains the expected number of customer records before continuing
+
+# 2. Identify at-risk accounts
+python scripts/churn_risk_analyzer.py customer_portfolio.json --format json > risk_results.json
+# Verify: confirm risk_results.json is non-empty and risk tiers are present for each customer
+
+# 3. Find expansion opportunities in healthy accounts
+python scripts/expansion_opportunity_scorer.py customer_portfolio.json --format json > expansion_results.json
+# Verify: confirm expansion_results.json lists opportunities ranked by priority
+
+# 4. Prepare QBR using templates
+# Reference: assets/qbr_template.md
+```
+
+**Error handling:** If a script exits with an error, check that:
+- The input JSON matches the required schema for that script (see Input Requirements above)
+- All required fields are present and correctly typed
+- Python 3.7+ is being used (`python --version`)
+- Output files from prior steps are non-empty before piping into subsequent steps
+
+---
+
+## Scripts
+
+### 1. health_score_calculator.py
+
+**Purpose:** Multi-dimensional customer health scoring with trend analysis and segment-aware benchmarking.
+
+**Dimensions and Weights:**
+| Dimension | Weight | Metrics |
+|-----------|--------|---------|
+| Usage | 30% | Login frequency, feature adoption, DAU/MAU ratio |
+| Engagement | 25% | Support ticket volume, meeting attendance, NPS/CSAT |
+| Support | 20% | Open tickets, escalation rate, avg resolution time |
+| Relationship | 25% | Executive sponsor engagement, multi-threading depth, renewal sentiment |
+
+**Classification:**
+- Green (75-100): Healthy -- customer achieving value
+- Yellow (50-74): Needs attention -- monitor closely
+- Red (0-49): At risk -- immediate intervention required
+
+**Usage:**
+```bash
+python scripts/health_score_calculator.py customer_data.json
+python scripts/health_score_calculator.py customer_data.json --format json
+```
+
+### 2. churn_risk_analyzer.py
+
+**Purpose:** Identify at-risk accounts with behavioral signal detection and tier-based intervention recommendations.
+
+**Risk Signal Weights:**
+| Signal Category | Weight | Indicators |
+|----------------|--------|------------|
+| Usage Decline | 30% | Login trend, feature adoption change, DAU/MAU change |
+| Engagement Drop | 25% | Meeting cancellations, response time, NPS change |
+| Support Issues | 20% | Open escalations, unresolved critical, satisfaction trend |
+| Relationship Signals | 15% | Champion left, sponsor change, competitor mentions |
+| Commercial Factors | 10% | Contract type, pricing complaints, budget cuts |
+
+**Risk Tiers:**
+- Critical (80-100): Immediate executive escalation
+- High (60-79): Urgent CSM intervention
+- Medium (40-59): Proactive outreach
+- Low (0-39): Standard monitoring
+
+**Usage:**
+```bash
+python scripts/churn_risk_analyzer.py customer_data.json
+python scripts/churn_risk_analyzer.py customer_data.json --format json
+```
+
+### 3. expansion_opportunity_scorer.py
+
+**Purpose:** Identify upsell, cross-sell, and expansion opportunities with revenue estimation and priority ranking.
+
+**Expansion Types:**
+- **Upsell**: Upgrade to higher tier or more of existing product
+- **Cross-sell**: Add new product modules
+- **Expansion**: Additional seats or departments
+
+**Usage:**
+```bash
+python scripts/expansion_opportunity_scorer.py customer_data.json
+python scripts/expansion_opportunity_scorer.py customer_data.json --format json
+```
+
+---
+
+## Reference Guides
+
+| Reference | Description |
+|-----------|-------------|
+| `references/health-scoring-framework.md` | Complete health scoring methodology, dimension definitions, weighting rationale, threshold calibration |
+| `references/cs-playbooks.md` | Intervention playbooks for each risk tier, onboarding, renewal, expansion, and escalation procedures |
+| `references/cs-metrics-benchmarks.md` | Industry benchmarks for NRR, GRR, churn rates, health scores, expansion rates by segment and industry |
+
+---
+
+## Templates
+
+| Template | Purpose |
+|----------|---------|
+| `assets/qbr_template.md` | Quarterly Business Review presentation structure |
+| `assets/success_plan_template.md` | Customer success plan with goals, milestones, and metrics |
+| `assets/onboarding_checklist_template.md` | 90-day onboarding checklist with phase gates |
+| `assets/executive_business_review_template.md` | Executive stakeholder review for strategic accounts |
+
+---
+
+## Best Practices
+
+1. **Combine signals**: Use all three scripts together for a complete customer picture
+2. **Act on trends, not snapshots**: A declining Green is more urgent than a stable Yellow
+3. **Calibrate thresholds**: Adjust segment benchmarks based on your product and industry per `references/health-scoring-framework.md`
+4. **Prepare with data**: Run scripts before every QBR and executive meeting; reference `references/cs-playbooks.md` for intervention guidance
+
+---
+
+## Limitations
+
+- **No real-time data**: Scripts analyze point-in-time snapshots from JSON input files
+- **No CRM integration**: Data must be exported manually from your CRM/CS platform
+- **Deterministic only**: No predictive ML -- scoring is algorithmic based on weighted signals
+- **Threshold tuning**: Default thresholds are industry-standard but may need calibration for your business
+- **Revenue estimates**: Expansion revenue estimates are approximations based on usage patterns
+
+---
+
+**Last Updated:** February 2026
+**Tools:** 3 Python CLI tools
+**Dependencies:** Python 3.7+ standard library only