mkdocs.yml

site_name: AI-First Development Guidelines
site_description: Comprehensive guidelines for teams adopting AI-first development practices
site_url: https://solaris007.github.io/ai-first-guidelines/

repo_name: solaris007/ai-first-guidelines
repo_url: https://github.com/solaris007/ai-first-guidelines

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      primary: red
      accent: red
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: red
      accent: red
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

plugins:
  - search

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.tabbed:
      alternate_style: true
  - tables
  - toc:
      permalink: true

nav:
  - Home: index.md
  - What's New: LATEST.md
  - Foundations:
    - Philosophy: 01-foundations/philosophy.md
    - Harness Engineering: 01-foundations/harness-engineering.md
    - Substrate Model: 01-foundations/substrate-model.md
    - Workspace Setup: 01-foundations/workspace-setup.md
    - Tools Checklist: 01-foundations/tools-checklist.md
    - Agent DX Vision: 01-foundations/agent-dx-vision.md
    - Skill Distribution: 01-foundations/skill-distribution.md
    - Blackboard Mental Models: 01-foundations/blackboard-mental-models.md
    - Agentic Memory Review: 01-foundations/agentic-memory-review.md
  - Development Lifecycle:
    - Overview: 02-lifecycle/overview.md
    - 1. Design & Spec: 02-lifecycle/01-design-spec.md
    - 2. Planning: 02-lifecycle/02-planning.md
    - 3. Implementation: 02-lifecycle/03-implementation.md
    - 4. Validation: 02-lifecycle/04-validation.md
    - 5. Closure: 02-lifecycle/05-closure.md
    - Multi-Session Patterns: 02-lifecycle/multi-session-patterns.md
    - 6. Configuration Evolution: 02-lifecycle/06-config-evolution.md
    - Evaluation-Driven Development:
      - Overview: 02-lifecycle/eval-driven-development.md
      - Implementation Plan: 02-lifecycle/edd-implementation-plan.md
      - Quick Start: 02-lifecycle/evaluation-quickstart.md
      - Evaluation Guide: 02-lifecycle/evaluation-guide.md
      - Prompt Optimization: 02-lifecycle/prompt-optimization.md
      - Tool Replay: 02-lifecycle/tool-replay.md
      - Dual Tracing: 02-lifecycle/dual-tracing.md
      - Unified Optimization Flow: 02-lifecycle/unified-optimization-flow.md
      - Optimization Process Diagram: 02-lifecycle/optimization-process-diagram.md
      - LLM-Powered Evals: 02-lifecycle/llm-powered-evals.md
      - LLM-Powered Evals Requirements: 02-lifecycle/llm-powered-evals-requirements.md
      - Self-Improving Agents: 02-lifecycle/self-improving-agents.md
      - Dataset Persistence Proposal: 02-lifecycle/dataset-persistence-proposal.md
      - Evals Dashboard Architecture: 02-lifecycle/evals-dashboard-architecture.md
      - LangSmith Evaluation Fixes: 02-lifecycle/langsmith-evaluation-fixes.md
    - Shadow Mode Migration: 02-lifecycle/shadow-mode-migration.md
  - Templates:
    - Spec Proposal: 03-templates/spec-proposal.md
    - Migration Plan: 03-templates/migration.md
    - Decision Record: 03-templates/decision-record.md
    - Component Contract: 03-templates/contract.md
    - Pull Request Template: 03-templates/pull-request-template.md
    - TODO.md: 03-templates/TODO.md
  - Configuration:
    - Overview: 04-configuration/README.md
    - AI Tools:
      - Claude Code: 04-configuration/ai-tools/claude-code.md
      - Tool Permissions: 04-configuration/ai-tools/permissions.md
      - Cursor: 04-configuration/ai-tools/cursor.md
      - Copilot: 04-configuration/ai-tools/copilot.md
      - Codex: 04-configuration/ai-tools/codex.md
      - Gemini CLI: 04-configuration/ai-tools/gemini-cli.md
    - Plugins:
      - Overview: 04-configuration/plugins/README.md
      - Superpowers: 04-configuration/plugins/superpowers.md
      - Adobe Skills: 04-configuration/plugins/adobe-skills.md
    - MCP:
      - Overview: 04-configuration/mcp/overview.md
      - Servers: 04-configuration/mcp/servers.md
      - Workflows: 04-configuration/mcp/workflows.md
    - Skills:
      - Ecosystem Overview: 04-configuration/skills/overview.md
      - Auto-Improve Agent: 04-configuration/skills/auto-improve-agent.md
    - ACI Design: 04-configuration/aci-design.md
    - Cross-Tool Setup: 04-configuration/cross-tool-setup.md
    - Environment & Secrets: 04-configuration/env-secrets.md
  - Guardrails:
    - MUST Rules: 05-guardrails/must-rules.md
    - SHOULD Rules: 05-guardrails/should-rules.md
    - Mechanical Enforcement: 05-guardrails/mechanical-enforcement.md
    - Anti-Patterns: 05-guardrails/anti-patterns.md
    - AI Task Boundaries: 05-guardrails/ai-task-boundaries.md
    - Vibecoding Best Practices: 05-guardrails/vibecoding-best-practices.md
    - Repo Consolidation Decision: 05-guardrails/repo-consolidation-decision.md
  - Examples:
    - Workspace CLAUDE.md: examples/workspace-claude-md.md
    - Project CLAUDE.md: examples/project-claude-md.md
  - Adoption:
    - Onboarding Guide: 06-adoption/onboarding-guide.md
    - AI Readiness Checklist: 06-adoption/ai-readiness-checklist.md
  - Leadership:
    - AI-First Leadership: 07-leadership/ai-first-leadership.md
    - For Junior Engineers: 07-leadership/junior-engineers.md
    - For Experienced Engineers: 07-leadership/experienced-engineers-guide.md
    - AI-Native Phase 1: 07-leadership/ai-native-engineering-phase1.md
    - For Domain Experts: 07-leadership/domain-experts.md
    - AI-Native Leveling (IC): 07-leadership/ai-native-leveling-ic.md
    - AI-Native Leveling (Manager): 07-leadership/ai-native-leveling-manager.md
    - AI-Native Leveling (Domain Expert): 07-leadership/ai-native-leveling-domain-expert.md
  - Presentations:
    - Overview: presentations/README.md
    - Intro: presentations/intro.md
    - Getting Started: presentations/getting-started.md
    - Blackboard Overview: presentations/blackboard-overview.md
    - SMC Components: presentations/smc-components.md
    - Evals:
      - Overview: presentations/evals/README.md
      - Evaluation Presentation: presentations/evals/evaluation-presentation.md
      - Handout: presentations/evals/handout.md
      - Speaker Notes: presentations/evals/speaker-notes.md