ideabox 1.0.0

package/skills/ideabox/references/scoring-rubric.md

@@ -0,0 +1,245 @@
+# Idea Scoring Rubric
+
+## Hard Filter (must pass at least one)
+
+### Monetization Gate
+The idea has a clear path to revenue:
+- SaaS subscription (recurring)
+- One-time purchase / lifetime deal
+- Freemium (free tier + paid features)
+- Marketplace fees / commissions
+- Sponsorware (open source + paid sponsors)
+- Paid plugins / extensions
+- API access / usage-based pricing
+- Consulting / services built on the tool
+
+### Open-Source Impact Gate
+The idea would gain significant community traction:
+- Solves a pain point many developers face daily
+- Fills a gap in a popular ecosystem (npm, crates.io, MCP, etc.)
+- High potential for GitHub stars (comparable projects have 1K+ stars)
+- Evidence of community demand (forum posts, issues, comments asking for it)
+
+**If an idea passes neither gate, discard it immediately.**
+
+---
+
+## Scoring Dimensions (each 1-10, max 60)
+
+### 1. Revenue Potential
+
+| Score | Criteria |
+|-------|----------|
+| 1-3 | No clear revenue model, or market too small |
+| 4-5 | Possible freemium model, small market, low willingness to pay |
+| 6-7 | Clear revenue model, proven willingness to pay in comparable products, $1K-5K MRR potential |
+| 8-9 | Strong revenue model, large market, pricing precedent, $5K-20K MRR potential |
+| 10 | Exceptional: large underserved market, high willingness to pay, $20K+ MRR potential |
+
+### 2. Market Gap
+
+| Score | Criteria |
+|-------|----------|
+| 1-3 | Many good solutions already exist |
+| 4-5 | Solutions exist but are mediocre, expensive, or poorly maintained |
+| 6-7 | 1-2 competitors but significant room for improvement |
+| 8-9 | No direct competitor, or existing solutions miss key use case |
+| 10 | Completely greenfield -- nobody has built this |
+
+### 3. Demand Signal
+
+| Score | Criteria |
+|-------|----------|
+| 1-3 | No evidence of demand (just seems like a good idea) |
+| 4-5 | A few forum posts or tweets mentioning the problem |
+| 6-7 | Multiple sources show demand: GitHub issues, Reddit threads, HN comments |
+| 8-9 | Strong cross-platform demand: trending topics, many upvotes, recurring requests |
+| 10 | Overwhelming demand: appears across 4+ sources, hundreds of upvotes/stars |
+
+**Cross-source bonus:** If the same idea appears across 2+ independent sources:
+- 2 sources: +2 to demand signal
+- 3+ sources: +3 to demand signal (capped at 10)
+
+### 4. Feasibility
+
+| Score | Criteria |
+|-------|----------|
+| 1-3 | Requires large team, significant infrastructure, or domain expertise you lack |
+| 4-5 | Buildable but challenging: 2-4 weeks for MVP, some unknowns |
+| 6-7 | Achievable in 1-2 weeks with AI assistance, well-understood problem |
+| 8-9 | Weekend MVP: clear scope, standard tech, straightforward implementation |
+| 10 | Could build a working prototype in a single session |
+
+### 5. Stack Fit
+
+| Score | Criteria |
+|-------|----------|
+| 1-3 | Requires languages/frameworks you've never used |
+| 4-5 | Requires learning a new stack but related to what you know |
+| 6-7 | Mostly in your wheelhouse, one new tool to learn |
+| 8-9 | Perfect match for your existing skills |
+| 10 | You've built something very similar before |
+
+**Note:** Stack fit is a bonus, never a blocker. A score of 3 doesn't disqualify an idea.
+
+### 6. Trend Momentum
+
+| Score | Criteria |
+|-------|----------|
+| 1-3 | Stable/declining space, no growth signals |
+| 4-5 | Modest growth, some new entrants |
+| 6-7 | Growing space with active investment and developer interest |
+| 8-9 | Hot space: rapid growth, VC funding, many new tools launching |
+| 10 | Explosive: defining category of the year, everyone talking about it |
+
+**Agentic AI bonus:** Ideas in the agentic AI / MCP / AI tooling space get +2 to trend momentum (capped at 10).
+
+---
+
+## Total Score
+
+Sum of all 6 dimensions. Maximum: 60.
+
+| Range | Rating | Action |
+|-------|--------|--------|
+| 45-60 | Exceptional | Build this now |
+| 35-44 | Strong | Worth serious consideration |
+| 25-34 | Decent | Consider if it matches your interests |
+| < 25 | Weak | Skip unless you have a personal reason |
+
+---
+
+## Output Format
+
+### Step 1: Quick-Scan Summary Table
+
+Present ALL ideas in a scannable table first, before detailed cards:
+
+```
+## Research Results: {N} ideas scored
+
+| # | Idea | Score | Rating | Monetization | Complexity | Top Signal |
+|----|------|-------|--------|-------------|------------|------------|
+| 1 | MCP Testing Framework | 48/60 | Exceptional | Freemium $29/mo | 1-week | 47 upvotes on Reddit |
+| 2 | AI Cost Monitor | 42/60 | Strong | SaaS $19/mo | Weekend | 3 HN threads |
+| 3 | Context Engine CLI | 38/60 | Strong | Open source | 1-week | 12 GitHub issues |
+| 4 | Agent Debugger | 35/60 | Strong | Freemium | Multi-week | YC batch trend |
+| 5 | MCP Config Manager | 31/60 | Decent | One-time $29 | Weekend | MCP roadmap |
+```
+
+### Step 2: Visual Score Breakdown Per Idea
+
+For each idea, present a detailed card with visual score bars:
+
+```
+---
+
+### #1: MCP Testing Framework
+
+> Developers cannot test MCP servers before production deployment. No testing tools exist in the ecosystem.
+
+**Score: 48/60 -- Exceptional**
+
+Revenue    [=========-] 9/10   Strong willingness to pay (Postman comparison)
+Gap        [========--] 8/10   No direct competitor exists
+Demand     [=========-] 9/10   47 Reddit upvotes + 3 HN threads + 12 GitHub issues
+Feasibility[========--] 8/10   Weekend MVP achievable
+Stack Fit  [======----] 6/10   TypeScript (your stack), new testing patterns
+Trend      [========--] 8/10   MCP ecosystem is exploding (+2 agentic bonus)
+
+**Evidence chain:**
+  [Reddit]  "How do you test MCP servers?" (47 upvotes, r/LocalLLaMA)
+  [HN]     "Show HN: MCP server testing" (89 points)
+  [GitHub]  12 open issues on modelcontextprotocol/servers requesting testing tools
+
+**Revenue model:** Freemium -- free CLI tool, $29/mo cloud dashboard with CI integration
+  Comparables: Postman ($12/mo), Insomnia (free), Hoppscotch (free)
+
+**Tech stack:**
+  Best: TypeScript + Node.js test runner
+  Yours: TypeScript + Node.js (perfect match)
+
+**Complexity:** 1-week MVP (core test runner + basic assertions)
+
+---
+```
+
+### Score Bar Format
+
+Use bracketed bars to visualize scores at a glance:
+
+| Score | Visual |
+|-------|--------|
+| 10/10 | `[==========]` |
+| 9/10  | `[=========-]` |
+| 8/10  | `[========--]` |
+| 7/10  | `[=======---]` |
+| 6/10  | `[======----]` |
+| 5/10  | `[=====-----]` |
+| 4/10  | `[====------]` |
+| 3/10  | `[===-------]` |
+| 2/10  | `[==--------]` |
+| 1/10  | `[=---------]` |
+
+### Step 3: Action Prompt
+
+After all cards:
+
+```
+Pick an idea: type a number (1-5) to brainstorm and build
+  save N    -- save to backlog for later
+  dismiss N -- not interested (won't suggest similar)
+  compare N M -- side-by-side comparison
+  more      -- show more ideas
+  done      -- finish browsing
+```
+
+### Rating Labels
+
+Use these labels consistently:
+- 45-60: **Exceptional** -- strong evidence, clear path
+- 35-44: **Strong** -- worth serious consideration
+- 25-34: **Decent** -- matches interests
+- < 25: not shown (filtered out)
+
+### Evidence Chain Rules
+
+- Lead with the strongest evidence (highest upvotes/stars)
+- Always include the source platform in brackets: `[Reddit]`, `[HN]`, `[GitHub]`, `[npm]`
+- Include the specific metric: upvotes, points, stars, issue count
+- Link to the actual URL when available
+- Cross-source evidence gets a callout: "Appeared across 3 sources"
+
+### Comparison Format
+
+When user types `compare N M`:
+
+```
+## Head-to-Head: #1 vs #3
+
+|                | #1: MCP Testing    | #3: Context Engine  |
+|----------------|--------------------|--------------------|
+| Score          | **48/60**          | 38/60              |
+| Rating         | Exceptional        | Strong             |
+| Revenue        | [=========-] 9     | [======----] 6     |
+| Gap            | [========--] 8     | [=======---] 7     |
+| Demand         | [=========-] 9     | [======----] 6     |
+| Feasibility    | [========--] 8     | [========--] 8     |
+| Stack Fit      | [======----] 6     | [=========-] 9     |
+| Trend          | [========--] 8     | [==--------] 2     |
+| Monetization   | Freemium $29/mo    | Open source        |
+| Complexity     | 1-week             | 1-week             |
+| Top Evidence   | 47 Reddit upvotes  | 12 GitHub issues   |
+
+**Recommendation:** #1 (MCP Testing) -- higher demand evidence, clearer monetization,
+stronger trend momentum. #3 has better stack fit but weaker market signals.
+
+Build which one? (1 / 3 / neither)
+```
+
+## Ranking
+
+Present ideas sorted by total score (highest first). If tied, prefer:
+1. Higher demand signal (proven market)
+2. Higher feasibility (faster to ship)
+3. Higher revenue potential (monetizable)

