@laitszkin/apollo-toolkit 3.12.1 → 3.13.0

package/iterative-code-quality/SKILL.md

@@ -1,112 +0,0 @@
----
-name: iterative-code-quality
-description: >-
-  Improve an existing codebase through repeated evidence-based repository-wide
-  scans, module-by-module deep-read coverage, and behavior-safe refactors until
-  no known in-scope actionable quality issue or unvisited in-scope module
-  remains: clarify poor names, simplify or extract reusable functions, split
-  mixed-responsibility code, repair stale or missing logs, and add high-value
-  tests where guardrails are missing, while preserving intended business
-  behavior and the system's macro architecture. Use when users ask for
-  comprehensive refactoring, code cleanup, maintainability hardening, naming
-  cleanup, log alignment, or test coverage improvement across a repository.
----
-
-# Iterative Code Quality
-
-## Dependencies
-
-- Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
-- Conditional: `systematic-debug` when a newly added or existing test exposes a real business-logic defect that must be fixed at the true owner.
-- Optional: `improve-observability` for non-trivial telemetry design.
-- Fallback: If required completion dependencies are unavailable, finish code and validation first, then report exactly which documentation or constraint-sync action could not run.
-
-## Standards
-
-- Evidence: Read repository docs, project constraints, source, tests, logs, build scripts, entrypoints, and nearby abstractions before editing; every refactor and every new test must be justified by code context.
-- Execution: Run a continuous three-step loop of full-codebase scan → choose this round's jobs and refactor → if and only if the latest full-codebase scan is clear, update docs and constraints; otherwise return to scanning immediately. Maintain a module inventory and coverage ledger so every in-scope module receives a job-oriented deep-read iteration before completion. Do not treat jobs as workflow steps. Do not produce a completion report while any known in-scope actionable issue or unvisited in-scope module remains, unless the remaining surface is explicitly classified with evidence as blocked, unsafe, user-owned active work, speculative, low-value, or approval-dependent.
-- Quality: Resolve as many inherited quality problems as safely possible without changing intended behavior or the system's macro architecture. Do not require pre-existing tests before every safe refactor; if an area is high-risk and weakly guarded, add the missing guardrails as part of the work instead of treating the area as untouchable.
-- Output: Return iteration-by-iteration decisions, selected jobs, module coverage status, changed files, behavior-preservation evidence, tests and guardrails added, validation results, and docs/constraint sync status only after the latest scan shows no remaining known actionable in-scope issue and no unvisited in-scope module.
-
-## Mission
-
-Leave the repository materially cleaner by continuously scanning the whole codebase, landing the highest-value safe refactors available at each moment, and repeating until there is no known in-scope actionable quality gap left to fix.
-
-For this skill, `macro architecture` means the system's top-level runtime shape and overall operating logic: major subsystems, top-level execution model, deployment/runtime boundaries, persistence model, service boundaries, and the end-to-end way the whole system works. Ordinary module interactions, helper extraction, local responsibility moves, internal call-boundary cleanup, and local module splits do not count as macro-architecture changes by themselves.
-
-## Three-Step Loop
-
-### 1) Scan the repository
-
-- Read root guidance first: `AGENTS.md/CLAUDE.md`, `README*`, package manifests, task runners, CI/test config, and major project docs.
-- Map runtime entrypoints, domain modules, external integrations, logging utilities, and current test surfaces.
-- Exclude generated, vendored, lock, build-output, fixture, or snapshot files unless evidence shows they are human-maintained source.
-- Build or refresh a concrete repository-wide backlog of known actionable quality issues.
-- Build or refresh a module inventory and coverage ledger; every in-scope module starts as unvisited until it has received a job-oriented deep-read iteration with callers, callees, tests, logs, relevant contracts, and each available job lens inspected.
-- Re-scan the full codebase after every landed iteration, not only the files just changed.
-- Load `references/repository-scan.md` for the scan checklist and backlog shaping rules.
-- Load `references/module-coverage.md` for module inventory, job-oriented deep-read coverage, easy-first ordering, and completion rules.
-
-### 2) Choose this round's jobs and refactor
-
-- Choose jobs only after the latest full-codebase scan. Jobs are optional execution directions, not ordered workflow steps.
-- Treat module scanning and job choice as one linked activity: inspect the selected module through every available job lens before deciding which jobs actually land in this round.
-- Select the smallest set of jobs that can safely improve the currently selected module or module cluster under current guardrails.
-- If the user has clearly indicated that a touched area is their active in-progress change, treat that area as blocked for this skill, record the evidence, and continue with other in-scope modules instead of modifying or debugging it.
-- Before choosing or deferring a refactor, explicitly assess refactor confidence as a combination of the agent's own ability to understand and complete the task, the objective safety net from tests and other guardrails, the clarity of rollback or repair paths, and the task's inherent difficulty. Do not treat difficulty alone as low confidence; when strong tests guard the behavior, use them to support bolder changes because failures can be driven back to green.
-- Prefer easy-first module ordering: start from low-risk, high-confidence modules when doing so builds context, tests, naming clarity, or seams that make harder modules safer later.
-- Do not keep revisiting familiar modules while other in-scope modules remain unvisited unless the familiar module blocks the next unvisited module's safe deep read.
-- Prefer smaller, high-confidence refactors that reduce risk and prepare the ground for deeper later cleanup.
-- If a desired refactor is high-risk and weakly guarded, make guardrail-building part of this round instead of stopping.
-- If a file feels too coupled, too central, or too risky for a direct rewrite, do staged unlock work rather than declaring the area blocked.
-- Read all directly affected callers, tests, interfaces, and logs before editing.
-- Validate from narrow to broad after each bounded round, then perform a full-codebase stage-gate decision:
-  - if any known in-scope actionable issue still remains or any in-scope module has not received a deep-read iteration, return to Step 1;
-  - only continue to Step 3 when the latest scan is clear.
-
-Load references for this step only as needed:
-
-- `references/module-coverage.md` for choosing the next module and proving every in-scope module has been deeply read through the available-job lenses.
-- `references/job-selection.md` for next-job choice conditions and tie-breakers.
-- `references/naming-and-simplification.md` for naming cleanup and function simplification/extraction.
-- `references/module-boundaries.md` for single-responsibility module cleanup.
-- `references/logging-alignment.md` for stale or missing log repair.
-- `references/testing-strategy.md` for unit, property, integration, and E2E test strategy.
-- `references/coupled-core-file-strategy.md` for staged unlock work on large coupled or apparently core files.
-- `references/iteration-gates.md` for validation cadence, stage-gate rules, and stop criteria.
-
-### 3) Update project documents and constraints
-
-Only enter this step when the latest full-codebase scan confirms there is no remaining known actionable in-scope quality issue and every in-scope module has received a deep-read iteration, except items explicitly classified as blocked, unsafe, speculative, low-value, excluded, or approval-dependent.
-
-- Run `align-project-documents` when README, architecture notes, setup docs, debugging docs, or test guidance may have drifted.
-- Run `maintain-project-constraints` to verify `AGENTS.md/CLAUDE.md` still matches the repository's real architecture, business flow, commands, and conventions.
-- Update only the documentation and constraints that changed in reality because of the refactor.
-
-## Hard Guardrails
-
-- Do not change intended business logic while refactoring, except to fix a real defect exposed by tests and verified at the true owner.
-- Do not change the system's macro architecture unless the user explicitly expands scope.
-- Do not use one-off scripts to rewrite product code.
-- Do not stop early just because a file is large, central, or historically fragile; if a safe unlock step exists, that is the next job.
-- Do not stop before every in-scope module has been inventoried, deeply read, and either improved, validated as clear, or explicitly deferred/excluded with evidence.
-- Do not touch user-owned active edits; classify them as blocked with evidence and continue elsewhere.
-- Do not weaken tests to make a refactor pass; fix the real defect or update stale expectations to stable invariants.
-- Do not add style-only churn that does not improve naming, modularity, observability, reuse, or guardrail strength.
-- Do not add unreliable E2E coverage when a controlled integration or characterization test can prove the same risk more safely.
-
-## Completion Report
-
-Only report completion after Step 3 is done, the latest Step 1 scan is clear, and the module coverage ledger has no unvisited in-scope module.
-
-Return:
-
-1. Iterations completed and the jobs selected in each iteration.
-2. Stage-gate verdict after each full-codebase re-scan.
-3. Module coverage ledger summary: modules deep-read, improved, validated-clear, deferred, or excluded.
-4. Key files changed and the quality issue each change resolved.
-5. Business behavior preservation evidence.
-6. Tests or other guardrails added or updated, including property/integration/E2E `N/A` reasons where relevant.
-7. Validation commands and results.
-8. Documentation and `AGENTS.md/CLAUDE.md` synchronization status.
-9. Remaining blocked or approval-dependent items, if any.

