diff --git a/.agents/roles.md b/.agents/roles.md index fa5fb32d..b8839fd9 100644 --- a/.agents/roles.md +++ b/.agents/roles.md @@ -4,7 +4,7 @@ This file defines the runnable AI role workflow for DevLog work. -It is not background documentation. Use it to split work across AI models, pass task packets between roles, and decide which review or verification gates must run before completion. +It is not background documentation. Use it to split work across AI models, create and approve Specs, pass task packets between roles, and decide which review or verification gates must run before completion. Use `.agents/workflows.md` for task-specific runbooks that combine these roles into executable workflows. @@ -19,6 +19,8 @@ Use `.agents/workflows.md` for task-specific runbooks that combine these roles i - Build-only verification is allowed. Do not run, launch, install, boot, or open the app or Simulator unless the user explicitly requests it in the current turn. - Keep generated Xcode workspace/project and `Package.resolved` churn out of source control unless an approved dependency-lock policy requires it. - Keep AI workflow and rule documents under `.agents/`. Do not put them under `docs/`. +- For non-trivial design or implementation work, do not dispatch `Implementer`, `Code Reviewer`, or `Verification Runner` before the user approves a `Designer Result` and the Planner persists its Spec under `.agents/specs/`. +- If implementation changes a requirement or scope, update the Spec and obtain user approval again before continuing. ## Model assignment @@ -27,6 +29,7 @@ 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 | +| `SDD Gate` | Design analysis and final diff review | `gpt-5.6-sol` with `xhigh` reasoning | | `Lightweight` | Read-only review, checklist validation, log summarization, documentation draft, first-pass architecture preflight | `gpt-5.3-codex-spark`, unavailable 시 `gpt-5.6-luna`와 `high` 추론 | | `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 | @@ -35,14 +38,15 @@ Default role-to-model and execution assignment: | Role | Execution owner or custom agent | Default tier | Escalate to `Primary` when | | --- | --- | --- | --- | | Planner | active main agent | `Primary` | Always for live issues, PR scope, architecture scope, or implementation planning | +| Designer | `designer` | `SDD Gate` | Any unresolved constraint, alternative, scope boundary, acceptance criterion, verification method, commit unit, or user approval | | Implementer | active main agent | `Primary` | Always for Swift production code, tests, target dependencies, DI, SDK placement, or GitHub writes | | 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 | -| Code Reviewer | `code_reviewer` | `Lightweight` for first pass, `Primary` for final blocking review | Findings involve runtime behavior, concurrency, data loss, architecture, or test strategy | +| Code Reviewer | `code_reviewer` | `SDD Gate` | Any finding that blocks Spec acceptance criteria or requires user decision | | Verification Runner | `verification_runner` | `Lightweight` | Verification fails, failure cause is unclear, or a fix is needed | | GitHub/CI Analyst | `github_ci_analyst` | `Lightweight` | CI root cause requires code or workflow changes, or review comments conflict | | Documentation Writer | `documentation_writer` | `Lightweight` | Text must explain complex architecture, release risk, CI root cause, or PR scope tradeoffs | -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. +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. `Designer` and `Code Reviewer` are Sol-only SDD gates; the other custom roles retain the existing Spark-first routing. 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. @@ -50,44 +54,46 @@ Do not assign `Lightweight` as the only model for production Swift implementatio - A model tier assignment is an execution requirement, not a label for work the main agent already performed. - `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. -- Every sub-agent created through this role workflow must use either a `Lightweight` or `Fast` model that is different from the active `Primary` model. -- 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. -- A sub-agent that inherits the active `Primary` model does not satisfy a `Lightweight` or `Fast` assignment. -- Do not satisfy a `Lightweight` or `Fast` role by completing the role directly in `Primary` and describing it as delegated work. -- A generic sub-agent spawn that does not load the configured custom agent TOML does not satisfy the role assignment. +- Every sub-agent created through this role workflow must use the configured `SDD Gate`, `Lightweight`, or `Fast` model that is different from the active `Primary` model. The exact `designer` and `code_reviewer` custom agent dispatches are the only exception when the active `Primary` also uses their required Sol model. +- When a role is assigned to `SDD Gate`, `Lightweight`, or `Fast`, the main agent must dispatch the configured custom agent from the routing table before using its result. +- A sub-agent that inherits the active `Primary` model does not satisfy an `SDD Gate`, `Lightweight`, or `Fast` assignment. The Sol exception applies only to the exact `designer` and `code_reviewer` custom agent dispatches; it does not permit an inherited or generic sub-agent. +- Do not satisfy an `SDD Gate`, `Lightweight`, or `Fast` role by completing the role directly in `Primary` and describing it as delegated work. +- A generic sub-agent spawn that does not load the configured custom agent TOML does not satisfy an `SDD Gate`, `Lightweight`, or `Fast` role execution. - If the custom agent cannot be loaded or the dispatch surface cannot select that custom agent, stop before dispatch and report which role cannot run. +- `Designer` and `Code Reviewer` must use only `gpt-5.6-sol` with `xhigh` reasoning. If the connected side-task surface cannot select Sol after an exact `task_name` retry, stop the SDD gate; do not use a fallback. - A configured `gpt-5.3-codex-spark` model is unavailable only when the connected side-task surface cannot select it after an exact `task_name` retry. In that case, dispatch the matching `*_luna` custom role with `gpt-5.6-luna` and `high` reasoning effort. Do not select another fallback model. - 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. +- Run every `SDD Gate`, `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 count a generic sub-agent that does not select the configured custom agent as an `SDD Gate`, `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 | | --- | --- | --- | +| Designer | `designer` | `.codex/agents/designer.toml` | | 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` | -Spark fallback custom agents use the same role suffix with `_luna`: `architecture_watcher_luna`, `code_reviewer_luna`, `verification_runner_luna`, `github_ci_analyst_luna`, and `documentation_writer_luna`. +Spark fallback custom agents use the same role suffix with `_luna`: `architecture_watcher_luna`, `verification_runner_luna`, `github_ci_analyst_luna`, and `documentation_writer_luna`. `Designer` and `Code Reviewer` have no Luna fallback. ### Fallback policy - The configured custom agent TOML is the source of truth for the non-Primary role model and sandbox. -- The configured custom agent TOML keeps `gpt-5.3-codex-spark` as the default non-Primary model. If Spark is unavailable, use only the matching `*_luna` custom agent with `gpt-5.6-luna` and `high` reasoning effort, preserving the same sandbox and developer instructions. +- The configured custom agent TOML keeps `gpt-5.3-codex-spark` as the default model for existing Lightweight roles. If Spark is unavailable, use only the matching `*_luna` custom agent with `gpt-5.6-luna` and `high` reasoning effort, preserving the same sandbox and developer instructions. - If `gpt-5.6-luna` with `high` reasoning effort is also 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. @@ -112,13 +118,15 @@ Escalation does not mean the `Primary` model should automatically edit. It must Use this sequence for non-trivial AI-assisted work. -1. Planner creates a task packet. -2. Implementer edits only the assigned scope. -3. Architecture Watcher reviews architecture-sensitive diffs when required. -4. Code Reviewer reviews the final diff for bugs, regressions, and missing tests. -5. Verification Runner runs allowed checks and records the result. -6. Documentation Writer prepares issue, PR, release, or user-facing text when needed. -7. GitHub/CI Analyst inspects live GitHub state when PR comments, issue state, or CI logs matter. +1. Planner creates a `Design Brief`. +2. Designer returns a `Designer Result`; the user approves it. +3. Planner persists the approved Spec and creates a `Task Packet` from it. +4. Implementer edits only the assigned scope. +5. Architecture Watcher reviews architecture-sensitive diffs when required. +6. Code Reviewer reviews the final diff against the approved Spec for bugs, regressions, and missing acceptance criteria. +7. Verification Runner records acceptance-criterion evidence and runs allowed checks. +8. Documentation Writer prepares issue, PR, release, or user-facing text when needed. +9. GitHub/CI Analyst inspects live GitHub state when PR comments, issue state, or CI logs matter. Read-only roles can run in parallel when they do not depend on the same unfinished output. Editing roles should run sequentially unless their assigned files and ownership boundaries are disjoint. @@ -132,23 +140,26 @@ Planner must produce this packet before handing work to another role. ## Task Packet - Source: +- Approved Spec: - Goal: - Scope: - Out of scope: +- Acceptance criteria: - Expected changed files: - Current owner: - Architecture risk: none / possible / confirmed - Required roles: - Model assignment: +- Execution authority: app or Simulator / external writes / CI or PR actions - Verification: - Stop conditions: ``` -Use `Architecture risk: possible` when the task touches module boundaries, imports, target dependencies, DI, repository or service contracts, Widget flow, `ThirdParty` package linkage, StorePattern boundaries, or architecture documentation. +Use `Architecture risk: possible` when the task touches module boundaries, imports, target dependencies, DI, repository or service contracts, Widget flow, `ThirdParty` package linkage, StorePattern boundaries, or architecture documentation. The `Approved Spec` field must be a `.agents/specs/` path for non-trivial work, and `Acceptance criteria` must reproduce only the approved Spec criteria needed for execution and verification. ## Role activation -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. +Use this template when assigning an `SDD Gate`, `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. @@ -157,7 +168,7 @@ You are the `` for the DevLog iOS repository. Read `AGENTS.md` first. Then read `.agents/roles.md` and follow the `` section. -Assigned model tier: `` +Assigned model tier: `` Custom agent: `` Task packet: @@ -178,17 +189,17 @@ The receiving model must start by identifying its active role and must end with | Task type | Required roles | Notes | | --- | --- | --- | -| Issue planning | Planner | Add GitHub/CI Analyst when live issue or PR state is the source of truth. | -| Swift implementation | Planner, Implementer, Code Reviewer, Verification Runner | Add Architecture Watcher when boundary or dependency risk exists. | -| Module, DI, SDK, Widget, StorePattern, or architecture docs | Planner, Architecture Watcher, Implementer, Code Reviewer, Verification Runner | Architecture Watcher must read `AGENTS.md`, `README.md`, and `.agents/rules/architecture.md`. | -| Review feedback | GitHub/CI Analyst, Planner, Implementer, Code Reviewer, Verification Runner | Use thread-aware review inspection when unresolved review threads matter. | -| CI failure | GitHub/CI Analyst, Planner, Verification Runner | Add Implementer only after the failure source is identified. | +| Issue planning | Planner, Designer | Add GitHub/CI Analyst when live issue or PR state is the source of truth. | +| Swift implementation | Planner, Designer, Implementer, Code Reviewer, Verification Runner | Add Architecture Watcher when boundary or dependency risk exists. | +| Module, DI, SDK, Widget, StorePattern, or architecture docs | Planner, Designer, Architecture Watcher, Implementer, Code Reviewer, Verification Runner | Architecture Watcher must read `AGENTS.md`, `README.md`, and `.agents/rules/architecture.md`. | +| Review feedback | GitHub/CI Analyst, Planner, Designer, Implementer, Code Reviewer, Verification Runner | Use thread-aware review inspection when unresolved review threads matter. | +| CI failure | GitHub/CI Analyst, Planner, Designer, Verification Runner | Add Implementer only after a user-approved Spec identifies a concrete root cause. | | PR or release text | Documentation Writer | Add Code Reviewer when text must match actual diff. | -| Docs-only AI workflow change | Planner, Implementer, Code Reviewer, Verification Runner | No iOS build required unless Swift/iOS project code changes. | +| Docs-only AI workflow change | Planner, Designer, Implementer, Code Reviewer, Verification Runner | No iOS build required unless Swift/iOS project code changes. | ## Planner -Planner converts the user request, issue, or PR state into a scoped task packet. +Planner converts the user request, issue, or PR state into a `Design Brief`. After user approval of the `Designer Result` and Spec persistence, Planner converts only that Spec into a scoped `Task Packet`. May: @@ -196,10 +207,12 @@ May: - Identify likely owning layer, target, and files. - Decide which roles are required. - Ask the user when scope, ownership, or architecture decisions are ambiguous. +- Persist an approved Spec under `.agents/specs/` before fixing the `Task Packet` for non-trivial work. Must not: - Edit implementation files. +- Confirm a `Task Packet` before an approved Spec exists for non-trivial work. - Relax architecture rules to make a task easier. - Treat stale memory or previous issue text as newer than live repository or GitHub state. @@ -212,10 +225,44 @@ Output: - Scope: - Out of scope: - Required roles: +- Design Brief: +- Approved Spec: - Handoff packet: - User decision needed: ``` +## Designer + +Designer is the `gpt-5.6-sol` and `xhigh` SDD gate for non-trivial work. + +May: + +- Analyze a `Design Brief`, the current repository state, and live issue or PR context provided by the Planner. +- Identify constraints, alternatives, changed boundaries, acceptance criteria, verification methods, and independently reviewable minimum commit units. +- Return a `Designer Result` that the user can approve as the basis for a Spec. + +Must not: + +- Edit files, stage changes, commit, push, or change GitHub state. +- Approve its own result on behalf of the user. +- Select a fallback model when Sol is unavailable. + +Output: + +```md +## Designer Result + +- Design Brief: +- Constraints: +- Alternatives: +- Changed boundaries: +- Acceptance criteria: +- Verification: +- Minimum commit units: +- Spec path: +- User approval needed: +``` + ## Implementer Implementer applies the scoped code or document change. @@ -223,12 +270,14 @@ Implementer applies the scoped code or document change. May: - Edit files in the task packet. +- Use the approved Spec and its acceptance criteria as the implementation boundary. - Add narrowly scoped helper types or tests when required by the task. - Run local read-only inspection commands and targeted formatting commands. Must not: - Expand scope beyond the task packet. +- Continue after a requirement or scope change without updating the Spec and obtaining user approval. - Change app logic unless the new approach preserves results and strictly improves time or space complexity, or the user explicitly requested the logic change. - Add or loosen module dependencies without an Architecture Watcher pass. - Run, launch, install, boot, or open the app or Simulator. @@ -295,13 +344,13 @@ Output: ## Code Reviewer -Code Reviewer is a read-only diff reviewer. +Code Reviewer is the `gpt-5.6-sol` and `xhigh` read-only final-diff SDD gate. May: - Inspect `git diff`, changed files, and related tests. - Prioritize bugs, regressions, architecture drift, readability problems, and missing tests. -- Verify whether the change matches the task packet and issue body. +- Verify whether the change matches the approved Spec, its acceptance criteria, and the task packet. Must not: @@ -316,6 +365,7 @@ Output findings first: - Verdict: Pass / Block / Needs Follow-up - Findings: +- Spec path and acceptance criteria: - Missing tests or verification: - Scope drift: ``` @@ -332,6 +382,7 @@ May: - Run unit tests when they do not launch the app. - Run `xcodebuild build` or equivalent build-only checks. - Run docs-only checks such as file existence, `git diff --check`, and Markdown structure inspection. +- Record evidence for every Spec acceptance criterion. Must not: @@ -347,6 +398,7 @@ Output: - Status: Pass / Fail / Not Run - Commands: +- Spec path and acceptance criteria evidence: - Evidence: - Not run: - Failure notes: @@ -415,6 +467,7 @@ Output: Before reporting completion: - Confirm the diff only touches the assigned scope. +- Confirm the approved Spec path and every acceptance criterion are referenced by the task packet, code review, and verification result. - Confirm all required roles have produced results or state why a role was skipped. - Confirm Swift changes received the required lint, test, or build-only verification. - Confirm docs-only changes were checked without claiming app build verification. @@ -424,26 +477,32 @@ Before reporting completion: ### Docs-only AI workflow change -1. Planner creates a task packet from the issue. -2. Implementer edits `AGENTS.md` and `.agents/roles.md`. -3. Code Reviewer checks whether the workflow is executable and scoped. -4. Verification Runner runs `git diff --check` and file-presence checks. -5. Main agent reports changed files, architecture boundary decision, and verification result. +1. Planner creates a `Design Brief` from the issue. +2. Designer returns a `Designer Result`; the user approves it. +3. Planner persists the approved Spec and creates a task packet from it. +4. Implementer edits the assigned workflow files. +5. Code Reviewer checks the Spec, task packet, and final diff. +6. Verification Runner records evidence for every acceptance criterion. +7. Main agent reports changed files, architecture boundary decision, and verification result. ### Swift bug fix -1. Planner reads the issue and identifies owner layer and files. -2. Architecture Watcher runs if imports, dependencies, DI, Widget, SDK placement, or StorePattern ownership might change. -3. Implementer applies the focused fix. -4. Code Reviewer reviews the diff for regressions and missing tests. -5. Verification Runner runs changed-file SwiftLint and build-only or test checks. +1. Planner creates a `Design Brief` from the issue. +2. Designer returns a `Designer Result`; the user approves it. +3. Planner persists the approved Spec and creates a `Task Packet` from it. +4. Architecture Watcher runs if imports, dependencies, DI, Widget, SDK placement, or StorePattern ownership might change. +5. Implementer applies the focused fix. +6. Code Reviewer reviews the Spec, task packet, and final diff. +7. Verification Runner records acceptance-criterion evidence and runs changed-file SwiftLint and build-only or test checks. ### Review-thread follow-up 1. GitHub/CI Analyst reads unresolved review threads. -2. Planner separates required changes from optional suggestions. -3. Implementer applies only accepted fixes. -4. Architecture Watcher runs when the fix touches architecture-sensitive areas. -5. Code Reviewer checks the final diff. -6. Verification Runner runs allowed checks. -7. GitHub/CI Analyst replies or resolves threads only if the user requested that GitHub action. +2. Planner creates a `Design Brief` that separates required changes from optional suggestions. +3. Designer returns a `Designer Result`; the user approves it. +4. Planner persists the approved Spec and creates a `Task Packet` from it. +5. Implementer applies only accepted fixes. +6. Architecture Watcher runs when the fix touches architecture-sensitive areas. +7. Code Reviewer checks the Spec, task packet, and final diff. +8. Verification Runner records acceptance-criterion evidence and runs allowed checks. +9. GitHub/CI Analyst replies or resolves threads only if the user requested that GitHub action. diff --git a/.agents/rules/general.md b/.agents/rules/general.md index ce93a526..7c5ff991 100644 --- a/.agents/rules/general.md +++ b/.agents/rules/general.md @@ -21,6 +21,7 @@ ## Documentation placement - Keep AI workflow and rule documents under `.agents/`. +- Keep approved workflow Specs under `.agents/specs/`. - Keep `docs/` for README images and draw.io sources. - Do not add AI workflow documents under `docs/`. diff --git a/.agents/rules/project-workflows.md b/.agents/rules/project-workflows.md index 40a3d6f7..e43718f0 100644 --- a/.agents/rules/project-workflows.md +++ b/.agents/rules/project-workflows.md @@ -21,6 +21,12 @@ This reference holds DevLog-specific working rules that should live with the pro - CI is build validation, not a full test run, unless the workflow changes. - Avoid unrelated generated project and `Package.resolved` churn. Generated Xcode workspace/project files should not be tracked unless the project explicitly changes that policy. +## SDD execution authority + +- An approved Spec records behavioral constraints, acceptance criteria, and prohibited actions. +- A `Task Packet` records role assignment and current-turn execution authority separately from the Spec. +- Record app or Simulator execution, external writes, CI or PR actions, and verification commands separately in both artifacts. Do not infer authorization from a Spec or a `Task Packet` field that does not grant it. + ## Xcode project file work - Inspect Swift imports and Tuist target dependencies together. diff --git a/.agents/specs/823-pr-826-review-follow-up.md b/.agents/specs/823-pr-826-review-follow-up.md new file mode 100644 index 00000000..30e1007f --- /dev/null +++ b/.agents/specs/823-pr-826-review-follow-up.md @@ -0,0 +1,50 @@ +# PR #826 Review Follow-up + +- Source: https://github.com/opficdev/DevLog_iOS/pull/826 +- Approved Designer Result: PR #826의 수용된 review thread 4개에 대한 `Designer Result` +- User approval: 네 review thread 전체 수용, 개별 커밋, push, `반영 {커밋번호}` 답글, resolve 승인 + +## Constraints + +- `Designer`와 `Code Reviewer`의 `gpt-5.6-sol`, `xhigh`, 정확한 `task_name` 유지 +- 기존 `Lightweight` 역할의 Spark 우선 및 Luna 대체 정책 유지 +- 앱 코드, Swift 테스트, Tuist, CI 동작, QALenz, app 또는 Simulator 실행 제외 + +## Alternatives and decision + +- 활성 `Primary`가 Sol일 때 SDD Gate 생략 또는 다른 모델 대체 방안 제외 +- Sol 동일 모델 허용을 정확한 `designer`, `code_reviewer` custom agent dispatch로 한정 +- 단순 작업의 SDD 절차 강제 방안 제외 + +## Changed boundaries + +- `.agents/roles.md`의 Sol `Primary`와 Sol 전용 SDD Gate 공존 규칙 +- `.agents/workflows.md`의 비단순 작업 전용 SDD 흐름 +- `.agents/specs/README.md`의 이슈 없는 Spec 이름 +- `README.md`의 SDD 역할 흐름과 모델 안내 + +## Acceptance criteria + +- [ ] Sol `Primary`에서도 정확한 `designer`, `code_reviewer` SDD Gate dispatch 허용 +- [ ] 단순 작업의 `Task Packet` 경로와 비단순 작업의 SDD 흐름 분리 +- [ ] 이슈 없는 요청의 Spec 이름 규칙 정의 +- [ ] `README.md`의 흐름과 역할 표를 현재 SDD 규칙과 동기화 +- [ ] 스레드별 독립 커밋, push, `반영 {커밋번호}` 답글, resolve 완료 + +## Verification + +- Command: `git diff --check -- AGENTS.md .agents .codex/agents README.md` +- Evidence: 역할·모델·정확한 `task_name` 점검, Mermaid 흐름 대조, GraphQL `reviewThreads` 상태 확인 + +## Minimum commit units + +1. Sol `Primary`와 SDD Gate 공존 규칙 +2. 비단순 작업 전용 SDD protocol +3. 이슈 없는 Spec 이름 규칙 +4. `README.md` SDD 흐름과 역할 표 동기화 + +## Execution constraints + +- app or Simulator execution: 금지 +- External writes: git commit, push, 승인된 review reply와 resolve만 허용 +- CI or PR actions: PR 생성 또는 병합 금지 diff --git a/.agents/specs/README.md b/.agents/specs/README.md new file mode 100644 index 00000000..0f9cc1c4 --- /dev/null +++ b/.agents/specs/README.md @@ -0,0 +1,56 @@ +# DevLog Spec Format + +`Designer Result`를 사용자가 승인한 뒤, Planner가 비단순 설계 또는 구현 작업마다 이 디렉터리에 Spec을 작성한다. 이슈 기반 작업은 `-.md`, 이슈 없는 사용자 요청은 `user--.md` 형식을 사용한다. + +## Responsibility + +- `Design Brief`는 Planner가 요청, 현재 상태, 범위, 제외 범위, 알려진 제약을 Designer에게 전달하는 입력이다. +- `Designer Result`는 Designer가 제약, 대안, 변경 경계, 수용 기준, 검증, 최소 커밋 단위를 분석한 승인 대기 결과다. +- Spec은 사용자가 승인한 `Designer Result`를 영속화한 구현·검토·검증의 공통 기준이다. +- `Task Packet`은 승인된 Spec 경로와 수용 기준을 참조하고, 현재 작업의 역할 배정과 실행 권한을 전달한다. + +## Required format + +```md +# + +- Source: +- Approved Designer Result: +- User approval: + +## Constraints + +- + +## Alternatives and decision + +- + +## Changed boundaries + +- + +## Acceptance criteria + +- [ ] + +## Verification + +- Command: +- Evidence: + +## Minimum commit units + +1. + +## Execution constraints + +- app or Simulator execution: +- External writes: +- CI or PR actions: +``` + +## Change control + +- 구현 중 요구 사항 또는 범위가 바뀌면 Spec을 수정하고 사용자 재승인을 받은 뒤에만 `Task Packet`과 구현을 갱신한다. +- Spec은 동작과 수용 기준, 금지된 실행을 기록한다. `Task Packet`은 역할별 현재 작업 권한과 실제 검증 명령을 별도로 기록한다. diff --git a/.agents/workflows.md b/.agents/workflows.md index 215121a3..95cd5ceb 100644 --- a/.agents/workflows.md +++ b/.agents/workflows.md @@ -14,22 +14,27 @@ The main agent must run every workflow with this protocol. 1. Read `AGENTS.md`, then `.agents/roles.md`, then this file. 2. Select one workflow from this file. -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. -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. +3. Classify the work as simple or non-trivial. +4. For non-trivial work, have Planner create a `Design Brief`. +5. For non-trivial work, dispatch `Designer` and obtain its `Designer Result`. +6. For non-trivial work, obtain user approval, then persist the approved result as a Spec under `.agents/specs/`. +7. For non-trivial work, have Planner create a `Task Packet` from only the approved Spec. +8. For simple work, have Planner create a `Task Packet` directly from the request and record its scope and execution authority. +9. Assign only the roles required by the selected workflow. +10. Assign each role a model tier from `.agents/roles.md`. +11. Keep `Primary` roles with the active main agent. +12. Find the exact custom agent name in `.agents/roles.md` and its matching `.codex/agents/.toml` before dispatching an `SDD Gate`, `Lightweight`, or `Fast` role. +13. 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. +14. Do not use external `codex exec`, a separate user-owned `create_thread`, or an arbitrary `task_name` for repository role dispatch. +15. Reuse the existing role agent with `followup_task` when assigning later work to the same role. +16. Return every delegated role result to the current main task for `Primary` review and integration. +17. Do not complete a required `SDD Gate`, `Lightweight`, or `Fast` role directly in `Primary`, and do not substitute a generic sub-agent for the configured custom agent. +18. Dispatch read-only `SDD Gate`, `Lightweight`, or `Fast` roles in parallel only when they do not depend on unfinished edits. +19. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint. +20. Integrate role outputs. +21. Escalate any `SDD Gate`, `Lightweight`, or `Fast` blocker to a `Primary` model before editing. +22. Run completion gates. +23. Report changed files, Spec path, acceptance-criterion evidence, 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. @@ -38,9 +43,11 @@ Do not skip the task packet. The task packet is the contract between models. Stop and ask the user before editing when: - The task packet conflicts with `AGENTS.md`. +- A non-trivial task lacks an approved Spec or its `Task Packet` does not cite the Spec path and acceptance criteria. +- A requirement or scope change needs a Spec update and user reapproval. - 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 through the connected side-task surface with its exact `task_name`, the matching `*_luna` fallback cannot be selected after Spark is unavailable, or current tool policy requires user permission that has not been granted. +- A required `SDD Gate`, `Lightweight`, or `Fast` custom agent cannot be loaded or selected through the connected side-task surface with its exact `task_name`, the matching `*_luna` fallback cannot be selected after Spark 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`. @@ -66,12 +73,14 @@ Use when implementing a live issue or user-scoped code change. ### Role order 1. GitHub/CI Analyst, if live issue or PR state matters. -2. Planner. -3. Architecture Watcher, if `Architecture risk` is `possible` or `confirmed`. -4. Implementer. -5. Code Reviewer. -6. Verification Runner. -7. Documentation Writer, if PR, release, or issue text is needed. +2. Planner creates a `Design Brief`. +3. Designer returns a `Designer Result`; the user approves it. +4. Planner persists the approved Spec and creates a `Task Packet` from it. +5. Architecture Watcher, if `Architecture risk` is `possible` or `confirmed`. +6. Implementer. +7. Code Reviewer. +8. Verification Runner. +9. Documentation Writer, if PR, release, or issue text is needed. ### Task packet source @@ -79,24 +88,28 @@ Use when implementing a live issue or user-scoped code change. ## Task Packet - Source: +- Approved Spec: <.agents/specs/... path> - Goal: - Scope: - Out of scope: +- Acceptance criteria: - Expected changed files: - Current owner: - Architecture risk: none / possible / confirmed - Required roles: - Model assignment: +- Execution authority: app or Simulator / external writes / CI or PR actions - Verification: - Stop conditions: ``` ### Execution +- Planner must not create a `Task Packet` before the user approves the `Designer Result` and its Spec is persisted. - Planner must identify the owning layer and target before Implementer edits Swift code. - Implementer must edit only files listed in the task packet unless Planner updates the packet. -- Code Reviewer must check scope drift before style concerns. -- Verification Runner must run changed-file SwiftLint for Swift changes and build-only checks when applicable. +- Code Reviewer must check Spec acceptance-criterion coverage and scope drift before style concerns. +- Verification Runner must record evidence for every Spec acceptance criterion, then run changed-file SwiftLint for Swift changes and build-only checks when applicable. ### Completion @@ -106,6 +119,7 @@ Report: ## Workflow Result - Workflow: Issue-driven implementation +- Approved Spec: - Changed files: - Architecture decision: - Verification: @@ -118,12 +132,14 @@ Use when the task touches module boundaries, file ownership, layer dependencies, ### Role order -1. Planner. -2. Architecture Watcher before editing. -3. Implementer, only after Architecture Watcher returns `Pass`. -4. Architecture Watcher after editing, if imports, target dependencies, or ownership changed. -5. Code Reviewer. -6. Verification Runner. +1. Planner creates a `Design Brief`. +2. Designer returns a `Designer Result`; the user approves it. +3. Planner persists the approved Spec and creates a `Task Packet` from it. +4. Architecture Watcher before editing. +5. Implementer, only after Architecture Watcher returns `Pass`. +6. Architecture Watcher after editing, if imports, target dependencies, or ownership changed. +7. Code Reviewer. +8. Verification Runner. ### Architecture Watcher gate @@ -153,6 +169,7 @@ Report: ## Workflow Result - Workflow: Architecture-sensitive implementation +- Approved Spec: - Architecture Watcher verdict: - Changed files: - Boundary decision: @@ -167,19 +184,21 @@ Use when the user asks to address PR review comments or unresolved review thread ### Role order 1. GitHub/CI Analyst. -2. Planner. -3. Architecture Watcher, if a requested fix touches architecture-sensitive areas. -4. Implementer. -5. Code Reviewer. -6. Verification Runner. -7. GitHub/CI Analyst, only if the user requested replies or thread resolution. +2. Planner creates a `Design Brief`. +3. Designer returns a `Designer Result`; the user approves it. +4. Planner persists the approved Spec and creates a `Task Packet` from it. +5. Architecture Watcher, if a requested fix touches architecture-sensitive areas. +6. Implementer. +7. Code Reviewer. +8. Verification Runner. +9. GitHub/CI Analyst, only if the user requested replies or thread resolution. ### Execution - GitHub/CI Analyst must use thread-aware inspection when unresolved review threads matter. -- Planner must classify each comment as required, optional, already handled, or rejected. +- Planner must classify each comment as required, optional, already handled, or rejected in the `Design Brief`. - Implementer must apply only accepted fixes. -- Code Reviewer must verify that the final diff addresses the accepted comments without unrelated cleanup. +- Code Reviewer must verify that the final diff addresses the approved Spec and accepted comments without unrelated cleanup. - GitHub/CI Analyst must mirror the existing PR reply style when replying. ### Completion @@ -190,6 +209,7 @@ Report: ## Workflow Result - Workflow: Review-thread follow-up +- Approved Spec: - Addressed comments: - Deferred or rejected comments: - Changed files: @@ -204,11 +224,13 @@ Use when GitHub Actions, merge-risk-watch, release, TestFlight, App Store, or PR ### Role order 1. GitHub/CI Analyst. -2. Planner. -3. Verification Runner, if a local reproduction is possible without launching the app. -4. Implementer, only after a concrete root cause is identified. -5. Code Reviewer. -6. Verification Runner. +2. Planner creates a `Design Brief`. +3. Designer returns a `Designer Result`; the user approves it. +4. Planner persists the approved Spec and creates a `Task Packet` from it. +5. Verification Runner, if a local reproduction is possible without launching the app. +6. Implementer, only after a concrete root cause is identified in the approved Spec. +7. Code Reviewer. +8. Verification Runner. ### Execution @@ -225,6 +247,7 @@ Report: ## Workflow Result - Workflow: CI failure triage +- Approved Spec: - Failing run: - Root cause: - Changed files: @@ -238,14 +261,17 @@ Use for PR body, issue text, release note, README wording, review reply draft, o ### Role order -1. Documentation Writer. -2. Code Reviewer, if wording must match a diff. -3. GitHub/CI Analyst, if live issue, PR, or release state matters. -4. Verification Runner, for file presence and Markdown checks when files changed. +1. Planner and Designer, when the documentation change is non-trivial. +2. User approval and Spec persistence, when a Designer Result is required. +3. Documentation Writer. +4. Code Reviewer, if wording must match a diff. +5. GitHub/CI Analyst, if live issue, PR, or release state matters. +6. Verification Runner, for file presence and Markdown checks when files changed. ### Execution - Documentation Writer must inspect the actual diff before writing PR or release text. +- For non-trivial documentation changes, Documentation Writer must use the approved Spec and task packet scope. - When the Documentation Writer role is required, the main agent must dispatch the draft through `documentation_writer` before writing the final response. - If dispatch requires explicit user permission and it has not been granted, ask before drafting, returning, or posting the Documentation Writer output. - `Primary` must review the Documentation Writer output against the template, issue scope, and diff before returning or posting it. @@ -273,10 +299,12 @@ Use for `AGENTS.md`, `.agents/roles.md`, this file, `.agents/rules`, or AI role ### Role order -1. Planner. -2. Implementer. -3. Code Reviewer. -4. Verification Runner. +1. Planner creates a `Design Brief`. +2. Designer returns a `Designer Result`; the user approves it. +3. Planner persists the approved Spec and creates a `Task Packet` from it. +4. Implementer. +5. Code Reviewer. +6. Verification Runner. Architecture Watcher is required only if the change modifies architecture policy, layer maps, ambiguity gates, or architecture rules. @@ -290,16 +318,31 @@ Architecture Watcher is required only if the change modifies architecture policy - `.agents/rules/general.md` should define general logic preservation, response style, and Swift coding rules. - `.agents/rules/architecture.md` should define detailed architecture boundaries and ambiguity gates. - `.agents/rules/project-workflows.md` should define project-specific verification and delivery rules. +- `.agents/specs/` should define the approved Spec format and change-control rule. ### Verification Verification Runner must run: ```sh -git diff --check -- AGENTS.md .agents .codex/agents README.md +git diff --check -- AGENTS.md .agents .codex/agents +``` + +Verification Runner must also confirm the configured role names, model assignments, and fallback files: + +```sh +test -f .codex/agents/designer.toml +test ! -e .codex/agents/designer_luna.toml +test ! -e .codex/agents/code_reviewer_luna.toml +rg -qx 'name = "designer"' .codex/agents/designer.toml +rg -qx 'model = "gpt-5.6-sol"' .codex/agents/designer.toml +rg -qx 'model_reasoning_effort = "xhigh"' .codex/agents/designer.toml +rg -qx 'name = "code_reviewer"' .codex/agents/code_reviewer.toml +rg -qx 'model = "gpt-5.6-sol"' .codex/agents/code_reviewer.toml +rg -qx 'model_reasoning_effort = "xhigh"' .codex/agents/code_reviewer.toml ``` -If only Markdown workflow files changed, no iOS build is required. +If only Markdown workflow files and agent TOML files changed, no iOS build is required. ### Completion @@ -309,6 +352,7 @@ Report: ## Workflow Result - Workflow: AI workflow maintenance +- Approved Spec: - Changed files: - Operational change: - Verification: @@ -321,13 +365,14 @@ Use only side tasks connected to the current main task for parallel role dispatc Parallelize only these combinations: -- GitHub/CI Analyst reading live GitHub state while Planner inspects local files. +- GitHub/CI Analyst reading live GitHub state while Planner inspects local files for a `Design Brief`. - Architecture Watcher reviewing boundaries while Code Reviewer reviews non-architecture risks after the diff is complete. - Documentation Writer drafting PR text while Verification Runner runs checks, after the diff is stable. Do not parallelize: - Two Implementers over overlapping files. +- Designer and Implementer before user approval and Spec persistence. - Implementer and Code Reviewer before Implementer finishes the diff. - Verification Runner before the relevant files are saved. - GitHub write actions with local code edits. @@ -337,6 +382,7 @@ Do not parallelize: Use the activation template from `.agents/roles.md`, then set `` to one of: - `Planner` +- `Designer` - `Implementer` - `Architecture Watcher` - `Code Reviewer` @@ -354,18 +400,21 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s ## Task Packet - Source: https://github.com/opficdev/DevLog_iOS/issues/704 +- Approved Spec: `.agents/specs/704-ai-role-workflow.md` - Goal: Define AI agent roles and executable role-based workflows for this repository. - Scope: Update root AI workflow files and README visual summary only. - Out of scope: Swift/iOS app code, target dependency changes, architecture rule relocation, GitHub Actions changes, app launch. -- Expected changed files: `AGENTS.md`, `.agents/roles.md`, `.agents/workflows.md`, `README.md` +- Acceptance criteria: approved Spec의 역할, 모델, 실행 흐름, 검증 조건 +- Expected changed files: `AGENTS.md`, `.agents/roles.md`, `.agents/workflows.md`, `.agents/specs/README.md` - Current owner: repository workflow documentation - 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` +- Required roles: Planner, Designer, Implementer, Code Reviewer, Verification Runner +- Model assignment: Planner=Primary, Designer=designer (SDD Gate, `gpt-5.6-sol`, `xhigh`), Implementer=Primary, Code Reviewer=code_reviewer (SDD Gate, `gpt-5.6-sol`, `xhigh`), Verification Runner=verification_runner (Lightweight) +- Custom agent `task_name`: Designer=`designer`, 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 +- Execution authority: app or Simulator=not allowed / external writes=not allowed / CI or PR actions=not allowed +- Verification: `git diff --check -- AGENTS.md .agents .codex/agents` +- Stop conditions: missing user approval for the Spec, Swift/iOS code changes, request to remove architecture rules immediately ``` ### Review-thread follow-up example @@ -374,16 +423,19 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s ## Task Packet - Source: +- Approved Spec: <.agents/specs/... path> - Goal: Address accepted review feedback without expanding PR scope. - Scope: Apply only required review fixes confirmed by GitHub/CI Analyst and Planner. - Out of scope: Optional suggestions, unrelated cleanup, new architecture policy, app launch. +- Acceptance criteria: - Expected changed files: - Current owner: - 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` +- Required roles: GitHub/CI Analyst, Planner, Designer, Implementer, Code Reviewer, Verification Runner +- Model assignment: GitHub/CI Analyst=github_ci_analyst (Lightweight), Planner=Primary, Designer=designer (SDD Gate, `gpt-5.6-sol`, `xhigh`), Implementer=Primary, Code Reviewer=code_reviewer (SDD Gate, `gpt-5.6-sol`, `xhigh`), Verification Runner=verification_runner (Lightweight) +- Custom agent `task_name`: GitHub/CI Analyst=`github_ci_analyst`, Designer=`designer`, Code Reviewer=`code_reviewer`, Verification Runner=`verification_runner` - Result recipient: `Primary` of the current main task +- Execution authority: app or Simulator=not allowed / external writes=only user-authorized reply or resolution / CI or PR actions=inspection only - 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/.codex/agents/code_reviewer.toml b/.codex/agents/code_reviewer.toml index bdf69106..786a200e 100644 --- a/.codex/agents/code_reviewer.toml +++ b/.codex/agents/code_reviewer.toml @@ -1,6 +1,6 @@ name = "code_reviewer" description = "Read-only DevLog code reviewer focused on correctness, regressions, scope drift, and missing verification." -model = "gpt-5.3-codex-spark" +model = "gpt-5.6-sol" model_reasoning_effort = "xhigh" sandbox_mode = "read-only" developer_instructions = """ diff --git a/.codex/agents/code_reviewer_luna.toml b/.codex/agents/code_reviewer_luna.toml deleted file mode 100644 index 9f64418f..00000000 --- a/.codex/agents/code_reviewer_luna.toml +++ /dev/null @@ -1,12 +0,0 @@ -name = "code_reviewer_luna" -description = "Fallback DevLog code reviewer when gpt-5.3-codex-spark is unavailable." -model = "gpt-5.6-luna" -model_reasoning_effort = "high" -sandbox_mode = "read-only" -developer_instructions = """ -Read AGENTS.md and .agents/roles.md before reviewing. -Act only as the Code Reviewer defined in .agents/roles.md. -Review the assigned diff without editing files, staging changes, committing, pushing, or changing GitHub state. -Prioritize correctness, regressions, architecture drift, scope drift, and missing tests over style preferences. -Return exactly the Code Review Result format from .agents/roles.md with file and line references when possible. -""" diff --git a/.codex/agents/designer.toml b/.codex/agents/designer.toml new file mode 100644 index 00000000..6579b3dc --- /dev/null +++ b/.codex/agents/designer.toml @@ -0,0 +1,12 @@ +name = "designer" +description = "Read-only DevLog SDD gate for Design Brief analysis, Spec acceptance criteria, verification, and minimum commit units." +model = "gpt-5.6-sol" +model_reasoning_effort = "xhigh" +sandbox_mode = "read-only" +developer_instructions = """ +Read AGENTS.md and .agents/roles.md before analysis. +Act only as the Designer defined in .agents/roles.md. +Analyze the provided Design Brief and current repository context without editing files or changing GitHub state. +Do not run, launch, install, boot, or open the app or Simulator. +Return exactly the Designer Result format from .agents/roles.md. +""" diff --git a/AGENTS.md b/AGENTS.md index 4f3fb65b..06aa8899 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,8 +10,9 @@ | Task | Required document | | --- | --- | | Every task | `.agents/rules/general.md` | -| Non-trivial planning, implementation, review, or verification | `.agents/roles.md` | +| Non-trivial design, planning, implementation, review, or verification | `.agents/roles.md` | | Repeatable role-based execution | `.agents/workflows.md` | +| Approved Spec required by a non-trivial workflow | `.agents/specs/README.md` | | Module boundaries, file ownership, layer dependencies, DI, repository/service contracts, external SDK placement, Widget flow, `StorePattern`, or architecture documentation | `.agents/rules/architecture.md` | | PR, review thread, commit, Xcode project, CI, verification, localization, release, or build tooling | `.agents/rules/project-workflows.md` | @@ -23,5 +24,6 @@ - For architecture work, also read `README.md` before editing. - For a delegated role, read `.agents/roles.md` and follow the assigned role section and output format. - Use `.agents/workflows.md` when the task matches one of its executable workflows. +- For a non-trivial design or implementation workflow, create a `Design Brief`, obtain a `Designer Result`, and use an approved Spec before fixing the `Task Packet`. - If repository-local instructions conflict with global memory, follow the repository-local instructions. - Write DevLog PR and review text in Korean. diff --git a/README.md b/README.md index 95614090..b94d5781 100644 --- a/README.md +++ b/README.md @@ -275,22 +275,32 @@ flowchart LR end subgraph ConnectedSideTasks["현재 task 연결형 사이드 작업
사이드바: Option-Command-S
도구: spawn_agent"] + Designer["Designer
designer
gpt-5.6-sol · xhigh"] ArchitectureWatcher["Architecture Watcher
architecture_watcher"] - CodeReviewer["Code Reviewer
code_reviewer"] + CodeReviewer["Code Reviewer
code_reviewer
gpt-5.6-sol · xhigh"] VerificationRunner["Verification Runner
verification_runner"] GitHubCIAnalyst["GitHub/CI Analyst
github_ci_analyst"] DocumentationWriter["Documentation Writer
documentation_writer"] end subgraph Gate["Gate"] + DesignBrief["Design Brief"] + UserApproval["사용자 승인"] + Spec["Approved Spec"] TaskPacket["Task Packet"] ReviewGate["Review Gate"] VerificationGate["Build-only Verification"] end - TaskPacket --> Planner - Planner --> Implementer - Planner -->|"Architecture risk
task_name 선택"| ArchitectureWatcher + Planner -->|"비단순 작업"| DesignBrief + DesignBrief --> Designer + Designer --> UserApproval + UserApproval --> Spec + Spec --> Planner + Planner -->|"Approved Spec"| TaskPacket + Planner -->|"단순 작업"| TaskPacket + TaskPacket -->|"Architecture risk
task_name 선택"| ArchitectureWatcher + TaskPacket -->|"No architecture risk"| Implementer ArchitectureWatcher -->|Pass| Implementer ArchitectureWatcher -->|Block / Decision| Integrator Implementer --> CodeReviewer @@ -304,10 +314,11 @@ flowchart LR | 역할 | 정확한 `task_name` / Custom Agent | 모델 | 담당 | 다음 흐름 | | --- | --- | --- | --- | --- | -| Planner | active main agent | Primary | 이슈, 요청, 변경 범위, role routing 정리 | Implementer / Architecture Watcher | +| Planner | active main agent | Primary | 이슈, 요청, 변경 범위, `Design Brief`, 승인된 Spec 기반 `Task Packet` 정리 | Designer / Implementer / Architecture Watcher | +| Designer | `designer` | `gpt-5.6-sol` (`SDD Gate`, `xhigh`), 대체 없음 | `Design Brief`의 제약, 대안, 변경 경계, 수용 기준, 검증, 최소 커밋 단위 분석 | 사용자 승인 / Spec | | Implementer | active main agent | Primary | task packet 기준 코드 또는 문서 수정 | Code Reviewer | | Architecture Watcher | `architecture_watcher` | `gpt-5.3-codex-spark` (`Lightweight`), 불가 시 `gpt-5.6-luna` (`high`) -> Primary | layer, target, dependency, SDK placement, Widget/StorePattern 경계 감시 | Implementer / Final Integration | -| Code Reviewer | `code_reviewer` | `gpt-5.3-codex-spark` (`Lightweight`), 불가 시 `gpt-5.6-luna` (`high`) -> Primary | diff 기준 버그, 회귀, 테스트 누락, scope drift 검토 | Verification Runner | +| Code Reviewer | `code_reviewer` | `gpt-5.6-sol` (`SDD Gate`, `xhigh`), 대체 없음 | 승인된 Spec과 최종 diff의 수용 기준, 버그, 회귀, scope drift 검토 | Verification Runner | | Verification Runner | `verification_runner` | `gpt-5.3-codex-spark` (`Lightweight`), 불가 시 `gpt-5.6-luna` (`high`) | SwiftLint, test, build-only, docs check 결과 기록 | Final Integration | | GitHub/CI Analyst | `github_ci_analyst` | `gpt-5.3-codex-spark` (`Lightweight`), 불가 시 `gpt-5.6-luna` (`high`) | issue, PR thread, review comment, workflow run, CI log 분석 | Planner | | Documentation Writer | `documentation_writer` | `gpt-5.3-codex-spark` (`Lightweight`), 불가 시 `gpt-5.6-luna` (`high`) | PR 본문, release note, README, issue/comment 문안 작성 | Final Integration |