Naming Conventions — Talent Factory

Maintained by: Nora · Nomenclature Specialist Last updated: 2026-03-16

General Rules

1. Language: English only — no translations, no mixed languages
2. No abbreviations unless universally understood (e.g., API, CI/CD, QA, CTO, TFD)
3. Maximum length: 3-4 words per name segment (aim for clarity within brevity)
4. Characters: Only lowercase alphanumeric and hyphens in file system names (no underscores, spaces, or special characters)
5. Descriptive: Names should be self-explanatory — a new team member should understand what it is without reading its contents

Directory Naming

Rule	Convention	Example
Case	kebab-case, lowercase	client-services/, infrastructure-engineer/
Length	1-4 words	quality/, production-lines/
Specificity	Use the full descriptive name, not abbreviations	nomenclature-specialist/ not nom-spec/
Department dirs	Match the department name from org chart	engineering/, methodology/
Role dirs	Match the role name from org chart, kebab-case	infrastructure-engineer/, nomenclature-specialist/
Subdirectories	Describe the contents (plural when containing multiple items)	standards/, processes/, decisions/

File Naming

Rule	Convention	Example
Case	kebab-case, lowercase	naming-conventions.md, role.md
Extension	Always include the appropriate extension	.md, .json, .yaml
Length	1-4 words (excluding extension)	org-chart.md, eval-cases.md
Specificity	Describe the file's purpose or content	naming-conventions.md not standards.md
Canonical files	Use the standard name for role artifacts	role.md, agent.md, eval-cases.md, test-report.md

Role Naming

Context	Convention	Example
In documentation	Title Case	Infrastructure Engineer, Nomenclature Specialist
In directory names	kebab-case, lowercase	infrastructure-engineer/, nomenclature-specialist/
Persona names	First letter matches role initial	Ivan (Infrastructure), Nora (Nomenclature)
In org chart	Title Case, with department prefix where needed	Engineering > Infrastructure Engineer

Persona names are factory-internal only (TFD-0029)

Persona names (Edward, Ivan, Nora…) are an internal factory device for both factory workers and the talents the factory builds. They are not propagated to client deployments: a delivered talent is branded by function for the client (e.g. "l'agent AE STM", "agent-ea"), never given a client-facing human persona name. This follows the founding principle Factory workers ≠ Products. Example: the EA talent is Edward inside the factory; its STM deployment carries no persona name (the earlier client-side "Arnaud" is to be stripped).

Command Naming

Role-owned commands

Rule	Convention	Example
Case	kebab-case, lowercase	name-check, infra-scaffold
Prefix	Role abbreviation (3-5 chars) + hyphen	name- for Nomenclature, infra- for Infrastructure
Action	Verb or noun describing the action	-check, -review, -scaffold, -standards
File	Same as command name with .md extension	name-check.md, infra-scaffold.md
Location	Always in .claude/commands/	.claude/commands/name-check.md

Reserved prefixes

Prefix	Role
infra-	Infrastructure Engineer
name-	Nomenclature Specialist
request-	Request lifecycle (cross-departmental workflow)
role-	Role Factory (workflow)

This table grows as roles are built. Each role claims a unique prefix. Workflow prefixes (request-, role-) are cross-departmental and not owned by a single role.

Toolkit commands (cross-cutting)

General-purpose skills reusable across all agents and projects use the toolkit: colon namespace.

Rule	Convention	Example
Namespace	toolkit: prefix (colon, not hyphen)	toolkit:note-create, toolkit:auto-research
File location	.claude/commands/toolkit/ subdirectory	.claude/commands/toolkit/note-create.md
File naming	kebab-case, 1-4 words	note-create.md, auto-research.md
Source	Managed in bockbr/toolkit-catalog repo	Installed via /toolkit use or manual copy
Scope	Not owned by any role — usable by anyone	No role prefix needed

When a skill is general-purpose (not role-specific), it belongs in the toolkit namespace.

