Skip to content

Commit b02392b

Browse files
hacker-b2kCodeKing
hacker-b2k
and
CodeKing
authored
chore: setup workspace governance, docs, and fix webview test OOM (#1)
* fix(webview): increase vitest heap memory to prevent OOM on Windows Set vitest pool to 'forks' with --max-old-space-size=4096 to fix JavaScript heap out of memory errors when running webview test suite on Windows. The default worker pool (threads) was causing node to exceed its available memory under the large test suite. Refs: Zoo-Code-Org#443 (Vitest 4 upgrade) * docs: add workspace governance, planning requirements, and architecture documentation Establishes professional development standards for the Zoo Code project: - WORKSPACE_GOVERNANCE.md: Absolute rules, tech stack, build commands, branch strategy, and commit message conventions - PLANNING_REQUIRED.md: Mandatory 5-stage pipeline (Research → Design → Plan → Review → Execute) before any code change - docs/README.md: Master index with golden workflow and core principles - docs/ARCHITECTURE.md: Deep technical reference — monorepo build order, task execution, key classes, IPC protocol, AI providers, state mgmt - docs/REQUIREMENTS.md: Standing/project requirements and DoD checklist - docs/DEV_SETUP.md: Zero-to-running setup guide - docs/research/: Research log template - docs/plans/: Implementation plan template - docs/decisions/: Architecture Decision Records (ADRs 1-3) - ADR-001: SettingsView cached state pattern - ADR-002: Monorepo with Turborepo - ADR-003: types package build first --------- Co-authored-by: CodeKing <codeking@example.com>
1 parent e8acc6a commit b02392b

12 files changed

Lines changed: 1055 additions & 0 deletions

‎PLANNING_REQUIRED.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# 📐 Planning Required — Before Every Change
2+
3+
> **RULE: Zero code without a plan. This is not optional.**
4+
>
5+
> Every task — no matter how small — must go through this pipeline before implementation begins.
6+
7+
---
8+
9+
## The Pipeline (5 Stages, No Skipping)
10+
11+
```
12+
1. RESEARCH → 2. DESIGN → 3. PLAN → 4. REVIEW → 5. EXECUTE
13+
```
14+
15+
---
16+
17+
## Stage 1: Research
18+
19+
Before writing a single line, answer these questions in `docs/research/<topic>.md`:
20+
21+
- What is the exact problem or feature being addressed?
22+
- What existing code is involved? (Read all affected files fully.)
23+
- What does the current behavior look like? (Run it, test it, observe it.)
24+
- What are the constraints? (Performance, compatibility, API limits, bundle size?)
25+
- What have others done? (Check existing patterns in this codebase first.)
26+
- What could go wrong?
27+
28+
**Minimum time: Do not rush this. A missed dependency here = broken code later.**
29+
30+
---
31+
32+
## Stage 2: Design
33+
34+
Write a design document in `docs/decisions/<ADR-NNN-topic>.md`:
35+
36+
- Proposed solution (with rationale)
37+
- Alternative approaches considered (and why rejected)
38+
- Data flow / sequence diagram if applicable
39+
- API surface changes (if any)
40+
- Types / interfaces affected
41+
- Test strategy
42+
43+
---
44+
45+
## Stage 3: Plan
46+
47+
Create an implementation plan in `docs/plans/<task-name>.md` using this template:
48+
49+
```markdown
50+
# Implementation Plan: <Task Name>
51+
Date: YYYY-MM-DD
52+
Status: Draft | In Progress | Complete
53+
54+
## Objective
55+
One sentence: what does this accomplish?
56+
57+
## Scope
58+
- Files to create: []
59+
- Files to modify: []
60+
- Files to delete: []
61+
- Packages affected: []
62+
63+
## Steps
64+
- [ ] Step 1 — description (estimated: X min)
65+
- [ ] Step 2 — description
66+
- [ ] Step 3 — description
67+
...
68+
69+
## Verification
70+
- [ ] `pnpm check-types` passes
71+
- [ ] `pnpm test` passes (relevant test suites)
72+
- [ ] `pnpm lint` passes
73+
- [ ] Manual test: [describe what to verify visually/functionally]
74+
75+
## Risks
76+
- Risk 1: [mitigation]
77+
- Risk 2: [mitigation]
78+
79+
## Dependencies
80+
- Depends on: [other tasks/PRs]
81+
- Blocks: [other tasks/PRs]
82+
```
83+
84+
---
85+
86+
## Stage 4: Review
87+
88+
Before executing, the plan must be self-reviewed:
89+
90+
- Does this plan cover all edge cases?
91+
- Is there a simpler approach that achieves the same result?
92+
- Does this break any existing behavior?
93+
- Is the scope creep-free? (Only doing what was planned.)
94+
95+
---
96+
97+
## Stage 5: Execute
98+
99+
Only now write code. Follow the plan step by step. Mark steps complete as you go.
100+
101+
**During execution:**
102+
- Make one logical change at a time.
103+
- Run type checks after each significant change.
104+
- Never leave the codebase in a broken state between steps.
105+
- If you discover something that changes the plan → stop, update the plan, then continue.
106+
107+
---
108+
109+
## ⛔ What Happens If You Skip This
110+
111+
- Broken builds that block others
112+
- Regressions in features that seemed unrelated
113+
- Type errors discovered at bundle time, not at dev time
114+
- Wasted hours debugging avoidable issues
115+
- Rejected PRs that require full rewrites
116+
117+
**The plan takes 10 minutes. The bugs it prevents take hours to fix.**
118+
119+
---
120+
121+
*This document applies to ALL contributors: human and AI agents alike.*

‎WORKSPACE_GOVERNANCE.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# 🔒 Zoo Code Workspace Governance
2+
3+
> **This document is LAW in this workspace. Every agent, developer, and contributor MUST read and follow it before touching a single line of code.**
4+
5+
---
6+
7+
## ⚠️ ABSOLUTE RULES — NON-NEGOTIABLE
8+
9+
### 1. NO SHORTCUTS
10+
- Never use `--no-verify`, `--force`, shallow clones, or any flag that bypasses safety checks unless explicitly documented and approved.
11+
- Never skip tests, type checks, or linting.
12+
- Never comment out failing tests to make CI pass.
13+
- Never use `any` in TypeScript unless it is the ONLY option and is explicitly justified in a comment.
14+
- Never hardcode values that belong in config or constants.
15+
16+
### 2. NO CHEATING
17+
- Do not fabricate test results. Run them. Report what actually happened.
18+
- Do not claim a task is done if verification was not performed.
19+
- Do not skip LFS files, binary assets, or large files because they are inconvenient.
20+
- Do not fake file counts, hashes, or comparison results.
21+
- Every claim must be provable. Every action must be verifiable.
22+
23+
### 3. PLAN FIRST — ALWAYS
24+
- **Zero code changes without a written plan.** See `PLANNING_REQUIRED.md`.
25+
- Every feature, fix, or refactor starts with: Research → Design → Plan → Review → Execute.
26+
- No one-line "quick fixes" without understanding the full impact.
27+
28+
### 4. NO HALF-WORK
29+
- A task is not done until it is verified end-to-end.
30+
- No "I'll fix it later." Fix it now or do not do it.
31+
- Every PR must be complete: code + tests + docs update if needed.
32+
33+
### 5. INDUSTRY STANDARD QUALITY
34+
- Code must be production-grade. No placeholder logic, no TODO-driven development in final output.
35+
- All TypeScript must be strictly typed.
36+
- All new modules must have unit tests.
37+
- All public APIs must be documented.
38+
39+
---
40+
41+
## 📋 PRE-CHANGE CHECKLIST
42+
43+
Before making ANY change to this codebase, answer ALL of these:
44+
45+
- [ ] Have I read `ARCHITECTURE.md` and understand the affected modules?
46+
- [ ] Have I read `REQUIREMENTS.md` for the current task scope?
47+
- [ ] Have I written a plan in `docs/plans/` (from `PLANNING_REQUIRED.md`)?
48+
- [ ] Have I identified all files that will be affected?
49+
- [ ] Have I checked for existing tests that cover this area?
50+
- [ ] Have I verified the change does not break existing functionality?
51+
- [ ] Have I run `pnpm check-types` before submitting?
52+
- [ ] Have I run `pnpm test` before submitting?
53+
- [ ] Have I run `pnpm lint` before submitting?
54+
55+
---
56+
57+
## 🛠️ TECH STACK (READ BEFORE CODING)
58+
59+
| Layer | Tech |
60+
|---|---|
61+
| Language | TypeScript 5.8 (strict) |
62+
| Runtime | Node.js 20.20.2 |
63+
| Package manager | pnpm 10.8.1 |
64+
| Monorepo | Turborepo 2.9 |
65+
| Extension host | VS Code Extension API |
66+
| Frontend | React 18 + Vite 8 |
67+
| Testing | Vitest (unit) + Playwright (e2e) |
68+
| Linting | ESLint 9 |
69+
| Formatting | Prettier 3.5 |
70+
| Build | esbuild 0.28 (extension) + Vite (webview) |
71+
72+
---
73+
74+
## 📁 WHERE THINGS LIVE
75+
76+
```
77+
src/ ← VS Code Extension (main package)
78+
extension.ts ← Activation entry point
79+
core/ ← AI task engine, tools, prompts, context
80+
api/ ← AI provider integrations (50+)
81+
services/ ← MCP, code-index, tree-sitter, ripgrep, etc.
82+
integrations/ ← terminal, editor, browser, diagnostics
83+
activate/ ← Command/action registration
84+
shared/ ← Shared utilities across extension
85+
utils/ ← Pure utility functions
86+
87+
webview-ui/ ← React sidebar UI
88+
src/components/ ← All UI components
89+
src/context/ ← Extension state context
90+
src/hooks/ ← Custom React hooks
91+
92+
packages/ ← Internal shared libraries
93+
@roo-code/types ← Shared types (build first!)
94+
@roo-code/core ← Shared AI engine logic
95+
@roo-code/cloud ← Zoo Code Cloud service
96+
@roo-code/telemetry ← Analytics (PostHog)
97+
@roo-code/ipc ← Extension ↔ Webview message contracts
98+
99+
apps/
100+
vscode-e2e/ ← End-to-end tests
101+
vscode-nightly/ ← Nightly build configuration
102+
103+
docs/ ← All planning, research, decisions (our addition)
104+
plans/ ← Per-task implementation plans
105+
research/ ← Research notes
106+
decisions/ ← Architecture Decision Records (ADRs)
107+
```
108+
109+
---
110+
111+
## 🔄 BUILD COMMANDS
112+
113+
```bash
114+
pnpm install # Install all dependencies
115+
pnpm build # Build all packages
116+
pnpm test # Run all tests
117+
pnpm check-types # TypeScript type check
118+
pnpm lint # ESLint check
119+
pnpm format # Prettier format
120+
pnpm vsix # Build .vsix extension package
121+
pnpm clean # Clean all build artifacts
122+
```
123+
124+
---
125+
126+
## 🚦 BRANCH STRATEGY
127+
128+
- `main` — stable, always passing CI
129+
- `feature/<name>` — new features
130+
- `fix/<name>` — bug fixes
131+
- `refactor/<name>` — refactoring
132+
- `docs/<name>` — documentation only
133+
134+
Never push directly to `main`. Always use a branch + PR.
135+
136+
---
137+
138+
## 📝 COMMIT MESSAGE FORMAT
139+
140+
```
141+
type(scope): short description
142+
143+
Types: feat | fix | refactor | test | docs | chore | perf | style
144+
Scope: core | api | ui | services | integrations | build | deps
145+
146+
Examples:
147+
feat(core): add parallel tool execution support
148+
fix(api): handle claude rate limit with exponential backoff
149+
refactor(services/mcp): extract connection pooling to separate class
150+
```
151+
152+
---
153+
154+
*Last updated: 2026-06-24 | Maintainer: hacker-b2k (Zoo Code fork)*

0 commit comments

Comments
 (0)