procedure-cli 0.1.0

package/dist/steps/project-info.js

@@ -0,0 +1,61 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { Text } from "ink";
+import { TextInput } from "@inkjs/ui";
+import { GutterLine } from "../components/gutter-line.js";
+import { GutteredSelect } from "../components/guttered-select.js";
+const STEP_ORDER = [
+    "projectName",
+    "description",
+    "packageManager",
+    "license",
+];
+const PACKAGE_MANAGER_OPTIONS = [
+    { label: "npm", value: "npm" },
+    { label: "pnpm", value: "pnpm" },
+    { label: "bun", value: "bun" },
+    { label: "yarn", value: "yarn" },
+];
+const LICENSE_OPTIONS = [
+    { label: "MIT — Permissive, allows commercial use", value: "MIT" },
+    { label: "ISC — Simplified MIT, minimal restrictions", value: "ISC" },
+    { label: "Apache-2.0 — Permissive with patent protection", value: "Apache-2.0" },
+    { label: "GPL-3.0 — Copyleft, requires source disclosure", value: "GPL-3.0" },
+    { label: "Unlicense — Public domain, no restrictions", value: "Unlicense" },
+];
+export default function ProjectInfo({ onComplete }) {
+    const [stepIndex, setStepIndex] = useState(0);
+    const [answers, setAnswers] = useState({});
+    const [error, setError] = useState("");
+    const currentStep = STEP_ORDER[stepIndex];
+    function advance(key, value) {
+        const next = { ...answers, [key]: value };
+        setAnswers(next);
+        setError("");
+        if (stepIndex < STEP_ORDER.length - 1) {
+            setStepIndex(stepIndex + 1);
+        }
+        else {
+            onComplete(next);
+        }
+    }
+    function handleTextSubmit(value) {
+        const val = value.trim();
+        if (!val) {
+            setError(currentStep === "projectName"
+                ? "Project name is required"
+                : "Description is required");
+            return;
+        }
+        advance(currentStep, val);
+    }
+    function handleSelectChange(key) {
+        return (value) => {
+            advance(key, value);
+        };
+    }
+    // Render completed fields
+    const completed = STEP_ORDER.slice(0, stepIndex).map((key) => (_jsx(GutterLine, { children: _jsxs(Text, { dimColor: true, children: [key === "projectName" && `Project name: ${answers[key]}`, key === "description" && `Description: ${answers[key]}`, key === "packageManager" && `Package manager: ${answers[key]}`, key === "license" && `License: ${answers[key]}`] }) }, key)));
+    return (_jsxs(_Fragment, { children: [completed, currentStep === "projectName" && (_jsxs(GutterLine, { children: [_jsx(Text, { bold: true, children: "Project name: " }), _jsx(TextInput, { placeholder: "...", onSubmit: handleTextSubmit })] })), currentStep === "description" && (_jsxs(GutterLine, { children: [_jsx(Text, { bold: true, children: "One-line description: " }), _jsx(TextInput, { placeholder: "...", onSubmit: handleTextSubmit })] })), currentStep === "packageManager" && (_jsxs(_Fragment, { children: [_jsx(GutterLine, { children: _jsx(Text, { bold: true, children: "Package manager:" }) }), _jsx(GutteredSelect, { options: PACKAGE_MANAGER_OPTIONS, onChange: handleSelectChange("packageManager") })] })), currentStep === "license" && (_jsxs(_Fragment, { children: [_jsx(GutterLine, { children: _jsx(Text, { bold: true, children: "License:" }) }), _jsx(GutteredSelect, { options: LICENSE_OPTIONS, onChange: handleSelectChange("license") })] })), error && (_jsx(GutterLine, { children: _jsx(Text, { color: "red", children: error }) }))] }));
+}
+//# sourceMappingURL=project-info.js.map

package/dist/steps/project-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-info.js","sourceRoot":"","sources":["../../src/steps/project-info.tsx"],"names":[],"mappings":"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"}

package/dist/steps/stack-style.d.ts

