You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
onboard-code-projects is a Windows-first Codex Desktop multi-repository workflow-isolation Skill.
11
+
`onboard-code-projects` is the Codex Desktop multi-repository workflow-isolation Skill that reduces context pollution with verified, reusable project tasks and `codebase-memory` indexes, plus an optional controller for cross-project coordination and evidence-backed reuse of accepted successes and deterministic failures.
12
12
13
13
-**Use when:** work crosses two or more related repositories.
14
14
-**You get:** exact-root, verified project-bound entry tasks, a `codebase-memory` index for each repository, and an optional controller for cross-project coordination.
15
15
-**It does not:** create saved Codex projects or approve permissions.
16
16
-**It is not:** a security sandbox, and it does not deploy software.
17
17
18
-
This reduces the risk of repository instructions, branches, permissions, evidence, and edits being mixed in one long conversation.
19
-
20
18
> **Preview:** Windows and Codex Desktop are the supported release surface. Other platforms are not yet release-tested end to end.
21
19
22
20
## Problems this Skill solves
@@ -43,23 +41,117 @@ Project entry tasks may still use subagents internally; the two approaches are c
43
41
44
42
## What you get
45
43
46
-
```mermaid
47
-
flowchart LR
48
-
U["User"] --> A["Project A entry task"]
49
-
U --> B["Project B entry task"]
50
-
U -.->|optional cross-project work| C["Controller"]
51
-
C --> A
52
-
C --> B
53
-
A --> RA["Repository A + index"]
54
-
B --> RB["Repository B + index"]
55
-
```
56
-
57
44
- For each source: one verified saved-project binding, one reusable local entry task, and one `codebase-memory` index.
58
45
- Optionally: one controller directory and controller task outside every business repository.
59
46
- Optionally: durable result return when the plugin Stop Hook and Node.js are available; automatic wake additionally requires validated rule, worker, and automation capabilities.
60
47
61
48
The Skill cannot create a saved Codex project. Add each exact directory in Codex Desktop first; the Skill verifies and uses that identity.
62
49
50
+
## Core workflows
51
+
52
+
The four flows below cover the public lifecycle. Exact payloads, hashes, reason codes, and recovery commands remain in the [controller runtime reference](./references/controller-runtime.md).
53
+
54
+
### 1. Onboard or reuse each repository
55
+
56
+
```mermaid
57
+
flowchart TD
58
+
O1["Local paths or Git URLs"] --> O2["Load or confirm the saved index mode, then parse inputs and run read-only preflight"]
59
+
O2 --> O3{"Source type?"}
60
+
O3 -->|Local directory| O7{"One exact saved project on this host?"}
61
+
O3 -->|Git URL| O4["Clone only into a new cloneRoot child"]
62
+
O4 --> O5["Return needs-project-add"]
63
+
O5 --> O6["User saves the exact clone and reruns"]
64
+
O6 --> O7
65
+
O7 -->|No or ambiguous| O8["Block with a precise next action"]
66
+
O7 -->|Yes| O9["Read AGENTS and verify root, branch, HEAD, and dirty state"]
67
+
O9 --> O10["Create or reuse one project-bound entry task"]
68
+
O10 --> O11["Build or refresh the selected codebase-memory index"]
69
+
O11 --> O12["Verify index root and revision"]
70
+
O12 --> O13["Repository lane ready for direct work"]
71
+
O13 -.->|Optional cross-project work| O14["Verify or initialize an external controller and register this entry"]
72
+
O14 -.->|Controller unavailable or creation result unknown| O15["Keep ready repositories; report pending registration or reconcile evidence without retrying"]
73
+
```
74
+
75
+
Saved projects stay user-owned. The Skill creates neither projectless tasks nor worktrees, and the optional controller must remain outside every business repository.
76
+
77
+
### 2. Coordinate, dispatch, and accept cross-project work
D3 -->|Same project runs one active task in FIFO order| D4
84
+
D3 -->|Independent projects run in parallel| D4
85
+
D4["Seal the dispatch and select the model class by complexity and risk"] --> D5["Send only to the verified project entry task"]
86
+
D5 -.->|Timeout or empty delivery| D15["Stop or hold only this lane; never resend blindly or expand authority"]
87
+
D5 -->|Delivered| D6["Re-read AGENTS and verify root, baseline, and scope"]
88
+
D6 --> D7{"Runtime approval required?"}
89
+
D7 -->|Yes| D8["Only this project waits; other lanes continue"]
90
+
D7 -->|No| D9["Implement and test inside the repository"]
91
+
D8 -->|Approved| D9
92
+
D8 -.->|Declined| D15
93
+
D9 --> D10{"Available return channel?"}
94
+
D10 -->|Hook receipt, with optional wake| D11["Controller re-reads branch, HEAD, diff, tests, and contract; wake is not acceptance"]
95
+
D10 -->|native-callback| D11
96
+
D10 -->|foreground| D11
97
+
D11 --> D12{"Result and evidence disposition?"}
98
+
D12 -->|accepted success| D13["Record success, release the lease, and start the next FIFO item"]
99
+
D12 -->|Eligible business or review failure| D14["Keep the lease and enter the bounded convergence flow below"]
100
+
D12 -->|Cancelled, declined, or non-retryable blocked| D15
101
+
```
102
+
103
+
The controller writes governance state only. Repository edits and tests remain in the exact project entry task; a callback or receipt only signals that evidence is ready to inspect.
104
+
105
+
### 3. Reuse evidence-backed experience and stop retry loops
106
+
107
+
```mermaid
108
+
flowchart TD
109
+
E1["Canonical goal logs and curated evidence-bound imports"] --> E2["ExperienceRead verifies the bounded experience index"]
110
+
E2 --> E3["Match problem, strategy family, and material conditions"]
111
+
E3 --> E4{"Prior verified outcome?"}
112
+
E4 -->|accepted success| E5["Reuse the proven strategy, then recheck current readiness"]
113
+
E4 -->|deterministic failure: reject the same mechanism| E6["Reserve the next allowed strategy"]
114
+
E4 -->|No match or proved material change| E6
115
+
E5 --> E7["Execute, test, and collect current evidence"]
116
+
E6 --> E7
117
+
E7 --> E8{"Reviewed outcome?"}
118
+
E8 -->|accepted success| E9["Store reusable success in the bounded index and close the lane"]
119
+
E8 -->|deterministic failure| E10["Store the hard failure in the bounded index"]
120
+
E8 -->|Transient, environment, superseded, cancelled, or authorization result| E11["Audit only; do not blacklist; cancellation or declined authorization stops the lane"]
121
+
E10 --> E12{"Which business attempt failed?"}
122
+
E11 -.->|Eligible environment change or supersession| E12
123
+
E12 -->|Initial| E13["Run one comprehensive repair"]
124
+
E12 -->|Repair| E14["Run one whole-goal rebaseline"]
125
+
E12 -->|Rebaseline| E15["convergence-failed: stop for a user decision"]
126
+
E13 --> E2
127
+
E14 --> E2
128
+
```
129
+
130
+
This is evidence reuse, not automatic learning. A changed material condition needs direct canonical evidence; renaming a task, opening a new conversation, or changing an unproved hash cannot erase a known deterministic failure. Only a zero-repository-write transport, tool-bootstrap, or payload-parse failure may receive one same-attempt preflight replay.
131
+
132
+
### 4. Refresh a long-lived controller task set
133
+
134
+
```mermaid
135
+
flowchart TD
136
+
R1["Explicit reset request from an external coordinator"] --> R2{"Exact generated v3, task APIs, Node.js, single roots, and quiet state?"}
137
+
R2 -->|No| R3["Block without changing or deleting tasks"]
138
+
R2 -->|Yes| R4["Read-only Plan returns planHash"]
139
+
R4 --> R5["Separately authorized Apply uses the exact planHash"]
140
+
R5 --> R6["Re-read complete history, quiet state, and active work; prepare the runtime fence"]
Apply is forward-only. An interruption keeps the set frozen and resumes the same operation; it never rolls back, deletes tasks, mutates canonical work records, or retries a task creation whose result is unknown.
154
+
63
155
## Quick start
64
156
65
157
### 1. Install
@@ -126,7 +218,6 @@ When a controller and its project entry tasks need fresh conversations, exact ge
126
218
```text
127
219
resetControllerTasks: true
128
220
Action: Plan
129
-
130
221
# Review the returned planHash, then send the same request with:
131
222
Action: Apply
132
223
planHash: <returned planHash>
@@ -153,18 +244,10 @@ indexMode: full
153
244
154
245
The Skill clones only into a new child of `cloneRoot` and then returns `needs-project-add`. Save the exact clone as a Codex project and rerun the same request. The existing clone is reused only after its root, credential-free origin, and requested branch or ref are verified.
155
246
156
-
## How it works
157
-
158
-
1. Match each source to one exact saved project on the current host.
159
-
2. Verify its task identity, root, Git baseline, dirty state, and `codebase-memory` index.
160
-
3. Keep repository changes and tests in that repository's entry task.
161
-
4. Use the optional controller only for shared contracts, sequencing, dispatch, and end-to-end acceptance.
162
-
5. Validate returned branch, HEAD, diff, tests, contract impact, and remaining risk before accepting a result.
247
+
## Boundaries
163
248
164
249
This is **workflow isolation**, not a security sandbox. It does not change filesystem permissions, and manually mixing repositories in one task can reintroduce context pollution.
165
250
166
-
Detailed queue, recovery, convergence, receipt, and controller-state contracts live in [the controller runtime reference](./references/controller-runtime.md), not in this project overview.
0 commit comments