# Hydra PLG Strategy
**Version:** 1.0 | 2026-04-30
**Status:** DRAFT

---

## 1. Overview and Principles

Hydra is product-led. The product acquires, activates, retains, and expands revenue without a sales team. Every function that a traditional SaaS company assigns to a sales or marketing rep is handled by the product itself or by automated systems triggered by product behavior.

This is not a cost-saving measure. PLG is the right model for Hydra because the buyer is also the user. Engineering teams adopt developer tools the same way they adopt any technical dependency: they evaluate it themselves, they install it, they form an opinion based on what it does, and they pay for it when it proves its value. A sales rep cannot substitute for that experience. A demo cannot substitute for the first autonomous fix appearing in their actual codebase.

PLG does not mean no marketing. It means the product is the primary conversion mechanism. Marketing's job is to drive installs and create the conditions under which the product can do its work.

**The five functions PLG must execute without a sales team:**

1. **Acquire**: Get developers to install Hydra on a real repo
2. **Activate**: Get them to experience the first autonomous fix
3. **Retain**: Make Hydra a dependency they cannot imagine removing
4. **Convert**: Move them from free to paid at the natural limit
5. **Expand**: Grow revenue from within existing accounts over time

Every strategic decision in this document is evaluated against one question: does this make the product better at one of those five functions?

---

## 2. The Hydra PLG Loop

```
ACQUIRE
GitHub Marketplace / SEO / Community / Word of Mouth
    |
    v
INSTALL (GitHub App, 2 clicks, no credit card)
    |
    v
ACTIVATE
Discovery runs. .hydra/ directory created. Codebase mapped.
    |
    v
AHA MOMENT
First autonomous fix executes. PR opens. Linear ticket closes.
Developer did nothing.
    |
    v
RETAIN (ACTIVE)
Every PR triggers Hydra. Product is in the workflow automatically.
    |
    v
RETAIN (PASSIVE)
Improve layer runs continuously. Codebase gets cleaner.
Developer notices without being prompted.
    |
    v
VIRAL LOOP
.hydra/ directory visible in repo. Teammates see autonomous PRs.
"What is this?" Internal spread within org.
    |
    v
HIT LIMIT (5 fixes/month)
Non-punitive upgrade prompt. User already knows it works.
    |
    v
CONVERT (Free to Team, $20/dev/month)
Stripe Checkout. No sales call. Self-serve.
    |
    v
EXPAND
Team grows. Repos grow. Team to Business. Business to Enterprise.
NRR > 100%.
    |
    v [loop repeats inside account]
```

---

## 3. Acquisition

### The Primary Surface: GitHub Marketplace

GitHub Marketplace is where engineering teams discover developer tools. It is the highest-intent discovery channel for a product like Hydra: developers searching there are actively looking for tools to install on their repos. The GitHub App listing is not an ad: it is a conversion page that must do the full job of explaining what Hydra does and why to install it.

The GitHub App listing requires:
- A headline that communicates autonomous execution, not advisory review
- A short description optimized for Marketplace search (keywords: code review, autonomous, fix, governance)
- Screenshots showing a real fix being executed: before/after diff, PR description, Linear ticket closed
- A clear free tier statement: "Start free. No credit card."
- A social proof hook: installs, repos, or fixes executed (placeholder until data exists)

**GitHub Marketplace is not optional.** It is the PLG install surface. Everything else drives traffic toward it.

### SEO: Developer-Intent Queries

Developers search before they buy. The content strategy for acquisition is built around the queries a developer types when they are experiencing the AI velocity paradox.

**High-intent queries to own:**

| Query | Intent | Content Type |
|---|---|---|
| "AI code review tool" | Evaluating options | Comparison page, landing page |
| "autonomous code review" | Looking for execution, not advisory | Landing page, blog |
| "code review automation GitHub" | Workflow-specific | Integration page, how-to |
| "fix code automatically AI" | Outcome-specific | Landing page |
| "technical debt automation" | Improve layer intent | Blog, use case page |
| "code governance automation" | Govern layer intent | Blog, landing page |
| "CodeRabbit alternative" | Competitor displacement | Comparison page |
| "Qodo alternative" | Competitor displacement | Comparison page |
| "replace SonarQube AI" | Competitor displacement | Comparison page |
| "AI velocity paradox" | Market context, thought leadership | Blog |

Competitor comparison pages ("Hydra vs. CodeRabbit," "Hydra vs. Qodo") are high-converting PLG acquisition assets because the user is already in evaluation mode. These pages do not need to be aggressive: they just need to clearly show the category difference: every competitor is advisory, Hydra executes.

### Community Channels

Developer communities are trust-based. The install decision for a developer tool is often made after seeing it discussed by another developer they respect. Community presence is a long-game acquisition channel that compounds over time.

**Primary channels:**

**Hacker News:** Show HN post at launch ("Show HN: Hydra: autonomous code governance agent that fixes, improves, and governs your codebase"). The HN developer community is the right audience. A strong Show HN can drive thousands of installs in 24 hours. The post needs to be honest, technical, and specific. No marketing language.

**GitHub:** The product's natural home. Stars, forks, and issues on the Hydra public repo are social proof. Contributing to discussions in related repos (code quality, AI tooling) builds organic presence. The .hydra/ directory appearing in public repos is inherently visible.

**Reddit:** r/programming, r/devops, r/MachineLearning (for the AI angle), r/ExperiencedDevs. Developer-authentic content: genuine value, no spam. Post when there is something genuinely worth sharing: a benchmark result, a case study, a technical deep-dive.

