docs: monorepo restructure plan

[jeanduplessis]

Summary

Adds a detailed plan for restructuring the monorepo from the current flat layout (where the root serves as both pnpm workspace root and the Next.js app) into a standard apps/ + services/ + packages/ structure.

Key decisions captured in the plan:

• Move Next.js app from root to apps/web/
• Move Storybook to apps/storybook/
• Move all Cloudflare workers to services/, stripping the cloudflare- prefix from directory names
• Move kiloclaw-secret-catalog to packages/ (shared across web app and kiloclaw)
• Keep tightly-coupled sub-packages (wrappers, containers) nested within their service
• Add Turborepo for build orchestration
• Split root package.json into lean workspace root + apps/web/package.json

The plan covers 12 implementation phases, CI/CD workflow updates, config file migrations, risk mitigations, and post-merge manual steps (Vercel dashboard).

No code changes — this is a plan document for team review before implementation.

Verification

• Plan document is well-structured and complete
• All 19 worker directories are accounted for in the migration mapping
• CI/CD workflow impacts are identified for all 6 affected workflows
• External dependencies (Vercel dashboard, Sentry) are called out

Visual Changes

N/A

Reviewer Notes

Please review plans/monorepo-restructure.md and comment on any decisions you disagree with or risks you see. Key areas to weigh in on:

• The apps/ vs services/ split for deployables
• Stripping cloudflare- prefix from service directory names
• Whether Turborepo is the right build orchestration choice
• The single-PR approach vs phased rollout
• Anything missing from the out-of-scope list that should be addressed now

[kilo-code-bot]

WARNING: Root workflow commands are missing from the new script list

Today the repo still relies on root format:check, dependency-cycle-check, drizzle, and test:e2e commands (ci.yml, deploy-production.yml, and chromatic.yml all call them). If the root package is reduced to only the scripts listed here, the first restructure PR will leave those workflows red unless the plan also preserves root aliases or explicitly rewrites each caller.

[kilo-code-bot]

WARNING: turbo run test changes CI semantics in a risky way

The current top-level test job only runs the web Jest suite; several worker packages are tested in separate jobs because they need extra setup (for example cloud-agent and cloud-agent-next build their wrappers first, and Playwright runs in chromatic.yml). Replacing the root script with turbo run test would make the generic CI job execute every workspace test script on every PR, which duplicates work and can break packages that are not prepared in that job.

[kilo-code-bot]

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Fix these issues in Kilo Cloud

Issue Details (click to expand)

WARNING

File	Line	Issue
plans/monorepo-restructure.md	259	Root script list drops commands that current CI and deploy workflows still invoke (format:check, dependency-cycle-check, drizzle, test:e2e).
plans/monorepo-restructure.md	264	Changing root test to turbo run test would make the generic CI job run every workspace test instead of only the web suite.

Other Observations (not in diff)

N/A

Files Reviewed (1 files)

• plans/monorepo-restructure.md - 2 issues

---

_{Reviewed by gpt-5.4-20260305 · 1,207,881 tokens}