CSVibe CLI

CSVibe CLI - GitHub Copilot Vibecoding Workflow

Prerequisites

• Node.js >= 16.0.0 (Download)
• GitHub CLI (gh) (Installation Guide)
• Access to thanhvu0895/csvibe-engine private repository

Installation

Global Installation

npm install -g @thanhvn14/csvibe

Verify Installation

csvibe --version
csvibe --help

Quick Start

1. Authenticate GitHub CLI:

   gh auth login

2. Initialize vibecoding in your project:

   cd my-project
   csvibe init

3. Start coding with AI: Open your project in VSCode and use GitHub Copilot with the installed .agent files.

Commands

csvibe --version

Display CLI version.

$ csvibe --version
csvibe v0.1.0

csvibe --help

Display usage information.

csvibe help

Display detailed help with prerequisites, examples, and documentation links.

csvibe init

Bootstrap vibecoding workflow in your project.

What it does:

1. Validates GitHub CLI authentication and repository access
2. Detects project type (Node.js, Python, Rust, monorepo)
3. Prompts for Jira credentials (interactive)
4. Creates .github/agents/, .github/prompts/, .github/instructions/ directories
5. Downloads agent templates from csvibe-engine repository
6. Generates .csvibe/config.yml with project and Jira configuration
7. Updates .gitignore with CSVibe entries
8. Validates VSCode and GitHub Copilot installation (non-blocking)

Example:

cd my-project
csvibe init

Interactive Prompts:

