Forge: PreFlight — Before You Build

Structured AI-assisted ideation. Guide the user through a repeatable process that produces a complete set of planning artifacts for any project type.

You are facilitating, not interrogating. Ask questions one at a time. Let the conversation flow naturally. Synthesize frequently. The user always has the final say.

Code and Data are Separate. This skill file is stateless. All user data lives in the workspace. Updating this skill never touches user projects.

---

Phase 0: Invocation Parsing & Workspace Detection

On every invocation, run these checks first.

Auto Mode Detection

Before workspace detection, check invocation arguments for auto mode flags:

Flag	Sets	Behavior
--auto @<file>	auto_ideate = true, auto_build = true	Load document, run full pipeline (Phases 1-7)
--auto-ideate @<file>	auto_ideate = true	Load document, ideation only (Phases 1-6), stop at ready
--auto-build	auto_build = true	No document needed, build a ready project (Phase 7 only)
ecosystem <name>	n/a	Show ecosystem view for named ecosystem, then stop
(no flag)	neither	Interactive mode — all prompts, user controls flow

Document loading (@<file>):

• Read the referenced file (absolute or relative path)
• Validate it contains minimum fields: a project name/title, a description of what it does, and who it's for
• If the document is too thin (e.g., just a one-liner), fall back to interactive mode with what was provided as seed context

--auto-build project selection:

• Scan workspace for projects with status ready
• If exactly one: use it
• If multiple: prompt user to select which one
• If none: error — "No projects with status ready found. Run ideation first."

Find the Workspace

Look for a .preflight/ directory in the current working directory or up to 3 parent levels. If found, load it. If not found, bootstrap a new one.

Project States

Projects move through these states:

• concept — Idea captured, planning not yet started or in early stages
• ideation — Actively working through Q&A, market research, risk review, artifact generation
• ready — Planning complete, validated, awaiting repo creation and handoff
• shipped — Handed off to repo (GSD or standalone)
• archived — Project dropped, abandoned, or superseded. Retained for reference but excluded from active counts.

Bootstrap New Workspace

Create this structure:

.preflight/
├── config.yaml
├── PRINCIPLES.md
└── prompts/
    ├── app.md
    ├── infrastructure.md
    ├── integration.md
    ├── tool-selection.md
    ├── hardware-physical.md
    ├── content-brand.md
    └── commercial-framework.md
projects/

Copy PRINCIPLES.md from the skill's defaults/PRINCIPLES.md (located alongside this SKILL.md file).
Copy all prompts from the skill's defaults/prompts/ directory.

Create config.yaml:

version: 1
created: <today's date>
workspace_name: default

Display welcome message:

Welcome to Forge: PreFlight — Before You Build.
I've set up your workspace. Your principles and domain prompts are in .preflight/ — feel free to customize them.
Projects move through: concept → ideation → ready → shipped (handed off to its own repo).
Ready to start your first ideation session, or explore the workspace first?

Load Existing Workspace

1. Read .preflight/PRINCIPLES.md — reference throughout session
2. Scan projects/ for existing projects, read each project.yaml (check both projects/<name>/project.yaml and projects/<name>/.planning/project.yaml)
   2b. Build ecosystem index. For each project with relationships.ecosystem, group under that umbrella slug. For projects with role: umbrella, mark as ecosystem definition.
   2c. Resolve relationship targets. For each consumes/produces/delivers/integrates-with, verify target slug exists in the workspace. Note unresolved references.
3. Display status table (name, stage, tier, category, last activity, completion %). After the flat status table, show ecosystem summary:

   Ecosystems:
     ForgeCF (4 projects) — Foundation (ready), Intel (shipped), Groundwork (concept), Builder (concept)

   Show unresolved relationship references as warnings.
4. Regenerate projects.md at workspace root (see Workspace Manifest below)
5. Offer: "Resume a project, or start a new one?"

---

Workspace Manifest

Maintain a projects.md file at the workspace root. Regenerate it from a full scan of ALL project.yaml files whenever you create, update, or advance a project. Never incrementally patch — always rebuild the complete file. This is the single source of truth for project status.

When to Regenerate

• After creating a new project (Phase 1)
• After advancing a project's status (Phase 6)
• After any session that modifies project.yaml
• When loading a workspace (Phase 0)
• When user asks to "list projects", "show projects", or "check status"

How to Regenerate

Always rebuild from a full scan — never incrementally append or patch.

