procedure-cli 0.1.11 → 0.1.12

package/CODE-FIXED.md

@@ -169,3 +169,29 @@ None.
 - `rg "dimColor|color=\"(cyan|green|red|yellow|blue|magenta|white|black)\"" -n src`: no matches
 
 ---
+## Entry 2026-02-22
+
+### Entry ID
+- `CF-20260222-006`
+
+### Source Review
+- `CR-20260222-004` (CODE-REVIEW.md entry 2026-02-22)
+
+### Fixes Applied
+
+1. Finding #12 (Medium) — **Fixed**
+- `src/cli.tsx:11` — Replaced hard-stop behavior with warning-only messaging when directory is non-empty.
+- `src/cli.tsx:13` — Added explicit note that existing files may be overwritten during Step 6, preserving the intended Generation conflict-confirmation flow.
+- `src/cli.tsx:16` — Removed process exit path so wizard continues and existing overwrite warnings in Generation remain reachable.
+
+2. Finding #13 (Low) — **Fixed**
+- `src/cli.tsx:16` — Updated setup hint to include both valid invocations: `npx procedure-cli` and `npx @b3awesome/procedure`, avoiding single-command drift.
+
+### Deferred
+None.
+
+### Verification Notes
+- `npm run typecheck`: pass
+- `npm run build`: pass
+
+---

package/CODE-REVIEW.md

@@ -384,3 +384,48 @@
 
 ### Residual Risks / Testing Gaps
 - No snapshot/UI regression tests currently enforce theme consistency rules across wizard steps.
+
+---
+
+## Entry 2026-02-22
+
+### Entry ID
+- `CR-20260222-004`
+
+### Supersedes
+- `CR-20260222-003`
+
+### Scope
+- New review cycle after recent CLI pre-flight and documentation updates.
+- Validate latest fixed findings and check for regressions in runtime behavior.
+
+### Validation Matrix
+| Finding # | Previous Severity | Current Status | Evidence | Notes |
+|-----------|-------------------|----------------|----------|-------|
+| 11 | Low | Fixed | `CODE-FIXED.md:188`, `src/steps/build-test.tsx:68` | Theme consistency fix remains present (`color={C.overlay1}` in Build & Test default hint). |
+
+### Findings (ordered by severity)
+1. Medium - New empty-directory hard stop regresses overwrite-confirmation flow (`Finding #12`, `Status: New`)
+- `src/cli.tsx:7`
+- `src/cli.tsx:8`
+- `src/steps/generation.tsx:45`
+- `src/steps/generation.tsx:139`
+- `src/lib/template.ts:40`
+- CLI now exits before wizard render when cwd has any entries. This bypasses the existing generation-stage conflict detection and explicit overwrite confirmation (`checkConflicts` + "⚠ Will overwrite"), removing a previously supported safe path for regeneration in non-empty directories.
+- Recommendation: downgrade pre-flight to a warning (not hard exit), or gate strict-empty behavior behind an explicit flag while preserving Step 6 overwrite confirmation.
+
+2. Low - Empty-directory guidance command is inconsistent with repo package metadata (`Finding #13`, `Status: New`)
+- `src/cli.tsx:15`
+- `package.json:2`
+- Error guidance suggests `npx @b3awesome/procedure`, but repository package metadata is `procedure-cli` with bin `procedure`. This can mislead contributors running the package directly from this repo context.
+- Recommendation: derive suggested invocation from package metadata/config (single source of truth) or print both supported invocations explicitly.
+
+### Verification Notes
+- Procedure compliance: read latest `CODE-REVIEW.md` and `CODE-FIXED.md` before this review.
+- `npm run typecheck`: pass.
+- `npm run build`: pass.
+- Reviewed local working-tree diffs in `README.md`, `docs/PRD.md`, `docs/USER-STORIES.md`, and `src/cli.tsx`.
+
+### Residual Risks / Testing Gaps
+- No integration test for behavior in non-empty directories vs regeneration flow (`checkConflicts` path).
+- No test that validates CLI guidance text stays aligned with actual package/bin invocation names.

package/README.md

@@ -1,29 +1,30 @@
 # Procedure CLI
 
