/docs-manager

name: docs-manager
description: Internal engine for managing project documentation and technical standards in .maister/docs/. Handles file operations, INDEX.md generation, and .github/copilot-instructions.md integration. Invoked by maister-init, standards-update, and standards-discover skills.
user-invocable: false

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
• **.github/copilot-instructions.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**: `.github/copilot-instructions.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)

4. 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

5. Generate INDEX.md with entries for all copied documentation (see "Manage INDEX.md"