Document Types

Archcore has 23 document types organized into 3 categories: 13 vision, 8 knowledge, and 2 experience. Each type has a template that the Archcore CLI generates. If you have not installed the CLI yet, get it from the CLI page.

The template sections listed below are what the CLI writes into a new document. A narrower set is checked after every write, and Precision checks lists it per type.

Choosing the right type

Need to record a final decision?           → adr
Need to propose a change for review?       → rfc
Need to enforce a team standard?           → rule
Need step-by-step instructions?            → guide
Need a contract for a boundary or feature? → spec
Need user flows and examples for a spec?   → scenario
Need reference/lookup material?            → doc
Need a record of one external material?    → evidence
Need to define product requirements?       → prd
Need to capture an early idea?             → idea
Need a user path before any spec exists?   → journey
Need to investigate before deciding?       → rnd
Need to map a territory with no decision?  → research
Need to plan implementation tasks?         → plan
Need market analysis (TAM, competitors)?   → mrd
Need business justification (ROI, budget)? → brd
Need user personas and journeys?           → urd
Need ISO business requirements?            → brs
Need ISO stakeholder requirements?         → strs
Need ISO system requirements?              → syrs
Need ISO software requirements?            → srs
Need to document a repeatable workflow?    → task-type
Need to record a coding pattern change?    → cpat

Let agents choose

When you work with an AI agent, describe what you want to document. The agent picks the type from these same rules, which are embedded in the MCP server instructions.

---

Vision

Where the product and project are heading. Vision documents are organized into three requirement tracks. Pick the one that matches your team’s complexity and process.

Product track (simple)

The starting point for most teams. Six types that cover the lifecycle from investigation through implementation.

PRD (Product Requirements Document)

Product requirements with goals, scope, and acceptance criteria.

File extension	.prd.md
When to use	Product requirements with goals and acceptance criteria are defined
Template sections	Vision, Problem Statement, Goals and Success Metrics, Requirements

Idea

A product or technical concept that needs capturing before it is fully formed.

File extension	.idea.md
When to use	A concept needs capturing for future evaluation
Template sections	Idea, Value, Possible Implementation, Risks and Constraints, Next Steps

Journey

The intended path of one user type through the system, written before a spec covering this interaction exists. Every step takes the actor as its subject and carries no data. Requires Archcore CLI 0.8.4 or later.

File extension	.journey.md
When to use	You want to agree on how a user should move through the system, and no spec for this interaction exists yet
Template sections	Intent, Actors, Journeys, Open Questions

Intent opens with the header In order to [goal] / As a [actor] / I want [outcome]. Actors is a table with the columns Actor, Who they are, and What they want. Journeys holds one ### subsection per actor, with numbered steps and an Extensions list.

The status of a journey records team agreement:

• accepted: the team agreed this is the wanted interaction
• rejected: the interaction was abandoned

By convention, a journey is related to its prd or idea. When a spec for the interaction exists, record the flow as a scenario that implements the journey.

RnD

A bounded investigation that answers an open question before a decision is made or work begins. Every rnd ends with a Recommendation (proceed, refine, defer, or stop) plus the single next action that follows from it.

File extension	.rnd.md
When to use	A bounded investigation is needed to answer a question before deciding or building
Template sections	Research Goal, Context and Trigger, Questions / Hypotheses, Approach, Findings, Implications, Recommendation, Next Action, Risks and Unknowns, Related Materials

An rnd sits in front of the committing tracks (rnd -> idea, rnd -> adr -> spec -> plan). Its status maps to the verdict:

• draft: still investigating
• accepted: recommendation adopted, proceed or refine
• rejected: defer or stop

A rejected rnd is a first-class outcome. Keep it in the repository, because “we investigated and decided not to” stays visible as a record of the dead end. By convention, prd/plan/adr depends_on an rnd, and an rfc may extend one; rnd never uses implements.

RnD vs Idea vs ADR vs RFC

An rnd investigates an open question and must conclude with a recommendation. Use it for “should we” and “which way.” An idea proposes a concept worth exploring, the “we could” case. An adr records a decision already made; gather evidence in an rnd, then record the resulting decision as an adr. An rfc puts a concrete proposal up for review. If there is nothing to propose yet, use rnd.

Research

An open investigation of a territory: a market landscape, a state-of-the-art review, a competitor watch. A research has no single decision behind it and closes on coverage of its declared scope, not on a verdict. It is revised as the territory changes.