package/iterative-code-quality/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Iterative Code Quality"
-  short_description: "Refactor names, functions, modules, logs, and tests in repeated behavior-safe passes"
-  default_prompt: "Use $iterative-code-quality as a strict three-step loop. Step 1: scan the full repository, refresh the actionable quality backlog, and maintain a module inventory plus coverage ledger. Step 2: choose this round's module or bounded module cluster, scan it through every available job lens, and only then decide which jobs actually land now; start from the easiest useful unvisited modules, jobs are selectable directions rather than workflow steps, and assess refactor confidence from your own ability to understand and complete the change, task complexity, guardrail strength, rollback or repair paths, and whether tests can drive accidental breakage back to green. If a high-risk area is weakly guarded add the missing tests or other guardrails instead of stopping; if strong tests guard the behavior, use them to justify bolder safe refactors rather than avoiding the work. If a file is too coupled or too central for direct cleanup, switch to staged unlock work and keep progressing. After validation, run a full-codebase stage-gate; if any known in-scope actionable issue remains or any in-scope module has not received a job-oriented deep-read iteration, go back to Step 1 immediately. Step 3: only when the latest full-codebase scan is clear and every in-scope module is deeply read through the available-job lenses, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md/CLAUDE.md. Preserve intended business behavior and the system's macro architecture, keep the guarded test surface green, and do not write a completion report while actionable gaps or unvisited modules still exist."