@@ -0,0 +1,6 @@
+import type { WizardAnswers } from "../lib/types.js";
+interface Props {
+    onComplete: (answers: Partial<WizardAnswers>) => void;
+}
+export default function StackStyle({ onComplete }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/steps/stack-style.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Text } from "ink";
+import { TextInput } from "@inkjs/ui";
+import { GutterLine } from "../components/gutter-line.js";
+import { GutteredSelect } from "../components/guttered-select.js";
+const PRESET_OPTIONS = [
+    { label: "TypeScript + Node.js", value: "typescript-node" },
+];
+const ADVANCED_FIELDS = [
+    { key: "language", label: "Language" },
+    { key: "framework", label: "Framework" },
+    { key: "codeStyle", label: "Code style conventions (comma-separated)" },
+];
+const PRESETS = {
+    "typescript-node": {
+        language: "TypeScript",
+        framework: "Node.js",
+        codeStyle: [
+            "TypeScript strict mode, ESM imports",
+            "camelCase for variables, PascalCase for types",
+            "stdlib -> external -> internal import ordering",
+            "Return errors, don't throw",
+        ],
+        buildCommand: "npm run build",
+        testCommand: "npm run test",
+        typecheckCommand: "npm run typecheck",
+        lintCommand: "npm run lint",
+    },
+};
+export default function StackStyle({ onComplete }) {
+    const [mode, setMode] = useState("choosing");
+    const [advancedIndex, setAdvancedIndex] = useState(0);
+    const [answers, setAnswers] = useState({});
+    if (mode === "choosing") {
+        return (_jsxs(_Fragment, { children: [_jsx(GutterLine, { children: _jsx(Text, { bold: true, children: "Setup mode:" }) }), _jsx(GutteredSelect, { options: [
+                        { label: "QuickStart (use a preset)", value: "quickstart" },
+                        { label: "Advanced (manual config)", value: "advanced" },
+                    ], onChange: (val) => setMode(val) })] }));
+    }
+    if (mode === "quickstart") {
+        return (_jsxs(_Fragment, { children: [_jsx(GutterLine, { children: _jsx(Text, { bold: true, children: "Select a stack preset:" }) }), _jsx(GutteredSelect, { options: PRESET_OPTIONS, onChange: (val) => {
+                        const preset = PRESETS[val];
+                        if (preset) {
+                            onComplete(preset);
+                        }
+                    } })] }));
+    }
+    // Advanced mode
+    const current = ADVANCED_FIELDS[advancedIndex];
+    function handleSubmit(value) {
+        const next = { ...answers, [current.key]: value };
+        setAnswers(next);
+        if (advancedIndex < ADVANCED_FIELDS.length - 1) {
+            setAdvancedIndex(advancedIndex + 1);
+        }
+        else {
+            onComplete({
+                language: next.language,
+                framework: next.framework,
+                codeStyle: (next.codeStyle || "").split(",").map((s) => s.trim()),
+            });
+        }
+    }
+    return (_jsxs(_Fragment, { children: [ADVANCED_FIELDS.slice(0, advancedIndex).map((f) => (_jsx(GutterLine, { children: _jsxs(Text, { dimColor: true, children: [f.label, ": ", answers[f.key]] }) }, f.key))), _jsxs(GutterLine, { children: [_jsxs(Text, { bold: true, children: [current.label, ": "] }), _jsx(TextInput, { placeholder: "...", onSubmit: handleSubmit })] })] }));
+}
+//# sourceMappingURL=stack-style.js.map

package/dist/steps/stack-style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-style.js","sourceRoot":"","sources":["../../src/steps/stack-style.tsx"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,206 @@
+---
+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

@@ -0,0 +1,130 @@
+# 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.
+
+## 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 timeline progress view
+- Validates input, provides sensible defaults
+- Timeline preview shows estimated completion time
+
+**F-002: CLAUDE.md Generation**
+- Code style and import conventions
+- Build & test commands
+- Architecture decisions and rationale
+- Workflow guidance (planning, verification, bug fixing)
+- 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
+
+**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.)
+
+**F-005: Environment & Config Files**
+- `.env.example` template with user-specified variables
+- `.gitignore` with language/framework-specific rules
+
+**F-006: Powerline Integration (Optional)**
+- Shell prompt styling and configuration
+- Powerline font detection and fallbacks
+- Theme color selection during setup
+
+### 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
+
+## Non-Goals
+
+- IDE/editor integration (intentionally CLI-first)
+- Runtime code generation or plugins
+- Database schema generation
+- Frontend component scaffolding
+- Package template marketplace
+
+## Tech Stack
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| **Runtime** | Node.js + TypeScript | Type-safe CLI |
+| **UI** | Ink + React | Interactive CLI rendering |
+| **Templating** | Handlebars | Dynamic file generation |
+| **AI** | ai-sdk + OpenAI | Future: GPT-assisted prompts (optional) |
+| **Build** | tsc | Minimal, fast compilation |
+
+## 7 Wizard Steps (Detailed)
+
+### Step 1: Project Info
+- Inputs: Project name, description, package manager preference, license
+- Output: Basic project metadata
+
+### Step 2: Stack & Style
+- Inputs: Language, framework, code style (strict mode, imports, naming, error handling)
+- Output: Stack summary and style guide anchors
+
+### Step 3: Build & Test
+- Inputs: Build, test, typecheck, lint, PR check commands
+- Output: Development commands for CLAUDE.md
+
+### Step 4: Architecture
+- Inputs: Architecture pattern, architectural decisions, detailed notes
+- Output: Architecture section for CLAUDE.md
+
+### 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
+
+### 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
+
+### Step 7: Powerline (Optional)
+- Inputs: Enable powerline, font selection, theme colors
+- Output: Shell configuration and setup instructions
+
+## 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)?
+- Auto-generate user stories from feature descriptions?
+- 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

@@ -0,0 +1,181 @@
+# 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 procedure-cli`
+  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
+```
+
+```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
+```
+
+## US-002: Quick Start Mode
+
+**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
+
+### Feature: QuickStart Shortcuts
+
+```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
+```
+
+## US-003: Advanced Configuration
+
+**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
+
+### 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
+```
+
+## US-004: Powerline Setup Integration
+
+**As a** shell enthusiast
+**I want** to configure powerline font and prompt styling during setup
+**So that** my terminal matches my project's branding
+
+### Feature: Shell Prompt Customization
+
+```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
+```
+
+## US-005: PRD Generation with Features
+
+**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 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 |
+```
+
+## US-006: 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 include Given/When/Then
+  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
+```
+
+## US-007: Git Initialization
+
+**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
+
+### Feature: Git Setup
+
+```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"
+```
+
+## US-008: Partial Scaffolding & Regeneration
+
+**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
+
+### Feature: Selective Regeneration
+
+```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
+```
+
+## US-009: Visual Timeline with Estimated Completion
+
+**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
+
+### Feature: Timeline Progress Indicator
+
+```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
+```
+
+```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
+```