skillpanel/maister/docs-manager

Documentation Manager (Internal Engine)

Internal skill that manages documentation file operations in .maister/docs/. Not directly user-invocable — called by maister:init, standards-update, and standards-discover skills.

Core Principles

• Project documentation is source of truth — plugin-bundled docs are baseline/reference only
• INDEX.md is the master map — always kept up-to-date after changes
• CLAUDE.md integration is mandatory — ensures AI reads documentation

Documentation Structure

.maister/docs/
├── INDEX.md                      # Master index - READ THIS FIRST
├── project/                      # Project-level documentation (generated by maister:init, not copied from templates)
│   ├── vision.md                # Project vision and goals
│   ├── roadmap.md               # Development roadmap
│   ├── tech-stack.md            # Technology choices and rationale
│   └── architecture.md          # System architecture (optional)
└── standards/                    # Technical standards and conventions
    ├── global/                  # Language-agnostic standards
    │   ├── error-handling.md
    │   ├── validation.md
    │   ├── conventions.md
    │   ├── coding-style.md
    │   └── commenting.md
    ├── frontend/                # Frontend-specific standards
    │   ├── css.md
    │   ├── components.md
    │   ├── accessibility.md
    │   └── responsive.md
    ├── backend/                 # Backend-specific standards
    │   ├── api.md
    │   ├── models.md
    │   ├── queries.md
    │   └── migrations.md
    └── testing/                 # Testing standards
        └── test-writing.md

Standard File Conventions

Standard files follow the structure standards/[category]/[topic].md:

• Category = domain folder (global, frontend, backend, testing, or custom)
• Topic file = contains multiple related standards

Format: Each file uses ## Topic as the file heading, with ### Standard Name for each individual standard. Each standard has a 1-10 line description (excluding code snippets) and an optional brief code example (under 10 lines).

Conciseness: Standards are quick-reference conventions, not tutorials. If a file grows unwieldy, split into focused sub-topic files.

Why ### per standard: Each standard as a discrete section makes it easier for agents to find, update, and reference individually — no need to parse bullet lists.

Bundled Resources

This skill bundles the following resources within the plugin:

• Standards Directory: Contains baseline technical standards organized by category:
• global/ - Global standards (error handling, validation, conventions, etc.)
• frontend/ - Frontend-specific standards (CSS, components, accessibility, etc.)
• backend/ - Backend-specific standards (API design, database, queries, etc.)
• testing/ - Testing standards (test writing, coverage, etc.)
• INDEX.md Template: Master template for documentation index

Location Reference

• Plugin bundles (read-only baseline): This skill's docs/ subdirectory within the plugin
• Project documentation (source of truth): .maister/docs/ in the project root
• Project configuration: CLAUDE.md in the project root

Capabilities

1. Initialize Documentation in Project

Use this when a project doesn't have .maister/docs/ or needs documentation for the first time. This is a one-time baseline setup that gives the project a starting point.

IMPORTANT: This operation accepts an optional standards_selection parameter (array of standard categories) to control which standards to initialize. If not provided, all standards are copied (backward compatible). It also accepts an optional standards_source_path parameter to copy standards from an external project instead of the bundled defaults.

What to do:

1. Check if .maister/docs/ exists in the project root
2. If it exists, warn the user that initialization will overwrite existing documentation and ask for confirmation
3. Create the directory structure based on standards_selection:

`` .maister/docs/ ├── project/ └── standards/ ├── global/ (if 'global' in standards_selection or no selection provided) ├── frontend/ (if 'frontend' in standards_selection or no selection provided) ├── backend/ (if 'backend' in standards_selection or no selection provided) └── testing/ (if 'testing' in standards_selection or no selection provided) ``

1. Copy standards to the project's .maister/docs/standards/ directory. Source selection: If standards_source_path is provided, copy from that external path. Otherwise, copy from this skill's bundled docs/standards/ directory:

• Project documentation: Do NOT copy project templates — only create the project/ directory. Project documentation files (vision, roadmap, tech-stack, architecture) are generated by the calling skill (e.g., maister:init) using analyzer data, not copied as placeholder templates.
• Standards: Only copy selected standard categories based on standards_selection parameter:
• If standards_selection is empty or not provided: Copy ALL standards (backward compatible)
• If standards_selection is provided: Only copy specified categories
• Examples:
• ['global', 'frontend', 'testing'] → Copy only these three categories
• ['global', 'backend', 'testing'] → Skip frontend standards
• ['global', 'testing'] → Only global and testing standards