package/iterative-code-quality/references/coupled-core-file-strategy.md

@@ -1,73 +0,0 @@
-# Staged Strategy For Large Coupled Or Apparently Core Files
-
-## Purpose
-
-Teach the agent how to keep making progress when a file feels too central, too coupled, or too risky to refactor directly.
-
-The correct response is usually not "stop". The correct response is "find the next unlock step".
-
-## Core rule
-
-A large coupled file is a **decomposition signal**, not a **completion blocker**.
-
-If a safe, behavior-preserving unlock step exists under current guardrails, take that step now instead of deferring the whole area.
-
-If guardrails are too weak for direct cleanup, strengthening them is itself the next unlock step.
-
-## First questions to ask
-
-When a file feels untouchable, ask:
-
-- Which parts are pure logic and which parts are side effects?
-- Which names or local concepts are blocking understanding?
-- Which behavior can be locked down with characterization tests?
-- Which dependency seams can be introduced without changing behavior?
-- Which caller groups or workflow slices can be isolated first?
-- Which refactor would most reduce the cost of the next refactor?
-
-## Typical unlock sequence
-
-Pick one or more of these, in the order justified by current evidence:
-
-1. Add characterization or regression tests around current behavior.
-2. Rename confusing variables, flags, intermediate states, and helper names.
-3. Extract constants, schemas, types, and small pure transformations.
-4. Separate read path from write path, or decision logic from side effects.
-5. Isolate external calls, persistence, and logging behind clearer seams.
-6. Group callers by responsibility and split one slice at a time.
-7. Move one coherent responsibility into a new internal module.
-8. Re-scan and decide whether a deeper split is now safer.
-
-## What not to do
-
-Avoid these anti-patterns:
-
-- declaring the area blocked just because it is important,
-- attempting a full rewrite before guardrails exist,
-- preserving obvious local design debt only because the file is central,
-- escalating ordinary internal decomposition into a fake macro-architecture concern,
-- mixing unlock work with unrelated style churn.
-
-## Choosing the next step
-
-Prefer the next step that maximizes:
-
-1. combined confidence from the agent's own ability, code understanding, existing tests, or quickly addable tests,
-2. leverage for future deeper cleanup,
-3. reduction in coupling or cognitive load,
-4. low risk to current business behavior.
-
-If two steps are both safe, choose the one that makes the next iteration easier.
-
-If the file is high-risk and under-tested, prefer adding the smallest useful characterization tests before attempting deeper structural edits. If the file is high-risk but well-guarded, do not stop only because the change is difficult; use the guardrails to validate the agent's work and repair any accidental breakage.
-
-## Completion rule for coupled files
-
-Do not ask "Can I solve the whole file now?"
-
-Ask:
-
-- "Can I make this file meaningfully easier to change in the next iteration?"
-- "Can I reduce coupling, clarify ownership, or improve guardrails right now?"
-
-If the answer is yes, continue iterating.

