nomadcode/README.md

# NomadCode

NomadCode is a monorepo for AI-assisted development workflows. It brings together a Go orchestration service, a React/Vite operator console, a Flutter client, shared contract space, and root-level agent-operation rules.

The repository is currently an early product scaffold. The core service owns task orchestration and persistence, the web and mobile apps provide initial operator surfaces, and `agent-ops/` keeps the rules and roadmap that AI agents need before changing the workspace.

NomadCode is the development-workflow shell that consumes IOP. It structures user and provider requests into development tasks, tracks project/session/workspace state, and shows execution results to users. It does not own the model runtime, model routing, RAG, MCP policy, or output-validation engine; those responsibilities belong to IOP.

## Current Status

- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, an IOP OpenAI-compatible Responses client path, future A2A agent-delegation scaffolding, and Plane/Mattermost adapter stubs.
- `apps/web` is a React/Vite scaffold for Agent, Projects, Settings, and browser-based project workspace views. Some state and integration status areas are still mocked or stubbed.
- `apps/mobile` is a Flutter app scaffold for mobile and desktop client surfaces, Firebase Messaging, local notifications, and HTTP client dependencies.
- `packages/contracts` is a placeholder for future shared OpenAPI, protobuf, generated client, fixture, and compatibility assets.
- Active planning lives under `agent-ops/roadmap/`; this README links to that context instead of duplicating milestone state.

## Product Boundary

NomadCode owns the product and workflow layer:

- agent chat, project workspace management, task queue state, and execution status.
- Plane/Jira-style work item intake, provider projection, comments, and status updates.
- user-facing file change, diff, branch, commit, and PR flows.
- desktop and mobile project management surfaces, including project-level desktop windows and mobile top-tab workflows.
- task metadata prepared for IOP calls.

IOP owns the execution and optimization layer:

- OpenAI-compatible model calls, with Responses API support as the current NomadCode integration target.
- local/cloud model routing, model profiles, runtime selection, usage logs, and quality signals.
- CLI agent/runtime adapters such as OpenCode, Aider, Claude Code, Gemini CLI, and Codex CLI.
- RAG, context compression, MCP/tool policy, output validation, retry/fallback, and token/speed/quality optimization.

NomadCode should call IOP through its supported external surfaces. The current NomadCode path is IOP's OpenAI-compatible Responses API. A2A is reserved for later external agent delegation work, and IOP native protocol is not a NomadCode default external call path.

## Quick Start

Install only the runtimes needed for the part of the workspace you are using.

```bash
# Show service/app dev entrypoints.
bin/dev

# Run workspace checks for installed toolchains.
bin/test
bin/lint
bin/build
```

Run the core service locally. The scripts provide local defaults, but they still expect reachable PostgreSQL and Redis services; see `services/core/README.md` for the current `code-server` database setup notes.

```bash
cd services/core
./bin/migrate-up
./bin/run
```

Run the web console:

```bash
cd apps/web
npm install
npm run dev
```

Run the Flutter app:

```sh
cd apps/mobile
flutter pub get
flutter run
```

## Major Commands

| Purpose | Command | Notes |
|------|------|------|
| Show local dev entrypoints | `bin/dev` | Prints core, web, and mobile commands. |
| Test workspace | `bin/test` | Runs `go test ./...`, web `npm run check` or tests if present, and `flutter test`; skips missing toolchains. |
| Lint workspace | `bin/lint` | Runs `go vet ./...`, web `npm run lint --if-present`, and `flutter analyze --no-fatal-infos`; skips missing toolchains. |
| Build workspace | `bin/build` | Runs core `go build ./...`, web `npm run build`, and `flutter build web`; skips missing toolchains. |
| Run core | `cd services/core && ./bin/run` | Uses local defaults from the core script unless environment variables override them. |
| Migrate core DB | `cd services/core && ./bin/migrate-up` | Uses goose against the configured PostgreSQL database. |
| Test core | `cd services/core && ./bin/test` | Thin wrapper around `go test ./...`. |
| Build core binary | `cd services/core && ./bin/build` | Outputs to `.build/nomadcode-core` unless `OUTPUT` is set. |
| Run web dev server | `cd apps/web && npm run dev` | Vite development server. |
| Check web types | `cd apps/web && npm run check` | TypeScript `--noEmit`. |
| Verify web | `cd apps/web && npm run verify` | Runs type check and production build. |
| Run mobile tests | `cd apps/mobile && flutter test` | Flutter test suite. |

