---
name: greenfield
description: "Start a new project from scratch. UI products run the full prototype-driven SDLC (concept → wireframe → prototype → iterate → codify → production build → deliver); CLIs, services, and libraries default to a lighter path (concept + executable verification → codify → production build → deliver), with wireframe + prototype available on opt-in."
argument-hint: "[project-name]"
---

# /greenfield — New Project From Scratch

You are orchestrating a complete new project build. This is for projects that do not yet have a codebase. The default phase plan depends on the project's `stack:`:

- **UI-shaped products** (`vite-react`, `nextjs`): full prototype-driven pipeline — discover → concept → wireframe → prototype (iterate) → codify → production build → deliver. The interactive wireframe + prototype is the verification surface, and that surface is what makes the SDLC pay off for UI work.
- **Non-UI products** (`cli`, `go-service`, `python-fastapi`, `none`, and library/SDK work): concept slides for architectural framing, then the stack-appropriate **executable verification surface** (working binary + demo for CLI, `/docs` + sample requests for FastAPI, grpcurl/curl traces for Go services), then codify → production build → deliver. Wireframe + UI prototype are **skipped by default** — there is no user-facing surface that benefits from them. The user can opt them in at preflight when novel terminal UX or an admin/playground UI is worth pre-visualizing.

Phase planning at Step 1 surfaces the proposed plan to the user; the user can override any phase before the workflow proceeds.

## Execution Protocol

**REQUIRED SUB-SKILL**: load and follow the skill — do not substitute judgment. Step summaries describe outcomes; the loaded skill defines the process.

## Input

