# 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.

## Current Status

- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, model/A2A client paths, and Plane/Mattermost adapter stubs.
- `apps/web` is a React/Vite scaffold for Agent, Projects, and Settings views. Some state and integration status areas are still mocked or stubbed.
- `apps/mobile` is a Flutter app scaffold with 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.

## 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 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.

## 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 OpenAI-compatible model endpoint used by worker execution. |
| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the A2A-compatible agent call path. |
| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | No | Reserved for Mattermost adapter integration. |
| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | No | Reserved for Plane adapter 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`