**Dev.to / Hashnode:** Long-form technical content that ranks in search and builds credibility. "How we built autonomous fix execution," "The AI velocity paradox and why better code review is the wrong solution."

**Twitter/X:** Developer community is active and fast-moving. Follow and engage with developers talking about code quality, AI-generated code problems, and developer productivity. Post specific results, not abstract claims.

**Podcasts:** Changelog, Software Engineering Daily, DevDiscuss, Syntax. These audiences are senior engineers and engineering leaders: the exact ICP. A single strong podcast appearance can drive hundreds of installs from the right audience.

### Word of Mouth and Virality

Word of mouth is not passive in PLG. It is engineered through the product.

The primary viral mechanic for Hydra is the `.hydra/` directory. When a developer installs Hydra on a shared team repo, the `.hydra/` directory is committed. Every teammate who pulls the repo sees it. When Hydra opens autonomous PRs, every teammate with GitHub notifications sees those PRs. The product spreads inside organizations without any deliberate marketing action.

Secondary viral mechanic: developers talk about tools that surprise them. The first autonomous fix: "I didn't touch anything and a PR appeared": is a genuinely surprising experience. Developers share surprising experiences. Every install is a potential tweet, a Slack message to a colleague, a Reddit comment.

### Integration Partnerships as Distribution

Linear integration means Hydra appears in Linear ticket closures. Every Linear user in a team that uses Hydra sees ticket closures attributed to Hydra. This is passive distribution inside tools the team is already using.

Potential future distribution partnerships:
- Cursor marketplace (when available)
- VS Code extension marketplace
- JetBrains plugin marketplace
- Claude integrations / Anthropic app ecosystem (Hydra built on Claude)

---

## 4. Activation

Activation is the most important metric in PLG. A user who installs but never activates has zero conversion probability. A user who reaches the aha moment converts at dramatically higher rates.

### The Aha Moment

For Hydra, the aha moment is the first autonomous fix:
- Issue found in the codebase
- Baseline tests written
- Fix executed using the codebase's own conventions
- PR opened with full description and audit trail
- Linear ticket closed
- The developer did nothing

This must happen in under 10 minutes from install. If it takes longer, users drop off before they experience it.

### The Activation Funnel

Every step in this funnel is a potential drop-off point. Each step needs measurement and optimization.

```
Step 1: GitHub App Install
    → User lands on GitHub Marketplace listing
    → Clicks "Install"
    → Selects repos to grant access
    → Redirected to Hydra onboarding
    [DROP-OFF RISK: repo selection confusion, unclear permissions]

Step 2: First Discovery Run
    → Hydra begins reading the codebase
    → User sees progress indicator
    → Discovery completes (~16 minutes, a few dollars of compute)
    → .hydra/ directory PR opened
    [DROP-OFF RISK: long wait time, user abandons before discovery completes]

Step 3: Discovery Complete
    → User reviews .hydra/ PR
    → Merges (or Hydra merges automatically, TBD)
    → Codebase is now mapped
    [DROP-OFF RISK: user does not review or merge the PR]

Step 4: First Audit Run
    → Audit runs across the mapped codebase
    → Findings surfaced: security, quality, conventions, architecture
    → User sees what Hydra found
    [DROP-OFF RISK: too many findings, user overwhelmed]

Step 5: AHA MOMENT: First Autonomous Fix
    → Hydra selects a fixable finding
    → Writes baseline tests
    → Executes fix
    → Opens PR
    → Closes Linear ticket
    → User sees the completed PR with no action taken
    [THIS IS ACTIVATION]
```

### Reducing Time to Aha

Every minute between install and first fix is a minute where the user can lose interest and leave. Tactics to compress this:

**Accelerated first fix path:** After discovery, Hydra should immediately identify the highest-confidence, lowest-risk fix to execute first. The first fix is not about impact: it is about demonstrating the mechanic. A small, clean, obvious fix with passing tests is better than a complex fix that takes longer or has lower confidence.

**Progress visibility:** The discovery and audit phases need clear progress indicators. A developer who installs a tool and sees nothing happen for 10 minutes will uninstall. Show what Hydra is doing: "Reading your codebase... Analyzing authentication module... Generating conventions..."

**Email bridge:** If discovery takes longer than the user's active session (16 minutes is longer than most install sessions), an email at discovery completion bridges the drop-off risk. "Hydra finished mapping your codebase. Here's what it found." with a link back into the product.

**Repo selection guidance:** During install, most developers do not know which repo to start with. Guide them: "Start with your most active repo: the one with the most PRs in the last 30 days. Hydra delivers the most value where code changes most frequently."

### Activation Metrics to Track

- **Install-to-discovery rate:** % of installs that complete a discovery run
- **Discovery-to-first-fix rate:** % of discovery completions that reach a first fix
- **Time to first fix (TtFF):** Median time from install to first autonomous fix
- **Activation rate:** % of installs that reach the aha moment (first fix)
- **D1 / D7 / D30 retention of activated users:** Are users who reached the aha moment still active?

---

## 5. Retention

Retention is what makes PLG economics work. High activation with low retention means acquiring the same users repeatedly. The goal is: once a developer activates on Hydra, they never leave.

### Active Retention: The Workflow Hook

Hydra's active retention mechanic is the PR event trigger. Every time a developer opens a PR, Hydra runs. The product does not require the developer to remember to use it, navigate to a dashboard, or take any action. It is in the workflow because it is connected to GitHub, and GitHub is where all code goes.

