| name | architecture-refactor |
| description | Use for folder movement, layer boundaries, and domain/application/runtime/adapters refactors in Gantry. |
Architecture Refactor
Use this skill when a task moves files, changes layer ownership, changes imports across domain, application, runtime, or adapters, or updates architectural boundaries.
Required Workflow
- Read
docs/architecture/codebase-refactor-principles.md, docs/architecture/codex-harness.md, and relevant docs/decisions/ records before editing.
- Keep
domain provider-free and channel-free. Keep provider SDKs, channel SDKs, Postgres, CLI, HTTP, browser, and sandbox implementations behind ports or adapters.
- Prefer clean deletion of obsolete paths over compatibility shims unless a decision record explicitly approves a transition path.
- Use
gantry-change-contract when the refactor needs a Surface Impact Matrix, cleanup search, or no-legacy handoff evidence.
- Update
.codex/architecture-map.json only when the desired ownership model changes, not to hide current debt.
- Run
python3 .codex/scripts/check_architecture.py and python3 .codex/scripts/check_task_completion.py before final handoff when possible.
Evidence To Provide
- Architecture docs or decision records read.
- Boundary rule affected.
- Tests or verification command proving the refactor did not add provider leakage.