AIFC-012: Metadata and Markdown

Status: Draft 0.1 Standard: AI-First Community Standard Short name: AIFC Related to:

• AIFC-000: Manifesto for AI-First Communities
• AIFC-001: Core Concepts
• AIFC-002: Community Model
• AIFC-010: Knowledge Structure
• AIFC-011: Operational DNA

Purpose of this document: Define principles for writing an AIFC knowledge base in a human-readable, agent-actionable, and software-verifiable form. Describe the role of Markdown, metadata, standardized structure, lifecycle, owners, sensitivity, AI access, and maintenance.

1. Purpose of this document

This document describes how an AIFC community knowledge base should be written.

An AIFC knowledge base should be simultaneously:

human-readable
agent-actionable
software-verifiable

This means that one source of knowledge must serve three types of readers:

• a person,
• an AI agent,
• software or a validator.

Markdown is a natural candidate because it is readable, simple, versionable, and widely supported. On its own, however, it is not enough.

AIFC therefore combines:

Markdown
+ metadata
+ standardized structure
+ validation rules
+ Human Cockpit Layer

2. Core principle

The core principle of this document is:

Markdown gives knowledge a readable body.
Metadata gives knowledge a manageable structure.
Validation gives knowledge operational reliability.

AIFC must not create a system that only AI or only developers understand.

The knowledge base must remain readable to people.

At the same time, it must not remain only free text without structure, because such documentation is difficult to validate, maintain, and use agentically.

3. Why Markdown

Markdown is suitable for AIFC because it supports several key principles:

• it is readable without a special application,
• it can be versioned in Git,
• changes are easy to compare,
• AI can read it well,
• it is portable across tools,
• it can combine text and structure,
• it supports long-term maintainability,
• it reduces vendor lock-in.

Markdown is not a mandatory AIFC technology.

It is the reference text format.

AIFC may be implemented differently if the implementation preserves:

• human readability,
• exportability,
• versioning,
• metadata,
• auditability,
• agent-actionability,
• validation.

Minimum requirement

AIFC knowledge artefacts must be exportable into a human-readable and machine-processable form.

4. Markdown alone is not enough

Markdown alone is not enough.

Free text may be readable to a person, but software has difficulty determining:

• who the owner is,
• whether content is approved,
• whether content is outdated,
• what sensitivity applies,
• whether AI may read it,
• which values it relates to,
• what lifecycle it has,
• when it should be reviewed,
• whether it is a rule, proposal, decision, or note.

Without metadata, the knowledge base gradually turns into documentation chaos.

Minimum requirement

Critical knowledge artefacts must have metadata.

5. Metadata

Metadata is structured information about a knowledge artefact.

It describes, for example:

• artefact type,
• status,
• owner,
• sensitivity,
• AI access,
• lifecycle,
• links to values,
• links to decisions,
• review date,
• affected communities,
• confidence,
• source,
• validation.

Metadata is not decoration.

It is the operational layer that enables:

• navigation,
• audit,
• validation,
• workflow,
• Human Cockpit Layer,
• AI agentic behavior,
• security,
• cleanup,
• maintenance,
• reporting,
• compliance.

Minimum requirement

Metadata must be simple enough for people and AI to maintain, but structured enough to enable validation.

6. Recommended metadata placement

AIFC recommends using metadata either:

1. at file level,
2. at section level,
3. at block level,
4. or in combination.

6.1 File-level metadata

Useful for documents with one clear purpose.

Example:

---
aifc_type: values
status: active
owner: community-owner
sensitivity: internal
ai_access: allowed
review_cycle: quarterly
last_reviewed: 2026-06-15
---

6.2 Section-level metadata

Useful for long documents where different parts have different status, owner, or sensitivity.

Example:

## AI-NDA Boundary

metadata:
  status: approved
  owner: security-owner
  sensitivity: restricted
  ai_access: limited

6.3 Block-level metadata

Useful where individual blocks have separate meaning, lifecycle, or approval.

For example:

• individual change proposals,
• individual rules,
• individual decisions,
• individual skills,
• individual risks,
• individual assumptions.

