Python Backend Skill Architecture Research

Conclusion

The smallest coherent next design is a thin python-backend-structure overlay that composes with backend-domain-structure, in the same way that effect-backend-structure adds stack-specific rules without redefining the agnostic topology. This is a research hypothesis, not an accepted product decision. The overlay should translate domain ownership into Python package, private-module, application-factory, bootstrap, import-boundary, and test conventions. Recoverability, async, testing, and style should remain separate skills.

The deprecated Collective Intelligence skills contain useful migration mechanics, but they are not a clean reusable package. Their portable value is boundary discovery, explicit dependency edges, narrow public surfaces, atomic moves, and architecture-test enforcement. Their exact FastAPI, SQLAlchemy, dependency_injector, and Collective Intelligence directory rules belong in project guidance or project architecture tests. Deleting the deprecated skills should be proof-gated on those project-owned rules and tests remaining authoritative.

Scope, method, and lane coverage

Three readonly lanes covered:

1. Collective Intelligence's current Python/backend guidance, deprecated backend skills, current Python pack, project configuration, and architecture tests.
2. Harness pack composition, repository detection, scaffold selection, current backend/Python skill boundaries, logging examples, and specialist manifests.
3. Transfer candidates from current Effect/frontend skills and deprecated Python/React skills.

The consolidator re-read the cited primary files and compared corresponding skill trees with diff -rq or diff -u. Facts below are tied to repository, immutable ref, relative path, and 1-based line ranges. Recommendations are marked separately.

Snapshot refs

Facts: current composition

• Harness defines the backend pack as exactly backend-domain-structure, backend-recoverable-actions, and logging-best-practices. It separately defines a Python language pack containing async, code-style, design-pattern, project-structure, and testing skills. Harness@1f82ce5f — apps/cli/src/data/catalog/packs.ts:26-41, apps/cli/src/data/catalog/packs.ts:402-419.
• Repository analysis selects language packs from detected languages and selects backend independently from backend surface detection. It unions defaults, languages, technologies, packages, and surfaces; scaffold materialization then flattens selected pack skills and removes duplicates. A Python backend therefore receives both pack contributions without duplicate skill IDs. Harness@1f82ce5f — apps/cli/src/features/repository-analysis/pack-selection.ts:80-110, apps/cli/src/features/repository-analysis/pack-selection.ts:130-163, apps/cli/src/scaffold/run.ts:34-37.
• The catalog registers the five Python language skills and no python-backend-structure entry. Harness@1f82ce5f — apps/cli/src/data/catalog/skills.ts:575-614.
• backend-domain-structure already owns domain-first placement, dependency direction, composition-root ownership, deliberate public surfaces, actions/services/repositories, and feature-local tests. Harness@1f82ce5f — .agents/skills/backend-domain-structure/SKILL.md:16-62, .agents/skills/backend-domain-structure/references/layout.md:69-178, .agents/skills/backend-domain-structure/references/layout.md:180-217.
• backend-recoverable-actions is a separate failure-semantics workflow for multi-step mutation, transaction, retry, compensation, repair, and failure-path testing. It does not define source topology. Harness@1f82ce5f — .agents/skills/backend-recoverable-actions/SKILL.md:10-49.
• python-project-structure owns general module cohesion, __all__, shallow layouts, package initialization, import style, and alternative test placements. Its examples include both technical-layer and domain structures, but it does not define a backend composition-root overlay. Harness@1f82ce5f — apps/cli/skills/languages/python/python-project-structure/SKILL.md:19-50, apps/cli/skills/languages/python/python-project-structure/SKILL.md:72-147, apps/cli/skills/languages/python/python-project-structure/SKILL.md:180-252.
• Collective Intelligence currently routes both generic backend skills and five current Python skills from apps/backend/AGENTS.md; neither deprecated Python backend skill is routed there. Collective Intelligence@0ddc23a3 — apps/backend/AGENTS.md:1-10.
• Most of the deprecated backend topology now lives as project guidance: owner-first placement, the app/extensions/features/platform/framework/infrastructure/integrations/database/domain distinctions, typed boundaries, public feature services, dependency direction, composition containers, and DI rules. Collective Intelligence@0ddc23a3 — apps/backend/AGENTS.md:31-66, apps/backend/AGENTS.md:68-106; compare .agents/skills/python-backend-layer-architecture-deprecated/SKILL.md:22-60, .agents/skills/python-backend-layer-architecture-deprecated/SKILL.md:71-142.
• Collective Intelligence also has executable architecture locks for public feature imports, feature-private modules, narrow root exports, removed service locators, and lower modules not importing features. Collective Intelligence@0ddc23a3 — apps/backend/tests/architecture/test_feature_boundaries.py:882-925, apps/backend/tests/architecture/test_feature_boundaries.py:962-1020, apps/backend/tests/architecture/test_feature_boundaries.py:1579-1605.
• Recursive comparison found the current project-structure, design-patterns, and testing skill directories identical between Collective Intelligence and canonical shared skills. Code style differs only by three Markdown blank lines, and async differs only by table formatting. These are effectively one shared Python-pack snapshot, not two competing designs. Collective Intelligence@0ddc23a3 and Shared skills@d8f596aa — .agents/skills/python-project-structure/SKILL.md:1-252 and skills/languages/python/python-project-structure/SKILL.md:1-252; .agents/skills/python-design-patterns/SKILL.md:1-433 and skills/languages/python/python-design-patterns/SKILL.md:1-433; .agents/skills/python-testing-patterns/SKILL.md:1-622 and skills/languages/python/python-testing-patterns/SKILL.md:1-622; .agents/skills/python-code-style/SKILL.md:332-350 and skills/languages/python/python-code-style/SKILL.md:332-347; .agents/skills/async-python-patterns/SKILL.md:21-35 and skills/languages/python/async-python-patterns/SKILL.md:21-35.
• The current Effect service-design, Effect backend-structure, and frontend-domain-structure trees are byte-identical in Harness and Collective Intelligence at these snapshots. Harness@1f82ce5f and Collective Intelligence@0ddc23a3 — .agents/skills/effect-service-design/SKILL.md:1-118, .agents/skills/effect-service-design/references/AUDIT.md:1-98, .agents/skills/effect-backend-structure/SKILL.md:1-95, .agents/skills/frontend-domain-structure/SKILL.md:1-55, .agents/skills/frontend-domain-structure/references/structure.md:1-257, .agents/skills/frontend-domain-structure/references/react/structure.md:1-102 in both repositories.

