From f106af9ab45ac0cb0d3f57a9566283aff06b13f0 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Sun, 3 May 2026 00:25:54 +0200 Subject: [PATCH] docs(front-matter): add YAML front-matter to docs/ root --- docs/API.md | 8 + docs/INDEX.md | 1 + docs/MD3_Color_Scheme_Documentation.md | 8 + docs/agent-instruction-audit.md | 8 + docs/obsidian-authoring.md | 202 +++++++++++++++++++++++++ docs/scrum4me-architecture.md | 8 + docs/scrum4me-backlog.md | 8 + docs/scrum4me-functional-spec.md | 8 + docs/scrum4me-pbi-dialog.md | 8 + docs/scrum4me-personas.md | 8 + docs/scrum4me-product-backlog.md | 8 + docs/scrum4me-story-dialog.md | 8 + docs/scrum4me-styling.md | 8 + docs/scrum4me-task-dialog.md | 8 + docs/scrum4me-test-plan.md | 8 + docs/solo-paneel-spec.md | 8 + 16 files changed, 315 insertions(+) create mode 100644 docs/obsidian-authoring.md diff --git a/docs/API.md b/docs/API.md index bfda532..1fe6d32 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,3 +1,11 @@ +--- +title: "Scrum4Me REST API" +status: active +audience: [ai-agent, contributor] +language: en +last_updated: 2026-05-03 +--- + # Scrum4Me REST API REST-API contract voor Claude Code en andere clients. diff --git a/docs/INDEX.md b/docs/INDEX.md index 031ff1b..6a47c8a 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -62,4 +62,5 @@ Auto-generated on 2026-05-02 from front-matter and headings. | [Agent Instruction Audit](./agent-instruction-audit.md) | `agent-instruction-audit.md` | — | — | | [Scrum4Me REST API](./API.md) | `API.md` | — | — | | [Material Design 3 Color Scheme Documentation](./MD3_Color_Scheme_Documentation.md) | `MD3_Color_Scheme_Documentation.md` | — | — | +| [Obsidian as Personal Authoring Layer](./obsidian-authoring.md) | `obsidian-authoring.md` | active | 2026-05-02 | | [Solo Paneel — Implementatie-specificatie (v2)](./solo-paneel-spec.md) | `solo-paneel-spec.md` | — | — | diff --git a/docs/MD3_Color_Scheme_Documentation.md b/docs/MD3_Color_Scheme_Documentation.md index 2fcd7af..90f75b3 100644 --- a/docs/MD3_Color_Scheme_Documentation.md +++ b/docs/MD3_Color_Scheme_Documentation.md @@ -1,3 +1,11 @@ +--- +title: "Material Design 3 Color Scheme Documentation" +status: active +audience: [maintainer, contributor] +language: en +last_updated: 2026-05-03 +--- + # Material Design 3 Color Scheme Documentation ## Project Management Application for Scrum Teams diff --git a/docs/agent-instruction-audit.md b/docs/agent-instruction-audit.md index 1cd185f..ab69675 100644 --- a/docs/agent-instruction-audit.md +++ b/docs/agent-instruction-audit.md @@ -1,3 +1,11 @@ +--- +title: "Agent Instruction Audit" +status: active +audience: [maintainer] +language: en +last_updated: 2026-05-03 +--- + # Agent Instruction Audit Datum: 2026-04-25 diff --git a/docs/obsidian-authoring.md b/docs/obsidian-authoring.md new file mode 100644 index 0000000..61aa6b7 --- /dev/null +++ b/docs/obsidian-authoring.md @@ -0,0 +1,202 @@ +--- +title: Obsidian as Personal Authoring Layer +status: active +audience: maintainer, contributor +language: en +last_updated: 2026-05-02 +related: + - docs/adr/README.md + - scripts/generate-docs-index.mjs + - .gitignore +--- + +# Obsidian as Personal Authoring Layer + +Scrum4Me's documentation lives as plain Markdown under `docs/`. The canonical +source of truth is the committed `.md` file — rendered on GitHub, read by +agents (Claude Code, Codex) directly from the file system, and indexed by +`scripts/generate-docs-index.mjs`. + +Note: the `scrum4me-mcp` server does **not** expose `docs/` content. Its +20 tools serve database state (products, sprints, stories, tasks, jobs, +questions) via Prisma. Documentation reaches the agent only through the +file-system tools, so the canonical Markdown is the one and only channel. + +Obsidian is **not** a second source of truth. It is a personal authoring +layer that you can opt into without changing what the repo or the agent +sees. This document records the conventions that keep both views consistent. + +## Why an authoring layer at all + +A canonical `0003-job-claim-strategy.md` is short, declarative, and final. +The thinking that produced it — alternatives weighed, links followed, half- +ideas — is messy and personal. Forcing that into the committed file inflates +ADRs and dilutes the signal future readers (human or agent) need. + +Obsidian gives you a place to keep the thinking next to the artefact without +polluting it: graph view, backlinks, properties, scratch notes. The +`.gitignore` rules below ensure none of that crosses the repo boundary. + +## Vault setup + +Open the repo root as the vault, not just `docs/`. + +Reasons: + +- ADRs and patterns frequently reference code (`prisma/schema.prisma`, + `lib/task-status.ts`). Markdown links from a `docs/`-only vault cannot + resolve those targets; from a root vault they can. +- The same vault then surfaces `README.md`, `CLAUDE.md`, and `AGENTS.md` + as nodes in the graph — useful when reasoning about agent instructions. +- Per-developer Obsidian config lives in `.obsidian/` at the vault root, + which is already gitignored. + +### Two repos, two vaults + +The MCP server lives in a separate repo (`scrum4me-mcp`) with its own +`CLAUDE.md`, tools, and tests. Open it as a **separate** Obsidian vault +when you work there. Each `.obsidian/` directory is per-folder and stays +gitignored on both sides; cross-repo notes belong in whichever vault you +opened first, not in some shared third location. + +Schema-related ADRs are an exception: the MCP server consumes the +Scrum4Me Prisma schema via the `vendor/scrum4me/` git submodule, so the +*decision* about the schema belongs in this repo's `docs/adr/`. The +mirror in `scrum4me-mcp` only needs an `npm run sync-schema` after the +ADR lands here, not its own ADR. + +## Link style + +In Settings → Files & Links: + +- **Use [[Wikilinks]]** → off +- **New link format** → Relative path to file +- **Default location for new notes** → "Same folder as current file" + +Wikilinks would render as plain text on GitHub and are not parsed by the +docs index generator. Stick to standard Markdown links (`./adr/0001-foo.md`) +so the same file works in Obsidian, GitHub, and any agent reader. + +Obsidian still resolves Markdown links for backlinks and graph view, so you +do not lose Obsidian's navigation features. + +## Front-matter is Obsidian Properties + +`scripts/generate-docs-index.mjs` reads a small set of YAML front-matter +keys: `title`, `status`, `date` (or `last_updated`). Obsidian renders the +exact same YAML block as its Properties panel. + +Practical consequence: flipping a plan from `proposal` to `accepted` in +the Obsidian Properties UI and then running `npm run docs:index` is a +complete workflow — no separate metadata store, no plugin needed. + +The repo's front-matter is intentionally flat (no nested objects, no lists +beyond simple arrays) to stay parseable by the dependency-free generator. +When adding fields, keep them flat. + +## Templates + +Two ADR templates ship in `docs/adr/templates/`: + +- `nygard.md` — default, for one-way-door decisions +- `madr.md` — for decisions where rejected alternatives must be recorded + +Both use `{{curly braces}}` placeholders so they read naturally in any +editor and so Codex and Claude Code can fill them mechanically. + +Two ways to use them from Obsidian: + +1. **Core Templates plugin** (recommended starting point). Settings → + Templates → Template folder location: `docs/adr/templates`. Then + `Cmd-P → Insert template → nygard` inserts the body verbatim. Fill + placeholders by hand. +2. **Templater** (community plugin). If filling the next ADR number and + today's date by hand becomes a bottleneck, write a Templater wrapper + in a vault-only `_templates/` folder that reads `nygard.md` and + substitutes `<% tp.date.now("YYYY-MM-DD") %>` plus a computed next + number. Keep this wrapper out of git — it is personal tooling, not + part of the canonical convention. + +Do not modify the canonical templates to use Templater syntax. The +placeholders must remain agent-readable. + +## Sidecar files for personal notes + +`.gitignore` already excludes `_*.md` and the docs index generator +mirrors that exclusion (`/\/_[^/]+\.md$/`). Use this for any file that +should stay personal: + +- `docs/adr/_draft-0003-job-claim-strategy.md` — alternatives, doubts, + links you considered before settling on the canonical ADR +- `docs/plans/_questions-for-jp.md` — open questions you want to think + about but not raise yet +- `_scratch.md` anywhere in the tree + +Workflow for an ADR: + +1. Brainstorm in `docs/adr/_draft-NNNN-…md` — free-form, link-heavy. +2. When the decision is clear, copy the relevant prose into the canonical + `docs/adr/NNNN-…md`, applying the Nygard or MADR template. +3. Run `npm run docs:index`. +4. Commit only the canonical ADR (the sidecar is invisible to git). + +The sidecar can stay as a personal trail or be deleted — both are local- +only choices. + +## Plugin recommendations + +Useful and low-risk: + +- **Outline** (core) — table of contents per file +- **Backlinks**, **Outgoing Links** (core) — see what links to and from + the current document +- **Linter** (community) — can enforce that ADRs have a `status` field + in front-matter + +Use with care: + +- **Dataview** — tempting to replace `INDEX.md` with a Dataview query. + Don't. The query renders blank on GitHub and is invisible to Claude + Code. Use Dataview only in a sidecar (`_dashboard.md`) for personal + views. + +Avoid as canonical source: + +- **Canvas**, **Excalidraw** — not diff-able, not agent-readable. Keep + diagrams as committed SVG (`docs/erd.svg`) or as Mermaid blocks inside + Markdown. + +## Index generator interaction + +`generate-docs-index.mjs` is the system of record for `docs/INDEX.md`. +Two reliability concerns when authoring through Obsidian: + +- **Forgetting to regenerate the index.** If you create or rename a doc + in Obsidian and commit without running the generator, INDEX.md goes + stale. Mitigations: a `pre-commit` hook that runs `npm run docs:index` + whenever staged changes touch `docs/**/*.md`, or a habit of running + `npm run docs:index` before every `git add docs/`. +- **Renaming and "update links" prompts.** Obsidian's "automatically + update internal links" applies to wikilinks. Since this vault uses + Markdown links, Obsidian will still try to update them — verify the + diff before committing, especially for cross-folder renames. + +## What Obsidian must not do + +- Introduce wikilinks into committed files +- Add Obsidian-only blocks (callouts, embeds with `![[...]]`) into + canonical docs +- Replace `INDEX.md` with a Dataview view in the committed tree +- Modify front-matter keys outside the documented set without also + updating `generate-docs-index.mjs` + +If a workflow benefits the personal vault but breaks one of those rules, +keep it in a `_*.md` sidecar. + +## Summary + +Treat Obsidian like a notebook bound to the same desk as the repo: +useful for thinking, never confused with what's published. The +gitignore rules and the index generator already enforce most of this +mechanically — these conventions cover the parts that still depend on +the author's judgement. diff --git a/docs/scrum4me-architecture.md b/docs/scrum4me-architecture.md index 12085c9..9d94693 100644 --- a/docs/scrum4me-architecture.md +++ b/docs/scrum4me-architecture.md @@ -1,3 +1,11 @@ +--- +title: "Scrum4Me — Technische Architectuur" +status: active +audience: [maintainer, contributor] +language: nl +last_updated: 2026-05-03 +--- + # Scrum4Me — Technische Architectuur **Versie:** 0.1 — april 2026 diff --git a/docs/scrum4me-backlog.md b/docs/scrum4me-backlog.md index 689063a..60a44a4 100644 --- a/docs/scrum4me-backlog.md +++ b/docs/scrum4me-backlog.md @@ -1,3 +1,11 @@ +--- +title: "Scrum4Me — Implementatie Backlog" +status: active +audience: [maintainer, contributor] +language: nl +last_updated: 2026-05-03 +--- + # Scrum4Me — Implementatie Backlog **Versie:** 0.1 — april 2026 diff --git a/docs/scrum4me-functional-spec.md b/docs/scrum4me-functional-spec.md index 69dc93a..406f19e 100644 --- a/docs/scrum4me-functional-spec.md +++ b/docs/scrum4me-functional-spec.md @@ -1,3 +1,11 @@ +--- +title: "Scrum4Me — Functionele Specificatie" +status: active +audience: [maintainer, contributor] +language: nl +last_updated: 2026-05-03 +--- + # Scrum4Me — Functionele Specificatie **Versie:** 0.2 — april 2026 diff --git a/docs/scrum4me-pbi-dialog.md b/docs/scrum4me-pbi-dialog.md index 79fb5ae..5e297ea 100644 --- a/docs/scrum4me-pbi-dialog.md +++ b/docs/scrum4me-pbi-dialog.md @@ -1,3 +1,11 @@ +--- +title: "PbiDialog Profiel" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-03 +--- + # PbiDialog Profiel > Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me). diff --git a/docs/scrum4me-personas.md b/docs/scrum4me-personas.md index 2f3c518..474a6bf 100644 --- a/docs/scrum4me-personas.md +++ b/docs/scrum4me-personas.md @@ -1,3 +1,11 @@ +--- +title: "DevPlanner — User Personas" +status: active +audience: [maintainer] +language: nl +last_updated: 2026-05-03 +--- + # DevPlanner — User Personas **Versie:** 0.1 — april 2026 diff --git a/docs/scrum4me-product-backlog.md b/docs/scrum4me-product-backlog.md index 59d62a5..ecb8f57 100644 --- a/docs/scrum4me-product-backlog.md +++ b/docs/scrum4me-product-backlog.md @@ -1,3 +1,11 @@ +--- +title: "DevPlanner — Product Backlog" +status: active +audience: [maintainer] +language: nl +last_updated: 2026-05-03 +--- + # DevPlanner — Product Backlog **Versie:** 0.1 — april 2026 diff --git a/docs/scrum4me-story-dialog.md b/docs/scrum4me-story-dialog.md index 250dec0..9926650 100644 --- a/docs/scrum4me-story-dialog.md +++ b/docs/scrum4me-story-dialog.md @@ -1,3 +1,11 @@ +--- +title: "StoryDialog Profiel" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-03 +--- + # StoryDialog Profiel > Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me). diff --git a/docs/scrum4me-styling.md b/docs/scrum4me-styling.md index e1b82e1..5bb00fe 100644 --- a/docs/scrum4me-styling.md +++ b/docs/scrum4me-styling.md @@ -1,3 +1,11 @@ +--- +title: "Scrum4Me — Styling & Design System" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-03 +--- + # Scrum4Me — Styling & Design System **Versie:** 0.1 — april 2026 diff --git a/docs/scrum4me-task-dialog.md b/docs/scrum4me-task-dialog.md index c2ecca1..c1431fd 100644 --- a/docs/scrum4me-task-dialog.md +++ b/docs/scrum4me-task-dialog.md @@ -1,3 +1,11 @@ +--- +title: "TaskDialog Profiel" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-03 +--- + # TaskDialog Profiel > Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me). diff --git a/docs/scrum4me-test-plan.md b/docs/scrum4me-test-plan.md index a200ed9..875f200 100644 --- a/docs/scrum4me-test-plan.md +++ b/docs/scrum4me-test-plan.md @@ -1,3 +1,11 @@ +--- +title: "Scrum4Me — API Test Plan" +status: active +audience: [maintainer, contributor] +language: nl +last_updated: 2026-05-03 +--- + # Scrum4Me — API Test Plan **Versie:** 1.0 diff --git a/docs/solo-paneel-spec.md b/docs/solo-paneel-spec.md index 949776c..c82fc85 100644 --- a/docs/solo-paneel-spec.md +++ b/docs/solo-paneel-spec.md @@ -1,3 +1,11 @@ +--- +title: "Solo Paneel — Implementatie-specificatie" +status: active +audience: [maintainer, contributor] +language: nl +last_updated: 2026-05-03 +--- + # Solo Paneel — Implementatie-specificatie (v2) > **Doel:** een persoonlijk Kanban-bord per product dat de taken toont van stories die geclaimd zijn door de ingelogde developer. Bord werkt met drie kolommen (TO_DO / IN_PROGRESS / DONE), drag-and-drop tussen kolommen, en koppelt aan een nieuw `Story.assignee_id` veld.