docs-manager

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

Documentation Manager (Internal Engine)

Internal skill that manages documentation file operations in .flowbit/docs/. Not directly user-invocable — called by flowbit-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

.flowbit/docs/
├── INDEX.md                      # Master index - READ THIS FIRST
├── project/                      # Project-level documentation (generated by flowbit-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): .flowbit/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 .flowbit/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 .flowbit/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:

   .flowbit/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 .flowbit/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., flowbit-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" 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:

     ### Frontend Standards
     
     *Not initialized for this project. If you need frontend standards, you can:*
     - *Add them manually using the docs-manager skill*
     - *Run `/flowbit-standards-discover --scope=frontend` to auto-discover*
     

6. MANDATORY - Update .github/copilot-instructions.md:
   • Check if .github/copilot-instructions.md exists in the project root; if not, ask the user if they want to create it
   • Add the documentation reference section (see "Manage .github/copilot-instructions.md Integration" operation)
   • Ensure it emphasizes reading INDEX.md at the beginning of any task
7. 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/.flowbit/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 .flowbit/docs/, a comprehensive INDEX.md, and .github/copilot-instructions.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
• /flowbit-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 .flowbit/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.
3. Read references/index-md-template.md for the INDEX.md structure template
4. Generate INDEX.md by populating the template with discovered files and descriptions
5. Write the generated INDEX.md to .flowbit/docs/INDEX.md
6. Verify that .github/copilot-instructions.md references this index (see "Manage .github/copilot-instructions.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/)
2. 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 .flowbit/docs/
3. 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
4. Update INDEX.md to include the new documentation (see "Manage INDEX.md" operation)
5. If this is a technical standard and corresponds to a Github Copilot 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 .flowbit/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
4. 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
5. After updating:
   • Check if INDEX.md needs updating (if the purpose/description changed significantly)
   • If updating tech-stack.md or architecture.md, suggest reviewing .github/copilot-instructions.md for consistency
6. For technical standards:
   • If a corresponding Copilot 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.

What to do:

1. Compare the documentation in this skill's bundled docs/ directory with the project's .flowbit/docs/ directory to identify differences
2. Show the user which documents differ and how they differ
3. Explain that plugin documentation is baseline/reference only, and project documentation is superior
4. WARNING: Copying plugin documentation to the project will overwrite any project-specific customizations
5. Ask the user if they want to:
   • View the differences for reference only (no changes)
   • Reset specific documentation to plugin baseline (selective overwrite)
   • Reset all documentation to plugin baseline (full overwrite - rarely recommended)
6. If the user chooses to copy any documentation:
   • Copy the selected files from this skill's bundled docs/ directory to the project's .flowbit/docs/ directory
   • Update INDEX.md to reflect any changes
   • Review .github/copilot-instructions.md for any necessary updates

Important: This operation should be used rarely, mainly when a team wants to reset to baseline. Project documentation is the source of truth and should be maintained by the team.

Result: User can reference plugin baseline documentation and optionally reset specific docs to plugin versions.

---

6. List Available Documentation

Use this to show what documentation is bundled with this plugin and their installation status in the project.

What to do:

1. List all documentation in this skill's bundled docs/ directory, organized by category
2. For each bundled document:
   • Show the category and name
   • Check if it exists in the project at .flowbit/docs/[category]/[name].md
   • Show installation status (bundled only, installed, or customized)
   • If installed, show whether it differs from the baseline (customized)
3. Show whether INDEX.md exists and is up-to-date
4. Show whether .github/copilot-instructions.md has documentation integration
5. Remind the user that plugin documentation is baseline/reference only, and project documentation (if installed) is the source of truth

Result: The user sees a complete inventory of available baseline documentation and their installation status in the current project.

---

7. Manage .github/copilot-instructions.md Integration

Use this to ensure the project's .github/copilot-instructions.md properly integrates with the documentation system, encouraging AI to read and use the documentation.

What to do:

1. Check if .github/copilot-instructions.md exists in the project root
2. If it doesn't exist, ask the user if they want to create it
3. Look for a documentation reference section in .github/copilot-instructions.md
4. If the section doesn't exist or is incomplete:
   • Read references/copilot-instructions-template.md for the template
   • Add the template section to .github/copilot-instructions.md
5. Ensure the documentation section is placed prominently in .github/copilot-instructions.md (near the top)
6. Verify that the INDEX.md path is correct and the file exists
7. If .flowbit/docs/ doesn't exist, suggest running the initialization operation first

Result: .github/copilot-instructions.md properly integrates with the documentation system, ensuring AI assistance is documentation-aware and follows team conventions.

---

8. Validate Documentation Consistency

Use this to check that documentation is consistent, up-to-date, and properly integrated.

What to do:

1. Check structure:
   • Verify .flowbit/docs/ directory exists
   • Verify all expected subdirectories exist (project/, standards/global/, etc.)
2. Check INDEX.md:
   • Verify it exists and is readable
   • Check that all files in .flowbit/docs/ are listed in INDEX.md
   • Check that all files listed in INDEX.md actually exist
   • Report any orphaned files or broken references
3. Check .github/copilot-instructions.md integration:
   • Verify .github/copilot-instructions.md exists
   • Verify it contains documentation reference section
   • Verify it uses valid file reference format: @.flowbit/docs/INDEX.md (with @ prefix, without backticks)
   • Warn if using incorrect formats like .flowbit/docs/INDEX.md or @.flowbit/docs/INDEX.md (backticks)
4. Check project documentation:
   • Verify critical files exist (vision.md, tech-stack.md)
   • Check if they contain placeholder text vs. actual project information
   • Warn if critical documentation is missing or empty
5. Check standards consistency:
   • If Copilot skills exist, check if corresponding standards documentation exists
   • If standards exist without skills, suggest creating skills (if appropriate)
   • Report any inconsistencies
6. Generate validation report:
   • Summary of documentation status
   • List of issues found
   • Recommendations for fixes
7. Offer to fix issues:
   • Ask if the user wants to automatically fix found issues
   • Fix missing INDEX.md entries
   • Fix missing .github/copilot-instructions.md integration
   • Create missing directory structure

Result: A comprehensive validation report with optional automatic fixes for common issues.

---

Usage Examples

Initialize documentation in a new project:

User: "Set up documentation for this project"
Copilot: [Executes Initialize Documentation - creates structure, copies baseline docs, generates INDEX.md, updates .github/copilot-instructions.md, gathers project info]

Update project vision:

User: "I want to update our project vision to include AI-first approach"
Copilot: [Executes Update Documentation - reads current vision.md, helps user edit it, updates INDEX.md if needed]

Add custom documentation:

User: "Add documentation for our deployment process"
Copilot: [Executes Add Documentation File - creates custom project/deployment.md, updates INDEX.md]

Reference plugin baseline:

User: "Show me the plugin's baseline error handling standard"
Copilot: [Executes Use Plugin Documentation as Reference - shows plugin baseline, compares with project version, no changes unless user requests]

Validate documentation:

User: "Check if our documentation is complete and consistent"
Copilot: [Executes Validate Documentation Consistency - checks structure, INDEX.md, .github/copilot-instructions.md integration, generates report]

Manage INDEX.md:

User: "Rebuild the documentation index"
Copilot: [Executes Manage INDEX.md - scans .flowbit/docs/, regenerates comprehensive INDEX.md]

---

Important Notes

• Project documentation is source of truth — plugin-bundled docs are baseline/reference only
• INDEX.md must stay current — regenerate after any documentation change
• .github/copilot-instructions.md integration is mandatory — ensures AI reads documentation at task start
• This skill is an internal engine — called by flowbit-init, standards-update, and standards-discover. Not directly user-invocable.
• CRITICAL: Return control after completion — This is an internal sub-skill. After completing the requested operation, return control to the calling workflow. Do NOT treat completion of this skill as the end of the conversation turn — the parent skill has more steps to execute.