From e60c10851e27ae780efb0e865f5dd5405e1b2b4b Mon Sep 17 00:00:00 2001 From: opficdev Date: Sat, 12 Sep 2026 22:14:13 +0900 Subject: [PATCH 1/5] =?UTF-8?q?chore:=20AI=20=EC=97=AD=ED=95=A0=20?= =?UTF-8?q?=EC=B2=B4=EC=9D=B8=20=EC=A0=9C=EA=B1=B0=20=EB=B0=8F=20=EA=B2=BD?= =?UTF-8?q?=EB=9F=89=20=EB=AA=A8=EB=8D=B8=20=EC=9C=A0=EC=A7=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/roles.md | 508 ------------------- .agents/rules/architecture.md | 2 +- .agents/rules/general.md | 6 +- .agents/rules/project-workflows.md | 6 - .agents/specs/README.md | 60 +-- .agents/workflows.md | 441 ---------------- .codex/agents/architecture_watcher.toml | 9 +- .codex/agents/architecture_watcher_luna.toml | 11 +- .codex/agents/code_reviewer.toml | 12 - .codex/agents/designer.toml | 12 - .codex/agents/documentation_writer.toml | 9 +- .codex/agents/documentation_writer_luna.toml | 11 +- .codex/agents/github_ci_analyst.toml | 9 +- .codex/agents/github_ci_analyst_luna.toml | 11 +- .codex/agents/verification_runner.toml | 9 +- .codex/agents/verification_runner_luna.toml | 11 +- AGENTS.md | 17 +- README.md | 59 --- 18 files changed, 57 insertions(+), 1146 deletions(-) delete mode 100644 .agents/roles.md delete mode 100644 .agents/workflows.md delete mode 100644 .codex/agents/code_reviewer.toml delete mode 100644 .codex/agents/designer.toml diff --git a/.agents/roles.md b/.agents/roles.md deleted file mode 100644 index 400da41c..00000000 --- a/.agents/roles.md +++ /dev/null @@ -1,508 +0,0 @@ -# DevLog Agent Roles - -## Purpose - -This file defines the runnable AI role workflow for DevLog work. - -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. - -`AGENTS.md` remains the canonical repository rule file. If this file conflicts with `AGENTS.md`, follow `AGENTS.md`. - -## Operating rules - -- Use one active writer for a file at a time. -- Do not dispatch multiple editing roles over overlapping files. -- Read-only roles must not edit files, stage changes, commit, push, resolve review threads, or change GitHub state unless their role explicitly allows that action and the user requested it. -- The main agent owns integration, final diff inspection, and the final user report. -- 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 - -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-6-astra` with `medium` 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 | - -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` | `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. `Designer` and `Code Reviewer` are Astra-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. - -### Model dispatch requirements - -- 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 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 Astra 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 Astra 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-6-astra` with `medium` reasoning. If the connected side-task surface cannot select Astra 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 `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 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`, `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 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. -- 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. - -### Escalation rule - -Escalate to `Primary` before editing or reporting completion when a non-Primary role returns any of these: - -- `Block` -- `Needs Owner Decision` -- `Fail` -- unclear root cause -- architecture boundary uncertainty -- runtime behavior uncertainty -- conflicting review comments -- missing verification that affects confidence - -Escalation does not mean the `Primary` model should automatically edit. It must first re-check the task packet, the blocking output, and `AGENTS.md`. - -## Workflow - -Use this sequence for non-trivial AI-assisted work. - -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. - -For full issue, implementation, review, CI, and docs-only runbooks, use `.agents/workflows.md`. - -## Task packet - -Planner must produce this packet before handing work to another role. - -```md -## 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. 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 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. - -```md -You are the `` for the DevLog iOS repository. - -Read `AGENTS.md` first. Then read `.agents/roles.md` and follow the `` section. - -Assigned model tier: `` -Custom agent: `` - -Task packet: - - -Rules: -- Stay inside the role permissions. -- Do not edit files if this is a read-only role. -- Do not run, launch, install, boot, or open the app or Simulator. -- Perform this role in the assigned model context. Do not return work copied from a different model context as this role's own result. -- Stop and report if the task packet conflicts with `AGENTS.md`. -- Return only the output format defined for ``. -``` - -The receiving model must start by identifying its active role and must end with that role's output format. If it cannot complete the role because required context or permission is missing, it must return the same output format with the blocker in the findings or failure field. - -## Routing table - -| Task type | Required roles | Notes | -| --- | --- | --- | -| 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, 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 `Design Brief`. After user approval of the `Designer Result` and Spec persistence, Planner converts only that Spec into a scoped `Task Packet`. - -May: - -- Inspect repository files, current diffs, issue bodies, PR bodies, and recent commits. -- 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. - -Output: - -```md -## Planner Result - -- Goal: -- Scope: -- Out of scope: -- Required roles: -- Design Brief: -- Approved Spec: -- Handoff packet: -- User decision needed: -``` - -## Designer - -Designer is the `gpt-6-astra` and `medium` 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 Astra 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. - -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. -- Commit, push, or create PRs unless the user explicitly requested that git action. - -Output: - -```md -## Implementer Result - -- Changed files: -- Scope notes: -- Architecture-sensitive changes: -- Verification suggested: -``` - -## Architecture Watcher - -Architecture Watcher is a read-only gate for DevLog boundaries. - -Use it when a task touches module boundaries, file ownership, layer dependencies, DI assembly, repository or service contracts, widget data flow, `ThirdParty` package linkage, StorePattern responsibilities, or architecture documentation. - -Must read before reviewing: - -- `AGENTS.md` -- `README.md` -- `.agents/rules/architecture.md` -- `.agents/rules/project-workflows.md` when PR, commit, Xcode project, CI, widget, Store, localization, release, or build tooling is involved - -Must inspect: - -- Source imports in changed Swift files. -- Relevant `Project.swift`, `Workspace.swift`, or target dependency changes. -- Layer ownership before and after the change. -- `ThirdParty` package product linkage and whether it remains free of DevLog application behavior. -- Same-layer dependency injection. -- Widget, WidgetCore, and WidgetExtension boundaries when widget flow is touched. -- Presentation `StorePattern` responsibility boundaries when Presentation feature logic is touched. - -Must not: - -- Edit files. -- Approve ambiguous ownership by assumption. -- Treat a manifest-only target dependency as permission for a source-level DevLog architecture dependency. A direct `ThirdParty` dependency permits only imports of its external package products. -- Hide architecture decisions inside build-fix wording. - -Output: - -```md -## Architecture Watch Result - -- Verdict: Pass / Block / Needs Owner Decision -- Changed layer: -- Owning target: -- Dependency direction: -- Target dependency impact: -- ThirdParty linkage: -- Same-layer DI: -- Widget boundary: -- StorePattern: -- Findings: -- Required user decision: -``` - -## Code Reviewer - -Code Reviewer is the `gpt-6-astra` and `medium` 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 approved Spec, its acceptance criteria, and the task packet. - -Must not: - -- Edit files. -- Rewrite style-only preferences as required fixes. -- Request unrelated cleanup outside the current scope. - -Output findings first: - -```md -## Code Review Result - -- Verdict: Pass / Block / Needs Follow-up -- Findings: -- Spec path and acceptance criteria: -- Missing tests or verification: -- Scope drift: -``` - -Use file and line references for findings when possible. - -## Verification Runner - -Verification Runner runs allowed checks and records evidence. - -May: - -- Run `swiftlint` on changed Swift files with the applicable config. -- 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: - -- Run, launch, install, boot, or open the app or Simulator. -- Use build-and-run commands as verification. -- Treat skipped checks as passed. -- Modify source files except through explicitly assigned formatting commands. - -Output: - -```md -## Verification Result - -- Status: Pass / Fail / Not Run -- Commands: -- Spec path and acceptance criteria evidence: -- Evidence: -- Not run: -- Failure notes: -``` - -## GitHub/CI Analyst - -GitHub/CI Analyst inspects live GitHub state. - -May: - -- Read issues, PRs, review comments, labels, and workflow runs. -- Inspect CI logs with `gh` when GitHub Actions details matter. -- Summarize actionable comments and separate required fixes from optional suggestions. -- Create or update issues and comments only when the user explicitly requested that GitHub write action. - -Must not: - -- Edit local files. -- Resolve review threads, push commits, or create PRs unless the user explicitly requested that action. -- Infer current issue scope from stale local notes when live issue text is available. - -Output: - -```md -## GitHub CI Result - -- Source: -- Current state: -- Actionable items: -- Non-actionable items: -- Links: -- Next role: -``` - -## Documentation Writer - -Documentation Writer prepares user-facing or project-facing text. - -May: - -- Draft issue bodies, PR bodies, release notes, README changes, and review replies. -- Edit documentation files when assigned by the task packet. -- Align wording with actual diff and repository templates. - -Must not: - -- Edit app code. -- Put AI workflow documents under `docs/`. -- Overstate implementation details that are not present in the diff. -- Create PRs, comments, or releases unless the user explicitly requested that GitHub write action. - -Output: - -```md -## Documentation Result - -- Target: -- Draft or changed file: -- Source diff used: -- Remaining decision: -``` - -## Completion gates - -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. -- Report unresolved user decisions instead of silently choosing architecture policy. - -## Example workflows - -### Docs-only AI workflow change - -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 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 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/architecture.md b/.agents/rules/architecture.md index 455d3179..84cbc093 100644 --- a/.agents/rules/architecture.md +++ b/.agents/rules/architecture.md @@ -6,7 +6,7 @@ This reference defines the DevLog-specific flow and boundaries for AI-assisted a The goal is not to make the AI decide more architecture policy. The goal is to make the AI stop before it makes project-specific architecture decisions that should be confirmed by the user. -Use this reference with `AGENTS.md`, `.agents/rules/general.md`, and `.agents/roles.md`. +Use this reference with `AGENTS.md` and `.agents/rules/general.md`. This repository is a Tuist-generated, workspace-based modular iOS app. There is no root `Package.swift`; module projects are generated from `Workspace.swift` and each module's `Project.swift`. diff --git a/.agents/rules/general.md b/.agents/rules/general.md index 7c5ff991..06c55068 100644 --- a/.agents/rules/general.md +++ b/.agents/rules/general.md @@ -20,10 +20,10 @@ ## Documentation placement -- Keep AI workflow and rule documents under `.agents/`. -- Keep approved workflow Specs under `.agents/specs/`. +- Keep AI working rules under `.agents/rules/`. +- Treat existing files under `.agents/specs/` as historical records, not required inputs for new work. - Keep `docs/` for README images and draw.io sources. -- Do not add AI workflow documents under `docs/`. +- Do not add AI working rules under `docs/`. ## Repository-local rules diff --git a/.agents/rules/project-workflows.md b/.agents/rules/project-workflows.md index 1772d6f9..be02e379 100644 --- a/.agents/rules/project-workflows.md +++ b/.agents/rules/project-workflows.md @@ -21,12 +21,6 @@ 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/README.md b/.agents/specs/README.md index 0f9cc1c4..de942f21 100644 --- a/.agents/specs/README.md +++ b/.agents/specs/README.md @@ -1,56 +1,8 @@ -# DevLog Spec Format +# DevLog Spec 기록 -`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 deleted file mode 100644 index 1680983a..00000000 --- a/.agents/workflows.md +++ /dev/null @@ -1,441 +0,0 @@ -# DevLog Agent Workflows - -## Purpose - -This file defines executable AI workflows for DevLog work. - -Use this after reading `AGENTS.md` and `.agents/roles.md`. `.agents/roles.md` defines what each role may do. This file defines how to combine those roles for common project tasks. - -If this file conflicts with `AGENTS.md`, follow `AGENTS.md`. - -## Main-agent protocol - -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. 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. - -## Universal stop conditions - -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 `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`. -- 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 | -| --- | --- | -| "이슈 구현", issue number, feature, bug fix | Issue-driven implementation | -| Module, DI, SDK, Widget, StorePattern, architecture docs | Architecture-sensitive implementation | -| PR review comment, unresolved thread, requested changes | Review-thread follow-up | -| Failing GitHub Actions, CI log, workflow failure | CI failure triage | -| PR body, release note, README, issue wording | Documentation-only writing | -| AI role, AGENTS, workflow, or architecture-rule docs | AI workflow maintenance | - -## Issue-driven implementation - -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 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: -- 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 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 - -Report: - -```md -## Workflow Result - -- Workflow: Issue-driven implementation -- Approved Spec: -- Changed files: -- Architecture decision: -- Verification: -- Remaining decisions: -``` - -## Architecture-sensitive implementation - -Use when the task touches module boundaries, file ownership, layer dependencies, DI assembly, repository or service contracts, Widget flow, Firebase or SDK placement, StorePattern boundaries, or architecture documentation. - -### Role order - -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 - -Architecture Watcher must return: - -- `Pass` before Implementer edits. -- `Block` when the requested change violates current rules. -- `Needs Owner Decision` when the repository rules require user confirmation. - -Implementer must not proceed on `Block` or `Needs Owner Decision`. - -### Required inspection - -- Changed Swift imports. -- `Workspace.swift` and relevant `Project.swift` files. -- Current owner and proposed owner. -- `ThirdParty` package linkage and external import policy. -- Same-layer DI. -- Widget and WidgetCore boundaries when touched. -- StorePattern reducer, side effect, and run responsibility when Presentation feature logic is touched. - -### Completion - -Report: - -```md -## Workflow Result - -- Workflow: Architecture-sensitive implementation -- Approved Spec: -- Architecture Watcher verdict: -- Changed files: -- Boundary decision: -- Verification: -- Remaining decisions: -``` - -## Review-thread follow-up - -Use when the user asks to address PR review comments or unresolved review threads. - -### Role order - -1. GitHub/CI Analyst. -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 in the `Design Brief`. -- Implementer must apply only accepted fixes. -- 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 - -Report: - -```md -## Workflow Result - -- Workflow: Review-thread follow-up -- Approved Spec: -- Addressed comments: -- Deferred or rejected comments: -- Changed files: -- Verification: -- GitHub actions: -``` - -## CI failure triage - -Use when GitHub Actions, merge-risk-watch, release, TestFlight, App Store, or PR CI fails. - -### Role order - -1. GitHub/CI Analyst. -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 - -- GitHub/CI Analyst must inspect the failing run, job, and log excerpts before proposing fixes. -- Planner must separate workflow failure, environment failure, dependency failure, and app build failure. -- Implementer must not edit workflow files until the failing step is identified. -- Verification Runner must not treat CI polling as a substitute for local verification when local checks are available. - -### Completion - -Report: - -```md -## Workflow Result - -- Workflow: CI failure triage -- Approved Spec: -- Failing run: -- Root cause: -- Changed files: -- Verification: -- Remaining CI risk: -``` - -## Documentation-only writing - -Use for PR body, issue text, release note, README wording, review reply draft, or user-facing explanation. - -### Role order - -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. -- Do not write AI workflow documents under `docs/`. -- If the user asks only for text, return text directly and do not create files. -- If documentation files are changed, keep the change scoped to the requested document. - -### Completion - -Report: - -```md -## Workflow Result - -- Workflow: Documentation-only writing -- Target: -- Changed files: -- Source checked: -- Verification: -``` - -## AI workflow maintenance - -Use for `AGENTS.md`, `.agents/roles.md`, this file, `.agents/rules`, or AI role routing changes. - -### Role order - -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. - -### Execution - -- Keep `AGENTS.md` as the repository-root AI workflow entrypoint. -- Do not add AI workflow documents under `docs/`. -- `AGENTS.md` should stay the short canonical entrypoint. -- `.agents/roles.md` should define role permissions, output formats, and handoff packet shape. -- `.agents/workflows.md` should define executable role sequences. -- `.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 -``` - -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-6-astra"' .codex/agents/designer.toml -rg -qx 'model_reasoning_effort = "medium"' .codex/agents/designer.toml -rg -qx 'name = "code_reviewer"' .codex/agents/code_reviewer.toml -rg -qx 'model = "gpt-6-astra"' .codex/agents/code_reviewer.toml -rg -qx 'model_reasoning_effort = "medium"' .codex/agents/code_reviewer.toml -``` - -If only Markdown workflow files and agent TOML files changed, no iOS build is required. - -### Completion - -Report: - -```md -## Workflow Result - -- Workflow: AI workflow maintenance -- Approved Spec: -- Changed files: -- Operational change: -- Verification: -- Remaining decisions: -``` - -## 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 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. - -## Role prompt snippets - -Use the activation template from `.agents/roles.md`, then set `` to one of: - -- `Planner` -- `Designer` -- `Implementer` -- `Architecture Watcher` -- `Code Reviewer` -- `Verification Runner` -- `GitHub/CI Analyst` -- `Documentation Writer` - -Include the selected workflow name in the task packet `Source` or `Goal` field so the receiving model can align its output to this runbook. - -## Task packet examples - -### Issue-driven implementation example - -```md -## 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. -- 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, Designer, Implementer, Code Reviewer, Verification Runner -- Model assignment: Planner=Primary, Designer=designer (SDD Gate, `gpt-6-astra`, `medium`), Implementer=Primary, Code Reviewer=code_reviewer (SDD Gate, `gpt-6-astra`, `medium`), 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 -- 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 - -```md -## 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, Designer, Implementer, Code Reviewer, Verification Runner -- Model assignment: GitHub/CI Analyst=github_ci_analyst (Lightweight), Planner=Primary, Designer=designer (SDD Gate, `gpt-6-astra`, `medium`), Implementer=Primary, Code Reviewer=code_reviewer (SDD Gate, `gpt-6-astra`, `medium`), 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/architecture_watcher.toml b/.codex/agents/architecture_watcher.toml index e55573df..4c25ec6b 100644 --- a/.codex/agents/architecture_watcher.toml +++ b/.codex/agents/architecture_watcher.toml @@ -1,12 +1,11 @@ name = "architecture_watcher" -description = "Read-only DevLog architecture boundary reviewer for module ownership, dependencies, DI, SDK placement, Widget flow, and StorePattern changes." +description = "Read-only DevLog architecture boundary preflight for module ownership, dependencies, DI, SDK placement, Widget flow, and StorePattern changes." model = "gpt-5.3-codex-spark" model_reasoning_effort = "xhigh" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before reviewing. -Act only as the Architecture Watcher defined in .agents/roles.md. -Inspect the requested architecture scope and relevant manifests without editing files or changing GitHub state. +Read AGENTS.md, README.md, .agents/rules/general.md, and .agents/rules/architecture.md before analysis. +Inspect only the architecture scope assigned by the main agent. Do not edit files or change GitHub state. Do not run, launch, install, boot, or open the app or Simulator. -Return exactly the Architecture Watch Result format from .agents/roles.md. +Return a concise verdict, changed boundary, evidence, and any user decision required. """ diff --git a/.codex/agents/architecture_watcher_luna.toml b/.codex/agents/architecture_watcher_luna.toml index 1c363d97..2c9e3f9f 100644 --- a/.codex/agents/architecture_watcher_luna.toml +++ b/.codex/agents/architecture_watcher_luna.toml @@ -1,12 +1,11 @@ name = "architecture_watcher_luna" -description = "Fallback DevLog architecture boundary reviewer when gpt-5.3-codex-spark is unavailable." +description = "Fallback DevLog architecture boundary preflight when gpt-5.3-codex-spark is unavailable." model = "gpt-5.6-luna" -model_reasoning_effort = "high" +model_reasoning_effort = "xhigh" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before reviewing. -Act only as the Architecture Watcher defined in .agents/roles.md. -Inspect the requested architecture scope and relevant manifests without editing files or changing GitHub state. +Read AGENTS.md, README.md, .agents/rules/general.md, and .agents/rules/architecture.md before analysis. +Inspect only the architecture scope assigned by the main agent. Do not edit files or change GitHub state. Do not run, launch, install, boot, or open the app or Simulator. -Return exactly the Architecture Watch Result format from .agents/roles.md. +Return a concise verdict, changed boundary, evidence, and any user decision required. """ diff --git a/.codex/agents/code_reviewer.toml b/.codex/agents/code_reviewer.toml deleted file mode 100644 index c6355a69..00000000 --- a/.codex/agents/code_reviewer.toml +++ /dev/null @@ -1,12 +0,0 @@ -name = "code_reviewer" -description = "Read-only DevLog code reviewer focused on correctness, regressions, scope drift, and missing verification." -model = "gpt-6-astra" -model_reasoning_effort = "medium" -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 deleted file mode 100644 index ce0b8c28..00000000 --- a/.codex/agents/designer.toml +++ /dev/null @@ -1,12 +0,0 @@ -name = "designer" -description = "Read-only DevLog SDD gate for Design Brief analysis, Spec acceptance criteria, verification, and minimum commit units." -model = "gpt-6-astra" -model_reasoning_effort = "medium" -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/.codex/agents/documentation_writer.toml b/.codex/agents/documentation_writer.toml index e555c258..45a8a89f 100644 --- a/.codex/agents/documentation_writer.toml +++ b/.codex/agents/documentation_writer.toml @@ -4,9 +4,8 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "xhigh" sandbox_mode = "workspace-write" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before drafting. -Act only as the Documentation Writer defined in .agents/roles.md. -Match repository templates, actual diffs, live issue or PR state, and the requested Korean wording rules. -Edit only documentation files named in the task packet. Do not edit app code or create GitHub content unless the task packet explicitly authorizes that write action. -Return exactly the Documentation Result format from .agents/roles.md unless the task packet requests direct Markdown draft output. +Read AGENTS.md and all task-matching rules under .agents/rules before drafting. +Match repository templates, the actual diff, live issue or PR state supplied by the main agent, and the requested Korean wording. +Edit only documentation files explicitly assigned by the main agent. Do not edit app code or change GitHub state. +Return the draft or changed paths, sources used, and unresolved decisions concisely. """ diff --git a/.codex/agents/documentation_writer_luna.toml b/.codex/agents/documentation_writer_luna.toml index 6e6a77dd..4d8ca4b5 100644 --- a/.codex/agents/documentation_writer_luna.toml +++ b/.codex/agents/documentation_writer_luna.toml @@ -1,12 +1,11 @@ name = "documentation_writer_luna" description = "Fallback DevLog documentation writer when gpt-5.3-codex-spark is unavailable." model = "gpt-5.6-luna" -model_reasoning_effort = "high" +model_reasoning_effort = "xhigh" sandbox_mode = "workspace-write" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before drafting. -Act only as the Documentation Writer defined in .agents/roles.md. -Match repository templates, actual diffs, live issue or PR state, and the requested Korean wording rules. -Edit only documentation files named in the task packet. Do not edit app code or create GitHub content unless the task packet explicitly authorizes that write action. -Return exactly the Documentation Result format from .agents/roles.md unless the task packet requests direct Markdown draft output. +Read AGENTS.md and all task-matching rules under .agents/rules before drafting. +Match repository templates, the actual diff, live issue or PR state supplied by the main agent, and the requested Korean wording. +Edit only documentation files explicitly assigned by the main agent. Do not edit app code or change GitHub state. +Return the draft or changed paths, sources used, and unresolved decisions concisely. """ diff --git a/.codex/agents/github_ci_analyst.toml b/.codex/agents/github_ci_analyst.toml index 9239c0e3..30f3e49f 100644 --- a/.codex/agents/github_ci_analyst.toml +++ b/.codex/agents/github_ci_analyst.toml @@ -4,9 +4,8 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "xhigh" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before analysis. -Act only as the GitHub/CI Analyst defined in .agents/roles.md. -Use live GitHub state as the source of truth and use thread-aware review inspection when resolution state matters. -Do not edit files, reply, resolve threads, submit reviews, push, or change GitHub state unless the task packet explicitly authorizes that write action. -Return exactly the GitHub CI Result format from .agents/roles.md. +Read AGENTS.md and .agents/rules/project-workflows.md before analysis. +Use live GitHub state as the source of truth and inspect review threads when resolution state matters. +Do not edit files, reply, resolve threads, submit reviews, push, or change GitHub state. +Return concise current state, actionable items, evidence links, and unresolved decisions. """ diff --git a/.codex/agents/github_ci_analyst_luna.toml b/.codex/agents/github_ci_analyst_luna.toml index 35ee22f1..a382d3d9 100644 --- a/.codex/agents/github_ci_analyst_luna.toml +++ b/.codex/agents/github_ci_analyst_luna.toml @@ -1,12 +1,11 @@ name = "github_ci_analyst_luna" description = "Fallback DevLog GitHub and CI analyst when gpt-5.3-codex-spark is unavailable." model = "gpt-5.6-luna" -model_reasoning_effort = "high" +model_reasoning_effort = "xhigh" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before analysis. -Act only as the GitHub/CI Analyst defined in .agents/roles.md. -Use live GitHub state as the source of truth and use thread-aware review inspection when resolution state matters. -Do not edit files, reply, resolve threads, submit reviews, push, or change GitHub state unless the task packet explicitly authorizes that write action. -Return exactly the GitHub CI Result format from .agents/roles.md. +Read AGENTS.md and .agents/rules/project-workflows.md before analysis. +Use live GitHub state as the source of truth and inspect review threads when resolution state matters. +Do not edit files, reply, resolve threads, submit reviews, push, or change GitHub state. +Return concise current state, actionable items, evidence links, and unresolved decisions. """ diff --git a/.codex/agents/verification_runner.toml b/.codex/agents/verification_runner.toml index ac525f27..3256f14e 100644 --- a/.codex/agents/verification_runner.toml +++ b/.codex/agents/verification_runner.toml @@ -4,10 +4,9 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "xhigh" sandbox_mode = "workspace-write" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before verification. -Act only as the Verification Runner defined in .agents/roles.md. -Do not edit source or documentation files, except through an explicitly assigned formatting command. +Read AGENTS.md and all task-matching rules under .agents/rules before verification. +Run only the checks assigned by the main agent. Record exact commands, exit status, evidence, failures, and skipped checks. +Do not edit source or documentation files except through an explicitly assigned formatting command. Do not run, launch, install, boot, or open the app or Simulator. -Run only the checks assigned in the task packet and record exact commands, exit status, and evidence. -Return exactly the Verification Result format from .agents/roles.md. +Return a concise verification result. """ diff --git a/.codex/agents/verification_runner_luna.toml b/.codex/agents/verification_runner_luna.toml index 7dba28fd..bb6da38e 100644 --- a/.codex/agents/verification_runner_luna.toml +++ b/.codex/agents/verification_runner_luna.toml @@ -1,13 +1,12 @@ name = "verification_runner_luna" description = "Fallback DevLog verification runner when gpt-5.3-codex-spark is unavailable." model = "gpt-5.6-luna" -model_reasoning_effort = "high" +model_reasoning_effort = "xhigh" sandbox_mode = "workspace-write" developer_instructions = """ -Read AGENTS.md and .agents/roles.md before verification. -Act only as the Verification Runner defined in .agents/roles.md. -Do not edit source or documentation files, except through an explicitly assigned formatting command. +Read AGENTS.md and all task-matching rules under .agents/rules before verification. +Run only the checks assigned by the main agent. Record exact commands, exit status, evidence, failures, and skipped checks. +Do not edit source or documentation files except through an explicitly assigned formatting command. Do not run, launch, install, boot, or open the app or Simulator. -Run only the checks assigned in the task packet and record exact commands, exit status, and evidence. -Return exactly the Verification Result format from .agents/roles.md. +Return a concise verification result. """ diff --git a/AGENTS.md b/AGENTS.md index 06aa8899..717cad4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,9 +10,6 @@ | Task | Required document | | --- | --- | | Every task | `.agents/rules/general.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` | @@ -22,8 +19,16 @@ - `.agents/rules/general.md` applies to every task. - Read all matching task-specific documents before planning, editing, reviewing, or verifying. - 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`. +- The main agent owns investigation, editing, verification, and the final report. +- Do not require a `Design Brief`, Spec, `Task Packet`, or role-specific result before starting work. - If repository-local instructions conflict with global memory, follow the repository-local instructions. - Write DevLog PR and review text in Korean. + +## Lightweight delegation + +- Prefer the configured `gpt-5.3-codex-spark` agent for a bounded task that matches its description: `architecture_watcher`, `verification_runner`, `github_ci_analyst`, or `documentation_writer`. +- If Spark is unavailable, use only the matching `*_luna` agent with `gpt-5.6-luna` and `xhigh` reasoning. +- Dispatch the lightweight task directly from the user request or current diff. Do not create a role chain, `Design Brief`, Spec, or `Task Packet` for delegation. +- Keep planning, Swift implementation, final decisions, integration, git writes, and GitHub writes with the main agent. +- The main agent must check the delegated result before using it, but should not repeat the same investigation without a concrete reason. +- If both configured lightweight models are unavailable, continue with the main agent. Do not dispatch another fallback agent. diff --git a/README.md b/README.md index 8833ca2e..dcda360b 100644 --- a/README.md +++ b/README.md @@ -259,62 +259,3 @@ DevLog_iOS/ ├── docs/ # README 이미지와 draw.io 원본 └── README.md ``` - -## AI 역할 분리 - -```mermaid -flowchart LR - subgraph Primary["Primary"] - Planner["Planner"] - Implementer["Implementer"] - Integrator["Final Integration"] - 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
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 - - 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 - CodeReviewer --> ReviewGate - ReviewGate --> VerificationRunner - VerificationRunner --> VerificationGate - GitHubCIAnalyst -->|"현재 task로 결과 반환"| Planner - DocumentationWriter -->|"현재 task로 결과 반환"| Integrator - VerificationGate --> Integrator -``` - -| 역할 | 정확한 `task_name` / Custom Agent | 모델 | 담당 | 다음 흐름 | -| --- | --- | --- | --- | --- | -| 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.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 | From 1b7fd8527ce0b2eb384f562437ca63847de55b77 Mon Sep 17 00:00:00 2001 From: opficdev Date: Sat, 12 Sep 2026 22:37:34 +0900 Subject: [PATCH 2/5] =?UTF-8?q?fix:=20=EC=82=AC=EC=9A=A9=EC=9E=90=20?= =?UTF-8?q?=EC=9A=94=EC=B2=AD=20=EB=A1=9C=EC=A7=81=20=EB=B3=80=EA=B2=BD=20?= =?UTF-8?q?=EC=98=88=EC=99=B8=20=EB=B3=B5=EC=9B=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/rules/general.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/rules/general.md b/.agents/rules/general.md index 06c55068..c49cd5c5 100644 --- a/.agents/rules/general.md +++ b/.agents/rules/general.md @@ -3,8 +3,8 @@ ## Logic preservation and optimization - Reuse the existing program logic as-is whenever possible. -- Change logic only when the new approach produces exactly the same result and strictly improves time or space complexity. -- If there is no clear complexity improvement, keep the original logic. +- Change logic when the user explicitly requests the behavior change, or when the new approach produces exactly the same result and strictly improves time or space complexity. +- Otherwise, keep the original logic. ## Code modification response style From 962b8f5246aef225f5c3a2cde4645768c5ecd544 Mon Sep 17 00:00:00 2001 From: opficdev Date: Sat, 12 Sep 2026 22:38:02 +0900 Subject: [PATCH 3/5] =?UTF-8?q?chore:=20=EC=95=B1=EA=B3=BC=20Simulator=20?= =?UTF-8?q?=EC=8B=A4=ED=96=89=20=EC=8A=B9=EC=9D=B8=20=EA=B7=9C=EC=B9=99=20?= =?UTF-8?q?=EB=B3=B5=EC=9B=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 717cad4c..e3cc521d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,7 @@ - Read all matching task-specific documents before planning, editing, reviewing, or verifying. - For architecture work, also read `README.md` before editing. - The main agent owns investigation, editing, verification, and the final report. +- 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. - Do not require a `Design Brief`, Spec, `Task Packet`, or role-specific result before starting work. - If repository-local instructions conflict with global memory, follow the repository-local instructions. - Write DevLog PR and review text in Korean. From 808a1ee2ce516e1628caffc2465cadb20caab770 Mon Sep 17 00:00:00 2001 From: opficdev Date: Sat, 12 Sep 2026 22:38:40 +0900 Subject: [PATCH 4/5] =?UTF-8?q?fix:=20=ED=95=84=EC=88=98=20=EA=B2=80?= =?UTF-8?q?=EC=A6=9D=20=EC=83=81=ED=83=9C=20=ED=8C=90=EC=A0=95=20=EB=B3=B5?= =?UTF-8?q?=EC=9B=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codex/agents/verification_runner.toml | 3 +++ .codex/agents/verification_runner_luna.toml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/.codex/agents/verification_runner.toml b/.codex/agents/verification_runner.toml index 3256f14e..071a4130 100644 --- a/.codex/agents/verification_runner.toml +++ b/.codex/agents/verification_runner.toml @@ -6,6 +6,9 @@ sandbox_mode = "workspace-write" developer_instructions = """ Read AGENTS.md and all task-matching rules under .agents/rules before verification. Run only the checks assigned by the main agent. Record exact commands, exit status, evidence, failures, and skipped checks. +Compare the assigned checks with every required check for the changed file types in the repository rules. +Return Status: Pass only when every required check ran and passed, Fail when a required check ran and failed, or Not Run when any required check was skipped or unavailable. +Never report a skipped or unavailable required check as Pass. Do not edit source or documentation files except through an explicitly assigned formatting command. Do not run, launch, install, boot, or open the app or Simulator. Return a concise verification result. diff --git a/.codex/agents/verification_runner_luna.toml b/.codex/agents/verification_runner_luna.toml index bb6da38e..f9552cef 100644 --- a/.codex/agents/verification_runner_luna.toml +++ b/.codex/agents/verification_runner_luna.toml @@ -6,6 +6,9 @@ sandbox_mode = "workspace-write" developer_instructions = """ Read AGENTS.md and all task-matching rules under .agents/rules before verification. Run only the checks assigned by the main agent. Record exact commands, exit status, evidence, failures, and skipped checks. +Compare the assigned checks with every required check for the changed file types in the repository rules. +Return Status: Pass only when every required check ran and passed, Fail when a required check ran and failed, or Not Run when any required check was skipped or unavailable. +Never report a skipped or unavailable required check as Pass. Do not edit source or documentation files except through an explicitly assigned formatting command. Do not run, launch, install, boot, or open the app or Simulator. Return a concise verification result. From 658486072089cbae586c8b3c421a15193625ee03 Mon Sep 17 00:00:00 2001 From: opficdev Date: Sat, 12 Sep 2026 23:45:09 +0900 Subject: [PATCH 5/5] =?UTF-8?q?chore:=20DevLog=20Harness=20=EC=9E=90?= =?UTF-8?q?=EB=8F=99=20=EC=97=B0=EA=B2=B0=20=EA=B5=AC=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e3cc521d..18e1fe7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,8 @@ | Every task | `.agents/rules/general.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` | +| Prior technical decisions whose reasoning could change the current decision | `../DevLog_Harness/AGENTS.md`, `../DevLog_Harness/profiles/devlog-ios/profile.md`, `../DevLog_Harness/profiles/decision-memory.md`, `../DevLog_Harness/skills/decision-search/SKILL.md` | +| A durable technical decision that the user asks to record in Notion | `../DevLog_Harness/AGENTS.md`, `../DevLog_Harness/profiles/devlog-ios/profile.md`, `../DevLog_Harness/profiles/decision-memory.md`, `../DevLog_Harness/skills/decision-write/SKILL.md` | ## Routing rules @@ -25,6 +27,15 @@ - If repository-local instructions conflict with global memory, follow the repository-local instructions. - Write DevLog PR and review text in Korean. +## External Harness + +- Treat a sibling `../DevLog_Harness` repository as the automatic Harness for this repository when every routed Harness file exists. +- Load Harness files only for a matching route. Do not read Decision Memory or its skills for unrelated work. +- Resolve the sibling path at runtime. Do not persist a user-specific absolute path in this repository. +- Read Notion scope and data-source settings from the Harness repository's local Git configuration. Do not copy those values or credentials into this repository. +- Keep this repository's rules authoritative for source changes, architecture, verification, git, and GitHub work. +- If the Harness or a routed file is unavailable, continue with this repository's rules unless the requested capability depends on it. Report the missing dependency instead of guessing or broadening the search. + ## Lightweight delegation - Prefer the configured `gpt-5.3-codex-spark` agent for a bounded task that matches its description: `architecture_watcher`, `verification_runner`, `github_ci_analyst`, or `documentation_writer`.