name: "Documentation Kitty"
description: "Create and maintain high-quality software documentation following Write the Docs and Divio principles"
version: "1.0.0"
domain: "other"

# Workflow customization
workflow:
  phases:
    - name: "discover"
      description: "Identify documentation needs and target audience"
    - name: "audit"
      description: "Analyze existing documentation and identify gaps"
    - name: "design"
      description: "Plan documentation structure and Divio types"
    - name: "generate"
      description: "Create documentation from templates and generators"
    - name: "validate"
      description: "Check quality, accessibility, and completeness"
    - name: "publish"
      description: "Deploy documentation and notify stakeholders"

# Expected artifacts
artifacts:
  required:
    - spec.md
    - plan.md
    - tasks.md
    - gap-analysis.md
  optional:
    - divio-templates/
    - generator-configs/
    - audit-report.md
    - research.md
    - data-model.md
    - quickstart.md
    - release.md

# Path conventions for this mission
paths:
  workspace: "docs/"
  deliverables: "docs/output/"
  documentation: "docs/"

# Validation rules
validation:
  checks:
    - all_divio_types_valid
    - no_conflicting_generators
    - templates_populated
    - gap_analysis_complete
    - documentation_state_exists
    - audit_recency
  custom_validators: false  # No custom validators.py initially

# MCP tools recommended for this mission
mcp_tools:
  required:
    - filesystem
    - git
  recommended:
    - web-search
    - code-search
  optional:
    - github
    - gitlab

# Agent personality/instructions
agent_context: |
  You are a documentation agent following Write the Docs best practices and the Divio documentation system.

  Key Practices:
  - Documentation as code: docs live in version control alongside source
  - Divio 4-type system: tutorial, how-to, reference, explanation (distinct purposes)
  - Accessibility: clear language, proper headings, alt text for images
  - Bias-free language: inclusive examples and terminology
  - Iterative improvement: support gap-filling and feature-specific documentation

  Workflow Phases: discover → audit → design → generate → validate → publish

  Generator Integration:
  - JSDoc for JavaScript/TypeScript API reference
  - Sphinx for Python API reference (autodoc + napoleon)
  - rustdoc for Rust API reference

  Gap Analysis:
  - Audit existing docs to identify missing Divio types
  - Build coverage matrix showing what exists vs what's needed
  - Prioritize gaps by user impact

# Task metadata fields
task_metadata:
  required:
    - task_id
    - lane
    - phase
    - agent
  optional:
    - shell_pid
    - assignee
    - estimated_hours

# Command customization
commands:
  specify:
    prompt: "Define documentation needs: iteration mode (initial/gap-filling/feature-specific), Divio types to include, target audience, and documentation goals"
  plan:
    prompt: "Design documentation structure, configure generators (JSDoc/Sphinx/rustdoc), plan gap-filling strategy if iterating"
  tasks:
    prompt: "Break documentation work into packages: template creation, generator setup, content authoring, quality validation"
  implement:
    prompt: "Generate documentation from templates, invoke generators for reference docs, populate templates with project-specific content"
  review:
    prompt: "Validate Divio type adherence, check accessibility guidelines, verify generator output quality, assess completeness"
  accept:
    prompt: "Validate documentation completeness, quality gates, and readiness for publication"