Comparison and gap matrix

Salvage and leave-behind matrix

Recommended minimum target shape

This section is a recommendation, not a selected design.

1. Add python-backend-structure as a thin overlay paired with backend-domain-structure. Mirror the composition relationship stated by the Effect overlay, not its APIs. Harness@1f82ce5f — .agents/skills/effect-backend-structure/SKILL.md:13-35.
2. Limit the overlay to Python-specific translation: package/private-module boundaries, narrow feature-root imports, application factory and bootstrap/composition ownership, constructor or explicit setup injection, cycle repair, import-boundary test recipes, cross-domain workflow ownership, and precedence over general Python examples.
3. Keep backend-recoverable-actions, async, testing, code style, and logging independent. They answer failure semantics, concurrency, test mechanics, tooling, and observability rather than topology.
4. Scope python-project-structure examples so backend-domain-structure wins for backend placement, public API, and test location. Preserve the language skill for libraries and non-backend projects.
5. Adapt only the language-neutral service-design theory from Effect. Do not create a Python-shaped copy of Effect services or layers.
6. Add the ownership-preserving component-decomposition loop and stable named public-boundary seam to current frontend guidance only if a focused review shows they are not already implied strongly enough.
7. Remove deprecated Collective Intelligence skills only after scoped AGENTS.md rules and architecture tests cover every retained invariant. Existing boundary locks demonstrate the right enforcement surface, but this research did not run a deletion simulation. Collective Intelligence@0ddc23a3 — apps/backend/AGENTS.md:31-106, apps/backend/tests/architecture/test_feature_boundaries.py:882-925, apps/backend/tests/architecture/test_feature_boundaries.py:962-1020.

Explicit conflicts

• platform / integrations / domain features conflicts with root technical buckets such as api / services / models / utils when both are presented as defaults.
• Backend feature-root public APIs conflict with “define __all__ for every module” and eager package re-export examples.
• Feature-local backend tests conflict with the Python skill's equal recommendation of a parallel root tests/ tree.
• Generic backend actions / services / repositories overlaps Python design-pattern layering and Collective Intelligence's project-specific services / operations / providers model.
• Shared tooling examples conflict with project-owned Pyright/Ruff settings when presented as prescriptions.

The evidence for these conflicts is the paired source material in the comparison matrix. They require explicit precedence; silently merging the texts would make the composed pack internally inconsistent.

Unresolved product decisions

1. Choose the abstraction boundary: a thin python-backend-structure overlay, a broader python-project-structure, or a new agnostic backend-service-design base shared by Effect and Python.
2. Decide whether the Python overlay is automatically included in the Python pack, the backend pack, or selected only when both Python and backend are detected.
3. Define precedence for public exports and test placement when language and surface packs compose.
4. Define the language-neutral owner of cross-domain workflows and adapter construction before naming Python folders.
5. Decide whether Python backend specialist coverage is required and, if so, whether it is a new role or a capability expansion of an existing backend specialist.
6. Decide the deletion proof for deprecated CI skills: exact architecture suite, guidance audit, missing-link repair, and whether a migration rehearsal must precede removal.

Next route

Route the unresolved alternatives through requirements/design before shared-skill implementation. The decision artifact should select one abstraction boundary, define pack-selection and precedence rules, and state the CI deletion gate. If the thin overlay is accepted, implement source-first in the canonical shared-skills repository, validate its contract there, sync Harness from the exact pushed ref, then verify a repository detected as both Python and backend receives a coherent deduplicated skill set. Frontend additions should remain a separate small change so they are not coupled to the Python backend decision.