Before You Build
AI-assisted ideation that takes raw ideas through structured planning — market research, adaptive Q&A, risk review — and produces a planning suite adapted to project domain and complexity.
Forge: PreFlight is a Claude Code skill that guides you through a repeatable ideation process. It works for software, hardware, infrastructure, consulting, content — any project type. Run it, answer questions, walk away with everything you need to start building.
For software projects, 4 artifacts are GSD-compatible (PROJECT, REQUIREMENTS, ROADMAP, STATE). For non-software projects, PreFlight is the complete planning tool.
# Clone
git clone https://github.com/rbales79/forge-preflight.git
cd forge-preflight
# Install globally (all projects)
cp -rL dist/claude-code/preflight ~/.claude/skills/preflight
# Or install per-project
mkdir -p .claude/skills
cp -rL dist/claude-code/preflight .claude/skills/Restart Claude Code after installing. Use -rL to resolve symlinks from dist/ back to src/.
Start a new project:
let's ideate on <idea>
Resume an existing project:
preflight
Check project status:
list projects
PreFlight detects the .preflight/ workspace in the current directory, scans projects, and offers to resume or start new.
7 phases (0–6):
| Phase | What Happens |
|---|---|
| 0. Workspace Detection | Find or create .preflight/ workspace, scan existing projects |
| 1. Concept Capture | Listen to the idea, create project.yaml and PROJECT.md |
| 2. Market Research | Search for 3-5 commercial + 3-5 OSS competitors, identify gaps |
| 3. Domain Q&A | Adaptive questions from 7 domain prompts, complexity scoring, track recommendation |
| 4. Risk Review | Cross-reference decisions against market evidence, walk through risks |
| 5. Artifact Generation | Domain + complexity-adaptive artifact suite |
| 6. Validation | Cross-reference check, iterate on feedback, lock scope |
Every project gets 5 core artifacts, 0–3 complexity-gated artifacts, plus domain-specific extras:
Core (all projects):
| # | Artifact | GSD |
|---|---|---|
| 1 | PROJECT.md — what/why/who/done |
Yes |
| 2 | research/market-research.md — landscape + learnings |
|
| 3 | memory.md — session history, status, next steps |
|
| 4 | project.yaml — metadata (status, tier, category, tags) |
|
| 5 | transcripts/<date>.md — session record |
Complexity-gated (moderate+ or when earned):
| Artifact | When |
|---|---|
CHARTER.md |
Non-goals, success metrics, or stakeholder boundaries needed |
PRINCIPLES.md |
Project-specific principles emerged during Q&A |
risks-and-considerations.md |
Genuine risks identified in Phase 4 |
Domain-specific:
| Domain | Extra Artifacts | Total |
|---|---|---|
| Software | REQUIREMENTS (GSD), ROADMAP (GSD), STATE (GSD), ARCHITECTURE, epics-stories, implementation-plan | 11–14 |
| Hardware | SPECIFICATIONS, ROADMAP (GSD), DESIGN, work-packages | 9–12 |
| Content | BRIEF, OUTLINE, production-plan | 8–11 |
| Commercial | REQUIREMENTS, ROADMAP, engagement-model, pricing-and-packaging | 9–12 |
7 specialized question sets, loaded based on project type:
| Domain | Use When |
|---|---|
app |
Software applications, features, products, CLIs |
infrastructure |
Cloud, servers, networking, homelab, ops |
integration |
API integrations, data pipelines, webhooks |
tool-selection |
Build vs buy, vendor selection |
hardware-physical |
Drones, IoT, sensors, edge compute |
content-brand |
Content strategy, personal brand, marketing |
commercial-framework |
Consulting frameworks, pricing, GTM |
Domain prompts ship as defaults in .preflight/prompts/ and are fully editable per workspace.
Flagship: examples/vendor-intel/ — A CLI tool for comparing tech vendors using RAG. Moderate complexity, GSD track, 12 artifacts. Start here to see what the full process produces. The examples README walks through each artifact in reading order.
Secondary: examples/homelab-monitor/ — A Go TUI health monitor. Simple complexity, Lightweight track. Shows how the process scales down for simpler projects.
When PreFlight runs, it creates this in your project directory:
.preflight/ ← workspace config (editable)
├── config.yaml
├── PRINCIPLES.md ← your decision framework
└── prompts/ ← domain question sets (editable)
projects/
├── <project-name>/
│ ├── project.yaml ← metadata + status
│ └── planning/ ← all artifacts
│ ├── PROJECT.md, memory.md, ...
│ ├── research/
│ │ └── market-research.md
│ ├── transcripts/
│ │ └── <date>-<slug>.md
│ └── <domain + gated artifacts>
└── projects.md ← auto-generated manifest
concept → ideation → shipped
↘ archived
- concept — Idea captured, basic project.yaml
- ideation — Active planning through Q&A, research, artifact generation
- shipped — Planning complete, ready for its own implementation repo
- archived — Dropped, abandoned, or superseded (retained for reference)
forge-preflight/
├── src/ ← single source of truth
│ ├── SKILL.md ← core orchestration (Phases 0-6)
│ ├── defaults/ ← PRINCIPLES.md + 7 domain prompts
│ └── references/ ← artifact templates, complexity criteria, GSD format
├── dist/ ← platform packaging (symlinks to src/)
│ ├── claude-code/preflight/ ← Claude Code skill layout
│ └── cowork/ ← Cowork plugin layout
├── docs/ ← learning resources and guides
├── examples/ ← reference output
│ ├── vendor-intel/ ← flagship example (moderate, GSD track)
│ └── homelab-monitor/ ← secondary example (simple, lightweight)
├── planning/ ← PreFlight's own ideation artifacts
└── CLAUDE.md ← AI assistant context
Edit src/, never dist/ — dist symlinks back to src, so changes propagate automatically.
The workspace folder IS your data. Back up the workspace, restore the workspace. The skill code is separate and stateless — updating the skill never touches your projects.
PreFlight produces planning/ directories with 4 GSD-compatible artifacts (software projects only):
| PreFlight generates | GSD consumes |
|---|---|
| PROJECT.md | PROJECT.md |
| REQUIREMENTS.md | REQUIREMENTS.md |
| ROADMAP.md | ROADMAP.md |
| STATE.md | STATE.md |
PreFlight extras (CHARTER, ARCHITECTURE, epics, risks, market research) ride alongside — GSD ignores what it doesn't recognize.
Three-tier system — each layer inherits from the one above:
- Skill defaults (
src/defaults/PRINCIPLES.md) — opinionated starting point shipped with the skill - Workspace (
.preflight/PRINCIPLES.md) — copied from defaults on bootstrap, fully user-customizable - Per-project (
planning/PRINCIPLES.md) — overrides/extensions only, references workspace principles by default
New to AI-assisted planning? Start here:
| Doc | What | Time |
|---|---|---|
| Why Structure? | Why structured ideation beats "just build it" | 5 min read |
| Quickstart Prompt | A single prompt that works in any AI tool — no install needed | Copy and go |
| Learning Path | 3-tier progression from simple prompt to full PreFlight + GSD | Reference guide |
Version: 0.1.0 Stage: Shipped — actively in use, iterating
All phases (0–6) shipped. 4 synthetic end-to-end tests completed (homelab-monitor, devlog, mesh-network-lab, preflight-article). Programs and GSD handoff untested. See planning/STATE.md for current position.