-Interactive CLI wizard that scaffolds projects with AI-driven documentation and best practices. Inspired by [Skills.sh](https://skills.sh) visual style.
+Interactive CLI wizard that scaffolds new projects with a battle-tested `CLAUDE.md`, PRD, user stories, and optional tooling setup. Inspired by [Skills.sh](https://skills.sh) visual style.
 
-## What It Does
+## Requirements
 
-Procedure CLI generates a complete project foundation including:
+Must be run in an **empty directory**. If the directory has existing files, the CLI exits with a helpful message.
+
+```bash
+mkdir my-project && cd my-project
+npx @b3awesome/procedure
+```
+
+## What It Generates
 
 | File | Purpose |
 |------|---------|
-| `CLAUDE.md` | AI-ready development guide with architecture, code style, workflow |
+| `CLAUDE.md` | AI-ready development guide with architecture, code style, and workflow |
 | `README.md` | Project overview with quick start, tech stack, and docs links |
-| `docs/PRD.md` | Product Requirements Document with vision, features, tech stack |
+| `docs/PRD.md` | Product Requirements Document with vision, features, and tech stack |
 | `docs/USER-STORIES.md` | Gherkin-formatted acceptance criteria and user stories |
 | `.env.example` | Environment variables template |
-| `.gitignore` | Sensible git ignore defaults |
-
-## Quick Start
-
-```bash
-npx procedure-cli
-```
+| `.gitignore` | Language/framework-appropriate git ignore defaults |
 
 ## Visual Style
 
-Procedure CLI uses a Skills.sh / @clack/prompts-inspired vertical timeline UI:
+Catppuccin Mocha color theme with a Skills.sh-inspired vertical timeline:
 
 ```
 █▀█ █▀█ █▀█ █▀▀ █▀▀ █▀▄ █ █ █▀█ █▀▀
@@ -32,96 +33,119 @@ Procedure CLI uses a Skills.sh / @clack/prompts-inspired vertical timeline UI:
 Bootstrap any project with a battle-tested
 CLAUDE.md, PRD, user stories, and powerline.
 ───────────────────────────────────────────
-◇  Project Info
-│  my-app — A task management tool
+┌
+│ ◇  Project Info
+│    my-app — A task management tool
 │
-◆  Stack & Style
-│  ❯ QuickStart (use a preset)
-│    Advanced (manual config)
+│ ◆  Stack & Style          ← animated dot while active
+│  ❯ TypeScript + Node.js — CLI tools, backend APIs, npm packages
+│    Next.js Full-Stack — SaaS apps, marketing sites, SSR/SSG
+│    React SPA — Dashboards, admin panels, SPAs
+│    ↓ more
+│    ↑↓ move, enter select
 │
-○  Build & Test
+│ ○  Build & Test
 │
-○  Architecture
+│ ○  Architecture
 │
-○  Product Context
+│ ○  Product Context
 │
-○  Generation
+│ ○  Generation
 │
-○  Powerline
+│ ○  Setup
+└
 ```
 
-- `◇` completed step (green) — summary on separate `│` line
-- `◆` active step (green, bold) — content with `│` gutter
-- `○` pending step (dim)
-- `│` continuous vertical gutter connecting all steps
+| Indicator | Meaning |
+|-----------|---------|
+| `◇` (green) | Completed — summary shown on the `│` line below |
+| `◆◈◇◈` (mauve, animated) | Active — waiting for input |
+| `○` (dim) | Pending |
+| `┌` / `└` | Open/close corners wrapping the full wizard flow |
 
 ## The 7 Wizard Steps
 
-1. **Project Info** — Name, description, package manager (select), license (select)
-2. **Stack & Style** — QuickStart preset or advanced manual config (language, framework, code style)
-3. **Build & Test** — Build/test/typecheck/lint/pre-PR commands with smart defaults
-4. **Architecture** — Select from 7 patterns (Monorepo, MVC, Feature folders, etc.) with auto-generated best-practice notes
-5. **Product Context** — Problem, users, tech stack (multi-select with 18 technologies, prefilled from Step 2), core features, non-goals
-6. **Generation** — Review summary, see overwrite warnings, and confirm before writing files (or skip)
-7. **Powerline** — Optional Claude Code powerline setup + git init (commit only when applicable)
+### 1. Project Info
+Name, description, package manager (select), license (select).
+
+### 2. Stack & Style
+Choose a **QuickStart preset** or configure manually:
+
+| Preset | Best for |
+|--------|----------|
+| TypeScript + Node.js | CLI tools, backend APIs, npm packages |
+| Next.js Full-Stack | SaaS apps, marketing sites, SSR/SSG |
+| React SPA | Dashboards, admin panels, SPAs |
+| Python + FastAPI | AI/ML backends, REST APIs, data services |
+| Go HTTP Service | High-perf APIs, microservices |
+| React Native + Expo | Cross-platform mobile apps |
+| Configure manually → | Custom language, framework, and code style |
+
+Presets auto-fill build/test/typecheck/lint/PR commands.
+
+### 3. Build & Test
+Build, test, typecheck, lint, and pre-PR commands — with smart defaults pre-filled when a QuickStart preset was selected.
+
+### 4. Architecture
+Select from 7 patterns (Monolith, MVC, Feature folders, Hexagonal, Microservices, Event-driven, Monorepo). Architecture notes are auto-generated from the chosen pattern.
+
+### 5. Product Context
+Problem statement, target users, tech stack (multi-select, prefilled from Step 2), core features (multi-select with custom input), non-goals.
+
+### 6. Generation
+Full summary of all collected inputs. Warns about any files that will be overwritten. Confirm to write files or skip.
+
+### 7. Setup *(optional)*
+Three independent yes/no prompts — each explained before asking:
+
+- **Claude Powerline** — live status bar (git branch, context %, cost, active tools); runs via `npx` per session
+- **Git repository** — `git init` + initial commit with the generated files
+- **npm release scripts** — creates `~/bin/<project>-release` and adds `release:patch/minor/major` to `package.json`
 
 ## UI Components
 
 | Component | File | Purpose |
 |-----------|------|---------|
-| Banner | `src/components/banner.tsx` | ASCII art header + tagline + horizontal rule |
-| Timeline | `src/components/timeline.tsx` | Vertical step flow with `◇`/`◆`/`○` indicators |
-| StepIndicator | `src/components/step-indicator.tsx` | Single step dot + label rendering |
-| GutterLine | `src/components/gutter-line.tsx` | `│  ` prefix wrapper for content lines |
-| GutteredSelect | `src/components/guttered-select.tsx` | Single-select with `│  ❯` gutter (replaces @inkjs/ui Select) |
-| GutteredMultiSelect | `src/components/guttered-select.tsx` | Multi-select with `●`/`○` toggle + prefill support |
+| Banner | `src/components/banner.tsx` | ASCII art header + tagline + divider |
+| Timeline | `src/components/timeline.tsx` | `┌`/`└` corners, `│` gutter, step flow |
+| StepIndicator | `src/components/step-indicator.tsx` | Animated dot + label per step |
+| GutterLine | `src/components/gutter-line.tsx` | `│  ` prefix wrapper (Box row) |
+| GutteredSelect | `src/components/guttered-select.tsx` | Sliding-window single-select with `│  ❯` gutter |
+| GutteredMultiSelect | `src/components/guttered-select.tsx` | Multi-select with `●`/`○` toggle + custom input |
 
 ## Tech Stack
 
-- **Language:** TypeScript (strict mode, ESM)
-- **UI Framework:** Ink 6 (React for CLI)
-- **UI Components:** Custom guttered select/multi-select (not @inkjs/ui Select)
-- **Templating:** Handlebars (.hbs)
-- **AI:** Vercel AI SDK 6, Z.ai (GLM models), OpenAI
-- **Build:** tsc
+| Layer | Technology |
+|-------|-----------|
+| Language | TypeScript (strict mode, ESM) |
+| UI Framework | Ink 6 (React for CLI) |
+| Templating | Handlebars (`.hbs`) |
+| AI | Vercel AI SDK 6, Z.ai (GLM), OpenAI |
+| Build | tsc |
 
 ## Development
 
 ```bash
-npm run dev              # Run CLI in dev mode (⚠️ run in a temp dir, not here!)
-npm run build            # Compile TypeScript
+npm run dev              # Run CLI directly via tsx
+npm run build            # Compile to dist/
 npm run typecheck        # Type check only
-npm run lint             # Alias of typecheck in this repo
 ```
 
-> **Warning:** Never run `npm run dev` from the procedure project directory — scaffolding writes to cwd and will overwrite procedure's own files. Always `cd` to a temp directory first.
+> **Warning:** Never run `npm run dev` from the procedure project directory — scaffolding writes to `cwd` and will overwrite procedure's own files. Always `cd` to a temp directory first.
 
 ## Review & Fix Workflow
 
-This repo tracks review/fix cycles with two append-only logs:
-
-- `CODE-REVIEW.md` — review entries (`CR-YYYYMMDD-###`)
-- `CODE-FIXED.md` — fix entries (`CF-YYYYMMDD-###`)
-
-Process:
-1. Start review by reading latest `CODE-REVIEW.md` and `CODE-FIXED.md`.
-2. Append new review findings to `CODE-REVIEW.md` only.
-3. During implementation, write fix actions to `CODE-FIXED.md` only.
-4. Re-review and update finding statuses in a new review entry.
-
-Verification standard after fixes: run `npm run typecheck` and `npm run build`.
+Two append-only logs track review/fix cycles:
 
-## Recent Behavior Updates
+- `CODE-REVIEW.md` — findings (`CR-YYYYMMDD-###`)
+- `CODE-FIXED.md` — fix actions (`CF-YYYYMMDD-###`)
 
-- Generation step now warns when target files already exist before writing.
-- If generation is skipped, final summary explicitly states no files were written.
-- Git setup no longer hard-fails on empty directories; it reports a warning when nothing is committed.
-- `docs/USER-STORIES.md` now includes fallback starter content when no stories are provided.
+Verification standard after fixes: `npm run typecheck` + `npm run build`.
 
 ## Documentation
 
-- [CLAUDE.md](./CLAUDE.md) — Project development guide
-- [docs/PRD.md](./docs/PRD.md) — Procedure CLI product requirements
+- [CLAUDE.md](./CLAUDE.md) — Development guide
+- [docs/PRD.md](./docs/PRD.md) — Product requirements
 - [docs/USER-STORIES.md](./docs/USER-STORIES.md) — User stories and acceptance criteria
 - [docs/GIAI-THICH-CLAUDE-MD.md](./docs/GIAI-THICH-CLAUDE-MD.md) — 4-layer CLAUDE.md methodology (Vietnamese)
 

package/dist/cli.js

@@ -1,6 +1,18 @@
 #!/usr/bin/env node
 import { jsx as _jsx } from "react/jsx-runtime";
 import { render } from "ink";
+import { readdirSync } from "node:fs";
 import App from "./app.js";
+const entries = readdirSync(process.cwd()).filter((e) => e !== ".DS_Store");
+if (entries.length > 0) {
+    const sample = entries.slice(0, 3).join(", ");
+    const extra = entries.length > 3 ? `, +${entries.length - 3} more` : "";
+    console.error(`\nWarning: current directory is not empty.`);
+    console.error(`  Found: ${sample}${extra}`);
+    console.error(`  Existing files can be overwritten during Step 6 (Generation).`);
+    console.error(`  Recommended for a fresh project:`);
+    console.error(`    mkdir my-project && cd my-project`);
+    console.error(`    npx procedure-cli   (or: npx @b3awesome/procedure)\n`);
+}
 render(_jsx(App, {}));
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.tsx"],"names":[],"mappings":";;AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,MAAM,CAAC,KAAC,GAAG,KAAG,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.tsx"],"names":[],"mappings":";;AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC;AAC5E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC5D,OAAO,CAAC,KAAK,CAAC,YAAY,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACjF,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACpD,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACvD,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,CAAC,KAAC,GAAG,KAAG,CAAC,CAAC"}

package/docs/PRD.md

@@ -2,7 +2,7 @@
 
 ## Vision
 
-Empower developers to start projects with production-ready documentation and architecture decisions from day one, reducing onboarding time and ensuring best practices are baked in.
+Empower developers to start projects with production-ready documentation and architecture decisions from day one, reducing onboarding time and ensuring best practices are baked in from the first commit.
 
 ## Problem
 
@@ -24,46 +24,52 @@ Empower developers to start projects with production-ready documentation and arc
 ## Core Features
 
 **F-001: Interactive Project Wizard**
-- 7-step guided setup with timeline progress view
-- Validates input, provides sensible defaults
-- Timeline preview shows estimated completion time
+- 7-step guided setup with Catppuccin Mocha timeline UI
+- `┌`/`└` corners wrap the full flow; animated dot on active step
+- Empty-directory guard: exits with helpful message if cwd contains files
+- Validates required fields; ESC exits at any point; Enter exits on completion
 
 **F-002: CLAUDE.md Generation**
-- Code style and import conventions
-- Build & test commands
-- Architecture decisions and rationale
-- Workflow guidance (planning, verification, bug fixing)
+- Code style and import conventions (from preset or manual config)
+- Build, test, typecheck, lint, and pre-PR commands
+- Architecture pattern with auto-generated best-practice notes
+- Workflow guidance (planning, verification, bug fixing, elegance)
 - Lessons learned section (AI-updatable)
 
 **F-003: PRD.md Generation**
 - Vision, problem statement, target users
-- Core features (F-001 through F-006 format)
-- Non-goals and success metrics
-- Tech stack table
-- Open questions placeholder
+- Core features (F-001 format), non-goals, tech stack table
+- Success metrics placeholder, open questions section
 
 **F-004: USER-STORIES.md Generation**
 - Gherkin-formatted acceptance criteria
 - "As a / I want / So that" narrative format
 - Feature scenarios with Given/When/Then
-- Supports 9+ standard scenarios (full scaffolding, quick start, powerline, etc.)
+- Scaffolded from wizard-collected core features and user context
 
 **F-005: Environment & Config Files**
 - `.env.example` template with user-specified variables
-- `.gitignore` with language/framework-specific rules
+- `.gitignore` with language/framework-specific defaults
 
-**F-006: Powerline Integration (Optional)**
-- Shell prompt styling and configuration
-- Powerline font detection and fallbacks
-- Theme color selection during setup
+**F-006: QuickStart Presets**
+- 6 one-click presets: TypeScript+Node, Next.js, React SPA, Python+FastAPI, Go, React Native+Expo
+- Each preset pre-fills stack, build, test, typecheck, lint, and pre-PR commands
+- "Configure manually →" option for custom language/framework/code-style
+
+**F-007: Setup & Tooling Integration (Optional)**
+Each option is explained before the yes/no prompt:
+- **Claude Powerline** — live status bar (git branch, context %, session cost, active tools); deployed via `npx` per session, no global install
+- **Git repository** — `git init` + initial commit containing all generated files
+- **npm release scripts** — creates `~/bin/<project>-release`; adds `release:patch`, `release:minor`, `release:major` to `package.json`; adapts commands to selected package manager
 
 ### Visual Style
 
-- **Banner:** ASCII header with "Procedure CLI" branding
-- **Timeline:** Vertical step indicators (pending → active → completed)
-- **Colors:** Cyan for highlights, green for success, dim gray for secondary info
-- **Icons:** ✔ (completed), ► (active), ○ (pending)
-- **Spacing:** Single-line padding, clean box layouts via Ink
+- **Theme:** Catppuccin Mocha Dark (mauve active, green complete, sapphire headers, overlay1 gutter)
+- **Layout:** `┌`/`│`/`└` vertical timeline with `┌` before step 1 and `└` after step 7
+- **Active step:** Animated dot cycling `◆ → ◈ → ◇ → ◈` at 350 ms
+- **Completed step:** `◇` (green); summary displayed on separate `│  ` line below
+- **Select menus:** Sliding window (5 visible at a time), `↑`/`↓` scroll indicators, `↑↓ move, enter select` hint
+- **Multi-select:** `●` selected, `○` unselected, space to toggle, enter to confirm; custom "Other" option via text input
 
 ## Non-Goals
 
@@ -72,46 +78,52 @@ Empower developers to start projects with production-ready documentation and arc
 - Database schema generation
 - Frontend component scaffolding
 - Package template marketplace
+- `--quick` or `--update` CLI flags (wizard is always interactive)
+- Partial regeneration of individual files
 
 ## Tech Stack
 
 | Component | Technology | Purpose |
 |-----------|-----------|---------|
 | **Runtime** | Node.js + TypeScript | Type-safe CLI |
-| **UI** | Ink + React | Interactive CLI rendering |
+| **UI** | Ink 6 + React 19 | Interactive terminal rendering |
 | **Templating** | Handlebars | Dynamic file generation |
-| **AI** | ai-sdk + OpenAI | Future: GPT-assisted prompts (optional) |
-| **Build** | tsc | Minimal, fast compilation |
+| **AI** | Vercel AI SDK 6, Z.ai, OpenAI | Optional AI-assisted generation |
+| **Build** | tsc | Fast compilation, strict mode |
 
 ## 7 Wizard Steps (Detailed)
 
 ### Step 1: Project Info
-- Inputs: Project name, description, package manager preference, license
-- Output: Basic project metadata
+- Inputs: Project name (required), description (required), package manager (select), license (select)
+- Outputs: Project metadata used across all generated files
 
 ### Step 2: Stack & Style
-- Inputs: Language, framework, code style (strict mode, imports, naming, error handling)
-- Output: Stack summary and style guide anchors
+- Inputs: QuickStart preset selection, or manual language + framework + code-style multi-selects
+- Outputs: Stack and style data; presets also pre-fill Step 3 commands
 
 ### Step 3: Build & Test
-- Inputs: Build, test, typecheck, lint, PR check commands
-- Output: Development commands for CLAUDE.md
+- Inputs: Build, test, typecheck, lint, pre-PR commands (pre-filled if preset chosen)
+- Outputs: Development commands section in CLAUDE.md
 
 ### Step 4: Architecture
-- Inputs: Architecture pattern, architectural decisions, detailed notes
-- Output: Architecture section for CLAUDE.md
+- Inputs: Architecture pattern selection (7 options)
+- Outputs: Architecture section in CLAUDE.md with auto-generated best-practice notes
 
 ### Step 5: Product Context
-- Inputs: Problem statement (5 bullets), target users table, core features, non-goals, tech stack, user stories
-- Output: PRD.md and USER-STORIES.md data
+- Inputs: Problem statement, target users, tech stack (multi-select, prefilled from Step 2), core features (multi-select + custom), non-goals
+- Outputs: Data for PRD.md and USER-STORIES.md
 
 ### Step 6: Generation
-- Automatic: Compile answers into CLAUDE.md, PRD.md, USER-STORIES.md, .env.example, .gitignore
-- Output: Files written to project directory with timestamps
+- Shows full summary of all collected inputs grouped by section
+- Warns about any existing files that will be overwritten
+- Confirm → writes all files; Skip → exits without writing
+- Outputs: CLAUDE.md, README.md, docs/PRD.md, docs/USER-STORIES.md, .env.example, .gitignore
 
-### Step 7: Powerline (Optional)
-- Inputs: Enable powerline, font selection, theme colors
-- Output: Shell configuration and setup instructions
+### Step 7: Setup (Optional)
+- Three sequential yes/no prompts (Powerline, Git, Release scripts)
+- Each explained in detail before asking
+- All three can be independently enabled or skipped
+- Outputs: `.claude/` powerline config, git repo with initial commit, `~/bin/<project>-release`, updated `package.json`
 
 ## Success Metrics
 
@@ -123,8 +135,6 @@ Empower developers to start projects with production-ready documentation and arc
 
 ## Open Questions
 
-- Should we support multiple AI models (Claude, GPT-4, local LLMs)?
-- Auto-generate user stories from feature descriptions?
+- Should we support multiple AI models (Claude, GPT-4, local LLMs) for assisted generation?
 - Integration with GitHub Actions for CI/CD template generation?
 - Support for monorepo scaffolding (workspaces)?
-- Interactive feature validation via AI (e.g., "Validate that F-001 and F-002 don't overlap")?

package/docs/USER-STORIES.md

@@ -10,70 +10,133 @@
 
 ```gherkin
 Scenario: User completes full 7-step wizard
-  Given a developer runs `npx procedure-cli`
+  Given a developer runs `npx @b3awesome/procedure` in an empty directory
   When they answer all wizard questions (project info, stack, build, architecture, product context)
-  Then CLAUDE.md, PRD.md, USER-STORIES.md, .env.example, and .gitignore are created
-  And a success message displays with project name and generated files
+  And confirm generation in Step 6
+  Then CLAUDE.md, README.md, PRD.md, USER-STORIES.md, .env.example, and .gitignore are created
+  And a success message displays with the project name and generated files listed
+  And pressing Enter exits the CLI
 ```
 
 ```gherkin
 Scenario: Wizard validates required inputs
   Given the user is on Step 1 (Project Info)
-  When they leave the project name empty and try to continue
-  Then validation error shows and they must re-enter
-  And "Next" button remains disabled until valid
+  When they leave the project name empty and press Enter
+  Then a validation error shows inline
+  And the wizard does not advance until a valid name is entered
 ```
 
-## US-002: Quick Start Mode
+```gherkin
+Scenario: User skips generation
+  Given the user reaches Step 6 (Generation)
+  When they press N at the "Proceed?" prompt
+  Then no files are written to disk
+  And the final summary states "Generation was skipped — no files were written"
+```
+
+## US-002: Empty Directory Guard
 
-**As a** developer in a hurry
-**I want** to scaffold a project with minimal questions
-**So that** I can start coding in under 2 minutes
+**As a** developer protecting an existing project
+**I want** the CLI to refuse to run in a non-empty directory
+**So that** I don't accidentally overwrite my existing files
 
-### Feature: QuickStart Shortcuts
+### Feature: Pre-flight Directory Check
+
+```gherkin
+Scenario: CLI exits when directory has existing files
+  Given a developer runs `npx @b3awesome/procedure` in a directory with files
+  When the CLI starts
+  Then it exits immediately with an error message
+  And the message lists up to 3 found files/directories
+  And it shows the commands to create an empty directory and retry
+  And the process exits with code 1
+```
 
 ```gherkin
-Scenario: Quick mode with sensible defaults
-  Given the developer runs `npx procedure-cli --quick`
-  When they provide only project name and description
-  Then defaults are used for tech stack, build commands, architecture
-  And files are generated immediately
+Scenario: CLI starts normally in an empty directory
+  Given a developer runs `npx @b3awesome/procedure` in an empty directory
+  When the CLI starts
+  Then the wizard renders with the banner and Step 1 active
 ```
 
-## US-003: Advanced Configuration
+## US-003: QuickStart Presets
+
+**As a** developer who knows their stack
+**I want** to pick a preset and have all commands pre-filled
+**So that** I can scaffold a project in under 2 minutes without typing every command
+
+### Feature: Stack & Style Presets
 
-**As a** team lead defining standards
-**I want** to customize every section of the generated docs
-**So that** the output matches our team's coding standards and practices
+```gherkin
+Scenario: User selects a QuickStart preset
+  Given the user is on Step 2 (Stack & Style)
+  When they navigate to "TypeScript + Node.js" and press Enter
+  Then Step 2 completes immediately with language, framework, and code style set
+  And Step 3 (Build & Test) opens with build, test, typecheck, lint, and PR commands pre-filled
+```
+
+```gherkin
+Scenario: User switches to manual configuration
+  Given the user is on Step 2 (Stack & Style) in QuickStart mode
+  When they navigate to "Configure manually →" and press Enter
+  Then they are shown the language multi-select
+  And then the framework multi-select
+  And then the code style multi-select
+  And can choose any combination with custom "Other" input
+```
+
+```gherkin
+Scenario: Preset list shows scrollable options
+  Given the user is on Step 2 (Stack & Style)
+  When the preset list renders
+  Then 5 presets are visible at a time
+  And "↓ more" appears when additional options are below the visible window
+  And pressing ↓ scrolls the window to reveal more presets
+```
+
+## US-004: Advanced Manual Configuration
+
+**As a** team lead defining custom standards
+**I want** to configure language, framework, and code style manually
+**So that** the output matches our team's exact conventions
 
 ### Feature: Detailed Customization
 
 ```gherkin
-Scenario: Full control over architecture and style
-  Given the user is on Step 4 (Architecture)
-  When they describe architecture decisions and code style details
-  Then CLAUDE.md includes the exact text in the Architecture and Code Style sections
-  And next steps reference these decisions
+Scenario: Full control over stack and style
+  Given the user selects "Configure manually →" in Step 2
+  When they choose multiple languages (e.g. TypeScript + Python)
+  And choose multiple frameworks (e.g. Next.js + FastAPI)
+  And select code style conventions with a custom "Other" rule
+  Then CLAUDE.md includes the exact languages, frameworks, and conventions chosen
 ```
 
-## US-004: Powerline Setup Integration
+## US-005: Generation Review and Confirmation
 
-**As a** shell enthusiast
-**I want** to configure powerline font and prompt styling during setup
-**So that** my terminal matches my project's branding
+**As a** developer reviewing before committing
+**I want** to see a full summary of all my inputs before files are written
+**So that** I can catch mistakes without having to edit generated files
 
-### Feature: Shell Prompt Customization
+### Feature: Generation Summary Screen
 
 ```gherkin
-Scenario: User enables powerline during Step 7
-  Given the wizard is on Step 7 (Powerline)
-  When they select "Yes, set up powerline"
-  Then they choose fonts (Noto Sans Mono, Fira Code, custom)
-  And pick a theme color (blue, green, purple)
-  And setup instructions are displayed
+Scenario: Generation step shows all collected inputs
+  Given the user reaches Step 6 (Generation)
+  When the summary renders
+  Then it shows Project Info, Stack & Style, Build & Test, Architecture, and Product Context
+  And it lists all 6 files that will be generated
+  And it warns "⚠ Will overwrite: <filename>" for any files that already exist
 ```
 
-## US-005: PRD Generation with Features
+```gherkin
+Scenario: Overwrite warning shown for existing files
+  Given the target directory already contains CLAUDE.md
+  When the user reaches Step 6 (Generation)
+  Then a peach-colored warning lists CLAUDE.md as a file that will be overwritten
+  And the user must confirm before any writing occurs
+```
+
+## US-006: PRD Generation with Full Context
 
 **As a** product manager
 **I want** the PRD to capture vision, problem, users, and core features
@@ -84,19 +147,12 @@ Scenario: User enables powerline during Step 7
 ```gherkin
 Scenario: PRD includes all required sections
   Given the user completes Step 5 (Product Context)
-  When they provide vision, problem statement, user table, and core features
-  Then PRD.md contains:
-    | Section | Content |
-    | Vision | User's description |
-    | Problem | 5 bullet points |
-    | Users | Table with roles and value |
-    | Core Features | F-001 through F-006 format |
-    | Non-Goals | Explicit out-of-scope items |
-    | Tech Stack | Table with technologies |
-    | Success Metrics | Measurable outcomes |
+  When they provide problem statement, user context, core features, and non-goals
+  Then PRD.md contains Vision, Problem, Users, Core Features, Non-Goals, Tech Stack, and Success Metrics
+  And core features are formatted as F-001 through F-NNN entries
 ```
 
-## US-006: User Stories with Gherkin Format
+## US-007: User Stories with Gherkin Format
 
 **As a** QA engineer
 **I want** user stories with Gherkin acceptance criteria
@@ -105,77 +161,104 @@ Scenario: PRD includes all required sections
 ### Feature: Structured User Stories
 
 ```gherkin
-Scenario: User stories include Given/When/Then
+Scenario: USER-STORIES.md includes Gherkin scenarios
   Given the user provides core features in Step 5
   When files are generated in Step 6
-  Then USER-STORIES.md contains:
-    - US-001 through US-009 headers
-    - "As a / I want / So that" format
-    - Feature: [name] sections
-    - Multiple Scenario: blocks with Gherkin syntax
+  Then USER-STORIES.md contains US-NNN headers with "As a / I want / So that" format
+  And each story includes one or more Scenario blocks with Given/When/Then syntax
 ```
 
-## US-007: Git Initialization
+## US-008: Visual Timeline Progress
 
-**As a** developer starting fresh
-**I want** the wizard to optionally initialize git with a sensible .gitignore
-**So that** I don't accidentally commit build artifacts or secrets
+**As a** new user
+**I want** to see a visual timeline of all steps with clear current-step indication
+**So that** I always know where I am and what's left
 
-### Feature: Git Setup
+### Feature: Timeline Progress Indicator
 
 ```gherkin
-Scenario: Git repo is initialized with language-specific ignores
-  Given the user completes the wizard
-  When they select "Initialize git repo" (optional prompt)
-  Then `git init` runs automatically
-  And .gitignore is committed with language/framework rules
-  And initial commit message is "chore: initialize project with Procedure CLI"
+Scenario: Timeline shows completed, active, and pending steps
+  Given the user is on Step 3 (Build & Test)
+  When they view the terminal
+  Then the timeline shows:
+    - ◇ Project Info (green, completed, with summary below)
+    - ◇ Stack & Style (green, completed, with summary below)
+    - ◆ Build & Test (mauve animated dot, active)
+    - ○ Architecture (dim, pending)
+    - ○ Product Context (dim, pending)
+    - ○ Generation (dim, pending)
+    - ○ Setup (dim, pending)
+  And ┌ appears before step 1 and └ appears after step 7
 ```
 
-## US-008: Partial Scaffolding & Regeneration
+```gherkin
+Scenario: Completed step summary appears below step name
+  Given the user completes Step 1 (Project Info)
+  When the timeline advances to Step 2
+  Then below "Project Info" on a separate │ line, the summary shows the entered name and description
+```
+
+## US-009: Optional Tooling Setup
+
+**As a** developer setting up a new project
+**I want** to optionally initialize git, configure Claude Powerline, and add release scripts
+**So that** my project has proper version control and publish tooling from day one
+
+### Feature: Setup Step
 
-**As a** developer iterating on docs
-**I want** to re-run the wizard and update only certain files
-**So that** I can refine PRD and user stories without re-answering all questions
+```gherkin
+Scenario: User enables all three setup options
+  Given the wizard is on Step 7 (Setup)
+  When the user answers Yes to Powerline, Yes to Git, and Yes to release scripts
+  Then .claude/ powerline configuration is created
+  And git init runs and an initial commit is made with the generated files
+  And ~/bin/<project>-release is created with the correct package manager commands
+  And package.json is created (or updated) with release:patch, release:minor, and release:major scripts
+```
 
-### Feature: Selective Regeneration
+```gherkin
+Scenario: Each setup option is explained before asking
+  Given the wizard is on Step 7 (Setup)
+  When the Powerline question renders
+  Then an explanation is shown describing what Powerline does before the yes/no prompt
+  And the same applies to the Git and release script questions
+```
 
 ```gherkin
-Scenario: User reruns wizard to update PRD only
-  Given a project was scaffolded previously
-  When they run `npx procedure-cli --update prd`
-  Then only Step 5 (Product Context) runs
-  And PRD.md and USER-STORIES.md are regenerated
-  And CLAUDE.md remains unchanged
+Scenario: Git init is skipped gracefully when nothing to commit
+  Given the user enables Git setup
+  When git init runs but there are no files to commit (generation was skipped)
+  Then a warning message is shown explaining why the commit was skipped
+  And the setup step completes without error
 ```
 
-## US-009: Visual Timeline with Estimated Completion
+```gherkin
+Scenario: Release script skipped when it already exists
+  Given ~/bin/<project>-release already exists
+  When the user enables release script setup
+  Then a message confirms the existing script was skipped
+  And package.json release scripts are still applied if not already present
+```
 
-**As a** new user
-**I want** to see a visual timeline of remaining steps with time estimate
-**So that** I know how long the setup will take
+## US-010: Escape and Graceful Exit
 
-### Feature: Timeline Progress Indicator
+**As a** developer who changed their mind
+**I want** to exit the wizard at any point
+**So that** I don't have to complete all steps or kill the process manually
+
+### Feature: ESC to Exit
 
 ```gherkin
-Scenario: Timeline shows current step and estimated completion
-  Given the user is on Step 3 of 7
-  When they view the sidebar
-  Then they see:
-    - ✔ Step 1: Project Info (completed)
-    - ✔ Step 2: Stack & Style (completed)
-    - ► Step 3: Build & Test (active)
-    - ○ Step 4: Architecture (pending)
-    - ○ Step 5: Product Context (pending)
-    - ○ Step 6: Generation (pending)
-    - ○ Step 7: Powerline (pending)
-  And "Est. time remaining: 8 minutes" is displayed
+Scenario: ESC exits the wizard at any step
+  Given the user is anywhere in the 7-step wizard
+  When they press Escape
+  Then the CLI exits cleanly with no files written
 ```
 
 ```gherkin
-Scenario: Step completion summary is shown in timeline
-  Given the user completes Step 1
-  When they move to Step 2
-  Then the timeline shows "Project Info — my-project — my description"
-  And a checkmark indicates completion
+Scenario: Enter exits after completion
+  Given the wizard has completed all 7 steps
+  When the final success screen is shown
+  Then pressing Enter exits the CLI
+  And the final timeline shows all steps as completed with their summaries
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "procedure-cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "CLI-based AI Agent powered by AI SDK 6, Z.ai, and OpenAI",
   "type": "module",
   "bin": {

package/src/cli.tsx

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 import React from "react";
 import { render } from "ink";
+import { readdirSync } from "node:fs";
 import App from "./app.js";
 
+const entries = readdirSync(process.cwd()).filter((e) => e !== ".DS_Store");
+if (entries.length > 0) {
+  const sample = entries.slice(0, 3).join(", ");
+  const extra = entries.length > 3 ? `, +${entries.length - 3} more` : "";
+  console.error(`\nWarning: current directory is not empty.`);
+  console.error(`  Found: ${sample}${extra}`);
+  console.error(`  Existing files can be overwritten during Step 6 (Generation).`);
+  console.error(`  Recommended for a fresh project:`);
+  console.error(`    mkdir my-project && cd my-project`);
+  console.error(`    npx procedure-cli   (or: npx @b3awesome/procedure)\n`);
+}
+
 render(<App />);