PARA Classification

Busflow adapts Tiago Forte's PARA method as machine-readable metadata for AI agent triage and documentation lifecycle management. Every file under docs/ carries a para_category frontmatter field that directs agent behavior, determines file placement, and governs the document's lifecycle.

Category Definitions

Category	Purpose	Agent Behavior	Folder
project	Active, time-bound initiative with an end state	Ignore unless the task explicitly relates to this project	`docs/1-projects/<name>/`
area	Ongoing standard, living spec, or domain knowledge	Read when working in the relevant domain	`docs/2-areas/<domain>/`
resource	Reference lookup material (schemas, protocols, ADRs, runbooks)	Read when exact specs or contracts are needed	`docs/3-resources/<type>/`
archive	Completed or superseded content	Never read unless explicitly asked	`docs/4-archive/`

Projects

Time-bound initiatives with a clear end state: BSFZ funding, GoBD compliance, GDPR migration. A project produces outputs (decisions, specs, learnings) and then completes or is abandoned. Use expires_on in frontmatter when a hard deadline exists — the linter flags expired projects as errors.

Examples: docs/1-projects/bsfz-funding/, docs/1-projects/docs-review/

Areas

Ongoing standards and living specs that evolve but never "finish." Architecture decisions, product scope, design principles, process guidelines — these define how Busflow works and agents read them when operating in the relevant domain.

Examples: docs/2-areas/architecture/frontend.md, docs/2-areas/product/PRODUCT_identity.md

Resources

Stable reference material that agents consult for exact specifications. Schemas, protocols, event contracts, ADRs, runbooks, templates. ADRs are immutable — agents never modify them.

Resources carry an inherent assumption: they may not reflect current reality. Unlike areas (which define how things should work), resources document how things were specified. When a resource contradicts the codebase, the codebase wins — the resource needs updating or archiving.

Examples: docs/3-resources/reference/ci-cd.md, docs/3-resources/decisions/adr-029-secrets-and-encryption.md

State Transitions

Documents move between categories when their purpose changes. Each transition has a trigger and produces a specific action.

project ──→ area       Outputs become ongoing standards
project ──→ archive    Initiative is completed or abandoned
area    ──→ resource   Living spec crystallizes into a stable reference
area    ──→ archive    Standard is superseded by a new approach
resource ──→ archive   Contract, schema, or ADR is superseded

Common Transitions

project → area — The most frequent transition. When a project produces durable outputs (architecture decisions, process guidelines, domain models), those outputs graduate into area docs. The project itself moves to archive.

Example: BSFZ research on CRDT-based trip planning produces adr-032-collaborative-trip-planning.md (resource) and updates to docs/2-areas/architecture/realtime-strategy.md (area).

project → archive — When a project completes or is abandoned. The project folder moves to docs/4-archive/. Outputs that became areas or resources remain in their respective folders.

Example: A completed compliance migration. The project checklist is archived; the compliance spec stays as an area doc.

resource → archive — When a resource is superseded. A new ADR replaces an old one. A schema version is deprecated.

Example: adr-015-auth-strategy.md is superseded by adr-029-secrets-and-encryption.md.

Rare Transitions

area → resource — Occurs when a living spec stabilizes and no longer evolves. The document shifts from "how we work" to "how we specified it." This is uncommon because most standards keep evolving.

area → archive — When an entire approach is abandoned. The area doc is superseded by a fundamentally different standard. Rare because areas typically evolve incrementally rather than getting replaced wholesale.

How to Transition

Update the para_category frontmatter field.
Move the file to the correct folder.
Update any related: edges in other files that pointed to the old path.
Run pnpm docs:lint to verify no broken links.

Content Lifecycle

Review Cadence

date_last_reviewed tracks the last date a human validated the document's accuracy. Agents must not bump this field on routine edits — it specifically records human review.

Area docs receive a CI warning when date_last_reviewed is older than 365 days. This nudge prompts a human to check whether the standard still matches actual practice. The warning does not block commits or CI — it surfaces in the lint output as informational.

Projects manage their own lifecycle through expires_on. No time-based staleness check applies — the motivation to keep the projects folder lean is intrinsic.

Resources do not receive time-based staleness warnings. Resources age by relevance, not by time — an ADR from 2024 that accurately documents a decision is not stale. A resource becomes an archive candidate when nothing references it anymore (no related: edges, no backlinks, no inline links). The reference graph, not the calendar, determines a resource's lifecycle.

Archives are frozen. No staleness checks apply.

Content Placement Guide

Keep durable intent separate from volatile implementation snapshots:

Content Type	Where It Belongs	Update Rule
Stable intent, principles, domain language	`docs/2-areas/**`	Keep concise and implementation-light
Exact contracts, schemas, event payloads	`docs/3-resources/**`	Update when the contract changes
Operational procedures	`docs/3-resources/runbooks/**`	Keep executable and step-oriented
Time-bound plans, checklists, migration work	`docs/1-projects/**`	Add `expires_on` when there is a hard deadline
Superseded ideas or completed context	`docs/4-archive/**`	Preserve only when historically useful
Package/app usage details	Adjacent `README.md`	Prefer colocated docs over central wiki pages

When an area doc starts accumulating step-by-step implementation details, extract those details into a resource, runbook, ADR, or colocated README and link to it.

Frontmatter Spec

→ See ADR-034 for the authoritative frontmatter schema specification.

Required Fields

yaml

---
para_category: area              # project | area | resource | archive
date_last_reviewed: 2026-05-06   # last human-validated date
---

Optional Fields

yaml

---
tags: [gdpr, compliance, dev]                        # from docs/.tags.yml
related:                                              # directed graph edges
  - docs/2-areas/architecture/database.md             # Löschmechanik
summary: One-liner for triage and search results.     # ≤200 chars
code_refs: [apps/api/src/gdpr/]                       # advisory code pointers
sources: [https://gdpr-info.eu/art-17/]               # authoritative external refs
expires_on: 2026-06-30                                # projects with hard deadlines
---

→ See guidelines.md for the full "when to use which" decision table and ADR frontmatter exceptions.

Enforcement

Pre-commit hook validates para_category and date_last_reviewed on every docs/**/*.md file.
CI linter (scripts/lint-docs.mjs) additionally validates tags: against docs/.tags.yml, checks related: path resolution, enforces summary length limits, and validates code_refs: / sources: format.
Area staleness produces a CI warning (not error) when date_last_reviewed exceeds 365 days.

References

The PARA Method — original blog post by Tiago Forte
Building a Second Brain — book (Forte, 2022) covering the full methodology
ADR-034: Frontmatter Spec — authoritative schema definition

Busflow Docs

PARA Classification ​

Category Definitions ​

Projects ​

Areas ​

Resources ​

Archives ​

State Transitions ​

Common Transitions ​

Rare Transitions ​

How to Transition ​

Content Lifecycle ​

Review Cadence ​

Content Placement Guide ​

Frontmatter Spec ​

Required Fields ​

Optional Fields ​

Enforcement ​

References ​