# Dominds — DevOps Mindsets — Sustainable Agentic Product Lifecycle

> Ship your product with an AI DevOps team that self-improves while it works.

> Agents should be sustaining the continuous development of your products, one-shot product creation is hallucination.

- Chinese version: [中文版](./README.zh.md)

## CAVEATS

- **NO WARRANTY / AT YOUR OWN RISK**: Dominds is powerful automation. If you point it at the wrong repo, give it the wrong goal, or trust output blindly, it can waste time or cause damage.
  - Keep backups and review changes carefully (especially before merging or deploying).
  - Prefer running on a disposable clone or non-critical branch until you trust your workflow.

- **No Human Permission Mechanism (won’t-have)**: Dominds does not aim to add a per-action “please approve” prompt for tool usage.
  - The intended safety model is _hard guardrails via workflow/policy_ (planned), not human-in-the-loop popups.
  - Put high-risk tools behind principled agents so their judgment enforces policies and mitigates risk.
  - Use least-privilege credentials and avoid production secrets in `.env` when experimenting.
  - Treat your rtws (runtime workspace) as sensitive: dialogs, logs, and memory may persist locally on disk.

- **Authorize Your Agents (or don’t use Dominds)**: Dominds is not pair‑programming. Once authorized, agents will act — assume mistakes and review outcomes from a distance.
  - If you prefer to work closely with your agents, use a more traditional copilot‑style tool.
  - You’re not a hands‑on driver; you’re fully responsible for the consequences of the team you define and animate — trust them to execute, stay remote, and accept the outcomes, good or bad.

- **Costs / Privacy / Compliance**: using LLM providers can cost money and may send prompts (sometimes including code) to third parties.
  - Review provider terms, set spending limits, and avoid putting secrets in prompts.
  - If you need strict privacy/compliance, evaluate self-hosted models and stricter tool policies.

- **Help Yourself (early community)**: Dominds is LGPL, with limited support and a young community.
  - Expect rough edges, breaking changes, and gaps in docs; issues/PRs are welcome.

## Table of Contents

