kurihada/ai-workflow-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add web product monorepo planning docs

Browse Source
This commit is contained in:
kurihada
2026-03-20 00:05:22 +08:00
parent b6ba470190
commit 0355d7a847
3 changed files with 487 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/implementation-roadmap.md
+4 -1
View File
@@ -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.
docs/roadmaps/archive/web-product-monorepo-doc.md
+56
View File
@@ -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
docs/web-product-monorepo.md
+427
View File
@@ -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.