agentleFS
hugobatistahugobatista/agent-skills/skills/review/saas-transition-strategy/SKILL.md

saas-transition-strategy

Skill1 starsChanged 57 days agoMITView on GitHub

Decision framework for projects that start self-hosted and evolve into SaaS. Encodes invariants, a decision tree, and strategic anti-patterns to guide every architecture choice. Load alongside the saas-anti-pattern-review skill. Triggered by: saas transition strategy, hybrid strategy, hybrid review, self-hosted strategy.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every refactoring must benefit both models, or at minimum leave self-hosted untouched.

    line 25
  2. Distinctive:

    Nothing requires SaaS-only infra: Every external dependency (Redis, S3, queues, object storage) must have a documented fallback — …

    line 54
  3. Distinctive:

    SaaS features are additive: Every SaaS feature must work with the self-hosted deploy (possibly degraded or no-op).

    line 56
  4. Distinctive:

    Default to smaller, simpler, optional.

    line 77
  5. Distinctive:

    No premium feature gating

    line 130
  6. Distinctive:

    Open-ended: Only when there's a concrete need:

    line 134

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

SaaS Transition Strategy: Self-Hosted → SaaS

This skill encodes a decision framework for projects that begin as self-hosted and later add a managed hosting / SaaS offering.

Audience: LLMs guiding refactoring decisions alongside the team. Purpose: Quick compass for every architecture choice — does it help or harm the hybrid model?

North Star

Single product. Two deployment modes. Same build artifact.

  • Self-hosted is first-class, never second-class. It is not a "free tier."
  • SaaS infrastructure is additive and always optional.
  • Every refactoring must benefit both models, or at minimum leave self-hosted untouched.
  • The same build artifact runs both modes. No separate build, no separate branch.

Ground Truths

Each project may define its own ground truths in AGENTS.md at the project root, under a ## Ground Truths section. If the section exists, the agent uses those values. If missing, the agent uses these defaults:

## Ground Truths

| Topic | Current state |
|---|---|
| Deployment | `docker compose up`, 3 containers (app + postgres + redis) |
| Infrastructure dependencies | Postgres required, Redis optional (in-memory fallback) |
| SaaS model | Per-organization dedicated stacks → shared multi-tenant later. An organization is a group of users sharing one isolated stack (one tenant unit). Evolve to shared multi-tenant only when needed. |
| First offering | Pure managed hosting, no premium features |
| Phase 1→2 trigger | Multi-worker is safe (durable queues, shared state) |
| Data portability | Users migrate freely between self-hosted and hosted |
| Scaling philosophy | Don't over-engineer. Handle capacity when it arrives. |

At the end of a review that used defaults, advise the user to add a ## Ground Truths section to AGENTS.md if the defaults don't match their project. The format is a markdown table with the columns Topic and Current state.

Invariants

Non-negotiable. If a change breaks one, it doesn't go in.

  1. The local deploy works. The standard run command must always start and run without errors.
  2. No regression for self-hosted. Existing features remain. No feature loss, no performance degradation, no added deploy complexity.
  3. Nothing requires SaaS-only infra. Every external dependency (Redis, S3, queues, object storage) must have a documented fallback — in-memory, local filesystem, no-op.
  4. Same artifact, both modes. The published build artifact runs self-hosted and managed hosting identically. Configuration determines the mode.
  5. SaaS features are additive. Every SaaS feature must work with the self-hosted deploy (possibly degraded or no-op). No self-hosted user sees "this requires a subscription."

Decision Tree

Facing a change? Run this:

Q1: Does this change affect both models the same way?
  → YES: Proceed. It's core. No gating needed.
  → NO (SaaS-only or SaaS-different): Go to Q2.

Q2: Can this be optional infrastructure with a fallback?
  → YES: Build with self-hosted fallback (memory://, DB, local FS, no-op).
  → NO (requires SaaS infra with no reasonable fallback): Go to Q3.

Q3: Is this actually necessary for the first SaaS offering?
  → YES: Gate it behind configuration. Keep it in separate modules
         that core never imports. Self-hosted defaults to disabled.
  → NO: Don't build it. Defer until a customer needs it.

Default to smaller, simpler, optional.

Strategic Anti-Patterns

These are thinking traps — not code issues (those are covered by the saas-anti-pattern-review skill).

Anti-patternWhy it's dangerous
"Let's make {SaaS infra} required — simpler code"Self-hosted must never require SaaS infra. Code can handle optional dependencies.
"We'll fix the self-hosted path later"Later never comes. Ship both paths at once or don't ship.
"This SaaS feature behind a feature flag is harmless"Flags hide complexity, they don't remove it. Prefer separate modules core never imports.
"Build it for the scale we'll have in 2 years"You don't know the scale yet. Build for now. Capacity answers "we'll handle it."
"Self-hosted users can live without this"Self-hosted isn't a free tier — it's the product. Every loss is a loss.
"We can add the fallback later"Fallbacks need to be designed, not bolted on. Design both paths from day one.

Phase Roadmap (Template)

Phases are triggered by milestones, not dates.

Phase 1 — Ops Readiness

Trigger: Decision to proceed with managed hosting pre-work. Goal: Make the app safe to run horizontally, without changing the self-hosted experience.

What changes:

  • Durable job queue (with fallback for single-worker self-hosted)
  • Shared state abstraction for multi-worker (pub/sub, auth state)
  • Object storage abstraction (local fs default, S3-compatible opt-in)
  • DB pool tuning for multi-worker safety
  • Multi-worker safety: scheduler, rate limits, auth state, provider sync

What does NOT change:

  • The self-hosted deploy
  • Feature set for self-hosted users
  • The artifact structure

Self-hosted impact: Zero.

Phase 2 — Managed Hosting MVP

Trigger: Phase 1 is stable. Multi-worker is safe. Goal: Ship managed hosting as a service.

What changes:

  • Instance provisioning scripts (one isolated stack per organization)
  • Admin tooling (list instances, health checks, restart)
  • Billing integration
  • Domain/subdomain routing per organization
  • Data import tool (self-hosted → hosted migration)

What does NOT change:

  • Core product code
  • Self-hosted features
  • No premium feature gating

Phase 3 — Maturity

Open-ended. Only when there's a concrete need:

  • Fleet observability and monitoring
  • Possible multi-tenant consolidation
  • Possible premium feature evaluation (must not degrade self-hosted)
  • Mobile strategy

Open Decisions

Tracked for future resolution, not blocking anything now:

TopicStatus
{decision}{TBD / Deferred / Not yet evaluated}

Related Skills

  • saas-anti-pattern-review — technical checklist for SaaS-unfriendly patterns

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.