Project structure and conventions
This skill defines the binding standards for directory structures, file
names, and ways of working. All other skills (BA, RE, Architecture,
Coding, Testing, Security Audit) follow these conventions. Details live
in references/; load a reference file only when the task touches its
area.
Codebase-awareness (core principle)
All skills operate in the context of the existing codebase, never in a
vacuum. Read references/codebase-awareness.md for the complete rules.
Summary: before any work, read existing code, recognize patterns,
understand dependencies, check reference implementations. The project's
CLAUDE.md takes PRECEDENCE over generic skill instructions.
Canonical Specs (single home; other skills link here)
Index. Full detail: references/canonical-specs.md. Phase skills and
templates never restate these specs; they link here.
- Reader budget. Every artifact scannable in under two minutes,
enforced as per-artifact line caps in the single source
references/artifact-caps.json (read at runtime by
/consistency-check; never mirror the values). Exceeding a cap
needs a one-line ## Reasoned exception block at the top of the
file, added only with justification, never routinely.
ARCHITECTURE-MAP, MODULE-README, JSDOC-HEADER and RULES-* carry
their caps in their template comments.
- Frontmatter spec. Identity and relations only;
status,
phase, author, claim are forbidden (N-15). Empty refs are
omitted, never stubbed. Full key list in the reference.
- Backlog vocabulary. Binding column order, GitHub-aligned status
values, phase tags
<id>/<phase>-done, DIA commit trailers
(DIA-Phase, DIA-Handoff, DIA-Triage), ID schema, Claim and
Refs column formats. Full vocabulary in the reference.
- Writing style. Zero em/en dashes, no AI vocabulary, active
voice, sentence case in headings. Blacklist and pre-save scan:
references/writing-style.md (single home, also used by
/humanizer).
- Activation Path format. Fixed
## Activation Path section in
every FEATURE spec, parsed by N-18. Exact format in the reference.
- Priority / Effort legend. P0-P3 and XS-XL definitions in the
reference. XL at FEAT scope means: split first.
- Three-layer model. Wayfinder / rule sets / backlog / detail
artifacts with binding boundaries, the ADR abstraction rule (A-1)
and the ADR/FEATURE/PLAN separation:
references/three-layer-model.md.
- Section policy. Sections are emitted only when they carry
decision content; optional sections live in template comments, not
as
TBD placeholders.
Backlog as single source of truth
State lives in the BACKLOG row, never in artifact frontmatter. The row
exists before the artifact and changes before the body. Lifecycle and
sync chain: references/backlog-sot.md.
Directory structure
Full reference: references/directory-structure.md.
{project}/
_devprocess/ -- Internal knowledge archive (not public)
analysis/ -- Flat: BA-, EXPLORE-, AUDIT-, RESEARCH- (sources/ for user files)
requirements/ -- Epics, features, fixes, improvements, handoff
architecture/ -- ADRs, arc42
rules/ -- Stable rule sets (full profile), max 500 lines total
implementation/plans/ -- PLAN files
context/ -- BACKLOG.md, BACKLOG-HISTORY.md, METRICS.md
src/ -- Source code + ARCHITECTURE.map + module READMEs
docs/ -- Public documentation (English)
scripts/ memory/ .claude/ -- Tooling, memory, Claude config
CLAUDE.md -- Project-specific context
File name conventions
Full reference: references/naming-conventions.md. Rules: 2-digit
counters, kebab-case slugs, no spaces, no umlauts in file names.
Features are numbered within their epic (FEAT-{ee}-{ff}-{slug}.md),
which keeps parallel epic work conflict-free and sort order stable.
Language conventions
| Context |
Language |
| Conversation with user |
User's language |
| Commit messages |
English, conventional prefixes |
Private documentation (_devprocess/) |
Match the user's chat language |
Public documentation (docs/, README) |
English |
| Code, identifiers, skill files |
English |
Artifact-language rule (binding, incl. the one clarifying question on
ambiguity): references/canonical-specs.md#artifact-language-binding.
Plan structure
Every non-trivial plan has: 1. Context (diagnostic, root cause),
2. Changes (per file, BEFORE/AFTER), 3. File summary table,
4. Not affected (blast radius), 5. Verification (build is step 1).
Git workflow
- Dual-remote: private (origin, all branches) + public (only main)
- Branch flow:
feature/* -> dev -> main -> public/main
- Safe-merge: merges to dev via
scripts/merge-to-dev.sh
- Commits: conventional prefixes, Co-Authored-By Claude, DIA trailers
on phase-end commits (see canonical spec 3)
- Two-stage stripping for public (dev tooling, then internal docs)
Initializing a project
Base structure, initial files, and the full mkdir block:
references/canonical-specs.md#initializing-a-project. In the lean
profile, rules consolidate into AGENTS.md instead of
_devprocess/rules/; see skills/dia-setup/SKILL.md.
Keywords
Project structure, conventions, init, project setup, directory
structure, naming conventions, coding standards, way of working
1---2name: project-conventions3description: Defines project structure, naming conventions, and way of working for all projects; other skills link here for the canonical specs. Use when the user mentions "project setup", "project structure", "conventions", "init", "initialize project", "directory structure", or starts a new project.4---56# Project structure and conventions78This skill defines the binding standards for directory structures, file9names, and ways of working. All other skills (BA, RE, Architecture,10Coding, Testing, Security Audit) follow these conventions. Details live11in `references/`; load a reference file only when the task touches its12area.1314## Codebase-awareness (core principle)1516All skills operate in the context of the existing codebase, never in a17vacuum. Read `references/codebase-awareness.md` for the complete rules.18Summary: before any work, read existing code, recognize patterns,19understand dependencies, check reference implementations. The project's20`CLAUDE.md` takes PRECEDENCE over generic skill instructions.2122## Canonical Specs (single home; other skills link here)2324Index. Full detail: `references/canonical-specs.md`. Phase skills and25templates never restate these specs; they link here.26271. **Reader budget.** Every artifact scannable in under two minutes,28 enforced as per-artifact line caps in the single source29 `references/artifact-caps.json` (read at runtime by30 `/consistency-check`; never mirror the values). Exceeding a cap31 needs a one-line `## Reasoned exception` block at the top of the32 file, added only with justification, never routinely.33 ARCHITECTURE-MAP, MODULE-README, JSDOC-HEADER and RULES-* carry34 their caps in their template comments.352. **Frontmatter spec.** Identity and relations only; `status`,36 `phase`, `author`, `claim` are forbidden (N-15). Empty refs are37 omitted, never stubbed. Full key list in the reference.383. **Backlog vocabulary.** Binding column order, GitHub-aligned status39 values, phase tags `<id>/<phase>-done`, DIA commit trailers40 (`DIA-Phase`, `DIA-Handoff`, `DIA-Triage`), ID schema, Claim and41 Refs column formats. Full vocabulary in the reference.424. **Writing style.** Zero em/en dashes, no AI vocabulary, active43 voice, sentence case in headings. Blacklist and pre-save scan:44 `references/writing-style.md` (single home, also used by45 `/humanizer`).465. **Activation Path format.** Fixed `## Activation Path` section in47 every FEATURE spec, parsed by N-18. Exact format in the reference.486. **Priority / Effort legend.** P0-P3 and XS-XL definitions in the49 reference. XL at FEAT scope means: split first.507. **Three-layer model.** Wayfinder / rule sets / backlog / detail51 artifacts with binding boundaries, the ADR abstraction rule (A-1)52 and the ADR/FEATURE/PLAN separation:53 `references/three-layer-model.md`.548. **Section policy.** Sections are emitted only when they carry55 decision content; optional sections live in template comments, not56 as `TBD` placeholders.5758## Backlog as single source of truth5960State lives in the BACKLOG row, never in artifact frontmatter. The row61exists before the artifact and changes before the body. Lifecycle and62sync chain: `references/backlog-sot.md`.6364## Directory structure6566Full reference: `references/directory-structure.md`.6768```69{project}/70 _devprocess/ -- Internal knowledge archive (not public)71 analysis/ -- Flat: BA-, EXPLORE-, AUDIT-, RESEARCH- (sources/ for user files)72 requirements/ -- Epics, features, fixes, improvements, handoff73 architecture/ -- ADRs, arc4274 rules/ -- Stable rule sets (full profile), max 500 lines total75 implementation/plans/ -- PLAN files76 context/ -- BACKLOG.md, BACKLOG-HISTORY.md, METRICS.md77 src/ -- Source code + ARCHITECTURE.map + module READMEs78 docs/ -- Public documentation (English)79 scripts/ memory/ .claude/ -- Tooling, memory, Claude config80 CLAUDE.md -- Project-specific context81```8283## File name conventions8485Full reference: `references/naming-conventions.md`. Rules: 2-digit86counters, kebab-case slugs, no spaces, no umlauts in file names.87Features are numbered within their epic (`FEAT-{ee}-{ff}-{slug}.md`),88which keeps parallel epic work conflict-free and sort order stable.8990## Language conventions9192| Context | Language |93|---------|----------|94| Conversation with user | User's language |95| Commit messages | English, conventional prefixes |96| Private documentation (`_devprocess/`) | Match the user's chat language |97| Public documentation (`docs/`, `README`) | English |98| Code, identifiers, skill files | English |99100Artifact-language rule (binding, incl. the one clarifying question on101ambiguity): `references/canonical-specs.md#artifact-language-binding`.102103## Plan structure104105Every non-trivial plan has: 1. Context (diagnostic, root cause),1062. Changes (per file, BEFORE/AFTER), 3. File summary table,1074. Not affected (blast radius), 5. Verification (build is step 1).108109## Git workflow110111- Dual-remote: private (origin, all branches) + public (only main)112- Branch flow: `feature/*` -> `dev` -> `main` -> `public/main`113- Safe-merge: merges to dev via `scripts/merge-to-dev.sh`114- Commits: conventional prefixes, Co-Authored-By Claude, DIA trailers115 on phase-end commits (see canonical spec 3)116- Two-stage stripping for public (dev tooling, then internal docs)117118## Initializing a project119120Base structure, initial files, and the full `mkdir` block:121`references/canonical-specs.md#initializing-a-project`. In the lean122profile, rules consolidate into AGENTS.md instead of123`_devprocess/rules/`; see `skills/dia-setup/SKILL.md`.124125## Keywords126127Project structure, conventions, init, project setup, directory128structure, naming conventions, coding standards, way of working
pssah4