# AGENTS — Agent Remote Control

## Overview

**Agent Remote Control** is a NestJS application for remote control and orchestration of AI software development agents, running over the **Agent Client Protocol (ACP)** and controlled through pluggable channel interfaces (a web interface and a **Discord Bot**). The work of each conversation is a board of features and tasks that the agents read and write themselves, routed by the CEO through their statuses.

The project follows **Clean Architecture with Ports & Adapters**, decoupling the business core from external technologies (Discord, the ACP SDK, the file system and processes). Behavior and business rules are orchestrated directly by independent, cohesive **Use Cases**.

Everything in the repository is written in **English**: source code, identifiers, tests, comments, documentation (`AGENTS.md`, README, skills) and commit messages.

## Repository Structure

```text
agent-remote-control/
├── .agents/                        # AI agent governance
│   └── skills/                     # Catalog of on-demand skills (SKILL.md)
├── data/                           # Runtime data persisted in DATA_DIR (outside Git): sessions, per-conversation agent settings, the board of each conversation (artifacts/), the user's own agent skills (skills/) and global preferences (user language)
├── packages/
│   ├── protocol/                   # @agent-remote-control/protocol: message contract (zod schemas) shared by server and web
│   ├── web/                        # @agent-remote-control/web: React + Rsbuild web interface (connection, conversations, components); its `p2p` build is the hosted web app of remote access
│   ├── p2p-server/                 # @agent-remote-control/p2p-server: NestJS signaling server of remote access; serves the `p2p` build of the web app
│   └── server/                     # @agent-remote-control/server: the NestJS application
│       ├── src/                    # NestJS application source code
│       │   ├── modules/                    # Vertical modules segregated by domain
│       │   │   ├── access-token/           # The access token of the web channel, local and remote alike
│       │   │   ├── agent/                  # ACP integration: IAgentPort port, factory, adapters, demux and the CLI login (IAgentAuthPort)
│       │   │   ├── agent-definitions/      # Agent catalog (CEO, GIT_OPS, PRODUCT_OWNER, TECH_LEAD, DEVELOPER, CODE_REVIEWER, QA), their access to the board, prompts, skills and registry
│       │   │   ├── artifacts/              # Board of each conversation: features and tasks, statuses, dependencies, holders and history (IArtifactsPort)
│       │   │   ├── discord/                # Discord Bot: handlers, formatters and progress utils
│       │   │   ├── logging/                # Application logger bound to Nest's LoggerService; conversation-tagged log files
│       │   │   ├── orchestrator/           # Turns, per-conversation queue, delegation and cancellation
│       │   │   ├── paths/                  # DATA_DIR and WORKSPACE_DIR resolution shared by the modules that persist data or use the workspace
│       │   │   ├── remote/                 # Remote access: the host's identity, its signaling socket and the WebRTC transport of the web channel
│       │   │   └── workspace/              # Workspace directory and manifest
│       │   │
│       │   │   Internal folders of a module (each module uses only the ones it needs):
│       │   │       ├── adapters/           # Secondary/technology adapters (*.adapter.ts)
│       │   │       ├── constants/          # Domain constants
│       │   │       ├── demux/              # Decomposition of streams into typed events
│       │   │       ├── formatters/         # Output formatting for the channel
│       │   │       ├── handlers/           # Primary/driving adapters (Discord events/commands)
│       │   │       ├── models/             # Domain types and models (*.model.ts, *.type.ts)
│       │   │       ├── ports/              # Interfaces and injection Symbols (*.port.ts)
│       │   │       ├── prompts/            # Agent system prompts (*.prompt.ts)
│       │   │       ├── services/           # Concrete supporting services (*.service.ts)
│       │   │       ├── testing/            # Stubs, fakes and fixtures shared by tests
│       │   │       ├── use-cases/          # Business rules and orchestration (*.use-case.ts)
│       │   │       ├── utils/              # Pure functions shared by two or more classes (*.util.ts)
│       │   │       └── <name>.module.ts    # Module configuration and NestJS DI wiring
│       │   ├── app.controller.ts           # Root diagnostics/healthcheck controller
│       │   ├── app.module.ts               # Application root module
│       │   ├── app.service.ts              # Application root service
│       │   └── main.ts                     # NestJS application bootstrap
│       ├── test/                   # e2e tests and global test utilities
│       ├── nest-cli.json           # NestJS CLI configuration
│       ├── tsconfig.json           # Server TypeScript configuration (extends tsconfig.base.json)
│       ├── tsconfig.build.json     # Build TypeScript configuration
│       ├── rstest.config.ts        # Rstest project "server" (unit tests)
│       ├── rstest.config.e2e.ts    # Rstest configuration for e2e tests
│       └── package.json            # Server dependencies and scripts
├── .github/workflows/              # CI (type check, lint and tests) on pull requests; commit author check (no AI agent as author, committer or co-author; the owner's own pull requests have only the owner's identities as author and committer); publishes the multi-platform Docker image to Docker Hub and deploys the p2p-server and coturn on CapRover on every GitHub release
├── captain-definition-*            # CapRover definitions of the p2p-server and of the coturn TURN relay
├── deploy/coturn/                  # Image and configuration of the coturn TURN relay
├── docs/                           # Roadmap, delivery plans and the remote access guide
├── Dockerfile                      # Production image (Debian-based) with the app and Codex
├── Dockerfile.p2p                  # Image of the p2p-server with the hosted web app
├── docker-entrypoint.sh            # Provides the CLIs listed in ARC_AGENTS at container startup
├── .dockerignore                   # Files excluded from the Docker build context
├── rstest.config.ts                # Rstest root configuration: test projects and coverage
├── tsconfig.base.json              # Compiler options shared by every package
├── eslint.config.js                # ESLint flat configuration for the whole repository
└── package.json                    # pnpm workspaces root: shared devDependencies and scripts
```

