Onion Framework

AI-powered development workflow system for 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

# 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 installed and configured
• Node.js >= 18
• Git

Install

npx @onion-ai/cli install

Verify

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

npx @onion-ai/cli update

Uninstall

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:

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:

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

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:

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

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