File extension	.research.md
When to use	A territory needs mapping and no single decision waits on the answer
Template sections	Goal, Scope, Coverage, Sources, Findings, Synthesis, Open Gaps

The closing test separates the two investigation types: a verdict closes an rnd, coverage closes a research. The tense test is the same line: “we investigated X to decide Y” is an rnd; “we are mapping X” is a research.

The status of a research records the state of its synthesis:

• draft: the scope is not yet covered
• accepted: the synthesis is current as of its last revision
• rejected: abandoned, or fully replaced through supersedes

Sources are recorded as rows in the Sources table first. A source gets its own evidence document only when two documents rely on it, when a contradicts edge involves it, or when a newer material supersedes it. By convention, rnd depends_on research links a decision-bound investigation to the territory it draws on; a research never uses implements or extends. See Relations.

Research vs RnD vs Doc

A research maps a territory and closes when its scope is covered. An rnd answers one question and closes with a recommendation. A doc records reference information the team controls; a research records external knowledge with dated sources, coverage, and gaps.

Plan

An actionable plan with phased tasks and acceptance criteria.

File extension	.plan.md
When to use	An implementation plan with tasks is formed
Template sections	Goal, Tasks (phased), Acceptance Criteria, Dependencies, Notes

Sources track (discovery)

Captures where requirements come from: the market, the business, and users. Documents flow naturally from MRD (market landscape) to BRD (business justification) to URD (user needs).

MRD (Market Requirements Document)

Market analysis covering TAM/SAM/SOM, competitive landscape, market needs, and timing.

File extension	.mrd.md
When to use	Market analysis is needed before proposing a solution
Template sections	Market Landscape, TAM / SAM / SOM, Competitive Analysis, Market Needs, Opportunity and Timing, Risks, References

BRD (Business Requirements Document)

Business justification with objectives, stakeholders, constraints, and ROI.

File extension	.brd.md
When to use	Business justification and organizational impact need documenting
Template sections	Business Objectives, Stakeholders, Business Rules and Constraints, Success Metrics and ROI, Dependencies, Risks, References

URD (User Requirements Document)

User needs captured through personas, journeys, user requirements, usability, and acceptance criteria.

File extension	.urd.md
When to use	User needs, personas, and journeys need capturing during discovery
Template sections	User Personas, User Journeys, User Requirements, Usability Requirements, Acceptance Criteria, References

ISO track (decomposition)

Decomposes requirements through progressively detailed levels, following ISO/IEC/IEEE 29148:2018 on requirements engineering. BRS (why the business needs it) -> StRS (what stakeholders need) -> SyRS (how the system behaves) -> SRS (how the software works).

BRS (Business Requirements Specification)

Mission and goals, operational concept, business constraints, and traceability.

File extension	.brs.md
ISO reference	ISO/IEC/IEEE 29148:2018 §9.3
When to use	Business requirements need formalizing into ISO-structured specification
Template sections	Business Purpose and Scope, Business Overview, Mission, Goals and Objectives, Business Operations, Business Constraints, High-Level Operational Concept, Project Constraints, Success Criteria, Assumptions and Dependencies, Traceability

StRS (Stakeholder Requirements Specification)

Per-stakeholder-class requirements with concept of operations and traceability.

File extension	.strs.md
ISO reference	ISO/IEC/IEEE 29148:2018 §9.4
When to use	Stakeholder requirements need structuring per class with ConOps
Template sections	Purpose and Scope, System Overview, Business Context, Stakeholder Classes, Operational Concept (ConOps), Stakeholder Requirements, System Processes, Operational Policies and Rules, Operational Constraints, Compliance and Regulatory, Project Constraints, Traceability

SyRS (System Requirements Specification)

System boundary, system requirements, interfaces, and verification approach.

File extension	.syrs.md
ISO reference	ISO/IEC/IEEE 29148:2018 §9.5
When to use	The whole system boundary, interfaces, and verification need specifying
Template sections	System Purpose and Scope, System Overview, System Requirements, System Interfaces, System Operations, Policy and Regulation, Life Cycle Sustainment, Assumptions and Dependencies, Verification Approach, Traceability

SRS (Software Requirements Specification)

Per-function and per-endpoint specifications with a verification matrix.

File extension	.srs.md
ISO reference	ISO/IEC/IEEE 29148:2018 §9.6
When to use	Detailed software requirements need per-function/per-endpoint specification
Template sections	Purpose and Scope, Product Perspective, Software Requirements, External Interfaces, Data Requirements, Usability Requirements, Performance, Design Constraints, Software Quality Attributes, Verification Matrix, Traceability

Choosing the right requirements track

Track	Documents	Best for
Product (prd)	idea -> prd -> spec -> plan, with an optional journey and scenario	Individual features, small teams, rapid prototyping, internal tools
Sources (discovery)	mrd -> brd -> urd	Product teams doing discovery, stakeholder alignment, business analysis
ISO (decomposition)	brs -> strs -> syrs -> srs	Regulated systems, multi-team projects, complex distributed systems

Default to the Product track; move to Sources or ISO only when the project demands it.

The Archcore plugin produces these documents through /archcore:plan, which computes which of them a request actually needs. Putting sdd, sources, iso, or research as the first word runs that track’s path directly. Without the plugin, create the same documents through the MCP tools in the same order.

All three tracks can coexist. For example, use the Product track for a small feature while the full ISO track covers a safety-critical subsystem.

Sources vs specifications

Sources and specifications have separate purposes:

• Layer A (sources): mrd, brd, urd, and prd capture raw requirements from market, business, and user perspectives.
• Layer B (specifications): brs, strs, syrs, and srs formalize what sources capture informally. The implements relation connects the two layers.

Formalization runs one way: from source to specification, never the reverse.

PRD is a hybrid. It belongs to the sources layer, but it can substitute for the full ISO cascade. Link a PRD to ISO types with related, not implements.

When types look similar

The Sources and ISO tracks overlap in subject matter but differ in formality:

• MRD vs PRD: MRD analyzes the market (TAM/SAM/SOM, competitors, timing) without proposing a solution. PRD proposes a product with requirements and solution overview.
• BRD vs PRD: BRD focuses on business justification (ROI, budget, organizational impact). PRD focuses on product definition (features, user stories, solution).
• URD vs PRD: URD captures user needs via personas and journeys (discovery-oriented). PRD defines product requirements with acceptance criteria (specification-oriented).
• BRS vs BRD: BRS is an ISO specification (formalized structure). BRD is an informal source (business justification, ROI). BRS formalizes what BRD captures.
• StRS vs URD: StRS is an ISO specification (per-class requirements with ConOps). URD is an informal source (personas, journeys). StRS formalizes what URD captures.
• SyRS vs SRS: SyRS defines the whole system boundary. SRS specifies a single component’s detailed behavior.
• Journey vs URD, scenario vs StRS: journey and scenario belong to the Product track beside prd and spec. URD User Journeys and StRS Operational Scenarios belong to the Sources and ISO tracks. Use the Product-track pair unless your project runs those tracks.

---

Knowledge

Decisions, standards, reference material, user flows, and records of external materials.

ADR (Architecture Decision Record)

Records a decision that has been made.

File extension	.adr.md
When to use	A technical decision is made or finalized
Template sections	Context, Decision, Alternatives Considered, Consequences, Implementation Notes

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

## Context
We need a relational database with strong ACID guarantees...

## Decision
Use PostgreSQL 16 for all persistent storage...

## Alternatives Considered
- MySQL — fewer advanced features
- MongoDB — doesn't fit our relational model

## Consequences
### Positive
- Strong ACID guarantees
- Excellent JSON support via JSONB
### Negative
- Schema migrations required for changes

RFC (Request for Comments)

Proposes a significant change for team review.

File extension	.rfc.md
When to use	A significant change is being proposed
Template sections	Summary, Motivation, Detailed Design, Drawbacks, Alternatives, Security Considerations, Testing Strategy, Rollout Plan, Unresolved Questions, Implementation Plan

Rule

Imperative statements that the team must follow.

File extension	.rule.md
When to use	A team standard or required behavior is established
Template sections	Description, Rule, Rationale, Examples (Good/Bad), Exceptions, Enforcement

---
title: API Error Response Format
status: accepted
---

## Rule

1. ALL API errors MUST return a JSON body with `code`, `message`, and `request_id`
2. Error codes MUST use UPPER_SNAKE_CASE
3. HTTP status codes MUST match the error semantics (404 for not found, etc.)
4. Stack traces MUST NOT be included in production responses

## Rationale
Consistent error format enables clients to handle errors programmatically...

## Examples
### Good
...
### Bad
...

