Skiller Dev

Skiller Dev

Use this skill to keep Skiller code flat, explicit, and easy to maintain.

Core Rules

• Follow the dependency rule: interfaces -> application -> domain <- infrastructure.
• Infrastructure may implement domain ports and use domain models, but must not orchestrate other domain ports or coordinate business flows.
• Put ports in domain under their feature directory, never in application.
• Keep services thin. Orchestrate; do not persist state directly from the service.
• Put state changes and side effects in dedicated use cases.
• Prefer closed contracts with enums for finite domains like statuses and step types.
• Keep result objects minimal. Prefer status + payload + error over many optional fields.
• Prefer typed contracts at port boundaries. Do not model stable operations as long scalar parameter lists or generic dict[str, object] bags when the domain concept is known.
• Prefer predictive flow over defensive flow. If a case is expected in normal execution, model it in the contract or result type instead of rediscovering it through scattered None checks or generic exceptions.
• Do not make dependencies or fields optional by default. Use | None only when absence is a real domain state or a boundary genuinely may not provide the value.
• Avoid adding __init__.py files by default. Use namespace packages unless a package needs real initialization logic, explicit re-exports, or tooling compatibility that requires it.
• Trust the contract of a use case. Do not add defensive checks for states that should be impossible.
• Prefer one clear error message over many overly specific status variants.
• Do not hide non-trivial preparation inside constructor or function-call parameters. Use explicit local variables; do not create private helpers for one or two simple statements unless asked.
• Do not put architectural responsibility in large top-level functions. If a function coordinates dependencies, owns a workflow, parses a whole external contract, or keeps growing, model it as an object with a clear role such as adapter, mapper, resolver, manager, use case, store, or tool.

Read By Need

• For readability and control-flow rules, read packages/skiller/docs/architecture/code-style.md.
• For architecture boundaries and allowed dependencies, read packages/skiller/docs/architecture/architecture.md.
• For port, datasource, mapper, and infrastructure implementation names, read packages/skiller/docs/architecture/naming-style.md.
• For runtime patterns used in this repo, read SKILL.md -> references/runtime-patterns.md.
• For test taxonomy and what counts as unit/integration/e2e here, read SKILL.md -> references/testing-rules.md.
• For the general pre-commit checklist used in this repo, read SKILL.md -> references/pre-commit-checklist.md.
• For the documented feature and release branch flow of this repo, read SKILL.md -> references/workflow.md.
• For functional runtime rules around waiting, resume, and persisted external events, prefer SKILL.md -> references/runtime-patterns.md.

Sandbox Execution

• Do not assume pytest is available in the global PATH.
• In this repo, run tests with ./.venv/bin/pytest ....
• If you prefer activation first, use source .venv/bin/activate and then pytest ....
• For ad hoc Python commands with local imports, use PYTHONPATH=src python3 ....
• When reporting verification, include the exact command so the next agent can repeat it without rediscovering the environment.

Release Workflow

Use the documented repo flow in references/workflow.md unless the user says otherwise.

• Treat the [Agent], [User], [Admin], and [Workflow] labels in references/workflow.md as the source of truth for responsibilities.

Default Checklist

• Is the control flow flat?
• Are statuses and types modeled as enums when appropriate?
• Does each use case have one clear responsibility?
• Is the service only coordinating use cases?
• Would a new reader understand the happy path first?
• Are constructor and function-call parameters simple names instead of inline transformations?
• Are invalid cases reported with one clear message?
• If behavior or step contracts changed, did you review the affected docs, especially docs/steps/* and docs/guia_creacion_skills.md?
• If the task involves integration or release prep, did you follow references/workflow.md instead of an older manual flow?