package/skills/ideabox/references/self-improvement.md

@@ -0,0 +1,217 @@
+# Self-Improvement Engine
+
+IdeaBox automatically improves its own research, scoring, and query strategies based on outcomes. This file defines the three self-improvement loops.
+
+---
+
+## 1. Source Quality Tracking
+
+Track which research sources contribute to ideas that actually get built.
+
+### Data: `~/.ideabox/source-quality.jsonl`
+
+Append after each session:
+```json
+{"ts":"{ISO}","session_id":"...","source":"agentic_ai","signals_found":5,"contributed_to_chosen":true,"idea_outcome":"completed"}
+{"ts":"{ISO}","session_id":"...","source":"pain_points","signals_found":8,"contributed_to_chosen":false,"idea_outcome":null}
+```
+
+### Source Score Formula
+
+For each source, compute a quality score:
+
+```
+contribution_rate = ideas_contributed_to_chosen / total_sessions_with_source
+outcome_weight = completed: 1.0, started: 0.6, planned: 0.3, dismissed: 0.0
+weighted_score = sum(contribution_rate * outcome_weight) / sessions_count
+
+Final source_score = 0.3 * contribution_rate + 0.4 * weighted_score + 0.3 * avg_signals_per_session
+Clamp to [0.1, 1.0]
+```
+
+### How Sources Adapt
+
+During the research phase:
+1. Read `~/.ideabox/source-quality.jsonl`
+2. Compute source scores
+3. Sources scoring > 0.7: allocate more search queries (expand coverage)
+4. Sources scoring 0.4-0.7: keep as-is
+5. Sources scoring < 0.4 for 5+ sessions: reduce to 1 query (don't eliminate — it may recover)
+6. Present source quality in the Research Coverage stats block:
+
+```
+| Source | Quality | Trend | Sessions |
+|--------|---------|-------|----------|
+| Agentic AI | 0.85 (high) | ↑ improving | 12 |
+| Pain Points | 0.62 (medium) | → stable | 12 |
+| Trending | 0.38 (low) | ↓ declining | 10 |
+```
+
+### Bootstrap (cold start)
+
+If fewer than 5 sessions exist, use equal weights for all sources. Quality tracking activates after 5+ sessions.
+
+---
+
+## 2. Scoring Weight Adaptation
+
+Track which scoring dimensions best predict ideas that actually ship.
+
+### Data: `~/.ideabox/scoring-feedback.jsonl`
+
+Append when an idea reaches a terminal state (completed, abandoned, or dismissed after planning):
+```json
+{
+  "ts": "{ISO}",
+  "idea_id": "...",
+  "outcome": "completed",
+  "original_scores": {"revenue": 7, "gap": 9, "demand": 8, "feasibility": 8, "stack_fit": 9, "trend": 9},
+  "total_score": 50,
+  "phases_completed": 8
+}
+```
+
+### Weight Adaptation Formula
+
+After 10+ scored outcomes, compute correlation between each dimension and successful outcomes:
+
+```
+For each dimension:
+  completed_avg = average score for ideas with outcome=completed
+  abandoned_avg = average score for ideas with outcome=abandoned/dismissed
+  predictive_power = completed_avg - abandoned_avg
+
+Normalize predictive_power across dimensions so they sum to 6.0 (preserving max 60 total).
+```
+
+**Example adaptation:**
+- If `feasibility` strongly predicts completion (high for completed, low for abandoned): increase its weight
+- If `stack_fit` doesn't predict outcomes (similar scores for both): decrease its weight
+- Never let any dimension drop below 0.5 or exceed 1.5 (prevent over-fitting)
+
+### How Weights Apply
+
+In the research phase scoring step:
+1. Read `~/.ideabox/scoring-feedback.jsonl`
+2. If 10+ outcomes exist, compute adapted weights
+3. Replace default equal weights (1.0 each) with adapted weights
+4. Present the adapted weights in the scoring output:
+
+```
+## Scoring Weights (adapted from 15 past outcomes)
+Revenue: 1.2x | Gap: 0.8x | Demand: 1.3x | Feasibility: 1.1x | Stack: 0.7x | Trend: 0.9x
+Note: Demand and Revenue are your strongest predictors of successful projects.
+```
+
+### Bootstrap
+
+If fewer than 10 outcomes, use default equal weights (1.0 each).
+
+---
+
+## 3. Research Query Evolution
+
+Track which search queries return useful results and evolve the query set over time.
+
+### Data: `~/.ideabox/query-performance.jsonl`
+
+Append after each research subagent returns:
+```json
+{
+  "ts": "{ISO}",
+  "session_id": "...",
+  "source": "agentic_ai",
+  "query": "MCP server gaps 2026",
+  "results_count": 8,
+  "useful_results": 3,
+  "contributed_to_idea": true
+}
+```
+
+### Query Lifecycle
+
+Queries go through a lifecycle:
+
+```
+NEW → ACTIVE → (PRODUCTIVE | DECLINING) → (KEEP | RETIRE | REPLACE)
+```
+
+**Scoring per query:**
+```
+query_score = (useful_results / total_results) * 0.5 + (contributed_to_idea ? 0.5 : 0)
+```
+
+**Lifecycle rules:**
+- **NEW** (< 3 uses): always run, building data
+- **ACTIVE** (3+ uses, score > 0.3): keep running
+- **PRODUCTIVE** (5+ uses, score > 0.5): expand with variations
+- **DECLINING** (5+ uses, score < 0.2 for 3 consecutive sessions): mark for retirement
+- **RETIRED** (marked declining for 3+ sessions): stop running, but keep in archive
+
+### Query Evolution
+
+When a query is PRODUCTIVE, generate 1-2 variations:
+- Original: `"MCP server gaps 2026"`
+- Variation 1: `"MCP server most requested features"`
+- Variation 2: `"MCP server community wishlist"`
+
+When a query is RETIRED, generate a replacement based on what IS working:
+- If agentic_ai queries are productive: generate more specific variants
+- If a new technology trend emerges from results: add queries for it
+
+### How Queries Evolve
+
+During the research phase:
+1. Read `~/.ideabox/query-performance.jsonl`
+2. Compute query scores
+3. Build the active query set: all NEW + ACTIVE + PRODUCTIVE queries
+4. Drop RETIRED queries
+5. For PRODUCTIVE queries, add variations if not already tracked
+6. Present query health in the Research Coverage stats:
+
+```
+## Query Health
+- Active queries: 18 (6 productive, 9 active, 3 new)
+- Retired this session: 2 (low yield for 3+ sessions)
+- New variations added: 1 ("AI agent testing framework" from productive "MCP server gaps")
+```
+
+### Bootstrap
+
+If `query-performance.jsonl` doesn't exist, use the default queries from `references/research-sources.md`. All queries start as NEW.
+
+### Query Storage
+
+The evolved query set is NOT stored in a separate file — it's computed from `query-performance.jsonl` on each run. The `research-sources.md` file remains the default/seed query set. Evolved queries are derived from performance data.
+
+---
+
+## Integration Points
+
+### Phase 01 (Research) — reads all three:
+1. Before launching subagents: load source quality scores, adapted scoring weights, and active query set
+2. Allocate more queries to high-quality sources
+3. Use adapted weights in scoring step
+4. Use evolved query set instead of defaults (if enough data exists)
+
+### Phase 09 (Learn) — writes all three:
+1. After session outcome: append to `source-quality.jsonl` (which sources contributed)
+2. After terminal idea state: append to `scoring-feedback.jsonl` (scores vs outcome)
+3. After research phase: append to `query-performance.jsonl` (per-query results)
+
+### Cold Start Protection
+- Source quality: activates after 5 sessions
+- Scoring weights: activates after 10 scored outcomes
+- Query evolution: activates after 3 uses per query
+
+All three fall back to defaults when insufficient data exists. No degradation for new users.
+
+---
+
+## Anti-Drift Safeguards
+
+1. **Score clamping**: source scores [0.1, 1.0], dimension weights [0.5, 1.5]
+2. **Never eliminate**: low-scoring sources get reduced queries, not removed
+3. **Archive, don't delete**: retired queries kept in log for trend analysis
+4. **Periodic reset option**: user can run `/ideas profile` and choose "reset learning" to clear all feedback data and start fresh
+5. **Transparency**: every adapted weight and source score is shown to the user — no hidden adjustments

package/skills/profile/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: profile
+description: >
+  Manage your IdeaBox profile — interests, tech stacks, goals, and GitHub username.
+  Use when asked to "set up ideabox", "edit ideabox profile", "change interests",
+  "update my stack", or "ideabox profile".
+  This skill is also invoked automatically on first /ideas run if no profile exists.
+---
+
+# IdeaBox Profile Manager
+
+Manage the user's IdeaBox profile stored at `~/.ideabox/profile.json`.
+
+## If profile.json exists
+
+Read `~/.ideabox/profile.json` and display the current profile:
+
+```
+## Your IdeaBox Profile
+
+**GitHub:** {github_username}
+**Interests:** {interests as comma-separated list}
+**Tech Stacks:** {stacks as comma-separated list}
+**Goals:** {goals as comma-separated list}
+**Avoid:** {avoid_topics or "none"}
+**Exploration rate:** {exploration_rate}%
+**Total ideas seen:** {total_interactions}
+**Last updated:** {updated_at}
+```
+
+Then ask: "Want to update anything? (interests / stacks / goals / avoid topics / GitHub username / reset learning)"
+
+Update only the fields the user specifies. Set `updated_at` to current ISO timestamp.
+
+### Reset Learning
+
+If the user chooses "reset learning":
+1. Confirm: "This will reset all self-improvement data (source quality, scoring weights, query performance, preference scores). Your profile settings (interests, stacks, goals) will be kept. Proceed? (yes/no)"
+2. If yes:
+   - Delete `~/.ideabox/source-quality.jsonl`
+   - Delete `~/.ideabox/scoring-feedback.jsonl`
+   - Delete `~/.ideabox/query-performance.jsonl`
+   - Delete `~/.ideabox/preferences.jsonl`
+   - Reset `profile.json` fields: `category_scores: {}`, `complexity_preference: {}`, `monetization_preference: {}`, `exploration_rate: 0.30`, `total_interactions: 0`
+   - Confirm: "Learning data reset. IdeaBox will start fresh with default weights and full exploration."
+
+## If profile.json does NOT exist
+
+Run the first-time setup. Ask these questions ONE AT A TIME:
+
+### Question 1
+"What's your GitHub username? (I'll scan your repos to understand your tech stack)"
+
+### Question 2
+"What are you most interested in building? Pick all that apply:
+A) Developer tools (CLIs, plugins, MCP servers, VS Code extensions)
+B) SaaS apps (web apps with subscriptions)
+C) Mobile apps (React Native, Expo, Flutter)
+D) AI/ML tools (agents, wrappers, fine-tuning tools)
+E) Open source libraries (npm packages, crates, PyPI)
+F) Desktop apps (Tauri, Electron)
+G) Other (tell me)"
+
+### Question 3
+"What's your primary goal?
+A) Make money (monetization-first ideas)
+B) Build great open source (community impact)
+C) Both — show me ideas that could do either
+D) Learn new tech (ideas that push my skills)"
+
+### Question 4 (optional)
+"Any topics you want me to avoid? (e.g., crypto, social media, gaming — or 'none')"
+
+Save the profile:
+
+```json
+{
+  "github_username": "{answer1}",
+  "interests": ["{mapped from answer2}"],
+  "stacks": [],
+  "goals": ["{mapped from answer3}"],
+  "avoid_topics": ["{answer4 or empty}"],
+  "category_scores": {},
+  "complexity_preference": {},
+  "monetization_preference": {},
+  "exploration_rate": 0.30,
+  "total_interactions": 0,
+  "created_at": "{ISO timestamp}",
+  "updated_at": "{ISO timestamp}"
+}
+```
+
+The `stacks` array will be populated by the research phase when it scans the user's GitHub profile.
+
+The `category_scores`, `complexity_preference`, `monetization_preference`, `exploration_rate`, and `total_interactions` fields are used by the self-improving recommendation system (Phase 09 — Learn).
+
+After saving, confirm: "Profile saved! Run `/ideas` to get your first batch of project ideas."

