umadev

UmaDev: A coding agent that works like a real dev team, commanding one of five AI coding CLIs you already use.

English | 简体中文 | 繁體中文

umadev is a coding agent that works like a real dev team. It drives one of five first-class AI coding CLIs you already have — Claude Code, Codex, OpenCode, Grok Build, or Kimi Code — and owns no model endpoint of its own: the model your selected base is connected to is the brain.

What you get is role-based team orchestration over that borrowed brain. For work whose depth warrants it, bounded sessions take product, architecture, UI/UX, frontend, backend, QA, security, and DevOps assignments; a small edit stays a small edit. These roles are not independent people and their verdicts are advisory. UmaDev owns the plan and deterministic acceptance floor, produces depth-appropriate artifacts/evidence, and reports failed or incomplete work honestly rather than promising that every request becomes shippable software.

A ninth seat, the coordinator, routes the request, owns a visible plan for deliberate work, schedules the selected roles, evaluates gates, and leaves the audit trail. It doesn't generate code; the base CLI does. Roles exchange bounded blackboard artifacts and structured verdicts rather than free-form cross-talk.

It's a single Rust binary. npm is just the delivery shell.

Table of Contents

• Install
• Quickstart
• Project Origin
• What Problem It Solves
• Features
• How It Works
• The Team
• Why You Can Trust the Output
• Runtime Modes
• The Full Delivery Flow
• Quality Gate
• Governance
• Knowledge Base
• Deliverables
• Commands
• Configuration
• Rust Architecture
• Development
• License

Install

npm install -g umadev

On Linux, don't reach for sudo. The default npm prefix (/usr/local) is root-owned, so npm i -g there fails with EACCES — and sudo npm i -g "fixes" it by writing a root-owned tree into the npm prefix, which then breaks every later non-root npm command on that prefix (npm update -g, npm i -g <anything>) with EACCES. npm aborts the whole transaction, so your other global packages — including your base CLI (@anthropic-ai/claude-code, @openai/codex) — can no longer be updated either. Use a prefix you own instead:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc
npm install -g umadev

Or skip the global install entirely — no prefix, no sudo, nothing on PATH:

npx umadev                 # run it straight from the registry
npm i umadev && npx umadev # or as a project-local dependency