Guide

Step-by-step instructions for completing a specific task.

File extension	.guide.md
When to use	Step-by-step instructions need to be documented
Template sections	Overview, Prerequisites, Steps (numbered), Verification, Common Issues, Next Steps

Spec

A normative behavior contract for something others rely on: a boundary (API/interface/schema/protocol) or a feature/subsystem. You can capture a spec after the code exists or specify it ahead of the code. If the implementation diverges from the spec, the spec takes precedence.

A spec covers one subject and is not a general reference dump. Keep the body at or under 120 lines.

File extension	.spec.md
When to use	A normative contract with behavior, constraints, and conformance criteria is being formalized
Template sections	Purpose & Scope, Surface, Normative Behavior, Constraints & Invariants, Failure Behavior, Conformance

Write each Normative Behavior item as a numbered requirement in EARS clause order, with one uppercase BCP 14 keyword (MUST, SHOULD, or MAY, defined by RFC 2119 and RFC 8174) per requirement. EARS has four forms:

• Ubiquitous: The <subject> MUST <response>.
• Event-driven: WHEN <trigger>, the <subject> MUST <response>.
• State-driven: WHILE <state>, the <subject> MUST <response>.
• Unwanted behavior: IF <condition>, THEN the <subject> MUST <response>.

Failure Behavior items use the same notation, but each one takes the IF ..., THEN ... form, never WHEN.

---
title: Webhook Delivery Contract
status: accepted
---

## Purpose & Scope
This specification is normative for webhook delivery — how the system pushes
event payloads to subscriber endpoints.

Depended on by: subscriber integrations and the delivery worker.

Out of scope: the webhook management API (registration, listing, deletion).

## Surface
What dependents see of the subject. Reference source definitions with @-notation —
don't copy interface or struct bodies; copies go stale.

- Delivery worker: @internal/webhooks/delivery.go — sends each event to subscribers
- Signature header: `X-Signature` carries the payload HMAC
- States: queued → delivering → delivered | failed

## Normative Behavior
1. The system MUST deliver payloads as JSON with Content-Type `application/json`.
2. WHEN a delivery fails, the system MUST retry up to 5 times with exponential backoff.
3. The system SHOULD include an HMAC-SHA256 signature in the `X-Signature` header.

## Constraints & Invariants
- Constraint: payloads MUST NOT exceed 256 KB — keeps delivery within the request timeout.
- Invariant: each event MUST be delivered at least once to every active subscriber.

## Failure Behavior
1. IF all retries are exhausted, THEN the system MUST mark the delivery `failed` and stop.
2. IF a subscriber endpoint times out, THEN the system MUST re-queue the delivery for retry.

## Conformance
An implementation conforms when it satisfies all MUST requirements, all
invariants, and all failure rules above.

Spec vs Doc vs Rule

A spec defines a normative contract for a specific technical boundary: how a component must behave. A doc is non-behavioral reference material (registries, glossaries, lookup tables). A rule sets a cross-cutting team standard (“Always do X”). If you are documenting how one system works → spec. If you are describing what exists → doc. If you are prescribing how engineers must act → rule. If the document answers “what should we build and why” (user stories, priorities, success metrics) → prd or an ISO type, not a spec.

Scenario

How a user or an external actor moves through the system, with concrete Given/When/Then examples that illustrate the clauses of one existing spec. Every step takes the actor as its subject and carries no BCP 14 modal. The rules stay in the spec. Requires Archcore CLI 0.8.4 or later.

File extension	.scenario.md
When to use	A spec exists, and you need to show how an actor uses it, with concrete examples
Template sections	Subject, Actors, Flows, Examples, Open Questions

Flows holds one ### subsection per actor. Each subsection opens with an Anchors: line of @path references to the code and test files that the flow walks. Examples holds a Background block and titled examples, each with an Illustrates: line and unfenced Given/When/Then lines. Keep the body at or under 120 lines; past that, split the scenario by actor.

---
title: Refund Request
status: draft
tags:
  - "actor:customer"
---

## Subject
Order service refunds — the system this document illustrates.

Illustrates: clauses 1 and 2 of the linked spec.

## Actors
| Actor | Who they are | What they want |
|---|---|---|
| Customer | A buyer with a paid order | Money back for a returned book |

## Flows
### Customer
Anchors: @src/refunds/handler.go, @features/refund.feature

1. Customer requests a refund; the service shows the refund as approved.

