maksimzayats/specx

This system is a Python framework and CLI tool called Specx designed to scaffold and enforce a clean, layered architecture for application development. It provides foundational abstractions for core business logic, delivery controllers, and infrastructure, while using rule-based validation to ensure structural integrity and naming conventions. The project has transitioned from a legacy Django-based bot application to this framework-neutral architecture guardrail system.

5 changes.

The project removed its legacy Django-based architecture, including the core application, web configuration, and associated entry scripts, to eliminate the web framework entirely. Simultaneously, it migrated to the Specx package for rule-based guardrails and isolated documentation into a dedicated Storybook environment.

10 changes.

This period focused on establishing the Specx framework by defining core architectural abstractions, including base classes for use cases, services, and infrastructure. The work introduced a CLI for project scaffolding and architecture validation, alongside comprehensive testing rules and agent skills to enforce strict layer boundaries and coding standards.

A new \scripts/validate\_skills.py\ script has been introduced to validate the structure and content of skills. It enforces that skill directory names follow lowercase kebab-case, ensures each skill contains a \SKILL.md\ file with valid YAML frontmatter (including a matching name and a description without angle brackets), and checks that referenced files exist. It also limits skill files to 500 lines and requires a Contents section for long reference files. Additionally, it validates \agents/openai.yaml\ files if present, ensuring the default prompt references the skill name and the short description is between 25-64 characters. Finally, it checks for consistency between the source skills directory and a tracked mirror in \.agents/skills\, flagging missing, unexpected, or stale files.

scripts · high confidence

Added new Specx skills that guide the creation and structure of core scope services, use cases, delivery controllers, and infrastructure adapters. These skills enforce a layered architecture with strict separation between core business logic, delivery frameworks (such as FastAPI), and technical infrastructure, including specific patterns for dependency injection, unit-of-work management, and testing.

skills · high confidence

New base classes have been added to the infrastructure layer to standardize how the application handles runtime configuration. The \BaseConfigurator\ class provides a common interface for bootstrap objects that apply configuration to runtime systems, while \BaseRuntimeSettings\ extends Pydantic's \BaseSettings\ to load settings from environment variables and dotenv files, including a dedicated \from\_environment\ class method to handle the complexity of required fields supplied by various sources.

src/specx/infrastructure · high confidence

The specx package now includes a command-line interface that allows users to initialize new framework-neutral Python projects and enforce architectural standards. The \specx init\ command scaffolds a project structure with a core health slice, dependency injection container, and tooling configuration (Ruff, MyPy, Pytest). The \specx check\ command analyzes existing projects against a set of built-in architecture rules, reporting violations or warnings in text or JSON format. Additionally, the \specx rule\ subcommand lets users list and explain the specific architectural constraints enforced by the tool.

_src/specx, src/specx/\internal · high confidence

This change adds a new architecture-checking subsystem to specx, enabling users to enforce structural rules (such as import boundaries and service layering) via a CLI and configuration in pyproject.toml. It also provides a project initialization command that scaffolds a new specx project with a standard directory layout, base classes for commands, queries, DTOs, entities, and framework-specific foundations for FastAPI and SQLAlchemy.

specx · high confidence

The \src/specx/testing\ package now includes a rule-based architecture testing system. This adds a new \architecture\ subpackage that provides an AST-based checker (\check\_specx\_architecture\) and a registry of built-in rules. These rules enforce architectural boundaries (such as core packages not importing delivery or infrastructure layers), naming conventions (e.g., capabilities must end in 'Capability'), and structural requirements (like requiring explicit base classes and scoped docstrings). This allows users to automatically validate their project's adherence to the specx architectural style during testing.

src/specx/testing · high confidence

Added agent skills that guide the creation of specx core services, use cases, delivery controllers, infrastructure adapters, and scope architecture. These skills enforce class naming conventions (e.g., \Service\ suffix), dependency injection via \Injected\[...\]\, transaction management through \UnitOfWorkManager\, and strict layer boundaries between core, delivery, and infrastructure. They also standardize test patterns using the pytest \container\ fixture and provide reference documentation for base classes, ports, and adapters.

.agents · high confidence