Block-level metadata allows the Human Cockpit Layer to display and manage content in smaller parts.

Minimum requirement

An AIFC implementation must define at which level metadata is used and how it is inherited between folder, file, section, and block.

7. Metadata inheritance

Metadata may be inherited from a higher structure.

For example, a folder may define:

/work/maintenance/high-priority/

and provide default values:

work_type: maintenance
priority: high

A file or block may refine or temporarily override these values.

Metadata inheritance reduces repetition.

It can also create inconsistency risk.

For example, a file is in a maintenance folder but a block inside has work_type: change.

This may not be an error. It may be a signal that the block should be moved or reclassified.

Minimum requirement

An AIFC implementation must define inheritance rules and conflict resolution rules between inherited metadata and explicit metadata.

8. Reclassification and cleanup

The knowledge base evolves.

An artefact may change:

• type,
• priority,
• owner,
• sensitivity,
• status,
• AI access,
• lifecycle,
• decision level.

AIFC must therefore support reclassification.

Reclassification may be performed:

• manually by a person,
• through the Human Cockpit Layer,
• by AI agent proposal,
• or by a cleanup agent.

A cleanup agent may regularly check whether metadata matches location, structure, and rules.

For example:

• a task is in the wrong folder,
• a block has high priority but is in a low-priority file,
• a document is active but contains deprecated sections,
• AI access is allowed but sensitivity is restricted,
• an artefact has no owner,
• a workflow is critical but has no fallback.

Minimum requirement

An AIFC knowledge base must have a mechanism for detecting and resolving metadata conflicts.

9. Avoid fragile sequential IDs

AIFC does not recommend using human-visible sequential IDs as the primary identity of blocks.

For example:

TASK-001
TASK-002
TASK-003

Such IDs are fragile when content is inserted between existing items, moved, or merged.

They may create:

• need for renumbering,
• gaps,
• duplicate IDs,
• misleading order,
• conflict between identity and position.

AIFC recommends separating:

identity
order
display order
priority

Artefact identity should be stable. Order and priority may change.

Minimum requirement

If an implementation uses IDs, it must distinguish stable artefact identity from its order in a document or backlog.

10. Stable identity

Stable artefact identity may be based on:

• UUID,
• short random ID,
• hash-based ID,
• system-generated ID,
• combination of namespace and ID,
• or identity stored in metadata.

Example:

id: cp_8f3a91
type: change_proposal

A stable ID does not have to be beautiful to people.

People can work with title, status, priority, and context.

The system needs stable IDs for:

• links,
• history,
• relationships,
• audit,
• moves,
• merges,
• validation.

Minimum requirement

Critical artefacts that have lifecycle or relationships must have stable identity.

11. Standardized structure

An AIFC knowledge base must not have a creative structure based on which person or AI agent happened to create it.

Inconsistent structure creates attention debt.

A person has to relearn every project, repository, and folder.

An AI agent also loses reliability when each workspace looks different.

AIFC therefore recommends standardized structure:

• consistent domain names,
• consistent artefact types,
• consistent metadata keys,
• consistent lifecycle states,
• consistent Decision Records,
• consistent change proposal schema,
• consistent skill schema,
• consistent AI governance schema.

Minimum requirement

An AIFC community must have documented structure and naming rules.

An AI agent must not freely create new folders, names, and templates outside community rules.

12. Minimal metadata fields

Critical artefacts should have at least:

id:
title:
aifc_type:
status:
owner:
sensitivity:
ai_access:
created_at:
updated_at:
review_cycle:
related_values:
related_decisions:

Not every artefact needs all metadata.

But the more critical an artefact is, the more structure it needs.

Recommended minimum by criticality

Low criticality:
title, type, status

Medium criticality:
title, type, status, owner, updated_at

High criticality:
id, title, type, status, owner, sensitivity, ai_access, review_cycle, related_decisions

Operational DNA:
id, title, type, status, owner, sensitivity, ai_access, review_cycle, access_roles, exit_strategy, fallback, audit

13. Common metadata keys

Recommended general metadata keys:

id:
title:
aifc_type:
status:
owner:
sensitivity:
ai_access:
human_access_roles:
created_at:
updated_at:
last_reviewed:
review_cycle:
source:
confidence:
related_values:
related_purpose:
related_strategy:
related_decisions:
related_workflows:
related_skills:
related_risks:
affected_communities:

aifc_type

Defines the artefact type.

Examples:

purpose
value
strategy
decision_record
workflow
human_skill
ai_skill
observed_signal
change_proposal
risk
ai_workflow
security_rule
community_interface
operational_dna

status

Defines lifecycle.

Examples:

draft
proposed
under_review
approved
active
deprecated
archived
rejected

sensitivity

Defines sensitivity.

Examples:

public
internal
restricted
operational_dna

ai_access

Defines AI access.

Examples:

allowed
limited
forbidden
requires_approval

14. Lifecycle states

AIFC recommends consistent lifecycle states:

draft
proposed
under_review
approved
active
deprecated
archived
rejected

For Operational DNA, these may be added:

restricted
compromised

Why it matters

Without lifecycle, the community does not know what to trust.

An AI agent must not use deprecated or rejected artefacts as current rules.

The Human Cockpit Layer must be able to show what is draft, what is waiting for review, and what is approved.

Minimum requirement

Critical artefacts must have lifecycle status.

15. Sensitivity and AI access

Sensitivity and AI access are not the same.

Sensitivity

Sensitivity says how sensitive the content is.

Example:

sensitivity: restricted

AI access

AI access says whether and how AI may work with the content.

Example:

ai_access: limited

Restricted content may be forbidden for some AI tools and allowed for others inside an AI-NDA Boundary.

Public content may be allowed for AI, but may still require review if AI generates public output.

Minimum requirement

Critical artefacts must separately define sensitivity and AI access rules.

16. Metadata for AI workflows

AI workflows must have metadata that enables governance.

Example:

id: aiw_7c91ab
title: Draft Jira ticket from change proposal
aifc_type: ai_workflow
status: active
owner: ai-governance-owner
sensitivity: internal
ai_access: allowed
model_dependency: replaceable
human_approval_required: true
fallback_required: true
fallback_defined: true
exit_strategy_required: true
related_values:
  - resilience
  - accountability

Minimum requirement

Critical AI workflows must have metadata for:

• owner,
• scope,
• data sensitivity,
• AI access,
• approval,
• fallback,
• exit strategy,
• audit,
• related values.

17. Metadata for change proposals

Change proposal metadata must enable a governed feedback loop.

Example:

id: cp_8f3a91
title: Add non-AI fallback for routine implementation tasks
aifc_type: change_proposal
status: submitted
proposer_type: human
source_signal: ai_dependency_observed
proposal_type: ai_dependency
decision_level: ai_governance_owner
affected_values:
  - resilience
  - human_capability
affected_communities:
  - development_team

Minimum requirement

A change proposal must have metadata for:

• status,
• proposer,
• proposal type,
• decision level,
• affected values,
• affected communities,
• source signal.

18. Metadata for skills

Human skills and AI skills must be distinguishable.

Human skill

id: hskill_2d41aa
title: Write clear dashboard requirements
aifc_type: human_skill
status: active
owner: ux-lead
sensitivity: internal
review_cycle: yearly
related_values:
  - clarity
  - attention_protection

AI skill

id: askill_94c7f1
title: Generate dashboard UX review
aifc_type: ai_skill
status: active
owner: ux-lead
sensitivity: internal
ai_access: allowed
human_approval_required: true
related_human_skill: hskill_2d41aa

Minimum requirement

Critical AI skills must be linked to human-readable knowledge or a Human Skill.

An AI skill must not be the only carrier of know-how.

19. Metadata for decisions

Decision Records must be traceable and connected.

Example:

id: dr_3b72e4
title: Use Human Cockpit Layer as AIFC concept
aifc_type: decision_record
status: approved
owner: standard-owner
decision_date: 2026-06-15
related_values:
  - human_control
  - attention_protection
related_documents:
  - AIFC-001
  - AIFC-002

A Decision Record should connect:

• context,
• decision,
• reason,
• alternatives,
• impacts,
• review date,
• affected artefacts.

