Document Format

File Naming

Every document follows the pattern:

<slug>.<type>.md

Slug Rules

• Lowercase letters and numbers only
• Words separated by hyphens
• Must match: ^[a-z0-9]+(-[a-z0-9]+)*$

Valid: jwt-strategy, use-postgres, api-v2-migration

Invalid: JWT_Strategy, use postgres, my.decision

Valid Types

adr, rfc, rule, guide, doc, prd, idea, plan, task-type, cpat

Examples

use-postgres.adr.md
api-versioning.rfc.md
error-handling.rule.md
ci-cd-setup.guide.md
api-endpoints.doc.md
auth-redesign.prd.md
caching-layer.idea.md
q1-migration.plan.md
api-endpoint-creation.task-type.md
callbacks-to-async.cpat.md

Frontmatter

Every document requires YAML frontmatter with title and status:

---
title: Use PostgreSQL as Primary Database
status: accepted
---

Required Fields

Field	Type	Description
title	string	Human-readable document title. Must not be empty
status	string	Document status: draft, accepted, or rejected

Status Values

Status	Meaning
draft	Work in progress (default for new documents)
accepted	Finalized or approved
rejected	Superseded, abandoned, or declined (preserves history)

Optional Fields

The meta field can hold arbitrary YAML metadata:

---
title: API Rate Limiting Standards
status: accepted
meta:
  author: team-backend
  reviewed: 2025-01-15
---

Content Structure

After the frontmatter, content is standard Markdown. Each document type has recommended sections (generated by the template), but the structure is not enforced beyond frontmatter validation.

Code References

Documents may reference source code using @-notation:

See the implementation at @cmd/init.go and @internal/config/config.go.

This is optional but helps agents navigate between documentation and code.

Template Generation

When creating a document through the MCP create_document tool without providing content, Archcore generates a template with all required and recommended sections for that type.

For example, an ADR template includes:

## Context
[Describe the situation and problem]

## Decision
[What was decided and why]

## Alternatives Considered
[Other options that were evaluated]

## Consequences
### Positive
- [Benefit 1]

### Negative
- [Trade-off 1]

### Risks
- [Risk 1]

## Implementation Notes
[Key implementation details]

## References
- [Link 1]