AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-module-boundary
mas-module-boundary
VerifiedDefine and enforce backend module boundaries for Python services. Use when adding or refactoring backend code under app/, reviewing dependency direction, deciding layer ownership, or preventing logic leakage across schema/api/core/services/task/utils modules.
MAS Module Boundary
Objective
Keep backend code maintainable by enforcing clear ownership, dependency direction, and placement rules across modules.
Layer Model
models/schema: external API contract and typed data structure.api: request parsing, response shaping, transport concerns.core: orchestration, lifecycle, task scheduling, state coordination.task: script-domain execution flow.services: system/network/integration capabilities.utils: reusable low-level helpers with no business policy.
Current Dev Map
- API routes:
app/api/*.py - Runtime orchestration:
app/core/*.py - Schema/config/runtime models:
app/models/schema.py,app/models/config.py,app/models/task.py,app/models/ConfigBase.py - Script domains:
app/task/MAA,app/task/general,app/task/SRC
Dependency Direction
api -> core/services/models.schemacore -> services/task/models/utilstask -> core/services/models/utilsservices -> utils/modelsmodels -> none of api/core/services/task
Disallowed examples:
models/schemaimportingcoreorservicesutilsimportingcoreorapiservicesimporting concreteapiroutersapiembedding long-running workflow loops directly
Ownership Rules
app/models/schema.py: naming, typing, field descriptions only. No filesystem, network, process, or business branching.app/api/*: accept*In, return*Out/OutBase, validate input, callcore/services, shape response.app/core/*: own global coordination, lifecycle, config composition, task scheduling, and broadcast.app/task/*: own per-script execution lifecycle (check/prepare/run/final) and domain task decisions.app/services/*: wrap external integrations and provide stable capabilities tocore/task.app/utils/*: generic helpers and low-level adapters only. No domain policy and no orchestrator imports.- Script-config import/restore policy belongs to
core/taskorchestration, notapiorschema: AUTO-MAS manages other scripts by swapping their config files/folders before and after task execution. - Script success/failure heuristics based on log text, log timestamp, and process exit belong to orchestrators and log-monitor helpers, not to schema models or transport handlers.
Placement Decision Tree
- Request/response contract or DTO typing ->
models/schema - Endpoint parsing and response mapping ->
api - Cross-task orchestration or global runtime state ->
core - Script-domain run logic ->
task/<domain> - OS/network/third-party integration ->
services - Reusable, context-agnostic helper ->
utils
Cross-Cutting Rules
- Avoid circular imports; if seen, extract interface/helper to a lower layer.
- Avoid direct config file IO in
api; use acorefacade. - Keep business constants close to the owning domain layer.
- Shared schema semantics should align with
mas-schema-naming. - New config modes or raw-config capabilities must be end-to-end complete: model field, edit entry, persistence path, and runtime consumer must all exist before the feature is considered real.
- Do not leave placeholder config fields, fake detailed-mode branches, or dead save paths in one layer when no owning runtime path exists.
- Do not create standalone
builder,loader, or helper-service modules for a feature that has no second call site and no real ownership boundary. - If a domain can be expressed as one task class plus nearby local helpers, prefer that over creating a mini-subsystem inside the domain folder.
- When adding support for a new external script, preserve the product's config-copy plus log-monitor architecture instead of embedding script-specific state machines into shared layers.
- Script-specific adaptation is cross-layer by design: add the script config/user config in
app/models/config.py, expose schema types inapp/models/schema.py, add endpoints inapp/api/scripts.py, extend global config orchestration inapp/core/config.py, and add task dispatch inapp/core/task_manager.py.app/api/scripts.pyholds endpoints only: parse the request, call a function exposed by the owningapp/task/<Xxx>/module, shape the response model. Directory handling, import, update, validation, and group propagation belong in the script domain; do not define script-private helpers in the API layer. The MaaFW engine underapp/task/MaaFW/is the exception: itstools/core/packages must stay host-agnostic and its worker subprocess must not import host modules — seeapp/task/MaaFW/AGENTS.mdbefore touching it. - For a new script domain, start from the closest existing task folder shape, commonly
app/task/general, then rename and adapt domain-specific config, run, manual-review, and manager code in place.
Anti-Patterns
- Business rules inside schema definitions.
- Route handlers containing workflow loops or retry engines.
- Utility modules importing orchestrators for convenience.
- Duplicated policy checks spread across
api/core/taskwithout an owner. - A new domain folder that introduces multiple thin modules without actual reuse or boundary pressure.
- Route handlers or module-private helpers in
app/api/that carry script-specific business (directory layout, import/update flows, config migration) instead of calling the owningapp/task/<Xxx>/module.
PR Boundary Checklist
- Each changed file belongs to the right layer by responsibility.
- New imports follow allowed dependency direction.
- No new circular dependency is introduced.
- Schema changes do not add business execution logic.
- API changes keep the thin-controller pattern.
- Core/task/services boundaries remain explicit and testable.
- New configuration concepts are complete across model, UI, and runtime, or they are not introduced yet.
- New helper modules justify their existence with reuse or a real dependency boundary, not just naming neatness.
- New script support is complete across config templates, schema, API, task manager dispatch, task folder, and frontend entry points before it is treated as implemented.
- Searches for the source template domain, such as
GeneralConfig/GeneralUserConfig, were used to find all required registry and branch updates.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |