diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md index 4dd0c61..92da1c8 100644 --- a/docs/implementation-roadmap.md +++ b/docs/implementation-roadmap.md @@ -30,6 +30,7 @@ As of now: - the original five `docs/tests/orch-skill/` cases also include recorded real subagent-forward runs captured on `2026-03-19`, with spawned leader and worker agents using the packaged `skills/orch/` and `skills/inbox/` bundles - a council-review skill forward-test plan directory now exists under `docs/tests/council-review-skill/`, with a shared execution contract and nine council workflow scenarios covering end-to-end flow, unanimous-only defaults, timeout/before-tally errors, explicit minority reporting, invalid report filters, strict tally semantics, malformed reviewer JSON, and target-file inputs - an execution-roadmap workflow now exists under `docs/roadmaps/active/` and `docs/roadmaps/archive/` for agent-level work traces and completion archives +- a forward-looking web product monorepo plan now exists under `docs/web-product-monorepo.md`, defining the recommended React frontend, `chi` HTTP service, `cmd/orchd` entrypoint, and shared application/query layering for future web work - a repo-local `scripts/package_skill_clis.sh` packaging flow now builds bundled skill CLI assets for `inbox`, `orch`, and `council-review` - `orch` now implements `run init/show`, `task add`, `dep add`, `ready`, `dispatch`, `reconcile`, `wait`, `blocked`, `answer`, `retry`, `reassign`, `cancel`, `cleanup`, and `status` - `orch` can create runs, gate tasks through dependencies, dispatch work through `inbox`, reconcile worker thread state back into task state, answer blocked tasks, retry or reassign work, cancel tasks or runs, clean attempt worktrees, and create per-attempt Git worktrees during strict dispatch @@ -53,6 +54,7 @@ Read these docs first: - [orch-cli.md](/home/kurihada/project/ai-workflow-skill/docs/orch-cli.md) - [worktree-execution.md](/home/kurihada/project/ai-workflow-skill/docs/worktree-execution.md) - [council-review.md](/home/kurihada/project/ai-workflow-skill/docs/council-review.md) +- [web-product-monorepo.md](/home/kurihada/project/ai-workflow-skill/docs/web-product-monorepo.md) Use this roadmap for implementation order, not for protocol design. @@ -371,7 +373,8 @@ If a new agent is taking over now, the next concrete step should be: 1. treat `Milestone 7: Council Review` as complete unless a new user request introduces a new council capability 2. keep the authored inbox test-plan set in `docs/tests/inbox/` synchronized if future `orch` work changes shared CLI behavior -3. choose the next milestone explicitly instead of reopening the completed council v1 slice +3. if the next milestone is the web product, use `docs/web-product-monorepo.md` as the starting implementation shape for the monorepo, `cmd/orchd`, and `apps/web` +4. choose the next milestone explicitly instead of reopening the completed council v1 slice The inbox implementation and its human-readable test-plan set are already in place, and `orch` now supports the main scheduler loop plus the complete council start/wait/tally/report workflow, so any next step should be a new milestone rather than unfinished council v1 work. diff --git a/docs/roadmaps/archive/web-product-monorepo-doc.md b/docs/roadmaps/archive/web-product-monorepo-doc.md new file mode 100644 index 0000000..58443d6 --- /dev/null +++ b/docs/roadmaps/archive/web-product-monorepo-doc.md @@ -0,0 +1,56 @@ +# Web Product Monorepo Doc + +## Status + +- `completed` + +## Owner + +- Codex + +## Started At + +- `2026-03-19` + +## Goal + +- Capture the agreed monorepo skeleton and web-product backend/frontend direction in a durable project document under `docs/`. +- Keep the implementation roadmap synchronized so future agents can pick up the web milestone without rediscovering the repository shape. + +## Scope + +- add a new planning document for the web-product monorepo direction +- update the implementation roadmap to reference the new document +- archive this execution roadmap when the documentation work is complete + +## Checklist + +- [x] create an active execution roadmap for this documentation workstream +- [x] add the web-product monorepo planning document under `docs/` +- [x] update the implementation roadmap to reference the new document +- [x] validate the changed docs for consistency +- [x] archive this execution roadmap with a completion summary + +## Files + +- `docs/web-product-monorepo.md` +- `docs/implementation-roadmap.md` +- `docs/roadmaps/active/web-product-monorepo-doc.md` + +## Decisions + +- keep the work scoped to documentation and roadmap sync rather than implementation +- treat the current repository as the future backend monorepo root rather than proposing an immediate backend repo split + +## Blockers + +- none + +## Next Step + +- use `docs/web-product-monorepo.md` as the planning reference when implementation starts for `cmd/orchd`, `apps/web`, and the shared application/query layers + +## Completion Summary + +- added `docs/web-product-monorepo.md` to capture the agreed monorepo skeleton, React frontend direction, `chi` backend direction, and phased migration plan +- updated `docs/implementation-roadmap.md` so future agents can discover and use the new web-product planning document as the next milestone entrypoint diff --git a/docs/web-product-monorepo.md b/docs/web-product-monorepo.md new file mode 100644 index 0000000..38358d7 --- /dev/null +++ b/docs/web-product-monorepo.md @@ -0,0 +1,427 @@ +# Web Product Monorepo Plan + +## Purpose + +This document defines the recommended repository shape and implementation direction for evolving the current local CLI-based coordination stack into a formal web product. + +The target shape is: + +- a React frontend for leaders and operators +- a Go HTTP backend built with `chi` +- continued reuse of the existing `inbox` and `orch` domain logic +- one monorepo rather than separate frontend and backend repositories + +This is an implementation-oriented planning document. +It does not replace the current protocol and workflow documents for `inbox`, `orch`, worktrees, or council review. + +## Decision Summary + +The recommended direction is: + +- keep a single monorepo +- add a standalone frontend app under `apps/web` +- add a standalone HTTP backend entrypoint under `cmd/orchd` +- keep the current Go repository as the backend source of truth +- evolve the backend by introducing shared application services and UI-oriented query layers +- avoid building the web backend by shelling out to the existing CLIs + +This gives the product a front/back runtime split without creating a second backend codebase. + +## Why Monorepo + +For the current project stage, a monorepo is the most practical choice. + +Benefits: + +- the current domain model, scheduler logic, and SQLite schema already live in this repository +- frontend and backend changes will often move together while the web product is still forming +- API contracts, event contracts, and backend changes can be versioned together +- the existing CLI tools can stay in the same repo as operator and debugging surfaces +- shared scripts, fixtures, and docs remain simple + +## Why The Backend Should Stay In This Repo + +The backend should become a first-class HTTP service, but it should not start as a brand new repo. + +Reasons: + +- the existing state machine and storage behavior already live here +- duplicating `store` and schema logic into a second backend codebase would create unnecessary drift +- wrapping the CLIs from a web server would produce an unstable and hard-to-test integration boundary +- the fastest safe path is to let both the CLI and HTTP service call the same Go services + +The backend may be split into another repo later only after the application-service boundary is stable and intentionally extracted. + +## Product Direction + +The target product is not just a local dashboard. +It should be able to evolve into a formal multi-user web application. + +That means the backend should be designed for: + +- stable HTTP APIs +- authenticated users +- eventual organization and membership concepts +- server-pushed run and thread updates +- UI-oriented read models for task boards, blocked queues, and timelines +- eventual migration away from SQLite if write concurrency or deployment shape requires it + +## Recommended Repository Layout + +The recommended monorepo shape is: + +```text +. +├─ apps/ +│ └─ web/ # React frontend application +├─ api/ +│ ├─ openapi.yaml # HTTP API contract +│ └─ events.md # SSE or websocket event contract +├─ cmd/ +│ ├─ inbox/ # existing worker-facing CLI +│ ├─ orch/ # existing leader-facing CLI +│ └─ orchd/ # new HTTP backend entrypoint +├─ internal/ +│ ├─ app/ # shared application services used by CLI and HTTP +│ ├─ httpapi/ # chi router, handlers, middleware, SSE +│ ├─ query/ # frontend-oriented read models and aggregate queries +│ ├─ store/ # existing persistence and orchestration state logic +│ ├─ db/ # existing SQLite open and migration layer +│ └─ protocol/ # shared DTO and response helpers where appropriate +├─ docs/ +├─ scripts/ +├─ package.json +├─ pnpm-workspace.yaml +├─ go.mod +└─ Makefile +``` + +## Layout Decisions + +### `apps/web` + +The frontend should live under `apps/web`. + +Recommended stack: + +- React +- Vite +- TypeScript +- TanStack Router +- TanStack Query + +The frontend should consume only HTTP APIs and event streams from the backend. +It should never read SQLite directly and should not depend on CLI output parsing. + +### `cmd/orchd` + +The backend HTTP service should start as a new Go binary under `cmd/orchd`. + +Responsibilities: + +- expose REST or RPC-style HTTP endpoints for the web frontend +- expose SSE or websocket updates for run and thread activity +- load the same database as the CLI tools +- use shared application services rather than reimplementing logic + +The existing `cmd/orch` and `cmd/inbox` binaries should remain available as operator and debugging tools. + +### `internal/app` + +This package should become the shared application-service layer. + +It should own business actions that currently sit mostly in CLI command handlers, such as: + +- dispatch +- reconcile +- answer +- retry +- reassign +- cancel +- council start, wait, tally, and report orchestration entrypoints + +Both CLI commands and HTTP handlers should call into this layer. + +### `internal/query` + +This package should hold read models specifically shaped for the web UI. + +Examples: + +- run overview with task counts and recent event summaries +- kanban-style task board grouped by status +- blocked queue with latest question details +- thread timeline including artifacts and lease state +- council run summaries and grouped recommendation views + +These should be query-oriented models rather than raw database table mirrors. + +### `internal/httpapi` + +This package should hold the web transport layer. + +Recommended contents: + +- `router.go` +- handler packages by domain +- auth and request middleware +- error mapping +- SSE handlers +- request validation and response serialization + +The HTTP layer should stay thin. +It should not own business rules or embed SQL-heavy logic. + +## Why `chi` + +`chi` is the recommended HTTP router for this product direction. + +Reasons: + +- it stays close to standard `net/http` +- it provides cleaner routing and middleware composition than a bare `ServeMux` +- it avoids the heavier framework lock-in of `gin` +- it fits a backend that is expected to grow into a real product API + +The decision here is not about raw performance. +It is about long-term code organization and maintainable HTTP structure. + +## Why Not Build The Backend Around The Existing CLIs + +The new web backend should not execute `orch` or `inbox` binaries as subprocesses. + +That approach would create avoidable problems: + +- duplicate input validation paths +- harder error mapping +- unstable process-level integration points +- slower request handling +- more difficult testing +- awkward transaction and context handling + +The CLIs should become alternate entrypoints into shared services, not the implementation boundary for the web product. + +## API Contract Direction + +The monorepo should add an explicit API contract under `api/`. + +Recommended starting files: + +- `api/openapi.yaml` +- `api/events.md` + +`openapi.yaml` should define: + +- runs list and detail endpoints +- task list and task action endpoints +- blocked queue endpoints +- thread detail endpoints +- council report endpoints + +`events.md` should define: + +- event stream transport choice +- cursoring model +- payload shapes for run, task, thread, and council events + +The web frontend should generate a typed client from the HTTP contract where practical. + +## Frontend Direction + +The frontend should be a standalone app in the monorepo, not embedded templates. + +Recommended responsibilities: + +- run dashboard +- task board +- blocked queue +- thread detail and timeline +- council result and report views +- operator actions such as answer, retry, reassign, and cancel + +Recommended development model: + +- local dev server from `apps/web` +- proxy API requests to `orchd` +- consume typed API clients instead of hand-written fetch calls where possible + +## Backend Evolution Plan + +The current project already has strong backend assets: + +- durable schema and migrations +- store-layer logic for `inbox` and `orch` +- stable JSON conventions +- working CLI surfaces + +The backend should therefore evolve in-place: + +1. keep the current store and schema as the persistence foundation +2. extract shared application actions into `internal/app` +3. add UI-oriented read models in `internal/query` +4. add `cmd/orchd` and `internal/httpapi` +5. attach the React frontend after the API contract stabilizes + +This is safer than first attempting a large repo split or backend rewrite. + +## Suggested Initial Endpoint Set + +The first useful web slice should remain narrow. + +Recommended read endpoints: + +- `GET /api/runs` +- `GET /api/runs/{runID}` +- `GET /api/runs/{runID}/tasks` +- `GET /api/runs/{runID}/blocked` +- `GET /api/threads/{threadID}` +- `GET /api/council/runs/{runID}` + +Recommended write endpoints: + +- `POST /api/runs/{runID}/tasks/{taskID}/answer` +- `POST /api/runs/{runID}/tasks/{taskID}/retry` +- `POST /api/runs/{runID}/tasks/{taskID}/reassign` +- `POST /api/runs/{runID}/tasks/{taskID}/cancel` + +Recommended realtime endpoint: + +- `GET /api/events/stream` + +The first UI should prioritize observation over broad mutation. + +## Realtime Direction + +The current system already has a shared `events` table for monotonic activity tracking. +That makes SSE a good first realtime transport. + +Recommended approach: + +- begin with SSE rather than websockets +- stream cursor-based events from the backend +- let the frontend use events to invalidate or refresh query results +- keep the server-side event payloads close to run, task, thread, and council activity + +Websockets can be reconsidered later if bidirectional session behavior becomes necessary. + +## Database Direction + +SQLite remains appropriate for the current CLI-focused local workflow and can also support early web product development in controlled environments. + +However, if the product becomes truly multi-user or centrally hosted, the backend should expect a later database transition. + +Recommended position: + +- keep SQLite during the first web API and frontend milestone +- avoid SQLite-specific assumptions in the new application-service and query layers +- plan for a future Postgres migration if concurrency, deployment, or tenancy requirements grow + +The goal is to avoid rewriting product boundaries just because the storage engine changes later. + +## Implementation Phases + +### Phase 1: Monorepo Skeleton And Backend Service + +Add: + +- `apps/web` +- `cmd/orchd` +- `internal/httpapi` +- `internal/app` +- `internal/query` +- `api/openapi.yaml` +- `api/events.md` +- root JS workspace files such as `package.json` and `pnpm-workspace.yaml` + +Deliverable: + +- the repository builds with the new monorepo structure in place +- the backend can serve a small read-only API + +### Phase 2: Read-Only Web UI + +Build: + +- runs page +- run detail view +- task board +- blocked queue +- thread detail + +Deliverable: + +- the React frontend can inspect live orchestration state through `orchd` + +### Phase 3: Realtime Updates + +Add: + +- SSE event endpoint +- frontend subscription and refresh behavior + +Deliverable: + +- run and thread views update without manual reload loops + +### Phase 4: Write Operations + +Add: + +- answer +- retry +- reassign +- cancel + +Deliverable: + +- the web UI becomes a practical operator surface rather than read-only reporting + +### Phase 5: Product Hardening + +Add: + +- auth +- user and organization concepts +- audit trails +- deployment configuration +- database migration planning beyond SQLite if needed + +Deliverable: + +- the system can evolve beyond a local operator tool into a formal product backend + +## Non-Goals For The First Web Milestone + +Do not treat these as part of the initial skeleton task: + +- a full permissions model +- background job infrastructure +- multi-tenant isolation +- websocket-first architecture +- immediate database migration +- full replacement of the CLI workflows + +The first milestone should create a durable path, not solve every product concern at once. + +## Migration Notes For Existing Code + +The current codebase should be adapted incrementally. + +Recommended rules: + +- keep `cmd/orch` and `cmd/inbox` working while the HTTP layer is introduced +- move business logic out of command handlers only when the shared service abstraction is clear +- do not rewrite `store` just to match HTTP names +- let the frontend shape drive `internal/query`, not the table layout alone +- avoid introducing duplicate orchestration logic between CLI and HTTP + +## Immediate Recommended Next Step + +If the project begins this web-product milestone, the first implementation slice should be: + +1. scaffold the monorepo workspace files and `apps/web` +2. add `cmd/orchd` with a `chi` router and a minimal health or runs endpoint +3. introduce the first shared application or query boundary rather than letting handlers call storage ad hoc +4. write the initial API contract in `api/openapi.yaml` + +This gives the project a clean backbone before deeper UI work begins.