ideabox 1.0.0

package/skills/ideabox/phases/01-research.md

@@ -0,0 +1,173 @@
+# Phase 01: Research
+
+Research project ideas from multiple data sources using parallel subagents. Present scored, evidence-backed ideas for the user to pick from.
+
+## Prerequisites
+
+- Read `~/.ideabox/profile.json` — if missing, invoke the `ideabox:profile` skill for setup, then continue
+- Read `~/.ideabox/ideas.jsonl` (if exists) — load dismissed and built idea IDs for deduplication
+
+## Step 0: Load Self-Improvement Data
+
+Read `${CLAUDE_SKILL_DIR}/references/self-improvement.md` for the full self-improvement engine specification, then load adaptive data:
+
+1. **Source quality** — read `~/.ideabox/source-quality.jsonl` (if exists, 5+ entries). Compute source scores. Allocate more queries to high-quality sources, reduce queries for low-quality sources.
+2. **Scoring weights** — read `~/.ideabox/scoring-feedback.jsonl` (if exists, 10+ outcomes). Compute adapted dimension weights. If insufficient data, use default equal weights (1.0 each).
+3. **Query evolution** — read `~/.ideabox/query-performance.jsonl` (if exists). Build the active query set: drop RETIRED queries, add variations for PRODUCTIVE queries. If no data, use default queries from `${CLAUDE_SKILL_DIR}/references/research-sources.md`.
+
+If any self-improvement file doesn't exist or has insufficient data, use defaults silently — no error messages for new users.
+
+## Step 1: Launch Parallel Research Subagents
+
+Announce: "Researching project ideas across 6 source categories..."
+
+**Rate limiting note:** Reddit JSON endpoints may return 429 if hit too aggressively. GitHub API allows 60 req/hr unauthenticated (5000 with `gh` CLI). HN Algolia has no documented limit. If any API returns an error, the subagent should note the failure and continue with available data — never retry in a loop.
+
+Launch these 6 subagents in parallel using the Agent tool. Each subagent searches its category and returns structured findings.
+
+**Subagent 1 — Agentic AI Ecosystem (PRIORITY):**
+"Research the agentic AI ecosystem for project opportunities. Use WebSearch to find:
+- Gaps in AI agent frameworks (LangChain, CrewAI, AutoGen, Claude Agent SDK, OpenAI Agents SDK)
+- Missing or requested MCP servers
+- Claude Code plugin ideas and feature requests
+- AI coding tool extension gaps (Cursor, Windsurf, Cline)
+Also use WebFetch on `https://hn.algolia.com/api/v1/search_by_date?tags=story&query=MCP+agent+framework&numericFilters=points%3E20` for trending HN posts about agents.
+Return a JSON array of findings. Each finding: {source_category: 'agentic_ai', source_url: '...', signal_type: 'gap|complaint|trend|revenue', title: '...', description: '...', evidence: '...', demand_score: 1-10}"
+
+**Subagent 2 — Developer Pain Points:**
+"Search for developer complaints and unmet needs. Use WebFetch on:
+- `https://www.reddit.com/r/webdev/top.json?t=week&limit=25`
+- `https://www.reddit.com/r/selfhosted/top.json?t=week&limit=25`
+- `https://www.reddit.com/r/SideProject/top.json?t=week&limit=25`
+- `https://hn.algolia.com/api/v1/search_by_date?tags=ask_hn&numericFilters=points%3E30`
+Look for 'I wish this existed', unresolved problems, and repeated complaints.
+Return JSON array of findings with: source_category: 'developer_pain_points', source_url, signal_type, title, description, evidence, demand_score."
+
+**Subagent 3 — Trending Projects:**
+"Find projects gaining rapid traction. Use WebSearch for 'github trending developer tools this week'. Use WebFetch on:
+- `https://hn.algolia.com/api/v1/search_by_date?tags=show_hn&numericFilters=points%3E50`
+Identify patterns in what's trending and gaps adjacent to trending projects.
+Return JSON array with: source_category: 'trending', source_url, signal_type, title, description, evidence, demand_score."
+
+**Subagent 4 — Indie Hacker & Monetization:**
+"Search for revenue-generating developer tool projects and validated business models. Use WebSearch for 'indie hacker developer tool revenue 2026', 'micro SaaS making money 2026'. Use WebFetch on:
+- `https://www.reddit.com/r/indiehackers/top.json?t=month&limit=25`
+Focus on projects making $1K-50K MRR and pricing models that work.
+Return JSON array with: source_category: 'indie_hacker', source_url, signal_type, title, description, evidence, demand_score."
+
+**Subagent 5 — Package & Plugin Ecosystem:**
+"Search for gaps in npm packages, Claude Code plugins, and MCP servers. Use WebSearch for 'Claude Code plugin marketplace', 'missing MCP servers', 'npm trending new packages'. Use WebFetch on `https://registry.npmjs.org/-/v1/search?text=claude-code-plugin&size=20`.
+Return JSON array with: source_category: 'packages', source_url, signal_type, title, description, evidence, demand_score."
+
+**Subagent 6 — User's GitHub Profile:**
+"Fetch the GitHub profile for {profile.github_username}. Use WebFetch on `https://api.github.com/users/{username}/repos?sort=updated&per_page=30`. Extract primary languages, frameworks, project types, and notable repos with star counts.
+Return a JSON object: {languages: [...], frameworks: [...], project_types: [...], notable_repos: [{name, stars, description}]}"
+
+## Step 2: Score & Filter
+
+Once all subagents return:
+
+1. **Merge** all findings into a single list
+2. **Synthesize** — look for ideas that combine signals from multiple findings (same gap from different sources = one stronger idea, not two weak ones)
+3. **Cross-reference bonus** — ideas appearing across 2+ sources get +2 demand signal; 3+ sources get +3 (capped at 10)
+4. **Apply agentic AI bonus** — ideas in agentic AI / MCP / AI tooling space get +2 trend momentum (capped at 10)
+5. **Filter history** — load dismissed/built ideas from `~/.ideabox/ideas.jsonl`, remove ideas with >70% title+problem similarity
+6. **Filter avoid topics** — remove ideas matching `profile.avoid_topics`
+7. **Score each idea** — read `${CLAUDE_SKILL_DIR}/references/scoring-rubric.md` and apply:
+   - Rate each of 6 dimensions 1-10
+   - Hard filter: must pass monetization gate OR open-source impact gate
+   - Apply adapted scoring weights from Step 0 (if available). Multiply each dimension score by its weight before summing.
+   - If using adapted weights, show them: "Scoring with adapted weights: Revenue 1.2x, Demand 1.3x, ..."
+   - Compute weighted total
+8. **Filter** — remove ideas scoring below 25 (adjusted for weight changes)
+9. **Rank** — sort by total score descending
+10. **Update profile stacks** — if GitHub subagent returned language data, update `~/.ideabox/profile.json` stacks field
+11. **Record query performance** — for each subagent's queries, append to `~/.ideabox/query-performance.jsonl`: query text, results count, useful results count, contributed to any presented idea
+
+## Step 3: Demand Validation
+
+For each top idea, mentally verify these forcing questions (from YC office hours methodology):
+
+1. **Demand Reality:** What concrete evidence exists that someone wants this? (not interest — actual demand)
+2. **Status Quo:** What are people doing now, even badly?
+3. **Desperate Specificity:** Who exactly needs this? (their role, what gets them promoted/fired)
+4. **Narrowest Wedge:** What's the smallest version someone would pay for this week?
+
+If an idea fails all 4 questions, demote it regardless of score.
+
+## Step 4: Research Coverage Stats
+
+Before presenting ideas, show a research stats block so the user knows what was searched:
+
+```
+## Research Coverage
+
+| Source | Items Found | Top Signal |
+|--------|------------|------------|
+| HN (Algolia) | N stories | "{highest-scored title}" |
+| GitHub Search | N repos | "{top repo}" |
+| Reddit (r/webdev, r/SideProject) | N threads | "{top thread}" |
+| npm Registry | N packages | "{trending package}" |
+| Agentic AI ecosystem | N gaps found | "{top gap}" |
+| GitHub Profile | N repos analyzed | Primary: {languages} |
+
+**Total signals:** N findings across M sources
+**Cross-source matches:** N ideas appeared in 2+ sources
+**Filtered out:** N ideas (previously dismissed or built)
+**Confidence:** HIGH / MEDIUM / LOW (based on source coverage)
+```
+
+## Step 5: Auto-Save Research History
+
+Save the full research results to `~/.ideabox/research/YYYY-MM-DD-HHMMSS.md` (create directory if needed). This builds a searchable research history for trend detection over time.
+
+Include: all findings, scores, sources searched, and timestamp. If previous research exists from the past 30 days, briefly note any trends ("MCP testing tools appeared in 3 of your last 5 research sessions — demand is persistent").
+
+## Step 6: Present Top Ideas
+
+Present 3-5 ideas using the output format from `${CLAUDE_SKILL_DIR}/references/scoring-rubric.md`.
+
+Then ask:
+"Pick an idea number to brainstorm and build, or:
+- `save N` to save idea #N for later
+- `dismiss N` to dismiss idea #N
+- `more` for additional ideas
+- `done` to finish browsing"
+
+## Step 7: Handle User Choice
+
+**If user picks an idea to build:**
+1. Append the full idea record to `~/.ideabox/ideas.jsonl` with status "planned"
+2. Update `.ideabox/state.json`:
+   - Set `idea` field with id, title, problem
+   - Set `current_phase` to "02-brainstorm"
+   - Add "01-research" to `phases_completed`
+   - Set `artifacts.research` to `.ideabox/session/01-research.md`
+3. Write research summary to `.ideabox/session/01-research.md` (idea details + evidence + scores)
+4. Do NOT log to sessions.jsonl here — Phase 09 (Learn) handles the final session log with complete outcome data
+5. Proceed to Phase 02
+
+**If user saves/dismisses:**
+- Append to `~/.ideabox/ideas.jsonl` with appropriate status
+- Continue presenting or ask for next action
+
+**If user wants more:**
+- Present next 3-5 ideas from ranked list
+
+**If user says done:**
+- Log session to `~/.ideabox/sessions.jsonl`
+- Append all presented-but-not-acted-on ideas to `ideas.jsonl` with status "suggested"
+- End phase
+
+## Gate Condition
+
+Phase 01 passes when: >=3 ideas have been presented with >=3 evidence sources each AND user has picked one idea to build.
+
+## Preferences Tracking
+
+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}"}
+```

package/skills/ideabox/phases/02-brainstorm.md

@@ -0,0 +1,213 @@
+# Phase 02: Brainstorm
+
+Refine the chosen idea into a full design spec through collaborative dialogue.
+
+## HARD GATE
+
+Do NOT write any code, scaffold any project, or take any implementation action until the design is presented and user-approved. This applies regardless of perceived simplicity.
+
+## Prerequisites
+
+Read `.ideabox/session/01-research.md` for the chosen idea's details: problem statement, evidence, target users, monetization angle, tech stack suggestions, and score.
+
+## Step 1: Explore Context
+
+- Check the current project directory for existing code, docs, recent commits
+- If this is a new project (no existing code), note that the brainstorm should include project structure decisions
+- If adding to an existing project, follow existing patterns
+
+## Step 2: Scope Check
+
+If the idea describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"):
+- Flag this immediately
+- Help decompose into sub-projects
+- Each sub-project gets its own spec -> plan -> build cycle
+- Brainstorm the first sub-project through this process
+
+## Step 3: Ambiguity Scoring (Deep-Interview Validation)
+
+Before diving into detailed questions, score the idea's clarity across 4 dimensions:
+
+| Dimension | Weight | Score 1-10 | What to assess |
+|-----------|--------|-----------|----------------|
+| Problem Clarity | 35% | ? | Is the problem specific? Who exactly has it? |
+| Target User Clarity | 25% | ? | Can you name the job title? What gets them promoted/fired? |
+| MVP Scope Clarity | 25% | ? | Is the smallest viable version defined? |
+| Monetization Clarity | 15% | ? | Is the revenue model specific with pricing precedent? |
+
+**Ambiguity Score** = weighted average. Present it:
+```
+Ambiguity Check: Problem 7/10 | User 5/10 | Scope 4/10 | Revenue 8/10 | Overall: 5.9/10
+```
+
+**If overall < 6/10:** Focus clarifying questions on the lowest-scoring dimensions. "Your idea's scope is still vague — let me ask a few questions to sharpen it."
+
+**If overall >= 8/10:** Skip most clarifying questions, proceed directly to approaches.
+
+### Assumption Challenges
+
+After 3-4 clarifying questions, inject one challenge question:
+- **Contrarian:** "What if nobody pays for this? What would you do differently?"
+- **Simplifier:** "Can this be cut to a weekend MVP? What's the absolute minimum?"
+- **Status quo:** "Why wouldn't someone just use [existing tool] instead?"
+
+These prevent echo-chamber thinking. Ask ONE challenge, not all three.
+
+## Step 4: Clarifying Questions
+
+Ask questions ONE AT A TIME to refine the idea. Rules:
+
+- **One question per message** — never overwhelm with multiple questions
+- **Prefer multiple choice** — easier to answer than open-ended
+- **Focus on:** purpose, constraints, success criteria, user experience, technical boundaries
+- **Stop asking when** you have enough clarity to propose approaches (usually 3-5 questions)
+
+Good questions for a project idea:
+- "Who is the primary user — developers using it daily, or occasional users?"
+- "What's the MVP scope — which features are essential for v1?"
+- "Any technical constraints? (hosting, budget, specific stack requirements)"
+- "What does success look like in 2 weeks? In 3 months?"
+
+## Step 5: Propose 2-3 Approaches
+
+Present 2-3 different approaches with trade-offs:
+
+```
+### Approach A: [Name] (Recommended)
+[Description, architecture, key decisions]
+**Pros:** ...
+**Cons:** ...
+**Effort:** Weekend MVP / 1-week / Multi-week
+
+### Approach B: [Name]
+[Description, architecture, key decisions]
+**Pros:** ...
+**Cons:** ...
+**Effort:** ...
+
+### Approach C: [Name] (if applicable)
+...
+```
+
+Lead with your recommendation and explain why. Consider:
+- The user's tech stack from their profile
+- The monetization angle from research
+- The complexity vs. impact trade-off
+- YAGNI — remove unnecessary features ruthlessly
+
+## Step 6: Present Design
+
+Once the user picks an approach (or you converge on one), present the design section by section:
+
+- Scale each section to its complexity (a few sentences if straightforward, up to 200-300 words if nuanced)
+- Ask after each section: "Does this look right so far?"
+- Be ready to go back and revise
+
+**Sections to cover:**
+1. **Overview** — what it does, who it's for, one-paragraph summary
+2. **Architecture** — high-level structure, key components, data flow
+3. **Core Features** — MVP feature list (YAGNI: only what's needed for v1)
+4. **Tech Stack** — recommended stack with reasoning
+5. **Data Model** — key entities and relationships (if applicable)
+6. **API / Interface** — how users interact with it
+7. **Monetization** — specific revenue model from research, pricing strategy
+8. **Success Criteria** — measurable outcomes for v1
+
+### Design for Isolation and Clarity
+- Break the system into smaller units with one clear purpose each
+- Each unit: clear interfaces, independently testable, understandable without reading internals
+- Prefer smaller, focused files — you reason better about code you can hold in context
+
+## Step 7: Spec Self-Review
+
+After presenting the complete design, review it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, vague requirements? Fix them.
+2. **Internal consistency:** Do sections contradict each other? Does architecture match features?
+3. **Scope check:** Focused enough for a single implementation plan?
+4. **Ambiguity check:** Could any requirement be interpreted two ways? Pick one, make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+## Step 8: Write Spec Document
+
+Save the validated design to `.ideabox/session/02-brainstorm-spec.md`:
+
+```markdown
+# [Project Name] Design Spec
+
+**Date:** {today}
+**Idea Score:** {score}/60
+**Target Users:** {who}
+**Monetization:** {model}
+
+## Problem
+{one paragraph}
+
+## Solution
+{one paragraph}
+
+## Architecture
+{description + component diagram if helpful}
+
+## Core Features (MVP)
+{numbered list}
+
+## Tech Stack
+{stack with reasoning}
+
+## Data Model
+{entities and relationships}
+
+## Success Criteria
+{measurable outcomes}
+```
+
+## Step 9: Write Handoff Document
+
+Save a structured handoff to `.ideabox/session/02-handoff.md`:
+
+```markdown
+# Phase 02 Handoff: Brainstorm -> Plan
+
+## Decisions Made
+- [list key design decisions with reasoning]
+
+## Alternatives Rejected
+- [list approaches considered but not chosen, with why]
+
+## Risks Identified
+- [list risks that the plan/build phases should watch for]
+
+## Ambiguity Score (Final)
+- Problem: X/10 | User: X/10 | Scope: X/10 | Revenue: X/10 | Overall: X/10
+
+## Next Phase Needs
+- [what the planning phase should focus on]
+```
+
+## Step 10: User Review Gate
+
+Ask: "Spec written to `.ideabox/session/02-brainstorm-spec.md`. Please review — any changes before we plan the implementation?"
+
+Wait for user response. If changes requested, make them and re-run self-review. Only proceed once approved.
+
+## Step 11: Update State
+
+Update `.ideabox/state.json`:
+- Add "02-brainstorm" to `phases_completed`
+- Set `current_phase` to "03-plan"
+- Set `artifacts.brainstorm` to `.ideabox/session/02-brainstorm-spec.md`
+
+## Gate Condition
+
+Phase 02 passes when: spec document is written, self-reviewed (no placeholders, no ambiguity), and user-approved.
+
+## Key Principles
+
+- **One question at a time** — don't overwhelm
+- **Multiple choice preferred** — easier to answer
+- **YAGNI ruthlessly** — cut unnecessary features
+- **Always 2-3 approaches** — never settle without exploring alternatives
+- **Incremental validation** — present sections, get approval, move on
+- **Design before code** — the HARD GATE is absolute

package/skills/ideabox/phases/03-plan.md

@@ -0,0 +1,166 @@
+# Phase 03: Plan
+
+Create a comprehensive implementation plan from the approved spec.
+
+## Prerequisites
+
+Read `.ideabox/session/02-brainstorm-spec.md` for the approved design spec.
+
+## Philosophy
+
+Write the plan assuming the engineer has zero context and questionable taste. Document everything: which files to touch, code examples, test commands, expected output. Bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+## Step 1: Scope Check
+
+If the spec covers multiple independent subsystems, suggest breaking into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+
+## Step 2: Map File Structure
+
+Before defining tasks, map out which files will be created or modified:
+
+- Design units with clear boundaries and well-defined interfaces
+- Each file should have one clear responsibility
+- Prefer smaller, focused files over large ones
+- Files that change together should live together
+- In existing codebases, follow established patterns
+
+Document this structure at the top of the plan.
+
+## Step 3: Define Tasks
+
+Each task follows this structure:
+
+```markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.ext`
+- Modify: `exact/path/to/existing.ext`
+- Test: `tests/exact/path/to/test.ext`
+
+- [ ] **Step 1: Write the failing test**
+[actual test code in a code block]
+
+- [ ] **Step 2: Run test to verify it fails**
+Run: `[exact command]`
+Expected: FAIL with "[expected error]"
+
+- [ ] **Step 3: Write minimal implementation**
+[actual implementation code in a code block]
+
+- [ ] **Step 4: Run test to verify it passes**
+Run: `[exact command]`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+```bash
+git add [specific files]
+git commit -m "[descriptive message]"
+```
+```
+
+### Bite-Sized Granularity
+
+Each step is ONE action (2-5 minutes):
+- "Write the failing test" — one step
+- "Run it to make sure it fails" — one step
+- "Implement the minimal code" — one step
+- "Run tests to verify" — one step
+- "Commit" — one step
+
+### No Placeholders — These Are Plan Failures
+
+NEVER write any of these:
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without actual test code)
+- "Similar to Task N" (repeat the code — tasks may be read out of order)
+- Steps that describe what to do without showing how
+- References to types, functions, or methods not defined in any task
+
+Every step must contain the actual content an engineer needs.
+
+## Step 4: Write Plan Document
+
+Save the complete plan to `.ideabox/session/03-plan.md`:
+
+```markdown
+# [Project Name] Implementation Plan
+
+**Goal:** [One sentence]
+**Architecture:** [2-3 sentences]
+**Tech Stack:** [Key technologies]
+
+---
+
+## File Structure
+[mapped structure from Step 2]
+
+---
+
+### Task 1: [Component]
+[full task with steps, code, commands]
+
+### Task 2: [Component]
+...
+```
+
+## Step 5: Plan Self-Review
+
+After writing the complete plan, review it:
+
+1. **Spec coverage:** Skim each section in the spec. Can you point to a task that implements it? List any gaps.
+2. **Placeholder scan:** Search for "TBD", "TODO", "appropriate", "similar to", "handle edge cases". Fix any found.
+3. **Type consistency:** Do types, method signatures, and property names match across tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
+
+If issues found, fix inline. If a spec requirement has no task, add the task.
+
+## Step 6: User Review Gate
+
+Present the plan to the user:
+"Plan written to `.ideabox/session/03-plan.md` with {N} tasks. Review it — any changes before we start building?"
+
+Wait for approval.
+
+## Step 7: Execution Handoff
+
+After plan is approved, offer execution choice:
+
+"Two execution options:
+1. **Subagent-Driven (recommended)** — I dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Higher quality, faster iteration.
+2. **Inline Execution** — I execute tasks sequentially in this session with verification checkpoints.
+
+Which approach?"
+
+## Step 8: Write Plan Handoff
+
+Save a structured handoff to `.ideabox/session/03-handoff.md`:
+
+```markdown
+# Phase 03 Handoff: Plan -> Build
+
+## Plan Summary
+- {N} tasks defined
+- Estimated complexity: {weekend/1-week/multi-week}
+- Key architectural decisions: [list]
+
+## Execution Recommendation
+- {Subagent-driven or Inline} because {reason}
+
+## Risks for Build Phase
+- [potential blockers or tricky areas]
+
+## Dependencies
+- [external packages, APIs, or services needed]
+```
+
+## Step 9: Update State
+
+Update `.ideabox/state.json`:
+- Add "03-plan" to `phases_completed`
+- Set `current_phase` to "04-build"
+- Set `artifacts.plan` to `.ideabox/session/03-plan.md`
+
+## Gate Condition
+
+Phase 03 passes when: plan document is written, self-review passes (no placeholders, full spec coverage, type consistency), and user approves.