Package Exports

@ai-eng-system/cli

Readme

AI Engineering System

Advanced development tools with context engineering, research orchestration, and 28 specialized agents for Claude Code & OpenCode.

🚀 Quick Start

Spec-Driven Development (Recommended)

This toolkit follows spec-driven development methodology from GitHub's official blog post: Spec-driven development with AI: Get started with a new open source toolkit.

The 5-Phase Workflow (always in this order):

flowchart LR
    A[🎯 Research] --> B[📋 Specify] --> C[📝 Plan] --> D[🔨 Work] --> E[🔍 Review]
    D -.->|If changes needed| E
    E -.->|Repeat| D

Phase	Command	Output	Ralph Wiggum 🔄
1. Research	`/ai-eng/research`	Context and findings	`--ralph` for iterative deepening
2. Specify	`/ai-eng/specify`	Feature specification	`--ralph` for requirement refinement
3. Plan	`/ai-eng/plan`	Implementation plan	`--ralph` for task completeness
4. Work	`/ai-eng/work`	Quality-gated code	`--ralph` for TDD cycles
5. Review	`/ai-eng/review`	Multi-agent approval	`--ralph` for thorough analysis

This approach ensures specifications are your "source of truth" for what gets built, reducing guesswork and enabling more reliable AI-assisted development.

🔄 New: Ralph Wiggum Iteration - Add --ralph flag to any phase command for persistent refinement until quality standards are met. See Ralph Wiggum Integration Guide.

See docs/spec-driven-workflow.md for complete workflow guide with examples.

Claude Code (Recommended)

/plugin marketplace add v1truv1us/ai-eng-system
/plugin install ai-eng-system@ai-eng-marketplace

OpenCode

# Add to opencode.jsonc:
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-skills", "ai-eng-system"]
}

# Run OpenCode - plugin auto-installs commands, agents, and skills

📋 What's Included

Spec-Driven Development Workflow

Core workflow for systematic development (always research → specify → plan → work → review):

Phase	Command	Purpose	Ralph Wiggum 🔄
1. Research	`/ai-eng/research`	Multi-phase research with codebase and external context	Iterative deepening, gap analysis
2. Specify	`/ai-eng/specify`	Create feature specifications with TCRO framework	Requirement refinement, completeness
3. Plan	`/ai-eng/plan`	Create detailed implementation plans from specs	Task atomicity, dependency mapping
4. Work	`/ai-eng/work`	Execute plans with quality gates and validation	TDD cycles, implementation refinement
5. Review	`/ai-eng/review`	Multi-perspective code review (28 agents)	Escalating focus, thorough analysis

Methodology: Based on GitHub's spec-driven development approach

🔄 Ralph Wiggum: Add --ralph flag to any phase command for persistent iteration. Perfect for complex tasks requiring multiple refinement cycles. Learn more →

🛠️ Fixed (v0.2.2): Ralph Wiggum now runs continuously without stopping between phases. Full backward compatibility maintained. Fix details →

Terminal UI: ai-eng ralph CLI

New! Terminal-based interface for autonomous research and implementation workflows:

# Install globally via npm (requires Node.js or Bun)
npm install -g ai-eng-system
ai-eng ralph "implement user authentication"

# Or run directly from source (requires Bun)
bun run build
bun src/cli/run.ts "implement user authentication"

# Shortcut: "ai-eng prompt" defaults to ralph
ai-eng "fix the bug" --print-logs

Installation command (replaces automatic postinstall):

ai-eng install --scope project   # Install to project .opencode/
ai-eng install --scope global    # Install to ~/.config/opencode/

Features:

🖥️ Full-screen TUI with keyboard navigation
⏱️ Timeout handling (default 120s) to prevent hangs
🔄 Rate-limit detection with smart backoff
🤖 Configurable models per task type (research/planning/exploration/coding)
🚀 4-tier model resolution priority
🎯 Continuous iteration through all 5 phases
✅ Research-backed prompt optimization (+45-115% quality)

