From 60e3f55321cde1740ee8c65c495714fa96f8c013 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 22 Jul 2026 18:06:26 +0900 Subject: [PATCH] update workspace docs and remove redundant AGENTS.md --- .workspace-ops/docs/environments.md | 5 +++-- .workspace-ops/docs/ports.md | 2 ++ .workspace-ops/docs/remote-test-environments.md | 6 ++++-- AGENTS.md | 10 ---------- 4 files changed, 9 insertions(+), 14 deletions(-) delete mode 100644 AGENTS.md diff --git a/.workspace-ops/docs/environments.md b/.workspace-ops/docs/environments.md index 7af515b..bcd2499 100644 --- a/.workspace-ops/docs/environments.md +++ b/.workspace-ops/docs/environments.md @@ -1,7 +1,7 @@ # Workspace Environments 이 문서는 하위 프로젝트의 local/test/runtime 환경을 workspace 관점에서 요약한다. -상세 구현과 최종 source of truth는 각 프로젝트의 `agent-test/local/`, compose/env example, roadmap milestone에 둔다. +상세 구현과 최종 source of truth는 각 프로젝트의 `agent-test//`, compose/env example, roadmap milestone에 둔다. ## 공통 기준 @@ -19,6 +19,7 @@ | `nexo` | Mattermost core, webapp, push-proxy, Flutter test host, upstream dev compose | `ssh toki@toki-labs.com`, repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | core `18065`, push-proxy `18066`은 compatibility baseline. upstream dev compose 포트는 nexo-owned runtime 포트와 분리한다. | | `nomadcode` | Core local default `8080`, Docker compose DB/Redis, Flutter client, code-server preview | Android runner `$HOME/agent-work/nomadcode`, sibling `../nexo/packages/messaging_flutter`, `../proto-socket/dart` | frontend 후보 `13010`, backend 후보 `18010`, DB/cache `15410/16310`. Plane, Mattermost, Jira, IOP Edge endpoint는 secret 없이 책임 경계만 기록한다. | | `gito` | Core local default `8080`, Go control plane/worker/shell, Flutter client, optional Postgres/Redis/proto-socket runner smoke. 기본 local 테스트 evidence는 standard remote runner 기준 | `ssh toki@toki-labs.com`, `$HOME/agent-work/gito` | frontend `13060`, backend/Core HTTP `18060`, optional wire/agent transport `19060`, DB/cache `15460/16360`. Core 내부 listen `8080`은 유지하되 shared runner 검증은 gito-owned host slot을 사용한다. | +| `rara` | local config는 Control Plane `18080`, RAG API `18081`, Go Worker `18082`, Python Executor `19090`, PostgreSQL `5432` compatibility 값 사용 | 기본 검증은 `ssh toki@toki-labs.com`, 목표 checkout `/Users/toki/agent-work/rara-dev`; 2026-07-18 기준 checkout provisioning 필요 | remote dev는 Control Plane `18070`, RAG API `18071`, Go Worker `18072`, Python Executor `19070`, PostgreSQL `15470`, compose subnet 후보 `10.89.7.0/24` 사용. local compatibility 포트는 shared runner에 publish하지 않는다. | | `oto` | 기본 local 테스트 evidence는 remote runner 기준. OTO Core product fallback `127.0.0.1:8080`, runner typed-command tests, Flutter client는 compatibility 경로로 유지 | `ssh toki@toki-labs.com`, `/Users/toki/agent-work/oto` | frontend `13020`, backend/Core HTTP `18020`. `make core-run`은 `OTO_CORE_ADDR=0.0.0.0:18020`, `make client-run-web`은 preview `13020`을 사용한다. `OTO_RUNNER_RELEASE_BASE_URL`은 HTTPS release URL 기준을 유지하되 private host 원문은 기록하지 않는다. | | `appsok` | 기본 local 테스트 evidence는 standard remote Mac runner 기준. 현재 checkout의 `git diff --check`와 문법 수준 확인은 preflight로만 사용 | `ssh toki@toki-labs.com`, `$HOME/docker/services/code-server/data/volume/workspace/appsok` | Flutter/macOS build는 public port 없음. Flutter web preview가 필요하면 frontend `13050`을 사용한다. Jenkins/ADB/Xcode/Keychain credential 원문은 tracked 문서에 쓰지 않는다. | | `proto-socket` | same-language/cross-language test matrix, examples, per-language runners | Dart web/Chrome fallback: `ssh toki@toki-labs.com`, `~/agent-work/proto-socket-dart-web` | runtime 포트 없음. fixed crosstest local port `29090-29899`는 workspace 표준 예외. 예제 `9090`은 제품 host publish 포트로 보지 않는다. | @@ -30,7 +31,7 @@ - compose host publish 변경인지, container 내부 listen 변경인지 먼저 구분한다. - remote runner, code-server proxy, Android/Detox/Flutter Web smoke가 같은 포트를 참조하는지 확인한다. -- README, `.env.example`, `agent-test/local/*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다. +- README, `.env.example`, `agent-test//*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다. - DB/Redis host publish 변경은 로컬 도구와 외부 접속 필요 여부를 확인한 뒤 진행한다. - field runtime에서 이미 쓰는 `18080`, `18081`, `19080`, `19090`, `18065`, `18066`은 먼저 compatibility baseline으로 취급한다. - 프로젝트별 원격 테스트 환경과 포트 충돌 관리는 `.workspace-ops/docs/remote-test-environments.md`를 함께 확인한다. diff --git a/.workspace-ops/docs/ports.md b/.workspace-ops/docs/ports.md index 823868e..4e4174e 100644 --- a/.workspace-ops/docs/ports.md +++ b/.workspace-ops/docs/ports.md @@ -35,6 +35,7 @@ | `nexo` | `13040` | `18065`, `18066` 유지 | - | - | - | compose-internal 우선 | 변경 필요 시 `18040` 계열 후보. `18065/18066`은 compatibility baseline | | `appsok` | `13050` | - | - | - | - | - | remote Mac runner 중심. 일반 Flutter/macOS build는 public port 없음 | | `gito` | `13060` (`dev:13061`) | `18060` (`dev:18061`) | - | `19060` optional (`dev:19061`) | - | `15460`, `16360` (`dev:15461/16361`) | remote runner 기준. Core 내부/default `8080`은 유지하고 host publish/direct smoke만 gito-owned slot 사용 | +| `rara` | `13070` reserved | `dev:18070/18071/18072` | - | Python Executor gRPC `dev:19070` | `19170-19172` reserved | PostgreSQL `dev:15470`, cache `16370` reserved | 기본 테스트는 remote `dev`. 제품 local 기본 `18080-18082`, `19090`, `5432`는 compatibility 값이며 shared remote runner에 publish하지 않음 | | `proto-socket` | - | - | - | test runner `29090-29899` | - | - | 운영 포트가 아니라 crosstest local fixed port 예외 | ## 제외 또는 host 의존 @@ -57,3 +58,4 @@ | `proto-socket` | `agent-roadmap/milestones/workspace-port-env-standardization.md` | | `appsok` | 현재 workspace-level inventory로 관리. 프로젝트 milestone 확인 시 추가 | | `gito` | 현재 workspace-level inventory와 `agent-test/local/` 기준으로 관리. 프로젝트 milestone 필요 시 추가 | +| `rara` | 현재 workspace-level inventory와 `agent-test/dev/` 기준으로 관리. 프로젝트 milestone 필요 시 추가 | diff --git a/.workspace-ops/docs/remote-test-environments.md b/.workspace-ops/docs/remote-test-environments.md index 8fb648b..0a2f4bb 100644 --- a/.workspace-ops/docs/remote-test-environments.md +++ b/.workspace-ops/docs/remote-test-environments.md @@ -2,7 +2,7 @@ 이 문서는 workspace 하위 프로젝트의 원격 테스트 환경, 원격 checkout, 공개/host publish 포트, 충돌 관리 기준을 한곳에서 보기 위한 운영 인벤토리다. -상세 실행 명령과 최종 테스트 기준은 각 프로젝트의 `agent-test/local/`, compose/env example, project rule을 따른다. 이 문서는 raw secret, token, password, private key, 계정 password, private endpoint 원문을 기록하지 않는다. +상세 실행 명령과 최종 테스트 기준은 각 프로젝트의 `agent-test//`, compose/env example, project rule을 따른다. 이 문서는 raw secret, token, password, private key, 계정 password, private endpoint 원문을 기록하지 않는다. ## 관리 기준 @@ -22,6 +22,7 @@ | `nexo` | `ssh toki@toki-labs.com` | repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | Mattermost core/push-proxy runtime, Flutter/Android, Detox, FCM/device evidence | core `18065`, push-proxy `18066` | Android Detox Metro는 `8081` 점유 시 `8088`; Flutter Web preview는 ignored `web-smoke.env` 값 기준 | Mattermost/FCM/test account 값은 `agent-test/local/secrets.md` 같은 ignored profile에서만 확인 | | `nomadcode` | `ssh toki@toki-labs.com` standard remote runner | local `$HOME/agent-work/nomadcode`; dev `$HOME/agent-work/nomadcode-dev` | Core, Flutter client, Android SDK runner, Mattermost/FCM 시나리오, Gito branch webhook consumer | local preview `13010`, Core host publish `18010:8080`, DB/cache 후보 `15410/16310`; dev preview `13011`, Core host publish `18011:8080`, DB/cache 후보 `15411/16311` | sibling `../nexo/packages/messaging_flutter`, `../proto-socket/dart` 경로 전제. IOP dev model endpoint `http://toki-labs.com:18083/v1`은 dependency baseline이며 nomadcode-owned port가 아님 | Mattermost/FCM/signature/Gito webhook secret 등 private input은 ignored local profile 기준 | | `gito` | `ssh toki@toki-labs.com` standard remote runner | local `$HOME/docker/services/code-server/data/volume/workspace/gito`; dev `$HOME/agent-work/gito-dev` | Core Go, Flutter client, provider webhook/proto-socket smoke, agent-shell runner baseline, NomadCode delivery smoke | local preview `13060`, Core host publish/direct HTTP `18060`, optional proto-socket/agent transport `19060`, DB/cache 후보 `15460/16360`; dev preview `13061`, Core HTTP `18061`, optional transport `19061`, DB/cache 후보 `15461/16361` | Core internal/default `8080`은 compatibility 경로. NomadCode webhook target은 local `http://127.0.0.1:18010/api/integrations/gito/webhook`, dev `http://127.0.0.1:18011/api/integrations/gito/webhook` | Provider webhook secret, credential_ref, runner credential, Gito delivery signing secret은 ignored local profile 기준 | +| `rara` | `ssh toki@toki-labs.com` standard remote Mac runner | 목표 checkout `/Users/toki/agent-work/rara-dev`; 2026-07-18 기준 provisioning 필요 | Go/Python source test와 build, PostgreSQL-backed Control Plane/RAG/Worker readiness, Python executor gRPC smoke | Control Plane `18070`, RAG API `18071`, Go Worker `18072`, Python Executor gRPC `19070`, PostgreSQL host publish `15470`, compose subnet 후보 `10.89.7.0/24`; `13070`, `16370`, `19170-19172`는 RARA dev reserve | 제품 local compatibility `18080-18082`, Python 기본 `19090`, PostgreSQL 기본 `5432`는 IOP shared baseline과 충돌하므로 shared runner에 그대로 publish하지 않음 | Database/integration/model credential은 원격에서 주입하고 tracked 문서와 shell 출력에 기록하지 않음 | | `proto-socket` | 기본은 local matrix; Dart.web Chrome 없을 때 remote fallback | `toki@toki-labs.com`, `~/agent-work/proto-socket-dart-web` | Dart.web/WSS Chrome fallback, SPKI wrapper, cross-language matrix 보조 | crosstest runner fixed range `29090-29899` | runtime service port 없음; 예제 `9090`은 제품/테스트 슬롯 아님 | runner 입력 secret 없음. SSH 인증은 local 계정/agent 환경 책임 | | `oto` | `ssh toki@toki-labs.com` standard remote runner | `/Users/toki/agent-work/oto` | OTO runner, Core HTTP, Flutter client/web preview, bootstrap/release validation | frontend/web preview `13020`, Core HTTP host publish `18020` | product fallback `127.0.0.1:8080`은 compatibility 경로. OTO-owned wire/agent transport port는 아직 확정하지 않음 | `OTO_RUNNER_RELEASE_BASE_URL`, enrollment token, private release host 원문은 tracked 문서에 기록하지 않음 | | `agent-shell` | 없음 | 없음 | Dart/Flutter package test | 없음 | package 자체 포트 없음. host 앱이 환경 소유 | 없음 | @@ -40,6 +41,7 @@ | `nexo` `18065/18066` | workspace backend 후보 `18040` 계열과 다름 | Mattermost compatibility baseline으로 유지한다. 신규 nexo-owned backend가 필요할 때만 `18040` 계열을 검토한다. | | `nomadcode` local/dev split | local profile과 dev profile을 같은 원격 host에서 분리해야 함 | local은 `13010/18010/15410/16310`, dev는 `13011/18011/15411/16311`을 사용한다. Gito dev subscription target은 `http://127.0.0.1:18011/api/integrations/gito/webhook`이다. | | `gito` local/dev split | Gito provider intake와 NomadCode consumer target을 같은 원격 host에서 분리해야 함 | local은 `13060/18060/19060/15460/16360`, dev는 `13061/18061/19061/15461/16361`을 사용한다. dev Gito는 NomadCode dev `18011`로 delivery한다. | +| `rara` local compatibility vs IOP shared field | RARA config 기본 `18080-18082`, Python 기본 `19090`이 IOP artifact/model/wire baseline과 겹침 | RARA 기본 원격 `dev`에서는 `18070-18072`, `19070`, PostgreSQL `15470`을 override하고 local 기본값을 shared runner에 publish하지 않는다. | | `proto-socket` `29090-29899` | 일반 runtime port가 아니라 test runner fixed range | workspace 예외 대역으로 유지하고 제품 host publish 표준화 대상에서 제외한다. | ## 변경 전 체크리스트 @@ -47,5 +49,5 @@ - 원격 checkout이 현재 작업과 동기화되어 있는지 확인한다. - compose host publish 변경인지, container 내부 listen 변경인지 구분한다. - remote runner, code-server proxy, Android/Detox/Flutter Web smoke가 같은 포트를 참조하는지 확인한다. -- README, `.env.example`, `agent-test/local/*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다. +- README, `.env.example`, `agent-test//*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다. - field/runtime 포트는 문서 정리만으로 바꾸지 않는다. 변경 전 smoke, client config, remote runner path를 같이 확인한다. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 95ce1b0..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,10 +0,0 @@ -# 워크스페이스 진입 파일 - -이 파일은 호환을 위한 얇은 진입 파일이다. -실제 workspace 운영 규칙은 `.workspace-ops/rules/common/rules.md`를 먼저 읽고 따른다. - -- workspace 운영 도구, 룰, 스킬, 설정, sync 자료는 `.workspace-ops/`에서만 관리한다. -- 분석 대상 탐색은 `.workspace-ops/shared/target-discovery.md`와 `.workspace-ops/config/target-excludes.txt`를 따른다. -- 주기 분석, 주간 작업 요약, 주간 분석, 구현 전 점검은 `.workspace-ops/skills/` 아래 해당 `SKILL.md`를 사용한다. -- SOPS 시크릿 관리와 Jenkins/OTO 빌드 관리는 `.workspace-ops/skills/router.md`에서 해당 도메인으로 라우팅한다. -- 루트 진입 파일 목록은 `.workspace-ops/config/entry-files.txt`에 둔다.