|
| 1 | +--- |
| 2 | +name: devlog-architecture-harness |
| 3 | +description: Use before architecture, modularization, dependency-boundary, DI, repository, Firebase-boundary, or widget-data-flow work in the SwiftUI_DevLog repository. |
| 4 | +version: 1.0.0 |
| 5 | +metadata: |
| 6 | + hermes: |
| 7 | + tags: |
| 8 | + - swift |
| 9 | + - ios |
| 10 | + - architecture |
| 11 | + - modularization |
| 12 | + - devlog |
| 13 | + category: project |
| 14 | +--- |
| 15 | + |
| 16 | +# DevLog Architecture Harness |
| 17 | + |
| 18 | +## When to use |
| 19 | + |
| 20 | +Use this skill in the repository root when the task touches any of these areas: |
| 21 | + |
| 22 | +- Module boundary changes. |
| 23 | +- File moves across `Application/DevLog*` or `Widget/DevLog*` targets. |
| 24 | +- Import or target dependency changes. |
| 25 | +- DI assembler wiring. |
| 26 | +- Repository, service, store, or use case contracts. |
| 27 | +- Firebase, social login, network, link metadata, notification, or WidgetKit dependency placement. |
| 28 | +- Widget snapshot, App Group, or widget deep-link data flow. |
| 29 | +- Architecture diagrams, README architecture text, or PR architecture explanation. |
| 30 | + |
| 31 | +This repository is an Xcode workspace-based modular iOS app. There is no root `Package.swift`; modules are separate `.xcodeproj` entries under `DevLog.xcworkspace`. |
| 32 | + |
| 33 | +## Required project context |
| 34 | + |
| 35 | +Before editing, read: |
| 36 | + |
| 37 | +1. `AGENTS.md` |
| 38 | +2. `.gemini/styleguide.md` |
| 39 | +3. `README.md` |
| 40 | +4. `references/devlog-architecture-flow.md` |
| 41 | +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. |
| 42 | + |
| 43 | +Then inspect the concrete files and imports related to the requested change. Do not rely on the layer names alone. |
| 44 | + |
| 45 | +## Procedure |
| 46 | + |
| 47 | +### 1. Classify the request |
| 48 | + |
| 49 | +Classify the task as one of these: |
| 50 | + |
| 51 | +- `mechanical`: unused import cleanup, approved rename fallout, approved access-control adjustment, docs sync. |
| 52 | +- `architectural`: module dependency, layer ownership, DI, protocol boundary, external SDK placement, widget data flow. |
| 53 | +- `ambiguous`: more than one layer could reasonably own the type or dependency. |
| 54 | + |
| 55 | +If the task is `ambiguous`, stop and ask the user before editing. |
| 56 | + |
| 57 | +### 2. Build a boundary note |
| 58 | + |
| 59 | +For every architecture task, write a short internal boundary note before editing: |
| 60 | + |
| 61 | +- Current owner. |
| 62 | +- Proposed owner. |
| 63 | +- Current imports. |
| 64 | +- Proposed imports. |
| 65 | +- Dependency direction. |
| 66 | +- Xcode target/framework dependency impact. |
| 67 | +- External SDK exposure. |
| 68 | +- Whether user confirmation is required. |
| 69 | + |
| 70 | +### 3. Apply the ambiguity gate |
| 71 | + |
| 72 | +Ask the user before editing when: |
| 73 | + |
| 74 | +- Core vs Domain ownership is unclear. |
| 75 | +- A shared type is being moved only because multiple modules need access. |
| 76 | +- Firebase/Auth/Firestore/Functions/Messaging-specific logic would leave Infra. |
| 77 | +- WidgetCore would depend on Domain, Data, Infra, Persistence, Presentation, or App. |
| 78 | +- Presentation would depend on Data, Infra, Persistence, or App. |
| 79 | +- Data would gain concrete SDK or storage implementation details. |
| 80 | +- The Presentation `Store` flow or reducer responsibility would change. |
| 81 | +- A compile fix requires relaxing the intended architecture. |
| 82 | +- The change is outside the requested issue or PR scope. |
| 83 | + |
| 84 | +### 4. Edit narrowly |
| 85 | + |
| 86 | +When the boundary is clear: |
| 87 | + |
| 88 | +- Keep the diff limited to the requested task. |
| 89 | +- Preserve existing logic unless the user explicitly approved logic changes. |
| 90 | +- Prefer existing DevLog naming and layer patterns. |
| 91 | +- Preserve the existing Presentation `Store` pattern: `@MainActor`, `State`, `Action`, `SideEffect`, and `send -> reduce -> run`. |
| 92 | +- Do not introduce unrelated cleanup. |
| 93 | +- Do not change lockfiles unless dependency resolution is part of the task. |
| 94 | + |
| 95 | +### 5. Verify |
| 96 | + |
| 97 | +For Swift/iOS code changes: |
| 98 | + |
| 99 | +- Use Xcode Local MCP for the build. |
| 100 | +- If Xcode Local MCP is unavailable, say so and ask before using another path unless the user already approved a fallback. |
| 101 | +- Inspect the final diff for architecture-scope drift. |
| 102 | + |
| 103 | +For docs-only or harness-only changes: |
| 104 | + |
| 105 | +- Verify file presence. |
| 106 | +- Check Markdown for obvious broken structure. |
| 107 | +- No iOS build is required. |
| 108 | + |
| 109 | +## Required response shape |
| 110 | + |
| 111 | +After completion, report only: |
| 112 | + |
| 113 | +- Changed files. |
| 114 | +- Architecture boundary decision. |
| 115 | +- Verification result. |
| 116 | +- Any user decisions still needed. |
| 117 | + |
| 118 | +## Do not do |
| 119 | + |
| 120 | +- Do not infer project-specific architecture policy from generic Clean Architecture rules when DevLog already has a concrete pattern. |
| 121 | +- Do not move domain entities to Core just because multiple modules need them. |
| 122 | +- Do not hide architecture decisions inside build-fix wording. |
| 123 | +- Do not broaden a modularization task into unrelated Firestore, Messaging, or UI safety edits. |
| 124 | +- Do not mark work complete if the diff contains unrelated project-file or lockfile churn. |
0 commit comments