procedure-cli 0.1.13 → 0.1.15

package/docs/GIAI-THICH-CLAUDE-MD.md

@@ -1,206 +0,0 @@
----
-type: explainer
-project: claude-code-best-practices
-lang: vi
-created: 2026-02-20
-updated: 2026-02-20
----
-
-# CLAUDE.md — File "Luật Chơi" Cho AI
-
-> Tài liệu giải thích bằng tiếng Việt, dùng ngôn ngữ đơn giản, để đọc lại khi cần.
-> Xem template mẫu tại [[SUGGESTED-CLAUDE-MD]].
-
----
-
-## CLAUDE.md Là Gì?
-
-Hãy tưởng tượng bạn thuê một lập trình viên mới vào team. Ngày đầu tiên, bạn sẽ nói gì với họ?
-
-- "Dự án này dùng TypeScript, build bằng `npm run build`"
-- "Luôn chạy test trước khi tạo PR"
-- "Đừng dùng `any` type — team mình không chấp nhận"
-- "Khi gặp bug, tự tìm root cause, đừng fix tạm"
-
-**CLAUDE.md chính là tập hợp những lời dặn dò đó**, nhưng dành cho AI (Claude). Nó là một file text đặt trong thư mục gốc của dự án, và Claude đọc nó mỗi khi bắt đầu làm việc.
-
-Boris Cherny — người tạo ra Claude Code — và team của anh ấy ở Anthropic dùng file này mỗi ngày. File của họ chỉ khoảng **2.500 từ** nhưng cực kỳ hiệu quả.
-
----
-
-## Tại Sao Cần CLAUDE.md?
-
-Không có CLAUDE.md, Claude sẽ:
-- **Đoán mò** lệnh build (có thể dùng `npm` thay vì `bun`)
-- **Tự nghĩ ra** convention đặt tên (có thể khác với team bạn)
-- **Làm xong rồi nói "done"** mà không chạy test
-- **Lặp lại sai lầm cũ** vì không nhớ lần trước bị sửa
-
-Có CLAUDE.md, Claude sẽ:
-- Chạy đúng lệnh build/test
-- Tuân theo convention của team
-- Tự kiểm tra trước khi nói "xong"
-- Không lặp lại lỗi đã ghi trong Lessons
-
----
-
-## Cấu Trúc 4 Tầng
-
-Phát hiện quan trọng nhất từ nghiên cứu: **hầu hết mọi người chỉ viết 1-2 trong 4 tầng cần thiết**, nên kết quả không ổn định.
-
-Ngoài 4 tầng trong CLAUDE.md, phương pháp procedure còn tạo thêm **PRD** (docs/PRD.md) và **User Stories** (docs/USER-STORIES.md) — giúp AI hiểu không chỉ cách code, mà còn sản phẩm là gì và cần xây cái gì.
-
-### Tầng 1: Kiến Thức Dự Án — "Codebase này trông như thế nào?"
-
-Phần **cụ thể, máy móc**: lệnh build/test, convention code, kiến trúc, file quan trọng.
-
-Trong template: `Build & Test`, `Code Style`, `Architecture`
-
-**Nếu thiếu:** Claude đoán lệnh, tự nghĩ ra convention, phá vỡ kiến trúc.
-
-### Tầng 2: Hợp Đồng Hành Vi — "Claude nên làm việc như thế nào?"
-
-Phần **quy tắc tư duy**, bao gồm 5 quy tắc:
-
-| Quy tắc | Ý nghĩa đơn giản | Ví dụ dễ hiểu |
-|---------|-------------------|----------------|
-| **Planning** | Task phức tạp → lên plan trước, rồi mới code | Không xây nhà mà không có bản vẽ |
-| **Verification** | Không nói "xong" mà chưa chứng minh nó chạy | Đầu bếp nếm thử trước khi bưng ra cho khách |
-| **Self-Improvement** | Mỗi lần bị sửa → ghi bài học → không lặp lại | Sau mỗi trận thua, ghi lại lý do |
-| **Bug Fixing** | Nhận bug report → tự tìm, tự sửa | Thợ ống nước giỏi không cần bạn chỉ ống nào rò |
-| **Elegance** | Task lớn → hỏi "có cách nào đẹp hơn?" | Nấu ăn ngon nhưng không cần trang trí cho bữa cơm gia đình |
-
-Trong template: `Workflow` section
-
-**Nếu thiếu:** Claude biết codebase nhưng làm việc cẩu thả — bỏ qua verification, không plan, không tự cải thiện.
-
-**Tip quan trọng nhất** theo Boris: Verification — tăng chất lượng lên 2-3 lần.
-
-### Tầng 3: Hợp Đồng Phối Hợp — "Claude phối hợp nhiều agent như thế nào?"
-
-Phần **quản lý đội** (mới từ tháng 2/2026 với Agent Teams). 3 quy tắc vàng:
-
-1. **Mỗi người sở hữu file riêng** — KHÔNG BAO GIỜ để 2 người sửa cùng 1 file
-   - Ví dụ: thợ điện chỉ đi dây điện, thợ nước chỉ đi ống nước. 2 người cùng đục 1 bức tường → hỏng!
-
-2. **Mô tả task phải đầy đủ** — teammate không biết context trước đó
-   - Ví dụ: đừng nói "sửa cái lỗi hồi nãy" → hãy nói "sửa lỗi null pointer ở file src/auth.ts dòng 42"
-
-3. **Nhắn riêng, không broadcast** — chỉ gửi tin nhắn chung khi thật sự cấp bách
-
-Trong template: `Task Management` section
-
-**Nếu thiếu:** Nhiều agent đụng nhau (sửa cùng file), thiếu context, task chạy loạn.
-
-**Giống như:** Nếu Tầng 2 là "luật chơi cho 1 người", thì Tầng 3 là "luật chơi cho cả đội".
-
-**3 cách chia việc song song:**
-
-| Cách | Khi nào dùng | Ví dụ |
-|------|-------------|-------|
-| **Subagent** | Việc nhỏ, một chiều | Sai người đi photocopy |
-| **Agent Team** | Nhiều người phối hợp | Dự án xây nhà |
-| **Git Worktree** | Việc hoàn toàn độc lập | 3 nhà hàng khác nhau |
-
-### Tầng 4: Bộ Nhớ Sống — "Claude không được lặp lại sai lầm gì?"
-
-Phần **tích lũy theo thời gian**:
-
-```
-## Lessons
-- Không dùng `any` type — luôn định nghĩa interface rõ ràng
-- Container `--rm` flag không đáng tin — luôn thêm explicit `container rm`
-```
-
-**Cách hoạt động:**
-1. Claude mắc lỗi
-2. Bạn sửa Claude
-3. Bạn nói: *"Cập nhật CLAUDE.md để lần sau không mắc lại lỗi này"*
-4. Claude tự viết rule cho chính nó
-5. Rule được commit vào git → cả team hưởng lợi
-
-Trong template: `Lessons` section
-
-Boris gọi đây là **"chi phí của một sai lầm sinh lời mãi mãi"** — mỗi lần sửa lỗi là một khoản đầu tư.
-
----
-
-## PRD và User Stories — Tại Sao AI Cần Biết "Sản Phẩm Là Gì"?
-
-4 tầng CLAUDE.md giúp Claude biết **cách làm việc** — lệnh build gì, convention gì, phối hợp thế nào. Nhưng vẫn thiếu một thứ quan trọng: **Claude không biết sản phẩm là gì**.
-
-Hãy tưởng tượng bạn thuê một thợ mộc giỏi. Anh ta biết cách cưa gỗ, đóng đinh, đánh bóng (= CLAUDE.md). Nhưng nếu bạn không nói "tôi cần một cái tủ sách, cho phòng khách, cao 1m8" — anh ta sẽ làm gì? Đoán mò? Hỏi liên tục?
-
-**PRD (Product Requirements Document)** chính là bản mô tả "cái tủ sách" đó:
-- **Vấn đề** — tại sao cần sản phẩm này?
-- **Người dùng** — ai sẽ dùng?
-- **Tính năng** — cần làm gì?
-- **Không làm** — ranh giới ở đâu?
-
-**User Stories** là danh sách "việc cần làm" cụ thể:
-- "Là người dùng, tôi muốn đăng nhập bằng email, để không cần nhớ mật khẩu"
-- Kèm theo **tiêu chí chấp nhận** (Gherkin) — giống như checklist để biết việc đã xong chưa
-
-### Tại Sao Không Chỉ CLAUDE.md Là Đủ?
-
-| Chỉ có CLAUDE.md | CLAUDE.md + PRD + User Stories |
-|---|---|
-| Claude biết cách code | Claude biết cách code **và** biết đang code cái gì |
-| Hỏi "feature này để làm gì?" | Tự đọc PRD, hiểu bối cảnh |
-| Viết code đúng convention nhưng sai mục đích | Viết code đúng convention **và** đúng mục đích |
-| Không biết khi nào nên nói "không, cái này out of scope" | Đọc Non-Goals, tự biết ranh giới |
-
-### Cách Procedure Tạo PRD và User Stories
-
-Trong bước **Product Context** (bước 5 của wizard), bạn trả lời 4 câu hỏi:
-1. Sản phẩm giải quyết vấn đề gì?
-2. Ai là người dùng?
-3. Tính năng chính là gì?
-4. Cái gì KHÔNG làm?
-
-Procedure dùng câu trả lời để tạo `docs/PRD.md` và `docs/USER-STORIES.md`. Sau đó CLAUDE.md tham chiếu đến 2 file này — tạo thành bộ 3 hoàn chỉnh:
-
-- **CLAUDE.md** = luật chơi (HOW — làm thế nào)
-- **PRD** = bối cảnh sản phẩm (WHAT + WHY — cái gì và tại sao)
-- **User Stories** = việc cần làm (WHAT to build — xây cái gì, kiểm tra thế nào)
-
-Giống như xây nhà: CLAUDE.md là "quy tắc xây dựng", PRD là "bản vẽ kiến trúc", User Stories là "danh sách phòng cần xây".
-
----
-
-## 3 Nguyên Tắc Cốt Lõi
-
-| Nguyên tắc | Giải thích |
-|-----------|-----------|
-| **Đơn giản là nhất** | Mỗi thay đổi phải đơn giản nhất có thể. Ít code = ít bug. |
-| **Không lười biếng** | Tìm nguyên nhân gốc. Không fix tạm. Chuẩn senior developer. |
-| **Ảnh hưởng tối thiểu** | Chỉ sửa những gì cần sửa. Đừng "tiện tay" sửa thêm thứ khác. |
-
----
-
-## Cách Bắt Đầu (Ngày 1)
-
-Bắt đầu với 3 thứ:
-
-1. **Lệnh build/test** — copy paste đúng lệnh của dự án
-2. **Một convention** — quy tắc quan trọng nhất
-3. **Một bài học** — lỗi gần nhất mà Claude mắc phải
-
-Sau đó, mỗi lần sửa Claude, nói: *"Cập nhật CLAUDE.md để lần sau không mắc lại."*
-
-File sẽ tự lớn lên theo thời gian — và đó chính là sức mạnh của nó.
-
----
-
-## Cách Team (Con Người) Dùng CLAUDE.md
-
-- **Commit vào git** — cả team cùng hưởng lợi
-- **Review PR → cập nhật CLAUDE.md** — dùng `@.claude` để thêm bài học từ mỗi PR
-- **Prune thường xuyên** — xóa rule mà Claude không vi phạm nữa, gộp rule trùng lặp
-- **Giữ dưới 3.000 từ** — file ngắn và tập trung hiệu quả hơn file dài
-
----
-
-## Tóm Tắt Một Câu
-
-> CLAUDE.md = luật chơi (HOW) + PRD = bối cảnh sản phẩm (WHAT + WHY) + User Stories = việc cần làm (WHAT to build) — ba thứ này cùng nhau giúp AI không chỉ code đúng, mà còn code đúng thứ.

