Document Format

An Archcore document is a Markdown file with YAML frontmatter and a <slug>.<type>.md filename. The parser requires title and status, accepts tags, and retains every other frontmatter key without interpreting or validating it. From CLI v0.8.3, update_document writes those retained keys back after title, status, and tags, so a key you add by hand survives an update through the MCP tool.

File naming

Every document follows the <slug>.<type>.md pattern. See Documents & Layout for full naming rules, valid types, and directory organization.

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

tags

Tags are cross-cutting labels. They categorize a document by team, domain, or topic, which the directory structure alone cannot express.

---
title: E2E Auth Flow Testing
status: accepted
tags:
  - frontend
  - team:backend
  - payment_flow
---

Tags must match ^[a-z][a-z0-9_:|-]*$: lowercase, with hyphens, underscores, colons, and pipes allowed. Colons enable namespace-like conventions (e.g., team:payments). Tags are stored sorted and deduplicated. Invalid tags are rejected with a “did you mean?” hint.

When tags are absent, the field is omitted from output. Documents without tags parse and work normally.

tags is the only optional frontmatter field. The parser interprets exactly three keys: title, status, and tags. Any other key (for example, an arbitrary meta: block) is retained as written: Archcore does not interpret or validate it, and update_document writes it back after the three owned keys.

Content structure

After the frontmatter, the content is standard Markdown. Each document type has sections generated by the template.

Only the frontmatter is validated when a document is written: title must be present and non-empty, and status must be draft, accepted, or rejected. The body is measured separately by the precision checks, which report a missing section, a vague word, or a misplaced requirement after the write. Those findings are advisory and never reject a document.

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.

Writing with the plugin

The Archcore plugin loads shared writing rules and the selected document type’s content contract before composing a document. The contract defines what the document needs to say; the prose profile defines how to say it. A Markdown body remains editable text, but the plugin does not treat it as an unrestricted essay.

Match the prose to its job

Job	How to write it	Example types
State an obligation	One requirement, a named actor, one uppercase BCP 14 modal; put a condition before the obligation	spec, rule
Give a procedure	One action per step, written as an imperative without a requirement modal	guide, task-type, tasks in a plan
Explain a decision or finding	State the claim, its reasons, evidence, and trade-offs; do not turn the argument into obligations	adr, rfc, research
Record reference information	Use named fields or tables for enumerable facts, with brief explanations where needed	doc, evidence

For example, a requirement can say:

When a token has expired, the API MUST reject the request with HTTP 401.

A procedure instead says:

Run archcore --version to check the installed version.

A decision record explains why the choice was made and which alternatives were rejected. It does not require MUST in every sentence. These examples illustrate prose forms, not rules your project must adopt.

Keep the reasoning precise

Lead with the result or conclusion. Use one term consistently, separate facts from assumptions, and name current versus planned behavior. Replace claims such as “fast” or “scalable” with evidence and measurement context; mark an ungrounded technical claim [assumption] rather than presenting it as established behavior.

Reference implementation through @path/to/file instead of copying function bodies. Preserve literal examples when their exact form is the point, such as commands in a guide or before-and-after code in a cpat. Connect Archcore documents through relations rather than maintaining a second related-document list in the body.

The sentence-focused profile uses clauses of at most 25 words and procedure steps of at most 20 words. The argument-focused profile preserves reasoning and evidence rather than forcing every statement into a short requirement. The profile table lists the assignment for every type.

These are internal profiles inspired by ASD-STE100 and ISO plain-language principles, not a claim of standards certification. The plugin writing rules describe the authoring conventions.

Separate authoring rules from enforcement

The plugin applies the conventions before a write. The CLI’s precision checks report a mechanical subset afterwards. They can identify a missing heading or a long clause; they cannot establish whether an argument is sound or a factual claim is true.

A successful write does not mean that every writing rule passed. Findings are advisory, and accepting a document remains your decision. The reference below distinguishes measured checks from the broader authoring guidance.

Template generation

When you create a document through the create_document MCP 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]

Precision checks

Precision checks report document structure and writing findings. They are advisory; they do not establish factual accuracy.

Prose profiles

Every document type carries one of two profiles. The profile decides which checks may report on the type, so an adr is never measured by a step’s word cap and a guide is never graded for a modal it does not owe.

Profile	Meaning	Types
STE	Lines instruct or obligate	spec, rule, guide, task-type, brs, strs, syrs, srs
ISO	Lines argue or describe	adr, rfc, doc, evidence, scenario, prd, plan, idea, rnd, research, journey, cpat, mrd, brd, urd

Two further tables decide which numbered items a check may read at all.