Ask the user for:
1. **Project name**
2. **Project description** (what does it do, who is it for?)
3. **Tech stack hints** (frontend product, backend service, library, CLI — affects what the prototype's verification frontend looks like)
4. **Any existing requirements** (docs, mockups, meeting notes, screenshots)

## Step 0: Preflight Checks

1. **Target directory** is clean or empty
2. **Required tools** available (Node, package manager, git, optionally Docker)
3. **User has confirmed** the project scope
4. **Project mode is set.** Read `.claude/CLAUDE.md` for `project.mode:`. If absent, write `mode: greenfield` to the `project:` YAML block (the greenfield flow treats this as `prototype` until the prototype locks, then the user updates `mode: production` per `rules/common/skill-selection.md` Step 1). If `/setup` has not run yet, run it before continuing — the project profile (stack, test runner, etc.) is needed for downstream phases.

## Step 0a: Wiki Bootstrap

REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.

## Step 1: Manifest + Phase Planning

Check if `.forge/work/greenfield/{project-name}/manifest.yaml` exists.

**If it exists**: Resume from the last incomplete phase. Skip phases marked `locked` or `skipped`. If `status: escalated` or `status: completed`, do NOT resume.

**If it does not exist**: Create `.forge/work/greenfield/{project-name}/` and the manifest from `.claude/templates/manifests/greenfield.yaml`. Fill placeholders.

### Step 1a: Detect stack

Resolve the project's `prototype.stack:` value BEFORE proposing the phase plan — the stack is what determines whether the default plan is UI-shaped or non-UI. Read in this order:

1. `project.stack:` in `.claude/CLAUDE.md` (set by `/setup`) — if present and one of the allowed values (`vite-react`, `nextjs`, `existing-repo`, `python-fastapi`, `cli`, `go-service`, `none`), use it.
2. Otherwise, ask the user once: "What stack? Options: `vite-react`, `nextjs`, `python-fastapi`, `cli`, `go-service`, `existing-repo` (extend a non-Next.js **UI** app — Vue / Astro / Svelte / SolidStart / etc.; pick `cli` / `go-service` / `python-fastapi` for non-UI hosts), `none` (no prototype phase)."

Record the chosen value in the manifest at `artifacts.prototype.stack:` immediately. `build-prototype` and `iterate-prototype` read from there.

### Step 1b: Default phase plan by stack class

Propose `active` / `skip` for each phase based on the stack class:

**UI-shaped stacks** (`vite-react`, `nextjs`, `existing-repo` — the last only when extending a non-Next.js UI app; non-UI hosts pick `cli` / `go-service` / `python-fastapi` instead):

| Phase | Default |
|---|---|
| Concept | active (8-15 slides for full products) |
| Wireframe | active (interactive HTML is the design surface) |
| Plan-design-system | active |
| Prototype + Iterate | active (the prototype is the running verification surface) |
| Codify | active |
| Production-build | active |
| Test-plan + UI/UX review + Deliver | active |

**Non-UI stacks** (`cli`, `go-service`, `python-fastapi`, `none`, and library/SDK work):

| Phase | Default |
|---|---|
| Concept | active (1-3 slides for architectural framing — what it does, what the contract is, who calls it) |
| Wireframe | **skipped** (no UI to wireframe — see "opt-in" below if you want a terminal mockup or admin playground sketch) |
| Plan-design-system | **skipped** (no design tokens needed without a UI surface) |
| Prototype + Iterate | replaced by **executable verification surface** — see Step 1c below |
| Codify | active |
| Production-build | active |
| Test-plan + Deliver | active |
| UI/UX review | **skipped** (no UI) |

### Step 1c: Executable verification surface (non-UI default)

For non-UI stacks, the prototype phase is **replaced** by a stack-appropriate executable verification surface — the same surfaces `build-prototype` Step 4 verifies for these stacks, used here as the primary deliverable of Phase 3 rather than a UI prototype:

| Stack | Verification surface |
|---|---|
| `cli` | Working binary at `pocs/{name}-prototype/` + `demo.sh` exercising the headline subcommands + `samples/expected.out` golden output |
| `go-service` | Runnable service (`go run ./cmd/server`) + `scripts/grpcurl-demo.sh` (or `curl-demo.sh` for HTTP) exercising each method/route against sample requests |
| `python-fastapi` | Runnable service (`uvicorn main:app --reload`) + `sample_request.sh` exercising each endpoint + the `/docs` OpenAPI playground |
| `none` (library/SDK without a consumer-test app) | No prototype phase at all; concept slides + harden carry the design directly into production-build. If a consumer-test app is wanted, the user opts into `stack: cli` and the table above applies. |

For non-UI stacks with a verification surface (`cli`, `go-service`, `python-fastapi`), this runs as `phase_plan.prototype: active` and uses the `build-prototype` skill — the skill already branches on `stack:` and produces the right surface (see `skills/build-prototype/SKILL.md` "Stack variants"). What changes for non-UI is that **wireframe is skipped** so build-prototype reads the source-of-truth from the concept deck + requirements doc rather than a wireframe HTML.

For `stack: none` (no prototype surface at all — library / SDK / IaC / research): set `phase_plan.prototype: skipped` AND `phase_plan.wireframe: skipped` AND `phase_plan.iterate: skipped` to match the build-prototype skill's contract (see `skills/build-prototype/SKILL.md:38`). Codify (harden) then reads source-of-truth from concept slides + requirements + the existing codebase directly. If you accidentally leave `prototype: active` with `stack: none`, build-prototype halts at its Step 1 stack switch — fix the manifest before resuming.

### Step 1d: Surface plan and offer opt-ins

Present the proposed plan to the user. For non-UI stacks, explicitly offer the two UI-shaped opt-ins so the user can override if their case benefits:

```
Detected stack: {stack}  ({UI-shaped|non-UI})

Default phase plan:
  concept:           active
  wireframe:         {active|skipped — no UI}
  plan-design-system: {active|skipped}
  prototype:         active ({UI prototype|executable verification: <surface>})
  iterate:           active
  codify:            active
  production-build:  active
  test-plan:         active
  uiux-review:       {active|skipped — no UI}
  code-review-final: active
  deliver:           active

Overrides:
  - Add wireframe + UI prototype anyway? [y/N]   # only offered for non-UI stacks
    (Useful if you want a terminal-UI mockup, an admin/playground HTML sketch,
     or a curl-flow walkthrough before scaffolding.)
  - Skip a phase you don't need? Name it and a one-line reason.
  - Change the stack? (re-runs Step 1a)
```

Capture the user's response. If they opt into wireframe + prototype on a non-UI stack, set both to `active` and proceed as the UI-shaped path — the wireframe becomes the screen list for `build-prototype` (and for `cli`, that wireframe is typically an admin/playground UI sketch, not the CLI itself). If they skip additional phases, record the reason in the `phase_plan` object form.

The chosen plan is written to `phase_plan:` in the manifest; downstream steps respect it.

## Step 2: Discover — Requirements (optional)

If the user provided detailed requirements upfront, this step extracts and structures them. If they're starting from a brief paragraph, this step is folded into Step 3 concept slides.

REQUIRED SUB-SKILL: Use **discover-requirements** (only if user has substantive existing requirements docs).

## Step 3: Concept (Phase 1)

REQUIRED SUB-SKILL: Use **concept-slides**.

Produces a low-fidelity marp deck at `decks/{project-name}/slides.md` with hook, 3-5 sub-concepts with sketches, user journey, and out-of-scope. 8-15 slides for full products. The user iterates 1-3 cycles.

### GATE: Concept Locked

User reviews the rendered deck (HTML), gives feedback, locks when satisfied. Update manifest: `artifacts.concept.{deck_path, locked_at}`.

## Step 4: Wireframe (Phase 2) — if active

**Skip if** `phase_plan.wireframe: skipped` (non-UI stack default, or explicit user skip). Non-UI products do not have a screen list to wireframe — the source of truth is the concept deck + requirements doc, and `build-prototype` reads from those at Step 1.

**Otherwise:** REQUIRED SUB-SKILL: Use **build-wireframe**.

Produces `pocs/{project-name}-wireframe/index.html` — single-HTML annotated wireframe with click-through demos and gutter callouts.

### GATE: Wireframe Locked

User clicks through the rendered HTML, gives feedback, locks when satisfied. Update manifest: `artifacts.wireframe.{html_path, locked_at}`.

## Step 4.5: Design System — if frontend project

**Skip if** `phase_plan.plan-design-system: skipped` (non-UI stack default). Without a UI surface there are no design tokens to lock.

**Otherwise:** REQUIRED SUB-SKILL: Use **plan-design-system** to lock design tokens before architecture.

The design tokens captured here feed scaffold, every frontend task spec, and the UI/UX review. The skill self-skips when `DESIGN.md` already exists and is current for this work item.

### GATE: Design Tokens Approved

User approves the design tokens written to `DESIGN.md`. Update manifest: `artifacts.design-system.{path, approved_at}`.

## Step 5: Prototype + Iterate (Phases 3–4)

Phases 3 and 4 are distinct in `references/common/phases.md` (Phase 3 = build-prototype, Phase 4 = iterate-prototype) and have separate entries in `hooks/config/gate-requirements.json` (`prototype` + `iterate`), but they share a single lock signal — `artifacts.prototype.locked_at`. The user's satisfaction emission after iteration is the close for both.

REQUIRED SUB-SKILL: Use **build-prototype** for the initial scaffold (Phase 3), then **iterate-prototype** for the polish loop (Phase 4).

Scaffolds the prototype according to `artifacts.prototype.stack:` (set at Step 1 preflight from the project profile). Default `vite-react` produces `pocs/{project-name}-prototype/` — Vite + React + TS + Tailwind v4 + Zustand v5 + lucide-react + Biome; `nextjs` skins into the existing app; `python-fastapi` produces a FastAPI service + `/docs` playground; `cli` produces a working binary + demo script; `go-service` produces a Go service + grpcurl fixtures; `none` skips the phase. See `skills/build-prototype/SKILL.md` "Stack variants" for the full table. Multi-instance prototype-builder for multi-track wireframes. User runs the stack's dev command, gives feedback in `pocs/{project-name}-prototype/.forge/feedback.md`.

During iteration: gotchas + conventions get captured to `aiwiki/gotchas/` and `aiwiki/conventions/` (Phase 5 inputs). Wiki-lint validates each write.

### GATE: Prototype Locked (closes Phases 3 + 4)

User emits "satisfied" or "LOCKED" after click-through verification. Update manifest: `artifacts.prototype.{path, locked_at}`. Both `phase_plan.prototype` and `phase_plan.iterate` reach terminal state on this lock.

Optional: `/autopilot prototype` for hands-off polish loop *(planned, not yet implemented — see docs/V6-PLAN.md §11; manual `[iterate-prototype]` runs are the only mode today)*.

## Step 6: Codify (Phase 5)

REQUIRED SUB-SKILL: Use **harden**.

Codifies the locked prototype into production-ready plans:
- `aiwiki/architecture/{topic}.md` — one or more focused architecture files
- `aiwiki/decisions/{nnnn}-{slug}.md` — ADRs (adversarial review runs inline at harden Step 2, surfacing objections in each ADR's `review:` block; optionally dispatched to Codex in verify mode when configured)
- `aiwiki/conventions/` — production-surface conventions
- `aiwiki/gotchas/` — Phase 4 gotchas with production addenda
- Slice graph + `tasks.md` in manifest
- `aiwiki/sessions/` entry indexing everything produced

Triggers a focused dream after writes; user reviews dream output in `aiwiki/proposed/` before phase closes.

### GATE: Codified Plan Approved

User reviews ALL outputs as a unit (architecture + ADRs + slice graph + dream proposal). Approves before Phase 6 starts. Update manifest: `artifacts.codify.locked_at` (no path — the populated slice_graph + aiwiki/architecture/ files ARE the codify artifacts).

## Step 7: Production Build (Phase 6)

Execute the slice graph from Phase 5. Per slice, in dependency order:

1. REQUIRED SUB-SKILL: Use **build-tdd** — strict RED-GREEN-REFACTOR
2. REQUIRED SUB-SKILL: Use **quality-code-review**
3. Fix any Critical or Important findings
4. Per-slice user-confirm

Per-slice dream fires after slice close — consolidates gotchas and slice-scoped wiki updates.

Optional: `/autopilot production` runs slices via Ralph loop until all gates green *(planned, not yet implemented — see docs/V6-PLAN.md §11; per-slice manual dispatch is the only mode today)*.

### GATE: All Slices Complete

All slices have `gate-passed: true` for build-tdd, code-review, runtime-reach. Update manifest: `artifacts.production-build.locked_at` (slice terminal state + production code ARE the production-build artifacts).

## Step 8: Test Plan + Execution

REQUIRED SUB-SKILL: Use **quality-test-plan**, then **quality-test-execution**.

### GATE: Test Results

ALL tests pass. Coverage meets thresholds (minimum 80%, 100% for critical paths).

## Step 8.5: UI/UX Review — if active

**Skip if** `phase_plan.uiux-review: skipped` (non-UI stack default — no UI to verify against).

**Otherwise** (the project has a frontend per Step 1 phase planning):

REQUIRED SUB-SKILL: Use **quality-uiux**.
Validates production implementation matches the locked wireframe + design tokens.

## Step 9: Final Code Review

REQUIRED SUB-SKILL: Use **quality-code-review** for a final pass across all production code (full diff). Fix any Critical or Important findings before deployment.

## Step 10: Deliver (Phase 7)

REQUIRED SUB-SKILL: Use **build-pr-workflow**.
Optionally: **deliver-deploy** (if deploying), **deliver-onboarding** (always for greenfield).

## Step 11: Support — Record Lessons

REQUIRED SUB-SKILL: Use **support-gotcha**.
Final dream cycle consolidates all Phase 4-7 captures into the curated wiki state.

Update manifest: `status: completed`.

## Phase Skip Handling

When the user opts to skip a phase during Step 1 phase planning, set the phase_plan entry to `skipped` (object form to capture the reason):

```yaml
phase_plan:
  wireframe:
    status: skipped
    reason: "User has detailed Figma mockups; converting directly to prototype"
```

Skipped phases do not run gates. The downstream phase reads from whatever artifact the skipped phase would have produced (e.g. user-provided mockups instead of a wireframe).

If a skipped phase reveals a gap during a later phase, surface the gap to the user and decide together whether to re-open the skipped phase (changing `phase_plan.{phase}` from `skipped` back to `active`) or carry deltas explicitly in the next phase's outputs. The flow does not auto-rewind.

## Gate Checking Logic

Resume rule: skip phases where `artifacts.{phase}.locked_at` is present (already locked) or `phase_plan.{phase}` is `skipped`. **Special case for prototype:** if `artifacts.prototype.scaffold_status: complete` is set but `locked_at` is absent, Phase 3 (build-prototype) is done — resume jumps straight into Phase 4 (iterate-prototype) which is the sole writer of `locked_at`. Halt and fix any phase whose gate hasn't passed before continuing.