Obsidian Markdown Standard

Purpose

Define a shared specification for all markdown documents generated by SynapSync skills, ensuring every .md output is Obsidian-native — with rich YAML frontmatter, wiki-links, bidirectional references, living document patterns, trackable IDs, and metric tables. When multiple skills produce documents for the same project, the result is an interconnected knowledge graph in Obsidian, not a collection of isolated files.

This skill is a specification — it is not invoked directly by users. Other skills reference it and embed the relevant compact profile into their output instructions.

When to Use This Skill

• Skill authors: When creating or updating a SynapSync skill that writes .md files to {output_base}

• Reference: When validating that generated documents follow the Obsidian-native standard

• Not for direct invocation: Users do not call this skill — it is consumed by other skills

Specification

1. Universal Frontmatter Schema

Every generated .md document MUST include YAML frontmatter with these fields:

Required Fields

title: "Document Title" date: "YYYY-MM-DD" # Creation date updated: "YYYY-MM-DD" # Last modification date project: "{project-name}" # Kebab-case project identifier type: "{document-type}" # From the Document Type Taxonomy (section 2) status: "draft" # draft | active | completed | superseded | archived version: "1.0" # Document version (semver-ish) tags:

• "{project-name}"
• "{type}"
• "{additional-tags}" changelog:
• version: "1.0" date: "YYYY-MM-DD" changes: ["Initial creation"] related:
• "[[related-document-1]]"
• "[[related-document-2]]"

Extended Fields (by document type)

Field Used By Description

sprint

sprint-plan, progress Sprint number (integer)

phase

sprint-plan, execution-plan Phase identifier (e.g., "1.1")

progress

sprint-plan, progress Completion percentage (0-100)

previous_doc

sprint-plan, retrospective "[[SPRINT-1-name]]"

next_doc

sprint-plan "[[SPRINT-3-name]]"

parent_doc

any child document "[[PROGRESS]]" or "[[README]]"

vision_ref

sprint-plan, progress "[[growth-vision]]"

retro_refs

sprint-plan, progress ["[[RETRO-1-name]]"]

metrics

sprint-plan, retrospective, progress Inline metric summary object

approved_by

any gated document Approver name

approved_date

any gated document "YYYY-MM-DD"

severity

bug-fix analysis critical / high / medium / low

scope_modules

refactor analysis List of affected modules

2. Document Type Taxonomy

Type Description Typical Skills

analysis

General analysis document universal-planner, project-planner

conventions

Project patterns and conventions universal-planner, project-planner

requirements

Functional/non-functional requirements universal-planner (NEW_PROJECT), sdlc-planner

architecture

Architecture decisions and design universal-planner, sdlc-planner

plan

Strategic planning document universal-planner, project-planner

execution-plan

Concrete task breakdown universal-planner, project-planner

sprint-plan

Sprint-level task plan universal-planner, project-planner

progress

Master progress dashboard universal-planner, universal-planner-executor

technical-report

Code/module analysis report code-analyzer

refactor-plan

Refactoring recommendations code-analyzer (v3)

retrospective

Sprint/project retrospective universal-planner, universal-planner-executor

decision-log

Architecture/engineering decisions universal-planner-executor

data-model

Entity relationships and storage sdlc-planner

flow-diagram

Core flows and sequences sdlc-planner

3. Wiki-Link Convention

Inter-document references MUST use wiki-links. Markdown links are reserved for external URLs only.

Pattern Usage Example

[[filename]]

Reference another document [[CONVENTIONS]]