Documentation: See docs-site/docs/features/ai-eng-ralph-cli.md for complete guide

Additional Commands (13 total)

/ai-eng/optimize - Prompt enhancement (+45% quality)
/ai-eng/deploy - Pre-deployment checklists
/ai-eng/compound - Document solved problems
/ai-eng/recursive-init - Initialize AGENTS.md across directories
/ai-eng/create-plugin - AI-assisted plugin creation
/ai-eng/create-agent - AI-assisted agent generation
/ai-eng/create-command - AI-assisted command generation
/ai-eng/create-skill - AI-assisted skill creation
/ai-eng/create-tool - AI-assisted custom tool creation
/ai-eng/context - Context management and retrieval
/ai-eng/clean - Remove build artifacts and generated files
/ai-eng/seo - SEO audits with Core Web Vitals

Total Commands: 17 + 1 CLI

Agents (29 total)

Architecture & Planning: architect-advisor, backend-architect, infrastructure-builder
Development & Coding: frontend-reviewer, full-stack-developer, api-builder-enhanced, database-optimizer, java-pro
Quality & Testing: code-reviewer, test-generator, security-scanner, performance-engineer
DevOps & Deployment: deployment-engineer, monitoring-expert, cost-optimizer
AI & Machine Learning: ai-engineer, ml-engineer
Content & SEO: seo-specialist, prompt-optimizer
Plugin Development: agent-creator, command-creator, skill-creator, tool-creator, plugin-validator

Skills (8 files)

devops - Coolify deployment, Git worktree workflows
prompting - Research-backed incentive prompting techniques
research - Comprehensive multi-phase research orchestration
plugin-dev - Plugin development knowledge base and references
text-cleanup - Pattern-based text cleanup (slop, comments)
workflow/ralph-wiggum - Persistent iteration patterns for quality refinement (NEW!)

🔄 Ralph Wiggum Philosophy: "Iteration > Perfection, Failures Are Data, Persistence Wins" - Now available across all phase commands with --ralph flag

🔄 Subagent Orchestrator Configuration

New! docs/subagent-orchestration-guide.md - Configure automatic agent routing for ai-eng-system

Learn how to configure subagent orchestration when using ai-eng-system with OpenCode or Claude Code:

For OpenCode: Inject orchestration into primary agent's prompt for zero-latency routing
For Claude Code: Use UserPromptSubmit hook for dynamic, per-prompt routing
Platform-specific configurations for both OpenCode and Claude Code
Three-layer approach: Base instructions + dynamic enhancement + detailed knowledge
Complete examples and troubleshooting for reliable agent delegation

Quick Answer: How does orchestrator always work?

OpenCode: Orchestrator is injected into primary agent's prompt (part of agent identity)
Claude Code: UserPromptSubmit Hook runs before every prompt and adds routing guidance

Both ensure reliable routing to ai-eng-system's 28 specialized agents!

🏗️ Architecture

This repo follows Anthropic's official Claude Code marketplace pattern:

Marketplace root: .claude-plugin/marketplace.json (only file at repo root)
Embedded plugin: plugins/ai-eng-system/ with standard plugin layout
Build system: Transforms canonical content/ sources into platform-specific outputs
OpenCode support: Pre-built distributions in dist/.opencode/
Auto-installation: Plugin automatically installs files when loaded by OpenCode or via npm postinstall

🔧 Development

Prerequisites

Bun >= 1.0.0
Node.js >= 18 (for compatibility)

Build & Test

bun run build        # Build all platforms
bun run build:watch  # Watch mode
bun run validate     # Validate content without building
bun test             # Run test suite

Repository Structure

├── content/          # Canonical markdown sources
│   ├── commands/     # Command definitions
│   └── agents/       # Agent definitions
├── skills/           # Skill packs
├── plugins/          # Embedded Claude plugin
├── dist/             # Built outputs (committed)
├── .claude-plugin/   # Marketplace manifest
└── .opencode/        # OpenCode config

📦 Distribution

