Language Conventions

Language Conventions

Overview

Language-specific coding conventions for DDD projects. Detects the project language and loads the corresponding convention reference. Does not change DDD architecture principles — only specifies how they land in a specific language and framework. This skill is automatically invoked by Phase 5 (defining-schemas), Phase 6 (spec-driven-development), and Phase 7 (coding-isolated-domains) to determine language-specific naming, package structure, and scaffolding conventions.

Foundational Principle: Language conventions are mandatory constraints, not style preferences. When a convention conflicts with team norms, IDE defaults, or "industry standard" tools — the convention wins. If no convention reference exists for the detected language, fall back to [coding-isolated-domains](../coding-isolated-domains/SKILL.md) generic rules.

When to Use

• When any pipeline skill needs language-specific conventions (naming, structure, scaffold, DI, testing)
• When Phase 5 (schemas), Phase 6 (behavior contracts), or Phase 7 (coding) need language-aware generation
• When setting up a new project scaffold at the Project Init Gate

Do NOT use when: No coding is involved (Phases 1-4 are language-agnostic), or the question is about DDD architecture principles rather than language-specific implementation.

Implementation Steps

Step 1 — Detect Project Language

Scan the project root for build/dependency files to detect language:

| File | Language | Convention Reference | |:---|:---|:---| | go.mod | Go | [go-conventions.md](./go-conventions.md) | | package.json + tsconfig.json | TypeScript | No convention file yet — fall back to generic rules | | pom.xml or build.gradle | Java | No convention file yet — fall back to generic rules | | pyproject.toml or requirements.txt | Python | No convention file yet — fall back to generic rules |

• If no build/dependency file matches → STOP: "Cannot detect project language from build files. Which language conventions should I apply?"
• If multiple build files for different languages are detected (e.g., go.mod + package.json in a monorepo) → STOP: "Multiple languages detected. Which language is primary for DDD domain code?"

Step 2 — Load Convention Reference

Read the corresponding convention reference file(s) for the detected language.

• Go loading rule: Always load go-conventions.md. If the caller is at the Project Init Gate, also load go-project-scaffold-reference.md. If the caller is in Phase 7 (coding/TDD — invoked by coding-isolated-domains or test-driven-development), also load go-wire-di-reference.md and (if Phase 4 selects gRPC/protobuf) go-proto-integration-reference.md.
• CRITICAL: Must READ each convention reference file from disk in full. Do not recall from memory or partially scan. The reference files contain mandatory constraints and their own Rationalization Table.
• If the detected language has no convention reference file:
• Non-trivial existing project (has packages/modules that may conflict with generic rules) → STOP: "Detected {language} but no convention file exists. The project has existing structure that generic DDD rules may conflict with. Please confirm: (a) proceed with generic rules, or (b) provide language-specific conventions."
• New/empty project → Fall back to generic DDD rules from [coding-isolated-domains](../coding-isolated-domains/SKILL.md) without STOP. RECORD the fallback in docs/ddd/decisions-log.md: "Language: {language}. No convention file — using generic DDD rules."

Step 3 — Apply Conventions to Current Task

Use the loaded conventions throughout the current task execution. Convention rules apply to naming, package structure, scaffolding, DI, testing, error handling, and schema generation.

• Convention rules override any conflicting patterns observed in existing project code (Foundational Principle).
• If a convention conflicts with an established project pattern → STOP: human decides whether to follow the convention (refactor existing code) or document an exception.
• When invoked by a calling skill (Phase 5/6/7), return the loaded conventions to the caller — do not re-detect or re-read on subsequent calls within the same session.

Quick Reference

| Rule | Requirement | |:-----|:-----------| | Language Detection | Scan root for build files (go.mod, package.json, etc.). STOP if multiple languages detected with no obvious primary. STOP if no build files match. | | Convention File Loading | Read convention reference file(s) for detected language completely from disk. Go (always): go-conventions.md. Go (Project Init): + go-project-scaffold-reference.md. Go (Phase 7): + go-wire-di-reference.md + go-proto-integration-reference.md (if gRPC). | | Missing Convention File | Non-trivial project: STOP and ask human to confirm approach. Empty project: silent fallback to generic DDD rules + RECORD in decisions-log. | | Override Priority | Convention file > existing code patterns > framework defaults. No exceptions without human approval. | | Convention Conflicts | STOP when convention conflicts with established project pattern. Human decides: follow convention or document exception. | | Full Read Requirement | Convention files must be read completely from disk on every invocation. No partial scans, no memory recall, no session caching. | | Session Persistence | Do not re-detect or re-read on subsequent calls within the same session after initial load. Return loaded conventions to caller. |