This is the single most important retention mechanic for a developer tool: **zero-action usage**. The developer does not decide to use Hydra on each PR. Hydra is just there, every time.

### Passive Retention: The Improve Loop

The Improve layer is the strongest retention mechanic Hydra has, and it requires zero developer engagement. The codebase gets cleaner while the team ships. Developers notice this without being prompted: code reviews start finding fewer issues, the debt backlog shrinks, the codebase starts to feel better maintained.

This is habit formation through passive benefit. The developer does not log in. They do not receive a notification. They simply notice, over weeks, that the codebase is in better shape. The moment they consider removing Hydra, they realize the improvement stops. The switching cost is the absence of the thing they stopped noticing because it was always working.

### Switching Cost Accumulation

Switching cost in a PLG product is the accumulated value that would be lost on cancellation. For Hydra, switching costs build over time:

**Week 1:** First fixes executed. Baseline value established.
**Month 1:** Improve loops have reduced measurable debt. The codebase is demonstrably different.
**Month 2:** Scanner rules generated from the codebase's own failure modes. These rules encode team-specific knowledge that took months to generate. Removing Hydra loses those rules.
**Month 3+:** The `.hydra/` directory contains the codebase's conventions, how-to guides, and architecture documentation. New engineers onboard faster because of it. Removing Hydra orphans this documentation.

By month 3, Hydra is infrastructure. The switching cost is not just losing a tool: it is losing the accumulated institutional knowledge the tool has generated.

### Churn Risk Signals

The inverse of retention signals. These indicate a user is at risk of churning and should trigger an intervention (email, in-product prompt, or in the case of high-value accounts, a human outreach).

| Signal | Risk Level | Response |
|---|---|---|
| No fix executed in 14 days after activation | High | Re-engagement email: "Your codebase has [N] open findings. Here is what Hydra can fix." |
| Discovery completed but no merge of .hydra/ PR | High | Email: "Your codebase map is ready. Merge the PR to unlock Hydra." |
| No login in 30 days | Medium-High | Email: "Hydra has been quietly working. Here is what changed in your codebase this month." |
| Free user, limit never hit after 30 days | Medium | Product is not generating value. Could indicate low PR volume repo. Onboarding intervention. |
| Team member who was PQL stops activity | Medium | Email to account admin. |

### Retention Metrics to Track

- **D7 retention:** % of activated users active 7 days after first fix
- **D30 retention:** % of activated users active 30 days after first fix
- **D90 retention:** % of activated users active 90 days after first fix
- **Weekly Active Accounts:** Accounts with at least one fix executed in the past 7 days
- **Monthly Active Accounts (MAA):** Accounts with at least one Hydra action in 30 days
- **Fix frequency per active account:** How often Hydra is running per account
- **Churn rate:** % of paying accounts canceling per month (target <2% monthly)

---

## 6. Monetization

### The Conversion Philosophy

A PLG conversion is not a sales moment. It is the natural result of a product delivering enough value that the limit feels like an obstacle the user wants to remove. The upgrade prompt should feel like: "You've hit the ceiling of a thing that is working. Here is how to remove the ceiling."

A bad upgrade prompt creates friction: paywalling, fear, or urgency that feels manufactured. A good upgrade prompt creates clarity: here is what you have, here is what you get, here is the price.

### Tier Definitions (Full)

| | Free | Team | Business | Enterprise |
|---|---|---|---|---|
| **Price** | $0 | $20/dev/month | $40/dev/month | Custom |
| **Fixes/month** | 5 | Unlimited | Unlimited | Unlimited |
| **Doc runs/month** | 1 | Unlimited | Unlimited | Unlimited |
| **Linear cycles/month** | 5 | Unlimited | Unlimited | Unlimited |
| **Repos** | Unlimited | Up to 5 | Unlimited | Unlimited |
| **Discovery + Audit** | Full | Full | Full | Full |
| **Custom agent rules** | No | Yes | Yes | Yes |
| **Priority fix queue** | No | No | Yes | Yes |
| **Audit logs** | No | No | Yes | Yes |
| **Usage reporting** | No | No | Yes | Yes |
| **Jira integration** | No | No | Yes | Yes |
| **SSO / SAML / RBAC** | No | No | No | Yes |
| **VPC deployment** | No | No | No | Yes |
| **SLA + dedicated support** | No | No | No | Yes |
| **Credit card required** | No | Yes | Yes | Yes |

### Product Qualified Leads (PQLs)

A PQL is a free user who has demonstrated enough product engagement to be highly likely to convert. PQLs should be tracked, scored, and used to trigger targeted conversion interventions (email, in-product prompt).

**Hydra PQL definition:**
A free user who has:
- Completed at least one discovery run (activated)
- Had at least one autonomous fix execute (experienced the aha moment)
- Used 3 or more of their 5 monthly fixes (approaching the limit)
- Has been active in the past 14 days (still engaged)

A user who meets all four criteria has a dramatically higher conversion probability than a user who only installed. All four criteria must be true simultaneously.

### Product Qualified Accounts (PQAs)

A PQA is an organization (GitHub org / team account) where multiple users exhibit PQL behavior. PQAs are the highest-value expansion targets.

**Hydra PQA definition:**
A GitHub organization where:
- 3 or more developers have installed Hydra on repos
- At least 2 of those developers are PQLs
- No one in the org has converted to paid yet

