Diagrams:
- All diagrams MUST use Mermaid format
- Use fenced code blocks with
mermaid language identifier
- Supported diagram types: flowchart, sequence, class, state, ER, gantt, pie, mindmap
Example:
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action]
B -->|No| D[End]
If NO path provided, determine based on document type and project structure.
---
document: [Document Name]
created: [YYYY-MM-DD HH:MM]
classification: [external-research | internal-analysis | contextual | other]
---
**Purpose**: [What this document is for]
**Author**: [Who created it - can be "Claude" or user name]
**Context**: [Why this document was created - what prompted it]
---
---
## Change History
| Date | Change | Author |
|------|--------|--------|
| [YYYY-MM-DD] | Initial creation | [Author] |
Example after updates:
## Change History
| Date | Change | Author |
|------|--------|--------|
| 2024-03-15 | Added section on error handling | Claude |
| 2024-03-14 | Expanded API examples | User |
| 2024-03-14 | Initial creation | Claude |
Purpose: Document the current authentication flow and identify potential improvements
Author: Claude
Context: User requested security review of login system
[Document content goes here...]
Change History
| Date |
Change |
Author |
| 2024-03-14 |
Initial creation |
Claude |
</complete_example>
<success_criteria>
Document is correctly structured when:
- Header contains all required fields (document, created, classification)
- Purpose, Author, and Context are clearly stated
- Classification matches document content
- Footer has Change History table
- Change History is updated after every modification
- Path respects user-provided location or follows classification-based suggestion
- Markdown is lint-free (proper spacing, heading levels, code fences)
- Any diagrams use Mermaid format
</success_criteria>
<anti_patterns>
<avoid>
- Creating documents without headers
- Skipping change history updates
- Overriding user-specified paths
- Applying this to subagents, commands, or skills
- Using vague document names like "Notes" or "Document"
- Leaving Purpose/Author/Context empty
- Producing markdown with lint errors (missing blank lines, skipped heading levels)
- Using ASCII art, PlantUML, or other diagram formats instead of Mermaid
- Code fences without language specifiers
</avoid>
</anti_patterns>
1---2name: manage-markdown-docs-23description: Standardize markdown document creation and updates with proper headers and footers. Use when creating OR updating any markdown file that is NOT a subagent, command, or skill definition. Ensures consistent metadata, classification, and change tracking.4---56<objective>7Ensure all markdown documents have consistent structure with proper header metadata and footer change history. Standardizes documentation across projects regardless of type (workspace, monorepo, ontology, etc.).8</objective>910<scope>11<applies_to>12- Research notes and findings13- Analysis reports14- Context documents15- Design documents16- Meeting notes17- Technical documentation18- Any general-purpose markdown file19</applies_to>2021<does_not_apply_to>22- Subagent definitions (agents/*.md)23- Slash commands (commands/*.md)24- Skills (SKILL.md files)25- README.md files (these have their own conventions)26- CLAUDE.md files27- CHANGELOG.md files28</does_not_apply_to>29</scope>3031<quick_start>32<workflow_new_document>33When CREATING a new markdown file:341. Check if document type is excluded (subagent, command, skill) → MUST stop if excluded352. If path provided by user, use it; otherwise determine appropriate location363. Classify document type374. Generate header with required metadata385. Write document content396. Add footer with change history (initial creation entry)40</workflow_new_document>4142<workflow_update_document>43When UPDATING an existing markdown file:441. Check if document type is excluded (subagent, command, skill) → MUST stop if excluded452. If document lacks proper header/footer, add them463. Make the requested content changes474. Update the Change History table in footer with new entry48</workflow_update_document>4950<quality_requirements>51**Markdown Lint Compliance**:52- All produced markdown must be free from lint errors53- Use consistent heading levels (no skipping levels)54- Blank lines before and after headings, code blocks, and lists55- No trailing whitespace56- Single blank line at end of file57- Properly closed code fences with language specifier5859**Diagrams**:60- All diagrams MUST use Mermaid format61- Use fenced code blocks with `mermaid` language identifier62- Supported diagram types: flowchart, sequence, class, state, ER, gantt, pie, mindmap6364Example:65```mermaid66flowchart TD67 A[Start] --> B{Decision}68 B -->|Yes| C[Action]69 B -->|No| D[End]70```71</quality_requirements>7273<path_behavior>74If user provides a specific file path:75- MUST use that path exactly76- NEVER suggest alternatives77- NEVER question the location7879If NO path provided, determine based on document type and project structure.80</path_behavior>81</quick_start>8283<document_classification>84Classify every document into ONE of these categories:8586<category name="external-research">87**External Research Finding**88- Information gathered from outside sources89- Web research, API documentation, third-party analysis90- Competitor analysis, market research91- Directory suggestion: `research/` or `docs/research/`92</category>9394<category name="internal-analysis">95**Internal Analysis Report**96- Analysis of internal systems, code, or processes97- Performance reports, architecture reviews98- Code quality assessments, technical debt analysis99- Directory suggestion: `analysis/` or `docs/analysis/`100</category>101102<category name="contextual">103**Contextual Document**104- Background information for ongoing work105- Project context, decision rationale106- Historical context, migration notes107- Directory suggestion: `context/` or `docs/context/`108</category>109110<category name="other">111**Other**112- Documents that don't fit above categories113- Meeting notes, scratch documents, miscellaneous114- Directory suggestion: `docs/` or project root115</category>116</document_classification>117118<header_template>119Every document MUST start with this header structure:120121```markdown122---123document: [Document Name]124created: [YYYY-MM-DD HH:MM]125classification: [external-research | internal-analysis | contextual | other]126---127128**Purpose**: [What this document is for]129**Author**: [Who created it - can be "Claude" or user name]130**Context**: [Why this document was created - what prompted it]131132---133```134135<field_guidance>136- **document**: Clear, descriptive name (not the filename)137- **created**: Current date and time when document is first created138- **classification**: One of the four categories above139- **Purpose**: 1-2 sentences on what the document achieves140- **Author**: Who or what produced this document141- **Context**: The triggering event or need that led to creation142</field_guidance>143</header_template>144145<footer_template>146Every document MUST end with this footer structure:147148```markdown149---150151## Change History152153| Date | Change | Author |154|------|--------|--------|155| [YYYY-MM-DD] | Initial creation | [Author] |156```157158<update_behavior>159After EVERY modification to the document:1601. Add a new row to the Change History table1612. Include date, brief description of change, and who made it1623. Keep entries in reverse chronological order (newest first)163164Example after updates:165```markdown166## Change History167168| Date | Change | Author |169|------|--------|--------|170| 2024-03-15 | Added section on error handling | Claude |171| 2024-03-14 | Expanded API examples | User |172| 2024-03-14 | Initial creation | Claude |173```174</update_behavior>175</footer_template>176177<complete_example>178```markdown179---180document: Authentication Flow Analysis181created: 2024-03-14 09:30182classification: internal-analysis183---184185**Purpose**: Document the current authentication flow and identify potential improvements186**Author**: Claude187**Context**: User requested security review of login system188189---190191[Document content goes here...]192193---194195## Change History196197| Date | Change | Author |198|------|--------|--------|199| 2024-03-14 | Initial creation | Claude |200```201</complete_example>202203<success_criteria>204Document is correctly structured when:205- Header contains all required fields (document, created, classification)206- Purpose, Author, and Context are clearly stated207- Classification matches document content208- Footer has Change History table209- Change History is updated after every modification210- Path respects user-provided location or follows classification-based suggestion211- Markdown is lint-free (proper spacing, heading levels, code fences)212- Any diagrams use Mermaid format213</success_criteria>214215<anti_patterns>216<avoid>217- Creating documents without headers218- Skipping change history updates219- Overriding user-specified paths220- Applying this to subagents, commands, or skills221- Using vague document names like "Notes" or "Document"222- Leaving Purpose/Author/Context empty223- Producing markdown with lint errors (missing blank lines, skipped heading levels)224- Using ASCII art, PlantUML, or other diagram formats instead of Mermaid225- Code fences without language specifiers226</avoid>227</anti_patterns>
majiayu000