ideabox 1.0.0

package/skills/ideabox/phases/09-learn.md

@@ -0,0 +1,208 @@
+# Phase 09: Learn
+
+Track what happened, update preferences, and improve future suggestions. This phase always runs — even if earlier phases were skipped.
+
+## Step 1: Record Session Outcome
+
+Determine the session outcome based on which phases completed:
+
+| Phases Completed | Outcome | Event |
+|-----------------|---------|-------|
+| 01 only | browsed | User looked at ideas but didn't pick one |
+| 01-02 | brainstormed | User refined an idea but didn't plan/build |
+| 01-03 | planned | User planned but didn't build |
+| 01-04+ | started | User began building |
+| 01-07+ | shipped | User shipped the project |
+| 01-08+ | completed | Full cycle including post-ship |
+
+## Step 2: Update Idea Status
+
+Read `.ideabox/state.json` to get the idea that was worked on.
+
+Append a status update to `~/.ideabox/ideas.jsonl`:
+```json
+{"type":"status_update","idea_id":"{id}","old_status":"planned","new_status":"{outcome_status}","timestamp":"{ISO}"}
+```
+
+Status mapping:
+- browsed/brainstormed/planned -> keep status as "planned" (incomplete)
+- started -> "in_progress"
+- shipped/completed -> "built"
+
+## Step 3: Record Implicit Feedback
+
+Append to `~/.ideabox/preferences.jsonl`:
+
+```json
+{"ts":"{ISO}","event":"{outcome}","idea_id":"{id}","category":"{idea_category}","complexity":"{idea_complexity}","monetization":"{idea_monetization}","phases_completed":{count},"dropped_at_phase":"{phase_name_or_null}"}
+```
+
+## Step 4: Update Preference Scores
+
+Read `~/.ideabox/profile.json` and update scores based on what happened:
+
+### Signal Weights
+| Event | Weight |
+|-------|--------|
+| accepted (picked idea) | +0.15 |
+| dismissed | -0.10 |
+| started (began building) | +0.25 |
+| completed (shipped) | +0.40 |
+| abandoned (dropped mid-build) | -0.20 |
+
+### Score Update Formula
+
+For the idea's category, complexity, and monetization type:
+```
+new_score = old_score + (learning_rate * signal_weight)
+learning_rate = 0.3
+Clamp result to [0.05, 0.95]
+```
+
+Example: if category is "developer-tools" with current score 0.6, and user completed the project:
+```
+new_score = 0.6 + (0.3 * 0.40) = 0.72
+```
+
+### Update category_scores
+```json
+"category_scores": {
+  "developer-tools": {"accepted": 9, "dismissed": 2, "completed": 4, "score": 0.72}
+}
+```
+Increment the relevant counter and update the score.
+
+### Update complexity_preference
+Same formula for the idea's complexity level (weekend, 1-week, multi-week).
+
+### Update monetization_preference
+Same formula for the idea's monetization type (freemium, saas, sponsorware, etc.).
+
+### Decay Exploration Rate
+```
+exploration_rate = max(0.10, 0.3 / sqrt(total_interactions))
+```
+This starts at 30% (high exploration when data is scarce) and decays toward 10% as more data accumulates. The 10% floor ensures some random suggestions always appear — preventing echo chambers.
+
+### Increment total_interactions
+```
+total_interactions += 1
+```
+
+### Save Updated Profile
+Write the updated scores back to `~/.ideabox/profile.json`.
+
+## Step 5: Pattern Detection
+
+Check for repeating patterns:
+
+- **If same category shipped 3+ times:** Note in profile as "preferred category" (add to interests if not already there)
+- **If same category dismissed 3+ times:** Note as "frequently dismissed" but DO NOT remove from consideration (exploration rate keeps it alive)
+- **If user consistently picks high-feasibility ideas:** Note preference for "quick wins"
+- **If user consistently picks high-revenue ideas:** Note "monetization-focused"
+
+## Step 6: Self-Improvement Data Updates
+
+Read `${CLAUDE_SKILL_DIR}/references/self-improvement.md` for the full specification, then update the following. **Note:** `query-performance.jsonl` was already written during Phase 01 — do NOT re-write it here.
+
+### 6a: Source Quality Tracking
+
+For each research source used in this session, append to `~/.ideabox/source-quality.jsonl`:
+```json
+{"ts":"{ISO}","session_id":"...","source":"{source_name}","signals_found":{N},"contributed_to_chosen":{true|false},"idea_outcome":"{outcome}"}
+```
+
+Record whether each source contributed signals that were part of the chosen idea's evidence chain.
+
+### 6b: Scoring Feedback
+
+If the idea reached a terminal state (completed, abandoned, or dismissed after brainstorming), append to `~/.ideabox/scoring-feedback.jsonl`:
+```json
+{"ts":"{ISO}","idea_id":"...","outcome":"{outcome}","original_scores":{"revenue":7,"gap":9,"demand":8,"feasibility":8,"stack_fit":9,"trend":9},"total_score":50,"phases_completed":8}
+```
+
+This feeds the scoring weight adaptation engine — after 10+ outcomes, dimension weights auto-adjust to predict successful projects better.
+
+### 6c: Adaptation Summary
+
+If enough data exists (5+ sessions for source quality, 10+ outcomes for scoring), compute and show:
+
+```
+## Self-Improvement Status
+
+**Source Quality (from {N} sessions):**
+- Best source: {name} (score: {X})
+- Weakest source: {name} (score: {X})
+- Sources to expand next session: {list}
+- Sources to reduce: {list}
+
+**Scoring Adaptation (from {N} outcomes):**
+- Strongest predictor: {dimension} ({weight}x) — ideas you ship score high on this
+- Weakest predictor: {dimension} ({weight}x) — doesn't correlate with what you build
+- Weights: Revenue {X}x | Gap {X}x | Demand {X}x | Feasibility {X}x | Stack {X}x | Trend {X}x
+
+**Query Health (from {N} queries tracked):**
+- Active: {N} | Productive: {N} | Retired: {N}
+- New variations generated: {N}
+```
+
+If insufficient data, show: "Self-improvement activates after 5+ sessions. Current: {N} sessions."
+
+## Step 7: Session Summary
+
+Present to the user:
+
+```
+## Session Summary
+
+**Idea:** {title}
+**Phases completed:** {list of phases}
+**Outcome:** {outcome}
+
+**Preferences updated:**
+- Category "{category}": {old_score} -> {new_score}
+- Complexity "{complexity}": {old_score} -> {new_score}
+- Exploration rate: {old_rate}% -> {new_rate}%
+- Total ideas seen: {total_interactions}
+
+Run `/ideas` again for your next project!
+```
+
+## Step 8: Log Session
+
+Append to `~/.ideabox/sessions.jsonl`:
+```json
+{
+  "session_id": "{session_id}",
+  "timestamp": "{ISO}",
+  "mode": "full_pipeline",
+  "idea_id": "{id}",
+  "idea_title": "{title}",
+  "idea_category": "{category}",
+  "phases_completed": ["01-research", "02-brainstorm", ...],
+  "outcome": "{outcome}",
+  "duration_phases": {count},
+  "score_updates": {
+    "category": {"field": "{category}", "old": 0.6, "new": 0.72},
+    "complexity": {"field": "{complexity}", "old": 0.5, "new": 0.65}
+  }
+}
+```
+
+## Step 9: Clean Up State
+
+Delete `.ideabox/state.json` (session complete — no need to resume).
+
+**Session artifact archival:** Move `.ideabox/session/` to `.ideabox/archive/{session_id}/` to preserve artifacts without accumulating clutter. If more than 10 archived sessions exist, delete the oldest ones (keep the 10 most recent).
+
+## Gate Condition
+
+Phase 09 always passes. It completes when preferences are updated and session is logged.
+
+## Anti-Echo-Chamber Safeguards
+
+1. **Score clamping [0.05, 0.95]:** Nothing is ever fully eliminated or guaranteed
+2. **Exploration floor 10%:** Always some random/diverse suggestions
+3. **Diversity guarantee:** Each suggestion batch spans >= 3 categories
+4. **Novelty bonus:** +0.1 for categories not recently suggested
+5. **No hard blocks:** Even "frequently dismissed" categories can appear via exploration