Claude Code Marketplace

Source: https://github.com/v1truv1us/ai-eng-system
Marketplace: v1truv1us/ai-eng-marketplace
Plugin: ai-eng-system

OpenCode

Global: ~/.config/opencode/ (default)
Local: ./.opencode/ (project-specific)
Namespace: ai-eng/

✅ Validation Status

Marketplace manifest: ✅ Valid
Embedded plugin: ✅ Valid
Build system: ✅ Working
Tests: ✅ Passing (21/21)

📚 Documentation

Online Documentation

Deploy with Coolify (recommended):

📖 Coolify Deployment Guide - Complete deployment instructions
🚀 Deploy to Coolify in 5 minutes

Built Site: docs-site/ directory

Developer Documentation

Installation Guide - Detailed setup instructions
Agent Coordination - Agent usage patterns and coordination
Plugin Documentation - Technical plugin details
Research Guide - Research orchestration usage
Ralph Wiggum Integration - Iterative refinement patterns (NEW!)

Documentation Site

The documentation site is built with Astro + Starlight and ready for deployment:

# Local development
cd docs-site
bun install
bun run dev  # http://localhost:4321

# Build for production
bun run build

# Deploy to Coolify
# Repository path: docs-site/
# Build command: bun install && bun run build
# Output directory: dist

💻 Usage Example

OpenCode Setup

# 1. Create opencode.jsonc in your project
cat > opencode.jsonc << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-skills", "ai-eng-system"]
}
EOF

# 2. Install package (optional - auto-installs via plugin)
npm install ai-eng-system

# 3. Run OpenCode
# Commands and agents are automatically available!

When OpenCode loads the plugin, it automatically:

✅ Installs 16 commands to .opencode/command/ai-eng/
✅ Installs 30 agents to .opencode/agent/ai-eng/
✅ Installs 7 skill files to .opencode/skill/

Using Commands

# Basic workflow
/ai-eng/plan              # Create implementation plan
/ai-eng/review             # Multi-agent code review
/ai-eng/work               # Execute implementation plan
/ai-eng/seo                # SEO audit
/ai-eng/create-agent       # Generate new agent

# Ralph Wiggum iteration (NEW!)
/ai-eng/work "feature" --ralph                    # TDD cycles until complete
/ai-eng/research "topic" --ralph --ralph-max-iterations 15  # Deep research
/ai-eng/specify "feature" --ralph --ralph-quality-gate="rg '\[NEEDS CLARIFICATION\]'"
/ai-eng/plan --from-spec=specs/feature.md --ralph  # Enhanced planning
/ai-eng/review src/ --ralph --ralph-focus=security # Thorough review

# ... and 11 more commands

Using Agents

Commands reference specialized agents automatically:

/ai-eng/review --agent=code-reviewer     # Quality-focused review
/ai-eng/review --agent=frontend-reviewer # Frontend review
/ai-eng/review --agent=backend-architect  # Architecture review

Built with research-backed prompting techniques (+45-115% quality improvement)

📖 Workflow Guide

For complete documentation on the Research → Specify → Plan → Work → Review workflow, see:

docs/spec-driven-workflow.md - Visual workflow guide with examples
docs/research-command-guide.md - Research command deep dive

@ai-eng-system/cli

Package Exports

Readme

AI Engineering System

🚀 Quick Start

Spec-Driven Development (Recommended)

Claude Code (Recommended)

OpenCode

📋 What's Included

Spec-Driven Development Workflow

Terminal UI: ai-eng ralph CLI

Additional Commands (13 total)

Agents (29 total)

Skills (8 files)

🔄 Subagent Orchestrator Configuration

🏗️ Architecture

🔧 Development

Prerequisites

Build & Test

Repository Structure

📦 Distribution

Claude Code Marketplace

OpenCode

✅ Validation Status

📚 Documentation

Online Documentation

Developer Documentation

Documentation Site

💻 Usage Example

OpenCode Setup

Using Commands

Using Agents

📖 Workflow Guide