idea-forge

Collaborative idea refinement and multi-format document generation platform. Turn raw ideas into polished presentations, product specs, whitepapers, tutorials, research briefs, and more - with optional cross-agent review using Claude, Codex, and Gemini.

Overview

idea-forge is a skill-based platform for Claude Code that transforms vague ideas into structured, reviewed documents. The workflow:

1. research (optional) - investigate the topic, gather facts, verify claims
2. north-star-builder - create an immutable North Star guardrail that anchors all downstream work
3. idea-refiner - detect document type, create a plan, route to the right builder
4. Builder skill - generate the document from the approved plan
5. Cross-agent review (optional) - multi-model critique loop for quality assurance

Supported Document Types

Type	Builder Skill	Output Format	Typical Length
Presentation	presentation-planner -> presentation-builder	.pptx + .docx + .md	15-30 slides
Product Spec / PRD	product-spec-builder	Markdown (.md)	5-15 pages
Whitepaper	whitepaper-builder	Markdown (.md)	10-30 pages
One-Pager	one-pager-builder	Markdown (.md)	1 page (250-400 words)
Blog Post	blog-builder	Markdown (.md) with YAML frontmatter	800-2500 words
Tutorial / Demo	tutorial-builder	Markdown (.md) + demo repo	Varies
Technical Architecture	tech-arch-builder	Markdown (.md)	5-20 pages
HIP	hip-builder	Markdown (.md)	HIP format
Infrastructure (Lean)	infra-lean-builder	Markdown (.md)	3-10 pages
Infrastructure (Enterprise)	infra-cost-builder	Markdown (.md)	10-30 pages

Skills

Intake

Skill	Purpose
north-star-builder	Deep North Star with competitive research and iterative refinement
idea-refiner	Universal intake funnel - raw idea -> plan -> route to builder
research	Structured research briefs with verified facts and citations
brain-dump	Unstructured input (dumps, transcripts, notes) -> triaged idea inventory (ACT NOW/RESEARCH/PARK/KILL)
learn-and-improve	Ingest external sources, audit the meta-stack, produce improvement plans

Builders

Skill	Purpose
product-spec-builder	PRD with personas, user stories, architecture, metrics
whitepaper-builder	Strategic whitepapers with claim-evidence-analysis structure
one-pager-builder	Executive briefs optimized for 30-second reads
blog-builder	Blog posts with YAML frontmatter and SEO optimization
tech-arch-builder	Technical architecture docs with component design, API spec, ADRs
hip-builder	Hedera/Hiero Improvement Proposals with factual verification
tutorial-builder	Tutorials and code demos with working code and verification
hip-tutorial-builder	HIP-specific tutorial extension (research agents, mirror node patterns)
builder-foundation	Shared quality framework all builders inherit (scoring, refine loops, evaluator)

Presentations

Skill	Purpose
presentation-planner	Presentation planning with deep domain knowledge
presentation-builder	PPTX + DOCX + transcript generation
presentation-reskin	Rebuild PPTX using a template's visual patterns (Python)

Infrastructure

Skill	Purpose
infra-lean-builder	DEFAULT - small teams, managed services, free tiers
infra-cost-builder	Enterprise cost estimation (AWS/GCP/Azure)

Code Projects

Skill	Purpose
code-project-foundation	Language-agnostic build framework (8-layer cadence, exit-criteria split, retrospective contract)
python-package-builder	Python packages via uv/PyPI: ruff + mypy strict + pytest + commit-per-layer + CLI smoke gates
code-project-retrospective	Post-phase lessons capture + pattern promotion back into the foundation

Review

Cross-agent review (multi-model critique by Claude + Codex + Gemini) is provided as a global skill (~/.claude/skills/cross-agent-review/), not vendored here — see Cross-Agent Review below.

Quick Start

Prerequisites

• Claude Code CLI installed
• Node.js (for presentation generation)
• Optional: Codex CLI and/or Gemini CLI (for cross-agent review)

Install as a Claude Code Plugin