The \src/specx/core\ module now provides a set of base classes and interfaces that define the application's architectural boundaries. This includes \BaseUseCase\ for application actions, \BasePureService\ and \BaseEffectService\ for deterministic and side-effecting logic respectively, and \BaseReadService\ for read-only orchestration. Data access is abstracted via \BaseRepository\ and \BaseGateway\ interfaces, while transaction management is handled by \BaseUnitOfWork\ and \BaseUnitOfWorkManager\. Additional foundational types include \BaseCapability\ for small injectable collaborators, \BaseFactory\ for object composition, \BaseStrEnum\ for string-based enums, and specific exception bases (\BaseApplicationError\, \BaseApplicationValueError\). These components establish the core contracts for building scalable, testable application logic.

src/specx/core · high confidence

The application has removed its Django web framework configuration, including settings, URL routing, ASGI/WSGI entry points, and the environment variable template (.env.dist). This change eliminates the built-in web server and admin interface capabilities, aligning with the shift away from Django towards a different architecture (likely the aiogram/Tortoise ORM stack previously configured in these files).

application/config · high confidence

The entire \application/apps/core\ module has been removed, deleting the legacy Django application configuration, the \User\ model (which previously used a Tortoise ORM-to-Django converter), the Telegram bot integration (handlers, filters, middlewares, and services), and the associated web layer (admin registration, URLs, views, and middleware). This eliminates the core app's functionality, including user registration via Telegram commands and the automatic conversion of Tortoise models to Django models.

application/apps/core · high confidence

The entire \application/config/app\template\ directory has been deleted, removing the default scaffolding files for new Django applications. This includes the template-based configuration (\\\init\\_.py-tpl\, \app.py-tpl\), bot integration components (handlers, filters, middlewares, keyboards, states), database models using Tortoise ORM, and web layer stubs (views, URLs, admin). Users can no longer generate new apps using this specific legacy template structure.

_application/config/app\template · high confidence

The application has removed the direct execution entry points for the bot, Django administrative tasks, and the ASGI server. Specifically, \bot.py\ (which handled bot polling), \manage.py\ (which wrapped Django management commands), and \server.py\ (which initialized the ASGI app and bot instance) have been deleted. Users can no longer run these components directly via \python bot.py\, \python manage.py\, or \python server.py\; the bot and server initialization logic previously contained in these files is no longer accessible through these scripts.

application · high confidence

The delivery module now provides abstract base classes to standardize how application components are structured. A new \BaseController\ allows delivery controllers to register public routes against a registry, while \BaseLifecycle\ defines the interface for managing application startup and shutdown events. Additionally, \BaseDeliveryService\ serves as a base for helper services like authentication or rate limiting. These classes have been moved from the application configuration templates into the core delivery foundation to enforce a consistent structure for new applications.

src/specx/delivery · high confidence

Added unit and integration tests covering the Specx architecture validation engine, including rules for class categories, import boundaries, logging practices, and lifecycle management. The suite also validates core foundation base classes (DTOs, commands, queries, gateways, repositories, use cases), delivery foundations (FastAPI schemas, lifecycles), infrastructure foundations (runtime settings, SQLAlchemy models), CLI initialization behavior, branding consistency, and distribution wheel contents.

tests · high confidence

The project has pivoted to the Specx rule-based architecture guardrails, introducing a new \pyproject.toml\ that defines the \specx\ package with dependencies on \diwire\, \pydantic\, and \sqlalchemy\, alongside a CLI entry point. The legacy \requirements.txt\ (containing Django, aiogram, etc.) has been removed. Additionally, the documentation tooling has been isolated into a dedicated \docs/\ directory, featuring a new \package.json\ and \package-lock.json\ that set up a Storybook environment with React 19, Vite, and MDX support.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 54 → 64 (+9.1)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 79 → 86 (+7.1)
• Architecture 100 → 99 (-0.6)
• Maturity 68 → 60 (-7.5)
• Readiness 26 → 53 (+27.3)
• Security 100 → 84 (-15.9)
• Accessibility 80 (new)