package/skills/ideabox/references/research-sources.md

@@ -0,0 +1,247 @@
+---
+type: reference
+title: Research Sources & Data Endpoints
+description: Source catalog for research subagents. 6 parallel subagents launched per session; additional categories serve as supplementary reference.
+---
+
+# Research Sources
+
+This catalog defines all available research categories. During execution, **6 parallel subagents** are launched (categories 1-4 + 5 + 6). Categories 5, 7, 8, and 10 are consolidated into other subagents or used as filter steps, not standalone subagents.
+
+---
+
+## Source Categories
+
+### 1. Agentic AI Ecosystem (PRIORITY)
+
+The highest-value category. Agentic AI tools, MCP servers, Claude Code plugins, and AI coding assistants are exploding in demand.
+
+**WebSearch queries:**
+- `"MCP server" site:github.com`
+- `"Claude Code plugin" OR "claude code skill"`
+- `"AI coding agent" framework 2025 2026`
+- `"agentic AI" developer tool`
+
+**API endpoints:**
+- HN Algolia: `https://hn.algolia.com/api/v1/search_by_date?tags=story&query=MCP+server&hitsPerPage=25`
+- HN Algolia: `https://hn.algolia.com/api/v1/search_by_date?tags=story&query=AI+coding+agent&hitsPerPage=25`
+- HN Algolia: `https://hn.algolia.com/api/v1/search_by_date?tags=story&query=Claude+Code+plugin&hitsPerPage=25`
+- GitHub Search: `gh api "/search/repositories?q=MCP+server+created:>$(date -v-30d +%Y-%m-%d 2>/dev/null || date -d '30 days ago' +%Y-%m-%d)+stars:>5&sort=stars&per_page=30"`
+- GitHub Search: `gh api "/search/repositories?q=claude+code+plugin+created:>$(date -v-90d +%Y-%m-%d 2>/dev/null || date -d '90 days ago' +%Y-%m-%d)&sort=stars&per_page=30"`
+- GitHub Topics: `gh api "/search/repositories?q=topic:mcp+topic:server&sort=stars&per_page=30"`
+
+**Key signals:** New frameworks, missing integrations, unserved use cases, complaints about existing tools.
+
+---
+
+### 2. Developer Pain Points
+
+Complaints and frustrations are the strongest demand signals. Developers describe exactly what they need.
+
+**API endpoints:**
+- Reddit r/webdev: `https://www.reddit.com/r/webdev/top.json?t=week&limit=25`
+- Reddit r/node: `https://www.reddit.com/r/node/top.json?t=week&limit=25`
+- Reddit r/typescript: `https://www.reddit.com/r/typescript/top.json?t=week&limit=25`
+- Reddit r/nextjs: `https://www.reddit.com/r/nextjs/top.json?t=week&limit=25`
+- Reddit r/reactjs: `https://www.reddit.com/r/reactjs/top.json?t=week&limit=25`
+- HN Ask HN: `https://hn.algolia.com/api/v1/search_by_date?tags=ask_hn&hitsPerPage=25`
+- HN Algolia: `https://hn.algolia.com/api/v1/search?query=frustrated+with&tags=comment&hitsPerPage=25`
+- Stack Overflow (via WebSearch): `"site:stackoverflow.com [tag] no library" OR "is there a tool"`
+
+**Key signals:** "I wish there was...", "Why doesn't X exist?", "Frustrated with...", "Looking for alternatives to..."
+
+---
+
+### 3. Trending Projects
+
+What's gaining traction right now. Early-stage projects with momentum reveal where demand is heading.
+
+**API endpoints:**
+- GitHub new stars: `gh api "/search/repositories?q=created:>$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d '7 days ago' +%Y-%m-%d)+stars:>10&sort=stars&per_page=30"`
+- GitHub weekly stars: `gh api "/search/repositories?q=created:>$(date -v-30d +%Y-%m-%d 2>/dev/null || date -d '30 days ago' +%Y-%m-%d)+stars:>50&sort=stars&per_page=30"`
+- HN Show HN (high points): `https://hn.algolia.com/api/v1/search_by_date?tags=show_hn&numericFilters=points>50&hitsPerPage=25`
+- HN Show HN (recent): `https://hn.algolia.com/api/v1/search_by_date?tags=show_hn&hitsPerPage=25`
+
+**Key signals:** Rapid star growth, Show HN with 100+ points, trending topics appearing across platforms.
+
+---
+
+### 4. Indie Hacker / Monetization
+
+Real revenue data and validated business models from solo developers and small teams.
+
+**API endpoints:**
+- Reddit r/SideProject: `https://www.reddit.com/r/SideProject/top.json?t=week&limit=25`
+- Reddit r/indiehackers: `https://www.reddit.com/r/indiehackers/top.json?t=week&limit=25`
+- Reddit r/SaaS: `https://www.reddit.com/r/SaaS/top.json?t=week&limit=25`
+- Reddit r/microsaas: `https://www.reddit.com/r/microsaas/top.json?t=week&limit=25`
+- HN Algolia: `https://hn.algolia.com/api/v1/search?query=side+project+revenue&tags=story&hitsPerPage=25`
+
+**Key signals:** Revenue numbers, pricing strategies, market validation, "hit $X MRR" posts.
+
+---
+
+### 5. AI SaaS Landscape
+
+The broader AI tooling ecosystem. Identify white space where existing tools fall short.
+
+**Sources (WebSearch/WebFetch):**
+- YC news and batch companies: WebSearch `"YC" "AI" "developer tool" site:ycombinator.com`
+- AI funding rounds: WebSearch `"AI startup" "seed round" "developer tool" 2026`
+- AI SaaS directories: WebSearch `"AI tools for developers" list 2026`
+- HN Algolia: `https://hn.algolia.com/api/v1/search_by_date?tags=story&query=AI+SaaS&hitsPerPage=25`
+
+**Note:** Product Hunt deprioritized due to API limitations. Use WebSearch for PH pages if needed.
+
+**Key signals:** Funding activity in specific niches, gaps YC companies haven't filled, underserved verticals.
+
+---
+
+### 6. Package Ecosystem Gaps
+
+Missing, unmaintained, or poorly-implemented packages in the npm/Python ecosystems.
+
+**API endpoints:**
+- npm search: `https://registry.npmjs.org/-/v1/search?text=keyword:{keyword}&size=25`
+- npm downloads: `https://api.npmjs.org/downloads/point/last-week/{package}`
+- npm downloads range: `https://api.npmjs.org/downloads/range/last-month/{package}`
+- GitHub issues (abandoned): `gh api "/search/issues?q=repo:{owner}/{repo}+is:open+is:issue+sort:created-desc&per_page=10"`
+
+**Assessment flow:**
+1. Search for packages in a category
+2. Check download counts (low downloads + high GitHub stars = opportunity)
+3. Check last publish date (>1 year = potentially abandoned)
+4. Read open issues for unmet needs
+5. Look for "looking for alternative" issues
+
+**Key signals:** Deprecated packages with high downloads, missing TypeScript support, abandoned projects with active forks.
+
+---
+
+### 7. MCP & Plugin Ecosystems
+
+The Claude Code / MCP ecosystem and adjacent plugin marketplaces.
+
+**Sources:**
+- GitHub MCP servers: `gh api "/search/repositories?q=topic:mcp+topic:server&sort=stars&per_page=30"`
+- GitHub Claude Code plugins: `gh api "/search/repositories?q=claude+code+plugin&sort=stars&per_page=30"`
+- GitHub Cursor extensions: `gh api "/search/repositories?q=cursor+extension&sort=stars&per_page=20"`
+- Awesome MCP lists: WebFetch `https://raw.githubusercontent.com/punkpeye/awesome-mcp-servers/main/README.md`
+- WebSearch: `"MCP server" "missing" OR "need" OR "wish" site:github.com`
+
+**Key signals:** Categories with few servers, frequently requested integrations, popular tools without MCP support.
+
+---
+
+### 8. Claude Code Skills & Plugin Inspiration
+
+Study existing Claude Code plugins/skills for patterns, gaps, and improvement opportunities.
+
+**Known plugins to study:**
+- `superpowers` — skill collections, patterns for multi-skill plugins
+- `gstack` — project scaffolding and templates
+- `labrat` — autonomous research and experiment loops
+- `engineering-skills` — code quality and engineering best practices
+- `claudemod` — modding and customization
+
+**Analysis approach:**
+1. Clone or WebFetch README of each known plugin
+2. Catalog what each plugin does
+3. Identify missing categories (deployment, monitoring, database, testing, documentation, security)
+4. Look for plugin interoperability gaps
+5. Note UI/UX patterns that work well
+
+**Key signals:** Plugin categories with zero entries, common workflows not yet automated, integration gaps between plugins.
+
+---
+
+### 9. User's GitHub Profile
+
+Personalize recommendations based on the user's actual skills and interests.
+
+**API endpoints:**
+- User repos: `https://api.github.com/users/{username}/repos?sort=updated&per_page=30`
+- User repos (via CLI): `gh api "/users/{username}/repos?sort=updated&per_page=30"`
+- User starred repos: `gh api "/users/{username}/starred?per_page=30"`
+- User languages: Aggregate from repo language fields
+
+**Extracted signals:**
+- Primary languages and frameworks
+- Domain expertise (web, CLI, mobile, blockchain, AI, etc.)
+- Project patterns (libraries vs apps vs plugins)
+- Active vs archived repos
+- Star counts on own projects (what resonated)
+
+**Note:** Username is loaded from `~/.ideabox/profile.json` or prompted on first run.
+
+---
+
+### 10. Dismissed Ideas Filter
+
+Prevent resurfacing ideas the user has already seen and rejected.
+
+**Data source:**
+- Load from `~/.ideabox/ideas.jsonl`
+- Each line: `{"id":"...","title":"...","problem":"...","status":"dismissed|built|saved|suggested","timestamp":"..."}`
+
+**Matching logic (concrete rules since this runs in LLM context, not code):**
+- Extract 3-5 key terms from each dismissed idea's title and problem statement
+- For each new idea, check if 3+ key terms overlap with any dismissed idea
+- Also check: same target user AND same problem domain = likely match
+- If match found: skip idea or flag as "similar to dismissed: {name}"
+- If status is `backlog`: note it, don't skip (user may want to revisit)
+- When in doubt, present the idea with a note: "Note: similar to previously dismissed idea '{name}'"
+
+**Key behavior:** Never silently drop ideas. Always log when a match is found with the reason.
+
+---
+
+## Subagent Output Format
+
+Each subagent returns an array of structured signals:
+
+```json
+[
+  {
+    "source_category": "developer_pain_points",
+    "source_url": "https://www.reddit.com/r/webdev/comments/abc123/...",
+    "signal_type": "gap|complaint|trend|revenue",
+    "title": "No good self-hosted analytics with AI insights",
+    "description": "Multiple developers complaining about lack of privacy-focused analytics that use AI to surface actionable insights automatically.",
+    "evidence": "Reddit post with 247 upvotes, 89 comments. Top comment: 'I've been looking for exactly this for months'",
+    "demand_score": 8
+  }
+]
+```
+
+### Signal Types
+
+| Type | Description | Weight |
+|------|-------------|--------|
+| `gap` | Missing tool or feature in the ecosystem | High |
+| `complaint` | Active frustration with existing solutions | High |
+| `trend` | Growing interest or momentum | Medium |
+| `revenue` | Evidence of willingness to pay | Very High |
+
+### Demand Score Guidelines
+
+| Score | Meaning |
+|-------|---------|
+| 1-3 | Weak signal, single source, few engagements |
+| 4-5 | Moderate signal, some engagement |
+| 6-7 | Strong signal, multiple engagements or cross-platform |
+| 8-9 | Very strong, high engagement, multiple sources |
+| 10 | Overwhelming demand, viral discussion |
+
+---
+
+## Aggregation
+
+After all subagents complete, the aggregator:
+
+1. Deduplicates signals (fuzzy match on title + description)
+2. Groups related signals into idea clusters
+3. Cross-references with dismissed ideas filter
+4. Scores each cluster using the scoring rubric
+5. Ranks ideas by total score
+6. Formats top ideas for presentation

