Procedure CLI

Interactive CLI wizard that scaffolds new projects with a battle-tested CLAUDE.md, PRD, user stories, and optional tooling setup. Inspired by Skills.sh visual style.

Getting Started

mkdir my-project && cd my-project
npx @b3awesome/procedure

If the directory already has files, the CLI shows an interactive prompt to Continue or Exit. If you continue, existing files that would be overwritten are listed explicitly in Step 5 (Generation) before you confirm.

What It Generates

| File | Purpose | |------|---------| | CLAUDE.md | AI-ready development guide with architecture, code style, and workflow | | AGENTS.md | Tool-agnostic AI agent instructions (open standard, works with Copilot, Codex, Cursor, etc.) | | README.md | Project overview with quick start, tech stack, and docs links | | 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 | Language/framework-appropriate git ignore defaults |

Visual Style

Catppuccin Mocha color theme with a Skills.sh-inspired vertical timeline:

█▀█ █▀█ █▀█ █▀▀ █▀▀ █▀▄ █ █ █▀█ █▀▀
█▀▀ █▀▄ █ █ █   █▀▀ █ █ █ █ █▀▄ █▀▀
▀   ▀ ▀ ▀▀▀ ▀▀▀ ▀▀▀ ▀▀  ▀▀▀ ▀ ▀ ▀▀▀
Bootstrap any project with a battle-tested
CLAUDE.md, PRD, user stories, and powerline.
───────────────────────────────────────────
┌
│ ◇  Project Info
│    my-app — A task management tool
│
│ ◆  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
│
│ ○  Architecture
│
│ ○  Product Context
│
│ ○  Generation
│
│ ○  Setup
└

| 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 |

In-Step Navigation

Within any active step, you can navigate between its input fields without restarting the step:

| Key | Action | |-----|--------| | Tab | Go to the next field (saves current value) | | Shift+Tab | Go to the previous field (restores saved value) | | Enter | Confirm current field and advance |

↑/↓ retain their original role: navigating options within a select or multi-select. They are never used for field-to-field navigation.

The 6 Wizard Steps

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 | | Go TUI + Bubbletea | Terminal UIs, interactive CLIs, wizard tools (Bubbletea + Bubbles ecosystem) | | Ink TUI | Terminal UIs with Ink + React (Node.js) — includes UI/UX guideline and tech specs docs | | Configure manually → | Custom language, framework, and code style |

Build/test/typecheck/lint/PR commands are auto-derived from the selected preset or language+framework — no manual entry needed. They are shown as read-only in Step 5 (Generation) before you confirm.

3. Architecture

Select from 7 patterns (Monolith, MVC, Feature folders, Hexagonal, Microservices, Event-driven, Monorepo). Architecture notes are auto-generated from the chosen pattern.

4. Product Context

Problem statement, target users, tech stack (multi-select, prefilled from Step 2; Bubbletea preset also preselects Lipgloss + Bubbles), core features (multi-select with custom input), non-goals.

5. Generation

Full summary of all collected inputs including auto-derived build commands. Warns about any files that will be overwritten. Confirm to write files or skip.

6. 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
• Code review skills — installs /b3awesome-code-review and /b3awesome-code-fix slash commands for Claude Code, Codex CLI, and OpenCode; creates CODE-REVIEW.md and CODE-FIXED.md append-only log templates; places an archive script in scripts/ for compacting resolved entries

UI Components

| Component | File | Purpose | |-----------|------|---------| | 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

| 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

npm run dev              # Run CLI directly via tsx
npm run build            # Compile to dist/
npm run typecheck        # Type check only

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

Two append-only logs track review/fix cycles:

• CODE-REVIEW.md — findings (CR-YYYYMMDD-###)
• CODE-FIXED.md — fix actions (CF-YYYYMMDD-###)

Verification standard after fixes: npm run typecheck + npm run build.

Documentation

• CLAUDE.md — Development guide
• docs/PRD.md — Product requirements
• docs/USER-STORIES.md — User stories and acceptance criteria
• docs/GIAI-THICH-CLAUDE-MD.md — 4-layer CLAUDE.md methodology (Vietnamese)

License

ISC