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
Copy file name to clipboardExpand all lines: .agents/roles.md
+28-5Lines changed: 28 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,8 +27,8 @@ Use these model tiers when assigning work to another LLM.
27
27
| Tier | Use | Default model |
28
28
| --- | --- | --- |
29
29
|`Primary`| Planning, implementation, architecture decisions, final integration, failed-check triage | Strongest available Codex/GPT coding model |
30
-
|`Lightweight`| Read-only review, checklist validation, log summarization, documentation draft, first-pass architecture preflight |Best available lightweight coding model that is different from the active `Primary` model|
31
-
|`Fast`| Low-risk text cleanup, simple file presence checks, short summaries |Fastest available coding model that is different from the active `Primary` model|
30
+
|`Lightweight`| Read-only review, checklist validation, log summarization, documentation draft, first-pass architecture preflight |Pinned non-Primary model from the configured custom agent TOML|
31
+
|`Fast`| Low-risk text cleanup, simple file presence checks, short summaries |Pinned fast model from the configured custom agent TOML when a Fast role is defined|
32
32
33
33
Default role-to-model and execution assignment:
34
34
@@ -59,11 +59,32 @@ Do not assign `Lightweight` as the only model for production Swift implementatio
59
59
- If the assigned model is available but current tool policy requires explicit user permission before dispatch, missing permission is not fallback. Stop and ask for permission before continuing the required role.
60
60
-`Primary` must integrate and verify delegated output, but must not skip the delegated role when the workflow requires it and the assigned model is available.
61
61
62
+
### Connected side-task dispatch
63
+
64
+
- Run every `Lightweight` or `Fast` role as a side task connected to the current main task.
65
+
- Use `spawn_agent` from tools or `Option-Command-S` from the UI sidebar. Treat both as the same connected dispatch surface.
66
+
- Set `spawn_agent.task_name` to the exact `.codex/agents/<name>.toml` filename without the extension and the exact TOML `name` value.
67
+
- Do not add arbitrary prefixes or suffixes to `task_name`. Names such as `issue_documentation_writer` and `documentation_writer_issue` do not select the configured custom agent.
68
+
- Return each role result to the current main task so `Primary` can review and integrate it.
69
+
- Send later work for the same role to the existing agent with `followup_task` instead of creating another agent name.
70
+
- Do not use external `codex exec` or a separate user-owned `create_thread` as a repository role dispatch surface.
71
+
- Do not count a generic sub-agent that does not select the configured custom agent as a `Lightweight` or `Fast` role execution.
72
+
- Do not treat a failure from external `codex exec`, `create_thread`, or an arbitrary `task_name` as proof that the configured custom agent or pinned model is unavailable.
- Choose the best available role-capable lightweight coding model without hardcoding a provider or model name.
65
-
- If the preferred lightweight model is unavailable, choose another available role-capable model that is still different from the active `Primary` model.
66
-
- If no eligible non-Primary model is available, do not fall back to `Primary`; stop and report the unavailable role.
86
+
- The configured custom agent TOML is the source of truth for the non-Primary role model and sandbox.
87
+
- If a required custom agent or its pinned non-Primary model is unavailable, do not fall back to another model; stop and report the unavailable role.
67
88
- If `Primary` is unavailable, do not perform implementation, architecture verdict, final integration, git write actions, or GitHub write actions.
68
89
- Do not downgrade `Primary` roles to `Lightweight` or `Fast` only because a cheaper model is available.
69
90
- For user-facing summaries, a lower tier may draft text, but `Primary` must check it when the text depends on architecture decisions, release risk, CI root cause, or exact diff behavior.
@@ -125,6 +146,8 @@ Use `Architecture risk: possible` when the task touches module boundaries, impor
125
146
126
147
Use this template when assigning a `Lightweight` or `Fast` role through its configured custom agent. `Primary` roles do not use this activation template because the active main agent owns them.
127
148
149
+
Create the connected side task with `spawn_agent.task_name` set to the exact identifier in the routing table. When using the UI sidebar, create the same connected side task with `Option-Command-S`. After the first dispatch, use `followup_task` for later work assigned to the same role.
150
+
128
151
```md
129
152
You are the `<Role Name>` for the DevLog iOS repository.
Copy file name to clipboardExpand all lines: .agents/workflows.md
+23-10Lines changed: 23 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,14 +17,19 @@ The main agent must run every workflow with this protocol.
17
17
3. Create the task packet.
18
18
4. Assign only the roles required by the selected workflow.
19
19
5. Assign each role a model tier from `.agents/roles.md`.
20
-
6. Keep `Primary` roles with the active main agent, and dispatch every `Lightweight` or `Fast` role through the custom agent mapped in `.agents/roles.md`.
21
-
7. Dispatch read-only `Lightweight` or `Fast` roles in parallel only when they do not depend on unfinished edits.
22
-
8. Do not complete a required `Lightweight` or `Fast` role directly in `Primary`, including when the dispatch tool would inherit the active `Primary` model.
23
-
9. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint.
24
-
10. Integrate role outputs.
25
-
11. Escalate any `Lightweight` or `Fast` blocker to a `Primary` model before editing.
26
-
12. Run completion gates.
27
-
13. Report changed files, architecture decision, verification result, delegated roles, model tiers used, and unresolved decisions.
20
+
6. Keep `Primary` roles with the active main agent.
21
+
7. Find the exact custom agent name in `.agents/roles.md` and its matching `.codex/agents/<name>.toml` before dispatching a `Lightweight` or `Fast` role.
22
+
8. Create the role as a side task connected to the current main task with `spawn_agent.task_name` set to that exact name, or use `Option-Command-S` from the UI sidebar for the same connected dispatch surface.
23
+
9. Do not use external `codex exec`, a separate user-owned `create_thread`, or an arbitrary `task_name` for repository role dispatch.
24
+
10. Reuse the existing role agent with `followup_task` when assigning later work to the same role.
25
+
11. Return every delegated role result to the current main task for `Primary` review and integration.
26
+
12. Do not complete a required `Lightweight` or `Fast` role directly in `Primary`, and do not substitute a generic sub-agent for the configured custom agent.
27
+
13. Dispatch read-only `Lightweight` or `Fast` roles in parallel only when they do not depend on unfinished edits.
28
+
14. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint.
29
+
15. Integrate role outputs.
30
+
16. Escalate any `Lightweight` or `Fast` blocker to a `Primary` model before editing.
31
+
17. Run completion gates.
32
+
18. Report changed files, architecture decision, verification result, delegated roles, model tiers used, and unresolved decisions.
28
33
29
34
Do not skip the task packet. The task packet is the contract between models.
30
35
@@ -35,12 +40,14 @@ Stop and ask the user before editing when:
35
40
- The task packet conflicts with `AGENTS.md`.
36
41
- The requested fix requires relaxing a layer boundary.
37
42
- A role needs to run, launch, install, boot, or open the app or Simulator.
38
-
- A required `Lightweight` or `Fast` custom agent cannot be loaded or selected, its pinned model is unavailable, or current tool policy requires user permission that has not been granted.
43
+
- A required `Lightweight` or `Fast` custom agent cannot be loaded or selected through the connected side-task surface with its exact `task_name`, its pinned model is unavailable, or current tool policy requires user permission that has not been granted.
39
44
- The current issue or PR scope is unclear after live GitHub inspection.
40
45
- Two editing roles would touch the same file.
41
46
- A read-only role reports `Block` or `Needs Owner Decision`.
42
47
- Verification fails for a reason that suggests a scope or architecture decision.
43
48
49
+
Do not apply the custom-agent stop condition only because external `codex exec`, a separate `create_thread`, or an arbitrary `task_name` failed. Retry through the connected side-task surface with the exact configured name first.
50
+
44
51
## Workflow selection
45
52
46
53
| User request | Workflow |
@@ -289,7 +296,7 @@ Architecture Watcher is required only if the change modifies architecture policy
If only Markdown workflow files changed, no iOS build is required.
@@ -310,6 +317,8 @@ Report:
310
317
311
318
## Parallel dispatch guide
312
319
320
+
Use only side tasks connected to the current main task for parallel role dispatch. Create them with exact configured custom agent names through `spawn_agent` or with `Option-Command-S` in the UI sidebar.
321
+
313
322
Parallelize only these combinations:
314
323
315
324
- GitHub/CI Analyst reading live GitHub state while Planner inspects local files.
@@ -353,6 +362,8 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s
0 commit comments