## Structure

| Path | Role |
|------|------|
| `services/core/` | Go backend for orchestration, persistence, scheduling, HTTP APIs, and external service adapters. |
| `apps/web/` | React/Vite operator console and browser-based agent/project workspace UI. |
| `apps/mobile/` | Flutter mobile/desktop client, project management surface, and notification integration surface. |
| `packages/contracts/` | Future shared API/schema contracts and generated client boundary. |
| `docs/` | Architecture and operations notes. |
| `bin/` | Root test, lint, build, and dev helper commands. |
| `agent-ops/` | Agent rules, domain routing, roadmap, and repeatable task skills. |

## Work Context

AI agents should start with the root instructions and project rules before changing files:

- `AGENTS.md`
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/private/rules.md` when present

For workspace-level files such as this README, also check:

- `agent-ops/rules/project/domain/workspace-ops/rules.md`
- `agent-ops/skills/common/create-readme/SKILL.md`
- `agent-ops/roadmap/current.md`

Keep detailed roadmap state in `agent-ops/roadmap/` and detailed domain rules in `agent-ops/rules/project/domain/`. Do not read `agent-task/archive/**` unless the user explicitly asks for it.

IOP boundary work should be checked against the sibling IOP repository when it is available in the same workspace. NomadCode roadmap documents should remain the source of truth for NomadCode product/workflow scope; IOP roadmap documents should remain the source of truth for execution/runtime scope.

## Development Flow

- Prefer the root `bin/test`, `bin/lint`, `bin/build`, and `bin/dev` entrypoints for whole-workspace work.
- Keep changes scoped to the owning domain rules. Cross-boundary changes should close the contract, service, and client behavior in the same branch when those boundaries move together.
- For core database changes, update `services/core/migrations/` and `services/core/queries/`, then regenerate sqlc output instead of hand-editing generated files under `services/core/internal/db/`.
- Keep `agent-ops/rules/common/**` and `agent-ops/skills/common/**` as framework-synced areas; put project-specific rules under `agent-ops/rules/project/**`.

## Environment Variables

| Runtime | Name | Required | Notes |
|------|------|------|------|
| Core | `DATABASE_URL` | No, with scripts | Core scripts provide local defaults; set it when running the binary directly or using a different PostgreSQL database. |
| Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | No, with scripts | Core scripts provide local defaults for worker/queue state; set them when running outside those scripts. |
| Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | No | `AUTH_PASSWORD` enables HTTP Basic Auth for `/readyz` and `/api/*`. |
| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | No | Configure the IOP Edge OpenAI-compatible Responses endpoint used by worker execution. Legacy direct model endpoint compatibility may exist in local scripts, but the target runtime path is IOP. |
| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the future A2A-compatible agent delegation path. This is not the current default execution path. |
| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | No | Reserved for Mattermost adapter integration. |
| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | No | Configure Plane work item lookup, comment, and state update integration. |
| Web | `VITE_NOMADCODE_API_BASE_URL` | No | The web client falls back to `http://localhost:8080`; `apps/web/.env.example` documents the same local value. |

## Reference Documents

- `docs/monorepo.md`
- `services/core/README.md`
- `apps/web/README.md`
- `apps/mobile/README.md`
- `packages/contracts/README.md`
- `agent-ops/roadmap/current.md`