ideabox 1.0.0

package/bin/cli.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = resolve(__dirname, "..");
+
+const SKILLS = ["ideabox", "research", "backlog", "profile"];
+const MARKER_START = "<!-- ideabox:start -->";
+const MARKER_END = "<!-- ideabox:end -->";
+const HOME = homedir();
+const DATA_DIR = join(HOME, ".ideabox");
+
+function hasCommand(cmd) {
+  try {
+    const check = process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`;
+    execSync(check, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function autoDetect() {
+  const targets = [];
+  if (hasCommand("claude")) targets.push("claude");
+  if (hasCommand("codex")) targets.push("codex");
+  if (targets.length === 0) {
+    console.log("No supported CLI detected. Installing to .claude/skills/ (default).");
+    targets.push("claude");
+  }
+  return targets;
+}
+
+function getSkillsDir(target) {
+  switch (target) {
+    case "claude":
+      return join(process.cwd(), ".claude", "skills");
+    case "codex":
+      return join(HOME, ".codex", "skills");
+    case "codex-project":
+      return join(process.cwd(), ".codex", "skills");
+    default:
+      return join(process.cwd(), ".claude", "skills");
+  }
+}
+
+function getInstructionFile(target) {
+  if (target === "codex" || target === "codex-project") {
+    return join(process.cwd(), "AGENTS.md");
+  }
+  return join(process.cwd(), "CLAUDE.md");
+}
+
+function getInstructionSource(target) {
+  if (target === "codex" || target === "codex-project") {
+    return join(ROOT, "AGENTS.md");
+  }
+  return join(ROOT, "CLAUDE.md");
+}
+
+function stripSection(content) {
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+  if (startIdx === -1 || endIdx === -1) return content;
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + MARKER_END.length).trimStart();
+  return before + (after ? "\n\n" + after : "") + "\n";
+}
+
+function mergeInstructionFile(target) {
+  const destPath = getInstructionFile(target);
+  const sourcePath = getInstructionSource(target);
+
+  if (!existsSync(sourcePath)) return;
+
+  const sourceContent = readFileSync(sourcePath, "utf-8").trim();
+  const section = `${MARKER_START}\n${sourceContent}\n${MARKER_END}`;
+
+  if (existsSync(destPath)) {
+    let existing = readFileSync(destPath, "utf-8");
+    existing = stripSection(existing);
+    writeFileSync(destPath, existing.trimEnd() + "\n\n" + section + "\n");
+  } else {
+    writeFileSync(destPath, section + "\n");
+  }
+}
+
+function installSkills(target) {
+  const skillsDir = getSkillsDir(target);
+  const srcSkillsDir = join(ROOT, "skills");
+
+  for (const skill of SKILLS) {
+    const src = join(srcSkillsDir, skill);
+    const dest = join(skillsDir, skill);
+
+    if (!existsSync(src)) {
+      console.log(`  Skipping ${skill} (not found in plugin)`);
+      continue;
+    }
+
+    // Copy skill files
+    mkdirSync(dest, { recursive: true });
+    cpSync(src, dest, { recursive: true });
+
+    // For skills that reference phases/references, copy them locally
+    // so cross-skill references work without depending on sibling paths
+    if (skill !== "ideabox" && skill !== "profile") {
+      const ideasRefs = join(srcSkillsDir, "ideabox", "references");
+      const ideasPhases = join(srcSkillsDir, "ideabox", "phases");
+      if (existsSync(ideasRefs)) {
+        const destRefs = join(dest, "references");
+        mkdirSync(destRefs, { recursive: true });
+        cpSync(ideasRefs, destRefs, { recursive: true });
+      }
+      if (existsSync(ideasPhases)) {
+        const destPhases = join(dest, "phases");
+        mkdirSync(destPhases, { recursive: true });
+        cpSync(ideasPhases, destPhases, { recursive: true });
+      }
+    }
+
+    console.log(`  Installed ${skill}`);
+  }
+}
+
+function ensureDataDir() {
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { recursive: true });
+    console.log(`  Created ${DATA_DIR}`);
+  }
+}
+
+function install(targets) {
+  console.log("\nIdeaBox -- Installing...\n");
+  ensureDataDir();
+
+  for (const target of targets) {
+    console.log(`Target: ${target}`);
+    installSkills(target);
+    mergeInstructionFile(target);
+    console.log(`  Merged instruction file for ${target}`);
+  }
+
+  console.log("\nDone! Run /ideabox to get started.\n");
+}
+
+function uninstall(targets) {
+  console.log("\nIdeaBox -- Uninstalling...\n");
+
+  for (const target of targets) {
+    const skillsDir = getSkillsDir(target);
+
+    for (const skill of SKILLS) {
+      const dest = join(skillsDir, skill);
+      if (existsSync(dest)) {
+        rmSync(dest, { recursive: true });
+        console.log(`  Removed ${skill}`);
+      }
+    }
+
+    const instrPath = getInstructionFile(target);
+    if (existsSync(instrPath)) {
+      const content = readFileSync(instrPath, "utf-8");
+      if (content.includes(MARKER_START)) {
+        writeFileSync(instrPath, stripSection(content));
+        console.log(`  Cleaned instruction file for ${target}`);
+      }
+    }
+  }
+
+  console.log(`\nNote: ${DATA_DIR} was kept. Delete it manually if you want to remove all data.\n`);
+}
+
+function doctor() {
+  console.log("\nIdeaBox -- Health Check\n");
+  let ok = true;
+
+  // Check 1: Node version
+  const nodeVersion = parseInt(process.version.slice(1));
+  if (nodeVersion >= 18) {
+    console.log(`  ✓ Node.js ${process.version}`);
+  } else {
+    console.log(`  ✗ Node.js ${process.version} (need >= 18)`);
+    ok = false;
+  }
+
+  // Check 2: Data directory
+  if (existsSync(DATA_DIR)) {
+    console.log(`  ✓ Data directory exists (${DATA_DIR})`);
+  } else {
+    console.log(`  ✗ Data directory missing (${DATA_DIR})`);
+    ok = false;
+  }
+
+  // Check 3: Profile
+  const profilePath = join(DATA_DIR, "profile.json");
+  if (existsSync(profilePath)) {
+    console.log(`  ✓ Profile configured`);
+  } else {
+    console.log(`  ○ No profile yet (will be created on first /ideas run)`);
+  }
+
+  // Check 4: Skills installed (check both Claude and Codex paths)
+  const claudeSkills = join(process.cwd(), ".claude", "skills");
+  const codexSkills = join(HOME, ".codex", "skills");
+  const claudeInstalled = SKILLS.filter((s) => existsSync(join(claudeSkills, s)));
+  const codexInstalled = SKILLS.filter((s) => existsSync(join(codexSkills, s)));
+  const installed = claudeInstalled.length >= codexInstalled.length ? claudeInstalled : codexInstalled;
+  const installTarget = claudeInstalled.length >= codexInstalled.length ? "Claude" : "Codex";
+  if (installed.length === SKILLS.length) {
+    console.log(`  ✓ All ${SKILLS.length} skills installed (${installTarget})`);
+  } else if (installed.length > 0) {
+    console.log(`  △ ${installed.length}/${SKILLS.length} skills installed (${installed.join(", ")})`);
+  } else {
+    console.log(`  ✗ No skills installed in current project`);
+    ok = false;
+  }
+
+  // Check 5: Claude Code / Codex available
+  if (hasCommand("claude")) {
+    console.log(`  ✓ Claude Code CLI detected`);
+  } else if (hasCommand("codex")) {
+    console.log(`  ✓ Codex CLI detected`);
+  } else {
+    console.log(`  ○ No supported CLI found (optional)`);
+  }
+
+  console.log(ok ? "\n  All checks passed!\n" : "\n  Some issues found.\n");
+}
+
+// --- Main ---
+function parseTargets(args) {
+  const explicit = args.slice(1).filter((a) => !a.startsWith("-") && a !== "--");
+  return explicit.length > 0 ? explicit : autoDetect();
+}
+
+const args = process.argv.slice(2);
+const command = args[0] || "init";
+
+switch (command) {
+  case "init":
+    install(parseTargets(args));
+    break;
+  case "uninstall":
+    uninstall(parseTargets(args));
+    break;
+  case "doctor":
+    doctor();
+    break;
+  default:
+    console.log(`Unknown command: ${command}`);
+    console.log("Usage: ideabox-agent [init|uninstall|doctor]");
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ideabox",
+  "version": "1.0.0",
+  "description": "Data-driven project idea engine for coding agents. Research, brainstorm, plan, and build — all from one command.",
+  "type": "module",
+  "bin": {
+    "ideabox": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "keywords": [
+    "ideabox",
+    "ideas",
+    "project-ideas",
+    "claude-code",
+    "codex-cli"
+  ],
+  "author": "Pawan Paudel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pawanpaudel93/ideabox.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "bumpp": "^10.4.1"
+  },
+  "scripts": {
+    "version": "node --input-type=commonjs -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('.claude-plugin/plugin.json'));p.version=require('./package.json').version;fs.writeFileSync('.claude-plugin/plugin.json',JSON.stringify(p,null,2)+'\\n');\"",
+    "release": "bumpp && pnpm publish"
+  }
+}

package/skills/backlog/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: backlog
+description: >
+  View your IdeaBox idea backlog — saved, dismissed, planned, and built ideas.
+  Use when asked to "show ideas", "idea backlog", "saved ideas", "what ideas do I have",
+  "ideabox backlog", or "list ideas".
+---
+
+# IdeaBox Backlog
+
+Display and manage the user's idea history from `~/.ideabox/ideas.jsonl`.
+
+## Reading the Backlog
+
+Read `~/.ideabox/ideas.jsonl`. Each line is a JSON object. There are two record types:
+- **Idea records:** have fields `id`, `title`, `problem`, `scores`, `status`, `evidence`, `monetization`, `tech_stack`, `complexity`
+- **Status update records:** have `type: "status_update"`, `idea_id`, `old_status`, `new_status`, `timestamp`
+
+To get the current status of an idea: find the latest `status_update` for that `idea_id`. If no status_update exists, use the idea record's `status` field.
+
+Parse arguments from the user's command:
+- `/ideas backlog` — show all ideas grouped by status
+- `/ideas backlog saved` — show only saved ideas
+- `/ideas backlog dismissed` — show only dismissed ideas
+- `/ideas backlog built` — show only built ideas
+
+## Display Format
+
+### If ideas.jsonl does not exist or is empty
+"No ideas in your backlog yet. Run `/ideas` to research your first batch!"
+
+### If ideas exist
+
+Group by current status and display:
+
+```
+## IdeaBox Backlog
+
+### Saved (ready to build)
+| # | Idea | Score | Monetization | Added |
+|---|------|-------|-------------|-------|
+| 1 | MCP Server Testing Framework | 48/60 | Freemium $29/mo | Mar 26 |
+
+### Planned (in progress)
+| # | Idea | Score | Status | Started |
+|---|------|-------|--------|---------|
+
+### Built
+| # | Idea | Score | Shipped |
+|---|------|-------|---------|
+
+### Dismissed
+Showing {count} dismissed ideas. Use `/ideas backlog dismissed` for details.
+```
+
+## Actions
+
+After displaying, offer:
+- "Pick a number to brainstorm and build that idea"
+- "Or run `/ideas` for fresh research"
+
+If the user picks a saved idea by number:
+1. Read the full idea record from `ideas.jsonl`
+2. Present the complete idea card (problem, evidence, monetization, tech stack, score)
+3. Ask "Ready to brainstorm this one?"
+4. If yes:
+   a. Append a status update to `~/.ideabox/ideas.jsonl`:
+      ```json
+      {"type":"status_update","idea_id":"{id}","old_status":"saved","new_status":"planned","timestamp":"{ISO}"}
+      ```
+   b. Create `.ideabox/` and `.ideabox/session/` directories if they don't exist
+   c. Initialize `.ideabox/state.json`:
+      ```json
+      {
+        "session_id": "sess_YYYYMMDD_HHMMSS",
+        "current_phase": "02-brainstorm",
+        "phases_completed": [],
+        "idea": {"id": "{id}", "title": "{title}", "problem": "{problem}"},
+        "artifacts": {},
+        "started_at": "{ISO}"
+      }
+      ```
+   d. Write the idea details to `.ideabox/session/01-research.md` (so phase 02 has context)
+   e. Read `${CLAUDE_SKILL_DIR}/phases/02-brainstorm.md` and follow it
+
+## Comparison Mode
+
+If the user says `/ideas backlog compare N M` (e.g., `compare 1 3`):
+
+1. Load both idea records from `ideas.jsonl`
+2. Present using the visual comparison format from `${CLAUDE_SKILL_DIR}/references/scoring-rubric.md` (Head-to-Head section) — with score bars, evidence, and a recommendation
+3. Ask: "Build which one? (N / M / neither)"
+
+## Updating Idea Status
+
+To update an idea's status, append a NEW line to `~/.ideabox/ideas.jsonl`:
+```json
+{"type":"status_update","idea_id":"idea_20260326_001","old_status":"saved","new_status":"planned","timestamp":"2026-03-26T17:00:00Z"}
+```
+
+**Never modify existing lines.** Append-only. The latest status_update for an idea_id is the current status.

package/skills/ideabox/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: ideabox
+description: >
+  Full idea-to-code pipeline. Researches real market demand, presents data-backed project ideas,
+  then brainstorms, plans, builds, tests, polishes, and ships the one you pick — 9 phases, fully self-contained.
+  Use when asked to "give me ideas", "what should I build", "project ideas", "ideabox",
+  "find me something to build", "I need a project", "ideas", or "suggest a project".
+argument-hint: "[research|backlog|profile]"
+---
+
+# IdeaBox — Full Pipeline
+
+Research -> Present -> Pick -> Brainstorm -> Plan -> Build -> QA -> Polish -> Ship -> Post-Ship -> Learn
+
+## Subcommand Routing
+
+Check if the user passed a subcommand:
+- `/ideabox research` -> invoke `ideabox:research` skill
+- `/ideabox backlog` -> invoke `ideabox:backlog` skill
+- `/ideabox profile` -> invoke `ideabox:profile` skill
+- `/ideabox` (no subcommand) -> continue with pipeline below
+- `/ideabox [anything else]` -> respond: "Unknown subcommand. Available: `/ideabox`, `/ideabox research`, `/ideabox backlog`, `/ideabox profile`"
+
+## Pipeline State
+
+Check if `.ideabox/state.json` exists in the current project directory.
+
+**If state.json exists and `current_phase` is not null:**
+Ask: "You have an in-progress session (Phase: {current_phase}, Idea: {idea.title}). Resume or start fresh?"
+- Resume: read state, load the current phase file, continue from where you left off
+- Start fresh: delete `.ideabox/state.json` and `.ideabox/session/`, proceed as new
+
+**If no state.json or starting fresh:**
+1. Create `.ideabox/` and `.ideabox/session/` directories
+2. Add `.ideabox/` to the project's `.gitignore` if not already present (session state should not be committed)
+3. Check for existing artifacts (phase skipping):
+   - If `~/.ideabox/research/` has a file from today -> ask: "You already researched today. Use those results or research fresh?"
+   - If `.ideabox/session/02-brainstorm-spec.md` exists -> ask: "Found an existing spec. Resume from planning?"
+   - If `.ideabox/session/03-plan.md` exists -> ask: "Found an existing plan. Resume from building?"
+4. Initialize `.ideabox/state.json` with the appropriate starting phase:
+```json
+{
+  "session_id": "sess_YYYYMMDD_HHMMSS",
+  "current_phase": "01-research",
+  "phases_completed": [],
+  "idea": null,
+  "artifacts": {},
+  "started_at": "{ISO timestamp}"
+}
+```
+
+## Phase Execution
+
+For the current phase, read the corresponding phase file and follow it completely:
+
+| Phase | File to Read | Gate Condition |
+|-------|-------------|---------------|
+| 01-research | `phases/01-research.md` | >=3 ideas with >=3 evidence sources each |
+| 02-brainstorm | `phases/02-brainstorm.md` | Spec document written and user-approved |
+| 03-plan | `phases/03-plan.md` | Plan passes self-review (no placeholders) |
+| 04-build | `phases/04-build.md` | All tests pass, two-stage review complete |
+| 05-qa | `phases/05-qa.md` | Health score above threshold, no critical bugs |
+| 06-polish | `phases/06-polish.md` | Before/after evidence, no AI slop detected |
+| 07-ship | `phases/07-ship.md` | PR created, CI passes |
+| 08-post-ship | `phases/08-post-ship.md` | Canary passes or skipped |
+| 09-learn | `phases/09-learn.md` | Preferences updated |
+
+**Conditional loading (save tokens):**
+- Phase 06 (polish): If the project has no visual UI (library, API, backend-only), skip directly to phase 07 without reading the phase file
+- Phase 08 (post-ship): If no deployment URL exists and no documentation files exist, skip directly to phase 09
+
+**To execute a phase:**
+```
+Read `${CLAUDE_SKILL_DIR}/phases/{phase_file}` and follow it completely.
+```
+
+## Phase Transition Protocol
+
+After each phase completes and its gate condition is met:
+
+1. **Save artifact path** in state.json `artifacts` field
+2. **Move phase** to `phases_completed` array
+3. **Advance** `current_phase` to next phase
+4. **Write state** to `.ideabox/state.json`
+5. **Present summary** to user: "Phase {N} complete. {one-line summary of output}"
+6. **Ask at gate:** "Continue to {next phase name}? (yes / revise / skip remaining / abort)"
+   - **yes**: read next phase file and follow it
+   - **revise**: stay in current phase, user explains what to change
+   - **skip**: jump to phase 09 (learn) to save progress, then end
+   - **abort**: save state, end session (can resume later with `/ideas`)
+
+## Phase Rules
+
+- **Phases 01-04 are MANDATORY** (research, brainstorm, plan, build) — cannot be skipped
+- **Phases 05-08 can be skipped** if user says "skip" — for CLI tools without UI, skip polish; for unpublished tools, skip ship
+- **Phase 09 (learn) always runs** after any end point — tracks what happened for self-improvement
+
+## Context Management
+
+- **Re-read state** before every phase transition to prevent drift
+- **Each phase writes output** to `.ideabox/session/` (e.g., `01-research.md`, `02-brainstorm-spec.md`, `03-plan.md`, `05-qa-report.md`)
+- **Next phase reads** only its own instructions + the previous phase's output (not all phases)
+- **If context is running low:** save state to `.ideabox/state.json`, tell user: "Context getting full. Run `/ideas` in a new session to resume from phase {current_phase}."
+
+## Error Handling
+
+- **Phase gate fails:** stay in current phase, explain what's needed to pass
+- **User aborts:** save state, they resume later with `/ideas`
+- **Subagent fails:** note the failure, offer to retry or skip
+- **No profile:** run profile setup inline (don't tell user to run another command)