> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# project-config.yaml

> Level 2 (Project) configuration schema for team-shared settings

## Overview

`project-config.yaml` contains **project-specific settings shared across the team**. This Level 2 configuration file is committed to the repository and allows projects to customize AIOX behavior without modifying framework defaults.

<ParamField path="Location" type="string">
  `.aiox-core/project-config.yaml`
</ParamField>

<ParamField path="Level" type="string">
  L2 (Project)
</ParamField>

<ParamField path="Mutability" type="string">
  Editable by project maintainers
</ParamField>

<ParamField path="Git Status" type="string">
  Committed to repository
</ParamField>

<Note>
  **Reference:** ADR-PRO-002 — Configuration Hierarchy
</Note>

## Schema Reference

### Project Metadata

<ParamField path="project" type="object" required>
  Project installation metadata (project portion)

  <Expandable title="properties">
    <ResponseField name="type" type="string" required>
      Project type classification

      * `EXISTING_AIOX` - Existing project with AIOX installed
      * `NEW_AIOX` - New project using AIOX
      * `GREENFIELD` - Greenfield project
    </ResponseField>

    <ResponseField name="installed_at" type="string" required>
      ISO 8601 installation timestamp

      Example: `"2025-01-14T00:00:00Z"`
    </ResponseField>

    <ResponseField name="version" type="string" required>
      AIOX framework version for this project

      Example: `"2.1.0"`
    </ResponseField>
  </Expandable>
</ParamField>

### Documentation Paths

<ParamField path="documentation_paths" type="object">
  Project documentation structure (Section 2)

  <Expandable title="properties">
    <ResponseField name="qa_dir" type="string" default="docs/qa">
      Quality assurance artifacts directory
    </ResponseField>

    <ResponseField name="prd_file" type="string" default="docs/prd.md">
      Product Requirements Document path
    </ResponseField>

    <ResponseField name="prd_version" type="string" default="v4">
      PRD template version
    </ResponseField>

    <ResponseField name="prd_sharded" type="boolean" default="true">
      Enable PRD sharding for large documents
    </ResponseField>

    <ResponseField name="prd_sharded_location" type="string" default="docs/prd">
      Directory for PRD shards
    </ResponseField>

    <ResponseField name="architecture_file" type="string" default="docs/architecture.md">
      Architecture documentation path
    </ResponseField>

    <ResponseField name="architecture_version" type="string" default="v4">
      Architecture doc version
    </ResponseField>

    <ResponseField name="architecture_sharded" type="boolean" default="true">
      Enable architecture sharding
    </ResponseField>

    <ResponseField name="architecture_sharded_location" type="string" default="docs/architecture">
      Directory for architecture shards
    </ResponseField>

    <ResponseField name="stories_dir" type="string" default="docs/stories">
      User stories directory
    </ResponseField>

    <ResponseField name="dev_debug_log" type="string" default=".ai/debug-log.md">
      Development debug log path
    </ResponseField>

    <ResponseField name="slash_prefix" type="string" default="AIOX">
      Command prefix for slash commands
    </ResponseField>

    <ResponseField name="dev_load_always_files" type="array">
      Files loaded by dev agent on activation

      ```yaml theme={null}
      dev_load_always_files:
        - "docs/framework/coding-standards.md"
        - "docs/framework/tech-stack.md"
        - "docs/framework/source-tree.md"
      ```
    </ResponseField>
  </Expandable>
</ParamField>

### GitHub Integration

<ParamField path="github_integration" type="object">
  GitHub integration configuration (Section 8)

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable GitHub integration
    </ResponseField>

    <ResponseField name="cli_required" type="boolean" default="false">
      Require GitHub CLI (`gh`) for operations
    </ResponseField>

    <ResponseField name="features" type="object">
      Feature flags

      ```yaml theme={null}
      features:
        pr_creation: true
        issue_management: true
      ```
    </ResponseField>

    <ResponseField name="pr" type="object">
      Pull request configuration

      <Expandable title="pr properties">
        <ResponseField name="title_format" type="string" default="conventional">
          PR title format: `conventional`, `simple`
        </ResponseField>

        <ResponseField name="include_story_id" type="boolean" default="true">
          Include story ID in PR title
        </ResponseField>

        <ResponseField name="conventional_commits" type="object">
          Conventional commits settings

          ```yaml theme={null}
          conventional_commits:
            enabled: true
            branch_type_map:
              "feature/": "feat"
              "fix/": "fix"
              "docs/": "docs"
            default_type: "feat"
          ```
        </ResponseField>

        <ResponseField name="auto_assign_reviewers" type="boolean" default="false">
          Automatically assign reviewers to PRs
        </ResponseField>

        <ResponseField name="draft_by_default" type="boolean" default="false">
          Create PRs as drafts by default
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="semantic_release" type="object">
      Semantic release configuration

      ```yaml theme={null}
      semantic_release:
        enabled: true
      ```
    </ResponseField>
  </Expandable>
</ParamField>

### CodeRabbit Integration

<ParamField path="coderabbit_integration" type="object">
  CodeRabbit AI code review integration (Section 9)

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable CodeRabbit integration
    </ResponseField>

    <ResponseField name="self_healing" type="object">
      Self-healing configuration

      ```yaml theme={null}
      self_healing:
        enabled: true
        type: "full"  # or "partial"
        max_iterations: 3
        timeout_minutes: 30
      ```
    </ResponseField>

    <ResponseField name="severity_handling" type="object">
      Issue severity handling rules

      ```yaml theme={null}
      severity_handling:
        CRITICAL: "auto_fix"
        HIGH: "auto_fix"
        MEDIUM: "document_as_debt"
        LOW: "ignore"
      ```
    </ResponseField>

    <ResponseField name="graceful_degradation" type="object">
      Graceful degradation settings

      ```yaml theme={null}
      graceful_degradation:
        skip_if_not_installed: true
        fallback_message: "CodeRabbit CLI not found..."
      ```
    </ResponseField>

    <ResponseField name="report_location" type="string" default="docs/qa/coderabbit-reports/">
      Directory for CodeRabbit reports
    </ResponseField>
  </Expandable>