## `.agents/` Structure

- `.agents/skills/`: Skills loaded on demand by the agent. Each folder contains a prescriptive `SKILL.md`.

Before creating or changing any code, consult the catalog in `.agents/skills/`, inspecting the `description` in each frontmatter to load the mandatory rules for the topic.

## Cross-Cutting Conventions

- **Commit messages**: Conventional Commits (Angular) in **English**, imperative mood in the present tense (e.g. "add", "fix"), subject line of up to 50 characters with no trailing period. When there is detailed context, separate the body with a blank line.
- **No agent attribution**: Nothing written for the repository says that an AI agent produced or helped with it. Commits carry no `Co-Authored-By` trailer naming an agent and no session link, and pull request descriptions, issue and review comments, code comments and documentation carry no "Generated with" line or similar signature.
- **Language**: Everything in **English** — identifiers, file names, classes, interfaces, methods, variables, test descriptions (`describe`, `it`), comments, documentation, skills and commit messages.
- **Testing with Rstest**:
  - Unit tests live side by side with the files under test, following the `*.spec.ts` pattern.
  - Target of **100% coverage** of executable production code lines.
  - `rs.mock` is restricted **exclusively to external I/O boundaries** (third-party SDKs such as Discord.js and the ACP SDK, and native Node modules such as `node:fs` and `node:child_process`). Internal code in `packages/server/src/` is **never** mocked with `rs.mock`; use stubs/fakes that implement the ports (`implements IMyPort`).
- **Ban on barrel exports (`index.ts`)**:
  - Do not use `index.ts` files that re-export symbols from folders or modules. Always import directly from the symbol's source file to avoid unnecessary coupling and circular dependencies.

## Writing Comments and Documentation

All text kept in the repository describes the **current state**, written for whoever reads the file today without consulting the repository history or earlier conversations:

