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
description = "DevLog documentation writer for PR bodies, issue text, review replies, release notes, and repository documentation changes."
3
+
model = "gpt-5.3-codex-spark"
4
+
model_reasoning_effort = "medium"
5
+
sandbox_mode = "workspace-write"
6
+
developer_instructions = """
7
+
Read AGENTS.md and AGENT_ROLES.md before drafting.
8
+
Act only as the Documentation Writer defined in AGENT_ROLES.md.
9
+
Match repository templates, actual diffs, live issue or PR state, and the requested Korean wording rules.
10
+
Edit only documentation files named in the task packet. Do not edit app code or create GitHub content unless the task packet explicitly authorizes that write action.
11
+
Return exactly the Documentation Result format from AGENT_ROLES.md unless the task packet requests direct Markdown draft output.
description = "Read-only DevLog GitHub and CI analyst for live issues, PR metadata, review threads, and Actions logs."
3
+
model = "gpt-5.3-codex-spark"
4
+
model_reasoning_effort = "medium"
5
+
sandbox_mode = "read-only"
6
+
developer_instructions = """
7
+
Read AGENTS.md and AGENT_ROLES.md before analysis.
8
+
Act only as the GitHub/CI Analyst defined in AGENT_ROLES.md.
9
+
Use live GitHub state as the source of truth and use thread-aware review inspection when resolution state matters.
10
+
Do not edit files, reply, resolve threads, submit reviews, push, or change GitHub state unless the task packet explicitly authorizes that write action.
11
+
Return exactly the GitHub CI Result format from AGENT_ROLES.md.
|`Fast`| Low-risk text cleanup, simple file presence checks, short summaries | Fastest low-cost model available|
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|
32
32
33
-
Default role-to-model assignment:
33
+
Default role-to-model and execution assignment:
34
34
35
-
| Role | Default tier | Escalate to `Primary` when |
36
-
| --- | --- | --- |
37
-
| Planner |`Primary`| Always for live issues, PR scope, architecture scope, or implementation planning |
38
-
| Implementer |`Primary`| Always for Swift production code, tests, target dependencies, DI, SDK placement, or GitHub writes |
39
-
| Architecture Watcher |`Spark` for preflight, `Primary` for final boundary verdict | Any finding is `Block` or `Needs Owner Decision`, or the change touches module dependency, SDK placement, Widget flow, StorePattern, or DI |
40
-
| Code Reviewer |`Spark` for first pass, `Primary` for final blocking review | Findings involve runtime behavior, concurrency, data loss, architecture, or test strategy |
41
-
| Verification Runner |`Spark`| Verification fails, failure cause is unclear, or a fix is needed |
42
-
| GitHub/CI Analyst |`Spark`| CI root cause requires code or workflow changes, or review comments conflict |
43
-
| Documentation Writer |`Spark`| Text must explain complex architecture, release risk, or PR scope tradeoffs |
35
+
| Role | Execution owner or custom agent | Default tier | Escalate to `Primary` when |
36
+
| --- | --- | --- | --- |
37
+
| Planner | active main agent |`Primary`| Always for live issues, PR scope, architecture scope, or implementation planning |
38
+
| Implementer | active main agent |`Primary`| Always for Swift production code, tests, target dependencies, DI, SDK placement, or GitHub writes |
39
+
| Architecture Watcher |`architecture_watcher`|`Lightweight` for preflight, `Primary` for final boundary verdict | Any finding is `Block` or `Needs Owner Decision`, or the change touches module dependency, SDK placement, Widget flow, StorePattern, or DI |
40
+
| Code Reviewer |`code_reviewer`|`Lightweight` for first pass, `Primary` for final blocking review | Findings involve runtime behavior, concurrency, data loss, architecture, or test strategy |
41
+
| Verification Runner |`verification_runner`|`Lightweight`| Verification fails, failure cause is unclear, or a fix is needed |
42
+
| GitHub/CI Analyst |`github_ci_analyst`|`Lightweight`| CI root cause requires code or workflow changes, or review comments conflict |
43
+
| Documentation Writer |`documentation_writer`|`Lightweight`| Text must explain complex architecture, release risk, CI root cause, or PR scope tradeoffs |
44
+
45
+
Project-scoped custom agents live in `.codex/agents/`. Their TOML files pin the concrete model and sandbox for spawned sessions; this table is the canonical role-to-agent routing map.
44
46
45
-
Do not assign `Spark` as the only model for production Swift implementation, target dependency changes, DI assembly, repository/service contract changes, Firebase or SDK placement, Widget data-flow changes, StorePattern responsibility changes, commits, pushes, PR creation, or final integration.
47
+
Do not assign `Lightweight` as the only model for production Swift implementation, target dependency changes, DI assembly, repository/service contract changes, Firebase or SDK placement, Widget data-flow changes, StorePattern responsibility changes, commits, pushes, PR creation, or final integration.
46
48
47
49
### Model dispatch requirements
48
50
49
51
- A model tier assignment is an execution requirement, not a label for work the main agent already performed.
50
-
- When a role is assigned to `Spark` or `Fast`, and tooling can select that model, the main agent must dispatch that role through a separate model or sub-agent call before using its result.
51
-
- Do not satisfy a `Spark` or `Fast` role by completing the role directly in `Primary` and describing it as delegated work.
52
-
- If the assigned model cannot be called because the model or model-selecting tool is unavailable, apply the fallback policy and report which role was not dispatched to its default tier.
52
+
-`Primary` roles belong to the active main agent and must not be delegated to a sub-agent that uses or inherits the active `Primary` model.
53
+
- Every sub-agent created through this role workflow must use either a `Lightweight` or `Fast` model that is different from the active `Primary` model.
54
+
- When a role is assigned to `Lightweight` or `Fast`, the main agent must dispatch the configured custom agent from the routing table before using its result.
55
+
- A sub-agent that inherits the active `Primary` model does not satisfy a `Lightweight` or `Fast` assignment.
56
+
- Do not satisfy a `Lightweight` or `Fast` role by completing the role directly in `Primary` and describing it as delegated work.
57
+
- A generic sub-agent spawn that does not load the configured custom agent TOML does not satisfy the role assignment.
58
+
- If the custom agent cannot be loaded, its pinned model is unavailable, or the dispatch surface cannot select that custom agent, stop before dispatch and report which role cannot run.
53
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.
54
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.
55
61
56
62
### Fallback policy
57
63
58
-
- If `gpt-5.3-codex-spark` is unavailable, assign `Spark` roles to the fastest available read-only capable coding model.
59
-
- If no reliable read-only model is available, assign the role to `Primary`.
64
+
- 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.
60
67
- If `Primary` is unavailable, do not perform implementation, architecture verdict, final integration, git write actions, or GitHub write actions.
61
-
- Do not downgrade `Primary` roles to `Spark` or `Fast` only because a cheaper model is available.
68
+
- Do not downgrade `Primary` roles to `Lightweight` or `Fast` only because a cheaper model is available.
62
69
- 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.
63
70
64
71
### Escalation rule
@@ -116,14 +123,15 @@ Use `Architecture risk: possible` when the task touches module boundaries, impor
116
123
117
124
## Role activation
118
125
119
-
Use this template when assigning work to another AI model or sub-agent.
126
+
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.
120
127
121
128
```md
122
129
You are the `<Role Name>` for the DevLog iOS repository.
123
130
124
131
Read `AGENTS.md` first. Then read `AGENT_ROLES.md` and follow the `<Role Name>` section.
Copy file name to clipboardExpand all lines: AGENT_WORKFLOWS.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,12 +17,12 @@ 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 `AGENT_ROLES.md`.
20
-
6.Dispatch each `Spark` or `Fast` role through a separate model or sub-agent call when tooling can select that assigned model.
21
-
7. Dispatch read-only `Spark` or `Fast` roles in parallel only when they do not depend on unfinished edits.
22
-
8. Do not complete a required `Spark` or `Fast` role directly in `Primary` unless the model or model-selecting tool is unavailable and the fallback policy in `AGENT_ROLES.md` applies.
20
+
6.Keep `Primary` roles with the active main agent, and dispatch every `Lightweight` or `Fast` role through the custom agent mapped in `AGENT_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
23
9. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint.
24
24
10. Integrate role outputs.
25
-
11. Escalate any `Spark` or `Fast` blocker to a `Primary` model before editing.
25
+
11. Escalate any `Lightweight` or `Fast` blocker to a `Primary` model before editing.
26
26
12. Run completion gates.
27
27
13. Report changed files, architecture decision, verification result, delegated roles, model tiers used, and unresolved decisions.
28
28
@@ -35,7 +35,7 @@ Stop and ask the user before editing when:
35
35
- The task packet conflicts with `AGENTS.md`.
36
36
- The requested fix requires relaxing a layer boundary.
37
37
- A role needs to run, launch, install, boot, or open the app or Simulator.
38
-
- A required `Spark` or `Fast`role needs a separate model or sub-agent call, but current tool policy requires user permission that has not been granted.
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.
39
39
- The current issue or PR scope is unclear after live GitHub inspection.
40
40
- Two editing roles would touch the same file.
41
41
- A read-only role reports `Block` or `Needs Owner Decision`.
@@ -239,7 +239,7 @@ Use for PR body, issue text, release note, README wording, review reply draft, o
239
239
### Execution
240
240
241
241
- Documentation Writer must inspect the actual diff before writing PR or release text.
242
-
- When the Documentation Writer role is required and `Spark` is available, the main agent must dispatch the draft to `gpt-5.3-codex-spark` or the configured `Spark` fallback before writing the final response.
242
+
- When the Documentation Writer role is required, the main agent must dispatch the draft through `documentation_writer` before writing the final response.
243
243
- If dispatch requires explicit user permission and it has not been granted, ask before drafting, returning, or posting the Documentation Writer output.
244
244
-`Primary` must review the Documentation Writer output against the template, issue scope, and diff before returning or posting it.
245
245
- Do not write AI workflow documents under `docs/`.
@@ -350,7 +350,7 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s
350
350
- Current owner: repository workflow documentation
0 commit comments