duaer-spec 0.1.0

package/bin/duaer.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * duaer — CLI for the duaer-spec methodology
+ *
+ *   duaer init [dir] [--all|--method|--ops] [--force] [--branch <name>]
+ *   duaer check [dir]
+ *   duaer version
+ *   duaer help
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_ROOT = resolve(__dirname, '..')
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'))
+
+const USAGE = `duaer — Duaer methodology installer (duaer-spec ${PKG.version})
+
+Usage:
+  duaer init [dir] [options]   Install Duaer into a project
+  duaer check [dir]            Verify install shape
+  duaer version                Print version
+  duaer help                   Show this help
+
+Init options:
+  --all          Agent ops + method (default)
+  --method       Method only (.duaer, skills, DUADER.md, duaer-spec rule)
+  --ops          Agent ops only (AGENTS.md, docs/agent, ops rules)
+  --force        Overwrite existing managed files
+  --branch <n>   Integration branch for baseline note (default: main)
+  --here         Same as dir=.
+
+Examples:
+  npx github:fujiezee/duaer-spec duaer init --here
+  node bin/duaer.mjs init ../my-app --all
+  duaer check .
+`
+
+function parseArgs(argv) {
+  const args = argv.slice(2)
+  const out = {
+    cmd: args[0] || 'help',
+    dir: '.',
+    mode: 'all',
+    force: false,
+    branch: 'main',
+  }
+  const rest = args.slice(1)
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]
+    if (a === '--all') out.mode = 'all'
+    else if (a === '--method') out.mode = 'method'
+    else if (a === '--ops') out.mode = 'ops'
+    else if (a === '--force') out.force = true
+    else if (a === '--here') out.dir = '.'
+    else if (a === '--branch') {
+      out.branch = rest[++i]
+      if (!out.branch) throw new Error('--branch requires a value')
+    } else if (a.startsWith('-')) {
+      throw new Error(`Unknown flag: ${a}`)
+    } else {
+      out.dir = a
+    }
+  }
+  return out
+}
+
+function ensureDir(p) {
+  mkdirSync(p, { recursive: true })
+}
+
+function copyPath(from, to, { force }) {
+  if (!existsSync(from)) {
+    throw new Error(`Package missing required path: ${from}`)
+  }
+  if (existsSync(to) && !force) {
+    const st = statSync(to)
+    if (st.isDirectory()) {
+      // merge: copy children carefully
+      for (const name of readdirSync(from)) {
+        copyPath(join(from, name), join(to, name), { force })
+      }
+      return { skipped: false, merged: true }
+    }
+    console.log(`skip (exists): ${to}  (use --force to overwrite)`)
+    return { skipped: true }
+  }
+  ensureDir(dirname(to))
+  cpSync(from, to, { recursive: true, force: true })
+  return { skipped: false }
+}
+
+function writeIfNeeded(path, content, { force }) {
+  if (existsSync(path) && !force) {
+    console.log(`skip (exists): ${path}  (use --force to overwrite)`)
+    return
+  }
+  ensureDir(dirname(path))
+  writeFileSync(path, content, 'utf8')
+  console.log(`wrote ${path}`)
+}
+
+function installMethod(target, opts) {
+  console.log('Installing Duaer method…')
+  copyPath(join(PKG_ROOT, '.duaer'), join(target, '.duaer'), opts)
+  console.log('  .duaer/')
+
+  ensureDir(join(target, '.cursor', 'skills'))
+  const skillsRoot = join(PKG_ROOT, '.cursor', 'skills')
+  for (const name of readdirSync(skillsRoot)) {
+    if (!name.startsWith('duaer-')) continue
+    copyPath(join(skillsRoot, name), join(target, '.cursor', 'skills', name), opts)
+  }
+  console.log('  .cursor/skills/duaer-*')
+
+  ensureDir(join(target, '.cursor', 'rules'))
+  copyPath(
+    join(PKG_ROOT, '.cursor', 'rules', 'duaer-spec.mdc'),
+    join(target, '.cursor', 'rules', 'duaer-spec.mdc'),
+    opts,
+  )
+  console.log('  .cursor/rules/duaer-spec.mdc')
+
+  copyPath(join(PKG_ROOT, 'DUADER.md'), join(target, 'DUADER.md'), opts)
+  console.log('  DUADER.md')
+}
+
+function installOps(target, opts) {
+  console.log('Installing agent ops…')
+  copyPath(join(PKG_ROOT, 'AGENTS.md'), join(target, 'AGENTS.md'), opts)
+  console.log('  AGENTS.md')
+
+  ensureDir(join(target, '.cursor', 'rules'))
+  for (const name of ['agents-workflow.mdc', 'ai-ui-copy.mdc']) {
+    copyPath(
+      join(PKG_ROOT, '.cursor', 'rules', name),
+      join(target, '.cursor', 'rules', name),
+      opts,
+    )
+  }
+  console.log('  .cursor/rules/agents-workflow.mdc, ai-ui-copy.mdc')
+
+  ensureDir(join(target, 'docs', 'agent'))
+  for (const name of ['workflow.md', 'change-checklist.md', 'e2e-test-plan.md', 'README.md']) {
+    copyPath(
+      join(PKG_ROOT, 'docs', 'agent', name),
+      join(target, 'docs', 'agent', name),
+      opts,
+    )
+  }
+  console.log('  docs/agent/')
+
+  const baselineSrc = join(PKG_ROOT, 'docs', 'baseline.md')
+  const baselineDst = join(target, 'docs', 'baseline.md')
+  if (!existsSync(baselineDst) || opts.force) {
+    let text = readFileSync(baselineSrc, 'utf8')
+    text = text.replace(
+      /\*\*duaer-spec itself:\*\*[^\n]*/,
+      `**This project:** integration branch \`${opts.branch}\`; replace frozen decisions below.`,
+    )
+    if (!text.includes('Integration branch')) {
+      text += `\n\n## Integration branch\n\n\`${opts.branch}\`\n`
+    } else {
+      text = text.replace(/Integration branch[^\n]*/i, `Integration branch: \`${opts.branch}\``)
+    }
+    writeIfNeeded(baselineDst, text, opts)
+  } else {
+    console.log(`skip (exists): ${baselineDst}`)
+  }
+}
+
+function writeInitMarker(target, opts) {
+  const marker = join(target, '.duaer', 'duaer-init.json')
+  ensureDir(dirname(marker))
+  const payload = {
+    version: PKG.version,
+    installedAt: new Date().toISOString(),
+    mode: opts.mode,
+    branch: opts.branch,
+    source: 'duaer-spec',
+  }
+  writeFileSync(marker, JSON.stringify(payload, null, 2) + '\n')
+  console.log('  .duaer/duaer-init.json')
+}
+
+function cmdInit(opts) {
+  const target = resolve(opts.dir)
+  if (!existsSync(target)) {
+    ensureDir(target)
+  }
+  if (!statSync(target).isDirectory()) {
+    throw new Error(`Not a directory: ${target}`)
+  }
+
+  console.log(`Target: ${target}`)
+  console.log(`Mode:   ${opts.mode}`)
+  console.log(`Branch: ${opts.branch}`)
+  console.log('')
+
+  if (opts.mode === 'all' || opts.mode === 'method') {
+    installMethod(target, opts)
+  }
+  if (opts.mode === 'all' || opts.mode === 'ops') {
+    installOps(target, opts)
+  }
+  if (opts.mode === 'all' || opts.mode === 'method') {
+    writeInitMarker(target, opts)
+  }
+
+  console.log(`
+Done.
+
+Next:
+  1. Edit .duaer/memory/constitution.md and project-context.md for this product
+  2. Confirm docs/baseline.md (integration branch: ${opts.branch})
+  3. In Cursor, use /duaer-specify → /duaer-plan → /duaer-tasks → /duaer-implement → /duaer-converge
+  4. Agent ops: AGENTS.md wins over DUADER.md when they conflict
+
+See DUADER.md and AGENTS.md in the target project.
+`)
+}
+
+function cmdCheck(dir) {
+  const target = resolve(dir)
+  const checks = [
+    ['.duaer/memory/constitution.md', 'method'],
+    ['DUADER.md', 'method'],
+    ['.cursor/rules/duaer-spec.mdc', 'method'],
+    ['.cursor/skills/duaer-specify/SKILL.md', 'method'],
+    ['AGENTS.md', 'ops'],
+    ['.cursor/rules/agents-workflow.mdc', 'ops'],
+    ['docs/agent/workflow.md', 'ops'],
+  ]
+  let missing = 0
+  console.log(`Checking ${target}\n`)
+  for (const [rel, kind] of checks) {
+    const ok = existsSync(join(target, rel))
+    console.log(`${ok ? 'ok ' : 'MISS'}  [${kind}] ${rel}`)
+    if (!ok) missing++
+  }
+  if (missing) {
+    console.log(`\n${missing} missing — run: duaer init ${dir} --all`)
+    process.exitCode = 1
+  } else {
+    console.log('\nInstall looks complete.')
+  }
+}
+
+function main() {
+  let opts
+  try {
+    opts = parseArgs(process.argv)
+  } catch (e) {
+    console.error(e.message)
+    console.error(USAGE)
+    process.exit(1)
+  }
+
+  try {
+    switch (opts.cmd) {
+      case 'init':
+        cmdInit(opts)
+        break
+      case 'check':
+        cmdCheck(opts.dir)
+        break
+      case 'version':
+      case '--version':
+      case '-v':
+        console.log(PKG.version)
+        break
+      case 'help':
+      case '--help':
+      case '-h':
+        console.log(USAGE)
+        break
+      default:
+        console.error(`Unknown command: ${opts.cmd}\n`)
+        console.log(USAGE)
+        process.exit(1)
+    }
+  } catch (e) {
+    console.error(e.message || e)
+    process.exit(1)
+  }
+}
+
+main()

