mkdocs.yml

# MkDocs Configuration for amplihack
# Complete documentation website for the amplihack agentic coding framework

site_name: amplihack
site_description: Agentic coding framework that uses specialized AI agents to accelerate software development
site_author: amplihack contributors
site_url: https://rysweet.github.io/amplihack/
repo_name: rysweet/amplihack
repo_url: https://github.com/rysweet/amplihack
edit_uri: edit/main/docs/

# Theme Configuration
theme:
  name: material
  language: en
  palette:
    # Light mode
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - search.share
    - toc.follow
    - toc.integrate
    - content.code.copy
    - content.code.annotate
    - content.action.edit
    - content.action.view
  icon:
    repo: fontawesome/brands/github

# Navigation Structure
nav:
  - Home: index.md
  - Getting Started:
      - Installation: PREREQUISITES.md
      - Interactive Setup: INTERACTIVE_INSTALLATION.md
      - Quick Start: README.md
  - Core Concepts:
      - Philosophy: claude/context/PHILOSOPHY.md
      - Project Overview: claude/context/PROJECT.md
      - Patterns: claude/context/PATTERNS.md
      - Trust & Anti-Sycophancy: claude/context/TRUST.md
      - User Preferences: claude/context/USER_PREFERENCES.md
      - Rust Runner Execution Architecture: concepts/rust-runner-execution-architecture.md
  - Workflows:
      - Default Workflow: claude/workflow/DEFAULT_WORKFLOW.md
      - Document-Driven Development:
          - Overview: document_driven_development/README.md
          - Getting Started: document_driven_development/overview.md
          - Core Concepts:
              - Overview: document_driven_development/core_concepts/README.md
              - Context Poisoning: document_driven_development/core_concepts/context_poisoning.md
              - File Crawling: document_driven_development/core_concepts/file_crawling.md
              - Retcon Writing: document_driven_development/core_concepts/retcon_writing.md
          - Phase Guides:
              - Overview: document_driven_development/phases/README.md
              - Phase 0 - Planning: document_driven_development/phases/00_planning_and_alignment.md
              - Phase 1 - Documentation: document_driven_development/phases/01_documentation_retcon.md
              - Phase 2 - Approval: document_driven_development/phases/02_approval_gate.md
              - Phase 3 - Planning: document_driven_development/phases/03_implementation_planning.md
              - Phase 4 - Implementation: document_driven_development/phases/04_code_implementation.md
              - Phase 5 - Testing: document_driven_development/phases/05_testing_and_verification.md
              - Phase 6 - Cleanup: document_driven_development/phases/06_cleanup_and_push.md
          - Reference:
              - Overview: document_driven_development/reference/README.md
              - Checklists: document_driven_development/reference/checklists.md
              - Common Pitfalls: document_driven_development/reference/common_pitfalls.md
              - FAQ: document_driven_development/reference/faq.md
              - Tips for Success: document_driven_development/reference/tips_for_success.md
      - N-Version Programming: claude/workflow/N_VERSION_WORKFLOW.md
      - Multi-Agent Debate: claude/workflow/DEBATE_WORKFLOW.md
      - Fallback Cascade: claude/workflow/CASCADE_WORKFLOW.md
      - Investigation Workflow: claude/workflow/INVESTIGATION_WORKFLOW.md
      - Workflow Guardrails:
          - Overview: features/workflow-execution-guardrails.md
          - Configuration: howto/configure-workflow-execution-guardrails.md
          - Tutorial: tutorials/workflow-execution-guardrails.md
          - Reference: reference/workflow-execution-guardrails.md
      - Dual-Provider Workflow (GitHub + ADO):
          - Overview: features/dual-provider-workflow.md
          - Configuration: howto/configure-dual-provider-workflow.md
          - Tutorial: tutorials/dual-provider-workflow.md
          - Reference: reference/dual-provider-workflow.md
      - Workflow Publish Import Validation (planned):
          - Overview (spec): features/workflow-publish-import-validation.md
          - Configuration (spec): howto/configure-workflow-publish-import-validation.md
          - Tutorial (design walkthrough): tutorials/workflow-publish-import-validation.md
          - Reference (contract): reference/workflow-publish-import-validation.md
      - Pre-Commit Diagnostic: claude/agents/amplihack/specialized/pre-commit-diagnostic.md
      - CI Diagnostic: claude/agents/amplihack/specialized/ci-diagnostic-workflow.md
      - Fix Workflow: claude/agents/amplihack/specialized/fix-agent.md
      - Oxidizer: OXIDIZER.md
      - Issue Classifier:
          - Configuration: howto/configure-issue-classifier-workflow.md
  - Agents:
      - Overview: claude/agents/README.md
      - Core Agents:
          - Architect: claude/agents/amplihack/core/architect.md
          - Builder: claude/agents/amplihack/core/builder.md
          - Reviewer: claude/agents/amplihack/core/reviewer.md
          - Tester: claude/agents/amplihack/core/tester.md
      - Specialized Agents:
          - API Designer: claude/agents/amplihack/core/api-designer.md
          - Security: claude/agents/amplihack/specialized/security.md
          - Database: claude/agents/amplihack/specialized/database.md
          - Integration: claude/agents/amplihack/specialized/integration.md
          - Knowledge Archaeologist: claude/agents/amplihack/specialized/knowledge-archaeologist.md
      - Workflow Agents:
          - Ambiguity Handler: claude/agents/amplihack/specialized/ambiguity.md
          - Cleanup: claude/agents/amplihack/specialized/cleanup.md
          - Optimizer: claude/agents/amplihack/core/optimizer.md
          - Pattern Recognition: claude/agents/amplihack/specialized/patterns.md
  - Commands:
      - Command Guide: commands/COMMAND_SELECTION_GUIDE.md
      - /ultrathink: claude/commands/amplihack/ultrathink.md
      - /analyze: claude/commands/amplihack/analyze.md
      - /improve: claude/commands/amplihack/improve.md
      - /fix: claude/commands/amplihack/fix.md
      - /n-version: claude/commands/amplihack/n-version.md
      - /debate: claude/commands/amplihack/debate.md
      - /cascade: claude/commands/amplihack/cascade.md
      - /customize: claude/commands/amplihack/customize.md
      - DDD Commands:
          - /ddd:0-help: claude/commands/ddd/0-help.md
          - /ddd:prime: claude/commands/ddd/prime.md
          - /ddd:1-plan: claude/commands/ddd/1-plan.md
          - /ddd:2-docs: claude/commands/ddd/2-docs.md
          - /ddd:3-code-plan: claude/commands/ddd/3-code-plan.md
          - /ddd:4-code: claude/commands/ddd/4-code.md
          - /ddd:5-finish: claude/commands/ddd/5-finish.md
          - /ddd:status: claude/commands/ddd/status.md
  - Skills:
      - Overview: claude/skills/README.md
      - Available Skills:
          - Agent SDK: claude/skills/claude-agent-sdk/SKILL.md
          - DOCX: claude/skills/docx/SKILL.md
          - PPTX: claude/skills/pptx/SKILL.md
          - XLSX: claude/skills/xlsx/SKILL.md
          - PDF: claude/skills/pdf/SKILL.md
          - Oxidizer: claude/skills/oxidizer-workflow/SKILL.md
          - WorkIQ WSL: claude/skills/workiq-wsl/SKILL.md
          - Gherkin Expert: claude/skills/gherkin-expert/SKILL.md
          - TLA+ Expert: claude/skills/tla-plus-expert/SKILL.md
  - Tools:
      - Scenarios Overview: claude/scenarios/README.md
      - Analyze Codebase: claude/scenarios/analyze-codebase/README.md
      - Creating Tools: CREATE_YOUR_OWN_TOOLS.md
      - Hooks Configuration: HOOK_CONFIGURATION_GUIDE.md
      - GitHub Copilot CLI:
          - Overview: COPILOT_CLI.md
          - Tutorial: tutorials/copilot-parity-control-plane.md
          - How to Configure the Parity Control Plane: howto/configure-copilot-parity-control-plane.md
          - Parity Control Plane Design: concepts/copilot-parity-control-plane.md
          - Parity Control Plane Reference: reference/copilot-parity-control-plane.md
  - Guides:
      - Formal Specifications as Prompt Language: guides/formal-specifications-as-prompt-language.md
  - Advanced Topics:
      - Development Guide: DEVELOPING_AMPLIHACK.md
      - Hive Mind:
          - Architecture: hive_mind/ARCHITECTURE.md
          - Getting Started: hive_mind/GETTING_STARTED.md
          - Tutorial: hive_mind/TUTORIAL.md
          - Design: hive_mind/DESIGN.md
          - Evaluation: hive_mind/EVAL.md
          - Eval Operator Guide: hive_mind/EVAL_OPERATOR_GUIDE.md
          - Eval Components: hive_mind/EVAL_COMPONENTS.md
          - Investigation Guide: INVESTIGATION_hive_mind_guide.md
      - Goal-Seeking Agents:
          - Overview: GOAL_SEEKING_AGENTS.md
          - Generator Tutorial: tutorials/GOAL_SEEKING_AGENT_TUTORIAL.md
          - LearningAgent Architecture: concepts/learning-agent-module-architecture.md
          - Maintaining LearningAgent Modules: howto/maintain-learning-agent-modules.md
          - LearningAgent Module Reference: reference/learning-agent-module-reference.md
          - LearningAgent Refactor Tutorial: tutorials/learning-agent-refactor-tutorial.md
      - Agent Memory Integration: AGENT_MEMORY_INTEGRATION.md
      - Memory Quickstart: AGENT_MEMORY_QUICKSTART.md
      - External Knowledge: external_knowledge_integration.md
      - Documentation Graph: documentation_knowledge_graph.md
      - Blarify Integration: blarify_integration.md
      - Azure Integration: AZURE_INTEGRATION.md
      - Remote Sessions:
          - Overview: remote-sessions/index.md
          - User Guide: remote-sessions/README.md
          - CLI Reference: remote-sessions/CLI_REFERENCE.md
          - Tutorial: remote-sessions/TUTORIAL.md
  - Code Atlas:
      - Overview: atlas/index.md
      - Repository Surface: atlas/repo-surface/index.md
      - AST+LSP Bindings: atlas/ast-lsp-bindings/index.md
      - Compile-Time Dependencies: atlas/compile-deps/index.md
      - Runtime Topology: atlas/runtime-topology/index.md
      - API Contracts: atlas/api-contracts/index.md
      - Data Flow: atlas/data-flow/index.md
      - Service Components: atlas/service-components/index.md
      - User Journeys: atlas/user-journeys/index.md
      - Health Dashboard: atlas/health.md
      - Glossary: atlas/glossary.md
      - Inventory:
          - Services: atlas/inventory/services.md
          - Environment Variables: atlas/inventory/env-vars.md
          - Data Stores: atlas/inventory/data-stores.md
          - External Dependencies: atlas/inventory/external-deps.md
  - Reference:
      - Discoveries: claude/context/DISCOVERIES.md
      - Security: SECURITY_RECOMMENDATIONS.md
      - Testing: testing/README.md
      - Troubleshooting: troubleshooting/README.md
      - Code Review: CODE_REVIEW.md
      - Rust Runner Execution: reference/rust-runner-execution.md

# Plugins
plugins:
  - search:
      lang: en
      separator: '[\s\-\.]+'
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true

# Markdown Extensions
markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
      toc_depth: 3
  # PyMdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Extra Configuration
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/rysweet/amplihack
  version:
    provider: mike
  analytics:
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: Thanks for your feedback! Help us improve by opening an issue.

# Extra CSS
extra_css:
  - stylesheets/extra.css

# Extra JavaScript
extra_javascript:
  - javascripts/extra.js
  - https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

# Copyright
copyright: Copyright © 2024 amplihack contributors