Table	Types and sections	What the items are
Graded clauses	spec: Normative Behavior, Failure Behavior. rule: Rule	Requirements graded with a BCP 14 modal
Procedure steps	guide: Steps. task-type: Steps. plan: Tasks	Actions the reader takes
Actor-subject steps	scenario: Flows, Examples. journey: Journeys	Actions an actor takes, or Given/When/Then observations

A numbered item outside these sections is prose. In an actor-subject section, a line that opens with Given, When, Then, And, or But is a step whether or not it carries a number. An adr enumerates its alternatives without owing them a modal, and the four ISO 29148 types carry their requirements as identified table rows rather than numbered clauses, so neither is graded as a clause.

Checks that run on every type

Finding	Fires when
Vague wording	The body uses a word or phrase from the vagueness lexicon. Headings are excluded. Up to 5 offenders are named
Missing section	A required ## section for the type is absent. See Checked sections
Foreign section	The body carries a heading whose content another type owns. See Content ownership
Frontmatter	title is missing or empty, or status is missing or invalid
Placeholder body	The body is under 200 characters, counted in characters so a short non-ASCII document is flagged the same way
Cross-document links	The body links other .archcore/ documents instead of using add_relation. Up to 3 are named
Long code block	A code block of 5 or more lines in a type that argues rather than instructs: adr, rfc, doc, prd, idea, plan, mrd, brd, urd, brs, strs, syrs, and srs. Other types are exempt. A rule, a guide, a cpat, and an evidence need the literal text, because that text is the artifact
Restatement	A statement survived a move from a linked document nearly word for word. See Restatement

The vagueness lexicon covers English (appropriate, robust, scalable, modern, various, optimal, efficient, flexible, convenient, seamless, streamlined), Russian stems (оптимальн, удобн, правильн, надёжн, надежн, гибк, современн, передов, эффективн, масштабируем), and the phrases best practices, as needed, world class, and cutting edge.

Checks driven by the profile tables

These read the graded clauses and the procedure steps of the type, so a type outside both tables never receives them.

Finding	Fires when
Requirement over 25 words	A graded clause runs past the word cap
Step over 20 words	A procedure step or an actor-subject step runs past the word cap
Compound requirement	A graded clause carries two modals. MUST NOT counts once
Condition after the obligation	A graded clause states its trigger after the response instead of opening with WHEN, WHILE, or IF
Open-ended list	A clause or step ends with etc., and so on, и т.д., or и т.п.
Ambiguous alternative	A clause or step uses and/or or и/или
BCP 14 modal in a step	A procedure step or an actor-subject step carries MUST, SHOULD, SHALL, or MAY
BCP 14 modal in a claim	A numbered item of an ISO-profile type carries a modal. The graded behavior belongs in a linked spec or rule

Modals are matched case-sensitively. A lowercase must in prose is not a graded obligation and is not reported.

Checks for one type

Type	Finding	Fires when
spec	SHALL notation	The body uses SHALL instead of MUST, SHOULD, or MAY
spec, scenario, journey	Oversized body	The body exceeds 120 lines. The finding names the line count and the cap
spec	Subjectless passive	A graded clause states an obligation with no obligated component as its subject. Up to 3 are named
prd	EARS clause in a requirement	A numbered requirement opens with WHEN, WHILE, or IF. A prd requirement states an outcome, and the trigger and response form belongs in a spec
rule	No file target	No graded clause names a path or a glob, so the code-alignment injection can never match the rule to an edited file
rule	Enforcement names no verifier	The Enforcement section names no hook, lint rule, CI step, or test, and does not say manual review
adr	Bullets in Context	The Context section uses a bullet list. Fenced blocks are excluded
adr	One alternative recorded	Alternatives Considered holds a single item
adr	Alternative with no stated reason	An alternative does not say what ruled it out. Up to 5 are named
cpat	Before or After holds no code block	The section describes the form that changed instead of showing it
scenario	Flow without an Anchors line	A ### subsection under Flows has no line that opens with Anchors:
scenario, journey	Step opens with no actor	A step under Flows or Journeys opens with neither an actor from the Actors table nor Given, When, Then, And, or But. Skipped when the Actors table is absent

Thresholds

Threshold	Value
Findings per report	12
Minimum body length	200 characters
Graded clause length	25 words
Procedure step length	20 words
spec, scenario, and journey body length	120 lines each
Code block length in an ISO-profile type	5 lines
Restatement overlap	0.85
Documents read per restatement check	5

Checked sections

The missing-section check reads this table. It is narrower than the generated template: a template offers sections the author may fill, and this table lists the ones the type owes its reader.

A heading matches by prefix, followed by whitespace or the end of the line. ## Purpose & Scope therefore satisfies Purpose, and ## Purposeful does not.