A PQA signals a team where Hydra has demonstrated value to multiple people. The upgrade decision is likely being discussed internally. The intervention for a PQA is an email to the most engaged user with a Team plan framing (not an individual framing): "Your team is already using Hydra. Here is how to run it without limits."

### Upgrade Trigger System (Full)

**Free to Team**

| Trigger | In-Product Message | Email |
|---|---|---|
| 3rd fix executed (60% of limit) | Soft: "You have 2 fixes remaining this month. Team gives you unlimited." | No email at this point. |
| 5th fix executed (100%) | Hard: "You have used all 5 fixes for this month. Fixes resume [date] or upgrade now." Upgrade CTA prominent. | "You hit the limit. Here is what Team unlocks." Sent immediately. |
| 5th Linear cycle | "You have used all 5 Linear cycles. Upgrade to Team to keep the loop running." | Same-day email. |
| 1 doc run used | "You have used your doc run for this month. Team includes unlimited doc runs." | No immediate email. Include in weekly digest if limit hit. |
| Attempts custom agent rules | "Custom agent rules are available on Team. Configure how Hydra prioritizes your codebase." | No email. In-product only. |
| Month end with 5/5 used | Monthly reset email includes: "You used all your fixes last month. This month starts fresh: or upgrade to never hit the limit again." | Sent on reset date. |

**Team to Business**

| Trigger | In-Product Message | Email |
|---|---|---|
| 5th repo added | "You are at 5 repos. Business gives you unlimited." | Email: "Your team is growing. So should your repo access." |
| Attempts Jira connection | "Jira integration is available on Business." | No email. In-product only. |
| Audit log request from admin | "Audit logs are available on Business." | No email. In-product only. |
| Fix queue exceeds [N] items | "Your fix queue has [N] items waiting. Business includes a priority queue." | Weekly digest includes queue depth if relevant. |
| 30 days on Team, usage growing | | Growth email: "Your team has executed [N] fixes. Here is what Business adds." |

**Business to Enterprise**

Enterprise conversion in PLG does not follow the same trigger pattern. At the Business tier with 500+ developers, the economics justify human outreach. The in-product experience surfaces a "Talk to us" prompt rather than a self-serve Stripe checkout. The Business-to-Enterprise motion is the one moment in Hydra's GTM where a human enters the loop.

| Trigger | Response |
|---|---|
| Org size exceeds 500 developers | In-product: "You have [N] developers. Enterprise is designed for your scale. Talk to us." |
| IT team requests SSO or SAML | "SSO and SAML are available on Enterprise." + contact link |
| Security review requires VPC | "VPC deployment is available on Enterprise." + contact link |
| Compliance reporting required | "Compliance reporting is available on Enterprise." + contact link |

### Stripe Billing Flow

1. User hits upgrade trigger inside product
2. In-product prompt displays: tier comparison, what they get, price
3. User clicks "Upgrade to Team"
4. Stripe Checkout opens (embedded or redirect, TBD with engineering)
5. User enters payment details
6. Seat count confirmed: "How many developers should be on this plan?" (default: count of active users in the org)
7. Stripe subscription created
8. Webhook fires to Hydra backend: account upgraded, limits lifted immediately
9. User returns to product, limits are gone
10. Confirmation email sent from Stripe (receipt) and from Hydra (welcome to Team)

**Proration:** Stripe handles mid-cycle seat adds and tier upgrades automatically. A developer who upgrades on day 15 of a 30-day cycle pays half a month.

**Downgrade:** Available any time. Access continues through end of billing period. On next cycle, account reverts to previous tier limits. No immediate loss of access.

**Cancellation:** Available any time. Same as downgrade. Account reverts to free tier limits at end of billing period. Discovery and audit remain available. Fixes pause at 5/month limit.

**Annual billing:** [TBD. Recommended: 20% discount for annual commitment, invoiced upfront. Reduces churn, improves cash flow, justifies Enterprise contract structure.]

### Seat Definition and Management

[To be confirmed with engineering. Recommended definition: a developer seat is any GitHub user who has committed to a Hydra-connected repo in the past 30 days. This captures active contributors without penalizing orgs for inactive collaborators.]

Seat management must handle:
- New developers joining a repo mid-cycle (proration)
- Developers leaving a repo (seat reclaimed at next billing cycle)
- Repo transfers between orgs
- Org mergers and splits

---

## 7. Expansion

Expansion is how PLG generates NRR above 100%. The account starts at Free, moves to Team, grows seats as the engineering team grows, upgrades to Business as the org matures, and eventually reaches Enterprise. At each stage, Hydra's revenue from that account grows without any sales effort.

### Bottom-Up Expansion

The classic PLG expansion pattern. One developer installs Hydra. It works. They tell a colleague. The colleague installs it on a different repo. Now there are two free users in the same GitHub org. A third joins. The account is now a PQA. Someone upgrades to Team. The team grows from 5 to 15 developers. The seat count grows automatically. Seat count growth is revenue expansion with zero acquisition cost.

**The bottom-up expansion loop:**
```
1 developer installs (Free)
    → .hydra/ directory visible to teammates
    → Teammates see autonomous PRs
    → Teammates install (more Free seats in same org)
    → PQA threshold reached (3+ PQLs in same org)
    → Most engaged user prompted to upgrade for whole team
    → Team converts to Team plan
    → Team grows (more seats added automatically)
    → Team reaches 5 repo limit → Business upsell
    → Business seats grow as org grows
    → Org reaches Enterprise threshold
```

### The Viral Coefficient