package/iterative-code-quality/references/iteration-gates.md

@@ -1,127 +0,0 @@
-# Iteration Gates And Stopping Criteria
-
-## Pass discipline
-
-Each iteration must have:
-
-- a selected module or bounded module cluster,
-- a concrete quality target,
-- an explicit record of which job lenses were checked during the deep read,
-- a bounded file/symbol scope,
-- one or more selected execution directions,
-- a confidence assessment covering the agent's own ability to complete the refactor, the task's inherent difficulty, objective guardrail strength, and rollback or repair paths,
-- expected behavior-neutral outcome,
-- validation plan,
-- rollback point if evidence contradicts the change.
-
-An iteration is not "one work type", and it also does not need to include every direction every time. Within the selected scope, choose the subset of directions that has the best current confidence and leverage: naming, simplification, module boundaries, logging, and/or tests.
-
-Confidence is not a synonym for "easy". Assess whether the agent has enough understanding, skill, local context, tests, validation commands, and recovery path to complete the refactor safely. A hard task can still be high-confidence when strong tests, characterization coverage, and clear rollback let the agent repair mistakes by making the guarded behavior green again.
-
-Avoid starting a broad second iteration before validating the first, but do not stop after a validated iteration if known actionable quality issues remain anywhere in the in-scope codebase.
-
-Do not stop after a validated iteration if any in-scope module remains unvisited in the module coverage ledger.
-
-## Validation cadence
-
-Run validation from narrow to broad:
-
-1. Formatter or type check for touched files when available.
-2. Unit tests for touched helpers and modules.
-3. Integration tests for affected chains.
-4. Broader suite or build once multiple passes interact.
-
-If validation fails:
-
-- determine whether the failure is pre-existing, stale test expectation, test isolation issue, or real product bug,
-- fix the true owner,
-- keep regression coverage for real defects,
-- do not mask failures by weakening assertions.
-
-If validation passes and the guardrails meaningfully cover the changed behavior, do not keep a known quality issue in place purely because of subjective confidence concerns. Reassess whether the agent has enough capability and objective support to proceed; if yes, continue, and if no, choose the smallest guardrail or unlock step that would make the next refactor credible.
-
-The final stopping condition also requires the relevant guarded test surface to be green; a partially red repository is not a completed refactor outcome.
-
-## Re-scan after each iteration
-
-Inspect the full known quality backlog for:
-
-- modules that are still unvisited or only shallowly read,
-- modules that were read but not yet checked against every available job lens,
-- new naming drift from moved or extracted concepts,
-- duplicated logic that remains after extraction,
-- module boundaries that are still mixed,
-- logs that now use stale names,
-- tests that cover only the happy path,
-- documentation or `AGENTS.md/CLAUDE.md` drift.
-
-Then choose the next execution directions with these priorities:
-
-1. highest combined confidence from agent capability, code understanding, guardrails, and recovery path,
-2. strongest leverage for later deeper cleanup,
-3. lowest business-risk path toward broader system improvement.
-
-Use `references/job-selection.md` to convert those priorities into a concrete next-job choice.
-
-## Stage-gate after each iteration
-
-After every validated iteration, run a deliberate full-codebase decision pass:
-
-1. Re-scan the repository and refresh the known quality backlog.
-2. Refresh the module coverage ledger and identify unvisited in-scope modules.
-3. Ask whether any known in-scope actionable issue still remains.
-4. If yes, decide whether it should be addressed in the very next iteration or whether first-step unlock work is needed.
-5. If the obstacle is a large, coupled, or central file, do not stop there; switch to staged unlock work and continue.
-6. Only declare the repository iteration-complete when the re-scan shows no remaining actionable in-scope issue and no unvisited in-scope module except items that are explicitly deferred or excluded under the allowed stop categories.
-
-This stage-gate is mandatory. A validated local change does not by itself mean the repository is done.
-
-## Continue when
-
-Repeat the cycle when:
-
-- any known in-scope actionable quality issue remains unresolved,
-- any in-scope module remains unvisited,
-- high-impact unclear names remain,
-- duplicated or hard-coded workflows still have safe extraction paths,
-- a module still mixes distinct responsibilities and can be split locally,
-- logs are still misleading or missing at critical decisions,
-- high-value business logic remains untested and is testable.
-
-Do not produce a final completion report while any item in this section is true. Continue with the next bounded iteration instead.
-
-Prefer gradual outside-in progress: boundary cleanup, naming clarity, and guardrail strengthening should often come before deeper internal rewrites because they make the deeper work safer later.
-
-## Stop when
-
-Stop only when there are no unresolved known in-scope actionable issues. Any remaining candidates must be explicitly classified as one of:
-
-- low-value style preference,
-- speculative without concrete evidence,
-- public contract migrations,
-- macro-architecture changes,
-- product behavior changes needing user approval,
-- blocked by unavailable credentials, unstable external systems, or missing documentation,
-- untestable with the current repository tooling and too risky to change safely.
-
-If a remaining candidate cannot be placed in one of these categories, it is still an actionable gap and the agent must continue iterating rather than complete the task.
-
-If an in-scope module has not received a deep-read iteration, it is still an actionable coverage gap even when the already-read modules look clean.
-
-## Completion evidence
-
-The final report should make the stopping point auditable:
-
-- passes completed,
-- execution directions selected per iteration,
-- module or module cluster covered per iteration,
-- job lenses checked per iteration,
-- final module coverage ledger,
-- stage-gate verdict after each full-codebase re-scan,
-- validation commands and outcomes,
-- confirmation that the guarded test surface is green after the refactor,
-- tests added by risk category,
-- behavior-preservation evidence,
-- docs and constraints sync status,
-- proof that the latest scan found no known actionable in-scope quality issues,
-- deferred items with reason and required approval, dependency, or safety constraint.