1. Generate INDEX.md with entries for all copied documentation (see "Manage INDEX.md" operation):

• For skipped standard categories, add placeholder sections with "Not initialized - run standards discovery if needed"
• Example: If frontend standards are skipped, INDEX.md shows:

```markdown ### Frontend Standards

Not initialized for this project. If you need frontend standards, you can:

• Add them manually using the docs-manager skill
• Run `/maister:standards-discover --scope=frontend` to auto-discover

```

1. MANDATORY - Update CLAUDE.md:

• Check if CLAUDE.md exists in the project root; if not, ask the user if they want to create it
• Add the documentation reference section (see "Manage CLAUDE.md Integration" operation)
• Ensure it emphasizes reading INDEX.md at the beginning of any task

1. Inform the caller about the documentation structure created

Parameters:

• standards_selection (optional, array of strings): Standard categories to initialize
• Array of category names (e.g., ['global', 'frontend', 'backend', 'testing']). Baseline categories: global, frontend, backend, testing. Custom categories are also supported.
• If omitted or empty: Initialize all baseline standards (backward compatible)
• If provided: Only initialize specified categories (creates directories for custom ones)
• standards_source_path (optional, string): Absolute path to an external standards directory (e.g., /path/to/other-project/.maister/docs/standards/)
• If provided: Copy standards from this path instead of the bundled defaults
• If omitted: Copy from this skill's bundled docs/standards/ directory (default behavior)

Result: The project now has baseline documentation in .maister/docs/, a comprehensive INDEX.md, and CLAUDE.md integration that ensures AI assistance is documentation-aware. Only selected standard categories are initialized.

Important: After this initial setup, the project's documentation becomes the source of truth. Teams should customize it for their specific needs.

Note on Skipped Standards: If standard categories are skipped during initialization, teams can add them later using:

• "Add Documentation File" operation to add specific standards
• /maister:standards-discover command to auto-discover standards from codebase

2. Manage INDEX.md

Use this to create or update the INDEX.md file that serves as the master documentation map.

What to do:

1. Scan the .maister/docs/ directory structure
2. For each documentation file found:

• Read the file content to extract description
• Determine the file's purpose and category
• For technical standards: The description MUST enumerate the specific practices/conventions documented in the file, not just a generic category description.

1. Read references/index-md-template.md for the INDEX.md structure template
2. Generate INDEX.md by populating the template with discovered files and descriptions
3. Write the generated INDEX.md to .maister/docs/INDEX.md
4. Verify that CLAUDE.md references this index (see "Manage CLAUDE.md Integration" operation)

Result: A comprehensive, up-to-date INDEX.md that provides a clear map of all project documentation.

3. Add Documentation File

Use this to add new documentation to the project, either from plugin baseline or custom.

What to do:

1. Determine the type of documentation to add:

• Project documentation (vision, roadmap, tech-stack, architecture, custom)
• Technical standard (any category under standards/)

1. If adding from plugin baseline:

• Check if the requested documentation exists in this skill's bundled docs/ directory
• Copy it to the appropriate location in .maister/docs/

1. If creating custom documentation:

• Ask for the category (project/ or standards/category/)
• Ask for the filename and purpose
• Create a template file with appropriate frontmatter and structure

1. Update INDEX.md to include the new documentation (see "Manage INDEX.md" operation)
2. If this is a technical standard and corresponds to a Claude Code Skill, ensure consistency

Result: New documentation is added to the project and indexed in INDEX.md.

4. Update Documentation

Use this to help the user update or modify existing project documentation.

What to do:

1. Accept the documentation identifier from the user (e.g., "project/vision", "standards/global/error-handling")
2. Check if the documentation exists in .maister/docs/
3. If the documentation exists:

• Read the current documentation
• Ask the user what they want to change or update
• Help them edit the documentation file directly
• Optionally, show them the plugin's baseline version for reference if they ask

1. If the documentation doesn't exist:

• Offer to add it from the plugin baseline (see "Add Documentation File" operation)
• Or offer to help them create custom documentation from scratch

1. After updating:

• Check if INDEX.md needs updating (if the purpose/description changed significantly)
• If updating tech-stack.md or architecture.md, suggest reviewing CLAUDE.md for consistency

1. For technical standards:

• If a corresponding Claude Code Skill exists, suggest reviewing it for consistency
• Standards should align with actual code patterns in the project

Result: Documentation is updated to reflect current project state and team decisions.

5. Use Plugin Documentation as Reference

Use this when a team wants to see the plugin's baseline documentation for reference, or reset specific docs to plugin defaults.