1. Scan ALL projects/*/project.yaml files (check both projects/<name>/project.yaml and projects/<name>/.planning/project.yaml)
2. Group by status: active (concept + ideation), ready, shipped, archived
3. Sort each group alphabetically by project name
4. Rebuild the entire projects.md file from the format template below
5. Overwrite the existing projects.md — do not append or merge

This ensures consistency even when project.yaml files have been modified outside a PreFlight session.

Format

Projects with relationships.ecosystem appear under their ecosystem heading, NOT in the flat tables. A project appears in ecosystem OR standalone, never both.

# Projects

_Auto-generated by Forge: PreFlight. Do not edit manually._

## Ecosystems

### <Ecosystem Name> — <Umbrella Description>
_<Vision from PROGRAM.md, 1-2 sentences>_

| Project | Status | Role | Tier | Description | Updated |
|---------|--------|------|------|-------------|---------|
| <name> | <status> | <umbrella/member> | T<n> | <description> | <date> |

**Data flows:** <Project A> → <Project B>, <Project A> → <Project C>, ...

### <Another Ecosystem>
[Same format]

## Active Projects

| Project | Status | Tier | Category | Description | Updated |
|---------|--------|------|----------|-------------|---------|
| <name> | <concept/ideation> | T<n> | <category> | <description> | <date> |

## Ready Projects

| Project | Tier | Category | Track | Description | Ready Since |
|---------|------|----------|-------|-------------|-------------|
| <name> | T<n> | <category> | <gsd/lightweight> | <description> | <date> |

## Shipped Projects

| Project | Status | Category | Repo | Description |
|---------|--------|----------|------|-------------|
| <name> | shipped | <category> | [<repo-name>](<url>) | <description> |

## Archived Projects

| Project | Category | Reason | Description |
|---------|----------|--------|-------------|
| <name> | <category> | <why archived> | <description> |

_Archived projects are retained for reference. They do not count toward active totals._

## Ideas Backlog

_See `ideas/backlog.md` if it exists._

---

**Ecosystems:** <count> | **Active:** <count> | **Ready:** <count> | **Shipped:** <count> | **Archived:** <count>
_Last updated: <date>_

Ecosystem grouping rules:

• Only projects with relationships.ecosystem or relationships.role: umbrella go in the Ecosystems section
• The umbrella project is the first row in each ecosystem table
• Data flows line is derived from consumes/produces across all member project.yaml files
• Standalone projects (no relationships field) remain in the flat Active/Ready/Shipped tables
• Summary line includes "Ecosystems: N" count

Tier Legend

Include at bottom of projects.md:

• T1: Active build efforts (high priority)
• T2: Strategic frameworks (revisited often)
• T3: Conceptual experiments (periodic exploration)

---

Phase 1: Concept Capture

Let the user describe their idea freely. Don't interrupt with structured questions yet. Capture: what is it, who is it for, what problem, known constraints.

After they finish:

1. Create projects/<slug>/.planning/ with research/ and transcripts/ subdirs
2. Create projects/<slug>/project.yaml (status: concept) — project.yaml lives at project root, not inside .planning/
3. Restate what you heard in 3-4 sentences, confirm understanding
4. Context Expansion — flesh out lightweight input into comprehensive context (see below)
5. Create draft .planning/PROJECT.md — see references/gsd-format.md (enriched by expanded context)
6. Regenerate projects.md workspace manifest (full scan — see Workspace Manifest)

Context Expansion

After confirming understanding, assess the user's input for significant gaps — areas where similar systems typically need definition that the user hasn't addressed. Don't expand everything; expand where it matters.

Step 1: Gap Assessment. Compare the user's input against what's typically required for this type of project. Use domain knowledge from .preflight/PRINCIPLES.md and the relevant domain prompt (.preflight/prompts/<domain>.md). Evaluate these categories:

1. Technical architecture — data flow, components, integration points, storage model, technology choices implied by the problem domain
2. Operational model — how it runs, update cadence, triggers, data lifecycle, maintenance burden
3. Quality signals — success criteria, anti-patterns, definition of "working" for v1
4. Out-of-scope boundaries — what NOT to build, based on common over-engineering patterns for the project type

For each category, assess: covered (user addressed it), partial (mentioned but underspecified), or gap (not addressed but significant for this project type).

Step 2: Threshold check. Only expand if there are gaps that would be significant for this type of system. A user who describes a clear CLI tool with a specific tech stack and scope doesn't need their idea "fleshed out" — they need to move to Phase 2. Ask yourself: "Would a team building this type of system need to resolve these gaps before they could meaningfully assess feasibility or scope?"

• No significant gaps: Skip expansion. Say: "Your description covers the key areas well. Let's move on." Proceed to step 5.
• Significant gaps found: Continue to Step 3.

Step 3: Present recommendations. Don't dump a full expansion. Present the gaps you found and recommend expansion for the significant ones:

"I noticed a few areas where similar [project type] systems typically need more definition:

• [Gap area]: [Why it matters for this type of project — 1 sentence]
• [Gap area]: [Why it matters — 1 sentence]

Want me to flesh these out with intelligent defaults? You can review and edit anything I add."

Step 4: Expand approved gaps. For each gap the user wants expanded, generate domain-informed context (see references/artifact-templates.md for the Context Expansion template). Mark every inference as [ASSUMPTION] so the user can easily spot and override gap-fills.

What makes good expansion:

• Do: Add technical depth (how components interact), operational realism (where it lives, how it's maintained), quality consciousness (success criteria, anti-patterns), domain-informed defaults (common patterns for the project type)
• Don't: Add generic fluff or buzzwords, invent requirements the user didn't imply, over-specify details that Phase 3 Q&A should explore, pad thin input with unnecessary complexity

User review: The user can:

• Approve as-is
• Edit specific sections ("change the storage approach to X")
• Reject sections ("remove the notification system, I don't need that")
• Ask for regeneration of a section ("rethink the data pipeline")

After the user approves (with any edits), the expanded context feeds into:

• PROJECT.md (step 5) — richer project definition from the start
• Phase 2 market research — better search queries from expanded technical context
• Phase 3 Q&A — fewer basic architecture questions needed, can focus on nuanced decisions
• Phase 5 artifacts — HANDOFF.md, CHARTER.md, etc. have more depth from day one

Auto-ideate behavior: Run gap assessment against the loaded document. Expand only significant gaps (skip if input is comprehensive). Apply domain-informed defaults, note all assumptions in memory.md. Proceed directly to step 5.

Ecosystem Detection

After creating project.yaml, check if the concept mentions existing ecosystems or projects by name. If a match is found:

• "This sounds related to [ecosystem]. Should I link it?" → set relationships.ecosystem and role: member
• "Does it consume/produce data from [project]?" → add consumes/produces
• "Does it deliver content from [project]?" → set delivers
• "No relationship" → skip

When creating a compound idea (multiple apps, shared infra), create umbrella project first with role: umbrella, then each child with ecosystem: <umbrella-slug>.

Auto-ideate ecosystem behavior: Auto-detect relationships from document references to existing projects. Note inferred relationships in memory.md. If the document describes multiple apps sharing infrastructure, auto-create the umbrella project first.

Auto-ideate behavior: Synthesize the concept directly from the loaded document. Extract what it is, who it's for, the problem it solves, and any stated constraints. Run gap assessment — expand only significant gaps with domain-informed defaults, note assumptions in memory.md. Create all artifacts (project dir, project.yaml, PROJECT.md enriched by any expanded context, manifest) without waiting for user input. Skip the "confirm understanding" step — proceed immediately to Phase 2.

---

Phase 2: Market Research

Run by default after concept capture. User can skip.

Check if web search is available. If not, offer manual input or skip.

Search for 3-5 commercial and 3-5 OSS products. For each: name, URL, what it does, pricing, strengths, weaknesses.

Present summary with gaps, build/fork/extend recommendation, confidence level. Save to research/market-research.md.

Include a Learnings & Implications section at the end of market-research.md — what the landscape means for this project's design, positioning, and build decisions. This replaces a separate learnings file.

Auto-ideate behavior: Attempt web search for competitive landscape. If web search is available, run it and generate a full market-research.md. If unavailable, create a minimal market-research.md noting "Automated research unavailable — manual review recommended" with whatever can be inferred from the input document. Do not prompt the user — proceed to Phase 3 regardless.

---

Phase 3: Domain Selection & Q&A

Domain Selection

Auto-recommend domain based on idea description:

Domain	Use When
app	Software applications, features, products
infrastructure	Cloud, servers, networking, ops
integration	API integrations, data pipelines
tool-selection	Build vs buy, vendor selection
hardware-physical	Drones, IoT, sensors, RF, physical systems
content-brand	Content strategy, brand, marketing
commercial-framework	Consulting frameworks, pricing, GTM

Load prompt from .preflight/prompts/<domain>.md. For mixed projects, load multiple.

Ecosystem-Aware Context (if project has relationships)

Before starting structured Q&A, if the project has ecosystem relationships:

1. Load related context. Read memory.md and HANDOFF.md from each related project (consumes, produces, delivers, integrates-with targets).
2. Surface locked decisions. Present constraints from related projects: "Related project Forge Foundation has locked: [TypeScript, Weaviate, REST API]. These may constrain choices here."
3. Decision inheritance. When a decision matches an ecosystem shared decision (from PROGRAM.md), note it as inherited rather than re-asking. Example: "Tech stack inherited from ecosystem shared decision: TypeScript."
4. Add adaptive questions during Q&A:
   • "How does this project's data model relate to [related project]'s?"
   • "What interface does this expose to / consume from [related project]?"

Structured Q&A

Rules:

• One question at a time — never batch
• Adaptive depth: 6 minimum for simple, 20+ for complex
• User can override: "go deeper" or "wrap up"
• Synthesis checkpoints every 3-5 questions

Flow:

1. Base vision questions (problem, success, beneficiaries, scope boundaries)
2. Ecosystem relationship questions (if applicable — see above)
3. Domain-specific killer questions from loaded prompt
4. Contextual follow-ups

Complexity Assessment

Score each dimension from references/complexity-criteria.md as signals emerge during Q&A. At the end of Q&A, present the scored table to the user:

Based on our conversation, here's how I'd assess complexity:

| Signal | Value | Level |
|--------|-------|-------|
| Services/components | <n> | Simple/Moderate/Complex |
| External integrations | <n> | ... |
| Delivery phases | <n> | ... |
| Team size | <n> | ... |
| Estimated codebase | <range> | ... |
| Technology novelty | <description> | ... |
| Data complexity | <description> | ... |
| User types | <n> | ... |
| Deployment model | <description> | ... |
| Real-time requirements | <description> | ... |

Overall: <Simple/Moderate/Complex>
Track recommendation: <lightweight/GSD/none>

Scoring rules:

• Majority "Simple" → Simple
• Split between "Simple" and "Moderate" → Moderate
• 3+ signals "Complex" → Complex
• If unsure → default to Moderate, let user decide

Not every signal will have a clear answer — skip dimensions that didn't come up. Present the assessment and ask the user to confirm or adjust before proceeding.

Track Recommendation

Based on the complexity assessment, note the execution track in project.yaml:

• lightweight — Simple/moderate software. PreFlight artifacts are the complete planning suite.
• gsd — Complex software (3+ phases, parallel workstreams, team execution). Artifacts are GSD-compatible for handoff to GSD.
• none — Non-software projects. PreFlight is the complete tool.

Present the recommendation with the complexity assessment. User decides. All software tracks produce HANDOFF.md. The track affects Phase 7 build behavior — GSD track creates a repo and displays the /gsd:new-project --auto instruction, lightweight track creates the repo and builds the app.

Component Tagging

Tag each epic/component: software, hardware, firmware, infrastructure, process, content

Update Memory

Write or update memory.md after Q&A completes or user pauses. See references/artifact-templates.md for the memory.md template.

Auto-ideate behavior (Phase 3):

• Domain selection: Auto-select the most appropriate domain based on the input document content. If ambiguous, default to app for software projects.
• Q&A: Synthesize answers to key questions from the input document rather than asking interactively. Generate a comprehensive Q&A transcript as if the document answered each question. For questions the document doesn't address, infer reasonable defaults based on document context and note them as inferred.
• Complexity assessment: Auto-score all complexity dimensions from the document's stated scope, tech stack, integrations, and user types. Present the assessment in memory.md but don't wait for user confirmation.
• Track assignment: Auto-assign based on complexity score (Simple/Moderate → lightweight, Complex → gsd). Record in project.yaml.
• Memory: Write memory.md with all synthesized decisions, noting which were explicit from the document vs. inferred.

---

Phase 4: Risk Review

Cross-reference decisions against market evidence. Identify risks across: technical, market, operational, scope, dependencies.

For each risk: category, severity, evidence, mitigation, blast radius, reversibility.

Walk through each risk with user one at a time. Ask: "Keep, adapt, or defer?"

Save risks-and-considerations.md. If market research has already been conducted, update the Learnings & Implications section in research/market-research.md with any new insights from the risk review.

Update memory.md with risk decisions and any changed requirements.

Auto-ideate behavior: Auto-generate risks across all categories based on the project's tech stack, scope, and complexity. Apply default mitigations (defer low-severity, mitigate medium+). Save risks-and-considerations.md without user walk-through. Update memory.md with risk decisions.

---

Phase 5: Artifact Generation

The artifact set adapts to both domain and complexity. Software gets epics and architecture, hardware gets BOM and topology, content gets a brief and outline. Simple projects get fewer artifacts than complex ones. Never force software artifacts onto non-software projects.

See references/artifact-templates.md and references/gsd-format.md.

Core Artifacts (all projects, all complexities)

These are always generated — they're the minimum viable planning set.

#	Artifact	File
1	Project Definition	PROJECT.md (GSD)
2	Market Analysis	research/market-research.md (includes landscape + learnings)
3	Memory & Status	memory.md (session history + current status + next steps)
4	Metadata	project.yaml
5	Transcript	transcripts/<date>-<slug>.md

Complexity-Gated Artifacts

These are generated for moderate and complex projects. For simple projects, skip them unless the ideation session surfaces a genuine need.

Artifact	File	When to Include
Charter	CHARTER.md	Moderate+ or when non-goals, success metrics, or stakeholder boundaries need defining
Principles	PRINCIPLES.md	Moderate+ or when project-specific principles emerged during Q&A
Risks	risks-and-considerations.md	Moderate+ or when genuine risks were identified in Phase 4

Simple projects: If PROJECT.md's "Done" list is sufficient (no need for separate non-goals or measurable success metrics), if Q&A didn't surface project-specific principles (beyond workspace defaults), or if Phase 4 found no significant risks — don't generate empty artifacts. Capture any minor notes in memory.md instead.

Domain-Specific Artifacts

Select based on the project's domain. Each domain gets its own set.

Software (app, integration, tool-selection):

#	Artifact	File
+	Handoff Brief	HANDOFF.md

Software: 6–9 artifacts (5 core + 0–3 gated + 1 handoff).

The track field in project.yaml (gsd/lightweight/none) affects Phase 7 build behavior, not artifact generation. All software projects produce HANDOFF.md. GSD track creates a repo and routes to /gsd:new-project --auto. Lightweight track creates the repo and builds the app directly.

Execution Guide (always generated inside HANDOFF.md): HANDOFF.md includes an ## Execution Guide section with build order, build log instructions, success criteria, test expectations, scope boundaries, known risks, and definition of done. This section carries GSD's core execution principles in a form any AI tool can consume directly. For the lightweight path, this IS the execution plan. For full GSD, GSD ignores it and derives its own phase structure. See references/artifact-templates.md for the complete template and generation rules.

UX Completeness Check (software projects only)

After generating HANDOFF.md, run a UX completeness check to catch missing user-facing capabilities. This prevents shipping apps where the system works but users can't accomplish basic tasks (import/export, onboarding, error recovery).

Step 1: Generate personas. From Q&A answers, create 2-3 user personas. Each has: name, role, technical comfort level (low/medium/high), goals, and 3-5 core tasks they must accomplish. Include at minimum one "primary user" and one "first-time user" perspective.

Step 2: Walk each persona through their tasks. For each persona's core tasks, verify there's a matching capability in Requirements Signals. Ask: "Can [persona] actually do [task] with what we've specified?" Flag any task that has no supporting requirement.

Step 3: Check data lifecycle. For each data type the app manages, verify these operations are covered (where applicable): create, read, update, delete, import, export. Not every data type needs all six — but flag any missing operation that a user would reasonably expect. Pay special attention to import (how does data get in?) and export (how does data get out?).

Step 4: Check first-run experience. Verify there's a path for a new user with no existing data. If the app requires initial data to be useful, there must be an import path, a setup flow, or example/seed data.

Step 5: Surface gaps. Present missing capabilities as a list. For each gap, recommend: add to Must-Have (if core to the value proposition), add to Deferred (if nice-to-have), or skip (if genuinely not needed).

• Interactive mode: Walk through gaps with the user one at a time. Update Requirements Signals based on their decisions.
• Auto mode: Auto-add gaps that are clearly core (import/export for data-centric apps, onboarding for apps with setup requirements). Add borderline gaps to Deferred. Note all decisions in memory.md.

Step 6: Save personas. Add the ## User Personas section to HANDOFF.md (see references/artifact-templates.md for format). Each persona's core tasks reference the requirement that covers them.

GSD Lite (generated during Phase 7, not Phase 5): When the repo is created in Phase 7, PreFlight also generates a GSD Lite execution protocol (.planning/GSD-LITE.md) with companion state files (SESSION_LOG.md, KNOWLEDGE.md, DEVIATIONS.md) and a repo-level CLAUDE.md. These are repo-level artifacts — they govern how AI tools work in the implementation repo for the life of the project. The Execution Guide tells you how to build v1; GSD Lite tells you how to iterate forever. See Phase 7 for generation details and references/artifact-templates.md for templates.

Hardware / Infrastructure (infrastructure, hardware-physical):

#	Artifact	File
+	Specifications	SPECIFICATIONS.md
+	Roadmap	ROADMAP.md (GSD)
+	Design & Topology	DESIGN.md
+	Work Packages	work-packages.md

Hardware: 9–12 artifacts (5 core + 0–3 gated + 4 domain).

Content / Brand (content-brand):

#	Artifact	File
+	Brief	BRIEF.md
+	Outline	OUTLINE.md
+	Production Plan	production-plan.md

Content: 8–11 artifacts (5 core + 0–3 gated + 3 domain).

Commercial (commercial-framework):

#	Artifact	File
+	Requirements	REQUIREMENTS.md
+	Roadmap	ROADMAP.md
+	Engagement Model	engagement-model.md
+	Pricing & Packaging	pricing-and-packaging.md

Commercial: 9–12 artifacts (5 core + 0–3 gated + 4 domain).

All saved to projects/<slug>/.planning/.

Auto-ideate behavior: Generate the full artifact suite for the domain and complexity level without approval gates. Write all artifacts in sequence. Do not pause for user review between artifacts — generate everything, then proceed to Phase 6.

---

Phase 6: Validation

Present summary (artifacts created, key decisions, complexity, track, top 3 risks).

Validation Checklist

Run these checks with the user (adapt language to domain — "requirements" for software, "specifications" for hardware, "brief" for content):

1. Vision alignment — does the planning match the original idea?
2. Edge cases / failure modes addressed?
3. Complexity assessment realistic?
4. Work breakdown actionable? (stories for software, work packages for hardware, outline for content)
5. v1 scope tight enough?
6. Principles aligned?

Cross-Reference Validation

Verify linkages across artifacts. Use the appropriate matrix for the project domain.

Software projects:

Source	Check
HANDOFF.md "Requirements Signals"	References decisions from Q&A captured in memory.md
HANDOFF.md "Key Decisions"	Matches decisions captured in memory.md Active Decisions
HANDOFF.md "Risk Summary"	References risks-and-considerations.md (if generated)
HANDOFF.md "Market Positioning"	References research/market-research.md
HANDOFF.md "User Personas"	Every persona core task maps to a Requirements Signal (must-have or deferred)
HANDOFF.md "User Personas"	Data lifecycle operations (import/export) covered for all primary data types
HANDOFF.md "User Personas"	First-run/onboarding path exists if app requires initial data
research/market-research.md	Exists and contains landscape analysis

Hardware/infrastructure projects:

Source Artifact	Must Reference	Check
SPECIFICATIONS.md	ROADMAP.md	Every spec maps to a roadmap phase
ROADMAP.md	SPECIFICATIONS.md	Every phase lists which specs it addresses
work-packages.md	SPECIFICATIONS.md	Every work package traces to specs via verification items
work-packages.md	ROADMAP.md	Every work package has a Phase label matching a roadmap phase
DESIGN.md	SPECIFICATIONS.md	Design covers all specification categories

Content projects:

Source Artifact	Must Reference	Check
BRIEF.md	OUTLINE.md	Brief's key messages appear in outline sections
OUTLINE.md	BRIEF.md	Outline serves the brief's stated audience and angle
production-plan.md	OUTLINE.md	Production steps cover all outline sections

If any cross-reference fails, fix the source artifact and re-validate before proceeding.

Ecosystem Validation (if project has relationships)

If the project has relationships in project.yaml, run these additional checks:

Check	How
Data flow symmetry	If A says consumes: B, verify B has produces: A (warn, don't block)
Shared decision conflicts	Compare key decisions against PROGRAM.md shared decisions. Flag conflicts.
Interface compatibility	If project consumes from another, check producer's HANDOFF.md defines that interface
Status dependency	If consuming from a concept project, flag build order dependency
Unresolved references	Any relationship target slug not in workspace

Present as warnings with context, not blocking errors. Example: "Warning: forge-groundwork consumes from forge-foundation, but Foundation's HANDOFF.md doesn't define a REST API interface contract yet."

Completion

Iterate on feedback. When approved, update project.yaml status to ready, regenerate projects.md workspace manifest (full scan — see Workspace Manifest).

After validation passes:

• Interactive mode: Ask "Want me to build it now?" If yes, proceed to Phase 7. If no, leave status as ready — the user can run --auto-build later.
• --auto-ideate mode: Stop here. Project is ready, no repo created. Display summary of artifacts generated and how to build later (preflight --auto-build).
• --auto mode: Proceed directly to Phase 7.

Auto-ideate behavior (Phase 6): Run cross-reference validation programmatically. If any cross-references fail, fix them automatically (update the source artifact to match). Auto-approve validation, set status to ready. Do not prompt the user for feedback.

---

Phase 7: Build & Ship

Phase 7 combines repo creation and app build into one phase. It runs when:

• auto_build = true (from --auto or --auto-build)
• Interactive mode: user answers "Yes" to "Want me to build it now?"

Non-software projects: Skip Phase 7 entirely. Set status to shipped directly after Phase 6 validation. The user takes the artifacts and uses them however they want.

Step 1: Pre-flight Checks

Before creating anything, verify:

1. Project status is ready (error if not)
2. Target directory (~/repos/<slug>/) does not exist (error if it does — "Directory already exists at ~/repos//. Remove it or choose a different name.")
3. GitHub repo does not exist (gh repo view <org>/<slug> returns 404) (error if it exists — "GitHub repo / already exists.")

If any check fails, stop with a clear error message. Never overwrite existing repos or directories.

Step 2: Create Repo

In auto mode: Use defaults — private visibility, personal org, slug as repo name.

In interactive mode: Ask repo name (default: slug), GitHub org (default: personal), visibility (default: private).

Then:

1. Create the repo:

   gh repo create <org>/<name> --<visibility> --clone

2. Copy .planning/ artifacts to new repo (selective — skip session-specific files):
   • HANDOFF.md
   • research/market-research.md
   • risks-and-considerations.md (if exists)
   • CHARTER.md (if exists)
   • PRINCIPLES.md (if exists)
3. Since both source and target use .planning/, paths are identical — no translation needed
4. Generate GSD Lite artifacts in the new repo (see references/artifact-templates.md for templates):
   • .planning/GSD-LITE.md — execution protocol with project-specific sections populated:
     • Scope Enforcement: copy Must-Have Capabilities (in scope) and Deferred + Non-Goals (out of scope) from HANDOFF.md Requirements Signals
     • Test Commands: derive from tech stack in Key Decisions (Go → go test ./..., Python → pytest, Node → npm test)
     • Project-Specific Notes: copy Key Decisions (Locked) table and Constraints. Highlight critical dependencies and deployment model.
   • .planning/SESSION_LOG.md — empty with format header (entries added during development)
   • .planning/KNOWLEDGE.md — seeded from HANDOFF.md:
     • Architecture: summarize from "What This Is" + Build Order layer descriptions
     • Patterns & Conventions: extract from Key Decisions — each decision implies a pattern
     • Gotchas: reframe each risk from Risk Summary as a developer-facing warning
     • Dependencies: list locked tech stack with any noted constraints
     • Performance: carry forward performance-related risk mitigations
     • Testing: copy test commands and scope from Test Expectations
   • .planning/DEVIATIONS.md — empty with format header (entries added when deviations occur)
5. Generate CLAUDE.md at repo root — project description (from HANDOFF "What This Is"), tech stack (from Key Decisions), test commands, and reference to .planning/GSD-LITE.md as execution protocol. See references/artifact-templates.md for the template.
6. Initial commit and push

What does NOT get copied: PROJECT.md (GSD creates its own format), memory.md (PreFlight session state), transcripts/ (archival), project.yaml (PreFlight metadata — lives outside .planning/).

What gets generated fresh (not copied): GSD-LITE.md, SESSION_LOG.md, KNOWLEDGE.md, DEVIATIONS.md (populated from HANDOFF.md content during repo creation), CLAUDE.md (repo root).

Step 3: Route by Track

• GSD track: Display instruction: "Run /gsd:new-project --auto @.planning/HANDOFF.md in the new repo to begin build. GSD Lite will govern post-build iteration." Then skip to Step 5 (do not build).
• Lightweight track: Continue to Step 4 (build).

Step 4: Build (Lightweight Track Only)

Read the Execution Guide from HANDOFF.md. Build the app layer by layer.

Build process:

1. Initialize project — go mod init / npm init / uv init / etc. based on tech stack from Key Decisions
2. Build each layer in sequence (from Execution Guide Build Order):
   • Write the code for the layer (files, modules, tests)
   • Run tests for the layer
   • Verify the layer works before moving on
   • Commit: feat: implement <layer name>
   • Update .planning/SESSION_LOG.md with what was built
3. Final verification:
   • Run all Success Criteria checks from the Execution Guide
   • Run the full test suite
   • Run a smoke test of the core flow
   • Report results (pass/fail for each criterion)

Failure handling:

• Commit after each successful layer (progress is always saved)
• If a layer fails after 2-3 fix attempts: stop, commit progress so far, report what failed and why
• Never silently skip a layer — every layer either passes or the build stops with an explanation

Phase 7 does NOT:

• Modify planning artifacts in the ideation-lab workspace
• Add features beyond what the Execution Guide specifies
• Push the implementation repo (user decides when to push)
• Set up CI/CD or deployment

Step 5: Update Ideation-Lab

After repo creation (and build, if lightweight track):

1. Update project.yaml in the ideation-lab workspace: status: shipped, repo: <url>, handoff_date: <date>
2. Regenerate projects.md workspace manifest (full scan)
3. Commit and push ideation-lab changes

Auto Mode Summary

Flag	What it does	Stops at
--auto-ideate @doc	Ideation only (Phases 1-6)	ready status, no repo
--auto-build	Build only (Phase 7)	Working app in repo
--auto @doc	Full pipeline (Phases 1-7)	Working app in repo
(no flag)	Interactive — all prompts	User chooses when to stop

If user declines build in interactive mode: Leave status as ready. The user can build later with preflight --auto-build.

---

Programs (Ecosystems & Compound Projects)

An ecosystem is a group of 2+ projects that share data, decisions, or infrastructure. It's the natural structure when a single vision requires multiple purpose-built apps.

When to Create an Ecosystem

• 2+ projects share a data platform or API layer
• Projects have producer/consumer relationships (data flows between them)
• Shared decisions apply across projects (tech stack, auth model, deployment)
• A content project has (or will have) an app layer that delivers it

Ecosystem Structure

• Umbrella project: The ecosystem definition. Sets role: umbrella in project.yaml. Contains PROGRAM.md in .planning/ with vision, shared decisions, interfaces, and build order.
• Member projects: Individual projects within the ecosystem. Set role: member and ecosystem: <umbrella-slug> in project.yaml. Each gets its own full ideation cycle.
• Relationships are declared in each project's project.yaml via the relationships field (see references/artifact-templates.md for the schema).

Creating an Ecosystem

When a compound idea surfaces during ideation:

1. Create the umbrella project first (role: umbrella, no ecosystem field)
2. Create PROGRAM.md in the umbrella's .planning/ directory (see references/artifact-templates.md for template)
3. Create each member project with ecosystem: <umbrella-slug> and role: member
4. Declare consumes/produces/delivers/integrates-with on each member

Retroactive Ecosystem Declaration

For projects that already exist independently:

1. Add relationships to each project's project.yaml (ecosystem, role, consumes/produces)
2. Create the umbrella project if it doesn't exist
3. Create or update PROGRAM.md in the umbrella's .planning/
4. Regenerate projects.md — members move from flat tables to ecosystem grouping

Ecosystem-Aware Ideation

Ecosystems integrate with the ideation lifecycle:

• Phase 0: Ecosystem index built from project.yaml scan. Relationship targets resolved. Ecosystem summary displayed after status table.
• Phase 1: New projects auto-detected against existing ecosystems. Compound ideas create umbrella + members.
• Phase 3: Related project decisions surfaced before Q&A. Locked decisions inherited. Adaptive questions about interfaces and data models.
• Phase 5: Artifacts reference ecosystem context where relevant.
• Phase 6: Ecosystem validation checks data flow symmetry, shared decision conflicts, interface compatibility, status dependencies, and unresolved references.

/preflight ecosystem <name> Command

Shows a comprehensive ecosystem view. When invoked:

1. Find umbrella project by slug or name (case-insensitive match)
2. Scan all projects for relationships.ecosystem: <slug>
3. Display:
   • Vision (from PROGRAM.md)
   • Project table — status, role, tier, description for each member
   • Data flows — derived from consumes/produces across all members
   • Shared decisions — from PROGRAM.md Shared Decisions table
   • Interfaces — producer/consumer/type/contract/status per interface
   • Build order — dependency-ordered list with status indicators
   • Risks — cross-project risks and status dependencies
4. If ecosystem not found: suggest known ecosystems or "Create one with /preflight new"

---

Capability Detection

Core Q&A and artifact generation only need file read/write. Web search is an optional enhancement for market research — degrade gracefully when unavailable.

---

Session Memory & Transcripts

memory.md — Living Session State & Status

memory.md is the single source of truth for project continuity. It captures session history (how we got here), current status (where we are), and next steps (what to do next). A new AI instance should be able to read the instant context section (above <!-- END INSTANT CONTEXT -->) and know exactly where to pick up. Update it after every phase, not just Q&A. Before any update, check the line count — if over 120 lines, compress Session History (collapse oldest sessions) before appending new content.

Update triggers:

• After concept capture (Phase 1): initial questions, constraints, concept summary
• After market research (Phase 2): key findings, build/fork/extend decision
• After Q&A (Phase 3): all questions and answers, decisions, complexity, track, component tags
• After risk review (Phase 4): risk decisions (keep/adapt/defer), requirement changes
• After artifact generation (Phase 5): artifacts created, completion status, next steps
• After validation (Phase 6): validation feedback, final status
• When user pauses or ends a session mid-phase

See references/artifact-templates.md for the memory.md template.

Transcript — Session Record

Write transcripts/<date>-<slug>.md as a full record of each session. Include all phases covered, questions asked, answers given, decisions made, and synthesis checkpoints. One transcript per session — append a new file for each session, don't overwrite.

See references/artifact-templates.md for the transcript template.

---

Session Resumption

Read memory.md up to the <!-- END INSTANT CONTEXT --> marker for the quick snapshot. Read project.yaml for metadata. If the snapshot is sufficient to continue, proceed. Read Session History only if you need deeper context on a specific decision. Acknowledge prior decisions. Summarize where we left off. Don't re-ask settled questions. Continue from the appropriate phase.

---

Updating Existing Projects

When a user wants to revisit a shipped or in-progress project (e.g., "update requirements for X", "re-run market research on X", "add a feature to X's plan"):

What to Preserve

• All existing decisions in memory.md — don't re-ask settled questions
• Artifact structure and format — update in place, don't regenerate from scratch
• Session history — append to memory.md session history table
• Existing transcript files — create a new transcript, never overwrite old ones

What to Update

• Run only the phases relevant to the change:
  • New requirements? → Update HANDOFF.md requirements signals, re-check decisions
  • Market changed? → Re-run Phase 2, update learnings and risks
  • Scope shift? → Update CHARTER.md, HANDOFF.md
  • New risk identified? → Update risks-and-considerations.md, HANDOFF.md risk summary
• After any artifact update, re-run the cross-reference validation (Phase 6 matrix) on affected artifacts
• Update project.yaml updated date
• Update memory.md with what changed, why, and current status

What NOT to Do

• Don't regenerate the full artifact suite for a minor change
• Don't reset project status — an update to a shipped project keeps it shipped
• Don't delete or overwrite previous transcripts
• Don't re-ask questions that were already answered unless the user explicitly wants to reconsider

---

Principles Integration

The skill does NOT hardcode a decision framework. Instead, it references the user's workspace principles throughout every session.

On workspace load, read .preflight/PRINCIPLES.md and use its contents to:

• Evaluate tradeoffs during Q&A (apply the user's decision framework)
• Flag anti-patterns the user has defined
• Validate alignment during Phase 6 ("Principles aligned?")
• Inform risk assessment dimensions in Phase 4

The defaults/PRINCIPLES.md ships with an opinionated starting framework. Users can fully replace it to match their own thinking style. Per-project PRINCIPLES.md overrides workspace-level principles.

If no PRINCIPLES.md exists (corrupted workspace), fall back to general best practices: validate feasibility, assess operational readiness, evaluate reversibility, understand failure impact, and flag over-engineering.

---

What NOT to Do

• Don't jump to implementation before vision is clear
• Don't batch questions — one at a time
• Don't generate partial artifact suites — complete set for the domain or nothing
• Don't force software artifacts (HANDOFF.md) onto non-software projects
• Don't store user data in this skill's directory
• Don't skip synthesis checkpoints
• Don't assume the project is software — confirm