package/iterative-code-quality/references/job-selection.md

@@ -1,78 +0,0 @@
-# Job Selection Guide
-
-## Purpose
-
-Help the agent choose the next execution direction after each full-codebase re-scan.
-
-These are job-selection rules for Step 2 of the main skill loop. They are not workflow steps.
-
-The goal is not to force one permanent order. The goal is to choose the next job that most safely improves the selected module or module cluster and unlocks later work.
-
-Before choosing, the agent should first scan the selected module through every available job lens. Job selection happens after that scan; it is not a substitute for that scan.
-
-## Available jobs
-
-- naming cleanup
-- function simplification / extraction
-- module-boundary cleanup
-- logging alignment
-- test addition
-- staged unlock work
-
-## Choose `naming cleanup` when
-
-- confusing names are the main thing blocking understanding,
-- flags, units, lifecycle states, or ownership terms are misleading,
-- better naming would clearly reduce the risk of a later deeper refactor.
-
-## Choose `function simplification / extraction` when
-
-- duplicated logic exists across multiple call sites,
-- one function mixes too many concerns,
-- control flow is currently the main complexity bottleneck,
-- extracting a helper would make the next test or split easier.
-
-## Choose `module-boundary cleanup` when
-
-- one file or module clearly has multiple reasons to change,
-- local responsibilities are already visible enough to separate,
-- a safe split would reduce repeated touching of unrelated concerns.
-
-## Choose `logging alignment` when
-
-- stale or missing diagnostics are the main blocker to safe validation,
-- later refactors would be safer if branch decisions and outcomes were easier to observe,
-- observability drift is currently hiding the real ownership model.
-
-## Choose `test addition` when
-
-- the target area is high-risk and weakly guarded,
-- desired cleanup is blocked mainly by missing behavior locks,
-- coupling spans multiple modules and needs characterization before change,
-- regression risk is too high to justify deeper refactors without stronger coverage.
-
-## Choose `staged unlock work` when
-
-- the file feels too central or too coupled for direct cleanup,
-- no safe full refactor exists yet, but a preparatory step does,
-- you can reduce risk through naming, seam extraction, type extraction, side-effect isolation, or caller grouping,
-- the best next move is to make a future refactor cheaper rather than solve the whole area now.
-
-## Tie-breakers
-
-If multiple jobs are plausible, prefer the one that:
-
-1. increases safety for the next iteration,
-2. reduces cognitive load fastest,
-3. removes the strongest blocker to a deeper future refactor,
-4. helps an unvisited module reach deep-read coverage,
-5. matches the agent's self-assessed ability to understand, execute, and repair the change under current evidence,
-6. preserves behavior with the clearest available guardrails.
-
-## Hard rule
-
-If a high-risk area lacks enough guardrails, `test addition` or another guardrail-building job should usually win before a deeper structural refactor.
-
-If the area is difficult but the agent can explain the behavior, affected contracts, rollback path, and available tests clearly, do not downgrade confidence just because the refactor is non-trivial. Strong guardrails mean accidental breakage should be repaired by returning the test suite to green, not avoided by leaving an actionable quality issue in place.
-
-If any in-scope module remains unvisited, choose jobs that help the next easiest useful unvisited module become deeply read, improved, or validated-clear before spending another round on already-familiar areas.