Convention Interface

Every language convention reference file MUST provide these sections (section names are the contract — content is language-specific):

| Section | Content | |:---|:---| | Architecture Layers | Layer names, directories, dependency direction | | Naming & Package Structure | Package/file/type naming, directory layout, test file placement | | Project Scaffold | Initialization commands + DDD reorganization steps | | DI & Startup | Dependency injection and application bootstrap | | Schema & Proto | Language-specific schema handling | | Test Conventions | Test file placement, naming, framework | | Error Handling | Error propagation patterns per layer |

For detailed format requirements and quality checks, see [conventions-format-reference.md](./conventions-format-reference.md).

Go Convention References

When go.mod is detected, read these files:

| Reference | When to Load | Content | |:---|:---|:---| | [go-conventions.md](./go-conventions.md) | Always — primary convention file | Conventions, RT, Red Flags | | [go-project-scaffold-reference.md](./go-project-scaffold-reference.md) | Project Init Gate — during project scaffolding | Directory tree, Makefile template | | [go-wire-di-reference.md](./go-wire-di-reference.md) | Phase 7 wiring — when assembling DI | Wire setup, ProviderSet patterns | | [go-proto-integration-reference.md](./go-proto-integration-reference.md) | Phase 7 [gRPC] — only when Phase 4 selects gRPC/protobuf | Proto management, enums.go, pb access rules |

Note: During Phase 7, multiple references may be needed simultaneously (e.g., go-wire-di-reference.md + go-proto-integration-reference.md for gRPC projects). Load all applicable references — they are complementary, not exclusive.

Ambiguity Handling

Follow the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) throughout.

STOP Triggers

| Ambiguity | Why STOP | |:---|:---| | Detected language has no convention file AND project has existing directory structure | Generic DDD rules may conflict with established project patterns — human must confirm approach | | Convention conflicts with project's existing code patterns | Human decides: follow convention (refactor existing code) or document exception | | Multiple build files detected (e.g., go.mod + package.json in monorepo) | Cannot determine primary language — human must specify | | No build/dependency file matches any known language | Cannot detect project language — human must specify |

ASSUME & RECORD

| Ambiguity | Default | Why Low Radius | |:---|:---|:---| | Convention file references a framework not yet in dependency file (e.g., gin conventions but no gin in go.mod) | ASSUME framework is planned — apply conventions. RECORD in assumptions-draft.md | If wrong, naming conventions are find-and-replace fixable; structural patterns match regardless of framework | | New/empty project with no convention file for the detected language | ASSUME generic DDD rules from coding-isolated-domains apply. RECORD in decisions-log.md | Generic rules are a subset of any language convention — adding a convention file later only adds specificity, never contradicts | | Convention file specifies a test framework not available in project (e.g., testify but only stdlib testing in use) | ASSUME stdlib equivalent patterns. RECORD in assumptions-draft.md | Test structure conventions (file placement, naming) apply regardless of assertion library | | Convention file version is older than project's language version (e.g., Go 1.21 conventions, project uses Go 1.23) | ASSUME conventions still apply unless deprecated features are referenced. RECORD in decisions-log.md | Language conventions rarely break across minor versions; deprecated features would cause compile errors caught immediately |

Orchestrator Mode Exception

When invoked by a calling skill (Phase 5-7) running in Autonomous Mode under an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution):

• Language detection STOP triggers still apply — if multiple languages detected or no build files match, return STOP to the caller.
• Convention loading proceeds without interactive confirmation — read the convention file, apply rules, return conventions to the calling skill.
• Missing convention file for non-trivial project — return STOP to the caller (human must confirm approach).
• Missing convention file for new/empty project — silent fallback to generic DDD rules. RECORD in docs/ddd/decisions-log.md.

This exception does NOT change detection or loading behavior — it only removes interactive confirmations. All STOP triggers remain mandatory.

Self-Check Protocol

Follow the [Persistence Defense Reference](../ddd-protocol/persistence-defense-reference.md) for the shared check items (progress file updated, decisions logged). Additionally, verify these language-conventions-specific items:

1. Language detected from build files: Language was identified by scanning actual build/dependency files in the project root — not assumed, guessed, or inferred from file extensions.
2. Convention reference fully read: The convention reference file (e.g., go-conventions.md) was read in full from disk — not partially scanned, recalled from memory, or skipped.
3. Convention applied in output: At least one language-specific convention was concretely applied in the current task output (verify by checking naming patterns, package structure, directory layout, test placement, or error handling patterns).
4. Fallback recorded: If no convention file exists for the detected language, the fallback decision was recorded in docs/ddd/decisions-log.md.

If any check fails → STOP. Re-execute the failed step before proceeding.

Session Recovery

If a session using language conventions is interrupted:

1. Language detection is stateless — re-run detection from build files on every new session. Do not rely on previous session's detection result.
2. Convention files are on-disk references — no recovery needed for convention content itself. Re-read from disk.
3. If the calling skill (Phase 5/6/7) has a Session Recovery protocol: follow the calling skill's recovery — it will re-invoke language-conventions as part of its recovery flow.
4. Fallback decision: If a previous session recorded a fallback decision in docs/ddd/decisions-log.md (language with no convention file → generic rules), read the log entry — do not re-prompt the user for the same decision.

Loading Guidance

This skill references files on demand — do not preload them all:

• Step 1 (Detect): Scan root for build/dependency files only — no file reads needed.
• Step 2 (Load): Read the convention reference file(s) for the detected language. For Go: go-conventions.md (always); add go-project-scaffold-reference.md at Project Init Gate; add go-wire-di-reference.md + go-proto-integration-reference.md (if gRPC) when caller is Phase 7.
• On first STOP/ASSUME decision: Read ../ddd-protocol/ambiguity-handling-reference.md.
• Convention Interface check: If creating/reviewing a convention file, read [conventions-format-reference.md](./conventions-format-reference.md) for the mandatory section structure.

Red Flags

If you catch yourself thinking any of these — STOP. You are about to bypass a mandatory constraint.

• "I already know Go/Java/TypeScript conventions" → You know general language conventions; this project may have framework-specific overrides and DDD-specific constraints in the convention file. Read the file.
• "The project already has a consistent style, I'll follow that" → Convention file takes precedence over observed project patterns (Foundational Principle). Existing patterns may be anti-patterns that pre-date the DDD adoption.
• "I'll just use the default naming" → Default naming varies between frameworks and DDD layers. The convention file specifies the exact rules for each layer, type, and file. "Default" is not a substitute.
• "No convention file exists — I'll invent conventions as I go" → Fall back to generic DDD rules from coding-isolated-domains. Invented conventions have no enforcement, no Rationalization Table defense, and no consistency guarantee.

Rationalization Table

If you catch yourself thinking any excuse in the left column — STOP and re-read the Reality column.

| Excuse | Reality | |:---|:---| | "I know this language well — skip reading conventions" | Language conventions contain project-specific rules (framework constraints, DDD layer conventions) not covered by general language knowledge. Read the file. | | "Language detection is obvious — I'll assume Go" | Assumption-based detection skips the file check. Run the detection. A wrong assumption cascades wrong conventions into all downstream code. | | "Convention file is too long — I'll skim the relevant section" | Convention rules are dense by design. Skimming misses constraints that produce hard-to-debug violations later. Read the relevant sections completely. | | "No convention file for this language — I'll make up conventions" | Fall back to generic DDD rules in coding-isolated-domains. Invented conventions have no enforcement and no RT defense. | | "Conventions conflict with the project's existing patterns — use the project's" | Conventions override existing patterns unless the human explicitly approves an exception. Silently following existing anti-patterns perpetuates them. | | "I'll create a convention file for this language on the fly" | Convention files require careful design (RT entries, section structure, project-specific rules). Ad-hoc creation produces untested constraints. STOP and inform the user. | | "Generic rules are good enough for this project" | Generic rules lack language-specific enforcement (import syntax, annotation patterns, naming conventions). A Java project with generic rules gets no @Entity tag detection, no package-info enforcement. | | "Phase 5/6 don't need language conventions — they're language-agnostic" | Phase 5 schema naming (proto package, DDL table names) and Phase 6 directory layouts are language-specific. Skipping conventions here produces schemas that conflict with the language's code generation toolchain. | | "Convention file

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.