The repo doubles as a Claude Code plugin marketplace, so the skills can be installed into any project without cloning. In Claude Code, run /plugin marketplace add kpachhai/idea-forge and then /plugin install idea-forge@idea-forge.

All skills become available under the idea-forge: namespace (e.g. idea-forge:north-star-builder) and Claude invokes them automatically when a task matches a skill description. The plugin tracks the repo's main branch - /plugin update idea-forge pulls the latest commit. Note for plugin users: generated artifacts go in workspace/<project>/ relative to YOUR working directory; create it (gitignored) in the consuming project.

Usage

1. Start Claude Code in this directory
2. Describe your idea: "I want to write a blog post about..."
3. The north-star-builder skill creates a guardrail North Star
4. The idea-refiner skill creates a plan and routes to the appropriate builder
5. The builder skill generates your document
6. Optionally run cross-agent review for quality assurance

Presentation Generation

npm install                                      # Install dependencies (pptxgenjs, docx)
node workspace/<project>/generate-pptx.js        # Generate PPTX slide deck
node workspace/<project>/generate-docx.js        # Generate DOCX presenter reference

Project Structure

idea-forge/
├── skills/
│   ├── intake/                        # Entry points
│   │   ├── idea-refiner/
│   │   ├── north-star-builder/
│   │   └── research/
│   ├── builders/                      # Document generators
│   │   ├── product-spec-builder/
│   │   ├── whitepaper-builder/
│   │   ├── one-pager-builder/
│   │   ├── blog-builder/
│   │   ├── tech-arch-builder/
│   │   ├── hip-builder/
│   │   └── tutorial-builder/
│   ├── presentations/                 # Presentation pipeline
│   │   ├── presentation-planner/
│   │   ├── presentation-builder/
│   │   └── presentation-reskin/
│   └── infrastructure/                # Infra planning
│       ├── infra-lean-builder/
│       └── infra-cost-builder/
├── scripts/                           # Reference generation scripts
├── references/                        # Example plans and templates
└── workspace/                         # Active projects (gitignored)

Cross-Agent Review

idea-forge supports a multi-model review loop where Claude, Codex, and Gemini each critique documents from their specialized perspective:

Model	Lens	Focus
Gemini	Logic & Reasoning	Logical consistency, missing edge cases, argument coherence
Claude	Architecture & Design	Structure, maintainability, design quality
Codex	Coverage & Verification	Fact-checking, URL validation, code correctness

Cross-agent review is optional and user-controlled. It runs for both planning and deliverable phases.

Cross-Agent Review Config

The global cross-agent-review skill resolves its reviewer panel from a machine-local config — a convention shared by schema only (no cross-repo code or paths):

~/.config/cross-agent-review/config.json      # machine-local roster (gitignored)

With no config, review runs Claude-only multi-subagent (always available). Add Codex/Gemini by flipping a model's enabled and ensuring its CLI is installed. Preflight reachability with ~/.claude/scripts/cross-agent-review-config.sh --doctor (pass --config PATH for a non-default config).

Field	Meaning
defaults.timeout_seconds / claude_subagent_count	Per-model timeout default; Claude-only reviewer count.
models[].id	claude is always present and always the orchestrator.
models[].mode	subagent (in-process Claude reviewers) or cli (external process).
models[].enabled	Toggle into/out of the panel without deleting the entry.
models[].count + lenses	(subagent) reviewer count + review lenses.
models[].command + lens + timeout_seconds	(cli) command template ({prompt} or stdin), focus lens, timeout.

Workspace Conventions

Each project in workspace/ follows a consistent structure:

• north-star.md - immutable guardrail (always present)
• <slug>-research.md - research brief (if applicable)
• <slug>-plan-v<N>.md - document plan (versioned, keep only latest)
• <slug>-<type>-v<N>.md - document output (versioned, keep only latest)
• demo-repo/ - tutorial/demo code (if applicable)

See CLAUDE.md for full workspace naming conventions.

Dependencies

• pptxgenjs - PowerPoint generation
• docx - Word document generation

License

ISC