package/iterative-code-quality/references/logging-alignment.md

@@ -1,67 +0,0 @@
-# Logging Alignment And Missing Observability
-
-## Purpose
-
-Keep logs and diagnostics synchronized with the real code path while preserving behavior.
-
-## Stale log signals
-
-Update logs when they:
-
-- mention retired owners, lifecycle stages, resource names, or field names,
-- describe a branch that no longer matches the condition,
-- use generic text like `failed` without the operation or reason,
-- report aggregate success without identifiers that let operators reconcile details,
-- keep compatibility-era names after code has moved to a new canonical model,
-- conflict with structured field names or metrics in the same path.
-
-## Missing log criteria
-
-Add logs only where they answer a concrete debugging question.
-
-High-value locations:
-
-- workflow start and final outcome for long-running jobs,
-- branch selection or skipped work with reason code,
-- validation rejection with safe context,
-- external dependency outcome including status class, retry count, request id, and latency when available,
-- persistence side effect or emitted command,
-- rollback, compensation, idempotency, duplicate, or replay decisions.
-
-Low-value locations:
-
-- every line of a tight loop,
-- logs that only restate the function name,
-- dumping raw payloads,
-- duplicating an exception already logged with equal context,
-- noisy success logs in hot paths without operational value.
-
-## Structured field rules
-
-- Reuse the project's existing logger, field naming, metric naming, and trace conventions.
-- Prefer stable identifiers, counts, reason codes, status classes, and lifecycle stages.
-- Keep field names aligned with canonical owners, not stale compatibility projections.
-- Do not log secrets, tokens, private keys, passwords, raw personal data, or full sensitive payloads.
-- Avoid high-cardinality values unless they are necessary identifiers already used by the project.
-
-## Behavior-neutral updates
-
-Logging changes must not:
-
-- alter retry, error, persistence, or branch behavior,
-- swallow exceptions,
-- add blocking network calls,
-- create expensive serialization in hot paths,
-- change public output unless logs are the product output.
-
-## Tests
-
-Add or update tests when:
-
-- the project already captures logs in tests,
-- branch-specific reason codes matter,
-- stale field names were renamed,
-- extracted helpers need observability contracts,
-- aggregate and detail telemetry must stay reconcilable.
-
-Assert stable fields and event names, not timestamps or full formatted strings.