Request/Order Naming

Updated 2026-05-28 PM per TFD-0028 (slug restored on factory folders + TFD files; supersedes TFD-0026 §"no slug" rule). The ID format from TFD-0026 stands; only the folder NAMING gains a slug back.

Rule	Convention	Example
ID	{TYPE}-{NNNN} (canonical identifier, used in frontmatter + cross-refs)	RD-0008, CON-0004, MET-0008, WO-0008
Folder name	{TYPE}-{NNNN}-{slug}/ (slug for human recognition)	RD-0008-token-efficiency-eval/, CON-0004-stm-electrician-safety-cadenassage-process/
Slug rule	[a-z0-9][a-z0-9-]*, lowercase, alphanumerics + hyphens, soft cap 60 chars	derived from title: frontmatter; strip diacritics
Number	Zero-padded 4-digit, per-type sequence	0001, 0008, 0042
Metadata file	request.md (RD/CON/MET/INF) or order.md (WO)	Lowercase
Required frontmatter	id, title, dept, requestor, assignee, status, created	Title and dept live here too (slug in folder name is for recognition only)
Subfolders	input/, process/, output/	Lowercase
Location (R&D)	departments/executive/requests/{RD-NNNN}-{slug}/	departments/executive/requests/RD-0008-token-efficiency-eval/
Location (Consulting)	departments/consulting/requests/{CON-NNNN}-{slug}/	departments/consulting/requests/CON-0004-stm-electrician-safety-cadenassage-process/
Location (Methodology)	departments/methodology/requests/{MET-NNNN}-{slug}/	departments/methodology/requests/MET-0008-macroscope-rendering-templates-a100-a230-a280/
Location (work orders)	production-lines/orders/{WO-NNNN}-{slug}/	production-lines/orders/WO-0008-maya-conversational-kb-talent/
TFD file	company/decisions/TFD-{NNNN}-{slug}.md	company/decisions/TFD-0027-client-demande-hierarchy-flat-with-prefix-jira-synced.md
Notes in input/	note-{subject}.md	input/note-togaf-research.md
Q&A records	note-{subject}-qr.md alongside the note	input/note-togaf-research-qr.md

Type catalog (TFD-026 §Type catalog):

Type	Meaning	Owner pattern
RD	R&D evaluations (tools, patterns, ecosystem scans)	Riley
CON	Consulting requests (client-billable work)	Philippe
MET	Methodology infrastructure (frameworks, standards)	Marcel / Francois / Nora
WO	Work orders for digital talent production	Production line
DAE	Client EA deliverables	EA agent
TFD	Talent Factory Decisions	CEO + stakeholders
CI	Continuous improvement items	Various

New types get their own 2-3 letter prefix on first use — never invented retroactively, never collapsed into a generic REQ. Prefix max length: 3 chars.

Department lookup: the dept: frontmatter field uses the codes below for redundancy and search. Codes no longer appear in the folder name — dept is signaled by location plus frontmatter.

Code	Department
CS	Client Services
ENG	Engineering
EXEC	Executive
ARCH	IT Architecture
KM	Knowledge Management
METH	Methodology
OPS	Operations
QA	Quality Assurance
CONS	Consulting
PROD	Production Line

The voice-dictation contract is the test: "RD zero zero zero eight" must round-trip to RD-0008 without ambiguity. Slugs, dept codes, or prefixes longer than 3 chars break this.

Client-side artifact IDs (TFD-027)

Inside OneDrive/agent-ea/clients/<slug>/, every artifact uses {TYPE}-{NNNN} with a global sequence per type (TFD-026 compliant). These are client-side identifiers, distinct from the factory-side REQ/WO/CI catalog above.

