Universal Development Standards

# Universal Development Standards

> **Language**: English | [繁體中文](locales/zh-TW/README.md) | [简体中文](locales/zh-CN/README.md)

**Version**: 3.5.0
**Last Updated**: 2026-01-15
**License**: [Dual License](LICENSE) (CC BY 4.0 + MIT)

### What's New in 3.5.0

| Feature | Description |
|---------|-------------|
| **Multi-Agent Skills** | Install Skills to multiple AI agents simultaneously |
| **Gemini CLI TOML** | Auto-convert commands to TOML format for Gemini CLI |
| **i18n Support** | CLI supports EN, ZH-TW, ZH-CN with auto-detection |
| **9 AI Tools** | Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, Antigravity, Codex, OpenCode, Gemini CLI |
| **18 Core Standards** | New `ai-instruction-standards.md` |
| **Interactive Commands** | `/init`, `/config`, `/update` use AskUserQuestion |
| **Methodology System** 🧪 | TDD/BDD/SDD/ATDD workflows (experimental) |

> 🧪 = Experimental feature - requires `-E` flag, will be redesigned in v4.0

---

## Purpose

This repository provides **language-agnostic, framework-agnostic, domain-agnostic** documentation standards for software projects. These standards ensure consistency, quality, and maintainability across diverse technology stacks.

---

## Quick Start

### Install via npm (Recommended)

```bash
# Install globally
npm install -g universal-dev-standards

# Initialize your project
uds init
```

### Or use npx (No installation required)

```bash
npx universal-dev-standards init
```

### Manual Setup

Copy essential standards to your project:

```bash
cp core/anti-hallucination.md your-project/.standards/
cp core/checkin-standards.md your-project/.standards/
cp core/commit-message-guide.md your-project/.standards/
```

> **Important**: Copying standards alone won't enable AI assistance. You must also reference them in your AI tool's configuration file (e.g., `CLAUDE.md`, `.cursorrules`). Use `uds init` for automatic configuration.

### AI Tool Extensions (Optional)

After installing UDS, optionally enable AI-assisted features for your preferred tools:

| AI Tool | Configuration | Skills | Commands |
|---------|--------------|:------:|:--------:|
| Claude Code | `uds init` → `CLAUDE.md` | ✅ Marketplace / File | Built-in |
| OpenCode | `uds init` → `AGENTS.md` | ✅ `.opencode/skill/` | ✅ `.opencode/command/` |
| Cline | `uds init` → `.clinerules` | ✅ `.cline/skills/` | - |
| Roo Code | `uds init` → `.roorules` | ✅ `.roo/skills/` | ✅ `.roo/commands/` |
| OpenAI Codex | `uds init` → `AGENTS.md` | ✅ `.codex/skills/` | - |
| GitHub Copilot | `uds init` → `copilot-instructions.md` | ✅ `.github/skills/` | ✅ `.github/prompts/` |
| Windsurf | `uds init` → `.windsurfrules` | ✅ `.windsurf/skills/` | - |
| Gemini CLI | `uds init` → `GEMINI.md` | ✅ `.gemini/skills/` | ✅ `.gemini/commands/` (TOML) |
| Cursor | `uds init` → `.cursorrules` | ❌ Rules only | - |
| Google Antigravity | `uds init` → `INSTRUCTIONS.md` | - | - |

> **New in v3.5.0**: `uds init` supports multi-agent Skills installation. Select multiple agents to install Skills simultaneously. Gemini CLI commands are auto-converted to TOML format.

---

## Installation Methods

### CLI Tool (Primary Installation)

The CLI tool is the primary way to adopt UDS in your projects.

**npm (Recommended)**
```bash
npm install -g universal-dev-standards
uds init    # Interactive initialization
uds check   # Check adoption status
uds update  # Update to latest version
uds skills  # List installed skills
```

**npx (No installation)**
```bash
npx universal-dev-standards init
```

**Beta Version (Latest Features)**
```bash
# Install beta globally
npm install -g universal-dev-standards@beta

# Or use specific version
npm install -g universal-dev-standards@3.5.0-beta.13

# Or via npx
npx universal-dev-standards@beta init
```

> **Note**: Beta versions include experimental features like the Methodology System (`/methodology`, `/bdd`, `/tdd`). These features will be redesigned in v4.0. See [Feature Availability](#feature-availability) for details.

**Clone and Link (Development)**

macOS / Linux:
```bash
git clone https://github.com/AsiaOstrich/universal-dev-standards.git
cd universal-dev-standards/cli && npm install && npm link
```

Windows (PowerShell):
```powershell
git clone https://github.com/AsiaOstrich/universal-dev-standards.git
cd universal-dev-standards\cli; npm install; npm link
```

See [CLI README](cli/README.md) for detailed usage, [Windows Guide](docs/WINDOWS-GUIDE.md) for Windows-specific instructions, and [Operation Workflow](docs/OPERATION-WORKFLOW.md) for project maintenance and development workflow.

---

### AI Tool Configuration

Each AI tool uses a configuration file for project-specific rules. `uds init` generates these automatically:

| Tool | Configuration File | Location |
|------|-------------------|----------|
| Claude Code | `CLAUDE.md` | Project root |
| OpenCode | `AGENTS.md` | Project root |
| OpenAI Codex | `AGENTS.md` | Project root |
| Cursor | `.cursorrules` | Project root |
| Windsurf | `.windsurfru

... (truncated)