# Document Format > Document filenames, frontmatter, plugin writing conventions, prose profiles, templates, and advisory checks. An Archcore document is a Markdown file with YAML frontmatter and a `..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 [Section titled “File naming”](#file-naming) Every document follows the `..md` pattern. See [Documents & Layout](/concepts/project-context/#documents-and-layout) for full naming rules, valid types, and directory organization. ## Frontmatter [Section titled “Frontmatter”](#frontmatter) Every document requires YAML frontmatter with `title` and `status`: ```yaml --- title: Use PostgreSQL as Primary Database status: accepted --- ``` ### Required fields [Section titled “Required fields”](#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 [Section titled “Status values”](#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 [Section titled “Optional fields”](#optional-fields) #### tags [Section titled “tags”](#tags) Tags are cross-cutting labels. They categorize a document by team, domain, or topic, which the directory structure alone cannot express. ```yaml --- 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 [Section titled “Content structure”](#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](/reference/document-format/#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 [Section titled “Code references”](#code-references) Documents may reference source code using `@`-notation: ```markdown 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 [Section titled “Writing with the plugin”](#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 [Section titled “Match the prose to its job”](#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 [Section titled “Keep the reasoning precise”](#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](#prose-profiles) 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](https://github.com/archcore-ai/archcore/blob/main/plugins/archcore/skills/_shared/precision-rules.md) describe the authoring conventions. ### Separate authoring rules from enforcement [Section titled “Separate authoring rules from enforcement”](#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 [Section titled “Template generation”](#template-generation) When you create a document through the [`create_document`](/reference/mcp-tools/#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: ```markdown ## 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 [Section titled “Precision checks”](#precision-checks) Precision checks report document structure and writing findings. They are advisory; they do not establish factual accuracy. ### Prose profiles [Section titled “Prose profiles”](#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 [Section titled “Checks that run on every type”](#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](#checked-sections) | | Foreign section | The body carries a heading whose content another type owns. See [Content ownership](#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](#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 [Section titled “Checks driven by the profile tables”](#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 [Section titled “Checks for one type”](#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. For a `spec`, the plugin counts only the five contract sections and ignores the finding when they fit | | `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](/guides/connect-your-agent/#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 [Section titled “Thresholds”](#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 [Section titled “Checked sections”](#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 [Section titled “Content ownership”](#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: ```text 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 [Section titled “Restatement”](#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 [Section titled “Next steps”](#next-steps) * [Document types](/concepts/document-types/) explains the content each type holds. * [MCP tools](/reference/mcp-tools/) describes validated writes. * [Troubleshooting](/guides/troubleshooting/) covers failed mutations.