docs: SDD workflow와 검증 게이트 정리

Author: opficdev

.agents/workflows.md

@@ -14,22 +14,25 @@ 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/<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.
+3. For non-trivial work, have Planner create a `Design Brief`.
+4. Dispatch `Designer` and obtain its `Designer Result`.
+5. Obtain user approval, then persist the approved result as a Spec under `.agents/specs/`.
+6. Have Planner create a `Task Packet` from only the approved Spec.
+7. Assign only the roles required by the selected workflow.
+8. Assign each role a model tier from `.agents/roles.md`.
+9. Keep `Primary` roles with the active main agent.
+10. Find the exact custom agent name in `.agents/roles.md` and its matching `.codex/agents/<name>.toml` before dispatching an `SDD Gate`, `Lightweight`, or `Fast` role.
+11. 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.
+12. Do not use external `codex exec`, a separate user-owned `create_thread`, or an arbitrary `task_name` for repository role dispatch.
+13. Reuse the existing role agent with `followup_task` when assigning later work to the same role.
+14. Return every delegated role result to the current main task for `Primary` review and integration.
+15. 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.
+16. Dispatch read-only `SDD Gate`, `Lightweight`, or `Fast` roles in parallel only when they do not depend on unfinished edits.
+17. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint.
+18. Integrate role outputs.
+19. Escalate any `SDD Gate`, `Lightweight`, or `Fast` blocker to a `Primary` model before editing.
+20. Run completion gates.
+21. 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 +41,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,37 +71,43 @@ 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
 
 ```md
 ## Task Packet
 
 - Source: <issue URL, PR URL, or user request>
+- Approved Spec: <.agents/specs/... path>
 - Goal:
 - Scope:
 - Out of scope:
+- Acceptance criteria: <approved Spec 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 +117,7 @@ Report:
 ## Workflow Result
 
 - Workflow: Issue-driven implementation
+- Approved Spec:
 - Changed files:
 - Architecture decision:
 - Verification:
@@ -118,12 +130,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 +167,7 @@ Report:
 ## Workflow Result
 
 - Workflow: Architecture-sensitive implementation
+- Approved Spec:
 - Architecture Watcher verdict:
 - Changed files:
 - Boundary decision:
@@ -167,19 +182,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 +207,7 @@ Report:
 ## Workflow Result
 
 - Workflow: Review-thread follow-up
+- Approved Spec:
 - Addressed comments:
 - Deferred or rejected comments:
 - Changed files:
@@ -204,11 +222,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 +245,7 @@ Report:
 ## Workflow Result
 
 - Workflow: CI failure triage
+- Approved Spec:
 - Failing run:
 - Root cause:
 - Changed files:
@@ -238,14 +259,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 +297,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 +316,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 +350,7 @@ Report:
 ## Workflow Result
 
 - Workflow: AI workflow maintenance
+- Approved Spec:
 - Changed files:
 - Operational change:
 - Verification:
@@ -321,13 +363,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 +380,7 @@ Do not parallelize:
 Use the activation template from `.agents/roles.md`, then set `<Role Name>` to one of:
 
 - `Planner`
+- `Designer`
 - `Implementer`
 - `Architecture Watcher`
 - `Code Reviewer`
@@ -354,18 +398,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 +421,19 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s
 ## Task Packet
 
 - Source: <PR URL or review thread URL>
+- 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: <approved Spec criteria>
 - Expected changed files: <filled by Planner after reading threads>
 - Current owner: <layer and target identified by Planner>
 - 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
 ```