package/docs/agent/README.md

@@ -0,0 +1,12 @@
+# Agent workflow (duaer-spec)
+
+Authoritative docs for *how* agents operate. Wins over Duaer and `examples/`
+when they conflict.
+
+| Doc | Description |
+|---|---|
+| [workflow.md](workflow.md) | Rules R1–R6, development loop, spec guidance |
+| [change-checklist.md](change-checklist.md) | Finish checklist |
+| [e2e-test-plan.md](e2e-test-plan.md) | E2E scenario catalog template |
+
+Root contract: [`AGENTS.md`](../../AGENTS.md). Adoption: [`ADOPT.md`](../../ADOPT.md).

package/docs/agent/change-checklist.md

@@ -0,0 +1,130 @@
+# Change Checklist
+
+> Practical finish checklist for **duaer-spec** agent ops.  
+> Cross-references: [workflow](workflow.md) · [e2e-test-plan](e2e-test-plan.md) · [ADR index](../adr/README.md) · [AGENTS.md](../../AGENTS.md)
+
+---
+
+## 0. GitHub Issue Intake
+
+When the prompt includes a GitHub issue URL or unambiguous issue number for
+this repository:
+
+- [ ] Issue title, body, labels, comments, and state were fetched.
+- [ ] The reported problem was independently verified.
+- [ ] Implementation started only after the problem was confirmed to exist.
+- [ ] If the problem does not exist: verification comment; close when clear,
+  or leave open when inconclusive.
+- [ ] After a confirmed fix was merged: resolution comment and close.
+- [ ] Comment uses the issue's language.
+- [ ] No unrelated issue was touched; push was not inferred from the link.
+
+See [R5](workflow.md#r5--verify-linked-github-issues-before-work-then-reply-and-close).
+
+---
+
+## 0.1 GitHub Pull Request Intake
+
+When the prompt includes a GitHub pull request URL or unambiguous PR number:
+
+- [ ] PR metadata, files, commits, checks, draft state, and linked issues were
+  fetched.
+- [ ] The **principle** was judged independently.
+- [ ] Completeness gaps were not treated as merge blockers.
+- [ ] If sound: merged first, preserving commits; follow-up only after `main`.
+- [ ] If unsound or harmful: not merged; evidence commented; not reimplemented.
+- [ ] Draft not merged unless the user explicitly asked.
+- [ ] Comment uses the PR's language; no force-push of the contributor branch.
+
+See [R6](workflow.md#r6--merge-a-linked-pull-request-whose-principle-is-sound-then-follow-up).
+
+---
+
+## 1. Request Start
+
+- [ ] Existing uncommitted work is identified and preserved.
+- [ ] `origin/main` fetched; local `main` fast-forwarded when clean.
+- [ ] Dedicated `<type>/<short-description>` branch and worktree created from
+  that commit.
+- [ ] Shared toolchains/caches reused where safe; mutable state stays local.
+- [ ] Current branch is not `main` before implementation begins.
+
+---
+
+## 2. Impact Analysis
+
+- [ ] What behavior changes?
+- [ ] Which specs / Duaer features are affected? (list paths)
+- [ ] Architectural boundary? (contracts, storage, security, public API)
+- [ ] User-visible or protocol-visible?
+- [ ] Smallest targeted validation set (or none, with reason)?
+
+See [spec update guidance](workflow.md#3-spec-update-guidance).
+
+---
+
+## 3. Spec Sync
+
+- [ ] Every affected spec is updated.
+- [ ] Architectural boundary change → ADR under `docs/adr/`.
+- [ ] Cross-references still correct (no stale links).
+
+---
+
+## 4. E2E / Test Docs
+
+- [ ] User/protocol-visible change → scenario added or updated in the project's
+  E2E catalog ([template](e2e-test-plan.md)).
+- [ ] Unit/integration tests updated when risk requires them.
+- [ ] Targeted local checks passed, or assessed unnecessary.
+- [ ] E2E suites run only if the user explicitly requested them (except fork
+  landing rules in `AGENTS.md`).
+
+---
+
+## 5. Git Commit
+
+- [ ] One logical unit (or split into focused commits).
+- [ ] No secrets, tokens, or local data.
+- [ ] No build artifacts or dependency trees in the diff.
+- [ ] Message: `type(scope): description` (English, imperative).
+- [ ] `git diff --stat` reviewed — nothing unexpected.
+
+---
+
+## 6. Merge / PR
+
+- [ ] Branch refreshed against latest `main`.
+- [ ] Merged into local `main` (and/or remote PR/MR when required).
+- [ ] Only this request's logical changes included.
+- [ ] Push performed only if the user explicitly asked for this request.
+
+---
+
+## 6.1 Merge Cleanup
+
+- [ ] Expected commits present in `main`.
+- [ ] Request worktree clean.
+- [ ] `git worktree remove <path>` succeeded without forcing.
+- [ ] `git branch -d <branch>` succeeded (no `-D` on unmerged).
+- [ ] `git worktree prune`; no stale entry for this request.
+- [ ] No other agent's worktree or branch was removed.
+
+---
+
+## 7. Definition of Done
+
+| # | Gate | Source |
+|---|---|---|
+| 1 | Branch + worktree from up-to-date `main` | [R4](workflow.md#r4--request-branch--worktree--merge-gate) |
+| 2 | Change implements the planned work | [Development loop](workflow.md#2-development-loop) |
+| 3 | Impacted specs updated | [R1](workflow.md#r1--spec-first--spec-sync) |
+| 4 | E2E docs updated or confirmed unnecessary | [R3](workflow.md#r3--e2e-coverage-doc) |
+| 5 | Targeted validation done or waived with reason | Development loop |
+| 6 | Conventional commits | [R2](workflow.md#r2--commit-per-change) |
+| 7 | No secrets or local data | [§4](workflow.md#4-what-never-to-commit) |
+| 8 | Merged into `main`; worktree and branch removed | [R4](workflow.md#r4--request-branch--worktree--merge-gate) · [§6.1](#61-merge-cleanup) |
+| 9 | Linked issue: verified, commented, closed when conclusive | [R5](workflow.md#r5--verify-linked-github-issues-before-work-then-reply-and-close) |
+| 10 | Linked PR: principle reviewed; merged when sound; follow-up after | [R6](workflow.md#r6--merge-a-linked-pull-request-whose-principle-is-sound-then-follow-up) |
+
+If any gate fails, the change is **not Done**.

package/docs/agent/e2e-test-plan.md

@@ -0,0 +1,33 @@
+# E2E test plan (template)
+
+Each adopting project should maintain its own E2E scenario catalog. This file is
+a **template** for that catalog — not a product suite.
+
+When a change is user-visible or protocol-visible, add or update a scenario
+before or alongside the change (see [R3](workflow.md#r3--e2e-coverage-doc)).
+
+## Scenario template
+
+```text
+ID:          E2E-NNN
+Title:       Short name
+Preconditions:
+Steps:
+Expected:
+Specs:       Links to specs / Duaer feature dirs
+Status:      planned | automated | manual
+```
+
+## Catalog
+
+| ID | Title | Status |
+|---|---|---|
+| — | *(replace with project scenarios)* | — |
+
+## Traceability
+
+Keep this matrix current when scenarios or specs change.
+
+| Scenario | Spec / feature | Notes |
+|---|---|---|
+| — | — | — |

package/docs/agent/workflow.md

@@ -0,0 +1,127 @@
+# AI-Assisted Development Workflow
+
+> Scope: **duaer-spec** agent ops (adoptable by other repositories)  
+> Status: Accepted  
+> Precedence: this document and root `AGENTS.md` win over Duaer / examples  
+> Cross-references: [baseline](../baseline.md) · [e2e-test-plan](e2e-test-plan.md) · [change-checklist](change-checklist.md) · [ADR index](../adr/README.md) · [ADOPT](../../ADOPT.md)
+
+---
+
+## 1. Core Immutable Rules
+
+R1–R4 restate the numbered Immutable Rules in `AGENTS.md` (R4 covers merge-back
+and worktree clean-up). R5 and R6 restate GitHub issue and pull request
+handling. They cannot be relaxed without explicit human override.
+
+### R1 — Spec-first / Spec-sync
+
+> **No behavior change without updating the corresponding spec.**
+
+- Every change that alters observable behavior must update the relevant
+  specification (project `docs/spec/`, Duaer feature specs, or
+  `docs/agent/` when changing duaer-spec itself).
+- Architectural boundary changes also require an ADR under `docs/adr/`.
+- Pure refactors that preserve behavior and contracts do not require spec
+  updates, but must still be committed (R2).
+
+### R2 — Commit-per-change
+
+> **Every completed logical change must be git committed.**
+
+- One logical unit per commit. No large uncommitted piles at session end.
+- Incomplete work: commit as `WIP:` draft or roll it back.
+
+### R3 — E2E coverage doc
+
+> **User-visible or protocol-visible changes must update E2E scenario docs.**
+
+- Document scenarios in the project's E2E catalog (see
+  [e2e-test-plan](e2e-test-plan.md)).
+- Internal-only changes (logging format, private renames) do not require it.
+
+### R4 — Request branch + worktree + merge gate
+
+> **Every new request starts from `main` in a dedicated worktree on a dedicated
+> branch and finishes only after it is merged into `main`.**
+
+- Before editing: preserve existing uncommitted work; fetch and fast-forward
+  local `main` when clean; create a new request branch and worktree from that
+  commit. Never stash or overwrite another agent's work merely to start.
+- Name branches `<type>/<short-description>` (for example `feat/adopt-docs`).
+- Do not implement in the primary checkout or reuse another request's worktree.
+- Reuse shared toolchains and caches where safe; keep mutable or
+  concurrency-sensitive state worktree-local and ignored.
+- After validation: merge into local `main` (or via PR/MR when required), then
+  remove the request worktree and delete the merged branch immediately.
+- Push only when the user explicitly requests remote publishing for this
+  request.
+
+Adopting projects may replace `main` with another integration branch; document
+it in the project baseline. **duaer-spec itself uses `main`.** Example overlays
+under `examples/` do not change this repo's default.
+
+### R5 — Verify linked GitHub issues before work, then reply and close
+
+> **A linked GitHub issue is not a task until the reported problem is shown to
+> exist. After a conclusive outcome, reply and close.**
+
+Applies when the prompt includes a GitHub issue URL or unambiguous issue number
+for this repository. Comment in the issue's language. An issue link does not
+authorize push.
+
+### R6 — Merge a linked pull request whose principle is sound, then follow up
+
+> **Judge principle first. Merge that PR when sound; completeness is follow-up.**
+
+Do not silently reimplement. Do not force-push the contributor branch. Draft
+PRs stay unmerged unless the user explicitly asks. A PR link does not authorize
+unrelated pushes.
+
+---
+
+## 2. Development Loop
+
+1. **Intake** — If an issue or PR is linked, complete R5 / R6 first.
+2. **Isolate** — Update `main`, create branch + worktree (R4).
+3. **Orient** — Read baseline, relevant specs, and Duaer memory when present.
+4. **Specify (when using Duaer)** — Feature / hotfix specs before coding.
+5. **Implement** — Smallest coherent change; update specs alongside (R1).
+6. **Verify** — Targeted checks; E2E runs only if the user asks (except fork
+   landing rules in `AGENTS.md`).
+7. **Commit** — One logical change per commit (R2).
+8. **Merge & clean** — Refresh against `main`, merge, remove worktree (R4 / R5).
+9. **Report** — Use the Final Report section in `AGENTS.md`.
+
+---
+
+## 3. Spec Update Guidance
+
+| Change type | Spec sync | ADR |
+|---|---|---|
+| User-visible or protocol-visible behavior | Required | If architecture / contracts / security boundaries change |
+| Internal refactor, same behavior | Not required | No |
+| New public interface or data ownership | Required | Required |
+| Docs-only / standards-only in this repo | Update `docs/` / `AGENTS.md` as needed | If a frozen decision changes |
+
+Prefer Duaer feature directories for product feature work. Prefer `docs/agent/`
+when changing duaer-spec's own agent-ops contract.
+
+---
+
+## 4. What Never to Commit
+
+- Secrets, tokens, credentials, private keys
+- Local databases, caches, build artifacts, `node_modules/`
+- Machine-specific paths or environment files with secrets
+- Unrelated changes from another request or agent
+
+---
+
+## 5. Duaer Relationship
+
+- **Agent ops** (`AGENTS.md`, this file): isolation, commits, Issue/PR, merge.
+- **Duaer** (repo root `.duaer/`, `DUADER.md`): what to build — specify →
+  plan → tasks → implement → converge.
+
+When they conflict, **agent ops win**. Install and conventions:
+[DUADER.md](../../DUADER.md) · [ADOPT.md](../../ADOPT.md).

package/docs/baseline.md

@@ -0,0 +1,10 @@
+# Baseline (project-specific)
+
+Frozen decisions for the adopting project: language, stack, architecture
+boundaries, and integration-branch override (if not `main`).
+
+**duaer-spec itself:** English docs and commits; integration branch `main`;
+no application runtime.
+
+When you copy agent ops into another repository, replace this file with that
+product's baseline (or point agents at the project's existing baseline path).

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "duaer-spec",
+  "version": "0.1.0",
+  "description": "Duaer Spec-Driven Development methodology + agent ops for AI coding agents",
+  "type": "module",
+  "bin": {
+    "duaer": "bin/duaer.mjs",
+    "duaer-spec": "bin/duaer.mjs"
+  },
+  "files": [
+    "bin",
+    ".duaer",
+    ".cursor",
+    "AGENTS.md",
+    "DUADER.md",
+    "ADOPT.md",
+    "CHANGELOG.md",
+    "docs/agent",
+    "docs/baseline.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fujiezee/duaer-spec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fujiezee/duaer-spec/issues"
+  },
+  "homepage": "https://github.com/fujiezee/duaer-spec#readme",
+  "keywords": [
+    "duaer",
+    "spec-driven",
+    "agents",
+    "cursor",
+    "ai-engineering",
+    "methodology"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "duaer": "node ./bin/duaer.mjs"
+  }
+}