ideabox 1.0.0

package/skills/ideabox/phases/04-build.md

@@ -0,0 +1,213 @@
+# Phase 04: Build
+
+Execute the implementation plan using subagent-driven development with TDD discipline.
+
+## Prerequisites
+
+Read `.ideabox/session/03-plan.md` for the approved implementation plan.
+
+## Iron Laws
+
+```
+1. NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+2. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+3. NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+## Step 1: Setup Workspace
+
+If building a new project:
+1. Create the project directory
+2. Initialize git repo
+3. Install dependencies
+4. Verify the environment works (run a hello-world or initial test)
+
+If adding to existing project:
+1. Create a feature branch
+2. Verify existing tests pass before making changes
+
+## Step 2: Execute Plan — Subagent-Driven
+
+**Parallelization:** For independent tasks (no shared files or dependencies), dispatch multiple implementer subagents in parallel. This significantly speeds up plans with 5+ independent tasks. Only serialize tasks that modify the same files or depend on each other's output.
+
+For each task in the plan:
+
+### 2a: Dispatch Implementer Subagent
+
+Use the Agent tool to dispatch a fresh subagent with:
+- Full task text (pasted, never make subagent read plan file)
+- Context about where this task fits in the overall project
+- Instructions to follow TDD: write failing test first, verify it fails, implement, verify it passes, commit
+
+**Implementer instructions to include:**
+- "Follow TDD strictly: write the failing test FIRST. Run it. See it fail. Then implement. Run again. See it pass."
+- "Commit after each task with a descriptive message."
+- "If you're stuck, report NEEDS_CONTEXT or BLOCKED — don't guess."
+- Self-review checklist: Completeness, Quality, Testing, Discipline
+- Report format: Status (DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT), files changed, tests added, issues
+
+### 2b: Handle Implementer Response
+
+- **DONE:** Proceed to spec review
+- **DONE_WITH_CONCERNS:** Read concerns. If about correctness/scope, address before review. If observations, note and proceed.
+- **NEEDS_CONTEXT:** Provide missing info, re-dispatch
+- **BLOCKED:** Assess: context problem -> provide more context. Task too complex -> break it up. Plan wrong -> flag to user.
+
+### 2c: Dispatch Spec Compliance Reviewer
+
+After implementer reports DONE:
+
+"Review the implementation for spec compliance. Read the actual code that was written (don't trust the implementer's report). Compare implementation to these requirements line by line: {paste task requirements}. Check:
+- Every requirement is implemented
+- Nothing extra was added (no scope creep)
+- Types and interfaces match the plan
+Report: SPEC_COMPLIANT or ISSUES_FOUND with specific file:line references."
+
+**CRITICAL: Do not trust the implementer's report.** Verify everything independently.
+
+### 2d: Dispatch Code Quality Reviewer
+
+Only AFTER spec compliance passes:
+
+"Review the code quality of changes in the recent commits. Check:
+- Single responsibility per file
+- Well-defined interfaces
+- Code can be understood and tested independently
+- No unnecessary complexity
+- Tests are meaningful (not testing mock behavior)
+Report: Strengths, Issues (Critical/Important/Minor), Assessment (APPROVED or NEEDS_CHANGES)."
+
+**Never start quality review before spec compliance is approved.**
+
+### 2e: Fix Cycle
+
+If either reviewer finds issues:
+1. Dispatch the implementer to fix specific issues
+2. Re-dispatch the relevant reviewer
+3. Repeat until approved
+4. Mark task complete
+
+## Step 3: TDD Discipline
+
+For every piece of code written during this phase:
+
+### RED — Write One Minimal Test
+- Tests one behavior
+- Clear name describing what should happen
+- Uses real code (no mocks unless unavoidable)
+
+### Verify RED (MANDATORY)
+- Test fails (not errors — fails)
+- Failure message is the expected one
+- Fails because feature is missing, not because of typos
+
+### GREEN — Write Simplest Code to Pass
+- Don't add features beyond what the test requires
+- Don't refactor yet
+- Don't "improve" surrounding code
+
+### Verify GREEN (MANDATORY)
+- New test passes
+- All other tests still pass
+- No errors or warnings in output
+
+### REFACTOR — Only After Green
+- Remove duplication
+- Improve names
+- Extract helpers
+- Keep all tests green
+
+### Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests-after proves nothing about design. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "TDD will slow me down" | TDD is faster than debugging. |
+| "Existing code has no tests" | You're improving it. Add tests. |
+
+## Step 4: Debugging Protocol
+
+When tests fail unexpectedly:
+
+1. **Read error messages carefully** — don't skip, read completely
+2. **Reproduce consistently** — exact steps, every time?
+3. **Check recent changes** — git diff, what changed?
+4. **Trace data flow** — where does the bad value originate? Keep tracing up.
+5. **Form single hypothesis** — "I think X because Y"
+6. **Test minimally** — smallest possible change, one variable at a time
+7. **If fix doesn't work** — form NEW hypothesis, don't pile fixes
+
+**After 3+ failed fixes: STOP.** Question the architecture. The pattern of each fix revealing new problems means the approach is wrong. Discuss with user before attempting more fixes.
+
+## Step 5: Acceptance Criteria Verification (Ralph Pattern)
+
+After all plan tasks are executed, verify against acceptance criteria from the brainstorm spec:
+
+1. Read `.ideabox/session/02-brainstorm-spec.md` — extract the Success Criteria section
+2. Convert each criterion into a testable check
+3. For each criterion:
+   - Run the verification (test command, manual check, or inspection)
+   - Record: PASS or FAIL with evidence
+   - If FAIL: fix the issue, re-verify, commit atomically
+4. **Only mark build as complete when ALL criteria pass**
+
+```
+## Acceptance Criteria Verification
+
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | {criterion from spec} | PASS/FAIL | {test output or observation} |
+| 2 | {criterion from spec} | PASS/FAIL | {evidence} |
+...
+
+**Result:** X/Y criteria passing
+```
+
+**Non-negotiable:** Never declare "build complete" with failing acceptance criteria. Fix or escalate.
+
+## Step 6: Verify All Tasks Complete
+
+After all plan tasks are executed AND acceptance criteria pass:
+
+1. Run the full test suite — verify ALL tests pass
+2. Run linter/typecheck if configured — verify clean
+3. Count: tasks planned vs tasks completed
+4. Review git log — verify all tasks have commits
+
+**Evidence before claims:** Run the command, read the output, THEN claim it passes. Never say "should work" or "probably passes."
+
+## Step 7: Write Build Handoff
+
+Save a structured handoff to `.ideabox/session/04-handoff.md`:
+
+```markdown
+# Phase 04 Handoff: Build -> QA
+
+## What Was Built
+- [list of components/features implemented]
+
+## Acceptance Criteria Status
+- X/Y criteria passing
+
+## Known Issues
+- [any issues discovered during build that need QA attention]
+
+## Test Coverage
+- [number of tests, what they cover]
+
+## Architecture Decisions Made During Build
+- [any decisions that deviated from the plan, with reasoning]
+```
+
+## Step 8: Update State
+
+Update `.ideabox/state.json`:
+- Add "04-build" to `phases_completed`
+- Set `current_phase` to "05-qa"
+- Set `artifacts.build` to the project directory path
+
+## Gate Condition
+
+Phase 04 passes when: all plan tasks are complete, all tests pass (with evidence — show the test output), and two-stage review (spec + quality) is complete for every task.

package/skills/ideabox/phases/05-qa.md

@@ -0,0 +1,135 @@
+# Phase 05: QA
+
+Systematic testing and bug-fixing. Test like a real user, find bugs, fix them with atomic commits, re-verify.
+
+## Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## Step 1: Run Test Suite
+
+Run the project's full test suite. Record exact output.
+
+- **All pass:** Note pass count and continue to user-facing QA
+- **Failures:** Fix each failure before proceeding. For each fix:
+  1. Identify root cause (don't guess)
+  2. Fix the actual issue (not the symptom)
+  3. Run tests again — verify fix with evidence
+  4. Commit atomically: `git commit -m "fix: [specific description]"`
+
+## Step 2: User-Facing QA (if applicable)
+
+For projects with a UI or CLI interface:
+
+### 2a: Test Core User Flows
+Walk through every major user flow as a real user would:
+- Happy path (normal usage)
+- Error cases (bad input, missing data, network failures)
+- Edge cases (empty states, max values, special characters)
+
+### 2b: Per-Page/Screen Checklist (for web/mobile)
+For each page or screen, check:
+
+| Category | Check |
+|----------|-------|
+| **Console** | Zero errors in browser/terminal console |
+| **Links** | All links resolve (no 404s, no dead links) |
+| **Visual** | Layout correct, no overlapping elements, responsive |
+| **Functional** | All buttons/forms/interactions work correctly |
+| **UX** | Loading states, error messages, empty states handled |
+| **Performance** | Page loads in <3 seconds, no jank |
+| **Content** | No placeholder text, no lorem ipsum, no "TODO" |
+| **Accessibility** | Color contrast OK, keyboard navigation works, alt text present |
+
+### 2c: CLI Verification (for CLI tools)
+- `--help` shows correct usage
+- All commands work with valid input
+- Error messages are clear for invalid input
+- Exit codes are correct (0 for success, non-zero for errors)
+
+## Step 3: Health Score
+
+Compute a health score (0-100) based on findings:
+
+| Category | Weight |
+|----------|--------|
+| Console errors | 15% |
+| Broken links | 10% |
+| Visual issues | 10% |
+| Functional bugs | 20% |
+| UX problems | 15% |
+| Performance | 10% |
+| Content issues | 5% |
+| Accessibility | 15% |
+
+**Scoring per category:**
+- 0 issues: 100
+- 1-3 issues: 70
+- 4-10 issues: 40
+- 10+ issues: 10
+
+**Severity deductions from base score:**
+- Critical bug: -25
+- High: -15
+- Medium: -8
+- Low: -3
+
+## Step 4: Fix-Verify Loop
+
+For each bug found (prioritized by severity — critical first):
+
+1. **Locate source** — find the root cause in the code
+2. **Fix** — make the minimal change needed
+3. **Commit atomically** — `git commit -m "fix: [specific bug description]"`
+4. **Re-verify** — run the specific test or check to confirm the fix
+
+**Rules:**
+- One fix per commit (atomic)
+- Always re-verify after fixing (don't trust that it works — check)
+- Depth over breadth: 5 well-fixed bugs > 20 half-fixed bugs
+
+## Step 5: Verification Gate
+
+Before claiming QA is complete:
+
+1. **Run full test suite** — show output, count pass/fail
+2. **Health score** — compute and present
+3. **Remaining issues** — list any unfixed issues with severity
+
+**Verification evidence format:**
+```
+## QA Results
+
+**Test suite:** X/X passing (command output below)
+**Health score:** XX/100
+**Bugs found:** X total (X fixed, X remaining)
+**Critical/High remaining:** X
+
+[paste actual test output]
+```
+
+## Step 6: Update State
+
+Update `.ideabox/state.json`:
+- Add "05-qa" to `phases_completed`
+- Set `current_phase` to "06-polish"
+- Set `artifacts.qa` to `.ideabox/session/05-qa-report.md`
+
+Write QA report to `.ideabox/session/05-qa-report.md`.
+
+## Gate Condition
+
+Phase 05 passes when: health score >= 70, zero critical bugs remaining, all tests pass (with evidence — show the output).
+
+## Verification Rationalization Prevention
+
+| Claim | Requires | NOT Sufficient |
+|-------|----------|----------------|
+| "Tests pass" | Test command output: 0 failures | Previous run, "should pass" |
+| "Bug fixed" | Re-test shows fix works | "Code changed" |
+| "QA complete" | Health score computed | "Looked good" |
+| "No issues" | Systematic check completed | "Didn't notice any" |

package/skills/ideabox/phases/06-polish.md

@@ -0,0 +1,111 @@
+# Phase 06: Polish
+
+Visual QA and design refinement. Find and fix visual inconsistencies, spacing issues, AI slop patterns, and interaction problems.
+
+**Skip this phase if:** the project has no visual UI (libraries, APIs, backend services without a frontend).
+
+**For CLI tools:** This phase still applies — polish help text formatting, output alignment, error message clarity, progress indicators, and color usage. Skip the visual/responsive sections but apply interaction and content checks.
+
+## Step 1: First Impression
+
+Before detailed analysis, capture your gut reaction:
+- "The site/app communicates..."
+- "I notice..."
+- "First 3 things my eye goes to..."
+- "One word description..."
+
+## Step 2: AI Slop Detection
+
+Check for these 10 anti-patterns that scream "AI-generated":
+
+1. Purple gradients on white backgrounds
+2. 3-column feature grid with icon-in-colored-circle
+3. Centered everything (no visual hierarchy)
+4. Uniform border-radius on all elements
+5. Decorative blobs/shapes that serve no purpose
+6. Emoji used as design elements (use SVG icons instead)
+7. Colored left-border cards
+8. Generic hero copy ("Transform your workflow...")
+9. Cookie-cutter rhythm (same section pattern repeated)
+10. Overused fonts (Inter, Roboto, Arial for everything)
+
+If 3+ anti-patterns found, flag "AI slop detected" and prioritize fixing.
+
+## Step 3: Design Audit
+
+Check in priority order:
+
+### Priority 1: Accessibility (CRITICAL)
+- Color contrast >= 4.5:1 for normal text, >= 3:1 for large text
+- All interactive elements have focus states (focus-visible)
+- Alt text on images
+- Keyboard navigation works
+- Form labels present
+- Color is not the sole indicator of state
+
+### Priority 2: Touch & Interaction
+- Touch targets >= 44x44px
+- All clickable elements have `cursor-pointer`
+- Hover states exist and provide feedback
+- Loading states for async operations
+- Error messages are specific and helpful
+- Disabled states are visually distinct
+
+### Priority 3: Layout & Responsive
+- No horizontal scroll at any viewport
+- Min 16px body text on mobile
+- Consistent max-width across sections
+- Responsive at key breakpoints (375, 768, 1024, 1440px)
+- Images are responsive (srcset or max-width: 100%)
+
+### Priority 4: Typography & Color
+- Max 3 font families
+- Consistent heading hierarchy (h1 > h2 > h3)
+- Line height 1.4-1.6 for body text
+- Line length 45-75 characters for readability
+- Cohesive color palette (max 12 colors)
+
+### Priority 5: Motion & Animation
+- Transitions 150-300ms
+- Meaningful easing (not linear)
+- `prefers-reduced-motion` respected
+- No `transition: all` (specify properties)
+
+## Step 4: Atomic Fix-Verify Loop
+
+For each issue found (prioritized — accessibility first):
+
+1. **Fix one issue** in the source code
+2. **Take before/after evidence** (screenshots if available, or describe the change)
+3. **Commit atomically** — `git commit -m "polish: [specific fix]"`
+4. **Move to next issue**
+
+Rules:
+- One fix per commit
+- Fix from highest priority category down
+- Don't fix everything — focus on impact
+- 5-10 well-executed fixes > 20 rushed ones
+
+## Step 5: Professional UI Rules
+
+Apply these finishing touches:
+- No emoji icons — use SVG icons (Heroicons, Lucide)
+- Consistent spacing scale (4px/8px base)
+- Z-index scale (10, 20, 30, 50 — not random values)
+- Transitions on interactive elements
+- Consistent border-radius hierarchy
+
+## Step 6: Write Polish Report
+
+Save a summary of fixes to `.ideabox/session/06-polish-report.md`: issues found, fixes applied, before/after descriptions.
+
+## Step 7: Update State
+
+Update `.ideabox/state.json`:
+- Add "06-polish" to `phases_completed`
+- Set `current_phase` to "07-ship"
+- Set `artifacts.polish` to `.ideabox/session/06-polish-report.md`
+
+## Gate Condition
+
+Phase 06 passes when: no AI slop detected (or fixed), accessibility basics met, before/after evidence shows improvement.

package/skills/ideabox/phases/07-ship.md

@@ -0,0 +1,119 @@
+# Phase 07: Ship
+
+Create PR, bump version, update changelog, and prepare for deployment.
+
+## Step 1: Pre-Flight
+
+1. **Check branch:** Verify you're NOT on main/master
+2. **Git status:** Check for uncommitted changes — commit or stash before proceeding
+3. **Diff stats:** `git diff --stat origin/main...HEAD` — review what's being shipped
+
+## Step 2: Merge Base Branch
+
+Ensure you're up to date with the base branch:
+```bash
+git fetch origin main && git merge origin/main --no-edit
+```
+If merge conflicts: resolve them, run tests, commit.
+
+## Step 3: Run Tests
+
+Run the full test suite one final time. ALL tests must pass.
+
+**If tests fail:** Fix failures before shipping. Do not ship with failing tests.
+**Evidence required:** Show the test command output with pass count.
+
+## Step 4: Pre-Merge Review
+
+Two-pass review of the diff:
+
+### Pass 1 — Critical (must fix before shipping)
+- **SQL & Data Safety:** Any raw SQL? Missing parameterization?
+- **Race Conditions:** Shared mutable state? Missing locks?
+- **Secret Exposure:** Any hardcoded keys, tokens, passwords?
+- **Enum Completeness:** Switch statements missing cases?
+
+### Pass 2 — Informational (fix if quick, note otherwise)
+- **Magic Numbers:** Unexplained constants?
+- **Dead Code:** Unreachable code, unused imports?
+- **Test Gaps:** New features without tests?
+- **Performance:** O(n^2) loops, missing indexes, large payloads?
+
+**Rule:** Never say "probably handled elsewhere" — cite the specific line or flag as unverified.
+
+## Step 5: Version Bump
+
+Determine version bump type:
+- **MICRO/PATCH** (auto-pick): bug fixes, minor improvements — no user-facing behavior change
+- **MINOR** (ask user): new features, new commands — backwards compatible
+- **MAJOR** (ask user): breaking changes — not backwards compatible
+
+If `package.json` exists, bump the version. If `plugin.json` exists, sync it.
+
+## Step 6: Changelog
+
+Generate/update CHANGELOG.md from the diff:
+
+- Lead with **what the user can now DO** (not technical changes)
+- Group by: Added, Changed, Fixed, Removed
+- One line per change, linking to relevant files
+
+Example:
+```markdown
+## [1.1.0] - 2026-03-26
+
+### Added
+- Research phase now pulls from 6 data sources in parallel
+- Self-improving recommendation system learns your preferences
+```
+
+## Step 7: Commit & Push
+
+Stage specific files (never use `git add -A` — it can stage sensitive files like .env or credentials):
+
+```bash
+git add package.json CHANGELOG.md [other changed files by name]
+git commit -m "chore: bump version to X.Y.Z and update changelog"
+git push -u origin HEAD
+```
+
+**Before staging:** Verify no `.env`, credentials, or secret files are in the diff. If found, warn the user.
+
+## Step 8: Create PR
+
+Create a structured pull request:
+
+```bash
+gh pr create --title "[short descriptive title]" --body "$(cat <<'EOF'
+## Summary
+- [bullet points of what this PR does]
+
+## Test Plan
+- [ ] All tests pass
+- [ ] Manual testing completed
+- [ ] No console errors
+
+## Review Checklist
+- [ ] No hardcoded secrets
+- [ ] No breaking changes (or documented)
+- [ ] Tests cover new functionality
+EOF
+)"
+```
+
+## Step 9: Update State
+
+Update `.ideabox/state.json`:
+- Add "07-ship" to `phases_completed`
+- Set `current_phase` to "08-post-ship"
+- Set `artifacts.ship` to the PR URL
+
+## Gate Condition
+
+Phase 07 passes when: PR created, all tests pass (with evidence), version bumped, changelog updated.
+
+## Shipping Rules
+
+**Never stop for:** uncommitted changes (just commit them), PATCH version bump, changelog content, commit message wording.
+
+**Always stop for:** merge conflicts, test failures, critical review findings, MINOR/MAJOR version bumps.

package/skills/ideabox/phases/08-post-ship.md

@@ -0,0 +1,83 @@
+# Phase 08: Post-Ship
+
+Post-deployment verification and documentation sync.
+
+**Skip canary if:** no deployment URL exists (local-only tool, library, CLI tool without hosting).
+**Skip docs sync if:** no documentation files exist beyond README.
+
+## Step 1: Canary Health Check (if deployed)
+
+If the project has a deployment URL:
+
+1. **Visit the URL** — verify it loads
+2. **Check console** — zero new errors (compare to pre-deploy baseline if available)
+3. **Test core flow** — walk through the primary user flow
+4. **Check performance** — page loads in <3 seconds
+
+**Alert levels:**
+- CRITICAL: page doesn't load
+- HIGH: new console errors
+- MEDIUM: performance regression (noticeably slower)
+- LOW: minor visual issues
+
+**Verdict:** HEALTHY / DEGRADED / BROKEN
+
+If BROKEN: immediately flag to user, consider reverting.
+If DEGRADED: note issues, continue — they can be fixed in next iteration.
+
+## Step 2: Documentation Sync
+
+Cross-reference the git diff against all documentation files (.md files in the project):
+
+### Auto-Update (do without asking):
+- Fix factual inaccuracies (wrong paths, outdated counts, broken links)
+- Update file/directory references to match current structure
+- Mark completed TODOs as done
+- Fix cross-references between docs
+
+### Ask User (before changing):
+- Narrative changes (rewriting descriptions)
+- Removing sections
+- Significant rewrites
+
+### CHANGELOG Voice Polish
+Review CHANGELOG.md entries:
+- Lead with what the user can now DO
+- Use active voice
+- Be specific: "Add parallel research across 6 data sources" not "Update research module"
+
+### Cross-Doc Consistency
+- Feature lists match across README, CLAUDE.md, AGENTS.md?
+- Component lists accurate?
+- Installation instructions current?
+- Every doc reachable from README?
+
+## Step 3: Engineering Retrospective (Quick)
+
+Briefly note:
+- **What went well:** Which phases were smooth?
+- **What was hard:** Which phases took longest or had issues?
+- **What to improve:** For next time, what would you do differently?
+
+Save to `.ideabox/session/08-post-ship.md`.
+
+## Step 4: Commit Documentation Changes
+
+Stage only the documentation files that were changed (never use `git add -A`):
+
+```bash
+git add README.md CHANGELOG.md CLAUDE.md AGENTS.md [other changed .md files]
+git commit -m "docs: sync documentation with shipped changes"
+git push
+```
+
+## Step 5: Update State
+
+Update `.ideabox/state.json`:
+- Add "08-post-ship" to `phases_completed`
+- Set `current_phase` to "09-learn"
+- Set `artifacts.post_ship` to `.ideabox/session/08-post-ship.md`
+
+## Gate Condition
+
+Phase 08 passes when: canary passes (HEALTHY or DEGRADED) or was skipped, and docs are synced.