- **Describe what is, never the transition**: Write from the consolidated result. Phrases such as "no longer", "became", "now is", "used to be", "instead of" and "without needing to" are forbidden, except when recording business decisions in commit messages or migration specs.
- **Negate only to prevent a plausible mistake**: A negative constraint ("do not use X") is only justified when a competent reader would try X and the sentence explains why it would fail.
- **Three-question test before commenting**:
  1. Does it say something the code does not express?
  2. Would a competent reader try the alternative it rules out?
  3. Will it still be true after the next refactor?
- **Mandatory pruning pass**: Before finishing any task, inspect the documentation and comment additions in the diff (`git diff`) and cut whatever is redundant or obvious.

## Essential Commands

All commands run from the repository root and apply to every package in `packages/`.

- Install dependencies: `pnpm install`
- Development mode with watch, server and web together: `pnpm dev` (`pnpm dev:server` or `pnpm dev:web` for one of them)
- Remote access locally: `pnpm dev:p2p-server` and `pnpm dev:web:p2p` (the web app in `p2p` mode)
- Preview the built web app: `pnpm preview:web`
- Every package script runs from its own folder (`packages/server`, `packages/web`); the root scripts delegate to them. The server resolves `.env`, `data/` and `workspaces/` from the repository root through `repository-root.util.ts`, whatever the working directory.
- Build: `pnpm build`
- TypeScript static type checking: `pnpm ts`
- Two TypeScript compilers are installed: `typescript-native` (TypeScript 7) type checks (`ts` and the check in the web `build`), and `typescript` (TypeScript 6) serves the tools that use the compiler API (typescript-eslint, the Nest CLI) and emits `protocol`. Both ship a `tsc` binary, so package scripts call each one by its path in `node_modules`.
- Linter: `pnpm lint`
- Code formatting via ESLint: `pnpm format` (or `pnpm lint:fix`)
- Run unit tests: `pnpm test` (`TEST_LOGS=true pnpm test` also prints the server's Nest logs)
- Test coverage: `pnpm test:cov`
- End-to-end (e2e) tests: `pnpm test:e2e`

## Mandatory Rules for AI Agents

1. **Consult skills before acting**: Before creating or changing code, check the catalog in `.agents/skills/` and follow the governing skill.
2. **Follow the NestJS Clean Architecture pattern**:
   - Use cases orchestrate business rules (`*.use-case.ts`).
   - Ports define interfaces and injection Symbols (`*.port.ts`).
   - Adapters implement technical ports (`*.adapter.ts`).
   - Dependency injection via `@Inject(IMyPort)`.
   - NestJS modules configure providers by binding the Symbol to the concrete class (`{ provide: IMyPort, useClass: MyAdapter }`).
3. **Orchestration via Use Cases**: All business logic and flow coordination is done exclusively by Use Case classes (`*.use-case.ts`). Do not use workflow classes.
4. **No barrel exports**: Import classes, ports and types directly from their definition file, without `index.ts`.
5. **No obvious comments**: Do not repeat what the code, typing or signature already says.
6. **Stubs and fakes for internal dependencies**: Isolate internal `packages/server/src/` dependencies by injecting stubs in the constructor or overriding providers in the testing module (`createTestingModule` from `test/testing-module.ts`); `rs.mock` is reserved for external I/O boundaries.
7. **Pruning pass before finishing**: Check comments and text introduced in the diff and remove any noise before submitting.
8. **Mandatory type checking, lint and tests on every change**: Any code change in the project requires running `pnpm ts`, `pnpm lint` and `pnpm test` (plus `pnpm test:e2e` when touching entry points). Code formatting is the sole responsibility of ESLint (`pnpm format`). No delivery can be completed with TypeScript errors, lint errors or test failures.
9. **Skills in sync with the code**: Every change to a port contract, public signature, lifecycle or rule described in a skill updates the skill in the same commit. Before finishing, compare the skills of the touched module against the `git diff`.
