jfl 0.4.3 → 0.5.0

package/packages/pi/skills/startup/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: startup
+description: The startup journey from idea to scale — stage assessment, MVP scoping, launch playbooks, informed by Paul Graham + Garry Tan
+---
+
+# Startup Skill
+
+The startup journey from idea to scale, informed by Paul Graham + Garry Tan wisdom.
+
+---
+
+## Philosophy
+
+**Vision is emergent.** You don't know what you're building at first. The skill adapts to where you are.
+
+**Do things that don't scale.** Early stage is about learning, not efficiency.
+
+**Talk to users.** Every week. The answers are in conversations, not spreadsheets.
+
+---
+
+## Commands
+
+```
+/startup                      # Where am I? What's next?
+/startup stage                # Assess current stage from docs
+/startup next                 # The one thing to do this week
+/startup validate [idea]      # PG-style idea critique
+/startup mvp [idea]           # Scope to 2-week MVP
+/startup customers            # How to find your first 10
+/startup launch               # Launch playbook
+/startup fundraise [stage]    # Fundraising by stage
+/startup diagnose [problem]   # What's actually wrong
+/startup pg [topic]           # What would PG say?
+/startup garry [topic]        # What would Garry say?
+```
+
+---
+
+## THE STAGES
+
+### Stage 0: Idea
+
+**Goal:** Validate that real people have this problem and will pay to solve it.
+
+**Key questions:**
+- Who has this problem? (Be specific—names, not personas)
+- How are they solving it now?
+- Why will they switch to you?
+- What's the insight that makes this work?
+
+**PG frameworks:**
+- "How to Get Startup Ideas" - Live in the future, build what's missing
+- "Schlep Blindness" - The best ideas look like work
+- "Organic Startup Ideas" - Build what you need yourself
+- "Frighteningly Ambitious Startup Ideas" - Think bigger
+
+**Actions:**
+1. Talk to 10 potential users this week
+2. Document their exact words (not your interpretation)
+3. Find the hair-on-fire problem
+
+**Anti-patterns:**
+- Building before talking
+- Asking "would you use this?" (ask about their current behavior)
+- Targeting everyone (niche down)
+
+---
+
+### Stage 1: MVP
+
+**Goal:** Build the smallest thing that delivers value to one person.
+
+**Key questions:**
+- What's the one thing it needs to do?
+- Can you build it in 2 weeks?
+- Can you describe it in one sentence?
+
+**PG frameworks:**
+- "Do Things That Don't Scale" - Manual before automated
+- "The Airbnbs" - Professional photos changed everything
+- "Ramen Profitable" - Survive while you figure it out
+- "Default Alive or Default Dead" - Know which you are
+
+**Actions:**
+1. Cut scope until it hurts
+2. Ship something this week
+3. Get it in front of one real user
+
+**Anti-patterns:**
+- Building for 6 months before launching
+- Adding features before anyone uses it
+- Waiting until it's "ready"
+
+---
+
+### Stage 2: First Customers
+
+**Goal:** Get 5-10 paying customers manually.
+
+**Key questions:**
+- Who are the first 10 people who will pay?
+- Can you name them?
+- How will you reach them?
+
+**PG frameworks:**
+- "Do Things That Don't Scale" - Recruit users manually
+- "Relentlessly Resourceful" - Find a way or make one
+- "Be Good" - Make something people want
+- "Mean People Fail" - Nice founders win
+
+**Garry frameworks:**
+- "Default alive matters" - Grow profitably if you can't raise
+- "Six skills for startup success" - What to develop early
+
+**Actions:**
+1. Make a list of 20 potential customers (names, not categories)
+2. Reach out to 5 today
+3. Offer to do it for them manually
+
+**Anti-patterns:**
+- Waiting for inbound
+- Mass marketing before product-market fit
+- Discounting instead of learning
+
+---
+
+### Stage 3: Launch
+
+**Goal:** Create a moment that gets attention and establishes your position.
+
+**Key questions:**
+- What's the story?
+- Who will amplify it?
+- What's the one thing people should remember?
+
+**PG frameworks:**
+- "Startup = Growth" - Launch is just the beginning of the curve
+- "How to Convince Investors" - Same principles apply to users
+- "The Submarine" - PR is a game
+
+**Actions:**
+1. Line up 5 people who will share on launch day
+2. Have a specific, concrete demo
+3. Ship, don't wait for perfect
+
+**Anti-patterns:**
+- Launch as a one-time event (it's a process)
+- Waiting for the "right moment"
+- Announcing without showing
+
+---
+
+### Stage 4: Growth
+
+**Goal:** Find repeatable acquisition and scale what works.
+
+**Key questions:**
+- What's your growth rate?
+- What's the one channel that's working?
+- Are you default alive?
+
+**PG frameworks:**
+- "Startup = Growth" - If you're not growing, you're dying
+- "The Fatal Pinch" - When growth and runway cross
+- "How to Raise Money" - Raise when you don't need it
+- "Founder Mode" - Stay hands-on longer than feels right
+
+**Garry frameworks:**
+- "Why startups are growing 5x faster" - AI enables smaller teams
+- "Micromanagement is toxic" - Delegate as you scale
+
+**Actions:**
+1. Measure weekly growth rate
+2. Double down on what's working
+3. Kill what isn't
+
+**Anti-patterns:**
+- Premature scaling
+- Hiring before product-market fit
+- Multiple channels before one works
+
+---
+
+## DIAGNOSIS FRAMEWORK
+
+When something's wrong, find the root cause:
+
+| Symptom | Likely Cause | Prescription |
+|---------|--------------|--------------|
+| No users signing up | Distribution problem or wrong audience | Talk to 10 more people, find where they are |
+| Users sign up but don't use | Onboarding or value prop problem | Watch 5 users try it, fix the friction |
+| Users use but don't pay | Pricing or value problem | Ask them what they'd pay for |
+| Users churn | Not solving real problem | Talk to churned users, find why |
+| Can't raise money | Traction or story problem | Focus on customers, not investors |
+| Growing but unprofitable | Unit economics problem | Fix before you scale |
+
+---
+
+## INTEGRATION WITH DOCS
+
+The skill reads your docs to understand where you are:
+
+```
+knowledge/VISION.md     → EMERGENT = still figuring it out
+                       → DECLARED = you know what you're building
+
+knowledge/CRM.md        → Who you're talking to, what's resonating
+
+content/articles/       → How you explain it to the world
+
+drafts/                 → Active outreach, what's working
+```
+
+---
+
+## KNOWLEDGE BASE
+
+```
+knowledge/startup/
+├── 0-idea/
+│   ├── HOW_TO_GET_STARTUP_IDEAS.md
+│   ├── SCHLEP_BLINDNESS.md
+│   ├── ORGANIC_STARTUP_IDEAS.md
+│   └── VALIDATION.md
+├── 1-mvp/
+│   ├── DO_THINGS_THAT_DONT_SCALE.md
+│   ├── RAMEN_PROFITABLE.md
+│   └── SCOPE.md
+├── 2-customers/
+│   ├── FIRST_10.md
+│   ├── RELENTLESSLY_RESOURCEFUL.md
+│   └── BE_GOOD.md
+├── 3-launch/
+│   ├── LAUNCH_PLAYBOOK.md
+│   └── STARTUP_EQUALS_GROWTH.md
+├── 4-growth/
+│   ├── THE_FATAL_PINCH.md
+│   ├── HOW_TO_RAISE_MONEY.md
+│   └── FOUNDER_MODE.md
+└── raw/
+    ├── pg/              # All PG essays
+    └── garry/           # All Garry content
+```
+
+---
+
+## QUICK REFERENCE
+
+### The PG Stack
+
+1. **Make something people want** (the only thing that matters)
+2. **Do things that don't scale** (early stage superpower)
+3. **Talk to users** (the answers are there)
+4. **Launch fast** (embarrassingly early)
+5. **Grow or die** (weekly growth is the metric)
+
+### The Garry Stack
+
+1. **Default alive > default dead**
+2. **AI enables smaller teams**
+3. **Delegation > micromanagement**
+4. **Learn or earn at every job**
+5. **The best time to start is now**
+
+### Anti-patterns (from "18 Mistakes That Kill Startups")
+
+1. Single founder
+2. Bad location
+3. Marginal niche
+4. Derivative idea
+5. Obstinacy
+6. Hiring bad programmers
+7. Choosing the wrong platform
+8. Slowness in launching
+9. Launching too early
+10. Having no specific user in mind
+11. Raising too little money
+12. Spending too much
+13. Raising too much money
+14. Poor investor management
+15. Sacrificing users to (supposed) profit
+16. Not wanting to get your hands dirty
+17. Fights between founders
+18. A half-hearted effort
+
+---
+
+## OUTPUT FILES
+
+```
+outputs/startup/
+├── assessments/
+│   └── stage-assessment-{date}.md
+├── ideas/
+│   └── validation-{idea}.md
+├── mvp/
+│   └── scope-{idea}.md
+└── fundraising/
+    └── prep-{stage}.md
+```
+
+---
+
+## SOURCES
+
+- Paul Graham essays: paulgraham.com (200+ essays)
+- Garry Tan: blog.garrytan.com, YC blog, YouTube
+- Y Combinator library: ycombinator.com/library
+
+---
+
+*"Make something people want."* — Paul Graham
+
+*"At every job you should either learn or earn. Either is fine. Both is best. But if it's neither, quit."* — Garry Tan

package/packages/pi/skills/web-architect/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: web-architect
+description: Generate brand assets and audit web code against best practices - CSS, favicons, social images, exports, React/Next.js performance
+---
+
+# Web Architect Skill
+
+Implements the brand system by generating all required assets. Also audits web code against best practices.
+
+## Related Skills
+
+- **react-best-practices** - React/Next.js performance optimization. Use when building or auditing React sites.
+
+## Capabilities
+
+- Generate favicon package (all sizes)
+- Create social assets (OG images, banners, PFP)
+- Build CSS with brand tokens
+- Export SVGs to PNGs
+- Audit asset completeness
+- Update preview files with final assets
+
+## Input Requirements
+
+Requires `knowledge/BRAND_DECISIONS.md` with:
+- Selected mark
+- Color palette
+- Typography choices
+
+## Commands
+
+```
+/web-architect                    # Show status
+/web-architect audit              # Check what's missing
+/web-architect implement all      # Generate everything
+/web-architect implement css      # Generate CSS only
+/web-architect implement favicons # Generate favicon package
+/web-architect implement social   # Generate social assets
+/web-architect implement marks    # Generate mark size variants
+/web-architect export png         # Export all SVGs to PNG
+```
+
+## Workflow
+
+### Audit
+
+```
+/web-architect audit
+
+Checking brand assets...
+
+MARKS:
+├─ [✓] Primary mark selected
+├─ [✓] Transparent version
+├─ [ ] Size variants (80, 160, 400)
+└─ [ ] Dark/light variants
+
+FAVICONS:
+├─ [ ] 16px
+├─ [ ] 32px
+├─ [ ] 48px
+├─ [ ] 96px
+├─ [ ] 180px (Apple Touch)
+├─ [ ] 192px (Android)
+└─ [ ] 512px (PWA)
+
+SOCIAL:
+├─ [ ] Twitter banner (1500x500)
+├─ [ ] OG image (1200x630)
+├─ [ ] Twitter PFP (400x400)
+└─ [ ] Banner size variants
+
+CSS:
+├─ [ ] Color tokens
+├─ [ ] Typography tokens
+└─ [ ] global.css generated
+
+Missing: 18 assets
+Run /web-architect implement all to generate.
+```
+
+### Implement All
+
+```
+/web-architect implement all
+
+Generating brand assets...
+
+MARKS:
+├─ [✓] mark-v3-80-dark.svg
+├─ [✓] mark-v3-80-light.svg
+├─ [✓] mark-v3-160-dark.svg
+├─ [✓] mark-v3-400-dark.svg
+└─ Saved to outputs/svg/mark/
+
+FAVICONS:
+├─ [✓] favicon-16-dark.svg
+├─ [✓] favicon-32-dark.svg
+├─ [✓] favicon-48-dark.svg
+├─ [✓] favicon-96-dark.svg
+├─ [✓] favicon-180-dark.svg
+├─ [✓] favicon-192-dark.svg
+├─ [✓] favicon-512-dark.svg
+└─ Saved to outputs/svg/favicon/
+
+SOCIAL:
+├─ [✓] twitter-banner-sm-1500x500-dark.svg
+├─ [✓] twitter-banner-md-1500x500-dark.svg
+├─ [✓] twitter-banner-lg-1500x500-dark.svg
+├─ [✓] twitter-banner-xl-1500x500-dark.svg
+├─ [✓] og-default-1200x630-dark.svg
+├─ [✓] pfp-400-dark.svg
+└─ Saved to outputs/svg/social/
+
+CSS:
+├─ [✓] outputs/css/global.css
+└─ Tokens from BRAND_DECISIONS.md
+
+PNG EXPORT:
+├─ [✓] All SVGs exported to PNG
+└─ Saved to outputs/png/
+
+Complete! 24 assets generated.
+```
+
+## Asset Generation
+
+### Favicons
+
+Generate all standard favicon sizes:
+
+```bash
+# Sizes needed
+16   - Browser tab
+32   - Browser tab @2x
+48   - Windows
+96   - Android Chrome
+180  - Apple Touch Icon
+192  - Android Chrome @2x
+512  - PWA splash
+```
+
+SVG structure:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {size} {size}">
+  <rect width="100%" height="100%" fill="{bg-color}"/>
+  <!-- Mark scaled to fit with padding -->
+</svg>
+```
+
+### Social Assets
+
+#### Twitter Banner (1500x500)
+- Box with mark inside
+- Left-aligned with padding
+- Size variants: sm, md, lg, xl
+
+#### OG Image (1200x630)
+- Mark centered in box
+- Optional: tagline variant
+
+#### PFP (400x400)
+- Square crop
+- Mark centered
+- High contrast
+
+### CSS Generation
+
+Read from BRAND_DECISIONS.md and generate:
+
+```css
+:root {
+  /* Colors from decisions */
+  --brand-bg: {bg};
+  --brand-fg: {fg};
+  --brand-accent: {accent};
+
+  /* Typography from decisions */
+  --brand-font: {font-stack};
+  --brand-font-weight: {weight};
+}
+```
+
+### PNG Export
+
+Use rsvg-convert for all SVG → PNG conversions:
+
+```bash
+# Single file
+rsvg-convert -w {width} -h {height} input.svg -o output.png
+
+# Batch export script
+./scripts/export-pngs.sh
+```
+
+## File Structure
+
+```
+outputs/
+├── svg/
+│   ├── mark/
+│   │   ├── mark-v3-transparent.svg
+│   │   ├── mark-v3-80-dark.svg
+│   │   ├── mark-v3-80-light.svg
+│   │   ├── mark-v3-160-dark.svg
+│   │   ├── mark-v3-400-dark.svg
+│   │   └── ...
+│   ├── social/
+│   │   ├── twitter-banner-sm-1500x500-dark.svg
+│   │   ├── twitter-banner-md-1500x500-dark.svg
+│   │   ├── twitter-banner-lg-1500x500-dark.svg
+│   │   ├── twitter-banner-xl-1500x500-dark.svg
+│   │   ├── og-default-1200x630-dark.svg
+│   │   ├── pfp-400-dark.svg
+│   │   └── (light variants)
+│   └── favicon/
+│       ├── favicon-16-dark.svg
+│       ├── favicon-32-dark.svg
+│       └── ...
+├── png/
+│   ├── mark/
+│   ├── social/
+│   └── favicon/
+└── css/
+    └── global.css
+```
+
+## Naming Conventions
+
+```
+{type}-{variant}-{size}-{theme}.{ext}
+
+Examples:
+mark-v3-80-dark.svg
+twitter-banner-xl-1500x500-dark.svg
+og-tagline-1200x630-dark.svg
+favicon-32-dark.png
+```
+
+## Error Handling
+
+### No Decisions Found
+```
+No brand decisions found.
+
+Run /brand-architect first to:
+1. Generate mark options
+2. Select colors and typography
+3. Record decisions
+
+Then run /web-architect implement all.
+```
+
+### Missing Dependencies
+```
+rsvg-convert not found.
+
+PNG export requires librsvg. Install with:
+  brew install librsvg   # macOS
+  apt install librsvg2-bin  # Ubuntu
+```
+
+### Incomplete Decisions
+```
+Brand decisions incomplete.
+
+Missing:
+- Primary mark selection
+- Color palette
+
+Update knowledge/BRAND_DECISIONS.md or run /brand-architect decide.
+```
+
+---
+
+## Code Auditing
+
+### React/Next.js Projects
+
+For React or Next.js sites, use the **react-best-practices** skill:
+
+```
+/web-architect audit react
+```
+
+This runs the Vercel React Best Practices audit covering:
+- Eliminating waterfalls (CRITICAL)
+- Bundle size optimization (CRITICAL)
+- Server-side performance (HIGH)
+- Client-side data fetching (MEDIUM-HIGH)
+- Re-render optimization (MEDIUM)
+- Rendering performance (MEDIUM)
+- JavaScript performance (LOW-MEDIUM)
+
+See `skills/react-best-practices/SKILL.md` for full rule reference.
+
+### Static Sites
+
+For static HTML sites:
+```
+/web-architect audit static
+```
+
+Checks:
+- Asset optimization (images, SVGs)
+- CSS best practices
+- Accessibility basics
+- Performance hints