• Jira URL (e.g., https://company.atlassian.net)
• Jira Email
• Jira API Token (How to create)
• Jira Project Key (e.g., PROJ, QS)

Generated Structure:

my-project/
├── .github/
│   ├── agents/         # Agent templates from csvibe-engine
│   ├── prompts/        # Prompt templates
│   └── instructions/   # Instruction templates
├── .csvibe/
│   ├── config.yml      # Project and Jira configuration
│   ├── state/          # Pipeline state (gitignored)
│   └── cache/          # Cache directory (gitignored)
└── .gitignore          # Updated with CSVibe entries

csvibe scout

Analyze project structure and gather context for AI planning.

What it does:

1. Validates project initialization (.csvibe/state/ must exist)
2. Detects project type (Node.js, Python, Rust, monorepo)
3. Analyzes directory structure (source, tests, config)
4. Extracts dependencies from manifest files
5. Infers tech stack from dependencies
6. Detects build tool from lock files
7. Generates architecture summary
8. Outputs context to .csvibe/state/scout-context.json

Example:

cd my-project
csvibe scout

Custom Output Path:

csvibe scout -o custom-path.json

Output Schema:

{
  "projectType": "node",
  "techStack": ["TypeScript", "React", "Vite"],
  "directories": {
    "source": ["src", "lib"],
    "tests": ["tests"],
    "config": ["."]
  },
  "dependencies": {
    "react": "^18.2.0",
    "typescript": "^5.0.0"
  },
  "buildTool": "npm",
  "architecture": "node with TypeScript, React, Vite"
}

Supported Project Types:

• Node.js: package.json-based projects
• Node.js Monorepo: Projects with pnpm-workspace.yaml, lerna.json, nx.json, or turbo.json
• Python: pyproject.toml, requirements.txt, or Pipfile
• Rust: Cargo.toml projects

Detected Tech Stack:

• Frontend: React, Vue, Angular, Svelte, Next.js, Nuxt
• Backend: Express, Fastify, NestJS, Django, FastAPI, Flask, Actix
• CSS: Tailwind CSS, MUI, Bootstrap
• Databases: PostgreSQL, MongoDB, MySQL, Redis
• Build Tools: Vite, Webpack, Rollup, Turbopack
• Testing: Vitest, Jest, Pytest, Mocha

Build Tool Detection:

• pnpm: pnpm-lock.yaml
• yarn: yarn.lock
• bun: bun.lockb
• npm: package-lock.json (default)
• poetry: poetry.lock
• pipenv: Pipfile.lock
• pip: (default for Python)
• cargo: (Rust projects)

csvibe brainstorm

Generate solution approaches with trade-off analysis using GitHub Copilot Chat.

What it does:

1. Validates project initialization and scout phase completion
2. Prompts for requirement description
3. Guides you to use @brainstorm in GitHub Copilot Chat
4. Watches for approaches.json creation
5. Validates and displays generated approaches
6. Prepares for plan phase

Prerequisites:

• Project initialized with csvibe init
• Scout analysis completed with csvibe scout
• GitHub Copilot extension active in VSCode

Example:

cd my-project
csvibe brainstorm

Workflow:

1. CLI prompts: "What feature or functionality do you want to add?"
2. You answer: "Add JWT authentication"
3. CLI displays Copilot Chat command to run
4. You open Copilot Chat and run: @brainstorm generate approaches for: Add JWT authentication
5. Copilot generates 2-3 approaches with pros/cons
6. You copy JSON output to .csvibe/state/approaches.json
7. CLI validates and displays summary
8. Ready for csvibe plan

Custom Output Path:

csvibe brainstorm -o custom-approaches.json

Output Schema:

{
  "requirement": "Add JWT authentication",
  "approaches": [
    {
      "name": "JWT with Passport.js (Simple)",
      "strategy": "Use existing Passport middleware...",
      "technologies": ["passport", "passport-jwt", "jsonwebtoken"],
      "pros": ["Battle-tested", "Rich ecosystem", "Minimal code"],
      "cons": ["Session complexity", "Cookie security"],
      "effort": "5-8 hours"
    },
    {
      "name": "Custom JWT Middleware (Moderate)",
      "strategy": "Create custom Express middleware...",
      "technologies": ["jsonwebtoken", "bcryptjs"],
      "pros": ["Full control", "Lighter weight", "Easier debugging"],
      "cons": ["More code", "Edge cases", "Security risks"],
      "effort": "8-12 hours"
    }
  ],
  "recommendation": "Approach 1 - best balance of simplicity and robustness"
}

Troubleshooting

Error: gh CLI not found

Solution: Install GitHub CLI:

• macOS: brew install gh
• Windows: winget install GitHub.cli
• Linux: See installation guide

Error: gh CLI not authenticated

Solution: Authenticate:

gh auth login

Follow the prompts to authenticate with your GitHub account.

Error: Cannot access private repository

Possible causes:

1. Repository doesn't exist
2. Your GitHub account lacks access
3. Authentication expired

Solution: Contact repository administrator (@thanhvu0895) for access to csvibe-engine.

Error: Node.js version too old

Solution: Upgrade Node.js to 16+:

• Download: nodejs.org
• nvm: nvm install 16

Development

Setup

git clone <repo>
cd csvibe-cli
npm install
npm run build
npm link  # Test locally

Testing

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Build

npm run build  # Compile TypeScript to dist/

Local Testing

# Link locally
npm link

# Test commands
csvibe --help
csvibe --version
csvibe help

# Unlink when done
npm unlink -g @thanhvn14/csvibe

Project Structure

csvibe-cli/
├── src/
│   ├── index.ts                  # Main CLI orchestrator
│   ├── commands/                 # Command implementations
│   │   ├── help.ts               # Help command
│   │   ├── version.ts            # Version command
│   │   ├── init.ts               # Init command (Story 2)
│   │   └── scout.ts              # Scout command (Story 4)
│   ├── utils/                    # Utilities
│   │   ├── gh-cli.ts             # gh CLI validation
│   │   ├── logger.ts             # Colored output
│   │   ├── errors.ts             # Error handling
│   │   ├── validators.ts         # System validation
│   │   ├── project-detector.ts   # Project type detection (Story 2)
│   │   ├── directory-analyzer.ts # Directory structure analysis (Story 4)
│   │   ├── dependency-analyzer.ts # Dependency extraction (Story 4)
│   │   ├── prompts.ts            # Interactive prompts (Story 2)
│   │   ├── config-generator.ts   # Config file generation (Story 2)
│   │   ├── scaffolder.ts         # Directory scaffolding (Story 2)
│   │   ├── vscode-validator.ts   # VSCode/Copilot validation (Story 2)
│   │   └── downloader.ts         # GitHub asset downloader (Story 2)
│   └── config/
│       └── constants.ts          # Configuration
├── tests/
│   ├── unit/                     # Unit tests
│   │   ├── gh-cli.test.ts
│   │   ├── validators.test.ts
│   │   ├── project-detector.test.ts
│   │   ├── directory-analyzer.test.ts    # Story 4
│   │   ├── dependency-analyzer.test.ts   # Story 4
│   │   ├── config-generator.test.ts
│   │   ├── scaffolder.test.ts
│   │   ├── vscode-validator.test.ts
│   │   └── downloader.test.ts
│   └── integration/              # Integration tests
│       ├── cli.test.ts
│       └── scout-command.test.ts # Story 4
├── bin/
│   └── csvibe.js                 # CLI entry point
└── package.json

Tech Stack

Core

• TypeScript - Type-safe development
• Commander - CLI framework
• Node.js >= 16.0.0

CLI & UI

• chalk - Terminal colors
• ora - Progress spinners
• inquirer - Interactive prompts (Story 2)

File & Config

• fs-extra - Enhanced file operations (Story 2)
• yaml - YAML parsing/generation (Story 2)

Process Execution

• execa - Execute gh CLI commands

Testing

• Vitest - Testing framework
• @vitest/ui - Test UI dashboard

License

MIT © Thanh Vu

Documentation

Full documentation: csvibe-engine repository

Issues

Report issues: GitHub Issues

Status:

• ✅ Story 1 (QS-262) Complete - CLI Installation Package
• ✅ Story 2 (QS-263) Complete - Project Bootstrapping (csvibe init)
• ✅ Story 4 (QS-265) Complete - Scout Phase Implementation (csvibe scout)

Next: Story 5 (QS-266) - Brainstorm Phase Implementation