[#727] Codex custom agent를 현재 task 연결형 사이드 작업으로 위임한다

.agents/roles.md

@@ -27,8 +27,8 @@ Use these model tiers when assigning work to another LLM.
 | Tier | Use | Default model |
 | --- | --- | --- |
 | `Primary` | Planning, implementation, architecture decisions, final integration, failed-check triage | Strongest available Codex/GPT coding model |
-| `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 |
-| `Fast` | Low-risk text cleanup, simple file presence checks, short summaries | Fastest available coding model that is different from the active `Primary` model |
+| `Lightweight` | Read-only review, checklist validation, log summarization, documentation draft, first-pass architecture preflight | Pinned non-Primary model from the configured custom agent TOML |
+| `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 |
 
 Default role-to-model and execution assignment:
 
@@ -59,11 +59,32 @@ Do not assign `Lightweight` as the only model for production Swift implementatio
 - 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.
 - `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.
 
+### Connected side-task dispatch
+
+- Run every `Lightweight` or `Fast` role as a side task connected to the current main task.
+- Use `spawn_agent` from tools or `Option-Command-S` from the UI sidebar. Treat both as the same connected dispatch surface.
+- Set `spawn_agent.task_name` to the exact `.codex/agents/<name>.toml` filename without the extension and the exact TOML `name` value.
+- 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.
+- Return each role result to the current main task so `Primary` can review and integrate it.
+- Send later work for the same role to the existing agent with `followup_task` instead of creating another agent name.
+- Do not use external `codex exec` or a separate user-owned `create_thread` as a repository role dispatch surface.
+- Do not count a generic sub-agent that does not select the configured custom agent as a `Lightweight` or `Fast` role execution.
+- 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.
+
+Use these exact role identifiers:
+
+| Role | Exact `task_name` | Configuration |
+| --- | --- | --- |
+| Architecture Watcher | `architecture_watcher` | `.codex/agents/architecture_watcher.toml` |
+| Code Reviewer | `code_reviewer` | `.codex/agents/code_reviewer.toml` |
+| Verification Runner | `verification_runner` | `.codex/agents/verification_runner.toml` |
+| GitHub/CI Analyst | `github_ci_analyst` | `.codex/agents/github_ci_analyst.toml` |
+| Documentation Writer | `documentation_writer` | `.codex/agents/documentation_writer.toml` |
+
 ### Fallback policy
 
-- Choose the best available role-capable lightweight coding model without hardcoding a provider or model name.
-- If the preferred lightweight model is unavailable, choose another available role-capable model that is still different from the active `Primary` model.
-- If no eligible non-Primary model is available, do not fall back to `Primary`; stop and report the unavailable role.
+- The configured custom agent TOML is the source of truth for the non-Primary role model and sandbox.
+- 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.
 - If `Primary` is unavailable, do not perform implementation, architecture verdict, final integration, git write actions, or GitHub write actions.
 - Do not downgrade `Primary` roles to `Lightweight` or `Fast` only because a cheaper model is available.
 - 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
 
 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.
 
+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.
+
 ```md
 You are the `<Role Name>` for the DevLog iOS repository.
 

.agents/workflows.md

@@ -17,14 +17,19 @@ The main agent must run every workflow with this protocol.
 3. Create the task packet.
 4. Assign only the roles required by the selected workflow.
 5. Assign each role a model tier from `.agents/roles.md`.
-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`.
-7. Dispatch read-only `Lightweight` or `Fast` roles in parallel only when they do not depend on unfinished edits.
-8. Do not complete a required `Lightweight` or `Fast` role directly in `Primary`, including when the dispatch tool would inherit the active `Primary` model.
-9. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint.
-10. Integrate role outputs.
-11. Escalate any `Lightweight` or `Fast` blocker to a `Primary` model before editing.
-12. Run completion gates.
-13. Report changed files, architecture decision, verification result, delegated roles, model tiers used, and unresolved decisions.
+6. Keep `Primary` roles with the active main agent.
+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.
+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.
+9. Do not use external `codex exec`, a separate user-owned `create_thread`, or an arbitrary `task_name` for repository role dispatch.
+10. Reuse the existing role agent with `followup_task` when assigning later work to the same role.
+11. Return every delegated role result to the current main task for `Primary` review and integration.
+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.
+13. Dispatch read-only `Lightweight` or `Fast` roles in parallel only when they do not depend on unfinished edits.
+14. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint.
+15. Integrate role outputs.
+16. Escalate any `Lightweight` or `Fast` blocker to a `Primary` model before editing.
+17. Run completion gates.
+18. Report changed files, architecture decision, verification result, delegated roles, model tiers used, and unresolved decisions.
 
 Do not skip the task packet. The task packet is the contract between models.
 
@@ -35,12 +40,14 @@ Stop and ask the user before editing when:
 - The task packet conflicts with `AGENTS.md`.
 - The requested fix requires relaxing a layer boundary.
 - A role needs to run, launch, install, boot, or open the app or Simulator.
-- 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.
+- 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.
 - The current issue or PR scope is unclear after live GitHub inspection.
 - Two editing roles would touch the same file.
 - A read-only role reports `Block` or `Needs Owner Decision`.
 - Verification fails for a reason that suggests a scope or architecture decision.
 
+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.
+
 ## Workflow selection
 
 | User request | Workflow |
@@ -289,7 +296,7 @@ Architecture Watcher is required only if the change modifies architecture policy
 Verification Runner must run:
 
 ```sh
-git diff --check -- AGENTS.md .agents .codex/agents
+git diff --check -- AGENTS.md .agents .codex/agents README.md
 ```
 
 If only Markdown workflow files changed, no iOS build is required.
@@ -310,6 +317,8 @@ Report:
 
 ## Parallel dispatch guide
 
+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.
+
 Parallelize only these combinations:
 
 - 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
 - Architecture risk: none
 - Required roles: Planner, Implementer, Code Reviewer, Verification Runner
 - Model assignment: Planner=Primary, Implementer=Primary, Code Reviewer=code_reviewer (Lightweight), Verification Runner=verification_runner (Lightweight)
+- Custom agent `task_name`: Code Reviewer=`code_reviewer`, Verification Runner=`verification_runner`
+- Result recipient: `Primary` of the current main task
 - Verification: `git diff --check -- AGENTS.md .agents .codex/agents README.md`
 - Stop conditions: README `docs/` asset policy changes, Swift/iOS code changes, request to remove architecture rules immediately
 ```
@@ -371,6 +382,8 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s
 - Architecture risk: none / possible / confirmed
 - Required roles: GitHub/CI Analyst, Planner, Implementer, Code Reviewer, Verification Runner
 - Model assignment: GitHub/CI Analyst=github_ci_analyst (Lightweight), Planner=Primary, Implementer=Primary, Code Reviewer=code_reviewer (Lightweight) -> Primary if blocking, Verification Runner=verification_runner (Lightweight)
+- Custom agent `task_name`: GitHub/CI Analyst=`github_ci_analyst`, Code Reviewer=`code_reviewer`, Verification Runner=`verification_runner`
+- Result recipient: `Primary` of the current main task
 - Verification: changed-file SwiftLint for Swift changes, targeted tests or build-only check when applicable
 - Stop conditions: unresolved thread requires owner decision, fix relaxes architecture boundary, two comments conflict, CI failure source is unrelated to review feedback
 ```

README.md

@@ -264,12 +264,12 @@ flowchart LR
 		Integrator["Final Integration"]
 	end
 
-	subgraph Lightweight["gpt-5.3-codex-spark"]
-		ArchitectureWatcher["Architecture Watcher"]
-		CodeReviewer["Code Reviewer"]
-		VerificationRunner["Verification Runner"]
-		GitHubCIAnalyst["GitHub/CI Analyst"]
-		DocumentationWriter["Documentation Writer"]
+	subgraph ConnectedSideTasks["현재 task 연결형 사이드 작업<br/>사이드바: Option-Command-S<br/>도구: spawn_agent"]
+		ArchitectureWatcher["Architecture Watcher<br/>architecture_watcher"]
+		CodeReviewer["Code Reviewer<br/>code_reviewer"]
+		VerificationRunner["Verification Runner<br/>verification_runner"]
+		GitHubCIAnalyst["GitHub/CI Analyst<br/>github_ci_analyst"]
+		DocumentationWriter["Documentation Writer<br/>documentation_writer"]
 	end
 
 	subgraph Gate["Gate"]
@@ -280,24 +280,24 @@ flowchart LR
 
 	TaskPacket --> Planner
 	Planner --> Implementer
-	Planner --> ArchitectureWatcher
+	Planner -->|"Architecture risk<br/>task_name 선택"| ArchitectureWatcher
 	ArchitectureWatcher -->|Pass| Implementer
 	ArchitectureWatcher -->|Block / Decision| Integrator
 	Implementer --> CodeReviewer
 	CodeReviewer --> ReviewGate
 	ReviewGate --> VerificationRunner
 	VerificationRunner --> VerificationGate
-	GitHubCIAnalyst --> Planner
-	DocumentationWriter --> Integrator
+	GitHubCIAnalyst -->|"현재 task로 결과 반환"| Planner
+	DocumentationWriter -->|"현재 task로 결과 반환"| Integrator
 	VerificationGate --> Integrator
 ```
 
-| 역할 | 모델 | 담당 | 다음 흐름 |
-| --- | --- | --- | --- |
-| Planner | Primary | 이슈, 요청, 변경 범위, role routing 정리 | Implementer / Architecture Watcher |
-| Implementer | Primary | task packet 기준 코드 또는 문서 수정 | Code Reviewer |
-| Architecture Watcher | Lightweight -> Primary | layer, target, dependency, SDK placement, Widget/StorePattern 경계 감시 | Implementer / Final Integration |
-| Code Reviewer | Lightweight -> Primary | diff 기준 버그, 회귀, 테스트 누락, scope drift 검토 | Verification Runner |
-| Verification Runner | gpt-5.3-codex-spark | SwiftLint, test, build-only, docs check 결과 기록 | Final Integration |
-| GitHub/CI Analyst | gpt-5.3-codex-spark | issue, PR thread, review comment, workflow run, CI log 분석 | Planner |
-| Documentation Writer | gpt-5.3-codex-spark | PR 본문, release note, README, issue/comment 문안 작성 | Final Integration |
+| 역할 | 정확한 `task_name` / Custom Agent | 모델 | 담당 | 다음 흐름 |
+| --- | --- | --- | --- | --- |
+| Planner | active main agent | Primary | 이슈, 요청, 변경 범위, role routing 정리 | Implementer / Architecture Watcher |
+| Implementer | active main agent | Primary | task packet 기준 코드 또는 문서 수정 | Code Reviewer |
+| Architecture Watcher | `architecture_watcher` | `gpt-5.3-codex-spark` (`Lightweight`) -> Primary | layer, target, dependency, SDK placement, Widget/StorePattern 경계 감시 | Implementer / Final Integration |
+| Code Reviewer | `code_reviewer` | `gpt-5.3-codex-spark` (`Lightweight`) -> Primary | diff 기준 버그, 회귀, 테스트 누락, scope drift 검토 | Verification Runner |
+| Verification Runner | `verification_runner` | `gpt-5.3-codex-spark` (`Lightweight`) | SwiftLint, test, build-only, docs check 결과 기록 | Final Integration |
+| GitHub/CI Analyst | `github_ci_analyst` | `gpt-5.3-codex-spark` (`Lightweight`) | issue, PR thread, review comment, workflow run, CI log 분석 | Planner |
+| Documentation Writer | `documentation_writer` | `gpt-5.3-codex-spark` (`Lightweight`) | PR 본문, release note, README, issue/comment 문안 작성 | Final Integration |