duaer-spec
Duaer turns AI coding agents into digital employees that deliver
satisfactory work: you speak in normal language; the employee turns that
into a checkable Brief (goal / boundary / acceptance), implements only that
scope, and only claims done when acceptance is met.
The product pitch is norms → satisfactory delivery — not teaching humans
to operate Spec phases, slash commands, or a professional delivery process.
You do not need to understand that process. After a one-time install, talk
in Cursor or Claude Code in plain language; the employee runs the
workflow.
One-time install
npx duaer-spec init --here
Update
Global CLI (when duaer is installed globally):
npm i -g duaer-spec@latest # works on any build (incl. older CLIs without self-update)
duaer self-update # same as above once CLI ≥ 0.13
The CLI also prints a one-line hint when a newer npm release exists
(cache ≤24h; disable with DUAER_NO_UPDATE_CHECK=1).
Product repo adapters (after init):
npx duaer-spec update
Then use Cursor or Claude Code — describe what you want in plain
language. You do not need to learn Spec phases or slash commands.
init / update also write optional adapters for other editors (see
ADOPT.md). FDE console dispatch launches Cursor Agent or
Claude Code only.
Chinese guide: README.zh-CN.md
What you get
After install, these are the capabilities you actually use:
In your editor: a digital employee that delivers
- You talk; it runs the process. No slash commands, no “you must run Spec phases.”
- Clarify before coding. It turns your ask into: what to build, what not to build, how we know it’s done.
- Done means accepted. It only claims finished when acceptance checks out — not when code merely exists.
- Reviewed before done. It codes the Ponytail way (smallest complete change) and runs a Ponytail review of its own diff before accept. If it skips that,
duaer check keeps the job open, and in Claude Code a stop hook sends it back.
- Optional PR mode. Turn on
.duaer/memory/pr.json and every job merges through a GitHub PR: CI failures go back to the employee, and the PR auto-merges when green.
- Supported in Cursor and Claude Code. Install once, then speak there — no professional Spec workflow required. (Optional adapters for other editors:
ADOPT.md.)
In the browser: Duaer-spec FDE (live console)
A local web console (duaer live) for “chat → confirm → dispatch → watch → open result”:
- Projects. Create and switch projects; each keeps its own chat and progress.
- Chat until the ask is clear. Left chat; center confirm cards (goal / out of scope / checkable acceptance). Feature cards also need device matrix, critical paths, and exception cases. Vague acceptance cannot be confirmed. Beside Send, tap Record to capture speech; with a speech recognition (STT) model in Settings (OpenAI-compatible
/audio/transcriptions, e.g. whisper-1), the clip is decoded into the composer—edit, then send.
- Split big work into modules. Confirm module by module; nothing starts until you kick off after the ones you care about are confirmed.
- Architecture diagram. After requirements, review the system diagram; click it for fullscreen; kickoff waits until architecture is confirmed. If chat claims the diagram is ready but the middle panel is empty, the same bubble offers Regenerate — it does not leave a false “ready” line.
- Sign the scope + acceptance baseline before kickoff. After architecture confirm, an operator must sign (signer + time; fingerprint of confirmed module cards). Unsigned or stale fingerprints block Write Brief and start. An open change (with reason) clears the sign, returns modules for re-confirm, then architecture and re-sign.
- Dispatch digital employees to code. Pick a product folder and Cursor Agent or Claude Code; work happens in an isolated worktree, not directly on your long-lived branches.
- Visible task progress. Work is a checklist; each finished item is checked off and the console refreshes; dependent tasks release in waves so agents don’t pile on blocked work.
- Employee roles. Top-bar digital employee directory (Implementer / Functional regression / Deployer). Optional parallel workers on the same CLI. See the next section.
- Locales. Console UI: zh-CN, zh-TW, en, ja, ko, es, pt-BR, fr, de, ru, vi.
- Deliverables and results. Open a deliverables page (requirements timeline,
confirmation, baseline sign-off and change history, architecture, tasks,
delivery); when done, open the page or the project folder.
- Revise when it’s not right. Continue in left chat → re-confirm → relaunch on
the same job without starting from scratch. After deploy, Revise again and
Fix a bug stay on the result bar.
- Fix a bug. Defect card (no multi-module growth); architecture skipped by
default; short pool and branch (optional hotfix from ). Delivery
facts autofill; defects join the same project timeline as revisions.
Digital employees: three roles
Open Employees in the top bar. Runtime is still Cursor Agent or Claude Code; the difference is task role — who builds, who regresses, who deploys.
| Role | Does | Does not |
|---|
| Implementer | Build to acceptance; update product README; start preview and stamp delivery | — |
| Functional regression | Check confirmed acceptance against the product .duaer/memory/testing.md risk table (prefer Playwright, npm test, npm run test:live, L0–L3); add missing tests, run them, keep evidence | Change product scope; on failure, leave a reproducible note — do not stamp accepted |
| Deployer | Publish to the planned host and write the public URL into delivery preview | Change product scope |
With multiple workers, the last lane owns functional regression (and deploy tasks); implement work stays on earlier lanes. With one worker, the same CLI session runs roles in task order.
Before a job can stay accepted, the console runs the commands in the product .duaer/memory/verify.json. A non-zero exit, or a missing contract, reopens delivery. Docs-only work must set { "waiver": "docs-only" } explicitly.
PR mode (opt-in). With .duaer/memory/pr.json set to { "enabled": true, "base": "develop" }, a job merges through a GitHub PR instead of a local merge: push → gh pr create → CI → failures and Request changes go back to the employee as tasks (at most 3 CI rounds) → auto-merge when green. A job counts as accepted only when its PR is merged. Needs gh logged in. Turning it on authorizes pushing the request branch and merging its PR.
Code review gate. Employees code the Ponytail way (smallest complete change). Before accept they run ponytail-review on the job diff and save review.md in the Brief. Only Verdict: Ship. for the current code passes; Must fix items go back as tasks, at most 2 rounds. duaer init installs the Ponytail skills for Claude Code, Cursor and Codex and merges a stop hook into .claude/settings.json and .cursor/hooks.json, so the gate also holds when Claude Code or Cursor runs the duaer-spec rules on its own, in the terminal or the editor, without the console. duaer check / duaer job, the stop hooks and the console all reopen a stamp that fails it.
Deploy: supported hosts
Before kickoff, pick a planned host on the console. Coding follows that platform; the Deployer employee publishes and writes the public URL into delivery preview.
| Option | Good for | You prepare |
|---|
| No deploy yet | Local delivery only | Nothing |
| GitHub Pages | Static / docs sites; default when hosting is implied but no host was chosen | GitHub repo + gh auth |
| Cloudflare | Pages for static; Workers for edge APIs | API Token + Account ID in console Settings |
| Alibaba Cloud | OSS (+ CDN) for static; Function Compute and similar for APIs | AccessKey in console Settings |
| AWS | S3 + CloudFront for static; Amplify / Lambda and similar when needed | Access keys in console Settings |
Detail: docs/agent/deploy-targets.md · GitHub default path: docs/agent/deploy-github.md
Repo habits (for humans and employees)
- Clear branches:
main for production, develop for day-to-day, short feat/fix branches merge back to develop.
- Isolated changes: each request uses its own worktree; after merge, clean up and hand local services back to the primary checkout.
The sections below are how to run it; this section is what it can do.
What the employee does (by itself)
- Turns your ask into a Brief with checkable acceptance
- Implements within that Brief
- Verifies against acceptance (and project testing rules)
- Runs a Ponytail review of its diff; fixes Must fix items (at most 2 rounds)
- In PR mode: opens a PR, fixes CI failures (at most 3 rounds), auto-merges when green
- Stamps accept only when the result should satisfy you — one handoff line
Step skills and CLI checks exist for agents and power users — not as the
everyday human UI.
Duaer-spec FDE (live console)
Isolated from product repos. Config and Briefs live under ~/.duaer/live/.
Duaer-spec FDE = Field Development Environment.
# Start anytime (opens the console even if the model is not configured yet)
duaer live
# In the page Settings, or via CLI:
duaer live config --provider deepseek --api-key sk-...
# Remember a product repo for dispatch (optional; run inside that repo)
duaer live repo add
duaer live opens the browser to the console URL (default http://127.0.0.1:8787).
If the model is missing, use Settings in the page. The console is full-width
with three columns: chat | modules / confirm / architecture / kickoff /
revise | task progress. Detail:
docs/agent/live-desk.md.
Verify (maintainers / agents): after Duaer-spec FDE UI or validate-gate changes,
run npm run test:live (L3 smoke: console shell markers + /api/validate with a
mock LLM — no paid API).
Flow
- Open or create a project, then chat. The Projects drawer shows each
project’s delivery status; open Deliverables when the session has
content. Messy multi-topic talk is fine: the console evolves
modules[]
(tabs). Chat bubbles render Markdown (**bold**, code, links).
- Per module: fill the confirm card (goal / out-of-scope / checkable
acceptance / assumptions; feature cards also need device matrix /
critical paths / exception cases). Vague acceptance or missing baseline
fields fails the gate; validate must pass before Confirm. Confirming a
module locks that card only — it does not write a Brief or start
workers yet. Jump between modules freely.
- When all modules you care about are confirmed → review / confirm
architecture (Archify) → sign the scope + acceptance baseline
(signer) → kickoff. Kickoff stays blocked while unsigned or when the
fingerprint no longer matches confirmed cards. Kickoff writes the Brief,
builds a dependency-aware task pool (
dependsOn), and assigns work.
Default is 1 worker; optionally N parallel workers on the same
CLI. Shared tasks go to worker 1; module tasks round-robin. Each worker
gets its own Terminal queue lane (live-terminal /
live-terminal/w2…). To change scope: open change (reason) → clear
sign and re-confirm modules → architecture again → re-sign.
- Pick a product repo (browse / scan / recent), or paste a path / project name.
Missing paths are created; set Projects parent folder so short names
resolve under it. Non-git folders get
git init -b develop; missing
develop/main/master creates local develop.
- Choose a CLI digital employee: Cursor Agent or Claude Code
- Cursor:
curl https://cursor.com/install -fsS | bash
- Claude Code:
npm install -g @anthropic-ai/claude-code (or curl -fsSL https://claude.ai/install.sh | bash)
- To run DeepSeek or other models for coding, point Claude Code at that API — see . The FDE setup page guide covers the same.
Worktree id ≠ Brief folder name — use .worktree/feat-<name>/, Brief under .duaer/specs/<nnn-slug>/ inside that worktree.
Branches (mandatory)
| Branch | Role |
|---|
main | Production / online |
develop | Day-to-day integration |
feat/<name> | Features → develop |
fix/<name> | Fixes → develop (hotfix via main) |
Go-live and flows by issue type:
docs/agent/branching-and-release.md.
After merge: duaer handoff [--run] restarts local services on develop
(configure commands in .duaer/handoff.json).
Optional
npx duaer-spec init --here --method
Details: ADOPT.md · Method: DUADER.md · Ops: AGENTS.md
When agent ops and method conflict, agent ops win.