- [Dominds — DevOps Mindsets — Sustainable Agentic Product Lifecycle](#dominds--devops-mindsets--sustainable-agentic-product-lifecycle)
  - [Table of Contents](#table-of-contents)
  - [What is Dominds?](#what-is-dominds)
  - [Installation](#installation)
    - [Prerequisites](#prerequisites)
    - [Install Dominds](#install-dominds)
    - [rtws Setup](#rtws-setup)
  - [Quick Start](#quick-start)
  - [Start from scratch](#start-from-scratch)
  - [Core Philosophy](#core-philosophy)
    - [1) Clear minds, focused tasks](#1-clear-minds-focused-tasks)
    - [2) Tools with intent: safe by design](#2-tools-with-intent-safe-by-design)
    - [3) Diverse, self‑improving team from templates](#3-diverse-selfimproving-team-from-templates)
  - [Documentation](#documentation)
    - [Getting Help](#getting-help)

## What is Dominds?

Dominds is an AI-powered DevOps framework that creates autonomous agentic teams with persistent memory and self-improving capabilities. Unlike traditional AI assistants, Dominds agents maintain context across conversations, learn from experience, and collaborate as a cohesive team to handle complex development workflows.

**Key Features:**

- **Local-first Runtime**: The orchestration layer runs on your machine and persists team state locally in your rtws (runtime workspace). LLM calls still go to your configured provider (so apply normal cost/privacy discipline).

- **Transparent rtws Integration**: Agent personas, know-how, pitfalls, and other mindset artifacts are stored locally as part of your rtws. This maximizes transparency to humans and enables version control alongside your product code, creating a complete historical record of both human and AI contributions to your project.

- **Persistent Team Memory**: Agents maintain context across conversations, remember past decisions, and build upon learned patterns. Teams evolve their practices and knowledge over time, with all insights preserved in your rtws.

- **Collaborative Intelligence**: Multiple specialized agents work together on shared tasks, combining their unique capabilities while maintaining clear communication channels and shared understanding through rtws-stored context.

- **Safe Tool Access**: AI-driven guardrails provide secure access to powerful development tools, with all safety policies and access patterns transparently stored and version-controlled within your rtws.

- **Task-Focused Architecture**: Clear, bounded contexts prevent cognitive overload while maintaining rich inter-agent communication and knowledge sharing through the local rtws knowledge base.

## Installation

### Prerequisites

- **Node.js (with npm bundled)**: Version 24.5+ LTS
- **npm (if used directly)**: Use the npm bundled with your installed Node.js 24 LTS; current minimum in this repo is `11.16.0`, and newer versions are allowed.
- **LLM provider configured for your team**: Dominds ships with a built-in provider catalog [main/llm/defaults.yaml](./main/llm/defaults.yaml) including Codex (ChatGPT) and Anthropic, plus several Anthropic-compatible endpoints (e.g. MiniMax, Z.ai, BigModel). You’ll need valid credentials for at least one provider.
- **pnpm (optional)**: Recommended only if you’re developing Dominds itself. Prefer enabling the pinned CLI once via `npm run setup:pm`. If Corepack shims cannot be enabled in your environment, install `pnpm@11.5.0` manually.

For repo development, initialize the package manager once after `nvm use --lts`:

```bash
npm run setup:pm
```

### Proxy Support

Dominds can use Node's built-in environment proxy handling on Windows, macOS, and Linux.

Default behavior:

- `DOMINDS_USE_ENV_PROXY` is enabled by default.
- When enabled, Dominds calls Node's runtime env-proxy initializer early in CLI startup.
- Dominds does not set or clear `NODE_USE_ENV_PROXY`; leave that variable for users who intentionally want Node startup-time or child-process behavior.
- Set `DOMINDS_USE_ENV_PROXY=0` to stop Dominds from auto-enabling env-proxy support.

Supported proxy variables:

- `HTTP_PROXY`
- `HTTPS_PROXY`
- `NO_PROXY`
- `http_proxy`
- `https_proxy`
- `no_proxy`

Practical guidance:

- Set both `HTTP_PROXY` and `HTTPS_PROXY` when your network uses the same proxy for both schemes. Lowercase forms also work.
- Use `NO_PROXY` for hosts that should bypass the proxy. Node's built-in support includes exact hosts, suffix matches like `.company.com`, wildcard hosts like `*.company.com`, exact IPs, IP ranges like `192.168.1.1-192.168.1.100`, and `host:port` entries.
- `NO_PROXY` syntax is not standardized across languages and clients. Do not assume CIDR notation such as `192.168.0.0/16` is supported unless the specific runtime documents it.
- Values should be standard proxy URLs, for example `http://proxy.company.com:8080`.
- If your shell already exports proxy variables, Dominds will read them too; clear unrelated proxy vars if you want a clean test environment.

Examples:

```bash
# Windows PowerShell
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.corp.local,192.168.1.1-192.168.1.100"
dominds

# macOS / Linux shell
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.local,192.168.1.1-192.168.1.100"
dominds

# Disable Dominds env-proxy handling
export DOMINDS_USE_ENV_PROXY=0
dominds
```

### Install Dominds

```bash
# Global installation (recommended)
npm install -g dominds
# (or) pnpm add -g dominds

# Verify installation
dominds --help
```

You can also run Dominds with **no global install** (useful for quick trials / CI / keeping your machine clean):

```bash
# Run the latest release (downloads to npm cache, then executes)
npx -y dominds@latest --help
npx -y dominds@latest

# Or pin an exact version (more reproducible)
# npx -y dominds@1.2.3
```

Notes:

- `npx dominds` does **not** necessarily mean “always latest”: if your project already has `dominds` installed, or your npm cache already contains an older version, `npx` may reuse that.
- If you want “resolve whatever `latest` points to”, use `dominds@latest` explicitly. It may still reuse the cached copy of that same version (expected).

### Installing Dominds apps

Installing the `dominds` CLI itself and installing a **Dominds app** into your current rtws are two different operations:

- `npm install -g dominds` / `pnpm add -g dominds`: install the Dominds CLI.
- `npx -y dominds@latest`: run the Dominds CLI without a global install.
- `dominds install <app>`: add a Dominds app into the current rtws capability graph.

Examples:

```bash
# Install a published app into the current rtws
dominds install @longrun-ai/web-dev --enable

# Install a local app under development into the current rtws
dominds install ./dominds-apps/@longrun-ai/web-dev --local --enable
```

Important distinctions:

- `npm install` / `pnpm add` only download packages; they do **not** register an app into `.minds/app.yaml` for the current rtws.
- `npx` is used by the kernel/CLI as a package-execution backend. For app installation, the kernel may execute `npx -y <pkg> --dominds-app` under the hood.
- `--dominds-app` is a low-level app handshake flag between the kernel/CLI and the app package. It is not the normal end-user interface.

For development and any sort of open source contribution, use the in-tree dev wrapper rtws:

https://github.com/longrun-ai/dominds-feat-dev

1. Clone dominds-feat-dev
2. Clone your dominds fork into dominds-feat-dev/dominds/
3. Open PRs against [longrun-ai/dominds](https://github.com/longrun-ai/dominds) from that inner repo

### Contributor Test Rule (Script rtws Isolation)

When running script tests inside the Dominds repo (for example `pnpm -C tests run rtws -- ...`):

- Start with `pnpm -C tests run` to list available scripts, then run target suites via `pnpm -C tests run <script-name>`.
- Default mode is **isolated rtws**: each run copies `tests/script-rtws` into a unique temp rtws before execution.
- Because isolation is default, script tests are safe to run in parallel; do not rely on shared-rtws serial assumptions.
- Use `--shared-rtws` for debugging only; it runs directly in `tests/script-rtws` and must not be used concurrently.
- Set `DOMINDS_TEST_RTWS_KEEP_TMP=1` if you want to keep temporary rtws artifacts for post-failure debugging.

### rtws Setup

There are two common ways to create an rtws:

- **Recommended**: start from a scaffold/template (see [Quick Start](#quick-start)).
- **Minimal**: start from an empty folder (see [Start from scratch](#start-from-scratch)).

Dominds uses your current working directory as the runtime workspace (rtws). When you start `dominds`, the WebUI listens on `5666` or the next available lower port, then automatically redirects to `/setup` if the rtws is missing required configuration (for example `.minds/team.yaml` or provider env vars).

Note: In production mode, Dominds enables a local shared-secret auth key by default, so the browser may open with a URL containing `?auth=...`. Treat that token as sensitive.

**Template creation (recommended)**:

```bash
# Use official scaffold templates (default base = https://github.com/longrun-ai)
dominds create web-scaffold my-project

# Use custom organization templates
export DOMINDS_TEMPLATE_BASE="https://github.com/myorg"
dominds create web-scaffold my-project

# Or use full URLs for any template
dominds create https://github.com/myorg/custom-template.git my-project
```

**Template Resolution:**

- Short names like `web-scaffold` resolve to `${DOMINDS_TEMPLATE_BASE}/web-scaffold.git`
- Default `DOMINDS_TEMPLATE_BASE` is `https://github.com/longrun-ai`
- Set your own `DOMINDS_TEMPLATE_BASE` for organization-specific templates

For more template options, see the [CLI Usage Guide](docs/cli-usage.md#rtws-creation).

## Quick Start

```bash
# 1) Create an rtws from a scaffold template
dominds create web-scaffold my-project
cd my-project

# 2) Start the WebUI (opens a browser by default)
dominds
```

Then:

1. Your browser should land on the local WebUI `/setup` page (usually `http://localhost:5666/setup`, unless that port was already occupied).
2. In **Setup**, pick a provider + model. If your template didn’t create `.minds/team.yaml`, use Setup to create/overwrite it (this writes a minimal `member_defaults` config).
3. Still in **Setup**, set the required provider env var (the name comes from the provider catalog, e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `CODEX_HOME`, etc.).
   - The setup UI can write it to `.env.local` (all platforms), and on Linux/macOS it can also write into `~/.zshrc` / `~/.bashrc` in managed blocks. It also applies the value to the running server process immediately.
4. Click **Go to App**, create a dialog, and start working.

Platform note:

- Windows also registers `codex_inspect_and_patch_tools`; its `readonly_shell` tool runs through `cmd.exe`, so prefer allowlisted commands available in that shell/PATH, such as `rg`, `git`, `dir`, `type`, and `where`.

### Local HTTPS Certificates

Dominds always keeps an HTTP listener. When a valid certificate matching the current `--host` exists under `~/.dominds/certs/`, Dominds also starts HTTPS. Certificates match DNS/IP hostnames, not ports, so one certificate covers all Dominds WebUI ports on that host.

Dominds generates certificates through npm dependencies, so no separate `openssl` command is required.

```bash
# Create a 10-year self-signed certificate for detected non-loopback LAN hosts
dominds cert create

# Add explicit SAN hosts; --host can be repeated
dominds cert create --host 192.168.1.10 --host my-host.local

# Inspect whether the detected LAN hosts can use an HTTPS certificate
dominds cert status
```

`localhost`, `loopback`, `127.0.0.0/8`, `169.254.0.0/16`, `::1`, `fe80::/10`, `0.0.0.0`, and `::` are not certificate hosts. `0.0.0.0` / `::` only mean bind-all; certificate matching uses detected non-loopback LAN hosts. A bare `--port 5666` disables Dominds built-in HTTPS and assumes a front proxy handles HTTPS, while the default port behavior and `--port 5666+/-` may auto-enable built-in HTTPS when a matching certificate exists.

## Start from scratch

Starting from scratch means: create an empty folder, run `dominds`, let Setup generate the minimal `.minds/team.yaml`, then use the shadow team manager (`@fuxi`) to design a real team for your product.

```bash
mkdir my-rtws
cd my-rtws

# Starts the WebUI server and opens a browser (default port behavior: 5666-)
dominds
```

1. The WebUI should redirect you to the local `/setup` page because the rtws has no `.minds/team.yaml` yet.
2. In **Setup**:
   - Select a provider + model and click **Create `.minds/team.yaml`**.
   - Provide the required provider env var and write it to your shell rc (or set it manually). Setup applies it immediately to the running server.
   - Click **Go to App**.
3. In the app, create a new dialog with **shadow member** `@fuxi` (Fuxi is hidden by default; use the “Shadow members” picker in the dialog creation modal). Until you add visible members, you’ll mostly work through shadow members.
4. Tell `@fuxi` your product idea and ask it to propose and apply a suitable agentic team configuration by updating `.minds/team.yaml` (Fuxi has the `team_mgmt` toolset scoped to `.minds/**`).

## Build from source

When developing Dominds itself, use the integrated build entry from the repo root:

```bash
pnpm run clean
pnpm run build
pnpm run lint:types
```

Notes:

- `pnpm run build` is the canonical full build. It runs backend first, then frontend.
- `pnpm run build:backend` and `pnpm run build:frontend` are sub-steps for focused debugging. They are not the recommended "full rebuild" command.
- Do not manually run multiple top-level build commands in parallel. They share `dist/` outputs, so concurrent runs can create racey, misleading results.
- The backend build may still let pnpm build independent workspace packages concurrently according to the workspace dependency graph. That scheduler-controlled concurrency is expected.

## Core Philosophy

Dominds is designed for long-running product development and operations, with a “division of labor” constitution:

- Reduce **agent mental overhead** by dividing and distributing work across a team of specialized agents, and by using more effective **dialog course control** (instead of brittle context condensation) to shed conversational/tool-output noise when a dialog becomes cluttered.
- Prevent **tool misuse** by putting side-effectful tools only in the hands of well-prompted specialist agents, via least-privilege toolsets/policies.
- Prevent **staleness** (agents acting on outdated assumptions) by encoding decisions, conventions, configuration, and key repo facts into version-tracked rtws artifacts intended to be loaded into agent context (team-shared and agent-individual memory, Taskdocs, and dialog-local reminders), rather than leaving them as “undiscovered” knowledge scattered across the repo.

### 1) Clear minds, focused tasks

> Split big initiatives into bounded tasks. Each agent should operate with a clear, minimal context; everything else is noise.

- Smaller context reduces hallucination risk and error rates.
- Bounded scopes make evaluation and iteration faster.
- Clear task contracts enable parallelism and reuse.

### 2) Tools with intent: safe by design

> Side-effectful tools are powerful, yet dangerous. Safety comes from intent-aware guardrails; vague “be careful” prompts don’t scale, and neither does a human doing constant micro-audits.

Principles

- Least privilege by default; expand access only when justified.
- For dangerous tools, require per-call intent justification:
  - Will it cause unexpected side effects?
  - Could it be misused (even “nerfed”)?
  - Does it create an “evil leverage” path?
  - Is there a safer/minimal alternative?
  - Pattern-based command matching is not enough; safety comes from disciplined specialist agents enforcing policy with judgment.
- Keep tool grants explicit and reviewable (toolsets, per-agent tool lists, and rtws access scopes).

Result: fewer bad side effects, higher plan fidelity, and more first‑try successes.

### 3) Diverse, self‑improving team from templates

> Start from a template team, then curate and evolve both individual and shared memory as versioned artifacts.

- Bootstrap from a domain-specific scaffold (team + workflows).
- Keep individual and shared memory in `.minds/**` (personas, know-how, pitfalls, playbooks).
- Evolve mindsets and governance as the product evolves.
- Keep it transparent to humans: plain Markdown, version-tracked.

## Documentation

- **[Terminology](docs/dominds-terminology.md)** — Canonical vocabulary across prompts and implementation docs (Taskdoc, Teammate Tellask, etc.)
- **[Memory System](docs/memory-system.md)** — The hierarchical memory system
- **[CLI Usage Guide](docs/cli-usage.md)** — Commands, options, and usage patterns
- **[Q4H](docs/q4h.md)** — Questions for Human (`askHuman`) mechanism and WebUI support
- **[MCP Support](docs/mcp-support.md)** — MCP tool integration
- **[Encapsulated Taskdocs](docs/encapsulated-taskdoc.md)** — `*.tsk/` Taskdoc packages and parsing
- **[FBR](docs/fbr.md)** — Fresh Boots Reasoning (`freshBootsReasoning`) design and enhancements
- **[Context Health](docs/context-health.md)** — Measuring/maintaining context quality
- **[Diligence Push](docs/diligence-push.md)** — Auto-continue (diligence) mechanism
- **[Idle Reminder Wake](docs/idle-reminder-wake.md)** — Runtime wakeups from owner-managed reminder events
- **[Showing-by-Doing](docs/showing-by-doing.md)** — A dialog-creation prelude that makes Tellask feel real
- **[Design](docs/design.md)** — Architecture and key abstractions
- **[Roadmap](docs/roadmap.md)** — Major-version plan and evolution
- **[OEC Philosophy](docs/OEC-philosophy.md)** — Philosophy and safety stance

- **[Team Mgmt Toolset](docs/team_mgmt-toolset.md)** — Managing team members via tools
- **[Text Editing Tools (ws_mod)](docs/txt-editing-tools.md)** — `ws_mod` toolset design doc (as implemented)
- **[i18n](docs/i18n.md)** — Language and localization rules
- **[Dialog System](docs/dialog-system.md)** — Dialog runtime model and streaming
- **[Dialog Persistence](docs/dialog-persistence.md)** — On-disk layout and lifecycle
- **[Interruption & Resumption](docs/interruption-resumption.md)** — Stop/resume semantics
- **[Auth](docs/auth.md)** — Authentication and access model
- **[Mottos](docs/mottos.md)** — Short guiding statements

### Getting Help

- Open an issue on [GitHub](https://github.com/longrun-ai/dominds/issues) for bugs or feature requests

---

**License:** [LGPL](./LICENSE) | **Repository:** [github.com/longrun-ai/dominds](https://github.com/longrun-ai/dominds)