## Examples
### Refund within 14 days

Illustrates: clause 1

Given Anna bought a book on 1 Sep
When she requests a refund on 10 Sep
Then she sees the refund approved

Archcore does not run a scenario. Executable examples stay in your test tree, for example features/*.feature, and a document cites them with @path. The status of a scenario records a reader’s check:

• accepted: a reader confirmed the examples against the running system, by a test run or by hand
• rejected: the examples no longer hold and no replacement was written

By convention, a scenario depends_on the one spec it illustrates, so an edit to the spec reaches the scenario through the cascade notice. A scenario implements its journey when one exists. Tags such as actor:<type>, component:<name>, and nfr:<concern> are a convention, not a fixed list.

Spec vs Scenario vs Journey

The subject of the line decides. A spec clause obligates the component with a modal: “WHEN the user requests a refund, the service MUST approve it”. A scenario step takes the actor as its subject and has no modal: “Anna requests a refund on 10 Sep; she sees the refund approved”. If a spec that the document illustrates exists, use scenario. If no spec exists yet, use journey.

Doc

Non-behavioral reference material: registries, glossaries, lookup tables, and component lists.

File extension	.doc.md
When to use	Non-behavioral reference material like registries, glossaries, or lookup tables needs documenting
Template sections	Overview, Content, Examples, Best Practices, FAQ

Rule vs Doc

A rule contains imperative statements (“Always do X”, “Never do Y”) with enforcement info. A doc is non-behavioral reference material. If it prescribes behavior, use rule. If it describes what exists, use doc.

Evidence

A record of one external material: a report, a page, a dataset, an interview. An evidence carries the address of the material, the access date, and the extract another document relies on. It never carries the file itself. A snapshot, when kept, lives outside .archcore/.

File extension	.evidence.md
When to use	Two documents rely on one source, a contradicts edge involves it, or a newer material replaces it
Template sections	Locator, Extract, Notes

The Locator section opens with fixed lines: address, access date, publication date when known, publisher when known. The frontmatter stays title, status, and tags. The class of the material travels as a tag: source:primary, source:secondary, source:measurement, source:interview, or source:dataset.

The material test decides the type: an evidence is one material, never one statement. A finding inside a research or an rnd stays a line in that document. Most sources stay rows in a Sources table and never become a file.

The status values keep their names and gain one reading:

• draft: recorded by whoever found the material
• accepted: a second reader confirmed that the material exists and that the extract is in it
• rejected: retracted or found unreliable

The second reader is a convention. The CLI does not fetch, hash, or snapshot a source.

Evidence vs Doc

An evidence records one material and its extract. A doc records reference information that may combine several materials.

---

Experience

Patterns learned from doing the work. You can ignore these types at first. They become useful once your team has enough practice to recognize repeatable patterns.

Task type

A proven workflow for a recurring implementation task.

File extension	.task-type.md
When to use	A proven workflow for a recurring task is documented
Template sections	What, When to Use, Steps, Example, Things to Watch Out For

CPAT (Code Pattern Change)

Records how and why a coding convention or pattern changed.

File extension	.cpat.md
When to use	A coding pattern or convention has deliberately changed
Template sections	What Changed, Why, Before, After, Scope, Notes

---
title: Switch from Callbacks to Async/Await
status: accepted
---

## What Changed
All asynchronous code now uses async/await instead of callbacks.

## Why
Callbacks led to deeply nested code and inconsistent error handling...

## Before
\`\`\`javascript
getUser(id, (err, user) => {
  if (err) return handleError(err);
  getOrders(user.id, (err, orders) => { ... });
});
\`\`\`

## After
\`\`\`javascript
const user = await getUser(id);
const orders = await getOrders(user.id);
\`\`\`

## Scope
All files in `src/services/` and `src/handlers/`.

---

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 of them 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

Two documents holding one statement have no single owner. An edit to one leaves the other stating the opposite, and a reader cannot tell which of the two binds.

The prd template carries four sections for this reason. A section it does not own is not offered to the author, and the graded behavior that satisfies a prd requirement goes in the linked spec.

Two post-write checks report a crossing of the boundary. A foreign-section finding names a heading whose content another type owns. A restatement finding names a statement that survived a move from a linked document nearly word for word. Both are advisory and reject nothing. See Precision checks.

Next steps

• Commands and examples shows how to use this reference in your agent.
• Project context explains the document model.