Naming conventions
Contract C2 — canonical identifiers and filenames for A2C artifacts.
Repository: a2c-workflow
Enforced in: a2c_core.contracts.id_format, a2c_core.services.validation
Planning artifact IDs
Core invariants (always enforced)
| Rule | Behavior |
|---|---|
id required | Non-empty string in front matter |
id unique | Unique across all Epics, Tasks, and Sprints in the repo |
type required | Must match directory: epic / task / sprint |
| Filename | Should match id; mismatch emits warning A2C_NAME_004 |
A2C does not force a specific ID style unless id_format.enabled: true in .a2c/config.yaml.
When ids are omitted at apply time, a2c_core allocates the next id for the artifact kind:
| Mode | Example ids | Config |
|---|---|---|
| Jira-like (default) | TASK-1, EPIC-2 | id_format.pattern default or task_prefix / epic_prefix / sprint_prefix |
| GitLab numeric | 1, 2, 3 | id_format.enabled: true and pattern: '^[0-9]+$' |
Recommended shape (Jira-like, optional)
When teams have no existing convention, prefer:
- Pattern:
PREFIX-NUMBER(uppercase prefix, hyphen, positive integer) - Examples:
EPIC-1,EPIC-0001,TASK-101,SPRINT-3,PROJ-1234 - Loose regex:
^[A-Z][A-Z0-9]+-[0-9]+$
When strict mode is off, IDs outside this shape (slug IDs, pure numbers, legacy keys) still work.
A2C may emit non-fatal warning A2C_ID_003 suggesting the recommended shape.
Configurable strict validation
# .a2c/config.yaml
id_format:
enabled: false # default: permissive
pattern: '^[A-Z][A-Z0-9]{1,9}-[0-9]+$'
task_prefix: TASK # allocated ids: TASK-1, TASK-2, …
epic_prefix: EPIC # allocated ids: EPIC-1, EPIC-2, …
sprint_prefix: SPRINT # allocated ids: SPRINT-1, SPRINT-2, …
Set task_prefix, epic_prefix, or sprint_prefix to override the default
string segment (for example A2C → A2C-1). Prefixes apply to allocation when ids are
omitted; they are ignored when pattern is GitLab numeric (^[0-9]+$).
enabled | Behavior |
|---|---|
false | Only core invariants; no regex on id |
true | id must match pattern; failure code A2C_ID_001 |
Example patterns:
| Team style | pattern |
|---|---|
| Jira-like (default) | ^[A-Z][A-Z0-9]{1,9}-[0-9]+$ |
| GitLab numeric | ^[0-9]+$ |
| Strict house style | `^(EPIC |
Other identifiers
| Kind | Pattern | Example |
|---|---|---|
| Workflow ID | ^[a-z][a-z0-9_]*$ | a2c, superbuild |
Filenames and paths
| Artifact | Path | Filename rule |
|---|---|---|
| Config | .a2c/config.yaml | Fixed name |
| Workflow manifest | docs/workflow-manifest.yaml | Fixed name |
| Epic | planning/epics/<id>.md | <id> should match epic ID in front matter |
| Task | planning/tasks/<id>.md | <id> should match task ID in front matter |
| Sprint | planning/sprints/<id>.md | <id> should match sprint ID in front matter |
| ADR | docs/adr/ | NNNN-kebab-title.md |
Error codes
| Code | Meaning |
|---|---|
A2C_ID_001 | id does not match configured id_format.pattern |
A2C_ID_002 | Duplicate planning artifact id |
A2C_ID_003 | Recommended ID shape suggestion (warning) |
A2C_NAME_001 | Invalid or empty artifact id |
A2C_NAME_002 | Invalid ADR filename |
A2C_NAME_003 | Invalid workflow ID |
A2C_NAME_004 | Filename does not match id (warning) |
A2C_SCHEMA_004 | type does not match planning directory |
A2C_FORMAT_001 | Legacy pure-YAML planning artifact |
A2C_FORMAT_002 | Deprecated .a2c/planning/ location |