npm package: @onion-ai/cli
Description: The Onion Framework - AI-powered development workflow system for Claude Code
Author: David
Latest version: 1.0.0-beta.1

# Onion Framework

AI-powered development workflow system for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

Onion provides **88 commands**, **45 specialized agents**, and **8 skills** that guide you through the entire software development lifecycle — from collecting requirements to shipping features.

## Quick Start

```bash
# Install the framework globally
npx @onion-ai/cli install

# Configure your project
npx @onion-ai/cli init
```

The `install` step adds 88 commands, 45 agents, and 8 skills to Claude Code. The `init` step creates a `.onion/` directory in your project with task manager settings, API keys, and team preferences.

## What It Does

Onion structures your development workflow into clear phases:

```
Collect → Refine → Spec → Plan → Build → Test → PR → Ship
```

Each phase has dedicated commands and agents that handle the heavy lifting:

| Phase | Commands | What happens |
|-------|----------|-------------|
| **Requirements** | `/onion:product:collect` → `/onion:product:refine` → `/onion:product:spec` | Gather ideas, clarify requirements, write specifications |
| **Planning** | `/onion:product:task` → `/onion:engineer:plan` | Create structured tasks, plan implementation |
| **Development** | `/onion:engineer:start` → `/onion:engineer:work` | Start features, continue work with session context |
| **Quality** | `/onion:engineer:pre-pr` → `/onion:test:unit` | Pre-PR validation, run tests |
| **Delivery** | `/onion:engineer:pr` → `/onion:git:feature:finish` | Create PRs, merge features |
| **Documentation** | `/onion:docs:build-tech-docs` → `/onion:docs:build-business-docs` | Generate technical and business documentation |

## Installation

