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 | | Swift iOS (SwiftUI) | Native iOS apps with SwiftUI + Swift concurrency | | Swift macOS (SwiftUI + XcodeGen) | Native macOS apps — SwiftUI + XcodeGen project generation | | Configure manually → | Custom language, framework, and code style |

Coming in v1.5 (planned, see docs/PRD.md F-006 / F-008 / F-009):

| Preset | Best for | |--------|----------| | Android (Kotlin + Compose) | Native Android with Jetpack Compose + Material 3 | | Flutter | Cross-platform mobile/desktop with Dart + Riverpod | | React Native (bare) | Mobile apps without Expo (full native module access) | | Ionic + Capacitor | Hybrid mobile apps reusing web codebase | | Next.js + Supabase | App Router + RSC + RLS scaffolding |

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.

Test command flag is stack-aware (planned v1.5): Vitest/Jest get -t, Go gets -run, pytest gets -k, xcodebuild gets -only-testing. The current generic -- -t "name" is being replaced. Optional E2E test slot lights up only when Playwright is selected as a tech stack chip.

3. Architecture

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

Coming in v1.5: options are filtered by the stack chosen in Step 2 — Bubbletea/Ink preselect Elm Architecture, SwiftUI/Compose preselect MVVM, Next.js App Router preselects "App Router + RSC". Architecture notes are rewritten per (framework × pattern) combo so a TUI project never reads "Controllers handle HTTP".

4. Product Context

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

Coming in v1.5: tech stack chips are regrouped into 8 semantic categories — UI / Data / Cache / Auth / Payments / Observability / AI-MCP / Deploy. Same multi-select UX, no extra step. Each chip selected injects a small targeted section into CLAUDE.md (Auth & RLS stub, rate-limit note, MCP tools section, deployment runbook). Nothing selected → nothing rendered (zero-noise default).

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, /b3awesome-code-fix, and /add-procedure-cli-rule 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

Utility Scripts

procedure-cli-skills-copy.sh

Standalone script to copy all AI agent skills to an existing project generated by Procedure CLI (useful if the project was created before the skill was available, or if Setup was skipped).

What it does:

• Copies /add-procedure-cli-rule skill to Claude Code, Codex CLI, and OpenCode
• Creates required directories if missing
• Skips existing files (safe — never overwrites)
• Provides clear feedback for each agent

Setup:

# Copy script to home directory
cp /path/to/procedure-cli/procedure-cli-skills-copy.sh ~

# Add alias to ~/.zshrc (or ~/.bashrc)
echo "alias pcsc='bash ~/procedure-cli-skills-copy.sh'" >> ~/.zshrc
source ~/.zshrc

Usage:

cd /path/to/your-project
pcsc

# Or explicitly specify destination
~/procedure-cli-skills-copy.sh /path/to/your-project

Output:

📦 Copying add-procedure-cli-rule skill to .
✅ Claude Code: .claude/skills/add-procedure-cli-rule/SKILL.md
✅ Codex CLI: .codex/skills/add-procedure-cli-rule/SKILL.md
✅ OpenCode: .opencode/commands/add-procedure-cli-rule.md
✨ Done!

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