(npm i umadev without -g installs fine, but npm deliberately does not put a local command on PATH — bare umadev will say "command not found". That's npm, not a broken install: run it as npx umadev.)

Already hit the sudo trap? umadev doctor detects a root-owned install or npm cache and prints the exact repair (sudo chown -R $(whoami) ~/.npm, then reinstall under a user-owned prefix).

The npm package is a distribution shim. The actual program is a Rust binary. Prebuilt binaries ship for macOS (Apple Silicon and Intel), Linux (x86_64 and ARM64, glibc ≥ 2.31 or musl/Alpine), and Windows (x86_64).

The Rust binary and curated corpus need no cloud knowledge service. Real coding still requires an installed, authenticated base CLI. The optional local embedding model (multilingual-e5-small, f16, ~224 MB) is not inside the npm tarball: the npm launcher fetches the version-matched, checksummed release asset on the first command that needs retrieval and stores it in ~/.umadev/embed-model. Later local inference needs no API key or network. If the fetch is unavailable, retrieval continues as BM25-only and a later eligible launch retries; a corrupt cache is rejected and re-fetched.

Build from source:

git clone https://github.com/umacloud/umadev.git
cd umadev && cargo build --release --features vector-local
./target/release/umadev --version

Building from source? The embedding model is not in the repository. A plain cargo build --release supports BM25 and the explicitly opted-in remote vector backend, but does not compile the local candle backend. Local vectors require --features vector-local and a compatible config.json, tokenizer.json, and model.safetensors on disk. Point UMADEV_EMBED_MODEL_DIR at that directory, or place it at ~/.umadev/embed-model. The npm launcher provisions version-matched, verified release assets automatically; a source-built binary does not download them. Without a usable vector backend, engine = "hybrid" safely executes as BM25-only.

You also need one AI coding CLI installed and logged in — that's the brain umadev drives:

The curl | bash/sh entries are the Unix install hints understood by the current driver. On Windows, use each vendor's official Windows installation instructions; do not paste those Unix commands into PowerShell.

UmaDev itself needs no additional model API key. You still install and authenticate the selected base, and that base keeps ownership of its account, subscription, credentials, model, and any third-party/local-model routing. UmaDev does not run login flows or open an authentication browser for you. It sends the task and governance context, but never stores or silently replaces the base's credentials or model endpoint. umadev doctor confirms authentication where a reliable probe exists; for Grok Build, only a successfully opened real session proves readiness — “installed” does not mean “logged in.”

Quickstart

umadev                       # launch the chat UI; first run lets you pick a base

Tell it what you want built:

> add CSV export to the reports page
> build me a todo app with a Postgres backend
> /goal ship a working SaaS landing page       # keep working until the goal is met

Or run a build non-interactively:

umadev run "add CSV export to the reports page" --backend claude-code

umadev sizes the work to the request — you don't have to select an intent class. A request classified as Build enters the same owned Director contract whether it came from chat or umadev run; the plan, simulated role reviews, checks, and delivery artifacts remain proportional to its depth. On a clean Git worktree UmaDev can create a derived umadev/<slug> isolation branch. A non-Git or already-dirty worktree reports why isolation was skipped and preserves pre-existing changes. UmaDev never merges or pushes on its own.

A full worked example

Suppose you run:

umadev init
umadev

Then type:

Build a course-booking mini app. Users can browse courses, pick a time, book,
cancel. Admins can manage courses and bookings.

umadev will:

1. Route the request. The base's own model judges this: a full build, not a quick edit. You see an intent card — "full build, entering the delivery flow" — before any code is written.
2. Clarify. Fill in sensible defaults for target platform, payment scope, and admin complexity. Auto mode self-resolves; manual mode lets you confirm each.
3. Research. When the base has web access, search competing booking apps — features, pricing, design trends, real user reviews — and merge that with built-in knowledge about booking systems, admin CRUD, permissions, and form validation. Everything lands in output/<slug>-research.md.
4. Draft three core documents. PRD (roles, scope, EARS acceptance criteria), architecture (data model, APIs, auth, deployment), UI/UX (design direction, tokens, typography, component states, icon library). Pause for your review.
5. Build an execution plan. A dependency plan (plan.json) rendered as a live checklist. Each task links back to its FR id.
6. Implement the frontend. The coordinator schedules each task, the base writes the code, each file is governance-checked as it lands.
7. Pause for preview. You see the running app before backend work starts.
8. Implement the backend and integration.
9. Run the full quality gate. Build, test, lint, contract check, runtime probe, governance scan.
10. Produce the delivery pack. Scorecard, proof pack, compliance mapping — on disk and ready to hand to a teammate, client, or reviewer.

You end up with real files on disk — the research note, the three docs, source, a quality report, and a proof pack.

Project Origin

umadev evolved from the original shangyankeji/super-dev project.

Early super-dev was closer to an AI coding governance tool. It focused on what AI-generated code must not contain: emoji icons, hardcoded colors, unsafe patterns.

umadev has grown that into a coding agent that works like a real dev team:

• From single-point governance to whole-pipeline governance. It no longer only checks code; every phase from requirement to delivery is brought under the process and its gates.
• From loose scripts to a spec-driven system. The source of truth is UMADEV_HOST_SPEC_V1, 34 normative clauses, backed by 113 governance content checks.
• Rewritten in Rust. One binary, fast startup, low dependency surface, cross-platform distribution.
• From blocking bad output to delivering like a team. Your selected base is the brain and hands; umadev is the coding agent that works like a real dev team, with governance as the safety net underneath.

super-dev asked: "how do we stop AI from writing bad code?" umadev asks: "how do we make AI deliver a complete, shippable, auditable project — the way a real software team would?"

What Problem It Solves

Most people hit the same problems when they use AI coding tools at scale:

• The AI starts coding immediately, without a PRD, architecture, or acceptance criteria.
• The frontend is built, but backend API paths do not match.
• The UI looks generic: random colors, random fonts, template-like composition.
• The AI leaves placeholders, fake data, and TODOs — and still says "done."
• After one requirement change, context drifts and earlier decisions are forgotten.
• Code exists, but there is no quality report or delivery evidence.
• Your team has standards and internal knowledge, but you copy them manually into prompts.

umadev turns those problems into a structured workflow:

flowchart LR
    A["One requirement"] --> B["Route & plan"]
    B --> C["Research"]
    C --> D["PRD / Architecture / UI/UX"]
    D --> E["Execution plan"]
    E --> F["Frontend"]
    F --> G["Preview"]
    G --> H["Backend"]
    H --> I["Quality gate"]
    I --> J["Delivery proof"]

Features

• Deeply integrates the base you already use. All five are equal, first-class, deeply adapted bases. Claude Code, Codex, and OpenCode keep their vendor-specific protocol drivers; Grok Build and Kimi Code use their official ACP v1 interfaces through a hardened core and isolated vendor profiles. This implementation detail is not a support tier: every base presents the same UmaDev interaction contract while retaining its own launch, authentication, permission, resume, and capability boundaries. UmaDev needs no additional model API key; the selected base still uses its own login and model configuration.
• Role-based team orchestration. For work whose depth warrants it, eight specialist roles — product manager, architect, UI/UX designer, frontend engineer, backend engineer, QA, security, and DevOps — receive bounded assignments and return typed artifacts or advisory verdicts. They are isolated base sessions coordinated over a shared blackboard, not independent people or a claim that every small edit convenes every role.
• Plans the work and shows it. A build becomes a dependency plan (.umadev/plan.json) rendered as a live checklist you can steer with /plan. Steps are driven step by step; the coordinator owns the plan, not the base.
• One governed Build contract. A Build routed from chat and one started with umadev run both enter the owned Director path; planning, role scheduling, checks, and artifacts scale with depth and observed evidence.
• Produces delivery evidence when the floor passes. A clean, sufficiently deep delivery can include PRD, architecture, UI/UX, a scorecard, and a proof pack. A small edit gets targeted verification, while a failed or incomplete plan is reported as such rather than receiving a completion certificate.
• Local-first, fail-soft retrieval. A curated corpus and project repo map are available locally. BM25 is always the lexical floor; deliberate Full-tier work can additionally use local candle vectors when the shipped feature and verified model are present, then fuse the channels with RRF and optional HyDE expansion. Cloud embedding stays off unless both OPENAI_EMBED_KEY and UMADEV_ALLOW_CLOUD_EMBED=1 are set; a generic OPENAI_API_KEY never authorizes an upload. Any unavailable or inconsistent vector path degrades to BM25.
• Auditable learning from real failures. Concrete incidents are recorded locally; two independent matches form a pending rule, and only the same verifier passing after an exact repair attempt validates it. Recalled evidence reduces repeated mistakes without claiming that a probabilistic base can never repeat one; passive general-knowledge recall remains outcome-neutral until exact turn-level attribution is available.
• Remembers evidence-backed project facts. After meaningful work, a bounded read-only extraction can record stable facts such as the JDK path or real build/test/lint commands in .umadev/memory/facts.jsonl. Safe, non-stale facts are recalled on later work-class turns, which can reduce rediscovery after transcript trimming; Chat does not receive this store and recall is not a correctness guarantee.
• Surfaces supported base questions. When the active driver exposes a structured user-question event, umadev renders its prompt/options inline and correlates the answer to that live session. Question and approval event richness is vendor- and capability-specific; an unsupported surface is reported rather than simulated.
• Your app's runtime model is yours to pick. The base you borrow to write the code and the model your built AI app calls at runtime are kept separate: umadev treats the app's runtime provider, model id, and key as user-configurable env, instead of silently hardcoding the dev base's vendor into the generated product.
• A real terminal UI. Markdown, syntax-highlighted code, live diff cards as files change (word-level highlighting), folding tool rows, a build-completion card with a clickable preview URL, slash commands throughout, and /logs to surface the base's live build output for long-running commands.
• Governance you can audit. A trust dial (plan / guarded / auto), irreversible actions always confirm on every tier — including a fail-closed boundary for obfuscated commands — plus an MCP server (umadev mcp serve) that exposes the governor to other tools, and compliance mapping (SOC 2 / ISO 27001 / EU AI Act).
• Goal-until-met builds. /goal <objective> has the same product entry on all five bases. Claude Code, Codex, and OpenCode expose vendor-specific persistent-goal capability; the ACP bases keep the goal alive through UmaDev's coordinator because ACP v1 defines no common goal mode. UMADEV_NO_GOAL_MODE=1 opts out.

How It Works

A turn flows through up to five layers. Retrieval and governance helpers have bounded safe degradation, and critic opinions never replace the deterministic floor. Once a critic is required at a review boundary, however, its transport or parse failure parks the run as operationally unavailable rather than fabricating acceptance. Authentication, transport, hard-gate, and verification failures are surfaced honestly as degraded, paused, blocked, incompatible, or failed work; they are never converted into success just to keep the flow moving.

flowchart TB
    User["User — requirement / review / preview / deploy"] --> UI["umadev TUI / CLI<br/>chat + slash commands"]

    UI --> Director["umadev-agent<br/>Router · Plan · Schedule · Verify · Finalize"]

    Director --> Spec["umadev-spec<br/>UMADEV_HOST_SPEC_V1 · 34 clauses"]
    Director --> Knowledge["umadev-knowledge<br/>curated corpus · BM25 + vector · repo-map"]
    Director --> Governance["umadev-governance<br/>113 checks · audit · compliance"]
    Director --> Contract["umadev-contract<br/>OpenAPI · frontend↔backend path check"]

    Director --> Runtime["umadev-runtime<br/>Runtime trait"]
    Runtime --> Host["umadev-host<br/>5 first-class deep integrations<br/>3 vendor-specific + 2 isolated ACP v1 drivers"]
    Runtime --> Offline["Offline templates<br/>CI / no-base fallback"]

    Host --> Workspace["Workspace<br/>source · output · release"]
    Offline --> Workspace

    Governance --> Evidence[".umadev/audit/<br/>tool-calls.jsonl · verify.jsonl"]
    Contract --> Quality["Quality gate"]
    Evidence --> Quality
    Quality --> Release["proof-pack-*.zip<br/>scorecard-*.html"]

The five layers in plain English:

1. Route. Before any writer acts, the selected base model judges the complete current request on a fresh Plan-profile child: Chat, Explain, QuickEdit, Debug, or Build, plus depth, write authorization, scope, confidence, and clarification. A valid model decision can scale work in either direction; deterministic matching is only the conservative fallback when the typed consult is unavailable or invalid. Explicit no-write intent, the single-writer rule, and irreversible-action safeguards remain hard ceilings. Clarification happens before the writer lock or branch is created. Plan is mapped to each vendor's real permission surface; it is not advertised as the same hard sandbox on every base.
2. Plan. A real build is broken into a dependency plan that umadev owns and renders as a live checklist. The plan is stored in .umadev/plan.json and is steerable with /plan.
3. Schedule. umadev walks the plan step by step. Writing roles (frontend / backend engineer) drive the main session serially — single-writer. Reviewing roles (product manager, architect, designer, QA, security, frontend, backend, DevOps) each get a fresh independent Plan-profile child and review in parallel, returning structured verdicts. The child sees typed blackboard artifacts, not the writer transcript. Roles communicate only through shared artifact files and their verdicts.
4. Verify and self-correct. Each step is checked against its acceptance criteria on a deterministic floor — coverage, contract, build/test, hard gates — not by the model self-assessing "good enough." Blocking findings are classified as build, contract, coverage, behavior, or craft and return with raw evidence plus a classifier-owned repair playbook. Stable fingerprints and source-tree snapshots prevent identical no-progress repairs from spinning: strategy changes on the second unchanged observation and the third settles as an evidence-bearing failure.
5. Finalize. Once the applicable floor is clean, umadev produces the depth-appropriate delivery artifacts. Eligible incidents and exact repair/verifier outcomes may update evidence-gated learned memory; an arbitrary episode does not automatically become a lesson.

While a writer run is active, only an explicit correction to that current task is steered into it. Questions and future or ambiguous tasks stay queued as ordinary model-routed turns until the run settles; a question at a gate is never silently converted into a revision.

Firmware is proportional to the route: Chat gets only stable identity/language, Explain adds bounded read context, QuickEdit/Debug add engineering craft, and a deliberate Build adds the relevant knowledge slice, recalled pitfalls, project facts, repo map, and team doctrine. The stable identity layer remains byte-stable so the base's prompt cache stays warm without forcing every conversation through build machinery.

The stable identity layer is pre-loaded when the resident session opens; the bounded route overlay is composed per turn. This preserves a warm base session without making an ordinary question inherit build plans or stale TODOs.

The Team

umadev convenes a nine-seat team — eight specialists plus a coordinator — and each role is a real job function with a real deliverable. Each role owns something concrete on the shared blackboard:

flowchart TB
    Director["Coordinator<br/>owns plan · drives main session · aggregates verdicts"]

    subgraph Writing ["Writing roles — main session, serial (single-writer)"]
        FE["Frontend engineer"]
        BE["Backend engineer"]
    end

    subgraph Reviewing ["Reviewing roles — fresh Plan child, parallel"]
        PM["Product manager<br/>scope · acceptance criteria"]
        Arch["Architect<br/>data model · APIs · scalability"]
        Design["UI/UX designer<br/>tokens · typography · component states"]
        QA["QA engineer<br/>test coverage · edge cases"]
        Sec["Security<br/>SAST · secrets · auth"]
        FER["Frontend reviewer<br/>contract · accessibility · slop"]
        DevOps["DevOps<br/>Dockerfile · CI · deploy"]
    end

    Director --> Writing
    Director --> Reviewing

    Writing --> Artifacts["Shared artifact files<br/>output/*.md · source tree"]
    Reviewing --> Artifacts

    Artifacts --> Verdicts["RoleVerdict { accepts, blocking, advisory, evidence }"]
    Verdicts --> Director

How the team ships without stepping on itself:

• Doer roles drive the main session serially to produce their deliverable. Only one writer touches source at a time (single-writer).
• Deployment boundary for the writer lock. Cooperating UmaDev processes must use the same OS identity and stable per-user lock namespace, and the filesystem must provide coherent advisory-lock semantics. Cross-identity use is unsupported and its safety is not guaranteed. The workspace root path and every alias used to reach it must remain stable for the lifetime of a run: do not rename or replace the root, or retarget an entry symlink/junction. NFS/SMB also requires a verified cross-client lock manager and an invariant .umadev namespace for the lifetime of a run (the outer namespace guard is host-local); a single-machine test cannot certify either property.
• Reviewing roles each run on a fresh independent Plan-profile child, in parallel, and return a RoleVerdict — accepts, blocking findings with evidence, and advisory notes. Read-only enforcement is vendor-specific; see the runtime matrix below.
• The coordinator aggregates deterministically. The deterministic floor governs loop control; critic opinions are advisory only. Blocking findings are folded into one rework directive injected back into the main session, along with the evidence.
• A missing required review is an operational pause, not a pass or a code defect. A reviewer timeout, startup failure, or unparseable/empty reply becomes Unavailable; it never fabricates acceptance and never asks the writer to repair source, run Docker, or repeat an automatic review loop. UmaDev checkpoints the live run without rendering completion or ending it. /continue retries the parked review boundary; when the source fingerprint is unchanged, already-passed source work and deterministic build/test checks are not replayed.
• Roles never chat to each other. The shared blackboard is the output artifact files and the source tree. The only communication channel between roles is the verdict.
• The team scales with the task. A bugfix convenes no team. A greenfield build convenes the full roster. Complexity determines the seats.

Why You Can Trust the Output

Trust in the output comes from four things that happen on every build:

1. The deterministic floor runs regardless of what the model thinks

Build, lint, typecheck, and test results are checked directly. The acceptance floor checks spec coverage and contract alignment — the model doesn't self-report "it passed."

2. The frontend↔backend contract is verified mechanically

umadev-contract parses the architecture doc's API table into a typed spec, renders openapi.json to .umadev/contracts/, extracts every fetch/axios call in the frontend source, and cross-validates the paths. A mismatch is a blocking finding.

3. Every important action leaves evidence

Tool calls, verification runs, and critic verdicts are written to .umadev/audit/ as JSONL. The proof pack includes the evidence chain.

4. Governance runs on every file write

113 content checks cover emoji-as-icons, hardcoded colors, leaked secrets, AI-slop UI patterns, and unsafe code constructs. They run as a pre-write hook into Claude Code, as a pre-commit hook in git, and as part of the quality gate. At write time only the irreversible floor (leaked secrets / credentials, sensitive-path writes, destructive shell) is hard-blocked; craft and quality findings (emoji, color, AI-slop) are flagged and repaired by the post-write QC loop rather than pinning the base's hands mid-file. All rules are configurable in .umadev/rules.toml and are fail-open — a bug in the governor never blocks your work.

Runtime Modes

Drive a local AI coding CLI (the product)

All five integrations expose a logical continuous, bidirectional product surface. Users stay in the UmaDev TUI; follow-up turns and only the questions, approvals, and tool events actually exposed or negotiated by that base travel through its driver. Missing capabilities are reported, not simulated. “Headless” or “non-interactive” describes the background machine-protocol child process, not the UmaDev product's interaction model.

All five rows above are first-class integrations and none uses a CLI version allowlist. Version output is diagnostic only; live protocol negotiation, typed responses, and fail-closed runtime rules decide each capability. ACP is an official machine-protocol path for both Grok Build and Kimi Code, not a lower support tier. Both accept every official version and are continuously checked against their open-source repositories. Grok's installed binary may negotiate session/resume or advertise session/load, but capability presence alone does not prove that the newly launched process applied the same sandbox or completed Grok's native pre-start resume check, so UmaDev uses a bounded fresh-session handoff until both facts are attested. Kimi discovers model, mode, thinking, resume, and load controls from the live ACP session. Review critics always start fresh Plan-profile sessions rather than loading the writable main line.

Attachments use ordered structured input, never a hidden @path fallback. Claude Code and Codex deliver images natively and require an explicit bounded UTF-8 materialization choice for generic files; OpenCode delivers image/file parts natively; Grok Build and Kimi Code accept image/resource blocks only when their live ACP handshake advertises them. The TUI reports how every block was actually delivered. Codex is the only base currently advertised with proven same-turn turn/steer; the other four queue or reject active-turn input according to their real session capability instead of pretending parity.

The base brings its own model — umadev has none

umadev connects to no model API and stores no base credentials of its own. The selected base uses its own configured model — your logged-in subscription, or whatever third-party/local model routing that base supports. Configure model selection in the base itself. /model is informational and never silently changes the base.

umadev reads and surfaces the base's model and reasoning effort where the base exposes them. The three vendor-specific protocol drivers can inspect their documented local configuration or session metadata; each ACP driver exposes only what its installed CLI negotiates or emits. Kimi's model, thinking, and exact configured context are read from Kimi's own config/options rather than guessed. A missing value remains unknown — UmaDev never guesses a context window from a model-name table.

Wider model coverage behind any of these five bases remains the base's job. Adding another model id does not require UmaDev to own a provider endpoint.

Offline templates (internal fallback, not a product mode)

Offline mode (/offline) makes no model calls and no network requests. It is an internal deterministic fallback for demos, smoke tests, and CI — not a mode you choose for real work. The first-run picker lists the five first-class bases, not Offline. Offline output is templates with TODO placeholders, not real code.

The Full Delivery Flow

For a heavyweight greenfield build, the coordinator expands the plan into the full nine-phase chain — the most complete delivery path. Most requests route to something shorter.

flowchart LR
    CL["clarify"] --> R["research"]
    R --> D["docs<br/>PRD · Architecture · UI/UX"]
    D --> G1["docs_confirm<br/>gate"]
    G1 --> S["spec<br/>plan · tasks"]
    S --> F["frontend"]
    F --> G2["preview_confirm<br/>gate"]
    G2 --> B["backend"]
    B --> Q["quality gate"]
    Q --> L["delivery"]

Small tasks have a lightweight path — the router classifies the request and routes to the right depth, and the plan expands or trims to fit. A bugfix convenes no team; a greeting stays chat; only a full product requirement expands into the chain above. Force the light path for a trivial change with /quick.

Phase outputs

Quality Gate

The quality gate is a pre-delivery review that runs independently of the model.

It checks:

• PRD goal, scope, and acceptance criteria completeness.
• Architecture APIs, data model, error handling, and authentication.
• UI/UX tokens, typography, icon library, component states, and dark mode.
• Frontend API calls cross-validated against the backend contract.
• Emoji icons, hardcoded colors, and generic AI-template UI patterns.
• Build, test, lint, and typecheck results.
• Dockerfile, CI config, migrations, and .env.example.
• Leaked API keys, passwords, and connection strings.
• Audit logs and compliance mapping.

The runtime probe (umadev verify --runtime) boots the app and hits its routes, writing runtime-proof.json — evidence that the app actually starts and responds.

Outputs:

output/<slug>-quality-gate.json
output/<slug>-quality-gate.md
runtime-proof.json

Default threshold:

[quality]
threshold = 90
skip_checks = []

Governance

umadev started as a governance tool and that remains a core capability.

The spec layer has 34 normative clauses. The implementation includes 113 governance content checks across UI quality, security, frontend architecture, backend engineering, and language-specific hazards. Every check is configurable in .umadev/rules.toml — each rule can be disabled, path-excluded, or tuned. They exist to backstop the base's output, not to make the final engineering call for you.

Governance entry points:

flowchart LR
    A["Claude Code hook<br/>pre-write"] --> G["umadev-governance"]
    B["umadev ci<br/>pre-commit / CI"] --> G
    C["MCP server<br/>umadev mcp serve"] --> G
    D["Quality gate<br/>pre-delivery scan"] --> G
    G --> E["Decision: pass · block · advisory"]
    E --> F[".umadev/audit/<br/>tool-calls.jsonl"]

Every governance function is fail-open: an error path returns pass, never a block. A bug in the governor never stops your work.

Project policy:

[disabled]
clauses = []

[exclusions]
paths = ["src/legacy/**", "**/*.test.ts"]

[extra]
blocked_domains = ["internal-bad-proxy.corp"]

The compliance mapping (umadev report) maps the evidence chain to SOC 2 / ISO 27001 / EU AI Act controls.

Knowledge Base

umadev ships with a curated markdown knowledge corpus bundled directly into the binary and auto-extracted to ~/.umadev/knowledge on first launch. It is not generic documentation — it is a set of commercial-grade engineering standards formatted for injection into an AI coding CLI. The count is intentionally not a product invariant: the corpus can grow without making this document stale.

The corpus covers: product design, PRD methodology, system architecture, frontend engineering, backend engineering, database design, security, testing, CI/CD, operations, mobile, desktop, mini programs, HarmonyOS, cross-platform development, domain verticals, UI/UX, design systems, and engineering playbooks.

Retrieval is route-proportional. A deliberate Full-tier Build/Debug turn receives the most relevant knowledge and pitfall chunks for the current requirement and phase; work routes can also receive bounded facts and a repo-map slice. Chat remains lightweight, and QuickEdit/Fast Debug use a smaller craft overlay rather than paying for the full corpus path.

Retrieval flow:

flowchart LR
    A["Requirement + phase"] --> B["Tokenizer<br/>CJK bigram + English"]
    B --> C["BM25 lexical<br/>(pure Rust)"]
    B --> D["Optional vector embeddings<br/>(local model or explicit cloud opt-in)"]
    A --> H["HyDE query expansion"]
    H --> C
    H --> D
    C --> E["RRF fusion"]
    D --> E
    E --> F["Top-k chunks"]
    F --> G["Injected into base system prompt<br/>alongside repo-map slice + recalled pitfalls"]

Configured hybrid, observed channels. engine = "hybrid" requests lexical BM25 plus a dense vector channel fused with Reciprocal Rank Fusion; HyDE-style expansion can widen recall. Official release binaries compile the local candle backend, and the npm launcher downloads and verifies the version-matched multilingual-e5-small f16 assets on first eligible use. Plain source builds need vector-local plus a compatible model. If local vectors are unavailable, remote vectors remain disabled unless both OPENAI_EMBED_KEY and UMADEV_ALLOW_CLOUD_EMBED=1 are set. A generic OPENAI_API_KEY never authorizes upload. Missing, failed, empty, or dimension-incompatible vectors all fall back to BM25 rather than being reported as hybrid evidence.

It learns conservatively from verified incidents. A concrete failure is recorded locally, an independent recurrence can form a pending corrective rule, and the rule becomes validated only when the original verifier is rerun and passes after the exact repair attempt. This evidence is recalled to reduce repeat mistakes; it is not a promise that the base can never repeat one. Passive general lessons are deliberately not rewarded or punished until umadev can attribute the exact memory IDs sent to a host turn.

The stores have different scopes and evidence boundaries: