Add Codex cross-repo review workflow and cleanup rules
This commit is contained in:
parent
912fdf54ba
commit
fa504660bd
240
CODE_REVIEW_WORKFLOW.md
Normal file
240
CODE_REVIEW_WORKFLOW.md
Normal file
@ -0,0 +1,240 @@
|
||||
# Code Review Workflow
|
||||
|
||||
This document captures the current Codex-based review workflow for ZeroLagHub cross-repo code review and cleanup.
|
||||
|
||||
## Current review goal
|
||||
|
||||
Review the three active implementation repos together without breaking operations:
|
||||
- `zlh-agent`
|
||||
- `zpack-api`
|
||||
- `zpack-portal`
|
||||
|
||||
Primary goals:
|
||||
- verify inter-repo contracts and ownership boundaries
|
||||
- identify mismatches and risky assumptions
|
||||
- identify behavior-preserving cleanup / code-fold opportunities
|
||||
- keep cleanup separate from runtime/toolchain modernization
|
||||
|
||||
## Current setup
|
||||
|
||||
All target repos should be fully up to date before review begins.
|
||||
|
||||
Codex environments are **one repo per environment**. The current working setup is:
|
||||
- `Agent Review` environment -> `zlh-agent`
|
||||
- `API Review` environment -> `zpack-api`
|
||||
- `Portal Review` environment -> `zpack-portal`
|
||||
|
||||
There is **no multi-repo Codex environment** in the current setup. Cross-repo synthesis happens afterward in a separate chat/task by comparing the three outputs.
|
||||
|
||||
Recommended environment settings:
|
||||
- universal image
|
||||
- container caching ON
|
||||
- setup script automatic
|
||||
- internet access OFF unless explicitly needed
|
||||
|
||||
## Review order
|
||||
|
||||
1. review `zlh-agent` first as the source of truth for runtime behavior
|
||||
2. review `zpack-api` second as the auth/transport/contract layer
|
||||
3. review `zpack-portal` third as the UI/state/rendering layer
|
||||
4. synthesize the three outputs in a separate chat/task
|
||||
5. only then start cleanup / folding waves
|
||||
|
||||
## Cross-repo review checklist
|
||||
|
||||
For all three repos, the critical flows to trace are:
|
||||
- provision / start / first boot
|
||||
- stop / restart
|
||||
- status / readiness
|
||||
- backup create / list / delete / restore
|
||||
- file edit / upload / revert
|
||||
- console connect / reconnect
|
||||
|
||||
For each flow, review should identify:
|
||||
- owner of behavior
|
||||
- current contract
|
||||
- assumptions about the other repos
|
||||
- confirmed aligned areas
|
||||
- mismatches / risky assumptions
|
||||
- cleanup-safe folds
|
||||
- high-risk breakpoints
|
||||
- suggested follow-up checks
|
||||
|
||||
## Repo prompts
|
||||
|
||||
### Agent Review prompt
|
||||
|
||||
```text
|
||||
Review this repository as the source of truth for runtime behavior in the ZeroLagHub stack.
|
||||
|
||||
Focus on:
|
||||
- provisioning/startup
|
||||
- stop/restart
|
||||
- readiness and status
|
||||
- backup/create/list/delete/restore
|
||||
- file edit/upload/revert
|
||||
- console lifecycle
|
||||
|
||||
Goals:
|
||||
- identify owned behavior
|
||||
- identify assumptions this repo makes about API and Portal
|
||||
- identify any behavior that other repos are likely depending on implicitly
|
||||
- identify cleanup-safe folds that preserve behavior
|
||||
- identify any risky areas where refactoring could break operations
|
||||
|
||||
Do not refactor yet.
|
||||
Do not propose broad architecture changes.
|
||||
Prefer operational correctness over style commentary.
|
||||
|
||||
Return in this exact structure:
|
||||
1. Owned behavior
|
||||
2. Current contracts exposed to other repos
|
||||
3. Assumptions about API/Portal
|
||||
4. Confirmed aligned or stable areas
|
||||
5. Mismatches / risky assumptions
|
||||
6. Cleanup-safe folds
|
||||
7. High-risk breakpoints
|
||||
8. Suggested follow-up checks
|
||||
```
|
||||
|
||||
### API Review prompt
|
||||
|
||||
```text
|
||||
Review this repository as the transport, auth, and contract layer between zlh-agent and the Portal in the ZeroLagHub stack.
|
||||
|
||||
Focus on:
|
||||
- auth / ownership / IP checks
|
||||
- route forwarding to agent
|
||||
- status polling and shaping
|
||||
- backup/create/list/delete/restore forwarding
|
||||
- restore async-start contract
|
||||
- file edit/upload/revert forwarding
|
||||
- websocket / console proxy behavior
|
||||
|
||||
Goals:
|
||||
- identify owned behavior
|
||||
- identify assumptions this repo makes about agent behavior
|
||||
- identify assumptions this repo makes about Portal behavior
|
||||
- identify duplicated logic that belongs in agent or portal instead
|
||||
- identify cleanup-safe folds that preserve behavior
|
||||
- identify risky areas where refactoring could break operations
|
||||
|
||||
Do not refactor yet.
|
||||
Do not propose broad architecture changes.
|
||||
Prefer operational correctness over style commentary.
|
||||
|
||||
Return in this exact structure:
|
||||
1. Owned behavior
|
||||
2. Current contracts exposed to Portal
|
||||
3. Assumptions about agent
|
||||
4. Confirmed aligned or stable areas
|
||||
5. Mismatches / risky assumptions
|
||||
6. Cleanup-safe folds
|
||||
7. High-risk breakpoints
|
||||
8. Suggested follow-up checks
|
||||
```
|
||||
|
||||
### Portal Review prompt
|
||||
|
||||
```text
|
||||
Review this repository as the UI/state/rendering layer of the ZeroLagHub stack.
|
||||
|
||||
Focus on:
|
||||
- polling and status rendering
|
||||
- server action flows
|
||||
- backup/create/list/delete/restore UX
|
||||
- restore accepted -> in-progress -> completion behavior
|
||||
- file edit/upload/revert UX
|
||||
- console connect/reconnect behavior
|
||||
- any duplicated logic that looks like it belongs in API or agent
|
||||
|
||||
Goals:
|
||||
- identify owned behavior
|
||||
- identify assumptions this repo makes about API responses and agent semantics
|
||||
- identify status/rendering mismatches that could mislead users
|
||||
- identify cleanup-safe folds that preserve behavior
|
||||
- identify risky areas where refactoring could break operations
|
||||
|
||||
Do not refactor yet.
|
||||
Do not propose broad architecture changes.
|
||||
Prefer operational correctness over style commentary.
|
||||
|
||||
Return in this exact structure:
|
||||
1. Owned behavior
|
||||
2. Current contracts consumed from API
|
||||
3. Assumptions about API/agent
|
||||
4. Confirmed aligned or stable areas
|
||||
5. Mismatches / risky assumptions
|
||||
6. Cleanup-safe folds
|
||||
7. High-risk breakpoints
|
||||
8. Suggested follow-up checks
|
||||
```
|
||||
|
||||
## Synthesis step
|
||||
|
||||
After all three reviews complete, paste the outputs into a separate chat/task with headers like:
|
||||
|
||||
```text
|
||||
AGENT REVIEW
|
||||
...
|
||||
|
||||
API REVIEW
|
||||
...
|
||||
|
||||
PORTAL REVIEW
|
||||
...
|
||||
```
|
||||
|
||||
Then synthesize into:
|
||||
- confirmed aligned contracts
|
||||
- mismatches
|
||||
- risky assumptions
|
||||
- operational breakpoints
|
||||
- cleanup-safe folds
|
||||
- suggested fix order
|
||||
|
||||
## Cleanup / folding rules
|
||||
|
||||
Cleanup happens **after** synthesis, not before.
|
||||
|
||||
Shared rule across Agent / API / Portal:
|
||||
- prefer behavior-preserving folding over broad refactors
|
||||
- fold repeated flows first
|
||||
- split oversized files by responsibility second
|
||||
- merge repeated flows, not concepts
|
||||
- keep helpers small and concrete
|
||||
- keep cleanup separate from runtime/toolchain/dependency upgrades
|
||||
|
||||
## Current cleanup direction
|
||||
|
||||
### Agent
|
||||
- fold Forge + NeoForge installer flow
|
||||
- fold devcontainer runtime installers
|
||||
- split oversized HTTP files by responsibility
|
||||
- add only small concrete helpers
|
||||
|
||||
### API
|
||||
- fold repeated forwarding/auth/IP-guard patterns
|
||||
- centralize stream-vs-JSON forwarding
|
||||
- split oversized route/service files by responsibility
|
||||
|
||||
### Portal
|
||||
- fold repeated API-client/status-polling/state-mapping logic
|
||||
- centralize shared management action handling
|
||||
- split oversized page/component/state files by responsibility
|
||||
|
||||
## Current toolchain posture
|
||||
|
||||
Current pinned / confirmed runtime posture at time of writing:
|
||||
- Node: `22.22.2`
|
||||
- Go: updated to a current supported line
|
||||
|
||||
Toolchain/runtime upgrades should be tracked and validated separately from cleanup-only changes.
|
||||
|
||||
## Session restart note
|
||||
|
||||
If a fresh session is needed, resume by:
|
||||
1. reading this file
|
||||
2. checking `OPEN_THREADS.md`
|
||||
3. checking repo-specific trackers under `Codex/*/OPEN_ITEMS.md`
|
||||
4. continuing the three-review -> synthesis -> cleanup workflow
|
||||
Loading…
Reference in New Issue
Block a user