Planning artifact format
Epics, Tasks, and Sprints are Markdown files with YAML front matter stored under the
visible planning/ directory at the repository root. They are first-class project
artifacts — not tool-internal metadata.
Repository and workspace configuration remains pure YAML under .a2c/ and docs/.
Repository: a2c-workflow
Parsed by: a2c_core.services.frontmatter, a2c_core.services.loader
Repository layout
repo-root/
├── planning/ # human-facing planning artifacts
│ ├── epics/<id>.md
│ ├── tasks/<id>.md
│ └── sprints/<id>.md
├── .a2c/ # tool-internal storage only
│ ├── config.yaml
│ ├── cache/ # optional
│ └── indexes/ # optional
└── docs/ # workflow docs, ADRs, manifest
Planning artifacts must not live under .a2c/. Use .a2c/ for configuration, caches,
indexes, and other machine-owned data that humans rarely edit directly.
Format rules
- File starts with
---on the first line. - YAML metadata block follows until a closing
---line. - Everything after the closing delimiter (and optional blank line) is the Markdown body.
- Filename is
<artifact-id>.md; theidin front matter must match (mismatch → warning). - Required front matter:
type,id,title. Unknown fields are ignored.
| Artifact | Directory | Example filename |
|---|---|---|
| Epic | planning/epics/ | epic-m2-contracts.md |
| Task | planning/tasks/ | task-define-models.md |
| Sprint | planning/sprints/ | sprint-m2.md |
Front matter vs Markdown body
| Location | Purpose |
|---|---|
| Front matter | Machine-parseable metadata: type, id, title, status, references, optional version |
| Markdown body | Human-readable narrative: summary, context, acceptance criteria, notes, links |
Optional short summary may still appear in front matter; prefer the Markdown body for longer prose.
Epic example
---
version: 1
type: epic
id: EPIC-0001
title: Schemas and core contracts
status: active
summary: Milestone 2 artifact contracts
task_ids:
- task-define-models
- task-add-validation
---
# Schemas and core contracts
## Summary
Define and validate the minimum durable contracts for A2C repository artifacts.
## Acceptance criteria
- Core models load from Markdown front matter.
- Invalid artifacts fail with structured validation output.
Task example
---
version: 1
type: task
id: TASK-0101
title: Define core models
status: done
epic_id: EPIC-0001
---
# Define core models
## Summary
Implement Pydantic models for Epic, Task, and Sprint metadata.
## Acceptance criteria
- Models reject unknown front matter fields.
- Required fields are documented and tested.
Sprint example
---
version: 1
type: sprint
id: SPRINT-0003
title: Milestone 2 sprint
status: active
task_ids:
- task-define-models
- task-add-validation
---
# Milestone 2 sprint
## Summary
Deliver schemas, validation, and repository loading foundations.
## Acceptance criteria
- Fixture repository validates successfully.
- Planning artifacts render well in browser and editor views.
Legacy formats and locations
| Legacy | Warning code | Canonical replacement |
|---|---|---|
Pure .yaml under planning/ or .a2c/planning/ | A2C_FORMAT_001 | <id>.md with YAML front matter under planning/ |
Markdown under .a2c/planning/ | A2C_FORMAT_002 | Move to planning/<kind>/<id>.md |
The loader reads canonical planning/ first, then deprecated .a2c/planning/ for artifacts
not already loaded. New artifacts must be created only under planning/.
Migration steps:
- Move files from
.a2c/planning/{epics,tasks,sprints}/toplanning/{epics,tasks,sprints}/. - Convert any remaining pure
.yamlfiles to.mdwith front matter (see above). - Remove empty
.a2c/planning/directories.
Templates: pathname:///a2c-assets/templates/planning/.
ID validation
See naming-conventions.md for core ID rules, the recommended Jira-like
shape, and the optional id_format block in .a2c/config.yaml.