Type	Checked sections
adr	Context, Decision, Alternatives Considered, Consequences
rfc	Summary, Motivation, Detailed Design, Drawbacks, Alternatives
rule	Rule, Rationale, Enforcement
guide	Prerequisites, Steps, Verification
spec	Purpose, Surface, Normative Behavior, Conformance
doc	Overview
prd	Vision, Problem, Goals, Requirements
idea	Idea, Value, Risks and Constraints
rnd	Approach, Findings, Recommendation, Next Action
research	Goal, Scope, Coverage, Sources, Findings, Synthesis, Open Gaps
evidence	Locator, Extract, Notes
plan	Goal, Tasks, Acceptance Criteria
mrd	Market Landscape, Competitive Analysis, Market Needs
brd	Business Objectives, Stakeholders, Success Metrics and ROI
urd	User Personas, User Requirements, Acceptance Criteria
brs	Business Purpose and Scope, Mission, Goals and Objectives, Business Constraints, Success Criteria
strs	Purpose and Scope, Stakeholder Classes, Stakeholder Requirements, Operational Concept
syrs	System Purpose and Scope, System Requirements, System Interfaces, Verification Approach
srs	Purpose and Scope, Software Requirements, External Interfaces, Verification Matrix
task-type	When to Use, Steps
cpat	Why, Before, After, Scope
scenario	Subject, Actors, Flows, Examples, Open Questions
journey	Intent, Actors, Journeys, Open Questions

Several sections accept an older spelling so a rename does not turn existing documents into findings. Alternatives satisfies Alternatives Considered, Procedure satisfies Steps, Contract Surface satisfies Surface, Rationale satisfies a cpat’s Why, ConOps satisfies Operational Concept, and Verification satisfies both Verification Approach and Verification Matrix.

Content ownership

Each kind of content has one owning document type and one section inside it. A track produces several documents on one topic and links them with implements, so the boundary decides which document a statement belongs in.

Content kind	Owner	Section
Wanted outcome, beneficiary, threshold	prd	Requirements
Measured goal with units and a target value	prd	Goals and Success Metrics
Graded behavior: EARS clauses, BCP 14 modals	spec	Normative Behavior
Interfaces, signatures, states, field-driven rules	spec	Surface
Error, edge, and degradation handling	spec	Failure Behavior
Phases, tasks, milestones, delivery dates	plan	Tasks
Rejected alternative and the reason it was rejected	adr	Alternatives Considered
Intended user path before a spec exists	journey	Journeys
User flow anchored to code	scenario	Flows
Concrete example with data that illustrates a spec clause	scenario	Examples

The foreign-section check names a heading whose content another type owns, and names that type:

section ## Normative Behavior in a prd — a spec owns that content; link the two documents instead

Seven types carry an ownership table:

Type	Headings it must not carry	Owner
prd	Surface, Normative Behavior, Failure Behavior, Conformance, Solution Overview, Technical Considerations	spec
prd	Tasks, Timeline, Milestones, Phases, Acceptance Criteria	plan
prd	Alternatives Considered	adr
prd, spec	Flows, Examples	scenario
prd, spec	Journeys	journey
scenario, journey	Surface, Normative Behavior, Failure Behavior	spec
scenario, journey	Requirements	prd
mrd, brd, urd	Mission, Goals and Objectives	brs
mrd, brd, urd	Operational Concept, Stakeholder Requirements	strs
mrd, brd, urd	System Requirements, Verification Approach	syrs
mrd, brd, urd	Software Requirements, Verification Matrix	srs

Only unambiguous headings carry an owner. A prd names a business constraint inside its Problem Statement without owing the reader a Constraints section, so Constraints is deliberately absent and produces no finding. A rule and a doc have their own Examples section, so the Examples row applies only to prd and spec.

Restatement

The restatement check compares the written document against the documents its content flows from or into, and names a statement that survived the move nearly word for word.

• Which documents it reads. Neighbours across implements and extends, in both directions, sorted then capped at 5. related and depends_on are excluded: an association implies no content flow, and a dependency orders two documents without moving text between them.
• What it compares. List items only, at least 6 content-carrying words long. Prose paragraphs and fenced blocks are skipped, because a paragraph restates by summarizing and this comparison would report those at random.
• What counts as a restatement. Token overlap at or above 0.85. A copied line scores 1.0; a prd requirement and the spec behavior that grades it score well under the threshold.
• What it reports. At most 3 findings, one per statement however many neighbours carry it.

The check is deliberately restricted to near-verbatim copies. Two documents on one topic share vocabulary, and paraphrase detection would report exactly the pairs that are meant to differ.

If the sync manifest cannot be loaded, the check returns nothing rather than guessing. A missed finding costs a glance; a wrong one costs trust in the report.

Next steps

• Document types explains the content each type holds.
• MCP tools describes validated writes.
• Troubleshooting covers failed mutations.