### Prerequisites

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured
- [Node.js](https://nodejs.org/) >= 18
- [Git](https://git-scm.com/)

### Install

```bash
npx @onion-ai/cli install
```

### Verify

```bash
npx @onion-ai/cli doctor
```

Output:

```
Onion Framework Health Check

  → Checking prerequisites...
  ✓ Claude Code config directory exists
  ✓ Claude Code CLI available
  ✓ Git available
  ✓ Node.js v22.16.0 (>= 18 required)

  → Checking installation...
  ✓ Framework home exists (~/.claude/onion/)
  ✓ Version 1.0.0-beta.1 installed on 2026-02-28
  ✓ 88 commands installed → /onion:*
  ✓ 45 agents installed
  ✓ 8 skills installed (onion-* prefix)
  ✓ CLAUDE.md integration active
  ✓ 46 documentation files available

All checks passed!
  ✓ Onion Framework is healthy and ready to use
```

### Update

```bash
npx @onion-ai/cli update
```

### Uninstall

```bash
npx @onion-ai/cli uninstall
```

Clean removal — restores your `~/.claude/CLAUDE.md` and removes all framework files.

## Project Configuration

After installing the framework globally, configure each project with:

```bash
npx @onion-ai/cli init
```

This creates a `.onion/` directory in your project root:

```
<your-project>/
└── .onion/
    ├── config.yaml       ← Team settings (commit this)
    ├── .env              ← API keys and secrets (gitignored)
    └── .env.example      ← Template for team onboarding (commit this)
```

### Interactive Setup

The `init` command walks you through configuration:

```
? Which task manager does this project use?
  1) ClickUp — via MCP integration
  2) Jira — via API
  3) Linear — via API
  4) Asana — via MCP integration
  5) None — offline mode

? Documentation and comments language?
  1) English
  2) Portuguese (Brazil)
  3) Spanish

? Git workflow for this project?
  1) GitFlow — feature/release/hotfix branches
  2) GitHub Flow — feature branches from main
  3) Trunk-based — short-lived branches

? Enable Gamma.app integration (presentations)? (y/N)
? Enable automated code review? (Y/n)
```

### config.yaml

Committable settings shared across the team:

```yaml
version: "1.0"

task_manager:
  provider: clickup
  workspace_id: "12345"
  default_list: "67890"

language:
  code: en
  docs: pt-BR
  commits: pt-BR

git:
  flow: gitflow
  main_branch: main
  develop_branch: develop

integrations:
  gamma:
    enabled: false
  code_review:
    enabled: true
```

### .env

Secrets that stay local (auto-added to `.gitignore`):

```bash
CLICKUP_API_TOKEN=pk_your_token_here
# or JIRA_API_TOKEN=, LINEAR_API_KEY=, ASANA_API_TOKEN=
```

### Team Onboarding

New team members clone the repo and run:

```bash
cp .onion/.env.example .onion/.env
# Fill in API keys
npx @onion-ai/cli doctor
```

## Commands

All commands are prefixed with `onion:` so they don't conflict with your own commands or other tools.

### Entry Points

| Command | Description |
|---------|-------------|
| `/onion` | Intelligent entry point — ask anything about the framework |
| `/onion:warm-up` | Load project context and prepare for work |

### Product

| Command | Description |
|---------|-------------|
| `/onion:product:collect` | Collect feature ideas or bug reports |
| `/onion:product:refine` | Refine requirements through clarification questions |
| `/onion:product:spec` | Create product specification from requirements |
| `/onion:product:task` | Create structured tasks with subtasks and action items |
| `/onion:product:feature` | Create feature tasks for planning and backlog |
| `/onion:product:estimate` | Story point estimation |
| `/onion:product:check` | Verify requirements against project meta-specs |
| `/onion:product:validate-task` | Validate existing tasks |
| `/onion:product:light-arch` | Lightweight architecture design for features |
| `/onion:product:branding` | Branding and positioning analysis |
| `/onion:product:analyze-pain-price` | Customer pain and pricing analysis |
| `/onion:product:presentation` | Generate presentations via Gamma.app |
| `/onion:product:extract-meeting` | Extract structured knowledge from meeting transcripts |
| `/onion:product:consolidate-meetings` | Consolidate multiple meetings into strategic insights |

### Engineering

| Command | Description |
|---------|-------------|
| `/onion:engineer:start` | Start feature development — creates session, analyzes tasks |
| `/onion:engineer:plan` | Plan feature implementation with structured approach |
| `/onion:engineer:work` | Continue work on active feature with session context |
| `/onion:engineer:pre-pr` | Pre-PR validation — checks patterns and quality |
| `/onion:engineer:pr` | Create Pull Request with GitFlow integration |
| `/onion:engineer:pr-update` | Update existing PR with additional changes |
| `/onion:engineer:hotfix` | Emergency workflow: task + hotfix branch + development |
| `/onion:engineer:docs` | Invoke documentation agent for current branch |
| `/onion:engineer:bump` | Semantic version bump (major, minor, patch) |
| `/onion:engineer:warm-up` | Load project context for engineering work |

### Git

| Command | Description |
|---------|-------------|
| `/onion:git:feature:start` | Start GitFlow feature branch |
| `/onion:git:feature:finish` | Finish feature with merge to develop |
| `/onion:git:feature:publish` | Publish feature branch to remote |
| `/onion:git:hotfix:start` | Start hotfix branch for production fixes |
| `/onion:git:hotfix:finish` | Finish hotfix with merge to main and develop |
| `/onion:git:release:start` | Start release branch with versioning |
| `/onion:git:release:finish` | Finish release with merge, tag, and publish |
| `/onion:git:fast-commit` | Quick commit for typical workflow changes |
| `/onion:git:sync` | Sync with remote using GitFlow conventions |
| `/onion:git:code-review` | Setup and manage automated code review |
| `/onion:git:init` | Initialize repository with GitFlow conventions |

### Documentation

| Command | Description |
|---------|-------------|
| `/onion:docs:build-tech-docs` | Generate comprehensive technical documentation |
| `/onion:docs:build-business-docs` | Generate business context and strategy docs |
| `/onion:docs:build-compliance-docs` | Generate compliance documentation (ISO 27001, SOC2, etc.) |
| `/onion:docs:reverse-consolidate` | Reverse-engineer project documentation |
| `/onion:docs:validate-docs` | Validate documentation completeness |
| `/onion:docs:docs-health` | Documentation health check |
| `/onion:docs:build-index` | Manage and update documentation indexes |
| `/onion:docs:refine-vision` | Refine product/project vision and strategy |

### Testing

| Command | Description |
|---------|-------------|
| `/onion:test:unit` | Unit test generation and execution |
| `/onion:test:integration` | Integration test workflows |
| `/onion:test:e2e` | End-to-end test workflows |

### Validation

| Command | Description |
|---------|-------------|
| `/onion:validate:workflow` | Validate workflow completeness |
| `/onion:validate:test-strategy:create` | Create test strategy |
| `/onion:validate:test-strategy:analyze` | Analyze existing test strategy |
| `/onion:validate:qa-points:estimate` | QA story points estimation |
| `/onion:validate:collab:three-amigos` | Three Amigos collaboration session |
| `/onion:validate:collab:pair-testing` | Pair testing session |

### Meta

| Command | Description |
|---------|-------------|
| `/onion:meta:create-agent` | Create new AI agents for the framework |
| `/onion:meta:create-command` | Create new commands |
| `/onion:meta:create-knowledge-base` | Create structured knowledge bases via research |
| `/onion:meta:create-abstraction` | Create abstraction layers |
| `/onion:meta:analyze-complex-problem` | Structured analysis of complex problems |
| `/onion:meta:setup-integration` | Configure task manager and API integrations |

## Agents

Onion includes 45 specialized agents organized by domain:

| Category | Agents | Examples |
|----------|--------|---------|
| **Development** (17) | Full-stack specialists | React, Node.js, Nx monorepo, Docker, Mermaid diagrams |
| **Product** (8) | Product workflow | Product management, storytelling, branding, meeting extraction |
| **Compliance** (5) | Standards and audit | ISO 27001, SOC2, PMBOK, corporate compliance |
| **Meta** (4) | Framework management | Agent creator, command creator, gate keeper, onion orchestrator |
| **Git** (4) | Branch operations | Code review, documentation, test planning, metaspec checking |
| **Testing** (3) | Quality assurance | Test agent, test engineer, test planner |
| **Review** (2) | Code quality | Code reviewer, compliance reviewer |
| **Deployment** (1) | Infrastructure | Docker specialist |
| **Research** (1) | Investigation | Multi-source research and analysis |

Use `@onion` to access the master orchestrator that knows all agents and can route your request to the right specialist.

## Skills

| Skill | Description |
|-------|-------------|
| `onion-codebase-visualizer` | Interactive collapsible tree visualization of your codebase |
| `onion-db-schema-visualizer` | ERD generation from Prisma, TypeORM, or raw SQL |
| `onion-collect` | Structured feature idea and bug collection |
| `onion-create-prd` | Product Requirements Document creation |
| `onion-refine-prd` | PRD refinement and improvement |
| `onion-create-rule` | Claude Code rule creation with best practices |
| `onion-sync-meetings` | Meeting transcript synchronization |

## Task Manager Integration

Onion supports multiple task management providers through an abstraction layer:

| Provider | Status | Detection |
|----------|--------|-----------|
| **ClickUp** | Supported (via MCP) | 9-char alphanumeric task IDs |
| **Asana** | Supported (via MCP) | 15+ digit numeric IDs |
| **Linear** | Supported (via API) | Custom prefix IDs (e.g., ABC-123) |
| **None** | Offline mode | Local-only task tracking |

Configure your provider with `onion init` or by editing `.onion/config.yaml`.

## Workflows

### Feature Development (most common)

```
/onion:product:task          # Create the task
/onion:engineer:start        # Start development session
/onion:engineer:work         # Continue working (resume context)
/onion:engineer:pre-pr       # Validate before PR
/onion:engineer:pr           # Create the Pull Request
```

### Hotfix (urgent production fix)

```
/onion:engineer:hotfix       # Creates task + hotfix branch + starts dev
/onion:engineer:work         # Fix the issue
/onion:engineer:pr           # Create PR
/onion:git:hotfix:finish     # Merge to main and develop
```

### New Project Setup

```
onion init                       # Configure project (.onion/)
/onion:warm-up               # Load project context
/onion:product:collect       # Collect initial requirements
/onion:product:check         # Verify requirements
/onion:product:refine        # Refine through questions
/onion:docs:build-business-docs  # Generate business docs
/onion:docs:build-tech-docs      # Generate tech docs
/onion:product:spec          # Write specifications
/onion:product:light-arch    # Design architecture
/onion:product:task          # Create tasks
/onion:engineer:start        # Begin development
```

### Documentation

```
/onion:docs:build-tech-docs      # Technical documentation
/onion:docs:build-business-docs  # Business documentation
/onion:docs:build-compliance-docs # Compliance docs
/onion:docs:build-index          # Update indexes
```

## How It Works

### Installation Layout

When you run `onion install`, the framework installs into your Claude Code global config:

```
~/.claude/
├── commands/
│   └── onion/              ← 88 commands (accessible as /onion:*)
│       ├── product/
│       ├── engineer/
│       ├── git/
│       ├── docs/
│       ├── test/
│       └── ...
├── agents/
│   └── onion/              ← 45 specialized agents
│       ├── development/
│       ├── product/
│       ├── compliance/
│       └── ...
├── skills/
│   ├── onion-codebase-visualizer/
│   ├── onion-collect/
│   └── ...                 ← 8 skills (onion- prefix)
├── onion/                  ← Framework home
│   ├── CLAUDE.md           ← Framework entry point
│   ├── docs/               ← Reference documentation
│   ├── utils/              ← Task manager abstraction, utilities
│   ├── rules/              ← Default rules and patterns
│   └── manifest.json       ← Installation metadata
└── CLAUDE.md               ← Patched to load framework
```

### Namespacing

- **Commands** use the `onion:` prefix: `/onion:product:task`, `/onion:engineer:start`
- **Skills** use the `onion-` prefix: `onion-codebase-visualizer`, `onion-collect`
- **Agents** live under `onion/` namespace

This prevents conflicts with your own commands, skills, or other frameworks.

### Non-Destructive

- Install patches `~/.claude/CLAUDE.md` with a clearly marked block
- Uninstall removes only Onion files and restores CLAUDE.md
- Your existing Claude Code configuration is never overwritten

## CLI Reference

```
Usage: onion [options] [command]

Options:
  -V, --version        output the version number
  -h, --help           display help for command

Commands:
  install [options]    Install the Onion Framework into ~/.claude/
  uninstall [options]  Remove the Onion Framework from ~/.claude/
  init [options]       Initialize project configuration (.onion/)
  doctor               Check installation health and prerequisites
  update               Update the Onion Framework to the latest version
  list [options]       List installed framework components
```

### `onion install`

```
Options:
  --force     Overwrite existing installation
  --dry-run   Show what would be installed without making changes
```

### `onion init`

```
Options:
  --force     Overwrite existing .onion/ configuration
```

Interactive setup that creates `.onion/config.yaml` (team settings) and `.onion/.env` (secrets). Automatically patches `.gitignore` to exclude `.onion/.env`.

### `onion uninstall`

```
Options:
  --keep-config   Keep user customizations in ~/.claude/onion/config/
```

### `onion list`

```
Options:
  --commands   List only commands
  --agents     List only agents
  --skills     List only skills
```

## Development

### Project Structure

```
├── bin/onion.js              # CLI entry point
├── src/
│   ├── cli.js                # Command router (Commander.js)
│   ├── commands/             # CLI command implementations
│   └── utils/                # Shared utilities
├── framework/                # Publishable framework files (auto-generated)
├── scripts/
│   └── sync-framework.js     # Syncs .claude/ → framework/
├── .claude/                  # Development source (working copy)
└── package.json
```

### Building

The `framework/` directory is auto-generated from `.claude/`:

```bash
npm run sync
```

This runs automatically before `npm publish`.

### Adding New Commands

1. Create the command in `.claude/commands/<category>/<name>.md`
2. Run `npm run sync` to update `framework/`
3. Run `onion install --force` to test locally

### Adding New Agents

1. Create the agent in `.claude/agents/<category>/<name>.md`
2. Run `npm run sync` to update `framework/`
3. Run `onion install --force` to test locally

## Requirements

- **Node.js** >= 18 (required)
- **Git** (required for GitFlow commands)
- **Claude Code** (required — this is a Claude Code framework)
- **Python 3** (optional — only needed for specific commands)

## License

MIT