package/iterative-code-quality/references/module-boundaries.md

@@ -1,83 +0,0 @@
-# Module Boundary And Single Responsibility Refactoring
-
-## When to split a module
-
-Split only when the module has multiple independent reasons to change, such as:
-
-- domain rules mixed with IO, formatting, CLI parsing, or external service calls,
-- unrelated workflows sharing one file because of history, not ownership,
-- test setup forced to instantiate unrelated dependencies,
-- large files where local changes frequently touch distant concepts,
-- circular or awkward imports caused by unclear ownership,
-- logging, validation, persistence, and presentation all living in one function or class.
-
-## Before splitting
-
-Define:
-
-- the current module's actual responsibilities,
-- the target responsibility of each new module,
-- which module owns the canonical business rule,
-- which interfaces must remain stable,
-- which tests prove behavior did not change.
-
-## Macro architecture boundary
-
-For this skill, `macro architecture` means the whole system's runtime shape and operating model, such as:
-
-- major subsystems and their top-level responsibilities,
-- deployment/runtime boundaries,
-- persistence model and data ownership model,
-- inter-service or inter-process boundaries,
-- the overall execution logic by which the system operates end to end.
-
-The following do **not** count as macro-architecture changes by themselves:
-
-- moving logic between ordinary internal modules,
-- extracting helpers,
-- splitting a mixed-responsibility file into narrower local modules,
-- clarifying call boundaries inside one subsystem,
-- replacing duplicated local control flow with a shared internal abstraction.
-
-Treat those changes as ordinary refactoring work unless they also alter the top-level system model above.
-
-Large coupled or central files should therefore be treated as decomposition problems, not as automatic macro-architecture blockers. If the top-level system model remains intact, prefer staged internal cleanup over stopping.
-
-## Safe split patterns
-
-- Move pure domain logic into a domain-owned helper module.
-- Move external adapter code into an integration or infrastructure-adjacent module if the repository already uses that boundary.
-- Move formatting/reporting away from computation.
-- Move test helpers into existing test utility locations rather than production modules.
-- Keep orchestration modules thin: validate inputs, call owners, handle outcomes.
-
-## Interface design
-
-Use narrow interfaces:
-
-- pass only data the callee needs,
-- return explicit result objects or existing domain types,
-- avoid leaking framework/request/database objects into pure domain modules,
-- preserve existing error taxonomy,
-- keep naming aligned with current project vocabulary.
-
-## Anti-patterns
-
-Avoid:
-
-- creating a generic `utils` dumping ground,
-- moving code only to reduce file length,
-- adding new layers that duplicate existing architecture,
-- introducing dependency injection frameworks or service locators without explicit approval,
-- splitting tightly coupled state machines before defining the state owner,
-- changing public boundaries during a cleanup pass.
-
-## Validation checklist
-
-After a split:
-
-- imports remain acyclic or no worse than before,
-- public entrypoints still call the same behavior,
-- tests cover moved logic and orchestration glue,
-- logs still carry the same correlation identifiers,
-- docs or `AGENTS.md/CLAUDE.md` are updated only if the visible architecture or command surface changed.