package/skills/research/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: research
+description: >
+  Research-only mode — browse project ideas without committing to build.
+  Use when asked to "research ideas", "browse ideas", "just show me ideas",
+  "ideabox research", "what's trending", or "find project ideas".
+---
+
+# IdeaBox Research (Browse Only)
+
+Research and present project ideas without entering the full build pipeline.
+This is the "window shopping" mode — look at ideas, save the ones you like, dismiss the rest.
+
+## Process
+
+This skill delegates to the shared research phase for the actual research logic, but runs in browse-only mode (no automatic transition to brainstorm/plan/build).
+
+### Step 1: Setup
+
+1. Read `~/.ideabox/profile.json`. If it doesn't exist, invoke the `ideabox:profile` skill for setup, then continue.
+2. Create `.ideabox/` directory if needed (for state tracking).
+
+### Step 2: Execute Research Phase
+
+Read `${CLAUDE_SKILL_DIR}/phases/01-research.md` and follow Steps 1-6 (research, score, validate, stats, auto-save, present).
+
+**Browse-only override:** When the user picks an idea, handle differently than the full pipeline:
+
+### Step 3: User Actions
+
+After presenting ideas, offer:
+- **save N** — Save idea #N to backlog (append to `~/.ideabox/ideas.jsonl` with status "saved")
+- **dismiss N** — Dismiss idea #N (append with status "dismissed")
+- **more** — Show 3-5 more ideas from the research results
+- **build N** — Execute Steps 4 and 5 first (log session + track preferences), then save with status "planned", initialize `.ideabox/state.json` with `current_phase: "02-brainstorm"`, and read `${CLAUDE_SKILL_DIR}/phases/02-brainstorm.md`
+- **compare N M** — Side-by-side comparison of two ideas (same format as backlog compare)
+- **done** — Finish browsing
+
+### Step 4: Log Session
+
+Append to `~/.ideabox/sessions.jsonl`:
+```json
+{
+  "session_id": "sess_YYYYMMDD_HHMMSS",
+  "timestamp": "{ISO}",
+  "mode": "research",
+  "sources_searched": "{actual count of subagents that returned results}",
+  "ideas_generated": "{count}",
+  "ideas_presented": "{count}",
+  "ideas_saved": "{count}",
+  "ideas_dismissed": "{count}"
+}
+```
+
+### Step 5: Track Preferences
+
+Append to `~/.ideabox/preferences.jsonl` for each user action:
+```json
+{"ts":"{ISO}","event":"suggested","idea_id":"{id}","category":"{cat}","complexity":"{complexity}","monetization":"{model}"}
+{"ts":"{ISO}","event":"accepted","idea_id":"{id}"}
+{"ts":"{ISO}","event":"dismissed","idea_id":"{id}"}
+```