v3.4.4 Key Changes (2026-04-05) — HTML generation decoupled from phase skills: /u-plan, /u-design, /u-check, /u-reverse no longer auto-generate HTML output. Use /u-output command to generate HTML independently. Phase prerequisite cascade: /u-dev auto-invokes /u-design if Design docs missing; /u-design auto-invokes /u-plan if Plan docs missing.

TL;DR

Forward Engineering (New Project)

# 1. Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/upleat-ax/u-maker-plugin/main/install.sh | bash

# 2. Restart Claude Code, then run in your project
/u-init my-app                # Create .u-maker/ structure + register app

# 3. Collect data → Analyze → Plan
# → Drop RFP, meeting notes, AS-IS materials into .u-maker/_dropzone/ (auto-classified)
/u-ingest [app]              # raw → classified analysis
/u-plan [app]                # Auto-generate SRS + IA + Roadmap

# 4. Design → Implement → Verify
/u-design [app]              # ERD + API + Screen + Flow + RTM + wireframes
/u-dev [app]                 # Generate FE + BE + DB code
/u-qa [app]               # TC design + test + report

# 5. Deploy + Retrospective
/u-ship [app]                # Final verification + iteration log + retrospective

Reverse Engineering (Existing Project)

/u-init my-app                # Initialize project
/u-reverse --app my-app       # Source code → SSoT reverse engineering (ERD, API, Screen, SRS, IA)
/u-sync [app]                # Cross-document consistency verification

Natural Language Also Works

"Create SRS for the [app] app"      # U-MAKER router auto-dispatches

1. What This Plugin Solves

U-MAKER is a collaboration orchestrator that implements Intent-driven, document-centric development (SSoT).

Traditional Approach vs U-MAKER v3

2. Architecture Overview

Skill Naming Convention

3. PDCA 5-Phase Process

You can select 4-Phase mode (merging Design into Do) in config: designPhase: "merged"

Phase Definition

Mandatory Scorecard Display

Every gate validation must display the full N-criteria scorecard on screen (N = 1–11, default 5; controlled by --loop [N]). No abbreviation or omission allowed.

┌─────────────────────────────────────────────────────────────┐
│  GATEKEEPER REPORT — Plan Phase (myapp)                  │
├─────┬────────────────────┬───────┬────────┬───────────────┤
│  #  │ Criteria             │ Score │ Status │ Findings      │
├─────┴────────────────────┴───────┴────────┴───────────────┤
│  01 │ Completeness         │   98  │   PASS │ —             │
│  04 │ Traceability         │   88  │   FAIL │ FR-030 orphan │
│  ... (all N rows shown, default 5) ...                       │
├─────┴────────────────────┴───────┴────────┴───────────────┤
│ AVG │                      │ 95.2  │ PASS   │               │
┘─────┴────────────────────┴───────┴────────┴───────────────└
  Attempt: 1/3 · Threshold: 95 · Result: PASS → advance to Design

On FAIL: Improvement items are appended below the scorecard, ordered by severity. After 3 retries: LOOP HALTED — manual intervention required.

4. 3-Layer Data Pipeline

Processing raw data all at once causes early content loss due to context window limits. An intermediate refinement layer solves this:

.u-maker/_dropzone/ Auto-Classification

When you drop files into .u-maker/_dropzone/, running /u-ingest analyzes filenames and contents to auto-classify them into appropriate subfolders like .u-maker/_input/rfp/, as-is/, meeting-notes/, etc. After processing, .u-maker/_dropzone/ is emptied. (_input/raw/ is also supported as a fallback)

_classified 12 Categories

Item Lifecycle

extracted → validated → adopted / rejected

5. Agents

7 specialized agents share responsibilities by phase.

6. Commands

Grammar

/u-{command} [scope] [target] [flags]

• scope: app name | common | all | omit (auto-selected)
• target: document/item name
• flags: -i (interactive) | --step | --only X | --cascade | --dry-run | --json

6.1 Lifecycle (11)

6.2 Operations (5)

6.3 Observability (5)

6.4 Collaboration (5)

Global Flags

7. Engine Skills

13 cross-cutting engines. Not user-invocable; called internally by command skills.

Core Engines (orchestrator)

Domain Engines (planner)

Execution Engines (builder+gatekeeper)

8. Interaction Modes

Assumptions Log

A safety mechanism that records every time an agent "decides instead of asking" in auto mode.

/u-status [app] --assumptions    # Check pending assumptions
/u-assume approve A-001           # Approve
/u-assume reject A-001 "cancel only"  # Reject → cascade correction

When maxAssumptions (default: 20) is exceeded, auto mode switches to interactive automatically.

9. 4-Tier ID Hierarchy

FT = Feature (implementation unit). Functional Test — absolutely not.

10. Folder Structure

Project Root

project-root/
+-- .u-maker/                         # SSoT directory
+-- src/                              # Source code
+-- ...

.u-maker/ (Project)

