Ucai — Use Claude Code As Is

A Claude Code plugin that solves the same problems as GSD, BMAD, Ralph, and Agent OS — but using Claude Code's native architecture instead of fighting it.

Ucai was built from the inside out.
We read the source code. We studied how Anthropic builds their own plugins.
Every component maps 1:1 to a native Claude Code system — no wrappers, no personas, no bash loops.

🥊 Frameworks vs. Ucai — What's Actually Different?

Community frameworks were built from the outside in — wrapping Claude Code in bash scripts, mega-prompts, and persona engineering.

Ucai is built from the inside out — using Claude Code's native systems exactly as Anthropic designed them.

✨ What Ucai Gives You

• Project planning with discovery agents
• Feature-level FRDs with milestone breakdown (each milestone = one fresh context window)
• 8-phase build workflow with parallel agents, elegance checkpoints, and staff engineer self-checks
• Persistent task tracking (tasks/todo.md) and self-improvement loop (tasks/lessons.md)
• Automated test writing (TDD) integrated into build and debug workflows
• Native autonomous iteration (/ucai:iterate)
• Multi-agent code review with lessons-aware pattern detection
• Structured debugging with single approval gate and autonomous execution
• Documentation generation with gotcha extraction from lessons
• Release automation
• Hook lifecycle coverage — session context injection, task/lessons awareness, config guardrails, subagent quality gates, and iterate-state preservation across compaction
• Built-in skills (backend, frontend, QA, DevOps, architecture, code review, and more)

All using native Claude Code commands, agents, hooks, and skills.

⚡ Quickstart

Requirements

Claude Code v2.1.0+. Check with:

claude --version

Install (Marketplace)

Inside an interactive Claude Code session:

/plugin marketplace add Joncik91/ucai
/plugin install ucai-plugin@ucai-marketplace

This installs Ucai globally — available in every project and every session.

Development / Local Testing

claude --plugin-dir ./ucai

🧪 Verify Installation

All commands are namespaced under ucai::

/ucai:init
/ucai:plan
/ucai:build
/ucai:debug
/ucai:docs
/ucai:release
/ucai:iterate
/ucai:review
/ucai:cancel-iterate

Run /help to see them listed.

🧩 Commands

→ Full workflow guide — getting started patterns, milestone-based builds, command deep-dives, context chain reference.

🚀 Typical E2E Workflow

Greenfield project

# 1. Define what you're building — project.md + requirements backlog
/ucai:plan

# 2. Generate CLAUDE.md — two valid timings, pick one:
#    Right after /plan  →  if planning settled the stack, folder structure,
#                          and key conventions well enough to write them down now
#    After first /build →  if those choices were left open and only resolved
#                          once implementation started
/ucai:init

# 3. FRD for your first feature (optional but recommended for complex work)
/ucai:plan vertical slice

# 4. Build it — 8-phase: explore → clarify → design → implement → verify → test
/ucai:build vertical slice

# 5. Keep building from the backlog
/ucai:build authentication
/ucai:build notifications
...

# 6. Review, document, release
/ucai:review
/ucai:docs
/ucai:release minor

Existing project

# 1. Analyze the codebase → generate CLAUDE.md
/ucai:init

# 2. Create a requirements backlog if one doesn't exist
/ucai:plan

# 3. Jump straight to building
/ucai:build fix the broken auth flow

/ucai:build auto-loads the FRD created by /ucai:plan <feature> when names match. /ucai:debug, /ucai:review, and /ucai:docs are standalone — use them whenever needed.

🧠 Built-In Skills

Ucai ships with 8 curated skills auto-loaded by Claude Code:

🔄 Self-Improvement Loop

Ucai learns from corrections. When you correct Claude during a /build or /debug session, the pattern is captured in tasks/lessons.md. Future sessions load these lessons and apply them proactively.

• SessionStart announces lessons count and warns when consolidation is needed (>100 entries)
• /build Phase 1 and /debug Phase 1 load relevant lessons before starting work
• /review feeds known patterns to reviewer agents
• /docs extracts gotchas from lessons for documentation

This is inspired by Boris Cherny's methodology — persistent correction capture is the highest-ROI investment for AI-assisted development.

🏗 Architecture

ucai/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── CLAUDE.md
├── commands/
├── agents/
├── hooks/
├── scripts/
├── skills/
└── tasks/                  ← created at runtime by commands
    ├── todo.md             ← persistent task tracking (overwritten per session)
    └── lessons.md          ← self-improvement loop (append-only)

Every component is a native Claude Code system. Nothing invented.

🧭 Principles

1. Use native systems — Commands, agents, hooks, skills
2. Files are context — No external memory
3. Context is a public good — Only add what Claude doesn't know
4. Agents are not personas — Real model assignments + tools
5. Explicit approval gates — Never proceed without user decision
6. Parallel by default — Spawn focused agents simultaneously
7. CLAUDE.md is for project facts — Not framework config
8. Learn from corrections — Capture patterns in lessons, apply them proactively
9. Verify before done — Automated tests + manual confirmation, never just agent review

⭐ Support the Project

If Ucai helps you ship faster, consider starring the repo.