owflow 0.5.0 → 0.7.0

package/dist/skills/docs-manager/SKILL.md

@@ -1,379 +1,379 @@
----
-name: owflow:docs-manager
-description: Internal engine for managing project documentation and technical standards in .owflow/docs/. Handles file operations, INDEX.md generation, and AGENTS.md integration. Invoked by flow-init, standards-update, and standards-discover skills.
-user-invocable: false
----
-
-# Documentation Manager (Internal Engine)
-
-Internal skill that manages documentation file operations in `.owflow/docs/`. Not directly user-invocable — called by `flow-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
-- **AGENTS.md integration is mandatory** — ensures AI reads documentation
-
-## Documentation Structure
-
-```
-.owflow/docs/
-├── INDEX.md                      # Master index - READ THIS FIRST
-├── project/                      # Project-level documentation (generated by flow-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): `.owflow/docs/` in the project root
-- **Project configuration**: `AGENTS.md` in the project root
-
-## Capabilities
-
-### 1. Initialize Documentation in Project
-
-Use this when a project doesn't have `.owflow/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 `.owflow/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:
-   ```
-   .owflow/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 `.owflow/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., flow-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:
-
-     ```markdown
-     ### Frontend Standards
-
-     _Not initialized for this project. If you need frontend standards, you can:_
-
-     - _Add them manually using the owflow:docs-manager skill_
-     - _Run `/owflow:standards-discover --scope=frontend` to auto-discover_
-     ```
-
-6. **MANDATORY - Update AGENTS.md:**
-   - Check if `AGENTS.md` exists in the project root; if not, ask the user if they want to create it
-   - Add the documentation reference section (see "Manage AGENTS.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/.owflow/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 `.owflow/docs/`, a comprehensive INDEX.md, and AGENTS.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
-- `/owflow: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 `.owflow/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 `.owflow/docs/INDEX.md`
-6. Verify that AGENTS.md references this index (see "Manage AGENTS.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 `.owflow/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 Agent 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 `.owflow/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 AGENTS.md for consistency
-6. For technical standards:
-   - If a corresponding Agent 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 `.owflow/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 `.owflow/docs/` directory
-   - Update INDEX.md to reflect any changes
-   - Review AGENTS.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 `.owflow/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 AGENTS.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 AGENTS.md Integration
-
-Use this to ensure the project's AGENTS.md properly integrates with the documentation system, encouraging AI to read and use the documentation.
-
-**What to do:**
-
-1. Check if `AGENTS.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 AGENTS.md
-4. If the section doesn't exist or is incomplete:
-   - Read `references/agents-md-template.md` for the template
-   - Add the template section to AGENTS.md
-5. Ensure the documentation section is placed prominently in AGENTS.md (near the top)
-6. Verify that the INDEX.md path is correct and the file exists
-7. If `.owflow/docs/` doesn't exist, suggest running the initialization operation first
-
-**Result:** AGENTS.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 `.owflow/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 `.owflow/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 AGENTS.md integration:**
-   - Verify AGENTS.md exists
-   - Verify it contains documentation reference section
-   - Verify it uses valid file reference format: @.owflow/docs/INDEX.md (with @ prefix, without backticks)
-   - Warn if using incorrect formats like `.owflow/docs/INDEX.md` or `@.owflow/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 Agent 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 AGENTS.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"
-Agent: [Executes Initialize Documentation - creates structure, copies baseline docs, generates INDEX.md, updates AGENTS.md, gathers project info]
-```
-
-**Update project vision:**
-
-```
-User: "I want to update our project vision to include AI-first approach"
-Agent: [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"
-Agent: [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"
-Agent: [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"
-Agent: [Executes Validate Documentation Consistency - checks structure, INDEX.md, AGENTS.md integration, generates report]
-```
-
-**Manage INDEX.md:**
-
-```
-User: "Rebuild the documentation index"
-Agent: [Executes Manage INDEX.md - scans .owflow/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
-- **AGENTS.md integration is mandatory** — ensures AI reads documentation at task start
-- **This skill is an internal engine** — called by flow-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.
+---
+name: owflow:docs-manager
+description: Internal engine for managing project documentation and technical standards in .owflow/docs/. Handles file operations, INDEX.md generation, and AGENTS.md integration. Invoked by flow-init, standards-update, and standards-discover skills.
+user-invocable: false
+---
+
+# Documentation Manager (Internal Engine)
+
+Internal skill that manages documentation file operations in `.owflow/docs/`. Not directly user-invocable — called by `flow-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
+- **AGENTS.md integration is mandatory** — ensures AI reads documentation
+
+## Documentation Structure
+
+```
+.owflow/docs/
+├── INDEX.md                      # Master index - READ THIS FIRST
+├── project/                      # Project-level documentation (generated by flow-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): `.owflow/docs/` in the project root
+- **Project configuration**: `AGENTS.md` in the project root
+
+## Capabilities
+
+### 1. Initialize Documentation in Project
+
+Use this when a project doesn't have `.owflow/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 `.owflow/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:
+   ```
+   .owflow/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 `.owflow/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., flow-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:
+
+     ```markdown
+     ### Frontend Standards
+
+     _Not initialized for this project. If you need frontend standards, you can:_
+
+     - _Add them manually using the owflow:docs-manager skill_
+     - _Run `/owflow:standards-discover --scope=frontend` to auto-discover_
+     ```
+
+6. **MANDATORY - Update AGENTS.md:**
+   - Check if `AGENTS.md` exists in the project root; if not, ask the user if they want to create it
+   - Add the documentation reference section (see "Manage AGENTS.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/.owflow/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 `.owflow/docs/`, a comprehensive INDEX.md, and AGENTS.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
+- `/owflow: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 `.owflow/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 `.owflow/docs/INDEX.md`
+6. Verify that AGENTS.md references this index (see "Manage AGENTS.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 `.owflow/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 Agent 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 `.owflow/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 AGENTS.md for consistency
+6. For technical standards:
+   - If a corresponding Agent 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 `.owflow/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 `.owflow/docs/` directory
+   - Update INDEX.md to reflect any changes
+   - Review AGENTS.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 `.owflow/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 AGENTS.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 AGENTS.md Integration
+
+Use this to ensure the project's AGENTS.md properly integrates with the documentation system, encouraging AI to read and use the documentation.
+
+**What to do:**
+
+1. Check if `AGENTS.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 AGENTS.md
+4. If the section doesn't exist or is incomplete:
+   - Read `references/agents-md-template.md` for the template
+   - Add the template section to AGENTS.md
+5. Ensure the documentation section is placed prominently in AGENTS.md (near the top)
+6. Verify that the INDEX.md path is correct and the file exists
+7. If `.owflow/docs/` doesn't exist, suggest running the initialization operation first
+
+**Result:** AGENTS.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 `.owflow/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 `.owflow/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 AGENTS.md integration:**
+   - Verify AGENTS.md exists
+   - Verify it contains documentation reference section
+   - Verify it uses valid file reference format: @.owflow/docs/INDEX.md (with @ prefix, without backticks)
+   - Warn if using incorrect formats like `.owflow/docs/INDEX.md` or `@.owflow/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 Agent 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 AGENTS.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"
+Agent: [Executes Initialize Documentation - creates structure, copies baseline docs, generates INDEX.md, updates AGENTS.md, gathers project info]
+```
+
+**Update project vision:**
+
+```
+User: "I want to update our project vision to include AI-first approach"
+Agent: [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"
+Agent: [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"
+Agent: [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"
+Agent: [Executes Validate Documentation Consistency - checks structure, INDEX.md, AGENTS.md integration, generates report]
+```
+
+**Manage INDEX.md:**
+
+```
+User: "Rebuild the documentation index"
+Agent: [Executes Manage INDEX.md - scans .owflow/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
+- **AGENTS.md integration is mandatory** — ensures AI reads documentation at task start
+- **This skill is an internal engine** — called by flow-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.