.u-maker/
+-- u-maker.config.json              # Global settings (language, designTool, iteration, etc.)
+-- _links.json                       # Dependency graph
+-- _dropzone/                        # File drop zone (drop RFP, meeting notes, AS-IS materials; auto-classified on /u-ingest)
|
+-- common/                           # Project-wide common
|   +-- _index.json
|   +-- policy/                       # Service/Security/Privacy/ErrorCodes/Terms
|   +-- ux/                           # UX Guide, Design Token, UI Components
|   +-- dev/                          # Coding Convention, Git Strategy, Testing
|   +-- architecture/                 # System Overview, ERD, API, Infra
|   +-- project/                      # Roadmap, Stakeholders, Iteration Log
|
+-- apps/{app-name}/                  # Independent pipeline per app
|   +-- _index.json                   # App document TOC + status
|   +-- app.config.json               # Per-app settings
|   +-- _input/                       # Layer 1: Raw data (classified storage)
|   |   +-- raw/                      # Fallback drop zone (.u-maker/_dropzone/ recommended)
|   |   +-- rfp/                      # RFP, proposals
|   |   +-- as-is/                    # AS-IS analysis materials
|   |   +-- meeting-notes/            # Meeting notes
|   |   +-- interviews/               # Interview notes
|   |   +-- _manifest.json            # Input file manifest
|   +-- _classified/                  # Layer 2: Refined data (12 categories)
|   |   +-- requirements/             # FR-nnn, NR-nnn
|   |   +-- pain-points/             # PP-nnn
|   |   +-- domain-terms/            # DT-nnn
|   |   +-- stakeholders/            # SH-nnn
|   |   +-- workflows/               # WF-nnn
|   |   +-- screens/                 # SC-nnn
|   |   +-- data-models/             # DM-nnn
|   |   +-- constraints/             # CN-nnn
|   |   +-- decisions/               # DC-nnn
|   |   +-- questions/               # QS-nnn
|   |   +-- standards/              # STD-nnn
|   |   +-- ux-standards/           # UXS-nnn
|   |   +-- _summary.json            # Classification summary
|   +-- _sessions/                    # Discussion session archive
|   +-- _assumptions/                 # Assumptions log
|   +-- _backlog/                     # Backlog
|   +-- docs/                         # Layer 3: Deliverables
|   |   +-- 01-plan/                  # srs.md, ia.md, roadmap.md
|   |   +-- 02-design/               # erd.md, api.md, screen.md, screen-flow.md
|   |   |   +-- wireframes/
|   |   |   |   +-- index.html       # Wireframe browser
|   |   |   |   +-- {SCR-ID}.html    # Per-screen wireframe
|   |   +-- 03-dev/                  # code.md, spec-sync-report.md
|   |   +-- 04-check/               # test-cases.md, test-report.md
|   +-- rtm.md                       # Traceability matrix
|
+-- _input/                           # Project-wide common raw data
|   +-- raw/                          # Common fallback drop zone
+-- _classified/                      # Common classified
+-- _sessions/                        # Cross-app discussions
+-- _assumptions/                     # Cross-app assumptions

Config Settings

{
  "language": {
    "documents": "ko",
    "supported": ["ko", "en", "ja", "zh"]
  }
}

Set the document language for deliverables with language.documents. Supports ko (Korean), en (English), ja (Japanese), zh (Chinese). IDs and code are always in English.

wireframes/index.html

An SPA viewer generated via /u-wireframe. Navigate Screen documents via sidebar navigation and visualize wireframes with MD rendering. Each wireframe uses a 6-section layout: Header, Stage (app-frame + annotation panel), Component Spec table, 2-column logic diagrams, Overlay UI (modals/bottomsheets/popups), and Annotation Legend. Screen layout SVG replaces State Transition diagrams. Screen spec JSON companion includes a layout field.

Scope-First Navigation

Claude reads only _index.json first instead of opening files directly, then selectively loads only the needed files → saves context window.

11. Document Output Rules

Document Status Lifecycle

Auto-Cascade

When SRS changes, impact flags are automatically propagated to ERD, Screen, TestCase via _links.json.
Use /u-update --cascade for automatic dependent document updates.

12. Plugin Repository Layout

u-maker-plugin/
+-- .claude-plugin/plugin.json        # v3.4.4
+-- agents/                           # 7 agent definitions
|   +-- u-agent-pm.md
|   +-- u-agent-plan.md
|   +-- u-agent-design.md
|   +-- u-agent-dev.md
|   +-- u-agent-qa.md
|   +-- u-agent-gatekeeper.md
|   +-- u-agent-report.md
+-- skills/
|   +-- u-*/SKILL.md                  # 13 skills (12 user-facing + 1 engine)
+-- hooks/                            # Event hooks (3)
|   +-- hooks.json
|   +-- on-dropzone-added.js
|   +-- on-gate-result.js
|   +-- on-doc-change.js
+-- shared/references/                # Reference documents

13. Hooks & Guardrails

All hooks are bound to PostToolUse(Write) events and run automatically after file writes.

14. Scenario Guide — When to Use Which Command?

Project Start (Forward Engineering)

Project Start (Reverse Engineering)

Planning (Plan Phase)

Design (Design Phase)

Implementation (Do Phase)

Prerequisite Cascade: /u-dev auto-invokes /u-design if Design documents are missing; /u-design auto-invokes /u-plan if Plan documents are missing. This means running /u-dev alone can trigger the entire Plan → Design → Dev pipeline.

Verification (Check Phase)

Deploy + Retrospective (Act Phase)

Day-to-Day Operations

Q&A & Discussions

Micro-commands available during sessions:

Backlog & PR

Natural Language Also Works

If you don't know the command, just say it in natural language:

"Create SRS for the [app] app"             → /u-plan [app] --only srs
"Optimize ERD for PostgreSQL"              → /u-design [app] --only erd
"Create test cases"                        → /u-qa [app]
"What's the current project status?"       → /u-status
"Extract API docs from existing source"    → /u-reverse --app my-app
"Create a PR"                              → /u-git-pr main

15. Prerequisites & Install

Installation

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/upleat-ax/u-maker-plugin/main/install.sh | bash

# Update
curl -fsSL https://raw.githubusercontent.com/upleat-ax/u-maker-plugin/main/update.sh | bash

# Local development
cd /path/to/u-maker-plugin && ./deploy_local.sh

After install/update, you must restart Claude Code.

16. Troubleshooting