a6371e156a
Enables parallel agents to communicate through a CLI-based conversation mechanism coordinated via tRPC. Agents can ask questions to peers and receive answers, with target resolution by agent ID, task ID, or phase ID.
159 lines
5.6 KiB
Markdown
159 lines
5.6 KiB
Markdown
# CLI & Configuration
|
|
|
|
`src/cli/` — CLI commands, `src/config/` — workspace configuration, `src/bin/` — entry point.
|
|
|
|
## Entry Point
|
|
|
|
`src/bin/cw.ts` — hashbang entry that imports and runs the CLI.
|
|
|
|
## CLI Framework
|
|
|
|
Uses **Commander.js** for command parsing.
|
|
|
|
## Global Flags
|
|
|
|
- `-s, --server` — Start coordination server in foreground
|
|
- `-p, --port <number>` — Server port (default: 3847, env: `CW_PORT`)
|
|
- `-d, --debug` — Enable debug mode (archive agent workdirs before cleanup)
|
|
|
|
## Commands
|
|
|
|
### System
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `cw init` | Create `.cwrc` workspace file in current directory |
|
|
| `cw start` | Start coordination server (see Server Wiring below) |
|
|
| `cw stop` | Stop running server (reads PID file, sends signal) |
|
|
| `cw status` | Query server health endpoint |
|
|
| `cw id [-n count]` | Generate nanoid(s) offline |
|
|
|
|
### Agent Management (`cw agent`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `spawn <prompt> --task <id> [--name] [--provider] [--initiative] [--cwd]` | Spawn agent |
|
|
| `stop <name>` | Stop running agent |
|
|
| `delete <name>` | Delete agent, clean workdir/branches/logs |
|
|
| `list` | List all agents with status |
|
|
| `get <name>` | Agent details (ID, task, session, worktree, status) |
|
|
| `resume <name> <answers>` | Resume with JSON answers or single string |
|
|
| `result <name>` | Get execution result |
|
|
|
|
### Task Management (`cw task`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `list --parent\|--phase\|--initiative <id>` | List tasks with counts |
|
|
| `get <taskId>` | Task details |
|
|
| `status <taskId> <status>` | Update status |
|
|
|
|
### Dispatch (`cw dispatch`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `queue <taskId>` | Queue task for dispatch |
|
|
| `next` | Dispatch next available task |
|
|
| `status` | Show queue status |
|
|
| `complete <taskId>` | Mark task complete |
|
|
|
|
### Initiative Management (`cw initiative`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `create <name> [--project <ids...>]` | Create initiative |
|
|
| `list [-s status]` | List initiatives |
|
|
| `get <id>` | Initiative details |
|
|
| `phases <initiativeId>` | List phases |
|
|
|
|
### Architect (`cw architect`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `discuss <initiativeId> [-c context]` | Start discussion agent |
|
|
| `plan <initiativeId> [-s summary]` | Start plan agent |
|
|
| `detail <phaseId> [-t taskName] [-c context]` | Detail phase into tasks |
|
|
|
|
### Phase (`cw phase`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `add-dependency --phase <id> --depends-on <id>` | Add dependency edge |
|
|
| `dependencies <phaseId>` | List dependencies |
|
|
| `queue <phaseId>` | Queue approved phase |
|
|
| `dispatch` | Dispatch next phase |
|
|
| `queue-status` | Show phase queue |
|
|
|
|
### Merge & Coordination (`cw merge`, `cw coordinate`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `merge queue <taskId>` | Queue task for merge |
|
|
| `merge status` | Show merge queue |
|
|
| `merge next` | Show next mergeable task |
|
|
| `coordinate [-t branch]` | Process all ready merges (default: main) |
|
|
|
|
### Messages (`cw message`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `list [--agent <id>] [--status <s>]` | List messages |
|
|
| `read <messageId>` | Read full message |
|
|
| `respond <messageId> <response>` | Respond to message |
|
|
|
|
### Projects (`cw project`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `register --name <n> --url <u>` | Register git repo |
|
|
| `list` | List projects |
|
|
| `delete <id>` | Delete project |
|
|
|
|
### Preview Deployments (`cw preview`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `start --initiative <id> --project <id> --branch <branch> [--phase <id>]` | Start Docker preview |
|
|
| `stop <previewId>` | Stop and clean up preview |
|
|
| `list [--initiative <id>]` | List active previews |
|
|
| `status <previewId>` | Get preview status with service details |
|
|
|
|
### Inter-Agent Conversation (`cw listen`, `cw ask`, `cw answer`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `listen --agent-id <id> [--poll-interval <ms>] [--timeout <ms>]` | Poll for pending questions, print JSON, exit |
|
|
| `ask <question> --from <agentId> [--agent-id\|--phase-id\|--task-id <target>] [--poll-interval <ms>] [--timeout <ms>]` | Ask question, block until answered, print answer |
|
|
| `answer <answer> --conversation-id <id>` | Answer a pending conversation |
|
|
|
|
All three commands output JSON for programmatic agent consumption.
|
|
|
|
### Accounts (`cw account`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `add [--provider] [--email] [--token]` | Auto-discover, manually register, or register with setup token |
|
|
| `list` | Show accounts with exhaustion status |
|
|
| `remove <id>` | Remove account |
|
|
| `refresh` | Clear expired exhaustion markers |
|
|
|
|
## Server Wiring
|
|
|
|
The CLI is the composition root. It creates concrete implementations and passes them as `contextDeps`:
|
|
|
|
```
|
|
ServerContextDeps = Omit<TrpcAdapterOptions, 'eventBus' | 'serverStartedAt' | 'processCount'>
|
|
```
|
|
|
|
This includes all repositories, managers, and the credential manager. The server adds `eventBus`, `serverStartedAt`, and `processCount` at startup.
|
|
|
|
## Workspace Configuration
|
|
|
|
`src/config/` module:
|
|
|
|
### .cwrc File
|
|
JSON file at workspace root that marks a `cw` workspace:
|
|
```json
|
|
{ "version": 1 }
|
|
```
|
|
|
|
### findWorkspaceRoot()
|
|
Walks up directory tree looking for `.cwrc` file. Returns the directory containing it, or throws if not found.
|
|
|
|
### Schema
|
|
Currently `{ version: 1 }` — extend with new top-level keys as needed.
|
|
|
|
### Files
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `types.ts` | CwrcConfig type definition |
|
|
| `cwrc.ts` | findWorkspaceRoot(), readCwrc(), writeCwrc() |
|
|
| `index.ts` | Public API exports |
|