</ParamField>

### Squads System

<ParamField path="squads" type="object">
  Agent squad configuration (Section 10)

  <Expandable title="properties">
    <ResponseField name="template_location" type="string" default="templates/squad">
      Squad template directory
    </ResponseField>

    <ResponseField name="auto_load" type="boolean" default="false">
      Automatically load squads on activation
    </ResponseField>
  </Expandable>
</ParamField>

### Logging & Status

<ParamField path="logging" type="object">
  Logging and status configuration (Section 7)

  <Expandable title="properties">
    <ResponseField name="decision_logging" type="object">
      Architecture Decision Record logging

      ```yaml theme={null}
      decision_logging:
        enabled: true
        async: true
        location: ".ai/"
        index_file: "decision-logs-index.md"
        format: "adr"
        performance:
          max_overhead: 50
      ```
    </ResponseField>

    <ResponseField name="project_status" type="object">
      Project status tracking

      ```yaml theme={null}
      project_status:
        enabled: true
        auto_load_on_agent_activation: true
        show_in_greeting: true
        cache_time_seconds: 60
        components:
          git_branch: true
          git_status: true
          recent_work: true
          current_epic: true
          current_story: true
        status_file: ".aiox/project-status.yaml"
        max_modified_files: 5
        max_recent_commits: 2
      ```
    </ResponseField>

    <ResponseField name="agent_identity" type="object">
      Agent identity and greeting settings

      ```yaml theme={null}
      agent_identity:
        greeting:
          context_detection: true
          session_detection: "hybrid"
          workflow_detection: "hardcoded"
          performance:
            git_check_cache: true
            git_check_ttl: 300
      ```
    </ResponseField>
  </Expandable>
</ParamField>

### Additional Features

<ParamField path="story_backlog" type="object">
  Story backlog management

  ```yaml theme={null}
  story_backlog:
    enabled: true
    location: "docs/stories/backlog"
    prioritization: "value_risk"
  ```
</ParamField>

<ParamField path="pv_mind_context" type="object">
  PV Mind Context (personal voice/persona system)

  ```yaml theme={null}
  pv_mind_context:
    enabled: true
    location: "outputs/minds/pedro_valerio"
    features:
      persona_voice: true
      technical_depth: "advanced"
      communication_style: "structured"
  ```
</ParamField>

<ParamField path="auto_claude" type="object">
  Auto-Claude automation configuration (Section 13)

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" default="true">
      Enable Auto-Claude features
    </ResponseField>

    <ResponseField name="version" type="string" default="3.0">
      Auto-Claude version
    </ResponseField>

    <ResponseField name="worktree" type="object">
      Git worktree configuration

      ```yaml theme={null}
      worktree:
        enabled: true
        auto_create: "on_story_start"
        auto_cleanup: "manual"
        max_worktrees: 10
        stale_days: 30
        branch_prefix: "auto-claude/"
      ```
    </ResponseField>

    <ResponseField name="spec_pipeline" type="object">
      Specification pipeline settings

      ```yaml theme={null}
      spec_pipeline:
        enabled: false
      ```
    </ResponseField>
  </Expandable>
</ParamField>

## Example Configuration

```yaml theme={null}
# ============================================
# AIOX Project Configuration (Level 2)
# ============================================

project:
  type: EXISTING_AIOX
  installed_at: "2025-01-14T00:00:00Z"
  version: "2.1.0"

documentation_paths:
  qa_dir: "docs/qa"
  prd_file: "docs/prd.md"
  prd_version: "v4"
  stories_dir: "docs/stories"
  dev_load_always_files:
    - "docs/framework/coding-standards.md"
    - "docs/framework/tech-stack.md"

github_integration:
  enabled: true
  features:
    pr_creation: true
    issue_management: true
  pr:
    title_format: "conventional"
    include_story_id: true
    conventional_commits:
      enabled: true
      default_type: "feat"

coderabbit_integration:
  enabled: true
  self_healing:
    enabled: true
    type: "full"
    max_iterations: 3
  severity_handling:
    CRITICAL: "auto_fix"
    HIGH: "auto_fix"
    MEDIUM: "document_as_debt"

logging:
  decision_logging:
    enabled: true
    format: "adr"
  project_status:
    enabled: true
    auto_load_on_agent_activation: true

auto_claude:
  enabled: true
  version: "3.0"
  worktree:
    enabled: true
    auto_create: "on_story_start"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Team Collaboration">
    * Commit `project-config.yaml` to repository
    * Document all project-specific customizations
    * Review changes in PRs like any other code
    * Keep settings minimal and intentional
  </Accordion>

  <Accordion title="Configuration Management">
    * Override framework defaults only when necessary
    * Use descriptive comments for complex settings
    * Test configuration changes in isolation
    * Maintain backward compatibility for team members
  </Accordion>

  <Accordion title="Security">
    * Never commit secrets or API keys
    * Use environment variables for sensitive data
    * Document required environment variables
    * Use `local-config.yaml` for personal credentials
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Configuration Files Overview](/api/config-files)
* [Core Config Schema](/api/core-config)
* [Framework Config Schema](/api/framework-config)
* [Configuration Best Practices](/guides/configuration)

***

*Reference: `.aiox-core/project-config.yaml` | ADR-PRO-002*