• CapabilitiesDoNotOwnWorkflowsOrOtherPortRolesRule.check (cognitive 38) (src/specx/testing/architecture/rules.py)
• CapabilitiesLiveInExpectedPackagesAndUseExpectedSuffixesRule.check (cognitive 26) (src/specx/testing/architecture/rules.py)
• ClassesUseSuffixFromMostSpecificFoundationCategoryRule.check (cognitive 17) (src/specx/testing/architecture/rules.py)
• CoreInnerPackagesDoNotImportOuterLayersOrIOLibrariesRule.check (cognitive 20) (src/specx/testing/architecture/rules.py)
• Coverage not included — suite not readable by the collector
• DeliveryControllersDoNotImportInfrastructureRule.check (cognitive 17) (src/specx/testing/architecture/rules.py)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (10 lines × 2) (.agents/skills/specx-tests/references/render_architecture_guardrails.py)
• Duplicated block (12 lines × 2) (src/specx/testing/architecture/rules.py)
• Duplicated block (12 lines × 3) (src/specx/testing/architecture/rules.py)
• Duplicated block (15 lines × 2) (src/specx/testing/architecture/rules.py)
• Duplicated block (15 lines × 2) (src/specx/testing/architecture/rules.py)
• Duplicated block (19 lines × 2) (.agents/skills/specx-tests/references/render_architecture_guardrails.py)
• Duplicated block (19 lines × 2) (src/specx/testing/architecture/rules.py)
• Duplicated block (6 lines × 2) (src/specx/testing/architecture/rules.py)
• Duplicated block (7 lines × 2) (src/specx/testing/architecture/rules.py)
• Duplicated block (7 lines × 3) (src/specx/testing/architecture/rules.py)
• Duplicated block (7 lines × 5) (src/specx/testing/architecture/rules.py)
• EffectServicesDoNotOwnTransactionsOrImportDeliveryRule.check (cognitive 41) (src/specx/testing/architecture/rules.py)
• EffectServicesDoNotOwnTransactionsOrImportDeliveryRule.check (cyclomatic 16) (src/specx/testing/architecture/rules.py)
• …and 24 more

• CapabilitiesDoNotOwnWorkflowsOrOtherPortRolesRule.check (cognitive 38) (src/specx/testing/architecture/rules/capabilities_no_workflows_or_port_roles.py)
• CapabilitiesLiveInExpectedPackagesAndUseExpectedSuffixesRule.check (cognitive 26) (src/specx/testing/architecture/rules/capabilities_placement_and_suffix.py)
• ClassesUseSuffixFromMostSpecificFoundationCategoryRule.check (cognitive 17) (src/specx/testing/architecture/rules/classes_suffix_from_foundation_category.py)
• CoreInnerPackagesDoNotImportOuterLayersOrIOLibrariesRule.check (cognitive 20) (src/specx/testing/architecture/rules/core_inner_packages_no_outer_layers_or_io_libraries.py)
• DeliveryControllersDoNotImportInfrastructureRule.check (cognitive 23) (src/specx/testing/architecture/rules/delivery_controllers_do_not_import_infrastructure.py)
• Dependency hygiene PARTLY measured — Python dependencies read, no exact pin to grade for currency
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (12–14 lines × 3) (src/specx/testing/architecture/rules/capabilities_no_workflows_or_port_roles.py)
• Duplicated block (14 lines × 2) (src/specx/testing/architecture/rules/capabilities_no_workflows_or_port_roles.py)
• Duplicated block (14 lines × 2) (src/specx/testing/architecture/rules/tests_mirror_source_structure.py)
• Duplicated block (16 lines × 2) (src/specx/testing/architecture/rules/services_effect_no_owned_transactions_or_delivery.py)
• Duplicated block (18 lines × 2) (src/specx/testing/architecture/rules/tests_mirror_source_structure.py)
• Duplicated block (42 lines × 2) (.agents/skills/specx-tests/references/render_architecture_guardrails.py)
• Duplicated block (6 lines × 2) (src/specx/testing/architecture/rules/uow_services_do_not_open_scopes.py)
• Duplicated block (6 lines × 3) (src/specx/testing/architecture/rules/uow_use_cases_open_at_most_one_scope.py)
• Duplicated block (7 lines × 2) (.agents/skills/specx-tests/references/render_architecture_guardrails.py)
• Duplicated block (7–8 lines × 2) (src/specx/testing/architecture/rules/_shared.py)
• Duplicated block (7–8 lines × 6) (src/specx/testing/architecture/rules/uow_use_cases_inject_managers.py)
• Duplicated block (9 lines × 2) (src/specx/testing/architecture/rules/uow_use_cases_open_at_most_one_scope.py)
• …and 41 more

• Containers 0 added · 0 removed · contexts 1 added · 0 removed · edges 0 added · 0 removed

• specx

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

maksimzayats/specx was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.