{
  "markdown": "<p align=\"center\">\n  <h1 align=\"center\">PlanFirst</h1>\n  <p align=\"center\"><strong>Calm down. You don't need Kafka yet.</strong></p>\n  <p align=\"center\">\n    <a href=\"#install\"><img src=\"https://img.shields.io/badge/Claude_Code-Plugin-blue?style=flat-square\" alt=\"Claude Code Plugin\"></a>\n    <img src=\"https://img.shields.io/badge/status-Published-brightgreen?style=flat-square\" alt=\"Published\">\n    <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"MIT License\"></a>\n    <a href=\"#how-it-works\"><img src=\"https://img.shields.io/badge/flows-3-orange?style=flat-square\" alt=\"3 Flows\"></a>\n    <a href=\"#hard-rules-by-moment\"><img src=\"https://img.shields.io/badge/dimensions-9-purple?style=flat-square\" alt=\"9 Dimensions\"></a>\n  </p>\n</p>\n\n---\n\n**PlanFirst** is a Claude Code skill that designs the right architecture for your project's **current moment** — not what's trending on Hacker News.\n\nMost AI coding agents recommend what's popular. PlanFirst recommends what's **appropriate**.\n\n---\n\n## Quick Start\n\n```bash\n# Add the marketplace\n/plugin marketplace add Serxo1/planfirst-plugin\n\n# Install the plugin\n/plugin install planfirst@planfirst-marketplace\n```\n\nThen just describe your project:\n\n```\nYou: I'm building a personal finance tracker, solo side project, MVP\n\nPlanFirst: [extracts dimensions, asks 2 follow-up questions,\n           generates architecture.md + agent rules]\n```\n\n> **Local testing:** `claude --plugin-dir ./path-to/planfirst-plugin`\n\n---\n\n## The Problem\n\nYou describe your project to an AI agent. It recommends:\n\n| What it suggests | Your reality |\n|-----------------|-------------|\n| Supabase | You only need a database |\n| Redis | You have 12 users |\n| Kafka | You process 50 events/day |\n| Kubernetes | You're one person |\n| Microservices | Your app has 3 routes |\n\nResult: **$200/mo** in infra, 6 services in Docker Compose, and a weekend lost to DevOps instead of building your product.\n\n## The Solution\n\nPlanFirst analyzes **9 project dimensions** and recommends architecture that fits **where you are now**, with measurable triggers for when to evolve.\n\n```\ndescription ──> extract dimensions ──> confidence scoring\n                                            │\n                              ┌──────────────┴──────────────┐\n                              │                             │\n                        confidence < 0.7              all >= 0.7\n                              │                             │\n                     ask follow-up questions          generate recommendation\n                     (max 4, conversational)                │\n                              │                    ┌────────┴────────┐\n                              └──> re-score ──>    │                 │\n                                              docs/architecture.md  agent file\n                                                                    injection\n```\n\n### The 9 Dimensions\n\n| Dimension | What it captures |\n|-----------|-----------------|\n| `project_moment` | validate / grow / scale / optimize |\n| `product_type` | web, mobile, CLI, game, IoT, data pipeline, desktop |\n| `team_size` | solo, small team, or large org |\n| `user_scale` | from <1k to >1M users |\n| `monthly_budget` | free tier to enterprise spend |\n| `needs_realtime` | chat, live feeds, or just CRUD |\n| `access_pattern` | read-heavy, write-heavy, graph-like, time-series |\n| `has_offline_requirement` | local-first or cloud-only |\n| `latency_critical` | gaming/trading vs blog/admin |\n\n---\n\n## How It Works\n\n### Three Flows\n\n| Flow | Trigger | What it does |\n|------|---------|-------------|\n| **Greenfield** | New project, \"what stack should I use?\" | Extracts dimensions, asks smart follow-ups, recommends stack |\n| **Brownfield** | Existing codebase, \"review my architecture\" | Scans project structure, manifests, schemas — diagnoses complexity |\n| **Update** | Architecture exists, \"we're pivoting to mobile\" | Reads existing doc, preserves what works, evolves the rest |\n\n### The Conversation\n\nPlanFirst doesn't dump a form at you. It infers what it can and asks **max 4 conversational questions** per round:\n\n```\nYou: \"I'm building a social network for dog owners, just me and my\n     co-founder, we have 2k users in beta\"\n\nPlanFirst: I got most of what I need. Two quick questions:\n\n  1. Will users need to see updates from each other in real time,\n     like a live feed or chat?\n     (This determines whether we need WebSocket infrastructure)\n\n  2. Do you have a monthly budget in mind for hosting, or are you\n     trying to stay on free tiers for now?\n     (This affects whether we go managed services or self-hosted)\n```\n\n### Hard Rules by Moment\n\n```\nVALIDATE (MVP)          GROW (post-launch)       SCALE (high traffic)     OPTIMIZE (mature)\n─────────────────       ──────────────────       ────────────────────     ─────────────────\nMax 2 managed svcs      Decouple bundles         Graph DB if graph-like   No new DBs without\nNo Redis                Redis: session only      CDN: non-negotiable      benchmarks\nNo message queues       Evaluate Supabase        Read replicas before     Focus on\nNo microservices        usage (>50%?)            adding cache             observability\nSingle deployable       Start CI/CD              Message queues OK        Reduce cost\n```\n\n### Cross-Cutting Rules\n\n```\nteam_size = 1           → never recommend anything requiring dedicated ops\nlatency_critical        → discuss TCP/UDP transport, not just HTTP\noffline_requirement     → mention local-first (SQLite, PouchDB, Realm)\nCLI tool                → database rarely needed; files or SQLite suffice\ndata pipeline           → Kafka only above 100k events/day\nany recommendation      → MUST link to a specific project dimension\n```\n\n---\n\n## What It Produces\n\n### `docs/architecture.md`\n\nFull architecture spec with:\n\n- Executive summary tied to your project's moment\n- ASCII + Mermaid architecture diagrams\n- **Use Now** — stack with justifications\n- **Add Later** — with measurable triggers (`\"when DAU > 10k\"`), never `\"when you need it\"`\n- **Don't Use Now** — mandatory, minimum 2 items, honest reasons\n- Architecture Decision Records (ADRs)\n- Cost estimates with specific traps\n\n### Agent File Injection\n\nRules automatically injected into `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, or `AGENTS.md`:\n\n```markdown\n<!-- planfirst:start -->\n## Architecture Reference\nFull spec: `./docs/architecture.md` — read before adding any infrastructure.\n\n### Stack (momento: validate)\n- Framework: Next.js\n- DB: SQLite / Turso\n- Hosting: Vercel\n\n### Agent Rules\n- DO NOT add Redis — not justified at current scale\n- DO NOT introduce microservices — single deployable unit\n- PREFER SQLite for persistence until concurrent writes become an issue\n<!-- planfirst:end -->\n```\n\nThese rules **persist across sessions** — your coding agent follows them every time it touches your project.\n\n---\n\n## Use Cases\n\n<table>\n<tr><td width=\"50%\">\n\n### Solo MVP\n> *\"Personal finance tracker, solo, MVP\"*\n\nRecommends SvelteKit + SQLite on Cloudflare.\nTells you NOT to use Redis, Supabase, or Docker.\n**Monthly cost: $0.**\n\n</td><td width=\"50%\">\n\n### Database Decision\n> *\"Social network for dog owners, 2k beta users\"*\n\nDetects graph-like access patterns.\nRecommends PostgreSQL now, flags graph DB for later.\n**Neo4j at 2k users? Not yet.**\n\n</td></tr>\n<tr><td>\n\n### Codebase Review\n> *\"Review this project\" (7 Docker services)*\n\nScans structure, manifests, schemas.\nFlags premature complexity.\n**Diagnosis + evolution roadmap.**\n\n</td><td>\n\n### Post-Funding Scaling\n> *\"Series A, 50k MAU, next phase?\"*\n\nCDN (non-negotiable), Redis for sessions (now justified).\n**Cost estimates with traps included.**\n\n</td></tr>\n<tr><td>\n\n### Architecture Update\n> *\"Adding mobile to our web app\"*\n\nPreserves what works, adds mobile ADRs.\n**Updates agent rules for multi-platform.**\n\n</td><td>\n\n### Stopping Over-Engineering\n> *\"I want Redis and Kafka for my blog\"*\n\nFirmly says no. HTTP caching + CDN instead.\n**\"Reconsider when p95 > 500ms under load.\"**\n\n</td></tr>\n</table>\n\n---\n\n## Install\n\n### From marketplace (recommended)\n\n```bash\n# 1. Add the marketplace\n/plugin marketplace add Serxo1/planfirst-plugin\n\n# 2. Install the plugin\n/plugin install planfirst@planfirst-marketplace\n\n# 3. Use it\n/planfirst:planfirst\n# or just describe your project — the skill triggers automatically\n```\n\n### Local testing\n\n```bash\n# Clone and test locally\ngit clone https://github.com/Serxo1/planfirst-plugin.git\nclaude --plugin-dir ./planfirst-plugin\n```\n\n### Manual skill install\n\n```bash\n# Copy to your Claude Code skills directory\ncp -r skills/planfirst ~/.claude/skills/planfirst\n\n# Use with\n/planfirst\n```\n\n---\n\n## Philosophy\n\n| Principle | What it means |\n|-----------|--------------|\n| **Moment over hype** | Validate-stage needs different infra than scale-stage |\n| **Dimension-linked** | Every recommendation ties to a specific project dimension |\n| **Measurable triggers** | \"Add when DAU > 10k\" — never \"add when you need it\" |\n| **Honest avoids** | Always tells you what NOT to use (mandatory, min 2) |\n| **Solo-friendly** | `team_size = 1` means zero ops overhead, period |\n| **Agent-native** | Rules persist in your agent file across sessions |\n\n---\n\n## Contributing\n\nFound a rule that should be different? A moment heuristic that's off? Open an issue or PR.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 9404,
  "sha": "bcc7353f83892cced5f57d075fd1c3184ef0a07e48a5a4271913778b8a401ecd",
  "repo_slug": "serxo1/planfirst-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_serxo1_planfirst_plugin_plan_first_7ac5ea6b/readme"
}