Type	Prefix	Sequence	Use
Initiative	INIT-NNNN	global across clients	transformation, multi-demande business context
Demande EA	DAE-NNNN	global across clients (continues existing sequence)	architecture work-package (full mode)
Demande PM	PM-NNNN	global across clients (new sequence, starts 0001)	project-management work-package
Demande Ops	OPS-NNNN	global across clients (new sequence)	run-the-business work
Demande OCM	OCM-NNNN	global across clients (reserved)	organisational change management
Light-mode request	REQ-NNNN	global across clients (client-side, separate from factory REQ)	quick intake before discipline is known; discipline: unclassified until classified

Rules:

• Folder name = {ID}-{slug}/ (slug KEPT for client-side recognition; departs from TFD-026 no-slug rule which applies only to factory artifacts). Full title still in frontmatter.
• Slug rule: [a-z0-9][a-z0-9-]* — lowercase, alphanumerics + hyphens. Concise but descriptive (DAE-0007-evaluation-systemes, INIT-0002-electrification).
• Light-mode demande = a single {ID}-{slug}.md at the client root. Promotion to folder keeps the slug (DAE-0011-evaluation-wifi.md → DAE-0011-evaluation-wifi/).
• Sub-demande = sister folder with parent_demande: <ID> in frontmatter — never a suffix scheme like DAE-0007-A.
• Parent relation (parent_initiative XOR parent_capacite) is mandatory on every demande.
• Status enum (shared across init / demande / sub-task): backlog | active | blocked | done | cancelled.
• REQ collision: factory REQ-NNNN (in departments/) and client-side REQ-NNNN (in clients/) are separate sequences, disambiguated by location. Always qualify in cross-references.

See TFD-027 for the full hierarchy and frontmatter schemas.

TFD (Decision Record) Naming

Updated 2026-05-28 per TFD-026: file slug dropped, number zero-padded to 4 digits. Title lives in the document body.

Rule	Convention	Example
Format	TFD-NNNN	TFD-0026
Number	Zero-padded 4-digit, auto-incrementing	0001, 0026
File	TFD-NNNN.md	TFD-0026.md
Location	company/decisions/	company/decisions/TFD-0026.md
Title	Lives in first H1 of the file, never in filename	# TFD-0026: DAE-Style Global IDs

Production Line Naming (Phase 2+)

Rule	Convention	Example
Case	kebab-case, lowercase	customer-support-agent/
Format	Describes the digital talent type produced	sales-assistant/, onboarding-specialist/
Location	production-lines/{line-name}/	production-lines/customer-support-agent/

Client Deliverable Naming (Phase 2+)

Rule	Convention	Example
Case	kebab-case, lowercase	acme-support-agent
Format	{client-slug}-{deliverable-type}	acme-support-agent, globex-onboarding-bot
No internal names	Client deliverables never expose internal Talent Factory names	Not tf-acme-prod-line-3

Jira Naming

Type	Pattern	Example
Epic	[DEPT] Description — scope qualifier	[QA] Quality gates — prevent escapes
Story (with ref)	[REQ-NNNN] or [CI-NNNN] Verb + object	[CI-0038] Adopt DAE-style global IDs across factory
Task	Verb + object (plain, short)	Create TOGAF adaptation guide for Enterprise Architect
Bug	Fix + description	Fix Mermaid diagrams in Confluence — use macro plugin

Rules:

1. Language: English only (same as general rule #1)
2. Max length: ~60 characters (Jira truncates around 70)
3. Verb-first (Stories/Tasks/Bugs): Start with an action verb (Add, Analyze, Audit, Build, Complete, Create, Define, Design, Document, Enable, Enforce, Evaluate, Explore, Fix, Implement, Make, Publish, Remove, Run, Test, Update, Upgrade, Validate, Verify, Write)
4. No numbering prefixes: No 4.1 —, 1.2 —, Epic N — patterns
5. Department prefix on epics: Use [DEPT] bracket prefix from the department code table. After [DEPT], use a descriptive noun phrase (epics are themes, not actions)
6. Cross-reference prefix on stories: Use [REQ-NNNN] or [CI-NNNN] in brackets when the story maps to a factory request or CI item (4-digit zero-padded per TFD-026)
7. Em-dash for scope: Use — (spaced em-dash) to separate the main title from a scope qualifier

Jira Issue Body Standards

All issues use a two-zone template: Human Zone (top, for approval) and Agent Zone (bottom, for execution), separated by ---.

Story body

Section	Zone	Required	Format
User Story	Human	Yes	As a {role}, I want {goal} so that {benefit}
Context	Human	Yes	1-3 sentences: why now, what triggered it
Scope	Human	Yes	In/Out bullets
Acceptance Criteria	Human	Yes	Given {x}, when {y}, then {z} — binary, testable
Definition of Done	Human	Yes	Checklist of completion checks
Agent Context > References	Agent	Yes	File paths, request IDs, TFDs
Agent Context > Constraints	Agent	Yes	What to touch/not touch, patterns
Agent Context > Verification	Agent	Yes	Commands to confirm done

Epic body

Section	Zone	Required
Goal	Human	Yes
Scope / Out of Scope	Human	Yes
Success Criteria	Human	Yes
Owner	Human	Yes
Agent Context > Dependencies	Agent	Yes

Task body

Section	Zone	Required
What	Human	Yes
Acceptance Criteria	Human	Yes
Definition of Done	Human	Yes
Agent Context (References, Constraints, Verification)	Agent	Yes

Bug body

Section	Zone	Required
Problem	Human	Yes
Steps to Reproduce	Human	Yes
Expected vs Actual	Human	Yes
Fix Criteria	Human	Yes
Agent Context (References, Constraints, Verification)	Agent	Yes

Source of truth

• request.md / order.md in the repo are the source of truth
• Jira descriptions are synced copies — same two-zone structure
• Templates: workflows/templates/request-template.md, workflows/templates/order-template.md

EA Object Naming (Capability / Process / Business Service)

Applies to all enterprise-architecture catalogs produced for clients (LeanIX v4 model: Business Capability, Process, Business Service). Aligned with BIZBOK and ArchiMate so names are industry-standard, not invented.

Object	Rule	Example
Business Capability	Noun / business-object phrase. Never a verb, no gerund (BIZBOK). Stable, outcome-oriented.	Contract Management
Process / Value Stream	Verb + object construct (APQC PCF). Describes the action performed.	Manage contracts and mandates
Business Service	Noun phrase, value-oriented (ArchiMate). Names the value offered, not the "how". No tool/product name (products live on the Application layer via realized-by).	Electronic signature

Rules:

1. Capability ≠ Process: capabilities are nouns (what the business can do); processes are verb-noun (how it does it). Do not mix.
2. No product names in service/capability names: Consigno, Sage, SAP etc. belong to Application fact sheets, never the service name.
3. One value per service: a Business Service names a single externally-visible unit of value to a consumer.
4. Language: follow the deliverable's language (client deliverables = client language; internal = English).
5. Sources: BIZBOK Guide (capabilities = nouns); APQC PCF (processes = verb-noun); ArchiMate (services = value noun phrase).

Reference application: DAE-0007 Transgesco business-service catalogue (out/_skeletons-executifs/04-catalogue-services-affaires-leanix.html).

Anti-patterns (Do NOT use)

Pattern	Problem	Correct alternative
camelCase	Inconsistent with kebab-case standard	kebab-case
snake_case	Underscores not allowed in file system names	kebab-case
UPPER_CASE	Reserved for environment variables, not file names	kebab-case
Abbreviations (nom-spec)	Not self-descriptive	nomenclature-specialist
Numbers as prefixes (01-setup)	Creates ordering dependencies	Use descriptive names
Generic names (utils, misc, stuff)	Not descriptive	Name by purpose: standards, templates
Verb in a capability name (Manage contracts)	Capability ≠ process (BIZBOK)	Noun: Contract Management
Tool name in a service (Consigno signing)	Mixes Application into the Business layer	Value noun: Electronic signature