toki/nomadcode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update README and workflow-core milestone

Browse source
This commit is contained in:
toki 2026-05-22 09:36:47 +09:00
parent 4a80f4a4e7
commit 8148b53ca1
2 changed files with 117 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
README.md
View file

@ -1,24 +1,125 @@
# NomadCode
NomadCode is the monorepo for the mobile app, web console, core service, shared contracts, and agent-operation rules that coordinate AI-assisted development workflows.
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.
## Workspace
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.
- `apps/mobile`: Flutter client.
- `apps/web`: React/Vite web console.
- `services/core`: Go backend and orchestration service.
- `packages/contracts`: shared API contracts and generated client boundary.
- `agent-ops`: root-level rules, skills, and routing context for AI agents.
- `docs`: architecture and operations notes.
- `bin`: workspace helper commands.
## Current Status
## Common Commands
- `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.
```sh
bin/test
bin/build
bin/lint
## 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
```
Each command delegates to the projects that are present in the workspace.
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`

1
agent-ops/roadmap/milestones/workflow-core.md
View file

@ -49,3 +49,4 @@ Workflow Core
- 선행 작업: Plane Thin E2E Loop
- 후속 작업: External Integration
- 검증 기준: scheduler, persistence, adapter behavior를 크게 바꾸면 관련 테스트를 함께 갱신한다.
벼