# Language Conventions

> >

- **Type:** Skill
- **Install:** `agentstack add skill-lockp111-agent-ddd-engineering-language-conventions`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lockp111](https://agentstack.voostack.com/s/lockp111)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lockp111](https://github.com/lockp111)
- **Source:** https://github.com/lockp111/agent-ddd-engineering/tree/main/skills/language-conventions

## Install

```sh
agentstack add skill-lockp111-agent-ddd-engineering-language-conventions
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/lockp111)
- **Source:** [lockp111/agent-ddd-engineering](https://github.com/lockp111/agent-ddd-engineering)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lockp111-agent-ddd-engineering-language-conventions
- Seller: https://agentstack.voostack.com/s/lockp111
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.