package/skills/ideabox/references/revenue-models.md

@@ -0,0 +1,81 @@
+# Revenue Model Library
+
+Reference for assessing monetization potential of project ideas.
+
+## Model 1: SaaS Subscription
+
+**Pattern:** Monthly/annual recurring fee for hosted service.
+**Pricing range:** $9-99/month for individual devs, $29-499/month for teams.
+**Examples:** Vercel ($20/mo), Railway ($5/mo), Supabase ($25/mo), Sentry ($26/mo).
+**Best for:** Tools that provide ongoing value, need hosting, or aggregate data.
+**Moat:** Data network effects, switching costs, integrations.
+
+## Model 2: Freemium / Open Core
+
+**Pattern:** Core product is free and open source. Paid tier adds features.
+**Pricing range:** Free tier unlimited for personal use, $19-99/month for pro features.
+**Examples:** PostHog (free -> $450/mo), GitButler (free -> teams), Raycast (free -> $8/mo).
+**Best for:** Developer tools where adoption matters more than immediate revenue.
+**Moat:** Community, ecosystem, brand.
+
+## Model 3: One-Time Purchase / Lifetime Deal
+
+**Pattern:** Pay once, use forever. Optional paid updates for major versions.
+**Pricing range:** $29-299 one-time.
+**Examples:** Sublime Text ($99), TablePlus ($89), Paw/RapidAPI ($50).
+**Best for:** Desktop apps, CLI tools, tools where the value is immediate.
+**Moat:** Quality, brand loyalty.
+
+## Model 4: Sponsorware
+
+**Pattern:** Open source but early access / premium features for GitHub sponsors.
+**Pricing range:** $5-25/month sponsorship tiers.
+**Examples:** Sindre Sorhus packages, Caleb Porzio (Livewire), Anthony Fu (VueUse).
+**Best for:** Popular open source projects with a solo maintainer.
+**Moat:** Reputation, community trust.
+
+## Model 5: API / Usage-Based
+
+**Pattern:** Pay per API call, per token, per request.
+**Pricing range:** $0.001-1 per call depending on compute.
+**Examples:** OpenAI API, Stripe ($0.029/txn), Twilio ($0.0075/msg).
+**Best for:** Infrastructure tools, data services, AI wrappers with added value.
+**Moat:** Infrastructure lock-in, data moats.
+
+## Model 6: Marketplace / Platform Fee
+
+**Pattern:** Take a percentage of transactions on your platform.
+**Pricing range:** 5-30% of transaction value.
+**Examples:** Gumroad (10%), Lemon Squeezy (5%), Shopify apps (20%).
+**Best for:** Tools that facilitate transactions between creators and consumers.
+**Moat:** Two-sided network effects.
+
+## Model 7: Paid Plugin / Extension
+
+**Pattern:** Sell plugins for popular platforms (VS Code, Figma, Claude Code).
+**Pricing range:** $5-49 one-time or $3-19/month.
+**Examples:** VS Code extensions, Figma plugins, Raycast extensions.
+**Best for:** Niche tools that enhance existing platforms.
+**Moat:** Platform ecosystem, first-mover in a niche.
+
+## Model 8: Consulting + Tool
+
+**Pattern:** Open source tool that creates demand for paid consulting/support.
+**Pricing range:** $150-500/hour consulting, $5K-50K projects.
+**Examples:** Hashicorp (Terraform -> consulting), many DevOps tools.
+**Best for:** Complex infrastructure tools where expertise is valuable.
+**Moat:** Expertise, reputation.
+
+---
+
+## Quick Assessment
+
+When evaluating which model fits an idea:
+
+1. **Does it need hosting?** -> SaaS or API
+2. **Is adoption more important than revenue initially?** -> Freemium
+3. **Is it a one-time solve?** -> One-time purchase
+4. **Does it enhance an existing platform?** -> Paid plugin
+5. **Are you building a reputation?** -> Sponsorware
+6. **Does it facilitate transactions?** -> Marketplace
+7. **Is the value in expertise, not code?** -> Consulting + Tool