diff --git a/AGENT_ROLES.md b/.agents/roles.md similarity index 95% rename from AGENT_ROLES.md rename to .agents/roles.md index e78d816c..f28a02c2 100644 --- a/AGENT_ROLES.md +++ b/.agents/roles.md @@ -6,7 +6,7 @@ This file defines the runnable AI role workflow for DevLog work. It is not background documentation. Use it to split work across AI models, pass task packets between roles, and decide which review or verification gates must run before completion. -Use `AGENT_WORKFLOWS.md` for task-specific runbooks that combine these roles into executable workflows. +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`. @@ -18,7 +18,7 @@ Use `AGENT_WORKFLOWS.md` for task-specific runbooks that combine these roles int - 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/`. +- Keep AI workflow and rule documents under `.agents/`. Do not put them under `docs/`. ## Model assignment @@ -97,7 +97,7 @@ Use this sequence for non-trivial AI-assisted work. 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`. +For full issue, implementation, review, CI, and docs-only runbooks, use `.agents/workflows.md`. ## Task packet @@ -128,7 +128,7 @@ Use this template when assigning a `Lightweight` or `Fast` role through its conf ```md You are the `` for the DevLog iOS repository. -Read `AGENTS.md` first. Then read `AGENT_ROLES.md` and follow the `` section. +Read `AGENTS.md` first. Then read `.agents/roles.md` and follow the `` section. Assigned model tier: `` Custom agent: `` @@ -153,7 +153,7 @@ The receiving model must start by identifying its active role and must end with | --- | --- | --- | | 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`. | +| 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 `.agents/rules/architecture.md`. | | Review feedback | GitHub/CI Analyst, Planner, Implementer, Code Reviewer, Verification Runner | Use thread-aware review inspection when unresolved review threads matter. | | CI failure | GitHub/CI Analyst, Planner, Verification Runner | Add Implementer only after the failure source is identified. | | PR or release text | Documentation Writer | Add Code Reviewer when text must match actual diff. | @@ -229,8 +229,8 @@ 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 +- `.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: @@ -399,7 +399,7 @@ Before reporting completion: ### Docs-only AI workflow change 1. Planner creates a task packet from the issue. -2. Implementer edits `AGENTS.md` and `AGENT_ROLES.md`. +2. Implementer edits `AGENTS.md` and `.agents/roles.md`. 3. Code Reviewer checks whether the workflow is executable and scoped. 4. Verification Runner runs `git diff --check` and file-presence checks. 5. Main agent reports changed files, architecture boundary decision, and verification result. diff --git a/.hermes/skills/devlog-architecture-harness/references/devlog-architecture-flow.md b/.agents/rules/architecture.md similarity index 84% rename from .hermes/skills/devlog-architecture-harness/references/devlog-architecture-flow.md rename to .agents/rules/architecture.md index 734399fd..bc68575a 100644 --- a/.hermes/skills/devlog-architecture-harness/references/devlog-architecture-flow.md +++ b/.agents/rules/architecture.md @@ -1,16 +1,52 @@ -# DevLog Architecture Flow +# DevLog Architecture Rules ## Purpose -This reference defines the DevLog-specific harness flow for AI-assisted architecture work. +This reference defines the DevLog-specific flow and boundaries for AI-assisted architecture work. 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` and `.hermes/skills/devlog-architecture-harness/SKILL.md`. +Use this reference with `AGENTS.md`, `.agents/rules/general.md`, and `.agents/roles.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`. -## High-level harness flow +## When to use + +Read this file before work that changes any of these areas: + +- Module boundaries or file ownership across `Application/*` and `Widget/*` targets. +- Swift imports or Tuist target dependencies. +- DI assembler wiring or same-layer dependency injection. +- Repository, service, store, or use case contracts. +- Firebase, social login, network, link metadata, notification, or WidgetKit dependency placement. +- Widget snapshot, App Group, or widget deep-link data flow. +- Architecture diagrams, README architecture text, or PR architecture explanations. + +Before editing, also read `.gemini/styleguide.md` and `README.md`. Read `.agents/rules/project-workflows.md` when the task involves PR review, commits, Xcode project files, CI, widgets, Store reducers, localization, release, or build tooling. + +Then inspect the concrete files, Swift imports, and Tuist target dependencies related to the requested change. Do not rely on layer names alone. + +## Mandatory flow + +1. Identify the changed layer and owning target before editing. +2. Inspect the current Swift import direction and Xcode target/framework dependency before deciding. +3. Classify the change as mechanical, architectural, or ambiguous. +4. Stop and ask the user before editing when the architecture boundary is ambiguous. +5. Keep the diff limited to the requested architecture scope. +6. Follow `.agents/rules/project-workflows.md` for verification after Swift or iOS project changes. +7. Report the changed files, architecture decision, verification result, and unresolved user decisions. + +## Safe mechanical changes + +These may proceed after inspection when they do not change architecture meaning: + +- Removing unused imports. +- Updating import statements after an already-approved file move. +- Fixing access control needed by an already-approved module boundary. +- Updating tests to match an already-approved public contract. +- Editing docs to reflect the current verified architecture. + +## High-level architecture flow ```mermaid flowchart TD @@ -309,7 +345,7 @@ Widget UI should consume snapshot data. It should not fetch app services or doma flowchart TD Changed["Files changed"] Swift{"Swift/iOS project code changed?"} - Docs{"Docs or harness only?"} + Docs{"Docs or architecture rules only?"} Xcode["Build with Xcode Local MCP"] Diff["Inspect git diff scope"] NoBuild["No iOS build required"] @@ -346,4 +382,4 @@ Before editing architecture code, the AI should be able to answer these question - Swift logic was preserved unless explicitly approved. - Diff scope was checked. - Xcode Local MCP build was used for Swift/iOS code changes. -- Docs-only or harness-only changes were reported as such, without claiming app build verification. +- Docs-only or architecture-rule-only changes were reported as such, without claiming app build verification. diff --git a/.agents/rules/general.md b/.agents/rules/general.md new file mode 100644 index 00000000..ce93a526 --- /dev/null +++ b/.agents/rules/general.md @@ -0,0 +1,31 @@ +# DevLog General Agent Rules + +## 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. + +## Code modification response style + +- When asked to modify code, return only the precise changed locations and the modified code for those locations. +- 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. + +## Naming and Swift style + +- In Swift, do not write explicit type annotations unless required. +- Use `opfic` in new Swift file headers. +- Prefer `<` and `<=` over `>` and `>=` when writing comparisons, if the condition can be expressed clearly that way. + +## Documentation placement + +- Keep AI workflow and rule documents under `.agents/`. +- Keep `docs/` for README images and draw.io sources. +- Do not add AI workflow documents under `docs/`. + +## Repository-local rules + +- DevLog-specific working rules belong in this repository, not in global agent memory. +- Treat `AGENTS.md` and the routed `.agents/` documents as the canonical DevLog AI working rules. +- If global memory conflicts with this repository, follow the repository. diff --git a/.hermes/skills/devlog-architecture-harness/references/devlog-workflow-rules.md b/.agents/rules/project-workflows.md similarity index 92% rename from .hermes/skills/devlog-architecture-harness/references/devlog-workflow-rules.md rename to .agents/rules/project-workflows.md index a078209d..40a3d6f7 100644 --- a/.hermes/skills/devlog-architecture-harness/references/devlog-workflow-rules.md +++ b/.agents/rules/project-workflows.md @@ -4,13 +4,13 @@ This reference holds DevLog-specific working rules that should live with the pro ## Canonical source -- Treat this repository's `AGENTS.md` and `.hermes/skills/devlog-architecture-harness` as the canonical DevLog working rules. +- Treat this repository's `AGENTS.md` and routed `.agents/` documents as the canonical DevLog working rules. - Use global memory only as historical context. If global memory conflicts with this repository, follow the repository. - Before changing architecture rules, update the repository-local rules first. ## Verification -- Follow `AGENTS.md` for the canonical lint and build verification policy. +- Treat this section as the canonical lint and build verification policy routed by `AGENTS.md`. - Run Homebrew SwiftLint (`swiftlint`) on changed Swift files. - Lint production Swift files with the applicable source `.swiftlint.yml` config. - Lint test Swift files with `.swiftlint-tests.yml` or the module `Tests/.swiftlint.yml` that inherits from it. Do not use the root production config for tests. @@ -43,6 +43,11 @@ This reference holds DevLog-specific working rules that should live with the pro ## Commit guidance +- Commit messages must start with a short prefix used by recent local commits, such as `feat`, `fix`, `refactor`, `chore`, `test`, `docs`, `ui`, or `rollback`. +- Write commit message prose in Korean. +- Keep implementation names such as `ToastPresenter`, `toastHost`, `MainView`, `Presentation`, file paths, commands, branch names, and commit hashes in their original form. +- Do not translate implementation names into Korean unless the user explicitly asks for a user-facing Korean label. +- Do not write a commit message body. - If the user says they will commit or asks only for a commit message, provide commit-message guidance instead of committing. - Before proposing a commit message, inspect the actual diff and recent `git log`. - When recent history contains GitHub merge commits, do not infer commit-message style from merge subjects such as `[#123] ... (#456)`. Open the merge commit with `git show --no-patch --format=full ` and use the individual commit messages in the body, or inspect nearby non-merge commits. diff --git a/AGENT_WORKFLOWS.md b/.agents/workflows.md similarity index 87% rename from AGENT_WORKFLOWS.md rename to .agents/workflows.md index a9a0c45b..5c1a62af 100644 --- a/AGENT_WORKFLOWS.md +++ b/.agents/workflows.md @@ -4,7 +4,7 @@ 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. +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`. @@ -12,12 +12,12 @@ If this file conflicts with `AGENTS.md`, follow `AGENTS.md`. The main agent must run every workflow with this protocol. -1. Read `AGENTS.md`, then `AGENT_ROLES.md`, then this file. +1. Read `AGENTS.md`, then `.agents/roles.md`, then this file. 2. Select one workflow from this file. 3. Create the task packet. 4. Assign only the roles required by the selected workflow. -5. Assign each role a model tier from `AGENT_ROLES.md`. -6. Keep `Primary` roles with the active main agent, and dispatch every `Lightweight` or `Fast` role through the custom agent mapped in `AGENT_ROLES.md`. +5. Assign each role a model tier from `.agents/roles.md`. +6. Keep `Primary` roles with the active main agent, and dispatch every `Lightweight` or `Fast` role through the custom agent mapped in `.agents/roles.md`. 7. Dispatch read-only `Lightweight` or `Fast` roles in parallel only when they do not depend on unfinished edits. 8. Do not complete a required `Lightweight` or `Fast` role directly in `Primary`, including when the dispatch tool would inherit the active `Primary` model. 9. Keep `Primary` editing roles sequential unless the files and ownership boundaries are disjoint. @@ -50,7 +50,7 @@ Stop and ask the user before editing when: | 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 | +| AI role, AGENTS, workflow, or architecture-rule docs | AI workflow maintenance | ## Issue-driven implementation @@ -262,7 +262,7 @@ Report: ## AI workflow maintenance -Use for `AGENTS.md`, `AGENT_ROLES.md`, this file, `.hermes` harness relationship, or AI role routing changes. +Use for `AGENTS.md`, `.agents/roles.md`, this file, `.agents/rules`, or AI role routing changes. ### Role order @@ -271,23 +271,25 @@ Use for `AGENTS.md`, `AGENT_ROLES.md`, this file, `.hermes` harness relationship 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. +Architecture Watcher is required only if the change modifies architecture policy, layer maps, ambiguity gates, or architecture rules. ### Execution -- Keep AI workflow entry files at the repository root. +- 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. -- `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. +- `.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. ### Verification Verification Runner must run: ```sh -git diff --check -- AGENTS.md AGENT_ROLES.md AGENT_WORKFLOWS.md +git diff --check -- AGENTS.md .agents .codex/agents ``` If only Markdown workflow files changed, no iOS build is required. @@ -323,7 +325,7 @@ Do not parallelize: ## Role prompt snippets -Use the activation template from `AGENT_ROLES.md`, then set `` to one of: +Use the activation template from `.agents/roles.md`, then set `` to one of: - `Planner` - `Implementer` @@ -345,14 +347,14 @@ Include the selected workflow name in the task packet `Source` or `Goal` field s - 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` +- Out of scope: Swift/iOS app code, target dependency changes, architecture rule relocation, GitHub Actions changes, app launch. +- Expected changed files: `AGENTS.md`, `.agents/roles.md`, `.agents/workflows.md`, `README.md` - Current owner: repository workflow documentation - Architecture risk: none - Required roles: Planner, Implementer, Code Reviewer, Verification Runner - Model assignment: Planner=Primary, Implementer=Primary, Code Reviewer=code_reviewer (Lightweight), Verification Runner=verification_runner (Lightweight) -- 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 +- Verification: `git diff --check -- AGENTS.md .agents .codex/agents README.md` +- Stop conditions: README `docs/` asset policy changes, Swift/iOS code changes, request to remove architecture rules immediately ``` ### Review-thread follow-up example diff --git a/.codex/agents/architecture_watcher.toml b/.codex/agents/architecture_watcher.toml index 3b153495..6bb92102 100644 --- a/.codex/agents/architecture_watcher.toml +++ b/.codex/agents/architecture_watcher.toml @@ -4,9 +4,9 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and AGENT_ROLES.md before reviewing. -Act only as the Architecture Watcher defined in AGENT_ROLES.md. +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. Do not run, launch, install, boot, or open the app or Simulator. -Return exactly the Architecture Watch Result format from AGENT_ROLES.md. +Return exactly the Architecture Watch Result format from .agents/roles.md. """ diff --git a/.codex/agents/code_reviewer.toml b/.codex/agents/code_reviewer.toml index c39f1acf..bfcf6c39 100644 --- a/.codex/agents/code_reviewer.toml +++ b/.codex/agents/code_reviewer.toml @@ -4,9 +4,9 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and AGENT_ROLES.md before reviewing. -Act only as the Code Reviewer defined in AGENT_ROLES.md. +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 AGENT_ROLES.md with file and line references when possible. +Return exactly the Code Review Result format from .agents/roles.md with file and line references when possible. """ diff --git a/.codex/agents/documentation_writer.toml b/.codex/agents/documentation_writer.toml index 9acd3813..3fea7a9f 100644 --- a/.codex/agents/documentation_writer.toml +++ b/.codex/agents/documentation_writer.toml @@ -4,9 +4,9 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "workspace-write" developer_instructions = """ -Read AGENTS.md and AGENT_ROLES.md before drafting. -Act only as the Documentation Writer defined in AGENT_ROLES.md. +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 AGENT_ROLES.md unless the task packet requests direct Markdown draft output. +Return exactly the Documentation Result format from .agents/roles.md unless the task packet requests direct Markdown draft output. """ diff --git a/.codex/agents/github_ci_analyst.toml b/.codex/agents/github_ci_analyst.toml index a38729cb..b0c8be63 100644 --- a/.codex/agents/github_ci_analyst.toml +++ b/.codex/agents/github_ci_analyst.toml @@ -4,9 +4,9 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "read-only" developer_instructions = """ -Read AGENTS.md and AGENT_ROLES.md before analysis. -Act only as the GitHub/CI Analyst defined in AGENT_ROLES.md. +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 AGENT_ROLES.md. +Return exactly the GitHub CI Result format from .agents/roles.md. """ diff --git a/.codex/agents/verification_runner.toml b/.codex/agents/verification_runner.toml index 2497e33a..ef944ad4 100644 --- a/.codex/agents/verification_runner.toml +++ b/.codex/agents/verification_runner.toml @@ -4,10 +4,10 @@ model = "gpt-5.3-codex-spark" model_reasoning_effort = "medium" sandbox_mode = "workspace-write" developer_instructions = """ -Read AGENTS.md and AGENT_ROLES.md before verification. -Act only as the Verification Runner defined in AGENT_ROLES.md. +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. 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 AGENT_ROLES.md. +Return exactly the Verification Result format from .agents/roles.md. """ diff --git a/.hermes/README.md b/.hermes/README.md deleted file mode 100644 index 623b46eb..00000000 --- a/.hermes/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# Hermes Setup for DevLog - -This directory stores the DevLog-specific Hermes skill source. - -## Skill - -- `skills/devlog-architecture-harness` - -Use this skill before module boundary, DI, repository, Firebase-boundary, widget-data-flow, or architecture documentation work in this repository. - -## Install into Hermes - -Hermes loads installed skills from the user's Hermes skills directory. Keep this repository copy as the project-owned source of truth, then install or copy it into your Hermes profile when needed. - -```sh -mkdir -p ~/.hermes/skills/project -cp -R .hermes/skills/devlog-architecture-harness ~/.hermes/skills/project/devlog-architecture-harness -``` - -After installing, start a new Hermes session and invoke: - -```text -/devlog-architecture-harness -``` - -## Canonical project rules - -`AGENTS.md` is the canonical repo-wide rule file. The Hermes skill should stay aligned with it. - -Detailed DevLog workflow rules live in: - -- `skills/devlog-architecture-harness/references/devlog-architecture-flow.md` -- `skills/devlog-architecture-harness/references/devlog-workflow-rules.md` diff --git a/.hermes/skills/devlog-architecture-harness/SKILL.md b/.hermes/skills/devlog-architecture-harness/SKILL.md deleted file mode 100644 index e1821119..00000000 --- a/.hermes/skills/devlog-architecture-harness/SKILL.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -name: devlog-architecture-harness -description: Use before architecture, modularization, dependency-boundary, DI, repository, Firebase-boundary, or widget-data-flow work in the DevLog_iOS repository. -version: 1.0.0 -metadata: - hermes: - tags: - - swift - - ios - - architecture - - modularization - - devlog - category: project ---- - -# DevLog Architecture Harness - -## When to use - -Use this skill in the repository root when the task touches any of these areas: - -- Module boundary changes. -- File moves across `Application/*` or `Widget/*` targets. -- Import or target dependency changes. -- DI assembler wiring. -- Repository, service, store, or use case contracts. -- Firebase, social login, network, link metadata, notification, or WidgetKit dependency placement. -- Widget snapshot, App Group, or widget deep-link data flow. -- Architecture diagrams, README architecture text, or PR architecture explanation. - -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`. - -## Required project context - -Before editing, read: - -1. `AGENTS.md` -2. `.gemini/styleguide.md` -3. `README.md` -4. `references/devlog-architecture-flow.md` -5. `references/devlog-workflow-rules.md` when the task involves PR review, commits, Xcode project files, CI, widgets, Store reducers, localization, or release/build tooling. - -Then inspect the concrete files and imports related to the requested change. Do not rely on the layer names alone. - -## Procedure - -### 1. Classify the request - -Classify the task as one of these: - -- `mechanical`: unused import cleanup, approved rename fallout, approved access-control adjustment, docs sync. -- `architectural`: module dependency, layer ownership, DI, protocol boundary, external SDK placement, widget data flow. -- `ambiguous`: more than one layer could reasonably own the type or dependency. - -If the task is `ambiguous`, stop and ask the user before editing. - -### 2. Build a boundary note - -For every architecture task, write a short internal boundary note before editing: - -- Current owner. -- Proposed owner. -- Current imports. -- Proposed imports. -- Dependency direction. -- Xcode target/framework dependency impact. -- External SDK exposure. -- Whether user confirmation is required. - -### 3. Apply the ambiguity gate - -Ask the user before editing when: - -- Core vs Domain ownership is unclear. -- A shared type is being moved only because multiple modules need access. -- Firebase/Auth/Firestore/Functions/Messaging-specific logic would leave Infra. -- WidgetCore would depend on Domain, Data, Infra, Persistence, Presentation, or App. -- Widget would depend on Domain, Infra, Persistence, Presentation, or App. -- Widget would use WidgetKit for anything beyond the app-side widget reload bridge. -- Widget sync ownership would move away from the preferred split: Data contracts and snapshot repositories, Widget app-side bridge/snapshot update orchestration, WidgetCore snapshot models/factories/store contracts, and WidgetExtension rendering. -- Persistence would gain widget snapshot generation, WidgetCore, WidgetKit reload, or Widget bridge ownership. -- Presentation would depend on Data, Infra, Persistence, or App. -- Data would gain concrete SDK or storage implementation details. -- Data or Presentation would expand platform SDK usage beyond the existing narrow cancellation-classification or notification-badge patterns. -- Infra would add any Domain dependency, source import, or SDK service contract coupling. -- A same-layer dependency would be injected outside a SwiftUI `View` file in `Application/Presentation`. -- The Presentation `StorePattern` flow or reducer responsibility would change. -- A compile fix requires relaxing the intended architecture. -- The change is outside the requested issue or PR scope. - -### 4. Edit narrowly - -When the boundary is clear: - -- Keep the diff limited to the requested task. -- Preserve existing logic unless the user explicitly approved logic changes. -- Prefer existing DevLog naming and layer patterns. -- Preserve the existing Presentation `StorePattern`: `@MainActor`, `State`, `Action`, `SideEffect`, and `send -> reduce -> run`. -- Do not introduce unrelated cleanup. -- Do not change lockfiles unless dependency resolution is part of the task. - -### 5. Verify - -For Swift/iOS code changes: - -- Follow the repository `AGENTS.md` Verification section. -- Inspect the final diff for architecture-scope drift. - -For docs-only or harness-only changes: - -- Verify file presence. -- Check Markdown for obvious broken structure. -- No iOS build is required. - -## Required response shape - -After completion, report only: - -- Changed files. -- Architecture boundary decision. -- Verification result. -- Any user decisions still needed. - -## Do not do - -- Do not infer project-specific architecture policy from generic Clean Architecture rules when DevLog already has a concrete pattern. -- Do not move domain entities to Core just because multiple modules need them. -- Do not inject same-layer dependencies except from SwiftUI `View` files in `Application/Presentation` into same-layer presentation objects for UI composition. -- Do not collapse the current Widget bridge back into Data, Persistence, App, or WidgetCore without explicit boundary approval. -- Route app-side widget bridge and snapshot update orchestration through Widget. -- Do not hide architecture decisions inside build-fix wording. -- Do not broaden a modularization task into unrelated Firestore, Messaging, or UI safety edits. -- Do not mark work complete if the diff contains unrelated project-file or lockfile churn. diff --git a/AGENTS.md b/AGENTS.md index 539fd8d5..ca5d8505 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,132 +2,25 @@ ## Scope -These instructions apply only to the repository root. - -## 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. - -## Code modification response style - -- When asked to modify code, return only the precise changed locations and the modified code for those locations. -- 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. -- Use `opfic` in new Swift file headers. -- Prefer `<` and `<=` over `>` and `>=` when writing comparisons, if the condition can be expressed clearly that way. - -## DevLog Architecture Harness - -Use this harness before any task that changes module boundaries, file ownership, layer dependencies, DI assembly, repository/service contracts, widget data flow, Firebase dependency placement, or architecture documentation. - -Treat this repository as 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`. - -### Mandatory flow - -1. Read this file, `.gemini/styleguide.md`, `README.md`, and `.hermes/skills/devlog-architecture-harness/references/devlog-architecture-flow.md`. -2. Identify the changed layer and owning target before editing. -3. Inspect the current Swift import direction and Xcode target/framework dependency before deciding. -4. Classify the change as mechanical, architectural, or ambiguous. -5. For ambiguous architecture changes, stop and ask the user before editing. -6. Keep the diff limited to the requested architecture scope. -7. After Swift/iOS code changes, follow the Verification section. -8. Report the changed files, architecture decision, and verification result. - -### Current layer map - -- `Application/Core`: shared app primitives such as DI, logging, query/value types, display options, activity kinds, and lightweight widget bridge values such as `WidgetTodoSnapshot`. Core is shared, but shared access alone is not enough reason to move domain entities into Core. -- `Application/Domain`: entities, repository protocols, use case protocols, and use case implementations. Domain may depend on Core. Domain must not depend on Data, Infra, Persistence, Presentation, App, Widget extension UI, Firebase SDKs, or storage implementations. -- `Application/Data`: repository implementations, DTOs, mappers, data-layer protocols for external services/stores, widget snapshot repository implementations, and widget sync/updater contracts. Data may depend on Domain and Core. Data should not own concrete widget sync handlers, event bus implementations, WidgetCore snapshot model/factory usage, or WidgetKit reload behavior, and should not gain direct Firebase, GoogleSignIn, WidgetKit, or concrete storage implementation details unless the user explicitly approves the boundary change. -- `Application/Infra`: Firebase, social login, network, link metadata, messaging, and platform service implementations. Infra may depend on Data and Core. Infra must not depend on Domain even if a manifest-only target dependency exists. Firebase/Auth/Firestore/Functions/Messaging-specific behavior belongs here unless the user approves another boundary. -- `Application/Persistence`: local persistence, user defaults, image store, and non-widget app persistence. Persistence may depend on Data and Core. Widget snapshot generation, widget snapshot persistence orchestration, and WidgetKit reload behavior belong to Widget. -- `Application/Presentation`: SwiftUI views, view models, coordinators, UI state structures, presentation-only helpers, and narrow presentation-scoped platform side effects such as notification badge updates. Presentation may depend on Domain and Core. It must not depend on Data, Infra, Persistence, or App. -- `Application/Widget`: app-side bridge between the app runtime and widget system, widget sync event bus implementation, widget sync/session handlers, auth-session sync provider, widget snapshot generation/persistence orchestration, WidgetKit reload bridge, and `WidgetAssembler`. Widget may depend on Data, Core, and WidgetCore. It must not depend on Domain, Infra, Persistence, Presentation, or App without explicit user approval. -- `Application/App`: composition root, app lifecycle, app delegate, app-level routing, assembler wiring, and app target ownership for widget extension embedding. App may import concrete layers to assemble the dependency graph. -- `Widget/WidgetCore`: widget snapshot models, factories, keys, app-group constants/defaults store, deep links, and widget-only pure helpers. WidgetCore may depend on Core. It must not depend on Domain, Data, Infra, Persistence, Presentation, App, or Widget without explicit user approval. -- `Widget/WidgetExtension`: WidgetKit UI, widget providers, entries, timelines, and extension resources. It should consume WidgetCore outputs rather than app/domain services directly. - -### Layer-internal dependency injection - -- Do not inject dependencies between types that belong to the same layer. -- This applies to initializer injection, stored-property injection, environment injection, and resolving same-layer types through `DIContainer`. -- The only allowed exception is a SwiftUI `View` file in `Application/Presentation` receiving same-layer presentation objects such as a ViewModel, Coordinator, or Store for UI composition. -- The exception does not apply to non-View files in Presentation, and does not apply to Core, Domain, Data, Infra, Persistence, Widget, App, WidgetCore, or WidgetExtension. - -### StorePattern flow - -- Preserve the existing Presentation `StorePattern`. -- `StorePattern` is `@MainActor` and uses `State`, `Action`, `SideEffect`, and the `send -> reduce -> run` flow. -- Reducers should compute state and return side effects. -- I/O belongs in `run` or injected services, not in reducer state computation. -- Ask before changing reducer, side-effect, or ViewModel responsibility boundaries. - -### Ambiguity gate - -Ask the user before editing when any of these are true: - -- A type could plausibly live in both Core and Domain. -- A shared type is being moved only because multiple modules need access to it. -- A new target dependency would make a lower-level module know a higher-level module. -- A build fix would be achieved by loosening an architecture boundary. -- Firebase, GoogleSignIn, AuthenticationServices, UserNotifications, LinkPresentation, Network, WidgetKit, or storage implementation details would move to another layer. -- A repository protocol, service protocol, assembler, or DI ownership boundary would change. -- WidgetCore would start depending on app/domain/data implementation concepts. -- Widget would start depending on Domain, Infra, Persistence, Presentation, or App. -- Widget would use WidgetKit for anything beyond the app-side widget reload bridge. -- Widget sync ownership would move away from the preferred split: Data contracts and snapshot repositories, Widget app-side bridge/snapshot update orchestration, WidgetCore snapshot models/factories/store contracts, and WidgetExtension rendering. -- Persistence would gain widget snapshot generation, WidgetCore, WidgetKit reload, or Widget bridge ownership. -- Data or Presentation would expand platform SDK usage beyond the existing narrow cancellation-classification or notification-badge patterns. -- Infra would add any Domain dependency, source import, or SDK service contract coupling. -- A same-layer dependency would be injected outside a SwiftUI `View` file in `Application/Presentation`. -- The requested change suggests cleanup outside the current issue or PR scope. - -### Safe mechanical changes - -These may proceed after inspection when they do not change architecture meaning: - -- Removing unused imports. -- Updating import statements after an already-approved file move. -- Fixing access control needed by an already-approved module boundary. -- Updating tests to match an already-approved public contract. -- Editing docs to reflect the current verified architecture. - -## Verification - -- If Swift files change, run Homebrew SwiftLint (`swiftlint`) on the changed Swift files. -- For production Swift files, use the applicable source `.swiftlint.yml` config. -- For test Swift files, use `.swiftlint-tests.yml` or the module `Tests/.swiftlint.yml` that inherits from it. Do not lint tests with the root production config. -- If iOS project code changes, verify with Xcode Local MCP when it is available. -- If Xcode Local MCP is unavailable, state that explicitly before using a fallback. -- Do not claim architecture work is complete without checking the diff scope. -- Do not spend time on unrelated generated project or lockfile churn. Keep generated workspace/project and `Package.resolved` changes out of source control unless they are part of an explicitly approved dependency-lock policy. - -## Git and commit rules - -- Commit messages must start with a short prefix used by recent local commits, such as `feat`, `fix`, `refactor`, `chore`, `test`, `docs`, `ui`, or `rollback`. -- Write commit message prose in Korean. -- Keep implementation names such as `ToastPresenter`, `toastHost`, `MainView`, `Presentation`, file paths, commands, branch names, and commit hashes in their original form. -- Do not translate implementation names into Korean unless the user explicitly asks for a user-facing Korean label. -- Do not write a commit message body. -- When checking recent commit-message style, do not infer local commit style from GitHub merge or squash-merge subjects such as `[#123] ... (#456)`. -- For squash-merge commits, inspect the commit body and use the individual bullet commit messages as the style reference. - -## Canonical project rules - -- DevLog-specific working rules belong in this repository, not in global agent memory. -- Treat `AGENTS.md` and `.hermes/skills/devlog-architecture-harness` as the canonical DevLog AI working rules. -- If global memory conflicts with this repository, follow this repository. -- For PR, commit, Xcode project, CI, widget, Store, localization, or release workflow details, read `.hermes/skills/devlog-architecture-harness/references/devlog-workflow-rules.md`. +- These instructions apply only to the repository root. +- Read every route that matches the current task. Routes are cumulative. + +## Required routing + +| Task | Required document | +| --- | --- | +| Every task | `.agents/rules/general.md` | +| Non-trivial planning, implementation, review, or verification | `.agents/roles.md` | +| Repeatable role-based execution | `.agents/workflows.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` | + +## Routing rules + +- `AGENTS.md` is the repository entrypoint and routing source. +- `.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 `.gemini/styleguide.md` and `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. +- If repository-local instructions conflict with global memory, follow the repository-local instructions.