Minimum requirement

Significant decisions must have stable IDs and links to affected artefacts.

20. Metadata for review

Review metadata helps prevent knowledge degradation.

Example:

last_reviewed: 2026-06-15
review_cycle: quarterly
next_review_due: 2026-09-15
review_owner: knowledge-owner

An unmaintained knowledge base degrades over time.

What is not reviewed gradually changes from active knowledge into risk.

Minimum requirement

Critical artefacts must have a review mechanism.

21. Markdown block structure

AIFC may use a block-based approach.

A block is an independent part of the knowledge base with its own meaning, metadata, or lifecycle.

Examples:

• rule,
• decision,
• change proposal,
• risk,
• assumption,
• task,
• skill step,
• anti-pattern,
• observed signal.

The block-based approach helps the Human Cockpit Layer display content in smaller units.

A person does not have to read a long document at once. An AI agent can work with a specific block. A validator can verify a specific rule.

Minimum requirement

If an implementation uses block-level metadata, it must define stable block identity and rules for moving blocks between files.

22. Folder and file naming

AIFC recommends folder and file names that are:

• stable,
• predictable,
• non-creative,
• documented,
• validatable,
• usable by people and AI.

Names should not be generated freely according to the style of a particular agent.

Poor pattern:

/Important Stuff
/AI Ideas
/New Docs
/Final FINAL
/Maybe useful

Better pattern:

/purpose
/values
/strategy
/decisions
/workflows
/skills/human
/skills/ai
/feedback/change-proposals
/security
/ai-governance

Minimum requirement

An AIFC workspace must have consistent folder and file naming rules.

23. Root README

An AIFC workspace should have one standardized root README.

The root README should say:

• that this is an AIFC workspace,
• what its structure is,
• how to navigate it,
• where must rules are,
• where the Source of Truth is,
• how new artefacts are created,
• what AI agents may and must not do,
• how the Human Cockpit Layer is used,
• how validation is performed.

The root README should not be a creative introduction.

It should be a stable navigation and governance document.

Minimum requirement

An AIFC workspace must have a human-readable entry point.

24. AI agent rules for structure

AI agents must not freely change the knowledge base structure.

An agent must:

• respect the existing folder structure,
• use approved templates,
• follow the metadata schema,
• not create new artefact types without approval,
• not rename folders without a change proposal,
• mark uncertainty,
• propose structural changes as change proposals.

Minimum requirement

Every AI agent with write access to the knowledge base must have rules for working with structure.

25. Human editing

AIFC must respect that people can edit text directly.

Direct editing is a strength of a text-based Source of Truth.

It also creates risks:

• missing metadata,
• broken structure,
• moved blocks without updated links,
• status change without a Decision Record,
• restricted content inserted into a public section,
• accidental conflict.

Direct editing should therefore be supported by validators and a cleanup agent.

Minimum requirement

An AIFC workspace must have a mechanism that helps people find and fix structural errors after manual editing.

26. Validation

Validation verifies whether the knowledge base follows rules.

It may check, for example:

• missing owner,
• missing status,
• missing sensitivity,
• restricted content with allowed AI access,
• AI workflow without fallback,
• critical workflow without owner,
• deprecated artefact used as active,
• change proposal without decision level,
• Decision Record without links,
• skill without review,
• Operational DNA without protection.

Validation should not be a punitive mechanism.

It should protect the community from knowledge base degradation.

Minimum requirement

Critical AIFC workspaces must have validation rules for minimal metadata and security conflicts.

27. Cleanup agent

A cleanup agent is an AI or software agent that helps maintain the knowledge base.

It may:

• find metadata conflicts,
• propose block moves,
• mark deprecated content,
• find duplication,
• find artefacts without owner,
• detect missing review,
• flag AI access conflicts,
• create maintenance tasks,
• propose change proposals.

A cleanup agent must not freely change critical content without permission.

Minimum requirement

A cleanup agent must have scope, permissions, audit, and approval rules.

28. Human Cockpit Layer and metadata

The Human Cockpit Layer uses metadata to protect human attention.

Metadata makes it possible to show, for example:

• what is important,
• what is waiting for review,
• what is deprecated,
• what is restricted,
• what requires approval,
• what AI proposed,
• what is Operational DNA,
• what has no owner,
• what has an upcoming review,
• what conflicts with structure.

Without metadata, the Human Cockpit Layer could only display documents.

With metadata, it can display system state.

Minimum requirement

Metadata must be designed to support not only AI and validation, but also human orientation.

29. Portability

AIFC metadata and Markdown structure must be portable.

Portability means the community can:

• export the knowledge base,
• move it to another tool,
• replace an AI vendor,
• run another Human Cockpit Layer,
• audit content outside the original system,
• restore operation from backup.

Minimum requirement

Critical artefacts, metadata, and skills must not be locked only in a proprietary tool without export.

30. Minimal example of an AIFC Markdown artefact

Example of a simple artefact:

---
id: wf_4a92c1
title: Change Proposal Review Workflow
aifc_type: workflow
status: active
owner: governance-owner
sensitivity: internal
ai_access: allowed
review_cycle: quarterly
related_values:
  - accountability
  - human_control
related_decisions:
  - dr_3b72e4
---

# Change Proposal Review Workflow

## Purpose

This workflow defines how submitted change proposals are reviewed, decided, and written back to the Source of Truth.

## Inputs

- submitted change proposal
- observed signal
- affected values
- proposed decision level

## Outputs

- accepted, rejected, or deferred proposal
- Decision Record
- Source of Truth update

## Rules

AI may summarize and analyze the proposal.

AI must not approve significant changes.

Human or community governance owns the decision.

## Fallback

If AI tools are unavailable, the workflow can be executed manually using the same checklist.

31. Anti-patterns

AIFC rejects the following anti-patterns.

31.1 Markdown without metadata

Content is readable, but not manageable.

31.2 Metadata without readability

Content is structured, but people do not understand it.

31.3 Creative folder structure

Each project has different names, layout, and rules.

31.4 AI-created structure without approval

An AI agent creates new folders, templates, or artefact types without governance.

31.5 Sequential IDs as primary identity

Artefact identity is based on order, which breaks when changes happen.

31.6 Deprecated content used as truth

Outdated content is still used by people or AI agents.

31.7 No owner

The artefact exists, but nobody is responsible for it.

31.8 No sensitivity

It is unclear whether AI, a person, or an external tool may see the content.

31.9 Human Cockpit without Source of Truth

The human interface displays information that is not connected to the authoritative knowledge base.

31.10 Source of Truth without human access

The knowledge base is formally correct, but people cannot use it.

32. Minimal requirements

For Metadata and Markdown, an AIFC community must at least:

1. Keep knowledge artefacts human-readable.
2. Give critical artefacts metadata.
3. Give critical artefacts owners.
4. Give critical artefacts lifecycle status.
5. Give critical artefacts sensitivity classification.
6. Separate AI access from sensitivity.
7. Give AI workflows metadata for approval, fallback, and exit strategy.
8. Give change proposals metadata for lifecycle and decision level.
9. Give Decision Records stable identity.
10. Distinguish Human Skill and AI Skill.
11. Prevent deprecated artefacts from being used as the current Source of Truth.
12. Standardize folder and file structure.
13. Prevent AI agents from freely changing structure.
14. Explain workspace structure through a root README or another entry point.
15. Support manual editing with validation or cleanup.
16. Design metadata to support the Human Cockpit Layer.
17. Keep the knowledge base exportable and portable.
18. Give Operational DNA special metadata and protection.

33. Summary

An AIFC knowledge base must be readable, manageable, and verifiable.

Markdown helps preserve human readability.

Metadata helps manage lifecycle, ownership, sensitivity, AI access, and relationships.

Validation protects the knowledge base from degradation.

The Human Cockpit Layer uses metadata so people do not have to read the whole repository, but can see system state.

AI agents use metadata so they act according to rules, not impressions.

AIFC therefore says:

Readable text is not enough.
Structured data is not enough.
AIFC knowledge must be readable, actionable, and verifiable.

Metadata and Markdown turn community knowledge into a maintainable operating system.