diff --git a/.agents/roles.md b/.agents/roles.md index f28a02c2..9d5ff320 100644 --- a/.agents/roles.md +++ b/.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/.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 `` for the DevLog iOS repository. diff --git a/.agents/workflows.md b/.agents/workflows.md index 5c1a62af..786f8268 100644 --- a/.agents/workflows.md +++ b/.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/.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 ``` diff --git a/README.md b/README.md index 07de8e2a..9a2cf199 100644 --- a/README.md +++ b/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 연결형 사이드 작업
사이드바: Option-Command-S
도구: spawn_agent"] + ArchitectureWatcher["Architecture Watcher
architecture_watcher"] + CodeReviewer["Code Reviewer
code_reviewer"] + VerificationRunner["Verification Runner
verification_runner"] + GitHubCIAnalyst["GitHub/CI Analyst
github_ci_analyst"] + DocumentationWriter["Documentation Writer
documentation_writer"] end subgraph Gate["Gate"] @@ -280,24 +280,24 @@ flowchart LR TaskPacket --> Planner Planner --> Implementer - Planner --> ArchitectureWatcher + Planner -->|"Architecture risk
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 |