mdkg 0.0.1 → 0.0.2

package/dist/init/core/rule-6-templates-and-schemas.md

@@ -0,0 +1,186 @@
+---
+id: rule-6
+type: rule
+title: mdkg templates and schemas (global templates, required frontmatter, body guidance)
+tags: [mdkg, schema, templates]
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: 2026-01-06
+updated: 2026-01-22
+---
+
+# Templates and schemas
+
+This rule defines:
+- global template sets
+- required frontmatter fields per node type
+- recommended body headings for agent-friendly editing
+- the token substitution contract used by `mdkg new`
+
+## Global templates (v1)
+
+Templates are global and live at:
+
+- `.mdkg/templates/<set>/<type>.md`
+
+Workspace overrides are disabled in v1.
+
+### Template sets
+
+Recommended sets:
+- `default` (balanced)
+- `minimal` (lean body headings)
+- `verbose` (more guidance, more sections)
+
+All sets should provide the same set of types.
+
+## Token substitution
+
+Templates are filled using simple token replacement.
+
+Required tokens supported by v1:
+- `{{id}}`
+- `{{type}}`
+- `{{title}}`
+- `{{created}}`
+- `{{updated}}`
+- `{{status}}` (work items only)
+- `{{priority}}` (work items only)
+
+Optional tokens (nice-to-have, may be empty):
+- `{{epic}}`
+- `{{parent}}`
+- `{{prev}}`
+- `{{next}}`
+- `{{relates}}` (list)
+- `{{blocked_by}}` (list)
+- `{{blocks}}` (list)
+- `{{tags}}` (list)
+- `{{owners}}` (list)
+- `{{links}}` (list)
+- `{{artifacts}}` (list)
+- `{{refs}}` (list)
+- `{{aliases}}` (list)
+- `{{cases}}` (list)
+
+## Frontmatter requirements by type
+
+All nodes:
+- `id`
+- `type`
+- `title`
+- `created` (YYYY-MM-DD)
+- `updated` (YYYY-MM-DD)
+
+Searchable metadata (optional)
+
+All nodes MAY include the following searchable frontmatter lists:
+- `tags: [a, b, c]`
+- `owners: [a, b, c]`
+- `links: [ref, ref]` (any searchable reference string; may include URLs)
+- `artifacts: [ref, ref]` (build outputs, releases, commits, PRs, tarballs, etc.)
+- `refs: [id, id]` (non-edge references to other nodes)
+- `aliases: [text, text]` (extra searchable terms)
+- `cases: [id, id]` (test case identifiers; for test nodes)
+
+List fields SHOULD be written as `[]` when empty.
+Optional scalar graph fields (like `epic`, `parent`, `prev`, `next`) should be omitted when empty.
+
+Work items (`epic/feat/task/bug/chk/test`):
+  - `status` (enum)
+  - optional `priority` (0..9)
+  - optional graph edges: `epic`, `parent`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
+
+Decision records (`dec-*`):
+- `status` (enum: `proposed`, `accepted`, `rejected`, `superseded`)
+- optional `supersedes: dec-#`
+
+Design docs (`prd/edd/prop`):
+- no required status field
+- recommended `tags`
+
+Rules (`rule-*`):
+- no required status field
+
+## Body headings (guidance only)
+
+Body headings are strongly recommended for agent usability but should not be hard requirements.
+
+### Task / bug template headings (recommended)
+
+- Overview
+- Acceptance Criteria
+- Files Affected
+- Implementation Notes
+- Test Plan
+- Links / Artifacts
+
+### Test template headings (recommended)
+
+- Overview
+- Target / Scope
+- Preconditions / Environment
+- Test Cases
+- Results / Evidence
+- Notes / Follow-ups
+
+### Epic template headings (recommended)
+
+- Goal
+- Scope
+- Milestones
+- Out of Scope
+- Risks
+- Links / Artifacts
+
+### Checkpoint template headings (recommended)
+
+- Summary
+- Scope Covered
+- Decisions Captured
+- Implementation Summary
+- Verification / Testing
+- Known Issues / Follow-ups
+- Links / Artifacts
+
+### PRD headings (recommended)
+
+- Problem
+- Goals
+- Non-goals
+- Requirements
+- Acceptance Criteria
+- Metrics / Success
+- Risks
+- Open Questions
+
+### EDD headings (recommended)
+
+- Overview
+- Architecture
+- Data model
+- APIs / interfaces
+- Failure modes
+- Observability
+- Security / privacy
+- Testing strategy
+- Rollout plan
+
+### Decision record headings (recommended)
+
+- Context
+- Decision
+- Alternatives considered
+- Consequences
+- Links / references
+
+## Validation behavior
+
+- Frontmatter: strict, hard fail if invalid.
+- Body headings: warn only (do not break indexing).
+- If a template is missing:
+  - `mdkg new` must fail with a helpful error (exit code 3).

package/dist/init/templates/default/bug.md

@@ -0,0 +1,54 @@
+---
+id: {{id}}
+type: bug
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Overview
+
+What is broken? What’s the impact?
+
+# Reproduction Steps
+
+1. step 1
+2. step 2
+
+# Expected vs Actual
+
+- expected:
+- actual:
+
+# Suspected Cause
+
+Hypotheses or known causes.
+
+# Fix Plan
+
+What needs to change?
+
+# Test Plan
+
+How will we verify the fix?
+
+# Links / Artifacts
+
+- logs
+- screenshots
+- related tasks

package/dist/init/templates/default/chk.md