The viral coefficient (K) is the number of new users generated by each existing user. For PLG to be self-sustaining, K must be close to 1 or above. For Hydra, the viral mechanics are:

- **`.hydra/` directory visibility:** Every commit to a shared repo makes Hydra visible to all collaborators. Estimated reach: 3-5 additional developers per install on a team repo.
- **Autonomous PR authorship:** Every autonomous PR appears in the GitHub activity feed of collaborators. It is a visible artifact.
- **Linear ticket closures:** Teammates who use Linear see tickets being closed by Hydra.

The K coefficient needs to be measured post-launch. Target: K > 0.5 within the first 90 days.

### Expansion Revenue Metrics

- **Net Revenue Retention (NRR):** (MRR at start of period + expansion - churn - contraction) / MRR at start. Target: >110%. This means existing accounts alone grow Hydra's revenue by 10%+ annually.
- **Average Contract Value (ACV) expansion:** Track how ACV per account grows over time. A Free install that becomes a 20-person Business account represents a significant ACV expansion event.
- **Seat expansion rate:** Average seat count growth per paying account per quarter.
- **Tier upgrade rate:** % of Team accounts that upgrade to Business within 12 months.

### Expansion Triggers and Interventions

| Signal | Intervention |
|---|---|
| Team plan, 4 repos in use | Email: "You are at 4 repos. Business gives you unlimited." |
| Team plan, 3 months active, fix volume high | Email: "Your team has run [N] fixes. Here is what Business adds." |
| Team plan, teammate requests Jira integration | In-product: "Jira is available on Business." |
| New developer added to paid account | Automatic seat add. Email receipt confirming proration. |
| Business plan, org size approaching 500 | In-product: "Looks like your org is growing. Enterprise is designed for your scale." |
| Business plan, 12 months active | QBR email: "Here is what Hydra has done for your codebase this year." + Enterprise prompt. |

---

## 8. Viral Mechanics

The two primary viral mechanics are worth expanding in detail because they are architectural, not marketing decisions.

### Mechanic 1: The .hydra/ Directory

When Hydra completes discovery, it opens a PR creating a `.hydra/` directory in the repository root. This directory contains:
- `hydra.md`: the AI entry point and codebase overview
- Architecture documentation
- Extracted conventions and definition-of-done
- How-to guides specific to the codebase
- The application profile

This directory is:
- **Committed to the repo**: visible in every `git clone`, every IDE, every pull, every GitHub browse
- **Opened as a PR**: visible in GitHub notifications to all collaborators
- **Maintained over time**: updated as the codebase evolves, meaning it is a living artifact

Every developer who contributes to a Hydra-connected repo encounters the `.hydra/` directory. It is a recurring signal that something is monitoring and improving this codebase. It prompts the question "what is this?" which leads to discovery.

### Mechanic 2: Autonomous PR Authorship

Every fix Hydra executes appears as a pull request in the repo. The PR author is Hydra (a GitHub App). The PR description includes the issue found, the baseline tests written, the fix applied, the conventions matched, and the Linear ticket closed.

For developers watching the repo, these PRs are visible in:
- GitHub PR list
- GitHub email notifications
- GitHub mobile notifications
- Slack GitHub integration (if connected)
- Linear activity feed

Every autonomous PR is an impression for a new developer. It demonstrates the product in the most compelling way possible: not a screenshot, not a demo, but a real fix in a real repo with a real audit trail.

### Mechanic 3: Linear Ticket Closures

Tickets closed by Hydra appear in Linear with Hydra as the closer. Teammates browsing the ticket board see tickets being resolved autonomously. This is particularly visible to engineering managers and PMs who monitor the board.

---

## 9. Analytics and Instrumentation

PLG runs on product data. Without instrumentation, there is no way to know where users are dropping off, what is working, or when to intervene. Every activation step, every limit hit, every upgrade prompt, every conversion must be tracked.

### Instrumentation Requirements

The following events must be tracked at a minimum. All events should fire to a product analytics tool (PostHog recommended for PLG: open source, developer-friendly, self-hostable).

**Acquisition events:**
- `install_initiated`: GitHub App install started
- `install_completed`: GitHub App install completed, repos selected
- `repo_connected`: specific repo connected to Hydra

**Activation events:**
- `discovery_started`: discovery run initiated
- `discovery_completed`: discovery run completed, .hydra/ PR opened
- `hydra_pr_merged`: .hydra/ PR merged by developer
- `audit_completed`: first audit run completed
- `fix_executed`: autonomous fix executed (properties: fix type, confidence score, conventions matched, time since install)
- `first_fix_executed`: first fix for this account (activation event)

**Engagement events:**
- `fix_executed` (recurring)
- `pr_reviewed`: developer reviewed a Hydra PR
- `pr_merged`: developer merged a Hydra PR
- `pr_closed_without_merge`: developer closed a Hydra PR without merging (quality signal)
- `improve_loop_started`: Kaizen improvement loop initiated
- `improve_loop_completed`: improvement loop completed
- `scanner_rule_generated`: new governance rule generated from codebase patterns
- `linear_ticket_closed`: Linear ticket closed by Hydra execution

**Limit and conversion events:**
- `limit_approaching`: user at 60% of monthly limit (3/5 fixes)
- `limit_reached`: user at 100% of monthly limit
- `upgrade_prompt_shown`: upgrade prompt displayed to user
- `upgrade_prompt_clicked`: user clicked upgrade CTA
- `checkout_started`: Stripe Checkout opened
- `checkout_completed`: payment succeeded, account upgraded
- `checkout_abandoned`: user opened Checkout but did not complete