[[filename#Section]]

Reference a specific section [[ANALYSIS#Success Criteria]]

[[filename]] (v1.2)

Reference a specific version [[SPRINT-1-foundation]] (v1.0)

[[filename|display text]]

Aliased reference [[functional-requirements|FR Spec]]

text

External URL only Obsidian docs

Rules:

• All inter-document references use [[wiki-links]] , never text

• Filenames in wiki-links omit the .md extension

• Wiki-links are case-insensitive in Obsidian but use the actual filename casing for clarity

4. References Section

Every generated document MUST end with a ## Referencias section. This section provides structured navigation between related documents.

Referencias

Parent: [[PROGRESS]] | [[README]] Siblings: [[SPRINT-1-foundation]], [[SPRINT-3-testing]] Children: [[RETRO-2-core-implementation]] Input Documents: [[CONVENTIONS]], [[ANALYSIS]] External: Relevant external link

Categories (include only those that apply):

• Parent: The document this one belongs to (e.g., PROGRESS for a sprint)

• Siblings: Documents at the same level (e.g., other sprints)

• Children: Documents spawned from this one (e.g., retro from sprint)

• Input Documents: Documents this one was derived from

• External References: External URLs relevant to this document

5. Living Document Pattern

Documents that evolve over time (sprint plans, progress dashboards, visions) follow the living document pattern:

Versioning: Track in frontmatter version field + changelog array.

Status transitions:

draft → active → completed → superseded → archived

Status Meaning

draft

Initial creation, not yet reviewed

active

Currently in use, may be updated

completed

Work described is finished

superseded

Replaced by a newer version (link to successor in related )

archived

Historical record, no longer active

Update protocol: When modifying a living document:

• Bump the version field

• Update the updated date

• Add an entry to changelog

• Update status if the transition applies

6. ID System

Trackable IDs provide stable anchors for cross-referencing within and across documents.

Prefix Domain Example

FR-

Functional Requirement FR-001, FR-002

NFR-

Non-Functional Requirement NFR-001

ADR- / DEC-

Architecture/Engineering Decision ADR-1, DEC-3

T-

Task T-1.1.1, T-2.3.1

K-

Retrospective: Keep K1, K2, K3

P-

Retrospective: Problem P1, P2

L-

Retrospective: Learning L1, L2

A-

Retrospective: Action A1, A2

D-

Technical Debt item D-001, D-002

M-

Metric M-001, M-002

Rules:

• IDs are scoped to the document they appear in (not globally unique)

• Reference from another document: [[document-name#FR-001]]

• Sequential numbering within each document

• Once assigned, an ID is never reused in that document (even if the item is removed)

7. Bidirectional References

If document A references document B, then document B MUST reference document A.

Implementation:

• related array in frontmatter of both documents

• Referencias

section at the end of both documents

• When generating multiple documents, ensure bidirectionality before finishing

Verification: After generating a batch of documents, check that for every [[X]] in document Y, document X contains [[Y]] in its related field or ## Referencias section.

8. Metric Tables

When reporting quantitative data, use the standard metric table format:

Status values: NOT_STARTED | IN_PROGRESS | IMPROVED | DEGRADED | COMPLETED | AT_RISK

Use this format in: sprint plans (planned vs actual), retrospectives (before/after), progress dashboards (target vs current), technical reports (metrics section).

9. Graduation Gates

Sprint plans and phase-gated documents use checkbox-based graduation criteria:

Graduation Gate

Sprint {N} is approved for completion when ALL criteria are met:

• All tasks marked complete with passing verification
• No open P0/P1 blockers
• Test coverage >= 85% for new code
• Build passes in CI
• Code reviewed and approved
• PROGRESS.md updated with final metrics

Rules:

• Gates use - [ ] / - [x] checkbox syntax

• Criteria must be verifiable (not subjective)

• A document with unmet gates cannot transition to completed status

• Gates are checked by the executor skill (universal-planner-executor) or manually

10. Sequential Numbering

Documents within the same directory that have a reading order MUST use numeric prefixes:

requirement-analysis/ ├── 01-problem-definition.md ├── 02-goals-and-success-metrics.md ├── 03-stakeholders-and-personas.md ├── 04-functional-requirements.md ├── 05-non-functional-requirements.md ├── 06-assumptions-and-constraints.md └── 07-out-of-scope.md

Rules:

• Use two-digit zero-padded prefixes: 01- , 02- , ..., 99-

• Sequential numbering indicates reading order, not priority

• Sprints use their sprint number: SPRINT-1-name.md , SPRINT-2-name.md

• Retrospectives pair with sprints: RETRO-1-name.md

11. Carried Forward Rules

When a document is part of a sequence (e.g., Sprint 2 follows Sprint 1), include a section for items carried from the previous document:

Carried Forward from [[SPRINT-1-foundation]]

The following items were not completed in Sprint 1 and are carried into this sprint:

• T-1.2.3 — Implement caching layer (blocked by ADR-3 in Sprint 1)
• T-1.3.1 — Add integration tests for auth module

Decisions inherited:

• DEC-2: Use Redis for session storage ([[SPRINT-1-foundation#DEC-2]])

Rules:

• Only Sprint 2+ and sequential documents include this section

• Reference the source document with wiki-links

• Include specific task IDs and decision IDs

• Place this section after the sprint header but before the first phase

12. Retrospective Template

When a skill generates a retrospective document (optional feature in universal-planner and universal-planner-executor):

title: "Retrospective: Sprint {N} — {Sprint Name}" date: "YYYY-MM-DD" updated: "YYYY-MM-DD" project: "{project-name}" type: "retrospective" status: "active" version: "1.0" sprint: {N} previous_doc: "[[SPRINT-{N}-name]]" tags:

• "{project-name}"
• "retrospective"
• "sprint-{N}" changelog:
• version: "1.0" date: "YYYY-MM-DD" changes: ["Initial retrospective"] related:
• "[[SPRINT-{N}-name]]"
• "[[SPRINT-{N+1}-name]]"
• "[[PROGRESS]]"

Retrospective: Sprint {N} — {Sprint Name}

Context

{Brief description of what the sprint aimed to accomplish and its outcome}

Keep (What Went Well)

• K1: {What to continue doing}
• K2: {What to continue doing}

Problems (What Went Wrong)

• P1: {Issue encountered}
• P2: {Issue encountered}

Learnings (What We Learned)

• L1: {Insight gained}
• L2: {Insight gained}

Actions (What to Do Differently)

• A1: {Concrete action for next sprint} → Assigned to: {who}
• A2: {Concrete action for next sprint} → Assigned to: {who}

Metrics

Signals to Watch

• {Early warning indicator for next sprint}
• {Trend to monitor}

Verdict

{One paragraph: was the sprint successful? Key takeaway for the team.}

Referencias

Parent: [[PROGRESS]] Input Documents: [[SPRINT-{N}-name]] Siblings: [[RETRO-{N-1}-name]], [[RETRO-{N+1}-name]]

Domain Profiles

Each SynapSync skill that produces .md output embeds a compact profile from this standard into its ## Obsidian Output Standard section. Profiles are domain-specific subsets of the full specification, providing just the rules and templates relevant to that skill's output.

Planning Profile

For: project-planner , universal-planner

Obsidian Output Rules (Planning)

All documents generated by this skill MUST follow the obsidian-md-standard:

1. Frontmatter: Every .md file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. Types: Use conventions, analysis, plan, execution-plan, sprint-plan, progress, requirements, architecture as appropriate
3. Wiki-links: All inter-document references use [[filename]] syntax — never [text](relative-path.md)
4. Referencias: Every document ends with ## Referencias listing Parent, Siblings, Children, and Input Documents
5. Living documents: PROGRESS.md and sprint plans are living documents — bump version, update changelog, transition status on modification
6. IDs: Use FR-/NFR- for requirements, ADR- for architecture decisions, T- for tasks
7. Bidirectional: If document A references B, document B must reference A in related and ## Referencias
8. Metrics: Use | Metric | Before | After | Delta | Status | format for all quantitative data
9. Gates: Sprint plans include ## Graduation Gate with verifiable checkbox criteria
10. Carried Forward: Sprint 2+ includes ## Carried Forward from [[previous-sprint]] for incomplete items
11. Sequential numbering: Use 01-, 02- prefixes where reading order matters

Frontmatter template for sprint plans:

---
title: "Sprint {N}: {Name}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "sprint-plan"
status: "draft"
version: "1.0"
sprint: {N}
phase: "{active-phases}"
progress: 0
previous_doc: "[[SPRINT-{N-1}-name]]"
next_doc: "[[SPRINT-{N+1}-name]]"
parent_doc: "[[PROGRESS]]"
tags: ["{project-name}", "sprint-{N}", "sprint-plan"]
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial sprint plan"]
related:
  - "[[PROGRESS]]"
  - "[[EXECUTION]]"
  - "[[SPRINT-{N-1}-name]]"
  - "[[SPRINT-{N+1}-name]]"
---

### Technical Report Profile

**For:** `code-analyzer`

```markdown
### Obsidian Output Rules (Technical Reports)

All documents generated by this skill MUST follow the obsidian-md-standard:

1. **Frontmatter**: Every `.md` file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. **Types**: Use `technical-report` for REPORT.md, `refactor-plan` for REFACTOR.md
3. **Wiki-links**: When both REPORT.md and REFACTOR.md exist, cross-reference with `[[REPORT]]` / `[[REFACTOR]]`
4. **Referencias**: Every document ends with `## Referencias` listing related analysis documents
5. **Metrics**: Use `| Metric | Before | After | Delta | Status |` format for code quality metrics, complexity scores, and coverage data
6. **IDs**: Use D- for debt items in refactor plans
7. **Bidirectional**: If REFACTOR.md references REPORT.md, REPORT.md must reference REFACTOR.md

**Frontmatter template for REPORT.md:**
```yaml
---
title: "Module Analysis: {module-name}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "technical-report"
status: "active"
version: "1.0"
tags: ["{project-name}", "technical-report", "module-analysis", "{module-name}"]
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial analysis"]
related:
  - "[[REFACTOR]]"
---

### SDLC Profile

**For:** `sdlc-planner`

```markdown
### Obsidian Output Rules (SDLC)

All documents generated by this skill MUST follow the obsidian-md-standard:

1. **Frontmatter**: Every `.md` file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. **Types**: Use `requirements` for Phase 1 files, `architecture` for Phase 2 files, `plan` for future-phases
3. **Wiki-links**: All inter-document references use `[[filename]]` — README links to all children via wiki-links
4. **Referencias**: Every document ends with `## Referencias` with bidirectional links to sibling and parent documents
5. **Sequential numbering**: Maintain `01-`, `02-` prefixes for reading order
6. **IDs**: Use FR-/NFR- for requirements, ADR- for architecture decisions
7. **Bidirectional**: All 17 documents must have reciprocal references — README↔children, siblings↔siblings
8. **Parent document**: README.md serves as the parent; all other documents include `parent_doc: "[[README]]"` in frontmatter

**Frontmatter template for requirement files:**
```yaml
---
title: "{Document Title}"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
project: "{project-name}"
type: "requirements"
status: "active"
version: "1.0"
parent_doc: "[[README]]"
tags: ["{project-name}", "requirements", "sdlc", "{specific-tag}"]
changelog:
  - version: "1.0"
    date: "YYYY-MM-DD"
    changes: ["Initial generation"]
related:
  - "[[README]]"
  - "[[{sibling-documents}]]"
---

### Sprint Execution Profile

**For:** `universal-planner-executor`

```markdown
### Obsidian Output Rules (Sprint Execution)

When modifying sprint documents and PROGRESS.md, follow the obsidian-md-standard:

1. **Frontmatter maintenance**: When updating a sprint file, bump `version`, update `updated` date, add `changelog` entry, update `status` and `progress`
2. **Status transitions**: Move status through `draft → active → completed` as work progresses
3. **Decision Log**: Decisions logged with DEC- IDs include wiki-links to the sprint and task that triggered the decision
4. **Metrics**: Use `| Metric | Before | After | Delta | Status |` format when recording actual vs planned metrics
5. **Gates**: Verify all `## Graduation Gate` criteria before marking a sprint `completed`
6. **Bidirectional**: When adding decision references or notes that mention other documents, ensure reciprocal links
7. **Wiki-links**: All document references in notes, decision logs, and completion summaries use `[[filename]]` syntax

**When completing a sprint, update frontmatter:**
```yaml
status: "completed"
progress: 100
version: "{bumped}"
updated: "YYYY-MM-DD"
changelog:
  - version: "{new}"
    date: "YYYY-MM-DD"
    changes: ["Sprint completed — all tasks done, gates passed"]

### Retrospective Profile

**For:** `universal-planner` (optional), `universal-planner-executor` (optional)

```markdown
### Obsidian Output Rules (Retrospective)

When generating a retrospective document:

1. **Frontmatter**: Include full universal schema plus `sprint`, `previous_doc` (the completed sprint)
2. **Type**: `retrospective`
3. **IDs**: Use K1-Kn (Keep), P1-Pn (Problems), L1-Ln (Learnings), A1-An (Actions)
4. **Metrics**: Use `| Metric | Planned | Actual | Delta | Status |` comparing sprint targets to outcomes
5. **Wiki-links**: Reference the completed sprint, next sprint, and PROGRESS with wiki-links
6. **Bidirectional**: The completed sprint's `related` and the PROGRESS `retro_refs` must link back to this retrospective
7. **Referencias**: Include Parent (PROGRESS), Input (completed sprint), Siblings (other retros)

See the full retrospective template in the obsidian-md-standard specification (Section 12).

Sync Profile

For: obsidian-sync

### Obsidian Output Rules (Sync)

When syncing documents to Obsidian:

1. **Frontmatter enrichment**: If a document has minimal frontmatter (only title/date/project/type/tags), enrich it with the full universal schema (add updated, status, version, changelog, related)
2. **Frontmatter preservation**: If a document already has rich frontmatter, preserve all existing fields — only add missing ones
3. **Frontmatter generation**: If a document has no frontmatter, generate the complete universal schema
4. **Wiki-link preservation**: Never convert `[[wiki-links]]` to `[markdown](links)` — preserve them exactly
5. **Type inference**: Map document content to the 14-type taxonomy defined in the standard
6. **Cross-reference validation**: After syncing a batch of files, verify that `related` fields and `## Referencias` sections are bidirectional — if A references B, B should reference A
7. **Status**: New documents get `status: "active"`, documents with existing status are preserved

Compliance Checklist

When validating that a skill's output follows this standard:

-  Every .md
 file has YAML frontmatter with all required fields

-  type
 field uses a value from the Document Type Taxonomy

-  All inter-document references use [[wiki-links]]
 (no relative markdown links)

-  Every document ends with ## Referencias

-  Living documents have version
 and changelog
 maintained

-  IDs follow the prefix convention (FR-, ADR-, T-, K-, P-, L-, A-, D-, M-)

-  Bidirectional references are reciprocal

-  Metric tables use the standard format

-  Graduation gates use verifiable checkbox criteria

-  Sequential documents use 01-
, 02-
 prefixes

-  Sprint 2+ documents include ## Carried Forward

-  No [text](relative-path.md)
 patterns for inter-document links

Version History

Version
Date
Changes

1.0
2026-02-11
Initial release with full Obsidian-native markdown specification