diff --git a/AGENTS.md b/AGENTS.md index 404cc8d0..539fd8d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,14 @@ These instructions apply only to the repository root. - Do not include full files, unrelated code, or explanatory text unless explicitly requested. - You do not need to paste code in the prompt after updating it in the repository. +## AI role workflow + +- For non-trivial AI-assisted work, read `AGENT_ROLES.md` before planning, implementing, reviewing, or verifying the task. +- Use `AGENT_ROLES.md` to assign model-specific roles, define handoff packets, and run review or verification gates. +- Use `AGENT_WORKFLOWS.md` when a task should be executed through repeatable role-based workflows. +- Treat `AGENT_ROLES.md` as an operational extension of this file. If it conflicts with `AGENTS.md`, follow `AGENTS.md`. +- Keep `docs/` for README images and draw.io sources. Do not add AI workflow documents under `docs/`. + ## Naming and Swift style - In Swift, do not write explicit type annotations unless required. diff --git a/AGENT_ROLES.md b/AGENT_ROLES.md new file mode 100644 index 00000000..79296315 --- /dev/null +++ b/AGENT_ROLES.md @@ -0,0 +1,405 @@ +# 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, pass task packets between roles, and decide which review or verification gates must run before completion. + +Use `AGENT_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 documents at the repository root, such as `AGENT_ROLES.md`. Do not put them under `docs/`. + +## 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 | +| `Spark` | Read-only review, checklist validation, log summarization, documentation draft, first-pass architecture preflight | `gpt-5.3-codex-spark` when available | +| `Fast` | Low-risk text cleanup, simple file presence checks, short summaries | Fastest low-cost model available | + +Default role-to-model assignment: + +| Role | Default tier | Escalate to `Primary` when | +| --- | --- | --- | +| Planner | `Primary` | Always for live issues, PR scope, architecture scope, or implementation planning | +| Implementer | `Primary` | Always for Swift production code, tests, target dependencies, DI, SDK placement, or GitHub writes | +| Architecture Watcher | `Spark` 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 | `Spark` for first pass, `Primary` for final blocking review | Findings involve runtime behavior, concurrency, data loss, architecture, or test strategy | +| Verification Runner | `Spark` | Verification fails, failure cause is unclear, or a fix is needed | +| GitHub/CI Analyst | `Spark` | CI root cause requires code or workflow changes, or review comments conflict | +| Documentation Writer | `Spark` | Text must explain complex architecture, release risk, or PR scope tradeoffs | + +Do not assign `Spark` 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. + +### Fallback policy + +- If `gpt-5.3-codex-spark` is unavailable, assign `Spark` roles to the fastest available read-only capable coding model. +- If no reliable read-only model is available, assign the role to `Primary`. +- 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 `Spark` 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 task packet. +2. Implementer edits only the assigned scope. +3. Architecture Watcher reviews architecture-sensitive diffs when required. +4. Code Reviewer reviews the final diff for bugs, regressions, and missing tests. +5. Verification Runner runs allowed checks and records the result. +6. Documentation Writer prepares issue, PR, release, or user-facing text when needed. +7. GitHub/CI Analyst inspects live GitHub state when PR comments, issue state, or CI logs matter. + +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 `AGENT_WORKFLOWS.md`. + +## Task packet + +Planner must produce this packet before handing work to another role. + +```md +## Task Packet + +- Source: +- Goal: +- Scope: +- Out of scope: +- Expected changed files: +- Current owner: +- Architecture risk: none / possible / confirmed +- Required roles: +- Model assignment: +- Verification: +- Stop conditions: +``` + +Use `Architecture risk: possible` when the task touches module boundaries, imports, target dependencies, DI, repository or service contracts, Widget flow, Firebase or SDK placement, StorePattern boundaries, or architecture documentation. + +## Role activation + +Use this template when assigning work to another AI model or sub-agent. + +```md +You are the `` for the DevLog iOS repository. + +Read `AGENTS.md` first. Then read `AGENT_ROLES.md` and follow the `` section. + +Assigned model tier: `` + +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. +- 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 | Add GitHub/CI Analyst when live issue or PR state is the source of truth. | +| Swift implementation | Planner, Implementer, Code Reviewer, Verification Runner | Add Architecture Watcher when boundary or dependency risk exists. | +| Module, DI, SDK, Widget, StorePattern, or architecture docs | Planner, Architecture Watcher, Implementer, Code Reviewer, Verification Runner | Architecture Watcher must read `AGENTS.md`, `.gemini/styleguide.md`, `README.md`, and `.hermes/skills/devlog-architecture-harness/references/devlog-architecture-flow.md`. | +| Review feedback | GitHub/CI Analyst, Planner, Implementer, Code Reviewer, Verification Runner | Use thread-aware review inspection when unresolved review threads matter. | +| CI failure | GitHub/CI Analyst, Planner, Verification Runner | Add Implementer only after the failure source is identified. | +| PR or release text | Documentation Writer | Add Code Reviewer when text must match actual diff. | +| Docs-only AI workflow change | Planner, Implementer, Code Reviewer, Verification Runner | No iOS build required unless Swift/iOS project code changes. | + +## Planner + +Planner converts the user request, issue, or PR state 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. + +Must not: + +- Edit implementation files. +- 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: +- Handoff packet: +- User decision needed: +``` + +## Implementer + +Implementer applies the scoped code or document change. + +May: + +- Edit files in the task packet. +- 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. +- 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, Firebase dependency placement, external SDK placement, StorePattern responsibilities, or architecture documentation. + +Must read before reviewing: + +- `AGENTS.md` +- `.gemini/styleguide.md` +- `README.md` +- `.hermes/skills/devlog-architecture-harness/references/devlog-architecture-flow.md` +- `.hermes/skills/devlog-architecture-harness/references/devlog-workflow-rules.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. +- External SDK exposure. +- 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 architecture dependency. +- 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: +- SDK placement: +- Same-layer DI: +- Widget boundary: +- StorePattern: +- Findings: +- Required user decision: +``` + +## Code Reviewer + +Code Reviewer is a read-only diff reviewer. + +May: + +- Inspect `git diff`, changed files, and related tests. +- Prioritize bugs, regressions, architecture drift, readability problems, and missing tests. +- Verify whether the change matches the task packet and issue body. + +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: +- 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. + +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: +- 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 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 task packet from the issue. +2. Implementer edits `AGENTS.md` and `AGENT_ROLES.md`. +3. Code Reviewer checks whether the workflow is executable and scoped. +4. Verification Runner runs `git diff --check` and file-presence checks. +5. Main agent reports changed files, architecture boundary decision, and verification result. + +### Swift bug fix + +1. Planner reads the issue and identifies owner layer and files. +2. Architecture Watcher runs if imports, dependencies, DI, Widget, SDK placement, or StorePattern ownership might change. +3. Implementer applies the focused fix. +4. Code Reviewer reviews the diff for regressions and missing tests. +5. Verification Runner runs changed-file SwiftLint and build-only or test checks. + +### Review-thread follow-up + +1. GitHub/CI Analyst reads unresolved review threads. +2. Planner separates required changes from optional suggestions. +3. Implementer applies only accepted fixes. +4. Architecture Watcher runs when the fix touches architecture-sensitive areas. +5. Code Reviewer checks the final diff. +6. Verification Runner runs allowed checks. +7. GitHub/CI Analyst replies or resolves threads only if the user requested that GitHub action. diff --git a/AGENT_WORKFLOWS.md b/AGENT_WORKFLOWS.md new file mode 100644 index 00000000..3987cf66 --- /dev/null +++ b/AGENT_WORKFLOWS.md @@ -0,0 +1,368 @@ +# DevLog Agent Workflows + +## Purpose + +This file defines executable AI workflows for DevLog work. + +Use this after reading `AGENTS.md` and `AGENT_ROLES.md`. `AGENT_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 `AGENT_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 `AGENT_ROLES.md`. +6. Dispatch read-only `Spark` or `Fast` roles in parallel only when they do not depend on unfinished edits. +7. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint. +8. Integrate role outputs. +9. Escalate any `Spark` or `Fast` blocker to a `Primary` model before editing. +10. Run completion gates. +11. Report changed files, architecture decision, verification result, 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`. +- The requested fix requires relaxing a layer boundary. +- A role needs to run, launch, install, boot, or open the app or Simulator. +- 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. + +## 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, harness 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. +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. + +### Task packet source + +```md +## Task Packet + +- Source: +- Goal: +- Scope: +- Out of scope: +- Expected changed files: +- Current owner: +- Architecture risk: none / possible / confirmed +- Required roles: +- Model assignment: +- Verification: +- Stop conditions: +``` + +### Execution + +- 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. + +### Completion + +Report: + +```md +## Workflow Result + +- Workflow: Issue-driven implementation +- 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. +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. + +### 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. +- External SDK placement. +- 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 +- 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. +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. + +### 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. +- Implementer must apply only accepted fixes. +- Code Reviewer must verify that the final diff addresses the 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 +- 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. +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. + +### 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 +- 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. 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. + +### Execution + +- Documentation Writer must inspect the actual diff before writing PR or release text. +- 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`, `AGENT_ROLES.md`, this file, `.hermes` harness relationship, or AI role routing changes. + +### Role order + +1. Planner. +2. Implementer. +3. Code Reviewer. +4. Verification Runner. + +Architecture Watcher is required only if the change modifies architecture policy, layer maps, ambiguity gates, or harness architecture rules. + +### Execution + +- Keep AI workflow entry files at the repository root. +- Do not add AI workflow documents under `docs/`. +- `AGENTS.md` should stay the short canonical entrypoint. +- `AGENT_ROLES.md` should define role permissions, output formats, and handoff packet shape. +- `AGENT_WORKFLOWS.md` should define executable role sequences. +- `.hermes/skills/devlog-architecture-harness` may remain as the detailed architecture reference unless the task explicitly removes or replaces it. + +### Verification + +Verification Runner must run: + +```sh +git diff --check -- AGENTS.md AGENT_ROLES.md AGENT_WORKFLOWS.md +``` + +If only Markdown workflow files changed, no iOS build is required. + +### Completion + +Report: + +```md +## Workflow Result + +- Workflow: AI workflow maintenance +- Changed files: +- Operational change: +- Verification: +- Remaining decisions: +``` + +## Parallel dispatch guide + +Parallelize only these combinations: + +- GitHub/CI Analyst reading live GitHub state while Planner inspects local files. +- 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. +- 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 `AGENT_ROLES.md`, then set `` to one of: + +- `Planner` +- `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 +- 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, `.hermes` removal, GitHub Actions changes, app launch. +- Expected changed files: `AGENTS.md`, `AGENT_ROLES.md`, `AGENT_WORKFLOWS.md`, `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=Spark, Verification Runner=Spark +- Verification: `git diff --check -- AGENTS.md AGENT_ROLES.md AGENT_WORKFLOWS.md README.md` +- Stop conditions: README `docs/` asset policy changes, Swift/iOS code changes, request to remove architecture harness immediately +``` + +### Review-thread follow-up example + +```md +## Task Packet + +- Source: +- 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. +- Expected changed files: +- Current owner: +- Architecture risk: none / possible / confirmed +- Required roles: GitHub/CI Analyst, Planner, Implementer, Code Reviewer, Verification Runner +- Model assignment: GitHub/CI Analyst=Spark, Planner=Primary, Implementer=Primary, Code Reviewer=Spark -> Primary if blocking, Verification Runner=Spark +- Verification: changed-file SwiftLint for Swift changes, targeted tests or build-only check when applicable +- Stop conditions: unresolved thread requires owner decision, fix relaxes architecture boundary, two comments conflict, CI failure source is unrelated to review feedback +``` diff --git a/README.md b/README.md index ece1a99d..97ca6c2f 100644 --- a/README.md +++ b/README.md @@ -253,3 +253,51 @@ DevLog_iOS/ ├── docs/ # README 이미지와 draw.io 원본 └── README.md ``` + +## AI 역할 분리 + +```mermaid +flowchart LR + subgraph Primary["Primary"] + Planner["Planner"] + Implementer["Implementer"] + Integrator["Final Integration"] + end + + subgraph Spark["gpt-5.3-codex-spark"] + ArchitectureWatcher["Architecture Watcher"] + CodeReviewer["Code Reviewer"] + VerificationRunner["Verification Runner"] + GitHubCIAnalyst["GitHub/CI Analyst"] + DocumentationWriter["Documentation Writer"] + end + + subgraph Gate["Gate"] + TaskPacket["Task Packet"] + ReviewGate["Review Gate"] + VerificationGate["Build-only Verification"] + end + + TaskPacket --> Planner + Planner --> Implementer + Planner --> ArchitectureWatcher + ArchitectureWatcher -->|Pass| Implementer + ArchitectureWatcher -->|Block / Decision| Integrator + Implementer --> CodeReviewer + CodeReviewer --> ReviewGate + ReviewGate --> VerificationRunner + VerificationRunner --> VerificationGate + GitHubCIAnalyst --> Planner + DocumentationWriter --> Integrator + VerificationGate --> Integrator +``` + +| 역할 | 모델 | 담당 | 다음 흐름 | +| --- | --- | --- | --- | +| Planner | Primary | 이슈, 요청, 변경 범위, role routing 정리 | Implementer / Architecture Watcher | +| Implementer | Primary | task packet 기준 코드 또는 문서 수정 | Code Reviewer | +| Architecture Watcher | Spark -> Primary | layer, target, dependency, SDK placement, Widget/StorePattern 경계 감시 | Implementer / Final Integration | +| Code Reviewer | Spark -> Primary | diff 기준 버그, 회귀, 테스트 누락, scope drift 검토 | Verification Runner | +| Verification Runner | gpt-5.3-codex-spark | SwiftLint, test, build-only, docs check 결과 기록 | Final Integration | +| GitHub/CI Analyst | gpt-5.3-codex-spark | issue, PR thread, review comment, workflow run, CI log 분석 | Planner | +| Documentation Writer | gpt-5.3-codex-spark | PR 본문, release note, README, issue/comment 문안 작성 | Final Integration |