Path and Naming Conventions
General Path Rules
- •Use forward slashes (/) in documentation, even on Windows.
- •Leading / indicates repository root (absolute path within repo).
- •Avoid relative paths in cross-document references.
Module Documentation Layout
text
/modules/<module_id>/ AGENTS.md # Module strategy (required) ABILITY.md # Ability catalog (if module has abilities) .codex/skills/ # (Optional) module-local Codex skill wrappers workdocs/ # Module-local task state # Durable, reusable docs should live in skill packages under `/.system/skills/ssot/**`.
Project-Level Registries
| Location | Purpose |
|---|---|
| /modules/overview/ | Module type graph, instance list, interface definitions |
| /.system/registry/ | System-level registries (abilities, hooks) |
| /.system/guides/ | System guides and conventions |
DevOps Documentation Layout
text
/PROJECT_INIT/ # Project initialization scenario /AI/AGENTS.md # Init-specific AI strategy /workdocs/ # Init task state /db/ # Database operations /schema/AGENTS.md # Schema management strategy /migrations/AGENTS.md /config/AGENTS.md /workdocs/ /ops/ # Operations scenarios /packaging/AGENTS.md /deploy/AGENTS.md /workdocs/
Naming Conventions
| Type | Pattern | Example |
|---|---|---|
| AGENTS strategy | AGENTS.md (fixed name) | /modules/auth/AGENTS.md |
| Ability entry | ABILITY.md (fixed name) | /modules/auth/ABILITY.md |
| Skill SSOT entry | SKILL.md (fixed name) | /.system/skills/ssot/repo/execution-plans/execution-plan-authoring/SKILL.md |
| Provider skill wrapper | SKILL.md (fixed name) | /.codex/skills/execution-plan-authoring/SKILL.md |
| Supporting doc | Descriptive name | /.system/skills/ssot/repo/architecture-core-mechanisms/repo-architecture-overview/SKILL.md |
| Workdocs task folder | T-YYYYMMDD-slug/ | workdocs/active/T-20241217-auth-feature/ |
Additional conventions:
- •Module IDs: prefer lower_snake_case; dot.separated is also acceptable when needed.
- •If you include YAML front matter IDs in supporting docs (optional), prefer lower_snake_case.
- •CLI flags (when introduced): kebab-case.
- •Environment variables (when introduced): UPPER_SNAKE_CASE.