**Expansion events:**
- `seat_added`: new developer added to paid account
- `repo_limit_approaching`: Team account at 4/5 repos
- `repo_limit_reached`: Team account at 5/5 repos
- `tier_upgrade_prompt_shown`: Business upgrade prompt shown
- `tier_upgraded`: account upgraded from Team to Business or Business to Enterprise

**Retention / churn events:**
- `account_inactive_7d`: no activity in 7 days
- `account_inactive_30d`: no activity in 30 days
- `subscription_cancelled`: account cancelled paid subscription
- `subscription_downgraded`: account downgraded to lower tier

### Cohort Analysis

The most important ongoing analysis in PLG. Track each install cohort (week of install) through the funnel over time.

| Metric | Week 1 | Week 2 | Week 4 | Week 12 |
|---|---|---|---|---|
| Activation rate (% reached first fix) | Target: 60% | | | |
| Retention of activated users | | Target: 50% | Target: 40% | Target: 30% |
| Free-to-paid conversion | | | Target: 5% | Target: 12% |
| Average fixes executed per active account | | | | |

These targets are benchmarks based on PLG industry data (OpenView Partners). Actual targets should be revised after first 90 days of production data.

### The PLG Health Dashboard

The dashboard that matters for Hydra's growth. Should be reviewed weekly.

| Metric | Definition | Target | Frequency |
|---|---|---|---|
| Weekly New Installs | GitHub App installs in last 7 days | Growing week-over-week | Weekly |
| Activation Rate | % of installs completing first fix | >60% | Weekly |
| Time to First Fix (TtFF) | Median minutes from install to first fix | <10 min | Weekly |
| Weekly Active Accounts | Accounts with any Hydra action in 7 days | Growing | Weekly |
| Free-to-Paid Rate (90-day) | % of 90-day-old installs that converted | 8-15% | Monthly |
| MRR | Total monthly recurring revenue | Growing | Weekly |
| MRR Growth Rate | Week-over-week MRR change | >10% early stage | Weekly |
| Net Revenue Retention | (MRR + expansion - churn) / MRR | >110% | Monthly |
| Churn Rate | % of paying accounts canceling per month | <2% | Monthly |
| Viral Coefficient (K) | New installs generated per existing install | >0.5 | Monthly |
| PQL Count | Free users meeting all PQL criteria | Growing | Weekly |
| PQA Count | Orgs meeting PQA criteria | Growing | Weekly |
| PQL-to-Paid Conversion | % of PQLs converting within 30 days | >25% | Monthly |

---

## 10. Email Lifecycle

PLG email is triggered by product behavior, not time. An email sent because "it has been 7 days since install" is spam. An email sent because "discovery completed and you have not merged the .hydra/ PR" is relevant.

Every email in the lifecycle has three properties: the trigger (the product event that causes it to send), the goal (what action the email should produce), and the message (what it says).

### Onboarding Sequence (Free Tier)

**Email 1: Install Confirmation**
Trigger: `install_completed`
Goal: Set expectations, confirm what happens next
Subject: "Hydra is reading your codebase"
Content: What discovery does, how long it takes, what the .hydra/ PR will look like. One clear CTA: "Watch your repo."

**Email 2: Discovery Complete**
Trigger: `discovery_completed`
Goal: Drive the developer back into the product to see what Hydra found
Subject: "Hydra finished mapping [repo name]. Here is what it found."
Content: Summary of discovery output: conventions extracted, architecture overview, issues identified. CTA: "Review the .hydra/ PR."

**Email 3: First Fix Executed (Activation)**
Trigger: `first_fix_executed`
Goal: Celebrate the aha moment, reinforce the value, prime for future engagement
Subject: "Hydra just fixed something in [repo name]. You did nothing."
Content: Summary of the fix: what was found, what test was written, what was fixed, what PR was opened, what ticket was closed. CTA: "Review the PR." No upgrade prompt yet: this is the celebration email.

**Email 4: Limit Approaching (3/5 fixes)**
Trigger: `limit_approaching`
Goal: Soft awareness of the limit, plant the seed for upgrade
Subject: "You have 2 fixes left this month"
Content: Brief summary of what Hydra has done this month. "Team gives you unlimited fixes across up to 5 repos. $20/dev/month." CTA: "See Team plan." Soft sell, not urgent.

**Email 5: Limit Reached (5/5 fixes)**
Trigger: `limit_reached`
Goal: Convert
Subject: "You have used all 5 fixes this month"
Content: "Your fixes resume [reset date]. Or upgrade to Team and remove the limit entirely." Show what Team includes. Price prominently. CTA: "Upgrade to Team."

**Email 6: Inactive After Activation (7 days)**
Trigger: `account_inactive_7d` (only if previously activated)
Goal: Re-engagement
Subject: "Your codebase has [N] open findings"
Content: Pull the top findings from the last audit. Remind them the fixes are waiting. "You have [N] fixes remaining this month." CTA: "See open findings."

**Email 7: Inactive After Activation (30 days)**
Trigger: `account_inactive_30d`
Goal: Last-chance re-engagement before churn
Subject: "Hydra has been quietly working"
Content: What the Improve loop has done in their absence (if anything). What is waiting to be fixed. CTA: "See what changed."

### Post-Conversion Sequence (Team Tier)

