mirror of
https://github.com/azaion/annotations.git
synced 2026-04-22 21:46:30 +00:00
Oleksandr Bezdieniezhnykh
108 lines
5.0 KiB
Markdown
108 lines
5.0 KiB
Markdown
# Module Layout Template
|
|
|
|
The module layout is the **authoritative file-ownership map** used by the `/implement` skill to assign OWNED / READ-ONLY / FORBIDDEN files to implementer subagents. It is derived from `_docs/02_document/architecture.md` and the component specs at `_docs/02_document/components/`, and it follows the target language's standard project-layout conventions.
|
|
|
|
Save as `_docs/02_document/module-layout.md`. This file is produced by the decompose skill (Step 1.5 module layout) and consumed by the implement skill (Step 4 file ownership). Task specs remain purely behavioral — they do NOT carry file paths. The layout is the single place where component → filesystem mapping lives.
|
|
|
|
---
|
|
|
|
```markdown
|
|
# Module Layout
|
|
|
|
**Language**: [python | csharp | rust | typescript | go | mixed]
|
|
**Layout Convention**: [src-layout | crates-workspace | packages-workspace | custom]
|
|
**Root**: [src/ | crates/ | packages/ | ./]
|
|
**Last Updated**: [YYYY-MM-DD]
|
|
|
|
## Layout Rules
|
|
|
|
1. Each component owns ONE top-level directory under the root.
|
|
2. Shared code lives under `<root>/shared/` (or language equivalent: `src/shared/`, `crates/shared/`, `packages/shared/`).
|
|
3. Cross-cutting concerns (logging, config, error handling, telemetry) live under `<root>/shared/<concern>/`.
|
|
4. Public API surface per component = files listed in `public:` below. Everything else is internal — other components MUST NOT import it directly.
|
|
5. Tests live outside the component tree in a separate `tests/` or `<component>/tests/` directory per the language's test convention.
|
|
|
|
## Per-Component Mapping
|
|
|
|
### Component: [component-name]
|
|
|
|
- **Epic**: [TRACKER-ID]
|
|
- **Directory**: `src/<path>/`
|
|
- **Public API**: files in this list are importable by other components
|
|
- `src/<path>/public_api.py` (or `mod.rs`, `index.ts`, `PublicApi.cs`, etc.)
|
|
- `src/<path>/types.py`
|
|
- **Internal (do NOT import from other components)**:
|
|
- `src/<path>/internal/*`
|
|
- `src/<path>/_helpers.py`
|
|
- **Owns (exclusive write during implementation)**: `src/<path>/**`
|
|
- **Imports from**: [list of other components whose Public API this component may use]
|
|
- **Consumed by**: [list of components that depend on this component's Public API]
|
|
|
|
### Component: [next-component]
|
|
...
|
|
|
|
## Shared / Cross-Cutting
|
|
|
|
### shared/models
|
|
- **Directory**: `src/shared/models/`
|
|
- **Purpose**: DTOs, value types, schemas shared across components
|
|
- **Owned by**: whoever implements task `[TRACKER-ID]_shared_models`
|
|
- **Consumed by**: all components
|
|
|
|
### shared/logging
|
|
- **Directory**: `src/shared/logging/`
|
|
- **Purpose**: structured logging setup
|
|
- **Owned by**: cross-cutting task `[TRACKER-ID]_logging`
|
|
- **Consumed by**: all components
|
|
|
|
### shared/[other concern]
|
|
...
|
|
|
|
## Allowed Dependencies (layering)
|
|
|
|
Read top-to-bottom; an upper layer may import from a lower layer but NEVER the reverse.
|
|
|
|
| Layer | Components | May import from |
|
|
|-------|------------|-----------------|
|
|
| 4. API / Entry | [list] | 1, 2, 3 |
|
|
| 3. Application | [list] | 1, 2 |
|
|
| 2. Domain | [list] | 1 |
|
|
| 1. Shared / Foundation | shared/* | (none) |
|
|
|
|
Violations of this table are **Architecture** findings in code-review Phase 7 and are High severity.
|
|
|
|
## Layout Conventions (reference)
|
|
|
|
| Language | Root | Per-component path | Public API file | Test path |
|
|
|----------|------|-------------------|-----------------|-----------|
|
|
| Python | `src/<pkg>/` | `src/<pkg>/<component>/` | `src/<pkg>/<component>/__init__.py` (re-exports) | `tests/<component>/` |
|
|
| C# (.NET) | `src/` | `src/<Component>/` | `src/<Component>/<Component>.cs` (namespace root) | `tests/<Component>.Tests/` |
|
|
| Rust | `crates/` | `crates/<component>/` | `crates/<component>/src/lib.rs` | `crates/<component>/tests/` |
|
|
| TypeScript / React | `packages/` or `src/` | `src/<component>/` | `src/<component>/index.ts` (barrel) | `src/<component>/__tests__/` or `tests/<component>/` |
|
|
| Go | `./` | `internal/<component>/` or `pkg/<component>/` | `internal/<component>/doc.go` + exported symbols | `internal/<component>/*_test.go` |
|
|
```
|
|
|
|
---
|
|
|
|
## Self-verification for the decompose skill
|
|
|
|
When writing `_docs/02_document/module-layout.md`, verify:
|
|
|
|
- [ ] Every component in `_docs/02_document/components/` has a Per-Component Mapping entry.
|
|
- [ ] Every shared / cross-cutting epic has an entry in the Shared section.
|
|
- [ ] Layering table rows cover every component.
|
|
- [ ] No component's `Imports from` list contains a component at a higher layer.
|
|
- [ ] Paths follow the detected language's convention.
|
|
- [ ] No two components own overlapping paths.
|
|
|
|
## How the implement skill consumes this
|
|
|
|
The implement skill's Step 4 (File Ownership) reads this file and, for each task in the batch:
|
|
|
|
1. Resolve the task's Component field to a Per-Component Mapping entry.
|
|
2. Set OWNED = the component's `Owns` glob.
|
|
3. Set READ-ONLY = the Public API files of every component listed in `Imports from`, plus `shared/*` Public API files.
|
|
4. Set FORBIDDEN = every other component's Owns glob.
|
|
|
|
If two tasks in the same batch map to the same component, the implement skill schedules them sequentially (one implementer at a time for that component) to avoid file conflicts on shared internal files.
|