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)

1. Turns your ask into a Brief with checkable acceptance
2. Implements within that Brief
3. Verifies against acceptance (and project testing rules)
4. Runs a Ponytail review of its diff; fixes Must fix items (at most 2 rounds)
5. In PR mode: opens a PR, fixes CI failures (at most 3 rounds), auto-merges when green
6. 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

1. 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).
2. 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.
3. 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.
4. 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.
5. 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.