**Email 8: Welcome to Team**
Trigger: `checkout_completed` (Team upgrade)
Goal: Confirm value, introduce Team-specific features, prevent early churn
Subject: "Welcome to Team. No more limits."
Content: What changed (unlimited fixes, unlimited doc runs, 5 repos, custom agent rules). How to set up custom rules. CTA: "Set up your first custom rule."

**Email 9: Team Onboarding: Custom Rules**
Trigger: 3 days after Team upgrade, if no custom rules set
Goal: Drive adoption of the Team-exclusive feature
Subject: "You haven't set up custom agent rules yet"
Content: What custom rules do. How to configure them. 2-minute setup. CTA: "Configure rules."

**Email 10: Monthly Codebase Health Report**
Trigger: Monthly, on billing anniversary
Goal: Reinforce value, surface expansion opportunity
Subject: "[Month] codebase health report for [org name]"
Content: Fixes executed, debt reduced, scanner rules generated, Linear tickets closed. Trends over time. "Your team has run [N] fixes since activating." If approaching repo limit: "You are using 4 of 5 repos. Business gives you unlimited." CTA: "View full report."

**Email 11: Approaching Repo Limit (Team)**
Trigger: `repo_limit_approaching` (4th repo connected)
Goal: Business upsell
Subject: "One repo slot remaining"
Content: "You are at 4 of 5 repos on Team. Business gives you unlimited repos, Jira integration, audit logs, and priority queue." CTA: "Upgrade to Business."

**Email 12: Repo Limit Reached (Team)**
Trigger: `repo_limit_reached`
Goal: Business conversion
Subject: "You have reached your repo limit"
Content: "You are at 5 repos. Upgrade to Business for unlimited repos and the full Hydra platform." CTA: "Upgrade to Business."

### Re-Engagement and Winback

**Email 13: Churned Account Winback (30 days post-cancellation)**
Trigger: 30 days after `subscription_cancelled`
Goal: Win back churned paying account
Subject: "What happened with [org name]?"
Content: Brief. What Hydra has shipped since they cancelled. No pitch: just product news. CTA: "See what's new."

---

## 11. In-Product Messaging

The messaging inside the product is as important as the marketing outside it. Every empty state, every limit state, every upgrade prompt, and every feature discovery moment is a conversion opportunity or a retention moment.

### Empty States

Empty states appear before the user has taken any action. They set expectations and drive the next step.

**Before first discovery:**
"Hydra has not mapped this repo yet. Discovery reads your entire codebase, extracts conventions, and generates the .hydra/ directory. It takes about 16 minutes and costs a few dollars. Run it once, and Hydra knows this repo permanently."
CTA: "Run Discovery"

**After install, no repos selected:**
"Connect a repo to get started. Start with your most active repo: the one your team pushes to most. That is where Hydra delivers the most value first."
CTA: "Connect a repo"

**Fix queue empty (all fixes resolved):**
"Your codebase is clean. Hydra will continue monitoring for new issues on every PR and running improvement loops in the background."
No CTA needed: this is a positive state.

### Progress States

States during active processing. These prevent the user from thinking nothing is happening.

**During discovery:**
"Reading [repo name]... Hydra is mapping your architecture, extracting conventions, and building your application profile. This runs once and takes about 16 minutes."
Show: progress bar, modules being processed, findings accumulating.

**During fix execution:**
"Writing baseline tests... Executing fix... Matching conventions... Opening PR..."
Show: step-by-step progress. Every step visible. No black box.

### Limit States

The most conversion-critical in-product moments.

**At fix limit (5/5):**
"You have used all 5 fixes for this month. Fixes resume on [date].
Team gives you unlimited fixes for $20/dev/month."
Show: what they have gotten from Hydra this month (fixes executed, issues resolved, tickets closed). Frame the upgrade against demonstrated value.
CTA: "Upgrade to Team" (primary) | "See you next month" (secondary, dismissible)

**At repo limit (5/5 on Team):**
"You are at 5 repos. Business gives you unlimited repos, Jira integration, audit logs, and priority queue."
CTA: "Upgrade to Business"

### Feature Discovery Nudges

Moments where a user has not tried a capability they have access to.

**Custom agent rules (Team, never configured):**
"Your team has not configured custom agent rules yet. Rules let you tell Hydra what to prioritize: security over style, performance over conventions, or specific modules to focus on."
CTA: "Configure rules" (5 minutes)

**Improve loop never initiated:**
"Hydra has found [N] instances of recurring patterns across your codebase. The Improve loop can work through these systematically. Give it a budget and a focus area."
CTA: "Run an Improve loop"

### Upgrade Prompts (Full Copy)

**Free to Team:**
Headline: "Remove the limit. Keep the momentum."
Body: "You've used all 5 fixes this month. Your codebase has [N] open findings waiting. Team gives you unlimited fixes, unlimited doc runs, unlimited Linear cycles, and up to 5 repos."
Price: "$20/dev/month. Cancel anytime."
CTA: "Upgrade to Team"
Dismiss: "Remind me next month"

**Team to Business:**
Headline: "Your team is outgrowing 5 repos."
Body: "Business gives you unlimited repos, Jira integration, audit logs, usage reporting, and a priority fix queue. Built for engineering teams who need full visibility."
Price: "$40/dev/month. Cancel anytime."
CTA: "Upgrade to Business"
Dismiss: "Not yet"

---

## 12. Pricing Page Strategy

The pricing page is the primary self-serve conversion surface. In PLG there is no sales call to fall back on. The pricing page must answer every objection, handle every concern, and make the upgrade decision feel low-risk and obvious.

### Page Structure