@@ -0,0 +1,55 @@
+---
+id: {{id}}
+type: checkpoint
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+scope: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Summary
+
+What was completed in this phase? What is now true?
+
+# Scope Covered
+
+Keep `scope` frontmatter updated when possible.
+
+# Decisions Captured
+
+Link the most important decision records.
+
+# Implementation Summary
+
+What changed? What patterns or architecture emerged?
+
+# Verification / Testing
+
+How do we know it works? What tests were run? What was reviewed?
+
+# Known Issues / Follow-ups
+
+- issue 1
+- issue 2
+
+# Links / Artifacts
+
+- packs
+- PRs/commits
+- docs
+- dashboards

package/dist/init/templates/default/dec.md

@@ -0,0 +1,38 @@
+---
+id: {{id}}
+type: dec
+title: {{title}}
+status: proposed
+supersedes: {{supersedes}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Context
+
+What is the situation? Why do we need a decision?
+
+# Decision
+
+What we decided and why.
+
+# Alternatives considered
+
+- alternative 1
+- alternative 2
+
+# Consequences
+
+What changes because of this decision?
+
+# Links / references
+
+- related docs
+- related tasks

package/dist/init/templates/default/edd.md

@@ -0,0 +1,50 @@
+---
+id: {{id}}
+type: edd
+title: {{title}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Overview
+
+What are we building and why?
+
+# Architecture
+
+Describe the high-level structure and key components.
+
+# Data model
+
+Key entities and their relationships.
+
+# APIs / interfaces
+
+External and internal interfaces.
+
+# Failure modes
+
+What can go wrong and how we handle it.
+
+# Observability
+
+Metrics, logs, tracing, and health checks.
+
+# Security / privacy
+
+Data handling, access, and protections.
+
+# Testing strategy
+
+How we validate the design.
+
+# Rollout plan
+
+How we ship this safely.

package/dist/init/templates/default/epic.md

@@ -0,0 +1,46 @@
+---
+id: {{id}}
+type: epic
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Goal
+
+What outcome does this epic deliver?
+
+# Scope
+
+What is included?
+
+# Milestones
+
+- milestone 1
+- milestone 2
+
+# Out of Scope
+
+What is explicitly excluded?
+
+# Risks
+
+- risk 1
+- risk 2
+
+# Links / Artifacts
+
+- related docs
+- related tasks
+- external links

package/dist/init/templates/default/feat.md

@@ -0,0 +1,35 @@
+---
+id: {{id}}
+type: feat
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Overview
+
+What is this feature?
+
+# Acceptance Criteria
+
+- criterion 1
+- criterion 2
+
+# Notes
+
+Implementation notes, constraints, and links.

package/dist/init/templates/default/prd.md

@@ -0,0 +1,59 @@
+---
+id: {{id}}
+type: prd
+title: {{title}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Problem
+
+What problem are we solving and for whom?
+
+# Goals
+
+- goal 1
+- goal 2
+
+# Non-goals
+
+- non-goal 1
+- non-goal 2
+
+# Requirements
+
+## Functional
+
+- requirement 1
+- requirement 2
+
+## Non-functional
+
+- requirement 1
+- requirement 2
+
+# Acceptance Criteria
+
+- criterion 1
+- criterion 2
+
+# Metrics / Success
+
+How do we know this worked?
+
+# Risks
+
+- risk 1
+- risk 2
+
+# Open Questions
+
+- question 1
+- question 2

package/dist/init/templates/default/prop.md

@@ -0,0 +1,45 @@
+---
+id: {{id}}
+type: prop
+title: {{title}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Summary
+
+One paragraph summary of the idea.
+
+# Motivation
+
+Why does this matter?
+
+# Proposal
+
+What is being proposed?
+
+# Impact
+
+What changes if we do this?
+
+# Risks
+
+- risk 1
+- risk 2
+
+# Alternatives
+
+- alternative 1
+- alternative 2
+
+# Next Steps
+
+- next step 1
+- next step 2

package/dist/init/templates/default/rule.md

@@ -0,0 +1,33 @@
+---
+id: {{id}}
+type: rule
+title: {{title}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Purpose
+
+Describe the rule’s purpose and what behavior it enforces.
+
+# Scope
+
+What parts of the repo/process this rule applies to.
+
+# Requirements
+
+List the concrete requirements as bullets.
+
+- requirement 1
+- requirement 2
+
+# Notes
+
+Any additional guidance, examples, or rationale.

package/dist/init/templates/default/task.md

@@ -0,0 +1,53 @@
+---
+id: {{id}}
+type: task
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Overview
+
+Describe what this task is and why it matters.
+
+# Acceptance Criteria
+
+- criterion 1
+- criterion 2
+
+# Files Affected
+
+List files/directories expected to change.
+
+- path 1
+- path 2
+
+# Implementation Notes
+
+- note 1
+- note 2
+
+# Test Plan
+
+How will we verify it works?
+
+# Links / Artifacts
+
+- related docs
+- related issues
+- references

package/dist/init/templates/default/test.md

@@ -0,0 +1,49 @@
+---
+id: {{id}}
+type: test
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+aliases: []
+cases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Overview
+
+Describe what this test validates and why it matters.
+
+# Target / Scope
+
+List the work items or areas covered (use `relates` for tickets).
+
+# Preconditions / Environment
+
+Document environment, data, and setup requirements.
+
+# Test Cases
+
+- case 1
+- case 2
+
+# Results / Evidence
+
+Record outcomes and link evidence in `artifacts` or `links`.
+
+# Notes / Follow-ups
+
+- follow-up 1
+- follow-up 2