package/docs/PRD.md

@@ -1,141 +0,0 @@
-# Procedure CLI — Product Requirements Document
-
-## 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 from the first commit.
-
-## Problem
-
-1. **Boilerplate burden** — New projects lack consistent structure for CLAUDE.md, PRD, and user stories
-2. **Documentation debt** — Teams postpone critical docs (architecture, requirements, acceptance criteria)
-3. **Inconsistent onboarding** — Each project has different documentation standards and styles
-4. **Time waste** — Developers manually create skeletal docs instead of focusing on code
-5. **Missing context** — New contributors lack centralized product and technical context
-
-## Users
-
-| User | Needs | Value |
-|------|-------|-------|
-| **Solo Developer** | Quick project setup with minimal config | Skip boilerplate, start coding faster |
-| **Team Lead** | Enforce documentation standards across projects | Consistency, faster onboarding, better reviews |
-| **New Contributor** | Understand project decisions and tech stack | Self-serve context, reduced onboarding calls |
-| **Product Manager** | Validate feature set and non-goals early | Clearer scope, better planning |
-
-## Core Features
-
-**F-001: Interactive Project Wizard**
-- 7-step guided setup with Catppuccin Mocha timeline UI
-- `┌`/`└` corners wrap the full flow; animated dot on active step
-- Empty-directory guard: warns when cwd has files and continues — Step 6 overwrite confirmation handles conflicts
-- Validates required fields; ESC exits at any point; Enter exits on completion
-- In-step field navigation: `Tab` = next field, `Shift+Tab` = previous field, `Enter` = confirm; `↑`/`↓` retain their option-navigation role inside selects
-
-**F-002: CLAUDE.md Generation**
-- 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 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
-- 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 defaults
-
-**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
-
-- **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
-
-- IDE/editor integration (intentionally CLI-first)
-- Runtime code generation or plugins
-- 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 6 + React 19 | Interactive terminal rendering |
-| **Templating** | Handlebars | Dynamic file generation |
-| **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 (required), description (required), package manager (select), license (select)
-- Outputs: Project metadata used across all generated files
-
-### Step 2: Stack & Style
-- 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, pre-PR commands (pre-filled if preset chosen)
-- Outputs: Development commands section in CLAUDE.md
-
-### Step 4: Architecture
-- 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, 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
-- 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: 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
-
-- **Adoption:** 100+ monthly runs within 3 months
-- **Time saved:** Average 10+ minutes per project setup
-- **User satisfaction:** 80%+ would recommend to teammates
-- **Documentation quality:** PRDs generated have 90%+ completeness
-- **Consistency:** 95%+ projects follow standard section format
-
-## Open Questions
-
-- 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)?