**Hero**
Headline: "Start free. The codebase gets better either way."
Subheadline: "Full discovery. Full audit. Five autonomous fixes to see it work. No credit card."

**Tier Cards**
Four cards: Free, Team, Business, Enterprise. Each card leads with what you get, not what you pay. Price is visible but not the headline.

**Feature Comparison Table**
Full side-by-side comparison. Developers want to see the complete list. Do not hide it behind a toggle or make them click to see more. Show everything.

**Social Proof Band**
Post-launch: install count, fix count, repos count. Pre-launch: "Join [N] developers on the waitlist." These numbers do the conversion work for skeptical visitors.

**FAQ**
Every objection handled. See Section 6 (Pricing Page FAQ) in the separate pricing document.

**CTA Persistence**
Every scroll position has a visible "Start free" CTA. The conversion action should never be more than one click away on the pricing page.

### Pricing Page Objection Handling (In-Page)

| Objection | Response |
|---|---|
| "What if Hydra makes a bad fix?" | Baseline tests before every fix. If they fail, nothing ships. Post-fix audit after. Every change is a PR your team can review and revert. |
| "Is free actually free?" | Yes. No credit card. No expiry. Five fixes per month, forever. |
| "How do I know this is worth $20/dev?" | [Post-launch: show fix count and time savings from active accounts. Pre-launch: show the math: one engineer-hour per week is worth $50-100+. $20/dev is a fraction of that.] |
| "What happens to my data?" | [Privacy and data handling page: to be written] |
| "Can I cancel anytime?" | Yes. Cancel from your account settings. Access continues through end of billing period. |

---

## 13. Community and Developer Relations

Community is the long-term acquisition flywheel. It is slow to build and nearly impossible to buy. The right approach for Hydra at launch is to be genuinely present and genuinely useful in the places developers already spend time: not to flood those channels with product marketing.

### Launch Community Strategy

**Hacker News Show HN**
A well-executed Show HN post at launch is the single highest-leverage acquisition moment available to a developer tool. The post must be:
- Written by a founder or technical lead, not a marketer
- Honest about what the product does and does not do
- Technically specific: explain the architecture, not just the outcome
- Ready to engage in the comments for the full first day

A Show HN that performs well (top 10 in the day) can drive 1,000-5,000 installs in 24 hours from exactly the right audience.

**Product Hunt**
Less technically rigorous than HN but higher volume. Run on the same day as the HN post. Product Hunt requires: a compelling demo GIF showing an autonomous fix executing, a clear tagline, and a maker who is present to respond to comments all day. Product Hunt upvotes correlate with install volume on launch day.

**GitHub**
Make the Hydra repo public before launch. Polish the README: it is a landing page, not a technical document. It needs the same headline, value prop, and install instructions that the marketing site has. Stars are social proof. Contributing guidelines and a clear issue tracker signal that this is a real, maintained project.

**Developer Newsletters**
Reach out to TLDR.tech, Changelog Weekly, and similar newsletters before launch. These newsletters reach tens of thousands of developers. A feature in one of them at launch drives sustained, high-quality install traffic.

### Ongoing Community Strategy

After launch, community compounds. The goal is to be genuinely useful in the conversations developers are already having about AI-generated code quality.

- **Answer questions** on Stack Overflow, Reddit, and GitHub Discussions when someone asks about code quality tools, autonomous code review, or AI code governance
- **Publish technical content** that is genuinely useful whether or not the reader installs Hydra: "How we built a codebase convention extractor," "Why we run baseline tests before every autonomous fix"
- **Changelog** every release. Developers who have installed Hydra want to know it is actively maintained. A public changelog (changelog.hydra.new or similar) and a changelog-focused email is a retention and re-engagement tool
- **OSS contribution** where relevant. If Hydra's tooling for convention extraction, scanner pattern generation, or baseline test writing could be useful in other contexts, open-sourcing those components builds developer goodwill and drives inbound discovery

---

## 14. Open Items and Dependencies

| Item | Owner | Priority | Notes |
|---|---|---|---|
| Stripe account for Hydra | Engineering | P0 | Separate from Iru. Must be set up before any paid tier can go live. |
| Seat definition confirmed | Engineering | P0 | Blocks billing implementation. |
| PostHog (or equivalent) instrumentation | Engineering | P0 | No PLG without product analytics. All events in Section 9 must fire before launch. |
| Email provider for lifecycle emails | Engineering | P0 | Recommended: Resend or Postmark for transactional, Customer.io for lifecycle triggers. |
| Free tier reset cadence | Engineering | P1 | Calendar month vs. rolling 30 days. Recommendation: calendar month (simpler, less user confusion). |
| Annual billing discount | Tristan | P1 | Recommended 20%. Blocks billing page finalization. |
| OSS / nonprofit pricing program | Tristan | P2 | Community goodwill. Not required for launch. |
| Hard stop vs. overage at limit | Engineering | P1 | Hard stop recommended for simplicity. Overage billing adds complexity and user anxiety. |
| Pricing page build | Engineering / Design | P0 | Required for launch. |
| GitHub Marketplace listing | Engineering / PMM | P0 | Primary acquisition surface. Required before launch. |
| Product analytics dashboard | Engineering | P1 | PLG health metrics from Section 9. |
| PQL / PQA scoring | Engineering | P1 | Can be manual initially (SQL queries), automated post-launch. |
| Upgrade prompt implementation | Engineering | P0 | In-product prompts at all limit states. Required for any free-to-paid conversion. |