package/docs/USER-STORIES.md

@@ -1,324 +0,0 @@
-# Procedure CLI — User Stories
-
-## US-001: Full Project Scaffolding
-
-**As a** new project owner
-**I want** to run a single command and answer guided questions
-**So that** I have a complete project with CLAUDE.md, PRD.md, and USER-STORIES.md
-
-### Feature: Complete Wizard Execution
-
-```gherkin
-Scenario: User completes full 7-step wizard
-  Given a developer runs `npx @b3awesome/procedure` in an empty directory
-  When they answer all wizard questions (project info, stack, build, architecture, product context)
-  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 press Enter
-  Then a validation error shows inline
-  And the wizard does not advance until a valid name is entered
-```
-
-```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 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: Pre-flight Directory Check
-
-```gherkin
-Scenario: CLI warns when directory has existing files and continues
-  Given a developer runs `npx @b3awesome/procedure` in a directory with files
-  When the CLI starts
-  Then a warning is printed listing up to 3 found files/directories
-  And a recommendation to use an empty directory is shown
-  And the wizard renders normally so the user can proceed
-  And Step 6 (Generation) will list any files that would be overwritten before confirmation
-```
-
-```gherkin
-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: 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
-
-```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 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-005: Generation Review and Confirmation
-
-**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: Generation Summary Screen
-
-```gherkin
-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
-```
-
-```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
-**So that** stakeholders understand scope without separate meetings
-
-### Feature: Comprehensive PRD Output
-
-```gherkin
-Scenario: PRD includes all required sections
-  Given the user completes Step 5 (Product Context)
-  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-007: User Stories with Gherkin Format
-
-**As a** QA engineer
-**I want** user stories with Gherkin acceptance criteria
-**So that** I can write automated tests and track feature completion
-
-### Feature: Structured User Stories
-
-```gherkin
-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-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-008: Visual Timeline Progress
-
-**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: Timeline Progress Indicator
-
-```gherkin
-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
-```
-
-```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
-
-```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
-```
-
-```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: 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
-```
-
-```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
-```
-
-## US-010: In-Step Field Navigation
-
-**As a** developer who made a typo in a previous field
-**I want** to navigate back and forward between inputs within the current step
-**So that** I can fix mistakes without restarting the step from scratch
-
-### Feature: ↑/↓ Field Navigation
-
-```gherkin
-Scenario: User navigates back to a previous field within a step
-  Given the user is on Step 3 (Build & Test) with "Test command" active
-  When they press Shift+Tab
-  Then "Build command" becomes active again with its previously saved value restored
-  And "Test command" becomes invisible (not yet re-confirmed)
-```
-
-```gherkin
-Scenario: User navigates forward using Tab
-  Given the user has gone back to "Build command" in Step 3
-  When they press Tab
-  Then the current value (typed or previously saved) is kept
-  And "Test command" becomes active again
-```
-
-```gherkin
-Scenario: Tab on a required empty field shows error
-  Given the user is on "Build command" in Step 3
-  And the field is empty with no saved value
-  When they press Tab
-  Then a validation error is shown
-  And the field index does not advance
-```
-
-```gherkin
-Scenario: Navigation hint is shown below each input field
-  Given the user is on any input field within a step
-  When the field renders
-  Then a hint line shows the available navigation keys
-  And "Shift+Tab prev" is omitted when on the first field
-  And "Tab next" is replaced by "Tab / Enter confirm" on the last field
-```
-
-```gherkin
-Scenario: Tab and Shift+Tab work on select fields too
-  Given the user is on "Package manager" select (Step 1)
-  When they press Shift+Tab
-  Then the "Description" text input becomes active again
-  When they press Tab
-  Then the "License" select becomes active
-  And ↑↓ continue to navigate options within the select as normal
-```
-
-```gherkin
-Scenario: Shift+Tab in Setup step navigates between confirm questions
-  Given the user is on the "Initialize git repo?" question in Step 7
-  When they press Shift+Tab
-  Then the "Set up Powerline?" question is shown again
-  And the user can re-answer it
-```
-
-## US-011: Escape and Graceful Exit
-
-**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: 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: 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
-```